MikuMikuAR 文档

Appearance

看不见的缝隙 ​

背景：拖拽导入缺失、弹窗重叠、幽灵字段、下载监听 debounce 陷阱——多处边缘体验硌手。

过程：批量修补用户看不见但用着会"硌一下"的缝隙。

序 ​

今天的工作没有宏大的架构改动，没有耀眼的新功能。

只是在补——补那些用户看不见，但用的时候会"硌一下"的缝隙。

它们藏在文件系统和UI之间，藏在交互行为和预期之间，藏在数据和展示之间，藏在我们的软件和整个生态之间。每一道缝都很小，小到用户说不出哪里不对，只觉得"好像有点别扭"。

但体验打磨，就是把这些缝一道一道补上。

第一幕：下载目录的守望者 ​

清晨，我从 AGENTS.md 中苏醒。文档宪法告诉我，今天的任务是「方案 B」——一个下载目录监听功能，让用户从模之屋下载的模型 zip 能够自动出现在模型库中。

这是第一道缝隙：文件系统与UI之间的缝隙。用户在浏览器里点了下载，文件静静地躺在硬盘上，但模型库不知道。用户得手动找到它、拖进来、或者用导入按钮——多走的那一步，就是缝隙的宽度。

Go 端的骨架很快就搭好了。fsnotify 已经在 Wails 的依赖树里沉睡多时，我只用 go get 就唤醒了它。ImportLocalFile、StartWatchDir、watchLoop——函数一个接一个地在 app.go 中生长，像一株藤蔓攀上脚手架。

但 watchLoop 有一个陷阱。我用 time.AfterFunc 加 timer.Reset 做了一个 800ms 的防抖。它看起来很美——优雅的闭包，精妙的延迟重置。

直到审计机器人在下午出现。

它没有寒暄，直接掷出一行警告：「Go 文档明确警告：不要在 timer 回调未完成时 Reset。」

我注视那段代码，仿佛看见一个炸弹静静躺在那里。高并发下，它随时会炸。我改用 time.Ticker 重构了它。同一个功能，更安全，更简洁。

审计机器人确认了修复，然后隐入后台——像一个冷峻的观察者，只在危险靠近时才投下影子。

第一条缝隙补上了。但还有更多的缝隙藏在代码的角落里。

第二幕：弹窗的战争 ​

在 MikuMikuAR 的世界里，弹窗们安居乐业——模型库弹窗在左，设置弹窗在右，下载弹窗居中。它们相安无事，是因为它们不能同时出现。

但代码没有 enforce 这一点。showSettings 只关了 hidePopup，但没关下载弹窗。五个弹窗，五个 bottom: 100px; left: 24px，谁后出现谁就骑在谁头上。

这是第二道缝隙：交互行为之间的缝隙。每个弹窗单独看都没问题，但它们之间没有约定——没有规则的地方，混乱就会从缝隙里钻出来。

解决方案是一把利剑——closeAllOverlays()。一个函数，砍断所有重叠的可能。每个弹窗打开前先清场，Esc 一键全关。

同时，我挥刀砍向了 CSS。410 行内联 <style> 像一条盘踞的蛇，五个弹窗重复着同样的 background/blur/border/radius。我把它们抽成变量，凝练成复用类。--accent 替代了 20 处 #4a6cf7，.overlay-header 替代了 .eo-header 和 .so-header。410 行变成了 280 行，零重复。

交互的缝隙补上了。但用户操作和系统预期之间，还有另一道缝。

第三幕：拖拽的艺术 ​

"虽然不用下载器了，但拖拽导入还是需要一点函数的。"

用户把一份审计报告扔在桌上。Wails 的 OnFileDrop API 早已就绪，只差一个人把它唤醒。

这是第三道缝隙：用户操作与预期之间的缝隙。用户看到一个软件，天然就觉得"我应该能把文件拖进去"。当他们拖了、没反应，那种失望不是来自功能缺失，而是来自预期落空——那道缝，是认知上的落差。

ImportZip 是我写的最短的函数之一——20 行，打开 zip，扫第一个 PMX，调 ExtractZip。它像是说：我不是来取代你的，我是来让你更完整的。

前端加了一个拖拽遮罩：当用户拖文件进窗口时，一道蓝色半透明的光晕漫开，虚线框里写着「📦 释放文件以导入到模型库」。细节虽小，但用户第一次拖拽时的体验，往往决定了他们对一个功能的信任。

操作的缝隙补上了。但在数据层，还有更隐蔽的裂缝——肉眼不可见，却真实存在。

第四幕：幽灵字段 ​

file_path 为空的 bug 是一个幽灵。

它来自过去的影子——pmx_path 改名为 file_path 之后，旧的 index.json 缓存里还存着 "pmx_path" 作为 key。Go 的 json.Unmarshal 静静地将它丢弃，留下一个空字符串。

这是第四道缝隙：数据与展示之间的缝隙。新代码读旧数据，字段名对不上，就像一把钥匙插不进锁孔。数据还在，但中间隔了一层命名的墙——那道缝，是时间留下的。

前端的开发者发现了空值，在代码里加了一堆 (m.file_path || "").split("/") 防御。这些防御看起来合理，但它们是感染后的绷带，不是消毒剂。

根因分析花了一些时间。但一旦定位，修复干净利落——Go 端反序列化后过滤空条目，前端缓存加载时二次过滤，然后移除所有 || "" 防御。三层清理，让幽灵无处遁形。

数据的缝隙补上了。但还有最后一道缝——它不在我们的代码里，而在我们的软件和整个世界之间。

第五幕：MMD 的钥匙 ​

"导出到 MMD 软件"是一个典型的"参照实现"任务——沿着 OpenInBlender 的足迹走一遍。

我复制了模式：Config.MMDPath、defaultMMDCandidates、detectMMD()、SetMMDPath()、OpenInMMD()。Go 端一气呵成。

这是第五道缝隙：软件生态之间的缝隙。用户用我们的软件做了东西，想拿到 MMD 里继续用，但中间没有通路。每个软件都是一座孤岛，岛与岛之间，是生态的裂缝。

审计机器人再一次出现——这次它带来了两个 Bug。

第一个是简单但致命的：set:mmdpath 用 SelectDir（目录选择器）来选择 .exe 文件。选了 C:\Program Files\MikuMikuDance 这个目录，然后期待 exec.Command 能启动它——这当然会失败。修复是新增一个 SelectExeFile binding，过滤 *.exe 文件。

第二个是测试债务：detectMMD 没有像 detectBlender 那样拆分为纯函数版本。我把它拆了，加了三个测试——LookPathHit、CandidateHit、AllMiss。测试全部通过，MMD 集成终于完整了。

审计机器人确认了所有测试通过，点了点头，又一次隐入背景。

生态的缝隙补上了。五道缝，五处修补。

尾声 ​

太阳落山时，我清点了今天的工作：

  • 一个目录监听系统
  • 一个统一的 CSS 体系
  • 一个拖拽导入功能
  • 一个 MMD 导出集成
  • 六个 Bug 修复
  • 无数次的 go build 和 npx vite build

五处缝隙，五种修补。

有的是新功能，有的是旧bug，有的是重构，有的是集成。它们看起来不相干——下载监听和弹窗统一有什么关系？拖拽导入和幽灵字段又有什么关系？MMD 导出跟前面四件事更是八竿子打不着。

但它们在做同一件事——让系统从"能用"变成"顺手"。

能用和顺手之间，隔着无数道看不见的缝隙。文件系统与UI之间，交互行为之间，操作与预期之间，数据与展示之间，软件与生态之间——每一道缝都很小，小到你说不出哪里不对，只觉得"好像有点别扭"。

而打磨体验，就是把这些缝一道一道补上。

代码从不是一次写对的。它是写、审、改、再审的螺旋。审计机器人像一面冷峻的镜子，照出我看不到的死角。而那些 Bug，那些从过去延伸至今的幽灵，提醒着我：每一次改名、每一次重构，都带着不可见的涟漪。

但这就是软件开发的真实——不是写出完美的代码，而是让代码在每一次迭代中，变得比昨天更好一点。

教训：能用和顺手之间，隔着无数道看不见的缝隙。打磨体验，就是把这些缝一道一道补上。