Agent/cyber_agent/docs/recursive-task-protocol.md

Recursive 任务协议

文档维护规范

1. 代码是权威实现 - 本文档只记录 AGENT_MODE=recursive revision 2 已实现的协议；字段和门禁变更时需同步更新
2. 协议与投影分层 - Trace.context.task_protocol 是权威状态，Goal 状态只用于流程展示
3. 不扩展到 Legacy - Legacy 仍使用自由文本 task/summary 和原 Goal 自动推进逻辑

---

概述

Recursive 任务协议把本地父子 Agent 协作约束为：

父 Agent 下发 TaskBrief
  → 子 Agent 执行并提交 TaskReport
  → 独立 Validator 生成 ValidationResult
  → 父 Agent 生成 TaskReview
  → 修订原孩子 / 创建新孩子 / 重新规划当前层 / 完成或失败

这套协议只用于本地 Recursive Agent。remote_* 和 Legacy 不进入本协议。模式、深度、孩子配额、调度和资源预算见 Agent 运行模式。

---

协议数据

TaskBrief：父级下发的任务说明

字段	类型	规则
objective	string	必填，子任务目标
reason	string	必填，说明为什么拆出该任务
completion_criteria	string[]	必填且至少一项
expected_outputs	string[]	必填且至少一项
parent_findings	string[]	父级已确认的发现，默认为空
context	object	与本任务直接相关的显式上下文
constraints	string[]	硬约束；自动继承父 TaskBrief 的约束，子级只能增加

TaskBrief 会去重、检查 JSON 可序列化性，规范化后最多 16,000 字符。Recursive 本地 agent() 使用 task_brief，不接受 messages。

TaskReport：子级提交的执行报告

字段	类型	规则
child_trace_id	string	框架注入，必须等于当前子 Trace
summary	string	必填的执行总结
outcome	satisfied \| partial \| failed \| protocol_error	任务结果
validation	Validation	执行者自检，不是框架权威验收
next_step_suggestion	object	子级建议，不直接创建父级的下一个孩子
outputs / evidence	object[]	产出和证据
remaining_issues	string[]	未解决问题

Validation 只包含 hard_passed 和 open_issues。outcome=satisfied 时必须 hard_passed=true，且 open_issues 和 remaining_issues 都为空。

next_step_suggestion.direction 为 DESCEND / REFINE / ASCEND / NONE。DESCEND/REFINE 必须附带 suggested_next_task；该字段仅是建议，父 Agent 必须审核后才能执行。

ValidationResult：框架权威验收

字段	类型	规则
validator_trace_id	string	框架注入
evaluated_trace_id	string	框架注入，指向被验收 Trace
outcome	passed \| failed \| error	独立验收结果
scope	evidence \| hypothesis \| output \| task \| root	验收范围
reason	string	必填结论
issues	string[]	具体问题
retry_from	evidence \| hypothesis \| output \| task_definition \| null	验收失败时的明确回退位置

• passed：issues=[]、retry_from=null。
• failed：至少一个 issue，必须有 retry_from。
• error：至少一个 issue，retry_from=null，表示 Validator 自身异常或输出非法。

TaskReview：父级的审核决定

字段	类型	规则
parent_trace_id	string	框架注入
child_trace_id	string	必须是当前 Trace 的直接孩子，且 UID 一致
decision	ReviewDecision	见下方决策矩阵
reason	string	必填
approved_next_task	TaskBrief \| null	批准的新建或修订任务
retry_from	RetryFrom \| null	仅由框架从 ValidationResult 注入，不是公开工具参数

---

状态机与工具门禁

Goal 可视状态为：

pending → in_progress → waiting_children → pending_review
                                 ↓
                     in_progress / completed / failed

1. 父 Agent 调用 agent(task_brief=...) 后，原 Goal 进入 waiting_children。
2. 子 Agent 必须先审核完自己的孩子、执行完已批准 action，再调用 submit_task_report。
3. 子报告经 Validator 处理后，父 Goal 进入 pending_review。
4. pending_review 期间运行时只暴露 review_task_result，Goal 工具也拒绝新增、完成、放弃或切换。
5. 审核产生 next action 后，运行时只暴露 agent，且实际 TaskBrief 必须与批准内容规范化后完全一致。

Recursive 禁止 GoalTree 自动切换下一个 pending sibling，也禁止所有孩子完成时级联完成父 Goal。父 Agent 必须在审核后自己决定。

---

审核决策

决策语义

决策	效果
ACCEPT_REFINE	接受建议，把 approved_next_task 加入父级 next action，由父级创建新的直接孩子
REJECT_REFINE	不采纳子级建议；其他待审报告处理完后，父级恢复 in_progress
REVISE_CHILD	进入修订 action；下一次只能用 continue_from 续跑原直接孩子，不消耗新孩子名额
DESCEND_AGAIN	批准一个新 TaskBrief，由当前父级再创建一个直接孩子
REPLAN_CURRENT	待当前批次审核完后，恢复创建该孩子的原 Goal 为 in_progress
ASCEND	完成父级当前 Goal，不级联完成它的父 Goal，不自动进入兄弟 Goal
FAIL	将父级当前 Goal 标为 failed，不级联到更高层

ValidationResult 决策矩阵

Validator 结果	允许的决策
passed	ACCEPT_REFINE / REJECT_REFINE / REVISE_CHILD / DESCEND_AGAIN / ASCEND / FAIL
failed	REVISE_CHILD / REPLAN_CURRENT / FAIL
error	REVISE_CHILD / FAIL

还有两层硬约束：

• TaskReport.outcome=failed/protocol_error 只能选 REVISE_CHILD/FAIL。
• ASCEND/FAIL 只能审核本批最后一份待审报告，且不得留有未执行的 next action。

REPLAN_CURRENT 只回退直接父级

REPLAN_CURRENT 没有 target_trace_id 或 ancestor_trace_id 参数。回退目标由子 Trace 持久化的 parent_trace_id 和 parent_goal_id 确定：

孙 Trace 验收失败
  → 子 Trace 审核并 REPLAN_CURRENT
  → 只恢复子 Trace 中创建孙节点的 Goal
  → 如果需要更高层回退，子 Agent 先提交自己的 TaskReport
  → 父 Agent 再独立审核

retry_from 来自当前报告的 ValidationResult，父 Agent 不能修改。

批量报告

批量孩子各自产生 TaskReport、ValidationResult 和 TaskReview。父级必须逐份审核：

• 只审核一部分时继续保持 pending_review。
• REPLAN_CURRENT 先记入 pending_replans，本批全部审核完才恢复目标。
• 本批后续选择 FAIL 会清除已记录的 replan。
• 已批准的新孩子还会预占每父六孩子配额，避免审核通过后才发现无名额。

---

独立 Validator

子任务验收

satisfied/partial 报告会启动一次真实 LLM Validator；failed/protocol_error 报告以及框架为已停止孩子生成的 failed 报告，会得到确定性的不通过结果，不额外调用模型。每个报告版本只保存一份 Validator 结果；REVISE_CHILD 提交新报告后才会重新验收。

Validator Trace 的约束：

• created_by_tool="validator"，agent_type="validator"。
• parent_trace_id 指向被验收的业务 Trace，root_trace_id 和 UID 保持一致。
• 不增加业务 agent_depth，不占每父六孩子和业务 Agent 预算。
• 无工具、无 Agent Loop、单次 LLM 调用，temperature=0。
• 调用计入整树 LLM、Token、成本和时间预算，并参与当前进程的子树停止。
• 不可 continue_from，不再生成 Validator。

Validator 输入由框架从 TaskBrief、TaskReport、完成标准、预期产出、持久化主路径消息和真实 Tool Result 组装。固定协议字段优先保留，轨迹按最新消息优先裁剪，整体最多 50,000 字符；不包含侧分支和持久化的 reasoning_content。

Validator 默认继承被验收 Agent 的模型，可用 AGENT_VALIDATOR_MODEL 覆盖。模型输出非法、返回错误 scope、尝试调用工具或调用异常时，直接生成 outcome=error，不再发起格式修正调用。

根任务完成门禁

新建 Recursive 根 Trace 必须显式提供 root_completion_criteria。根 Agent 生成无 Tool Call 的候选答案时，框架使用根标准、候选答案和持久化主路径运行 scope=root 的 Validator：

• 通过：根 Trace 才可写为 completed。
• 第一次未通过或 Validator 错误：将框架生成的 ValidationResult 追加到根消息，允许修正一次。
• 第二次仍未通过：根 Trace 写为 failed。
• Validator 异常、停止或预算不足都不会绕过完成门禁。

---

失败、停止、续跑与回溯

• 非根 Agent 没有合法 TaskReport 时，框架最多注入两轮纠正提示；仍未提交时生成 protocol_error 报告并失败结束。
• 子 Agent 异常或无有效报告时，父级依然会收到框架生成的报告和 ValidationResult，不会跳过审核。
• 停止的子 Agent 生成 outcome=failed 的 TaskReport；父级只能选择 REVISE_CHILD 或 FAIL。
• REVISE_CHILD 把旧报告移入 report_history，清空当前报告和 Validator 缓存；续跑后必须再提交新报告。
• 服务重启后，pending_reviews 和 next_actions 从 Trace context 恢复。
• 回溯会按 sequence 删除截断点之后的报告、审核和 action，恢复被回溯的待审报告，重建 pending_replans 和 Goal 状态投影。
• 回溯、停止和续跑都不退还已消耗的树级资源。

---

持久化状态

Trace.context.task_protocol 保存：

task_brief
task_report
task_report_submitted_at_sequence
task_report_validation
report_history
pending_reviews
reviews
next_actions
pending_replans
root_validation_attempts
root_validation_history
root_validation_passed
protocol_correction_attempts

pending_reviews 的每一项同时保存 TaskReport、ValidationResult、原 Goal ID 和接收 sequence。GoalTree 不是这些协议事实的权威存储。

---

实现与测试

内容	位置
数据模型和协议状态	cyber_agent/core/task_protocol.py
TaskBrief 规范化与约束继承	cyber_agent/core/context_policy.py
submit_task_report / review_task_result	cyber_agent/tools/builtin/task_protocol.py
Validator、ValidationResult 和输入裁剪	cyber_agent/core/validation.py
运行时门禁、根 Validator、回溯恢复	cyber_agent/core/runner.py
子报告汇合和 Validator 触发	cyber_agent/tools/builtin/subagent.py
Goal 状态与变更门禁	cyber_agent/trace/goal_models.py / goal_tool.py

主要测试：

• tests/test_task_protocol.py
• tests/test_recursive_replan_context.py
• tests/test_recursive_validation_core.py
• tests/test_recursive_runtime_extensions.py