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。Recursive revision 2 不允许 remote_*；Legacy 和 Recursive revision 1 的远端路由不进入本协议。模式、深度、孩子配额、调度和资源预算见 Agent 运行模式。

---

协议数据

RootTaskAnchor：根任务锚点

字段	类型	规则
objective	string	必填，整棵任务树的根目标
completion_criteria	string[]	必填且至少一项，也是根 Validator 的完成标准
constraints	string[]	根级硬约束，自动进入每层 TaskBrief

新建 Recursive 根 Trace 必须通过 RunConfig.root_task_anchor 或 REST root_task_anchor 提供。框架固化规范化内容和哈希，后代只读取根 Trace 权威副本；规范化后最多 4,000 字符。

TaskBrief：父级下发的任务说明

字段	类型	规则
objective	string	必填，子任务目标
reason	string	必填，说明为什么拆出该任务
completion_criteria	string[]	必填且至少一项
expected_outputs	string[]	必填且至少一项
parent_findings	string[]	父级已确认的发现，默认为空
context	object	与本任务直接相关的显式上下文
constraints	string[]	硬约束；自动继承父 TaskBrief 的约束，子级只能增加
context_refs	ContextRef[]	当前父 Trace 已授权且明确转授的 ref_id/version
validation_scopes	evidence \| hypothesis \| output \| task 数组	父级选择子任务验收维度；框架始终补上 task

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[]	产出和证据
artifact_refs	ArtifactRef[]	可由可信 Resolver 读取和校验的真实产物引用
source_urls	string[]	Evidence/Hypothesis Validator 可以直接打开的公开 HTTP(S) 来源
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 必须审核后才能执行。

ValidationPlan / ValidationResult：框架权威验收

ValidationPolicy 是信任应用注入并在根 Trace 固化的最低规则。框架将它与 TaskBrief、TaskReport、真实材料、轨迹 head、模型和工具策略编译为 ValidationPlan；plan_hash 覆盖这些输入，任一变化都必须整份重验。

Plan 中每个 ValidationCheckSpec 固定 check_id/scope/criterion/method/required。 每个 Scope 产生一份 ScopeValidationResult，内含逐项 ValidationCheck(status=passed|failed|unknown)。模型只能返回 Plan 中已有的 check_id；遗漏必选项、重复、新增、Scope 错误或伪造证据均使当前 Scope 变成 error。

最终 ValidationResult 包含 evaluated_trace_id/outcome/scope_results/issues/retry_from/plan_hash。 聚合优先级为 error > failed > unknown > passed；failed/unknown 有明确回退位置， error 的 retry_from=null。

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 和可用时的 read_context_ref，Goal 工具也拒绝新增、完成、放弃或切换。
5. 审核产生 next action 后，运行时只暴露 agent 和可用时的 read_context_ref，且实际 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
unknown	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 报告按有效 Scope 顺序执行：evidence → hypothesis → output → task， 每个 Scope 创建独立 Validator Trace，一份 TaskReport 最终只产生一份聚合 ValidationResult 和一次父级审核。根固定只执行 root。failed/protocol_error 报告以及已停止孩子走确定性不通过路径，不浪费模型调用。

Validator Trace 的约束：

• created_by_tool="validator"，agent_type="validator"。
• parent_trace_id 指向被验收的业务 Trace，root_trace_id 和 UID 保持一致。
• 不增加业务 agent_depth，不占每父六孩子和业务 Agent 预算。
• output/task 为单次无工具 LLM；evidence/hypothesis/root 可进入有轮次上限的受控 Agentic 循环，均使用 temperature=0。
• 调用计入整树 LLM、Token、成本和时间预算，并参与当前进程的子树停止。
• 不可 continue_from，不再生成 Validator。

Validator 输入由框架从 Policy、Plan、TaskBrief、TaskReport、RootTaskAnchor、 持久化主路径、真实 Tool Result 和已解析 Artifact 组装。固定协议和必需材料 优先保留，轨迹按最新消息优先裁剪，整体最多 50,000 字符；必需材料无法 完整进入时返回 unknown，不会截断后通过。侧分支和 reasoning_content 不进入验收。

RootTaskAnchor 也作为固定字段进入验收包。Validator 不会自动展开 ContextRef；只有业务 Agent 实际读取过的快照才会以 Tool Result 进入轨迹。

evidence/hypothesis/root 只能使用 Validator 私有的 validator_web_search 和 validator_open_url。页面读取只允许报告声明或本轮搜索返回的公开 HTTP(S) URL，逐跳校验 DNS 并固定已验证 IP，不携带 Cookie/Auth，不支持登录、点击、 JS、下载、PDF 或私网地址。网页正文始终标记为不可信材料；Evidence 通过时 evidence_refs 必须指向当前 Validator Trace 真实打开的 source ID。

Validator 默认继承被验收 Agent 的模型，可用 AGENT_VALIDATOR_MODEL 覆盖； 根可再用 AGENT_ROOT_VALIDATOR_MODEL 单独覆盖。模型输出非法、越权工具调用或轮次超限 直接生成 outcome=error，不发起格式修正调用。同一 plan_hash 在重启后可直接 恢复已完成 Scope；任一权威输入改变都整份重验。

真实产物

outputs/evidence 是执行者声明，不能单独证明交付存在。ArtifactRef 只保存 artifact_id/version/content_hash/kind/mime_type；应用通过可信、只读 ArtifactResolver 将它解析为真实材料。明确缺失或 hash 不符为 failed，解析器 暂不可用为 unknown，跨 root/UID 或结构伪造为 error。框架不提供任意本地路径读取。

根任务完成门禁

新建 Recursive 根 Trace 必须显式提供 root_task_anchor。根 Agent 生成无 Tool Call 的候选答案时，框架使用 Anchor 中的根标准、候选答案和持久化主路径运行 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_brief_version / task_brief_history
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

Trace.context.context_access 另存当前 Trace 被授权的不可变快照与字符用量；该目录不并入 task_protocol。引用的生成、转授、读取和限额见 Context 管理。

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

---

实现与测试

内容	位置
数据模型和协议状态	cyber_agent/core/task_protocol.py
RootTaskAnchor、TaskBrief 版本与 ContextRef	cyber_agent/core/context_policy.py
read_context_ref	cyber_agent/tools/builtin/context.py
submit_task_report / review_task_result	cyber_agent/tools/builtin/task_protocol.py
ValidationPolicy、Plan、Scope 执行与聚合	cyber_agent/core/validation.py
受控搜索、URL 边界和 Serper 适配	cyber_agent/core/validator_web.py
ArtifactRef 与 ArtifactResolver 窄接口	cyber_agent/core/artifacts.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_validator_web.py
• tests/test_recursive_validation_artifacts.py
• tests/test_recursive_validator_lifecycle_complex.py
• tests/test_recursive_runtime_extensions.py