这份文档回答一个问题：为什么是"导览"，而不是"更好的图"？
它和 principles.md 形成对仗：principles 管"架构职责怎么分"， 本文管"理解体验为什么这样设计"。导览相关的功能改动若违反本文的约束， 应当被打回——这是设计裁判，不是营销文案。
可视化工具的隐含假设是"理解 = 看一张更好的图"。这个假设违反两个被反复验证的认知事实：
1. 工作记忆只有 4±1 个组块（Cowan, 2001，对 Miller 7±2 的修正）。 一张 22 个 feature 节点的画布，在生理上就不可能被"看懂"，只能被"看到"。 高亮、淡出、聚焦都是在地图范式内做减法——天花板极低，因为瓶颈不在画面，在人脑带宽。
2. 人通过"按顺序走一条路"理解复杂系统，不通过"看全局"（Kintsch 建构-整合模型）。 理解是增量地把新命题挂到已有心智模型上的过程——一次一个命题，前一步是后一步的脚手架。 这就是为什么人能轻松跟完一部两小时的电影（几百个事件！），却看不懂一张 22 节点的图： 电影替你做了序列化，每一刻只喂一个组块，且用因果链做钩子。
结论：地图（map）和旅程（journey）是两种东西。突破方向不是优化地图， 而是让图退役为舞台，在上面铺一条有镜头、有因果叙事的引导路径。 理解的单位从"一张图"变成"一次导览"。
每条都有认知科学依据，每条都已落成工程约束（见第三节映射表）。
新手面对陌生系统的第一需求不是细节，是 schema——"这东西大概是个什么形状"。 导览第一步必须给出粗糙但完整的架子（2-3 个核心 epic + 三段论主线）， 后续所有细节都有地方挂。注意：并列罗列不是 schema，有因果方向的三段论才是。 "系统包含 A、B、C、D、E 五大模块"挂不住任何东西；"先 A，然后 B，最后 C"可以。
好奇心不是天生的，是缺口造出来的。每步先抛一个具体的、有张力的问题 （"订单创建后钱还没扣——系统怎么保证用户跑不掉？"），再用节点点亮 + 叙事填上。 这是纪录片和好老师的共同手法。陈述式过渡（"接下来看支付模块"）没有缺口，等于没问。
被动阅读的留存率惨不忍睹——人只真正记住自己生成过的东西，这是教育心理学最强的 实证结论之一。导览在关键岔路口停下来让用户猜（quiz），对错都立刻看到真实答案。 猜错比猜对记得更牢（hypercorrection）。这一步把工具从"可视化"变成"理解引擎"。
静态构图（crossing minimization、node placement）优化的是地图；旅程范式下真正 重要的是相机。三条镜头纪律：
- 逐盏点亮：未到达的节点不渲染（淡化的节点依然消耗注意力预算，必须是 hidden）
- 空间稳定：布局算满图、渲染做减法——节点位置自始至终不漂移，已走过的节点 保持微弱可见，利用空间记忆当锚点
- 马提尼杯结构：先窄后宽。导览走完才解锁自由探索的全图—— 全图是毕业证书，不是教科书
最反直觉也最重要：要质疑"让人理解整个项目"这个目标本身。真实场景里没有人需要 理解整个项目；人需要回答一个具体问题（"我要改优惠券逻辑，会炸到哪里？"）。 所以除了预设的新人导览，导览的终极形态是可被任意问题实例化的渲染范式： 用户提问 → AI 即时生成一条只含相关节点的临时小径，走完即弃。 这只有"AI 持有语义"的架构给得起——静态解析出来的图做不到随时重组。
理论只有长成代码约束才可信。每条原则在 schema / 校验器 / 播放器里的着陆点：
| 认知依据 | 工程约束 | 落点 |
|---|---|---|
| 工作记忆 4±1 组块 | 整条导览 6-10 步；每步 focus ≤3 个节点 | validate-features.mjs 警告 |
| 先行组织者 | 第一步必须是骨架步：2-3 个 epic + 三段论 reveal | schema 硬约束 + 校验警告 |
| 信息缺口 | gap 必须含问号——是问题，不是陈述句 |
校验器逐步检查 |
| 生成效应 | quiz 必须先选才能揭晓，不给跳过；1-2 个，多了变考试 | 播放器交互 + 校验警告 |
| hypercorrection | wrong_note 句式："你以为 X，实际 Y——因为 Z" |
scan-tour.md 写作规范 |
| 注意力预算 | 未到达节点 hidden（不渲染），不是降透明度 |
TourMode 渲染过滤 |
| 空间记忆 | 布局算满图、渲染做减法，节点位置全程稳定 | tourLogic.ts 核心模型 |
| 叙事节奏 | reveal ≤60 字——揭晓叙事要一口气读完 | 校验器警告 |
| 马提尼杯 | 走完/退出才 fitView 全图，导览中禁用全局镜头和下钻 | GraphCanvas 播放逻辑 |
| 组块层级 | 视图档位自动跟随：全 epic 步在概览（高空），含 feature 步在功能视图（街景） | stepViewMode() |
1. "无痛"不是目标。 认知负荷理论区分三种负荷：外在负荷（烂呈现造成的，该清零）、内在负荷（问题本身 的复杂度，不可压缩）、关联负荷（构建心智模型的必要努力，砍掉它就没有学习）。 Bjork 的"必要难度"研究说得更狠：太顺滑的学习体验留存反而差。 导览要消灭的是找入口、记位置、解码布局这些垃圾痛；"思考因果"这个必要痛必须保留—— quiz 不给跳过就是这条的落地。如果用户全程无痛走完导览，大概率他什么也没记住。
2. 作者被知识的诅咒锁死。 作者永远无法模拟新手看自己项目的认知状态（Camerer 实验：被告知答案的人系统性 高估他人的知情程度，且无法靠自我提醒修正）。所以导览质量不能靠闭门设计验证， 只能靠真人实验。北极星指标：一个没见过该代码库的人，从打开导览到正确回答 第一个迁移类问题（"新增一种 X 要改哪几处"）的分钟数。对照组：同一仓库 + 原始代码 + AI 助手自由摸索。
3. 已知的未验证假设。
- 手写导览的叙事质量 ≠ AI 生成导览的质量——
scan-tour.md的产出需要按北极星指标实测 - 视图档位切换（概览→功能）的"降落感"是否自然，样本量还不够
- 按需理解（问题驱动临时小径）尚未实现，目前只有预设导览
- Cowan (2001). The magical number 4 in short-term memory. BBS 24.
- Kintsch (1998). Comprehension: A Paradigm for Cognition. （建构-整合模型）
- Ausubel (1960). The use of advance organizers. J. Educational Psychology.
- Loewenstein (1994). The psychology of curiosity. Psychological Bulletin 116.
- Slamecka & Graf (1978). The generation effect. JEP: Human Learning and Memory.
- Butterfield & Metcalfe (2001). Errors committed with high confidence are hypercorrected. JEP.
- Segel & Heer (2010). Narrative visualization: Telling stories with data. IEEE TVCG.
- Bjork (1994). Memory and metamemory considerations. （必要难度）
- Sweller (1988-). Cognitive load theory.
- Camerer, Loewenstein & Weber (1989). The curse of knowledge. J. Political Economy.