Recursive 任务协议

文档维护规范

代码是权威实现 - 本文档只记录 AGENT_MODE=recursive revision 2 已实现的协议；字段和门禁变更时需同步更新
协议与投影分层 - Trace.context.task_protocol 是权威状态，Goal 状态只用于流程展示
不扩展到 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

父 Agent 调用 agent(task_brief=...) 后，原 Goal 进入 waiting_children。
子 Agent 必须先审核完自己的孩子、执行完已批准 action，再调用 submit_task_report。
子报告经 Validator 处理后，父 Goal 进入 pending_review。
pending_review 期间运行时只暴露 review_task_result 和可用时的 read_context_ref，Goal 工具也拒绝新增、完成、放弃或切换。
审核产生 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

recursive-task-protocol.md 14 KB Permalink History Raw