AI语义层设计工作流：从诊断到YAML契约的落地规范

上一篇我讲了"翻译能力"是什么，不是让你转岗，而是把你已经在做的语义判断，从"口头提醒"变成"机器可执行的规则"。但"能力"停留在认知层还不够。这篇我把"翻译能力"落地为一套可复用的工作流：从发现语义问题、到写成YAML契约、到验证规则生效，每一步都有判断逻辑和质量门槛。这不是"岗位说明书"，是"操作手册"，无论你现在的title是什么，只要你已经在做"把设计意图翻译成规则"这件事，这套规范就是为你写的。

开篇：你不是新角色，你已经在做这些

如果你正在做这些事，你已经是语义层设计师：

☐ 你曾因为”AI 生成的按钮颜色不对”而手动改稿

☐ 你曾写过”这个场景下不能用红色”的规范文档

☐ 你曾和前端争论”严重”和”Critical”到底用哪个

☐ 你曾发现设计稿和上线效果在”情绪权重”上不一致

☐ 你曾试图用一份文档让全团队理解”高危操作必须二次确认”

如果你勾了2项以上，你已经在做语义层的工作，你需要将零散的判断变成可复用的规范。

关于“专人专岗”的诚实说明：

前期团队小、规则少时，设计/前端/产品共担完全可行。但当同一条规则需要第3次人工同步、或者两个团队对”严重”的定义开始互相覆盖时，就是复杂度溢出的信号。继续共担，三个角色来回翻译的损耗，高于一个人统一写规则的成本。

本文默认”有编译管线支持”展开，但每个环节都标注了”无工具时怎么做”。

人机分工：机器跑80%，人做20%

在深入下面每一个Step之前先看一张总图。这条工作流不是”一个人做10步”，而是”机器自动跑9步，人只在6个决策点介入”。

关键认知：专岗的成本不是“多一个人干更多活”，而是“一个人做机器做不了的事，机器把重复劳动跑完”。

机器自动跑（约80%工作量，Phase 0推演口径：基于规则引擎可自动化项与需人工判断项的比例估算，接入真实环境后按实际工时校准）

第一部分：语义层设计师的三段工作流

三段工作流对应 Guard（诊断）→ Contract（定义）→ Verify（验证）。每一步都标注了”机器自动跑”和”人需要决策”的分界。

Guard 语义问题诊断

核心：把“我觉得不对”变成机器可归档、可匹配的记录。

Step 1：采集，区分语义问题 vs 视觉问题

人做决策：

判断标准：

• 颜色不对、间距不对、字体不对 → 视觉问题 → 走视觉走查流程
• 用户看到界面后做出了错误的行动决策 → 语义问题 → 进入本流程

无工具时： 用文档模板手动记录，发给语义规则负责人归档。

（本文只列填写要求，6字段完整定义后续会在主题行⑥《快照与模式诊断》中陈述）

Step 2：归类，匹配已知模式或触发新模式

机器自动跑：

输入6字段记录 → 机器按 component_type + user_confusion 关键词匹配已知模式 → 输出置信度分数。

人做决策：

无工具时： 人工对照6类模式卡片判断，由语义规则负责人手动归档。

（三层判定模型完整机制后续会在主题行⑥《快照与模式诊断》中陈述）

Step 3：定级，确定缺失的语义令牌

人做决策：

基于Step2的匹配结果，明确回答：这个组件缺了什么语义维度？

质量门槛： 诊断结论必须说明”缺了什么语义令牌”，不能只描述现象。

Contract 语义规则定义

核心：把诊断结论翻译成机器可读的YAML契约。

Step 4：查字典，确认语义令牌已注册

人做决策：

打开语义规范手册 → 搜索需要的语义令牌 → 判断：已注册 / 未注册。

• 已注册（如 status.critical 已存在）→ 直接引用
• 未注册（如团队需要新增 status.neutral）→ 走新增申请流程

关键约束：禁止自创语义令牌。 所有 semantic_domain、semantic_tokens 中的令牌必须在手册中有定义。

无工具时： 用共享文档维护手册，人工确认是否存在。

（语义字典完整定义见主题行①《语义令牌》与《语义字典》和主题行②《语义域》）

Step 5：写契约，填写7个冻结字段

人做决策：

基于诊断结论，填写YAML契约的7个字段：

关键设计：令牌层与呈现层分离

无工具时： 用文本编辑器手写YAML，人工对照检查清单校验。

（YAML契约7字段的完整写作指南见主题行④《语义契约》，本文只列操作要求）

Step 6：自检，10项检查清单

机器自动跑（有工具时）： 编译前置校验5项自动检查。

人做决策（无工具时）： 逐项勾选。

Step 7：提交 → 机器自动编译与分发

机器自动跑：

人需要做的：

关键认知： 这一步不需要人”盯着”。人只在异常时介入，正常流程机器全自动。

无工具时： 人工复制YAML → 手动发给前端/AI工程师/DesignOps（易遗漏，不推荐长期运行）。

（编译管线的技术细节见主题行⑤《编译管线：一份YAML契约编译出4种格式》）

Verify 规则生效验证

核心：证明“规则真的被消费了、真的拦住漂移了”。

Step 8-10：机器自动验证 → 人定期看面板做决策

机器自动跑（持续进行，不需要你主动触发）：

人定期查看的：

人主动做的（只在异常时）：

• 沉默规则处理：连续30天零消费 → 判断原因 → 唤醒修订 或 归档废弃
• 基线迭代建议：多个团队对同一条基线提出扩展申请 → 评估是否升级

无工具时： 人工询问各团队”这条规则你用了吗”，手动统计走查覆盖率。

第二部分：六类高频场景决策树

核心：不讲故事，给判断逻辑，“遇到 X 情况，先查 Y，再决定 Z”。

场景 1：错误状态语义混乱（ERR-001）

触发条件： 多种错误共用同一种视觉表达（如全是红色），用户无法判断后果严重程度。

质量门槛：

• 每个级别在视觉、文案、行动上都有明确区分
• 用户行动必须与后果严重程度匹配（fatal 不给“重试”，因为对话已丢）
• LLM约束必须可机器校验（禁止“文案要友好”，必须“禁止仅显示‘出错了’”）

场景 2：高危操作未约束（ACT-001）

触发条件： 不可逆操作按钮与普通操作按钮使用相同样式，误触风险高。

场景 3：过程状态认知不可见（PRO-001）

触发条件： AI执行多步任务时，只有”Searching…”等动作标签，用户不知道AI处于什么认知阶段。

场景 4：边界动作权利不清（BND-001）

触发条件： 系统拒绝用户时，”拒绝请求”和”终止会话”在界面上无法区分。

场景 5：告警文案语义降级（ALR-001）

触发条件： AI生成文案时，关键术语被同义词替换，导致语义权重降低。

场景 6：信息状态权重未对齐（INF-001）

触发条件： 紧急安全提示和普通功能通知使用相同视觉权重，用户无法区分优先级。

第三部分：翻译能力的四个层级（与上篇呼应）

核心：能力分级 → 自检门槛 → 升级路径。

升级门槛（不是时间，是能力标准）：

• L1→L2： 能独立完成6字段记录，且诊断结论被团队认可
• L2→L3： 能独立编写完整 YAML 契约，且通过编译前置校验
• L3→L4： 能独立设计对抗用例集，且误报率 < 5%
• L4： 能基于消费追踪数据，独立提出规则迭代建议并被采纳

关键认知： 不需要一次性做到 L4。L3 需要组织工具支持，不是个人能力问题。团队组件数 < 20 时，做到 L2 即可；组件数 > 50 时，需要推进到 L3-L4。

第四部分：与上下游的协作界面

核心：对方问什么 → 你怎么回应 → 你给什么交付件。

与设计师 / 产品经理

与前端工程师

与 AI 工程师

与 DesignOps

与管理层

第五部分：常见陷阱与纠偏

核心：不是“我第一次踩坑”的故事，而是“即使你有经验也会遇到的结构性问题”。

附录 A：交付件模板集

以下7个模板的字段定义和检查逻辑已在正文各章节完整给出，当前处于Phase 0（概念验证阶段）。标准化模板文件将在后续整理发布，当前可直接基于正文中的字段定义自行搭建。

附录 B：口径溯源表

过去大半年时间，我围绕”把设计规范写成代码格式”这件事，写了9个主题行的方法论文章，从语义令牌怎么编码，到语义域怎么划分，到约束怎么让机器读懂，到YAML契约怎么写、怎么审、怎么编译、怎么验证。每个主题行都在回答一个”为什么”：为什么这样定义、为什么这样校验、为什么这样分发。

而这篇工作流规范，是把那9个主题行的方法论翻译成了日常操作。

你在这篇规范里看到的每一个字段、每一项检查、每一个判断逻辑，都不是我临时拍脑袋写的，而是有明确的方法论出处。我把这些出处整理成下面这张表，方便你追溯：如果某个操作你觉得”为什么必须这样做”，这张表会告诉你答案在之前的哪篇文章里。

如果你发现某个操作在这篇规范里写得很死，但你的实际场景需要灵活处理，欢迎你对照溯源表去看原文的机制设计，那里通常留了”团队级扩展”或”豁免通道”的口子。规范是底线，不是天花板。

附录 C：延伸阅读

这篇规范只回答一个问题：“我现在该怎么做”。

但每一个”该这么做”的背后，都有一个”为什么该这么做”。那些”为什么”分散在 9 个主题行的文章里——有的是关于语义层的设计原理，有的是关于机器校验的工程机制，有的是关于组织治理的落地路径。

我把这些”为什么”的出处整理在下面这张表里。如果你：

• 刚接触这个领域，建议按表里的顺序读，从 ① 语义令牌开始；
• 遇到具体疑惑，比如”为什么 color_token 不能写死色值”，直接跳到对应主题行找原理；
• 已经在实践，发现这套规范在你团队里有”水土不服”的地方——我特别欢迎你来聊。这套规范不是标准答案，它是我基于当前观察写出来的”最小可行集”。你的场景、你的踩坑、你的变通，可能会成为规范下一版的迭代来源。

上篇关联：《意图设计的翻译能力》= 能力宣言篇

附录 D：一页纸速查表

本文由 @阿基拉de_Akir 原创发布于人人都是产品经理。未经作者许可，禁止转载

题图来自Unsplash，基于CC0协议