diff --git a/docs/superpowers/specs/2026-08-06-em-full-direction-segment-staged-execution-design.md b/docs/superpowers/specs/2026-08-06-em-full-direction-segment-staged-execution-design.md new file mode 100644 index 0000000..0190691 --- /dev/null +++ b/docs/superpowers/specs/2026-08-06-em-full-direction-segment-staged-execution-design.md @@ -0,0 +1,181 @@ +# EM 完整方向段规划与可视化修复阶段执行设计 + +**日期:** 2026-08-06 + +**状态:** 已批准阶段划分 + +**适用仓库:** `D:\Users\Desktop\项目\prakrobot\ParkingRobot` + +## 1. 目的 + +现有设计和总实施计划覆盖规划器、MovementTest、Web、Native Painter、文档和实车验收,若在一个长窗口中连续实现,容易累积过多上下文、混淆旧证据与新证据,并增加无关修改被误带入提交的风险。 + +本设计把已批准的 11 个实施任务重新组织为 9 个可独立交接的阶段。每个阶段由一个新窗口中的智能体执行;阶段完成后必须留下可审计交接,并生成下一阶段可直接复制的新提示词。阶段协议只切分执行,不改变功能设计、测试标准或安全边界。 + +## 2. 权威资料与职责 + +以下文档保持各自职责,不互相复制或替代: + +- 功能设计:`docs/superpowers/specs/2026-08-06-em-full-direction-segment-visualization-repair-design.md`。 +- 总实施计划:`docs/superpowers/plans/2026-08-06-em-full-direction-segment-visualization-repair.md`。 +- 本阶段执行设计:定义跨窗口边界、交接格式、阻塞行为和提示词协议。 +- 后续阶段执行计划:逐阶段列出需要阅读的总计划任务、允许修改范围、验证命令、提交和提示词正文。 +- 阶段交接:`docs/superpowers/handoffs/em-full-direction-visualization/phase-XX.md`。 + +功能设计是需求权威;总实施计划是 TDD 步骤和接口权威;阶段执行计划只负责安排顺序。若三者出现不一致,新窗口必须停止扩展实现,记录矛盾并请求用户决定,不得自行重新设计。 + +## 3. 阶段划分 + +| 阶段 | 对应总计划 | 核心结果 | 阶段退出门禁 | +| --- | --- | --- | --- | +| 1 | Task 1–2 | 显式规划范围、配置、状态码、完整方向段选择 | 契约、默认值、复制、请求验证、滚动兼容和完整段选择测试通过 | +| 2 | Task 3 | 从 Local G2 `s_end` 和速度/停车包络导出自适应优化结点与 `T_end` | 时间结点、资源上限、滚动兼容和发布采样独立性测试通过 | +| 3 | Task 4–5 | 静止起步、零进度拒绝、终点 3 cm/5° 位姿和发布样本门禁 | 原始全零症状变红后修复;终点、yaw wrap、样本数和 jerk 测试通过 | +| 4 | Task 6 | MovementTest 每个方向段只规划一次,换向后才规划下一段 | 一次规划、观察持续、停车保持与三个带符号速度样本测试通过;无执行器调用 | +| 5 | Task 7 | 统一快照、路径图层、曲线单位、`s_end`、车辆与换向语义 | C# 快照和可视化契约宿主通过;完整段不重复发布 current horizon | +| 6 | Task 8 | 真实 DOM/SVG 测试、分页、空白总览、双轴刻度和论文风格图层修复 | jsdom 与 .NET 可视化宿主通过;原网页结构不重做 | +| 7 | Task 9 | 每张图独立框选、滚轮、重置和全屏观察 | 交互 DOM 测试证明视域变化且原始快照不变 | +| 8 | Task 10 | Native Painter 坐标、比例、LS/ST 和标记语义修正 | Painter 几何/源审计与观察宿主通过;不出现大黑三角 | +| 9 | Task 11 | 文档、全量自动化、本地烟雾和受监督实车验收 | 自动证据新鲜;实车安全执行后通过,或明确保持“实车待验/阻塞” | + +每阶段最多实现表中列出的总计划任务。不得为了“顺手完成”提前修改下一阶段文件,除非当前阶段编译所需的最小签名传播已经在总计划中明确列出。 + +## 4. 阶段 9 的双检查点 + +阶段 9 允许使用两个新窗口,但仍属于同一验收阶段: + +1. **阶段 9 自动验收窗口:** 更新 README,运行全量自动验证和确定性本地网页烟雾,创建 `phase-09.md`。若没有可确认的有人监督安全环境,将状态写为“自动验收完成但实车待验”,并输出阶段 9 实车续验提示词。 +2. **阶段 9 实车续验窗口:** 只核查自动证据是否仍可沿用,并在受监督安全环境执行实车清单。通过或阻塞后创建 `phase-09-vehicle.md`。 + +自动验收不替代实车观察。任何实车项无法安全执行都必须记录为未完成,不得声称整体完成。不得通过操作真实底盘帮助只读观察条件成立。 + +## 5. 每个阶段的启动协议 + +新窗口首先执行以下只读动作: + +1. 记录当前分支、HEAD 和最近提交。 +2. 验证上一阶段交接声明的实现提交和交接提交均为当前 HEAD 的祖先。 +3. 完整阅读功能设计、本阶段执行计划中的当前阶段、总实施计划中映射的 Task,以及上一阶段交接。 +4. 读取提示词要求的技能文件;实现阶段必须使用 test-driven-development,出现测试失败或意外行为时使用 systematic-debugging,完成声明和提交前使用 verification-before-completion。 +5. 检查 `git status --short` 和 `git diff --cached --name-only`,记录既有脏工作区与暂存区。 +6. 对准备修改且已经脏的文件,先保存其精确 diff 证据,并逐 hunk 保留用户修改。 +7. 如果上一阶段后相关代码发生变化,先重跑受影响的上一阶段验证,不能直接沿用旧证据。 + +新窗口不得重新 brainstorming、重新选择架构、扩展功能或派生子智能体。若权威资料存在真实矛盾,停止实现并写阻塞交接。 + +## 6. 阶段内执行协议 + +每阶段严格遵循总实施计划的 RED → GREEN → 回归验证顺序: + +1. 先添加当前阶段指定的失败测试。 +2. 运行精确命令,确认失败原因就是目标缺失或已知回归。 +3. 实现使该测试通过的最小改动。 +4. 运行当前阶段聚焦验证。 +5. 运行被修改共享接口影响的既有回归验证。 +6. 执行源审计、`git diff --check` 和显式暂存范围核查。 +7. 使用精确路径暂存并提交;不得使用 `git add .`、`git add -A` 或宽泛 glob。 + +如果 RED 因环境、既有脏修改、依赖缺失或无关故障而失败,必须先用 systematic-debugging 确定首个有效原因。没有有效 RED 证据时不得写实现。 + +## 7. 提交协议 + +一个阶段可以包含总实施计划要求的多个小型实现提交,但必须满足: + +- 每个实现提交只包含当前阶段允许范围内的文件。 +- 提交信息沿用总实施计划给出的信息。 +- 共享脏文件只暂存本阶段 hunk;用户无关 hunk保持未暂存。 +- 当前阶段最后一个实现提交通过验证后,再创建阶段交接文件。 +- 阶段交接文件单独提交,信息格式为 `docs: record EM full-direction phase XX handoff`。 + +交接提交不得夹带实现、测试、构建产物、截图、日志或用户脏文件。日志与截图只在交接中记录路径。 + +## 8. 阶段交接格式 + +每个 `phase-XX.md` 必须包含: + +- 状态:`完成` 或 `阻塞`;阶段 9 自动窗口可使用 `自动验收完成但实车待验`。 +- 阶段目标和明确非目标。 +- 启动分支、启动 HEAD、上一阶段交接提交。 +- 本阶段实现提交;交接提交的真实哈希由提交后的最终回答记录。 +- 修改文件列表。 +- 新增或改变的接口与精确语义。 +- RED 命令、首个有效失败和失败原因。 +- GREEN/回归命令、退出码、PASS 数量或关键输出。 +- 源审计、无硬件写输出和清理证据。 +- 保留的脏工作区/暂存内容。 +- 未运行验证及原因。 +- 已知警告和偏差。 +- 下一阶段允许范围。 +- 下一阶段所需的事实输入、允许范围和验证要求。 + +交接里的验证必须是本阶段新鲜证据。只引用更早阶段证据时,要明确说明可达提交和为什么代码未受影响。 + +## 9. 阻塞协议 + +出现以下任一情况,阶段状态写为“阻塞”,不得推进到下一阶段: + +- 当前阶段的首个有效回归未能在允许范围内修复。 +- 需要修改下一阶段或无关系统才能继续。 +- 权威设计和总计划发生真实矛盾。 +- 既有用户脏修改与目标 hunk 无法安全合并。 +- 必需环境或依赖不可用,且没有等价的安全验证。 +- 实车条件不受监督或不安全。 + +阻塞交接必须记录首个有效失败、最小复现、当前安全影响、已排除原因、允许恢复的精确文件/命令范围,并生成“同阶段恢复提示词”,而不是下一阶段提示词。 + +恢复窗口只处理交接记录的首个有效失败。恢复成功后补全原阶段交接,再生成下一阶段提示词。 + +## 10. 下一阶段提示词协议 + +每个阶段在交接文件提交完成后,最终回答必须包含一份可直接复制的完整提示词。交接文件负责保存生成该提示词所需的全部事实,但不写入尚未产生的自身提交哈希。最终回答中的提示词必须使用已创建的真实交接提交哈希,且不得依赖上一窗口聊天内容。提示词至少包含: + +1. 当前任务是阶段几、目标和对应总计划 Task。 +2. 仓库绝对路径、预期分支和上一阶段实现/交接提交。 +3. 必读设计、总计划具体 Task、阶段执行计划具体节和上一阶段交接路径。 +4. 必须读取的技能及触发条件。 +5. 启动时的分支、HEAD、祖先、提交可达性、脏工作区和相关变化核查。 +6. 本阶段允许创建/修改的精确文件范围。 +7. 本阶段禁止事项,包括不提前实现下一阶段、不扩展功能、不派生子智能体。 +8. 必须执行的 RED、GREEN、回归、构建、源审计和清理命令。 +9. 阶段成功的精确退出门禁。 +10. 交接文件路径、单独提交信息和最终回答格式。 +11. 阻塞时的记录要求和恢复提示词要求。 + +提示词必须把上一阶段产生的真实提交哈希、验证事实、警告和未完成项填入正文,不能保留未解析的哈希变量、未决事项或依赖聊天上文的描述。 + +## 11. 最终回答协议 + +阶段完成时,最终回答按以下顺序给出: + +1. 阶段状态和完成的功能边界。 +2. 新鲜 RED/GREEN/回归证据。 +3. 实现提交和交接提交。 +4. 保留的脏工作区、未运行项和警告。 +5. 一个独立代码块中的下一阶段完整提示词。 + +阻塞时先给出真实失败和安全影响,再给同阶段恢复提示词。不得在阻塞状态下输出下一阶段提示词。 + +阶段 9 实车全部通过后,`phase-09-vehicle.md` 必须使用总实施计划规定的独立提交信息 `docs: record EM visualization vehicle acceptance`。最终回答列出新鲜实车证据和该提交,明确整体完成,不再输出后续提示词。 + +## 12. 第一阶段启动输入 + +在阶段执行计划获得批准并提交后,当前窗口负责生成阶段 1 的完整提示词。阶段 1 提示词至少要求阅读: + +- 本设计全文; +- 功能设计第 1–6、9–12 节; +- 总实施计划 Task 1–2; +- 阶段执行计划阶段 1; +- 当前阶段前置基线说明。 + +阶段 1 只允许实现显式规划范围、配置/复制/校验、状态码、元数据和完整方向段选择;不得开始自适应时间结点、静止起步修复、MovementTest 或任何可视化修改。 + +## 13. 完成标准 + +阶段执行体系只在以下条件全部满足时视为建立完成: + +- 9 个阶段都具有明确输入、输出、允许范围和退出门禁。 +- 每阶段都能由不了解聊天历史的新窗口仅凭仓库文档启动。 +- 完成阶段会生成下一阶段完整提示词;阻塞阶段会生成同阶段恢复提示词。 +- 提交与交接分离,并保护所有无关脏工作区和暂存内容。 +- 自动验收与实车验收被明确分开,实车安全条件不可被自动证据替代。 +- 阶段 1 的首个可复制提示词包含真实基线提交且没有未解析变量。