语义令牌表：把语义概念编码成离散枚举

本文是 Schema-As-Code 证据链 的"框架设计"站，属于主题行的第一个关键设计——语义令牌表（Semantic Token Table）。在前序章节中，阶段一 Guard 结构化诊断 通过 组件语义快照 与 三层判定模型 发现了 6 个漂移模式；语义域 建立了"组件是空容器，语义由场景定义"的覆盖层模型。但语义要能被机器识别、校验与生成，必须先解决一个编码问题：如何把"语义概念"变成"机器可运算的离散值"？本文要建立的正是 Schema-As-Code 的语义编码层——当 语义规范体系 需要被写入 YAML 契约 时，语义必须以离散令牌的形式存在，而非自然语言描述。

快速阅读：

方法论总纲与开源：把设计规范写成代码格式，是所有 AI 工具的上游约束方法论\
阶段一结构化诊断：组件语义快照与模式诊断：AI 生成界面的第一道检查\
阶段二语义契约化：设计师作为"语义翻译者" 当AI生成界面时我怎么用规则锁住设计意图\
角色专题1:设计师与产品经理：AI 界面语义走查指南\
角色专题2：前端与AI工程师把语义约束写进AI的生成上下文\
机制主题1:① 语义令牌与字典

1. 问题：语义是"感觉"，还是"可运算的值"？

行业现状中，语义以自然语言或视觉样式存在：设计师说"这个要用红色"，前端看到 #EF4444，AI 生成工具看到 color: red。但"红色"在不同场景下含义完全不同——在 语义域 的 transactional 域它是"阻断确认"，在 observational 域它可能是非法绑定（跨层禁止）。当语义以颜色值、文案词或"感觉"的形式流动时，机器无法区分"同一个红色在不同场景下是否合法"。

6 个漂移模式 中的 ERR-001（错误状态后果差异未分级）根因正是如此：致命错误、网络抖动、限流、降级四种完全不同的后果，共用同一种红色——因为机器看到的只是 color: #EF4444，而不是 error_severity.fatal 与 error_severity.retryable 的语义区别。没有离散令牌，就没有机器可执行的判定依据。

2. 为什么自然语言守不住：语义不可运算

设计规范文档用自然语言描述语义："致命错误用红色脉冲，限流用黄色时钟"。但自然语言对机器是不可运算的：

• AI 生成工具读不懂"致命错误"与"限流"的区别，它的训练语料里只有 red 和 yellow；
• 前端工程师看到的是 Design Token color-danger 和 color-warning，但 danger 与 warning 的语义边界没有机器定义，AI 可以把 color-danger 用在成功状态；
• 验收走查依赖人的主观判断，"感觉不对"无法转化为可复现的校验规则。

组件语义快照 的 6 字段记录法已经证明：观察界面时需要记录 component_type、visual、copy、interaction、context 等维度。但这些字段的值如果是自由文本（如 color: "red"），仍然不可运算。语义令牌表的作用，就是把"红色"编码为 status.critical，把"限流"编码为 error_severity.retryable——让语义成为机器可查询、可校验、可拦截的离散值。

3. 设计思路：把语义概念编码成离散枚举

本文的设计思路是三个递进命题：

• 语义概念 → 离散令牌：error_severity 不是文档里的段落，而是包含 fatal、transient、retryable、degraded 四个枚举值的令牌表；每个枚举值绑定唯一的视觉映射（status.critical → 红色脉冲）与行动约束（必须提供恢复路径）；
• 令牌 → 字典注册：所有语义令牌在 语义字典 中注册，成为组织级唯一信源。契约（YAML）不定义令牌，只引用令牌；
• 令牌 → 可执行规则：编译管线 将令牌表编译为 Prompt 前缀（注入 AI 上下文）、JSON Schema（组件 Props 校验）、CI 规则（流水线拦截）——同一组离散值，在不同工具链中以不同格式执行同一语义。

这与 语义规范体系 的关系：语义规范体系定义"有哪些语义维度"，语义令牌表定义"每个维度下有哪些离散值"。没有令牌表，规范体系只是分类框架；没有规范体系，令牌表只是孤立枚举。

4. 本文的核心命题

"把语义编码成离散令牌"必须翻译成可验证的框架设计。本文回答三个命题：

一、调整前：四个角色的真实反馈

在没有语义令牌之前，各角色在界面层"看到"的世界，用他们自己的话说：

前端与 AI 工程师的真实反馈："致命错误和限流提示，被渲染成了同一种红色背景条。"

AI 生成工具里只有 Design Token——color.danger: { value: "#EF4444" }。红色是一个色值，不附带任何场景含义。同一款 AI 对话产品中，"对话可能已丢失"的致命错误与"请求太频繁，请等 30 秒"的限流提示长得一模一样：色板合规、对比度达标，视觉走查挑不出任何毛病，但用户从界面上读不到两者的区别。

设计师与产品经理的真实反馈："同一个 alert，三个人三种理解，每个人都没错。"

组件库里的 Alert 只是视觉组件——圆角、图标位、关闭按钮。它不知道自己在交易确认场景里是阻断性语义，在信息展示场景里是旁观性语义。前端理解为弹窗，设计师指的是顶部通知条，两个人都对，因为没有任何注册表裁定。

前端与 AI 工程师的另一条真实反馈："LLM 把 Critical 降级为'严重'，代码里查不出来。"

在 LLM 的词汇表里，"Critical"和"严重"是近义词。AI 生成告警时把 "Critical" 替换为"严重"、把 "Data Loss Risk" 替换为"请稍后重试"——情绪权重在概率性输出中被随机降级，而没有任何机制判定这是违规。

DesignOps 与设计系统负责人的真实反馈："规范写在文档平台里，人可能看漏，AI 工具完全不可见。"

"错误状态分四级"供人阅读，机器查询不了，更校验不了。

汇总成一张表：

这四条反馈指向同一个根因：语义没有被编码成机器可读的东西。红色只是色值，组件只是容器，术语只是字符串——机器拿不到语义，就只能靠概率猜。

二、"把语义编码为离散令牌"不是自创概念

2003年，Eric Evans 在《Domain-Driven Design》中提出 Bounded Context（限界上下文）——同一个术语在不同业务边界内有不同含义，域内唯一定义，互不污染。这与我们的语义域是同一逻辑：同一个 Alert 在 transactional 域是"阻断确认"，在 observational 域是"旁观通知条"——域内唯一定义，域间含义不同。

同期，Evans 定义了 Anti-Corruption Layer（防腐层）——边界之间做翻译与隔离，非法引用被拒绝。这与我们的跨层禁止规则对应：status.critical 不可用于 observational 域，非法绑定在编译前置校验时直接阻断。域边界靠机器规则维护。

工业界也在做。Microsoft Azure 将 ACL 作为官方架构模式收录，W3C DTCG 已定义 Semantic Token 层。我们在其之上扩展了行为约束与跨域规则。

但行业也有反面的声音。许多设计系统的"语义令牌"只是换名（color-red-500 改叫 color-danger），没有场景定义；组件分类模型在 AI 生成时代系统性失效，<ErrorAlert> 自带语义导致升级时语义跟着重写。这恰恰反证了我们为什么需要覆盖层模型——语义必须外赋于组件（空容器），由域边界统一定义，可被机器校验。

参考链接：

• Eric Evans · DDD Reference 2015
  https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf
• Microsoft Azure · Anti-Corruption Layer Pattern
  https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer
• W3C DTCG · Design Tokens Format Module 2025.10
  https://www.designtokens.org/TR/2025.10/format/
• W3C · Design Tokens Community Group
  https://www.w3.org/community/design-tokens/

三、关键设计：语义令牌表

3.1 四大命名空间（码本原子集）

语义令牌按"回答的问题"分为四个命名空间，每个令牌是离散索引，编译管线查表后展开为连续约束：

status. —— 这件事有多严重？

phase. —— AI 处于什么阶段？用户在等什么？

boundary. —— 系统拒绝用户时，权利边界在哪里？

action. —— 用户点击后，后果是什么？

3.2 字典注册的 6 个语义绑定（v1.0.0）

字典 v1.0.0 注册的 6 个语义绑定，构成组织级语义码本的最小可行原子集：

3.3 令牌如何展开为连续约束

每个令牌在契约中展开为一组连续约束。以 status.critical 应用于致命错误（ERR-001 · fatal 级别）为例：

semantic_tokens:
  error_severity:
    fatal:
      description: "致命错误：数据可能丢失或会话不可恢复"
      visual_mapping:
        color_token: status.critical      # 引用字典绑定，非色值
        motion_token: pulse.red.urgent    # 红色脉冲：注意力强制的最高档
        icon_token: octagon-alert
      user_action:                        # 必须提供恢复路径
        - label: "刷新页面"
          action: refresh_page
          priority: 1
        - label: "导出历史"
          action: export_history
          priority: 2
      llm_constraints:
        - "文案必须说明'对话可能已丢失'"
        - "禁止仅显示'出错了'等模糊文案"
        - "禁止显示纯技术错误码"
      immutable_boundaries:
        - boundary_type: semantic
          rule: "禁止把 fatal 级错误渲染为普通文字提示"
          violation_action: block
        - boundary_type: semantic
          rule: "status.critical 不可用于 observational 域"
          violation_action: block

一个离散索引（status.critical）→ 展开为视觉方向（红色脉冲 + 八边形图标）+ 行为约束（恢复路径、二次确认）+ 文案约束（必须说明后果）+ 机器防线（跨层禁止 block）。这就是"码本解码"的完整形态。

四、架构层概念：设计背景

码本，而非术语表。 术语表供人查阅，码本供机器解码：每个令牌是离散索引，编译管线查表后展开为连续约束（视觉方向 + 行为约束 + 文案语气）。这决定了令牌的读者不只是设计师，更是编译管线与 AI 工具。

令牌层与呈现层分离。 color_token 是语义标识，color 是实际色值：同一个 status.critical 在不同设计系统里可映射到不同色值（Tailwind #EF4444 / Ant Design #F5222D / DevUI #FF4D4F）。语义令牌不关心具体色值，只关心语义映射关系——设计系统更新时改映射表，契约不变。

语义覆盖层（Semantic Overlay）。 组件库是底层（Underlay），只负责渲染——它提供圆角、色值、图标位这些空容器；语义覆盖层在组件之上加盖业务语义，把空容器翻译为业务语义组件。令牌是覆盖层加盖语义时使用的"印泥"。

术语双轨。 面向不同读者群时，三层结构有两套叫法：语义域 ≈ 覆盖层目录；语义令牌 ≈ 语义重绑定；场景映射 ≈ 约束注入。两套术语指向同一份注册表。

五、这些坑怎么被解掉：场景与角色对照

回到开头那些真实反馈，看令牌就位后它们各自怎么闭环。

踩过的坑 1："这个红到底代表什么，走查时谁也说不清"

● 症状：AI 生成限流提示时，Before 形态下选 color-danger 无可指责——红色本身没错，视觉走查也合规，但用户看到红色以为账户出了问题，实际只是需要等 30 秒。合规，但错误。

● 根因：Token 只定义颜色，没定义场景语义，机器拿不到"限流 ≠ 致命"这条信息。

● 关联机制：①语义令牌与字典（本篇 B1 + B3）+ C-D2《Token 层差异》

● 解法路径：有了令牌后，限流语义级别是 retryable（黄色时钟 + 倒计时）；AI 若选 status.critical，直接违反跨层规则，CI 阻断，PR 无法合入。错误在生成阶段就无法成立。

● 验证方式：前端与 AI 工程师的验收争议从"感觉不对"变成"违反了哪条绑定"——争议可引用、可定位、可裁决。

踩过的坑 2："LLM 把 Critical 降级为'严重'，代码里查不出来"

● 症状：AI 生成告警时把 "Critical" 替换为"严重"、把 "Data Loss Risk" 替换为"请稍后重试"——情绪权重被概率性输出随机降级，Schema 校验通过，语义却是错的。

● 根因：文案层没有术语锚定，同义词自由替换没有任何机制判定违规。

● 关联机制：①语义令牌与字典（B3 字典 synonym_firewall 同义词防火墙）+ 6 个漂移模式证据库（ALR-001）

● 解法路径：YAML 定义禁止词并编译进 Prompt 前缀，synonym_firewall 约束下关键术语替换即违规，生成阶段被校验规则命中。

● 验证方式：设计师与产品经理精心设计的语义权重不再被概率性输出随机抹平——"Critical" 在所有产出中保持锚定，替换即被校验规则命中。

六、调整后：工具界面层的呈现状态

同一批工具，在语义令牌就位之后：

边界声明

语义令牌表不解决视觉值的一致性（那是 Design Token 层的职责），不定义具体场景的约束实例（那是 YAML 契约的职责），也约束不了"有没有人查它"（消费纪律在角色侧，见角色 1 长篇）。当前量化收益均为数据模型推演，待生产数据验证。