docs: plan planner comment overhaul
This commit is contained in:
梁薄云
@@ -0,0 +1,295 @@
|
|||||||
|
# PathSmoothing 与 TrajectoryExecution 注释改造实施计划
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** 为 PathSmoothing 生产规划核心与 TrajectoryExecution 全部生产代码补齐 CoarsePath 风格的中文 XML 文档注释。
|
||||||
|
|
||||||
|
**Architecture:** 只在现有声明之前增加或替换 `///` 文档注释，不改变任何命名、签名、数值、控制流或项目文件。公开 API 使用完整的职责、参数、返回值和失败语义；关键内部算法边界补充单位、数据所有权和不变量；私有小工具、测试、报告及可视化模块保持不动。
|
||||||
|
|
||||||
|
**Tech Stack:** C# XML documentation comments、PowerShell、现有 PathSmoothing 验证脚本、`EMPlannerVerificationHost`。
|
||||||
|
|
||||||
|
## Global Constraints
|
||||||
|
|
||||||
|
- 只修改注释；禁止修改任何可执行 C# 语句、签名、命名空间、`using`、测试、`csproj`、UI、硬件或报告/可视化模块。
|
||||||
|
- 注释使用中文，并保留 C# 类型名；每个数值参数或属性都要标明现有单位（m、rad、`1/m`、m/s、m/s²、m/s³、s）或明确其为 ID、索引、布尔值、枚举、快照或集合。
|
||||||
|
- 每个公开构造函数和公开方法必须有 `<summary>`；有参数时逐项使用 `<param>`；非 `void` 方法使用 `<returns>`；`Try...` 方法明确 `true` / `false` 和每个 `out` 参数。
|
||||||
|
- 关键内部跨目录算法入口也使用相同规范；不为私有单行数学工具、测试、比较、报告或可视化代码增加注释。
|
||||||
|
- 路径、状态和结果的注释必须说明不可变性、集合顺序、失败时的空结果或 `false` 语义；不得宣称代码当前未实现的动态障碍物、UI、硬件、横移或原地旋转能力。
|
||||||
|
- 每个任务只能显式暂存该任务列出的文件；禁止 `git add .`、`git add -A`、清理命令或破坏性 Git 命令。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: PathSmoothing 契约与公开门面注释
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingConfiguration.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingDiagnostics.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingStatus.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPointSource.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothingMethod.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingComparisonService.cs`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: `PlanningResult`、`PlanningGridMap`、`VehicleParameters`、不可变 `PathSmoothingRequest` 与 `PathSmoothingConfiguration`。
|
||||||
|
- Produces: 只有成功状态才可消费的 `PathSmoothingResult`、严格递增弧长的 `SmoothedPathPoint` 序列，以及包含区域失败和性能信息的 `PathSmoothingDiagnostics`。
|
||||||
|
|
||||||
|
- [ ] **Step 1: 记录缺失参数/返回值注释的 RED 基线**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$path = 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs'
|
||||||
|
$text = Get-Content $path -Raw -Encoding UTF8
|
||||||
|
if ($text -notmatch 'public PathSmoothingResult Smooth\(') { throw 'Expected public Smooth entry point.' }
|
||||||
|
if ($text -match '<param name="request">') { throw 'RED baseline unexpectedly already documents request.' }
|
||||||
|
throw 'RED: PathSmoothingService.Smooth lacks parameter documentation.'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: command exits nonzero with the RED message.
|
||||||
|
|
||||||
|
- [ ] **Step 2: 为契约类型、构造函数、属性和门面补齐 XML 文档**
|
||||||
|
|
||||||
|
使用 `apply_patch` 在每个公开类型前写职责和边界；在构造函数前写参数类型意义、单位、可空性、集合顺序和防御性复制语义；在关键属性前写数据含义和单位。为 `PathSmoothingService.Smooth`、比较服务入口和结果工厂写完整 `<param>` / `<returns>`。
|
||||||
|
|
||||||
|
关键语义必须在注释中准确出现：`PathSmoothingRequest` 持有输入副本；`PathSmoothingResult` 仅在成功状态发布路径；`SmoothedPathPoint` 的位置为 m、航向 rad、曲率 `1/m`、弧长 m；失败结果不包含部分可消费路径。
|
||||||
|
|
||||||
|
- [ ] **Step 3: 运行 GREEN XML 契约检查**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$paths = @(
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs'
|
||||||
|
)
|
||||||
|
$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n"
|
||||||
|
foreach ($marker in @('<summary>', '<param name="request">', '<returns>', 'm', 'rad', '1/m', '不可变')) {
|
||||||
|
if (-not $text.Contains($marker)) { throw "Missing XML documentation marker: $marker" }
|
||||||
|
}
|
||||||
|
if ($text -notmatch '失败.*部分|部分.*路径') { throw 'Missing partial-result failure semantics.' }
|
||||||
|
Write-Output 'PASS PathSmoothing contract XML documentation'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: exit 0 and the PASS line.
|
||||||
|
|
||||||
|
- [ ] **Step 4: 检查纯注释差异并提交 Task 1**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
git diff --check
|
||||||
|
git diff -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade
|
||||||
|
git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingConfiguration.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingDiagnostics.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingStatus.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPointSource.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothingMethod.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingComparisonService.cs
|
||||||
|
git diff --cached --check
|
||||||
|
git commit -m "docs: document path smoothing contracts"
|
||||||
|
git diff-tree --no-commit-id --name-only -r HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: cached diff and commit contain only the listed files, with no non-comment code changes.
|
||||||
|
|
||||||
|
### Task 2: PathSmoothing 处理、校验与 LocalG2 阶段注释
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/ArcLengthResampler.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalysis.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalyzer.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathReferenceInterpolator.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedDirectionSegment.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedPath.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/RawPathBaselineBuilder.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/SmoothingPoint2D.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/CurvatureLimitPolicy.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransition.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransitionDetector.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateBuilder.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateGeometry.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2OptionsSnapshot.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PathSplicer.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PreSmoothingPipeline.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2RegionWorkOrder.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2SmoothingRegion.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/QuinticHermiteCurve2D.cs`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: 已准备的方向段、车辆约束、地图快照、局部 G2 配置和候选几何。
|
||||||
|
- Produces: 连续且严格递增弧长的平滑段、候选评估/拒绝原因、验证结果和不可变区域报告。
|
||||||
|
|
||||||
|
- [ ] **Step 1: 记录关键 `Try...` 入口缺失返回语义的 RED 基线**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$path = 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs'
|
||||||
|
$text = Get-Content $path -Raw -Encoding UTF8
|
||||||
|
if ($text -notmatch 'TryPrepare\(') { throw 'Expected TryPrepare entry point.' }
|
||||||
|
if ($text -match '<returns>.*true.*false') { throw 'RED baseline unexpectedly documents TryPrepare outcomes.' }
|
||||||
|
throw 'RED: TryPrepare lacks true/false and out-result documentation.'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: command exits nonzero with the RED message.
|
||||||
|
|
||||||
|
- [ ] **Step 2: 补齐处理/验证/LocalG2 的阶段边界注释**
|
||||||
|
|
||||||
|
使用 `apply_patch` 为公开类型与关键内部入口增加 `<summary>`、`<param>`、`<returns>`。所有 `Try...` 方法必须说明成功/失败、`out` 值和原因字符串；几何方法必须说明世界坐标 m、航向 rad、曲率 `1/m`、弧长 m 和严格递增约束；校验器必须说明碰撞、曲率、换向锚点和无部分发布规则。
|
||||||
|
|
||||||
|
LocalG2 注释必须说明候选构建、预平滑、窗口选择、拼接和评估的输入/输出关系，不得将内部启发式误描述为动态障碍或控制功能。
|
||||||
|
|
||||||
|
- [ ] **Step 3: 运行 GREEN 内部算法注释检查**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$paths = @(
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs'
|
||||||
|
)
|
||||||
|
$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n"
|
||||||
|
foreach ($marker in @('<summary>', '<param', '<returns>', 'true', 'false', 'm', 'rad', '1/m')) {
|
||||||
|
if (-not $text.Contains($marker)) { throw "Missing algorithm XML marker: $marker" }
|
||||||
|
}
|
||||||
|
if ($text -notmatch '严格递增|不发布部分') { throw 'Missing geometric or publication invariant.' }
|
||||||
|
Write-Output 'PASS PathSmoothing algorithm XML documentation'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: exit 0 and the PASS line.
|
||||||
|
|
||||||
|
- [ ] **Step 4: 运行既有 PathSmoothing 验证并提交 Task 2**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
& .\ClumsyPilot\tests\verify_path_smoothing_geometry.ps1
|
||||||
|
& .\ClumsyPilot\tests\verify_path_smoothing_validation.ps1
|
||||||
|
& .\ClumsyPilot\tests\verify_path_smoothing_local_g2_integration.ps1
|
||||||
|
git diff --check
|
||||||
|
git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/ArcLengthResampler.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalysis.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalyzer.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathReferenceInterpolator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedDirectionSegment.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedPath.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/RawPathBaselineBuilder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/SmoothingPoint2D.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/CurvatureLimitPolicy.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransition.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransitionDetector.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateBuilder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateGeometry.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2OptionsSnapshot.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PathSplicer.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PreSmoothingPipeline.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2RegionWorkOrder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2SmoothingRegion.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/QuinticHermiteCurve2D.cs
|
||||||
|
git diff --cached --check
|
||||||
|
git commit -m "docs: document path smoothing pipeline"
|
||||||
|
git diff-tree --no-commit-id --name-only -r HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: three existing validation scripts exit 0; cached diff and commit contain only listed production files and comment-only changes.
|
||||||
|
|
||||||
|
### Task 3: TrajectoryExecution 全部生产边界注释
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchState.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IEmPlanningCycleSink.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IVehicleStateProvider.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleIdentity.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleInput.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleResult.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlAdapter.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutionState.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs`
|
||||||
|
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectorySampler.cs`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: `IEmPlanningService`、调用方时钟与 `VehicleMotionState` 快照、已验证的不可变 `EmTrajectory`、方向确认状态和 `EmPlannerConfiguration`。
|
||||||
|
- Produces: latest-wins `PlanningCycleResult`、安全交接选择、不可变 `TrajectoryExecutionState` 和控制器中立的 `TrajectoryControlCommand`。
|
||||||
|
|
||||||
|
- [ ] **Step 1: 记录协调器方法缺失完整契约的 RED 基线**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$path = 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs'
|
||||||
|
$text = Get-Content $path -Raw -Encoding UTF8
|
||||||
|
if ($text -notmatch 'PlanLatestAsync\(') { throw 'Expected PlanLatestAsync entry point.' }
|
||||||
|
if ($text -match '<param name="input">') { throw 'RED baseline unexpectedly already documents rolling input.' }
|
||||||
|
throw 'RED: PlanLatestAsync lacks caller-clocked input and cancellation documentation.'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: command exits nonzero with the RED message.
|
||||||
|
|
||||||
|
- [ ] **Step 2: 补齐执行、交接与控制契约注释**
|
||||||
|
|
||||||
|
使用 `apply_patch` 为目录内所有公开类型、枚举、构造函数、属性和公开方法补齐 XML 文档；为 `CompleteCycle`、`SelectPoint`、交接/采样和换向状态机等跨职责内部入口补齐语义。
|
||||||
|
|
||||||
|
`EmPlanningCoordinator.PlanLatestAsync` 必须解释 caller-clocked `now`、取消旧周期、版本/身份检查和只发布完整成功轨迹。交接注释必须列出同段同方向、年龄、追踪、边界和末点拒绝。`UpdateCommand` 与 `TrajectoryControlCommand` 必须写明 m/s、rad/s、零速/制动、一次换向请求、无横向速度和无原地旋转。`TrySample` 必须明确区间外或跨边界时返回 `false`。
|
||||||
|
|
||||||
|
- [ ] **Step 3: 运行 GREEN 执行层 XML 契约检查**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$paths = @(
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs',
|
||||||
|
'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs'
|
||||||
|
)
|
||||||
|
$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n"
|
||||||
|
foreach ($marker in @('<summary>', '<param name="input">', '<returns>', 'm/s', 'rad/s', 'latest-wins', '零速', 'false')) {
|
||||||
|
if (-not $text.Contains($marker)) { throw "Missing execution XML marker: $marker" }
|
||||||
|
}
|
||||||
|
if ($text -match 'MultiVehicleScriptVx|MultiVehicleScriptVy|MultiVehicleScriptVth') {
|
||||||
|
throw 'Documentation must not leak UI/hardware command fields.'
|
||||||
|
}
|
||||||
|
Write-Output 'PASS TrajectoryExecution XML documentation'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: exit 0 and the PASS line.
|
||||||
|
|
||||||
|
- [ ] **Step 4: 运行执行层回归并提交 Task 3**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
|
||||||
|
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
|
||||||
|
git diff --check
|
||||||
|
git add -- ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchState.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IEmPlanningCycleSink.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IVehicleStateProvider.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleIdentity.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleInput.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleResult.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlAdapter.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutionState.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectorySampler.cs
|
||||||
|
git diff --cached --check
|
||||||
|
git commit -m "docs: document trajectory execution contracts"
|
||||||
|
git diff-tree --no-commit-id --name-only -r HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: both execution gates exit 0; cached diff and commit contain only listed files and comment-only changes.
|
||||||
|
|
||||||
|
### Task 4: 最终注释审查与完整回归
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: Task 1 至 Task 3 的文件（仅在发现缺失、错误单位或文档与实际行为矛盾时修正）。
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: CoarsePath 风格的 XML 文档约定、PathSmoothing 的纯规划边界和 TrajectoryExecution 的 caller-clocked 执行边界。
|
||||||
|
- Produces: 与实际代码一致、可由 IDE XML 文档显示的中文 API 说明。
|
||||||
|
|
||||||
|
- [ ] **Step 1: 检查差异仅包含注释**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$diff = git diff 297186a..HEAD -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution
|
||||||
|
$codeLines = $diff | Where-Object { $_ -match '^[+-](?![+-/\s])' }
|
||||||
|
if ($codeLines.Count -gt 0) { $codeLines; throw 'Non-comment C# changes detected.' }
|
||||||
|
Write-Output 'PASS comment-only diff review'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: exit 0 and the PASS line. Ignore `+++` / `---` headers and `///` documentation lines.
|
||||||
|
|
||||||
|
- [ ] **Step 2: 运行最终构建与门禁**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
dotnet build ClumsyPilot/ClumsyPilot.csproj --no-restore
|
||||||
|
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-all
|
||||||
|
git diff --check
|
||||||
|
git status --short -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: build 和 `em-all` 退出 0；无 whitespace 错误；两个目标目录没有未提交状态。
|
||||||
|
|
||||||
|
- [ ] **Step 3: 仅在最终审查发现需修正时，显式暂存和提交**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2 ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution
|
||||||
|
git diff --cached --check
|
||||||
|
git commit -m "docs: verify planner XML comments"
|
||||||
|
git diff-tree --no-commit-id --name-only -r HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: 仅在文字修正发生时创建提交；否则不执行此步骤。
|
||||||
Reference in New Issue
Block a user