214 lines
10 KiB
Markdown
214 lines
10 KiB
Markdown
# EM 纵向滚动规划四阶段执行路线图
|
||
|
||
日期：2026-08-05
|
||
|
||
## 目标
|
||
|
||
把原有的 10 个实现任务拆成 4 个可以在不同 Codex 窗口中依次完成的阶段。每个阶段必须独立验证、记录实际结果，并根据真实代码状态生成下一阶段的精细提示词。
|
||
|
||
本路线图只负责阶段划分和跨窗口交接。技术设计与逐步实现细节仍以下列文件为准：
|
||
|
||
- 设计规格：`docs/superpowers/specs/2026-08-05-em-longitudinal-rolling-planning-design.md`
|
||
- 十任务实施计划：`docs/superpowers/plans/2026-08-05-em-longitudinal-rolling-planning.md`
|
||
|
||
如三份文档发生冲突，设计规格决定行为语义，十任务实施计划决定具体实现步骤，本路线图决定阶段边界和停止位置。
|
||
|
||
## 不可破坏的全局约束
|
||
|
||
- `DistanceHorizonMeters` 是 LS 空间前视范围，不是车辆在一个 ST 周期内必须走完的距离。
|
||
- `TimeHorizonSeconds` 是单次 ST 优化覆盖的未来时间，不是观察循环周期。
|
||
- 只有真实 `Goal` 或 `GearSwitchApproach` 边界允许触发精确停车。
|
||
- `RollingContinuation` 和 `ApproachStopBoundary` 不得被强制设置末速度为零。
|
||
- `ExactStopAtBoundary` 必须在 QP 时间范围结束前达到 `S=S_end、U=0、A=0`，并在 QP 内至少保留一个完整 `OutputTimeStepSeconds` 的静止稳定区间。
|
||
- 不通过放宽速度、加速度、jerk、QP 残差或轨迹发布验证阈值掩盖逻辑错误。
|
||
- `OBSERVE_ONLY` 必须保持不变。本路线图不授权增加底盘命令、轨迹跟踪器或超时看门狗。
|
||
- 工作树内已有且与本任务无关的修改全部视为用户资产。禁止清理、回退或提交这些修改。
|
||
- 每次只实施当前阶段；完成交接文件后立即停止，不得提前执行下一阶段。
|
||
|
||
## 阶段总览
|
||
|
||
| 阶段 | 原计划任务 | 核心结果 | 阶段验收 |
|
||
|---|---:|---|---|
|
||
| 1. 纵向基础与窗口语义 | 1–2 | jerk 受限停车数学、三种纵向模式、空间窗口与真实停车边界分离、输入与配置验证 | `foundation`、`longitudinal-model` |
|
||
| 2. ST 优化核心 | 3–5 | 模式化速度包络、条件化 QP 终端约束、独立解验证、按模式生成初始解 | `longitudinal-model`、`longitudinal-integration` |
|
||
| 3. 发布与跨周期连续性 | 6–7 | 条件化轨迹采样、停车锚点和稳定尾段、发布验证、上一周期轨迹软参考 | `trajectory`、`em-planning-service`、`coordinator`、`executor` |
|
||
| 4. 端到端集成与诊断 | 8–10 | 模式流转、多周期 Goal/GearSwitch 回归、MovementTest 诊断、全量回归和目标机 OSQP 验证 | `em-core-all`、观察测试、构建、目标机探针 |
|
||
|
||
## 阶段一：纵向基础与窗口语义
|
||
|
||
对应十任务计划中的 Task 1 和 Task 2。
|
||
|
||
### 实施范围
|
||
|
||
- 新建完整 jerk 受限停车数学，统一停车距离、停车时间、末速度和末加速度语义。
|
||
- 新建 `EmLongitudinalMode`：
|
||
- `RollingContinuation`
|
||
- `ApproachStopBoundary`
|
||
- `ExactStopAtBoundary`
|
||
- 新建 `LongitudinalTerminalSchedule`，计算精确停车稳定尾段的起始 knot。
|
||
- 让 `PlanningHorizonSelector` 分离：
|
||
- LS 空间窗口末端；
|
||
- 真实 Goal/GearSwitch 停车边界；
|
||
- 当前纵向模式。
|
||
- 扩展 `LongitudinalPlanningInput` 和请求验证，拒绝不一致的模式、边界和稳定时间配置。
|
||
|
||
### 允许修改的主要文件
|
||
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Contracts/EmLongitudinalMode.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/JerkLimitedStoppingMath.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/LongitudinalTerminalSchedule.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/PathSpeedLimitBuilder.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Segmentation/PlanningHorizonSelector.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/LongitudinalPlanningInput.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Validation/EmPlanningRequestValidator.cs`
|
||
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Facade/EmPlanningService.cs`
|
||
- `ClumsyPilot/tests/EMPlannerVerificationHost/LongitudinalModelChecks.cs`
|
||
- `ClumsyPilot/tests/EMPlannerVerificationHost/FoundationChecks.cs`
|
||
|
||
若编译修复必须触及直接调用者，可以进行最小兼容修改，但必须在阶段交接中逐项解释。
|
||
|
||
### 完成条件
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- foundation
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-model
|
||
```
|
||
|
||
两项均须输出 `PASS`。阶段内按原十任务计划保留 Task 1、Task 2 两个独立提交。
|
||
|
||
## 阶段二：ST 优化核心
|
||
|
||
对应十任务计划中的 Task 3、Task 4 和 Task 5。
|
||
|
||
### 实施范围
|
||
|
||
- 按纵向模式构造 PathS 速度包络。
|
||
- Rolling 模式的局部路径末端不再出现人为零速边界。
|
||
- 仅为 `ExactStopAtBoundary` 添加停车位置、速度、加速度以及稳定尾段硬约束。
|
||
- 让 QP 行数、上下界和验证器随模式与稳定尾段 knot 数量变化。
|
||
- 使用与 QP 相同的恒 jerk 离散动力学做精确停车可达性验证。
|
||
- 为 Rolling、ApproachStop 和 ExactStop 构造各自合理的初始解和外层迭代行为。
|
||
|
||
### 阶段输入
|
||
|
||
- 阶段一完成后的提交。
|
||
- `docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-phase-1.md`。
|
||
- 阶段一生成的阶段二精细提示词。
|
||
|
||
### 完成条件
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-model
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-integration
|
||
```
|
||
|
||
两项均须输出 `PASS`，并保留 Task 3、Task 4、Task 5 的独立提交边界。
|
||
|
||
## 阶段三：轨迹发布与跨周期连续性
|
||
|
||
对应十任务计划中的 Task 6 和 Task 7。
|
||
|
||
### 实施范围
|
||
|
||
- 在轨迹元数据中保存纵向模式和真实停车边界身份。
|
||
- Rolling 和 ApproachStop 只发布时间范围内的运动轨迹，不追加虚假零速保持点。
|
||
- ExactStop 发布 QP 内部静止稳定段，并按配置追加外部零速保持点。
|
||
- 轨迹验证器按模式检查终端状态，同时保持普通运动学、碰撞和边界验证。
|
||
- 将上一条已发布轨迹按绝对时间重采样，并映射到新路径的 PathS，作为软参考而不是硬约束。
|
||
|
||
### 阶段输入
|
||
|
||
- 阶段二完成后的提交和交接文档。
|
||
- 阶段二根据实际结果生成的阶段三精细提示词。
|
||
|
||
### 完成条件
|
||
|
||
至少运行并通过：
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-planning-service
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
|
||
```
|
||
|
||
保留 Task 6 和 Task 7 的独立提交边界。
|
||
|
||
## 阶段四：端到端集成与实测诊断
|
||
|
||
对应十任务计划中的 Task 8、Task 9 和 Task 10。
|
||
|
||
### 实施范围
|
||
|
||
- 完成 `RollingContinuation → ApproachStopBoundary → ExactStopAtBoundary` 的服务流转。
|
||
- 覆盖真实 Goal、GearSwitchApproach、多周期滚动和停车稳定尾段。
|
||
- 完善 MovementTest 终端/UI 诊断，但继续保持 `OBSERVE_ONLY`。
|
||
- 更新 EMPlanner 文档。
|
||
- 完成全量回归、构建和目标运行环境中的 OSQP 探针。
|
||
|
||
### 阶段输入
|
||
|
||
- 阶段三完成后的提交和交接文档。
|
||
- 阶段三根据实际结果生成的阶段四精细提示词。
|
||
|
||
### 完成条件
|
||
|
||
严格执行十任务计划 Task 10 中列出的全部验证命令。至少包含：
|
||
|
||
```powershell
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-core-all
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
|
||
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
|
||
dotnet build ClumsyPilot/ClumsyPilot.csproj
|
||
```
|
||
|
||
目标机 OSQP 验证必须在实际部署/测试机器上运行；若当前窗口不在目标机，只能明确记录为“待目标机验证”，不得声称已通过。
|
||
|
||
## 跨窗口交接协议
|
||
|
||
### 每个阶段开始时
|
||
|
||
1. 阅读设计规格、十任务计划、本路线图、上一阶段交接文件和当前阶段提示词。
|
||
2. 运行 `git status --short` 和 `git log -8 --oneline`，记录阶段开始基线。
|
||
3. 确认上一阶段要求的提交存在；若不存在或测试不通过，先停止并报告，不得假设已完成。
|
||
4. 只执行当前阶段对应的原计划任务。
|
||
|
||
### 每个阶段结束时
|
||
|
||
1. 重新运行本阶段全部验收命令，不能只引用较早的结果。
|
||
2. 检查每个提交只包含当前任务文件，不得使用 `git add .` 或 `git add -A`。
|
||
3. 创建交接文件：
|
||
|
||
`docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-phase-N.md`
|
||
|
||
4. 交接文件必须记录：
|
||
|
||
- 阶段开始和结束提交；
|
||
- 每个任务的提交号；
|
||
- 实际修改和新增的文件；
|
||
- 新增或改变的公开/内部接口；
|
||
- 每条验证命令、退出码和关键输出；
|
||
- 未解决问题、目标机限制和与计划的偏差；
|
||
- 下一阶段必须继承的具体事实。
|
||
|
||
5. 根据交接文件和当前仓库状态创建下一阶段提示词：
|
||
|
||
`docs/superpowers/prompts/2026-08-05-em-longitudinal-rolling-phase-(N+1).md`
|
||
|
||
6. 下一阶段提示词不得只写“继续原计划”，必须包含实际提交号、实际接口、准确任务边界、允许修改文件、测试命令、提交边界和完成后的交接要求。
|
||
7. 提交交接文件与下一阶段提示词，然后停止，不执行下一阶段代码。
|
||
|
||
阶段四没有下一阶段提示词，改为生成最终验收报告：
|
||
|
||
`docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-final.md`
|
||
|
||
## 阶段状态
|
||
|
||
- [ ] 阶段一：纵向基础与窗口语义
|
||
- [ ] 阶段二：ST 优化核心
|
||
- [ ] 阶段三：轨迹发布与跨周期连续性
|
||
- [ ] 阶段四：端到端集成与实测诊断
|
||
|
||
当前入口提示词：`docs/superpowers/prompts/2026-08-05-em-longitudinal-rolling-phase-1.md`
|