chore: initial commit — import worldmodel workspace (plans/, research/)

2026-05-20 21:43:57 +08:00
commit bec8a9a4a3
98 changed files with 44128 additions and 0 deletions
@@ -0,0 +1,167 @@
+# Changelog
+
+> PRISM 项目变更日志。遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 风格,版本号遵循 [SemVer](https://semver.org/lang/zh-CN/) (MAJOR.MINOR.PATCH)。
+>
+> - **MAJOR** (1.x→2.x): 架构层面不向后兼容的改动 (例如 schema 变更、四层模型改动)
+> - **MINOR** (1.0→1.1): 新增章节/管线/特性,向后兼容
+> - **PATCH** (1.1.0→1.1.1): 拼写、排版、bug 修复
+
+---
+
+## [2.0.0] — 2026-05-17
+
+### Added (新增)
+- **第 19 章 `19_v2_brain_inspired_upgrade.md`** — PRISM 2.0 仿脑空间记忆架构升级
+  (11 个仿脑模块：GridMetric / DG Orthogonalizer / PredictiveLayer / CA3 Verifier /
+  ExplicitReplay / Reconsolidation / SalienceGate / BoundaryDistance /
+  SuccessorRepr / LandmarkRelative / EpisodicBinding)
+- **脑科学研究文档 `research/human_spatial_memory.md`** — 人类空间记忆神经科学机制综述
+  (位置细胞 / 网格细胞 / 头方向细胞 / 边界细胞 / 模式分离与完成 /
+  系统巩固 / 预测编码 / 再巩固 / 继任表征 / 物体向量细胞)
+- **P0 模块**: GridMetric (网格细胞式跨环境度量泛化) + DG 正交化 (模式分离) + PredictiveLayer (预测编码)
+- **P1 模块**: CA3 双确认 + ExplicitReplay + Reconsolidation + SalienceGate + BoundaryDistance
+- **P2 模块**: SuccessorRepr + LandmarkRelative + EpisodicBinding
+- 四层架构更新为包含 GridMetric 层 + PredictiveLayer
+- Pipeline A/B/C/D 全部更新为 v2.0 兼容流程
+- README 新增 🧠 阅读路径
+
+### Changed (变更)
+- **L2 绝对坐标度量 → GridMetric 周期性编码** (L2 仍保留作为 fallback)
+- **被动写入 → 预测驱动写入** (PredictiveLayer: 只在预测失败时写入)
+- **写放大降低 ~99%** (SalienceGate + PredictiveLayer 联合效应)
+- **Pipeline D 一次性 batch → 多轮压缩重播巩固** (ExplicitReplay)
+- **直接覆写 → 再巩固协议** (解锁→更新→重新封印)
+
+---
+
+## [1.5.0] — 2026-05-16
+
+### Added (新增)
+- **第 18 章 `18_lyra_inspirations.md`** — Lyra 2.0 启发的 3 大设计原则
+  (路由 vs 内容分离、keyframe-based 内容真源、self-augmentation 巩固)。
+- **§ 2.7b L2-L3 数据流:路由 vs 内容** —— 在 [`02_architecture.md`](02_architecture.md)
+  新增小节,阐明 L2 几何降级为"路由信号",L3 内容来自 L1 高保真 keyframe。
+- **§ 3.2.1 `KeyframeEvidence` dataclass** —— 在 [`03_data_schema.md`](03_data_schema.md)
+  新增字段定义、存储预算估算与 `SpatialNode` 的向后兼容扩展。
+- **§ 6.6b v1.5 新写法:keyframe-based L3 内容更新** —— 在
+  [`06_pipeline_C_online_perception.md`](06_pipeline_C_online_perception.md)
+  新增 keyframe 采样、压缩与 L3 写入流程。
+- **§ 7.13.1 Self-Augmentation 巩固训练算法** —— 在
+  [`07_pipeline_D_consolidation.md`](07_pipeline_D_consolidation.md)
+  新增训练范式 (随机视角扰动 + 重渲染监督, $p_{\text{aug}}=0.7$)。
+- **同档对比综述 [`comparison.md`](comparison.md)** —— 379 行,8 项目对比
+  (ConceptGraphs / HOV-SG / OK-Robot / Clio / Hydra / SemanticFusion / Voxblox++ / OpenScene)
+  + 4 个 Pipeline 维度矩阵。
+- **评分文档** —— [`rate.md`](rate.md) 技术难度 62/100、
+  [`rate_industry.md`](rate_industry.md) 行业贡献 48/100。
+- **Lyra 2.0 论文译读** —— [`research/lyra2_review.md`](../../research/lyra2_review.md)
+  作为本次升级的外部依据。
+
+### Changed (变更)
+- **L2 几何在 L3 写入中降级为"路由信号"**:L3 内容不再由 L2 voxel 反推几何/语义,
+  而是直接挂载 L1 高保真 keyframe 作为唯一真源。
+- **`SpatialNode` 新增 `keyframe_evidence: List[KeyframeEvidence]` 字段**
+  (向后兼容,默认空列表,旧 schema 数据无须迁移)。
+- **巩固期训练范式增加 self-augmentation**:$p_{\text{aug}}=0.7$
+  的概率对采样视角施加随机扰动,以重渲染 keyframe 作监督信号,提升 L4 语义稳健性。
+
+### References (引用与启发)
+- 上述设计借鉴 NVIDIA *Lyra 2.0: Explorable Generative 3D Worlds*
+  (arXiv:2604.13036),§ 3.2(routing-by-geometry)与 § 3.3(keyframe-augmented training)。
+- 工程模板对标:**ConceptGraphs** (ICRA 2024)、**HOV-SG** (RSS 2024)、
+  **OK-Robot** (FAIR 2024)、**Clio** (RA-L 2024)。
+
+---
+
+## [1.2.0] — 2026-05-16
+
+### Added (新增)
+- **第 15 章 缩略语表 (`15_glossary.md`)**:9 个分组、约 125 条术语,A–I 主题化排列,
+  采用 LaTeX `longtable` + `booktabs` 跨页排版。
+- **第 16 章 文档与代码统计 (`16_stats.md`)**:由 [`tools/gen_stats.py`](tools/gen_stats.py) 在每次构建时自动生成,
+  含总览表、各章字数/代码分布、按语言的代码块统计。
+- **第 17 章 变更日志 (`17_changelog.md`)**:由 [`tools/gen_changelog_chapter.py`](tools/gen_changelog_chapter.py) 从本 `CHANGELOG.md` 自动注入 PDF。
+- **版本管理**:新增 [`VERSION`](VERSION) 文件作为单一权威版本号,封面/页眉/PDF 元数据自动注入。
+- **构建工具链**:
+  - [`tools/render_mermaid.py`](tools/render_mermaid.py):mmdc 把 mermaid 块预渲染为 PNG,带 hash 缓存与失败降级。
+  - [`tools/gen_stats.py`](tools/gen_stats.py):构建期统计脚本。
+  - [`tools/gen_changelog_chapter.py`](tools/gen_changelog_chapter.py):本 CHANGELOG → 章节 md 转换。
+
+### Changed (变更)
+- **全部 ASCII 框线图 → Mermaid 图 (21 个)**:
+  - flowchart 14 个 (00, 02, 04, 05, 06, 07, 10, 11, README)
+  - quadrantChart 2 个 (01 能力象限、12 风险矩阵)
+  - timeline / sequenceDiagram / stateDiagram 各 1 (08 章)
+  - gantt 1 个 (09 路线图)
+- **构建管线 [`build_book.sh`](tools/build_book.sh)** 新增 4 个阶段:
+  - `1a` 生成统计章节
+  - `1b` mermaid → PNG 预渲染
+  - **后处理 LaTeX**:把 pandoc 默认的 `@{}lll@{}` 自然宽 longtable 自动改写为等宽 `p{w}` 列,
+    消除大量 `Overfull hbox` 警告
+- **LaTeX 模板 [`book_template.tex`](tools/book_template.tex)**:
+  - 启用 `\XeTeXlinebreaklocale "zh"` 让 CJK 字符可逐字断行
+  - 引入 `fvextra` 让代码块自动换行 (`breaklines=true, breakanywhere=true`)
+  - 引入 `xurl` 让长 URL 任意位置断开
+  - 引入 `hyphenat[htt]` 让 monospace (`\texttt{...}`) 长下划线文件名可断行
+  - `\sloppy + \emergencystretch=3em` 全局抗溢出
+- **Mermaid 图嵌入策略**:`\includegraphics` 同时约束 `width=0.92\linewidth, height=0.82\textheight, keepaspectratio`,
+  极端长宽比的图也不会冲出 A4 页面
+
+### Fixed (修复)
+- 修复 ~13 个 emoji/特殊字符无字体显示 (`🔬 🧑 💼 → ↔ ① ✓` 等),
+  在 [`build_book.sh`](tools/build_book.sh) 的 `EMOJI_MAP` 中扩展替换映射。
+- 修复 mermaid `quadrantChart` 标签因 `()` `·` `.` 等字符报 Lexical error。
+- 修复 mermaid `sequenceDiagram` label 含 `;` / `/` / `[v]` 等字符报 Parse error。
+- 修复 mermaid `timeline` 单行多冒号导致解析失败,改用 `section` 分组。
+- 修复极端纵向 mermaid 图溢出 A4 (高度 2700+ px) → 添加 height 约束。
+- 修复代码块长注释溢出页宽 (最严重 167pt) → 用 `fvextra` 自动换行。
+- 修复表格内长字符串/中文不换行溢出 → CJK locale + hyphenat 双管齐下。
+- 修复第 16 章统计表 7 列窄列溢出 → 使用 28% + 6×10% 等宽列布局,章节名用短形式 `ch00`–`ch16`。
+
+### Stats (统计)
+- 章节总数: **18** (README + 17 章)
+- 中文字数: **~19,000**
+- 代码行数: **~2,500** (Python 1,750 + 其他)
+- Mermaid 图数: **21**
+- PDF 页数: **165** (含封面)
+
+---
+
+## [1.1.0] — 2026-05-09
+
+### Added
+- 拆分 `robot_brain_spatial_memory.md` (主方案 v1.0) 为 14 个独立章节 (`00_overview.md` ~ `14_mvp.md`),
+  目录化为 `plans/PRISM/`。
+- 增加章节级元信息 (版本/估计阅读时间/关键收获)。
+- 引入 [`tools/build_book.sh`](tools/build_book.sh) + [`tools/book_template.tex`](tools/book_template.tex) 出版级 PDF 构建工具链
+  (pandoc → XeLaTeX → pypdf 合并 cover)。
+- 添加 ArUco 公共原点对齐方案 (R1.2 缓解)。
+- 添加 LLM Agent 任务接口示例 (T3 取遥控器剧本)。
+
+### Changed
+- L2 默认稠密表示从纯 OctoMap 改为 **OctoMap + TSDF + 3DGS** 三件套。
+- 重定位策略从一段式 ICP 改为 **CLIP 粗匹配 + ICP 精配准** 两段式。
+
+### Fixed
+- 修复多 session 间坐标系不一致问题 (强制 ArUco 兜底)。
+
+---
+
+## [1.0.0] — 2026-04-22
+
+### Added
+- PRISM 主方案首版 (`robot_brain_spatial_memory.md`):
+  - 四层空间记忆架构 L1–L4
+  - 两路输入 (iPhone RoomPlan 离线 + ZED 2i 在线)
+  - 四条管线 (A 离线建图 / B 重定位 / C 在线感知 / D 巩固)
+  - `SpatialNode` / `SpatialEdge` / `SpatialMemory` 统一 schema
+
+---
+
+## [Unreleased]
+
+### Planned (待规划)
+- v1.3:接入 M-JEPA / DreamerV3 的桥接代码 (目前仅为接口设计)
+- v1.3:扩展评测体系到 HM3D-Semantic / OpenEQA 公开 benchmark
+- v1.3:多机器人协同的初步设计
+- v2.0:原型实现 (从文档到能跑的 ROS 2 节点)