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

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

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

1. 同名异义无人仲裁：评审会上”这里用一个 alert”——前端理解为模态弹窗，设计师指的是顶部通知条，产品经理以为是 Toast。三个人用同一个词指三个东西，每个人都对，因为没有任何注册表裁定”alert 在这个场景下是什么”；
2. 决策无据全靠经验：新产品线设计”删除账户”流程，一位设计师主张红色实心按钮、一位主张橙色描边，双方都有道理，最终靠职级裁定。决策依据是个人经验，不可复用、不可跨产品线继承；
3. 需求模糊无法验收：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. 设计思路：先注册、后引用，字典是唯一信源

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

1. 先注册、后引用：字典没有的，先走变更流程注册（快照证据 → 诊断归档 → 候选模式 → 评审入典），再引用。不为想象中的需求提前定义语义；
2. 契约是只读消费面：所有 YAML 契约 必须引用字典中的已定义项，不可自创覆盖层或绑定；semantic_domain 的值必须在字典预定义列表中，非法引用在编译前置校验时直接阻断（跨层禁止）；
3. 三层注册表：覆盖层目录（L1 语义域）→ 语义重绑定（术语在覆盖层下的强制语义）→ 场景映射（业务场景的完整语义方案）。三层结构让查询者按需获取：设计师查场景映射拿完整方案，前端查语义绑定拿约束注入，AI 查覆盖层目录拿语义角色。

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

4. 本文的核心命题

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

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

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

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

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

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

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

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

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

汇总成一张表：

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

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

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
• Databricks · Semantic Layer Architecture
• Kyvos · AI-Ready Semantic Layer
• W3C DTCG · Design Tokens Format Module 2025.10

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

语义字典是覆盖层注册表，三层结构：覆盖层目录 → 语义重绑定→ 场景映射。

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

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

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

在演示环境中，系统以 L1/L2 层级徽章可视化展示覆盖层目录。每个覆盖层卡片标注了适用场景与禁止场景，L1 层级用蓝色徽章、L2 子层用紫色徽章区分。这证明了覆盖层目录不是抽象分类，而是机器可识别的层级结构——每个界面点必须且只能被一个 L1 覆盖，互斥性由编译管线强制执行。

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

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

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

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

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

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

在演示环境中，系统以三栏卡片展示同一个 Alert 在不同覆盖层下的语义重绑定：transactional 域为”阻断器”（红色脉冲 + 八边形 + 必须二次确认），observational 域为”信息条”（蓝色静态 + 可自动消失），navigational 域为”路径提示”（绿色静态 + 箭头图标）。下方表格展示 6 个语义绑定的完整注册信息，每行包含术语 ID、所属覆盖层、语义绑定、约束注入、跨层禁止五列。这证明了”同一个词在不同场景下意思不同”不是文档说明，而是字典中的强制绑定——机器查询时返回的语义是唯一的。

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

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

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

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

在演示环境中，系统以 6 张场景卡片展示 SCN-001 ~ SCN-006 的完整语义方案，每张卡片标注场景 ID、覆盖层、语义绑定组合、组件组合、文案约束、约束注入。点击 SCN-001 展开后，左侧显示字典返回的 YAML 格式完整方案，右侧显示设计师获得的”可直接执行”摘要。这证明了场景映射不是参考案例，而是可直接引用的生产资产——设计师查询即得，无需重新发明。

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

3.4 注册纪律

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

1. 唯一性： 全组织同一术语坐标系，任何团队不得维护平行的”私有字典”。
2. 强制性： 所有 YAML 契约必须引用字典中的已定义项，不可自创覆盖层或绑定；semantic_domain 的值必须在字典预定义列表中，非法引用在编译前置校验时直接阻断。
3. 先注册、后引用： 字典没有的，先走字典变更流程注册（快照证据 → 诊断归档 → 候选模式 → 评审入典），再引用。不为想象中的需求提前定义语义。

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

在演示环境中，系统以左右对比展示合法引用与非法引用的处理结果：合法引用（color_token: “status.critical”）编译通过；非法引用（color_token: “status.danger”）被 CI 阻断，输出错误码 dictionary-reference-not-found，提示”请先走字典变更流程”。这证明了”先注册、后引用”不是流程建议，而是机器强制执行的注册纪律——非法引用在编译前置校验时直接阻断，PR 无法合并。

推演条件： 接入生产环境后，注册纪律需接入 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 并附迁移指引；旧契约可继续引用旧版本字典（多版本共存，编译时按契约声明的字典版本解析）。

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

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

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

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

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

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

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

边界声明

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

附录

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

https://2436041978-ops.github.io/semantic-pipeline/mechanism/01-token-dictionary/semantic-dictionary.html

角色专题 ①｜设计师与产品经理：https://www.yuque.com/u222739/why7ts/nlwd1q32ny08n317

阶段一 Guard 结构化诊断：https://www.yuque.com/u222739/why7ts/lzwfwmg2iwde0qfw

组件语义快照：https://www.yuque.com/u222739/why7ts/eh9r40xm1wwku0os

三层判定模型：https://www.yuque.com/u222739/why7ts/rdyspgtkuky50zie

6 个漂移模式：https://www.yuque.com/u222739/why7ts/rwlzmucm3lgxzm10

语义域：https://www.yuque.com/u222739/why7ts/qxep0yb6b98uwkng?singleDoc#%20《②%20语义域：组件是空容器，语义由场景定义》

语义规范体系：https://www.yuque.com/u222739/why7ts/ugxdg4go2t7tlf9l

YAML 契约：https://www.yuque.com/u222739/why7ts/orfwe0f15ga79wdg

跨层禁止：https://www.yuque.com/u222739/why7ts/ko79ri1t7pxkq9wx?singleDoc#%20《②%20跨层禁止：机器如何拦截非法语义绑定》

语义字典：https://www.yuque.com/u222739/why7ts/kw7qgel1uio0nk2g

编译管线：https://www.yuque.com/u222739/why7ts/yvrpvhwawyb9b54u

语义规范体系：https://www.yuque.com/u222739/why7ts/ugxdg4go2t7tlf9l

Token 层差异：https://www.yuque.com/u222739/why7ts/to224eewapfpigp9?singleDoc#%20《①%20Token%20层差异：从颜色值到语义状态的三层跃迁》