你的 AI 功能说明文档是运行时依赖，而非营销文案

我上个季度合作的一个团队发布了一个 AI 助手，并附带了一整套完备的支撑文档：一个提醒 AI 可能会生成不准确结果的产品内工具提示（Tooltip）、一篇题为“助手如何工作”的帮助中心文章、一份处理升级问题的内部支持操作指南（Runbook），以及一份列出了底层模型、助手可调用的工具及其覆盖的数据领域的公开模型卡（Model Card）。发布过程非常顺利。六个月后，提示词（Prompt）被修改了 14 次，模型在不同层级间进行了切换，拒绝行为（Refusal Behavior）发生了微妙的变化，增加了两个新工具，一个工具被废弃但未从提示词中移除，语言设置也从仅限英语扩展到了 9 个语种。

每一份文档都出错了。并非灾难性的错误——而是那种一句话半真半假、描述的功能与模型实际表现不再匹配、记录的拒绝模式在新模型中从未触发、或者帮助文章里出现的工具名称助手根本不会调用的那种错误。这类错误会产生持续不断的令人困惑的支持工单，当 AI 做了文档说它不会做的事情时会导致客户信任倒退，并且——因为公司在受监管的垂直领域销售——还会产生一个微小但真实的合规漏洞，而 AI 团队中没有人想到要跟踪这一点。

团队的反应说明了一切。AI 工程师感到惊讶：他们一直在修改提示词和工具，因为那是他们的工作；而帮助中心的文案属于其他人的仓库。支持团队感到恼火：他们根据发布规范编写了操作指南，却没人告诉他们规范已经变了。法律团队感到担忧：提交给合规审查委员会的模型卡已不再描述当前的实时系统。产品经理（PM）负责功能，但不负责相关的文档，所以当问到“谁该为此负责”时，四个不同的人指向了另外四个不同的人。

这一切背后的架构错误在于，将说明文档视为营销文案，而它实际上是该功能信任契约（Trust Contract）的一个运行时依赖（Runtime Dependency）。文档并非与系统分离——客户阅读文档并形成预期，系统必须满足这些预期，否则信任就会瓦解。当提示词的漂移速度超过文档更新速度时，一旦这种漂移超出了文档的容差，信任契约就会立刻破裂，而且团队中没人注意到这一点，因为文档在心理上被归类为“沟通工作”而非“生产表面”。

漂移目录：究竟什么变陈旧了

AI 工程中传统的漂移讨论是关于模型的：提示词会漂移，检索索引会漂移，评估集会失效。文档漂移问题有着不同的形态和更长的清单。以下是我见过的最容易失去同步的表面，以及每种表面在产生可衡量的客户侧负面影响之前的半衰期。

产品内免责声明（“AI 可能会产生不准确的结果”）看起来是风险最低的表面，但在投诉期间，它是最常被客户引用回馈给团队的内容。当你更换底层模型且新模型对幻觉更加自信时，模板化的免责声明就不再匹配用户刚刚经历的失败模式——而“你说过它可能不准确”就不再是一个充分的回答。

帮助中心文章（“助手如何工作”）用营销散文描述功能。它会说“助手可以帮助你起草邮件、总结文档，并在你的工作区中查找信息”之类的话。这句话在写下时是正确的。经过三次提示词编辑后，由于数据丢失防护（DLP）的原因，助手被告知拒绝某些总结请求；由于审计结果，跨工作区搜索被缩小到用户自己的工作区；而邮件起草功能则增加了原文章中没有的语气策略。每一个编辑都是正确的，但文章现在有三处错误。

支持操作指南（“如果客户询问 AI 为什么说 X”）是杠杆作用最大的漂移表面，也是团队最不常跟踪的。支持团队每周会根据此操作指南进行数百次回复。当指南说“助手无法访问财务数据”，而提示词随后被扩展以包含财务摘要工具时，每一封引用该指南的支持回复都在与实时系统相矛盾。

公开模型卡或透明度说明是单位文字法律分量最重的表面。它指明了模型、数据领域、人工监督协议、拒绝类别以及关于训练和部署的可审计声明。随着《欧盟 AI 法案》的透明度义务于 2026 年 8 月生效，一份描述了公司已不再运行的系统的模型卡将成为监管机构可以书面追究你责任的文档——不是因为系统做错了什么，而是因为监管机构批准的系统不是生产环境中的系统。

CODEOWNERS 的隐喻是更高层级的表面。大多数团队对提示词仓库（AI 团队）、帮助中心（内容团队）、模型卡（法律/合规）和支持操作指南（支持运营）分别设有 CODEOWNERS（代码所有者）。一个本应扩散到所有四个仓库的更改只触达了其中一个，其他三个则在沉默中漂移。

为什么这种偏离被察觉的时间比你想象的要长

这种偏离之所以会不断累积，是有结构性原因的。在纯代码系统中，当一个函数签名发生变化时，调用点就会崩溃，构建系统会捕获到这个错误。但在 AI 系统中，当提示词（Prompt）发生了变化而帮助中心的文章没有更新时，什么都不会崩溃。构建依然通过，评估（Eval）依然运行，客户依然在使用该功能。这种偏离对于团队建立的每一项自动化检查来说都是不可见的——因为团队建立的是针对“提示词 vs 评估”偏离的检查，而不是“提示词 vs 文档”偏离的检查。

第一个信号通常以一个零散的支持工单形式出现：“文章说助手可以做 X，但它拒绝了。”工单被关闭，并附带一份礼貌的解释，说明功能已经改变。没有人去更新文章，因为支持代理的团队中没有人拥有这篇文章的所有权。于是，文章继续宣称可以做 X。两周后，关于同一主题的另一个工单又出现了。一个季度后，支持团队就有了一小部分但持续不断的由文档偏离驱动的工单，而他们已经默默地将其吸收为业务成本。

第二个信号——也是通常会触发组织严肃对待该问题的信号——则更加响亮。一位记者在关于公司的报道中引用了模型卡（Model Card）或透明度说明。公关团队意识到被引用的声明与现有的在线系统不再匹配。现在，文档偏离与公关周期挂钩了。或者，在受监管的环境中，合规性审计要求团队证明生产环境中的系统与模型卡中的系统相匹配。审计员比团队更早发现了差距，对话很快就会变得非常昂贵。

根据我的经验，从偏离开始到被察觉之间的滞后时间通常在 3 到 9 个月之间。提示词仓库可以预测这一点：如果你能看到提示词、工具清单（Tool Manifest）和模型选择的差异（Diff）历史，你就可以计算出偏离面，你就会知道——精确到段落——你的帮助中心文章和模型卡中哪些内容不再描述正确。

将解释文档视为代码

解决方法不是写出更好的文档，而是将解释面（Explainer Surface）视为一个运行时产物（Runtime Artifact），由提示词和工具相同的单一事实来源（Source-of-truth）拥有，并从中衍生出人类可读的文案。

在实际操作中，这看起来像是一个提示词清单（Prompt Manifest），其中列出了模型、系统提示词部分、带有易读描述的工具名称、带有易读解释的拒绝类别、助手运行的数据域以及人工监督升级路径。清单是事实的来源。帮助中心文章、支持操作手册（Runbook）和模型卡则是从清单中插值的模板。当清单发生变化时，模板会自动重新生成，如果重新生成的文档没有在同一个 PR 中经过审核，CI 步骤就会使该更改失败。

这与上一个十年中通过 OpenAPI 规范生成文档来解决 HTTP API 问题的模式完全相同：停止手动编写定义在别处的接口描述。对于 AI 功能来说，新颖之处在于接口是提示词和工具的组合，而不是方法签名，而且面向客户的描述包括拒绝行为和置信度校准等内容，这些在 REST 中没有对应物。

关于在提示词旁边进行版本控制的内容的一个实际构想：模型标识符和层级、带有语义标识符的命名系统提示词部分（这样“定义语气的策略”就可以与“定义安全政策的策略”分开寻址）、包含名称和工具用途及访问数据的一段话易读描述的工具注册表、带有用户端理由的拒绝类别注册表、数据域注册表、人工监督协议（谁可以在什么时间表下覆盖什么）以及语言区域注册表。这就是清单。它可能已经隐式存在于团队的提示词仓库中——只是还没有被提取为一个结构化的产物。

帮助中心文章是一个消耗工具注册表和拒绝类别注册表的模板。模型卡是一个消耗模型标识符、数据域注册表和人工监督协议的模板。支持操作手册是一个消耗拒绝类别注册表和一组精心策划的工具故障叙述的模板。当提示词清单发生变化时，CI 流水线会重新生成每个模板，运行差异对比，并阻止合并，直到内容负责人批准新的文案。

必须落地的组织变革

技术上的修复并不需要很长时间。更难的改变在于组织层面。AI 团队拥有提示词清单，内容团队拥有帮助中心的语调，合规团队拥有模型卡的声明，支持团队拥有操作手册的风格。目前，他们中没有一个人负责这些文档与在线系统之间的一致性。

行之有效的组织模式是：为解释面指定一个单一负责人——通常是 AI 功能的产品经理（PM）——并将该部分放入 AI 团队的 CODEOWNERS 部分，以便每个涉及提示词清单的 PR 都需要内容审阅者的审核。添加一个 CI 任务，当提示词或工具注册表发生更改而没有相应的文档更新时进行标记。安排季度审计，将在线系统的清单与模型卡进行对比，并将任何偏离视为合规工单，而不是内容工单。为支持团队的 AI 问题处理设定一个“记录文档”政策，以便回答客户关于助手问题的代理阅读的是当前的规范，而不是团队 Wiki 中发布首日的规范副本。

这种形式与之前出现的每一个“将 X 视为代码”运动的形式完全相同——基础设施即代码（IaC）、政策即代码、安全即代码。每一个运动最初都是内容团队在编写关于工程团队控制的系统的散文，随后发生了可以预见的偏离，并最终通过让散文与系统本身建立程序化关联而得到解决。解释即代码（Explainer-as-code）模式也是同样的策略，应用于大多数 AI 团队尚未意识到其作为运行时依赖项的领域。

本周要做的事

如果你已经上线了 AI 功能，在下一次提示词 (prompt) 变更发布前，有三件事值得去做。

首先，进行盘点：列出所有面向客户或合规要求的文档，这些文档描述了该功能的能力、拒绝行为、模型、工具或数据范围。这个清单通常比团队预想的要长。工具提示 (Tooltips)、帮助文章、运行手册 (runbooks)、模型卡 (model cards)、透明度说明、销售赋能课件、为企业潜在客户填写的安全问卷，以及网站自带的 AI 聊天机器人在访客询问助手时的回答 —— 所有这些都是信任契约的一部分。

其次，对比 (diff) 每一份文档与当前的提示词清单。对于每份文档，标注出哪些表述依然正确，哪些已经过时，以及哪些虽然在技术上正确，但由于上下文的变化而产生了新的误导性。第三类通常规模最大，且最具破坏性。

第三，确定什么是事实来源 (source of truth)。现实的答案是提示词仓库 (prompt repo) 及其旁边的一个小型结构化清单。其他所有内容都应模板化。在这方面领先六个月的团队已经在这么做了；而落后的团队正在为这一差距付出代价：支持工作量增加、审计发现问题，以及客户信任的缓慢侵蚀 —— 这种侵蚀悄无声息地积累，直到一次糟糕的意外事件让它彻底暴露。

说明文档不是营销文案。它是客户对你 AI 功能的心智模型，并以文字形式固定下来。当功能发生变化而文档没有更新时，客户的心智模型就出错了。下一次当功能的表现与客户持有的模型不符时，你就在透支原本想通过文档积累的信任。在 2026 年赢得信任竞赛的团队，将是那些文档失效速度不快于提示词仓库预测速度的团队 —— 这意味着文档和提示词仓库必须是同一个东西，只是渲染方式不同。