从「按回车没反应」到「方向键区回车又能换行」，这些桌面端输入框的坑，背后的根源其实是一个焦点模型的问题。

引子：一个用户报来的 bug

“在输入框里打字后，第一次回车会换行，第二次才正常提交。”

这是 Flutter 桌面端开发中极具代表性的问题：移动端的输入逻辑无法直接平移到桌面端。移动端软键盘上的「发送」按钮天然触发 onSubmitted；而桌面端有实体键盘，回车、Shift、方向键都是独立可见的物理事件，它们的语义需要开发者自己定义。

（背景说明：这个输入框来自一个 AI 驱动的交互式叙事应用，用户以「命运」身份输入指令，AI 据此展开故事。输入框和流式回复是这个应用最核心的两个交互入口，所以它的细节值得认真打磨。）

我最初的做法很「直觉」：用一个外层 Focus 包裹 TextField，在里面拦截 Enter 键。结果就有了文章开头那个 bug——第一次回车成了换行。

一、键盘事件真正的传播路径

直觉为什么是错的

大多数人（包括我）会这样写：

Expanded(
  child: Focus(
    onKeyEvent: _handleKeyEvent, // 外层 Focus 拦截
    child: TextField(
      focusNode: _focusNode,
      maxLines: null, // 桌面端多行
      textInputAction: TextInputAction.newline,
    ),
  ),
)

看起来 onKeyEvent 应该能收到所有按键。但实际上，键盘事件先到达真正获得焦点的节点——也就是 TextField 内部的 EditableText——而不是你外面套的那层 Focus。

在 maxLines: null + textInputAction: newline 的组合下，EditableText 收到 Enter 后会：

1. 在内部插入一个换行符
2. 返回 KeyEventResult.handled（标记事件已消费）

事件一旦被 handled，就不会继续冒泡到外层 Focus。你的 _handleKeyEvent 根本收不到这个事件，自然无法拦截。第一次回车变成了换行，第二次才「碰巧」正常提交。

这里「冒泡」这个词，前端读者自然会联想到 JS 的 DOM 事件冒泡。两者确实有一个共同点：事件从某一点开始，沿一条链向上传播，中途可以被消费从而停止。但「传播路径」和「中途停止」的细节完全不同：

在 JS 里，外层 div 包裹内层 input，事件一定会经过外层 div——视觉包裹关系就是传播路径，你在外层拦截理所当然。但在 Flutter 里，事件走的是焦点链，而不是 widget 树的包裹关系：TextField 内部的 EditableText 是当前焦点节点，事件从它开始沿焦点链向上传播。外层 Focus 作为 EditableText 的祖先，节点确实在焦点链上——但问题是 EditableText 处理 Enter 时返回了 KeyEventResult.handled，事件冒泡在到达外层 Focus 之前就被截断了，根本轮不到外层处理。这才是「外层 Focus 包裹 TextField 却拦截不到回车」的真正原因：不是节点不在链上，而是事件在到达它之前就已被消费。

正确的挂载点

把键盘事件处理直接绑定在 TextField 自己的 FocusNode 上：

late FocusNode _focusNode;

@override
void initState() {
  super.initState();
  _focusNode = FocusNode(onKeyEvent: _handleKeyEvent);
}

// build 中不再需要外层 Focus 包裹
Expanded(
  child: TextField(
    focusNode: _focusNode,
    // ...
  ),
)

这样 _handleKeyEvent 会在 EditableText 处理之前先运行。Enter（无 Shift）返回 handled 阻止换行并发送；Shift+Enter 返回 ignored 放行给 TextField 插入换行。

教训：在 Flutter 里，「包裹 widget」不等于「能拦截深层的键盘事件」。要拦截什么，就得把监听器挂在事件真正经过的那个节点上。

二、同一个「回车」，两个键码

修复了第一次回车换行后，用户又报来一个新问题：「方向键区域的回车键还是会导致换行」。

同一个回车键，为什么字母区正常、方向键区不正常？

因为在 Flutter 里，这两个「回车」是不同的键码：

而我的判断写的是：

if (event.logicalKey == LogicalKeyboardKey.enter) {

numpadEnter 不匹配，_handleKeyEvent 对它返回 ignored，事件放行到 TextField，照常插入换行。

修复只需把两个键码都匹配：

if (event.logicalKey == LogicalKeyboardKey.enter ||
    event.logicalKey == LogicalKeyboardKey.numpadEnter) {

教训：桌面端键盘不是「一个键 = 一个语义」。同一个物理动作（按回车）在不同区域可能对应不同键码——尤其当你匹配键位时，要想到主键盘区之外的存在。

三、Shift+Enter 的语义不能丢

桌面端有一个通行惯例：Enter 发送、Shift+Enter 换行。这在聊天工具、终端、编辑器里几乎一致。

实现时要注意的是：Shift+Enter 应该放行给 EditableText 处理，而不是自己构造换行：

if (HardwareKeyboard.instance.isShiftPressed) {
  // Shift+Enter → 交给 TextField 插入换行
  return KeyEventResult.ignored;
}

为什么「放行」比「自己插入换行」可靠？

• 让 EditableText 处理换行，能正确维护光标位置、选择区、IME 组合状态
• 自己往 controller 里塞 \n，在输入法（中文拼音等）组合期间容易破坏光标上下文

判断 Shift 状态用的是 HardwareKeyboard.instance.isShiftPressed——这是 Flutter 当前提供的全局硬件键盘状态查询。需要说明的是：KeyDownEvent 本身并不携带修饰键状态（KeyEvent 只有 physicalKey / logicalKey / character / timeStamp 等字段，没有 modifiers），所以判断 Shift 必须依赖 HardwareKeyboard 这个全局单例。

全局状态有一个应注意的边界：它反映的是「此刻」的硬件状态，而非「该事件发生的那一刻」。在快速连续按键、弹窗切换焦点后突然松开修饰键等场景，理论上可能读到滞后状态。Flutter 未来的 KeyEvent API 演进方向是让事件携带 modifiers 快照（类似 Web 的 KeyboardEvent），届时事件级判断会比全局状态更可靠——但在当前 Flutter 版本，HardwareKeyboard.instance.isShiftPressed 就是可用的标准做法。

值得一提的是，这里不需要也不建议自建「修饰键状态缓存」（自行在 KeyDown 置 true、KeyUp 置 false）——因为 HardwareKeyboard 本身就是 Flutter 框架层维护的全局状态：它内部通过 KeyDown / KeyUp 事件流 + 合成事件（synthesized event）同步机制，保证其状态与事件序列严格一致。举例：焦点切换导致 Shift 松开事件丢失时，Flutter 会注入合成事件来修正状态。自建缓存反而更容易在焦点切换、合成事件等边界场景出错——这正是框架替你处理掉的那部分复杂度。

四、输入历史：Widget 生命周期 ≠ 数据生命周期

问题：退出重进后 ↑ / ↓ 失效

桌面端加了「↑ / ↓ 回溯最近 5 条输入」的快捷键后，第一轮测试一切正常——发送几条消息，按 ↑ 能逐条找回。但用户又说：「退出重新进入之后，↑ 键就没用了。」

原因很简单：

class _InputBarState extends State<InputBar> {
  final List<String> _history = []; // ← 纯内存，Widget 销毁即清空
}

输入历史被放在了 State 里。当前游玩时 InputBar 一直活着，历史正常累积；一旦退出叙事页、InputBar 被销毁重建，_history 被重置为空。

Widget 生命周期 ≠ 数据生命周期。State 是为「界面状态」而生的（滚动位置、当前输入框内容），而不是为「用户数据」而生的（跨会话要保留的输入历史）。把持久化数据放进 State 是反模式。

正确方案：State 提升 + 持久化

借鉴 Riverpod 的 Notifier 模式，把输入历史提升为一个全局 Provider，用 SharedPreferences 持久化：

class InputHistoryNotifier extends Notifier<List<String>> {
  static const int maxHistory = 5;
  static const String key = 'mephisto_input_history';

  @override
  List<String> build() => const [];

  Future<void> push(String text) async {
    if (state.isNotEmpty && state.last == text) return; // 相邻去重
    final next = [...state, text];
    if (next.length > maxHistory) next.removeAt(0);
    state = next;
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(key, jsonEncode(next));
  }
}

// 一个可选的初始化器：从持久化恢复

InputBar 从 State 改为 ConsumerState 后：

List<String> get _history => ref.watch(inputHistoryProvider);

发送时写入 Provider，重建后从 Provider 读——历史跨会话保留。

一个设计决策：全局共享，还是按契约隔离？

用户有过一个很合理的顾虑：”如果我有多个正在进行的子版，历史都会保存吗？性能有影响吗？”

我最终选了全局单列表：

• 存储恒定：单个 SharedPreferences key，最多 5 条短文本（约几 KB），不随子版文件数量增长
• 语义合理：不同剧本/分支经常使用类似的方向词（「调查」「询问」「前往」），全局共享反而更方便
• 实现简单：无需 Map<文件名, List<String>> 序列化

按子版隔离（Map 结构）性能上其实也毫无压力（每个子版也就几 KB），但实现复杂、收益有限。对个人项目而言，全局单列表是「够用且简单」的正确取舍。

一个前瞻风险：全局单列表的写入是异步 setString，如果未来支持多窗口 / 多 Tab 同时编辑，存在理论上并发写覆盖的可能（两个窗口各自 push 后互相覆盖）。当前方案适用于单窗口串行场景；若将来引入多窗口，需为写入加防抖合并，或改用文件锁 / 数据库（如 sqlite）保证原子性。

还有一个极端场景的权衡：SharedPreferences.setString 是异步写入，如果使用者在 await 完成前直接关闭应用或系统强杀进程，最后一次写入可能丢失。鉴于输入历史属于「辅助体验」而非「核心资产」（丢了只是 ↑ 键少回溯一次，不会损坏叙事数据），这个极低概率的丢失是可接受的——因此未采用双写或事务日志这类过度设计。

五、如何测试这些交互边界

键盘事件：模拟桌面端平台

testWidgets 默认在 FakeAsync 中运行，可以用 sendKeyEvent 直接模拟按键。关键是指定平台——InputBar._isDesktop 依据 Theme.of(context).platform 判定，默认是 Android 而非桌面端：

await tester.pumpWidget(buildInputBar(onSend: sent.add)); // 内部设置 ThemeData(platform: linux)
await tester.enterText(find.byType(TextField), '命运指引');
await tester.sendKeyEvent(LogicalKeyboardKey.enter, platform: 'linux');
await tester.pump();

expect(sent, ['命运指引']); // 第一次回车即提交

同理可以测 Numpad Enter、↑ / ↓ 回溯。

FakeAsync 的局限：真实异步 IO 不会自动完成

当测试涉及「持久化 → 重建 → 恢复」时，我踩到了一个坑：testWidgets 的 FakeAsync 中，SharedPreferences 的读取 Future 不会自动完成——pumpAndSettle 只驱动 scheduled frames，不驱动纯异步 IO。

我最初的「输入历史持久化」widget 测试怎么都过不了：第一次会话写入历史 → 销毁重建 → 按 ↑ 却得不到之前的历史。尝试了 runAsync、多段 pump，最终在这两者之间总是有一层时序矛盾。

结论：不要把「持久化 round-trip」和「UI 回溯」强行塞进一个 widget 测试。测试拆解更稳定：

• Provider 层单测：验证 push 写入、重建容器后能恢复（round-trip）、去重、上限、JSON 损坏容错
• Widget 层测试：验证 ↑ / ↓ 回溯交互行为（在已 mock 持久化的 Provider 之上）

两者各自聚焦，互不干扰，避免了组合测试受 FakeAsync 与真实 IO 时序矛盾影响的脆弱性。

Provider 层单测的骨架长这样——SharedPreferences.setMockInitialValues 一行就搞定了内存 mock：

test('round-trip：push 后重建容器可恢复', () async {
  SharedPreferences.setMockInitialValues({});

  final container1 = ProviderContainer();
  await container1.read(inputHistoryProvider.notifier).push('测试历史');
  container1.dispose();

  // 重建容器（模拟应用重启）→ AutoLoadNotifier 从内存 mock 中恢复
  final container2 = ProviderContainer();
  await container2.read(inputHistoryProvider.notifier).load();
  expect(container2.read(inputHistoryProvider), ['测试历史']);
});

注意：Provider 层的 load() 是纯异步方法，可以在普通 test() 中直接 await，不必碰 testWidgets 的 FakeAsync——这正是把持久化逻辑从 widget 中剥离出来带来的可测性红利。

更进一步的架构取向：可以把持久化抽象为接口（如 InputHistoryStore），Provider 依赖接口而非直接依赖 SharedPreferences——测试时注入内存实现，彻底摆脱 FakeAsync 与真实 IO 的时序矛盾。setMockInitialValues 是 Flutter 自带的轻量 mock，足够覆盖当前场景；接口注入则是在需要更严格隔离时的升级路径。

结语

桌面端输入框的「边界感」来自对三件事的理解：

1. 键盘事件的传播路径：拦截要挂在真正的焦点节点（FocusNode）上，而非外层包裹 widget——事件在 handled 后不会冒泡
2. 键码的物理身份：匹配物理键（Enter）要考虑 numpadEnter；修饰键状态（Shift）在事件不携带时，可通过 HardwareKeyboard 全局状态查询（并留意其「此刻而非事件当下」的边界）
3. 数据的生命周期：什么数据放 State、什么数据提升到 Provider + 持久化，取决于它是否需要跨 Widget 生命周期存活——并用分层测试验证（round-trip 放 Provider 层，UI 交互放 widget 层）

这些细节在移动端几乎不会遇到——移动端只有一个软键盘回车，也没有「退出重进后状态要保留」的实体文件概念。但一旦要做桌面端，「功能正确」和「体验正确」之间就出现了这道需要认真思考的边界。

术语表

项目：Mephisto

打字机效果看起来简单：文字一个字一个字蹦出来。但「跳过动画」「不截断」「性能不退化」这些细节，藏着一整套工程决策。

文中实现基于 Flutter/Dart，但「跳过 ≠ 中止」「缓冲合并」等核心语义决策跨框架通用——Web 的 EventSource、原生/RN 的 SSE 客户端都会遇到同样的选择。

引子：一个「跳过打字机」按钮的翻车过程

我在一个 AI 叙事应用（用户通过输入命运指令影响 AI 驱动的交互式故事走向）里做了一个「⏩ 跳过打字机」按钮——用户点击后，应该直接看到完整的 AI 回复，而不是等文字慢慢蹦完。

这个按钮在开发日志里经历了三个阶段：

• 第一版：点了没反应——回调被调用了，用户却什么都没感受到
• 第二版：点了内容被截断——动画确实没了，但回复也残缺了
• 最终版：点了一下子显示已有全文，LLM 仍在后台悄悄生成完整内容，生成完毕后一次性补齐

这三个版本背后，是「流式 UI」这个领域里最容易踩的三个坑。这篇文章把它拆开讲清楚。

一、从 SSE 到屏幕：流式渲染的管道

LLM 为什么是「蹦」着出字的

LLM 的回复通过 HTTP 的 SSE（Server-Sent Events）分 chunk 返回。一个典型 chunk 长这样：

data: {"choices":[{"delta":{"content":"梅菲斯特出现在"}}]}

data: {"choices":[{"delta":{"content":"书斋门口。"}}]}

data: [DONE]

每个 chunk 到达的间隔取决于模型生成速度——快的时候几十毫秒，慢的时候可能上秒级。这段「逐字出现」的效果，就是用户感知到的打字机动画。

为什么不能每 chunk 都更新 UI

如果每收到一个 chunk 就触发一次状态更新，一个几百字的回复可能触发几十上百次 UI 重建，长文本下明显卡顿。所以要做节流合并：

final _buffer = StringBuffer();
Timer? _timer;

void onChunk(String chunk) {
  _buffer.write(chunk);
  // 50ms 窗口内累积，窗口结束统一提交一次
  _timer ??= Timer(const Duration(milliseconds: 50), flush);
}

void flush() {
  _timer?.cancel();
  _timer = null;
  state = state.copyWith(content: _buffer.toString());
}

50ms 的节流窗口把「几十次通知」降为「几百毫秒一次通知」。这个数字不是随便定的：人眼能感知的流畅动画通常在 60fps 以上（约 16.6ms/帧），但打字机「蹦字」的间隔通常在 100-300ms——50ms 的合并窗口远小于打字机的感知粒度，对使用者视觉零影响，却能有效合并高频的 chunk 帧渲染，显著降低 UI 开销。

StringBuffer：避免 O(n²) 拼接

每次提交时，如果把完整内容存为 pending，再 state.streamingContent = current + pending，长回复下就是反复全量拼接——O(n²) 复杂度。

正确做法是维护一个 StringBuffer 累积器，提交时用 toString() 一次性构建：

final _streamingBuffer = StringBuffer();

String applyAndGet(String pending) {
  _streamingBuffer.write(pending);
  return _streamingBuffer.toString(); // O(总长)，而不是 O(n²)
}

二、「跳过动画」的正确语义：静默累积 ≠ 中止生成

这是整个流式体验里最微妙、最容易搞反的一个点。

第一版误区：只跳过 UI 节流

我最初的实现是这样：

void revealStreaming() {
  _revealInstant = true;    // 后续 chunk 跳过 50ms 节流
  _flushStreamBuffer();     // 立即提交已缓冲内容
}

_revealInstant = true 后，后续 chunk 不再经过节流，直接提交到 UI。但这完全没有解决使用者的问题——因为打字机效果的真实来源是 LLM 逐 chunk 返回，而不是 UI 的 50ms 节流。

LLM 仍然是几秒内慢慢吐完整个回复。使用者看到的效果：点击按钮后，文字依然一个接一个出现。「跳过打字机」变成了「跳过节流」，在感知上约等于什么都没做。

第二版误区：触发取消信号

为了让「跳过」真正生效，我加了取消信号：

void revealStreaming() {
  _revealInstant = true;
  _flushStreamBuffer();
  cancelGeneration(); // 让 LLM 停止生成
}

这次确实「立即」了——因为点击后 LLM 被中止，已到达的内容连同 [DONE] 一起作为最终回复返回，所有「剩余未生成的内容」也就永远丢失了。

用户反馈：「点跳过之后，内容直接截断了，之后的内容不再出现。」

问题：我把「跳过动画」理解成了「跳过生成」。但用户想要的只是「不想看动画」，而不是「不让 AI 把话说完了」。

正解：静默累积，让 LLM 把话说完

「跳过动画」的正确语义是：停止 UI 逐字更新——打字机光标消失、文字不再一点点蹦——但 LLM 继续在后台完整生成，生成完毕后一次性把完整回复写进消息列表。

void _appendStreamChunk(String chunk) {
  if (_revealInstant) {
    // 跳过打字机：静默忽略后续 chunk，不触发 UI 重建
    // 完整内容由生成完毕后的 ReplySucceeded 一次性写入
  } else {
    _streaming.append(chunk, _applyStreamChunk);
  }
}

点击 ⏩ 后：

1. 立即 flush 当前已到达的内容到消息气泡（使用者立刻看到已有全文）
2. _revealInstant = true，后续 chunk 静默忽略——UI 不再逐字更新
3. LLM 继续后台生成完毕，ReplySucceeded 携带完整 reply 一次性写入消息列表

关键区分就一句话：

停止 UI 逐字更新 ≠ 中止 LLM 生成

一个需要正视的体验空窗

静默累积带来一个极端的体验场景：如果模型极慢且回复超长，使用者点击 ⏩ 时 LLM 可能才生成了前 10 个字，而剩余 2000 字还在排队——从点击跳到 ReplySucceeded 之间可能有长达 10-20 秒的完全无 UI 反馈空窗期。此时仅靠「光标消失」是不够的，使用者可能误以为应用卡死了。

产品层面的解法：在跳过模式下显示一个极淡的「后台生成中…」指示条（弱化视觉打扰，但让使用者知道系统仍在工作）。这是静默累积「稳住即时体验」与「保护使用者耐心」的平衡点——技术决策之下，往往还跟着一个体验决策。

一个真实存在的兜底缺陷

静默累积有一个必须正视的风险：如果 LLM 生成失败（网络超时、服务端 5xx），ReplySucceeded 永远不会到来。此时不能永远卡在「加载中」。

我的做法是依赖生成流程的全局兜底：

} catch (e, st) {
  debugPrint('生成回复异常: $e\n$st');
  _dispatch(const GenerationFailed(narrativeErrorGenFailed)); // 复位生成状态
} finally {
  endGeneration(); // 释放防重入标志，允许下一条消息
}

但这暴露了一个真实的体验缺陷：GenerationFailed 会清空 streamingContent——使用者点 ⏩ 时已经看到的部分内容会消失，只剩下一条错误提示。

这个问题其实可以立即修复，不必等到下一版。既然 _revealInstant = true 后是「静默忽略」后续 chunk，那么失败时的兜底逻辑应当是：若已进入跳过模式，失败时先 flush 累积缓冲，将已生成的部分作为一条「不完整回复」归档，再标记失败：

说明：_flushStreamBuffer() 会把节流缓冲中已累积的内容提交到界面（即 streamingContent）；_streamingContent 就是当前已显示的流式文本。失败兜底时先把这部分作为「不完整回复」归档，再置错误。

} catch (e, st) {
  debugPrint('生成回复异常: $e\n$st');
  if (_revealInstant) {
    // 跳过模式下：先把已累积的内容作为「不完整回复」归档，保住使用者看到的部分。
    // _flushStreamBuffer() 提交缓冲 → _streamingContent 为当前已显示的流式文本
    _flushStreamBuffer();
    final partial = _streamingContent;
    _dispatch(ReplySucceeded(
      reply: partial,
      // 状态/记忆等沿用当前值……
    ));
  }
  _dispatch(const GenerationFailed(narrativeErrorGenFailed));
} finally {
  endGeneration();
}

这只改失败分支、不动主框架，就能做到「跳过动画后即使生成失败，已看到的内容也不丢失」。

三、数据一致性：流式中断不丢内容

Mephisto 里有两个「打断生成」的入口：

• ⏹ 停止：使用者明确想中断，保留已生成内容
• ⏩ 跳过：使用者不想看动画，但希望 LLM 把话说完

它们底层复用同一个「协作式取消」信号——LlmClient 收到取消信号后，在下一条 SSE 数据行处停止读取，并返回已累积的完整内容：

// LlmClient 的 SSE 循环内
await for (final line in response.stream...) {
  if (isCancelled()) break; // 协作式：下一条数据行处停止
  // ...解析 delta、写入 fullContent、回调 onChunk
}
return fullContent.toString(); // 返回已累积内容，而非抛异常

• ⏹ stopGenerating()：触发取消 + flush 已显示内容 → 生成流程以「已累积内容」正常收尾
• ⏩ revealStreaming()：只置 _revealInstant，不触发取消 → LLM 继续生成，最终完整提交

两者都靠「取消后返回已累积内容」保证不丢已有数据；区别在于「是否让 LLM 继续」。

术语澄清：这里的「取消信号」是客户端主动停止读取 SSE 流（下一条数据行处 break），等于客户端断开接收——服务端/模型可能仍在后台继续生成、继续消耗算力。它不是一个「向服务端发送中止指令」的操作；LLM API 通常不支持 client-side cancellation。理解这点很重要：你点了「停止」只是自己不再接收，服务端的成本并不会因此立刻终止。

四、如何测试流式场景

流式 UI 是最难测的场景之一：时序敏感、涉及真实网络 IO、还夹着节流缓冲。好在 Flutter 测试里可以用 MockClient.streaming + StreamController 精确控制时间点。

可控分块流

核心思路：用一个 StreamController 手动推送 SSE chunk，在任意时间点注入「使用者点击 ⏩」的调用，验证后续行为。

final controller = StreamController<List<int>>();
final streamingClient = MockClient.streaming((request, bodyStream) async {
  return http.StreamedResponse(
    controller.stream,
    200,
    headers: {'content-type': 'text/event-stream; charset=utf-8'},
  );
});

测试「跳过动画不截断」的关键三步

// 1. 第一段内容到达
controller.add(utf8.encode(sseChunk('梅菲斯特出现在书斋门口。')));
await Future<void>.delayed(const Duration(milliseconds: 50));

// 2. 使用者点击 ⏩ 跳过打字机
notifier.revealStreaming();
expect(state.streamingContent, contains('梅菲斯特出现在书斋门口'));

// 3. 剩余内容继续到达（reveal 后不应中止生成）
controller.add(utf8.encode(sseChunk('他轻声提议进行一场交易。')));
controller.add(utf8.encode('data: [DONE]\n\n'));
await controller.close();
// waitForGeneration：轮询检查状态.isGenerating 直至复位，
// 确保 LLM 生成的异步流程（含自动存档）完全收尾后再断言
await waitForGeneration(container);

// 最终回复 = 完整内容（不截断）
expect(state.messages.last.content,
    '梅菲斯特出现在书斋门口。他轻声提议进行一场交易。');

这个测试一举验证了三个关键不变量：

1. 点击 ⏩ 后，已有内容立即显示
2. reveal 后，后续 chunk 仍然被接收（未被中止）
3. 生成结束后，消息列表写入的是完整拼接内容（不截断）

如果当时先写了这个测试，第二版「取消信号导致截断」的 bug 会在测试里立刻暴露——而不是等用户反馈。

结语

流式 UI 的「顺滑」不是靠运气，而是靠一套清晰的语义决策。总结三条：

1. 节流不等于动画：动画来自 LLM 的逐 chunk 输出，节流只是减少 UI 重建的优化手段
2. 跳过不是中止：跳过动画的语义是「停止逐字更新」，不是「停止生成」——让 LLM 把话说完，再一次性补齐
3. 中断要可测：用 StreamController 可控模拟分块流，把「中途打断」这个最脆弱的时序场景变成可重复验证的测试

术语表

项目：Mephisto

从 Mixin / part 到 Widget 组合的踩坑实录。 当你遇到 800 行 State 类时，该怎么做？

1. 问题信号：什么时候该拆

当一个 State 类长到 几百行，通常意味着它承担了多种职责：

以真实项目里的首页为例，800+ 行的 _HomeScreenState 里混着：

判断准则：如果同一个类里有超过 3 种「互不相关的关注点」，就该拆了。 行数不是目标，职责混杂才是根因。

2. 尝试一：抽 Mixin → 败给库级私有

最常见的直觉是「把方法抽成 Mixin，然后 with 进来」：

// home_screen.dart
class _HomeScreenState extends ConsumerState<HomeScreen>
    with HomeContractActions, HomeStageActions { ... }

// home_contract_actions.dart（另一个文件）
mixin HomeContractActions on ConsumerState<HomeScreen> {
  Future<void> _handleMasterMenu(...) { ... }  // ❌ 宿主访问不到！
}

报错：The method '_handleMasterMenu' isn't defined for the type '_HomeScreenState'

为什么？

Dart 的 _ 前缀私有是 library-level（库级）私有，而不是 class-level（类级）私有。

• 很多语言（Java / C++ / TS）的 private 是「类内可见」——同一个类里混入的成员自然可见；
• Dart 的 _ 是「同一个库文件内可见」——跨文件的 Mixin 与方法定义处于不同库，即使 with 进同一个类，宿主也看不见 Mixin 里的私有方法。

有个「看似可行」的桥接：让 Mixin 声明抽象 getter，宿主提供实现：

mixin HomeStageActions on ConsumerState<HomeScreen> {
  HomeSelectionController get selection; // 抽象 getter
  void refreshLists();
  Future<void> _handleStageMenu(...) { ... } // ❌ 仍是私有，宿主看不到
}

数据桥接解决了（selection / refreshLists），但 方法可见性问题没解决——_handleStageMenu 依旧是另一个库的私有方法。

澄清：问题不是「Mixin」，而是「跨文件」

如果你是在同一文件内定义 Mixin 再 with，是完全可行的：

// home_screen.dart（同一个文件）
mixin HomeStageActions on ConsumerState<HomeScreen> {
  Future<void> _handleStageMenu(...) { ... } // ✅ 同文件，私有可见
}

class _HomeScreenState extends ConsumerState<HomeScreen>
    with HomeStageActions { ... }

所以「Mixin 拆 State」的直觉本身没错。真正无解的约束是：Dart 的库级私有 + 文件天然构成库边界。一旦方法搬去另一个文件，_ 私有在跨库时就成了硬隔离。

📌 核心教训：Dart 的私有不是「类私」，而是「库私」。 跨文件组织代码时，_ 前缀成员默认互相隔离；Mixin 若留在同一文件则不受此限制。

3. 尝试二：用 part → 败给无 this

既然 _ 是库级私有，那用 part 把同一个库拆成多个文件，不就能共享私有成员了吗？

// home_screen.dart
part 'home_screen_contract.dart';
part 'home_screen_stage.dart';

// home_screen_contract.dart
part of 'home_screen.dart';

Future<void> _handleMasterMenu(...) { ... } // ✅ 私有可见了

part of 确实让私有成员可见（我看到了 _selection / _refreshLists），但是新的问题来了：

顶层函数没有 this 上下文。

part of 里的代码是库级顶层函数，不是宿主类的方法。于是：

part of 'home_screen.dart';

Future<void> editContract(ContractInfo info) {
  return editContractFile(
    context,          // ❌ Undefined name 'context'
    onRefreshLists: _refreshLists, // ❌ Undefined name '_refreshLists'
  );
}

context / ref / mounted / _selection 都是 _HomeScreenState 的实例成员，顶层函数无法访问。

那 part 到底什么时候合理？

项目里早就有成功的先例——freezed 生成代码：

// narrative_state.dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'narrative_state.freezed.dart'; // ✅ 纯生成代码，无 this 依赖

narrative_state.freezed.dart 是 freezed 工具生成的、只依赖 @freezed 注解产生的 _NarrativeState 类，它不需要访问宿主的实例成员。这种「纯声明 + 生成实现」的拆分才是 part 的正解。

📌 核心教训：part 分享的是「库级私有」，而非「宿主实例上下文」。 如果你的拆分目标是一堆要访问 this 的方法，part 不是答案。

4. 最终方案：Widget 组合 → 回归框架哲学（与合理的边界）

绕了两圈，最终回到 Flutter 组合（Composition） 的经典答案：

把「渲染」抽成独立 Widget，把「交互」用回调注入。

核心原则

具体做法

把「契约树 + 舞台聚合 + 最近编辑」这一大段纯渲染抽成 ContractTreeSection：

class ContractTreeSection extends ConsumerWidget {
  final List<ContractGroup> groups;
  final HomeSelectionController selection;

  // ---- 所有交互通过回调注入 ----
  final void Function(BuildContext, ContractGroup) onMasterTap;
  final void Function(ContractInfo child, String action) onChildMenu;
  final void Function(String stagePath) onStageTap;
  // ...

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 只剩渲染：ListView + ContractCard + StageSection ...
  }
}

宿主 _HomeScreenState 只剩「组装 + 委托」：

return ContractTreeSection(
  groups: groups,
  selection: _selection,
  onMasterTap: _onMasterTap,
  onChildMenu: (child, action) => _handleChildMenu(context, child, action),
  onStageTap: _openStageNarrative,
  // ...
);

效果（拆分 ≠ 删代码，而是职责重新归位）：

总代码量不变，但每个文件的职责从「混杂」变成「单一」；纯展示组件（StageCard / ContractTreeSection）还能脱离 State 独立测试。

stage_card_with_meta.dart 是「数据加载」与「纯渲染」之间的薄胶水：它负责从 Riverpod 读取舞台数据（角色列表 / 存档探测 / 最近活动时间），再原样传给纯展示的 StageCard——这样 StageCard 自身可以保持零 Riverpod 依赖、便于独立测试。

为什么这才是「Flutter 的方式」？

Flutter 的组合模型（Composition）天然就是「一个 Widget 渲染，回调交给上层」：

• Button.onPressed、TextField.onChanged、ListView.builder 全是回调解耦的例子；
• 项目里 ContractCard / StageSection 早就这么做了——只是这次把「完整页面的一整块渲染」也套用了同一模式；
• 同时缩小重绘范围：抽成独立 ConsumerWidget 后，State 中其他字段变化不会触达这棵子树——Flutter 的 Element 复用 + 子树隔离让无关更新不再重绘 ContractTreeSection。

Mixin 是给行为复用用的（如 GenerationCoordinator）；用它拆「State 的组织」，本身就是错配。

💡 TIPS：回调里的 String 该不该换成 enum？ action 用 String 可能触发类型安全直觉。但 PopupMenu 场景下这是务实取舍：PopupMenuItem<String> 天然以 String 为载荷、menu_actions.dart 常量层已提供编译期防护、菜单动作是持续演进的集合（enum 每加一个动作要改定义 + 所有 switch）。 结论：若 action 是「封闭且稳定」的集合（如 MessageRole），用 enum 换 exhaustiveness 值得；否则 String + 常量更贴合生态。

我们为什么停在这里（不继续抽协调器）

把交互编排抽到 State 之外（如 Riverpod Notifier 协调器）是常见的进阶建议，但我们评估后选择不做：

• State 里剩下的导航 / 弹窗 / 菜单分发本质是 UI 职责——Navigator.push、ScaffoldMessenger、确认弹窗无论如何都需要 BuildContext，抽进 Notifier 只是把壳搬走，参数一个不少；
• 这些逻辑早已抽到顶层函数（home_operations.dart / home_menu_actions.dart），State 里剩的是清晰的一行委托；
• 再抽协调器会引入「ref.read(coordinator.notifier).xxx() + context.mounted」的额外间接层，认知负担不降反升。

所以 640 行不是「没拆完」，而是拆到职责单一后的合理停点。维护性看的是「每个方法一眼可见它干什么」，不是行数。 📌 核心教训：遇到「语言机制」限制，不要用 dynamic 或变通去硬绕。 换个更符合框架哲学的架构，通常才是正解；知道何时停下来，同样是架构判断的一部分。

5. 决策树：三种方案怎么选

遇到「State 类太大」
│
├─ 想拆的是「行为复用」？（如流式节流、生成协调）
│    └─ ✅ 用 Mixin（同一文件内定义，避免库私坑）
│
├─ 拆的是「纯数据 / 生成代码」？（如 freezed .g.dart）
│    └─ ✅ 用 part / part of
│
└─ 拆的是「要访问 this 的 State 方法」？
     ├─ 纯渲染部分 → ✅ 抽独立 Widget + 回调注入
     └─ 交互编排部分 → ✅ 留在 State

6. 落地的工程保障

重构最容易翻车，所以纯移动 + 纯提参 = 零行为变更是底线：

1. 保持行为不变：只移动方法体、改写调用点，不改任何逻辑；
2. 静态分析兜底：flutter analyze 必须是 No issues found!；
3. 全量测试兜底：406 个测试全绿再算完成；
4. 小步提交：每次拆分一个关注点，独立验证，避免「大爆炸式」重构。

总结

• Dart 的 _ 是库级私有，不是类级私有 → Mixin 跨文件失败；
• part 分享私有但无 this → 不适合拆 State 方法；
• 抽独立 Widget + 回调注入 是拆超大 State 类的 Flutter 正解；
• 渲染与交互解耦，既符合框架哲学，又能独立维护与测试。

本系列共五篇，覆盖从零基础创建到工业级设计系统的 VS Code 主题开发全流程（对应 Moongate v2.6.0）：

1. VS Code 主题：从手写 JSON 到可发布 —— 不依赖脚手架，手写最小主题 JSON，掌握 colors 与 tokenColors 的核心机制与发布流程。

2. 主题工程化：从单体 JSON 到模块化 YAML —— 将单体 JSON 重构为模块化 YAML 项目，用构建脚本实现变量替换与自动生成。

3. 设计系统：DTCG 三层架构与昼夜双变体 —— 用 DTCG 设计令牌标准管理颜色，通过语义层与重力补偿构建深色/浅色双变体。

4. 构建体系：可测试、可验证的工程实践 —— 模块化构建体系、WCAG 对比度校验、scope 自动验证、自动化测试与多格式产物生成。

5. 品牌生态：设计哲学与视觉契约 —— 为你的主题赋予设计哲学、视觉契约和品牌生态，打造完整的设计系统。

🌕 引言：从工程化到设计系统的跃迁

在前四篇中，我们一步步构建了 Moongate 主题的工程基础：从手动 JSON 到模块化 YAML，从 DTCG 三层架构到可测试的工业级构建体系。至此，我们拥有了一套高效、可扩展、可自我验证的主题生产系统。

但一个真正优秀的主题，不应只是颜色规则的集合，而应是一套完整的设计系统——它包含明确的设计哲学、可复用的视觉语言、与用户沟通的契约，以及可跨平台复用的品牌生态。

本篇将完成最后的跃迁：从「工程化」升维到「设计系统」。你会看到，前四篇建立的工程能力（DTCG 令牌、构建产物、自动化验证）如何支撑起一套可跨平台复用的品牌生态。

🎨 第一部分：设计哲学——让每个颜色都有意义

任何设计系统都必须建立在清晰的设计哲学之上。没有哲学的颜色只是随机的搭配，有哲学的颜色才能形成品牌识别。

1.1 冷调基底：消除视觉脏感

通用原则：为背景、边框、灰阶添加微弱的冷色偏置（如蓝或绿），避免纯黑或纯白带来的视觉「脏感」。纯黑背景会让高亮色产生「发光溢散」，纯白背景则容易发黄发灰。微量的冷调能让底色干净、深邃，让叠加的彩色语义色更纯粹地呈现。

Moongate 实例：

• 深色背景：#0f172a（深空蓝黑）
• 浅色背景：#f9fafb（冷月白）

1.2 语义分层：信息的三级阶梯

通用原则：代码不是平面的，天然具有层次。将所有代码元素划分为三个视觉层级——前景（核心逻辑）、中景（普通代码）、背景（辅助信息），通过对比度、饱和度、字体样式（加粗、斜体）等区分，让代码结构自然「浮现」。

Moongate 实例：

这套分层贯穿所有语言、所有主题变体，是 Moongate 视觉一致性的底层保证。

1.3 重力补偿：昼夜视觉重量对等

通用原则：浅色主题不是深色主题的简单反相。深色背景上的亮色是「发光体」，浅色背景上的暗色是「吸光体」。要让同一语义角色在不同背景下拥有对等的视觉重量，必须保持色相不变，科学调整明度和饱和度。这称为重力补偿。

Moongate 实例：

用户切换主题时，同一语法元素的视觉重量几乎不变，无需重新适应。

1.4 海拔系统：为 UI 注入物理深度

通用原则：通过定义多级背景明度阶梯，表达 UI 元素的物理深度。深色模式下，海拔越高表面越亮（明度递增）；浅色模式下，海拔越高表面也越亮（但使用更高亮度的白色或浅色）。阶梯步长应保持一致，形成平滑的层次感。

Moongate 实例（v2.6.0 最新值）：

这种设计让侧边栏微微隆起，弹窗轻盈浮现，代码区沉静深邃——编辑器从平面走向立体，物理隐喻让界面层次一目了然。

📄 第二部分：视觉契约——连接用户与硬件

通用原则：主题设计得再好，如果用户显示器未校准，效果也会大打折扣。提供一份显示器校准指南（视觉契约），帮助用户调整 Gamma、亮度、对比度、色温，并提醒关闭「动态对比度」「生动模式」等味精功能。校准的终点不是理论完美，而是找到用户最舒服的平衡点。

Moongate 实例：extras/VISUAL_CONTRACT.md 提供了详细的《视觉契约》文档（v2.0 版），包含以下核心步骤：

v2.0 的视觉契约特别强调分模式校准：

• 深色模式（夜间环境）：在黑暗房间中，调节亮度使 Black level 测试页 上 2% 灰块刚能被分辨。
• 浅色模式（白天环境）：在典型照明下，使用 White saturation 测试页，让 250-255 亮块层次分明且 255 纯白不刺眼。

并列举了常见显示器陷阱及其对策：

💡 为什么视觉契约是「契约」而不是「教程」？ 因为它不是指导用户如何校准显示器，而是双方共同遵守的约定：主题开发者承诺「颜色经过精密设计」，用户承诺「通过合理校准让设计被忠实呈现」。这份契约让主题在各种硬件上的表现可控、可预期。

🚀 快速版：3 步「够用就好」

完整校准对追求精准的用户很有价值，但如果你不想折腾硬件参数，3 步就能获得够好的体验：

1. 选对模式：显示器切到 sRGB / 标准模式，关闭「动态对比度」「生动模式」「黑色稳定器」等味精功能——这一步解决 80% 的颜色偏移问题。
2. 看效果微调：深色模式下发灰、浅色模式下文字刺眼，就微调亮度直到观感舒服。
3. 色温保底：选择 6500K 或暖色，中和蓝光即可。

不追求 Gamma 曲线和测试块的硬件级精确，「观感舒适」就是第一标准。等想要更精细的效果时，再按上文的完整步骤校准。

🌐 第三部分：品牌生态——从主题到社区

通用原则：完整的品牌体系包括：文档体系（README、CHANGELOG、设计文档）、社区互动（开源、反馈渠道）、生态集成（与周边工具深度整合，提供一致体验）。

Moongate 实例：

3.1 文档体系

• README：中英双语，包含预览图、设计理念、优化项清单、推荐配置。
• CHANGELOG：按版本记录所有变更，折叠旧版本，突出当前亮点。
• 视觉契约：独立文档，作为主题附件提供。
• 设计系统文档：自动生成的 DESIGN_SYSTEM.md，包含完整色板、海拔系统、WCAG 对比度数据，以及「变量选择协议」——所有颜色必须经过「原始值 → 语义层 → 组件层」的传递链条，任何跨层直接引用都是架构污染。

3.2 社区互动

• GitHub 开源：公开源码，接受 PR。
• 反馈渠道：鼓励用户反馈校准体验，持续优化视觉契约。

3.3 生态集成

• Better Comments 预设：官方配色内置主题，零配置开箱即用（双源消除机制见构建体系）。
• 终端 ANSI 色同步：16 色 ANSI 配色映射到主题语义色，消除编辑器与终端的视觉割裂。
• 跨平台令牌资产：自动导出 CSS / SCSS / TypeScript 三种令牌（生成方式见构建体系），供博客、文档站、UI 组件库直接引用——一套颜色贯穿所有产品。

3.4 从作品到品牌

Moongate 不再只是一个主题，它是：

• 一套设计哲学（冷调基底、语义分层、重力补偿、海拔系统）
• 一份视觉契约（显示器校准指南）
• 一个可扩展的品牌（昼夜双星，未来更多变体）

📌 第四部分：总结与展望

至此，我们的五部曲系列已全部完成。回顾这段旅程：

• VS Code 主题：你从手动 JSON 出发，创建并发布了第一个 VS Code 主题，掌握了核心机制与发布流程。
• 主题工程化：你通过 YAML 模块化 + 构建脚本，让主题变得可维护、可自动构建。
• 设计系统：你用 DTCG 三层架构管理颜色，通过语义层与重力补偿构建了昼夜双变体。
• 构建体系：你构建了可测试、可验证的构建脚本架构，让质量保障自动化。
• 品牌生态：你将主题升华为设计系统，用设计哲学、视觉契约和跨平台资产建立了完整的品牌生态。

v2.6.0 正是这套系统的实践成果——所有颜色经过工业级校验，布局令牌导出为 CSS 变量，设计文档自动生成，跨平台令牌同时产出 SCSS 与 TypeScript 格式。

Moongate 主题正是这一系列理念的实践成果。如果你希望亲身体验这套设计哲学，欢迎在 VS Code 市场中搜索 Moongate Theme，或通过以下链接探索：

• VS Code 市场页面
• GitHub 仓库

如果你按照本系列的方法创建了自己的主题，或者有任何问题与想法，欢迎在评论区分享。代码世界那么大，愿你的主题也能被看见。

💡 另外，如果你读完本系列，希望有一个可以直接 fork 的工程模板——无论是想快速替换配色得到自己的主题，还是想要一份干净的体系代码作为参照——欢迎在评论区告诉我们你的偏好。这将帮助我们决定是否、以及以何种形态提供一个 starter 模板。

📌 附：版本与维护策略

本系列文章描述的是 Moongate v2.6.0 的真实状态。为了让读者对文章的时效性有合理预期，这里说明系列的维护策略：

版本锁定

• 本系列所有色值、scope、脚本示例均以 Moongate v2.6.0 为准。如果你安装的主题版本不同，部分细节（如海拔色值、语言规则）可能与文章存在出入。
• 系列导航与每篇文章开头的「对应 Moongate v2.6.0」标注，就是版本锁定的标识。

更新节奏

• 主要版本更新（如 v3.0 引入新的架构变化）时，系列文章会同步修订，确保读者学到的是当前最佳实践。
• 小版本更新（如新增语言支持、微调配色）不逐篇回改正文，通过项目的 CHANGELOG.md 记录。读者可以从更新日志追踪这些增量变化。

兼容性考虑

• VS Code 版本：package.json 中的 engines 字段（当前 ^1.130.0）决定了 workbench.yaml 可用的 UI 键范围。如果 VS Code 后续新增了大量 UI 键，主题工程可能需要相应扩展——这正是工程化体系的意义所在。
• DTCG 标准：DTCG 规范仍在演进。Moongate 的策略是保持「原始值 → 语义层 → 组件层」三层架构的稳定，在各层内部拥抱规范变化。

读者如何跟进

• 关注 GitHub 仓库 的 CHANGELOG，了解版本演进。
• 如果你按照本系列复刻了自己的主题工程，遇到与文章不符之处，欢迎在评论区反馈，这有助于我们校准文档与代码的一致性。

⬆ 返回顶部

本文是 VS Code 主题开发系列「从主题到品牌」的收官之作。五篇连读，助你从零成长为设计系统工程师。

本系列共五篇，覆盖从零基础创建到工业级设计系统的 VS Code 主题开发全流程（对应 Moongate v2.6.0）：

1. VS Code 主题：从手写 JSON 到可发布 —— 不依赖脚手架，手写最小主题 JSON，掌握 colors 与 tokenColors 的核心机制与发布流程。

2. 主题工程化：从单体 JSON 到模块化 YAML —— 将单体 JSON 重构为模块化 YAML 项目，用构建脚本实现变量替换与自动生成。

3. 设计系统：DTCG 三层架构与昼夜双变体 —— 用 DTCG 设计令牌标准管理颜色，通过语义层与重力补偿构建深色/浅色双变体。

4. 构建体系：可测试、可验证的工程实践 —— 模块化构建体系、WCAG 对比度校验、scope 自动验证、自动化测试与多格式产物生成。

5. 品牌生态：设计哲学与视觉契约 —— 为你的主题赋予设计哲学、视觉契约和品牌生态，打造完整的设计系统。

在设计系统中，我们已经拥有了一套基于 DTCG 三层架构的主题生产系统，构建脚本能自动生成深色/浅色双主题，并能导出 CSS 变量。

但随着语言数量增长到 15 种、构建脚本功能越来越复杂，新的问题浮现了：

1. 构建脚本本身缺乏架构——所有逻辑堆在 build.js 一个文件里，难以测试和维护。
2. 质量无法自动保证——颜色是否符合 WCAG 对比度标准？引用的变量是否都存在？有没有产生「组件层直接引用原始值」的架构污染？
3. 语言 scope 无法验证——写了 20 条语言规则，怎么确认每个 scope 真的存在于 VS Code 的 TextMate 语法中？「规则写了对不上」如何自动化检测？
4. 产物只有主题 JSON 和 CSS——能否进一步导出 SCSS、TypeScript 等更多格式，让设计资产在更多平台复用？

本篇将回答这些问题，把构建脚本从「能用」升级为「工业级」——一套可测试、可验证、可维护的工程基础设施。

🗺️ 本篇路线图：五个步骤，层层递进——

1. 架构：把单体脚本拆成可维护的模块（一）
2. 验证：让构建过程自我证明——质量校验与 scope 验证（二、四）
3. 优化：让生成的产物更精简（三）
4. 测试：让构建系统自身可回归验证（五）
5. 发布：把验证串进生态整合与交付链路（六、七、八）

篇幅较长，建议先通读一遍建立全局认知，再结合自己的项目逐节实践——每节结尾都有与下一节的衔接说明。

💡 提示：本篇内容涉及较深的工程实践，建议先完成前三篇再阅读。如果你希望先了解「这套体系支撑起什么样的品牌生态」，也可以先读第五篇再回来。

📁 一、模块化架构：从单体脚本到 scripts/lib/

当构建脚本超过 200 行时，它本身也需要架构。Moongate 将构建系统拆分为 scripts/lib/ 下的多个单职责模块：

your-theme/
├── scripts/
│   ├── build.js                     # 主流程（编排者，不包含具体实现）
│   ├── verify-scopes.js             # scope 验证 CLI
│   ├── generate-better-comments.js  # Better Comments 配置生成器
│   └── lib/
│       ├── config.js                # 路径配置
│       ├── tokens.js                # 令牌解析（resolveTokens、replaceVariables）
│       ├── utils.js                 # 通用工具（safeLoadYaml、normalizeHex 等）
│       ├── validators.js            # 质量验证（WCAG 对比度、结构验证、未使用令牌检测）
│       ├── optimizers.js            # 输出优化（token 合并、语义色精简）
│       ├── generators.js            # 多格式产物生成（CSS/SCSS/TS/设计文档）
│       └── scope-validator.js       # scope 验证逻辑
├── src/
│   ├── core/
│   │   ├── primitives/colors.yaml
│   │   ├── semantics/dark.yaml + light.yaml
│   │   └── layout.yaml
│   ├── languages/*.yaml
│   ├── workbench.yaml
│   ├── semantic.yaml
│   └── special/better-comments.yaml
├── themes/                          # 生成产物
├── docs/DESIGN_SYSTEM.md            # 自动生成的文档
├── test/*.test.js                   # 自动化测试
└── package.json

各模块的职责：

为什么用 ESM 而不是 CommonJS？

• 现代 Node.js（≥ 14）原生支持 ESM，无需额外构建工具。
• import / export 是静态的，工具可以静态分析依赖关系，更容易重构和调试。
• 项目 package.json 中声明 "type": "module"，所有 .js 文件默认视为 ESM。

build.js 作为主流程，只负责编排——加载模块、调用函数、捕获错误，不包含具体实现。

📌 与上一篇的分工：resolveTokens、replaceVariables 的完整实现在设计系统中已经见过，本篇不再重复。你要关注的是四个新增模块：validators（质量验证）、optimizers（输出精简）、generators（多格式产物）、scope-validator（scope 验证）——数据流地图里的每一步，都会落到这四个模块上。

在阅读下面的代码之前，先建立一张「数据流地图」——每个关键步骤输入什么、输出什么：

带着这张地图读代码，你会更清楚每个模块函数在整条流水线中的位置。

// scripts/build.js（主流程精简示意）
import { PATHS } from "./lib/config.js"
import { ensureFileExists, safeLoadYaml } from "./lib/utils.js"
import { resolveTokens, replaceVariables } from "./lib/tokens.js"
import { detectUnusedPrimitives, validateThemeStructure, checkContrast } from "./lib/validators.js"
import { mergeTokenColors, optimizeSemanticTokenColors } from "./lib/optimizers.js"
import { generateColorCss, generateLayoutCss, generateDesignSystemDoc, generateScssTokens, generateTsTokens } from "./lib/generators.js"

function main() {
  console.log("🚀 开始构建主题 (DTCG 标准 + 工业级质检)...\n")
  try {
    // 1. 检查必要文件
    // 2. 加载并标准化原始色值
    // 3. 生成布局 CSS
    // 4. 加载公共规则（workbench + semantic）
    // 5. 加载语言与特殊规则
    // 6. 扫描语义文件并检测未使用原始值
    // 7. 为每个语义层文件构建主题
    // 8. 生成 CSS 变量、跨平台令牌和设计系统文档
    console.log("\n🎉 所有主题构建完毕！")
  } catch (err) {
    console.error(err.message)
    process.exit(1)
  }
}

main()

核心原则：每个函数只做一件事。main() 中每个步骤对应一个命名清晰的函数（loadPrimitives()、loadCommonRules()、loadTokenColors()……），调用者一眼就能看出构建流程的每一步在做什么。

模块化的骨架搭好了，接下来要解决真正的工程问题：构建过程必须能够自我证明。

🛡️ 二、质量验证：让构建过程「自我证明」

工业级构建脚本的核心特征：它不仅仅生成文件，还会验证生成的文件是否正确。验证失败时中断构建，让错误在发布之前就被发现。

2.1 WCAG 对比度自动校验

主题的每个颜色都必须在背景上清晰可读。Moongate 为关键文本角色设置了对 editor.background 的最低对比度要求：

校验决策可用一棵简单的树来表达：

某个语义色 vs 背景
   ├─ ratio < 3.0        → ❌ 构建中断（任何角色都不合格）
   ├─ 3.0 ≤ ratio < 4.0  → ⚠️ 仅 textMuted 可接受（其余失败）
   ├─ 4.0 ≤ ratio < 4.5  → ⚠️ 仅 textDim/comment 可接受（text 失败）
   └─ ratio ≥ 4.5        → ✅ 全部通过（达到 WCAG AA）

// scripts/lib/validators.js（简化）
import wcag from "wcag-contrast"

export function checkContrast(color1, color2, role, themeType) {
  if (!color1 || !color2) return
  const ratio = wcag.hex(color1, color2)

  let minRatio = 4.5
  if (role === "textDim" || role === "comment") minRatio = 4.0
  if (role === "textMuted") minRatio = 3.0

  if (ratio < minRatio) {
    if (role === "textMuted") {
      console.warn(`⚠️ 对比度略低: ${themeType} · ${role} = ${ratio.toFixed(2)}:1`)
    } else {
      throw new Error(
        `❌ 对比度不足: ${themeType} · ${role} = ${ratio.toFixed(2)}:1` +
        `\n   WCAG 要求 ≥${minRatio}:1`,
      )
    }
  } else {
    console.log(`✅ ${themeType} · ${role}: ${ratio.toFixed(2)}:1`)
  }
}

构建成功时，你会看到类似输出：

✅ dark · text: 14.48:1
✅ dark · textDim: 12.02:1
✅ dark · textMuted: 6.96:1
✅ light · text: 17.08:1
✅ light · textDim: 7.25:1
✅ light · textMuted: 7.25:1

关键设计：textDim 和 textMuted 使用阶梯式标准而非统一 4.5:1——因为「视觉退后」本身就是设计意图，只要保持最低可读性即可。如果所有辅助文字都强制 4.5:1，注释和辅助信息就无法在视觉上「退后」了。

2.2 结构验证：生成的文件必须自洽

validateThemeStructure 验证生成的主题 JSON：

• 必须包含 name、type、colors、tokenColors、semanticTokenColors 五个必需键。
• colors 不能为空对象，且所有值必须是合法的 6 位或 8 位十六进制色值。
• tokenColors 必须是数组。
• 不能存在未解析的 ${var} 或 {token} 残留——如果某个变量因为拼写错误没有被替换，这里会直接报错并中断构建。

验证失败时，抛出 ThemeValidationError 并携带是哪个输出文件出错的信息，错误处理统一由主流程捕获，而不是散落在各个函数里。

2.3 循环引用检测

语义层可能引用原始值，原始值理论上也可能引用另一个原始值。如果 a → b → a 形成循环，resolveTokens 会无限递归。

tokens.js 的做法：设定深度上限（20 层），超过则抛出 [ENGINEERING_FATAL] 错误并输出引用链：

export function resolveTokens(obj, tokenMap, depth = 0, path = []) {
  const MAX_DEPTH = 20
  if (depth > MAX_DEPTH) {
    throw new Error(`[ENGINEERING_FATAL] 令牌循环引用检测: ${path.join(" → ")}`)
  }
  // ...
}

20 层的上限远高于正常的令牌引用深度（正常不会超过 2-3 层），因此一旦触发，几乎可以确定是循环引用。

2.4 重复色值与未使用令牌检测

• detectDuplicateColors：检测原始值中是否有两个不同名字指向同一个色值。这不是错误（有时同名色值用于语义区分），但值得提醒——可能是命名混乱的信号。
• detectUnusedPrimitives：检测哪些原始值没有被任何语义层引用。未被引用的原始值可能是「死代码」，也提示语义层可能存在缺口。

2.5 架构污染检测

上一篇文章介绍过：颜色必须经历「原始值 → 语义层 → 组件层」的传递链条，任何跨层直接引用都是架构污染。

tokens.js 中的 detectPrimitiveReference 会在构建时检测组件层是否直接引用了原始值（如 workbench.yaml 中出现 editor.background: "${blue-500}" 而非 ${surfaceGround}），并给出警告：

[架构提醒] workbench 中直接引用了原始值 "blue-500"，建议通过语义层引用。

这个功能让「架构规范」从口头约定变成了可自动检查的工程约束。

构建必须正确，但正确还不够——生成的产物还要精简，否则文件会随语言增多而膨胀。

⚙️ 三、输出优化：让生成的 JSON 更精简

工业级构建不仅要「生成正确」，还要「生成精致」。Moongate 通过两个优化步骤，让最终主题 JSON 大幅精简。

3.1 mergeTokenColors：合并相同样式的规则

不同语言中经常有为不同 scope 分配完全相同样式的规则。例如：

# python.yaml
- name: Python F-string Expression
  scope: ["meta.fstring.python"]
  settings: { foreground: "#7dd3fc" }

# jsx.yaml
- name: JSX Expression Braces
  scope: ["meta.jsx.expression"]
  settings: { foreground: "#7dd3fc" }

这两个规则的颜色相同，完全可以合并为一条规则、两个 scope。mergeTokenColors 自动完成这件事：

• 将 settings 序列化为稳定键（按键名排序，避免 {foreground, fontStyle} 和 {fontStyle, foreground} 被当作不同规则）。
• 相同样式的 rule 合并，scope 聚合为数组。
• 结果按 scope 数量降序排序（更具体的规则在前）。

实际效果：Moongate v2.4.0 中，tokenColors 规则数从约 89 条精简至约 34 条（减少 62%），主题 JSON 体积减少约 16%。

3.2 optimizeSemanticTokenColors：删除冗余 foreground

VS Code 的语义角色支持父级继承：function.declaration 会自动继承 function 的样式，除非被显式覆盖。

因此，当 function.declaration 的 foreground 与父级 function 完全相同时，可以安全删除 foreground，只保留额外的 fontStyle：

// 优化前
{
  "function": "#87cefa",
  "function.declaration": {
    "foreground": "#87cefa",  // 冗余！与父级相同
    "fontStyle": "bold"
  }
}

// 优化后
{
  "function": "#87cefa",
  "function.declaration": {
    "fontStyle": "bold"  // VS Code 自动继承 function 的颜色
  }
}

这个优化需要小心：只有当父子关系确实存在、且 foreground 确实相同时才安全。optimizeSemanticTokenColors 精确实现这个逻辑，并在删除时计数输出。

输出精简了，还藏着一个更深的问题：规则本身对不对？scope 是不是真的存在？

🔍 四、Scope 验证：让「规则写了对不上」成为历史

主题开发中最令人沮丧的问题之一：精心编写的语言规则，在代码里却不生效。

原因通常是：规则里的 scope 并不存在于 VS Code 实际使用的 TextMate 语法中。每个语言（Python、Go、Rust……）的 scope 是由语法文件定义的，不同语言、不同版本之间可能有巨大差异。手动对照语法文档编写 scope 非常容易出错。

Moongate 的解决方案是 scripts/verify-scopes.js——自动解析 VS Code 内置的 TextMate 语法文件，比对语言配置中的每个 scope，找出「写了却永远不生效」的死规则。

4.1 工作原理

// scripts/verify-scopes.js（CLI 入口）
import { verifyAllScopes, formatVerificationResult } from "./lib/scope-validator.js"

const result = verifyAllScopes({ verbose: true })

console.log("🔍 验证语言配置中的 scope...\n")
process.stdout.write(formatVerificationResult(result))

if (!result.isValid) {
  console.error(`\n❌ 发现 ${result.totalIssues} 个 scope 不匹配，验证失败！`)
  process.exit(1)
}

scope-validator.js 的核心流程：

1. 定位语法源：在 VS Code 安装目录中找到对应语言的 TextMate 语法 JSON 文件（如 python.tmLanguage.json）。
2. 提取全部作用域：遍历语法文件中的 patterns、captures、repository 等结构，收集该语言所有可用的 scope 列表。
3. 比对语言规则：将 src/languages/*.yaml 中定义的每个 scope 与语法中实际存在的 scope 比对。
4. 输出报告：列出每个不匹配的 scope、所在文件、是哪个语言规则定义的。

4.2 它发现了什么？

在 Moongate v2.6.0 中，verify-scopes.js 帮助修复了 8 个语言文件的 scope 问题。其中最有代表性的几个：

更关键的是，验证工具可以防止回归——每次修改语言规则后运行一次，立刻知道哪些 scope 是「写了但永远不会生效」的。

4.3 在 CI 中使用

verify-scopes.js 在发现错误时以退出码 1 结束，因此可以无缝集成到 CI 流程中：

{
  "scripts": {
    "test:scopes": "node scripts/verify-scopes.js"
  }
}

CI 中运行 pnpm test:scopes，一旦有人提交了错误的 scope，构建立即失败。

验证工具越来越多，验证工具自身也需要被验证——这就是自动化测试的价值。

🧪 五、自动化测试：让构建系统可回归验证

当构建系统承担了「生成全部产物 + 质量验证 + 架构检查」的重任后，构建系统自身也需要测试来防止回归。

Moongate 使用 Node.js 内置的 node --test 测试运行器，不需要额外安装测试框架：

5.1 测试覆盖范围

test/
├── tokens.test.js        # 令牌解析、变量替换、循环检测
├── validators.test.js    # WCAG 对比度、结构验证、架构污染检测
├── optimizers.test.js    # token 合并、语义色精简
├── generators.test.js    # CSS/SCSS/TS/文档生成器
├── utils.test.js         # normalizeHex、duplicateColors 等工具
├── scope-validator.test.js # scope 验证逻辑
├── better-comments.test.js # Better Comments 生成器
├── theme-output.test.js  # 构建输出的主题 JSON 完整性
└── helpers.js            # 测试辅助（捕获 console、断言抛错）

85 个测试覆盖三大类：

1. 纯函数逻辑：normalizeHex 对 3 位/4 位/8 位色值的处理、resolveTokens 的循环检测、mergeTokenColors 的稳定键等。
2. 边界条件：非法色值抛错、未定义变量警告、透明度后缀的多种边界情况。
3. 产物一致性：生成的 CSS 变量与语义层一一对应、Better Comments 配置与深色语义层色值同步。

5.2 测试辅助：捕获 console 输出

构建工具大量使用 console.log / console.warn 输出进度和警告。测试时，test/helpers.js 提供统一的辅助函数来捕获这些输出并断言：

// test/helpers.js（示意）
export function captureConsole(fn) {
  const logs = []
  const originalLog = console.log
  const originalWarn = console.warn
  console.log = (...args) => logs.push({ type: "log", args })
  console.warn = (...args) => logs.push({ type: "warn", args })
  try {
    const result = fn()
    return { logs, result }
  } finally {
    console.log = originalLog
    console.warn = originalWarn
  }
}

这个模式的优雅之处：不需要 mock 每个函数——只要断言 console.warn 被调用过，且传入了包含「警告」关键词的参数，就能验证「未定义变量时会发出警告」这类行为。

5.3 运行测试

{
  "scripts": {
    "test": "node --test \"test/*.test.js\""
  }
}

pnpm test

输出示例：

▶ tokens.test.js
  ✔ 解析令牌引用 {token}
  ✔ 替换变量 ${var} 支持透明度后缀
  ✔ 检测到循环引用时抛出错误
  ...
▶ validators.test.js
  ✔ 结构验证：缺少必需键时报错
  ✔ WCAG 对比度不足时抛出异常
  ...
✔ 85 tests passed

构建体系稳定之后，可以把这套能力伸向生态整合：让配色在插件生态里也不漂移。

🎨 六、Better Comments 双源消除

主题的一个重要生态整合是 Better Comments 插件——它让注释中的 TODO、FIXME、NOTE 等标记拥有专属颜色。旧方案的问题在于：颜色存在两处（主题的语义层 + Better Comments 的 JSON 配置），修改一处后另一处容易忘改，导致配色漂移。

Moongate 的解法：Better Comments 配置由构建脚本自动生成，从深色语义层读取色值。

6.1 单源真相

// scripts/generate-better-comments.js（核心逻辑）
import { resolveTokens } from "./lib/tokens.js"

// Better Comments 需要的语义变量 → tag 映射
const TAG_MAP = [
  { tag: "TODO", semanticKey: "warning", bold: true },
  { tag: "FIXME", semanticKey: "error", bold: true, italic: true },
  { tag: "NOTE", semanticKey: "highlight", italic: true },
  { tag: "HACK", semanticKey: "purple", bold: true },
  { tag: "BUG", semanticKey: "error", bold: true, underline: true },
  { tag: "XXX", semanticKey: "warning", bold: true },
]

// 从深色语义层解析每个 tag 对应的最终色值
const tags = TAG_MAP.map(({ tag, semanticKey, ...style }) => {
  const color = resolveTokens(darkSemantics[semanticKey], primitives)
  return { tag, color, ...style }
})

// 写入 extras/better-comments.json

当你在 dark.yaml 中调整 warning 的颜色时，运行 pnpm run gen:better-comments，extras/better-comments.json 自动同步。

6.2 内置规则：零配置开箱即用

除了生成独立预设，Moongate 还在 src/special/better-comments.yaml 中内置了 6 个特殊注释 scope 的规则（TODO、FIXME、NOTE、HACK、BUG、XXX）。安装 Moongate 主题后，Better Comments 插件自动使用官方配色，无需任何手动配置。

这条「双通道」设计覆盖了两种用户：

• 主题用户：安装 Moongate 即获得完整配色（内置规则）。
• 独立配置用户：不使用主题、只看注释配色的人，可以单独引入 extras/better-comments.json。

两条通道都从语义层生成，不会产生双源漂移。

📦 七、多格式产物生成：一套令牌，全平台复用

设计系统介绍了 CSS 变量导出，Moongate 进一步将语义层导出为四种格式，覆盖 Web、Sass 和 TypeScript 生态：

7.1 SCSS 令牌

// themes/_tokens.scss（自动生成）
// 部分示意
$ui-colors-dark: (
  bg: #0f172a,
  primary: #3b82f6,
  surface-raised: #1a2538,
  // ...
);

$ui-colors-light: (
  bg: #f9fafb,
  primary: #0284c7,
  surface-raised: #ffffff,
  // ...
);

// 深色模式便捷变量
$ui-bg: #0f172a;
$ui-primary: #3b82f6;

7.2 TypeScript 令牌

// themes/tokens.ts（自动生成）
export interface MoongateTokens {
  dark: Record<string, string>
  light: Record<string, string>
}

export const tokens: MoongateTokens = {
  dark: {
    bg: "#0f172a",
    primary: "#3b82f6",
    // ...
  },
  light: {
    bg: "#f9fafb",
    primary: "#0284c7",
    // ...
  },
}

export default tokens

7.3 设计系统文档自动生成

构建脚本还会自动生成 docs/DESIGN_SYSTEM.md——包含变量选择协议、原始色板预览、海拔系统表格、WCAG 对比度数据。这份文档不是手写的，而是每次构建时从真实数据生成，保证文档永远与代码一致。

🔧 八、CI/发布链路：错误在发布前被发现

工业级工程的最后一块拼图：把验证融入发布流程。

{
  "scripts": {
    "build": "node scripts/build.js",
    "test": "node --test \"test/*.test.js\"",
    "test:scopes": "node scripts/verify-scopes.js",
    "gen:better-comments": "node scripts/generate-better-comments.js",
    "package": "pnpm run build && pnpm run gen:better-comments && vsce package",
    "publish": "pnpm run build && pnpm run gen:better-comments && vsce publish",
    "prepublishOnly": "pnpm run build && pnpm run gen:better-comments"
  }
}

发布链路逐层把关：

pnpm run package
  → pnpm run build              # 构建 + WCAG 校验 + 结构验证 + 架构检测
  → pnpm run gen:better-comments # 重新生成 Better Comments 配置
  → vsce package                # 打包 .vsix

• 构建失败 → 不产生 .vsix。
• 对比度不足 → 构建中断，错误信息标明是哪个主题、哪个角色、差多少。
• scope 错误 → pnpm run test:scopes 退出码 1，CI 拦截。

「发布前检查清单」从手动流程升级为自动化门禁——这正是工业级与手动的分水岭。

📊 九、总结

至此，你的主题构建系统已经完成了从「能用」到「工业级」的跃迁：

这套体系不仅是 Moongate 主题的生产工具，更是一个可以复用的设计系统工程模板。它验证了「零散的颜色 → 工程资产 → 全平台可复用」的完整路径。

但工程能力再强，也只是「怎么做」的问题。下一个问题同样重要：「为什么这样做」——设计哲学从何而来？如何让用户在不同硬件上获得一致的体验？如何让主题超越代码，成为品牌的组成部分？

这正是系列的最后一篇——品牌生态要回答的。

品牌生态：设计哲学与视觉契约

本系列共五篇，覆盖从零基础创建到工业级设计系统的 VS Code 主题开发全流程（对应 Moongate v2.6.0）：

1. VS Code 主题：从手写 JSON 到可发布 —— 不依赖脚手架，手写最小主题 JSON，掌握 colors 与 tokenColors 的核心机制与发布流程。

2. 主题工程化：从单体 JSON 到模块化 YAML —— 将单体 JSON 重构为模块化 YAML 项目，用构建脚本实现变量替换与自动生成。

3. 设计系统：DTCG 三层架构与昼夜双变体 —— 用 DTCG 设计令牌标准管理颜色，通过语义层与重力补偿构建深色/浅色双变体。

4. 构建体系：可测试、可验证的工程实践 —— 模块化构建体系、WCAG 对比度校验、scope 自动验证、自动化测试与多格式产物生成。

5. 品牌生态：设计哲学与视觉契约 —— 为你的主题赋予设计哲学、视觉契约和品牌生态，打造完整的设计系统。

在主题工程化的结尾，我们指出了工程化方案的三个痛点：

• colors.yaml 是一个扁平的变量池，颜色之间的层级关系完全靠命名约定，没有结构性的约束。
• 深浅两套主题需要两套颜色变量文件，而「同一角色在深色和浅色下应该保持色相一致、明度不同」这件事完全靠手动维护。
• 构建脚本只能做变量替换，不能自动校验颜色是否符合对比度标准。

本篇将解决这些问题。我们将引入 DTCG（Design Tokens Community Group）设计令牌标准的三层架构，让颜色从「散乱的变量」升级为「有结构的工程资产」，并基于它构建深色/浅色双变体——这是主题迈向设计系统的关键一步。

🧱 一、核心思路：从「多主题」到「设计系统」

一个优秀的主题不应只有一副面孔。提供深色/浅色双主题，不仅能覆盖更广泛的用户需求，更是主题迈向设计系统的关键一步。

但多主题的真正价值不是多几套颜色，而是：所有主题共享同一套规则，唯一不同的是颜色变量的具体值。

• 语言规则（languages/*.yaml）在所有变体中完全复用。
• UI 颜色（workbench.yaml）和语义规则（semantic.yaml）只引用变量名，不写具体色值。
• 每个变体只提供一个「语义层」，定义每个语义角色在该变体下的具体颜色。

要做到这一点，需要一套能让「颜色」成为结构化工程资产的管理体系——这就是 DTCG 三层架构。

🏗️ 二、DTCG 三层架构

DTCG（Design Tokens Community Group）是 W3C 下属的行业标准组织，旨在为设计令牌（Design Tokens）建立统一格式。它的核心思想可以用一个简单的问题概括：一个颜色值，应该由谁来定义、被谁引用、以什么名称存在？

Moongate 采用 DTCG 推荐的三层架构：

┌─────────────────────────────────────────────────┐
│  原始值层（Primitives）                           │
│  src/core/primitives/colors.yaml                 │
│  按色相-明度命名：blue-500、gray-900             │
└───────────────────────┬─────────────────────────┘
                        │ 语义层用 {token} 引用原始值
                        ▼
┌─────────────────────────────────────────────────┐
│  语义层（Semantics）                              │
│  src/core/semantics/dark.yaml + light.yaml       │
│  定义角色：primary、bg、surfaceGround            │
│  primary: "{blue-500}"                           │
└───────────────────────┬─────────────────────────┘
                        │ 组件层用 ${variable} 引用语义层
                        ▼
┌─────────────────────────────────────────────────┐
│  组件层（Components）                             │
│  src/workbench.yaml + semantic.yaml              │
│  映射 UI 元素                                    │
│  editor.background: "${surfaceGround}"           │
└─────────────────────────────────────────────────┘

2.1 第一层：原始值（Primitives）

原始值层是所有颜色的物理事实——不表达任何语义，只按色相和明度命名。

# src/core/primitives/colors.yaml
# ==================== 蓝色系 ====================
blue-500: "#3b82f6" # 深色主蓝
blue-600: "#2563eb" # 深色按钮悬停
blue-700: "#0284c7" # 浅色主蓝
blue-800: "#0369a1" # 浅色高亮/函数

# 发光蓝（特殊）
blue-glow: "#7dd3fc" # 深色高亮
blue-glow-dark: "#87cefa" # 深色函数

# ==================== 灰色阶（冷调基底）====================
gray-900: "#0f172a" # 深色编辑器背景
gray-850: "#131c31" # 深色卡片/浮层
gray-800: "#1e293b" # 深色侧边栏/代码块
gray-750: "#252e40" # 深色悬停背景
gray-700: "#2d3748" # 深色边框
# ... 完整的色相-明度阶梯

命名规范：色相-明度，例如 blue-500、green-400、gray-900。这样命名不是为了好看，而是为了让「同一个色相在不同明度下如何变化」这件事变得可追溯。

原始值的价值：当你需要「给所有主题换一个更蓝的主色」时，只需要调整 blue-500 和 blue-700 两个原始值，所有引用它的语义色自动同步。

2.2 第二层：语义层（Semantics）

语义层定义角色——primary（主色）、bg（背景）、surfaceGround（地面层）——并为每个角色指派一个原始值。语义层不与任何 UI 元素绑定，它只回答一个问题：「主色应该是什么颜色？」

每个变体都有一个独立的语义层文件：

# src/core/semantics/dark.yaml（深色语义层）
# ==================== 月语义主色 ====================
primary: "{blue-500}"
success: "{green-400}"
warning: "{yellow-400}"
error: "{red-400}"
highlight: "{blue-glow}"

# 功能色（语法）
function: "{blue-glow-dark}"
operator: "{gray-600}"
comment: "{gray-525}"
variable: "{gray-200}"

# 海拔系统
surfaceGround: "{gray-900}"
surfaceRaised: "{gray-850}"
surfaceFloating: "{gray-800}"
surfaceTooltip: "{gray-750}"

# src/core/semantics/light.yaml（浅色语义层）
# 变量名与深色版完全一致，仅色值不同
# ==================== 月语义主色 ====================
primary: "{blue-700}"
success: "{green-600}"
warning: "{yellow-700}"
error: "{red-700}"
highlight: "{blue-800}"

# 功能色（语法）
function: "{blue-800}"
operator: "{gray-600}"
comment: "{gray-600}"
variable: "{gray-900}"

# 海拔系统
surfaceGround: "{gray-50}"
surfaceRaised: "{white}"
surfaceFloating: "{gray-100}"
surfaceTooltip: "{gray-200}"

关键原则：所有变体的语义层变量名必须完全一致。这是规则复用的基础——workbench.yaml 和 languages/*.yaml 不需要知道当前是深色还是浅色，它们只引用 ${primary}、${surfaceRaised}，具体值交给语义层决定。

2.3 第三层：组件层（Components）

组件层直接映射 UI 元素和语法角色。它只引用语义层变量，不写任何具体色值：

# src/workbench.yaml（组件层：UI 颜色）
editor.background: "${surfaceGround}"
editor.foreground: "${text}"
titleBar.activeBackground: "${surfaceRaised}"
titleBar.activeForeground: "${text}"
statusBar.background: "${surfaceGround}"
statusBar.foreground: "${textDim}"
sideBar.background: "${surfaceRaised}"
# ... 所有 UI 键

# src/semantic.yaml（组件层：语义高亮）
variable: "${variable}"
variable.readonly:
  foreground: "${variableDim}"
  fontStyle: "italic"
function: "${function}"
function.declaration:
  foreground: "${function}"
  fontStyle: "bold"
class: "${warning}"
# ... 语义规则

2.4 两种引用语法：{token} 与 ${variable}

在 Moongate 的架构中，两种「引用」有着完全不同的语义：

• 语义层用 {token} 引用原始值，构建脚本递归解析令牌引用（支持循环检测，见构建体系）。
• 组件层用 ${variable} 引用语义层变量，构建脚本替换为最终色值（支持透明度后缀，如 ${primary}20）。

这个分工不是形式主义——它让每个文件都清楚自己「属于哪一层、可以引用谁」。构建体系中我们会看到，构建脚本甚至能检测「组件层直接引用原始值」这种架构污染并发出警告。

⚖️ 三、昼夜双变体与重力补偿

有了三层架构，深色/浅色双主题的构建就变得非常自然：所有规则文件完全复用，只有语义层不同。但语义层的色值不是随手填的——深色和浅色之间需要一套科学的映射规则。

3.1 为什么浅色不是深色的「反相」？

很多新手以为浅色主题就是把深色主题的颜色反相。但这是完全错误的：

• 深色背景上的亮色是「发光体」——它们通过「亮于背景」来获得存在感。
• 浅色背景上的暗色是「吸光体」——它们通过「暗于背景」来获得存在感。

同样是 primary，在深色下用亮蓝 #3b82f6（明度 60%）很好看，但如果直接搬到白底上，就会因为和白色背景的对比度不足而「消失」。要实现视觉重量对等，必须进行重力补偿——保持色相不变，科学调整明度和饱和度。

3.2 Moongate 的补偿实例

补偿规律：

• 色相（H）不变——这是语义一致性的核心。primary 永远是蓝色，用户在切换主题时不需要重新学习。
• 明度（L）降低——深色版的亮色在白底上需要更暗才能达到同等对比度。通常降低 20-30%。
• 饱和度（S）适当调整——深色背景上高饱和度产生舒适的「发光感」，但在浅色背景上可能刺眼，通常降低 10-20%。

💡 如何科学地确定补偿值：手动「凭感觉」调整明度效率低且不一致。推荐使用 HSL 颜色模型：把 HEX 转成 HSL，保持 H 不变，调整 L 和 S。可以用 chroma.js 等工具程序化调整，例如：

const darkPrimary = chroma("#3b82f6")
const lightPrimary = darkPrimary.set("hsl.l", 0.48).set("hsl.s", 0.7)

3.3 海拔系统：为 UI 注入物理深度

除了语法颜色，UI 界面也需要在深浅两套主题中保持一致的「空间感」。海拔系统通过定义多级背景明度阶梯，表达 UI 元素的物理深度：

• 深色模式：海拔越高表面越亮（明度递增）。
• 浅色模式：海拔越高表面越亮（但用更高亮度的白色/浅色）。
• 每层阶梯的步长保持一致，形成平滑的层次感。

Moongate 的四层海拔（v2.6.0 最新值）：

📌 注意：浅色模式采用「越高越亮」还是「越高越暗」是一个设计选择。Moongate 选择浅色模式下浮层比背景更亮（更白），形成「纸张层叠」的通透感；深色模式则采用「越高越亮」，让浮层从背景中微微隆起。两种模式都遵循「海拔越高越醒目」的物理隐喻。

这种设计让侧边栏微微隆起，弹窗轻盈浮现，代码区沉静深邃——编辑器从平面走向立体。

🔨 四、构建脚本自动生成双主题

有了三层架构，构建脚本只需要做一件事：扫描 semantics/ 目录，为每个语义层文件生成一个主题 JSON。

以 scripts/build.js 的简化版为例：

// scripts/build.js（简化版，完整版见构建体系）
import fs from "node:fs"
import path from "node:path"
import yaml from "js-yaml"

const ROOT_DIR = process.cwd()

// 路径配置
const PATHS = {
  primitives: path.join(ROOT_DIR, "src", "core", "primitives", "colors.yaml"),
  semanticsDir: path.join(ROOT_DIR, "src", "core", "semantics"),
  workbench: path.join(ROOT_DIR, "src", "workbench.yaml"),
  semantic: path.join(ROOT_DIR, "src", "semantic.yaml"),
  langDir: path.join(ROOT_DIR, "src", "languages"),
  outputDir: path.join(ROOT_DIR, "themes"),
}

// 加载原始值
const primitives = yaml.load(fs.readFileSync(PATHS.primitives, "utf8"))

// 解析令牌引用 {token}：语义层引用原始值
function resolveTokens(obj, tokenMap, depth = 0) {
  const MAX_DEPTH = 20
  if (depth > MAX_DEPTH) {
    throw new Error(
      `[ENGINEERING_FATAL] 令牌循环引用检测: ${JSON.stringify(obj)}`,
    )
  }
  if (typeof obj === "string") {
    return obj.replace(/\{([a-zA-Z0-9_-]+)\}/g, (match, key) => {
      const value = tokenMap[key]
      if (value === undefined) {
        console.warn(`⚠️ 警告: 令牌 "${key}" 未定义，保留原样`)
        return match
      }
      return resolveTokens(value, tokenMap, depth + 1)
    })
  }
  if (Array.isArray(obj))
    return obj.map((item) => resolveTokens(item, tokenMap, depth + 1))
  if (obj && typeof obj === "object") {
    const result = {}
    for (const [k, v] of Object.entries(obj)) {
      result[k] = resolveTokens(v, tokenMap, depth + 1)
    }
    return result
  }
  return obj
}

// 替换变量 ${var}：组件层引用语义层（支持透明后缀）
function replaceVariables(obj, colors) {
  if (typeof obj === "string") {
    return obj.replace(
      /\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g,
      (match, key, alpha) => {
        const value = colors[key]
        if (value === undefined) {
          console.warn(`⚠️ 警告: 变量 "${key}" 未定义，保留原样`)
          return match
        }
        return value + (alpha || "")
      },
    )
  }
  if (Array.isArray(obj))
    return obj.map((item) => replaceVariables(item, colors))
  if (obj && typeof obj === "object") {
    const result = {}
    for (const [k, v] of Object.entries(obj)) {
      result[k] = replaceVariables(v, colors)
    }
    return result
  }
  return obj
}

// 加载公共规则
const workbenchRaw = yaml.load(fs.readFileSync(PATHS.workbench, "utf8"))
const semanticRaw = yaml.load(fs.readFileSync(PATHS.semantic, "utf8"))

// 扫描并合并语言规则
let tokenColorsRaw = []
fs.readdirSync(PATHS.langDir)
  .filter((f) => f.endsWith(".yaml"))
  .sort()
  .forEach((file) => {
    const rules = yaml.load(
      fs.readFileSync(path.join(PATHS.langDir, file), "utf8"),
    )
    if (rules?.tokenColors) {
      tokenColorsRaw = tokenColorsRaw.concat(rules.tokenColors)
    }
  })

// 读取 package.json 获取主题基础名
const pkg = JSON.parse(
  fs.readFileSync(path.join(ROOT_DIR, "package.json"), "utf8"),
)
const baseName = pkg.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase()

// 为每个语义层文件构建一个主题
const semanticFiles = fs
  .readdirSync(PATHS.semanticsDir)
  .filter((f) => f.endsWith(".yaml"))

semanticFiles.forEach((semanticFile) => {
  const themeType = path.basename(semanticFile, ".yaml") // 'dark' 或 'light'
  const semantics = yaml.load(
    fs.readFileSync(path.join(PATHS.semanticsDir, semanticFile), "utf8"),
  )

  // 1. 解析语义层的令牌引用 {token} -> 最终色值
  const resolved = resolveTokens(semantics, primitives)

  // 2. 组件层替换变量 ${var}
  const uiColors = replaceVariables(workbenchRaw, resolved)
  const semanticColors = replaceVariables(semanticRaw, resolved)
  const tokenColors = replaceVariables(tokenColorsRaw, resolved)

  // 3. 组装主题对象
  const type = themeType.includes("light") ? "light" : "dark"
  const theme = {
    name: `${pkg.displayName || "My Theme"} ${themeType === "dark" ? "Dark" : "Light"}`,
    type: type,
    colors: uiColors,
    tokenColors: tokenColors,
    semanticTokenColors: semanticColors,
  }

  // 4. 写入输出文件
  const outputFile = path.join(PATHS.outputDir, `${baseName}-${themeType}.json`)
  if (!fs.existsSync(PATHS.outputDir)) {
    fs.mkdirSync(PATHS.outputDir, { recursive: true })
  }
  fs.writeFileSync(outputFile, JSON.stringify(theme, null, 2))
  console.log(`   ✅ 构建完成: ${outputFile}`)
})

核心逻辑：

1. 加载原始值。
2. 扫描 semantics/ 目录，每个语义层文件（dark.yaml / light.yaml）对应一个主题。
3. 解析语义层的 {token} 引用，得到该变体的最终色值字典。
4. 组件层用 ${var} 替换为最终色值。
5. 输出 ${baseName}-dark.json 和 ${baseName}-light.json。

新增主题的成本：只需在 semantics/ 目录下添加一个新的 YAML 语义层文件（如 sepia.yaml），构建脚本自动扫描生成对应主题。无需修改任何规则文件。

🔮 预告：构建逻辑越来越复杂——解析令牌、替换变量、合并规则、扫描语义层。你可能会问：怎么证明它写得对？ 当颜色出错、scope 匹配不上时，如何自动发现？这就是下一篇引入自动化测试与质量验证的原因。

📦 五、注册多个主题

在 package.json 的 contributes.themes 中为每个主题添加一个条目，注意 uiTheme 字段的正确设置：

"contributes": {
  "themes": [
    {
      "label": "Moongate Dark",
      "uiTheme": "vs-dark",
      "path": "./themes/moongate-theme-dark.json"
    },
    {
      "label": "Moongate Light",
      "uiTheme": "vs",
      "path": "./themes/moongate-theme-light.json"
    }
  ]
}

• uiTheme 字段决定主题的基础色系：
  • 深色主题："vs-dark"
  • 浅色主题："vs"
• label 将显示在 VS Code 命令面板的「颜色主题」列表中。

📌 一个容易踩的坑：如果浅色主题的 uiTheme 误设为 "vs-dark"，VS Code 会按照深色基础色系渲染控件（滚动条、输入框等），导致浅色主题出现深色控件——看起来很别扭。务必根据主题类型设置正确的 uiTheme。

🌐 六、跨平台资产：颜色不只是主题

DTCG 三层架构还有一个额外的巨大收益：语义层的颜色字典可以直接导出为跨平台资产。

构建脚本可以在生成主题 JSON 的同时，自动生成一个 CSS 变量文件：

/* themes/moongate-colors.css（自动生成） */
:root,
.light {
  --ui-primary: #0284c7;
  --ui-bg: #f9fafb;
  --ui-surface-raised: #ffffff;
  /* ... 浅色模式所有语义色 */
}

.dark {
  --ui-primary: #3b82f6;
  --ui-bg: #0f172a;
  --ui-surface-raised: #1a2538;
  /* ... 深色模式所有语义色 */
}

这意味着你的博客、组件库、文档站可以直接引用主题的视觉语言：

<link rel="stylesheet" href="/themes/moongate-colors.css" />

body {
  background: var(--ui-bg);
  color: var(--ui-text);
}

切换深浅模式只需要在根元素上添加/移除 .dark class：

document.documentElement.classList.toggle("dark")

Moongate 正是这样做的——博客、设计系统文档与 VS Code 主题共享同一套颜色，实现「一个颜色体系，贯穿所有产品」。除了 CSS，还可以自动生成 SCSS 和 TypeScript 令牌（见构建体系）。

⚠️ 七、常见问题与陷阱

🚀 八、总结

通过引入 DTCG 三层架构，你将「多主题」升级为「设计系统」：

• ✅ 原始值层：颜色按色相-明度命名，成为可追溯的物理事实。
• ✅ 语义层：角色与变体解耦，每个变体只定义「角色该是什么颜色」。
• ✅ 组件层：规则文件完全复用，不写任何具体色值。
• ✅ 重力补偿：同一语义角色在不同背景下视觉重量对等。
• ✅ 海拔系统：UI 拥有物理深度，深浅模式层次一致。
• ✅ 一键扩展：新增主题只需添加一个语义层文件。
• ✅ 跨平台资产：语义层直接导出 CSS 变量，一套颜色贯穿所有产品。

但你可能已经注意到：本篇的构建脚本仍然比较简单——它只能做变量替换，还不能验证颜色是否符合对比度标准、是否引用了未定义的变量、是否产生了架构污染。而且随着语言数量增加（当前 Moongate 支持 15 种语言），「语言规则写了对不上」的问题也会浮现。

下一篇将解决这些问题——如何让构建脚本自身成为一套可测试、可验证的工程体系。

构建体系：可测试、可验证的工程实践

本系列共五篇，覆盖从零基础创建到工业级设计系统的 VS Code 主题开发全流程（对应 Moongate v2.6.0）：

1. VS Code 主题：从手写 JSON 到可发布 —— 不依赖脚手架，手写最小主题 JSON，掌握 colors 与 tokenColors 的核心机制与发布流程。

2. 主题工程化：从单体 JSON 到模块化 YAML —— 将单体 JSON 重构为模块化 YAML 项目，用构建脚本实现变量替换与自动生成。

3. 设计系统：DTCG 三层架构与昼夜双变体 —— 用 DTCG 设计令牌标准管理颜色，通过语义层与重力补偿构建深色/浅色双变体。

4. 构建体系：可测试、可验证的工程实践 —— 模块化构建体系、WCAG 对比度校验、scope 自动验证、自动化测试与多格式产物生成。

5. 品牌生态：设计哲学与视觉契约 —— 为你的主题赋予设计哲学、视觉契约和品牌生态，打造完整的设计系统。

在VS Code 主题中，你已经学会了如何手写一个可发布的 VS Code 主题。但随着主题功能越来越丰富，你可能遇到了以下痛点：

• 一个 JSON 文件动辄上千行，修改一个颜色需要全局搜索，容易误改。
• 想为不同语言定制高亮，却要在同一个 tokenColors 数组里堆砌规则，难以维护。
• 想尝试浅色版本，不得不复制整个文件，然后手动修改几百个颜色值。

是时候引入工程化了！本篇将带你将一个单体的 JSON 主题重构为模块化、可自动构建的工程化项目：用 YAML 拆分源文件，用构建脚本自动合并与变量替换。

💡 本篇的定位：本文采用的「单一颜色变量文件 + 构建脚本」方案是工程化的第一步。在设计系统中，这个方案会进一步升级为 DTCG 三层架构（原始值 → 语义层 → 组件层）。建议按顺序阅读，理解每一步的动机。

📦 准备工作

首先确保你已经安装了 Node.js 和 npm（或 pnpm）。然后安装构建依赖：

pnpm add -D js-yaml
# 或
npm install --save-dev js-yaml

⚠️ 注意：js-yaml 必须安装在 devDependencies 中，因为它只是构建工具，不应作为生产依赖随主题发布。

📁 设计目录结构

我们将源码放在 src/ 目录下，构建脚本放在 scripts/，最终生成的 JSON 放在 themes/：

your-theme/
├── src/
│   ├── core/
│   │   └── colors.yaml          # 颜色变量（主色、背景、文本等）
│   ├── languages/                # 各语言的语法规则
│   │   ├── base.yaml             # 跨语言通用规则
│   │   ├── python.yaml
│   │   ├── go.yaml
│   │   └── ... (其他语言)
│   ├── workbench.yaml             # UI 颜色（colors 对象）
│   └── semantic.yaml              # 语义高亮（semanticTokenColors）
├── scripts/
│   └── build.js                   # 构建脚本
├── themes/
│   └── your-theme.json            # 构建生成的最终文件
├── package.json
└── .vscodeignore

📌 注：上图中的 languages/ 目录中并没有 javascript.yaml、typescript.yaml——因为 JS/TS 的语法规则完全被 base.yaml 的通用规则覆盖，无需单独文件。这也是「通用规则 + 语言独有规则」架构的核心思路：只在语言文件里放真正独有的规则。

🎨 第一步：提取颜色变量

打开你原有的主题 JSON，找出所有 colors 对象中的颜色值以及 tokenColors 中反复出现的颜色，将它们定义为变量。创建 src/core/colors.yaml：

# 核心颜色变量
primary: "#3b82f6" # 主蓝
success: "#34d399" # 成功绿
warning: "#fbbf24" # 警告黄
error: "#f87171" # 错误红
highlight: "#7dd3fc" # 发光蓝

bg: "#0f172a" # 背景
bgMuted: "#1e293b" # 次级背景
text: "#e2e8f0" # 前景色
textMuted: "#94a3b8" # 辅助文字
border: "#2d3748" # 边框

# ... 其他变量

⚠️ 重要规则：

• 变量名使用驼峰或小写连字符，并且只使用字母、数字和下划线。
• 变量中不要包含透明度（如 #3b82f620 中的 20），透明度应通过后缀 ${primary}20 在引用时添加，构建脚本会自动拼接。
• 确保 colors.yaml 覆盖了所有将在其他文件中引用的变量，否则构建时会警告并保留原样。

✂️ 第二步：拆分语法规则

将 tokenColors 数组按语言拆分为多个 YAML 文件。以 src/languages/base.yaml 为例，存放所有语言共用的规则：

# 通用规则（base.yaml）
tokenColors:
  - name: Comment
    scope: ["comment", "punctuation.definition.comment"]
    settings:
      fontStyle: "italic"
      foreground: "${comment}"

  - name: Keyword
    scope: ["keyword", "storage.type", "storage.modifier"]
    settings:
      foreground: "${primary}"
      fontStyle: "bold"

  - name: String
    scope: ["string", "string.quoted.single", "string.quoted.double"]
    settings:
      foreground: "${success}"
  # ... 其他通用规则

核心原则：base.yaml 已有的通用规则（关键字、字符串、注释、操作符、变量等），语言文件不再重复定义。语言文件只放真正属于该语言的独有规则。

以 src/languages/go.yaml 为例，只包含 Go 的特有语法元素：

# Go 专用规则（go.yaml）
tokenColors:
  - name: Go Package Clause
    scope: ["source.go keyword.package.go"]
    settings:
      foreground: "${primary}"
      fontStyle: "bold"

  - name: Go Struct
    scope: ["keyword.struct.go"]
    settings:
      foreground: "${warning}"
      fontStyle: "bold"

  - name: Go Error Variable
    scope: ["variable.other.object.err.go"]
    settings:
      foreground: "${error}"
      fontStyle: "italic"
  # ... 其他 Go 独有规则

这种「通用 + 独有」的架构让每个文件的职责都非常清晰：

• 修改通用配色 → 只改 base.yaml 一处，全局生效。
• 为 Go 添加独有规则 → 只动 go.yaml，不影响其他语言。
• 想了解某语言的完整配色 → 看 base.yaml + 对应语言文件即可。

🧩 第三步：拆分 UI 颜色和语义规则

将 colors 对象移到 src/workbench.yaml，并将所有颜色值替换为变量引用：

# 编辑器 UI 颜色（workbench.yaml）
editor.background: "${bg}"
editor.foreground: "${text}"
titleBar.activeBackground: "${bg}"
titleBar.activeForeground: "${text}"
statusBar.background: "${bg}"
statusBar.foreground: "${textMuted}"
# ... 所有 UI 键

将 semanticTokenColors 移到 src/semantic.yaml，同样使用变量：

# 语义高亮规则（semantic.yaml）
variable: "${variable}"
function: "${function}"
class: "${warning}"
"*.decorator":
  foreground: "${purple}"
  fontStyle: "italic"
# ... 其他语义规则

🔍 注意：在 YAML 中，键名如果包含特殊字符（如 *.decorator）必须用双引号括起来，否则 YAML 解析会失败。

🔨 第四步：编写构建脚本

创建 scripts/build.js，使用 ESM（ES Module） 语法。它的任务是：

1. 加载 colors.yaml 获得变量字典。
2. 加载 workbench.yaml、semantic.yaml 以及 languages/ 下的所有语言规则。
3. 递归替换所有 ${变量名} 为实际颜色值（支持透明度后缀）。
4. 合并 tokenColors（base.yaml 先合并、语言规则后合并，后面的规则拥有更高优先级）。
5. 输出最终的 JSON 到 themes/。

// scripts/build.js
import fs from "node:fs"
import path from "node:path"
import yaml from "js-yaml"
import { fileURLToPath } from "node:url"

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const ROOT_DIR = path.resolve(__dirname, "..")

// 路径配置（根据你的项目结构调整）
const PATHS = {
  colors: path.join(ROOT_DIR, "src", "core", "colors.yaml"),
  workbench: path.join(ROOT_DIR, "src", "workbench.yaml"),
  semantic: path.join(ROOT_DIR, "src", "semantic.yaml"),
  langDir: path.join(ROOT_DIR, "src", "languages"),
  outputDir: path.join(ROOT_DIR, "themes"),
}

// 加载颜色变量
const colors = yaml.load(fs.readFileSync(PATHS.colors, "utf8"))

// 递归替换 `${var}`，支持两位十六进制透明度后缀（如 ${primary}20）
function replaceVariables(obj) {
  if (typeof obj === "string") {
    return obj.replace(/\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g, (match, key, alpha) => {
      const value = colors[key]
      if (value === undefined) {
        console.warn(`⚠️ 警告: 变量 "${key}" 未定义，保留原样`)
        return match
      }
      return value + (alpha || "")
    })
  }
  if (Array.isArray(obj)) {
    return obj.map(replaceVariables)
  }
  if (obj && typeof obj === "object") {
    const result = {}
    for (const [k, v] of Object.entries(obj)) {
      result[k] = replaceVariables(v)
    }
    return result
  }
  return obj
}

// 读取并解析 YAML
function loadYaml(filePath, description) {
  try {
    return yaml.load(fs.readFileSync(filePath, "utf8"))
  } catch (err) {
    console.error(`❌ 解析 ${description} 失败:`, err.message)
    return null
  }
}

// 加载 UI 颜色与语义规则
const workbench = replaceVariables(loadYaml(PATHS.workbench, "workbench.yaml"))
const semantic = replaceVariables(loadYaml(PATHS.semantic, "semantic.yaml"))

// 自动扫描 languages/ 目录下所有 YAML 文件，按文件名排序合并
// base.yaml 会被优先加载（作为通用规则），
// 语言专属规则随后合并（覆盖通用规则中相同 scope 的规则）
let tokenColors = []

if (fs.existsSync(PATHS.langDir)) {
  const langFiles = fs
    .readdirSync(PATHS.langDir)
    .filter((f) => f.endsWith(".yaml"))
    .sort() // base.yaml 按字母序排在最前

  for (const file of langFiles) {
    const rules = loadYaml(path.join(PATHS.langDir, file), `语言规则 ${file}`)
    if (rules?.tokenColors) {
      tokenColors = tokenColors.concat(rules.tokenColors)
      console.log(`   ✅ 已加载: ${file}`)
    }
  }
}

// 替换 tokenColors 中的变量
const processedTokenColors = replaceVariables(tokenColors)

// 确保输出目录存在
if (!fs.existsSync(PATHS.outputDir)) {
  fs.mkdirSync(PATHS.outputDir, { recursive: true })
}

// 构建最终主题对象
const theme = {
  name: "Your Theme Name",
  type: "dark",
  colors: workbench,
  tokenColors: processedTokenColors,
  semanticTokenColors: semantic,
}

// 写入文件
const outputFile = path.join(PATHS.outputDir, "your-theme.json")
fs.writeFileSync(outputFile, JSON.stringify(theme, null, 2))
console.log("✅ 主题构建完成！")

⚠️ 注意事项：

• 自动扫描而非手动排列：与过去手动维护 order 数组不同，这里直接扫描 languages/ 目录并按文件名排序。base.yaml 按字母序天然排在最前，其余语言文件按字母序排在其后——后合并的规则覆盖前面相同 scope 的规则，语言专属规则天然拥有更高优先级。新增语言时只需添加 YAML 文件，无需修改构建脚本。
• 如果颜色变量未定义，脚本会给出警告，生成的 JSON 中会保留 ${var} 占位符，导致主题无效。务必确保所有变量均已定义。
• 透明度后缀格式：透明度后缀使用两位十六进制数（00–FF），其中 20 对应约 12.5% 透明度，80 对应 50%，FF 对应完全不透明。这种表示法直接对应 CSS 的 #RRGGBBAA 格式，便于构建脚本直接拼接。
• 变量名仅使用字母、数字和下划线（如 primary、primaryColor），避免使用连字符或其他符号——因为正则表达式 \$\{([a-zA-Z0-9_-]+)\} 只匹配这些字符。

⚙️ 第五步：集成到 package.json

在 package.json 的 scripts 中添加构建命令，并设置 prepublishOnly 自动构建：

{
  "scripts": {
    "build": "node scripts/build.js",
    "prepublishOnly": "npm run build"
  }
}

🔍 检查：确保 js-yaml 在 devDependencies 中，而不是 dependencies。因为它是构建工具，不应随主题发布。

✨ 开发体验优化：实时预览与自动构建

手动运行 npm run build 每次修改后都很繁琐。我们可以添加一个 watch 模式，让构建脚本在源码文件变化时自动执行，实现「修改即预览」的高效工作流。

1. 安装 nodemon

nodemon 是一个常用的工具，可以监视文件变化并自动重启命令。将它安装为开发依赖：

pnpm add -D nodemon
# 或
npm install --save-dev nodemon

2. 添加 watch 脚本

在 package.json 的 scripts 中添加以下两个命令：

{
  "scripts": {
    "build": "node scripts/build.js",
    "watch": "nodemon --watch src -e yaml --exec \"npm run build\"",
    "dev": "npm run watch",
    "prepublishOnly": "npm run build"
  }
}

• --watch src：监视 src 目录下的所有文件变化。
• -e yaml：只监视扩展名为 .yaml 的文件。
• --exec "npm run build"：文件变化时执行构建命令。

dev 脚本是 watch 的别名，方便记忆。

3. 使用 watch 模式

在开发过程中，打开终端运行：

npm run watch
# 或
npm run dev

终端会保持运行状态，每当你在 src/ 下修改并保存任何 YAML 文件时，构建脚本会自动执行，重新生成 themes/ 下的 JSON 文件。

配合 VS Code 的调试功能，你只需按 F5 启动扩展开发宿主，然后保持 watch 运行。修改源码后，在开发宿主中执行 Developer: Reload Window 即可立即看到效果，无需手动重新构建。

4. 注意事项

• nodemon 只是开发时的辅助工具，不需要随主题发布，因此务必安装在 devDependencies 中。
• 如果你的项目结构复杂，可以自定义 --watch 参数监视更多目录。
• 如果不想安装额外依赖，也可以使用 Node.js 自带的 fs.watch 编写简单的监视脚本，但 nodemon 更成熟易用。

📦 第六步：更新 .vscodeignore

确保发布时只包含最终产物，不包含源码和依赖。一个典型的 .vscodeignore 内容如下：

.vscode/**
.gitignore
vsc-extension-quickstart.md
node_modules
pnpm-lock.yaml
src/**
scripts/**
!themes/*.json

💡 说明：!themes/*.json 表示保留 themes 目录下的所有 JSON 文件，这些是构建产物。

✅ 第七步：测试构建

运行以下命令，检查生成的 JSON 是否与原文件一致：

npm run build

然后用 diff 工具对比新生成的 themes/your-theme.json 与原始 JSON，确保没有意外差异。如果有差异，请检查：

• 变量定义是否完整。
• 透明度后缀是否正确。
• 语言规则合并顺序是否符合预期。

🚀 第八步：享受工程化带来的便利

现在你的主题源码已经模块化，维护变得轻而易举：

• 想修改主色？只需改 colors.yaml 一处。
• 想为 Python 添加新规则？直接在 python.yaml 中增加条目。
• 想创建浅色版本？新建 colors-light.yaml，并调整构建脚本输出两个主题。

🔍 常见问题排查

📝 总结

通过工程化重构，你从一个难以维护的 JSON 单体进化到了一个清晰、可扩展的模块化项目。你已经拥有了：

• ✅ 模块化的 YAML 源文件（颜色、语言规则、UI、语义高亮分离）
• ✅ 自动合并与变量替换的构建脚本
• ✅ watch 模式实时预览开发
• ✅ 发布时自动构建的正确配置

但你可能已经注意到，上一篇文章的方案还有一些问题需要解决：

• colors.yaml 是一个扁平的变量池，颜色之间的层级关系（哪些是原始色、哪些是语义角色）完全靠命名约定，没有结构性的约束。
• 深浅两套主题需要两套颜色变量文件，而「同一角色在深色和浅色下应该保持色相一致、明度不同」这件事完全靠手动维护。
• 构建脚本只能做变量替换，还不能自动校验颜色是否符合对比度标准、是否引用了不存在的变量。

这些问题，正是我们下一篇要解决的——设计系统：DTCG 三层架构与昼夜双变体。

设计系统：DTCG 三层架构与昼夜双变体

本系列共五篇，覆盖从零基础创建到工业级设计系统的 VS Code 主题开发全流程（对应 Moongate v2.6.0）：

1. VS Code 主题：从手写 JSON 到可发布 —— 不依赖脚手架，手写最小主题 JSON，掌握 colors 与 tokenColors 的核心机制与发布流程。

2. 主题工程化：从单体 JSON 到模块化 YAML —— 将单体 JSON 重构为模块化 YAML 项目，用构建脚本实现变量替换与自动生成。

3. 设计系统：DTCG 三层架构与昼夜双变体 —— 用 DTCG 设计令牌标准管理颜色，通过语义层与重力补偿构建深色/浅色双变体。

4. 构建体系：可测试、可验证的工程实践 —— 模块化构建体系、WCAG 对比度校验、scope 自动验证、自动化测试与多格式产物生成。

5. 品牌生态：设计哲学与视觉契约 —— 为你的主题赋予设计哲学、视觉契约和品牌生态，打造完整的设计系统。

如果你有编程基础（熟悉 JavaScript、JSON、命令行），想把一套配色方案变成 VS Code 主题，但完全不知道从何下手——这篇文章正是为你准备的。

Moongate 主题最初就是从个人博客的配色衍生而来。在这篇文章中，我们不使用任何脚手架，而是从一个最小的 JSON 文件开始，逐步理解主题的运作机制。等机制清楚了，你自然会发现哪些环节需要工程化——那就是整个系列接下来要做的事。

一、VS Code 主题的本质

一个主题说到底就是一份 JSON 文件，它告诉 VS Code 两件事：

• 界面长什么样：标题栏、状态栏、侧边栏、编辑器背景……这些 UI 区域的颜色。
• 代码怎么着色：不同的语法元素（关键字、字符串、注释、函数……）分别用什么颜色和样式。

理解文件结构本身并不难，真正难的是知道该配置哪些键名、每个键名是什么意思。所以这篇文章的核心目标是：带你亲手创建一个最小可用的主题，然后告诉你如何用 VS Code 自带的工具，找到任何你想调整的颜色所对应的正确键名。

二、自定义主题的最小路径

1. 创建项目结构

首先准备一个空目录，并创建 themes/ 文件夹：

mkdir my-theme
cd my-theme
mkdir themes

虽然 VS Code 的扩展项目通常还需要 package.json、README.md 等文件，但为了让读者先专注理解结构，这里从主题 JSON 本身开始。

2. 编写最小主题 JSON

在 themes/ 下创建一个 JSON 文件，例如 my-theme.json：

{
  "name": "My Theme",
  "type": "dark",
  "colors": {
    "editor.background": "#0f172a",
    "editor.foreground": "#e2e8f0"
  },
  "tokenColors": [
    {
      "name": "Comment",
      "scope": ["comment", "punctuation.definition.comment"],
      "settings": {
        "fontStyle": "italic",
        "foreground": "#a5b4cb"
      }
    },
    {
      "name": "Keyword",
      "scope": ["keyword", "storage.type", "storage.modifier"],
      "settings": {
        "foreground": "#3b82f6",
        "fontStyle": "bold"
      }
    },
    {
      "name": "String",
      "scope": ["string", "string.quoted.single", "string.quoted.double"],
      "settings": {
        "foreground": "#34d399"
      }
    }
  ]
}

这个文件虽然很小，但它已经包含了主题的全部核心结构。

三、核心概念：colors 与 tokenColors

colors：编辑器界面

colors 对象定义编辑器 UI 的配色——背景、标题栏、状态栏、侧边栏、选区高亮等。它是一个扁平的对象，键名是 VS Code 预定义的接口，例如：

⚠️ type 字段：顶级 type 字段决定主题是深色还是浅色，取值为 "dark" 或 "light"。它会影响 VS Code 默认控件的渲染方式（如滚动条、输入框的自适应）。

tokenColors：代码语法高亮

tokenColors 是一个规则数组，每条规则由 scope 和 settings 组成：

• scope：匹配的 TextMate 作用域（scope），可以是字符串或字符串数组。
• settings：该作用域应用的颜色与样式（foreground、fontStyle、background）。

{
  "name": "Comment",
  "scope": ["comment", "punctuation.definition.comment"],
  "settings": {
    "fontStyle": "italic",
    "foreground": "#a5b4cb"
  }
}

⚠️ 重要：tokenColors 数组的顺序很重要——后面的规则会覆盖前面相同 scope 的规则。这也是为什么工程化之后我们会用一个独立的 base.yaml 管理通用规则，再在语言文件中叠加专属规则。

四、如何找到正确的键名？

这是所有主题开发者最常遇到的问题：「我想把状态栏文字改成蓝色，该用什么键名？」

VS Code 提供了两个非常强大的内置工具，彻底解决了这个问题。

1. UI 颜色：提取当前主题

按下 Ctrl+Shift+P，运行命令 Developer: Generate Color Theme From Current Settings。

这会在输出面板中生成一个 JSON，包含当前主题所用到的所有 UI 颜色键名以及它们的值。你只需要：

1. 在输出中找到你关心的区域（比如 statusBar.foreground）。
2. 复制这个键名，粘贴到你自己的 colors 对象中。
3. 改成你自己的颜色值。

这个命令生成的是「当前生效值」，即使某个键名你从未配置过（VS Code 在使用默认值），它也会出现在输出中——相当于一份完整的键名清单。

2. 语法 scope：Inspect 工具

这是定位语法高亮问题的神器。打开任意代码文件，把光标放在你想着色的元素上，运行 Developer: Inspect Editor Tokens and Scopes。

弹出的窗口会显示：

• 该元素当前的 TextMate scope 链，从最具体到最通用。
• 当前颜色来自哪条规则（foreground 来源），以及是哪个文件定义的。

使用技巧：

• 选择最具体的 scope 来精确命中目标元素，避免误伤同一族元素。
• 例如注释既有 comment.line 也有 comment.block，如果你只想给行注释着色，就选 comment.line；如果想统一处理所有注释，就选 comment。
• 当你发现某个元素颜色「不对」时，Inspect 窗口会直接告诉你当前颜色来自哪个规则——这排查思路清晰得多。

五、本地调试

在确认主题文件书写正确后，下一步就是把它加载进 VS Code 实时查看。

1. 创建 package.json

要运行主题扩展，需要一个最小的 package.json 将它声明为扩展：

{
  "name": "my-theme",
  "displayName": "My Theme",
  "version": "0.0.1",
  "publisher": "your-name",
  "engines": {
    "vscode": "^1.109.0"
  },
  "categories": ["Themes"],
  "contributes": {
    "themes": [
      {
        "label": "My Theme",
        "uiTheme": "vs-dark",
        "path": "./themes/my-theme.json"
      }
    ]
  }
}

关键字段：

• contributes.themes：声明主题列表，每项包含 label（在颜色主题列表中显示的名称）、uiTheme（基础色系：vs-dark 深色 / vs 浅色）、path（主题 JSON 的相对路径）。
• publisher：你的发布者 ID。可以先填占位符，发布前注册后再回来修改。
• engines：最低 VS Code 版本要求。

2. F5 启动扩展开发主机

1. 在 VS Code 中打开项目文件夹。
2. 按 F5，启动「扩展开发主机」窗口。
3. 在开发主机中按 Ctrl+K Ctrl+T，选择你的主题。
4. 打开测试代码文件，实时查看效果。

修改主题 JSON 后，在开发主机中按 Ctrl+R 重新加载，修改立即生效。注意：修改 package.json 中的 contributes.themes 后，需要重启开发主机会话才能生效。

六、准备发布

1. 完善 package.json

发布之前，需要补全关键字段：

{
  "name": "my-theme",
  "displayName": "My Theme",
  "description": "简短介绍你的主题",
  "version": "1.0.0",
  "publisher": "你的发布者ID",
  "engines": { "vscode": "^1.109.0" },
  "categories": ["Themes"],
  "icon": "images/icon.png",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/my-theme"
  }
}

2. 准备截图

在根目录创建 images/ 文件夹，放入至少 3-5 张不同语言的代码截图（建议 1280×640），用于 README 和商店展示。

3. 编写 README.md

包含主题名称、预览截图、设计理念、安装方法、配色表（可选）等。

4. 添加 LICENSE

建议使用 MIT 许可证，创建 LICENSE 文件。

5. 创建 .vscodeignore

排除不需要打包的文件，但务必保留 images/ 文件夹：

.vscode/**
.gitignore
node_modules

七、发布前检查清单

在运行 vsce package 之前，花两分钟核对以下事项，可以避免大部分常见的发布错误：

• package.json 信息：确保 publisher、name、version 字段正确无误（publisher 必须与你在市场注册的 ID 完全一致）。
• 图标文件：确认 icon 路径指向一个 128×128 像素的 PNG 图片，且文件确实存在于该位置。
• 预览图：检查 README.md 中是否包含了至少一张主题预览图（建议使用 images/ 文件夹内的截图），没有预览图的主题很难吸引用户。
• .vscodeignore 配置：确认已排除不必要的文件，但务必保留 images/ 文件夹，否则截图无法随扩展一起发布。
• 本地打包测试：运行 vsce package 命令，若能成功生成 .vsix 文件，说明配置基本正确。如果失败，仔细阅读错误提示——最常见的原因是 icon 路径错误或 publisher 未设置。

八、打包与发布

1. 安装发布工具

npm install -g @vscode/vsce

2. 打包测试

vsce package

如果成功，会生成 .vsix 文件。可以拖进 VS Code 手动安装测试。若失败，仔细阅读错误提示，常见原因是 icon 路径错误或 .vscodeignore 误排除了必要文件。

3. 获取 Personal Access Token

• 登录 Azure DevOps（用你注册市场的微软账号）。
• 右上角头像 → Personal access tokens → New Token。
• 名称随意，组织选 All accessible organizations，有效期建议 1 年。
• 权限：只勾选 Marketplace → Manage。
• 创建后立即复制 Token（只显示一次）。

4. 登录并发布

vsce login 你的发布者ID
# 粘贴刚才的 Token（不会显示，直接回车）

vsce publish

几秒后主题就会上传。约 5-10 分钟即可在 VS Code 中搜索到。

常见发布错误：

• Token verification failed：权限未正确设置或 Token 过期，重新生成。
• Version already exists：版本号重复，更新 package.json 中的 version。
• 网络问题：尝试更换网络或使用代理。

🔁 替代方案：手动上传 .vsix 文件

如果你在命令行方式中遇到困难，完全可以通过浏览器手动上传：

1. 首先确保你已经运行 vsce package 成功生成了 .vsix 文件。
2. 访问 VS Code 市场管理页，用你的微软账号登录。
3. 在页面中点击你的发布者名称，进入发布者管理界面。
4. 点击右上角的 Publish extension 按钮。
5. 选择你的 .vsix 文件上传。
6. 几分钟后主题就会出现在市场中。

优点：完全绕过命令行 token 验证，过程可视化。

九、发布后

• 查看市场页面：https://marketplace.visualstudio.com/items?itemName=你的发布者ID.你的主题名
• 登录 市场管理后台 查看报表（页面浏览、安装量、转化率）。
• 在 GitHub 仓库添加 README 徽章（如版本、下载量）。
• 收集反馈，准备后续更新。

十、设计哲学：从「好看」到「好用」

很多新手以为主题就是配几个好看的颜色。但真正优秀的主题，能让代码的结构自己「浮现」出来。这就是 「视觉远近法」 的理念：

• 操作符、标点应该退后（亮度低一些），不干扰阅读；
• 函数名应该发光（亮度高一些），成为视觉锚点；
• 只读变量应该用斜体暗示「不可变」；
• 废弃代码应该加上删除线，一眼识别。

这套原则在 Moongate 中落地为「语义分层」：前景（核心逻辑）、中景（普通代码）、背景（辅助信息）三个视觉层级。你可以在后续的系列文章中看到它如何演变为完整的设计体系。

为什么手写 JSON 不可持续？

现在你已经拥有一个可以手动编辑、可以发布的 VS Code 主题了。但当你认真用起来，很快就会遇到这些痛点：

• 一个 JSON 文件动辄上千行，修改一个颜色需要全局搜索，容易误改。
• 想为不同语言定制高亮，却要在同一个 tokenColors 数组里堆砌规则，难以维护。
• 想尝试浅色版本，不得不复制整个文件，然后手动修改几百个颜色值。
• 一个不小心，就会用错 scope，某个语言的高亮「规则写了对不上」。

这些问题不是你的失误，而是手写 JSON 这种工作方式的极限。这正是我们接下来的系列要解决的问题——从工程化到设计系统，让主题维护变得轻松而优雅。

主题工程化：从单体 JSON 到模块化 YAML

本文记录了为组件库 Moongate Vue 编写单元测试时，在 jsdom 环境中测试 Teleport 组件的完整踩坑与收获。

背景

Moongate Vue 是一个包含 25 个组件的 Vue 3 组件库，其中 Modal（模态框）、Drawer（抽屉）、Message（消息）、Toast（通知）等都使用了 <Teleport to="body"> 将内容渲染到 document.body。

为了让测试环境尽量接近真实浏览器，我们选了 Vitest + jsdom 作为测试基础设施。原以为只是写几个断言的事，结果在 Teleport 组件上反复栽跟头——24 个测试失败，其中一大半都指向同一个诡异报错：

TypeError: Cannot read properties of null (reading 'insertBefore')

排查到最后发现，这不是巧合，而是 Teleport 机制 + jsdom 环境 + Vue 异步更新 三者在特定时序下的必然结果。下面按”坑 → 表现 → 根因 → 解法”拆解。

第一部分：Teleport 测试的 5 个陷阱

陷阱 1：Teleport 内容在 body 顶层，wrapper 查不到

表现：wrapper.find('.mg-modal-overlay') 返回空，即使组件已经通过 attachTo: document.body 挂载。

根因：Teleport 的目标元素是 body，其渲染内容作为 body 的直接子节点，不在 wrapper.element 子树内。即使能通过 wrapper.vm 访问到组件实例，Teleport 渲染的 v-if 内容也在 wrapper 管理的 DOM 树之外。

// ❌ 错误：wrapper 找不到 Teleport 内容
const wrapper = mount(Modal, { props: { modelValue: true } })
expect(wrapper.find(".mg-modal-overlay").exists()).toBe(true)

// ✅ 正确：从 body 顶层查询
const wrapper = mount(Modal, {
  props: { modelValue: true },
  attachTo: document.body, // ① 确保挂载到 body
})
expect(document.body.querySelector(".mg-modal-overlay")).not.toBeNull()

解法：

1. attachTo: document.body 确保组件渲染在 body 中
2. 断言 Teleport 内容永远用 document.body.querySelector，而不是 wrapper.find

陷阱 2：依赖自动卸载，触发 insertBefore on null

表现：测试断言全通过，但 Vitest 结束后抛出一个异步错误：

TypeError: Cannot read properties of null (reading 'insertBefore')
  at insert (runtime-dom.cjs.js:31)
  at processCommentNode ...

根因：Vue 的响应式更新是异步批量 patch 的。当测试结束时 wrapper 被自动卸载（或 document.body.innerHTML = '' 被清空），但 Vue 内部 scheduler 队列里还挂着上一轮渲染的 DOM patch 任务。这个 patch 试图操作已经脱离 DOM 的旧节点 → 崩溃。

Teleport 组件尤其容易触发，因为它的插入点（body）是测试环境里最容易被清空的目标。

解法：测试结束时显式卸载 wrapper，让 Teleport 有完整机会摘除自己：

import { mount } from "@vue/test-utils"

// 跟踪所有 wrapper，统一显式卸载
const wrappers: ReturnType<typeof mount>[] = []
const mountDrawer = (options = {}) => {
  const wrapper = mount(Drawer, { attachTo: document.body, ...options })
  wrappers.push(wrapper)
  return wrapper
}

afterEach(async () => {
  while (wrappers.length > 0) {
    const wrapper = wrappers.pop()!
    await wrapper.unmount() // 显式卸载，而非依赖自动清理
  }
})

陷阱 3：测试间 DOM 污染

表现：第一个测试用例渲染了一个 Modal，第二个用例查询 .mg-modal-overlay 莫名找到了上一轮残留的元素；或者反过来，第二个用例找不到预期元素。

根因：Teleport 把内容加到 document.body，但测试框架的自动清理不一定销毁它们。尤其当组件内部持有模块级缓存（比如我们的 createOverlay 共享容器 Map）时，残留引用会让 DOM 越积越多。

// ❌ 无法清理 Teleport 残留
afterEach(() => {
  document.body.innerHTML = "" // 直接把 body 清空
})

直接清空 body 是有问题的，因为 Vue 内部仍引用着这些节点，下一个 tick 的 patch 会对已移除节点操作而爆炸（这正是陷阱 2 的错误来源）。

解法：先 flush 再清空：

afterEach(async () => {
  await flushPromises() // ① 等待 Vue 异步作业（Teleport 移除、nextTick patch）完成
  document.body.innerHTML = "" // ② 再清空
})

⚠️ 注意：如果测试中使用了 vi.useFakeTimers()，flushPromises() 只能清空微任务队列，清不掉宏任务（如 setTimeout 触发的 DOM 操作）。此时应还原真实定时器，再清空 body：

afterEach(async () => {
  await flushPromises()
  // 若用了假定时器，直接还原真实定时器（会自动清空假定时器队列），比跑完所有宏任务更安全
  if (vi.isFakeTimers()) {
    vi.useRealTimers()
  }
  document.body.innerHTML = ""
})

⚠️ 避免 vi.runAllTimersAsync() 的陷阱：它会把所有宏任务（包括 setInterval、requestAnimationFrame 这类永久性定时器）循环跑完。如果被测组件内部有无限轮询或动画循环，这个调用会导致测试卡死/超时。还原真实定时器是更稳妥的清理方式。

陷阱 4：清理顺序错误，先清空 body 导致 Vue 找不到父节点

表现：诡异的是，把 document.body.innerHTML = '' 放在 afterEach 的开头反而报错，放在结尾就正常。

根因：Vue 的调度器不知道测试环境的存在。如果在 Vue 还没完成 last tick 的 DOM patch 时清空 body，等它去 patch 时父节点已经是 null。

正确的清理顺序必须是：

卸载所有 wrapper / destroyAllOverlays  →  flushPromises（若用了 fake timers 则 useRealTimers 还原）→  清空 body  →  restoreAllMocks

这是最容易忽略的一条。很多人（包括我）第一反应是”清空 body 嘛，什么时候不行”，结果 Vue 用崩溃告诉你不可以。

陷阱 5：v-model 关闭后立刻断言事件，但 DOM patch 还没发生

表现：点击关闭按钮后，wrapper.emitted('update:modelValue') 有值，但紧接着查询 document.body.querySelector('.mg-modal') 仍能查到（元素还在）。

根因：emit('update:modelValue', false) 是同步的，但 Teleport 移除 DOM 是异步 patch。事件已派发、DOM 还没更新。

解法：

1. 先操作 UI 再断言事件：wrapper.emitted(...) 是同步的，点击后立即可用
2. DOM 断言必须等待异步 patch：await flushPromises() 或 await wrapper.vm.$nextTick()
3. 先断言事件（同步派发），再断言 DOM（异步更新），在时间线上分离二者：

// ✅ 推荐写法：先触发 UI，事件同步断言；再等 DOM 异步更新
closeBtn.click()
expect(wrapper.emitted("update:modelValue")).toBeTruthy() // 事件是同步派发的
await flushPromises() // 等待 DOM 移除
expect(document.body.querySelector(".mg-modal")).toBeNull()

小结：Teleport 测试的黄金法则

第二部分：测试驱动顺手抓到的 2 个真实 Bug

写测试的过程中，失败的断言意外暴露了组件库本身的两个隐藏缺陷。这才是测试真正的价值——它不只是验证代码，而是替用户提前踩坑。

Bug 1：Input 组件的 change 事件完全丢失

现象：组件声明了 change 事件，但无论如何测试都收不到：

// Input.vue 中声明了
const emit = defineEmits<{
  /** 值变化时触发（原生事件透传） */
  change: [event: Event]
}>()

// 但测试始终收不到
wrapper.trigger("change")
expect(wrapper.emitted("change")).toHaveLength(1) // ❌ 失败

根因：模板里只绑定了 @input、@blur、@focus，漏掉了 @change。要理解为什么事件会”彻底消失”，需要先弄清 Vue 3 的事件透传机制：

Vue 3 中，组件模板上监听的未在 emits 中声明的事件，会被当作原生事件透传给根元素（进入 $attrs）；一旦在 emits 中声明，Vue 就认为该事件已由组件内部显式处理，不再透传。

因此，change 被 defineEmits 声明后，Vue 不会再把它透传给根 <input>。此时如果模板中又没有绑定 @change 处理器，这个事件就凭空消失了——既不会触发组件事件，也不会透传到原生元素。

<!-- 修复前：漏了 @change -->
<input @input="handleInput" @blur="handleBlur" @focus="handleFocus" />

<!-- 修复后 -->
<input
  @input="handleInput"
  @blur="handleBlur"
  @focus="handleFocus"
  @change="handleChange"
/>

教训：defineEmits 声明的事件如果没在模板绑定对应处理器，会被”吞掉”（既不触发、也不透传）。这条例外适用于所有组件库——尤其是表格、表单这类依赖原生事件透传的组件。

Bug 2：createOverlay 共享容器的孤儿引用

现象：测试清空 body 后，下一个用例创建 Message/Toast，查询容器时莫名失败。

根因：我们的 createOverlay 用模块级 Map 缓存共享容器（用于消息堆叠）：

// createOverlay.ts
const sharedContainers = new Map<string, HTMLDivElement>()

function getSharedContainer(containerClass: string) {
  let container = sharedContainers.get(containerClass)
  if (!container) {
    container = document.createElement("div")
    document.body.appendChild(container)
    sharedContainers.set(containerClass, container)
  }
  return container // ❌ 如果容器已被外部 remove，这里返回的是"孤儿节点"
}

当测试执行 document.body.innerHTML = '' 后，Map 里的容器引用已脱离 DOM（isConnected === false），但缓存没清空。下一个用例调用 createOverlay 时拿到孤儿节点，内容挂进去后从 document.body 查不到 → 失败。

修复：销毁逻辑增加 isConnected 检测，并提供同步清理 API：

// ① 容器可能已被外部移除时，同步从 DOM 摘除
if (container.childElementCount === 0 || !container.isConnected) {
  container.remove()
  sharedContainers.delete(containerClass)
}

// ② 新增同步清理 API，供测试/应用卸载使用
export function destroyAllOverlays(): void {
  activeInstances.forEach((instance) => {
    instance.element.remove()
    instance.app.unmount()
  })
  sharedContainers.clear()
  activeInstances.clear()
}

教训：动态挂载（createApp 手动管理生命周期）的工具，绝不能只依赖”元素存在”来判断是否复用——必须检测元素是否仍连接在文档树中（isConnected）。

附：可复现的最小示例

如果你想在本地复现这 5 个陷阱，下面是最小化的模板（完整可跑代码见 Moongate Vue 仓库 src/__tests__）：

<!-- MyTeleport.vue -->
<template>
  <div>
    <Teleport to="body">
      <div v-if="visible" class="my-overlay">overlay content</div>
    </Teleport>
    <button @click="visible = !visible">toggle</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
const visible = ref(true)
</script>

// my-teleport.test.ts —— 复现"不敢在 afterEach 清空 body"之坑
import { describe, it, expect, afterEach } from "vitest"
import { mount, flushPromises } from "@vue/test-utils"
import MyTeleport from "./MyTeleport.vue"

describe("MyTeleport", () => {
  afterEach(async () => {
    // ❌ 错误：先清空 body → Vue patch 崩溃
    // document.body.innerHTML = ''
    // ✅ 正确：先 flush 再清空
    await flushPromises()
    document.body.innerHTML = ""
  })

  it("Teleport 内容在 body 而非 wrapper", () => {
    const wrapper = mount(MyTeleport, { attachTo: document.body })
    expect(wrapper.find(".my-overlay").exists()).toBe(false) // wrapper 查不到
    expect(document.body.querySelector(".my-overlay")).not.toBeNull() // body 才能查到
  })
})

结语

这次为组件库补测试的经历，最大收获不是”写出了 204 个通过的断言”，而是验证了一个观点：测试环境（jsdom）不是浏览器，但它会以更严格的方式逼你直面组件实现和生命周期管理的每一处模糊地带。

Teleport 在 jsdom 中的这些坑，本质都是同一个问题：手动挂载（Teleport / createApp / 动态组件）产生的 DOM，其生命周期超出了组件 vnode 树的管理范围。这种”失控”在 jsdom 中会被放大——就像 Bug 2 中的孤儿引用，你以为清理干净了，实则残留的缓存和游离的 DOM 节点还在暗中作祟。理解了这一点，就掌握了应对所有类似场景（Portal、Dialog、Notification、ContextMenu）的思路。

最近在开发一个 VS Code 扩展，为自定义的 .meph 文件提供语法支持。其中有一个很自然的需求：用户输入 【 时，自动弹出标准区块名的补全列表。

注册方式按官方文档来：

vscode.languages.registerCompletionItemProvider(
  { language: "mephisto" },
  new MephistoCompletionProvider(),
  "【", // trigger character
  ".",
  "[",
)

预期行为是：输入 【 → 弹出补全 → 选择”角色名” → 自动变成 【角色名】。

实际表现：输入 【 后，auto-closing 自动补了 】，行变成 【】，但补全列表什么都没有。

2. 第一次排查：triggerCharacter 的问题

起初怀疑是 triggerCharacter 没生效。在 provideCompletionItems 开头加了一行测试代码：

provideCompletionItems() {
    return [new vscode.CompletionItem('测试-如果能看到我', CompletionItemKind.Text)];
    // ... 原有逻辑
}

重新加载扩展后，按 Ctrl+Space 手动触发补全，”测试-如果能看到我” 正常显示。

这说明 completion provider 本身注册成功了，也能正常返回数据。问题出在触发环节。

进一步测试发现，在中文输入法下 '【' 作为 trigger character 并不可靠。不是 【 本身不能作为 trigger——在英文输入法下直接输入 【 是可以触发补全的。问题在于中文输入法（如拼音）中，【 通常通过候选窗口选择输入，这个输入路径绕过了 VS Code 的 trigger character 检测机制。

改用 onDidChangeTextDocument 事件配合 triggerSuggest 命令，不依赖 trigger character，而是监听文档内容变化后强制弹出补全：

vscode.workspace.onDidChangeTextDocument((e) => {
  if (e.document.languageId === "mephisto") {
    for (const change of e.contentChanges) {
      if (change.text === "【") {
        vscode.commands.executeCommand("editor.action.triggerSuggest")
        break
      }
    }
  }
})

注意这里不需要 setTimeout(0)。根据 VS Code 的事件模型，onDidChangeTextDocument 在文档内容修改完成后才触发，此时 auto-closing 已经同步插入了 】，当前行已经是 【】 了。不过在极慢的扩展宿主环境下，setTimeout(0) 可以作为保险措施，但通常不需要。

3. 第二次排查：补全数据去哪了

用 onDidChangeTextDocument 替换 triggerCharacter 后，provider 确实被调用了，也返回了 9 个标准区块名。但补全列表依然是空的。

没有报错，没有警告，只有空荡荡的补全弹窗。

这就奇怪了：provider 返回了数据，VS Code 没有报错，为什么用户看不到？

4. 真正的原因：filterText

问题出在 VS Code 的补全过滤机制上。

当用户输入 【 后，auto-closing 立即插入 】，当前行变成了：

【】

光标在索引 1 的位置（【 和 】 之间）。此时 triggerSuggest 弹出补全，VS Code 自动提取光标位置的”当前词”作为过滤前缀。在 【】 中间，当前词就是 【。

然后 VS Code 拿 【 去匹配 provider 返回的每个补全项：

全部不匹配，所以全部被过滤掉。

这就是 filterText 的作用：它告诉 VS Code 用什么文本来做匹配，而不是用 label 作为匹配依据。

修复方式是在 getBlockCompletions 中设置 filterText：

private getBlockCompletions(): CompletionItem[] {
    const items: CompletionItem[] = [];
    for (const name of STANDARD_BLOCKS) {
        const item = new CompletionItem(name, CompletionItemKind.Module);
        item.insertText = name + '】\n';
        item.detail = '标准区块';
        item.filterText = '【' + name;  // ← 关键
        items.push(item);
    }
    return items;
}

• label（显示文本）仍然是”角色名”
• insertText（插入内容）仍然是 角色名】\n
• 但 filterText 设为 '【角色名'，VS Code 拿到当前词 【 去匹配 '【角色名' → 匹配成功 → 显示在列表中

5. CompletionItem 的文本相关属性

CompletionItem 有三个与文本相关的属性：

默认情况下，filterText 等于 label。当补全项 label 与触发字符（当前词）不匹配时，需要显式设置 filterText 来提供正确的匹配文本。

值得注意的是，VS Code 的过滤是 fuzzy matching（模糊匹配），不是严格的前缀匹配。filterText 的值会参与评分算法，当前词不需要严格作为 filterText 的前缀也能匹配。但在这个场景中，设 filterText 为 '【角色名' 已经足够让 【 匹配上了。

此外，sortText 控制补全列表的排序顺序：

item.sortText = "0" + name // 标准区块排在前面
item.sortText = "1" + name // 其他项排在后面

CompletionItemKind 则影响显示的图标：

item.kind = CompletionItemKind.Module // 方块图标
item.kind = CompletionItemKind.Class // 菱形图标
item.kind = CompletionItemKind.Struct // 结构体图标

挑一个视觉上顺眼的即可。

6. 最终代码

将上述改动整合在一起，最终实现如下：

// extension.ts — 监听中文输入法下的 【 输入
vscode.workspace.onDidChangeTextDocument(e => {
    if (e.document.languageId !== 'mephisto') return;
    for (const change of e.contentChanges) {
        if (change.text === '【') {
            vscode.commands.executeCommand('editor.action.triggerSuggest');
            break;
        }
    }
});

// completion.ts — CompletionProvider 中设置 filterText 和 range
private getBlockCompletions(): CompletionItem[] {
    return STANDARD_BLOCKS.map(name => {
        const item = new CompletionItem(name, CompletionItemKind.Module);
        item.insertText = name + '】\n';
        item.filterText = '【' + name;
        item.detail = '标准区块';
        return item;
    });
}

7. 总结

核心要点回顾

一句话总结

filterText 解决的是”拿什么去匹配“的问题，range 解决的是”当前要匹配的词是哪个“的问题。两者结合，能应对大多数补全过滤异常的场景。

最终的完整解决方案

// 1. 监听输入触发补全（不依赖 triggerCharacter）
vscode.workspace.onDidChangeTextDocument(e => {
    if (e.document.languageId !== 'mephisto') return;
    for (const change of e.contentChanges) {
        if (change.text === '【') {
            vscode.commands.executeCommand('editor.action.triggerSuggest');
            break;
        }
    }
});

// 2. 在 CompletionProvider 中设置 filterText 和 range
provideCompletionItems(document: vscode.TextDocument, position: vscode.Position) {
    const line = document.lineAt(position.line).text;
    const openIdx = line.indexOf('【');
    const closeIdx = line.indexOf('】');

    if (openIdx !== -1 && closeIdx !== -1 && position.character > openIdx && position.character <= closeIdx) {
        const items = STANDARD_BLOCKS.map(name => {
            const item = new vscode.CompletionItem(name, vscode.CompletionItemKind.Module);
            item.insertText = name + '】\n';
            item.filterText = '【' + name;
            item.range = new vscode.Range(
                new vscode.Position(position.line, openIdx),
                new vscode.Position(position.line, openIdx + 1)
            );
            item.detail = '标准区块';
            return item;
        });
        return items;
    }
    // 其他补全逻辑...
}

排查清单

当你在 VS Code 扩展中发现补全不显示时：

1. 补全列表完全没出现 → 检查 triggerCharacter / triggerSuggest 是否生效
2. 补全列表弹出了但什么都没有 → 检查 provider 是否返回了数据（加一个测试项验证）
3. 确认返回了数据但用户看不到 → 检查 filterText 是否匹配当前词
4. 以上都无效 → 检查 wordPattern 或设置 range

其中第 3 步是最容易忽略的，因为 VS Code 不会告诉你它过滤掉了什么。

前置阅读：这是本系列的最后一篇，建议先读前五篇——第一篇了解 .meph 格式，第二篇上手实操，第三、四篇理解解析器如何输出 domain.Contract，第五篇理解测试如何保障行为稳定。本篇假设你已经知道引擎拿到了 contract 结构体，要解决的核心问题是：怎么驱动它运转起来？

一、叙事引擎的第五个问题：怎么让规则活起来？

解析器把契约变成了结构体，但结构体不会叙事。一个叙事引擎还需要运行时——输入 → 匹配 → 执行 → 输出的完整闭环。

这里要解决的工程问题有三个：

1. 规则怎么实时匹配？ 用户输入到达时，引擎需要遍历所有规则、评估条件、决定触发哪些动作——这个过程必须在毫秒级完成，不能影响用户体验。
2. LLM 怎么遵守规则？ 规则不能直接约束 LLM 的行为，它们必须通过 Prompt 间接生效。怎么把规则”翻译”成 LLM 能理解的格式，是这个环节的核心难点。
3. 状态和记忆怎么持续？ 每一轮对话都会改变角色的状态和记忆池，但下一轮对话开始时，引擎必须恢复上一轮的完整状态。没有持久化，就没有长线叙事。

这一篇解决的就是这三个问题。第四、五篇解决的规则匹配细节（两阶段匹配、骰子判定）此处不再展开，聚焦运行时如何把整条链路串起来。

引擎拿到 contract 后进入一个循环：接收用户输入 → 匹配规则 → 执行动作 → 调用 LLM → 返回响应。这个循环构成了引擎的运行时。

但在实现这个循环之前，有几个工程问题必须先解决——它们决定了引擎是”能跑”还是”能用”。

二、小说级终端流：全角缩进与流式拦截

LLM 的流式输出是逐块返回的。引擎通过 onChunk 回调拦截每一块，然后直接写到终端。

这里有一个设计细节：全角缩进（　　）。

onChunk := func(chunk string) {
    for _, ch := range chunk {
        if ch == '\n' {
            fmt.Println()
            needIndent = true
            inParagraph = false
        } else {
            if !inParagraph && needIndent {
                fmt.Print("　　")  // 每个段落开头空两格
                needIndent = false
            }
            fmt.Print(string(ch))
            inParagraph = true
        }
    }
}

效果：终端输出的文本，每个自然段开头都有两个全角空格，看起来像一本实体书。这个细节对创作者的体验提升是巨大的——它把”终端输出”变成了”小说页面”。

但流式输出背后有一个更关键的工程决策：动作执行器统一处理流式回调。

• 状态修改动作：立即返回结果，然后通过回调模拟逐字符输出
• LLM 动作：真正的流式输出，逐块回调
• 静态文本：立即返回，然后模拟流式输出

所有动作最终都通过 onChunk 输出，不管来源是什么。这保证了终端的输出体验是一致的。

三、五层三明治 Prompt：把约束焊死在上下两端

LLM 叙事最大的问题是格式跑偏——它经常输出括号剧本流：

（冷笑一声）【贝利亚】：你们太弱了。

这破坏了沉浸感。解决方案是把格式约束放在 Prompt 的顶部和底部，形成三明治结构。v1.1.0 的实际 Prompt 渲染（internal/core/llm/prompt.go 的 RenderPrompt）是五层结构：

【格式硬性要求】
（NarrativeConstraints——禁止括号、禁止剧本标记、禁止独角戏）

【世界观】
（context）

【角色名】
你是 {角色名}，一个 {锚点风格} 的存在。你的背景：{角色背景}

【当前状态】
（从运行时 `map[string]any` 渲染而来）

【命运的推动】
（对话历史——命运与角色的交替记录）

【你记得的过往】
（运行时动态累积的记忆）

【此刻】
（user_input）

【要求】
（NarrativeConstraints，再次强调）

约束在两端出现两次，中间夹着上下文。这样做有两个原因：

1. 首因效应：LLM 最先看到约束，优先级最高
2. 近因效应：LLM 最后看到的约束会影响最终输出

两次强调，确保格式约束不会被中间的上下文稀释。

3.1 确定性渲染：排序保证 Cache 命中

这里有一个微妙的工程问题：Go 的 map 遍历顺序是随机的。

在引擎运行时，契约中的 【状态】 会被转换为 map[string]any 以便快速读写。当 Prompt 渲染 【当前状态】 时，如果每次遍历顺序不同，生成的 Prompt 文本就会变化——哪怕状态内容完全一样。这会导致 LLM 的 KV Cache 完全失效，每次都要重新计算。

解决方案：对 state 的键做排序（sort.Strings），确保渲染顺序稳定。这样在状态不变时，生成的 Prompt 文本字节级一致，LLM 服务的 KV Cache 能够命中，降低延迟和 Token 消耗。

3.2 反独角戏约束

NarrativeConstraints 中有一条被刻意强调：

每段回复必须包含至少一名其他角色（非玩家）的对话和动作反应。如果场景中没有其他角色，请引入或创造至少一个互动对象。禁止只有玩家独角戏。

这是为了解决叙事中的”空旷感”。如果 LLM 只回应玩家输入，不引入其他角色互动，故事会变成单人独白，失去戏剧张力。这条约束强制 LLM 在每轮回复中至少引入一个互动对象，让世界活起来。

四、Mother-Child 存档机制

每一轮对话结束后，引擎会自动保存当前状态到子版文件。

命名规则（v1.1.0 起与 Flutter 版对齐，点分隔）：

• 母版 story.meph → 默认子版 story.child.meph
• 分支 --branch dark → story.dark.meph

func BuildChildPath(filename string, branch string) string {
    dir := filepath.Dir(filename)
    base := filepath.Base(filename)
    ext := filepath.Ext(base)
    name := strings.TrimSuffix(base, ext)

    // 已是子版：直接覆盖（避免嵌套生成）
    if isChildFileName(name) {
        return filename
    }

    if branch != "" {
        return filepath.Join(dir, name+"."+branch+ext)
    }
    return filepath.Join(dir, name+childSuffix+ext) // childSuffix = ".child"
}

isChildFileName 精准识别已存在的子版：xxx.child（默认子版）或 xxx.分支名（分支名以字母开头）。这样 my_story_1.meph（数字序号）不会被误判为子版。

子版文件是完整的 .meph 契约，包含：

• 母版的所有静态区块（角色名、世界观、角色背景、开局场景、锚点、规则）
• 更新后的 【状态】
• 累积的 【记忆】
• 最近的 【历史】

这意味着一份静态契约可以演化出无数个动态子版：

story.meph (母版，只读)
    ├── story.child.meph (主线存档)
    ├── story.dark.meph (黑暗分支)
    ├── story.light.meph (光明分支)
    └── story.experimental.meph (实验分支)

每个分支独立演化，互不影响。项目自带的 data/dantes.meph 就伴随一个已运行的 data/dantes.child.meph 存档。

保存时机：不是每轮都写磁盘的低效模式，而是分两层：

1. 每轮对话后：Session 层（cmd/mephisto/session.go）调用 engine.Save()，实时持久化进度
2. 退出时：defer 再保存一次，确保退出前状态落盘

保存时的规则保鲜：Save() 有一个精妙设计——保存前先读取磁盘上的子版文件（若存在），以磁盘上的 【规则】 区块为最新规则。这样用户在编辑器中对规则区块的实时修改不会被自动保存覆盖。这同时支撑了 v1.0.3 引入的规则热重载：session.go 通过 fsnotify 监听子版文件变更，500ms 防抖后调用 ReloadContract 重新解析，只替换规则、保留状态和历史，让”编辑规则 → 保存 → 立即生效”成为可能。

加载时：

• 默认加载子版（如果存在）
• --reset 忽略子版，从母版重新开始
• --branch dark 加载对应的分支文件

注意：直接运行子版文件会覆盖原文件——引擎会将任何 .meph 文件视为母版，并生成对应的子版。如果不想丢失进度，请避免对子版文件直接运行 run 命令。

这个设计的价值：创作者可以在关键时刻分叉故事线，探索不同走向，而不丢失任何进度。

五、记忆提取：流式输出后的同步编织

记忆提取是长线叙事的关键——它把关键事件从对话历史中提取出来，压缩后长期保存，在每一轮中注入 LLM 上下文。

但提取需要调用 LLM，会耗时数秒。如果放在流式输出之前执行，用户每 5 轮就要等几秒才能看到第一个字。

解决方案很简单：先输出，后提取。

每一轮对话的流程是这样的：

用户输入
    │
    ▼
规则匹配 + 动作执行 + LLM 流式输出（用户看到文字逐字出现）
    │
    ▼
流式输出完成，用户读完回复
    │
    ▼
引擎 Run 同步执行记忆提取（此时代码在 Run 内部，用户已读完响应）
    │
    ▼
返回给 Session，Session 调用 Save 自动保存子版
    │
    ▼
显示输入提示，等待下一轮

注意和旧版本的区别：记忆提取在 engine.Run() 内部同步执行，子版保存由 Session 层在每轮 Run 返回后调用。两者解耦——引擎负责叙事与记忆，Session 负责持久化。

// internal/core/engine/engine.go

func (e *Engine) Run(input string, onChunk func(string)) (string, error) {
    // ... 规则匹配、LLM 调用、流式输出 ...

    // 4. 记录角色响应
    runtime.AddHistory("assistant", response)

    // 5. 记忆提取（每 N 轮，同步调用）
    e.processMemories()   // ← 用户此时已读完响应

    return response, nil
}

processMemories() 内部流程：

1. 提取间隔判断：ShouldExtract——轮数 % 5 == 0 时触发（ExtractInterval = 5）
2. 调用 LLM 提取：取最近 10 轮对话（ExtractWindow = 10），生成关键事件摘要（每条不超过 20 字）
3. 语义去重：shared.DeduplicateMemories 基于关键词 Jaccard 相似度去重，语义相近但表述不同的记忆自动合并。例如”浮士德在书斋中遇到了梅菲斯特”与”梅菲斯特在深夜来访浮士德的书斋”——两条记忆共享浮士德、梅菲斯特、书斋等多个关键词，被判定为描述同一事件而合并成一条
4. 追加 + 压缩：超过上限（MaxLimit = 30）时自动压缩，保留最近 5 条 + 3-5 条摘要

为什么这样设计？

1. 用户无感知：流式输出已经完成，用户正在阅读或思考回复内容。记忆提取在后台悄悄进行，用户不需要”等待”。
2. 逻辑简单：同步调用比异步 goroutine 更容易控制——没有竞态条件，没有”保存时记忆还没写完”的问题。

提取失败只会静默记录一条日志（提取函数返回错误则直接跳过），对话可以继续——只是本轮的记忆没有被保存。

六、完整闭环

把所有部分串起来，引擎的每一轮对话是这样运转的：

用户输入
    │
    ▼
规则匹配
    │   ├── 被动规则（状态修改 + 注入记忆）批量执行，多条同时触发
    │   └── 主动规则（LLM 指令 / 静态文本）互斥匹配，只取第一条
    │
    ▼
执行动作 → LLM 调用（60 秒超时保护，失败时 ⚠️ 降级为静态响应）
    │                        ↑——超时只保护 LLM 调用阶段
    ▼
流式输出（全角缩进 + 逐块回调）
    │
    ▼
记录 assistant 历史 → （同步）记忆提取（每 5 轮触发一次，无流式等待）
    │
    ▼
Session 层调用 Save → 自动保存到子版文件（story.child.meph）
    │
    ▼
规则热重载监听（后台异步 fsnotify，不阻塞主循环）
    │
    ▼
等待下一轮输入

几个运行时的健壮性细节值得说明：

• LLM 超时降级：整个 LLM 调用包裹在 60 秒超时上下文（context.WithTimeout）中。超时或失败时，引擎通过 onChunk 输出 （⚠️ LLM 调用失败：请求超时，已降级为静态响应），再返回默认静态文本。告诉用户”LLM 挂了”比让用户猜”角色沉默了”更好——前者是可诊断的工程问题，后者可能被误解为叙事设计。
• 调试与静默：调试信息（--debug）写入 os.Stderr，普通输出（--quiet）不干扰调试信息。两者可同时启用。

这就是 Mephisto 的运行时。

七、代价与局限

这套机制不是没有代价的：

1. 记忆提取依赖 LLM 质量

如果主模型状态不佳，提取的摘要可能跑偏——甚至篡改关键事实（如将”击败”误写为”放逐”）。这是一种”幻觉”风险。

当前应对策略有两个层面：

• 提示词保护：提取和压缩的提示词中明令禁止修改角色的核心设定（角色名、锚点内容、状态值等），在 DeepSeek 和 GPT-4 上效果可靠。
• 模型选择建议：对于 7B 本地模型，摘要质量下降明显。如果必须使用轻量模型，建议关闭自动记忆提取（设置 ExtractInterval = 0），改为手动管理记忆。

未来可以进一步加强：实现记忆后验验证——提取结果返回后，由引擎检查是否与核心设定冲突，发现有矛盾直接丢弃该条记忆。

2. 分支切换需要手动管理

子版文件是独立存储的，切换分支需要用户主动指定 --branch。不像真正的版本控制有 diff 和 merge，分支之间的内容不会自动同步。

3. 流式输出占用终端

全角缩进和流式输出在终端看起来很好，但如果用户想复制粘贴文本，缩进和换行符会一起被复制——有时会产生干扰。

八、小结

六篇走完了一条完整的路径：

合在一起，就是一个完整的长线叙事引擎：

契约（.meph）
    │
    ▼
解析器（第三、四篇）──→ Contract
    │
    ▼
引擎（第六篇）──→ 规则匹配 + LLM 流式叙事 + 记忆提取
    │
    ▼
子版存档（story.child.meph）──→ 长期连续性 + 多分支

速查卡：完整流程

.meph 契约文件
    │
    ▼ 扫描器（行号绑定）
    │
    ▼ 区块列表 []Block
    │
    ▼ Parser（按区块标题路由）
    │
    ▼ domain.Contract
    │   ├─ RoleName
    │   ├─ Anchor
    │   ├─ State
    │   ├─ Worldview
    │   └─ Rules（条件原样存储，运行时求值）
    │
    ▼ 引擎
    │   ├─ 五层三明治 Prompt（顶部约束 → 上下文 → 角色 → 状态/历史/记忆 → 底部约束）
    │   ├─ 规则匹配（被动批量 + 主动互斥）
    │   ├─ 动作执行（注入 / 状态修改 / LLM 调用 / 静态文本）
    │   ├─ 流式输出（全角缩进）
    │   ├─ 记忆提取（每 5 轮，同步调用，语义去重）
    │   ├─ LLM 超时降级（60 秒，⚠️ 提示 + 静态响应）
    │   └─ 子版存档（story.child.meph，点分隔命名）
    │
    ▼ 引擎循环
        用户输入 → 规则匹配 → 执行动作 → LLM 流式叙事
        → 记忆提取 → Session 自动保存 → 热重载监听 → 等待下一轮

如果你想快速定位某篇的具体内容，对照上面的流程节点查找：

项目地址：https://github.com/yuelinghuashu/mephisto

前置阅读：建议先读第三篇的“四、Parser”和第四篇的“四、小结”，理解解析器输出 domain.Contract 的完整流程。本篇假设你已经知道解析器能把 .meph 变成结构体。

一、叙事引擎的第四个问题：怎么保证行为稳定？

解析器写完了。但它是一个长期维护的代码——需求会变、格式会扩、bug 会修。每次改动都可能破坏已有的行为。

这里的关键矛盾是：创作者依赖的是稳定的行为，开发者依赖的是自由的修改权。如果改一行代码就要手动测试所有已知场景，开发者会畏惧重构；如果不测试，改坏了创作者会直接发现——但创作者不会关心”你重构了解析器”。

解决方案是把解析行为”冻结”下来：用一组固定的契约作为看门狗，每次变更后自动对比解析结果是否与预期一致。

这就是集成测试的作用：把一组固定的 .meph 契约作为”看门狗”，每次代码变更后跑一遍，确保行为没有被意外改变。

二、Golden File 测试：把解析结果固化下来

最直接的测试方式：准备一个标准契约文件，解析它，然后把解析结果序列化为 JSON 保存起来。以后每次跑测试，都把当前的解析结果和这个 JSON 文件做对比。

项目里的 testdata/sample.meph 就是这份标准契约。测试流程如下：

func TestParseSample(t *testing.T) {
    got, err := ParseFile("testdata/sample.meph")
    if err != nil {
        t.Fatalf("解析失败: %v", err)
    }

    goldenPath := "testdata/sample.golden"
    var want domain.Contract

    if err := loadGolden(goldenPath, &want); err != nil {
        // Golden 文件不存在，自动生成
        saveGolden(goldenPath, got)
        t.Log("Golden 文件已生成，请检查后重新运行测试")
        t.FailNow()
    }

    // 对比 got 和 want
    if diff := cmp.Diff(want, got); diff != "" {
        t.Errorf("解析结果与预期不符:\n%s", diff)
        t.Log("💡 如果更改是预期的，请运行: go test -update")
    }
}

首次运行会自动生成 sample.golden。之后每次运行都会对比，发现差异就报错。如果改动是预期的（比如新增了一个字段），运行 go test -update 即可刷新 Golden 文件。

这个机制的核心价值是： 让解析器的行为被“冻结”下来。任何改动都必须经过测试验证，不能偷偷改变解析结果。

三、解析即验证

解析不只是“把文本读进来”——它会在解析过程中直接验证必填项。

如果角色名为空，parseRoleName 直接报错：

第 X 行：角色名不能为空

如果规则名/条件/动作为空，parseRuleLine 直接报错并携带行号。

解析不通过，结构体就不存在。 不存在“解析成功但内容无效”的状态——这是手写解析器相比 JSON/YAML 的另一个优势。JSON 解析器不管语义完整性，它只管结构正确。

四、滑窗老化测试：历史记录的正确截断

引擎有一个关键行为：历史记录不能无限增长。它需要自动截断，只保留最近 N 轮对话。

测试用例验证这个行为：

func TestIntegrationHistoryLimit(t *testing.T) {
    contract, err := parser.ParseFile("../parser/testdata/sample.meph")
    if err != nil {
        t.Fatalf("解析失败: %v", err)
    }
    // 设置最大历史保留 2 轮
    eng := engine.New(contract, engine.WithMaxHistory(2))

    // 执行 5 轮对话
    for range 5 {
        eng.Run("你好", nil)
    }

    history := eng.History()
    // 5 轮对话产生 10 条记录，但容量只有 4 条（2 轮 * 2 条/轮）
    if len(history) != 4 {
        t.Errorf("历史记录长度 = %d, want 4", len(history))
    }
}

这个测试确保历史截断是“整轮丢弃”而不是“逐条丢弃”。如果逐条丢弃，可能出现“只剩下命运的输入、没有角色的响应”这种半轮数据，会导致 Prompt 中 【命运的推动】 区块出现不完整的上下文。

整轮截断的策略保证了历史的完整性——要么保留一整轮（fate + assistant），要么全丢。

五、错误场景测试：确保报错信息精确

除了“正常路径”，集成测试还覆盖“错误路径”——确保各类格式错误能正确报错，并且报错信息包含行号和区块名：

func TestParseErrors(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        wantErr string // 错误信息应包含的子串
    }{
        {
            name:    "区块外有内容",
            input:   "这是区块外的内容\n【角色名】\n贝利亚",
            wantErr: "内容出现在任何区块之外",
        },
        {
            name:    "列表项缺少 - 前缀",
            input:   "【锚点】\n核心信念：力量",
            wantErr: "列表项必须以 '-' 开头",
        },
        {
            name:    "列表项缺少冒号",
            input:   "【锚点】\n- 核心信念 \"力量\"",
            wantErr: "缺少 ':' 或 '：'",
        },
        // ...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := ParseString(tt.input)
            if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
                t.Errorf("期望错误包含 '%s'，实际: %v", tt.wantErr, err)
            }
        })
    }
}

这些测试确保报错信息不会退化为“unexpected token at position 42”——那是我们在第一篇就决定要消灭的东西。

六、代价

• 维护 Golden 文件需要手动确认（首次生成或更新时要检查内容是否正确）
• 错误场景测试需要覆盖尽可能多的边界情况
• 每次新增区块类型，需要同步更新测试用例

但收益是：重构时可以放心改代码，只要测试全绿，行为就没变。

七、小结

集成测试是工程的“看门狗”。它把解析器的行为冻结下来，任何改动都必须经过验证。

四件事构成了这套测试体系：

1. Golden File 测试：固化标准契约的解析结果
2. 解析即验证：解析过程中直接检查必填项和完整性
3. 滑窗老化测试：确保历史记录按整轮截断
4. 错误场景测试：确保报错信息精确到行号

有了这套体系，后续的引擎开发可以放心迭代——不怕改坏东西，测试会告诉你。

下一篇，我们将进入引擎的运行时。要解决的核心问题是：拿到了 domain.Contract 之后，怎么驱动大模型生成符合规则的叙事？

答案是三明治 Prompt 结构——把格式约束放在上下两端，把上下文放在中间，彻底根除括号剧本流。

项目地址：https://github.com/yuelinghuashu/mephisto

前置阅读：建议先读第三篇的”二、两阶段设计”和”三、区块扫描器”，理解扫描器如何输出 []Block。本篇假设你已经知道 Parser 如何根据 Title 路由到不同解析函数。

一、叙事引擎的第三个问题：条件-动作怎么拆解？

区块切分完以后，最复杂的部分是规则表达式。一个叙事引擎需要回答：条件怎么写、动作怎么写、变量怎么引用。

这里有一条重要的设计边界：解析器只负责拆解，不负责求值。条件字符串（如 包含 "攻击" && 状态.堕落指数 > 80）原样存入结构体，引擎运行时再计算 true/false。为什么这样做？因为求值所需的运行状态在解析时还不存在——状态值是在对话过程中动态变化的，无法在加载阶段就确定。

这一篇要解决的就是拆解逻辑本身。

二、规则解析：拆解条件-动作

规则格式固定：[规则名] if 条件 -> 动作

[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[光之国] if 包含 "光之国" && 状态.情绪 == "暴怒" -> 注入 "光之国的记忆让贝利亚更加愤怒"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

插值语法出现在规则动作和文本区块中：

注入 "{角色名}的故乡是光之国"

这一篇要解决两个问题：

1. 规则的条件和动作怎么拆解成可存储的结构？
2. 插值语法怎么在解析层被识别和处理？

2.1 规则名提取

找到第一个 [ 和第一个 ]，取中间内容：

func parseRuleLine(line string, lineNumber int) (*domain.Rule, error) {
    trimmed := strings.TrimSpace(line)
    if !strings.HasPrefix(trimmed, "[") {
        return nil, fmt.Errorf("规则必须以 '[' 开头")
    }
    idx := strings.Index(trimmed, "]")
    if idx == -1 {
        return nil, fmt.Errorf("缺少闭合的 ']'")
    }
    name := strings.TrimSpace(trimmed[1:idx])
    if name == "" {
        return nil, fmt.Errorf("规则名不能为空")
    }

    rest := strings.TrimSpace(trimmed[idx+1:])
    // 接下来提取条件和动作...
}

2.2 条件与动作的拆分

用 if 和 -> 作为分隔符：

// 去掉 "if " 前缀
if !strings.HasPrefix(rest, "if ") {
    return nil, fmt.Errorf("规则条件必须以 'if ' 开头")
}
rest = strings.TrimPrefix(rest, "if")
rest = strings.TrimSpace(rest)

// 取第一个 "->" 分割条件和动作
cond, action, ok := strings.Cut(rest, "->")
if !ok {
    return nil, fmt.Errorf("规则缺少 '->'")
}
cond = strings.TrimSpace(cond)
action = strings.TrimSpace(action)

2.3 互斥组

动作中可能带有 [group:xxx] 标记：

[攻击] if 包含 "攻击" -> [group:combat] 注入 "贝利亚发动了猛烈的攻击"

解析时提取组名，存入 domain.Rule.Group：

group := ""
if strings.HasPrefix(action, "[group:") {
    endIdx := strings.Index(action, "]")
    if endIdx != -1 {
        group = action[7:endIdx]
        action = strings.TrimSpace(action[endIdx+1:])
    }
}

互斥组的作用是：同一组内多条规则，只有第一条匹配的会被触发。这个逻辑在引擎运行时生效，解析层只需存好组名。

互斥组可以搭配任何动作类型，不仅限于 注入：

[高堕落] if 状态.堕落指数 > 80 -> [group:escalate] 状态.情绪 = "癫狂"
[失控] if 状态.情绪 == "癫狂" && 状态.堕落指数 > 90 -> [group:escalate] 注入 "{角色名}已完全失控"

2.4 引号处理

条件和动作中的字符串用 " 包裹。解析时我调用 unquote 剥离外层引号：

func unquote(s string) (string, error) {
    s = strings.TrimSpace(s)
    if len(s) >= 2 {
        if (strings.HasPrefix(s, "\"") && strings.HasSuffix(s, "\"")) ||
           (strings.HasPrefix(s, "“") && strings.HasSuffix(s, "”")) {
            return s[1:len(s)-1], nil
        }
    }
    return s, nil
}

支持中文引号是因为创作者可能使用中文输入法，“ 和 ” 比 " 更容易自然输入。

三、插值语法：{变量名} 的识别与替换

插值的核心需求：在任意文本中识别 {角色名} 并替换为对应的角色名称。 当前支持的插值变量只有一个——{角色名}，它来自 【角色名】 区块，静态不变。

3.1 为什么只有 {角色名}？

你可能好奇：为什么状态变量（如堕落指数、情绪）不能直接用 {堕落指数} 插值？

因为状态变量在引擎中是运行时动态读写的——创作者通过 状态.键 = 值 来修改，通过 状态.键 > 值 来比较。如果允许 {堕落指数} 插值，就引入了一套平行机制：既可以在规则中通过 状态.堕落指数 引用它，又可以通过 {堕落指数} 引用它。两套语法做同一件事，徒增学习成本。

所以状态变量的引用统一使用 状态.键 语法，不设插值。引擎运行时的模板替换也只做一件事：把 {角色名} 替换为实际的角色名称。

3.2 替换时机：三个场景

插值替换在引擎中发生在三个不同场景：

1. CLI 欢迎界面显示时：世界观、开局场景在显示给人类看时替换一次。创作者看到的是”贝利亚奥特曼”而非 {角色名}。

2. 规则动作执行时：注入 "{角色名}的故乡是光之国" 在每次规则触发时执行替换。这是插值最核心的使用场景。

3. Prompt 构建中：世界观和背景文本原样传给 LLM，不依赖引擎主动替换。LLM 从上下文中（”你是贝利亚奥特曼”）自然理解 {角色名} 的含义。

为什么第三种场景不主动替换？

因为替换会改变文本的原始形态。如果将 {角色名}的故乡是光之国 替换为 贝利亚奥特曼的故乡是光之国，LLM 收到的是一段已经”固化”的叙述。而保持 {角色名} 原样，让 LLM 在生成时根据上下文动态决定如何使用这个名字——在某些叙事分支中，角色名可能发生变化（如角色改名、被遗忘等），这时保留占位符反而更灵活。

四、交汇点：当规则遇上插值

以这条规则为例：

[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国"

完整执行流程：

用户输入 "我要去光之国！"
    │
    ▼
规则匹配：包含 "光之国" → true
    │
    ▼
动作识别：提取动作类型为 "注入"
    │
    ▼
运行时替换：{角色名} → "贝利亚奥特曼"
    │
    ▼
追加记忆："贝利亚奥特曼的故乡是光之国" 写入记忆库
    │
    ▼
LLM 叙事：带着新记忆生成响应

为什么坚持把替换放在运行时？

因为引擎支持多分支故事线。如果加载时就替换成静态文本，所有分支共享同一个值，无法独立演化。运行时替换意味着每个分支读取自己的状态——状态变了，插值结果就变了。

骰子表达式的容错

骰子表达式（如 roll(1d100) >= 80）在解析时原样存储，运行时求值。如果表达式格式错误（如 roll(1d10 缺少括号），引擎不会报错，而是视为条件不满足（返回 false）。这是因为骰子表达式本身就是条件的一部分，解析层不负责验证运行时的正确性——格式错误就当作”不匹配”处理。

五、小结：解析层完整了

到这一篇为止，解析层覆盖了所有语法单元：

最关键的一条边界：

解析器只负责”读出来”——把文本转化为结构化的数据。
引擎负责”算出来”——条件求值、变量替换、动作执行。

下一篇，我们将跨过这条边界，进入引擎的运行时。而引擎面对的第一个工程问题是：如何保证代码改动不破坏现有的解析行为？

答案是集成测试——用一组固定的 .meph 契约作为”看门狗”，每次改动后对比解析结果是否与预期一致。

项目地址：https://github.com/yuelinghuashu/mephisto

前置阅读：如果你是从搜索引擎直接跳到这一篇，建议先读第一篇的“一、先看目标”和“六、.meph 的设计原则”，了解 .meph 的长相和设计初衷。本篇假设你已经知道 【角色名】 和 【规则】 是什么。

.json 解析器报 position 246，创作者需要的是“第 12 行缺冒号”。这一篇实现的就是这种精确报错。

一、叙事引擎的第二个问题：规则怎么变成结构？

格式定义好之后，下一个问题是解析——怎么把文本变成程序能操作的数据。

这里有两个关键指标：解析正确性和报错可读性。通用格式（JSON/YAML）在第一个指标上很好，但在第二个指标上几乎是灾难——position 246 对创作者毫无意义。而对于自定义格式，解析器必须从头实现。

一篇好的解析器设计，应该做到三件事：

1. 精确识别：每个区块、每行内容都能被正确归类
2. 行号绑定：每一条错误都能追溯到具体行，而不是字符串偏移量
3. 白名单校验：错误的写法（如 【脚色名】）不会被当作有效内容

这一篇实现的就是这三件事。

二、先看问题：如果没有行号绑定

在开始写解析器之前，先看一个真实的场景。

创作者写了一份契约，其中一行是：

【锚点】
- 核心信念 "力量就是一切"

注意，- 核心信念 "力量就是一切" 缺少了冒号（正确写法是 - 核心信念: "力量就是一切"）。

如果我用通用解析器，报错大概是：

unexpected token at position 42

创作者需要复制粘贴去数 position 42 是哪个字符。这个过程极其折磨。

而我的目标是让解析器报出这样的错误：

第 2 行（区块「锚点」）：缺少 ':' 或 '：'

不需要数 position，不需要理解“token”是什么，直接告诉创作者：“第二行缺了一个冒号。”

这个差异，就是手写解析器的全部理由。

三、两阶段设计

我把解析拆成两个阶段：

关键设计：行号在扫描阶段就绑定到每一行，Parser 直接使用，无需计算偏移量。这样报错时永远是精确的绝对行号。

数据结构就两个：

type Line struct {
    Text   string
    Number int  // 绝对行号，从 1 开始
}

type Block struct {
    Title   string  // 如 "角色名"
    Content []Line  // 内容行，自带行号
    Line    int     // 标题行号
}

有了这个结构，报错可以这样写：

fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
    line.Number, blockName)

四、区块扫描器：一个简单的状态机

核心是一个逐行扫描的状态机。它只有两个状态：

• inBlock == false：当前不在任何区块内
• inBlock == true：当前在区块内，正在收集内容

func Lex(text string) ([]Block, error) {
    lines := strings.Split(text, "\n")
    var blocks []Block
    var currentTitle string
    var currentContent []Line
    var currentLine int
    inBlock := false

    for i, rawLine := range lines {
        lineNumber := i + 1

        // 不在区块内时，空行跳过
        if !inBlock && strings.TrimSpace(rawLine) == "" {
            continue
        }

        // 检查是否为区块标题
        if title, ok := isBlockTitle(rawLine); ok {
            if inBlock {
                // 保存当前区块
                blocks = append(blocks, Block{
                    Title:   currentTitle,
                    Content: currentContent,
                    Line:    currentLine,
                })
            }
            // 开始新区块
            currentTitle = title
            currentContent = []Line{}
            currentLine = lineNumber
            inBlock = true
            continue
        }

        // 非标题行：必须在区块内
        if !inBlock {
            return nil, fmt.Errorf("第 %d 行：内容出现在任何区块之外", lineNumber)
        }

        currentContent = append(currentContent, Line{
            Text:   rawLine,
            Number: lineNumber,
        })
    }

    if inBlock {
        blocks = append(blocks, Block{...})
    }

    if len(blocks) == 0 {
        return nil, fmt.Errorf("没有有效区块")
    }
    return blocks, nil
}

两个关键设计：

1. 白名单前置

isBlockTitle 只认预定义的标题列表：

var knownBlocks = map[string]bool{
    "角色名": true,
    "锚点":  true,
    "规则":  true,
    "状态":  true,
    // ...
}

如果创作者写了 【脚色名】（错别字），扫描器不会把它当作区块开始——而是会得到一个指向该行的错误。具体报错信息取决于上下文：如果该行出现在任何区块之外，报错“内容出现在任何区块之外”；如果出现在某个区块内部，则会在该区块的解析中报错。无论哪种情况，行号都是精确的。

2. 行号绑定

每一行在存入时直接携带 lineNumber，永不偏移。这是实现精确报错的根基。

五、Parser：路由到不同解析函数

扫描器输出 []Block 后，Parser 根据 Title 路由到对应的解析函数：

func parseBlocks(blocks []Block) (*domain.Contract, error) {
    contract := &domain.Contract{}
    for _, block := range blocks {
        switch block.Title {
        case "角色名":
            contract.RoleName, err = parseRoleName(block.Content, block.Line)
        case "锚点":
            contract.Anchor, err = parseKeyValuePairs(block.Content, block.Title)
        case "规则":
            contract.Rules, err = parseRules(block.Content, block.Title)
        // ... 其他区块
        }
        if err != nil {
            return nil, err
        }
    }
    return contract, nil
}

每种区块的解析逻辑是独立的。以键值对列表为例——所有错误都带行号和区块名：

func parseKeyValuePairs(lines []Line, blockName string) ([]KeyValue, error) {
    for _, line := range lines {
        trimmed := strings.TrimSpace(line.Text)
        if trimmed == "" || strings.HasPrefix(trimmed, "#") {
            continue
        }
        if !strings.HasPrefix(trimmed, "-") {
            return nil, fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
                line.Number, blockName)
        }
        // ... 提取键值对
    }
    return result, nil
}

六、错误信息对比

同一个错误，两种体验：

七、代价

• 写了约 400 行 Go 代码
• 需要为每个区块类型写独立的解析逻辑
• 新增区块要同步更新白名单

但没有外部依赖，go build 一步完成。解析逻辑完全可控，可以随时调整。

八、小结

区块扫描器和 Parser 完成了“文本到结构”的转化。现在 【角色名】 变成了 contract.RoleName，【规则】 变成了 contract.Rules。

但 contract.Rules 里的条件（如 包含 "攻击"）和动作（如 注入 "{角色名}的故乡是光之国"）仍然是字符串。下一篇我们要处理的是：规则的条件-动作表达式怎么拆解？插值语法 {变量} 怎么处理？

这是解析层最后两块拼图。

项目地址：https://github.com/yuelinghuashu/mephisto

前置阅读：建议先读完第一篇《自由叙事到契约约束》，了解 .meph 格式的设计动机。这篇不需要任何前置技术知识——只要你有终端和 Go 1.26+。

前一篇我们讨论了为什么 .meph 比 JSON 和 YAML 更适合做叙事契约。但光说不练没有用。

这篇我们放下理论，从零开始写一份真实的契约文件，编译它，运行它。整个过程不超过 20 分钟——你可以亲自看到自己写的规则如何驱动 LLM 生成叙事。

一、准备工作

你需要三样东西：

1. Go 1.26+：打开终端，运行 go version 确认版本
2. 一个终端：任何操作系统都可以
3. （可选）一个 LLM API Key：DeepSeek、OpenAI 或 Ollama 均可——如果没有也不影响，引擎在没有 LLM 时也能工作

如果你有 API Key，在项目根目录创建一个 .env 文件：

MEPHISTO_CLIENT=openai
MEPHISTO_MODEL=deepseek-v4-flash
OPENAI_API_KEY=sk-你的密钥

二、克隆并构建

git clone https://github.com/yuelinghuashu/mephisto.git
cd mephisto
go build -o ./mephisto ./cmd/mephisto

如果一切顺利，你会看到一个名为 mephisto 的可执行文件。

三、从零开始写契约

接下来才是关键。我们创建一个新文件 data/faust.meph，从头开始填充内容。

3.1 角色名

契约的第一行是角色名。用 【角色名】 标记区块，下面直接写名字：

【角色名】
浮士德

就这么简单——不需要引号，不需要冒号，不需要任何标记。

3.2 锚点

【锚点】 是角色的核心人格设定，用 - 键: 值 的格式列出：

【锚点】
- 核心信念：知识高于一切，我愿意为真理付出任何代价
- 欲望：体验一切人类能体验的事物
- 绝对禁忌：不会承认自己后悔

这些内容会被直接注入 LLM 的上下文，成为角色行为的基石。

3.3 状态

【状态】 是角色的动态变量，同样用键值对格式：

【状态】
- 灵魂完整度：100
- 情绪：永不满足
- 位置：书斋

状态值支持数字、布尔值、字符串三种类型。引擎在解析时自动推断类型——"100" 被解析为数字 100，"永不满足" 保持为字符串。这意味着你可以在规则中用 状态.灵魂完整度 > 50 直接比较数字，无需额外类型转换。

在运行时，状态被存储为 map[string]any，以便快速读写。初始顺序从契约中继承，但运行时只按键名访问，不依赖顺序。

3.4 世界观

【世界观】 是多行文本，直接写即可，保留换行：

【世界观】
故事发生在 16 世纪的德意志，这是一个神学与科学交织的时代。
大学中充斥着经院哲学的空洞争论，真正的新知被压制。
世界由上帝、天使、魔鬼与凡人共同构成，地狱与天堂是真实存在的维度。
梅菲斯特是地狱的使者，擅长以言语和契约诱捕人类灵魂。
灵魂交易在此世界是真实的契约——任何灵魂契约一旦签订，绝无撤回的可能。

3.5 角色背景

【角色背景】 与 【世界观】 一起定义了角色的详细背景。

【角色背景】
浮士德是一位学识渊博的学者，精通哲学、医学、法学和神学。
但他对人类知识的极限感到绝望——穷尽一生所学，仍无法触及世界的本质。
绝望中，他与梅菲斯特签订了契约：用灵魂换取在世上的无限体验。

3.6 开局场景

【开局场景】 定义了对话开始时的情境：

【开局场景】
深夜。书斋中烛火摇曳，桌上的书籍堆积成山。
浮士德站在窗边，望着窗外的月光。
桌角放着一份契约书，墨迹还未干透。

3.7 规则——让角色活起来的关键

【规则】 是引擎的核心。每条规则由三部分组成：[规则名] if 条件 -> 动作。

【规则】
[新体验] if 包含 "追求" || 包含 "想要" || 包含 "体验" -> 注入 "{角色名}感到心中燃起新的渴望，没有什么能阻止他去亲自体验这一切"
[梅菲斯特] if 包含 "梅菲斯特" || 包含 "契约" -> 注入 "梅菲斯特的声音在{角色名}耳边低语：'这就是你想要的吗？代价你可想好了。'"
[灵魂代价] if 包含 "代价" || 包含 "灵魂" -> 注入 "{角色名}低头看着自己的双手，仿佛能看见什么东西正在一丝丝流逝"
[永不满足] if 不包含 "放弃" && 不包含 "满足" -> 注入 "{角色名}的眼中闪烁着永不熄灭的火焰，他还想要更多"

规则的条件支持逻辑运算符（&&、||）、状态比较（状态.键 > 值）、以及骰子表达式（roll(1d100)）。动作最常用的是 注入——将消息追加到记忆，由 LLM 自然融入后续叙事。

3.8 验证

保存文件后，先验证解析是否正确：

./mephisto parse data/faust.meph

你会看到类似这样的 JSON 输出：

{
  "role_name": "浮士德",
  "anchor": [...],
  "state": [...],
  "rules": [...]
}

如果解析失败，错误信息会精确告诉你哪一行出了问题——比如”第 X 行（区块「锚点」）：缺少 ‘:’ 或 ‘：’“。

四、第一次对话（无 LLM 模式）

即使没有配置 LLM，引擎也能运行：

./mephisto run data/faust.meph

你会看到欢迎信息，然后进入对话模式。输入 “我想要体验爱情”：

命运 > 我想要体验爱情
浮士德 沉默地注视着命运。

因为没有 LLM，引擎返回了默认响应。但规则其实已经匹配了——输入了”我想要”，条件 包含 "想要" 为 true，规则 [新体验] 触发，注入被写入记忆。

输入 /state 查看当前状态：

当前状态：
  灵魂完整度: 100
  情绪: 永不满足
  位置: 书斋

输入 /history 查看对话历史——你输入的”我想要体验爱情”已经记录为命运指引。

这就是引擎在无 LLM 下的工作方式：规则匹配、注入、状态管理——全部正常运转。LLM 只是最后的”叙事输出层”。

五、打开 LLM 世界

现在加上 API Key，重新运行：

./mephisto run data/faust.meph -debug

你会看到同样的欢迎信息，但这次带上了 -debug 参数。LLM 的配置信息会先显示出来。

然后在提示符后输入：

命运 > 你想要获取超越人类认知的知识

终端中出现了调试输出，然后是——梅菲斯特从阴影中走了出来：

🔍 规则调试模式
----------------------------------------
📌 检查规则 [新体验] (行 26)
   条件: 包含 "追求" || 包含 "想要" || 包含 "体验"
   结果: true
   ✅ 触发 → 注入 "{角色名}感到心中燃起新的渴望，没有...

　　书斋里的烛火摇曳，将满墙的羊皮卷和典籍映照出深浅不一的阴影。浮士德枯坐在堆满手稿的书桌前，指尖摩挲着一本破旧星象书的封面，目光却穿过窗棂，望向一片漆黑的夜空。他低声自语，声音沙哑得几乎被风吹散："追寻了一生，终究连一扇门也未曾推开。"

　　这时，身后的书架间传来一声极轻的响动，像老鼠啃咬木屑，又像一声压抑的嗤笑。浮士德并未回头，只是冷冷问道："又是你吗，瓦格纳？夜已经深了，不必再来送热汤。"

　　脚步声却很轻，轻得不像那个笨拙的弟子。一个低沉的、带着金属质感的声音从暗处响起："瓦格纳只配为你添柴烧水，我带来的，是另一种暖意。"说话者从阴影中缓步走出——他穿着华丽的猩红长袍，面容清瘦，嘴角挂着似笑非笑的弧度，手中把玩着一枚古铜色的戒指。他站定在书桌前，微微倾身，目光直刺浮士德的双瞳："你方才说，穷尽一生也推不开那扇门。可你有没有想过，门根本不是用来推的？"

　　浮士德缓缓抬起头，盯住这位不速之客。他的手指按住那本星象书，沉声道："你是何人？未经允准，擅入我的书斋。"

　　那人轻轻一笑，将戒指在烛光下转了转，戒指竟投出一片扭曲的影子，仿佛是某种无法言说的符文。"我是你所有问题的答案，也是你所有渴望的代价。"他伸出一只手，掌心向上，五指张开，掌纹中隐约流转着暗红色的光，"我可以让你看见星辰背后的纹路，可以让你听见创世之初的旋律，可以让你触碰法则本身。只要你允许我带走一件微不足道的东西。"

　　浮士德站起身，衣袖拂过桌面上散落的草稿纸，那些写满公式和推演的纸张飘落一地。他盯着那只递来的手，沉默了许久，才开口道："你要什么？"

　　那人弯起嘴角，声音轻柔得像羽毛划过刀锋："你的灵魂。不过请放心，那东西你平日里也用不上——它既不能帮你解开方程，也不能让你飞上苍穹。你留着它，不过是让日渐腐朽的肉体多一块赘肉罢了。"他收回手，转而从怀中取出一卷漆黑的羊皮纸，摊开在桌面上。纸面上没有字迹，只有一片深不见底的暗色，仿佛能吞噬周围的光线。"签下它，我便立即兑现一切。"

　　浮士德的呼吸变得急促，他低头看着那片漆黑，又抬头看向那人的眼睛——那双眼睛里倒映着无数星辰的陨落与诞生。他终于伸出手，指尖触到羊皮纸的瞬间，一股凉意顺着指骨爬上肩头。他没有再犹豫，接过那人递来的羽毛笔，笔尖刺破了自己的拇指，带着血珠落向纸面。

　　就在此时，书斋的门被推开一道缝，瓦格纳捧着一盏昏黄的油灯探进头来。他看到房中多了一个陌生人，又看到老师指尖渗血的姿态，面色顿时发白，颤抖着喊道："老师！您在做什么？此人是何时进来的？"

　　浮士德没有停下动作，血字已在羊皮纸上成型。他头也不回地说："瓦格纳，关上门，今夜你将见证一位学者的夙愿。"话音未落，羊皮纸上的暗色开始涌动，如同一片无星之夜在室内铺展开来，而那位红衣人的笑声，在书卷间回荡不绝。

这就是你写的 30 行契约生成的叙事。

试试改一个数字。

把 【状态】 中的灵魂完整度从 100 改为 50，保存文件，重新运行，输入同样的话：

命运 > 你想要获取超越人类认知的知识

同样的规则，同样的输入，只差一个数字，结果却截然不同：

　　书斋的烛火在深夜中摇曳不定，投下巨大的阴影，仿佛活物般在书架上爬行。浮士德瘫坐在堆满古籍的书桌后，指间夹着一根鹅毛笔，墨水早已干涸在笔尖。他的目光空洞地扫过那些拉丁文、希腊文与希伯来文的卷轴——这些曾经让他心醉神迷的符号，如今像一堆干枯的昆虫尸体般毫无意义。

　　“四十年。”他的声音沙哑得几乎听不清，“四十年钻研，我连第一重天的边缘都未曾触碰。”

　　窗外传来低沉的夜鸟鸣叫，像是某个东西在回应他的绝望。就在这时，书房的门无声无息地打开了，走进来的是他的老仆人瓦格纳，手里端着一碗热气腾腾的草药汤。瓦格纳小心翼翼地绕过地上堆叠的羊皮纸，将汤碗放在桌角，颇有些忧虑地开了口：“老爷，您已经三天没有进食了。帕拉塞尔苏斯的笔记您看了一整夜，眼睛血丝密布，再这样熬下去，怕是……”

　　“怕是什么？怕我这副躯体先于我的渴望腐烂？”浮士德猛地抬起头，眼中闪烁着某种近乎疯狂的光芒，“瓦格纳，你钻研学问多年，告诉我，你可曾见过真理的模样？”

　　瓦格纳被他盯得后退一步，低声答道：“老爷，仆以为，真理是上帝的事。”

　　“上帝的事。”浮士德重复着这几个字，忽然大笑起来，笑声中满是苦涩，“正是如此，正是如此。我们把一切都推给上帝，用神学的栏杆把自己圈在安全的猪圈里，啃食着神父们丢下来的干面包，还感激涕零！”他站起身，带倒了身后的椅子，烛火被他袍角带起的风压得几乎熄灭。“我受够了这些文字、这些符号、这些由人写出来骗人的东西。我需要真正的知识——那古老者、原初者才配拥有的知识。”

　　瓦格纳惊恐地看着他，双手微微发抖：“老爷，您在说什么？这样的念头是亵渎……”

　　“亵渎？”浮士德走到窗前，一把推开窗户，深夜的寒风呼啸着灌进来，吹得他灰色的长发和长袍疯狂翻卷，“若求真知即是亵渎，那就让这场亵渎来得更彻底些。”他回身，目光如燃烧的煤炭般炽热，“瓦格纳，你走吧。今夜我要独自一人。”

　　瓦格纳张了张嘴，最终还是低下头，飞快地退了出去，木门在他身后重重合上。浮士德独自站在打开的窗前，仰望头顶那片缀满星斗却沉默不语的夜空，喃喃道：“你们站在那里已有亿万年，难道就没有一句想对我这个区区凡人说的话吗？”

　　话音未落，书桌上的烛火猛地窜高，化作一片幽蓝色的火焰。火焰中央，一个声音低沉而优雅地响了起来——不是从空气中传来，而是仿佛直接在浮士德的颅骨里回荡。

　　“你终于愿意听了，浮士德先生。”那个声音带着笑意，“那么，就请允许我做一下自我介绍。”

注意对比：灵魂完整度 100 时，浮士德是“枯坐的学者”，面对梅菲斯特的出场保持着冷静和犹疑——“你是谁？未经允准擅入我的书斋。”而灵魂完整度 50 时，他变成了“自焚边缘的疯狂求知者”，对瓦格纳怒吼，将知识追求定义为亵渎，连梅菲斯特出场的方式都更加激烈——不是从阴影中走出，而是烛火窜升、声音直接在颅骨内回荡。

状态值变了，叙事质感也跟着变了。这就是状态驱动的力量。

注意看第一次输出中的几个元素：

• 浮士德的学者身份和求知欲——来自 【锚点】 中的”知识高于一切”和 【世界观】 中”穷尽一生也无法触及本质”的设定。LLM 忠实地继承了这些特质。
• 梅菲斯特的出现——由规则 [梅菲斯特] 在之前的对话中注入的记忆触发。你输入了”想要获取超越人类认知的知识”，规则条件 包含 "想要" 匹配，触发了 [新体验] 规则，注入的记忆为 LLM 提供了”浮士德心中燃起新渴望”的上下文。
• “代价”和”灵魂”的回应——LLM 在叙事中自然引入了”代价”这个关键词，触发了规则 [灵魂代价]——即使你没有在输入中直接说出这两个词。
• “永不满足”的底色——规则 [永不满足] 的条件是 不包含 "放弃" && 不包含 "满足"，它几乎在每一轮都会触发，持续注入”浮士德还想要更多”的信息，让你写下的不只是单次对话，而是贯穿始终的角色气质。

每一行规则都在发挥作用。 没有一个多余。

六、试试改点什么

现在你已经看到引擎的效果，可以动手修改看看变化：

修改状态值

- 灵魂完整度：50

你刚才已经看到了结果。试试改成 10 或 0，看看浮士德会变成什么样子。

加一条骰子规则

[命运的眷顾] if 包含 "追求" && roll(1d100) >= 80 -> 注入 "命运似乎站在{角色名}这边，事情比预想中顺利"

roll(1d100) >= 80 的意思是：掷一个 100 面骰，结果 >= 80 时才触发。20% 的成功率，不是每次”追求”都会幸运——这为故事注入了真正的随机性。

跑两轮对话，看子版存档

运行两次对话后，用文本编辑器打开 data/faust_child.meph：

【状态】
- 灵魂完整度：100
- 情绪：永不满足

【记忆】
- 浮士德感到心中燃起新的渴望...
- 梅菲斯特的声音在他耳边低语...

【历史】
- fate: 我想要体验爱情
- assistant: ...

这就是引擎的 Mother-Child 存档机制：母版 faust.meph 是只读的静态契约，子版 faust_child.meph 是包含运行时状态、记忆和历史的动态快照。每次对话结束后自动保存。

七、小结

到这里你完成了三件事：

1. 写了一份完整的契约文件——30 行，覆盖了角色名、锚点、状态、世界观、规则等核心区块
2. 用解析器验证了它的结构——parse 命令精确告诉你内容是否正确
3. 运行引擎看到了角色”活”过来——即使没有 LLM，规则也在运行；有了 LLM，你写下的每条规则都在塑造叙事方向

那 30 行是你和引擎之间的契约。引擎确保 LLM 遵守它。

下篇文章将深入引擎内部，回答一个关键问题：区块扫描器是如何精确识别 【角色名】 和 【规则】 的？错误信息为什么能精确报出”第 12 行（区块「锚点」）：缺少 ‘:’ 或 ‘：’“——而不是 unexpected token at position 246？

答案是手写区块扫描器——一个逐行扫描、精确绑定行号、白名单前置的轻量级 Lexer。我们下一篇见。

项目地址：https://github.com/yuelinghuashu/mephisto

我定义了一个角色：贝利亚奥特曼，性格狂傲、蔑视光之国、崇尚力量。前三轮对话表现完美——每次回答都带着那种令人满意的反派质感。第五轮开始，他开始跟我讲人生哲理，像个温和的哲学家。第十轮，他自称“光之国的守护者”，完全忘记了自己是谁。

这不是模型不够好。这是“自由生成”的固有缺陷——大模型没有“必须遵守规则”的内置机制。你可以在系统提示里写“你是一个狂傲的反派”，但模型对“狂傲”的理解是概率性的，会在长上下文中逐渐衰减，被用户的输入、模型的输出、甚至 token 顺序漂移所覆盖。

我需要一种方式，把规则写下来，让模型必须遵循。于是我开始写 Mephisto。

但在写引擎代码之前，我先要解决一个更基础的问题：这些规则应该用什么格式来写？

它需要承载的内容包括角色名（单行）、世界观（多行）、状态变量（键值对）、行为规则（条件-动作）。每种内容的结构和解析方式都不同，这个格式直接决定了创作者是把时间花在写故事上，还是花在调试语法上。

这篇文章记录了我在这件事上的取舍和最终设计。

二、叙事引擎的第一个问题：规则怎么表达？

一个叙事引擎首先要解决的，是规则表达层的问题——创作者怎么告诉引擎”这个角色会做什么、不会做什么”。

通行的做法有三种：

• 通用结构化格式（JSON/YAML）：程序友好，但对创作者残忍——转义地狱、报错不可读
• 自定义领域格式（如 .meph、Ink）：可以在两者之间找到平衡，但解析器必须手写
• 纯文本：对创作者最友好，但程序几乎无法精确解析

每种都有代价。我将一一对比，最后解释为什么选择了自定义格式。

三、先看目标：一份真实的 .meph 契约

在讨论任何设计之前，先看成品。下面是一份完整的 .meph 契约文件，来自项目中的 data/sample.meph：

【角色名】
贝利亚奥特曼

【锚点】
- 核心信念：力量就是一切
- 说话风格：狂傲、嘲讽、不容置疑

【世界观】
光之国是宇宙中最强大的文明，也是贝利亚的故乡。
但他早已被驱逐，如今他带着对光之国的憎恨归来。

【状态】
- 堕落指数：50
- 情绪：暴怒
- 位置：宇宙空间站

【规则】
[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[防御] if 包含 "防御" || 包含 "防守" -> 注入 "贝利亚摆出了防御姿态"
[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国，也是他最大的仇恨来源"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

这就是一份契约的全部。创作者看到的不是 { 和 }，不是转义引号，不是缩进层级，而是：

• 【角色名】 下面直接写名字
• 【锚点】 下面用 - 键: 值 列出核心人格
• 【规则】 下面用 [名] if 条件 -> 动作 定义行为

注意规则中的 {角色名}——这是插值占位符，解析器原样存储，运行时由引擎替换为当前角色名。这保证了多分支场景下各分支独立演化，互不干扰。

看起来像文档。但程序可以精确地解析它，并且当它出错时，能告诉创作者“第 12 行（区块「状态」）：列表项必须以 ‘-’ 开头”，而不是 unexpected token at position 246。

接下来的问题就是：怎么走到这一步的？

四、JSON：对程序友好，对人残忍

JSON 是最自然的第一选择。结构清晰、解析简单、任何语言都有现成库。我最初也确实用 JSON 写过原型，但很快发现了一个致命问题。

上面那条规则在 JSON 里长这样：

{
  "rules": [
    {
      "name": "攻击",
      "condition": "包含 \"攻击\"",
      "action": "注入 \"贝利亚发动了猛烈的攻击\""
    }
  ]
}

创作者的意图是：

包含 "攻击"

在 JSON 里必须写成：

"condition": "包含 \"攻击\""

问题不在于语法“有多难”，而在于心智切换成本。创作者在书写时不能直接表达自己的意图，必须时刻思考“我是在写 JSON 还是在写规则”。在大型契约中，这种成本是持续累积的——你阅读的不是内容，而是在不断核对“这一行有多少个反斜杠”。

更糟糕的是错误信息。一个常见的错误：在 "rules" 数组的最后一个元素后面多加了一个逗号。JSON 解析器报错：

Unexpected token } in JSON at position 246

创作者需要复制粘贴去数“position 246”在哪。这个体验对于非技术用户几乎是毁灭性的。

JSON 对程序友好，但对人不友好。 而这份文件的作者是创作者，不是程序员。

五、YAML：简单的幻觉

YAML 看起来解决了 JSON 的可读性问题：

role_name: 贝利亚奥特曼
rules:
  - name: 攻击
    condition: 包含 "攻击"
    action: 注入 "贝利亚发动了猛烈的攻击"

缩进取代了括号和逗号，确实更像“写文档”了。

但 YAML 的问题比 JSON 更隐蔽。它不是“语法错误”的问题，而是“逻辑错误”的问题——文件能读，但行为完全不对。

想象一下：你在 YAML 中定义一个多行文本块（比如世界观），用 | 标记：

worldview: |
  光之国是宇宙中最强大的文明。
  贝利亚被驱逐后，一直在寻找复仇的机会。

然后在下面继续定义一个列表。缩进稍微偏差一个空格，解析器就可能把多行文本块的后续行当作列表的子元素。结果就是：世界观内容被截断，列表结构被破坏，没有任何报错，引擎运行时产生非预期的行为。

更隐蔽的是，中文全角空格和英文半角空格在视觉上几乎无法分辨。创作者在编辑器中敲了一个全角空格（　）而非半角空格（），YAML 解析器不会把它当作缩进的一部分，而是抛出语法错误，或者诡异地将整段文本识别为键名。没有语法高亮的情况下，这种错误几乎无法肉眼排查。

创作者不是在阅读内容，而是在不断核对“这一行到底缩进了几个空格”。对于上百行的契约文件，这种认知负担是持续累积的。

YAML 的“简单”是一个错觉。 它对人友好，但对程序来说，它的规则比 JSON 更复杂、更难以预测。

六、纯文本：自由但模糊

既然结构化格式都有问题，那能不能干脆不用结构，直接用纯文本写？

比如这样：

角色名是贝利亚奥特曼。
世界观是光之国。
规则是如果用户提到攻击，就执行攻击。

对创作者来说，这是最自然的方式——没有任何学习成本。

但问题是：程序看不懂。它不知道“角色名是贝利亚奥特曼”这句话里的“是”是声明还是叙述，不知道“世界观是光之国”和下一句“规则是……”之间是什么关系。纯文本的自然语言对人类来说是清晰的，但对程序来说，它是模糊的、歧义的、无法精确解析的。

如果我用纯文本，就需要设计一套隐式约定——比如靠关键词匹配来识别区块，靠换行来区分条目。这比显式语法更难保证正确性。

纯文本对创作者最友好，但对程序几乎不友好。

七、三个方案的对比

我需要一种格式：写起来像文档，读起来有结构。 它必须同时满足两个条件：

1. 创作者可以自然地书写，不需要学习 JSON 转义或 YAML 缩进规则
2. 程序可以精确地解析，并且报错时能告诉创作者具体位置和原因

这意味着我无法使用任何现成的通用格式——我需要设计一种专门针对“叙事契约”这个场景的格式。

八、.meph 的设计原则

回到开篇那份 .meph 契约。它的设计基于三条原则：

1. 用人类语言做边界，消除括号恐惧

创作者看到的不是 { 和 }，而是 【角色名】。中文书名号对中文创作者来说比花括号自然得多。【角色名】 本身说明了区块的内容是什么，不需要额外注释。

更重要的是，区块标题被限定在白名单内（角色名、锚点、规则、状态 等）。如果创作者写了 【脚色名】（错别字），解析器不会把它当作区块开始——创作者会得到一个指向该行的错误，具体信息取决于上下文，但行号是精确的。

2. 区分“语义区块”而非“数据结构”

在 JSON 中，创作者需要自己决定用对象还是数组，这属于实现细节。在 .meph 中，创作者只需要知道“这是一个列表”或“这是一段话”。“角色名是单行文本”和“规则是列表”由解析器根据区块名识别，不由创作者声明。

3. 语法贴近自然逻辑

规则采用 [规则名] if 条件 -> 动作 的直观写法。条件中的逻辑运算符用 包含、状态.键 > 值 这类可读性强的表达，而不是纯符号。

九、代价

这套设计不是没有代价的：

• 解析器需要手写：我不能用 json.Unmarshal 或 yaml.Unmarshal，需要自己写扫描器（Lexer）和解析器（Parser）
• 需要维护白名单：新增区块时要同步更新 knownBlocks 列表
• 需要文档：创作者需要学习这个格式的写法——虽然学习成本比 JSON 低，但毕竟需要学习
• 工具链缺失：没有现成的语法高亮、格式化、校验工具

但这个取舍的衡量标准很简单：这份文件的作者是谁？

如果是程序员写、程序读，JSON 够用了。如果是创作者写、程序读，就需要一种“以人为中心”的格式。而叙事引擎的目标用户正是创作者——写故事的人。

这个取舍，我认为是值得的。

十、小结

这篇文章回答了“用什么格式”这个问题。答案是 .meph——一种专门为叙事契约设计的、对创作者友好的文本格式。

但“设计”只解决了一半问题。下一篇，我们放下理论，先动手写一份真实的契约，看看它跑起来是什么样子。

项目地址：https://github.com/yuelinghuashu/mephisto

前两篇我们准备好了 Token 组件和统一符号映射表。这一篇，我们将正式实现整个词法分析的核心引擎——Lexer（词法分析器），让程序能够真正“阅读”文本，并将它切分成一条源源不断的 Token 流。

一、核心思想：Lexer 就像一条传送带

在动手写代码前，我们先要在脑海里建立一个物理模型。词法分析器（Lexer）的运作方式，极其类似于工厂里的扫描传送带：

1. 输入文本被平铺在传送带上，每个字符（rune）占据一个格子。
2. 有一个光标（指针），指向当前正在观察的字符。
3. Lexer 的工作就是：

• 瞧一眼当前光标指着的字符是什么（peek）。
• 如果是一个符号（比如左括号 【），把它打包成 Token，然后光标往后挪一格（advance）。
• 如果是一串连续的普通文字（比如 贝利亚奥特曼），就把它们拼在一起打包成一个 TEXT Token，直到撞上符号再停下来。

二、定义 Lexer 结构体

在 internal/parser/ 目录下创建 lexer.go。我们需要三个基础字段来维护这条“传送带”的状态：

package parser

// Lexer 词法分析器结构体
type Lexer struct {
	input    []rune // 待扫描的完整文本（转为 rune 切片，完美支持中文与 Emoji）
	position int    // 当前扫描到的字符索引位置
	line     int    // 当前行号（从 1 开始，用于后续报错提示）
}

// NewLexer 创建一个词法分析器实例
func NewLexer(input string) *Lexer {
	return &Lexer{
		input:    []rune(input), // 将 string 转为 []rune 存储
		position: 0,
		line:     1,
	}
}

为什么用 []rune(input) 提前转换？

我们在上一篇强调过，Go 的 string 底层是字节流（byte）。如果每次读取都去算字节，处理中文会非常痛苦。我们在初始化时直接将它转为 []rune 数组，之后光标的 position++ 移动的每一个单位，就稳稳当当地代表一个独立的中文字符、英文字母或 Emoji。

三、传送带的三驾马车：基础辅助方法

为了操纵这个光标，我们需要实现三个最基本的辅助方法：检查结束、瞅一眼、往前移。

// isEOF 检查光标是否已经走到了文件末尾 (End of File)
func (l *Lexer) isEOF() bool {
	return l.position >= len(l.input)
}

// peek 瞅一眼当前位置的字符，但【绝不挪动光标】
// 如果已经到末尾，返回 0
func (l *Lexer) peek() rune {
	if l.isEOF() {
		return 0
	}
	return l.input[l.position]
}

// advance 消费当前字符：读取并返回它，同时【将光标向后移动一位】
// 特别注意：如果消费的是换行符 '\n'，顺手将行号 line++
func (l *Lexer) advance() rune {
	if l.isEOF() {
		return 0
	}
	ch := l.input[l.position]
	if ch == '\n' {
		l.line++
	}
	l.position++
	return ch
}

有了这三个基础方法，我们的光标就能安全、自由地在文本数组中穿梭了。

四、跳过无意义的空白

在 .meph 文件中，用户可能会在括号两边打上空格或缩进，比如 【角色名】。

这些空格没有实际语义，Lexer 应该在识别下一个 Token 之前，默默把它们吞掉。

因为在同一个包（package parser）内部，我们直接越过复杂的函数封装，利用 Go 原生的 map 匹配来跳过空白：

// skipWhitespace 跳过无意义的空白字符（空格、制表符、回车符）
// 注意：千万不能跳过换行符 '\n'，因为换行在我们的语法里代表“区块标题结束”
func (l *Lexer) skipWhitespace() {
	for !l.isEOF() {
		info, ok := symbolMap[l.peek()]
		// 如果在符号表里，且 Category 是 whitespace，就消费掉它
		if !ok || info.Category != "whitespace" {
			break
		}
		l.advance() // 光标无情后移
	}
}

五、核心逻辑：实现 NextToken() 分发器

它的职责是：跳过空白，盯着光标位置。如果是符号表里的符号，一律直接消费并返回；如果表里找不到，那它必然是普通文本！

// NextToken 获取下一个 Token
func (l *Lexer) NextToken() Token {
	// 1. 每次进来，先清洗掉前面的无意义空格
	l.skipWhitespace()

	// 2. 查看当前光标指着谁
	ch := l.peek()

	// 3. 边界处理：如果到文件末尾了，吐出 EOF 哨兵 Token
	if ch == 0 {
		return Token{Type: TOKEN_EOF, Literal: "", Line: l.line}
	}

	// 4. 🚀 终极查表驱动：因为在同包内，直接匹配 symbolMap！
	if info, ok := symbolMap[ch]; ok {
		l.advance() // 是符号？光标前进，消费它！
		return Token{Type: info.TokenType, Literal: string(ch), Line: l.line}
	}

	// 5. 符号表里查不到？那它一定是普通文本文字（如 "贝利亚奥特曼"）
	return l.readText()
}

你看！得益于同包内直接查表的设计，整个分发核心干净得让人感动。这里没有任何复杂的条件分支，更去掉了不必要的套娃函数调用。无论未来你的语法扩充到有多少种符号，这个 NextToken() 的大框架都稳如磐石，永远不需要修改一行。

六、文本的贪婪读取：readText()

NextToken() 的核心逻辑我们已经看完了。现在进入它调用的最后一个分支——readText()，看看普通文本是如何被一口气吞下的。

当字符不在符号表里时（比如碰到了中文汉字 贝），Lexer 应该开启“贪婪模式”：只要后面接下来的字符不是符号，就一路把它们全部吞下，拼成一个长字符串。

有了上一篇建立的统一符号表，判定“什么时候该停下来”也变得不可思议的优雅：只要 peek() 到的字符能在 symbolMap 里匹配成功，就说明撞到了符号（比如换行符或括号），它天然就是分隔符，文本读取立刻停止！

// readText 读取一段连续的普通文本
// 停止条件：遇到符号表中的任意符号（如换行符、括号、冒号）或文件结束
func (l *Lexer) readText() Token {
	// 记录起始位置
	start := l.position

	for !l.isEOF() {
		// 🌟 降维打击：直接查表！只要当前字符在符号表里，说明撞墙了，立刻停下
		_, ok := symbolMap[l.peek()]
		if ok {
			break
		}
		l.advance() // 否则，继续快乐地吞噬文字
	}

	// 利用切片，把这段光标走过的 rune 范围直接转成字符串字面量
	literal := string(l.input[start:l.position])
	return Token{Type: TOKEN_TEXT, Literal: literal, Line: l.line}
}

七、大功告成：在 main.go 中验证成果

让我们把现在的 main.go 升级一下，用我们亲手写的 Lexer 去解析测试文件，看看它能不能顺利吐出我们要的零件流：

package main

import (
	"fmt"
	"mephisto/internal/parser"
	"os"
)

func main() {
	if len(os.Args) < 2 {
		fmt.Println("用法: mephisto <文件>")
		os.Exit(1)
	}

	content, err := os.ReadFile(os.Args[1])
	if err != nil {
		fmt.Printf("读取文件失败: %v\n", err)
		os.Exit(1)
	}

	// 1. 初始化我们的传送带 Lexer
	l := parser.NewLexer(string(content))

	// 2. 循环驱动传送带，直到撞上 TOKEN_EOF
	fmt.Printf("%-5s | %-20s | %s\n", "行号", "类型", "字面量")
	fmt.Println("------+----------------------+-----------")
	for {
		tok := l.NextToken()
		// 为了防止换行符 \n 导致终端实际换行破坏表格，打印时做个转换处理
		literal := tok.Literal
		if tok.Type == parser.TOKEN_NEWLINE {
			literal = "\\n"
		}

		fmt.Printf("%-5d | %-20s | %s\n", tok.Line, tok.Type, literal)

		if tok.Type == parser.TOKEN_EOF {
			break
		}
	}
}

再次运行我们的测试文件（testdata/sample.meph）：

go run main.go testdata/sample.meph

终端将会输出一行极其漂亮、对齐完美、极具工业美感的词法流结果：

行号    | 类型                 | 字面量
------+----------------------+-----------
1     | LEFT_BRACKET         | 【
1     | TEXT                 | 角色名
1     | RIGHT_BRACKET        | 】
1     | NEWLINE              | \n
2     | TEXT                 | 贝利亚奥特曼
3     | EOF                  |

看！计算机通过我们写的 Lexer，成功把一串冰冷的、毫无结构的原始字节，变成了一个个生动的、自带行号和类型的结构化 Token 块！

八、小结

到这一篇为止，我们的 Lexer 词法分析器已经完全体诞生了！

至此，词法分析的战役完美结束。

上一篇我们定义了 Token，但 Token 只是”零件”。在实现 Lexer 之前，还有一个问题要先解决——如何让 Lexer 能认识所有符号，而不需要每次新增符号都修改它的代码。

一、回顾：上一篇我们停在了哪里

上一篇我们定义了 Token：

package parser

type TokenType string

const (
	TOKEN_LEFT_BRACKET  TokenType = "LEFT_BRACKET"  // 【
	TOKEN_RIGHT_BRACKET TokenType = "RIGHT_BRACKET" // 】
	TOKEN_TEXT          TokenType = "TEXT"          // 普通文本
)

type Token struct {
	Type    TokenType
	Literal string
}

现在我们需要一个程序——Lexer（词法分析器）——来读取文本，不断产出这些 Token。

但在写 Lexer 之前，我们还需要做一件事：扩充 Token 类型，并建立一套让 Lexer 能识别所有符号的机制。

二、扩充 Token 类型

上一篇我们只定义了三种 Token 类型。但在一个完整的 .meph 文件中，除了 【、】 和普通文本，还有更多符号需要识别：

parser/token.go 现在的完整代码如下：

package parser

type TokenType string

const (
	// 语法符号
	TOKEN_LEFT_BRACKET  TokenType = "LEFT_BRACKET"  // 【
	TOKEN_RIGHT_BRACKET TokenType = "RIGHT_BRACKET" // 】
	TOKEN_COLON         TokenType = "COLON"         // ：
	TOKEN_HYPHEN        TokenType = "HYPHEN"        // -
	TOKEN_AT            TokenType = "AT"            // @
	TOKEN_HASH          TokenType = "HASH"          // #

	// 内容类型
	TOKEN_TEXT TokenType = "TEXT" // 普通文本

	// 控制标记
	TOKEN_NEWLINE TokenType = "NEWLINE" // 换行符
	TOKEN_EOF     TokenType = "EOF"     // 文件结束（哨兵）
)

type Token struct {
	Type    TokenType
	Literal string    // 符号的原始文本
	Line    int       // 当前行号（从 1 开始）
}

注意： NEWLINE 和 EOF 虽然在 Lexer 实现中才会用到，但我们提前定义好，这样后续文章就不需要回头修改 token.go 了。

三、问题：Lexer 需要认识多种符号

Lexer 的工作是扫描文本，识别出每个符号是什么。

一个最直接的写法是：

switch ch {
case '【':
    // 返回 LEFT_BRACKET
case '】':
    // 返回 RIGHT_BRACKET
case '：':
    // 返回 COLON
case '-':
    // 返回 HYPHEN
// ... 越来越多的 case
}

这样写有三个问题：

我们需要一种更好的方式：把”符号是什么”和”怎么判断符号”分开。

四、方案：用一张表统一管理所有符号

核心思想很简单：把所有的符号集中在一张表里管理，Lexer 通过查表来判断。

这张表里，每个符号记录两件事：

1. 对应的 Token 类型：如 LEFT_BRACKET、RIGHT_BRACKET、COLON
2. 分类：如 bracket（括号）、colon（冒号）

Lexer 只需要查这张表，就能知道当前字符是什么类型的 Token。

五、关键决策：用 rune 而不是 byte

在定义映射表之前，先确定一个关键问题：用什么类型来存储字符？

在 Go 中，遍历字符串有两种方式：

【 在 UTF-8 中占 3 个字节。如果按 byte 遍历，【 会被拆成 3 个独立的字节，无法正确识别。

所以必须用 rune——它能保证每个字符（无论中英文）都被当作一个整体处理。

用 rune 的代价： Go 的 string 底层是 []byte，把它转成 []rune 需要额外分配内存。但对于我们处理的 .meph 文件（通常只有几 KB 到几百 KB），这个代价可以忽略不计。正确性远比微小的性能损耗重要。

六、定义映射表

6.1 结构体定义

创建 parser/symbols.go：

package parser

// SymbolInfo 符号信息
type SymbolInfo struct {
    TokenType TokenType // 对应的 Token 类型
    Category  string    // 分类：bracket, colon, hyphen, at, hash, whitespace, newline
}

6.2 映射表

// symbolMap 所有符号的映射表
// 新增符号只需在这里加一行
var symbolMap = map[rune]SymbolInfo{
    // 括号
    '【': {TokenType: TOKEN_LEFT_BRACKET, Category: "bracket"},
    '】': {TokenType: TOKEN_RIGHT_BRACKET, Category: "bracket"},
    '[':  {TokenType: TOKEN_LEFT_BRACKET, Category: "bracket"},
    ']':  {TokenType: TOKEN_RIGHT_BRACKET, Category: "bracket"},

    // 冒号
    '：': {TokenType: TOKEN_COLON, Category: "colon"},
    ':':  {TokenType: TOKEN_COLON, Category: "colon"},

    // 连字符
    '-':  {TokenType: TOKEN_HYPHEN, Category: "hyphen"},

    // 引用符号
    '@':  {TokenType: TOKEN_AT, Category: "at"},

    // 标签/注释符号
    '#': {TokenType: TOKEN_HASH, Category: "hash"},

    // 空白字符（空格、制表符、回车）
    // 注意：这些字符会被 skipWhitespace() 提前消费，不会作为 Token 返回
    ' ':  {TokenType: TOKEN_TEXT, Category: "whitespace"},
    '\t': {TokenType: TOKEN_TEXT, Category: "whitespace"},
    '\r': {TokenType: TOKEN_TEXT, Category: "whitespace"},

    // 换行符
    '\n': {TokenType: TOKEN_NEWLINE, Category: "newline"},
}

关键设计说明：

七、基于映射表的符号查询

有了映射表，查询符号信息变得极其简单——直接查表即可：

// GetSymbolInfo 查询符号信息
// 返回值：(SymbolInfo, bool)，bool 表示是否找到
// 这是给外部包（如测试代码）用的查询入口
func GetSymbolInfo(ch rune) (SymbolInfo, bool) {
    info, ok := symbolMap[ch]
    return info, ok
}

这个函数是 symbolMap 的唯一直观体现：它告诉调用方”这个字符是不是我们认识的符号？如果是，它是什么类型？”

在下一篇文章中，我们会看到 Lexer 内部如何使用 symbolMap 来实现一次查表驱动整个词法分析。现在我们先验证这张表是否工作正常。

八、验证：查表逻辑的正确性

在 main.go 中测试 GetSymbolInfo：

package main

import (
    "fmt"
    "mephisto/internal/parser"
)

func main() {
    // 查询中文左括号
    info, ok := parser.GetSymbolInfo('【')
    fmt.Printf("'【' → %s, 找到: %v\n", info.TokenType, ok) // LEFT_BRACKET, true

    // 查询英文左括号
    info, ok = parser.GetSymbolInfo('[')
    fmt.Printf("'[' → %s, 找到: %v\n", info.TokenType, ok) // LEFT_BRACKET, true

    // 查询普通字母（不在表中）
    info, ok = parser.GetSymbolInfo('x')
    fmt.Printf("'x' → 找到: %v\n", ok) // false

    // 查询换行符
    info, ok = parser.GetSymbolInfo('\n')
    fmt.Printf("'\\n' → %s, 找到: %v\n", info.TokenType, ok) // NEWLINE, true
}

输出：

'【' → TOKEN_LEFT_BRACKET, 找到: true
'[' → TOKEN_LEFT_BRACKET, 找到: true
'x' → 找到: false
'\n' → TOKEN_NEWLINE, 找到: true

验证要点：

• 【 和 [ 都返回 TOKEN_LEFT_BRACKET——这就是中英双语支持
• x 不在表中——它会被当作普通文本处理
• \n 在表中，被识别为 TOKEN_NEWLINE——它有语法意义，会被返回

注意： 空格不在验证列表中，因为空格被 skipWhitespace() 提前消费了，我们验证的重点是”会被 Lexer 返回的符号”。

九、这种设计的优势

核心思想：让数据决定一切。

十、小结

这一篇完成了两件事：

下一篇：实现 Lexer，真正把文本变成 Token 流。

一个文本文件对计算机来说只是一串字符，毫无结构可言。我们要做的第一件事，就是让计算机能“认出”这些字符里藏着什么。

一、问题：计算机看不懂文本的结构

假设我有一个文本文件，内容是这样的：

【角色名】
贝利亚奥特曼

我（人类）一眼就能看出：

• 【角色名】 是一个标题
• 贝利亚奥特曼 是它的内容

但计算机看到的是：

[ 0xE3 0x80 0x90 0xE8 0xA7 0x92 0xE8 0x89 0xB2 0xE5 0x90 0x8D 0xE3 0x80 0x91 0x0A 0xE8 0xB4 0x9D 0xE5 0x88 0xA9 0xE4 0xBA 0x9A 0xE5 0xA5 0xA5 0xE7 0x89 0xB9 0xE6 0x9B 0xBC ]

这就是计算机眼中的文本——一串基于 UTF-8 编码的原始字节流。它不知道 0xE3 0x80 0x90 连起来就是中文的 【，也不知道 【 和 】 是配对的。

它看到的只是一串毫无意义的数字。

如果我想让程序读懂这种格式的文本，第一个要解决的问题就是：让计算机能“认出”文本的结构。

二、怎么办：拆成小块，贴上标签

计算机不认识“区块标题”这种概念，但它能识别字符。

如果我把这段文本拆成最小的“有意义的片段”，并给每个片段贴上固定的标签，计算机就能一步步理解它了。

比如，把：

【角色名】
贝利亚奥特曼

拆成：

这样，程序就能知道：

1. 这里有一个左括号
2. 后面跟了一段文本（“角色名”）
3. 然后是一个右括号
4. 换行后，又有一段文本（“贝利亚奥特曼”）

下一步，程序就可以根据这个规律，识别出“【】”包裹的是标题，标题下面跟着的是内容。

三、Token：有标签的最小片段

这种有标签的最小片段，就叫 Token。

每个 Token 需要记录两件事：

1. 类型：这是什么？（左括号？文本？右括号？）
2. 字面量：它长什么样？（【？角色名？）

把文本拆成 Token 的过程，叫词法分析。

执行词法分析的程序，叫 Lexer（词法分析器）。

四、定义 Token：第一行代码

4.1 项目结构

在开始写代码前，先建立清晰的模块化目录：

mephisto/
├── go.mod
├── main.go
├── testdata/
│   └── sample.meph
└── internal/
    └── parser/
        ├── token.go
        ├── symbols.go
        └── lexer.go

注意： 所有解析相关的代码都放在 parser/ 目录下，这样随着系列文章的推进，我们始终在同一个包里工作，目录结构的变化只是“新增文件”，不是“切换包”。读者从头到尾只需要关注 internal/parser/ 这一个目录的演进。

4.2 初始化 Go 模块

go mod init mephisto

4.3 定义 Token 类型与结构体

创建 parser/token.go：

package parser

// TokenType 表示 Token 的类型
// 用 string 而不是 int，调试时可以直接看到类型名
type TokenType string

const (
	TOKEN_LEFT_BRACKET  TokenType = "LEFT_BRACKET"  // 【
	TOKEN_RIGHT_BRACKET TokenType = "RIGHT_BRACKET" // 】
	TOKEN_TEXT          TokenType = "TEXT"          // 普通文本
	// 更多 Token 类型将在后续文章中逐步引入
)

// Token 是计算机理解文本的最小有意义片段
type Token struct {
	Type    TokenType // 类型：LEFT_BRACKET？TEXT？
	Literal string    // 字面量："【"？"角色名"？
	Line    int       // Line 字段将在后续文章中引入（用于错误提示）
}

为什么用 string 而不是 int 定义类型？

如果用一个数字表示类型，调试时打印出来的是一串数字，需要翻代码才能知道 0 代表什么。而用 string，fmt.Println(tok.Type) 直接打印 "LEFT_BRACKET"，可读性高得多。词法分析器处理的 Token 数量通常只有几百个，string 的性能开销可以忽略不计。

为什么 Token 的字段要大写？

在 Go 里，大写字母开头的字段是公开的，小写是私有的。Token 会被 main.go 使用，所以它的字段必须大写，否则外部包无法访问。

五、验证：让代码能编译

5.1 创建入口文件

在项目根目录创建 main.go。目前它只负责读取文件并打印内容——虽然还没有用到 parser 包，但项目的骨架已经搭建完毕：

package main

import (
	"fmt"
	"os"
)

func main() {
	if len(os.Args) < 2 {
		fmt.Println("用法: mephisto <文件>")
		os.Exit(1)
	}

	content, err := os.ReadFile(os.Args[1])
	if err != nil {
		fmt.Printf("读取文件失败: %v\n", err)
		os.Exit(1)
	}

	fmt.Print(string(content))
}

5.2 创建测试文件

testdata/sample.meph：

【角色名】
贝利亚奥特曼

5.3 运行

go run main.go testdata/sample.meph

看到文件内容输出，说明项目能跑了：

【角色名】
贝利亚奥特曼

六、小结

这一篇完成了一件事：为整个系列打下地基。

接下来我们要做的就是实现 Lexer——让程序能自动从文本里“吐”出 Token。

完整代码

parser/token.go

package parser

type TokenType string

const (
	TOKEN_LEFT_BRACKET  TokenType = "LEFT_BRACKET"
	TOKEN_RIGHT_BRACKET TokenType = "RIGHT_BRACKET"
	TOKEN_TEXT          TokenType = "TEXT"
)

type Token struct {
	Type    TokenType
	Literal string
}

main.go

package main

import (
	"fmt"
	"os"
)

func main() {
	if len(os.Args) <  {
		fmt.Println("用法: mephisto <文件>")
		os.Exit(1)
	}

	content, err := os.ReadFile(os.Args[1])
	if err != nil {
		fmt.Printf("读取文件失败: %v\n", err)
		os.Exit(1)
	}

	fmt.Print(string(content))
}

在个人博客中，代码高亮是阅读体验的核心。市面上主流的 Prism.js 和 Highlight.js 虽然普及度高，但高亮精度有限。相比之下，Shiki 使用与 VSCode 相同的 TextMate 语法引擎，能实现像素级精准的高亮，完全对标 VSCode 的代码着色体验。

我的需求很简单：个人博客使用我自己开发的 VSCode 主题插件 Moongate Theme 的深浅两套配色，代码块在 SSR 场景下正常渲染，且深浅主题能一键联动切换。 听起来不难？实际上坑比想象中多。

坑一：自定义主题怎么加载？

Shiki 官方文档提供了两种常规的加载方式：创建高亮器时直接传入主题对象，或使用 loadTheme 动态加载 JSON 文件。看起来很简单对吧？但当把它放到 Nuxt 项目中时，问题来了。

❌ 错误尝试：依赖 nuxt-shiki 模块

我一开始用了 nuxt-shiki 模块，想着它能帮我省事。配置如下：

import lightTheme from "./assets/themes/light.json"
import darkTheme from "./assets/themes/dark.json"

export default defineNuxtConfig({
  modules: ["nuxt-shiki"],
  shiki: {
    bundledThemes: [lightTheme.name, darkTheme.name],
    defaultTheme: lightTheme.name,
  },
})

运行后直接报错：

Failed to resolve import "shiki/themes/Moongate Theme Light.mjs"

根本原因：nuxt-shiki 的 bundledThemes 只接受 Shiki 内置主题的名称（如 github-dark），它会自动去 shiki/themes/ 目录下查找对应的内置 .mjs 文件。当你传入自定义主题名称时，它找不到对应的文件，自然 404。

✅ 正确做法：直接用原生 Shiki API

放弃 nuxt-shiki 模块，直接在 Composable 中使用原生 createHighlighter，将其作为常驻内存的全局单例：

// composables/useShikiHighlighter.ts
import { createHighlighter, type Highlighter } from "shiki"
import lightTheme from "~/assets/themes/light.json"
import darkTheme from "~/assets/themes/dark.json"

let highlighterInstance: Highlighter | null = null

export async function getShikiHighlighter() {
  if (!highlighterInstance) {
    highlighterInstance = await createHighlighter({
      themes: [lightTheme, darkTheme],
      langs: [
        "bash",
        "css",
        "docker",
        "go",
        "html",
        "javascript",
        "json",
        "markdown",
        "shell",
        "sql",
        "typescript",
        "vue",
        "xml",
        "yaml",
      ],
    })
  }
  return highlighterInstance
}

关键点：主题 JSON 对象直接传入 themes 数组，高亮时通过主题的 name 字段引用即可，不再依赖外部文件的动态寻址。

坑二：自定义主题的双主题联动

单主题方案的局限性

最初的方案是在客户端组件挂载后通过 DOMParser 解析 HTML，然后根据当前主题传入对应的主题名称重新高亮：

// ❌ 客户端高亮 + watch 主题变化
const theme = isDark ? "Moongate Theme Dark" : "Moongate Theme Light"
const result = highlighter.codeToHtml(code, { lang, theme })

watch(() => store.theme, highlight) // 主题变了要重新处理所有代码块

这种传统做法会带来三个极具毁灭性的痛点：

1. 闪动：客户端 Hydration 后才能高亮，用户打开网页会看到“原始内容/黑色外壳 → 高亮内容”的明显跳变。
2. 延迟：每次一键切换主题，客户端都需要重新执行 JS 高亮所有代码块，有明显的视觉等待时间。
3. CPU 开销：在手机端低配设备上，每次切换主题都调用 WASM 引擎处理大量文本，会导致页面瞬间掉帧。

坑三：服务端高亮 + Dual Themes = 完美方案

真正的突破是把高亮工作从客户端彻底移到服务端，同时利用 Shiki 的 Dual Themes（双主题） 特性。

核心工具函数：服务端高亮处理器

创建 utils/shikiProcessor.ts。这里使用正则异步替换未高亮的 HTML 块，并加入一个健壮的兜底机制：即使代码块没有写 language-xxx，也能默认以 text 纯文本进行高亮渲染。

// utils/shikiProcessor.ts
import { getShikiHighlighter } from "~/composables/useShikiHighlighter"

export async function highlightHtmlContent(
  htmlContent: string,
): Promise<string> {
  if (!htmlContent) return ""

  const highlighter = await getShikiHighlighter()

  // 增强正则：允许匹配没有定义 language 类的标准 <code> 块
  const preCodeRegex = /<pre>\s*<code([^>]*)>([\s\S]*?)<\/code>\s*<\/pre>/g
  const matches = [...htmlContent.matchAll(preCodeRegex)]
  let resultHtml = htmlContent

  for (const match of matches) {
    const [fullMatch, attributes, rawCode] = match

    // 提取语言类型，若无则默认为 'text'
    const langMatch = attributes.match(/class="[^"]*language-(\w+)"/)
    const lang = langMatch ? langMatch[1] : "text"

    // 解码 HTML 实体，防止 Shiki 二次转义
    const code = rawCode
      .replace(/&lt;/g, "<")
      .replace(/&gt;/g, ">")
      .replace(/&amp;/g, "&")
      .replace(/&quot;/g, '"')
      .replace(/&#39;/g, "'")

    // 🎯 关键：使用 Dual Themes 一次生成包含两套颜色 Token 的 HTML
    const highlighted = highlighter.codeToHtml(code, {
      lang,
      themes: {
        light: "Moongate Theme Light",
        dark: "Moongate Theme Dark",
      },
      defaultColor: false, // 核心配置：不生成默认内联 color，完全靠 CSS 变量驱动
    })

    resultHtml = resultHtml.replace(fullMatch, highlighted)
  }

  return resultHtml
}

在数据获取层拦截并转换

在组件内部，利用 useLazyAsyncData 的 transform 选项。这步是最高级的优化：数据在服务端被 Node.js 抓取到后瞬间完成高亮替换。数据吐到前端时就已经套好了 Shiki 的外衣。

const { data: page, pending } = useLazyAsyncData<DocDetailResponse>(
  `doc-${slug.value}`,
  async () => {
    const {
      public: { apiUrl },
    } = useRuntimeConfig()
    return await $fetch(`${apiUrl}/api/docs/${slug.value}`)
  },
  {
    watch: [slug],
    // 🔥 关键：数据在服务端获取后立即转换为高亮 HTML，客户端 0 开销
    transform: async (data) => {
      if (data && data.content) {
        data.highlightedContent = await highlightHtmlContent(data.content)
      }
      return data
    },
  },
)

// 优先使用服务端已高亮的完全体 HTML
const contentRef = computed(
  () => page.value?.highlightedContent || page.value?.content || "",
)

CSS 变量控制双主题切换

Dual Themes 生成的 HTML 中会精妙地包含 –shiki-light 和 –shiki-dark 两套 CSS 变量。配合 @nuxtjs/color-mode 切换时自动在 标记的 .dark 类，只需在全局样式表中写下几行映射，就能实现纯 CSS 级别的高性能切换：

/* 浅色模式默认映射 */
.shiki {
  background-color: var(--shiki-light-bg) !important;
  color: var(--shiki-light) !important;
}
.shiki span {
  color: var(--shiki-light) !important;
}

/* 深色模式映射 - 纯 CSS 触发，不经过任何 JS 运行时 */
.dark .shiki {
  background-color: var(--shiki-dark-bg) !important;
  color: var(--shiki-dark) !important;
}
.dark .shiki span {
  color: var(--shiki-dark) !important;
}

⚡ 为什么闪动消失了？

通过前后方案的对比，我们可以清晰地看到为什么这个方案能达到“降维打击”的效果：

核心突破：高亮工作在服务端一次性就位，客户端收到即用。由于两套变量早已直出，切换主题变成了浏览器的原生样式渲染，不再需要 Pinia 去跨组件追踪和重绘。

🎨 细节打磨：代码块边框与呼吸感

最后，给代码块加点微弱的边框和极浅的阴影，能在长文阅读中有效地为代码建立视觉锚点，提升整体的呼吸感与精致度：

.shiki-content pre.shiki {
  padding: 1.25rem;
  border-radius: 0.5rem;
  overflow-x: auto;
  border: 1px solid #e5e7eb;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
  transition:
    border-color 0.3s,
    box-shadow 0.3s;
}

.dark .shiki-content pre.shiki {
  border-color: #2d3748;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

📐 架构设计流向

 ┌─────────────────┐
 │  服务端 (SSR)    │
 └────────┬────────┘
          │
          ▼
 ┌─────────────────┐
 │ 获取原始内容     │
 └────────┬────────┘
          │
          ▼
 ┌──────────────────────────────────────────────┐
 │ transform: highlightHtmlContent()            │
 │  ├── 正则匹配 <pre><code>                     │
 │  ├── Shiki 原生 API 生成 Dual Themes HTML    │
 │  └── 替换原始代码块                           │
 └────────────────┬─────────────────────────────┘
          │
          ▼
 ┌──────────────────────────────────────────────┐
 │ 返回高亮后的 HTML (含 --shiki-light / dark)   │
 └────────────────┬─────────────────────────────┘
          │
          ▼
 ┌─────────────────┐
 │ 客户端直接渲染   │
 └────────┬────────┘
          │
          ├─► 浅色模式 ──► 自动映射 --shiki-light (纯 CSS)
          └─► 深色模式 ──► 自动映射 --shiki-dark  (纯 CSS)

📝 总结

在前端实战中，面对长文章下的代码高亮需求，“在服务端多做一点，客户端就能少做很多”。通过在服务端利用 Shiki 提取双主题直出，不仅完美消灭了视觉闪烁，还让我们的博客客户端免受庞大高亮引擎带来的首屏负荷。

希望这篇实战记录能帮你在使用 Shiki + Nuxt 的路上少走弯路！

本文是系列第四篇，将前三篇的 URL 状态管理延伸至 Go 后端，实现分页、筛选、排序的端到端数据流。涵盖前后端参数约定、Go Gin 框架实践、useAsyncData 自动联动，以及 39 篇文档从 4 分钟到 10 秒的部署优化。

适用读者：已了解 Nuxt URL 状态同步（前三篇），想打通前后端完整数据流的开发者。

你将学到： - 前后端参数约定的设计方法 - Go Gin 框架中处理分页、筛选、排序的实践 - 前端 useAsyncData 与后端 API 的自动联动 - 从 URL 状态到后端响应的完整数据流闭环

📚 系列导航

本系列共四篇，覆盖 Nuxt 中 URL 与状态双向同步的全流程：

1. Nuxt 中 URL 与状态双向绑定的终极指南（原理篇） —— 讲解 URL 与状态双向同步的原理与手写方案。

2. 手写一个更适合 Nuxt 的 useRouteQuery（封装篇） —— 将重复逻辑封装成开箱即用的 composable。

3. 从零到一：构建一个功能完备的文档列表页（实战篇） —— 综合运用前两篇的知识，实现完整的文档列表页。

4. Nuxt + Go 全栈实践：从 URL 状态到后端 API 的完整闭环 —— 将前端 URL 状态与 Go 后端 API 打通，形成完整的数据流闭环。

一、前置阅读

本文假设你已经了解：

• 前端 URL 状态同步（前三篇已覆盖）
• Go 如何加载 Markdown 文件到内存（独立短文《用 Go 重构 Markdown 加载》已覆盖）

如果你还不熟悉 Go 数据加载部分，建议先阅读独立短文（非系列，10 分钟读完），再回到本篇。

📖 关于 Go 后端的数据模型（Doc 结构体）和加载逻辑（loader 包），本文不再重复。下文直接使用已加载到内存的 Store。

二、整体架构

2.1 数据流向图

┌─────────────────────────────────────────────────────────────────────────────┐
│                           前端（Nuxt）                                    │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  用户操作：输入搜索、选择等级、点击标签、翻页                          │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                       │
│                                    ▼                                       │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  useRouteQuery：状态 ↔ URL 双向同步（前三篇）                        │ │
│  │  └── search, searchMode, page, size, level, tags                    │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                       │
│                                    ▼                                       │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  useAsyncData：自动响应状态变化，构建 API 请求                       │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                       │
└────────────────────────────────────┼───────────────────────────────────────┘
                                     │ HTTP GET
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        后端（Go + Gin）                                    │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  GET /api/docs?page=1&limit=10&search=nuxt&level=P3&tag=go&tag=vue  │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                       │
│                                    ▼                                       │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  1. 解析参数：page, limit, search, searchMode, level, tags           │ │
│  │  2. 校验参数：searchMode 必须是 all/title/description               │ │
│  │  3. 数据处理：排序、筛选、分页                                      │ │
│  │  4. 返回响应：{ data, total, page, limit, totalPages }              │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                       │
└────────────────────────────────────┼───────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                   数据源（独立短文已覆盖：MD → 内存）                      │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  39 篇 Markdown 文档，启动时加载到内存                              │ │
│  │  ├── title, description, date, permalink, level, series, tags       │ │
│  │  └── content（HTML 正文）                                           │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 本篇聚焦

系列前三篇：URL ↔ 前端状态（已完成）
独立短文：  MD 文件 → 内存 Store（已完成）
本篇：      前端状态 → API 参数 → Go 处理 → 响应返回（进行中）

三、前后端参数约定

3.1 API 设计

接口定义：

GET /api/docs

请求参数：

响应格式：

{
  "data": [
    {
      "permalink": "760e47b3-...",
      "slug": "nuxt-docs-list-page",
      "title": "构建一个功能完备的文档列表页",
      "description": "手把手教你用 Nuxt 4 构建...",
      "level": "P3",
      "series": "url-state",
      "tags": ["Nuxt", "Vue", "State Management"],
      "date": "2026-03-21T00:00:00Z",
      "content": "<h1>...</h1>"
    }
  ],
  "total": 39,
  "page": 1,
  "limit": 10,
  "totalPages": 4
}

3.2 前后端参数映射

前端状态（useDocs）  →  URL 参数  →  Go 后端参数
─────────────────────────────────────────────────────
searchInput          →  search   →  c.Query("search")
searchMode           →  searchMode → c.Query("searchMode")
page                 →  page     →  c.Query("page")
size                 →  limit    →  c.Query("limit")
level                →  level    →  c.Query("level")
tags                 →  tag[]    →  c.QueryArray("tag")

3.3 searchMode 枚举约定

// Go 后端
type SearchMode string

const (
    SearchModeAll         SearchMode = "all"         // 标题 + 描述
    SearchModeTitle       SearchMode = "title"       // 仅标题
    SearchModeDescription SearchMode = "description" // 仅描述
)

func (m SearchMode) IsValid() bool {
    return m == SearchModeAll || m == SearchModeTitle || m == SearchModeDescription
}

// 前端 Nuxt（与后端完全一致）
type SearchMode = 'all' | 'title' | 'description'

约定原则：枚举值前后端保持一致，任何非法值后端返回错误。

四、Go API 实现

4.1 项目结构（与本篇相关的部分）

moongate-api/
├── cmd/server/main.go          # 入口
├── internal/
│   ├── domain/
│   │   ├── doc.go              # Doc 结构体（独立短文已覆盖）
│   │   └── search_mode.go      # SearchMode 枚举 ← 本篇
│   ├── api/
│   │   └── docs.go             # DocsHandler ← 本篇核心
│   └── loader/                 # 数据加载（独立短文已覆盖）
└── content/                    # Markdown 文件

📖 domain.Doc 结构体和 loader 包的完整实现见独立短文《用 Go 重构 Markdown 加载》。

4.2 SearchMode 枚举

// internal/domain/search_mode.go
package domain

type SearchMode string

const (
    SearchModeAll         SearchMode = "all"
    SearchModeTitle       SearchMode = "title"
    SearchModeDescription SearchMode = "description"
)

func (m SearchMode) IsValid() bool {
    return m == SearchModeAll || m == SearchModeTitle || m == SearchModeDescription
}

4.3 DocsHandler

// internal/api/docs.go
package api

import (
    "moongate-api/internal/domain"
    "net/http"
    "sort"
    "strconv"
    "strings"

    "github.com/gin-gonic/gin"
)

type DocsHandler struct {
    Store map[string]*domain.Doc // key = permalink（来自独立短文）
}

func NewDocsHandler(store map[string]*domain.Doc) *DocsHandler {
    return &DocsHandler{Store: store}
}

// GetDocs 返回分页后的文章列表
// GET /api/docs?page=1&limit=10&search=vue&searchMode=all&level=P3&tag=go&tag=vue
func (h *DocsHandler) GetDocs(c *gin.Context) {
    // 1. 获取查询参数
    page := c.DefaultQuery("page", "1")
    limit := c.DefaultQuery("limit", "10")
    search := c.Query("search")
    searchMode := domain.SearchMode(c.DefaultQuery("searchMode", "all"))
    level := c.Query("level")
    tags := c.QueryArray("tag")

    // 2. 校验 searchMode
    if !searchMode.IsValid() {
        c.JSON(http.StatusBadRequest, gin.H{
            "error": "searchMode 参数只能是 all、title 或 description",
        })
        return
    }

    // 3. 字符串转整数
    pageNum, _ := strconv.Atoi(page)
    limitNum, _ := strconv.Atoi(limit)

    // 4. 边界保护
    if pageNum < 1 {
        pageNum = 1
    }
    if limitNum < 1 {
        limitNum = 10
    }
    // 只允许 10、20、50
    allowedLimits := map[int]bool{10: true, 20: true, 50: true}
    if !allowedLimits[limitNum] {
        limitNum = 20
    }

    // 5. 转成切片并排序
    docs := make([]*domain.Doc, 0, len(h.Store))
    for _, doc := range h.Store {
        docs = append(docs, doc)
    }

    sort.Slice(docs, func(i, j int) bool {
        return docs[i].Date.After(docs[j].Date)
    })

    // 6. 筛选逻辑
    filtered := make([]*domain.Doc, 0, len(docs))
    levelUpper := strings.ToUpper(level)

    for _, doc := range docs {
        // 6.1 等级筛选
        if level != "" && doc.Level != domain.Level(levelUpper) {
            continue
        }

        // 6.2 搜索筛选
        if search != "" {
            keyword := strings.ToLower(search)
            matchTitle := strings.Contains(strings.ToLower(doc.Title), keyword)
            matchDesc := strings.Contains(strings.ToLower(doc.Description), keyword)

            switch searchMode {
            case domain.SearchModeTitle:
                if !matchTitle {
                    continue
                }
            case domain.SearchModeDescription:
                if !matchDesc {
                    continue
                }
            default:
                if !matchTitle && !matchDesc {
                    continue
                }
            }
        }

        // 6.3 标签筛选（AND 关系——必须包含所有选中标签）
        if len(tags) > 0 && !doc.ContainsAllTags(tags) {
            continue
        }

        filtered = append(filtered, doc)
    }

    // 7. 分页
    total := len(filtered)
    start := (pageNum - 1) * limitNum
    end := start + limitNum

    // 边界保护 + 兜底
    if start > total {
        start = total
    }
    if end > total {
        end = total
    }
    if start > end {
        start = end
    }

    pagedDocs := filtered[start:end]

    // 8. 返回结果
    c.JSON(http.StatusOK, gin.H{
        "data":       pagedDocs,
        "total":      total,
        "page":       pageNum,
        "limit":      limitNum,
        "totalPages": (total + limitNum - 1) / limitNum,
    })
}

4.4 主程序入口

// cmd/server/main.go
package main

import (
    "log"
    "moongate-api/internal/api"
    "moongate-api/internal/loader"

    "github.com/gin-gonic/gin"
)

func main() {
    // 1. 加载数据到内存（独立短文已覆盖）
    store, err := loader.LoadAll("content/")
    if err != nil {
        log.Fatal("加载内容失败:", err)
    }

    log.Printf("✅ 加载完成: %d 篇文章\n", len(store.Docs))

    // 2. 创建 Handler
    docsHandler := api.NewDocsHandler(store.Docs)

    // 3. 设置路由
    r := gin.Default()
    r.GET("/api/docs", docsHandler.GetDocs)
    r.GET("/api/docs/:permalink", docsHandler.GetDoc)

    // 4. 启动服务
    r.Run(":8080")
}

4.5 标签筛选的算法说明

多标签筛选有两种实现方式：

本项目使用 AND 关系，即用户选中多个标签时，只返回同时包含所有这些标签的文章。这种”无序全包含”的集合逻辑更符合”多条件精确筛选”的直觉。

正如独立短文《用 Go 重构 Markdown 加载》中所沉淀的领域模型，ContainsAllTags 方法基于 map 实现了 O(n) 的高效集合逻辑：

// internal/domain/doc.go（独立短文已覆盖）
func (d *Doc) ContainsAllTags(targetTags []string) bool {
    if len(targetTags) == 0 {
        return true
    }
    if len(targetTags) > len(d.Tags) {
        return false
    }

    tagSet := make(map[string]bool, len(d.Tags))
    for _, t := range d.Tags {
        tagSet[strings.ToLower(t)] = true
    }

    for _, t := range targetTags {
        if !tagSet[strings.ToLower(t)] {
            return false
        }
    }
    return true
}

五、前端 useDocs 实现

5.1 useRouteQuery 封装

前三篇已完整实现，此处仅列出与本篇相关的使用方式：

// composables/useRouteQuery.ts
// 完整实现见系列第二篇

export function useRouteQueryString(name: string, options?: { defaultValue?: string })
export function useRouteQueryNumber(name: string, options?: { defaultValue?: number })
export function useRouteQueryArray(name: string)

5.2 useDocs Composable

// composables/useDocs.ts
import { createSharedComposable } from '@vueuse/core'
import { useRouteQueryString, useRouteQueryNumber, useRouteQueryArray } from './useRouteQuery'

interface DocItem {
    permalink: string
    slug: string
    title: string
    description: string
    level: string
    series: string | null
    tags: string[]
    date: string
    content: string
}

interface DocsResponse {
    data: DocItem[]
    total: number
    page: number
    limit: number
    totalPages: number
}

const DEFAULTS = {
    search: '',
    searchMode: 'all',
    page: 1,
    size: 10,
    viewMode: 1,
    level: '',
} as const

const _useDocs = () => {
    // URL 同步状态（来自前三篇）
    const searchInput = useRouteQueryString('search', { defaultValue: DEFAULTS.search })
    const searchMode = useRouteQueryString('searchMode', { defaultValue: DEFAULTS.searchMode })
    const page = useRouteQueryNumber('page', { defaultValue: DEFAULTS.page })
    const size = useRouteQueryNumber('size', { defaultValue: DEFAULTS.size })
    const viewMode = useRouteQueryNumber('viewMode', { defaultValue: DEFAULTS.viewMode })
    const level = useRouteQueryString('level', { defaultValue: DEFAULTS.level })
    const tags = useRouteQueryArray('tag')

    // 筛选变化时重置页码
    watch([searchInput, searchMode, level, tags], () => {
        page.value = DEFAULTS.page
    }, { deep: true })

    // 构建请求参数
    // 注意：使用 URLSearchParams 的多参数格式（?tag=go&tag=vue）
    // 与 Gin 的 c.QueryArray("tag") 天然兼容
    const queryParams = computed(() => {
        const params = new URLSearchParams()
        params.append('page', String(page.value))
        params.append('limit', String(size.value))

        if (searchInput.value.trim()) {
            params.append('search', searchInput.value.trim())
        }
        if (searchMode.value !== DEFAULTS.searchMode) {
            params.append('searchMode', searchMode.value)
        }
        if (level.value) {
            params.append('level', level.value)
        }

        // 标签：展开后逐项添加
        tags.value.forEach((t) => params.append("tag", t));

        return params
    })

    // 调用 Go API
    const { data, pending, refresh, error } = useAsyncData(
        'docs-list',
        async () => {
            const { public: { apiUrl } } = useRuntimeConfig()
            return await $fetch<DocsResponse>(
                `${apiUrl}/docs?${queryParams.value.toString()}`
            )
        },
        {
            watch: [searchInput, searchMode, page, size, level, tags],
        }
    )

    const resetFilters = () => {
        searchInput.value = DEFAULTS.search
        searchMode.value = DEFAULTS.searchMode
        page.value = DEFAULTS.page
        size.value = DEFAULTS.size
        viewMode.value = DEFAULTS.viewMode
        level.value = DEFAULTS.level
        tags.value = []
    }

    return {
        searchInput,
        searchMode,
        page,
        size,
        viewMode,
        level,
        tags,
        docs: data,
        pending,
        error,
        refresh,
        resetFilters,
    }
}

export const useDocs = createSharedComposable(_useDocs)

5.3 组件中使用

<!-- pages/docs/index.vue -->
<template>
    <div>
        <SearchHeader
            v-model:search="searchInput"
            v-model:searchMode="searchMode"
            v-model:viewMode="viewMode"
        />

        <TagFilter v-model:tags="tags" />

        <DocList
            :docs="docs?.data || []"
            :viewMode="viewMode"
            :pending="pending"
        />

        <Pagination
            v-if="docs && docs.totalPages > 1"
            v-model:page="page"
            :totalPages="docs.totalPages"
            :total="docs.total"
            :limit="docs.limit"
        />
    </div>
</template>

<script setup>
const {
    searchInput,
    searchMode,
    page,
    size,
    viewMode,
    level,
    tags,
    docs,
    pending,
    resetFilters,
} = useDocs()
</script>

六、数据流完整闭环

6.1 用户操作触发流程

用户输入 "nuxt" 到搜索框
    │
    ▼
searchInput 变化（useRouteQueryString）
    │
    ├─ watch 触发 → 更新 URL (?search=nuxt)
    │
    └─ watch 触发 → page 重置为 1
    │
    ▼
useAsyncData 的 watch 检测到依赖变化
    │
    ▼
调用 Go API：GET /api/docs?search=nuxt&searchMode=all&page=1&limit=10
    │
    ▼
Go 后端处理：
    1. 接收参数 search="nuxt", searchMode="all"
    2. 遍历内存中的 39 篇文章，搜索标题和描述
    3. 排序、分页
    4. 返回 JSON
    │
    ▼
前端渲染更新后的列表

6.2 浏览器后退触发流程

用户点击浏览器后退按钮
    │
    ▼
URL 从 ?search=nuxt 变为 ?search=vue
    │
    ▼
useRouteQueryRaw 监听到 route.query 变化
    │
    ▼
searchInput.value = "vue"（同步到内部状态）
    │
    ▼
useAsyncData 的 watch 检测到 searchInput 变化
    │
    ▼
重新调用 Go API，数据更新

6.3 完整数据流图

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  用户操作   │───▶│  URL 变化   │───▶│  状态变化   │───▶│  API 请求   │
└─────────────┘    └─────────────┘    └─────────────┘    └──────┬──────┘
                                                                 │
                                                                 ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  页面渲染   │◀───│  数据更新   │◀───│  响应返回   │◀───│  Go 后端   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

七、核心设计决策

7.1 为什么 limit 只允许 10/20/50？

allowedLimits := map[int]bool{10: true, 20: true, 50: true}
if !allowedLimits[limitNum] {
    limitNum = 20
}

• 给用户明确的选项，减少困惑
• 防止恶意请求（如 limit=999999）
• 与前端 UI 选项保持一致

7.2 为什么用内存存储？

本项目目前 39 篇文章，总体积不足 1MB。内存存储方案：

• 启动加载 < 50ms
• API 响应 < 20ms
• 零外部依赖（不需要数据库）

架构设计没有绝对的优劣，只有特定场景下的帕累托最优。

简单说：对于现阶段 39 篇、不足 1MB 的静态资产，”内存即数据库”不是技术上最先进的方案，但在”开发效率、响应速度、运维成本”这三个维度上，它达到了当前场景下的最优平衡。

7.3 标签参数格式

前端 useRouteQueryArray 使用多参数格式：

?tag=go&tag=vue

Gin 的 c.QueryArray("tag") 原生支持这种格式，直接解析为 ["go", "vue"]：

tags := c.QueryArray("tag")  // ["go", "vue"] ✅

八、迁移收益

九、结语

本篇将前三篇的 URL 状态管理延伸到了 Go 后端，完成了从前端到后端的完整数据流闭环。

系列四篇的演进路径：

你现在拥有的是一套完整可复用的全栈架构：

• 前端：URL 驱动的状态管理 + 自动响应式数据获取
• 后端：类型安全的 Gin API + 清晰的分层架构
• 数据：内存存储，毫秒级响应
• 约定：前后端参数统一，多标签筛选支持 AND 关系

这套架构已经在实际项目中稳定运行，希望也能帮到正在构建类似系统的开发者。🎯

我需要把 30 多篇 Markdown 文档变成 API 数据源。用 Node.js 能写，用 Python 也能写，但我选择了 Go——不是因为性能，而是因为我想在实战中学 Go。这篇文章记录的不仅是一个技术方案，更是一个前端开发者从 Go 新手到 Go 实践者的完整过程。

适用读者：想通过真实项目学 Go 的开发者，以及想从 Nuxt Content 迁移出来的用户。

你将学到： - 如何用 Go 实现 Markdown 加载与 API 服务（核心逻辑 ~200 行，完整项目 ~400-500 行） - Go 项目结构设计、接口使用、文件处理的核心实践 - 一种可复制的”项目驱动学习”方法论

一、为什么用 Go？

用 Node.js + Express 能写 Markdown API，用 Python + FastAPI 也能写。为什么我偏要用 Go？

原因很朴素：我想在实战中学 Go。

我不是为了用 Go 而用 Go。而是我本来就有一个真实问题要解决，同时又想提升 Go 能力——两个目标天然契合，那就一起做。

这大概是世界上最有效的学习方式：

• 有真实需求驱动：你不是在凭空学东西，每一步都有明确目的
• 有明确交付物：一个能跑的 API 服务
• 有可量化的收益：部署时间从 4 分钟降到 10 秒
• 有完整的学习闭环：从设计到实现到上线，全流程走一遍

所以这篇文章不只是技术方案，也是一个前端开发者从 Go 新手到 Go 实践者的完整成长记录。

二、背景：我需要一个学习项目

我之前用 Nuxt Content 管理博客的 39 篇技术文章，整体体验还不错，但也遇到了一些让我想”动一动”的问题。

配置逐渐复杂，分散在多个地方：

content.config.ts——集合定义

import { defineContentConfig, defineCollection } from '@nuxt/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: 'docs/*.md',
      schema: z.object({
        title: z.string(),
        description: z.string(),
        date: z.date(),
        permalink: z.string(),
        level: z.string(),
        series: z.string(),
        tags: z.array(z.string()),
      })
    }),
    about: defineCollection({
      type: 'page',
      source: 'about/*.md',
      schema: z.object({
        permalink: z.string(),
        title: z.string(),
        description: z.string(),
        date: z.date(),
      })
    })
  }
})

nuxt.config.ts——Markdown 渲染配置

const bundledLangs = [
  'bash', 'css', 'docker', 'go', 'html',
  'javascript', 'json', 'markdown', 'shell',
  'sql', 'typescript', 'vue', 'xml', 'yaml'
];

export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          langs: bundledLangs,      // 所有语言
        },
        toc: {
          depth: 4,
          searchDepth: 3
        },
        theme: {
          default: 'vitesse-light',
          light: 'vitesse-light',
          dark: 'vitesse-dark'
        }
      },
    },
    shiki: {
      bundledThemes: ['vitesse-light', 'vitesse-dark'],
      bundledLangs: bundledLangs,
      defaultTheme: 'material-theme-lighter',
      dynamic: true,  // 懒加载语言
    },
    experimental: {
      nativeSqlite: true
    }
  }
})

每新增一种内容类型，就要在 content.config.ts 中加一个 collection；每次调整 Markdown 渲染行为，就要改 nuxt.config.ts。配置本身就在累积复杂度。

另外，内容更新需要重新构建前端：GitHub Actions 每次跑 3-4 分钟。单次还好，但改错别字也要等 3-4 分钟，累积起来就不少了。

但说实话，这些都不是非换不可的理由。真正推动我行动的是另一件事：

我需要一个 Go 项目来练手，而这个场景刚好合适。

把”内容加载”从 Nuxt 中拆出来，用 Go 重写一遍——这个需求足够小（不会因为业务复杂而影响学习），又足够完整（涵盖了 Go 项目开发的核心环节），正好适合作为学习实战项目。

不是 Nuxt Content 不好，是我需要写 Go。

三、项目目标

1. 学习 Go：在实战中掌握 Go 的核心特性
2. 内容与代码分离：改内容不需要重新构建前端
3. 技术透明：每一行代码都在自己掌控中
4. 轻量依赖：按需引入，不背全家桶

四、整体设计

4.1 架构图

┌─────────────────────────────────────────────────────────────┐
│  content/                                                  │
│  ├── docs/                                                 │
│  │   ├── article1.md                                       │
│  │   ├── article2.md                                       │
│  │   └── ...                                              │
│  └── about/                                                │
│      └── about.md                                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Go 程序启动时加载                                          │
│  ├── 遍历所有 .md 文件                                     │
│  ├── 解析 Frontmatter + 正文                               │
│  └── 存入内存 map                                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Gin API 服务                                              │
│  GET /api/docs      → 返回所有文章                         │
│  GET /api/docs/:id  → 返回单篇文章                         │
└─────────────────────────────────────────────────────────────┘

4.2 技术选型

五、项目结构

moongate-api/
├── cmd/
│   └── server/
│       └── main.go          # 程序入口
├── internal/
│   ├── domain/              # 领域模型
│   │   ├── doc.go           # Doc 结构体
│   │   └── content.go       # ContentSetter 接口
│   ├── api/                 # HTTP Handler
│   │   └── docs.go          # 文章 API
│   └── loader/              # 数据加载
│       ├── load.go          # 批量加载
│       ├── parse.go         # 单文件解析
│       └── html.go          # Markdown → HTML
├── content/                 # Markdown 内容
│   ├── docs/                # 技术文章
│   └── about/               # 关于页面
└── go.mod

这个结构是我参考 Go 社区常见实践设计的。cmd/ 放入口，internal/ 放内部包，domain/ 放领域模型——第一次真正理解”项目结构”为什么这样组织。

六、数据模型

6.1 Doc 结构体

// internal/domain/doc.go
package domain

import "time"

type Level string

const (
    LevelP1 Level = "P1"
    LevelP2 Level = "P2"
    LevelP3 Level = "P3"
    LevelP4 Level = "P4"
    LevelP5 Level = "P5"
)

type Doc struct {
    Title       string    `yaml:"title" json:"title"`
    Description string    `yaml:"description" json:"description"`
    Date        time.Time `yaml:"date" json:"date"`
    Permalink   string    `yaml:"permalink" json:"permalink"`
    Slug        string    `yaml:"slug" json:"slug"`
    Level       Level     `yaml:"level" json:"level"`
    Series      *string   `yaml:"series" json:"series"`
    Tags        []string  `yaml:"tags" json:"tags"`
    Content     string    `json:"content"`
}

Series 用了 *string 而不是 string，因为文章可能不属于任何系列。用指针后，nil 表示没有系列，JSON 序列化时自动忽略，区分”空值”和”不存在”。

6.2 ContentSetter 接口

// internal/domain/content.go
package domain

type ContentSetter interface {
    SetSlug(slug string)
    SetContent(content string)
}

func (d *Doc) SetSlug(slug string) {
    d.Slug = slug
}

func (d *Doc) SetContent(content string) {
    d.Content = content
}

ParseMarkdown 需要同时支持 Doc 和 About 两种类型。如果为每个类型单独写解析函数，代码会重复。但用接口，只需要定义”你能设置 Content 和 Slug”这个能力，任何类型只要实现了这两个方法，就能被 ParseMarkdown 处理。

七、核心解析逻辑

7.1 文件格式

---
title: Go 后端开发实践
description: 从 Markdown 到内存的完整方案
date: 2026-07-10
permalink: 760e47b3-05bc-4ad6-9d43-ad95426b8127
level: P3
tags:
  - Go
  - Markdown
---
# 正文内容

7.2 解析函数

// internal/loader/parse.go
package loader

import (
    "fmt"
    "os"
    "path/filepath"
    "strings"

    "gopkg.in/yaml.v3"
)

func ParseMarkdown[T any](filePath string) (T, error) {
    var result T

    // 1. 读取文件
    data, err := os.ReadFile(filePath)
    if err != nil {
        return result, fmt.Errorf("读取失败: %w", err)
    }

    // 2. 分割 Frontmatter
    parts := strings.SplitN(string(data), "---", 3)
    if len(parts) < 3 {
        return result, fmt.Errorf("无效格式: %s", filePath)
    }
    frontmatter := parts[1]
    body := parts[2]

    // 3. 解析 YAML
    err = yaml.Unmarshal([]byte(frontmatter), &result)
    if err != nil {
        return result, fmt.Errorf("解析 frontmatter 失败: %w", err)
    }

    // 4. 提取文件名作为 Slug
    baseName := filepath.Base(filePath)
    slug := strings.TrimSuffix(baseName, filepath.Ext(baseName))

    // 5. 转换 Markdown 为 HTML
    htmlContent := mdToHTML(body)

    // 6. 通过接口设置 Content 和 Slug
    if setter, ok := any(&result).(ContentSetter); ok {
        setter.SetSlug(slug)
        setter.SetContent(htmlContent)
    }

    return result, nil
}

7.3 Markdown → HTML

// internal/loader/html.go
func mdToHTML(body string) string {
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse([]byte(body))

    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    renderer := html.NewRenderer(html.RendererOptions{Flags: htmlFlags})

    return string(markdown.Render(doc, renderer))
}

八、加载与内存存储

8.1 Store 结构

// internal/loader/load.go
type Store struct {
    Docs  map[string]*domain.Doc
    About map[string]*domain.About
}

func LoadAll(contentDir string) (*Store, error) {
    store := &Store{
        Docs:  make(map[string]*domain.Doc),
        About: make(map[string]*domain.About),
    }

    docsPath := filepath.Join(contentDir, "docs")
    if err := loadDocs(docsPath, store); err != nil {
        return nil, fmt.Errorf("加载 docs 失败: %w", err)
    }

    aboutPath := filepath.Join(contentDir, "about")
    if err := loadAbout(aboutPath, store); err != nil {
        return nil, fmt.Errorf("加载 about 失败: %w", err)
    }

    return store, nil
}

8.2 批量加载

func loadDocs(dir string, store *Store) error {
    files, err := filepath.Glob(filepath.Join(dir, "*.md"))
    if err != nil {
        return err
    }

    for _, file := range files {
        doc, err := ParseMarkdown[domain.Doc](file)
        if err != nil {
            fmt.Printf("⚠️ 跳过 %s: %v\n", file, err)
            continue
        }
        store.Docs[doc.Permalink] = &doc
    }

    return nil
}

单个文件解析失败时，跳过它继续处理其他文件，而不是直接退出。这样即使有某篇文章格式有问题，整个服务仍然可以启动。

九、我在写这段代码时真正理解的事

9.1 接口是能力验证

之前看 Go 的接口总觉得抽象——”方法集合”、”隐式实现”这些概念在文档里看懂了，但没有实感。

直到写了这行代码：

if setter, ok := any(&result).(ContentSetter); ok {
    setter.SetSlug(slug)
    setter.SetContent(htmlContent)
}

我才真正理解：接口是用来验证”你有没有这个能力”的。

ParseMarkdown 不关心传入的是什么类型。它只问一个问题：”你能设置 Content 和 Slug 吗？能的话，我就帮你设置。”

这就是 Go 接口的精髓。

9.2 指针的选择

store.Docs[doc.Permalink] = &doc

用指针还是值？这个问题困扰了我很久。通过这个项目我发现，存指针不仅节省内存，更重要的是多个地方可以共享同一份数据。

Series 用了 *string 而不是 string，也是同样的道理——需要区分”没有系列”和”系列名为空”。

9.3 泛型让代码更干净

func ParseMarkdown[T any](filePath string) (T, error)

没有泛型的话，我要么为 Doc 和 About 各写一个解析函数（代码重复），要么用 interface{} 然后到处做类型断言（不优雅且不安全）。泛型让代码既安全又简洁。

十、提供 HTTP API

// internal/api/docs.go
type DocsHandler struct {
    Store map[string]*domain.Doc
}

func (h *DocsHandler) GetDocs(c *gin.Context) {
    docs := make([]*domain.Doc, 0, len(h.Store))
    for _, doc := range h.Store {
        docs = append(docs, doc)
    }

    sort.Slice(docs, func(i, j int) bool {
        return docs[i].Date.After(docs[j].Date)
    })

    c.JSON(http.StatusOK, docs)
}

func (h *DocsHandler) GetDoc(c *gin.Context) {
    permalink := c.Param("permalink")
    doc, ok := h.Store[permalink]
    if !ok {
        c.JSON(http.StatusNotFound, gin.H{"error": "文章不存在"})
        return
    }
    c.JSON(http.StatusOK, doc)
}

// cmd/server/main.go
func main() {
    store, err := loader.LoadAll("content/")
    if err != nil {
        log.Fatal("加载内容失败:", err)
    }

    log.Printf("✅ 加载完成: %d 篇文章\n", len(store.Docs))

    docsHandler := api.NewDocsHandler(store.Docs)

    r := gin.Default()
    r.GET("/api/docs", docsHandler.GetDocs)
    r.GET("/api/docs/:permalink", docsHandler.GetDoc)

    r.Run(":8080")
}

十一、这个项目的运行数据

📊 运行数据
├── 文章数量: 39 篇
├── 总大小: 582KB
├── 加载耗时: < 50ms
├── 内存占用: < 5MB
├── API 响应: < 20ms
├── 部署时间: ~10 秒（仅同步文件）
└── 核心代码: ~200 行（完整项目 ~400-500 行）

十二、给想用项目学 Go 的人

如果你也在学一门新语言，我建议你：

从自己最熟悉的领域开始。

我写过很多年前端，对 Markdown 文件的格式、结构、内容组织非常熟悉。选择”用 Go 读取 Markdown 文件并提供 API”作为第一个项目，是因为这个场景我足够了解，不会因为业务本身的复杂性分散学习的注意力。

适合作为 Go 实战练手的场景：

• 用 Go 写一个 Markdown 文档 API 服务（本文的场景）
• 用 Go 写一个静态站点生成器
• 用 Go 写一个 RSS 订阅聚合器
• 用 Go 写一个 JSON 到 CSV 的转换工具
• 用 Go 写一个日志收集和查询服务

核心原则：从小处着手，让项目驱动学习。 一个能跑起来、能解决问题的小项目，比看 10 本教程都管用。

十三、结语

这是一个很小的项目。39 篇文章，200 行核心代码，一个简单的 API 服务。

但它对我的意义远远超过代码本身。

这是我第一个真正意义上的 Go 项目——不是教程里的 demo，不是 fork 下来的例子，而是为了解决真实问题，从零到一写出来的东西。

技术从来都是在实践中学会的。

如果你也想学 Go，别只停留在看文档、敲 demo 的阶段。找一个你熟悉的小场景，用 Go 写一个能跑起来的东西。不用多复杂，能把事情做成，就已经是最好的学习。

🎯

附：完整项目结构

moongate-api/
├── cmd/
│   └── server/
│       └── main.go          # 程序入口
├── internal/
│   ├── domain/              # 领域模型
│   │   ├── doc.go           # Doc 结构体
│   │   ├── about.go         # About 结构体
│   │   └── content.go       # ContentSetter 接口
│   ├── api/                 # HTTP Handler
│   │   ├── docs.go          # 文章 API
│   │   └── about.go         # 关于页面 API
│   └── loader/              # 数据加载
│       ├── load.go          # 批量加载
│       ├── parse.go         # 单文件解析
│       └── html.go          # Markdown → HTML
├── content/                 # Markdown 内容
│   ├── docs/                # 技术文章
│   └── about/               # 关于页面
├── go.mod
└── go.sum

• 已掌握 Go 基础语法
• 想学 GORM 但不知道从哪开始
• 想看到一个能直接运行的完整项目

完整项目结构

gin-demo/
├── main.go           # 入口文件
├── db/
│   └── db.go         # 数据库连接
├── models/
│   └── book.go       # 数据模型
├── handlers/
│   └── book.go       # 业务逻辑（CRUD）
└── go.mod

第一章：项目初始化

目标： 创建项目目录，安装依赖。

mkdir gin-demo
cd gin-demo
go mod init gin-demo

安装依赖：

# Web 框架
go get -u github.com/gin-gonic/gin

# ORM 库 + PostgreSQL 驱动
go get -u gorm.io/gorm
go get -u gorm.io/driver/postgres

数据库驱动说明：

本文使用 PostgreSQL 作为示例数据库。如果你使用的是其他数据库，替换对应的驱动即可：

Gin 负责处理 HTTP 请求和路由，GORM 负责数据库操作，两者各司其职，缺一不可。后续所有代码都依赖这两个库。

第二章：连接数据库

目标： 建立数据库连接，在项目启动时初始化。

连接流程：

1. main.go 启动时调用 db.InitDB()
2. db.InitDB() 构造 DSN 字符串，通过 gorm.Open() 建立连接
3. 连接成功返回 *gorm.DB 实例，失败则退出程序

创建 db/db.go：

package db

import (
    "fmt"
    "log"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

var DB *gorm.DB

func InitDB() {
    host := "localhost"
    port := 5432
    user := "postgres"
    password := "123456"
    dbname := "books"

    dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
        host, port, user, password, dbname)

    var err error
    DB, err = gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal("数据库连接失败：", err)
    }
    log.Println("数据库连接成功")
}

代码说明：

DSN 参数说明：

注意事项：

• PostgreSQL 需要手动创建数据库：CREATE DATABASE books;
• GORM 的 AutoMigrate 能自动创建表，但不能自动创建数据库
• sslmode=disable 仅用于本地开发，生产环境应开启 SSL

第三章：定义数据模型

目标： 用 Go 结构体定义数据库表结构。

创建 models/book.go：

package models

import "gorm.io/gorm"

type Book struct {
    gorm.Model
    Title  string  `json:"title" gorm:"not null"`
    Author string  `json:"author" gorm:"not null"`
    Price  float64 `json:"price"`
}

字段说明：

• gorm.Model：内置了 ID、CreatedAt、UpdatedAt、DeletedAt 四个字段
• gorm:"not null"：对应数据库的 NOT NULL 约束
• json:"title"：指定 JSON 序列化时的字段名

第四章：自动迁移

目标： 程序启动时自动创建或更新表结构。

在 main.go 中添加：

package main

import (
    "log"
    "gin-demo/db"
    "gin-demo/models"
    "github.com/gin-gonic/gin"
)

func main() {
    // 1. 连接数据库
    db.InitDB()

    // 2. 自动迁移（建表）
    if err := db.DB.AutoMigrate(&models.Book{}); err != nil {
        log.Fatal("迁移失败：", err)
    }

    // 3. 启动 Gin 服务
    r := gin.Default()
    // ... 路由
    r.Run(":8080")
}

注意事项：

• AutoMigrate 只会创建不存在的表，不会删除已有字段
• 字段类型变更时，GORM 不会自动修改已有字段类型

第五章：创建图书

目标： 实现 POST /books 接口，接收 JSON 请求并存入数据库。

注： 后续第六、七、八章的所有 CRUD 函数均追加至同一个文件 handlers/book.go 中。开头统一为：

package handlers

import (
    "gin-demo/db"
    "gin-demo/models"
    "net/http"

    "github.com/gin-gonic/gin"
)

创建图书：

func CreateBook(c *gin.Context) {
    var book models.Book

    // 1. 绑定 JSON 请求体
    if err := c.ShouldBindJSON(&book); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON"})
        return
    }

    // 2. 插入数据库
    result := db.DB.Create(&book)
    if result.Error != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "创建失败"})
        return
    }

    // 3. 返回创建的数据
    c.JSON(http.StatusCreated, book)
}

测试：

curl -X POST http://localhost:8080/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Go语言实战","author":"张三","price":59.9}'

第六章：查询图书

目标： 实现查询列表和查询单条两个接口。

// 查询所有图书
func GetBooks(c *gin.Context) {
    var books []models.Book
    db.DB.Find(&books)
    c.JSON(http.StatusOK, books)
}

// 查询单条图书
func GetBook(c *gin.Context) {
    id := c.Param("id")

    var book models.Book
    result := db.DB.First(&book, id)
    if result.Error != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }

    c.JSON(http.StatusOK, book)
}

测试：

# 查询所有
curl http://localhost:8080/books

# 查询单条
curl http://localhost:8080/books/1

第七章：更新图书

目标： 实现 PUT /books/:id 接口。

func UpdateBook(c *gin.Context) {
    id := c.Param("id")

    // 1. 检查图书是否存在
    var book models.Book
    if result := db.DB.First(&book, id); result.Error != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }

    // 2. 绑定 JSON 请求体
    var input models.Book
    if err := c.ShouldBindJSON(&input); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON"})
        return
    }

    // 3. 更新字段
    db.DB.Model(&book).Updates(input)

    // 4. 返回更新后的数据
    c.JSON(http.StatusOK, book)
}

零值陷阱与进阶思考：

Updates 传入结构体时，GORM 默认会忽略零值字段（0、""、false 等）。这是设计如此，通常能满足 90% 的业务场景。但如果你确实需要将某个字段更新为 0 或 ""，有两种方案：

方案一：用 Select 强制指定字段

db.DB.Model(&book).Select("Price").Updates(input)

方案二：用 map[string]interface{}（更通用，推荐）

// 前端只传需要更新的字段，零值也能正常更新
var inputMap map[string]interface{}
if err := c.ShouldBindJSON(&inputMap); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON"})
    return
}
db.DB.Model(&book).Updates(inputMap)

方案二的优势在于：前端传什么就更新什么，不会因为零值问题导致意外行为，且在字段较多的场景下更灵活。

测试：

curl -X PUT http://localhost:8080/books/1 \
  -H "Content-Type: application/json" \
  -d '{"price":69.9}'

第八章：删除图书

目标： 实现 DELETE /books/:id 接口。

因为 Book 使用了 gorm.Model，GORM 默认执行软删除。这意味着记录不会真正从数据库中移除，只是 deleted_at 字段被设为当前时间，查询时默认被过滤掉。

func DeleteBook(c *gin.Context) {
    id := c.Param("id")

    // 执行软删除
    result := db.DB.Delete(&models.Book{}, id)
    if result.RowsAffected == 0 {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }

    c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
}

软删除行为解析：

注意： 软删除后，默认的 First / Find 查询会自动加上 deleted_at IS NULL 条件，所以被软删除的记录不会出现在列表中。

如果需要查询已删除的记录：

db.DB.Unscoped().First(&book, id)

如果需要物理删除（彻底删除）：

func DeleteBookPermanently(c *gin.Context) {
    id := c.Param("id")
    // Unscoped() 绕过软删除，执行物理删除
    result := db.DB.Unscoped().Delete(&models.Book{}, id)
    if result.RowsAffected == 0 {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }
    c.JSON(http.StatusOK, gin.H{"message": "物理删除成功"})
}

测试：

curl -X DELETE http://localhost:8080/books/1

第九章：注册路由

目标： 把所有路由注册到 Gin 引擎。

更新 main.go：

package main

import (
    "log"
    "gin-demo/db"
    "gin-demo/handlers"
    "gin-demo/models"
    "github.com/gin-gonic/gin"
)

func main() {
    // 连接数据库
    db.InitDB()

    // 自动迁移
    if err := db.DB.AutoMigrate(&models.Book{}); err != nil {
        log.Fatal("迁移失败：", err)
    }

    r := gin.Default()

    // RESTful API 路由
    r.POST("/books", handlers.CreateBook)
    r.GET("/books", handlers.GetBooks)
    r.GET("/books/:id", handlers.GetBook)
    r.PUT("/books/:id", handlers.UpdateBook)
    r.DELETE("/books/:id", handlers.DeleteBook)

    r.Run(":8080")
}

第十章：总结

你学到的核心知识：

进阶方向：

• 关联查询：Preload、Joins
• 事务：db.Transaction()
• 查询条件：Where、Order、Limit、Offset
• 钩子函数：BeforeCreate、AfterUpdate

本文记录如何将 VitePress 文档站部署为子域名，并接入已有 docker-compose 管理的动态站点（如 Nuxt 博客），共用同一 Caddy 反向代理。

📚 系列导航

本系列共六篇，覆盖从静态网站到生产级 Docker 部署及服务集成的全流程：

1. 静态网站自动化部署（静态篇） —— 纯前端资源的自动化发布，Caddy 自动 HTTPS 和 SPA 路由支持。

2. 动态网站自动化部署（动态篇） —— 后端服务进程管理、环境变量注入、数据库迁移，结合 Caddy 反向代理。

3. Docker 极简入门（入门篇） —— 从零开始用 Docker + GitHub Actions 实现 CI/CD 流水线。

4. Docker 生产级部署（进阶篇） —— 多容器编排、健康检查、数据库迁移、自动 HTTPS，打造可靠的生产环境。

5. 自托管 Umami 分析服务与 Nuxt 4 项目集成指南（扩展篇） —— 在现有 Docker 生产环境中集成 Umami 分析服务，实现自动化数据跟踪与安全加固。

6. VitePress 文档站接入已有 Docker 基础设施：子域名部署（扩展篇） —— 将 VitePress 静态文档站作为子域名接入现有 Docker 基础设施，复用 Caddy 反向代理与网络。

📌 前置说明

本文的部署环境：

• 主站点：Nuxt 构建的个人博客（moongate.top），通过 docker-compose 管理（PostgreSQL + Nuxt + Caddy）
• 文档站：VitePress 构建的组件库文档，部署到子域名 vue.moongate.top
• 目标：将文档站容器接入现有的 Caddy 反向代理，复用同一套 Docker 网络和域名基础设施

如果你是从零开始部署（没有现有 Caddy、没有 docker-compose）：

• 本文部分内容（如网络连接）可简化
• 直接 docker run -p 80:80 即可运行

本文的核心价值在于 VitePress 静态站如何与现有 Docker 基础设施整合，而非从零搭建。

关于静态文件目录：本文沿用系列教程的自定义目录风格（/docs）。如果你习惯使用 Caddy 默认目录（/srv 或 /usr/share/caddy），可相应调整，不影响最终效果。

🎯 适用场景

• ✅ 已有 docker-compose 管理的动态站点（如 Nuxt 博客），需要将静态文档站作为子域名接入
• ✅ 希望多个站点共用同一 Caddy 反向代理和 HTTPS 证书
• ✅ 使用 Docker 部署静态网站，但不熟悉网络配置
• ✅ 遇到 pnpm 供应链安全检查报错，需要解决方案
• ✅ 需要将 VitePress 文档站接入自动化部署

📌 版本声明

🏗️ 系统架构（接入现有基础设施）

背景：本文档站部署在已有 Nuxt 博客的基础设施之上。主站点 moongate.top 由 Nuxt + PostgreSQL + Caddy 组成，通过 docker-compose 管理。文档站作为子域名 vue.moongate.top 接入同一 Caddy。 架构说明：实际运行中存在两个 Caddy：

• 网关 Caddy（docker-compose 管理）：接收外部 HTTPS 请求，反向代理到内部服务
• 文档站 Caddy（moongate-vue 容器内）：仅负责服务静态文件，监听 80 端口

由于两者在同一 Docker 网络中，网关 Caddy 通过 reverse_proxy moongate-vue:80 直接通信，无需暴露端口到宿主机。容器间通信为内网明文 HTTP（80 端口），外层 HTTPS 证书由网关 Caddy 自动托管解析。

┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 本地开发 │────▶│ GitHub Actions │────▶│ 阿里云 ACR │
│ git push │ │ 自动构建镜像 │ │ 镜像仓库 │
└─────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 阿里云 ECS 服务器 │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Docker 网络: my-blog_blog-network │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Caddy │ │ Nuxt 应用 │ │ PostgreSQL │ │ │
│ │ │ (网关代理) │◀──▶│ (博客) │◀──▶│ (数据库) │ │ │
│ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │
│ │ │ ┌─────────────────────────────────────────┐ │ │
│ │ └──│ moongate-vue │ │ │
│ │ │ (VitePress + 内部 Caddy 静态服务) │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

🔄 与动态应用的核心差异

🐳 第一步：Dockerfile 编写

VitePress 是静态站点生成器，构建后输出纯静态文件。因此 Dockerfile 分为两个阶段：

# ==================== 构建阶段 ====================
FROM node:24-alpine AS builder

WORKDIR /app

# 安装 git（VitePress 1.x 需要 git 来获取最后更新时间）
RUN apk add --no-cache git

# 安装 pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

# 复制依赖文件
COPY package.json pnpm-lock.yaml ./

# ⚠️ 关键点：使用 --ignore-scripts 跳过 pnpm 的供应链安全检查
# 否则会触发 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION
RUN pnpm install --frozen-lockfile --ignore-scripts

# 复制源代码并构建
COPY . .
RUN pnpm docs:build

# ==================== 运行阶段 ====================
FROM caddy:alpine

# 复制构建产物到自定义目录 /docs
# 注意：需要在 Caddyfile 中通过 root * /docs 指定根目录
COPY --from=builder /app/docs/.vitepress/dist /docs

EXPOSE 80

⚠️ 关键踩坑点

1. Git 依赖

VitePress 1.x 的默认主题会调用 git 命令获取文件的最后更新时间。如果容器中没有 git，构建会报错：

[vitepress] spawn git ENOENT

解决方案：在构建阶段安装 git：

RUN apk add --no-cache git

2. pnpm 供应链安全检查

pnpm 10.x 默认启用供应链安全检查，拦截发布时间 < 24 小时的包：

[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] @types/node@25.9.2 was published ... within the minimumReleaseAge cutoff
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.21.5, vitepress-theme-demoblock@3.1.3

解决方案：使用 --ignore-scripts 参数跳过检查：

RUN pnpm install --frozen-lockfile --ignore-scripts

3. 文件权限

Caddy 官方镜像默认以 caddy 非 root 用户运行（安全考虑）。如果构建产物权限不正确，容器启动后 Caddy 可能无法读取静态文件，导致 403 Forbidden。

解决方案：在 Caddyfile 中确保 root 目录可读，或使用 --chown 参数：

COPY --from=builder --chown=caddy:caddy /app/docs/.vitepress/dist /docs

如果你使用自定义目录 /docs，也可以在 Caddyfile 中正常配置 root * /docs，Caddy 会自动处理权限。

🚀 第二步：GitHub Actions 工作流

name: Deploy Docs To Aliyun

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "package.json"
      - "pnpm-lock.yaml"
      - "Dockerfile"
      - ".github/workflows/deploy-docs.yml"

jobs:
  ci:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Aliyun ACR
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.ACR_REGISTRY }}
          username: ${{ secrets.ACR_USERNAME }}
          password: ${{ secrets.ACR_PASSWORD }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: Dockerfile
          push: true
          tags: |
            ${{ secrets.ACR_REGISTRY }}/moongate/moongate-vue:latest
            ${{ secrets.ACR_REGISTRY }}/moongate/moongate-vue:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Deploy to Server via SSH
        uses: appleboy/ssh-action@v1.0.0
        env:
          ACR_REGISTRY: ${{ secrets.ACR_REGISTRY }}
          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          envs: ACR_REGISTRY, ACR_USERNAME, ACR_PASSWORD
          script: |
            set -e

            # 登录 ACR
            echo "$ACR_PASSWORD" | docker login "$ACR_REGISTRY" -u "$ACR_USERNAME" --password-stdin

            # 拉取最新镜像
            docker pull $ACR_REGISTRY/moongate/moongate-vue:latest

            # 强制删除旧容器（避免容器挂起导致的死锁）
            docker rm -f moongate-vue || true

            # 运行新容器（连接到博客的 Docker 网络）
            docker run -d \
              --name moongate-vue \
              --restart unless-stopped \
              --network my-blog_blog-network \
              $ACR_REGISTRY/moongate/moongate-vue:latest

            # 清理旧镜像
            docker image prune -f --filter "until=24h"

与动态应用 workflow 的差异

🌐 第三步：服务器端配置

3.1 首次部署：运行容器并连接网络

# 拉取镜像
docker pull crpi-xxx/moongate/moongate-vue:latest

# 运行容器（加入博客的网络）
docker run -d \
  --name moongate-vue \
  --restart unless-stopped \
  --network my-blog_blog-network \
  crpi-xxx/moongate/moongate-vue:latest

注意：不需要 -p 端口映射。Caddy 通过 Docker 内部网络直接访问容器，不经过宿主机端口。

3.2 Caddyfile 配置

在 /var/www/my-site/Caddyfile 中添加子域名配置，并指定静态文件根目录：

# 组件库文档站
vue.moongate.top {
    reverse_proxy moongate-vue:80
    encode gzip zstd
}

# 可选：添加 www 重定向
www.vue.moongate.top {
    redir https://vue.moongate.top{uri} permanent
}

说明：

• 网关 Caddy 只负责反向代理，不负责静态文件服务
• 静态文件服务由文档站容器内的 Caddy 负责
• 容器间通信使用内网 HTTP，HTTPS 证书由网关 Caddy 统一托管

3.3 重启网关 Caddy

cd /var/www/my-site
docker compose restart caddy

3.4 验证网络连接

# 查看容器网络
docker inspect moongate-vue | grep -A5 "Networks"

# 从网关 Caddy 容器测试连接
docker exec my-blog-caddy wget -qO- http://moongate-vue:80 | head -5

🌍 第四步：DNS 配置

在阿里云 DNS 控制台添加 A 记录：

等待 DNS 生效后，访问 https://vue.moongate.top 即可看到文档站。

🔧 第五步：完整配置清单

GitHub Secrets

服务器端命令速查

# 首次部署：运行容器并连接网络
docker run -d \
  --name moongate-vue \
  --restart unless-stopped \
  --network my-blog_blog-network \
  crpi-xxx/moongate/moongate-vue:latest

# 常用运维命令
docker logs moongate-vue          # 查看日志
docker restart moongate-vue       # 重启容器
docker stop moongate-vue          # 停止容器
docker start moongate-vue         # 启动容器
docker rm -f moongate-vue          # 强制删除容器

# 网络管理
docker network connect my-blog_blog-network moongate-vue  # 连接网络
docker network disconnect my-blog_blog-network moongate-vue  # 断开网络

🐛 踩坑记录

📈 部署流程图

┌─────────────────────────────────────────────────────────────────────┐
│                           开发者本地                                 │
│  $ git add docs/                                                     │
│  $ git commit -m "update docs"                                       │
│  $ git push origin main                                              │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        GitHub Actions                                │
│  1. 检出代码                                                         │
│  2. 安装 pnpm、依赖                                                   │
│  3. 执行 pnpm docs:build                                             │
│  4. 构建 Docker 镜像                                                 │
│  5. 推送到阿里云 ACR                                                  │
│  6. SSH 到服务器                                                      │
│  7. docker pull && docker rm -f && docker run --network ...         │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          阿里云 ECS                                   │
│  1. 拉取最新镜像                                                      │
│  2. 强制删除旧容器                                                    │
│  3. 启动新容器（加入博客网络）                                         │
│  4. 网关 Caddy 代理 vue.moongate.top → moongate-vue:80               │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                           用户访问                                    │
│                    https://vue.moongate.top                          │
└─────────────────────────────────────────────────────────────────────┘

📊 与动态应用部署的优劣对比

🎉 总结

VitePress 文档站接入已有 Docker 基础设施的关键步骤：

1. Dockerfile：使用多阶段构建 + Caddy 静态服务器，注意：
   • git 依赖（VitePress 需要）
   • pnpm 供应链安全检查（--ignore-scripts）
   • 文件权限（可选 --chown=caddy:caddy）
2. 镜像推送：推送到阿里云 ACR，利用 GitHub Actions 缓存加速
3. 容器部署：使用 docker rm -f 强制替换，--network 接入现有网络
4. Caddy 代理：在网关 Caddyfile 中添加子域名配置，指定 root * /docs
5. DNS 解析：为子域名添加 A 记录

架构亮点：

• 双 Caddy 架构：网关 Caddy 处理 HTTPS 和路由，容器内 Caddy 仅服务静态文件
• 内网通信：容器间通过 Docker 内部网络通信，无需暴露端口到宿主机
• 统一证书管理：HTTPS 证书由网关 Caddy 统一托管，子域名自动继承
• 系列风格统一：沿用自定义目录 /docs，与之前教程保持一致

与动态应用不同，静态站部署更简单、资源占用更少。本文完整记录了接入已有 Docker 基础设施的全过程，这套流程同样适用于任何静态站点生成器（如 Hexo、Hugo、Astro 等），只需调整构建命令和静态文件输出目录即可。

本文基于 vitepress-theme-demoblock@3.x 版本，详细解释每一步的作用和背后的原理。

背景

为 Vue 3 组件库搭建文档站，需要支持：

• 组件实时预览
• 代码展示 + 折叠
• 一键复制代码

官方推荐 vitepress-theme-demoblock，但配置过程中发现：官方文档虽然写全了步骤，但没有解释「为什么」，导致容易踩坑。

本文补充官方缺失的「连接逻辑」。

官方文档写了什么

根据官方文档，配置步骤如下：

1. 安装

pnpm add -D vitepress-theme-demoblock

2. 配置 config.ts

import {
  demoblockPlugin,
  demoblockVitePlugin,
} from "vitepress-theme-demoblock";

export default {
  markdown: {
    config: (md) => {
      md.use(demoblockPlugin);
    },
  },
  vite: {
    plugins: [demoblockVitePlugin()],
  },
};

3. 配置主题

import DefaultTheme from "vitepress/theme";
import "vitepress-theme-demoblock/dist/theme/styles/index.css";
import { useComponents } from "./useComponents"; // ← 从本地导入

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx);
    useComponents(ctx.app);
  },
};

4. 添加脚本

{
  "scripts": {
    "docs:dev": "yarn run register:components && vitepress dev docs",
    "register:components": "vitepress-rc"
  }
}

官方没说的是什么

问题一：useComponents 从哪来？

官方写的是 import { useComponents } from './useComponents'，但：

• 项目中一开始并没有这个文件
• 官方没说明这个文件是生成的

答案：vitepress-rc 命令会生成这个文件。

问题二：vitepress-rc 是做什么的？

官方只是列出了一个命令，没说明作用。

答案：vitepress-rc 会：

1. 扫描你的组件目录（默认读取 docs/.vitepress/components 或项目根目录的 components.json）
2. 自动注册 demoblock 需要的 Vue 组件
3. 生成 .vitepress/theme/useComponents.ts 文件

注意：如果你的组件库在 src/components 目录下，需要配置 vitepress-rc 的扫描路径，否则会生成空文件。

问题三：为什么要先运行 register:components？

官方脚本写了 && vitepress dev docs，但没解释为什么要先运行。

答案：因为 VitePress 启动时需要读取 ./useComponents.ts，而这个文件必须先由 vitepress-rc 生成。

问题四：不运行会怎样？

直接运行 vitepress dev docs 会报错：

Uncaught SyntaxError: Cannot find module './useComponents'

完整配置流程（含解释）

第一步：安装依赖

pnpm add -D vitepress vitepress-theme-demoblock

第二步：配置 config.ts

// docs/.vitepress/config.ts
import { defineConfig } from "vitepress";
import {
  demoblockPlugin,
  demoblockVitePlugin,
} from "vitepress-theme-demoblock";

export default defineConfig({
  title: "My UI",
  description: "Vue 3 组件库",

  markdown: {
    config: (md) => {
      md.use(demoblockPlugin); // Markdown-it 插件：解析 :::demo 语法
    },
  },

  vite: {
    plugins: [demoblockVitePlugin()], // Vite 插件：编译 demo 中的 Vue 组件
  },
});

💡 原理解析：两个插件的分工

• demoblockPlugin（Markdown-it 插件）：负责「偷梁换柱」。把 Markdown 里的 :::demo 语法转换成自定义的 <demo-block> 标签，将代码作为字符串和实时运行的组件传入。
• demoblockVitePlugin（Vite 插件）：负责「降维打击」。在编译阶段把抽离出来的虚拟 Vue 代码真正编译成浏览器可执行的 JS/Vue 组件。

第三步：配置主题

// docs/.vitepress/theme/index.ts
import DefaultTheme from "vitepress/theme";
import "vitepress-theme-demoblock/dist/theme/styles/index.css";
// 注意：从本地导入，不是从包导入
import { useComponents } from "./useComponents";

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx);
    useComponents(ctx.app); // 注册 demoblock 组件
  },
};

第四步：添加脚本

{
  "scripts": {
    "docs:dev": "pnpm run register:components && vitepress dev docs",
    "docs:build": "pnpm run register:components && vitepress build docs",
    "register:components": "vitepress-rc"
  }
}

脚本说明：

第五步：首次运行

pnpm docs:dev

执行过程：

1. 运行 vitepress-rc → 生成 useComponents.ts
2. 启动 VitePress → 读取生成的 useComponents.ts
3. 文档站正常运行

第六步：编写文档

v3 正确写法（不支持 :::demo 后面加描述文字）：

## 基础用法

这是按钮的基础用法描述。（直接写在 `:::demo` 上方）

:::demo
\`\`\`vue
<template>
<Button type="primary">主要按钮</Button>
</template>

<script setup>
import { Button } from 'my-ui'
</script>

\`\`\`
:::

官方文档 vs 本文补充

常见问题

Q1：vitepress-rc 生成的文件要提交到 Git 吗？

建议：提交 useComponents.ts，忽略 cache/

# .gitignore
docs/.vitepress/cache/
# 注意：不要忽略 useComponents.ts

理由：

• useComponents.ts 内容稳定（只在组件列表变化时改变），体积很小（几 KB）
• 提交后团队成员 git clone 即可直接运行 pnpm docs:dev，无需额外生成
• CI/CD 构建时也不需要重新运行 vitepress-rc，减少构建步骤

如果不提交：可以使用 prepare 钩子在 pnpm install 时自动生成：

{
  "scripts": {
    "prepare": "pnpm run register:components"
  }
}

但需要注意每次 install 都会重新生成，cache/deps 也会更新，可能导致 Git 状态变化。

Q2：更新依赖后需要重新运行吗？

建议重新运行一次：

pnpm run register:components

Q3：:::demo 后面的描述文字不生效？

3.x 版本不支持描述文字：

平替方案：在 :::demo 上方直接写标准 Markdown 文本即可。

### 基础用法

这是按钮的基础用法描述。

:::demo
\`\`\`vue
<template>
<Button type="primary">主要按钮</Button>
</template>
\`\`\`
:::

Q4：vitepress-rc 扫描不到我的组件怎么办？

vitepress-rc 默认读取 docs/.vitepress/components 目录或项目根目录的 components.json 配置。

如果你的组件库在 src/components 目录下，有两种解决方案：

方案 A：创建软链接

mkdir -p docs/.vitepress/components
ln -s ../../../src/components docs/.vitepress/components/ui

方案 B：创建 components.json

{
  "componentsDir": "./src/components"
}

总结

官方文档信息是全的，但问题是缺少「连接逻辑」：

• 写了 import from './useComponents'，没写这个文件从哪来
• 写了 vitepress-rc 命令，没写它的作用
• 写了 && 串联命令，没写为什么要先执行

核心要点：

1. vitepress-rc 会生成 useComponents.ts 文件
2. 必须先运行 vitepress-rc，再启动 VitePress
3. 3.x 版本不支持 :::demo 后面的描述文字，需要用普通 Markdown 代替
4. 从本地导入 useComponents，不是从包导入
5. demoblockPlugin（Markdown-it）负责解析语法，demoblockVitePlugin（Vite）负责编译组件

希望这篇文章能帮你理解 demoblock 的配置原理，少踩坑。

记录 moongate-vue 组件库从构建到发布的完整流程，以及 2FA 验证、网络代理解密、npm 源自动化管理等实战经验。

📚 系列导航

本系列共五篇，覆盖从设计令牌到 npm 发布的 Vue 3 组件库开发全流程：

1. 设计令牌 vs 原子化 CSS：失败整合与融合之道（理念篇） —— 用 UnoCSS 映射设计令牌的失败经历，量化对比后得出设计令牌优先的结论。

2. CSS 优先 + 组件薄封装：一个 25KB 组件库的极简实践（架构篇） —— 四层 CSS 架构、极简 Vue 组件、Vite 多入口构建、体积预算验证，单组件极简实现。

3. Vue 3 简单组件开发实战：从 Button 组件看 API 设计（简单组件篇） —— Props 定义、变体系统、尺寸取舍、插槽设计、状态管理、无障碍支持及与主流 UI 库对比。

4. Vue 3 复杂组件开发实战：Select 与 Pagination 的 API 设计（复杂组件篇） —— 数据格式适配、类型回溯、可搜索/多选、ARIA 键盘导航、组合式函数抽离及 SSR 适配，揭示工业级细节。

5. 从代码到 npm：Vue 3 组件库发布实战与避坑指南（发布篇） —— nrm 源管理、2FA 配置、WebAuthn 网络代理避坑、本地链接测试、自动化脚本及工业级发布检查清单。

一、引言

组件库开发完成后，最后一步也是至关重要的一步：发布到 npm。这个过程看似简单，实则暗藏不少现代工程包袱：包名冲突、2FA 强校验、安全密钥（WebAuthn）在特定网络下的卡死、源镜像频繁切换……以及——构建产物的正确性。

本文作为系列收官之作，记录了我从 v0.0.1 一路到 v1.5.0 的发布实战。

二、发布前的准备

2.1 构建与验证链路（v1.5.0 实际）

v1.5.0 的 build 脚本是一条自动化验证流水线：

# package.json scripts
"build": "pnpm run clean && vite build && pnpm run build:types && pnpm run clean:dts && pnpm run copy:reset && pnpm run verify:build && pnpm run check:size",
"prepublishOnly": "pnpm build && pnpm test"

每一步的职责：

verify-build.js 的核心逻辑——防止漏发布某个组件入口：

// 每个组件：dist/<kebab>.js 存在 + dist/exports/<Name>.d.ts 存在 + 导出名正确
for (const [componentName, kebabName] of Object.entries(componentEntries)) {
  const jsPath = join(distDir, `${kebabName}.js`)
  const dtsPath = join(distDir, 'exports', `${componentName}.d.ts`)
  if (!existsSync(jsPath)) {
    errors.push(`缺少组件产物: ${kebabName}.js`)
  }
  // 任一错误 → process.exit(1) 阻止发布
}

2.2 分发契约（package.json）

{
  "name": "moongate-vue",
  "version": "1.5.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    },
    "./style.css": "./dist/style.css",
    "./reset.css": "./dist/reset.css",
    "./button": {
      "types": "./dist/exports/Button.d.ts",
      "import": "./dist/button.js",
      "default": "./dist/button.js"
    }
    // ... 27 个组件入口
  },
  "files": ["dist"],
  "sideEffects": ["*.css"],
  "peerDependencies": {
    "vue": "^3.5.0"
  }
}

关键差异（vs 初版）：

• 纯 ES Module：只有 .js，没有 .cjs——这是刻意选择（现代打包工具均支持 ESM，且 exports 中有 import 条件即可）
• 27 个按需导出入口：用户可 import Button from 'moongate-vue/button' 只加载所需组件
• peerDependencies 升到 ^3.5.0：因为用了 useId()（Vue 3.5+ API）
• sideEffects: ["*.css"]：防止打包器 tree-shake 误删 CSS

💡 包体积防御提示：files 字段是”白名单”。配置 ["dist"] 后，npm 只上传 dist 目录。package.json、README.md、LICENSE 会被 npm 强制包含。

2.3 使用 nrm 管理 npm 源

发布到 npm 必须使用官方源。如果你之前为了加速下载切换到了国内镜像，推荐使用 nrm。

npm install -g nrm
nrm ls
nrm use npm        # 发布时切换到官方源
nrm current

提示：国内淘宝 npm 镜像已迁移至 https://registry.npmmirror.com。

2.4 本地集成测试

在发布到 npm 之前，最好在真实项目中先测试一遍：

# 1. 在组件库目录：构建 + 全局链接
pnpm build
pnpm link --global

# 2. 在测试项目目录：链接本地组件库
pnpm link /home/dark/projects/moongate-vue

测试清单：

• [ ] 组件能正常渲染
• [ ] 样式文件导入生效（import 'moongate-vue/style.css'）
• [ ] 按需入口生效（import Button from 'moongate-vue/button'）
• [ ] TypeScript 类型提示正常
• [ ] HMR 热更新工作正常

注意：测试完成后，删除链接需：pnpm remove moongate-vue + 手动清理 link: 条目。

三、攻克双重认证（2FA）泥潭

npm 强制要求发布时开启双重认证。npm 已全面拥抱 安全密钥 (WebAuthn) 模式。

3.1 浏览器选择与网络环境的”隐藏陷阱”

⚠️ 工业级避坑警告：npm 的 WebAuthn 验证会尝试与 Google 验证服务联动。在国内网络环境下，使用 Chrome/Edge 弹出密钥窗口时极易由于网络超时而无响应或报错。

3.2 CI/CD 备选：Granular Access Token

//registry.npmjs.org/:_authToken=你的_granular_token_值

权限勾选 Read and Write，并勾选 “Bypass two-factor authentication for automation”。

四、标准化发布流程

4.1 手动发布步骤

1. nrm use npm
2. npm login（浏览器完成 2FA）
3. npm version patch|minor|major（注意 --no-git-tag-version 可选）
4. npm publish --access public

作用域包必须加 --access public。

4.2 分步式自动化脚本

{
  "scripts": {
    "release:pre": "nrm use npm && npm run build && npm test",
    "release:version": "npm version patch --no-git-tag-version",
    "release:tag": "git add package.json && git commit -m \"chore: release v$(node -p 'require(\"./package.json\").version')\" && git tag v$(node -p 'require(\"./package.json\").version')",
    "release:publish": "npm publish --access public",
    "release": "npm run release:pre && npm run release:version && npm run release:tag && npm run release:publish"
  }
}

五、发布前最终检查清单

• [ ] 构建无误：pnpm run build 未报错（含 verify-build + check:size）
• [ ] 产物完整：dist/ 有 index.js、27 个组件 .js、style.css、reset.css、index.d.ts
• [ ] 体积达标：Min+Gzip ≤ 25KB（tree-shake-check.js 输出确认）
• [ ] 测试通过：pnpm test（450 个测试全绿）
• [ ] 版本干净：当前版本号从未在 npm 上存在过
• [ ] 本地沙盒：样式 + 按需入口 + 类型均正常
• [ ] peerDependencies 正确：vue ^3.5.0

六、FAQ

Q1: 发布返回 403/404？

403 = 包名被占用 或 未登录。404 = 忘了 nrm use npm 发布到只读镜像。

Q2: 2FA 弹不出安全密钥窗口？

确认代理开启全局/TUN 模式。仍失败则用 Granular Access Token。

Q3: 用户安装后样式白屏？

确认 sideEffects: ["*.css"] 已配置，且用户显式 import 'moongate-vue/style.css'。

Q4: 用户能 import ‘moongate-vue’ 但 import ‘moongate-vue/button’ 失败？

检查 exports 中是否声明了 /button 子路径。v1.5.0 已为 27 个组件全部配置。

七、结语

从第一篇的设计令牌，到薄封装架构、简单/复杂组件的 API 设计，再到今天的 npm 工业级分发——五篇文章，见证了一个组件库从零到 v1.5.0 的完整工程闭环。

v1.5.0 的发布不再是简单的 npm publish，而是一条由 verify-build.js + tree-shake-check.js + 450 测试 共同守护的自动化流水线。构建产物的正确性、体积的克制、API 的稳定，是组件库生命线。

愿你的组件库也能跨越泥潭，抵达更远的远方。🚀

从数据格式适配到可搜索/多选，深入复杂组件的设计要点与逻辑复用

📚 系列导航

本系列共五篇，覆盖从设计令牌到 npm 发布的 Vue 3 组件库开发全流程：

1. 设计令牌 vs 原子化 CSS：失败整合与融合之道（理念篇） —— 用 UnoCSS 映射设计令牌的失败经历，量化对比后得出设计令牌优先的结论。

2. CSS 优先 + 组件薄封装：一个 25KB 组件库的极简实践（架构篇） —— 四层 CSS 架构、极简 Vue 组件、Vite 多入口构建、体积预算验证，单组件极简实现。

3. Vue 3 简单组件开发实战：从 Button 组件看 API 设计（简单组件篇） —— Props 定义、变体系统、尺寸取舍、插槽设计、状态管理、无障碍支持及与主流 UI 库对比。

4. Vue 3 复杂组件开发实战：Select 与 Pagination 的 API 设计（复杂组件篇） —— 数据格式适配、类型回溯、可搜索/多选、ARIA 键盘导航、组合式函数抽离及 SSR 适配，揭示工业级细节。

5. 从代码到 npm：Vue 3 组件库发布实战与避坑指南（发布篇） —— nrm 源管理、2FA 配置、WebAuthn 网络代理避坑、本地链接测试、自动化脚本及工业级发布检查清单。

一、引言

如果说写 Button 组件是在享受写 CSS 变量的”涂料之美”，那么写 Select 和 Pagination 就是在应对原生 HTML 历史包袱的”泥潭摔跤”。简单组件是单向的数据消费者，而复杂组件则是数据适配器（兼容多格式）与状态协调器（可搜索、多选、键盘导航、SSR 安全）。

本文以 Select 和 Pagination 为例，展示 v1.5.0 实际实现的复杂组件开发思路。

二、Select 下拉选择框：数据适配器

Select 组件需要接收一组选项，并允许用户选择其中一个。真实世界的 API 可能返回对象数组、字符串数组甚至数字数组，因此组件必须具备强大的数据适配能力。

2.1 需求分析

• 支持对象数组 { label, value }（默认）
• 支持自定义字段名（labelKey / valueKey）
• 支持字符串数组 ['选项A', '选项B']
• 支持数字数组 [1, 2, 3]
• 提供占位符（不可选中的默认选项）
• 支持禁用选项（disabled: true）
• 可搜索模式（filterable）：输入过滤 + 下拉面板
• 多选模式（multiple + filterable）：标签展示
• 必须解决原生 <select> 返回字符串的类型陷阱
• 完整 ARIA 键盘导航（listbox + option + aria-activedescendant）

2.2 双模式架构：原生模式 + 可搜索模式

v1.5.0 的 Select 支持双模式：

• 原生模式（默认）：渲染原生 <select>，零 JS 开销
• 可搜索模式（filterable=true）：渲染自定义输入框 + 下拉面板，支持搜索/多选/键盘导航

<!-- 原生模式：性能最优 -->
<Select v-model="category" :options="categories" />

<!-- 可搜索模式：过滤 + 下拉 -->
<Select v-model="fruit" :options="fruits" filterable />

<!-- 可搜索 + 多选 -->
<Select v-model="tags" :options="tags" filterable multiple />

2.3 API 设计与类型防腐

为了避免 any 造成类型污染，我们采用联合类型收窄：

export type SelectValue = string | number
export type SelectOption = string | number | Record<string, any>

interface Props {
  options?: SelectOption[]
  placeholder?: string
  size?: Size
  disabled?: boolean
  error?: boolean
  labelKey?: string // 默认 'label'
  valueKey?: string // 默认 'value'
  filterable?: boolean // 可搜索模式
  emptyText?: string
  maxHeight?: number // 下拉面板最大高度
  multiple?: boolean // 多选（需 filterable）
}

类型回溯解决原生 select 总是返回字符串的问题：

const handleNativeChange = (event: Event) => {
  const target = event.target as HTMLSelectElement
  const rawValue = target.value

  // 在原始 options 中找回原始类型（数字或对象值）
  const originalItem = props.options?.find(
    (item) => String(getValue(item)) === rawValue,
  )
  const finalValue = originalItem !== undefined ? getValue(originalItem) : rawValue

  modelValue.value = finalValue
  emit('change', finalValue)
}

这个逻辑保证 v-model 绑定的数字值不会意外变成字符串。

2.4 属性透传拆分

这是可搜索模式的关键细节——哪些属性透传到原生 input，哪些保留在外层 wrapper：

const attrs = useAttrs()

/** 透传到原生表单元素的 form/aria 属性 */
const formAttrs = computed(() => {
  const result: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(attrs)) {
    if (key.startsWith('aria-') || ['name', 'id', 'role', 'tabindex'].includes(key)) {
      result[key] = value
    }
  }
  return result
})

/** 保留在外层 wrapper 的其余属性（class/style/事件等） */
const wrapperAttrs = computed(() => {
  const result: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(attrs)) {
    if (!(key in formAttrs.value)) {
      result[key] = value
    }
  }
  return result
})

为什么必须拆分？如果 aria-label 留在外层 wrapper 而未透传到实际 <input>，屏幕阅读器会无法识别输入框的可访问名称——在 a11y.test.ts 的 axe-core 检查中会报 aria-input-field-name 违规。

2.5 ARIA 键盘导航（WAI-ARIA Combobox 模式）

可搜索模式的键盘导航遵循 WAI-ARIA Combobox 模式：

<!-- 下拉面板 -->
<div
  v-if="isOpen"
  ref="dropdownRef"
  class="mg-select-dropdown"
  role="listbox"
  :aria-label="listboxAriaLabel"
  :aria-activedescendant="focusedIndex >= 0 ? getOptionId(focusedIndex) : undefined"
>
  <!-- 选项 -->
  <div
    v-for="(item, index) in filteredOptions"
    :id="getOptionId(index)"
    role="option"
    :aria-selected="isSelected(item)"
    :class="{ 'mg-select-option-focused': focusedIndex === index }"
    @click="selectOption(item)"
    @mouseenter="focusedIndex = index"
  >

支持的操作： - ArrowDown / ArrowUp：移动高亮（focusedIndex），并 scrollIntoView 保持可视 - Enter：选中当前高亮选项 - Esc：关闭下拉 - 每个选项有唯一 id（基于 useId()），供 aria-activedescendant 引用

2.6 多选模式

多选（multiple + filterable）将 modelValue 变为数组：

const modelValue = defineModel<SelectValue | SelectValue[]>({ default: '' })

// 多选时：切换选中
const selectOption = (item: SelectOption) => {
  if (isOptionDisabled(item)) return
  const value = getValue(item)

  if (props.multiple) {
    const current = multipleValues.value
    const isAlreadySelected = current.some((v) => String(v) === String(value))
    const next = isAlreadySelected
      ? current.filter((v) => String(v) !== String(value))
      : [...current, value]

    modelValue.value = next
    // 多选保持下拉打开，方便连续多选
    searchText.value = ''
    focusedIndex.value = -1
    nextTick(() => inputRef.value?.focus())
    return
  }

  // 单选：选择后关闭
  modelValue.value = value
  closeDropdown()
}

多选时： - 已选项渲染为标签（tag），每个标签有 aria-label="移除 {label}" 的删除按钮 - 选择后下拉保持打开（方便连续多选） - 输入框只显示搜索文本，已选标签在外部

三、Pagination 分页组件：状态同步器

3.1 API 设计（v1.5.0 实际）

interface Props {
  totalPages: number       // 总页数（必传）
  modelValue: number       // 当前页码（v-model）
  size?: "sm" | "md" | "lg"
  showQuickJump?: boolean  // 首尾页快速跳转按钮（默认 true）
  prevText?: string        // 上一页文案（走全局 i18n）
  nextText?: string
  firstText?: string
  lastText?: string
}

Pagination 使用 defineModel<number> 绑定当前页：

const currentPage = defineModel<number>({ required: true })

3.2 快速跳转 + 页码编辑

<!-- 显示模式：可点击的数字 → 进入编辑 -->
<span v-else class="mg-pagination-current" @click="startEdit">
  {{ currentPage }}
</span>

<!-- 编辑模式：输入框 -->
<input
  v-if="isEditing"
  v-model="inputPage"
  type="number"
  :min="1"
  :max="totalPages"
  @blur="commitJump"
  @keyup.enter="commitJump"
/>

commitJump 的极端边界防御：

const commitJump = () => {
  isEditing.value = false
  const newPage = parseInt(String(inputPage.value), 10)

  // 非法输入：放弃并恢复
  if (isNaN(newPage)) {
    inputPage.value = currentPage.value
    return
  }

  goToPage(newPage) // clamp 到 [1, totalPages]
}

const goToPage = (page: number) => {
  let newPage = page
  if (newPage < 1) newPage = 1
  if (newPage > props.totalPages) newPage = props.totalPages
  if (newPage === currentPage.value) return
  currentPage.value = newPage
  emit('change', newPage)
}

3.3 全局文案（i18n）

v1.5.0 加入了全局文案系统。Pagination 的所有 aria-label 和按钮文字都走配置链：

const texts = useTexts() // 响应式全局文案

const prevTextValue = computed(() => props.prevText ?? texts.value.paginationPrev)
const pageInfoLabel = computed(() =>
  formatTemplate(texts.value.paginationPageInfo, {
    current: currentPage.value,
    total: props.totalPages,
  }),
)

优先级：组件 prop > setConfig texts > 语言内置文案。文案支持 {current}/{total} 模板占位符。

四、组合式函数抽离

复杂组件往往需要抽离共享逻辑。v1.5.0 的核心 composables：

4.1 useFormField（Input/Textarea 共享）

处理 v-model 更新 + 原生事件透传：

export function useFormField(modelValue, emit) {
  const handleInput = (event: Event) => {
    modelValue.value = (event.target as HTMLInputElement).value
    emit('input', event)
  }
  // change/focus/blur 原生事件透传
  return { handleInput, handleChange, handleBlur, handleFocus }
}

4.2 useFloating（Popover/Tooltip 共享）

自研悬浮层定位引擎：视口翻转 + 边界修正 + ResizeObserver：

export function useFloating(options: UseFloatingOptions) {
  // 延迟显示/隐藏
  // 位置计算（按方向定位 + 视口翻转）
  // 滚动/窗口尺寸变化时重新定位
  // ResizeObserver 仅监听悬浮层自身尺寸
  // SSR 安全（isBrowser 守卫）
  return { triggerRef, floatingRef, visible, currentPlacement, floatStyle, show, hide, ... }
}

4.3 useOverlayBehavior（Modal/Drawer 共享，位于 useScrollLock.ts）

滚动锁定 + ESC 关闭 + 焦点陷阱：

// composables/useScrollLock.ts
export function useOverlayBehavior(isOpen, overlayRef, onClose, options) {
  // body 滚动锁定（模块级 lockCount 计数器，多实例安全）
  // ESC 键关闭
  // Tab 焦点陷阱
}

该函数与滚动锁定逻辑（lockBodyScroll/unlockBodyScroll）一同定义在 useScrollLock.ts 中——滚动锁、ESC 关闭、焦点陷阱三者在语义上同属”浮层行为”这一关注点，因此放在同一个文件内。

模块级锁计数解决多 Modal/Drawer 同时打开的滚动锁冲突——只有最后一个关闭时才恢复 body 滚动。

五、SSR 适配：useId 与 isBrowser

v1.5.0 的 SSR 适配比初版更完善，核心是两条：

5.1 useId() 保证 hydration 安全

所有需要 id 的组件（Modal/Drawer/Select/Tabs）使用 Vue 3 的 useId()：

const selectBaseId = useId()
const getOptionId = (index: number): string => `${selectBaseId}-option-${index}`

useId() 在服务端与客户端生成一致的 ID，避免 hydration mismatch。

5.2 isBrowser 守卫

所有 DOM 操作添加浏览器环境守卫：

const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'

// 在 watch/onMounted/顶层代码中：
if (!isBrowser) return

配合 useScrollLock.ts 的模块级计数器，lockBodyScroll() 在非浏览器环境下直接跳过 DOM 操作。

5.3 createOverlay：命令式组件 SSR 安全

// composables/createOverlay.ts
export function createOverlay(component, props, containerClass) {
  if (!isBrowser) return null // SSR 返回 null
  // ...
}

六、数据与状态流向

┌─────────────────────────────────────────────────────────┐
│ 复杂组件数据流 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 外部数据 │ -> │ 数据适配器 │ -> │ 内部状态 │ │
│ │ (options) │ │ (getLabel/ │ │ (selected/ │ │
│ └─────────────┘ │ getValue) │ │ searchText) │ │
│ └─────────────┘ └──────┬──────┘ │
│ ↓ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 全局环境 │ <- │ 状态协调器 │ <- │ 用户交互 │ │
│ │ (i18n/SSR) │ │ (watch/event)│ │ (click/ │ │
│ └─────────────┘ └─────────────┘ │ keyboard) │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────┘

七、测试策略

v1.5.0 的 Select 有 40+ 测试，Pagination 有 14 测试，覆盖：

以及 SSR 检查：renderToString 确认组件在服务端不崩溃且浮层默认隐藏。

八、总结

一个优秀的复杂组件，对内要像吸尘器一样容纳各种奇葩的后端数据格式（通过 Key 映射和类型回溯），对外要像绅士一样克制地与全局环境（i18n、SSR、键盘）发生耦合。高内聚、低耦合，在这两类组件身上体现得淋漓尽致。

极简不是简陋，克制不是缺失——从 Nuxt UI v4 汲取灵感，如何设计一个好用的组件 API

📚 系列导航

本系列共五篇，覆盖从设计令牌到 npm 发布的 Vue 3 组件库开发全流程：

1. 设计令牌 vs 原子化 CSS：失败整合与融合之道（理念篇） —— 用 UnoCSS 映射设计令牌的失败经历，量化对比后得出设计令牌优先的结论。

2. CSS 优先 + 组件薄封装：一个 25KB 组件库的极简实践（架构篇） —— 四层 CSS 架构、极简 Vue 组件、Vite 多入口构建、体积预算验证，单组件极简实现。

3. Vue 3 简单组件开发实战：从 Button 组件看 API 设计（简单组件篇） —— Props 定义、变体系统、尺寸取舍、插槽设计、状态管理、无障碍支持及与主流 UI 库对比。

4. Vue 3 复杂组件开发实战：Select 与 Pagination 的 API 设计（复杂组件篇） —— 数据格式适配、类型回溯、可搜索/多选、ARIA 键盘导航、组合式函数抽离及 SSR 适配，揭示工业级细节。

5. 从代码到 npm：Vue 3 组件库发布实战与避坑指南（发布篇） —— nrm 源管理、2FA 配置、WebAuthn 网络代理避坑、本地链接测试、自动化脚本及工业级发布检查清单。

一、背景与参考

在之前的文章中，我们讨论了设计令牌优先于原子化 CSS 的理念，以及 CSS 优先 + 组件薄封装的架构。但有一个问题始终没有深入：具体到单个组件，API 到底该怎么设计？

设计初期，我深度参考了 Nuxt UI v4 的设计思路。Nuxt UI v4 将对复杂样式和交互的封装收束为 variant/color/size 几个核心维度，这正是我想要的——把复杂逻辑内聚于组件内部，对外只暴露最精简的 API。

下文以 Button 组件为例，一步步展示我的设计取舍和思考过程。本文基于 v1.5.0 的实际实现——经过多个版本迭代，Button 的 API 已经比初版更完善。

二、从需求出发：Button 需要什么？

一个按钮组件最基本的功能：

• 显示文字
• 点击触发事件
• 禁用状态
• 不同样式（主要、次要、危险等）

但只有这些够吗？我们看看实际使用场景：

<!-- 带图标的按钮 -->
<Button>
  <template #icon>🔍</template>
  搜索
</Button>

<!-- 加载状态 -->
<Button loading>提交中</Button>

<!-- 块级按钮（占满宽度） -->
<Button block>全宽按钮</Button>

<!-- 不同尺寸 -->
<Button size="sm">小号</Button>

经过分析，Button 组件在 v1.5.0 支持的需求：

三、Props 设计：类型、默认值、优先级

3.1 基础 Props

interface Props {
  label?: string // 按钮文字
  disabled?: boolean // 是否禁用
  loading?: boolean // 是否加载中
  block?: boolean // 是否为块级
  type?: "button" | "submit" | "reset" // 原生按钮类型
  showLabelWhileLoading?: boolean // 加载时是否保留文字
  loadingLabel?: string // 加载时的自定义文字
}

默认值设计：

const props = withDefaults(defineProps<Props>(), {
  label: "",
  disabled: false,
  loading: false,
  block: false,
  type: "button", // 默认 button，防止表单意外提交
  showLabelWhileLoading: false,
})

为什么默认 type="button"？这是从实际项目踩坑中学到的重要决策。如果使用原生 <button> 的默认类型 submit，当按钮放在 <form> 里时，点击会意外提交表单。将其显式默认为 button 可避免绝大多数不期望的表单行为。

3.2 变体系统：variant + color

常见的按钮类型有：主要按钮、次要按钮、边框按钮、幽灵按钮。受 Nuxt UI v4 的 variant + color 设计启发，我选择将”视觉模式”与”语义颜色”完全解耦。

type Variant = "filled" | "outline"
type Color = "primary" | "success" | "warning" | "error"

为什么只保留 filled 和 outline，删除了 ghost？

同样，颜色只保留 4 种：

3.3 尺寸设计

type Size = "sm" | "md" | "lg"

尺寸选项与 Nuxt UI v4 提供的五种尺寸（xs, sm, md, lg, xl）相比做了精简。我删除了 xs 和 xl，因为极小尺寸可以用 Badge 或其他非按钮组件替代，而个人博客里几乎碰不到超大尺寸的场景。

默认尺寸的选择：主流 UI 库（Naive UI、PrimeVue 等）的默认按钮高度约 32-34px，对应我们的 sm，因此默认尺寸设为 sm。

const props = withDefaults(defineProps<Props>(), {
  size: "sm", // 默认小号
})

3.4 图标设计：prop 与插槽共存

初版设计时，我只提供 #icon 插槽，不提供 icon prop——理由是”保持单一职责”。但实际使用中发现两个问题：

1. 简单图标（如 ✓、emoji）用插槽太啰嗦：<template #icon>✓</template> 比 icon="✓" 多了 20 个字符
2. 图标库组件（如 lucide-vue-next 的 IconHome）用插槽不够直观：需要用 <component :is="IconHome" /> 包一层

经过多版本迭代，最终同时支持两者，并建立明确的优先级：

interface Props {
  icon?: string | Component // 图标：字符串或 Vue 组件
}

<!-- 使用插槽（优先级更高，更灵活） -->
<Button>
  <template #icon>🔍</template>
  搜索
</Button>

<!-- 使用字符串 prop -->
<Button icon="✓" label="确认" />

<!-- 使用 Vue 组件 prop -->
<Button :icon="IconHome" label="首页" />

模板中的实现逻辑：

<span v-if="hasIconSlot || icon" class="mg-button-icon">
  <!-- 插槽优先于 prop -->
  <slot name="icon">
    <!-- prop 是 Vue 组件时渲染组件 -->
    <component :is="icon" v-if="typeof icon !== 'string'" />
    <!-- prop 是字符串时直接渲染文本 -->
    <span v-else-if="icon">{{ icon }}</span>
  </slot>
</span>

设计原则：插槽优先于 prop。hasIconSlot 检测是否传入 #icon 插槽，如果有则完全忽略 icon prop。这保证了灵活性——当用户需要自定义图标布局时，插槽总是能覆盖 prop 的默认行为。

设计考量：Nuxt UI v4 同样支持 icon prop 和 leading-icon/trailing-icon 等多个图标相关属性。我合并为单个 icon prop（左侧图标——这是个人博客场景 90% 的需求），保留 #icon 插槽用于完全控制。

四、插槽设计：默认插槽 vs label prop

为了支持快速写法和自定义内容，同时提供 label prop 和默认插槽：

<span v-if="hasLabel" class="mg-button-label">
  <slot>{{ label }}</slot>
</span>

hasLabel 的判断逻辑有一个容易忽视的细节：

const hasLabel = computed(() => props.label !== "" || !!slots.default)

注意这里是 props.label !== "" 而不是 !!props.label。为什么？

• withDefaults 会将 undefined 解析为默认值 ""
• 当外部显式传入 label="" 时，我们不渲染空 label 容器——这是「纯图标按钮」的经典场景，空容器会导致图标无法垂直居中
• 但如果有默认插槽（无论插槽内容是否为空），仍然渲染容器

<!-- 纯图标按钮：label 为空，不渲染空 label 容器 -->
<Button icon="🔍" />

<!-- 带插槽内容：即使 label 为空也渲染 -->
<Button><template #icon>🔍</template>搜索</Button>

这解决了纯图标按钮居中问题——空的 .mg-button-label 会占据空间导致图标不居中。

五、状态处理

5.1 禁用状态与加载状态

disabled 和 loading 都会禁用按钮，但只有 disabled 时 click 事件才完全阻止（原生 disabled 属性）；loading 状态我们还希望保留正确的语义——用户知道按钮在”处理中”。

const handleClick = (event: MouseEvent) => {
  if (props.disabled || props.loading) return
  emit("click", event)
}

<button :disabled="disabled || loading" @click="handleClick">

5.2 加载状态增强

初版的 loading 只显示旋转动画，隐藏图标和文字。v1.5.0 增加了两个增强：

• showLabelWhileLoading：加载时是否保留文字
• loadingLabel：加载时的自定义文字（默认复用 label）
• #loading-label 插槽：完全自定义加载文字（优先级最高）

<template v-if="loading">
  <span class="mg-button-loading-icon" />
  <!-- 根据开关决定是否显示 label -->
  <span v-if="showLabelWhileLoading" class="mg-button-label">
    <!-- 插槽 > loadingLabel prop > label -->
    <slot name="loading-label">{{ loadingLabel || label }}</slot>
  </span>
</template>

使用场景：

<!-- 默认：只显示加载动画 -->
<Button loading label="保存" />

<!-- 保留文字：提示用户"正在保存" -->
<Button loading :show-label-while-loading="true" label="保存" />

<!-- 自定义加载文字 -->
<Button
  loading
  :show-label-while-loading="true"
  loading-label="提交中..."
  label="提交"
/>

<!-- 用插槽完全自定义 -->
<Button loading :show-label-while-loading="true">
  <template #loading-label>⏳ 拼命保存中...</template>
</Button>

纯 CSS 实现加载动画：

.mg-button-loading-icon {
  width: 1rem;
  height: 1rem;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: mg-button-spin 0.6s linear infinite;
}
@keyframes mg-button-spin {
  to {
    transform: rotate(360deg);
  }
}

六、CSS 样式设计

6.1 基础样式

按钮使用 inline-flex 布局，内容水平和垂直居中，直角边框（--ui-radius-none），内边距和字体大小使用设计令牌。

.mg-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--ui-spacing-sm);
  font-weight: 500;
  transition: all var(--ui-motion-duration-neural) ease;
  cursor: pointer;
  border-radius: var(--ui-radius-none);
  border: none;
  background: transparent;
  white-space: nowrap;
  padding: var(--ui-spacing-sm) var(--ui-spacing-md);
  font-size: var(--ui-typography-size-body);
}

6.2 尺寸变体

6.3 颜色变体：hover/active 状态

v1.5.0 的颜色变体不仅定义了基础色，还完善了 hover/active 反馈。使用 color-mix() 在令牌颜色基础上混合黑色实现：

.mg-button-filled-primary {
  background-color: var(--ui-primary);
  color: white;
}
.mg-button-filled-primary:hover:not(:disabled) {
  background-color: color-mix(in srgb, var(--ui-primary), black 10%);
}
.mg-button-filled-primary:active:not(:disabled) {
  background-color: color-mix(in srgb, var(--ui-primary), black 20%);
}

/* outline 变体：透明背景 + 边框 */
.mg-button-outline-primary {
  background-color: transparent;
  color: var(--ui-primary);
  border: 1px solid var(--ui-primary);
}
.mg-button-outline-primary:hover:not(:disabled) {
  background-color: color-mix(in srgb, var(--ui-primary), transparent 90%);
}

使用 :not(:disabled) 确保禁用状态不触发 hover 效果。

6.4 图标与文字容器

图标容器使用 inline-flex 并设置 line-height: 0 来消除行高影响，内部的 SVG 或 iconify 图标强制块级并设置宽高为 1em。

.mg-button-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
  line-height: 0;
}
.mg-button-icon svg,
.mg-button-icon .iconify {
  display: block;
  width: 1em;
  height: 1em;
}

/* 空标签隐藏 - 修复只有图标时的居中问题 */
.mg-button-label:empty {
  display: none;
}

CSS 层的 :empty 伪类 + 组件层的 hasLabel 判断共同保证了纯图标按钮的正确居中。

七、无障碍设计

当前 Button 不添加 aria-busy 和 aria-disabled 属性。无障碍策略的核心是依赖原生语义：

• disabled 原生属性已经可以让屏幕阅读器正确读出禁用状态
• 加载状态通过视觉反馈（旋转动画）表达，比额外的 ARIA 属性更直观
• 移除多余的 ARIA 属性，避免和原生语义重复

这不是”极简 ≠ 简陋”的妥协，而是避免 ARIA 过度使用——原生 HTML 语义（<button disabled>）本身就是最可靠的无障碍。项目真正的无障碍保障来自测试层：a11y.test.ts 使用 axe-core 对 12 个核心组件做自动化规范检查（expectNoViolations）。

八、属性透传

使用 v-bind="$attrs" 透传原生属性：

<button v-bind="$attrs" class="mg-button" ...>

用户可以直接传入 id、name、data-*、aria-* 等属性：

<Button id="submit-btn" name="submit" data-testid="submit">
  提交
</Button>

配合 defineOptions({ inheritAttrs: false })，外部 class 会通过 $attrs 暴露给用户自行处理，同时组件内部的 class 绑定不会冲突。

九、最终代码（v1.5.0 实际实现）

<template>
  <button
    v-bind="$attrs"
    :type="type"
    class="mg-button"
    :class="[
      `mg-button-${variant}-${color}`,
      `mg-button-${size}`,
      { 'mg-button-block': block, 'mg-button-loading': loading },
    ]"
    :disabled="disabled || loading"
    @click="handleClick"
  >
    <!-- 加载状态 -->
    <template v-if="loading">
      <span class="mg-button-loading-icon" />
      <span v-if="showLabelWhileLoading" class="mg-button-label">
        <slot name="loading-label">{{ loadingLabel || label }}</slot>
      </span>
    </template>

    <!-- 正常状态 -->
    <template v-else>
      <span v-if="hasIconSlot || icon" class="mg-button-icon">
        <slot name="icon">
          <component :is="icon" v-if="typeof icon !== 'string'" />
          <span v-else-if="icon">{{ icon }}</span>
        </slot>
      </span>
      <span v-if="hasLabel" class="mg-button-label">
        <slot>{{ label }}</slot>
      </span>
    </template>
  </button>
</template>

<script setup lang="ts">
import { useSlots, computed } from "vue"
import type { Component } from "vue"
import type { Size, AddonColor } from "../types/components"

defineOptions({ name: "Button", inheritAttrs: false })

type Variant = "filled" | "outline"
type ButtonType = "button" | "submit" | "reset"

interface Props {
  label?: string
  variant?: Variant
  color?: AddonColor
  size?: Size
  type?: ButtonType
  disabled?: boolean
  loading?: boolean
  showLabelWhileLoading?: boolean
  loadingLabel?: string
  block?: boolean
  icon?: string | Component
}

const props = withDefaults(defineProps<Props>(), {
  label: "",
  variant: "filled",
  color: "primary",
  size: "sm",
  type: "button",
  disabled: false,
  loading: false,
  showLabelWhileLoading: false,
  block: false,
})

defineSlots<{
  default: () => any
  icon: () => any
  "loading-label": () => any
}>()

const slots = useSlots()
const hasIconSlot = computed(() => !!slots.icon)
const hasLabel = computed(() => props.label !== "" || !!slots.default)

const emit = defineEmits<{ click: [event: MouseEvent] }>()

const handleClick = (event: MouseEvent) => {
  if (props.disabled || props.loading) return
  emit("click", event)
}
</script>

十、与其他主流 UI 库的 API 对比

说明：表格中 Nuxt UI、Naive UI 和 PrimeVue 的 API 信息均来自其官方文档 (2026 年版本)。

通过这张表，可以清晰地看到 Moongate 的设计取舍：

• variant 与 color 的解耦：关注”视觉模式”与”语义颜色”分离
• 尺寸的精简：3 种尺寸足够覆盖个人博客场景
• 加载状态的精细化：showLabelWhileLoading/loadingLabel 是对”加载时文案”需求的响应——这是其他库经常忽略的细节
• 图标支持的灵活性：prop 快速写法 + 插槽完全控制

十一、关于加载状态宽度变化的讨论

组件开发中有一个经典陷阱——按钮加载时宽度变化导致布局偏移（CLS）。

常见的解法是 min-width 预留 + 加载图标绝对定位。但在 v1.5.0 的实际实现中，我没有采用这种方式，原因是：

1. min-width: 88px 是硬编码值，会破坏”小型组件响应不同内容宽度”的灵活性
2. 绝对定位的加载图标在 loading="true" 时脱离文档流，如果按钮内有其他内容（如加载文字），布局仍可能变化
3. 更好的性能优化是保证加载状态的文案长度接近正常状态（loadingLabel 帮助用户保持文案一致）

如果你的场景确实对 CLS 要求严格（如电商下单按钮），可以在业务层手动添加：

.my-order-button {
  min-width: 120px; /* 根据你实际按钮宽度预留 */
}

组件库层面保持灵活，用户按需优化。

十二、设计决策总结