Claude Code Agent SDK详解

1.Claude Code Agent SDK的两种输入模式：Streaming | Single

2.在Claude Code Agent SDK中，MCP工具的命名规范与权限控制？

复制代码

const result = await query({
  prompt: "List open issues",
  options: {
    mcpServers: {
      github: githubServer,
      db: dbServer,
    },
    allowedTools: [
      "mcp__github__*",           // github 服务器的所有工具都免审批
      "mcp__db__query",           // db 服务器只放行 query 这一个工具
    ],
  },
});

Claude Code 核心架构中的"权限评估模型（Permission Evaluation Pipeline）"。

这是 Claude Code 最关键的安全护城河------当 AI 想去执行某个动作（比如删文件、跑命令、调外部 API）时，系统内部会像安检通道一样，依次经过 5 道关卡。只要前一步拦截了，后面就不再看。

💡 通俗比喻：公司门禁安检

想象 Claude 想进入公司执行某个操作（调用工具）：

第一关 (Hook)：最高级别的大楼总指挥，有"一票否决权"。不管你是谁（哪怕拿着总经理特批的 pass 卡），总指挥说不准进就不准进。

第二关 (deny 规则)：公司的黑名单列表。凡是在黑名单上的，直接轰走。

第三关 (permission mode)：全员通行模式。比如"管理员全免检模式"或者"只允许改文件模式"。

第四关 (allow 规则)：公司的白名单列表。专门登记了允许通行的工作牌。

第五关 (canUseTool 回调) ：前几关都没决定的，保安亲自拦下你，弹窗问管理员（你）："AI 想要动这个工具，你批准吗？"

在讲步骤前，先理解一个词：全限定名（Fully Qualified Name） 就像"张三"重名很多，但"中国/北京市/海淀区/张三"是唯一的。MCP 工具的全限定名通常是 mcp__服务名__工具名（例如 mcp__github__create_issue），用于精确锁定某一个工具。

1) PreToolUse Hook 先跑（最高的防线）

含义：生命周期钩子（Hook）最先触发。这是开发者自己写的底层拦截代码。

特点：绝对权威 。即使你开启了 bypassPermissions（绕过权限/全自动模式），Hook 如果返回 deny（拒绝），这道请求也会被死死拦截。

2) deny 规则检查（黑名单）

含义：检查 disallowedTools 配置文件中的黑名单。

特点：拒绝优先（Deny First）。只要你的请求匹配了黑名单里的全限定名，立马拒绝，保证系统安全。

3) permission mode 生效（全局权限模式）

含义：根据系统当前的全局模式做快速批准：

bypassPermissions：全自动模式/免打扰模式，一步到位批准剩余的所有工具调用。

acceptEdits ：只批准本地代码/文件修改（例如 Edit/Write），对于外部 MCP 工具（如访问数据库、发邮件）一律不管，交给后续关卡处理。

4) allow 规则检查（白名单与通配符）

含义：检查 allowedTools 配置文件中的白名单。

特点：支持通配符（Wildcards） ，比如配置 mcp__github__* 就可以直接一次性放行所有 GitHub 相关的工具。只要命中，直接通行。

5) 剩余的调用走 canUseTool 回调或弹出权限提示（最后的兜底）

含义：前 4 步既没拦截也没自动放行的工具，最终会触发弹窗（GUI/CLI 界面提示），等待你手敲 Y/N 确认。

举个例子：
假设你正在让 Claude Code 帮你在项目中处理 GitHub 事务。此时，Claude 决定调用一个强大的外部工具（全限定名为：mcp__github__delete_repository），准备直接删除远程的一个 GitHub 仓库 。

当这个工具调用请求发出的瞬间，它会像过海关一样，依次接受以下 5 道安检关卡的严格评估：

第一关：PreToolUse Hook（大楼总指挥/前置拦截钩子）

动作：系统最先运行开发者自己编写的底层 Hook 脚本。它会检查这个请求的全限定名 mcp__github__delete_repository。

结果：假设你在公司的安全脚本里写死了一条规则："任何包含 delete 的高危操作一律拒绝"。此时，哪怕你在全局开启了全自动免打扰模式（bypassPermissions），Hook 也会直接强制拦截并拒绝。

🛑 如果这里被拦截，流程立刻终止；如果没有 Hook 或 Hook 放行，进入第二关。

第二关：deny 规则检查（黑名单"死刑"判定）

动作：系统检查配置文件中的 disallowedTools（黑名单）。

结果：如果你的配置文件里写了 "mcp__github__delete_repository"（工具级 deny），或者匹配了其危险参数（作用域 deny），系统会立刻判定：命中黑名单，直接拒绝。因为"拒绝永远优先"。

🛑 如果黑名单命中，流程终止；如果没有命中，进入第三关。

第三关：permission mode 生效（全局模式特赦）

动作：检查当前的全局权限模式。

结果：

如果你开启了 bypassPermissions（全自动模式），它会大笔一挥，直接批准所有剩余的调用。

但是，如果你当前开的是 acceptEdits 模式，它只会批准本地的文件修改操作（如 Edit/Write） ，而对于像 mcp__github__delete_repository 这样的 MCP 扩展工具，它会直接不管、交由后面的关卡处理。

➡️ 如果模式没有直接全部批准（例如当前是 acceptEdits 或默认模式），进入第四关。

第四关：allow 规则检查（白名单"通行证"判定）

动作：检查配置文件中的 allowedTools（白名单）。

结果：系统检查白名单中是否有对应的全限定名或通配符（例如 mcp__github__*）。

结果：

如果你在白名单里配置过这个通配符，恭喜它，直接放行。

如果白名单里没有它（比如你只允许了 mcp__github__get_issue 查问题，没允许删库），则未命中，进入第五关。

第五关：canUseTool 回调（人工最后终审）

动作：前 4 步既没有被 Hook 掐死、也没有在黑名单、也没有被全局模式特赦、又不在白名单里。此时，系统只能拉响警报，把决定权交给你。

结果：你的 VS Code 界面或终端会弹出提示框：

"Claude 想要调用工具 mcp__github__delete_repository，是否允许？ $Y/N$ "

你看着屏幕大惊失色，果断点了 N（拒绝），化解了一场"删库危机"。

注意：不要贪图省事直接开 bypassPermissions 全局模式！

原因：

acceptEdits 模式不会自动批准 MCP 扩展工具（为了防止 AI 偷偷通过 MCP 调外部网络或破坏数据）。

如果你嫌每次弹窗麻烦，正确的做法 是：在 allowedTools 白名单里用通配符单独授权特定的 MCP 服务（如 mcp__myserver__*）。

因为通配符是"精准授权到某个服务"，而切 mode 是"全局一刀切"，全局一刀切会导致所有危险操作都被放行，安全风险极大！

Claude Code 配置文件中 disallowedTools（禁用工具）的两种不同写法：工具级 deny 与 作用域 deny。

1. 工具级 deny（Tool-level Deny）

定义：直接针对整个工具进行封禁（例如："mcp__dangerous__delete_all"）。

底层机制 ：系统会直接把这个工具从 Claude 的上下文（Context）中彻底抹除。在 Claude 的"认知"里，这个工具根本不存在。

优缺点：

更安全、效率更高：因为 Claude 压根不知道这个工具的存在，它不会浪费对话轮次（Turn）去尝试调用一个用不了的工具。

缺点：一刀切，只要封了就全功能不可用。

2. 作用域 deny（Scope-level Deny）

定义：针对工具的具体调用参数或范围 进行限制（例如："mcp__db__query(DROP *)"）。

底层机制 ：工具本身依然保留在 Claude 的上下文中，Claude 看得到它、也能正常调用它的大部分功能；但是，只要参数匹配了被禁止的范围（比如你想执行高危的 DROP * 删库操作），就会被安全拦截。

优缺点：

更灵活：允许 AI 正常使用该工具（比如查数据库），但把危险动作拦下来。

缺点：由于 Claude 知道这个工具存在，它可能会在不知情的情况下先尝试去调用 ，然后被系统拒绝，从而白白消耗一次对话循环（Turn）。

3.Claude Code Agent SDK支持哪些类型的插件组件？

复制代码

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件清单文件（可选，无则自动发现）
├── skills/                   # 模型自主调用或 /skill-name 触发
│   └── code-review/
│       └── SKILL.md
├── agents/                   # 特化的 subagent 定义
│   └── security-auditor.md
├── hooks/                    # 生命周期事件处理器
│   └── hooks.json
├── .mcp.json                 # MCP 服务器配置
├── .lsp.json                 # LSP 语言服务器配置
├── monitors/                 # 后台监控进程
│   └── monitors.json
├── themes/                   # 颜色主题
│   └── dracula.json
├── bin/                      # 可执行文件，注入 Bash PATH
│   └── my-tool
└── settings.json             # 默认设置，启用时生效

Claude Code 插件体系（Plugin Architecture）的 9 大核心组件。

1. Skills（技能包 / 锦囊）

是什么 ：教 Claude 学会某项特定流程或规范 的 SOP（标准作业程序）文档，放在 skills/ 目录下。

有啥用 ：比如你写了一个 SKILL.md 教它"按照我们公司的标准格式做 Code Review"。当你说"帮我审查这段代码"时，Claude 会自主读取这个锦囊，按规矩办事。

2. Agents（专职小弟 / 子智能体）

是什么 ：专门处理特定领域任务的 Subagent（子 Agent） ，比如"安全审计专家"、"测试用例生成器"，放在 agents/ 目录下。

有啥用 ：主 Agent 就像总指挥，遇到专业活儿（比如发一条 @tester）或者觉得任务太复杂时，就会把任务自动委派给这些"专职小弟"去独立完成。出于安全考虑，这些小弟被剥夺了修改安全钩子等核心权限（不支持 hooks 等配置）。

3. Hooks（自动机关 / 触发器）

是什么 ：确定性的事件监听器（不经过 AI 思考，触发条件就硬性执行）。它能响应 28 种生命周期事件。

有啥用 ：比如设定一个机关："每当 Claude 修改完代码（事件） ，自动运行 npm test 跑单元测试"；或者"当 Claude 准备发 HTTP 请求前，自动检查有没有泄露 API Key"。

4. MCP Servers（外部桥梁 / 跨系统工具箱）

是什么 ：通过 Model Context Protocol（MCP 协议）连接外部服务的通道，写在 .mcp.json 配置文件里。

有啥用：给 Claude 插上连接外网或第三方软件的翅膀！有了它，Claude 才能直接去操作 GitHub、连接你的 MySQL 数据库、或者给 Slack 发消息。

5. LSP Servers（代码安检员 / 语言服务）

是什么：Language Server Protocol（语言服务器协议），就是 IDE 里帮你做语法检查、报错红线和定义跳转的那个底层服务。

有啥用 ：给 Claude 戴上一副"看懂代码结构"的眼镜。Claude 改完代码后，LSP 会立刻像语法检查员一样推送诊断报告："这里少了个分号/类型不匹配"，Claude 就能据此自动修复错误。

6. Monitors（后台眼线 / 实时监控）

是什么 ：在后台默默运行的持久化小进程，把它看到的第一条控制台输出（stdout）实时推给 Claude。

有啥用 ：比如你在部署代码或启动本地 Dev Server，Monitor 在后台盯着日志，一旦发现控制台报了 500 Internal Server Error，立刻拍拍 Claude 的肩膀告诉它："后台出错了，快看看！"

7. Themes（皮肤 / 主题）

是什么：UI 界面的颜色样式主题。

有啥用 ：纯视觉体验组件，可以通过 /theme 命令切换终端或界面配色（比如暗黑模式、高对比度模式）。

8. Bin（武器库 / 可执行工具包）

是什么 ：一个存放本地可执行文件（脚本、命令行工具）的文件夹 bin/，系统会自动把它加进环境变量（PATH）。

有啥用 ：如果你写了一个自制的 Bash 命令行小工具（比如 my-custom-cli），把它扔进 bin/ 目录，Claude 和它的子 Agents 就能像调用 git、ls 一样在终端里直接运行它！

9. Settings（出厂预设 / 默认配置）

是什么：插件自带的默认配置文件，插件一启用就会自动生效。

有啥用：开箱即用！让用户安装插件后不用手动一堆繁琐配置，插件直接把需要的默认设置应用到当前会话中。

维度 代表组件 作用分类

大脑与团队 Skills (标准流程), Agents (专职小弟) 提升 AI 的"智力与分工"

安全与自动化 Hooks (触发机关), Monitors (后台眼线) 自动化响应与流程管控

能力扩展 MCP Servers (外部集成), LSP Servers (代码理解), Bin (命令行工具) 增强 AI 的"手脚与感知"

个性化与环境 Themes (皮肤), Settings (预设) 界面与运行环境配置

疑问：C:\Users\21031\.claude\settings.json与上面所说的9. Settings组件是同一个吗？

解答：它们完全同源，但作用的"作用域（Scope）"和"优先级"有所不同。

简单来说：你看到的 C:\Users\21031\.claude\settings.json 是 全局用户级配置 ，而图片里提到的 Settings 组件 是 插件自带的默认配置。

它们的生效逻辑与优先级（关键原理），优先级从高到低依次为：

项目级配置 (.claude/settings.json)：针对当前代码仓库的特有配置（最高优先级）。

全局用户配置 (C:\Users\21031\.claude\settings.json)：也就是你找到的这个文件，控制你个人偏好的全局开关（如全局允许/禁用的工具、个人 API Key 等）。

插件级配置 (Settings 组件)：插件开发者写的默认参数。

Skills、Agents、Hooks、MCP、LSP、Bin 在全局与项目级 的具体保存位置：

组件名称 全局用户级路径 (C:\Users\21031\.claude\) 项目级路径 (你的项目根目录\.claude\)

1) Skills ~/.claude/skills/ .claude/skills/

2) Agents ~/.claude/agents/ .claude/agents/

3) Hooks ~/.claude/hooks/ (或写在 settings.json) .claude/hooks/ (或写在 settings.json)

4) MCP Servers ~/.claude/mcp.json (或 settings.json) .claude/mcp.json (或 settings.json)

5) LSP Servers ~/.claude/settings.json (配置项) .claude/settings.json (配置项)

6) Bin ~/.claude/bin/ .claude/bin/

1. Skills（技能包）

文件形态 ：文件夹形式，每个技能是一个独立的子文件夹，里面必须包含 SKILL.md。

全局路径 ：C:\Users\21031\.claude\skills\my-skill\SKILL.md

项目路径 ：你的项目根目录\.claude\skills\my-skill\SKILL.md

2. Agents（专职子 Agent）

文件形态 ：.md 文件或单独的 Agent 文件夹。

全局路径 ：C:\Users\21031\.claude\agents\tester.md

项目路径 ：你的项目根目录\.claude\agents\tester.md

3. Hooks（钩子脚本/触发器）

文件形态 ：可以是一个独立的文件脚本（如 .sh、.js、.py），也可以直接内嵌写在 settings.json 里的 "hooks" 节点下。

全局路径 ：C:\Users\21031\.claude\hooks\ 或 C:\Users\21031\.claude\settings.json

项目路径 ：你的项目根目录\.claude\hooks\ 或 你的项目根目录\.claude\settings.json

4. MCP Servers（外部工具配置）

文件形态：配置 JSON 文件。

全局路径 ：C:\Users\21031\.claude\mcp.json （也可写在全局 settings.json 的 "mcpServers" 块中）

项目路径 ：你的项目根目录\.claude\mcp.json

5. LSP Servers（语言服务配置）

文件形态 ：它不是单独的文件 ，而是在 settings.json 中配置的二进制可执行文件路径或启动命令（如 pyright-langserver）。

全局路径 ：在 C:\Users\21031\.claude\settings.json 中的 "lspServers" 节点。

项目路径 ：在 你的项目根目录\.claude\settings.json 中的 "lspServers" 节点。

6. Bin（命令行工具包）

文件形态 ：可执行脚本或程序（如 .sh、.bat、.exe 等）。

全局路径 ：C:\Users\21031\.claude\bin\

项目路径 ：你的项目根目录\.claude\bin\

如果这些组件是作为第三方插件（Plugin）安装进来的，它们会存在于插件安装包内部 （类似于 Node.js 的 node_modules 结构）：

插件安装目录 ：C:\Users\21031\.claude\plugins\<插件名>\

...\plugins\<插件名>\skills\

...\plugins\<插件名>\agents\

...\plugins\<插件名>\bin\

...\plugins\<插件名>\.mcp.json

加载顺序：

当 Claude Code 启动时，它会自动按照以下优先级向上扫描并合并加载：

项目级 (.claude/) ------ 优先度最高，覆盖全局

全局用户级 (C:\Users\21031\.claude\) ------ 次之，全局通用

已启用的插件包内 (plugins/) ------ 提供基础扩展能力

维度	代表组件	作用分类
大脑与团队	Skills (标准流程), Agents (专职小弟)	提升 AI 的"智力与分工"
安全与自动化	Hooks (触发机关), Monitors (后台眼线)	自动化响应与流程管控
能力扩展	MCP Servers (外部集成), LSP Servers (代码理解), Bin (命令行工具)	增强 AI 的"手脚与感知"
个性化与环境	Themes (皮肤), Settings (预设)	界面与运行环境配置

组件名称	全局用户级路径 (C:\Users\21031\.claude\)	项目级路径 (你的项目根目录\.claude\)
1) Skills	`~/.claude/skills/`	`.claude/skills/`
2) Agents	`~/.claude/agents/`	`.claude/agents/`
3) Hooks	`~/.claude/hooks/` (或写在 `settings.json`)	`.claude/hooks/` (或写在 `settings.json`)
4) MCP Servers	`~/.claude/mcp.json` (或 `settings.json`)	`.claude/mcp.json` (或 `settings.json`)
5) LSP Servers	`~/.claude/settings.json` (配置项)	`.claude/settings.json` (配置项)
6) Bin	`~/.claude/bin/`	`.claude/bin/`

什么是插件（Plugins）？插件与以上9 大组件是啥归属关系？

插件就是"打包封装好的组件大礼包"。

如果把 9 大组件 （Skills、Agents、Hooks、MCP Servers 等）比作一颗颗零散的 "螺丝钉、齿轮和引擎" ，那么 插件（Plugin） 就是将这些组件按照特定功能打包在一起的"成品设备"。

插件的本质 ：它是一个带有特定结构（包含 plugin.json 声明文件）的文件夹或 npm/Marketplace 包。

插件的作用 ：让开发者可以把一套写好的能力（比如"GitHub 自动化插件"，里面既有 GitHub 的 MCP 工具，又有 Code Review 的 Skill，还有自动打标签的 Hook）打包发布，别人安装这一个插件，就能一次性获得这套组合拳能力！

插件与 9 大组件的"归属关系" 是 "容器"与"内容物" 的包含关系：

插件（Plugin） = 命名空间（Namespace） + 9 大组件的任意组合

组件是原子的（最小单元）：9 大组件是 Claude Code 系统能够识别的 9 种基本能力规格。

插件是组件的载体：一个插件内部，可以同时包含：

1 个 skills/ 文件夹（包含多个 Skill）

1 个 agents/ 文件夹（包含多个 Subagent）

1 个 .mcp.json（配置 MCP 服务）

1 个 bin/ 目录（命令行可执行文件）

以及 Hooks, LSP, Themes, Settings 等。

插件与本地独立配置（.claude/）又是什么关系？

它们本质上是用相同的 9 大组件，解决"本地单项目/个人使用"与"跨项目/团队共享"的两种不同组织形式。

维度 本地独立配置 (.claude/ 目录) 插件 (Plugins)

通俗比喻 自家小作坊定制：直接在自家客厅改装东西，方便快捷。 标准商品打包：工厂流水线封装好，贴上商标，带防伪和规格说明书。

技能/命令命名 直来直去，如 /hello 带有命名空间（Namespace）前缀，如 /plugin-name:hello

适用场景 个人工作流、单项目特有逻辑、快速实验团队共享、跨项目复用、对外版本发布

分发方式 手动拷贝文件，或 Git Submodule 嵌入 Marketplace（市场安装）或 --plugin-dir 命令行加载

冲突处理 容易撞名（必须手动避免命名冲突） 命名空间自动隔离（不同插件有相同的 Skill 也不会冲突）

核心区别：命名空间与隔离机制（Namespace）

本地独立配置 ：直接写在当前项目 .claude/skills/hello/SKILL.md 里的技能，触发命令就是 /hello。如果有两个不同的本地配置文件都叫 hello，系统就会冲突。

插件：假设插件名叫 my-team-tools，里面包含一个 hello 技能，安装后触发命令是 /my-team-tools:hello。它通过前缀（命名空间）完美解决了团队开发中的"撞名"问题。

官方推荐的最佳实践路径

先在 .claude/ 里快速迭代，成熟后转为插件打包分发。

阶段 1（开发实验） ：你在写一个新工具时，直接在当前项目的 .claude/ 目录下建 skills/、hooks/，随改随测，非常方便。

阶段 2（打包提炼） ：当你在 .claude/ 里把这套工具调通、验证成熟后，加上 plugin.json 声明文件，把它提取并打包成一个 Plugin，发布到团队内部或 Marketplace 供全公司/全网复用！

维度	本地独立配置 (.claude/ 目录)	插件 (Plugins)
通俗比喻	自家小作坊定制：直接在自家客厅改装东西，方便快捷。	标准商品打包：工厂流水线封装好，贴上商标，带防伪和规格说明书。
技能/命令命名	直来直去，如 `/hello`	带有命名空间（Namespace）前缀，如 `/plugin-name:hello`
适用场景	个人工作流、单项目特有逻辑、快速实验	团队共享、跨项目复用、对外版本发布
分发方式	手动拷贝文件，或 Git Submodule 嵌入	Marketplace（市场安装）或 `--plugin-dir` 命令行加载
冲突处理	容易撞名（必须手动避免命名冲突）	命名空间自动隔离（不同插件有相同的 Skill 也不会冲突）

复制代码

[
  {
    "name": "deploy-watcher",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

注意：禁用插件不会停止已经在跑的monitor，只有会话结束才停止。