Add project documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
arno
@@ -0,0 +1,262 @@
|
||||
# 工具系统分析
|
||||
|
||||
## 架构概述
|
||||
|
||||
工具系统是 Claude Code 的核心能力层，定义了 Agent 可以执行的所有操作。每个工具是一个自包含模块，包含输入 Schema、权限模型和执行逻辑。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Tool {
|
||||
+string name
|
||||
+string description
|
||||
+ToolInputJSONSchema inputSchema
|
||||
+isEnabled() boolean
|
||||
+getDescription() string
|
||||
+getPrompt() string
|
||||
+execute(input, context) ToolResult
|
||||
+validateInput(input) ValidationResult
|
||||
}
|
||||
|
||||
class BashTool {
|
||||
+name = "Bash"
|
||||
+execute() 运行 Shell 命令
|
||||
+沙盒支持
|
||||
+安全验证
|
||||
}
|
||||
|
||||
class FileReadTool {
|
||||
+name = "Read"
|
||||
+支持图片/PDF/Notebook
|
||||
+行号范围读取
|
||||
}
|
||||
|
||||
class FileWriteTool {
|
||||
+name = "Write"
|
||||
+完整文件写入
|
||||
+读取前置检查
|
||||
}
|
||||
|
||||
class FileEditTool {
|
||||
+name = "Edit"
|
||||
+字符串替换编辑
|
||||
+replace_all 模式
|
||||
}
|
||||
|
||||
class GlobTool {
|
||||
+name = "Glob"
|
||||
+文件模式匹配
|
||||
+基于 ripgrep
|
||||
}
|
||||
|
||||
class GrepTool {
|
||||
+name = "Grep"
|
||||
+内容正则搜索
|
||||
+ripgrep 集成
|
||||
}
|
||||
|
||||
class AgentTool {
|
||||
+name = "Agent"
|
||||
+子代理生成
|
||||
+worktree 隔离
|
||||
+代理类型选择
|
||||
}
|
||||
|
||||
class MCPTool {
|
||||
+MCP 服务器工具调用
|
||||
}
|
||||
|
||||
class LSPTool {
|
||||
+LSP 操作
|
||||
+goToDefinition 等
|
||||
}
|
||||
|
||||
class WebFetchTool {
|
||||
+URL 内容获取
|
||||
}
|
||||
|
||||
class WebSearchTool {
|
||||
+Web 搜索
|
||||
}
|
||||
|
||||
Tool <|-- BashTool
|
||||
Tool <|-- FileReadTool
|
||||
Tool <|-- FileWriteTool
|
||||
Tool <|-- FileEditTool
|
||||
Tool <|-- GlobTool
|
||||
Tool <|-- GrepTool
|
||||
Tool <|-- AgentTool
|
||||
Tool <|-- MCPTool
|
||||
Tool <|-- LSPTool
|
||||
Tool <|-- WebFetchTool
|
||||
Tool <|-- WebSearchTool
|
||||
```
|
||||
|
||||
## 工具注册机制
|
||||
|
||||
工具注册在 `src/tools.ts` 中，通过 `getAllBaseTools()` 函数集中管理：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[getAllBaseTools] --> B{环境判断}
|
||||
B -->|默认| C[核心工具集]
|
||||
B -->|USER_TYPE=ant| D[内部工具集]
|
||||
B -->|feature flag| E[特性开关工具]
|
||||
|
||||
C --> F[AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool, NotebookEditTool, WebFetchTool, WebSearchTool, AskUserQuestionTool, SkillTool, BriefTool, TaskStopTool, TodoWriteTool, ExitPlanModeV2Tool, ListMcpResourcesTool, ReadMcpResourceTool]
|
||||
|
||||
D --> G[ConfigTool, TungstenTool, REPLTool, SuggestBackgroundPRTool]
|
||||
|
||||
E --> H[SleepTool PROACTIVE/KAIROS]
|
||||
E --> I[CronCreateTool/CronDeleteTool/CronListTool AGENT_TRIGGERS]
|
||||
E --> J[RemoteTriggerTool AGENT_TRIGGERS_REMOTE]
|
||||
E --> K[EnterWorktreeTool/ExitWorktreeTool]
|
||||
E --> L[TeamCreateTool/TeamDeleteTool]
|
||||
E --> M[SendMessageTool]
|
||||
E --> N[ToolSearchTool]
|
||||
E --> O[WorkflowTool WORKFLOW_SCRIPTS]
|
||||
E --> P[WebBrowserTool WEB_BROWSER_TOOL]
|
||||
E --> Q[MonitorTool MONITOR_TOOL]
|
||||
E --> R[PowerShellTool]
|
||||
```
|
||||
|
||||
## 工具分类
|
||||
|
||||
### 文件操作类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| FileReadTool | Read | 读取文件（支持图片、PDF、Jupyter Notebook） |
|
||||
| FileWriteTool | Write | 创建或覆盖文件 |
|
||||
| FileEditTool | Edit | 部分文件修改（字符串替换） |
|
||||
| GlobTool | Glob | 文件模式匹配搜索 |
|
||||
| GrepTool | Grep | 基于 ripgrep 的内容搜索 |
|
||||
| NotebookEditTool | NotebookEdit | Jupyter Notebook 编辑 |
|
||||
|
||||
### 执行类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| BashTool | Bash | Shell 命令执行（含沙盒） |
|
||||
| PowerShellTool | PowerShell | Windows PowerShell 命令 |
|
||||
|
||||
### 网络类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| WebFetchTool | WebFetch | 获取 URL 内容 |
|
||||
| WebSearchTool | WebSearch | Web 搜索 |
|
||||
|
||||
### 代理和协调类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| AgentTool | Agent | 生成子代理（支持 worktree 隔离） |
|
||||
| SendMessageTool | SendMessage | 代理间消息传递 |
|
||||
| TeamCreateTool | TeamCreate | 创建代理团队 |
|
||||
| TeamDeleteTool | TeamDelete | 删除代理团队 |
|
||||
| TaskCreateTool | TaskCreate | 创建任务 |
|
||||
| TaskGetTool | TaskGet | 获取任务详情 |
|
||||
| TaskUpdateTool | TaskUpdate | 更新任务状态 |
|
||||
| TaskListTool | TaskList | 列出所有任务 |
|
||||
| TaskOutputTool | TaskOutput | 获取后台任务输出 |
|
||||
| TaskStopTool | TaskStop | 停止后台任务 |
|
||||
|
||||
### 交互类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| AskUserQuestionTool | AskUserQuestion | 向用户提问获取输入 |
|
||||
| EnterPlanModeTool | EnterPlanMode | 进入计划模式 |
|
||||
| ExitPlanModeV2Tool | ExitPlanMode | 退出计划模式 |
|
||||
| EnterWorktreeTool | EnterWorktree | 进入 Git Worktree |
|
||||
| ExitWorktreeTool | ExitWorktree | 退出 Git Worktree |
|
||||
|
||||
### 集成类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| MCPTool | (动态) | MCP 服务器工具调用 |
|
||||
| ListMcpResourcesTool | ListMcpResources | 列出 MCP 资源 |
|
||||
| ReadMcpResourceTool | ReadMcpResource | 读取 MCP 资源 |
|
||||
| LSPTool | LSP | Language Server Protocol 集成 |
|
||||
| SkillTool | Skill | 技能执行 |
|
||||
|
||||
### 特殊类
|
||||
| 工具 | 名称 | 功能 |
|
||||
|------|------|------|
|
||||
| BriefTool | Brief | 附件处理和上传 |
|
||||
| ConfigTool | Config | 设置管理（仅内部） |
|
||||
| ToolSearchTool | ToolSearch | 延迟工具发现 |
|
||||
| TodoWriteTool | TodoWrite | 待办事项管理 |
|
||||
| SleepTool | Sleep | 主动模式等待 |
|
||||
| SyntheticOutputTool | SyntheticOutput | 结构化输出生成 |
|
||||
| ScheduleCronTool | CronCreate/CronDelete/CronList | 定时任务 |
|
||||
| RemoteTriggerTool | RemoteTrigger | 远程触发 |
|
||||
| REPLTool | REPL | REPL 模式（仅内部） |
|
||||
| WorkflowTool | Workflow | 工作流脚本执行 |
|
||||
| WebBrowserTool | WebBrowser | Web 浏览器自动化 |
|
||||
|
||||
## 权限模型
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[工具调用请求] --> B{权限检查}
|
||||
B -->|auto 模式| C[自动允许]
|
||||
B -->|default 模式| D{规则匹配}
|
||||
B -->|plan 模式| E[只读操作允许]
|
||||
B -->|bypassPermissions| C
|
||||
|
||||
D -->|允许规则| F[执行工具]
|
||||
D -->|拒绝规则| G[拒绝执行]
|
||||
D -->|无规则| H[提示用户]
|
||||
|
||||
H -->|用户允许| F
|
||||
H -->|用户拒绝| G
|
||||
H -->|用户允许本次| I[临时允许并执行]
|
||||
|
||||
G --> J[getDenyRuleForTool 过滤]
|
||||
J --> K[从工具列表中移除]
|
||||
```
|
||||
|
||||
## AgentTool 子代理架构
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[AgentTool] --> B[子代理类型选择]
|
||||
B --> C[general-purpose<br/>通用代理]
|
||||
B --> D[Explore<br/>代码探索]
|
||||
B --> E[Plan<br/>架构规划]
|
||||
B --> F[claude-code-guide<br/>使用指南]
|
||||
|
||||
C --> G[可用工具: 全部]
|
||||
D --> H[可用工具: 只读<br/>Glob, Grep, Read, Agent]
|
||||
E --> I[可用工具: 只读<br/>同 Explore]
|
||||
|
||||
A --> J{隔离模式}
|
||||
J -->|worktree| K[Git Worktree 隔离]
|
||||
J -->|默认| L[同目录执行]
|
||||
|
||||
A --> M[代理能力]
|
||||
M --> N[并行代理启动]
|
||||
M --> O[后台运行]
|
||||
M --> P[消息传递]
|
||||
M --> Q[内存管理]
|
||||
```
|
||||
|
||||
## BashTool 安全机制
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[BashTool 命令执行] --> B{安全检查}
|
||||
B --> C[路径验证<br/>pathValidation.ts]
|
||||
B --> D[只读验证<br/>readOnlyValidation.ts]
|
||||
B --> E[破坏性命令警告<br/>destructiveCommandWarning.ts]
|
||||
B --> F[沙盒检查<br/>shouldUseSandbox.ts]
|
||||
B --> G[sed 命令验证<br/>sedValidation.ts]
|
||||
|
||||
C --> H{在工作目录内?}
|
||||
H -->|是| I[允许执行]
|
||||
H -->|否| J[路径限制警告]
|
||||
|
||||
E --> K{破坏性命令?}
|
||||
K -->|rm, git reset --hard| L[额外确认]
|
||||
K -->|其他| I
|
||||
|
||||
F --> M{沙盒可用?}
|
||||
M -->|是| N[沙盒执行]
|
||||
M -->|否| I
|
||||
```
|
||||
Reference in New Issue
Block a user