# 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`