mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-22 08:15:53 +00:00
docs: 重写扩展性三章（MCP配置/协议/自定义Agent）
移除 TypeScript 代码、源码路径和传输层实现细节， 聚焦多来源合并的企业管控设计、内置vs外部的架构一致性、 工具描述截断的防护和 disallowedTools 黑名单优先的安全思维。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
claude-code-best
@@ -1,211 +1,107 @@
|
||||
---
|
||||
title: "自定义 Agent - 从 Markdown 到运行时的完整链路"
|
||||
description: "揭秘 Claude Code 自定义 Agent 完整链路：Agent 定义的 Markdown 数据模型、三种加载来源、工具过滤策略和与 AgentTool 的联动机制。"
|
||||
keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "Agent 配置", "角色定制"]
|
||||
title: "自定义 Agent"
|
||||
description: "用 Markdown 文件定义自己的 Agent。理解 Agent 定义的数据模型、工具过滤策略和与 AgentTool 的联动。"
|
||||
keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "角色定制"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示 Agent 定义的完整数据模型、加载发现机制、工具过滤和与 AgentTool 的联动 */}
|
||||
## 核心概念
|
||||
|
||||
## Agent 定义的三种来源
|
||||
|
||||
Claude Code 的 Agent 不仅仅来自用户自定义——系统有三类来源，按优先级合并：
|
||||
|
||||
| 来源 | 位置 | 优先级 |
|
||||
|------|------|--------|
|
||||
| **Built-in** | `packages/builtin-tools/src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
|
||||
| **Plugin** | 通过插件系统注册 | 中 |
|
||||
| **User/Project/Policy** | `.claude/agents/*.md` 或 settings.json | 最高 |
|
||||
|
||||
合并逻辑在 `getActiveAgentsFromList()` 中：按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
|
||||
|
||||
## Markdown Agent 文件的完整格式
|
||||
自定义 Agent 是一个 Markdown 文件——frontmatter 定义配置，正文是 system prompt。不需要写代码。
|
||||
|
||||
```markdown
|
||||
---
|
||||
# === 必需字段 ===
|
||||
name: "reviewer" # Agent 标识（agentType）
|
||||
description: "Code review specialist, read-only analysis"
|
||||
|
||||
# === 工具控制 ===
|
||||
tools: "Read,Glob,Grep,Bash" # 允许的工具列表（逗号分隔）
|
||||
disallowedTools: "Write,Edit" # 显式禁止的工具
|
||||
|
||||
# === 模型配置 ===
|
||||
model: "haiku" # 指定模型（或 "inherit" 继承主线程）
|
||||
effort: "high" # 推理努力程度：low/medium/high 或整数
|
||||
|
||||
# === 行为控制 ===
|
||||
maxTurns: 10 # 最大 agentic 轮次
|
||||
permissionMode: "plan" # 权限模式：plan/bypassPermissions 等
|
||||
background: true # 始终作为后台任务运行
|
||||
initialPrompt: "/search TODO" # 首轮用户消息前缀（支持斜杠命令）
|
||||
|
||||
# === 隔离与持久化 ===
|
||||
isolation: "worktree" # 在独立 git worktree 中运行
|
||||
memory: "project" # 持久记忆范围：user/project/local
|
||||
|
||||
# === MCP 服务器 ===
|
||||
mcpServers:
|
||||
- "slack" # 引用已配置的 MCP 服务器
|
||||
- database: # 内联定义
|
||||
command: "npx"
|
||||
args: ["mcp-db"]
|
||||
|
||||
# === Hooks ===
|
||||
hooks:
|
||||
PreToolUse:
|
||||
- command: "audit-log.sh"
|
||||
timeout: 5000
|
||||
|
||||
# === Skills ===
|
||||
skills: "code-review,security-review" # 预加载的 skills（逗号分隔）
|
||||
|
||||
# === 显示 ===
|
||||
color: "blue" # 终端中的 Agent 颜色标识
|
||||
name: "reviewer"
|
||||
description: "Code review specialist"
|
||||
tools: "Read,Glob,Grep"
|
||||
model: "haiku"
|
||||
---
|
||||
|
||||
你是代码审查专家。你的职责是...
|
||||
|
||||
（正文内容 = system prompt）
|
||||
```
|
||||
|
||||
### 字段解析细节
|
||||
这个 Markdown 文件就定义了一个完整的 Agent：它使用什么工具、什么模型、什么行为规则。
|
||||
|
||||
- **`tools`**：通过 `parseAgentToolsFromFrontmatter()` 解析，支持逗号分隔字符串或数组
|
||||
- **`model: "inherit"`**：使用主线程的模型（区分大小写，只有小写 "inherit" 有效）
|
||||
- **`memory`**：启用后自动注入 `Write`/`Edit`/`Read` 工具（即使 `tools` 未包含），并在 system prompt 末尾追加 memory 指令
|
||||
- **`isolation: "remote"`**：仅在 Anthropic 内部可用（`USER_TYPE === 'ant'`），外部构建只支持 `worktree`
|
||||
- **`background`**：`true` 使 Agent 始终在后台运行，主线程不等待结果
|
||||
## Agent 的三种来源
|
||||
|
||||
## 加载与发现机制
|
||||
| 来源 | 位置 | 优先级 |
|
||||
|------|------|--------|
|
||||
| **Built-in** | 硬编码 | 最低（可被覆盖） |
|
||||
| **Plugin** | 插件系统注册 | 中 |
|
||||
| **User/Project** | `.claude/agents/*.md` | 最高 |
|
||||
|
||||
`getAgentDefinitionsWithOverrides()`（被 `memoize` 缓存）执行完整的发现流程：
|
||||
合并时按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
|
||||
|
||||
```
|
||||
1. 加载 Markdown 文件
|
||||
├── loadMarkdownFilesForSubdir('agents', cwd)
|
||||
│ ├── ~/.claude/agents/*.md （用户级，source = 'userSettings'）
|
||||
│ ├── .claude/agents/*.md （项目级，source = 'projectSettings'）
|
||||
│ └── managed/policy sources （策略级，source = 'policySettings'）
|
||||
│
|
||||
└── 每个 .md 文件：
|
||||
├── 解析 YAML frontmatter
|
||||
├── 正文作为 system prompt
|
||||
├── 校验必需字段（name, description）
|
||||
├── 静默跳过无 frontmatter 的 .md 文件（可能是参考文档）
|
||||
└── 解析失败 → 记录到 failedFiles，不阻塞其他 Agent
|
||||
## 配置字段
|
||||
|
||||
2. 并行加载 Plugin Agents
|
||||
└── loadPluginAgents() → memoized
|
||||
### 工具控制
|
||||
|
||||
3. 初始化 Memory Snapshots（如果 AGENT_MEMORY_SNAPSHOT 启用）
|
||||
└── initializeAgentMemorySnapshots()
|
||||
- `tools` — 允许的工具白名单（未指定 = 全部工具）
|
||||
- `disallowedTools` — 显式禁止的工具（即使 `tools` 未指定也生效）
|
||||
|
||||
4. 合并 Built-in + Plugin + Custom
|
||||
└── getActiveAgentsFromList() → 按 agentType 去重，后者覆盖前者
|
||||
**设计考量**：`disallowedTools` 是比 `tools` 更安全的控制方式。如果只指定 `tools` 白名单，新增工具时需要更新白名单。`disallowedTools` 是黑名单思维——默认允许，只禁止危险的。
|
||||
|
||||
5. 分配颜色
|
||||
└── setAgentColor(agentType, color) → 终端 UI 中区分不同 Agent
|
||||
```
|
||||
### 模型配置
|
||||
|
||||
## 工具过滤的实现
|
||||
- `model` — 指定模型（`haiku`/`sonnet`/`opus`/`inherit`）
|
||||
- `effort` — 推理努力程度（`low`/`medium`/`high`）
|
||||
|
||||
当 Agent 被派生时，`AgentTool` 根据定义中的 `tools` / `disallowedTools` 过滤可用工具列表：
|
||||
`inherit` 使用主线程的模型——适合需要完整推理能力的任务。`haiku` 适合轻量任务（如搜索），更便宜更快。
|
||||
|
||||
```
|
||||
全部工具
|
||||
↓ disallowedTools 移除
|
||||
↓ tools 白名单过滤（如果指定）
|
||||
可用工具
|
||||
```
|
||||
### 行为控制
|
||||
|
||||
- **`tools` 未指定**：Agent 可以使用所有工具（默认全能）
|
||||
- **`tools` 指定**：只能使用列出的工具
|
||||
- **`disallowedTools`**：即使 `tools` 未指定，这些工具也被禁止
|
||||
- **自动注入**：`memory` 启用时自动添加 `Write`/`Edit`/`Read`
|
||||
- `maxTurns` — 最大 agentic 轮次（防止无限循环）
|
||||
- `permissionMode` — 权限模式（`plan`/`bypassPermissions` 等）
|
||||
- `background` — 始终作为后台任务运行
|
||||
- `isolation` — 在独立 worktree 中运行
|
||||
|
||||
以内置 Explore Agent 为例：
|
||||
### 持久化
|
||||
|
||||
```typescript
|
||||
// packages/builtin-tools/src/tools/AgentTool/built-in/exploreAgent.ts
|
||||
disallowedTools: [
|
||||
'Agent', // 不能嵌套调用 Agent
|
||||
'ExitPlanMode', // 不需要 plan mode
|
||||
'FileEdit', // 只读
|
||||
'FileWrite', // 只读
|
||||
'NotebookEdit', // 只读
|
||||
]
|
||||
```
|
||||
- `memory` — 启用跨会话的持久记忆（`user`/`project`/`local`）
|
||||
- `mcpServers` — 引用或内联定义 MCP 服务器
|
||||
- `hooks` — Agent 专属的 Hook 配置
|
||||
- `skills` — 预加载的技能
|
||||
|
||||
## System Prompt 的注入方式
|
||||
|
||||
Agent 的 system prompt 通过 `getSystemPrompt()` 闭包延迟生成：
|
||||
Agent 的 Markdown 正文**完全替换**默认的 system prompt，而非追加。这意味着自定义 Agent 的行为完全由你定义——不受默认 prompt 的约束。
|
||||
|
||||
```typescript
|
||||
// Markdown Agent
|
||||
getSystemPrompt: () => {
|
||||
if (isAutoMemoryEnabled() && memory) {
|
||||
return systemPrompt + '\n\n' + loadAgentMemoryPrompt(agentType, memory)
|
||||
}
|
||||
return systemPrompt
|
||||
}
|
||||
如果启用了 `memory`，记忆指令自动追加到 system prompt 末尾。
|
||||
|
||||
## 工具过滤流程
|
||||
|
||||
```
|
||||
全部工具 → disallowedTools 移除 → tools 白名单过滤 → 可用工具
|
||||
```
|
||||
|
||||
这意味着：
|
||||
1. **Markdown 正文 = 完整的 system prompt**——不是追加，而是替换默认 prompt
|
||||
2. **Memory 指令**在 memory 启用时自动追加到末尾
|
||||
3. **闭包延迟计算**——memory 状态可能在文件加载后才变化
|
||||
内置 Explore Agent 的工具限制是很好的例子：
|
||||
- 禁止 `Agent`（不能嵌套调用子 Agent）
|
||||
- 禁止 `FileEdit`/`FileWrite`（只读）
|
||||
- 禁止 `ExitPlanMode`（不需要 plan mode）
|
||||
|
||||
对于 Built-in Agent，`getSystemPrompt` 接受 `toolUseContext` 参数，可以根据运行时状态（如是否使用嵌入式搜索工具）动态调整 prompt 内容。
|
||||
这些限制让 Explore Agent 成为一个纯粹的搜索工具——它只能看，不能改。
|
||||
|
||||
## 与 AgentTool 的联动
|
||||
|
||||
当主 Agent 需要派生子 Agent 时：
|
||||
|
||||
```
|
||||
AgentTool.call({ subagent_type: "reviewer", ... })
|
||||
↓
|
||||
1. 从 agentDefinitions.activeAgents 查找 agentType === "reviewer"
|
||||
↓
|
||||
2. 检查 requiredMcpServers（如果 Agent 要求特定 MCP 服务器）
|
||||
↓
|
||||
3. 过滤工具列表（tools / disallowedTools）
|
||||
↓
|
||||
4. 解析模型：
|
||||
- "inherit" → 使用主线程模型
|
||||
- 具体模型名 → 直接使用
|
||||
- 未指定 → 主线程模型
|
||||
↓
|
||||
5. 解析权限模式（permissionMode）
|
||||
↓
|
||||
6. 构建隔离环境（如果 isolation === "worktree"）
|
||||
↓
|
||||
7. 注入 system prompt（getSystemPrompt()）
|
||||
↓
|
||||
8. 注入 initialPrompt（如果定义了）
|
||||
↓
|
||||
9. 启动子 Agent 循环（forkSubagent / runAgent）
|
||||
查找 Agent 定义 → 检查 MCP 依赖 → 过滤工具 → 解析模型 → 构建隔离环境 → 注入 system prompt → 启动子 Agent
|
||||
```
|
||||
|
||||
每一步都使用 Agent 定义中的配置——工具列表、模型选择、权限模式、隔离环境等。
|
||||
|
||||
## 内置 Agent 参考
|
||||
|
||||
| Agent | agentType | 角色 | 工具限制 | 模型 |
|
||||
|-------|-----------|------|---------|------|
|
||||
| **General Purpose** | `general-purpose` | 默认子 Agent | 全部工具 | 主线程模型 |
|
||||
| **Explore** | `Explore` | 代码搜索专家 | 只读（无 Write/Edit） | haiku（外部） |
|
||||
| **Plan** | `Plan` | 规划专家 | 只读 + ExitPlanMode | inherit |
|
||||
| **Verification** | `verification` | 结果验证 | 由 feature flag 控制 | — |
|
||||
| **Code Guide** | `claude-code-guide` | Claude Code 使用指南 | 只读 | — |
|
||||
| **Statusline Setup** | `statusline-setup` | 终端状态栏配置 | 有限 | — |
|
||||
| Agent | 角色 | 工具限制 | 模型 |
|
||||
|-------|------|---------|------|
|
||||
| General Purpose | 通用任务 | 全部工具 | 继承主线程 |
|
||||
| Explore | 代码搜索 | 只读 | haiku |
|
||||
| Plan | 规划研究 | 只读 + ExitPlanMode | 继承主线程 |
|
||||
| Verification | 结果验证 | 由 feature flag 控制 | — |
|
||||
| Code Guide | 使用指南 | 只读 | — |
|
||||
|
||||
SDK 入口（`sdk-ts`/`sdk-py`/`sdk-cli`）不加载 Code Guide Agent。环境变量 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` 可以完全禁用内置 Agent，给 SDK 用户提供空白画布。
|
||||
## 接下来
|
||||
|
||||
## Agent Memory：持久化的 Agent 状态
|
||||
|
||||
当 `memory` 字段启用时，Agent 获得跨会话的持久记忆：
|
||||
|
||||
- **`local`**：当前项目、当前用户有效
|
||||
- **`project`**：当前项目所有用户共享
|
||||
- **`user`**：所有项目共享
|
||||
|
||||
Memory 通过 `loadAgentMemoryPrompt()` 注入到 system prompt 末尾，包含读写记忆的指令。Agent Memory Snapshot 机制在项目间同步 `user` 级记忆。
|
||||
- **子 Agent** — 理解子 Agent 的完整执行链路
|
||||
- **Skills** — 理解 Skill 中指定 Agent 定义
|
||||
- **MCP 配置** — 理解 Agent 中引用 MCP 服务器
|
||||
|
||||
Reference in New Issue
Block a user