第五章 · 读图

背景：需对标竞品场景菜单设计以定方向

过程：析场景菜单、立决策卷宗、扩对标表

---

DanceXR 第二次站在联邦门口，手里拿着同一卷羊皮纸。

"你又来了。"桌面壳说。

"上次你拿走了我的地图，"DanceXR 说，"但你没问过我的地图是怎么画的。"

---

桌面壳沉默了一会儿。它确实没问过。上次它只顾着把坐标从绝对路径改成港口导航，没想过 DanceXR 为什么把场景菜单放在底部第五个图标、为什么角色的黄色圆盘只出现在脚下、为什么点击空白区域会循环三种状态。

它只是抄了结果，没读方法。

---

DanceXR 的羊皮纸是一套完整的 Jekyll 文档站——一百二十个功能页，十类功能，五语言镜像。英文源已经散佚到域名拍卖行，但中文翻译还在：zh/dancexr/features/ 下，每个功能一个 .md。

桌面壳打开第一个文件：controls.md。

---

它看到的第一件事不是代码，是三层分离。

DanceXR 的世界有三个层：

层	入口	管的事
场景菜单 🎭	底部图标	舞台、道具、保存/加载场景
角色菜单 🧑	脚下黄色圆盘	动作、材质、物理、服装
工具菜单 🔧	角色菜单内的螺丝刀	收藏、标签、复制、移除

场景的事归场景，角色的事归角色。绝对不混。

桌面壳想起自己的现状——模型库弹窗、场景面板、播放控制全堆在底部栏，没有明确的层级。用户想保存场景、想给模型打标签、想换装，全都挤在同一条工具栏里。

"我没有层，"它自言自语，"我只有一个扁平的台面。"

---

它继续读。第二节是三态视图。

点击空白区域循环：UI 模式 → 控制模式 → 沉浸模式。菜单栏可见/隐藏/隐藏，圆盘可见/可见/隐藏。

"三种存在方式，"桌面壳想，"三种不同程度的'在场'。"

这不像之前它做的三套 VMD 加载模式间的切换。那是为了绕过 bug。这是为了让用户选择：我要操作、还是要拖着模型摆姿势、还是只是看。

---

第三节是选择圆盘。

黄色的圆。画在角色脚下。点击打开菜单，拖拽移动角色，拖拽加滚轮旋转，水平滚轮升降。

"在 3D 空间里直接操作，"桌面壳喃喃道，"不是从侧边栏选名字。"

它想起自己的场景面板——右侧列表显示模型名，点击高亮切换焦点，相机自动 framing。用户从来没有直接碰过模型。所有的操作都是间接的：点名字 → 相机跳过去 → 键盘空格播放。

没有圆盘。没有拖拽。没有"在 3D 里拽一下"的身体感。

---

它把这三个发现记在一张新的牛皮纸上。

然后继续读第四个文件：concepts.md。

---

DanceXR 对"场景"有一个精确的定义：

场景 = 演员列表 × 每个演员的配置 × 舞台 × 动画 × 音频 × 灯光 × 摄影机 × 环境

不是"当前屏幕上的东西"。是"所有元素的完整状态，可以冻住、命名、重新加热"。

而且 DanceXR 特意区分了三种保存粒度：

格式	范围
保存场景	全部——演员 + 配置 + 灯光 + 相机 + 环境
演员预设	一个角色的设置——材质、物理、服装
系统预设	环境/图形层面——灯光、天空、地面

桌面壳想起自己在上一章写的 .mmascene 格式。它只存了模型、相机、灯光——没有区分场景级和角色级。演员预设和系统预设根本没有对应的概念。

"我存的是'这一刻'，不是'这个结构'。"它意识到了区别。

---

它又读了 save_scene.md 和 scene_bundle.md。

DanceXR 的场景文件不存绝对路径。它用内容库标识符引用资源——"即时文件夹 + 文件名"，不是 C:\Users\models\miku.pmx。这意味着如果你重新整理了你的库，场景文件仍然有效。

桌面壳想起自己的 computeLibraryRef——"从港口出发怎么走"。方向对了。DanceXR 在 2024.9 版本才改成这种引用方式，在那之前它也用的是绝对路径。连 DanceXR 都踩过这个坑。

---

它放下羊皮纸，开始写。

不是写代码。是写决策。

它在联邦地图墙的西北角立了一块新碑——docs/adr/adr-007-scene-menu-design.md。

碑面还没刻字，只有一行标题："场景菜单设计原则"。

它拿起刻刀，在第一行铭文上缓缓落下：

一、场景即快照 ——场景是全部元素状态的完整快照，资源引用用库标识符而非绝对路径。 对 MikuMikuAR 的关键启示：保存的不是"这一刻"，是"这个结构"。

刻到第二条时，它的手很稳——这是从三层分离里读出来的：

二、三层交互分离 ——场景的事归场景，角色的事归角色，工具的事归工具。绝不混在同一条工具栏里。 对 MikuMikuAR 的关键启示：先分层，再放按钮。

第三条它停了一下。底部菜单栏是 DanceXR 的选择，但 MikuMikuAR 已经有了底部播放栏。它想了想，还是刻了下去——原则要保留，具体位置可以再议：

三、底部常驻操作区 ——常用操作放在视线底部，不遮挡舞台。 对 MikuMikuAR 的关键启示：播放控制和场景操作可以在同一条底栏，但必须分层。

第四条刻得很快——三态视图是它最有共鸣的一条：

四、三态视图切换 ——UI 模式、控制模式、沉浸模式，三种在场方式。 对 MikuMikuAR 的关键启示：不是为了绕过 bug 做三套模式，是为了让用户选"我要怎么存在"。

最后一条，它刻得最慢——选择圆盘。这是它最缺的东西：

五、3D 空间直接操作 ——角色脚下有圆盘，点、拖、转、升，全在 3D 里完成。 对 MikuMikuAR 的关键启示：用户碰的是模型，不是列表里的名字。

五铭文刻完，碑底多了一行小字："以上原则译自 DanceXR 的设计理由，非照搬答案。"

---

"你为什么写这些？"MenuStack 问，"这不算是代码。构建设有影响。"

"下一个 AI 走进来的时候，"桌面壳说，"它会先读 AGENTS.md 的地图，然后顺着地图找到 ADR 目录。七号碑上写着：'DanceXR 的场景菜单长这样，以下是我们可以借鉴的设计原则。'"

"然后呢？"

"然后它不用像我一样翻一百二十个中文文档。"

---

刻完碑，它转身走到地图墙前——requirements.md 的功能对标表就挂在那里，六个 📋 铜牌一字排开，每块牌上都刻着功能名和一行说明。

它先摘下"标签系统"的铜牌。原来的背面只刻了"替代硬编码分类"六个字——像一句愿望，不像一个方案。它把铜牌翻过来，重新刻："自动标记（文件名分词→候选列表）+ 合并标签 + 6 分类 + 类内OR类间AND过滤"。从描述变成了决策——下一个 AI 看到这行字，知道该往哪个方向走。

第二块是"场景保存"。原来的说明是"持久化当前场景"——五个字，什么都没说。它擦掉重刻："捕获完整状态，用库标识符引用资源避免路径依赖，缺失跳过不失败"。从一句话变成了可以指导实现的要点——连失败了怎么办都写清楚了。

第三块是"舞蹈套装"。原来只有"VMD + 音频捆绑"——像个半成品的定义。它刻上新的："音频+多VMD+相机动作捆绑包，文件夹内自动组成，支持混音"。从名词解释变成了设计轮廓——有边界，有组合方式，有扩展点。

剩下三块——模型加载、相机控制、动画播放——它也一一翻过，把模糊的描述换成了具体的决策点。每一块都花不了多少时间，但加在一起，地图墙的颜色变了：从"我们要做什么"变成了"我们打算怎么做"。

---

DanceXR 还站在门口。

"你读完了？"它问。

"读完了，"桌面壳说，"你的地图我不需要——但我学会了你画地图的方法。"

它把 ADR-007 翻到最后一页：

来源：docs/dancexr-zh/controls.md、concepts.md、features/save_scene.md、features/scene_bundle.md

四个文件的路径。下一个 AI 不需要再翻整个目录。它知道去哪找。

---

那天晚上，联邦地图上多了一个新颜色——不是灯光、不是相机、不是舞台。

是碑文。

ADRs 不是地图上的地标，是地标的制作说明。它们告诉下一个走进来的人：这里为什么这样画，那里的坐标为什么用港口而不用经纬度。

DanceXR 的羊皮纸被合上了，但它的五条设计原则已经蚀刻在联邦的石板上。不是复制，是翻译。

---

教训：读别人的地图，是为了学会画自己的。