mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 06:15:51 +00:00
cda7703ec4
移除 TypeScript 代码、源码路径和传输层实现细节， 聚焦多来源合并的企业管控设计、内置vs外部的架构一致性、 工具描述截断的防护和 disallowedTools 黑名单优先的安全思维。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
108 lines
3.8 KiB
Plaintext
108 lines
3.8 KiB
Plaintext
---
|
||
title: "自定义 Agent"
|
||
description: "用 Markdown 文件定义自己的 Agent。理解 Agent 定义的数据模型、工具过滤策略和与 AgentTool 的联动。"
|
||
keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "角色定制"]
|
||
---
|
||
|
||
## 核心概念
|
||
|
||
自定义 Agent 是一个 Markdown 文件——frontmatter 定义配置，正文是 system prompt。不需要写代码。
|
||
|
||
```markdown
|
||
---
|
||
name: "reviewer"
|
||
description: "Code review specialist"
|
||
tools: "Read,Glob,Grep"
|
||
model: "haiku"
|
||
---
|
||
|
||
你是代码审查专家。你的职责是...
|
||
```
|
||
|
||
这个 Markdown 文件就定义了一个完整的 Agent：它使用什么工具、什么模型、什么行为规则。
|
||
|
||
## Agent 的三种来源
|
||
|
||
| 来源 | 位置 | 优先级 |
|
||
|------|------|--------|
|
||
| **Built-in** | 硬编码 | 最低（可被覆盖） |
|
||
| **Plugin** | 插件系统注册 | 中 |
|
||
| **User/Project** | `.claude/agents/*.md` | 最高 |
|
||
|
||
合并时按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
|
||
|
||
## 配置字段
|
||
|
||
### 工具控制
|
||
|
||
- `tools` — 允许的工具白名单（未指定 = 全部工具）
|
||
- `disallowedTools` — 显式禁止的工具（即使 `tools` 未指定也生效）
|
||
|
||
**设计考量**：`disallowedTools` 是比 `tools` 更安全的控制方式。如果只指定 `tools` 白名单，新增工具时需要更新白名单。`disallowedTools` 是黑名单思维——默认允许，只禁止危险的。
|
||
|
||
### 模型配置
|
||
|
||
- `model` — 指定模型（`haiku`/`sonnet`/`opus`/`inherit`）
|
||
- `effort` — 推理努力程度（`low`/`medium`/`high`）
|
||
|
||
`inherit` 使用主线程的模型——适合需要完整推理能力的任务。`haiku` 适合轻量任务（如搜索），更便宜更快。
|
||
|
||
### 行为控制
|
||
|
||
- `maxTurns` — 最大 agentic 轮次（防止无限循环）
|
||
- `permissionMode` — 权限模式（`plan`/`bypassPermissions` 等）
|
||
- `background` — 始终作为后台任务运行
|
||
- `isolation` — 在独立 worktree 中运行
|
||
|
||
### 持久化
|
||
|
||
- `memory` — 启用跨会话的持久记忆（`user`/`project`/`local`）
|
||
- `mcpServers` — 引用或内联定义 MCP 服务器
|
||
- `hooks` — Agent 专属的 Hook 配置
|
||
- `skills` — 预加载的技能
|
||
|
||
## System Prompt 的注入方式
|
||
|
||
Agent 的 Markdown 正文**完全替换**默认的 system prompt，而非追加。这意味着自定义 Agent 的行为完全由你定义——不受默认 prompt 的约束。
|
||
|
||
如果启用了 `memory`，记忆指令自动追加到 system prompt 末尾。
|
||
|
||
## 工具过滤流程
|
||
|
||
```
|
||
全部工具 → disallowedTools 移除 → tools 白名单过滤 → 可用工具
|
||
```
|
||
|
||
内置 Explore Agent 的工具限制是很好的例子：
|
||
- 禁止 `Agent`（不能嵌套调用子 Agent）
|
||
- 禁止 `FileEdit`/`FileWrite`（只读）
|
||
- 禁止 `ExitPlanMode`（不需要 plan mode）
|
||
|
||
这些限制让 Explore Agent 成为一个纯粹的搜索工具——它只能看，不能改。
|
||
|
||
## 与 AgentTool 的联动
|
||
|
||
当主 Agent 需要派生子 Agent 时：
|
||
|
||
```
|
||
查找 Agent 定义 → 检查 MCP 依赖 → 过滤工具 → 解析模型 → 构建隔离环境 → 注入 system prompt → 启动子 Agent
|
||
```
|
||
|
||
每一步都使用 Agent 定义中的配置——工具列表、模型选择、权限模式、隔离环境等。
|
||
|
||
## 内置 Agent 参考
|
||
|
||
| Agent | 角色 | 工具限制 | 模型 |
|
||
|-------|------|---------|------|
|
||
| General Purpose | 通用任务 | 全部工具 | 继承主线程 |
|
||
| Explore | 代码搜索 | 只读 | haiku |
|
||
| Plan | 规划研究 | 只读 + ExitPlanMode | 继承主线程 |
|
||
| Verification | 结果验证 | 由 feature flag 控制 | — |
|
||
| Code Guide | 使用指南 | 只读 | — |
|
||
|
||
## 接下来
|
||
|
||
- **子 Agent** — 理解子 Agent 的完整执行链路
|
||
- **Skills** — 理解 Skill 中指定 Agent 定义
|
||
- **MCP 配置** — 理解 Agent 中引用 MCP 服务器
|