更新 recursive 分层验收协议文档

cyber_agent/docs/context-management.md

@@ -224,11 +224,11 @@ TaskBrief 可携带 `context_refs: [{ref_id, version}]`。框架当前只生成
 
 Validator 的输入不由被验收 Agent 自行组装。
 `cyber_agent/core/validation.py:build_validation_packet` 固定保留 RootTaskAnchor、TaskBrief、
-TaskReport、完成标准、预期产出和根候选答案，再按最新消息优先纳入
+TaskReport、ValidationPlan、已解析 Artifact 和根候选答案，再按最新消息优先纳入
 持久化主路径和真实 Tool Result。
 
 - 整个输入包最多 50,000 字符。
-- 固定协议部分本身已超限时直接失败，不会删减完成标准换取轨迹。
+- 固定协议或必需材料本身已超限时返回 `unknown`，不会删减标准或截断真实产物后通过。
 - 侧分支消息不进入验收包，持久化的 `reasoning_content` 会被移除。
 - Validator 不会自动展开所有 ContextRef；只有业务 Agent 真实调用 `read_context_ref` 后产生的 Tool Result 才会进入主路径验收轨迹。
 

cyber_agent/docs/recursive-task-protocol.md

@@ -48,6 +48,7 @@ Recursive 任务协议把本地父子 Agent 协作约束为：
 | `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`。
 
@@ -61,27 +62,29 @@ TaskBrief 会去重、检查 JSON 可序列化性，规范化后最多 16,000
 | `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 必须审核后才能执行。
 
-### ValidationResult：框架权威验收
+### ValidationPlan / 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 自身异常或输出非法。
+`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：父级的审核决定
 
@@ -136,6 +139,7 @@ Recursive 禁止 GoalTree 自动切换下一个 pending sibling，也禁止所
 |------------------|------------|
 | `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` |
 
 还有两层硬约束：
@@ -172,22 +176,44 @@ Recursive 禁止 GoalTree 自动切换下一个 pending sibling，也禁止所
 
 ### 子任务验收
 
-`satisfied/partial` 报告会启动一次真实 LLM Validator；`failed/protocol_error` 报告以及框架为已停止孩子生成的 `failed` 报告，会得到确定性的不通过结果，不额外调用模型。每个报告版本只保存一份 Validator 结果；`REVISE_CHILD` 提交新报告后才会重新验收。
+`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 预算。
-- 无工具、无 Agent Loop、单次 LLM 调用，`temperature=0`。
+- `output/task` 为单次无工具 LLM；`evidence/hypothesis/root` 可进入有轮次上限的受控 Agentic 循环，均使用 `temperature=0`。
 - 调用计入整树 LLM、Token、成本和时间预算，并参与当前进程的子树停止。
 - 不可 `continue_from`，不再生成 Validator。
 
-Validator 输入由框架从 TaskBrief、TaskReport、完成标准、预期产出、持久化主路径消息和真实 Tool Result 组装。固定协议字段优先保留，轨迹按最新消息优先裁剪，整体最多 50,000 字符；不包含侧分支和持久化的 `reasoning_content`。
+Validator 输入由框架从 Policy、Plan、TaskBrief、TaskReport、RootTaskAnchor、
+持久化主路径、真实 Tool Result 和已解析 Artifact 组装。固定协议和必需材料
+优先保留，轨迹按最新消息优先裁剪，整体最多 50,000 字符；必需材料无法
+完整进入时返回 `unknown`，不会截断后通过。侧分支和 `reasoning_content` 不进入验收。
 
 RootTaskAnchor 也作为固定字段进入验收包。Validator 不会自动展开 ContextRef；只有业务 Agent 实际读取过的快照才会以 Tool Result 进入轨迹。
 
-Validator 默认继承被验收 Agent 的模型，可用 `AGENT_VALIDATOR_MODEL` 覆盖。模型输出非法、返回错误 scope、尝试调用工具或调用异常时，直接生成 `outcome=error`，不再发起格式修正调用。
+`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`。框架不提供任意本地路径读取。
 
 ### 根任务完成门禁
 
@@ -247,7 +273,9 @@ protocol_correction_attempts
 | 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` |
-| Validator、ValidationResult 和输入裁剪 | `cyber_agent/core/validation.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` |
@@ -257,4 +285,7 @@ protocol_correction_attempts
 - `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`