docs: 完成大量文档

docs/tools/search-and-navigation.mdx

@@ -3,35 +3,136 @@ title: "搜索与导航"
 description: "AI 如何在百万行代码中精准定位目标"
 ---
 
-{/* 本章目标：介绍搜索类工具和工具搜索机制 */}
-
 ## 两种搜索维度
 
-| 维度 | 工具 | 适用场景 |
-|------|------|---------|
-| **按名称找文件** | Glob | "找到所有测试文件"、"找 config 开头的文件" |
-| **按内容找代码** | Grep | "哪里定义了这个函数"、"谁在调用这个 API" |
+| 维度 | 工具 | 底层实现 | 适用场景 |
+|------|------|----------|---------|
+| **按名称找文件** | Glob | ripgrep `--files` + glob 过滤 | "找到所有测试文件"、"找 config 开头的文件" |
+| **按内容找代码** | Grep | ripgrep 正则搜索 | "哪里定义了这个函数"、"谁在调用这个 API" |
 
-两者组合使用，AI 就拥有了在大型项目中"导航"的能力。
+两者共享同一个 ripgrep 引擎，通过不同的参数组合实现不同搜索模式。
 
-## 搜索结果的智能处理
+## ripgrep 的内嵌方式
 
-大型项目的搜索结果可能有成千上万条，直接全部返回不现实：
+Claude Code 不依赖系统安装的 ripgrep——它在 `src/utils/ripgrep.ts` 中实现了三级降级策略：
 
-- **结果数量限制**：默认最多返回 250 条匹配
-- **上下文行**：Grep 支持显示匹配行前后的上下文（类似 `grep -C`）
-- **按修改时间排序**：Glob 默认把最近修改的文件排在前面
-- **文件类型过滤**：按语言类型过滤（只搜 `.ts` 文件、只搜 `.py` 文件）
+```
+优先级 1: 系统 ripgrep (USE_BUILTIN_RIPGREP=false)
+  → 使用 PATH 中的 rg 二进制
+  → 安全考虑：只用命令名 'rg'，不用完整路径，防止 PATH 劫持
 
-## 工具发现机制
+优先级 2: 内嵌模式 (bundled/native build)
+  → process.execPath 自身，argv0='rg'
+  → Bun 将 rg 静态编译进二进制，通过 argv0 分发
 
-当可用工具超过 50 个时，AI 可能不知道该用哪个。系统提供了 **ToolSearch** 机制：
+优先级 3: vendor 目录 (npm build)
+  → vendor/ripgrep/{arch}-{platform}/rg
+  → macOS 需要 codesign 签名 + 移除 quarantine xattr
+```
 
-- AI 可以用自然语言描述需求（"我需要连接数据库"）
-- 系统在所有已注册工具（包括 MCP 提供的）中搜索匹配
-- 返回最相关的工具列表及使用说明
+平台适配示例：
+```
+vendor/ripgrep/
+  ├── x86_64-darwin/rg      # macOS Intel
+  ├── arm64-darwin/rg        # macOS Apple Silicon
+  ├── x86_64-linux/rg        # Linux Intel
+  ├── arm64-linux/rg         # Linux ARM
+  └── x86_64-win32/rg.exe    # Windows
+```
 
-这让 AI 在面对庞大的工具库时不会迷路。
+### macOS 代码签名
+
+vendor 模式下的 rg 二进制需要 ad-hoc 签名才能通过 Gatekeeper（`codesignRipgrepIfNecessary()`）：
+
+```typescript
+// 首次使用时执行：
+// 1. 检查是否已是有效签名
+codesign -vv -d <rg-path>
+// 2. 如果只是 linker-signed，重新签名
+codesign --sign - --force --preserve-metadata=entitlements,requirements,flags,runtime <rg-path>
+// 3. 移除隔离属性
+xattr -d com.apple.quarantine <rg-path>
+```
+
+## 搜索结果的设计考量
+
+### head_limit 与 Token 预算
+
+大型项目的搜索结果可能有数十万条。默认最多返回 250 条匹配——这不是随意选择，而是**token 预算**的约束：
+
+- 每条匹配行约 50-100 token
+- 250 条 ≈ 12,500-25,000 token
+- 这大约占 200k 上下文窗口的 6-12%
+- 超过这个比例，AI 的推理质量会下降
+
+Grep 工具的 `head_limit` 参数让 AI 可以按需调整——搜索小项目时可以用更大的值。
+
+### 按修改时间排序
+
+Glob 默认把**最近修改的文件排在前面**。这不是默认的文件系统排序，而是刻意的设计决策：
+
+```
+设计假设：最近修改的文件最可能与当前任务相关
+实际效果：AI 优先看到"活"的代码，而不是沉寂的历史文件
+```
+
+在 `src/tools/GlobTool/` 中，ripgrep 的输出在返回给 AI 前按 mtime 排序。
+
+### ripgrep 的错误处理
+
+ripgrep 执行有专门的错误恢复链（`src/utils/ripgrep.ts`）：
+
+| 错误 | 处理 |
+|------|------|
+| **EAGAIN**（资源不足） | 自动以单线程模式 `-j 1` 重试 |
+| **超时**（默认 20s，WSL 60s） | 返回已有部分结果，丢弃可能不完整的最后一行 |
+| **缓冲区溢出** | 截断到 20MB，返回已收集的结果 |
+| **SIGTERM 失效** | 5 秒后升级为 SIGKILL |
+
+## ToolSearch：在 50+ 工具中发现目标
+
+当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。**ToolSearch**（`src/tools/ToolSearchTool/`）提供了工具发现机制。
+
+### 搜索算法
+
+ToolSearch 实现了基于关键词的加权搜索（`searchToolsWithKeywords()`）：
+
+```
+输入: query = "database connection"
+     ↓
+1. 精确匹配: 检查是否有工具名完全匹配（快速路径）
+2. MCP 前缀匹配: "mcp__postgres" → 匹配所有 postgres 相关工具
+3. 关键词拆分: ["database", "connection"]
+4. 工具名解析:
+   - MCP 工具: "mcp__server__action" → ["server", "action"]
+   - 普通工具: "FileEditTool" → ["file", "edit", "tool"]
+5. 加权评分:
+   - 工具名精确匹配: 10 分（MCP: 12 分）
+   - 工具名部分匹配: 5 分（MCP: 6 分）
+   - searchHint 匹配: 4 分
+   - 描述匹配: 2 分
+6. 必选词过滤: "+database" 前缀表示必须包含
+7. 按分数排序，返回 top-N
+```
+
+### `select:` 直接选择
+
+AI 也可以用 `select:ToolName` 精确选择已知工具。这比搜索更快，且支持逗号分隔的批量选择（`select:A,B,C`）。
+
+### 延迟加载（Deferred Tools）
+
+不是所有工具都常驻内存。MCP 工具和低频工具被标记为 `isDeferredTool`，只有在 ToolSearch 选中后才真正加载。这减少了每次 API 调用的 token 开销（工具描述占用大量 token）。
+
+### 缓存策略
+
+工具描述的获取是 memoized 的——只在延迟工具集合变化时清除缓存：
+
+```typescript
+// 工具名排序后拼接作为缓存 key
+function getDeferredToolsCacheKey(deferredTools: Tools): string {
+  return deferredTools.map(t => t.name).sort().join(',')
+}
+```
 
 ## Web 搜索与抓取
 
@@ -41,3 +142,13 @@ AI 的信息获取不局限于本地代码：
 - **WebFetch**：抓取特定网页内容，转换为 Markdown 供 AI 阅读
 
 这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。
+
+### ripgrep 的流式输出
+
+对于交互式场景（如 QuickOpen），ripgrep 支持**流式输出**（`ripGrepStream()`）：
+
+```
+rg --files → 逐 chunk 到达 → 按行分割 → onLines(lines) 回调
+```
+
+不需要等 ripgrep 完成整个搜索——第一批结果在 rg 仍在遍历目录树时就已展示。调用者可以通过 AbortSignal 提前终止搜索（例如找到足够多的结果后）。

docs/tools/task-management.mdx

@@ -1,50 +1,211 @@
 ---
 title: "任务管理"
-description: "让 AI 的工作有条理、可追踪"
+description: "从单机 Todo 到多 Agent 任务队列的演进"
 ---
 
-{/* 本章目标：介绍任务系统如何帮助 AI 和用户保持同步 */}
+{/* 本章目标：揭示任务系统 V1（内存 TodoWrite）和 V2（文件系统 Task*）的双轨架构，以及依赖管理、认领竞争、验证推动的工程细节 */}
 
-## 为什么需要任务管理
+## 双轨架构：TodoWrite V1 与 Tasks V2
 
-当你给 AI 一个复杂需求（比如"重构整个认证模块"），它可能需要执行几十个步骤。没有任务管理，用户只能被动等待，不知道 AI 做到哪了、还要做什么。
+Claude Code 的任务管理并非单一系统，而是两个并存、按运行模式切换的实现：
 
-## 任务系统的运作方式
+| 维度 | V1: TodoWrite | V2: TaskCreate / TaskUpdate / TaskList / TaskGet |
+|------|--------------|--------------------------------------------------|
+| **启用条件** | 非交互式（pipe/SDK）或 `isTodoV2Enabled()` 返回 `false` | 交互式 REPL（默认）或 `CLAUDE_CODE_ENABLE_TASKS=1` |
+| **存储** | 内存中 `AppState.todos[sessionId]`（Zustand store） | 文件系统 `~/.claude/tasks/<taskListId>/<id>.json` |
+| **数据模型** | `{content, status, activeForm}` — 扁平三元组 | `{id, subject, description, activeForm, owner, status, blocks[], blockedBy[], metadata}` — 完整实体 |
+| **持久化** | 进程退出即丢失 | 跨进程存活，支持多 Agent 并发访问 |
+| **并发安全** | 无（单会话单写者） | 文件锁 + 高水位标记 + TOCTOU 防护 |
 
-AI 可以自主创建和管理任务列表：
+切换逻辑位于 `isTodoV2Enabled()`（`src/utils/tasks.ts:133`）：交互式会话默认启用 V2，SDK/pipe 模式回落 V1。两者互斥——`TodoWriteTool.isEnabled` 返回 `!isTodoV2Enabled()`，而 `TaskCreateTool.isEnabled` 返回 `isTodoV2Enabled()`。
 
-<Steps>
-  <Step title="分解任务">
-    AI 把大需求拆解为多个小任务，创建到任务列表
-  </Step>
-  <Step title="标记进度">
-    开始某个任务时标记为"进行中"，完成后标记为"已完成"
-  </Step>
-  <Step title="依赖管理">
-    任务之间可以设定依赖关系——"任务 B 必须等任务 A 完成后才能开始"
-  </Step>
-  <Step title="用户可见">
-    用户随时可以查看任务列表，了解整体进度
-  </Step>
-</Steps>
+## V1：TodoWrite 的极简设计
 
-## 任务与 Plan Mode 的配合
+TodoWrite 本质是一个**全量替换**操作——每次调用传入完整的 `todos[]` 数组，完全覆盖之前的状态：
 
-面对复杂任务，AI 可以先进入**计划模式**：
+```typescript
+// src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
+async call({ todos }, context) {
+  const todoKey = context.agentId ?? getSessionId()
+  const oldTodos = appState.todos[todoKey] ?? []
+  const allDone = todos.every(_ => _.status === 'completed')
+  const newTodos = allDone ? [] : todos  // 全部完成则清空列表
+  // ... 写入 AppState
+}
+```
 
-1. AI 进入计划模式 → 只允许使用搜索和阅读类工具（不能修改文件）
-2. AI 探索代码库、理解现有架构
-3. AI 制定实施计划，创建任务列表
-4. 用户审批计划
-5. AI 退出计划模式，按计划逐项执行
+### 智能清空与验证推动
 
-这种"先规划、后执行"的方式避免了 AI 盲目行动造成的返工。
+一个微妙的设计：当所有任务都 `completed` 时，`newTodos` 被设为空数组（而非保留 `completed` 列表）。这确保 UI 上不会有"已完成"的视觉噪音。
 
-## 状态展示
+此外，V1 包含一个**验证推动**（verification nudge）机制：当主线程 Agent 完成 3+ 个任务且没有任何一个是验证步骤时，系统在 tool_result 中追加提示，催促 Agent 派生验证子 Agent：
 
-终端 UI 中，任务列表会实时更新：
+```typescript
+// 条件：主线程 + 全部完成 + ≥3 项 + 无验证任务
+if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content))) {
+  verificationNudgeNeeded = true
+}
+// tool_result 中追加：
+// "NOTE: You just closed out 3+ tasks and none was a verification step..."
+```
 
-- 待办任务灰色显示
-- 进行中的任务有旋转动画
-- 已完成的任务打勾标记
-- 被阻塞的任务标注依赖项
+这是防止 Agent "自说自话地宣布完成"的防御性设计——通过结构性推动而非硬约束。
+
+## V2：文件系统持久化的任务系统
+
+### 数据模型
+
+每个任务是一个独立 JSON 文件，路径为 `~/.claude/tasks/<taskListId>/<id>.json`：
+
+```typescript
+// src/utils/tasks.ts — TaskSchema
+{
+  id: string,           // 自增整数（1, 2, 3...）
+  subject: string,      // 祈使句标题（如 "Fix auth bug"）
+  description: string,  // 详细描述
+  activeForm?: string,  // 进行时形式（如 "Fixing auth bug"），用于 spinner
+  owner?: string,       // 认领该任务的 Agent ID/名称
+  status: "pending" | "in_progress" | "completed",
+  blocks: string[],     // 此任务阻塞哪些任务 ID
+  blockedBy: string[],  // 哪些任务 ID 阻塞此任务
+  metadata?: Record<string, unknown>  // 任意附加数据
+}
+```
+
+### 任务列表 ID 的解析优先级
+
+`getTaskListId()` 按 5 级优先级解析任务归属：
+
+1. `CLAUDE_CODE_TASK_LIST_ID` 环境变量（显式覆盖）
+2. 进程内 teammate 上下文的 teamName（共享 leader 的任务列表）
+3. `CLAUDE_CODE_TEAM_NAME` 环境变量（进程级 teammate）
+4. Leader 通过 `setLeaderTeamName()` 设置的 teamName
+5. `getSessionId()`（独立会话的兜底）
+
+这意味着多 Agent 团队模式下，所有 teammate 自动共享同一个任务列表，无需额外协调。
+
+### ID 分配与高水位标记
+
+任务 ID 是简单的递增整数，但在并发场景下需要防止竞争：
+
+```typescript
+// src/utils/tasks.ts — createTask() 简化
+async function createTask(taskListId, taskData) {
+  release = await lockfile.lock(lockPath, LOCK_OPTIONS)  // 获取排他锁
+  const highestId = await findHighestTaskId(taskListId)   // 读取当前最大 ID
+  const id = String(highestId + 1)                        // 递增
+  await writeFile(path, JSON.stringify({ id, ...taskData }))
+  return id
+}
+```
+
+锁配置使用指数退避重试 30 次（总计约 2.6 秒），适配 10+ 并发 Agent 的 swarm 场景。
+
+高水位标记文件 `.highwatermark` 确保删除任务后 ID 不会被重用——即使任务 #5 被删除，下一个新建任务仍然是 #6。
+
+## 依赖管理：blocks / blockedBy
+
+任务间的依赖通过双向链表式的 `blocks` / `blockedBy` 字段实现：
+
+- `taskA.blocks = ["3"]` 表示 "任务 A 完成前，任务 3 不能开始"
+- `task3.blockedBy = ["A"]` 表示 "任务 3 必须等任务 A 完成"
+
+`blockTask()` 函数同时维护两端：
+
+```typescript
+// src/utils/tasks.ts — blockTask()
+// A blocks B → 更新 A.blocks 加入 B，同时更新 B.blockedBy 加入 A
+if (!fromTask.blocks.includes(toTaskId)) {
+  await updateTask(taskListId, fromTaskId, { blocks: [...fromTask.blocks, toTaskId] })
+}
+if (!toTask.blockedBy.includes(fromTaskId)) {
+  await updateTask(taskListId, toTaskId, { blockedBy: [...toTask.blockedBy, fromTaskId] })
+}
+```
+
+删除任务时，系统自动清理所有指向它的依赖引用（`deleteTask()` 遍历全部任务移除 `blocks` 和 `blockedBy` 中的引用）。
+
+## 任务认领与并发控制
+
+`claimTask()` 是 V2 的核心并发原语，支持两种锁定粒度：
+
+### 1. 任务级锁（默认）
+
+仅锁定目标任务文件，适合单 Agent 场景：
+
+```
+getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner
+```
+
+### 2. 列表级锁 + Agent 忙碌检查
+
+当 `checkAgentBusy: true` 时，锁定整个任务列表目录（`.lock` 文件），原子化地完成：
+
+```
+listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner
+```
+
+认领失败有 4 种原因：
+
+| `reason` | 含义 |
+|----------|------|
+| `task_not_found` | 任务 ID 不存在 |
+| `already_claimed` | 已被其他 Agent 认领 |
+| `already_resolved` | 任务已标记 completed |
+| `blocked` | blockedBy 列表中有未完成的任务 |
+| `agent_busy` | 该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式） |
+
+## Agent 团队的任务生命周期
+
+在 swarms 模式下，任务系统的生命周期是这样的：
+
+```
+Leader 创建团队
+  ↓
+Leader 用 TaskCreate 创建任务（status=pending, owner=undefined）
+  ↓
+Leader 用 TaskUpdate 设置依赖关系（addBlocks/addBlockedBy）
+  ↓
+Teammate 调用 TaskList → 发现可认领的任务
+  ↓
+Teammate 调用 TaskUpdate(taskId, {status: "in_progress"})
+         → 自动设置 owner 为 teammate 名称
+         → Leader 通过 mailbox 收到 task_assignment 通知
+  ↓
+Teammate 完成工作 → TaskUpdate(taskId, {status: "completed"})
+         → tool_result 提示 "Call TaskList to find your next available task"
+         → 依赖此任务的其他任务自动解锁
+  ↓
+Teammate 异常退出 → unassignTeammateTasks()
+         → 未完成任务被重置为 pending + owner=undefined
+         → Leader 收到通知并重新分配
+```
+
+### Hooks 集成
+
+TaskCreate 和 TaskUpdate 都集成了 hooks 系统：
+
+- **创建时**：`executeTaskCreatedHooks` — 外部钩子可以阻断任务创建（blockingError 导致任务被立即删除）
+- **完成时**：`executeTaskCompletedHooks` — 外部钩子可以阻断任务标记为完成
+
+这允许外部系统（CI、审批流）参与任务状态机。
+
+## activeForm：终端 UX 的细节
+
+每个任务有两个文案字段：
+
+- `subject`：祈使句，用于任务列表展示（"Fix auth bug"）
+- `activeForm`：进行时形式，用于 spinner 动画（"Fixing auth bug..."）
+
+当 `activeForm` 缺省时，spinner 回退显示 `subject`。这个看似微小的设计确保了用户在等待时看到的是"正在做什么"而非"要做什么"。
+
+## Plan Mode 与任务系统的配合
+
+Plan Mode（计划模式）和任务系统是互补但独立的机制：
+
+1. Plan Mode 限制工具集为只读（搜索、阅读），迫使 AI 先理解再行动
+2. AI 在 Plan Mode 中用 TaskCreate 建立任务列表
+3. 用户审批后退出 Plan Mode
+4. AI 按 `blockedBy` 拓扑序逐项执行，每项用 TaskUpdate 标记进度
+
+`shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。