① 语义字典：组织级语义注册表，契约的唯一信源

框架设计背景

本文是 Schema-As-Code 证据链 的"认知 合法性"站，属于主题行①的第二个关键设计——语义字典（Semantic Dictionary，覆盖层注册表）。在前序章节中， B1 语义令牌表 把语义概念编码为离散枚举值（status.critical、error_severity.retryable），回答了"语义用什么形式存在"； B2 语义域 建立了"组件是空容器，语义由场景定义"的覆盖层模型，回答了"语义住在哪里"。但离散令牌和覆盖层模型要能被全组织引用、查询与校验，必须有一个唯一信源——否则每个团队都会发明自己的"红色"、自己的"错误"、自己的"删除账户"。本文要建立的正是 Schema-As-Code 的组织级语义注册表：当 语义规范体系 需要被写入 YAML 契约 时，所有术语必须在字典中先注册、后引用，契约只是字典的只读消费面。

1. 问题：语义住在谁的脑子里？

行业现状中，语义住在三个地方：设计师的直觉、前端的经验、产品经理的文档。这导致三个系统性问题：

●同名异义无人仲裁：评审会上"这里用一个 alert"——前端理解为模态弹窗，设计师指的是顶部通知条，产品经理以为是 Toast。三个人用同一个词指三个东西，每个人都对，因为没有任何注册表裁定"alert 在这个场景下是什么"；

●决策无据全靠经验：新产品线设计"删除账户"流程，一位设计师主张红色实心按钮、一位主张橙色描边，双方都有道理，最终靠职级裁定。决策依据是个人经验，不可复用、不可跨产品线继承；

●需求模糊无法验收：PRD 写"需明显提示风险"——什么叫"明显"？开发按自己的理解实现，验收按自己的理解走查，争议在交付后才爆发。

6 个漂移模式 中的 ERR-001（错误状态后果差异未分级）、BND-001（边界动作权利差异未区分）等，根因都是"组织内没有统一的语义坐标系"。 组件语义快照 记录了界面的 6 个维度，但记录的值如果没有注册表对照，仍然是自由文本； 语义令牌表 定义了离散枚举值，但枚举值如果没有注册表管理，仍然是局部约定。没有字典，语义就住在人的脑子里——人走了，语义就丢了。

2. 为什么文档规范守不住：语义不可查询、不可校验

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

●AI 生成工具读不到文档，它的训练语料里只有 red 和 yellow；

●前端工程师看到的是 Design Token color-danger，但 danger 在组织内没有统一定义，不同产品线理解不同；

●验收走查依赖人的主观判断，"感觉不对"无法转化为可复现的校验规则；

●跨团队沟通没有共同坐标系，A 团队的"严重"和 B 团队的"Critical"是不是同一个级别，没有机器能回答。

语义域 已经证明：同一个 Alert 在 transactional 域是"阻断确认"，在 observational 域是"旁观提示"。但如果没有字典注册表，这个差异只存在于设计文档里，机器拿不到。语义字典的作用，就是把"alert 在 transactional 域下绑定为阻断器"写入注册表，让机器可以查询、校验、拦截。

3. 设计思路：先注册、后引用，字典是唯一信源

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

●先注册、后引用：字典没有的，先走变更流程注册（快照证据 → 诊断归档 → 候选模式 → 评审入典），再引用。不为想象中的需求提前定义语义；

●契约是只读消费面：所有 YAML 契约 必须引用字典中的已定义项，不可自创覆盖层或绑定；semantic_domain 的值必须在字典预定义列表中，非法引用在编译前置校验时直接阻断（跨层禁止）；

●三层注册表：覆盖层目录（L1 语义域）→ 语义重绑定（术语在覆盖层下的强制语义）→ 场景映射（业务场景的完整语义方案）。三层结构让查询者按需获取：设计师查场景映射拿完整方案，前端查语义绑定拿约束注入，AI 查覆盖层目录拿语义角色。

这与 语义令牌表 的关系：令牌表定义"有哪些离散值"，语义字典定义"这些值在什么场景下合法、什么场景下非法"。没有令牌表，字典没有原子；没有字典，令牌表没有边界。

4. 本文的核心命题

"语义字典是组织级唯一信源"必须翻译成可验证的框架设计。本文回答三个命题：

命题	验证标准
字典是唯一定义源	全组织同一术语坐标系，任何团队不得维护平行的"私有字典"；非法引用在编译前置校验时阻断
字典可被机器查询	覆盖层目录、语义绑定、场景映射三层结构可被编译管线查询，并编译为 Prompt 前缀 / JSON Schema / CI 规则
字典变更可同步	字典单点变更 → 契约重编译 → 四种消费格式同步更新，Git Diff 可追溯

一、调整前：三条真实反馈里的"语义三无"

在没有语义字典之前，组织内的"语义"处于三无状态，每条都有团队里的原话为证。

真实反馈 1："评审会上说'这里用一个 alert'，散会后发现三个人理解成三个东西。"

前端理解为模态弹窗，设计师指的是顶部通知条，产品经理以为是可以自动消失的 Toast。三个人用同一个词指三个东西，每个人都对——因为没有任何注册表裁定"alert 在这个场景下是什么"。同名异义，无人仲裁。

真实反馈 2："删除账户按钮该红色实心还是橙色描边？最后谁的职级高听谁的。"

新产品线设计"删除账户"流程，一位设计师主张红色实心按钮、一位主张橙色描边，双方都有道理，最终靠职级裁定。决策依据是个人经验，不可复用、不可跨产品线继承。决策无据，全靠经验。

真实反馈 3："PRD 写'需明显提示风险'，交付后才开始吵什么叫'明显'。"

开发按自己的理解实现，验收按自己的理解走查，争议在交付后才爆发。需求模糊，无法验收。

汇总成一张表：

环节	界面层呈现状态	缺失什么
评审沟通	同一术语多种理解	可引用的唯一定义注册表
设计决策	个人经验裁定	组织级场景语义方案
需求描述	自然语言形容词	可校验的语义引用
规范执行	文档供人阅读，AI 不可见	机器可查询、可校验的注册表

三条反馈，一个根因：组织里没有一份"唯一定义术语"的资产。字典在的时候，它是文档平台里供人阅读的文字；机器要查的时候，它不存在。

二、"用语义注册表统一定义"不是自创概念

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

也是在这一阶段，Evans 提出了 Anti-Corruption Layer（防腐层）这一概念——说白了，就是在不同边界之间负责翻译、负责隔离，任何不合规的引用都会被拦下。这一点，和这里的跨层禁止规则正好一一对应：status.critical 不能进入 observational 域，凡是非法绑定，都会在编译前置校验阶段被直接阻断。换句话说，域边界不是靠约定维持，而是由机器规则硬性守住。

2024年起，数据领域已大规模实践"语义层"概念。Databricks 在其 Semantic Layer Architecture 中将其定义为"business-friendly abstraction layer"，统一跨部门对"客户""订单"等业务术语的理解。这与我们的语义字典同构：Databricks 解决数据领域的语义一致性，我们解决界面领域的语义一致性。架构相同：元数据仓库 → 业务逻辑层 → 治理框架。

到了2026年，Kyvos 又把这件事往前推进了一步，提出了 AI-Ready 语义层：如果没有语义层，AI 就没法真正读懂数据背后的含义。这个判断放到界面领域，其实是完全一致的——没有语义字典，AI 同样无法准确理解“红色按钮”到底代表致命错误，还是只是一次普通警告。Kyvos 的语义层，正是为 Claude Cowork 这类 AI Agent 提供 governed business semantics，目的很明确：不让 agent 靠猜去理解数据，而是统一基于集中化定义来使用语义。对应到这里的编译管线，本质上也是同一套逻辑：把字典编译成 Prompt 前缀，在 AI 生成之前先注入语义约束。

工业界也在做。W3C DTCG 已定义 Semantic Token 层，把颜色和间距抽象为语义。我们在其之上扩展了行为约束与跨域规则。

但行业也有反面的声音。许多设计系统的"语义令牌"只是换名（color-red-500 改叫 color-danger），没有场景定义；组件分类模型在 AI 生成时代系统性失效， 自带语义导致升级时语义跟着重写。这恰恰反证了我们为什么需要真正的语义字典——不是换名，而是锁义。

参考链接：

Eric Evans · DDD Reference 2015 https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdfDatabricks · Semantic Layer Architecture https://www.databricks.com/blog/semantic-layer-architecture-components-design-patterns-and-ai-integrationKyvos · AI-Ready Semantic Layer https://www.kyvosinsights.com/ai/best-semantic-layer-tools-2026/W3C DTCG · Design Tokens Format Module 2025.10 https://www.designtokens.org/TR/2025.10/format/

三、关键设计：语义字典（三层注册表）

语义字典是覆盖层注册表，三层结构：覆盖层目录（Overlay Catalog）→ 语义重绑定（Semantic Rebinding）→ 场景映射（Scenario Mapping）。

层级	内容	查询时获得什么
第一层： 覆盖层目录	4 个 L1 语义域：transactional（交易与操作）/ observational（观察与信息）/ na vigational（导航与引导）/ conversational（对话与交互），加 L0/L2 层级	该界面点属于哪种交互关系、约束特征是什么
第二层： 语义重绑定	术语在具体覆盖层下的强制语义（6 个语义绑定）	某令牌在此场景的准确定义与跨层禁止
第三层： 场景映射	业务场景的绑定组合与组件组合（SCN-001 ~ SCN-006）	整个场景的完整语义方案，可直接引用

3.1 第一层：覆盖层目录（全量）

覆盖层 ID	中文名称	定义	适用场景示例	禁止场景	层级
universal	通用层	所有界面点的基础属性	可访问性、响应式	—	L0（被所有层覆盖）
transactional	交易与操作	用户动作会改变系统状态或数据	支付、删除、提交、确认、撤销	纯信息展示、状态更新、新手引导	L1
observational	观察与信息	用户仅接收信息，无需立即行动	通知、状态更新、提示、反馈	需要用户决策、需要二次确认、不可逆操作	L1
na vigational	导航与引导	用户需要方向指引，无数据变更	面包屑、步骤指示、返回、跳转	表单提交、数据操作、支付流程	L1
conversational	对话与交互	用户与系统双向交流，上下文持续	聊天、问答、建议、澄清	一次性操作、无上下文的状态提示	L1
financial	资金操作	transactional 的子层：涉及资金流动	支付、转账、退款	—	L2
data-destructive	数据销毁	transactional 的子层：涉及数据删除	删除账户、清空数据	—	L2

强制规则： 每个界面点必须且只能被一个 L1 覆盖层覆盖（互斥）；L2 是对 L1 的细化而非替代；未注册的覆盖层编译管线拒绝识别。

【Schema-As-Code 组织级语义注册表 · ① 语义字典演示环境 证明】

推演条件： 接入生产环境后，覆盖层目录需支持自定义扩展（如新增 onboarding 新手引导层），新增 L1 覆盖层属于 Minor 版本变更，需设计系统负责人审批；L2 子层扩展属于 Patch 级别，DesignOps 可直接合并。

3.2 第二层：语义重绑定（全量）

绑定是强制的，不是建议：

术语 ID	所属覆盖层	状态级别	语义绑定	约束注入	跨层禁止
status.critical	transactional	系统级故障	阻断器：用户必须立即处理，否则系统状态恶化	视觉：红色脉冲、八边形图标；行为：必须二次确认；文案：必须说明后果；适用：仅用于阻断性错误	observational / na vigational / conversational
status.warning	transactional	用户可恢复限制	限制器：用户需要注意，但可以自助恢复	视觉：黄色静态、三角图标；行为：必须显示恢复时间；文案：必须提供操作步骤；适用：仅用于可恢复错误	observational / na vigational / conversational
status.info	observational	一般信息提示	信息条：用户可选择性关注，不影响系统状态	视觉：蓝色静态、信息图标；行为：可自动消失；文案：禁止附加操作说明；适用：仅用于纯信息展示	transactional
status.success	observational	操作成功反馈	成功条：用户操作已完成，系统状态已更新	视觉：绿色静态、对勾图标；行为：可自动消失；文案：禁止附加操作说明；适用：仅用于成功状态	transactional
action.destructive	transactional	不可逆操作	危险动作：用户动作将导致数据永久丢失	视觉：红色空心描边、危险图标；行为：必须二次确认；文案：必须说明不可恢复；适用：仅用于删除/清空等操作	observational / na vigational / conversational
action.primary	na vigational	主要引导动作	引导动作：帮助用户进入下一步或完成流程	视觉：品牌色实心、箭头图标；行为：点击后跳转；文案：显示下一步预览；适用：仅用于流程推进	transactional / observational

通用术语的重绑定示例（同一个词，不同覆盖层下绑定为不同语义）：

通用术语	transactional 下绑定为	observational 下绑定为	na vigational 下绑定为
Alert	阻断器：用户必须立即处理，否则系统状态恶化	信息条：用户可选择性关注，不影响系统状态	路径提示：用户需要方向确认，无状态风险
确认	不可逆操作确认：用户理解后果并承担风险	已知晓确认：用户收到信息，无需承担风险	路径确认：用户确认前往下一节点
取消	操作撤销：系统回滚到操作前状态	关闭提示：信息消失，系统无变化	返回上一步：导航状态回退
红色	危险信号：阻断、不可逆、需立即响应	非法绑定（observational 下红色非法）	非法绑定（na vigational 下红色非法）

前端实现时不传 type="error" 参数，而是声明 overlay="transactional"，由覆盖层强制注入语义。非法绑定在编译时直接阻断。

【Schema-As-Code 组织级语义注册表 · ① 语义字典演示环境 证明】

推演条件： 接入生产环境后，语义重绑定表需支持版本锚定——契约头部声明依赖的字典版本（如 v1.1.0），加载时锁定该版本快照，字典升级不会意外破坏旧契约的引用关系。

3.3 第三层：场景映射（全量）

场景 ID	场景名称	覆盖层	语义绑定组合	组件组合	文案约束	约束注入
SCN-001	删除账户	transactional	status.critical action.destructive	Alert Button Modal	必须包含"此操作不可恢复"；必须说明数据删除范围	必须输入账户名二次确认；必须提供取消按钮；操作后跳转至登录页
SCN-002	网络中断	transactional	status.warning	Alert Button	必须显示"网络不稳定"；必须显示自动重试倒计时	提供手动重试按钮；倒计时结束后自动刷新
SCN-003	保存成功	observational	status.success	Toast	仅显示"保存成功"；禁止附加操作说明	3 秒后自动消失；不可手动关闭
SCN-004	新功能上线	observational	status.info	Banner	显示功能名称和一句话说明；提供"了解详情"链接	点击链接跳转帮助中心；不可阻断当前操作
SCN-005	支付确认	transactional	status.critical	Alert Form Button	必须显示金额、收款方、支付方式；必须说明支付后不可撤销	必须输入支付密码或指纹；必须提供"取消"按钮
SCN-006	步骤引导	na vigational	action.primary	Stepper Button	显示当前步骤和总步骤；提供上一步/下一步	第一步禁用"上一步"；最后一步变为"完成"

场景映射查询实例： 设计师查询 SCN-001（删除账户），字典直接给出完整方案——覆盖层 transactional；语义绑定 status.critical action.destructive；组件组合 Alert Button Modal；文案必须包含"此操作不可恢复"；交互必须输入账户名二次确认。视觉探索在边界内展开，语义方案无需重新发明。

【Schema-As-Code 组织级语义注册表 · ① 语义字典演示环境 证明】

推演条件： 接入生产环境后，场景映射需支持业务自定义扩展（如"批量删除""跨设备同步"），新增场景映射属于 Minor 版本变更；场景映射的查询接口需接入设计师工作台，支持按覆盖层、组件类型、关键词检索。

3.4 注册纪律

字典是组织内唯一定义覆盖层、语义绑定与场景映射的资产。三条纪律：

1. 唯一性： 全组织同一术语坐标系，任何团队不得维护平行的"私有字典"。

2. 强制性： 所有 YAML 契约必须引用字典中的已定义项，不可自创覆盖层或绑定；semantic_domain 的值必须在字典预定义列表中，非法引用在编译前置校验时直接阻断。

3. 先注册、后引用： 字典没有的，先走字典变更流程注册（快照证据 → 诊断归档 → 候选模式 → 评审入典），再引用。不为想象中的需求提前定义语义。

【Schema-As-Code 组织级语义注册表 · ① 语义字典演示环境 证明】

推演条件： 接入生产环境后，注册纪律需接入 CI 流水线——契约加载时逐条核对引用是否在字典中注册，版本是否匹配，跨层禁止是否被违反。非法引用在入库前即被阻断，并向 DesignOps 推送阻塞告警。

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

覆盖层（Overlay）不是分类（Taxonomy）。 分类模型语义内生于组件（ 自带"错误"语义，组件库升级时语义跟随重写）；覆盖层模型语义外赋于组件——组件是空容器（ 只负责渲染），语义由覆盖层强制注入。组件库是底层（Underlay），语义覆盖层在组件之上加盖业务语义，把空容器翻译为业务语义组件。分类回答"这是什么组件"，覆盖层回答"这个组件在此场景下承担什么语义"。

码本，而非术语表。 术语表供人查阅，码本供机器解码：每个绑定是离散索引，编译管线查表后展开为连续约束。这决定了字典的读者不只是设计师，更是编译管线与 AI 工具。

在全景中的位置。 语义字典位于建设层的最上游（元规则层）：语义字典（上游·元规则）→ YAML 契约（中游·实例）→ 编译管线（下游·执行），契约库 提供组织级管理。

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

五、这些坑怎么被解掉：三条反馈的闭环

回到开头的三条真实反馈，字典就位后它们各自的解法路径。

反馈 1 的解法："alert 到底是什么"——歧义在引用条目的瞬间消失

症状复盘：评审会上"这里用一个 alert"，三个人理解成三个东西。根因：没有可引用的唯一定义注册表，术语含义靠各自脑补。解法路径：查字典——transactional 域的 alert 是阻断确认，observational 域的 alert 是顶部通知条。设计师与产品经理沟通时，用字典条目编号替代形容词；争议以字典为仲裁依据，不再靠职级裁定。验证方式：同样的评审场景，引用条目编号后，三方理解在当次会议对齐，不再"散会后才发现"。

反馈 2 的解法："删除账户按钮之争"——决策依据从职级变成注册表

症状复盘：红色实心 vs 橙色描边，双方都有道理，靠职级裁定。根因：没有组织级场景语义方案，决策依据是个人经验，不可复用、不可跨产品线继承。解法路径：查询 SCN-001，完整语义方案既定（覆盖层 transactional status.critical action.destructive 二次确认），视觉探索在边界内展开。验证方式：跨产品线语义天然一致——下一个产品线遇到"删除账户"，直接引用同一场景映射，不重新争论。

反馈 3 的解法："什么叫明显提示风险"——需求从形容词升级为可校验引用

症状复盘：PRD 写"需明显提示风险"，交付后才吵"什么叫明显"。根因：需求用自然语言形容词描述，没有可校验的语义引用。解法路径：PRD 改写为"引用场景映射 SCN-001，语义绑定 action.destructive，必须二次确认"。验证方式：验收标准在需求阶段即已确定——交付后的争议消失，因为"明显"已经被翻译成字典里的具体约束。

六、扩展路线

当前： 4 个 L1 覆盖层 6 个语义绑定 6 个场景映射，只覆盖证据最充分的 6 个漂移模式。规划： 按业务需求新增覆盖层（如 onboarding 新手引导）、新增绑定（如 status.neutral 中性状态）、新增场景映射（如"批量删除""跨设备同步"）。远期： 重构覆盖层分类（如 transactional 拆分为 financial 和 data-operation），主版本变更，全组织升级。

版本治理（SemVer）： 新增覆盖层/绑定/场景 = Minor（设计系统负责人审批）；修改既有定义语义 = Major（设计委员会评审）；措辞澄清不改语义 = Patch（DesignOps 直接合并）。弃用项标记 deprecated 保留至少 90 天，编译时对引用方输出 warning 并附迁移指引；旧契约可继续引用旧版本字典（多版本共存，编译时按契约声明的字典版本解析）。

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

工具 / 环节	调整前	调整后
组件调用	Alert 是无语义的视觉容器	契约编辑器中覆盖层下拉自字典：选 observational 即继承"不可阻断流程"约束，选 transactional 即继承确认交互要求
验收环节	走查结论停留在"感觉不对"	Checklist 第一组直接引用字典：覆盖层检查 / 语义绑定检查 / 约束注入检查，结论注明字典版本号
规范变更	文档平台发通知，人看漏、AI 不可见	字典单点变更 → 契约重编译 → 四种消费格式同步更新，Git Diff 可追溯

一句话总结（给不同角色）

给设计师： "你不需要凭直觉选颜色，只需要查字典三层：这是什么页面？这个词在这里什么意思？这个场景完整方案是什么？字典给你唯一答案。"

给前端： "你不需要猜设计师的意思，只需要查字典。status.critical 在字典里锁死了红色脉冲 八边形 必须二次确认，没有第二种解释。"

给 DesignOps： "以前规范更新靠人肉广播，现在改一次字典，所有 AI 工具、所有契约、所有 Prompt 前缀自动跟着更新，Git Diff 告诉你影响了哪些地方。"

给 AI 工程师： "你不需要在 Prompt 里写半本设计规范，只需要引用字典里的场景编号（如 SCN-001），AI 自动生成符合语义约束的界面。"

给管理层： "以前十个团队十种叫法，现在一本字典管全公司。语义一致性从'人盯'变成'机查'，规范更新从 2 周降到 0.5 天。"

边界声明

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