overseer

使用 Overseer 进行 Agent 协调

核心原则：工单，而非待办事项

Overseer 任务是工单——包含全面上下文的结构化产物：

• 描述：一句话摘要（问题标题）
• 上下文：完整背景、要求和方案（问题正文）
• 结果：实现细节、决策和成果（PR 描述）

请思考：“仅凭这项任务，其他人能否理解做什么、为什么做、如何做，以及成功的标准是什么？”

任务 ID 是临时的

切勿在外部产物中引用任务 ID（提交、PR、文档）。像 task_01JQAZ... 这样的任务 ID 在任务完成后就失去意义了。请描述工作本身，而不是跟踪该工作的任务。

Overseer 与 OpenCode 的 TodoWrite

	Overseer	TodoWrite
持久性	SQLite 数据库	仅限当前会话
上下文	丰富（描述 + 上下文 + 结果）	基本
层级	3 级（里程碑 -> 任务 -> 子任务）	扁平

需要持久化的工作使用 Overseer。仅在当前会话中临时跟踪使用 TodoWrite。

何时使用 Overseer

以下情况使用 Overseer：

• 将复杂工作拆分为子任务
• 工作跨越多个会话
• 需要保留上下文以便交接
• 记录决策以供日后参考

以下情况跳过 Overseer：

• 工作是单个原子操作
• 所有内容都能在一次消息交互中完成
• 开销超过收益
• TodoWrite 已足够

查找工作

// Get next ready task with full context (recommended for work sessions)
const task = await tasks.nextReady(milestoneId); // TaskWithContext | null
if (!task) {
  console.log("No ready tasks");
  return;
}

// Get all ready tasks (for progress overview)
const readyTasks = await tasks.list({ ready: true }); // Task[]

开始工作时使用 nextReady()——它返回 TaskWithContext | null（具有完整上下文链和继承的经验中最深层的就绪叶节点）。 检查状态/进度时使用 list({ ready: true })——它返回 Task[]，不含上下文链。

基本工作流

// 1. Get next ready task (returns TaskWithContext | null)
const task = await tasks.nextReady();
if (!task) return "No ready tasks";

// 2. Review context (available on TaskWithContext)
console.log(task.context.own);       // This task's context
console.log(task.context.parent);    // Parent's context (if depth > 0)
console.log(task.context.milestone); // Root milestone context (if depth > 1)
console.log(task.learnings.own);     // Learnings attached to this task (bubbled from children)

// 3. Start work (VCS required - creates bookmark, records start commit)
await tasks.start(task.id);

// 4. Implement...

// 5. Complete with learnings (VCS required - commits changes, bubbles learnings to parent)
await tasks.complete(task.id, {
  result: "Implemented login endpoint with JWT tokens",
  learnings: ["bcrypt rounds should be 12 for production"]
});

// Alternative: Cancel if abandoning (does NOT satisfy blockers)
await tasks.cancel(task.id);

// 6. Archive finished tasks to hide from default list
await tasks.archive(task.id);

详细的工作流指导请参见 @file references/workflow.md。

理解任务上下文

任务具有渐进式上下文——从祖先继承而来：

const task = await tasks.get(taskId); // Returns TaskWithContext
// task.context.own      - this task's context (always present)
// task.context.parent   - parent task's context (if depth > 0)
// task.context.milestone - root milestone's context (if depth > 1)

// Task's own learnings (bubbled from completed children)
// task.learnings.own - learnings attached to this task

返回类型摘要

方法	返回值	备注
tasks.get(id)	TaskWithContext	完整上下文链 + 继承的经验
tasks.nextReady()	TaskWithContext | null	具有完整上下文的最深层就绪叶节点
tasks.list()	Task[]	仅包含基本任务字段
tasks.create()	Task	不含上下文链
tasks.start/complete()	Task	不含上下文链

阻塞项

在阻塞项完成之前，任务无法进入就绪状态。

限制：

• 阻塞项不能是任务本身
• 阻塞项不能是祖先（父级、祖父级等）
• 阻塞项不能是后代
• 使用无效阻塞项创建/重新指定父级将被拒绝

// Add blocker - taskA waits for taskB
await tasks.block(taskA.id, taskB.id);

// Remove blocker
await tasks.unblock(taskA.id, taskB.id);

任务层级

共 3 级：里程碑（深度 0）-> 任务（深度 1）-> 子任务（深度 2）。

级别	名称	用途	示例
0	里程碑	大型计划	“添加用户身份验证系统”
1	任务	重要工作项	“实现 JWT 中间件”
2	子任务	原子步骤	“添加令牌验证函数”

选择合适的级别：

• 小型功能（1-2 个文件）-> 单个任务
• 中型功能（3-7 个步骤）-> 带子任务的任务
• 大型计划（5 个以上任务）-> 带任务的里程碑

详细指导请参见 @file references/hierarchies.md。

记录结果

完成实现并验证后，立即完成任务：

• 趁记忆犹新时记录决策
• 记录与计划的偏差
• 记录执行过的验证
• 为技术债创建后续任务

结果必须包含明确的验证证据。请参见 @file references/verification.md。

最佳实践

1. 合理控制任务规模：可在一次专注的工作时段内完成
2. 明确完成标准：上下文应定义“完成”的含义
3. 不要过度拆分：每个父任务包含 3-7 个子任务
4. 描述以行动为导向：以动词开头（“添加”“修复”“更新”）
5. 完成前进行验证：测试通过，并完成手动测试

---

阅读顺序

任务	文件
了解 API	@file references/api.md
实现工作流	@file references/workflow.md
任务拆分	@file references/hierarchies.md
正反示例	@file references/examples.md
验证清单	@file references/verification.md

本参考中的内容

文件	用途
references/api.md	Overseer MCP codemode API 类型/方法
references/workflow.md	开始->实现->完成工作流
references/hierarchies.md	里程碑/任务/子任务组织方式
references/examples.md	优秀/不佳的上下文和结果示例
references/verification.md	验证清单和流程