renjianbo
beff3fac8d
- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions, schedules, executions, team_members) and unbind goals/tasks before delete - Remove hardcoded personality templates in Android, replace with dynamic system prompt generation from name + description - Set promptSectionsEnabled=false to bypass PromptComposer for personality - Add Tencent Cloud Linux deployment guide (Docker Compose) - Accumulated backend service updates, frontend UI fixes, Android app changes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
381 lines
10 KiB
Markdown
381 lines
10 KiB
Markdown
# Claude Code 工具系统分析
|
||
|
||
## 1. 工具系统架构
|
||
|
||
### 1.1 工具基类 (`src/Tool.ts`, 30KB)
|
||
|
||
所有工具继承自 `Tool` 抽象类：
|
||
|
||
```
|
||
Tool
|
||
├── 元数据属性:
|
||
│ ├── name: string # 工具名称 (如 "Bash", "Read", "Edit")
|
||
│ ├── description: string # 功能描述 (Markdown 格式，发送给模型)
|
||
│ ├── inputSchema: ZodSchema # 参数校验 (Zod v4)
|
||
│ ├── isEnabled: () => boolean # 是否可用 (受 feature flag 控制)
|
||
│ └── promptCategory?: string # 归类标签
|
||
│
|
||
├── 执行方法:
|
||
│ ├── toolUseOutput(): Promise<ToolResult>
|
||
│ │ 主执行逻辑，接收模型解析的参数
|
||
│ └── renderToolUse(): ReactElement
|
||
│ 工具调用消息的 UI 渲染 (Ink React 组件)
|
||
│
|
||
└── 辅助:
|
||
├── toolMatchesName(): 按名称/别名匹配工具
|
||
├── isConcurrencySafe(): 是否支持并发
|
||
└── yieldControl(): 是否释放控制权
|
||
```
|
||
|
||
### 1.2 工具注册 (`src/tools.ts`)
|
||
|
||
`tools.ts` 将所有工具汇总导出：
|
||
|
||
```typescript
|
||
export function getTools(): Tools {
|
||
const baseTools = [
|
||
AgentTool, SkillTool, BashTool, PowerShellTool,
|
||
FileEditTool, FileReadTool, FileWriteTool,
|
||
GlobTool, GrepTool, NotebookEditTool,
|
||
WebFetchTool, WebSearchTool, TaskStopTool,
|
||
TaskOutputTool, TodoWriteTool, ExitPlanModeV2Tool,
|
||
AskUserQuestionTool, LSPTool, ListMcpResourcesTool,
|
||
ReadMcpResourceTool, ToolSearchTool, EnterPlanModeTool,
|
||
EnterWorktreeTool, ExitWorktreeTool, ...
|
||
]
|
||
// 条件工具 (feature flag 控制)
|
||
if (feature('PROACTIVE')) baseTools.push(SleepTool)
|
||
if (feature('AGENT_TRIGGERS')) baseTools.push(...cronTools)
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 1.3 工具调用流程
|
||
|
||
```
|
||
模型响应
|
||
│
|
||
├── content_block.type === 'tool_use'
|
||
│ ├── 解析工具名和参数 (JSON → Zod 校验)
|
||
│ ├── 权限检查: useCanUseTool(toolName, params)
|
||
│ │ ├── bypass → 直接放行
|
||
│ │ ├── auto_accept → 自动批准 (特定模式)
|
||
│ │ └── 需要确认 → 弹出权限请求 UI
|
||
│ │
|
||
│ ├── 执行: tool.toolUseOutput(params)
|
||
│ │ ├── 实时流式输出 (Shell 命令)
|
||
│ │ └── 返回 ToolResult
|
||
│ │
|
||
│ └── 结果回传模型: { type: 'tool_result', content: [...] }
|
||
│
|
||
└── content_block.type === 'text'
|
||
└── 直接渲染 Markdown 到终端
|
||
```
|
||
|
||
## 2. 完整工具清单
|
||
|
||
### 2.1 文件系统工具
|
||
|
||
#### BashTool (`tools/BashTool/`)
|
||
- **功能**: 执行 Shell 命令 (bash/sh/zsh)
|
||
- **参数**: `command`, `description`, `timeout`, `dangerouslyDisableSandbox`
|
||
- **安全**: 沙箱模式、危险命令检测、命令白名单/黑名单
|
||
- **输出**: stdout + stderr 流式返回
|
||
|
||
#### PowerShellTool (`tools/PowerShellTool/`)
|
||
- **功能**: Windows PowerShell 命令执行
|
||
- **参数**: 同 BashTool，适配 PowerShell 语法
|
||
|
||
#### FileReadTool (`tools/FileReadTool/`)
|
||
- **功能**: 读取文件内容（支持分段、PDF、图片）
|
||
- **参数**: `file_path`, `offset?`, `limit?`, `pages?`
|
||
- **特性**: 图片自动识别显示，PDF 分页，大文件分段
|
||
|
||
#### FileWriteTool (`tools/FileWriteTool/`)
|
||
- **功能**: 创建/覆盖文件
|
||
- **参数**: `file_path`, `content`
|
||
- **约束**: 不在已有文件未读取时直接覆盖
|
||
|
||
#### FileEditTool (`tools/FileEditTool/`)
|
||
- **功能**: 基于字符串匹配的精准文件编辑
|
||
- **参数**: `file_path`, `old_string`, `new_string`, `replace_all?`
|
||
- **特性**:
|
||
- 要求 `old_string` 在文件中唯一（避免歧义编辑）
|
||
- 支持 `replace_all` 全局替换
|
||
- Diff 渲染展示变更
|
||
|
||
#### GlobTool (`tools/GlobTool/`)
|
||
- **功能**: 文件名模式搜索
|
||
- **参数**: `pattern`, `path?`
|
||
- **底层**: 使用 fast-glob / Bun 文件系统 API
|
||
|
||
#### GrepTool (`tools/GrepTool/`)
|
||
- **功能**: 文件内容正则搜索
|
||
- **参数**: `pattern`, `path?`, `glob?`, `output_mode?`, `-i?`, `multiline?`, `head_limit?`
|
||
- **底层**: 调用 ripgrep (rg) 可执行文件
|
||
|
||
#### NotebookEditTool (`tools/NotebookEditTool/`)
|
||
- **功能**: 编辑 Jupyter Notebook (.ipynb) 文件
|
||
- **参数**: `notebook_path`, `cell_id?`, `new_source`, `cell_type?`, `edit_mode?`
|
||
- **操作**: 替换/插入/删除 Cell
|
||
|
||
### 2.2 AI 编排工具
|
||
|
||
#### AgentTool (`tools/AgentTool/`)
|
||
- **功能**: 启动子 Agent 处理复杂任务
|
||
- **参数**: `description` (3-5 词), `prompt` (任务描述), `subagent_type?`, `model?`, `run_in_background?`
|
||
- **Agent 类型**:
|
||
- `general-purpose` — 通用 Agent（默认有全部工具）
|
||
- `statusline-setup` — 配置状态栏
|
||
- `claude-code-guide` — 回答 Claude Code 使用问题
|
||
- **执行模式**:
|
||
- 前台：等待结果返回后继续
|
||
- 后台 (`run_in_background: true`)：异步执行，完成时通知
|
||
|
||
#### SkillTool (`tools/SkillTool/`)
|
||
- **功能**: 执行可用技能
|
||
- **参数**: `skill` (技能名), `args?`
|
||
- **技能来源**: 内置技能 + 用户自定义 + MCP 技能
|
||
|
||
#### BriefTool (`tools/BriefTool/`)
|
||
- **功能**: 对指定内容做摘要/压缩
|
||
- **参数**: `content`, `instruction?`
|
||
|
||
#### AskUserQuestionTool (`tools/AskUserQuestionTool/`)
|
||
- **功能**: 在工具调用流程中向用户提问
|
||
- **参数**: `questions[]` (含选项、多选、预览等)
|
||
- **特性**: 渲染交互式选项 UI
|
||
|
||
### 2.3 任务管理工具
|
||
|
||
#### TaskCreateTool
|
||
- **功能**: 创建结构化任务
|
||
- **参数**: `subject`, `description`, `activeForm?`, `metadata?`
|
||
|
||
#### TaskListTool
|
||
- **功能**: 列出所有任务及其状态
|
||
|
||
#### TaskGetTool
|
||
- **功能**: 获取指定任务的完整详情
|
||
|
||
#### TaskUpdateTool
|
||
- **功能**: 更新任务状态/属性/依赖
|
||
- **参数**: `taskId`, `status?`, `subject?`, `addBlocks?`, `addBlockedBy?`
|
||
|
||
#### TaskOutputTool
|
||
- **功能**: 获取后台任务的输出
|
||
|
||
#### TaskStopTool
|
||
- **功能**: 停止运行中的任务
|
||
|
||
#### TodoWriteTool (`tools/TodoWriteTool/`)
|
||
- **功能**: 写入待办列表
|
||
|
||
### 2.4 Web 工具
|
||
|
||
#### WebFetchTool
|
||
- **功能**: 获取网页内容并分析
|
||
- **参数**: `url`, `prompt` (从页面提取什么信息)
|
||
- **特性**: HTML → Markdown 转换，15分钟缓存
|
||
|
||
#### WebSearchTool
|
||
- **功能**: Web 搜索
|
||
- **参数**: `query`, `allowed_domains?`, `blocked_domains?`
|
||
- **要求**: 结果需标注来源
|
||
|
||
#### WebBrowserTool
|
||
- **功能**: 浏览器自动化操作
|
||
|
||
### 2.5 计划/Worktree 工具
|
||
|
||
#### EnterPlanModeTool
|
||
- **功能**: 进入计划模式，用于复杂任务的设计阶段
|
||
- **触发条件**:
|
||
1. 新功能实现
|
||
2. 多种可行方案
|
||
3. 涉及架构决策
|
||
4. 多文件变更
|
||
|
||
#### ExitPlanModeTool
|
||
- **功能**: 退出计划模式，提交方案供用户审批
|
||
|
||
#### EnterWorktreeTool
|
||
- **功能**: 创建 Git Worktree 隔离工作区
|
||
- **参数**: `name?` (可选名称)
|
||
|
||
#### ExitWorktreeTool
|
||
- **功能**: 退出 Git Worktree
|
||
- **参数**: `action` ("keep"|"remove"), `discard_changes?`
|
||
|
||
### 2.6 MCP 工具
|
||
|
||
#### MCPTool
|
||
- **功能**: 调用 MCP 服务端提供的通用工具
|
||
|
||
#### McpAuthTool
|
||
- **功能**: MCP 服务端 OAuth 认证
|
||
|
||
#### ListMcpResourcesTool
|
||
- **功能**: 列出 MCP 服务端提供的资源
|
||
|
||
#### ReadMcpResourceTool
|
||
- **功能**: 读取指定 MCP 资源
|
||
|
||
### 2.7 协作/通信工具
|
||
|
||
#### SendMessageTool
|
||
- **功能**: 向用户发送消息通知
|
||
|
||
#### SendUserFileTool
|
||
- **功能**: 发送文件给用户 (ANT/KAIROS)
|
||
|
||
#### PushNotificationTool
|
||
- **功能**: 推送通知 (KAIROS)
|
||
|
||
#### TeamCreateTool / TeamDeleteTool
|
||
- **功能**: 创建/删除团队
|
||
|
||
#### ListPeersTool
|
||
- **功能**: 列出在线同伴/协作者
|
||
|
||
### 2.8 调度/监控工具
|
||
|
||
#### ScheduleCronTool (3个子工具)
|
||
- `CronCreateTool` — 创建定时任务
|
||
- `CronListTool` — 列出定时任务
|
||
- `CronDeleteTool` — 删除定时任务
|
||
- **特性**: 支持 Cron 表达式，Jitter 偏移
|
||
|
||
#### MonitorTool
|
||
- **功能**: 主动监控检查
|
||
|
||
#### RemoteTriggerTool
|
||
- **功能**: 远程触发任务执行
|
||
|
||
#### SleepTool
|
||
- **功能**: 休眠/等待指定时间
|
||
- **用途**: 定时任务等待 (PROACTIVE 模式)
|
||
|
||
### 2.9 专用工具
|
||
|
||
#### LSPTool
|
||
- **功能**: 调用 LSP (Language Server Protocol) 获取代码智能
|
||
|
||
#### ToolSearchTool
|
||
- **功能**: 搜索可用工具
|
||
|
||
#### ConfigTool
|
||
- **功能**: 读写配置项
|
||
|
||
#### CtxInspectTool
|
||
- **功能**: 检查当前上下文状态
|
||
|
||
#### DiscoverSkillsTool
|
||
- **功能**: 发现可用技能
|
||
|
||
#### SnipTool
|
||
- **功能**: 从内容中裁剪/截取片段
|
||
|
||
#### WorkflowTool
|
||
- **功能**: 执行预定义工作流
|
||
|
||
#### SubscribePRTool
|
||
- **功能**: 订阅 GitHub PR 状态更新
|
||
|
||
#### VerifyPlanExecutionTool
|
||
- **功能**: 验证计划是否正确执行
|
||
|
||
#### TerminalCaptureTool
|
||
- **功能**: 捕获终端输出截图
|
||
|
||
#### SyntheticOutputTool
|
||
- **功能**: 生成合成输出数据
|
||
|
||
#### ReviewArtifactTool
|
||
- **功能**: 审查产出物（代码审查）
|
||
|
||
#### TungstenTool
|
||
- **功能**: 特殊内部工具（少量使用）
|
||
|
||
#### OverflowTestTool
|
||
- **功能**: 溢出/边界测试（仅测试用）
|
||
|
||
#### REPLTool
|
||
- **功能**: 执行 REPL 代码片段 (ANT Only)
|
||
|
||
#### SuggestBackgroundPRTool
|
||
- **功能**: 后台建议创建 PR (ANT Only)
|
||
|
||
### 2.10 测试工具
|
||
|
||
#### TestingPermissionTool
|
||
- **功能**: 权限系统测试
|
||
|
||
---
|
||
|
||
## 3. 工具安全模型
|
||
|
||
### 3.1 权限层级
|
||
|
||
```
|
||
permissionMode:
|
||
├── default # 每次询问
|
||
├── acceptEdits # 自动批准文件编辑
|
||
├── bypass # 完全跳过权限
|
||
├── plan # 计划模式（只读+计划工具）
|
||
└── custom # 自定义规则
|
||
```
|
||
|
||
### 3.2 权限检查流程
|
||
|
||
```typescript
|
||
async function useCanUseTool(toolName, params, context) {
|
||
// 1. 检查是否 bypass 模式
|
||
if (permissionMode === 'bypass') return true;
|
||
|
||
// 2. 检查工具白名单/黑名单
|
||
if (isInDenyList(toolName)) {
|
||
showDenialMessage();
|
||
return false;
|
||
}
|
||
|
||
// 3. 检查 auto-accept 规则
|
||
if (isAutoAcceptable(toolName, params)) return true;
|
||
|
||
// 4. 弹出权限请求 UI 等待用户确认
|
||
const approved = await showPermissionDialog(toolName, params);
|
||
return approved;
|
||
}
|
||
```
|
||
|
||
### 3.3 沙箱系统
|
||
|
||
`BashTool` 支持沙箱模式：
|
||
- 网络隔离 (阻止出站连接)
|
||
- 文件系统只读挂载
|
||
- 进程隔离
|
||
|
||
由 `@anthropic-ai/sandbox-runtime` 提供，通过 `dangerouslyDisableSandbox` 参数控制。
|
||
|
||
---
|
||
|
||
## 4. 工具体系统计
|
||
|
||
| 分类 | 数量 |
|
||
|---|---|
|
||
| 文件系统 | 8 |
|
||
| AI 编排 | 4 |
|
||
| 任务管理 | 8 |
|
||
| Web | 3 |
|
||
| 计划/Worktree | 4 |
|
||
| MCP | 4 |
|
||
| 协作/通信 | 6 |
|
||
| 调度/监控 | 6 |
|
||
| 专用工具 | 15+ |
|
||
| 测试 | 1 |
|
||
| **总计** | **约 60 个工具** |
|
||
|
||
---
|
||
|
||
*本文档基于 2026-06-11 源码状态生成*
|