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
parent 86b98865e3
commit beff3fac8d
1084 changed files with 117315 additions and 1281 deletions
--- a/clode/tools.md
+++ b/clode/tools.md
@@ -0,0 +1,380 @@
+# 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 源码状态生成*