Files

T

梁薄云 8c687a7f6f docs: fix README plan scope check

2026-08-04 13:52:53 +08:00

11 KiB

Raw Blame History

EM Planner 与 TrajectoryExecution README 实施计划

For agentic workers: REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 以 CoarsePath/README.md 的结构重写 EMPlanner 文档，并为 TrajectoryExecution 新增准确、可操作的模块 README。

Architecture: README 只描述现有的不可变请求、纯单次规划、滚动协调、轨迹执行和通用控制命令边界。两份文档均从上游空间路径到未来硬件适配器的单向数据流解释职责；不改变任何 C#、测试、项目文件或发布脚本。

Tech Stack: Markdown、PowerShell、Git、现有 EMPlannerVerificationHost 命令。

Global Constraints

仅修改 ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md 和新建的 ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md。
保留所有既有用户工作区改动；只显式暂存本任务指定的 README，绝不使用 git add . 或 git add -A。
从仓库根目录运行所有检查；不改动 LS/ST/OSQP、测试夹具、发布脚本、csproj、UI 或硬件代码。
EmPlanningService.Plan(EmPlanningRequest, CancellationToken) 是纯、同步、一次性的规划入口。
只有 Success 和 SuccessWithFallback 可携带可消费的 EmTrajectory；其余状态不可发布部分轨迹。
动态障碍物、时空占用、行为决策、UI/硬件集成、横移、蟹行和原地旋转均明确为未实现范围。
验证命令只引用当前的 em-core-all、coordinator、executor、plugin-package 和 em-all。

Task 1: 重写 EMPlanner 模块 README

Files:

Modify: ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md

Interfaces:

Consumes: PathSmoothingResult、PlanningGridMap、VehicleParameters、VehicleMotionState、EmPlannerConfiguration 和可选上一条 EmTrajectory 快照。
Produces: 文档化的 IEmPlanningService.Plan(EmPlanningRequest request, CancellationToken cancellationToken) 消费边界，以及仅在 Success/SuccessWithFallback 时可消费的 EmTrajectory。
Step 1: 记录旧文档的 RED 基线

从仓库根目录运行：

$text = Get-Content ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md -Raw -Encoding UTF8
if ($text -notmatch '尚未实现 LS 横向优化、\s*ST 纵向优化、滚动协调、轨迹发布') {
  throw 'Expected the stale Foundation-only scope marker.'
}

Expected: 找到一条 Foundation 阶段的旧描述，证明重写前 README 与当前实现不一致。

Step 2: 以 CoarsePath 风格重写 README

使用 apply_patch 以 UTF-8 Markdown 整体替换文件。文档必须按以下顺序覆盖：

模块说明（职责/非职责与唯一入口）
文件结构（Configuration、Contracts、Segmentation、Frenet、Corridor、Lateral、Longitudinal、Trajectory、Validation、Facade）
规划数据流（校验 -> 方向段 -> 走廊 -> LS -> ST -> 装配 -> 独立验证）
结果、状态与停止
坐标、单位与前进/倒车符号
最小调用示例
详细使用指南
验证命令
常见错误
第一版限制

正文必须声明静态走廊、OSQP 通过 solver-neutral IQpSolver/QuadraticProgram、实际 PathS、终端零速安全尾段、世界空间独立复核和纯服务边界。示例只构造 EmPlanningService 和调用 Plan，不得包含 UI 或硬件对象。模块概览和首版限制都必须以相对链接指向 ../TrajectoryExecution/README.md，说明滚动执行不属于纯规划服务。

Step 3: 运行 GREEN 文档契约检查

从仓库根目录运行：

$path = 'ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md'
$text = Get-Content $path -Raw -Encoding UTF8
$required = @(
  '## 模块说明（Module Overview）',
  '## 文件结构（File Structure）',
  '## 规划数据流（Planning Data Flow）',
  'EmPlanningService.Plan',
  'SuccessWithFallback',
  'em-core-all',
  'em-all',
  '动态障碍物'
)
foreach ($item in $required) {
  if (-not $text.Contains($item)) { throw "Missing README contract: $item" }
}
if ($text -match '尚未实现 LS 横向优化、\s*ST 纵向优化、滚动协调、轨迹发布') {
  throw 'Stale Foundation-only scope remains.'
}

Expected: exit 0 without Missing README contract or stale-scope error.

Step 4: 检查差异并提交 Task 1

git diff --check
git add -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md
git diff --cached --check
git diff --cached --name-only
git commit -m "docs: rewrite EM Planner readme"
git diff-tree --no-commit-id --name-only -r HEAD

Expected: staged 和提交范围仅为 EMPlanner README；所有 diff 检查退出 0。

Task 2: 新增 TrajectoryExecution 模块 README

Files:

Create: ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md

Interfaces:

Consumes: IEmPlanningService、调用方冻结的 PlanningCycleInput、当前 VehicleMotionState 与已发布不可变 EmTrajectory。
Produces: EmPlanningCoordinator.PlanLatestAsync 的当前版本发布语义，以及 TrajectoryExecutor.UpdateCommand 返回的 TrajectoryControlCommand。
Step 1: 记录 README 缺失的 RED 基线

从仓库根目录运行：

if (Test-Path ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md) {
  throw 'TrajectoryExecution README unexpectedly already exists.'
}
throw 'RED: TrajectoryExecution README is absent.'

Expected: command exits nonzero and prints the RED message.

Step 2: 新增 CoarsePath 风格 README

使用 apply_patch 创建 UTF-8 Markdown。按以下顺序说明：

模块说明（协调、交接、执行与控制适配职责）
文件结构（所有 .cs 文件）
滚动执行数据流
周期身份、latest-wins 与安全交接
换向状态机和停止语义
通用控制命令的字段、单位及硬件边界
最小调用示例
详细使用指南
验证命令与插件部署链接
常见错误
第一版限制

文件结构必须逐项列出当前文件，且只赋予现有职责：

TrajectoryExecution/
├── EmPlanningCoordinator.cs
├── GearSwitchState.cs
├── GearSwitchStateMachine.cs
├── IEmPlanningCycleSink.cs
├── IVehicleStateProvider.cs
├── PlanningCycleIdentity.cs
├── PlanningCycleInput.cs
├── PlanningCycleResult.cs
├── TrajectoryControlAdapter.cs
├── TrajectoryControlCommand.cs
├── TrajectoryExecutionState.cs
├── TrajectoryExecutor.cs
├── TrajectoryHandoffSelector.cs
└── TrajectorySampler.cs

文档必须给出状态序列 Following -> ApproachingGearSwitch -> HoldingZero -> RequestingDirectionChange -> AwaitingDirectionConfirmation -> Following，说明失败重规划不覆盖上一条完整轨迹、轨迹末点不外推，以及 TrajectoryControlCommand 没有横向车体速度或原地旋转字段。插件章节必须指向 EMPlanner README 的 Windows x64 打包说明，不能重写发布脚本的细节。

Step 3: 运行 GREEN 文档契约检查

从仓库根目录运行：

$path = 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md'
$text = Get-Content $path -Raw -Encoding UTF8
$required = @(
  '## 模块说明（Module Overview）',
  '## 文件结构（File Structure）',
  '## 滚动执行数据流（Rolling Execution Data Flow）',
  'EmPlanningCoordinator.PlanLatestAsync',
  'TrajectoryExecutor.UpdateCommand',
  'Following -> ApproachingGearSwitch -> HoldingZero',
  'TrajectoryControlCommand',
  '../EMPlanner/README.md',
  'em-all',
  '动态障碍物'
)
foreach ($item in $required) {
  if (-not $text.Contains($item)) { throw "Missing README contract: $item" }
}

Expected: exit 0 without Missing README contract.

Step 4: 执行文档关联与回归验证

从仓库根目录运行：

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 -- plugin-package
git diff --check

Expected: 四个验证组均退出 0 并输出对应 PASS 行；git diff --check 退出 0。

Step 5: 检查差异并提交 Task 2

git add -- ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md
git diff --cached --check
git diff --cached --name-only
git commit -m "docs: add trajectory execution readme"
git diff-tree --no-commit-id --name-only -r HEAD

Expected: staged 和提交范围仅为 TrajectoryExecution README；所有 diff 检查退出 0。

Task 3: 最终 README 交叉核查

Files:

Modify: ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md（仅在发现失效相对链接或错误命令时修正）
Modify: ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md（仅在发现失效相对链接或错误命令时修正）

Interfaces:

Consumes: Task 1 的单次规划边界和 Task 2 的执行边界。
Produces: 两份边界互不矛盾、命令与仓库现状一致的交接文档。
Step 1: 运行最终文本与相对链接检查

$em = Get-Content ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md -Raw -Encoding UTF8
$execution = Get-Content ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md -Raw -Encoding UTF8
if ($em -match '尚未实现 LS 横向优化') { throw 'EMPlanner retains stale completion state.' }
if ($em -notmatch 'TrajectoryExecution') { throw 'EMPlanner does not describe its execution boundary.' }
if ($execution -notmatch '../EMPlanner/README.md') { throw 'Execution README lacks EMPlanner link.' }
if ($execution -match 'MultiVehicleScriptVx|MultiVehicleScriptVy|MultiVehicleScriptVth') {
  throw 'Execution README leaks a prohibited hardware/UI field.'
}

Expected: exit 0.

Step 2: 运行最终门禁并检查工作区范围

dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-all
git diff --check
git status --short -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md

Expected: em-all exit 0；无 whitespace 错误；两个 README 均已提交，因此范围状态为空。

Step 3: 如步骤 1 或 2 要求更正，显式暂存两份 README 并提交

git add -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md
git diff --cached --check
git commit -m "docs: verify EM Planner readme links"
git diff-tree --no-commit-id --name-only -r HEAD

Expected: 仅当发生文字修正时才创建提交；否则不执行此步骤。

11 KiB Raw Blame History Unescape Escape

EM Planner 与 TrajectoryExecution README 实施计划

Global Constraints

Task 1: 重写 EMPlanner 模块 README

Task 2: 新增 TrajectoryExecution 模块 README

Task 3: 最终 README 交叉核查

11 KiB

Raw Blame History