ParkingRobot/docs/superpowers/specs/2026-08-01-local-g2-split-derivative-scale-recovery-design.md

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. 失败证据与根因

旧软锚点设计规定：

softOffset = min(0.05 m, 0.5 × MaximumDeviationMeters)

默认配置产生 0.05 m 法向位移。隔离可行性探针对真实 SingleTurn 场景生成了三个非零偏移候选；三个候选均被未修改的 CurvatureExceeded 门槛拒绝。候选曲率范围分别为：

[-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，内部节点左右两段共用该尺度。修订后，一个节点具有：

IncomingDerivativeScale
OutgoingDerivativeScale

对片段 node[i] -> node[i+1]：

左端使用 node[i].OutgoingDerivativeScale
右端使用 node[i+1].IncomingDerivativeScale

路径窗口起点只需要离开尺度；窗口终点只需要进入尺度。无意义的一侧不参与曲线构造。

4.2 基础尺度

设内部节点左、右相邻的原始弧长跨度为：

L_left  = s_internal - s_previous
L_right = s_next - s_internal

基础尺度为：

IncomingBase = L_left
OutgoingBase = L_right

不再以 (L_left + L_right) / 2 同时赋给左右两侧。窗口起点的离开基础尺度等于第一个片段跨度；窗口终点的进入基础尺度等于最后一个片段跨度。

4.3 G2 条件

每个端点仍按下式构造导数：

r'  = λ T
r'' = λ² κ_geometric N

在内部节点，左右曲线使用同一位置、同一切线方向 T 和同一几何曲率 κ_geometric，但允许 λ_in != λ_out。因此：

• 位置连续；
• 单位切线方向连续；
• 几何曲率连续；
• 满足 G2；
• 不保证参数一阶导数向量相等；
• 不保证参数二阶导数向量相等。

这种差异是设计自由度，不是接缝错误。路径输出仍按物理弧长重新采样和分析，不依赖 Hermite 参数速度连续。

5. 有限尺度配置

内部节点使用三个确定性配置：

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 上测量。

性能门禁为：

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 仍需满足：

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. 任何安全或质量阈值都不因恢复设计而改变。