docs: design staged EM visualization execution

2026-08-06 08:42:11 +08:00
parent 29cf22d695
commit b0b79e5d78
1 changed files with 172 additions and 0 deletions
@@ -0,0 +1,172 @@
 # EM 观察网页可视化跨窗口阶段执行设计
 ## 1. 目标
 将已经批准的 EM 轨迹闭环观察与独立网页可视化工作拆成八个可在不同 Codex 窗口中执行的中等规模阶段。每个阶段必须具备独立目标、明确依赖、受控文件范围、完整验证和文件化交接，使新智能体不依赖上一窗口的会话上下文，也不会因重复读取整个仓库而造成上下文膨胀。
 本设计不改变功能范围，不替代原设计和两份详细实施计划，也不授权任何实车控制。它只定义如何安全地分阶段执行、验证和交接。
 ## 2. 权威资料与优先级
 阶段智能体按照以下优先级解释需求：
 1. 用户在当前阶段提示词中的新增明确要求。
 2. `docs/superpowers/specs/2026-08-05-em-observation-web-visualization-design.md` 的产品和架构约束。
 3. 当前阶段对应的原实施计划任务：
   - `docs/superpowers/plans/2026-08-05-trajectory-planning-visualization-library.md`
   - `docs/superpowers/plans/2026-08-05-em-observation-web-integration.md`
 4. 本阶段执行手册中的窗口边界、启动检查、交接规则和完成标准。
 5. 上一阶段交接文件记录的事实、验证结果和已知问题。
 上一阶段交接文件不是代码正确性的替代证据。新智能体必须核查提交、接口和至少一组阶段入口测试，不能只复述交接结论。
 ## 3. 阶段切分
 | 阶段 | 名称 | 原计划范围 | 独立阶段产物 |
 | --- | --- | --- | --- |
 | 1 | 可视化类库基础 | 类库 Task 1–2 | 独立项目、不可变契约、容量一帧交换、有界历史和稳定 JSON |
 | 2 | Loopback HTTP/SSE | 类库 Task 3 | 受限 HTTP/1.1 GET/SSE 服务、Token 鉴权、公开会话生命周期 |
 | 3 | 中文科研网页与类库收口 | 类库 Task 4–5 | 嵌入式 Canvas/SVG 页面、中文状态、类库文档和完整独立验证 |
 | 4 | 观察参数与换向状态机 | 集成 Task 1–2 | 冻结参数、网页/Painter 开关、纯顺序方向段确认器 |
 | 5 | 多段滚动规划控制器 | 集成 Task 3 | 活动方向段控制器、协调器切换和无执行器的多段观察循环 |
 | 6 | EM 数据可视化适配 | 集成 Task 4–5 | 静态地图/配置、LS/ST/运动学图、滚动语义和周期交接指标 |
 | 7 | MovementTest 托管与发布 | 集成 Task 6–7 | 网页生命周期、Painter 懒加载、故障隔离、插件 DLL 和操作文档 |
 | 8 | 全量验收 | 集成 Task 8 | 自动化证据、网页冒烟结果和实车观察清单状态 |
 阶段必须严格顺序执行。后续阶段不得在前一阶段验证未通过或交接状态为阻塞时启动。
 ## 4. 单窗口上下文预算
 每个阶段提示词只要求完整阅读以下内容：
 - 本设计；
 - 功能设计的全局约束与当前阶段相关章节；
 - 对应原实施计划的全局约束、文件结构和当前阶段任务；
 - 上一阶段交接文件；
 - 当前阶段列出的源码、测试和项目文件；
 - 提示词明确点名的技能说明。
 不得为了“熟悉项目”递归读取整个仓库、所有历史计划或全部 Git diff。发现符号依赖时先使用 `rg` 定位，再只读取直接相关文件。新窗口通过磁盘资料、Git 提交和测试恢复事实，不通过粘贴上一窗口的长篇推理恢复上下文。
 ## 5. 阶段启动协议
 每个阶段提示词都必须包含下列启动动作：
 1. 确认工作目录为仓库根目录，并读取适用的 `AGENTS.md`。
 2. 读取当前分支、`HEAD` 和最近阶段提交，不假设提示词生成时的哈希仍是当前 `HEAD`。
 3. 读取上一阶段交接文件，并核对其中列出的实现提交确实可达。
 4. 统计整个工作区改动数量，但只展开当前阶段文件范围内的状态和 diff，避免把大量无关变更加载进上下文。
 5. 检查暂存区。不得重置、覆盖、清理或提交用户及其他任务的改动。
 6. 如果当前阶段文件存在无法安全合并的既有修改，停止实现并报告精确冲突；无关脏文件不能作为停止理由。
 7. 运行提示词规定的阶段入口验证，建立可复现基线。
 阶段提示词禁止派生子智能体。一个窗口只由一个主智能体执行当前阶段，阶段结束后由用户复制下一提示词并显式开启新窗口。
 ## 6. 阶段实施协议
 阶段实现必须遵循当前原计划任务中的 TDD 顺序：先写聚焦失败检查，确认失败原因正确，再实现最小功能，最后运行聚焦测试和规定回归。遇到非预期失败时使用系统化调试，不得通过删除断言、扩大容差或跳过测试制造绿色结果。
 每个阶段只允许修改该阶段清单中的文件，以及为了修复由本阶段直接引入的编译错误而经解释后增加的最小依赖文件。任何新增文件范围都必须写入交接记录。阶段内保留原实施计划规定的细粒度提交，不把两个可独立回滚的原任务压成一个大提交。
 观察任务始终保持 `OBSERVE_ONLY`。阶段智能体不得调用或新增底盘、转向、制动、电机、档位或控制器写接口，也不得为测试绕过这一源代码审计。
 ## 7. Git 与提交边界
 仓库可能长期存在大量与本功能无关的修改。阶段智能体必须：
 - 使用精确路径检查、暂存和提交；
 - 保留所有无关修改，不执行 `git reset --hard`、`git checkout --`、清理命令或批量恢复；
 - 在提交前检查 `git diff --cached --name-status`；
 - 若暂存区已有无关内容，使用只包含当前阶段精确路径的提交方式，不能把无关内容带入阶段提交；
 - 提交后使用 `git diff-tree --no-commit-id --name-status -r <commit>` 核对实际文件；
 - 不创建空提交，不重写其他人的提交历史。
 阶段交接记录使用单独的文档提交，提交信息为 `docs: record EM visualization phase NN handoff`。记录中列出实现提交，不要求预先写入交接文档自身尚未生成的提交哈希。
 ## 8. 交接文件
 每阶段结束时创建：
 ```text
 docs/superpowers/handoffs/em-observation-web/phase-NN.md
 ```
 交接文件必须包含以下固定字段：
 ```markdown
 # EM 观察网页可视化阶段 NN 交接
 状态：完成 | 阻塞 | 自动验收完成但实车待验
 阶段目标：
 基线提交：
 实现提交：
 修改文件：
 新增或确认的接口：
 验证命令与结果：
 未运行的验证及原因：
 已知警告或遗留问题：
 与原计划的偏差：
 下一阶段注意事项：
 ```
 不得把“未运行”写成“通过”。命令失败时记录退出码和首个有效失败原因。只有当前阶段规定的自动验证全部通过，才能把状态写为“完成”并输出下一阶段提示词。
 若阶段阻塞，交接记录状态为“阻塞”，最终回答输出同阶段恢复提示词，而不是下一阶段提示词。恢复提示词必须携带阻塞事实、失败命令、相关文件和允许继续的范围。
 ## 9. 下一阶段提示词协议
 阶段执行手册为每个阶段预先提供一份完整中文启动提示词。提示词不能只写“继续上一阶段”，必须独立包含：
 - 仓库绝对路径和当前阶段编号；
 - 阶段目标、原计划任务映射和禁止扩展范围；
 - 必读设计、计划、交接、源码和测试文件；
 - 所需技能及其使用顺序；
 - Git/脏工作区保护规则；
 - TDD 实施顺序；
 - 精确验证命令和完成标准；
 - 交接文件路径与固定字段；
 - 最终回答中输出下一提示词或恢复提示词的要求。
 阶段完成后，智能体必须在最终回答的最后提供一个单独 Markdown 代码块，逐字输出执行手册中的下一阶段提示词。代码块外先总结本阶段结果、提交和验证；代码块内不得使用省略号、占位符或依赖已折叠的会话内容。
 阶段 8 有两种结束方式：
 - 自动与实车验收均完成：报告整体完成，不再输出下一阶段提示词。
 - 自动验收完成但当前没有实车条件：交接状态写为“自动验收完成但实车待验”，不得声称整体完成，并输出完整的“阶段 8 实车续验提示词”。
 ## 10. 阶段验证边界
 | 阶段 | 最低退出验证 |
 | --- | --- |
 | 1 | 独立可视化验证宿主通过；主项目无重复编译类型 |
 | 2 | 真实 Loopback socket、鉴权、慢客户端、端口释放检查通过 |
 | 3 | 嵌入资源、中文内容、Canvas/SVG、非仓库工作目录和独立构建通过 |
 | 4 | 设置冻结与方向段状态机检查通过；无执行器调用 |
 | 5 | 观察、协调器和执行器回归通过；跨方向不复用旧轨迹 |
 | 6 | 静态/动态适配检查及 EM 核心回归通过；jerk 为 `N-1` |
 | 7 | 生命周期隔离、源审计和插件包树检查通过 |
 | 8 | 两个验证宿主、`em-all`、主项目构建、网页冒烟和明确的实车状态完成 |
 完成前必须使用 `verification-before-completion` 所规定的证据优先流程。阶段最终回答只能声称刚刚运行且得到成功退出码的验证通过。
 ## 11. 阶段执行手册产物
 获批后新增一份执行手册：
 ```text
 docs/superpowers/plans/2026-08-06-em-observation-web-staged-execution.md
 ```
 手册包含八个阶段的文件边界、入口/退出检查、交接模板应用方式，以及八份可直接复制的主提示词和一份条件性的阶段 8 实车续验提示词。手册引用原计划的具体任务，不复制所有实现代码，以原计划继续作为代码级权威来源。
 ## 12. 完成标准
 阶段化设计完成需满足：
 - 八个阶段覆盖原两份计划的全部十三个任务，且无重复所有权或遗漏；
 - 每阶段的输入、输出、测试和 Git 边界明确；
 - 新窗口无需访问上一窗口聊天记录即可启动；
 - 阻塞不会错误推进到下一阶段；
 - 实车不可用不会被伪装为整体通过；
 - 所有下一阶段提示词均可直接复制，不含占位符；
 - 阶段执行机制不改变原功能设计和 `OBSERVE_ONLY` 安全边界。