docs: replace Local G2 soft anchors with split scales

2026-08-01 08:59:42 +08:00
parent bd08a9bac6
commit c1d9549640
3 changed files with 302 additions and 8 deletions
@@ -1,7 +1,7 @@
 # 局部 G2 路径预平滑设计

 **日期：** 2026-07-30
-**状态：** 已完成方案评审，等待用户评审书面规范
+**状态：** 已完成方案评审；2026-08-01 固定锚点分离导数尺度修订等待书面复核
 **范围：** Hybrid A* 粗路径与后续 SQP 路径优化之间的局部预平滑

 ## 1. 背景与问题
@@ -225,7 +225,7 @@ r''(u_endpoint) = λ² κ_geometric N

 ### 9.3 单个曲率事件

-窗口外端点从稳定的原始圆弧读取位置、切线和曲率。原运动基元边界的航向作为内部硬边界值；其位置默认作为内部锚点，但允许按 `2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md` 在配置偏移范围内沿运动法向生成有限软位置锚点候选。跳变两侧的两个曲率值替换为一个共享的内部目标曲率。
+窗口外端点从稳定的原始圆弧读取位置、切线和曲率。原运动基元边界的位置和航向均为内部硬边界值，不允许生成位置偏移候选。跳变两侧的两个曲率值替换为一个共享的内部目标曲率。

 内部目标曲率首先按照事件左右可用长度做距离加权插值：

@@ -236,7 +236,7 @@ r''(u_endpoint) = λ² κ_geometric N
    / (left_available_length + right_available_length)
 ```

-围绕该初值生成有限候选。窗口左片段和右片段在内部锚点共享位置、切线、导数尺度和曲率，使内部连接达到 G2；在参数尺度一致时达到 C2。
+该距离加权值作为固定的内部共享曲率。有限候选只改变窗口和导数尺度，不再同时改变共享曲率。窗口左片段和右片段在内部锚点共享位置、单位切线方向和曲率，使内部连接达到 G2。按照 `2026-08-01-local-g2-split-derivative-scale-recovery-design.md`，左片段的进入导数尺度与右片段的离开导数尺度可以不同；算法不额外要求参数速度连续或参数 C2。

 方向段起点处的真实起始曲率跳变只有单侧可用空间，直接以真实起始状态为左边界、稳定运动基元状态为右边界生成候选。

@@ -245,10 +245,10 @@ r''(u_endpoint) = λ² κ_geometric N
 当窗口重叠时：

 - 合并为一个联合区域。
- 保留各运动基元边界的航向；位置按软锚点恢复设计生成有限、同配置的内部位置候选。
+- 保留各运动基元边界的位置和航向硬约束，不生成内部位置偏移候选。
 - 每个内部锚点只允许一个共享曲率值。
- 相邻五次 Hermite 片段共享位置、一阶导数和二阶导数。
- 内部共享曲率和导数尺度通过有限、确定性的候选组合选取。
+- 相邻五次 Hermite 片段共享位置、单位切线方向和几何曲率；左右参数导数长度可以不同。
+- 内部共享曲率和分离的进入/离开导数尺度通过有限、确定性的候选组合选取。

 联合处理避免先分别生成曲线再拼接所产生的新曲率接缝。

@@ -272,7 +272,8 @@ r''(u_endpoint) = λ² κ_geometric N
 - 窗口总长度
 - 左右窗口长度分配
 - 端点和内部锚点的导数尺度
- 内部共享曲率在距离加权初值附近的有限变化
+
+内部共享曲率使用第 9.3 节的距离加权值，不作为当前恢复候选维度。

 约束：

@@ -370,7 +371,7 @@ candidateCost

 ## 13. 候选选择

-不能接受第一个通过安全检查的候选。所有有限候选评估完成后，按以下规则选择：
+不能接受当前启用层中第一个通过安全检查的候选。当前层的所有有限候选评估完成后，按以下规则选择；固定锚点分离导数尺度设计允许第一级已有合格项时不启用第二级：

 1. 仅保留通过全部硬约束的候选。
 2. 仅保留达到最低质量改善门槛的候选。
@@ -1,5 +1,15 @@
 # Local G2 Soft-Anchor Candidate Recovery Design

+> **Superseded on 2026-08-01.** The mandatory feasibility gate found that all
+> prescribed non-zero `0.05 m` profiles failed the unchanged vehicle-curvature
+> gate, reaching approximately `14.86 1/m` against a `0.8333 1/m` limit.
+> Production soft-anchor work stopped with the shared builder unchanged. The
+> normative replacement is
+> `2026-08-01-local-g2-split-derivative-scale-recovery-design.md`, which restores
+> every primitive-boundary position as a hard anchor and uses independent
+> incoming/outgoing derivative scales. The evaluator de-duplication and window
+> target-coverage work completed before this failure remain valid.
+
 ## Goal

 Repair the Local G2 candidate family so that a real, same-direction curvature
@@ -0,0 +1,283 @@
+# 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. 任何安全或质量阈值都不因恢复设计而改变。