docs: 添加文档大纲及 superpowers/outline 目录

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>
2026-06-24 17:15:50 +00:00 · 2026-06-15 16:17:03 +08:00
parent 37dac682b9
commit 178868175e
39 changed files with 9972 additions and 0 deletions
--- a/docs/outline-output/user/06-agents-plan-tasks.md
+++ b/docs/outline-output/user/06-agents-plan-tasks.md
@@ -0,0 +1,300 @@
+# 第六章：让 Claude 帮你跑大任务 -- 子代理、Plan 模式、Task 系统
+
+> 当任务太大、一步做不完时，如何让 Claude 自己拆分、规划和并行推进。
+
+## 什么时候该"升级"任务处理方式
+
+日常对话中，你给 Claude 一条指令，它执行一次就完成了。但有些任务天然不适合一口气干完：代码库迁移涉及几十个文件、排查 bug 需要同时在多处搜索、重构需要先理清依赖再动手。在这些场景下，三个工具能帮你把大任务拆小：**子代理（Agent）** 处理独立的子任务，**Plan 模式** 先想清楚再动手，**Task 系统** 跟踪进度和依赖。
+
+一个简单的判断标准：如果你发现自己反复对 Claude 说"再看看那个文件"、"顺便改一下这个"，说明这个任务已经需要拆分了。
+
+## 子代理：让 Claude 派一个"分身"去干活
+
+Claude Code 有一个 Agent 工具，允许 Claude 在对话过程中派生出子代理来处理子任务。子代理有自己的上下文和工具集，完成后会把结果汇报给主对话。你不需要手动启动子代理 -- 当 Claude 判断某个子任务适合独立处理时，它会自动使用 Agent 工具。
+
+### 内置的子代理类型
+
+Claude Code 内置了几种专门化的子代理，各有分工：
+
+- **general-purpose** -- 通用子代理，能使用全部工具。当你让 Claude 做一个需要多步骤研究或跨文件分析的任务时，它可能会派这个子代理去执行。
+- **Explore** -- 只读搜索专家，不能修改任何文件。擅长用 Glob、Grep、FileRead 快速在代码库中定位文件和关键词。当你问"这个功能在代码里怎么实现的"时，Explore 子代理会并行搜索多个路径然后汇总结果。
+- **Plan** -- 架构规划师，同样只读。它会深入阅读代码、理解现有架构，然后输出一份包含步骤和关键文件的实施方案。
+
+你不需要记住这些类型名。Claude 会根据你的问题自动选择合适的子代理。
+
+### 子代理是怎么工作的
+
+当你给 Claude 一个复杂指令时，它可能会这样处理：
+
+```
+你: 把 src/utils/ 下所有用到 deprecatedFunction 的地方重构掉
+
+Claude: [使用 Agent 工具，派出一个 Explore 子代理搜索所有引用]
+
+  > Agent (Explore): 正在搜索 src/utils/ 下的 deprecatedFunction 引用...
+
+  [子代理完成，返回搜索结果]
+
+Claude: 找到了 12 处引用，分布在 5 个文件中。让我逐一替换...
+```
+
+子代理运行时，你会看到一个带颜色的进度提示，标明子代理的类型和当前状态。每个子代理的输出会作为一条消息出现在对话中，Claude 主线程会基于这些结果继续工作。
+
+子代理之间也可以形成层级：主对话可以派子代理，子代理在复杂场景下还能继续派更小的子代理（取决于配置和 feature flag）。
+
+### 关于并行子代理
+
+当你使用一些 Skill（如 `ultra-batch` 或 `dispatching-parallel-agents`）时，可以显式要求 Claude 同时派发多个子代理并行处理不同子任务。这在需要同时探索多个代码路径、或同时修改多个独立文件时特别高效。
+
+```
+你: 用 3 个子代理同时查一下 authentication、authorization 和 session 管理的实现
+
+Claude: [同时派出 3 个 Explore 子代理，并行搜索]
+  > Agent #1 (Explore): 搜索 authentication 相关文件...
+  > Agent #2 (Explore): 搜索 authorization 相关文件...
+  > Agent #3 (Explore): 搜索 session 管理相关文件...
+
+  [三个子代理各自返回结果，Claude 汇总]
+```
+
+## Task 系统：跟踪任务进度和依赖
+
+Task 系统提供了一套完整的任务管理工具，让 Claude 能够像使用待办清单一样跟踪工作进度。这套工具包括 `TaskCreate`、`TaskUpdate`、`TaskList` 和 `TaskGet`。
+
+### 任务是怎么创建的
+
+Claude 会在拆分大任务时自动使用 `TaskCreate` 创建子任务。你也可以在对话中明确要求它创建任务清单：
+
+```
+你: 帮我把用户模块重构拆成任务清单
+
+Claude: [使用 TaskCreate 创建任务]
+
+  > Task #1 created: 提取用户验证逻辑到独立 service
+  > Task #2 created: 重构用户数据模型，添加类型约束
+  > Task #3 created: 更新 API 路由使用新的 service 层
+  > Task #4 created: 编写单元测试覆盖新 service
+```
+
+每个任务包含标题（subject）、描述（description）和状态（pending / in_progress / completed）。创建任务时，Claude 还可以设置 `activeForm`（进行中时显示的活动描述，如"Running tests"），以及任意的 `metadata` 键值对。
+
+### 任务状态流转
+
+任务创建后默认是 `pending` 状态。Claude 会用 `TaskUpdate` 把任务标记为 `in_progress`（开始执行）、`completed`（完成）或 `deleted`（删除）。
+
+```
+你: 继续执行任务清单
+
+Claude: [使用 TaskUpdate 更新状态]
+
+  > Updated task #1 in_progress, status
+  [开始执行第一个任务...]
+
+  > Updated task #1 completed, status
+  > Updated task #2 in_progress, status
+  [继续下一个任务...]
+```
+
+用 `TaskList` 可以随时查看所有任务的当前状态：
+
+```
+#1 [in_progress] 提取用户验证逻辑到独立 service
+#2 [pending] 重构用户数据模型，添加类型约束
+#3 [pending] 更新 API 路由使用新的 service 层
+#4 [pending] 编写单元测试覆盖新 service
+```
+
+`TaskGet` 则用于查看单个任务的完整详情，包括描述和依赖关系。
+
+### 任务依赖
+
+任务之间可以设置阻塞关系。如果任务 A 阻塞了任务 B（task B 被 task A blocked），那么在 A 完成之前，B 无法开始。Claude 在规划执行顺序时会参考这些依赖关系：
+
+```
+#1 [completed] 提取用户验证逻辑到独立 service
+#2 [in_progress] 重构用户数据模型，添加类型约束
+#3 [blocked by #2] 更新 API 路由使用新的 service 层
+#4 [blocked by #3] 编写单元测试覆盖新 service
+```
+
+### 任务钩子
+
+Task 系统支持 hooks 集成。你可以在 `settings.json` 中配置 hooks，让特定事件（如任务创建、任务完成）触发自定义逻辑。比如，当某个关键任务完成时自动运行测试套件。
+
+## Plan 模式：先想清楚再动手
+
+Plan 模式是处理复杂任务的最佳实践。进入 Plan 模式后，Claude 会切换到只读状态：它可以搜索代码、阅读文件、分析架构，但不能修改任何文件。等方案设计完毕并获得你的批准后，才退出 Plan 模式开始实际编码。
+
+### 进入 Plan 模式
+
+有两种方式进入 Plan 模式：
+
+**方式一：用 `/plan` 命令**
+
+```
+/plan 重构用户模块的数据层
+```
+
+这会启用 Plan 模式，并把你给出的描述作为规划目标。Claude 会在只读状态下探索代码库、设计实施方案。
+
+**方式二：让 Claude 自动进入**
+
+对于足够复杂的任务，Claude 会自动调用 `EnterPlanMode` 工具进入 Plan 模式。你不需要显式要求，但可以用 `/plan` 强制进入。
+
+### Plan 模式下发生了什么
+
+进入 Plan 模式后，权限模式会切换为 `plan`。在这个模式下：
+
+- Claude 只能使用只读工具（Read、Glob、Grep、Bash 的只读操作）
+- 文件编辑工具（Edit、Write）被禁用
+- Claude 会深入探索代码库，理解现有模式和架构
+- Claude 可能会问你一些问题来澄清需求
+
+Claude 会把规划结果写入一个计划文件。你可以随时用 `/plan` 查看当前计划，或用 `/plan open` 在你的默认编辑器中打开并手动修改计划内容。
+
+### 退出 Plan 模式并开始执行
+
+当 Claude 完成规划后，它会调用 `ExitPlanMode` 工具。这时你会看到一个审批对话框，显示完整的计划内容。你可以：
+
+- **批准** -- Claude 立即开始按计划编码
+- **编辑** -- 在编辑器中修改计划，然后批准修改后的版本
+- **拒绝** -- 让 Claude 重新规划
+
+批准后，权限模式会恢复到进入 Plan 模式之前的状态（通常是 `default` 或 `auto`），Claude 开始按计划执行。
+
+### VerifyPlanExecution：确认计划已正确执行
+
+在较新的版本中，Claude 在退出 Plan 模式之前可能会调用 `VerifyPlanExecution` 工具，对计划的执行情况进行校验。它会检查：
+
+- 计划中的所有步骤是否都已完成
+- 测试是否通过
+- 关键文件是否已正确创建或修改
+
+如果某些步骤被跳过或失败了，验证结果中会包含说明。
+
+## Goal 命令：给 Claude 一个自主推进的目标
+
+`/goal` 命令让你给 Claude 设定一个长期目标，然后 Claude 会自主地持续工作直到目标达成，而不是等你一轮一轮地下指令。
+
+### 设置和查看目标
+
+```
+/goal 把所有 API 端点从 REST 迁移到 GraphQL
+```
+
+这会设定一个目标。Claude 会开始自主规划、拆分任务、执行修改，每完成一轮会自动继续下一轮。你可以随时查看目标状态：
+
+```
+/goal status
+```
+
+输出会显示目标描述、当前状态、已用 token 数量、活跃时间和已执行的轮次。
+
+### 控制目标进度
+
+`/goal` 支持几个子命令来控制执行：
+
+- `/goal pause` -- 暂停自动继续
+- `/goal resume` -- 从暂停恢复
+- `/goal continue` -- 在达到最大轮次限制后重置计数器继续
+- `/goal complete` -- 手动标记目标已完成
+- `/goal clear` -- 清除当前目标
+
+当 Claude 遇到无法自行解决的阻塞时，它会用 `GoalTool` 将目标标记为 `blocked` 并说明原因。连续 3 轮遇到同样的阻塞条件后，目标会被自动标记为阻塞状态，等待你介入。
+
+### Goal 与 Task 系统的配合
+
+`/goal` 通常会与 Task 系统配合使用。Claude 设定目标后会自动创建任务清单，然后逐个执行。你可以在 `/workflows` 面板中同时看到目标和任务的状态。
+
+## Worktree 隔离：在独立分支里做实验
+
+当你需要做一些可能有风险或需要独立验证的改动时，Claude 可以用 `EnterWorktree` 工具创建一个 git worktree -- 一个独立的工作目录，关联到一个新的 git 分支。
+
+### Claude 如何使用 Worktree
+
+你不需要手动管理 worktree。当你告诉 Claude 做一些需要隔离的操作时，它可能会自动调用 `EnterWorktree`：
+
+```
+你: 试试把 ORM 从 Prisma 换成 Drizzle，先在一个独立分支上验证可行性
+```
+
+Claude 会创建一个 worktree，在新分支上做实验，完成后汇报结果。你的主工作目录完全不受影响。
+
+### Worktree 的生命周期
+
+- **创建**：`EnterWorktree` 创建 worktree 和关联分支，会话切换到 worktree 目录
+- **退出 -- 保留**：`ExitWorktree(action: "keep")` 保留 worktree 和分支，会话切回原目录
+- **退出 -- 删除**：`ExitWorktree(action: "remove")` 删除 worktree 和分支。如果有未提交的改动或未合并的 commit，Claude 会先列出它们，需要你确认并传入 `discard_changes: true` 才会执行删除
+
+你也可以在启动 Claude 时直接指定 worktree 模式：
+
+```bash
+claude --tmux --worktree
+```
+
+这会自动创建一个 worktree 并在 tmux 会话中运行。
+
+## Coordinator 模式：多 Worker 协作
+
+Coordinator 模式是一个高级特性（需要 `COORDINATOR_MODE` feature flag），把 Claude 变成一个任务调度器。启用后，Claude 只能使用 Agent（派发子任务）、SendMessage（给子代理发消息）和 TaskStop（停止子任务）三个工具，不再直接执行任何操作。
+
+### 启用 Coordinator 模式
+
+```
+/coordinator
+```
+
+启用后，Claude 会变成一个编排者。你给它一个大任务，它会拆分成多个子任务，然后派发给不同的 worker 子代理并行执行：
+
+```
+你: 把这个 monorepo 的所有包从 CommonJS 迁移到 ESM
+
+Claude (Coordinator): 我把这个任务拆成 5 个子任务，派发给 worker 执行...
+
+  > Agent (worker #1): 迁移 packages/utils/ ...
+  > Agent (worker #2): 迁移 packages/core/ ...
+  > Agent (worker #3): 迁移 packages/api/ ...
+  ...
+
+  [Worker 完成后汇报结果，Coordinator 汇总]
+```
+
+再次输入 `/coordinator` 可以关闭 Coordinator 模式，恢复正常的工具使用。
+
+## Workflow 脚本：固化可重放的多步工作流
+
+`/workflows` 命令打开一个监控面板，实时显示当前工作流的运行状态、各阶段进度和子代理活动。这个面板适合在 Claude 执行复杂多步任务时监控整体进展。
+
+在面板中，你可以看到：
+
+- 当前工作流的运行状态（running / paused / completed）
+- 各阶段的进度
+- 活跃的子代理列表及其状态
+- 用键盘快捷键控制工作流（暂停、继续、取消）
+
+```
+/workflows
+```
+
+面板以终端 UI 形式展示，不阻塞主对话。
+
+## 如何选择合适的方式
+
+面对一个大任务，选择哪种方式取决于任务的性质：
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 需要先理解代码再动手 | Plan 模式 |
+| 需要长时间自主推进 | `/goal` |
+| 需要并行处理多个独立子任务 | Agent 子代理 / Coordinator 模式 |
+| 需要在隔离环境做实验 | Worktree |
+| 需要跟踪多个子任务的进度 | Task 系统 |
+| 需要监控复杂工作流的执行 | `/workflows` 面板 |
+
+这些方式可以组合使用。比如，你可以先用 Plan 模式设计方案，然后 Claude 自动创建 Task 清单，再派子代理并行执行各任务，同时你在 `/workflows` 面板中监控进度。
+
+## 下一步
+
+- 想了解如何让 Claude 定时或后台执行任务，看 [第七章：Daemon、Background Sessions、Schedule](./07-daemon-bg-schedule.md)
+- 想了解如何通过 Bridge 或 RCS 远程控制这些任务，看 [第八章：跨机器与跨团队协作](./08-bridge-remote-acp.md)
+- 想了解权限模式如何影响子代理和 Plan 模式的行为，看 [第九章：省钱、提速、定制](./09-budget-caching-hooks.md)