更新 Validator 架构工具与 Trace 文档

cyber_agent/docs/agent-modes.md

@@ -164,19 +164,27 @@ Recursive 新根 Trace 会从环境变量读取一次预算，并把不可变快
 | `AGENT_MAX_TOTAL_TOKENS` | `1500000` | 输入和输出 Token 总数 |
 | `AGENT_MAX_TOTAL_COST_USD` | `15` | 累计模型成本（美元） |
 | `AGENT_MAX_DURATION_SECONDS` | `3600` | 从根用量初始化开始的最长时间 |
-| `AGENT_RESERVED_FINAL_CALLS` | `1` | 仅保留给根 Validator 的末尾调用数 |
+| `AGENT_MAX_VALIDATION_TOOL_CALLS` | `300` | 受控 Validator 搜索和页面读取总次数 |
+| `AGENT_MAX_VALIDATION_MATERIAL_CHARS` | `1000000` | Validator 解析的产物、搜索结果和页面正文字符总数 |
+| `AGENT_RESERVED_FINAL_CALLS` | `8` | 仅保留给根 Validator 的末尾调用数 |
 
 所有数值必须为正数，且 `AGENT_RESERVED_FINAL_CALLS < AGENT_MAX_LLM_CALLS`。预算动态用量保存在根 Trace 目录的 `resource_usage.json`，记录 Agent、LLM、Token、成本、起始时间和最后拒绝原因。
 
 关键计数语义：
 
-- Validator 不计入 Agent 数，但计入 LLM、Token、成本和时间。
+- Validator 不计入 Agent 数，但计入 LLM、Token、成本、时间、受控工具调用和验收材料字符数；搜索适配器上报的 Provider 成本也累加到整树成本。
 - `continue_from`、停止、失败、续跑和回溯不退还已产生用量。只有批量预留后实际未创建 Trace 的部分会撤销 Agent 预留。
 - 工具内部的模型调用只有在返回 `tool_usage` 时才能追加记录；`remote_*` 当前不纳入本地树预算。
 - LLM 次数在调用前预留，Token 和成本在响应后登记。在途响应导致超限时会保留实际消耗，但不再执行该响应的 Tool Call。
 
 用量文件缺失或损坏时 Recursive 会 fail closed。当前原子更新仅由单 Python 进程内每个 `root_trace_id` 的异步锁保护。
 
+Validator 配置也只在新建 Recursive 根 Trace 时固化：`AGENT_VALIDATOR_MODEL`
+可覆盖普通 Scope 模型，`AGENT_ROOT_VALIDATOR_MODEL` 可单独覆盖根验收模型。
+`AGENT_VALIDATOR_SEARCH_PROVIDER=serper` 且配置 `SERPER_API_KEY` 时，
+Evidence、Hypothesis 和 Root Validator 可使用受控公开网页搜索；默认
+`disabled`，缺少 Provider 时证据不足只能返回 `unknown`。
+
 **实现**：`cyber_agent/core/resource_budget.py:ResourceBudget`，`cyber_agent/core/resource_budget.py:ResourceBudgetController`，`cyber_agent/trace/store.py:FileSystemTraceStore.replace_resource_usage`
 
 ---
@@ -202,10 +210,13 @@ Recursive 新根 Trace 会从环境变量读取一次预算，并把不可变快
 | `tests/test_recursive_subtree_cancellation.py` | 子树停止、排队取消和 API Runner 路由 |
 | `tests/test_recursive_resource_budget.py` | 预算解析、原子计数、超限和用量持久化 |
 | `tests/test_recursive_replan_context.py` | 上下文继承、任务匹配和逐级回退 |
-| `tests/test_recursive_validation_core.py` | Validator 输入、独立性和结果校验 |
+| `tests/test_recursive_validation_core.py` | 分层 Policy、Plan、逐项结果和聚合 |
+| `tests/test_recursive_validator_web.py` | 搜索白名单、SSRF、DNS 固定、重定向和限额 |
+| `tests/test_recursive_validation_artifacts.py` | ArtifactRef、Resolver、hash 和跨树越权 |
 | `tests/test_recursive_runtime_extensions.py` | 根门禁、预算包装和停止后协议行为 |
 | `tests/test_recursive_context_policy.py` | 根锚点、TaskBrief 版本、引用授权与限额 |
-| `tests/test_recursive_context_integration.py` | 五层上下文漂移、真实读取、工具权限与逐层验收 |
+| `tests/test_recursive_context_integration.py` | 五层上下文、分层 Scope、受控搜索、权限与逐层审核 |
+| `tests/test_recursive_validator_lifecycle_complex.py` | 最深层修订和根结果独立验收的五层复杂用例 |
 
 ---
 

cyber_agent/docs/architecture.md

@@ -33,7 +33,9 @@ cyber_agent/
 │   ├── agent_mode.py      # Legacy / Recursive 模式策略
 │   ├── task_protocol.py   # Recursive 任务协议
 │   ├── context_policy.py  # Recursive TaskBrief 与验收上下文策略
-│   ├── validation.py      # Recursive 独立 LLM Validator
+│   ├── validation.py      # Recursive 分层 Policy、Plan、Scope 验收和聚合
+│   ├── validator_web.py   # Validator 受控公网搜索与只读页面
+│   ├── artifacts.py       # 不可变 ArtifactRef 与可注入 Resolver
 │   ├── resource_budget.py # Recursive 树级资源预算
 │   └── presets.py         # Agent 预设（delegate、explore、evaluate 等）
 │

cyber_agent/docs/tools.md

@@ -1006,6 +1006,11 @@ review_task_result(
 )
 ```
 
+Evidence、Hypothesis 和 Root Validator 可在独立私有 Registry 中看到
+`validator_web_search` 和 `validator_open_url`。这两个窄工具不注册到全局
+ToolRegistry，业务 Agent、Legacy、Remote 和普通 Sub-Agent 不能调用；它们也不等于
+完整 Browser，不提供 Cookie、登录、点击、JS、下载或写操作。
+
 当前 Trace 拥有框架授权的 ContextRef 时，Recursive 业务 Agent 还可按精确版本读取：
 
 ```python

cyber_agent/docs/trace-api.md

@@ -225,7 +225,9 @@ GET /api/traces/{trace_id}
 - GoalTree（该 Trace 的完整 Goal 树）
 - `sub_traces`：所有 `parent_trace_id == trace_id` 的直接子 Trace 元数据，包括业务子 Agent 和 Validator Trace
 
-Validator Trace 使用 `agent_type="validator"` 且 `context.created_by_tool="validator"`；它不增加业务 `agent_depth`，也不计入每父六个业务孩子。如果只需业务子 Agent，存储层查询应同时使用 `parent_trace_id` 和 `created_by_tool="agent"`。
+每个有效验收 Scope 都会生成一个 Validator Trace，使用 `agent_type="validator"`、
+`context.created_by_tool="validator"` 和 `context.validation_scope`。它不增加业务
+`agent_depth`，也不计入每父六个业务孩子。如果只需业务子 Agent，存储层查询应同时使用 `parent_trace_id` 和 `created_by_tool="agent"`。
 
 #### 3. 获取 Messages