284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
# Local G2 固定锚点分离导数尺度恢复设计
|
||
|
||
**日期：** 2026-08-01
|
||
**状态：** 已完成书面规格复核，批准进入实施
|
||
**范围：** 替代失败的软位置锚点候选族，恢复 Task 3 可行性门禁，并在不放宽安全阈值的前提下继续 Task 8
|
||
|
||
## 1. 结论
|
||
|
||
Local G2 不再移动任何内部运动基元边界。窗口外端点以及所有内部边界的位置、车辆航向和共享车辆曲率保持为硬边界值。新的几何自由度来自内部边界两侧相互独立的正导数尺度：左侧曲线以一个尺度进入节点，右侧曲线以另一个尺度离开节点。
|
||
|
||
相邻曲线在内部节点共享位置、切线方向和几何曲率，因此满足几何 G2。左右导数长度可以不同，所以不再额外强制参数速度连续或参数 C2。该变化不会产生坐标错位，也不修改曲率、偏差、碰撞、净空或质量改善门槛。
|
||
|
||
本设计取代 `2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md` 中的软位置锚点候选构造和候选调度。此前已经完成并提交的评估器边界去重和代表窗口规划继续有效。
|
||
|
||
## 2. 失败证据与根因
|
||
|
||
旧软锚点设计规定：
|
||
|
||
```text
|
||
softOffset = min(0.05 m, 0.5 × MaximumDeviationMeters)
|
||
```
|
||
|
||
默认配置产生 `0.05 m` 法向位移。隔离可行性探针对真实 `SingleTurn` 场景生成了三个非零偏移候选；三个候选均被未修改的 `CurvatureExceeded` 门槛拒绝。候选曲率范围分别为：
|
||
|
||
```text
|
||
[-6.5130, 9.1861] 1/m
|
||
[-11.2604, 14.8576] 1/m
|
||
[-14.3107, 10.1819] 1/m
|
||
```
|
||
|
||
该场景车辆最大曲率为约 `0.833333 1/m`，原始窗口曲率约为 `0…0.416668 1/m`。因此失败来自“短窗口内移动位置，同时锁定航向和曲率”的五次 Hermite 几何，而不是评估器、反射探针、车辆模型或 fixture 状态。
|
||
|
||
证据保存在：
|
||
|
||
- `.superpowers/sdd/local-g2-soft-anchor-feasibility-report.md`
|
||
- `.superpowers/sdd/local-g2-soft-anchor-task-3-report.md`
|
||
|
||
## 3. 不变约束
|
||
|
||
以下约束保持不变：
|
||
|
||
- 最小、首选和最大窗口长度仍是左右合计总长度：`0.20 m`、`0.50 m`、`0.80 m`。
|
||
- 路径起点、路径终点、换向点、窗口外端点和内部运动基元边界的位置全部为硬锚点。
|
||
- 内部边界的车辆航向和距离加权共享曲率为硬边界值。
|
||
- 最大车辆曲率、原始曲率范围 `1e-6` 容差、完整车体碰撞、额外净空、最大偏差、20% 峰值改善和 2% 变化代价容差不变。
|
||
- 不跨换向点生成候选；前进和倒车继续使用既有车辆曲率与几何曲率符号规则。
|
||
- 每区域的配置候选上限继续有效，并受现有绝对上限 `12` 约束。
|
||
- 不引入 SQP、梯度下降、Clothoid 非线性求解或依赖墙钟时间的生产超时。
|
||
- 相同请求必须生成相同候选顺序、状态、路径和区域报告。
|
||
|
||
## 4. 分离导数尺度边界模型
|
||
|
||
### 4.1 每个节点的尺度
|
||
|
||
当前 `BoundaryNode` 只保存一个 `DerivativeScale`，内部节点左右两段共用该尺度。修订后，一个节点具有：
|
||
|
||
```text
|
||
IncomingDerivativeScale
|
||
OutgoingDerivativeScale
|
||
```
|
||
|
||
对片段 `node[i] -> node[i+1]`：
|
||
|
||
```text
|
||
左端使用 node[i].OutgoingDerivativeScale
|
||
右端使用 node[i+1].IncomingDerivativeScale
|
||
```
|
||
|
||
路径窗口起点只需要离开尺度；窗口终点只需要进入尺度。无意义的一侧不参与曲线构造。
|
||
|
||
### 4.2 基础尺度
|
||
|
||
设内部节点左、右相邻的原始弧长跨度为：
|
||
|
||
```text
|
||
L_left = s_internal - s_previous
|
||
L_right = s_next - s_internal
|
||
```
|
||
|
||
基础尺度为：
|
||
|
||
```text
|
||
IncomingBase = L_left
|
||
OutgoingBase = L_right
|
||
```
|
||
|
||
不再以 `(L_left + L_right) / 2` 同时赋给左右两侧。窗口起点的离开基础尺度等于第一个片段跨度；窗口终点的进入基础尺度等于最后一个片段跨度。
|
||
|
||
### 4.3 G2 条件
|
||
|
||
每个端点仍按下式构造导数：
|
||
|
||
```text
|
||
r' = λ T
|
||
r'' = λ² κ_geometric N
|
||
```
|
||
|
||
在内部节点，左右曲线使用同一位置、同一切线方向 `T` 和同一几何曲率 `κ_geometric`，但允许 `λ_in != λ_out`。因此：
|
||
|
||
- 位置连续；
|
||
- 单位切线方向连续；
|
||
- 几何曲率连续；
|
||
- 满足 G2；
|
||
- 不保证参数一阶导数向量相等；
|
||
- 不保证参数二阶导数向量相等。
|
||
|
||
这种差异是设计自由度，不是接缝错误。路径输出仍按物理弧长重新采样和分析，不依赖 Hermite 参数速度连续。
|
||
|
||
## 5. 有限尺度配置
|
||
|
||
内部节点使用三个确定性配置：
|
||
|
||
```text
|
||
P0: incomingFactor = 1.00, outgoingFactor = 1.00
|
||
P1: incomingFactor = 0.75, outgoingFactor = 1.25
|
||
P2: incomingFactor = 1.25, outgoingFactor = 0.75
|
||
```
|
||
|
||
实际尺度为基础尺度乘以对应因子。窗口外端点始终使用 `1.00` 因子。联合多事件区域将同一配置应用于所有内部节点，避免组合数指数增长。
|
||
|
||
没有内部节点的单片段区域只生成 P0。尺度必须有限且严格为正；曲线仍必须通过现有全参数区间导数范数认证，不能以离散采样代替尖点证明。
|
||
|
||
## 6. 代表窗口与两级调度
|
||
|
||
Task 2 已保证窗口规划器按首选、最小、最大、`0.75 × 首选`、`1.25 × 首选`覆盖总长度，并先生成平衡窗口。生成器继续选取最多四个互异代表窗口：
|
||
|
||
1. 规划器第一个窗口；
|
||
2. 总长度最短窗口；
|
||
3. 总长度最长窗口；
|
||
4. 左右差异最大的窗口。
|
||
|
||
重复窗口按起止弧长去重，平局使用规划器候选编号。
|
||
|
||
### 6.1 第一级
|
||
|
||
第一级最多包含六次尝试，顺序固定：
|
||
|
||
1. 对每个代表窗口按代表顺序尝试 P0，最多四次；
|
||
2. 对第一个代表窗口尝试 P1；
|
||
3. 对第一个代表窗口尝试 P2。
|
||
|
||
评估第一级内所有成功构造的候选，并按照现有偏差、峰值、变化代价、长度变化和候选编号规则选择该层最优项。如果第一级存在被接受候选，不生成或评估第二级。
|
||
|
||
### 6.2 第二级
|
||
|
||
只有第一级没有被接受候选时才进入第二级：
|
||
|
||
1. 对剩余代表窗口按顺序尝试 P1；
|
||
2. 对剩余代表窗口按顺序尝试 P2；
|
||
3. 达到 `min(MaximumCandidatesPerRegion, 12)` 立即停止。
|
||
|
||
配置上限小于六时按上述全局顺序截断。候选编号只对成功构造的几何密集编号；构造失败不改变后续尝试顺序。现有区域报告的候选数量记录实际进入评估器的候选数；构造尝试数只通过内部测试快照和可行性报告公开，不新增公共报告字段。
|
||
|
||
本节明确修订主设计第 13 节的“所有有限候选”范围：必须评估当前启用层内的全部候选；第一级已有合格项时，第二级不是启用层，无需为了寻找理论全局最优而支付额外安全校核成本。
|
||
|
||
## 7. 评估数据流与缓存
|
||
|
||
同一个代表窗口的 P0、P1、P2 共享原始窗口几何。评估器为每个互异窗口只执行一次：
|
||
|
||
- 原始窗口提取；
|
||
- 原始窗口统一重采样和几何分析；
|
||
- 原始曲率范围、峰值和变化代价计算。
|
||
|
||
缓存键必须至少包含方向段编号、窗口起止弧长和本次请求身份；缓存生命周期只限一次区域评估，不能跨请求共享可变状态。
|
||
|
||
每个候选仍单独执行：
|
||
|
||
1. 候选有限值和几何分析；
|
||
2. 车辆曲率与原始曲率范围校核；
|
||
3. 最大偏差与质量门槛；
|
||
4. 拼接后的完整车体碰撞、净空和完整路径验证。
|
||
|
||
廉价几何门槛继续位于昂贵的完整车体校核之前。缓存只消除重复原始分析，不跳过任何候选安全检查。
|
||
|
||
## 8. 性能预算
|
||
|
||
生产性能使用确定性工作量上限：
|
||
|
||
- 代表窗口不超过 `4`；
|
||
- 第一级候选尝试不超过 `6`；
|
||
- 两级合计不超过配置值且绝对不超过 `12`；
|
||
- 原始窗口分析不超过互异代表窗口数；
|
||
- 无在线迭代优化器；
|
||
- 候选循环、导数认证和自适应采样继续检查取消令牌；
|
||
- 保留现有导数认证深度、认证区间数和采样递归深度硬上限。
|
||
|
||
可行性探针和最终验证报告执行固定性能基准：同一进程预热 `5` 次，测量 `30` 次，分别记录第一级成功场景和需要第二级场景的 P50/P95。比较基线为提交 `bd08a9b` 的固定锚点生成与评估路径，在相同机器、相同构建配置、相同 fixture 上测量。
|
||
|
||
性能门禁为：
|
||
|
||
```text
|
||
primary P95 <= 1.5 × baseline P95
|
||
fallback P95 <= 2.0 × baseline P95
|
||
```
|
||
|
||
墙钟结果只用于合并前性能门禁，不作为生产运行时中止条件。超出门禁时必须先定位重复分析或候选评估开销；不能通过删除碰撞、净空、曲率或质量校核获得通过。
|
||
|
||
## 9. 生产修改前的可行性门禁
|
||
|
||
共享 `LocalG2CandidateBuilder` 修改前，必须在隔离副本中实现本设计的完整尺度模型、调度和真实评估连接，并用真实 `SingleTurn` 请求证明：
|
||
|
||
- 至少一个候选被未修改的 `LocalG2CandidateEvaluator` 接受；
|
||
- 所有内部节点坐标与原始 transition 坐标误差不超过 `1e-9 m`；
|
||
- 至少一个被接受候选在内部节点使用不同的进入和离开尺度；
|
||
- 内部左右切线方向误差和曲率误差分别不超过既有 G2 测试容差；
|
||
- 车辆曲率、原始曲率范围、20% 峰值改善、2% 变化代价、偏差、碰撞和净空门槛全部通过；
|
||
- 探针记录窗口、配置、实际尺度、候选曲率范围、峰值、变化代价、偏差、净空和耗时。
|
||
|
||
若不存在这样的候选，设计再次停止。不能修改 fixture 期望、内部坐标、共享曲率、安全阈值或质量阈值强制获得 GREEN。
|
||
|
||
## 10. 失败、取消与发布
|
||
|
||
- 单个尺度配置无法构造：记录稳定原因并继续本层剩余尝试。
|
||
- 第一级无合格项：在剩余候选预算内进入第二级。
|
||
- 两级均无合格项：保留区域原始路径并报告 `Unchanged` 或总体 `PartialImprovement`。
|
||
- 第一级有合格项：选择该层最优项，不进入第二级。
|
||
- 取消：立即传播取消，不发布部分路径。
|
||
- 全局验证失败：继续按照接受区域的逆序逐个回滚并重新验证。
|
||
- 所有接受区域被回滚：发布已验证原始基线和 `Unchanged`。
|
||
- `Complete` 或 `PartialImprovement` 必须至少包含一个 `Improved` 区域报告。
|
||
|
||
Task 8 的检测报告顺序、反向工作顺序、可信原始曲率基线和旧方法隔离保持不变。
|
||
|
||
## 11. 测试与验收
|
||
|
||
### 11.1 TDD 与几何测试
|
||
|
||
当前候选验证脚本中的“接受非零软锚点”RED 断言改为：接受一个坐标零偏移、左右导数尺度不同的真实候选。必须先在共享旧生成器上观察预期 RED，再通过隔离可行性门禁，之后才修改共享生成器。
|
||
|
||
测试必须覆盖：
|
||
|
||
- 所有内部和外部锚点坐标误差 `<= 1e-9 m`；
|
||
- 外部位置、航向和曲率边界保持精确；
|
||
- 内部左右单位切线方向与几何曲率满足 G2；
|
||
- P1/P2 的左右导数范数确实不同；
|
||
- P0/P1/P2 顺序、代表窗口顺序和两级扩展顺序确定；
|
||
- 候选上限从 `1` 到 `12` 均不越界；
|
||
- 第一级有接受项时评估次数不超过六且第二级未运行；
|
||
- 第一级失败时才进入第二级，总尝试不超过十二；
|
||
- 同一窗口原始几何分析只执行一次；
|
||
- 前进、倒车、非对称窗口和联合多事件区域；
|
||
- 导数认证仍拒绝内部尖点或反向曲线；
|
||
- 相同请求运行两次得到相同候选、状态、坐标和报告。
|
||
|
||
### 11.2 集成验收
|
||
|
||
Task 8 仍需满足：
|
||
|
||
```text
|
||
Straight -> NotNeeded
|
||
SingleTurn -> Complete
|
||
LargeHeadingChange -> Complete
|
||
SBend -> Complete or PartialImprovement
|
||
RectangleDetour -> Complete or PartialImprovement
|
||
MultiObstacleDetour -> Complete or PartialImprovement
|
||
ReverseGearSwitch -> Complete, PartialImprovement, or NotNeeded
|
||
```
|
||
|
||
同时验证原始基线发布、全局回滚、取消、两区域反向处理与正向报告、旧平滑方法隔离以及完整路径覆盖。
|
||
|
||
## 12. 实施范围
|
||
|
||
预期生产修改限制为：
|
||
|
||
- `LocalG2CandidateBuilder.cs`：分离进入/离开尺度、有限配置和候选层次；
|
||
- `LocalG2CandidateGeometry.cs`：仅在需要承载内部诊断信息时增加内部只读元数据；
|
||
- `LocalG2CandidateEvaluator.cs`：区域内原始窗口分析缓存和分层评估支持；
|
||
- `LocalG2PreSmoothingPipeline.cs`：第一级/第二级控制和实际评估数量报告；
|
||
- Task 3 候选验证与 Task 8 集成/服务验证脚本。
|
||
|
||
`LocalG2WindowPlanner.cs` 的 Task 2 代表目标覆盖保持不变。不得修改 Hybrid A*、车辆模型、SQP、旧平滑算法、比较默认方法、安全阈值或 collision/clearance 行为。
|
||
|
||
## 13. 设计决策摘要
|
||
|
||
1. 删除软位置锚点候选；所有 primitive 边界坐标恢复为硬锚点。
|
||
2. 内部节点按左、右相邻实际弧长得到独立基础尺度。
|
||
3. P0/P1/P2 是有限、确定性配置，不使用在线优化器。
|
||
4. 正常路径最多评估六个候选；只有全部失败才扩展到十二个。
|
||
5. 当前启用层内选最优；第一级成功时不进入第二级。
|
||
6. 同一窗口原始分析只计算一次，但每个候选仍执行完整安全验证。
|
||
7. 新候选族必须先通过真实 `SingleTurn` 隔离门禁，再允许修改共享生成器。
|
||
8. 性能以候选/分析次数硬上限和相对 P95 合并门禁控制，不使用生产墙钟超时。
|
||
9. 任何安全或质量阈值都不因恢复设计而改变。
|