登记运动估计实验阶段

docs/superpowers/plans/2026-08-17-web-model-sdk-portal-roadmap.md

@@ -10,6 +10,8 @@ readiness, not by the number of models mentioned in the catalog.
 
 ## 当前优先级（2026-09-19 证据更新）
 
+**2026-09-23 运动估计 Spike：** Tracking 本地 `0.2.0-rc.2` 候选新增独立 `web-sdk-pp-tracking/motion` 子入口和 `/motion.html` 实验页，比较纯平移、稀疏光流与特征匹配。合成 Node 基准中 640×360 p95 约为 15.5/71.8/191.1 ms，成功率约 41.7%/33.3%/41.7%，复杂运动与歧义纹理均显式失败；当前质量和验证矩阵不足以自动接入 BoT-SORT，继续保留外部矩阵契约、ByteTrack 默认和线上 rc.1。见[阶段回执](../../../reports/tracking/2026-09-23-motion-estimation/README.md)。不扩展视频/摄像头、手机、Worker、GPU/NPU、Safari/Firefox 或 Workflow。
+
 **2026-09-22 rc.1 已发布：** Tracking `0.2.0-rc.1` 已接入 BoT-SORT 根工厂、严格运动类型、四算法 Demo 和版本化运动序列导入导出，见[集成回执](../../../reports/tracking/2026-09-22-botsort-integration/README.md)及[发布回执](../../../reports/tracking/2026-09-22-botsort-integration/release-receipt.md)。SDK PR #6 与门户 PR #50 已合并；不可变标签、GitHub Release、npm `next`、provenance 和线上 Demo 均已回读，`latest` 保持 0.1.0。下一阶段设计可选浏览器自动运动估计，先验证矩阵质量、失败策略和总成本；不扩展视频/摄像头、手机或 Workflow。
 
 **2026-09-22 外部运动矩阵核心完成：** Tracking 同包本地 `0.2.0-rc.0+botsort-core.1` 已实现严格帧/时间/矩阵契约、显式失败和可选外观融合；208项测试、候选双格式/类型消费、完整05浏览器及原Demo回归通过，见[阶段回执](../../../reports/tracking/2026-09-22-botsort-core/README.md)。固定七段5316帧三配置各运行两次，轨迹逐字对齐前期探针，CMC/CMC+外观IDF1仍54.5850%/55.3487%，09仍退步。仅平移消融也退步，后续估计器须验证近静止策略，当前不调参或替换默认。下一阶段将候选接入公开根工厂、版本/manifest、四算法双语Demo和导入导出，再做发布验收；本轮无远程发布。自动图像估计、视频/摄像头和Workflow继续独立后置。以下“下一步”为历史，以本段为准。

docs/superpowers/plans/2026-09-13-pp-detection-multi-model-roadmap.md

@@ -4,6 +4,8 @@
 
 **目标：** 明确 PP-Detection 单 SDK 的模型边界，并完成下一阶段 2D 检测模型兼容性评估，选择一个有证据支持的候选进入后续移植。
 
+**2026-09-23 Tracking 运动估计更新：** 独立 `motion` 子入口和实验 Demo 已进入本地 `0.2.0-rc.2` 候选；三算法合成结果证明纯平移较快，但 640×360 成功率仅约 41.7%/33.3%/41.7%，p95 约 15.5/71.8/191.1 ms，复杂运动和歧义纹理需失败。当前不自动接入 BoT-SORT、不改变 ByteTrack 默认或线上 rc.1，见[阶段回执](../../../reports/tracking/2026-09-23-motion-estimation/README.md)。这仍属于 Tracking 单 SDK，不是门户 Workflow。
+
 **2026-09-22 Tracking集成更新：** [本地rc.1回执](../../../reports/tracking/2026-09-22-botsort-integration/README.md)完成 BoT-SORT 公开根入口、四算法Demo和完整运动导入导出，保持 ByteTrack 默认与独立SDK边界。220项测试、实际包消费、18组桌面浏览器流程及固定输入结果对齐通过，09退步保留。下一步是候选预发布及线上回读，再设计浏览器自动运动估计；本轮无远程写入，不扩展媒体、手机和Workflow。后文早期“下一步”保留为历史。
 
 **2026-09-22 Tracking核心更新：** [外部运动矩阵候选](../../../reports/tracking/2026-09-22-botsort-core/README.md)已实现并通过208项测试、候选包消费及桌面浏览器验收。七段5316帧三配置两次输出一致且对齐前期研究，CMC收益与09退步都保留；未将第四算法写入公开清单。下一阶段为根工厂、版本/manifest、四算法Demo与导入导出的公开集成和发布验收；本轮不发布。单任务同包/独立SDK边界不变，图像估计、媒体与Workflow仍后置。

docs/superpowers/specs/2026-09-23-tracking-motion-estimation-design.md

@@ -0,0 +1,129 @@
+# 浏览器运动估计 Spike 设计
+
+日期：2026-09-23。层级：单 SDK 实验能力。状态：已获用户批准，待实施。关联 SDK：`web-sdk-PP-Tracking`。
+
+## 背景与决策
+
+PP-Tracking 当前的 BoT-SORT 接口接收调用方提供的相机运动矩阵。它不会从图片、视频或摄像头自动估计运动。本阶段先建立独立的运动估计实验入口，用相邻帧验证浏览器端估计是否值得进入后续跟踪流程，再决定是否扩展 BoT-SORT。
+
+首版只验证 Windows 11、Chromium 153、CPU/main 环境。它是实验能力，不能写成手机、Worker、GPU、NPU、Safari 或 Firefox 的兼容承诺，也不改变当前 `0.2.0-rc.1` 的稳定行为。
+
+## 目标
+
+- 接收相邻图像帧，输出可审计的平移或仿射运动结果。
+- 在同一组输入上比较纯平移基线、稀疏光流和特征匹配的质量、耗时与失败率。
+- 记录输入帧身份、矩阵、置信度、内点数、残差、阶段耗时和失败原因，便于复现和评估。
+- 为 Demo 提供独立实验页面或实验面板，明确结果不会自动注入默认跟踪流程。
+- 用合成场景和少量有许可的真实帧建立可重复的验证证据。
+
+## 非目标
+
+- 不自动替换或修改 BoT-SORT 的默认运动输入，也不为失败结果静默补造恒等矩阵。
+- 不实现完整视频播放器、摄像头调度、录制、转码或上传服务。
+- 不声明手机、Web Worker、WebGPU、NPU/WebNN、Safari、Firefox 或跨浏览器支持。
+- 不在本阶段接入多 SDK Workflow、门户组合流程或其他 SDK 的推理 runtime。
+- 不把实验结果发布为 stable/latest；若需要分发，只能使用单独的实验标签并保留限制。
+
+## 候选算法与比较顺序
+
+### 纯平移基线
+
+以相邻帧的稳定特征或亮度变化估计 `dx/dy`，输出二维平移矩阵。它实现简单、包体和耗时最低，适合作为失败率和收益的基线；无法表达缩放、旋转和一般仿射变化。
+
+### 稀疏光流
+
+在前一帧选取角点，在当前帧追踪这些点并用鲁棒拟合得到平移或仿射矩阵。它适合短时间、纹理充足的小到中等相机运动；低纹理、遮挡、大位移和快速亮度变化可能导致匹配不足或数值不稳定。
+
+### 特征匹配可行性对照
+
+使用可在浏览器 CPU/main 运行的特征描述与匹配方案评估大位移能力。它可能提高大位移成功率，但会增加包体、预处理和匹配耗时。本阶段只要求证明可行性与代价，不承诺将其作为默认算法。
+
+比较顺序固定为：纯平移基线 → 稀疏光流 → 特征匹配对照。每个算法必须使用同一输入集、相同图像尺寸和相同计时口径。
+
+## 实验接口
+
+实现可以在最终代码中拆分模块，但语义必须等价于以下框架：
+
+```ts
+type MotionEstimateInput = {
+  previous: ImageData | VideoFrame
+  current: ImageData | VideoFrame
+  imageSize: { width: number; height: number }
+  frameId: number
+  timestampMs: number
+}
+
+type MotionEstimateResult = {
+  status: 'estimated' | 'identity' | 'failed'
+  matrix: AffineMatrix
+  confidence: number
+  inlierCount: number
+  residual?: number
+  timings: {
+    preprocessMs: number
+    estimateMs: number
+    totalMs: number
+  }
+  reason?: MotionEstimateFailureReason
+}
+```
+
+具体输入类型、导出名称和矩阵字段可以在实施计划中微调，但必须遵守以下契约：
+
+- 两帧尺寸必须一致，宽高为正整数；`imageSize` 必须与实际输入一致。
+- `frameId` 和 `timestampMs` 必须是有限数；相邻帧关系必须可追溯。非递增或跳过的帧要返回明确输入错误，不得继续估计。
+- 输入可以是 `ImageData` 或 `VideoFrame`，实现必须声明实际支持的类型。若消费方把 `VideoFrame` 的所有权交给估计器，估计器负责在完成后关闭；若不拥有所有权，必须文档化由调用方关闭，不能重复关闭。
+- `estimated` 只表示通过质量门限的估计；`identity` 只允许调用方或明确的静止基线策略显式选择，不能把算法失败伪装成 identity。
+- `failed` 必须带有稳定的失败原因；失败不推进任何内部状态，不影响下一次独立调用。
+- 不得静默切换算法、来源或输入帧。矩阵的坐标系、行列布局和作用方向必须在 API 文档及导出数据中固定。
+- 置信度、内点数和残差没有可靠值时应省略或标记未知，不得填充常数。
+- 首选无状态纯函数；如果为性能引入可复用上下文，必须有显式 `reset`/`dispose`，并证明输入序列不会污染下一次实验。
+
+建议的失败原因枚举为：`invalid-input`、`frame-order`、`size-mismatch`、`unsupported-input`、`insufficient-texture`、`insufficient-matches`、`numerical-instability`、`quality-threshold` 和 `runtime-error`。最终实现不得使用含义不清的未分类状态或空字符串代替这些原因。
+
+## BoT-SORT 边界
+
+实验入口与 `createTracker({ algorithm: 'botsort' })` 解耦。实验页面可以把估计结果显示为回执，并提供与外部矩阵的并排比较；默认播放、导出和当前公开 API 继续要求调用方显式提供运动信息。只有在 Spike 通过质量、耗时和失败门限，并完成新的 API 设计与回归验证后，才另行评估自动接入。
+
+## Demo 设计
+
+沿用 PP-Tracking 当前品牌栏、左侧控制区、中央画面和可折叠详情的布局；不把实验面板做成门户目录。建议提供独立 `/motion` 入口或等价实验页，包含：
+
+- 输入帧对、尺寸、帧号和时间戳；
+- 算法选择与运行/重置控制；
+- 当前矩阵、状态、置信度、内点数、残差和三段耗时；
+- 纯平移、光流和特征匹配的同组对比表；
+- “实验能力，结果不会自动接入默认跟踪”提示；
+- 原始输入、估计结果和失败原因的 JSON 导出。
+
+页面必须保留中文默认、英文切换、390px 宽度不横向溢出，并使用标准 `data-sdk-runtime-info`、`data-sdk-timing` 和状态复位标记。实验结果与当前四算法 Demo 的 tracking 状态分开，切换实验算法不会重置或改写已有跟踪序列。
+
+## 验证矩阵
+
+### 输入场景
+
+1. 合成纯平移：水平、垂直、小位移、中位移和大位移。
+2. 合成缩放、旋转和一般仿射变化。
+3. 静止帧、低纹理、重复纹理、局部遮挡和前景运动。
+4. 亮度变化、轻度噪声、裁剪边界和尺寸不一致。
+5. 少量真实公开视频帧或已有合法本地样本；记录来源、日期和许可，禁止把未经核实的素材纳入发布证据。
+
+### 指标
+
+- 矩阵参数误差：平移、尺度、旋转和仿射项分别统计绝对误差。
+- 跟踪影响：把矩阵用于离线框预测时记录预测框中心误差和 IoU 变化；不把该离线结果当成自动接入证据。
+- 成功率、失败率和各失败原因占比。
+- `preprocessMs`、`estimateMs`、`totalMs` 的 p50/p95；首次运行与重复运行分开。
+- 不同分辨率下的峰值内存、输入像素数和包体增量。
+
+### 环境边界
+
+记录操作系统、浏览器版本、CPU、分辨率、输入类型和日期。当前只形成 Windows 11 + Chromium 153 + CPU/main 的 dated evidence；任何其他环境必须标为未验证。
+
+## 发布与治理
+
+Spike 通过前不改 `latest`、稳定版本或门户兼容承诺。若需要 npm/GitHub Release，使用独立预发布标签（例如后续 `0.2.0-rc.2`），在 README、manifest、Demo 和变更记录中标注实验状态、已验证环境和已知限制。门户只登记“运动估计实验”及证据链接，不把它写成 PP-Tracking 默认能力。
+
+## 通过门槛与后续决策
+
+实施完成后必须同时提供：可复现输入集、三算法对比报告、浏览器实验页面、运行时和计时证据、失败用例、包体/内存记录以及 API/许可说明。只有当结果满足预先记录的质量与耗时门槛、失败原因可解释且没有静默降级时，才进入下一份“自动运动接入 BoT-SORT”设计；否则保留为独立实验，并记录不接入的原因。