Complex Task

Complex Task — 复杂任务执行指导

触发条件：任务涉及多个交付阶段、需要协调多个 crew、或估计完成周期超过单次对话的长程任务。

适用领域：深度调研、自媒体内容生产、视频生成、故障排查与根因分析、多维度数据处理、配置新的对内/外 crew、开发新的技能等。

核心原则

• 1. 主 agent 只充当 planner 和 project manager，负责与用户确认、治理流程、维护文档、推动执行，不直接承担已拆分子任务的具体生产工作。
• 2. agent 与 subagent 的协作，不应主要依靠对话，而应主要依靠交付物、任务文档、验收文档、结构化约束和明确 verdict。
• 3. 计划确定后，所有子任务必须通过 sessions_spawn 交给 subagent；主 agent 不得代做任何子任务。
• 4. 每个子任务都必须有一对 subagent：执行者 + 评估者。最终聚合后还必须有一个单独的整体评估 subagent。
• 5. 子任务是否可接受，只能由对应 evaluator subagent 给出 verdict。不能因为“看到了新产物”就自行把状态改成完成。
• 6. 执行 subagent、评估 subagent、整体评估 subagent，都应优先从 allowAgents 白名单内选择最合适的 crew；如果 allowAgents 为空或没有合适的 crew，则 spawn 给自己。

术语

• 主 agent：和用户直接交互，负责确认、编排、巡检、变更管理和最终交付。
• 执行者：某个子任务的 executor subagent，负责依据 task.md 产出交付物。
• 评估者：某个子任务的 evaluator subagent，负责依据 acceptance.md 判断该子任务是否可以交付。
• GAN 模式：执行者持续产出或修正交付物，评估者持续指出与验收标准之间的缺口；双方围绕产物和约束循环，直到评估者明确给出可交付 verdict。

Phase 1 — 理解意图，制定验收标准

仔细阅读用户描述，提炼：

• 核心目标：任务要解决什么问题？
• 交付范围：最终产物是什么形式？
• 明确约束：时间、资源、风格、平台、字数、数据范围、技术边界等。
• 隐含预期：用户没明说但明显存在的质量底线。

基于以上分析，起草验收标准清单：

验收标准：
  AC-1: <可观测、可验证的具体标准>
  AC-2: ...
  AC-N: ...

要求：

• 每条 AC 必须可观测、可验证。
• 禁止使用“质量好”“尽量完整”“适当优化”等模糊表述。
• 能转成明确指标、检查清单或测试脚本时，优先转成这些形式。

Phase 2 — 与用户确认验收标准（L2）

向用户呈现：

任务目标：<一句话概括>

验收标准：
  AC-1: ...
  AC-2: ...
  ...

请确认以上验收标准，或告诉我需要调整的部分。

等待用户明确确认。用户有修改时，更新标准后重新确认。未经确认，不得进入 Phase 3。

Phase 3 — 制定执行计划，并用 subagent 自审拆分质量

3-1 任务拆解

将任务拆解为若干子任务。每个子任务必须可独立执行、可独立评估、可独立返工。每个子任务至少包含：

子任务 T-N：<子任务名称>
  目标：<该子任务解决什么问题>
  交付物：<必须产出的具体内容，可量化>
  约束：<执行限制、事实边界、质量要求、来源范围等>
  验收重点：<本子任务最关键的检查点>
  执行者指派：<crew-id 或 self>
  评估者指派：<crew-id 或 self>
  模型层级：<strong / default>
  依赖：<无 / 依赖 T-X 完成后启动>
  执行方式：<并行 / 串行>
  返工策略：<被打回后如何继续>

规则：

• 只能指派 self 或当前 crew allowAgents 白名单内的 crew。
• 不得指派 external crew。
• 子任务之间的接口应尽量落实为文件路径、字段结构、输出格式或检查点。
• 同一个子任务内不要同时混入“探索、决策、执行、整合”四类责任。

3-2 计划自审：必须创建 planning reviewer subagent

在计划落地实施前，必须创建一个独立的 planning reviewer subagent，与主 agent 以 GAN 模式完成计划定稿。

做法：

1. 主 agent 先形成一版计划草案。
2. spawn 一个 planning reviewer subagent，向其提供：任务目标、已确认 AC、当前子任务拆分草案、依赖关系、指派方案、返工策略。
3. planning reviewer 只做结构化批评，不参与执行。它必须指出：
   • 哪些子任务粒度过粗或过细
   • 哪些依赖关系不合理
   • 哪些交付物与验收重点不匹配
   • 哪些子任务边界不清或容易重复劳动
   • 哪些约束缺失，导致后续执行者和评估者无法协作
4. 主 agent 根据批评修订计划；如 reviewer 仍指出问题，则继续迭代，直到收敛出可执行计划。

要求：

• 计划自审阶段的沟通必须围绕计划文本和约束本身，而不是开放式讨论。
• 未通过计划自审，不得进入 Phase 4 的执行准备。

3-3 Anti-pattern 检查

Phase 4 — 初始化项目文件夹与子任务文档

这一步不必与用户确认，但必须经过 planning reviewer subagent 的审查通过。 当 planning reviewer subagent 认为技术方案和计划都已经足够清晰、可执行时，主 agent 应立即按计划创建项目文件夹： ./projects/<YYYYMMDD>-<task-slug>/

./projects/<id>/
  PROJECT.md
  tasks.json
  progress.md
  subtasks/
    T-1/
      task.md
      acceptance.md
      artifacts/
    T-2/
      task.md
      acceptance.md
      artifacts/
  final/

4-1 PROJECT.md

# Project: <任务名称>

**ID**: <YYYYMMDD>-<task-slug>
**Created**: <日期时间>
**Status**: planned

## 目标
<一句话概括任务目标>

## 验收标准
- AC-1: ...
- AC-2: ...

## 执行总览
- 子任务数量：N
- 并行组：...
- 关键依赖：...

4-2 tasks.json

{
  "project_id": "<YYYYMMDD>-<task-slug>",
  "created_at": "<ISO 8601>",
  "status": "planned",
  "subtasks": [
    {
      "id": "T-1",
      "name": "<子任务名称>",
      "executor_assignee": "<crew-id 或 self>",
      "evaluator_assignee": "<crew-id 或 self>",
      "dependencies": [],
      "status": "pending",
      "executor_status": "pending",
      "evaluator_status": "pending",
      "verdict": "unknown",
      "artifact_dir": "./projects/<id>/subtasks/T-1/artifacts/",
      "result_summary": ""
    }
  ]
}

建议状态流转：

• 顶层 status：planned → executing → aggregating → overall_review → done
• 子任务 status：pending → running → awaiting_verdict → accepted | needs_rework | blocked
• verdict 只能由 evaluator 或 overall evaluator 的正式结论驱动。

4-3 progress.md

# Progress Log — <任务名称>

## [<时间戳>] Phase 4: 项目初始化完成
- 项目目录：./projects/<id>/
- 子任务数量：N 个
- 已创建子任务文档：T-1 ... T-N

4-4 为每个子任务创建两个文档

必须在每个子任务目录下创建两个 Markdown：

• task.md：详细描述子任务内容、目标、上下文、依赖、产物位置、执行约束
• acceptance.md：详细描述子任务验收标准、检查方法、拒收条件、评估输出格式

建议模板：

# task.md
## 目标
## 输入与上下文
## 交付物
- 路径：./projects/<id>/subtasks/T-N/artifacts/
- 必须包含：...
## 约束
## 禁止事项

# acceptance.md
## 必须满足
- AC-TN-1: ...
- AC-TN-2: ...
## 拒收条件
## 评估输出格式
- verdict: accepted | needs_rework | blocked
- findings:
  - <编号化问题清单>
- evidence:
  - <对应文件 / 事实 / 缺口>

Phase 5 — 执行：每个子任务都以“执行者-评估者”双 subagent 并行推进

5-1 spawn 规范

每个子任务都必须创建两个 subagent：

• executor subagent，负责依据 task.md 执行
• evaluator subagent，负责依据 acceptance.md 评估

关键约束：

• 执行者和评估者的协作，应以 task.md、acceptance.md、artifacts/ 内产物和结构化 verdict 为中心。
• 允许最小必要澄清，但不得把“靠聊明白需求”当作主要协作方式。
• 如果评估者没有明确给出 accepted，该子任务就不能进入可交付状态。

5-2 Executor prompt 要求

executor 至少应收到：

• task.md 路径
• acceptance.md 路径
• 产物目录路径
• 明确要求：优先通过更新交付物解决问题，而不是长篇解释

建议 executor 输出格式：

执行回合：
  子任务：T-N
  本轮修改产物：
    - <文件路径>
  本轮结果摘要：
    - <1-3 条>
  需评估项：
    - <请 evaluator 针对哪些标准检查>

5-3 Evaluator prompt 要求

evaluator 至少应收到：

• acceptance.md 路径
• task.md 路径
• 产物目录路径
• 明确要求：只根据产物和标准做判断，不为执行者脑补完成度

建议 evaluator 输出格式：

评估回合：
  子任务：T-N
  verdict: accepted | needs_rework | blocked
  findings:
    1. <问题或通过项>
    2. ...
  evidence:
    - <文件路径 / 事实依据 / 缺失项>
  next_action:
    - <执行者下一轮应修改什么>

5-4 GAN 式循环

每个子任务都按以下循环推进，直到 evaluator 给出 accepted：

1. 执行者依据 task.md 产出或修改交付物。
2. 评估者依据 acceptance.md 对产物做批判性检查。
3. 如果 verdict 为 needs_rework，执行者只针对 findings 返工，不重做无关部分。
4. 如果 verdict 为 blocked，主 agent 介入，澄清事实、修正文档或向用户确认。
5. 只有当 verdict 为 accepted 时，主 agent 才能把该子任务状态写为 accepted。

5-5 巡检：主 agent 必须持续跟进，但不代替评估

Phase 5 的巡检仍然是主 agent 的职责，至少包括两类工作。

一类：推进卡住的 subagent

• 如果任何执行者或评估者明显卡住了，例如长时间无响应、上游模型挂起、上下文中断，应主动提示简短指令，例如“继续”。
• 巡检的目标是恢复执行，不是替子 agent 完成任务。

二类：处理问题与偏差

• 如果执行者或评估者发现 task.md 或 acceptance.md 与事实不符，应向主 agent 提问。
• 主 agent 能判断的，直接答复并同步更新文档。
• 主 agent 拿不准的，必须反馈用户；待用户确认后，及时更新相应文档，再回复相关 subagent。
• 文档一旦更新，必须通知受影响的执行者和评估者，避免双方继续基于旧约束工作。

5-6 状态更新纪律

主 agent 不得：

• 因为 artifacts/ 里出现新文件，就直接把子任务标记为完成。
• 因为执行者自称“已经好了”，就跳过 evaluator verdict。
• 因为主 agent 自己觉得“看起来差不多”，就代替 evaluator 做接受判定。

只有以下动作允许更新子任务状态：

• spawn 后，可改为 running
• 执行者提交产物待审时，可改为 awaiting_verdict
• evaluator 明确判定通过时，可改为 accepted
• evaluator 明确判定返工时，可改为 needs_rework
• 明确存在阻塞且需主 agent 介入时，可改为 blocked

巡检记录建议追加到 progress.md：

## [<时间戳>] 巡检
- T-1: evaluator 判定 needs_rework，已要求执行者继续
- T-2: evaluator 卡住，已发送“继续”
- T-3: task.md 与事实冲突，已向用户确认并更新文档

Phase 6 — 聚合结果

所有子任务都获得对应 evaluator 的 accepted verdict 后，主 agent 才能进入聚合阶段。

聚合时：

1. 检查 tasks.json，确认所有相关子任务 status = accepted
2. 读取各子任务产物，整合为统一最终成果
3. 将项目顶层状态更新为 aggregating
4. 在 ./projects/<id>/final/ 下生成聚合产物
5. 在 progress.md 追加记录

## [<时间戳>] Phase 6: 结果聚合完成
- 已接受子任务：X / N
- 聚合产物：./projects/<id>/final/

注意：在 Phase 6 完成前，不必创建整体评估 subagent。此时各子任务的可接受性，已经由各自 evaluator 负责。

Phase 7 — 整体评估与返工闭环

Phase 6 聚合完成后，必须再 spawn 一个独立的 overall evaluator subagent，专门评估最终整合结果。

它至少应读取：

• PROJECT.md
• 最终成果文件
• 全局 AC
• 必要时读取关键子任务的 acceptance.md 与产物摘要

其职责：

• 判断最终整合结果是否真正满足全局 AC
• 识别是“已有子任务未做到位”，还是“需要新增子任务”
• 输出结构化 verdict，而不是泛泛而谈

建议输出格式：

整体评估：
  verdict: accepted | needs_rework
  findings:
    1. <全局缺口>
    2. ...
  impacted_subtasks:
    - <T-2>
    - <需要新增 T-5>
  rationale:
    - <为何当前聚合结果仍不满足全局 AC>

7-1 若整体评估通过

如果 overall evaluator 明确给出 accepted，进入 Phase 8。

7-2 若整体评估未通过

如果 overall evaluator 给出 needs_rework，主 agent 必须基于 findings 组织返工：

• 如果是已有子任务的缺口：更新对应 task.md 或 acceptance.md
• 如果是新增范围：创建新的子任务目录、task.md、acceptance.md
• 为受影响子任务重新创建或重启执行者与评估者
• 返回 Phase 5 执行，再经过 Phase 6 聚合，最后重新进入 Phase 7

这个循环应持续，直到 overall evaluator 认为可以交付。

如果返工轮次明显增多，主 agent 应主动向用户汇报风险、差距和拟调整方案；但不能跳过 overall evaluator 的最终判定。

Phase 8 — 交付

当且仅当 overall evaluator 明确接受后：

1. 将 tasks.json 顶层 status 更新为 done
2. 在 progress.md 追加最终记录

## [<时间戳>] Phase 8: 任务完成
- 整体评估：accepted
- 最终产物：./projects/<id>/final/

向用户交付：

任务完成

项目目录：./projects/<id>/

最终产物：
  <路径 / 摘要>

验收确认：
  AC-1: ✅ ...
  AC-2: ✅ ...

整体评估：
  accepted

交付后执行常规 closeout。

Anti-patterns — 常见失败模式

Plan Mutation Protocol — 执行中计划变更

遇到以下情况，需要修改计划或文档时，遵守正式变更流程。

触发场景

• 子任务文档与事实冲突：先定位冲突点，必要时向用户确认，再更新 task.md / acceptance.md
• 整体评估发现新缺口：新增子任务，或拆分现有子任务
• 用户主动修改目标或范围：先判断是否影响全局 AC；影响则重走对应确认流程
• 关键依赖变化：调整子任务依赖和执行顺序，并同步受影响的执行者和评估者

变更记录

所有变更必须在 progress.md 追加：

## [<时间戳>] 计划变更
- 变更原因：<触发场景>
- 变更内容：<新增 / 修改 / 取消哪个子任务，或更新哪份文档>
- 影响范围：<受影响的子任务 / 评估者 / 聚合结果>
- 用户确认：<已确认 / 无需确认>

必须重走确认的内容

以下内容一旦已获用户确认，后续若要修改，必须重新与用户确认：

• 全局验收标准（AC）

• 最终交付物形式 以下内容通常不需要单独等待确认，但发生重大变化时，应及时同步用户：

• 子任务总体拆分逻辑

• 关键执行顺序与重大依赖关系