说明 recursive 根锚点与上下文授权协议

更新核心说明、上下文管理和 Recursive 任务协议，明确 RootTaskAnchor、TaskBrief 版本及逐边引用授权的职责。

记录不会继承的父级消息和内部状态、固定容量边界、回溯清理规则以及 Legacy 不进入新协议的兼容范围。

cyber_agent/README.md

@@ -110,7 +110,7 @@ QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 AGENT_MODE=legacy
 ```
 
-代码读取的是 `QWEN_API_KEY`；如果已有百炼 `BAILIAN_API_KEY`，需将其值同步给 `QWEN_API_KEY`。`AGENT_MODE=recursive` 还要在 `RunConfig.root_completion_criteria` 中提供根任务完成标准。
+代码读取的是 `QWEN_API_KEY`；如果已有百炼 `BAILIAN_API_KEY`，需将其值同步给 `QWEN_API_KEY`。`AGENT_MODE=recursive` 还要在 `RunConfig.root_task_anchor` 中提供根任务目标、完成标准和硬约束。
 
 ### 基础使用
 
@@ -151,7 +151,7 @@ asyncio.run(main())
 AGENT_MODE=recursive
 ```
 
-新建 Recursive 根 Trace 必须显式提供完成标准。在上例的 `main()`
+新建 Recursive 根 Trace 必须显式提供根任务锚点。在上例的 `main()`
 中将 `runner.run(...)` 替换为：
 
 ```python
@@ -159,16 +159,20 @@ async for item in runner.run(
     messages=[{"role": "user", "content": "分析项目架构并给出依赖关系"}],
     config=RunConfig(
         model="qwen3.5-plus",
-        root_completion_criteria=[
-            "列出主要模块及职责",
-            "说明核心调用链和模块依赖",
-        ],
+        root_task_anchor={
+            "objective": "分析项目架构并给出依赖关系",
+            "completion_criteria": [
+                "列出主要模块及职责",
+                "说明核心调用链和模块依赖",
+            ],
+            "constraints": ["结论必须来自实际代码"],
+        },
     ),
 ):
     ...
 ```
 
-Recursive 子任务使用结构化 TaskBrief，并经报告、独立验收和父级审核后继续规划。深度、工具权限、调度、停止和资源预算见 [Agent 运行模式](./docs/agent-modes.md)，报告与审核见 [Recursive 任务协议](./docs/recursive-task-protocol.md)。
+Recursive 子任务使用结构化 TaskBrief，并经报告、独立验收和父级审核后继续规划。根锚点与授权引用见 [Context 管理](./docs/context-management.md)，深度、工具权限、调度、停止和资源预算见 [Agent 运行模式](./docs/agent-modes.md)，报告与审核见 [Recursive 任务协议](./docs/recursive-task-protocol.md)。
 
 其他 Provider 通过对应的 `create_*_llm_call()` 创建，再传入 `AgentRunner(llm_call=...)`：
 

cyber_agent/docs/context-management.md

@@ -168,8 +168,22 @@ knowhub/agents/skills/         # KnowHub Librarian 的 skills
 
 ## Recursive 委托的 Context 边界
 
-Recursive revision 2 不把父 Agent 的完整 Context 复制给子 Agent。父级通过
-`TaskBrief` 显式下发：
+Recursive revision 2 不把父 Agent 的完整 Context 复制给子 Agent，而是分成根锚点、当前任务合同和逐层授权引用。
+
+### RootTaskAnchor：不漂移的根任务
+
+新建 Recursive 根 Trace 必须提供 `objective / completion_criteria / constraints`。框架规范化后在根 Trace 保存唯一副本和 SHA-256；创建任意子孙时重新读取该权威副本，中间 Agent 无法重新总结或覆盖。
+
+- 规范化后最多 4,000 字符。
+- 根约束自动进入第一层 TaskBrief，后续与各层新增约束稳定去重。
+- Anchor 在每个 Trace 的初始任务上下文和 `get_current_context` 中各出现一次，并固定进入 Validator 输入。
+- 缺少 Anchor 的早期 Recursive revision 2 Trace 不隐式升级，需重新创建。
+
+**实现**：`cyber_agent/core/context_policy.py:normalize_root_task_anchor`，`cyber_agent/core/runner.py:AgentRunner._prepare_new_trace`
+
+### TaskBrief：当前局部任务
+
+父级通过 `TaskBrief` 显式下发：
 
 ```text
 objective / reason
@@ -181,25 +195,42 @@ parent_findings / context / constraints
 
 - 校验必填字段和 JSON 可序列化性，拒绝 `NaN/Infinity`。
 - 对列表字段稳定去重。
-- 只自动继承父 TaskBrief 的 `constraints`，子级只能追加，不能删除。
+- 自动继承根 Anchor 和直接父 TaskBrief 的 `constraints`，子级只能追加，不能删除。
 - 规范化后的单份 TaskBrief 最多 16,000 字符。
 - 审核批准的下一份 TaskBrief 和实际 `agent()` 调用使用同一规范化逻辑，之后精确匹配。
+- 当前版本与历史版本保存在 `task_protocol`；`REVISE_CHILD` 续跑时统一替换，旧版本内容不变。
 
 子 Trace 还会获得必要的 Trace 血缘、固化工具能力快照、树级预算根 ID
 和协议状态。不会自动继承父级完整消息历史、`RunConfig.context`、内部
 运行对象、未筛选 Tool Result 或祖先 GoalTree。Recursive 本地 `agent()` 因此不接受
 `messages`；需要继承的业务信息必须写入 TaskBrief。
 
+### ContextRef：可逐层转授的完整协议引用
+
+TaskBrief 可携带 `context_refs: [{ref_id, version}]`。框架当前只生成两类不可变快照：
+
+- `task_brief`：直接父级某一版本的完整任务合同；根创建第一层时没有该引用。
+- `reviewed_task_result`：一次已完成父级审核的 `TaskReport + ValidationResult + TaskReview`。
+
+快照以规范化内容 SHA-256 作为版本。模型只能转授当前 Trace 本地目录已授权的精确 `ref_id/version`；孩子获得本地副本后通过 `read_context_ref` 按需读取，不会遍历其他 Trace。任意一层不再转授，更深后代立即失去访问权；不能按 Trace ID 自由读取祖先、兄弟、其他树或其他 UID。
+
+固定上限：每个 Trace 8 个引用，单个快照 16,000 字符，全部快照 64,000 字符。已审核结果超限时审核仍成功，但不生成可转授引用并返回警告。`REVISE_CHILD` 会清空旧授权，回溯会按 `granted_at_sequence` 删除截断点之后的授权。
+
+`get_current_context` 只展示 Anchor、TaskBrief 版本、引用元数据和静态字符用量，不自动展开快照。Token 用量仍以模型返回并进入 ResourceUsage 的 `prompt_tokens` 为准。
+
+**实现**：`cyber_agent/core/context_policy.py:build_child_context_access`，`cyber_agent/tools/builtin/context.py:read_context_ref`
+
 ### Validator 输入裁剪
 
 Validator 的输入不由被验收 Agent 自行组装。
-`cyber_agent/core/validation.py:build_validation_packet` 固定保留 TaskBrief、
+`cyber_agent/core/validation.py:build_validation_packet` 固定保留 RootTaskAnchor、TaskBrief、
 TaskReport、完成标准、预期产出和根候选答案，再按最新消息优先纳入
 持久化主路径和真实 Tool Result。
 
 - 整个输入包最多 50,000 字符。
 - 固定协议部分本身已超限时直接失败，不会删减完成标准换取轨迹。
 - 侧分支消息不进入验收包，持久化的 `reasoning_content` 会被移除。
+- Validator 不会自动展开所有 ContextRef；只有业务 Agent 真实调用 `read_context_ref` 后产生的 Tool Result 才会进入主路径验收轨迹。
 
 完整字段和验收流程见 [Recursive 任务协议](./recursive-task-protocol.md)。
 

cyber_agent/docs/recursive-task-protocol.md

@@ -26,6 +26,16 @@ Recursive 任务协议把本地父子 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：父级下发的任务说明
 
 | 字段 | 类型 | 规则 |
@@ -37,8 +47,9 @@ Recursive 任务协议把本地父子 Agent 协作约束为：
 | `parent_findings` | `string[]` | 父级已确认的发现，默认为空 |
 | `context` | `object` | 与本任务直接相关的显式上下文 |
 | `constraints` | `string[]` | 硬约束；自动继承父 TaskBrief 的约束，子级只能增加 |
+| `context_refs` | `ContextRef[]` | 当前父 Trace 已授权且明确转授的 `ref_id/version` |
 
-TaskBrief 会去重、检查 JSON 可序列化性，规范化后最多 16,000 字符。Recursive 本地 `agent()` 使用 `task_brief`，不接受 `messages`。
+TaskBrief 会去重、检查 JSON 可序列化性，规范化后最多 16,000 字符，并保存当前版本与历史版本。Recursive 本地 `agent()` 使用 `task_brief`，不接受 `messages`。
 
 ### TaskReport：子级提交的执行报告
 
@@ -98,8 +109,8 @@ pending → in_progress → waiting_children → pending_review
 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 必须与批准内容规范化后完全一致。
+4. `pending_review` 期间运行时只暴露 `review_task_result` 和可用时的 `read_context_ref`，Goal 工具也拒绝新增、完成、放弃或切换。
+5. 审核产生 next action 后，运行时只暴露 `agent` 和可用时的 `read_context_ref`，且实际 TaskBrief 必须与批准内容规范化后完全一致。
 
 Recursive 禁止 GoalTree 自动切换下一个 pending sibling，也禁止所有孩子完成时级联完成父 Goal。父 Agent 必须在审核后自己决定。
 
@@ -174,11 +185,13 @@ Validator Trace 的约束：
 
 Validator 输入由框架从 TaskBrief、TaskReport、完成标准、预期产出、持久化主路径消息和真实 Tool Result 组装。固定协议字段优先保留，轨迹按最新消息优先裁剪，整体最多 50,000 字符；不包含侧分支和持久化的 `reasoning_content`。
 
+RootTaskAnchor 也作为固定字段进入验收包。Validator 不会自动展开 ContextRef；只有业务 Agent 实际读取过的快照才会以 Tool Result 进入轨迹。
+
 Validator 默认继承被验收 Agent 的模型，可用 `AGENT_VALIDATOR_MODEL` 覆盖。模型输出非法、返回错误 scope、尝试调用工具或调用异常时，直接生成 `outcome=error`，不再发起格式修正调用。
 
 ### 根任务完成门禁
 
-新建 Recursive 根 Trace 必须显式提供 `root_completion_criteria`。根 Agent 生成无 Tool Call 的候选答案时，框架使用根标准、候选答案和持久化主路径运行 `scope=root` 的 Validator：
+新建 Recursive 根 Trace 必须显式提供 `root_task_anchor`。根 Agent 生成无 Tool Call 的候选答案时，框架使用 Anchor 中的根标准、候选答案和持久化主路径运行 `scope=root` 的 Validator：
 
 - 通过：根 Trace 才可写为 `completed`。
 - 第一次未通过或 Validator 错误：将框架生成的 ValidationResult 追加到根消息，允许修正一次。
@@ -205,6 +218,7 @@ Validator 默认继承被验收 Agent 的模型，可用 `AGENT_VALIDATOR_MODEL`
 
 ```text
 task_brief
+task_brief_version / task_brief_history
 task_report
 task_report_submitted_at_sequence
 task_report_validation
@@ -219,6 +233,8 @@ root_validation_passed
 protocol_correction_attempts
 ```
 
+`Trace.context.context_access` 另存当前 Trace 被授权的不可变快照与字符用量；该目录不并入 `task_protocol`。引用的生成、转授、读取和限额见 [Context 管理](./context-management.md#contextref可逐层转授的完整协议引用)。
+
 `pending_reviews` 的每一项同时保存 TaskReport、ValidationResult、原 Goal ID 和接收 sequence。GoalTree 不是这些协议事实的权威存储。
 
 ---
@@ -228,7 +244,8 @@ protocol_correction_attempts
 | 内容 | 位置 |
 |------|------|
 | 数据模型和协议状态 | `cyber_agent/core/task_protocol.py` |
-| TaskBrief 规范化与约束继承 | `cyber_agent/core/context_policy.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` |
 | Validator、ValidationResult 和输入裁剪 | `cyber_agent/core/validation.py` |
 | 运行时门禁、根 Validator、回溯恢复 | `cyber_agent/core/runner.py` |