Agent/cyber_agent/docs/application/m2-m3-implementation.md

M2/M3 应用框架实现说明

状态：已实现，实验性 API，M6 前不承诺兼容。

已实现的运行合同

• 新 Recursive Trace 使用 revision 3；revision 2 仅允许读取和导出，所有写入入口统一返回 recursive_revision_2_read_only。
• TaskProgressRevision 是 append-only 的当前 Task 推进记录，只保存 phase、Question、Blocker、Finding、Hypothesis、WorkItem 和简短判断依据。它不复制 Trace 终态、Validator 结论或父级 TaskReview 决策。
• TaskProtocolService 负责单 Trace 的读取、版本校验、追加和持久化；update_task_progress 提交完整快照并使用 expected_revision 防止并发覆盖。
• TaskReport 和根任务验收都绑定精确 Progress revision、Task 合同 hash 和当时材料；Validator 只生成 ValidationResult，不修改 Progress。

权威实现：

• cyber_agent/core/task_protocol.py
• cyber_agent/core/task_protocol_service.py
• cyber_agent/core/validation.py
• cyber_agent/core/agent_mode.py

Application Runtime

cyber_agent.application 是实验性包，未从 cyber_agent.__init__ 顶层导出。业务代码通过以下对象装配现有 AgentRunner：

• AgentApplication / AgentRole / ToolSet / RunLimits：可序列化的应用声明。
• ApplicationServices：不落盘的 ContextProvider、ArtifactResolver、CandidateRepository、QualityCheckProvider、RunEventProjector 和凭证。
• ApplicationRegistry：按 application_id + application_version + config_hash 精确解析不可变 Binding。
• ApplicationRuntime：新建或恢复现有 Runner，不实现第二套 loop。

应用 Run 固化 RunConfigSnapshotV2。恢复顺序为：验证 snapshot hash、解析精确 ApplicationRef、重算 config hash、校验 role hash 和 Provider 运行依赖，然后才创建 Runner 并允许状态修改。

Candidate 与质量验收

• CandidateRef 只记录不可变身份、归属、合同、ArtifactRef 和血缘；正文由业务 CandidateRepository 保存。
• 根 Trace 的 candidate_ledger.json 持久化版本、验收、生命周期和幂等 operation。
• QualityCheckProvider 只能回答应用版本已固化的 rule_id/version。框架把确定性 check 和 LLM check 分开编译进同一 ValidationPlan，并严格校验结果集完整性。
• 候选验收按精确 CandidateRef 与 plan hash 独立缓存；一个候选失败不污染同一 TaskReport 的其他候选。
• adopt 先持久化 intent，再以稳定 operation ID 调用 Repository，最后固化 receipt。已提交的外部采用会形成 rewind barrier。

权威实现：

• cyber_agent/application/candidate.py
• cyber_agent/application/candidate_service.py
• cyber_agent/application/quality.py

规范事件与投影

TaskProgress、Candidate、Validation、TaskReview 和 rewind 在权威状态落盘后，向根 Trace 现有 events.jsonl 追加 run_event。稳定 event_key 用于崩溃后对账补发。

RunEventProjector 必须在同一业务事务中完成幂等检查、视图更新和 cursor 推进。RunEventPump 不越过失败事件；投影失败不回滚 Agent Trace，应用恢复和 Run 完成时会继续尝试。

权威实现：cyber_agent/application/events.py。

参考应用与验证

examples/application_reference/ 是可运行的最小创作应用。它证明：

1. 事实工具只调用一次并产生可追溯 Artifact。
2. A 验收通过，B 因占位文本只在 output 层失败。
3. B2 从 B fork，不重跑事实工具或 A 的验收。
4. 停止/恢复后 B2 通过并被精确采用一次。
5. 事件反复对账无重复投影，采用后跨越副作用的 rewind 被拒绝。

运行验收：

.venv/bin/python -m unittest tests.test_application_reference

完整回归还包括 tests.test_candidate_quality、tests.test_candidate_service、tests.test_application_events 和 tests.test_application_runtime_integration。