Files

renjianbo beff3fac8d fix: delete agent 500 error + dynamic personality + deployment guide

- 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>

2026-06-29 01:17:21 +08:00

10 KiB

Raw Blame History

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 将所有工具汇总导出：

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 权限检查流程

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 源码状态生成

10 KiB Raw Blame History Unescape Escape

Claude Code 工具系统分析

1. 工具系统架构

1.1 工具基类 (src/Tool.ts, 30KB)

1.2 工具注册 (src/tools.ts)

1.3 工具调用流程

2. 完整工具清单

2.1 文件系统工具

BashTool (tools/BashTool/)

PowerShellTool (tools/PowerShellTool/)

FileReadTool (tools/FileReadTool/)

FileWriteTool (tools/FileWriteTool/)

FileEditTool (tools/FileEditTool/)

GlobTool (tools/GlobTool/)

GrepTool (tools/GrepTool/)

NotebookEditTool (tools/NotebookEditTool/)

2.2 AI 编排工具

AgentTool (tools/AgentTool/)

SkillTool (tools/SkillTool/)

BriefTool (tools/BriefTool/)

AskUserQuestionTool (tools/AskUserQuestionTool/)

2.3 任务管理工具

TaskCreateTool

TaskListTool

TaskGetTool

TaskUpdateTool

TaskOutputTool

TaskStopTool

TodoWriteTool (tools/TodoWriteTool/)

2.4 Web 工具

WebFetchTool

WebSearchTool

WebBrowserTool

2.5 计划/Worktree 工具

EnterPlanModeTool

ExitPlanModeTool

EnterWorktreeTool

ExitWorktreeTool

2.6 MCP 工具

MCPTool

McpAuthTool

ListMcpResourcesTool

ReadMcpResourceTool

2.7 协作/通信工具

SendMessageTool

SendUserFileTool

PushNotificationTool

TeamCreateTool / TeamDeleteTool

ListPeersTool

2.8 调度/监控工具

ScheduleCronTool (3个子工具)

MonitorTool

RemoteTriggerTool

SleepTool

2.9 专用工具

LSPTool

ToolSearchTool

ConfigTool

CtxInspectTool

DiscoverSkillsTool

SnipTool

WorkflowTool

SubscribePRTool

VerifyPlanExecutionTool

TerminalCaptureTool

SyntheticOutputTool

ReviewArtifactTool

TungstenTool

OverflowTestTool

REPLTool

SuggestBackgroundPRTool

2.10 测试工具

TestingPermissionTool

3. 工具安全模型

3.1 权限层级

3.2 权限检查流程

3.3 沙箱系统

4. 工具体系统计

10 KiB

Raw Blame History

1.1 工具基类 (`src/Tool.ts`, 30KB)

1.2 工具注册 (`src/tools.ts`)

BashTool (`tools/BashTool/`)

PowerShellTool (`tools/PowerShellTool/`)

FileReadTool (`tools/FileReadTool/`)

FileWriteTool (`tools/FileWriteTool/`)

FileEditTool (`tools/FileEditTool/`)

GlobTool (`tools/GlobTool/`)

GrepTool (`tools/GrepTool/`)

NotebookEditTool (`tools/NotebookEditTool/`)

AgentTool (`tools/AgentTool/`)

SkillTool (`tools/SkillTool/`)

BriefTool (`tools/BriefTool/`)

AskUserQuestionTool (`tools/AskUserQuestionTool/`)

TodoWriteTool (`tools/TodoWriteTool/`)