367 lines
13 KiB
Markdown
367 lines
13 KiB
Markdown
# EM Planner 多窗口执行与交接设计
|
||
|
||
## 1. 目标
|
||
|
||
将已批准的 28 个 EM Planner 实施任务拆成多个相互独立、可恢复的 Codex 窗口阶段，使每个窗口只需要有限上下文即可安全继续工作。
|
||
|
||
该设计解决以下问题：
|
||
|
||
- 避免单个会话连续执行 28 个任务造成上下文持续膨胀；
|
||
- 避免每个新窗口重新理解完整聊天历史；
|
||
- 保证任务、提交、验证和下一步之间存在可审计的交接链；
|
||
- 保证新窗口不会误改当前工作区中大量既有用户变更；
|
||
- 保证中途关闭、上下文压缩或执行失败后能够从文件和 Git 状态恢复；
|
||
- 保持 Foundation、OSQP、LS、ST、Rolling 五个子系统的边界。
|
||
|
||
## 2. 基本原则
|
||
|
||
### 2.1 阶段大小
|
||
|
||
一个窗口执行一个阶段，一个阶段最多包含三个连续任务。
|
||
|
||
优先保持子系统边界，不为满足“三个任务”而把两个不同子系统强行放入同一个窗口。因此 OSQP 和 LS 的收尾阶段各只有两个任务。
|
||
|
||
### 2.2 信息来源优先级
|
||
|
||
新窗口按以下优先级读取信息：
|
||
|
||
1. 当前 Git 工作区和分支；
|
||
2. `em-planner-progress.md` 中最近一次已提交检查点；
|
||
3. 当前阶段对应的实施计划任务；
|
||
4. EM Planner 总体设计规范；
|
||
5. 最近相关提交；
|
||
6. 旧聊天记录仅作为可选背景，不是继续执行的必要条件。
|
||
|
||
若进度文件与 Git 事实不一致，以 Git 已提交内容和实际验证结果为准，并先修复进度文件再继续。
|
||
|
||
### 2.3 一次只推进一个阶段
|
||
|
||
窗口不得提前实现下一阶段任务。当前阶段通过完整验收、完成检查点提交并生成下一窗口提示词后，当前窗口即结束。
|
||
|
||
### 2.4 任务提交与阶段检查点
|
||
|
||
实施计划中每个任务仍保留独立功能提交。完成该阶段所有任务后，再提交一次只包含进度文件的阶段检查点。
|
||
|
||
提交顺序如下：
|
||
|
||
```text
|
||
Task N 功能/测试提交
|
||
Task N+1 功能/测试提交
|
||
Task N+2 功能/测试提交
|
||
阶段验证
|
||
进度文件检查点提交
|
||
```
|
||
|
||
阶段检查点不得混入生产代码、测试代码、二进制或其他文档修改。
|
||
|
||
## 3. 十个窗口阶段
|
||
|
||
### 阶段 1：Foundation 契约与边界
|
||
|
||
计划：`2026-08-03-em-planner-foundation-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 1 — Verification Host and Immutable Contracts；
|
||
2. Task 2 — Configuration, Diagnostics, and Request Validation；
|
||
3. Task 3 — Direction Segmentation and Exact Boundary Anchors。
|
||
|
||
阶段出口：验证宿主可运行；核心请求/结果/轨迹契约存在；配置和状态验证确定；换向配对与精确边界锚点测试通过。
|
||
|
||
### 阶段 2：Foundation 坐标与走廊
|
||
|
||
计划：`2026-08-03-em-planner-foundation-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 4 — Reverse-Safe Frenet Projection and Reconstruction；
|
||
2. Task 5 — Topology-Preserving Static Corridor；
|
||
3. Task 6 — Foundation Documentation and Gate。
|
||
|
||
阶段出口：前进/倒车投影和重建通过；静态走廊保持既有绕障拓扑；`all-foundation` 验收通过。
|
||
|
||
### 阶段 3：OSQP 契约与原生加载
|
||
|
||
计划：`2026-08-03-em-planner-osqp-backend-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 1 — Solver-Neutral Sparse QP Contracts；
|
||
2. Task 2 — Reproducible OSQP 1.0.0 Native Package；
|
||
3. Task 3 — Absolute-Path Native Loader and ABI Structures。
|
||
|
||
阶段出口：稀疏 QP 契约通过；固定 OSQP 原生包、许可证和哈希存在；绝对路径加载与失败诊断通过。
|
||
|
||
### 阶段 4：OSQP 求解与验收
|
||
|
||
计划：`2026-08-03-em-planner-osqp-backend-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 4 — OSQP Solve Lifecycle and Status Mapping；
|
||
2. Task 5 — Backend Completion Gate。
|
||
|
||
阶段出口：固定可行/不可行 QP 状态正确；重复分配和释放稳定；干净插件目录加载通过。
|
||
|
||
### 阶段 5：LS 模型与几何验证
|
||
|
||
计划：`2026-08-03-em-planner-lateral-ls-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 1 — Variable Layout and Exact Discrete Lateral Dynamics；
|
||
2. Task 2 — Normalized Objective and Linear Hard Constraints；
|
||
3. Task 3 — Nonlinear Geometry Evaluation and Independent Validation。
|
||
|
||
阶段出口：LS 变量布局、离散动力学、代价和硬约束系数测试通过；世界坐标重建和车辆曲率独立验证通过。
|
||
|
||
### 阶段 6：LS SQP 与真实场景
|
||
|
||
计划：`2026-08-03-em-planner-lateral-ls-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 4 — Sequential Convex Outer Loop and Feasible-Candidate Fallback；
|
||
2. Task 5 — Real-OSQP Lateral Scenarios and Gate。
|
||
|
||
阶段出口：SQP 外循环、信赖域和最后可行解回退通过；真实 OSQP 横向场景通过；输出实际 `PathS`。
|
||
|
||
### 阶段 7：ST 模型与纵向优化
|
||
|
||
计划：`2026-08-03-em-planner-longitudinal-st-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 1 — Speed Envelope over Actual PathS；
|
||
2. Task 2 — Time-Knot Layout, Dynamics, Objective, and Hard Constraints；
|
||
3. Task 3 — Longitudinal Outer Loop and Strict Validation。
|
||
|
||
阶段出口：速度包络、停车预检、ST 动力学、代价、约束和纵向外循环通过。
|
||
|
||
### 阶段 8：轨迹发布与单次规划服务
|
||
|
||
计划：`2026-08-03-em-planner-longitudinal-st-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 4 — Complete Trajectory Assembly and Redundant-Field Consistency；
|
||
2. Task 5 — Independent World-Space Publication Validator；
|
||
3. Task 6 — Pure One-Shot EmPlanningService。
|
||
|
||
阶段出口：完整轨迹字段一致；世界坐标发布验证通过；纯单次规划流水线和状态覆盖通过。
|
||
|
||
### 阶段 9：滚动协调与换向执行
|
||
|
||
计划：`2026-08-03-em-planner-rolling-execution-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 1 — Cycle Identity, Scheduling Decision, and Stale-Result Suppression；
|
||
2. Task 2 — Safe Previous-Trajectory Handoff；
|
||
3. Task 3 — Gear-Switch State Machine and Trajectory Executor。
|
||
|
||
阶段出口：最新版本发布、旧结果淘汰、安全拼接、零速换向状态机通过。
|
||
|
||
### 阶段 10：控制适配、插件发布与总验收
|
||
|
||
计划：`2026-08-03-em-planner-rolling-execution-implementation.md`
|
||
|
||
包含：
|
||
|
||
1. Task 4 — Generic Control Adapter；
|
||
2. Task 5 — Plugin Output and License Packaging；
|
||
3. Task 6 — Rolling End-to-End and Final Gate。
|
||
|
||
阶段出口：通用控制命令通过；`ClumsyPilot.dll`、`osqp.dll` 和许可证目录打包通过；第一版 EM Planner 全链路验收通过。
|
||
|
||
## 4. 进度文件设计
|
||
|
||
实施时创建：
|
||
|
||
```text
|
||
docs/superpowers/progress/em-planner-progress.md
|
||
```
|
||
|
||
它是跨窗口唯一的人工可读运行状态文件，包含以下固定章节：
|
||
|
||
````markdown
|
||
# EM Planner Execution Progress
|
||
|
||
## Current State
|
||
- Current stage:
|
||
- Stage status:
|
||
- Current branch:
|
||
- Last checkpoint commit:
|
||
|
||
## Completed Tasks
|
||
| Stage | Plan | Tasks | Commits | Verification |
|
||
|
||
## Current Verification
|
||
- Commands:
|
||
- Result:
|
||
- Verified commit:
|
||
|
||
## Preserved Workspace State
|
||
- Existing unrelated changes remain untouched.
|
||
- Known baseline build issue:
|
||
|
||
## Decisions Needed
|
||
- None, or an exact blocking decision.
|
||
|
||
## Next Stage
|
||
- Stage:
|
||
- Plan:
|
||
- Tasks:
|
||
- Entry checks:
|
||
- Exit gate:
|
||
|
||
## Next-Window Prompt
|
||
```text
|
||
可直接复制的完整提示词
|
||
```
|
||
````
|
||
|
||
状态仅允许：
|
||
|
||
```text
|
||
NotStarted
|
||
InProgress
|
||
Blocked
|
||
Completed
|
||
```
|
||
|
||
只有阶段出口验证真实通过后，才能写入 `Completed`。
|
||
|
||
## 5. 新窗口启动协议
|
||
|
||
每个窗口开始时必须依次执行：
|
||
|
||
1. 确认当前工作目录和分支；
|
||
2. 读取总体设计规范；
|
||
3. 读取本多窗口执行规范；
|
||
4. 读取进度文件；
|
||
5. 读取当前阶段对应计划中的指定任务；
|
||
6. 检查 `git status --short`，不得把既有无关修改当成本阶段修改；
|
||
7. 检查进度文件记录的最后提交是否存在；
|
||
8. 运行进度文件列出的阶段入口验证；
|
||
9. 若入口验证与记录不一致，停止实施，先诊断并修正交接状态；
|
||
10. 使用当前阶段计划开始 TDD 实施。
|
||
|
||
新窗口不需要读取 28 个任务的全部计划，只读取当前阶段对应计划和必要的前置接口文件。
|
||
|
||
## 6. 窗口结束协议
|
||
|
||
阶段结束前必须依次执行：
|
||
|
||
1. 确认该阶段每个任务都有独立提交；
|
||
2. 确认每个提交只包含计划指定文件；
|
||
3. 运行阶段出口验证；
|
||
4. 运行 `git diff --check`；
|
||
5. 记录实际测试命令、退出码和关键输出；
|
||
6. 检查暂存区为空；
|
||
7. 更新进度文件中的已完成任务、提交和验证证据；
|
||
8. 填写下一阶段入口检查、任务和出口门槛；
|
||
9. 生成下一窗口提示词；
|
||
10. 单独提交进度文件；
|
||
11. 再次确认用户原有工作区修改仍被保留；
|
||
12. 向用户返回本阶段摘要和下一窗口提示词。
|
||
|
||
任何测试未通过时，不得把阶段标记为完成，也不得生成声称前置条件已满足的下一窗口提示词。
|
||
|
||
## 7. 下一窗口提示词模板
|
||
|
||
阶段结束时按实际阶段号、提交号和验证命令填充以下模板：
|
||
|
||
```text
|
||
请继续 ParkingRobot 仓库的 EM Planner 多窗口实施。
|
||
|
||
工作目录：D:\Users\Desktop\项目\prakrobot\ParkingRobot
|
||
|
||
必须先完整读取：
|
||
1. docs/superpowers/specs/2026-08-03-em-planner-ls-st-design.md
|
||
2. docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md
|
||
3. docs/superpowers/progress/em-planner-progress.md
|
||
4. <当前阶段对应计划路径>
|
||
|
||
本窗口只执行阶段 <N>：<阶段名称>。
|
||
只执行计划中的 Task <范围>，不得提前执行下一阶段。
|
||
|
||
开始前：
|
||
- 检查当前分支、git status 和进度文件记录的最近检查点提交；
|
||
- 运行进度文件中的阶段入口验证；
|
||
- 保留所有既有无关工作区修改，不得清理、覆盖或顺带提交；
|
||
- 若进度与 Git 或验证结果不一致，先诊断并报告，不要直接实施。
|
||
|
||
执行要求：
|
||
- 按对应实施计划逐任务使用 TDD；
|
||
- 每个任务只提交计划指定文件并形成独立提交；
|
||
- 不使用子代理；
|
||
- 不实现当前阶段范围外功能；
|
||
- 不处理已明确延期的动态障碍预测和动态绕障决策；
|
||
- 生产代码不得依赖 UI、硬件对象或当前工作目录；
|
||
- 任何完成声明前运行计划指定验证。
|
||
|
||
阶段结束时：
|
||
- 运行完整阶段出口验证和 git diff --check；
|
||
- 更新并单独提交 docs/superpowers/progress/em-planner-progress.md；
|
||
- 返回完成任务、提交、测试证据、遗留问题；
|
||
- 给出阶段 <N+1> 可直接复制的新窗口提示词。
|
||
```
|
||
|
||
阶段 10 完成时，最后一项改为输出全链路验收结果，不再生成下一实施窗口提示词。
|
||
|
||
## 8. 工作区保护
|
||
|
||
当前仓库已有大量与 EM Planner 无关或作为前置工作的未提交修改。每个窗口必须：
|
||
|
||
- 在开始和结束时保存 `git status --short` 结果用于范围对照；
|
||
- 使用显式文件路径暂存，不使用 `git add .` 或 `git add -A`；
|
||
- 不使用 `git reset --hard`、`git checkout --` 或清理未跟踪文件；
|
||
- 不修改计划范围外的 Map、CoarsePath、PathSmoothing 和旧 `auto_avoidance` 文件；
|
||
- 修改已有脏文件 `ClumsyPilot.csproj` 前先查看差异，只追加计划要求的最小变更；
|
||
- 每次提交后用 `git diff-tree` 核对提交文件集合；
|
||
- 发现与本阶段文件重叠的未知用户修改时停止并请求确认。
|
||
|
||
已知主项目构建可能被旧 `auto_avoidance/MultiWheelAutoAvoidance.cs` 缺少 `NetTopologySuite` 和 `OpenCvSharp` 引用阻断。各阶段必须运行隔离的 EM 验证宿主；不得通过擅自删除旧功能来使主项目构建通过，也不得把该既有错误声明为 EM 回归。
|
||
|
||
## 9. 失败与恢复
|
||
|
||
### 9.1 任务中途失败
|
||
|
||
保留已提交的前置任务。未完成任务不得提交半成品；若工作区已有该任务的未提交修改，在进度文件中记录准确文件和失败命令，阶段状态写为 `Blocked` 或 `InProgress`，不得写为 `Completed`。
|
||
|
||
### 9.2 窗口意外关闭
|
||
|
||
新窗口通过以下顺序恢复：
|
||
|
||
```text
|
||
git status
|
||
git log 最近相关提交
|
||
进度文件最近检查点
|
||
对应计划中第一个未完成任务
|
||
该任务的失败/通过验证
|
||
```
|
||
|
||
如果功能提交存在但进度文件未更新，以提交和测试为依据补写检查点；不得重复实现已经完成的任务。
|
||
|
||
### 9.3 验证记录过期
|
||
|
||
若进度文件记录的 `Verified commit` 不是当前相关 HEAD，新窗口必须重新运行入口验证。不得复用其他提交上的通过结果。
|
||
|
||
### 9.4 外部依赖缺失
|
||
|
||
OSQP 构建工具、原生 DLL 或许可证无法获得时，仅阻塞 OSQP 对应阶段。记录实际缺失项和命令输出；不得用假 DLL、空文件或跳过验证继续 LS/ST 集成。
|
||
|
||
## 10. 成功标准
|
||
|
||
多窗口执行协议满足以下条件时视为设计落地：
|
||
|
||
1. 28 个任务被完整且无重复地映射到 10 个阶段；
|
||
2. 每阶段最多三个任务且不跨子系统边界；
|
||
3. 任意新窗口无需旧聊天记录即可定位当前任务；
|
||
4. 每个已完成阶段都有功能提交、阶段验证证据和进度检查点提交；
|
||
5. 任何失败都能明确定位到任务、文件、命令和提交；
|
||
6. 用户既有工作区修改不会被暂存、提交、清理或覆盖；
|
||
7. 阶段 1 至阶段 9 均产生可直接复制的下一窗口提示词；
|
||
8. 阶段 10 产生完整的第一版 EM Planner 验收报告。
|