|
|
@@ -0,0 +1,244 @@
|
|
|
+# Application Reference Example 验收合同
|
|
|
+
|
|
|
+> **受众**：业务应用团队与框架团队
|
|
|
+>
|
|
|
+> **状态**：`[TARGET / CONTRACT]`，M1 只定义场景、目录和验收；本阶段不创建可运行代码
|
|
|
+>
|
|
|
+> **未来位置**：`examples/application_reference/`
|
|
|
+
|
|
|
+## 1. 为什么需要这个 example
|
|
|
+
|
|
|
+Application API 只有经过一条真实、跨停止恢复的业务链路验证，才能证明业务无需修改框架内核。这个 example 是 M2/M3 的 walking skeleton 和接入合规测试载体，不是脚本构建第三版，也不追求完整创作产品体验。
|
|
|
+
|
|
|
+它选择一个“证据驱动的创作任务”，因为该场景同时需要：
|
|
|
+
|
|
|
+- 先验证事实，再产生表达，能检验 Context 和 Artifact 的分层。
|
|
|
+- 同时保留两个候选，能检验归属、血缘和采用。
|
|
|
+- 用确定性规则发现局部产物问题，能检验 Validator 的局部回退。
|
|
|
+- 经父级审核决定下一步，能检验 ValidationResult 与 TaskReview 的权威边界。
|
|
|
+- 停止、重启和回溯，能检验应用身份和版本化状态是否完整恢复。
|
|
|
+
|
|
|
+本文依赖的业务接口仍是未实现草案，见 [Application API 0.1](./application-api-0.1-draft.md)。框架状态与业务边界见 [M1 设计基线](./application-framework-m1.md)。
|
|
|
+
|
|
|
+## 2. 场景定义
|
|
|
+
|
|
|
+### 2.1 输入
|
|
|
+
|
|
|
+根目标收到一个主题和一组已登记资料，要求形成一份完整、可发布的短内容。输入固定包含：
|
|
|
+
|
|
|
+- 一个需要核实的事实概念。
|
|
|
+- 两份可授权的来源资料，其中一份只允许事实核实 Task 使用。
|
|
|
+- 一条创作要求：正文必须基于已验证 Finding，不能保留占位描述。
|
|
|
+- 一条资源约束：只允许一个事实子 Task 和最多两个表达候选。
|
|
|
+
|
|
|
+示例不使用脚本段落、账号人设、Pattern、脚本元素或 SQL branch。未来脚本构建应用可以替换这里的业务对象，但不能把这些概念加入框架公共模型。
|
|
|
+
|
|
|
+### 2.2 角色
|
|
|
+
|
|
|
+| 角色 | 业务职责 | 框架约束 |
|
|
|
+|---|---|---|
|
|
|
+| `editor` | 持有根目标，委派事实核实，比较候选并提交最终内容 | 只能创建 `fact_checker` 和 `writer`；不能伪造验证结果 |
|
|
|
+| `fact_checker` | 提问、读取获授权资料、形成 Finding 和假设 | 只读资料工具；不能创建候选或写最终内容 |
|
|
|
+| `writer` | 使用已验证 Finding 生成两个候选表达 | 不能读取未转授的原始事实资料；候选必须进入 Repository |
|
|
|
+
|
|
|
+角色名和提示词属于 example。框架只识别应用内角色身份、允许的子角色关系、工具能力和资源限制。
|
|
|
+
|
|
|
+### 2.3 可替换应用组件
|
|
|
+
|
|
|
+example 必须分别实现并允许在测试中替换：
|
|
|
+
|
|
|
+- `TaskContextProvider`：枚举两份来源资料及其版本、hash、继承和授权元数据。
|
|
|
+- 事实核实工具：读取当前 Task 已获授权的资料并产出 ArtifactRef。
|
|
|
+- `ArtifactResolver`：按精确版本可信读取事实 Finding 和候选正文。
|
|
|
+- `CandidateRepository`：保存候选内容、fork、修订、归属和采用写回。
|
|
|
+- `QualityCheckProvider`：提供“正文不得含占位描述”的确定性规则。
|
|
|
+- `RunEventProjector`：把 Task、候选、验证和采用事件投影到测试业务视图。
|
|
|
+
|
|
|
+测试替身只能替换 Provider/工具实现，不得替换 Runner、TaskProtocol、TraceStore、Validator 或 ResourceBudgetController。
|
|
|
+
|
|
|
+## 3. 端到端流程
|
|
|
+
|
|
|
+### 步骤 1：创建根目标 `[M3A]`
|
|
|
+
|
|
|
+业务入口使用固定 ApplicationRef 创建新 Run。框架解析 `editor` 根角色，固化应用版本、config hash、角色 hash、工具、质量规则和 RunLimits，并创建 RootTaskAnchor。
|
|
|
+
|
|
|
+验收证据：Trace 的恢复合同能指出精确应用版本；根目标和根约束不可被子角色改写。
|
|
|
+
|
|
|
+### 步骤 2：事实核实子 Task `[M2 + M3A]`
|
|
|
+
|
|
|
+`editor` 委派一个 `fact_checker` Task。该 Task 通过框架命令记录：
|
|
|
+
|
|
|
+- 一个待回答 `Question`。
|
|
|
+- 资料之间的一个 `Finding`，带 ContextRef/ArtifactRef。
|
|
|
+- 一个仍待确认的 `Hypothesis` 或明确说明没有未决假设。
|
|
|
+- 简短判断依据，不保存模型原始思维链。
|
|
|
+
|
|
|
+TaskContextProvider 只枚举资料；框架决定授权，并阻止该 Task 读取另一个 root 或兄弟 Task 的引用。
|
|
|
+
|
|
|
+验收证据：TaskProgress 绑定当前 TaskBrief revision；事实报告经 Validator 和父级 TaskReview 接受后形成可复用证据，不靠自由文本暗示“已验证”。
|
|
|
+
|
|
|
+### 步骤 3：生成两个候选 `[M2 + M3B]`
|
|
|
+
|
|
|
+`editor` 把已验证 Finding 转授给 `writer`，但不必重新转授原始事实资料。`writer` 生成候选 A 和候选 B：
|
|
|
+
|
|
|
+- 两者都保存为不可变内容版本，并获得 ArtifactRef 和 CandidateRef。
|
|
|
+- CandidateRef 记录 application/root/trace/task 归属和血缘。
|
|
|
+- 候选 A 内容完整；候选 B 故意包含 `{待补充事实}` 占位描述。
|
|
|
+
|
|
|
+验收证据：两个 CandidateRef 均属于 writer Task；只凭候选 ID 不能从另一应用或另一 root 读取内容。
|
|
|
+
|
|
|
+### 步骤 4：确定性检查发现局部问题 `[M3A + M3B]`
|
|
|
+
|
|
|
+QualityCheckProvider 声明稳定、版本化的占位描述检查。框架把它编译进 ValidationPlan：候选 A 通过，候选 B 的 output scope 失败，结果仍覆盖该 scope 计划内的全部 check_id。
|
|
|
+
|
|
|
+验收证据：规则 Provider 不直接写 ValidationResult、TaskProgress 或候选阶段；规则 ID/版本和解析配置已经进入本 Run 的恢复合同。
|
|
|
+
|
|
|
+### 步骤 5：只退回候选产物层 `[M2 + M3B]`
|
|
|
+
|
|
|
+Validator 对候选 B 给出 output/candidate 层的回退建议，不让 `fact_checker` 重新检索已经通过的事实。父级 TaskReview 决定让 `writer` 从 B fork 修订版 B2，或放弃 B。
|
|
|
+
|
|
|
+验收证据：已接受的 Finding、事实 Artifact 和事实 TaskReport 保持原版本；只新增候选修订和对应验证历史，不覆盖旧 B。
|
|
|
+
|
|
|
+### 步骤 6：父级采用或继续修订 `[M2 + M3B]`
|
|
|
+
|
|
|
+`editor` 比较已通过的 A 与修订后的 B2，通过 TaskReview 选择：
|
|
|
+
|
|
|
+- 采用一个候选并返回根目标重新判断；或
|
|
|
+- 要求 writer 继续修订；或
|
|
|
+- 在根约束无法满足时失败上行。
|
|
|
+
|
|
|
+只有采用动作可以调用 CandidateRepository 的幂等业务写回。ValidationResult 只表示验收，不能替父级选择候选。
|
|
|
+
|
|
|
+验收证据：最终内容引用被采用的精确 CandidateRef/ArtifactRef；重复投递采用事件或重复写回不会产生两个业务结果。
|
|
|
+
|
|
|
+### 步骤 7：停止、重启和回溯 `[M2 + M3A + M3B]`
|
|
|
+
|
|
|
+测试在三个位置执行恢复：事实 Task 完成后停止、人工确认等待期间重启、候选 B 失败后回溯。恢复后必须保持：
|
|
|
+
|
|
|
+- 相同 ApplicationRef、角色 hash、工具、规则和 RunLimits。
|
|
|
+- 相同 TaskBrief/TaskProgress 历史和 sequence head。
|
|
|
+- 相同 Context/Artifact 授权，不扩大跨 Task 访问。
|
|
|
+- 相同候选内容、归属、血缘和验证结果。
|
|
|
+- 相同业务投影 cursor；事件重放不产生重复数据。
|
|
|
+
|
|
|
+应用版本缺失或 config hash 被修改时，恢复必须失败关闭，不能采用当前默认配置继续。
|
|
|
+
|
|
|
+## 4. 未来目录合同
|
|
|
+
|
|
|
+M1 **不会**创建以下目录。M2/M3 实现期间按能力逐步增加，目录名称可在实现评审时小幅调整，但职责不能混合：
|
|
|
+
|
|
|
+```text
|
|
|
+examples/application_reference/
|
|
|
+├── README.md # 运行方式、场景和里程碑状态
|
|
|
+├── application.py # AgentApplication 声明，不包含 Runner 分叉
|
|
|
+├── roles/
|
|
|
+│ ├── editor.prompt
|
|
|
+│ ├── fact_checker.prompt
|
|
|
+│ └── writer.prompt
|
|
|
+├── skills/ # example 专属业务技能
|
|
|
+├── tools/
|
|
|
+│ ├── verify_fact.py # 事实核实工具
|
|
|
+│ └── propose_candidates.py # 候选生成工具
|
|
|
+├── providers/
|
|
|
+│ ├── context.py # TaskContextProvider
|
|
|
+│ ├── artifacts.py # ArtifactResolver
|
|
|
+│ ├── candidates.py # CandidateRepository
|
|
|
+│ ├── quality.py # QualityCheckProvider
|
|
|
+│ └── projector.py # RunEventProjector
|
|
|
+├── fixtures/ # 小型、确定、无外网依赖的业务资料
|
|
|
+└── tests/
|
|
|
+ ├── test_happy_path.py
|
|
|
+ ├── test_context_authorization.py
|
|
|
+ ├── test_candidate_ownership.py
|
|
|
+ ├── test_local_retry.py
|
|
|
+ ├── test_application_restore.py
|
|
|
+ └── test_event_projection.py
|
|
|
+```
|
|
|
+
|
|
|
+`application.py` 只装配公共应用描述和 Provider，不创建自定义 loop。测试使用框架公开入口和可替换 Provider，不访问 TraceStore 的内部文件来伪造状态。
|
|
|
+
|
|
|
+## 5. 里程碑依赖
|
|
|
+
|
|
|
+| 能力/步骤 | M2 | M3A | M3B | M1 后的可运行状态 |
|
|
|
+|---|---:|---:|---:|---|
|
|
|
+| Question/Finding/Hypothesis 和 TaskProgress revision | 必需 | | | M2 后可做协议级测试 |
|
|
|
+| 应用身份、Registry/Binding/Runtime、严格恢复 | | 必需 | | M3A 后可创建应用 Run |
|
|
|
+| AgentRole、ToolSet、TaskContextProvider | | 必需 | | M3A 后可替换角色、资料和工具 |
|
|
|
+| ArtifactResolver 应用绑定 | | 必需 | | M3A 后可从应用恢复 Resolver |
|
|
|
+| QualityCheckProvider 与规则版本固化 | | 必需 | 可随候选联调 | M3A 后可跑单 Artifact 规则 |
|
|
|
+| CandidateRef 和 CandidateRepository | | | 必需 | M3B 后可完成双候选链路 |
|
|
|
+| 规范事件和 RunEventProjector cursor | | | 必需 | M3B 后可验证业务投影 |
|
|
|
+| 完整七步 example | 必需 | 必需 | 必需 | 三个里程碑完成后才可运行 |
|
|
|
+
|
|
|
+因此，任何文档或 README 都不能在 M2/M3B 完成前把此 example 标记为“可运行的应用模板”。
|
|
|
+
|
|
|
+## 6. 验收用例
|
|
|
+
|
|
|
+### AR-01 应用隔离
|
|
|
+
|
|
|
+同一进程注册 `application_reference@1` 和一个同名角色/工具但不同应用 ID 的测试应用。两者的角色、工具、Context、Resolver、规则和候选完全隔离；全局 Preset 不参与解析。
|
|
|
+
|
|
|
+### AR-02 跨 Task Context 越权
|
|
|
+
|
|
|
+writer 尝试读取只授权给 fact_checker 的原始资料，框架拒绝。父级合法转授已经验证的 Finding 后，writer 只能读取该新 ContextRef/ArtifactRef。
|
|
|
+
|
|
|
+### AR-03 应用恢复 hash
|
|
|
+
|
|
|
+停止并重启进程后，相同应用版本和 hash 能恢复。修改 Prompt、工具 schema、规则版本或 RunLimits 后复用旧版本号，旧 Trace 恢复失败；修改 Provider 凭证但行为配置未变时 hash 不变，凭证缺失则装配失败。
|
|
|
+
|
|
|
+### AR-04 候选归属与血缘
|
|
|
+
|
|
|
+候选只能由所属 application/root/task 读取或修订。B2 的 parent 指向 B；A 不因 B 的失败而被回退；另一 root 复用 candidate_id 时被拒绝。
|
|
|
+
|
|
|
+### AR-05 确定性规则完整性
|
|
|
+
|
|
|
+占位规则只让 B 的 output scope 失败，ValidationResult 的 check_id 与计划严格相等。Provider 异常时也产生计划完整的失败关闭结果，不生成计划外 ID。
|
|
|
+
|
|
|
+### AR-06 局部回退
|
|
|
+
|
|
|
+B 失败后只重新执行 writer 的候选修订，事实 Task 的工具调用次数、Artifact 版本和 ValidationResult 不变。父级 TaskReview 是是否修订的唯一决定来源。
|
|
|
+
|
|
|
+### AR-07 停止、重启、回溯
|
|
|
+
|
|
|
+在事实完成、工具确认等待和候选失败三个位置分别恢复。应用身份、协议版本、候选、授权和预算一致；回溯形成新历史，不覆盖旧结果。
|
|
|
+
|
|
|
+### AR-08 事件幂等
|
|
|
+
|
|
|
+Projector 在同一事件上故障并重放，业务视图只出现一个候选版本和一次采用动作。投影停机不改变 Trace 的 completed/failed 状态。
|
|
|
+
|
|
|
+### AR-09 内核零修改
|
|
|
+
|
|
|
+example 的实现提交不得修改以下目录中的运行时代码：
|
|
|
+
|
|
|
+- `cyber_agent/core/runner.py`
|
|
|
+- `cyber_agent/core/task_protocol.py`
|
|
|
+- `cyber_agent/trace/store.py`
|
|
|
+- `cyber_agent/core/validation.py`
|
|
|
+
|
|
|
+若 example 必须修改这些文件才能接入，应先判定为框架通用能力缺口，单独设计和测试，不能把业务特例塞入内核。
|
|
|
+
|
|
|
+## 7. 验收证据格式
|
|
|
+
|
|
|
+最终 reference example 的 CI 必须输出或保存以下可审计证据：
|
|
|
+
|
|
|
+- 测试所用 ApplicationRef 和解析后 config hash。
|
|
|
+- 根 Trace、事实 Task、writer Task 的 ID 和父子关系。
|
|
|
+- TaskBrief/TaskProgress revision、ValidationResult 和 TaskReview 引用链。
|
|
|
+- ContextRef、ArtifactRef、CandidateRef 的归属和内容 hash。
|
|
|
+- 局部回退前后的工具调用计数和保留版本。
|
|
|
+- Projector 起止 cursor、故障重放次数和最终业务记录数。
|
|
|
+
|
|
|
+证据可由测试 fixture 和结构化断言形成，不要求保存模型原始推理文本，也不应在日志中输出凭证或完整敏感资料。
|
|
|
+
|
|
|
+## 8. 完成定义
|
|
|
+
|
|
|
+只有同时满足以下条件，reference example 才能从合同升级为“可运行模板”：
|
|
|
+
|
|
|
+- 七步业务流程和 AR-01 至 AR-09 全部通过。
|
|
|
+- 角色、资料 Provider、工具、候选 Repository 和质量规则可分别替换。
|
|
|
+- 停止、进程重启和回溯均不改变应用身份、Task 合同、候选与验收结果。
|
|
|
+- 业务代码没有直接修改协议 context、TraceStore 文件或 Validator 结果。
|
|
|
+- example 中所有创作概念均留在 example；公共框架仍保持业务无关。
|
|
|
+- 业务团队只阅读公开接入文档即可完成一次同类替换实现。
|
|
|
+
|
|
|
+M1 到此只冻结验收问题，不宣称这些能力已经存在。
|
SamLee