Ouroboros AgentOS Projection 后续工作全解：从 946 基线到可交付的只读投影栈

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具

导读

本文围绕 Ouroboros（Agent OS）中 #946「Projection（投影）」后续工作序列展开，梳理了在 v1 投影记录、EventStore 投影构建器、MCP 查询表面、身份加固、边界文档与 RunSnapshot 读模型落地之后，剩余的全部 follow-up 通道（follow-up lanes）及其边界约束。读者将掌握：投影栈的只读数据模型与构建原理、ouroboros status run --json与ouroboros_query_projection的用法、哪些后续槽位已随 PR 发货、哪些仍开放可认领，以及判定一个后续改动是否「安全」的五问审查清单。

文档定位：非权威的队列配套说明

docs/agentos/projection-followups.md是 #946 投影栈的后续工作队列（follow-up queue），它记录的是 v1 投影记录、EventStore 构建器、MCP 查询面、身份加固、边界文档以及 RunSnapshot 读模型落地之后剩余的后续通道。它有三条明确的自我约束：

• 本文档是非权威的队列配套说明，服务于 #961（AgentOS 单一事实来源 SSOT）；
• 一旦与 projection-v1-scope.md 发生分歧，以 #961 与规范的 #946 issue 为准；
• 后续对本文档的编辑应严格限定在已被上述来源接受的排序范围内，不得借它创建新的 AgentOS 表面或第二个路线图 SSOT。

也就是说，读这篇文章时应当把它当作一张「可认领工作清单 + 边界护栏」，而不是一份独立的技术规范。

当前基线：一摞只读的投影栈

文档给出的 #946 基线由四个事实构成，全部可以在仓库源码中得到印证：

1. RunRecord、StageRecord、StepRecord、ArtifactRecord、VerdictRecord五类记录 schema 已经存在；
2. ProjectionBuilder从已知的工具调用 / LLM 调用事件对中推导稳定的 Run/Stage/Step 记录；
3. ouroboros_query_projection在不写行、不建 schema 的前提下，从 EventStore 行中暴露机器可读的投影数据；
4. build_run_snapshot从投影记录推导出一个保守的、可安全恢复（safe-resume）的读模型。

v1 记录 schema：不可变的 Pydantic 值对象

五类记录的 schema 定义在 src/ouroboros/harness/projection.py。其设计约束写在模块 docstring 里，直接对应 #946 的验收标准：

• 记录不可变：所有记录都是frozen=True的 Pydantic 模型，可被当作投影、比较与持久化层中的纯值使用；
• 元数据只读：metadata字段通过MappingProxyType视图包装，record.metadata[key] = value会在运行时抛出TypeError；序列化时再转回普通dict输出 JSON（见FrozenMetadata，projection.py）；
• 标识符卫生：IdentifierTuple/Identifier会剔除空白并拒绝空串或纯空白项，保证跨记录引用可用（projection.py）；
• Schema 版本化：每个记录携带schema_version，v1 是初始版本（PROJECTION_SCHEMA_VERSION = 1），未来新增字段需显式升版本。

记录模型的层次关系为：RunRecord（一次 Seed/目标执行的顶层封装，持有seed_id、goal、stage_ids、verdict_id）→StageRecord（命名阶段，kind取自StageKind：interview/seed/execute/evaluate/evolve/plugin/hitl）→StepRecord（最小可寻址工作单元，kind取自StepKind：model_call/tool_call/shell_command/subagent_dispatch/plugin_command/evaluation_check/evidence_submission/harness_internal）→ArtifactRecord与VerdictRecord。

三个值得注意的运行时不变式：

• StepRecord必须满足「有source_event_ids或legacy_inferred=True」二选一，否则构造失败（对应 #946 验收标准第 3 条，projection.py）；
• VerdictRecord中scope='ac'必须携带ac_id，scope='run'则必须没有ac_id（projection.py）；
• 时间戳必须是时区感知的（timezone-aware），拒绝 naive datetime。

ProjectionBuilder：对 EventStore 的纯读转换

构建器实现在 src/ouroboros/harness/projection_builder.py。它是一个纯读转换：只遍历有序BaseEvent序列，绝不持久化记录、绝不修改事件本身。

PR-1b 已识别的关键事件族及其配对规则：

阶段事件（stage events）目前尚未映射：构建器只产生一个默认的StageKind.EXECUTE阶段来承载所有步骤，更丰富的阶段检测被显式留作后续工作（projection_builder.py）。

构建器的身份派生是确定性的，这是「可重建读模型」的关键：

• _derive_projection_source_key优先使用唯一的 execution 聚合，其次唯一的 session 聚合，再次是事件切片摘要（uuid5基于事件身份部分计算），最后回退到seed:<seed_id>（projection_builder.py）；
• run_id/stage_id/step_id全部由uuid5(NAMESPACE_URL, ...)从 source key 稳定推导，因此「增量构建」与「对同一终态事件集的一次性重放」收敛到相同结果；
• 会话与执行语义的规范化（canonical AC 身份、tool call ID 提取、终端 ok 判定）集中在 src/ouroboros/harness/projection_event_semantics.py——resolve_tool_terminal_ok的一个设计要点是：禁止把畸形的 provider 声明洗白成成功，无任何 verdict 信号时保持unknown。

只读 MCP 查询表面：ouroboros_query_projection

查询处理器在 src/ouroboros/mcp/tools/projection_handlers.py，是 #946 PR-2 的只读 MCP 表面，按需从 EventStore 计算投影，不缓存、不改写任何行。工具参数如下：

校验规则同样值得注意：session_id与execution_id至少给一个；limit必须是正整数；若 session 声明/引用多个 execution，则必须显式提供execution_id，否则「歧义即失败关闭」（fail closed）。返回内容同时包含人类可读的文本摘要（Run Projection块）与机器可读的meta（含 run/stages/steps/artifacts/verdicts 的model_dump(mode="json")）。

build_run_snapshot：保守的安全恢复读模型

快照构建器在 src/ouroboros/harness/run_snapshot.py，是 #946 后续工作中「读模型之上再派生读模型」的典型：输入已经是投影记录，输出RunSnapshotRecord，期间不做任何 EventStore 写入或运行时调度。

safe_resume的判定是保守的：只有「非终结运行 + 至少一个 pending 步骤 + 无失败步骤 + 无任何 blocker」才标记可恢复（run_snapshot.py）。状态派生逻辑会输出一系列 blocker 代码，例如terminal_status:failed、human_input_required、linked_verdict_missing、pending_steps_after_stage_end、pending_step_source_events_missing等（run_snapshot.py）。此外，build_run_snapshot会对投影 bundle 做一致性校验：stage 必须归属 run、run.stage_ids必须与提供的 stages 一致、StageRecord.step_ids必须与提供的 steps 一致、verdict 的证据 artifact ID 必须都能在 bundle 中找到，任一不匹配即抛错——这保证了快照永远建立在自洽的投影之上。

后续 PR 槽位：哪些已发货，哪些仍开放

文档以表格形式给出了可认领的后续槽位。标注 ✅ 的表示已随对应 PR 发货；未标注的仍开放，且属于边界内的后续工作。这张表列举的是全部可认领槽位，而不只是未实现项——在排期新工作前应核对 ✅ 标记与对应 PR。

关于已发货槽位的实现证据：

• Artifact/Verdict 投影（#1061）：ProjectionBuilder的_artifact_from_event与_verdict_from_event即其落地实现——artifact 只挂接到已投影步骤（artifact.step_id in valid_step_ids才会被保留），verdict 只链接 bundle 内实际存在的 artifact ID，若记录的evidence_artifact_ids缺失，则把 outcome 降级为UNKNOWN并在元数据中标记missing_evidence_artifact_ids（projection_builder.py）；
• Status JSON CLI（#1064）：ouroboros status run命令实现在 src/ouroboros/cli/commands/status.py，它只是ProjectionQueryHandler的薄壳——源码注释明确「同一 run 锚点在 MCP 查询与本命令--json下返回逐字节一致的 JSON」。其退出码遵循 Wave-1 #946 S2 约定：0渲染成功、2run 锚点未知、64输入畸形（缺少或冲突的选择器），其余处理失败为1。典型用法：

# 以 execution 锚点投影 ouroboros status run <execution_id> --json # 以 session 锚点投影（会话覆盖多个 execution 时必须显式给 execution_id） ouroboros status run --session-id <session_id> --json # 以 execution 锚点 + seed 覆盖 + 事件数上限 ouroboros status run --execution-id <execution_id> --seed-id <seed_id> --limit 500 # 人类可读摘要 ouroboros status run <execution_id>

• 机械评估 fixture（PR #1132）：对应的测试目录为 tests/integration/test_mechanical_eval_projection.py，配合 tests/unit/harness/test_projection_builder.py、tests/unit/harness/test_projection_records.py、tests/unit/harness/test_projection_current_events.py 一起构成了确定性的事件对→记录投影测试面。

明确的禁止操作（anti-actions）

#946 的边界护栏逐条划清了投影栈不得变成什么。任何后续工作都不得：

• 不得把投影记录当作权威状态——EventStore/journal 始终是事实来源；
• 不得添加投影缓存——除非存在一个明确的缓存失效与迁移负责人；
• 不得在 #946 中定义新的类型化 AC 证据 schema——证据语义由 #830/#978 负责；
• 不得在 #946 中添加插件权限/审计行为——该表面归 #939；
• 不得在 #946 中引入 HITL 恢复权限——WAIT/RESUME 行为归 #960；
• 不得从 #946 接线 Workflow IR 的实时调度——规划 IR 归 #956，执行/默认门控由 #920/#978 管辖。

对应到 projection-v1-scope.md 的显式延后清单：类型化 AC 证据 schema、Workflow 节点图与生命周期、HITL WAIT/RESUME 权限契约、插件权限/审计 SDK、StepSnapshot/会话健康/运行时句柄/恢复令牌、OpenTelemetry 导出器、context pack 提供与检查点浓缩、完整重放/重跑语义、投影缓存——各自都有规范的归属 issue，投影栈在这些面上一律保持「只读读模型」身份。

审查清单：如何判定一个后续改动是安全的

一个 #946 后续改动只有在能对以下问题全部回答「是」时才安全（来自 projection-followups.md 的 Review checklist）：

• 该改动能否从同一份源事件切片重建？
• 它是否保留现有源事件 ID，或显式标记 legacy/推断缺口？
• 它是否只暴露有界/脱敏的元数据，而不是原始 prompt、原始 stdout、秘密或无限量的 provider 负载？
• 它是否只改善投影的可检查性，而不改变运行时行为？
• PR 描述是否点名它实现了上文中哪一个后续槽位？

projection-v1-scope.md 的清单补充了更细的约束：是否保持 EventStore/journal 为事实来源、是否能在不写新行的前提下用同一事件切片重建同一投影事实、是纯增量加字段还是需要显式 schema 版本升级与迁移说明、是否意外引入了证据词汇、是否在现在实现了一个本应留在后续视图中的折叠想法、以及是否让 #946 保持「读模型表面」而非 workflow/plugin/HITL/verifier 权威层。

从文档到代码：一张完整的阅读地图

• 队列与边界： docs/agentos/projection-followups.md、docs/agentos/projection-v1-scope.md
• 记录 schema 与枚举： src/ouroboros/harness/projection.py
• 事件→记录构建器： src/ouroboros/harness/projection_builder.py
• 身份与终端语义规范化： src/ouroboros/harness/projection_event_semantics.py
• 安全恢复读模型： src/ouroboros/harness/run_snapshot.py
• MCP 只读查询表面： src/ouroboros/mcp/tools/projection_handlers.py
• CLI JSON 表面（#1064 发货项）： src/ouroboros/cli/commands/status.py
• 确定性测试面： tests/integration/test_mechanical_eval_projection.py、tests/unit/harness/test_projection_builder.py、tests/unit/harness/test_projection_records.py

小结

Ouroboros 的 #946 投影栈是一个刻意保持「窄」的只读读模型：schema 版本化、身份确定、证据可溯、恢复保守。它不抢证据门控、插件审计、HITL 恢复与 Workflow IR 的权限，只做「从已持久化事件中可重建、可检查、可消费」这一件事。对贡献者而言，后续工作认领的正确姿势是：先在上表槽位中找到对应项，再逐条过审查清单，然后在 PR 描述中点名槽位——这既是边界纪律，也是让投影词汇长期保持有用的前提。

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具