作者是AI时协议要唯一规范答案

更新于 2026-06-11

**产物的作者是谁，决定协议该怎么设计。** 作者是人 → 友好 = 好记、可推断；作者是 AI skill → 友好 = **低歧义、唯一规范写法、可自动校验**。同一份协议里并存多套等价写法（别名），对人只是麻烦，对 AI 是**随机性**：它会随机挑一套，而且漏字段没人拦。

一、前提：模板作者不是人

本项目的模板 HTML/CSS 不由人编写，而是由 AI 通过 skill 生成后直接写入数据库。所以不能按人类直觉评估「协议好不好用」（「item.* 挺通用啊」），要按 AI 的失败模式评估：

  • AI 不怕字段名抽象，怕同一语义有多种写法（basics.name 与 profile.name 都能用）。
  • AI 不怕规则多，怕规则隐含（哪些字段必须预留，文档里没写）。
  • AI 不会因为漏一个字段而察觉 —— 漏了不报错，页面只是空白。

二、唯一规范答案：内部兼容，对外只暴露一套

做法是分层，不是删代码：

render / 数据层：继续兼容多套别名（旧模板已在用，不能破坏）
skill 层：只告诉 AI 一套推荐写法

即「兼容 ≠ 推荐」：老写法继续能渲染，但不再出现在 skill 的规范里。这个状态要显式命名成 deprecated，而不是含糊的「也可以这样写」——deprecated = 还能用 + 不要再生成 + 未来可迁移。

三、required 有两种含义

「必含字段」不能笼统地叫 required，要拆开：

名称约束谁含义
content_required用户表单简历内容必填 —— 实际基本没有强必填，简历可以是空的
template_coverage_requiredAI 生成的模板模板结构里必须预留这些 slot

关键区别：用户没填 item.link，渲染为空没问题；但模板 HTML 里根本没有 item.link 的 slot，用户以后填了也永远显示不出来。所以「必含」约束的是模板能力覆盖，不是用户内容填充。

四、闸门放在校验器，不放在 prompt 记忆

靠 skill prompt 记住「必须覆盖哪些字段」不可靠；可靠的是入库前跑 coverage validator，漏字段直接报错。协议文档（机器可读 JSON）应被 validator 与 skill 共同消费 —— 契约被消费才不是摆设。

06-11 实证：校验器只查了一半。 insert-template 当时只校验 required slot bindings（如 item.title / item.meta / item.link），不拦截三件事：HTML 里用了旧私有语义 class（.pro-item-title）、CSS 里继续写私有语义 selector、CSS 里把 renderer-owned 的底座规则（空值隐藏、contact spacing、正文行高）又塞回来。只要校验器不管这些，未来导入模板仍会重新污染数据库 —— 说明「把闸门放进 validator」不能只做字段覆盖，还要做命名与职责边界的校验。

五、三类文件：真源 / 契约 / 说明

给 AI 消费的协议，文件分三层，并明确谁是真源：

运行代码      → 系统真正执行；与文档冲突时以代码为准（真源）
机器可读契约  → JSON：字段清单 + canonical / required / deprecated；给 skill、validator、测试消费
人类说明文档  → MD：写法规范、示例、禁止项

判据：「真实使用」= 运行时会 import/执行，或被 validator 读取；否则只是说明。

六、落地顺序

先补 AI 的输入与校验（协议文档 → skill → coverage 校验 → 批量修存量模板），render 层的命名重构延后。理由：漏渲染的根因是「skill 不知道有哪些字段、也没有校验」，不是 render 机制本身。

相关