语雀 AI 写技术文档总跑偏 / 是提示词没给结构还是知识库没挂对？

语雀 AI 写技术文档跑偏，通常是两类原因叠加：一是提示词没给输出结构，模型每次自由发挥；二是知识库挂进去的文档本身是旧版本，模型照抄了过期内容。判断顺序建议是先固定同一段需求做提示词对照，再逐篇核对知识库文档的版本信息，最后用一篇已知结论的旧文档验证 AI 是否在照抄错误内容。这三步都能在语雀页面和输出文本里直接看到结果，不需要猜测模型内部行为。

如果同一段需求换两版提示词后输出结构明显变稳、术语统一，问题主要在提示词；如果两版都稳定地把旧版本号、旧字段名写进正文，问题在知识库挂的文档。建议先做提示词对照，再核对知识库文档的更新时间和正文版本信息，最后用一篇已知结论的文档验证 AI 是否照抄错误内容。能确认的只有文档版本、引用命中和输出文本，模型内部取舍无法直接观测。

用同一段需求跑两组提示词，把输出并排贴出来

先固定需求文字，不改一个字，只改提示词里有没有结构和术语约束。A 组只给需求：

请根据知识库写一篇「下单接口」的技术文档。

B 组额外给出输出小节顺序和术语约定：

请根据知识库写「下单接口」技术文档，按以下小节顺序输出：
1. 接口用途与适用场景
2. 请求方式与路径
3. 请求参数（表格：字段名 | 类型 | 是否必填 | 说明）
4. 返回字段（表格，表头同上）
5. 错误码
6. 调用示例
术语统一使用：订单(order)、下单(placeOrder)、超时(timeout)。
知识库里没有依据的内容标注「待确认」，不要自行补写。

两次生成后，把两份输出贴在同一篇语雀文档的两个代码块里并排看，重点观察这几点：

小节顺序是否一致，A 组是否出现小节缺失或前后调换。
同一个概念有没有两种叫法，例如正文里 order、orderInfo、订单混用。
是否出现知识库里根本没有的字段、错误码或参数默认值。
不确定的地方被写成肯定句，还是被标注为「待确认」。

如果 B 组在这四点上都比 A 组收敛，说明相当一部分偏移来自提示词缺少结构约束，可以继续往下加约束；如果两组都稳定地写出旧版本号，那就不是提示词的问题，进入下一步查知识库。

检查被引用的知识库文档是不是旧版本

这一步要确认 AI 是不是照着过期内容在写。做法是逐篇核对，不要只看更新时间：

在语雀知识库页面打开被引用的文档，看页面上的编辑时间和编辑记录，记下时间点。
翻到正文里出现的版本号、接口路径、字段名、错误码，逐条和当前实际在用的代码、配置或接口约定对照。
如果正文里的版本信息与当前不一致，把这篇文档移出该知识库，或加上「已过期」标记，并挂上确认过的新版文档。
重新跑一遍前面 B 组提示词，看旧版本号、旧字段名是否还出现在输出里。

需要注意，语雀里文档的编辑时间变新，未必代表内容是新的，可能只是改了排版或标题。判断依据应该是正文里的版本号、字段名、路径这些具体信息，而不是时间戳本身。另外，如果同一主题在知识库里存在新旧两篇，建议只保留一篇，否则引用命中哪一篇是随机的。

把术语表和输出结构写进提示词

术语不一致，最省事的办法是在提示词里直接把术语表贴进去，而不是指望模型从文档里自动统一叫法：

术语表（必须严格遵守，同一概念只允许一种写法）：
- 订单 = order，不要写成 trade / orderInfo
- 下单 = placeOrder，不要写成 createOrder / submitOrder
- 超时 = timeout，不要写成 timeOut
- 用户 = user，不要写成 member / customer

结构约束同样要写成可判断的措辞，而不是含糊要求：

输出格式约束：
- 只使用以下小节标题，顺序不可调整：用途 / 请求方式 / 请求参数 / 返回字段 / 错误码 / 示例
- 参数和返回字段用表格输出，表头固定为：字段名 | 类型 | 是否必填 | 说明
- 每节控制在合理长度，写不出依据的内容统一标注「待确认」
- 全程使用上面术语表中的叫法

不该写进提示词的是那些无法判断是否满足的形容词，例如「专业一些」「详细一点」「通俗易懂」「适当展开」「结合业务实际情况」「尽量全面」。这些词每次都能被理解成不同结果，反而让输出更不稳定。把「详细」换成「每个字段必须有说明列」，把「专业」换成固定的表头和术语表，约束才落得下去。

拿一篇已知结论的旧文档做对照验证

前两步做完还不放心，可以用一篇结论明确、且你知道正确写法的旧文档来验证 AI 是否照抄错误内容：

挑一篇旧文档，其中包含你明确知道的错误或过期结论，例如某个字段其实一直是必填、某个错误码已经废弃。
先人工写出正确结论，一句话即可，例如「订单金额单位为分，是整数」。
把这篇旧文档挂进知识库，用同一段需求让语雀 AI 生成文档。
逐句对比 AI 输出和人工写下的正确结论，标出偏离位置。

如果 AI 照抄了旧文档里的错误写法，说明知识库污染确实存在，改提示词解决不了，必须先把这篇文档替换或下架；如果 AI 在提示词没有明确要求的情况下写出了正确结论，反而照抄了旧文档，也可以判断出模型在这个场景下更依赖知识库内容而不是自身判断。验证结果只对当前这篇文档和这段提示词成立，换一篇文档需要重新做一次对照。