|
|
@@ -0,0 +1,68 @@
|
|
|
+# 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 被拒绝。
|
|
|
+
|
|
|
+运行验收：
|
|
|
+
|
|
|
+```bash
|
|
|
+.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`。
|
SamLee