地面路径重构失败，留下一些教训

.agents/skills/nw-api/SKILL.md

@@ -16,7 +16,9 @@ description: Navisworks API 开发助手，用于开发 Navisworks 插件。功
 | NET API | `doc/navisworks_api/NET/documentation/NET API.chm` | CHM 帮助文件 |
 | NET API HTML | `doc/navisworks_api/NET/documentation/NetAPIHtml/` | HTML 文档 |
 
-**HTML 文档入口**: `doc/navisworks_api/NET/documentation/NetAPIHtml/html/index.html`
+**推荐导航入口**: `doc/navisworks_api/NET/documentation/NetAPIHtml/index.html`
+
+**原始 HTML 文档入口**: `doc/navisworks_api/NET/documentation/NetAPIHtml/html/index.html`
 
 ### API 文档搜索方法
 

AGENTS.md

@@ -361,19 +361,37 @@ var rotation = new Rotation3D(qw, qx, qy, qz); // 错误
 
 ## 5. 开发原则
 
-### 5.1 不向后兼容
+### 5.1 彻底禁止 fallback
 
-项目只针对 Navisworks 2026。不要写旧版本兼容代码。
+这是当前项目的第一编码原则，优先级高于其他“先跑起来”的考虑。
 
-### 5.2 不要随意加 fallback
+不允许出现以下行为：
 
-不要为了“先跑起来”就：
+- 新姿态链失败时，静默退回旧姿态链
+- 新变换链失败时，静默退回旧变换链
+- 正确姿势/正确位置/正确尺寸语义拿不到时，用“差不多”的旧值、缓存值、默认值顶上
+- 只打印一条 warning，然后继续使用错误语义把流程跑完
+
+尤其禁止这类做法：
 
 - 偷偷退回旧 `yaw`
 - 偷偷用硬编码 `Z-up`
 - 偷偷在错误时给默认值掩盖问题
+- 偷偷在新链失败时自动掉回旧链
+- 读不到当前实际几何旋转时，回退到 `_trackedRotation`
+- 读不到当前真实姿态时，回退到 `referenceRotation`
+- 读不到当前显示姿态时，回退到 `ModelItem.Transform`
 
-如果完整姿态链失败，应优先暴露问题并修根因。
+正确做法只有两种：
+
+1. 在进入新链前把前置条件补齐
+2. 直接暴露失败并修根因
+
+不允许把“旧链兜底”当成正式实现的一部分。
+
+### 5.2 不向后兼容
+
+项目只针对 Navisworks 2026。不要写旧版本兼容代码。
 
 ### 5.3 临时补丁不是正式实现
 

doc/working/2026-04-08-ground-remove-fragment-dependency-plan.md

@@ -0,0 +1,136 @@
+# Ground 去 Fragment 依赖实施方案
+
+更新时间：2026-04-08
+
+## 1. 这份方案现在只解决什么
+
+只解决一件事：
+
+- `Ground + 真实物体` 主链里，尽量去掉 `fragment` 参考姿态依赖
+
+只允许改动：
+
+- `PathAnimationManager.cs`
+- 必要时补少量日志
+
+明确不做：
+
+- 不新建大范围工具链
+- 不改 `Hoisting`
+- 不改 `Rail`
+- 不重写 `ModelItemTransformHelper`
+- 不删除 `RealObjectReferencePoseResolver`
+- 不做“整项目去 fragment”
+
+这份方案的目标是：**缩小修改范围，先把 Ground 主链收干净。**
+
+---
+
+## 2. 当前已确认的事实
+
+1. `Ground` 的变换更适合走最简单的宿主增量法：
+   - 宿主旋转增量
+   - 宿主平移增量
+2. `Ground` 这条链不应该再扩散 `local/reference/fragment` 概念。
+3. `fragment` 现在的问题，不在于“所有地方都要立刻删”，而在于：
+   - Ground 主链还会读它
+   - 导致姿态来源不稳定
+
+---
+
+## 3. 只保留的改造目标
+
+这轮只保留 3 个具体目标：
+
+1. `Ground` 初始化时，不再优先读 fragment 参考姿态
+2. `Ground` 平面姿态求解时，不再走 fragment 参考旋转入口
+3. `Ground` 不再允许 fragment planar fallback
+
+只要这 3 点做到，就算这一轮完成。
+
+---
+
+## 4. 当前 Ground 需要处理的入口
+
+### 4.1 初始化入口
+
+当前重点看：
+
+- `SyncTrackedRotationToObjectReference(...)`
+
+要求：
+
+- 当 `PathType == Ground` 且是真实物体时
+- 不再去走 `TryCaptureRealObjectReferenceRotation(...)`
+- 直接改用当前实际几何姿态，或现有非 fragment 入口
+
+### 4.2 平面姿态求解入口
+
+当前重点看：
+
+- `TryGetRealObjectReferenceRotation(...)`
+- `TryCreateReferenceBasedRealObjectPlanarPoseSolution(...)`
+
+要求：
+
+- `Ground` 不再从这里拿 fragment 参考旋转
+- `Ground` 单独走非 fragment 的姿态来源
+
+### 4.3 fallback 入口
+
+当前重点看：
+
+- `ShouldAllowFragmentPlanarFallback(PathType pathType)`
+
+要求：
+
+- `Ground` 改成和 `Hoisting` 一样，不再允许 fragment planar fallback
+
+---
+
+## 5. 实施顺序
+
+只按下面顺序做，不扩展：
+
+1. 先改 `Ground` 初始化入口
+2. 再改 `Ground` 平面姿态求解入口
+3. 最后关掉 `Ground` 的 fragment fallback
+
+每一步都要求：
+
+- 先看日志
+- 只改 `Ground`
+- 不顺手改别的路径
+
+---
+
+## 6. 验证标准
+
+这轮不追求“大而全测试矩阵”，只看 3 条：
+
+1. 起点
+   - `Ground + 真实物体` 到起点后不再读 fragment 姿态
+
+2. 逐帧
+   - `Ground` 播放时姿态来源不再依赖 fragment
+
+3. fallback
+   - `Ground` 关闭 fragment fallback 后，主链要么成功，要么明确报错
+   - 不允许再偷偷回退
+
+---
+
+## 7. 当前停止线
+
+如果做到下面这句话，就先停：
+
+- **Ground 主链不再依赖 fragment，但 Hoisting / Rail / 通用参考姿态系统暂时不动。**
+
+不要在这一轮里再继续追求：
+
+- 抽象统一工具类
+- 清理全部 reference/local 命名
+- 一次性删光 fragment 代码
+- 统一三类路径的所有姿态入口
+
+这些都属于下一轮的事。