前阵子我们组内部文档上线后第二天隔壁同事照着示例代码初始化客户端跑了十分钟一直报“权限校验失败”最后翻源码才发现示例里漏了一行关键调用。这种问题靠人工校对很难抓出来——语法没错、格式也没错错在业务语义层面。也就是从那时候起我开始认真琢磨一件事技术文档上线前能不能让 AI 先做一轮审稿把这些“人眼看不见但真会造成事故”的硬伤提前筛出来。后来我一共往这个方向试了三版方案从手动粘贴 prompt到写脚本批量审再到把审稿结果接进发布流程前前后后折腾了挺久。这篇文章就是把整套思路和踩坑过程整理出来给同样在做技术写作、内容平台、开发者文档或内部知识库的同学一个可以直接落地的参考。我不会只给一个 prompt 让你复制而是会把为什么这样设计 prompt、怎么约束 AI 不乱说、代码示例怎么校验、以及批量审稿时容易忽略的问题都尽量讲透。1. 审稿不止校稿技术文档的硬伤为什么总被漏掉很多人一说到“文档审稿”第一反应是检查错别字、标点、格式统一。这些当然重要但对于技术文档来说它们远不是致命问题。真正的硬伤是什么是“照着文档做做不出来”。1.1 人工审稿的两个典型盲区我复盘过几次线上事故发现人工评审主要卡在两个地方。第一评审者的精力和知识背景有限。文档涉及多个模块时让一个人逐字检查逻辑一致性几乎不可能做到。大家通常会看有没有错别字、格式是否整齐但对“这段描述和另一章的参数表是否冲突”这种跨章节问题默认依赖作者自己负责。可作者恰恰因为太熟悉自己的实现经常看不到表达上的歧义和对新手的误导。第二人很难在“读文档”的同时“跑文档”。尤其是含代码示例的文档语法正确不代表能运行能运行不代表符合当前 SDK 版本。人工评审最多检查缩进和明显的拼写错误真正要验证代码是否正确得把示例摘出来实际执行这在一轮评审里往往没有时间做。所以技术文档的审稿逻辑天然应该分成两层一层是“语言层”检查表达是否清晰另一层是“语义层”检查描述是否与实际实现一致、示例是否可运行、前后文是否有矛盾。AI 审稿的重点恰恰应该放在第二层而不是第一层。1.2 AI 审稿能覆盖的检查维度我在实际设计审稿规则时把检查项拆成了五个维度。这里直接列出来后面设计 prompt 时全部用得上检查维度具体检查内容典型问题示例事实一致性文档描述与真实 API、参数、返回值是否一致文档说接口返回code0表示成功实际返回code200逻辑一致性同一文档内不同章节、步骤、参数表之间是否有矛盾前面说超时时间为 30 秒后面的配置示例里却写 60 秒代码可运行性示例代码是否完整、依赖是否齐全、调用顺序是否正确示例缺少初始化步骤或使用了已废弃的参数名表达歧义性是否存在模棱两可、可能被误解的表述“建议使用默认配置”没有说明默认配置到底指什么版本与兼容性文档是否与当前 SDK、依赖库版本匹配文档还写着旧版字段名新版本已经改名这五个维度里事实一致性、逻辑一致性、代码可运行性是最容易通过 AI 抓出问题的因为 AI 擅长比对上下文和知识库中的模式表达歧义性则相对主观需要靠人工再做判断。1.3 必须先想清楚AI 审稿的目标不是替代人在开始做之前有一条差点让我走偏一开始我总想让 AI 像人一样“判断对错”后来发现方向错了。AI 审稿最适合的定位是“高召回率的过滤网”——它的价值是把人工容易漏掉的大概率问题捞出来哪怕捞出来的 100 条里有 40 条是误报也不要紧只要剩下 60 条是真实问题就已经赢了。如果把 AI 当成最终裁决者要求它精确到每条都正确那 prompt 会变得非常保守最后只会给出“这句话表达可以更清晰”这类正确但没用的废话。反过来让它大胆提出问题、附上证据位置再配合人工复核整个方案才走得通。2. 把审稿标准翻译成提示词一份可以直接抄的审稿指令模板想明白 AI 审稿的定位之后真正决定效果的是 prompt 怎么设计。我见过不少团队直接丢一句“帮我检查一下这篇文档有没有问题”然后拿到的结果要么是空话要么是泛泛的排版建议这其实是提示词里缺少“审稿标准”和“输出约束”导致的。2.1 审稿指令的核心结构我自己用的 prompt 有固定五段结构角色定义、任务描述、检查维度、约束条件、输出格式。每一段都有它存在的理由。角色定义是为了让模型进入“挑剔审稿人”的状态任务描述要明确是发现问题而不是修改文稿检查维度就是上面那张表约束条件是为了限制它不要瞎发挥输出格式则是为了后续脚本能解析结果。下面是一个经过实测、可以直接拿去改的模板。我把其中的变量留成了{文档内容}和{相关上下文}你可以按自己的场景替换。你是一位资深技术文档审稿人专长是发现技术文档中的错误、歧义和逻辑漏洞。 我会给你一篇技术文档的正文以及与该文档相关的接口定义、代码片段或上下文资料。 你的任务不是润色而是找出所有可能让读者误解或照着操作失败的硬伤。 请从以下五个维度逐一检查 1. 事实一致性文档描述是否与给定的接口定义、参数说明、实际行为一致。 2. 逻辑一致性文档内前后章节、步骤、参数表之间是否存在矛盾。 3. 代码可运行性代码示例是否完整、调用顺序是否正确、是否有缺失的初始化步骤。 4. 表达歧义性是否存在会让读者产生多种理解的表述。 5. 版本兼容性文档内容是否与当前依赖库版本匹配有没有明显过时的字段或方法名。 约束条件 - 只报告确定存在的问题不要给出“建议补充更多细节”这类空泛意见。 - 如果某个问题你只有 60% 的把握请明确标注置信度为低不要斩钉截铁地说它错了。 - 每一条问题必须引用原文中的相关句子或行号作为证据。 - 不要直接输出修改后的整篇文档。 输出格式Markdown ## 问题清单 - 严重级别高/中/低 - 检查维度事实一致性/逻辑一致性/代码可运行性/表达歧义性/版本兼容性 - 原文引用具体句子或代码行 - 问题描述为什么这是错的或可能误导读者 - 修正建议只给出关键修正方向不要重写全文 以下是文档正文 {document内容} 以下是相关上下文资料 {相关上下文}注意这段 prompt 里我特意写了一条约束“不要输出修改后的整篇文档”。一开始我没加这条AI 经常直接把整篇文档重写一遍不仅输出冗长而且改完之后我们根本不知道它改了什么增加了人工复核成本。改成只输出问题清单之后效率提升非常明显。2.2 上下文注入让 AI 有“据”可查AI 审稿最怕的就是凭空脑补。比如你在文档里写“调用start()函数即可”AI 如果不知道这个函数真正的签名它只能根据通识来判断很容易把正确写法误报成错误。所以我会尽可能把“相关上下文”喂给模型。最常用的是三类接口定义文件、代码仓库里对应模块的 README 或源码片段、以及该篇文档依赖的配置示例。如果你的接口定义是 OpenAPI 或 protobuf 文件直接把它作为上下文给 AI事实一致性检查会准很多。还有一个细节是上下文长度管理。文档正文加接口定义很容易超过上下文窗口我的处理思路是先让 AI 基于“文档正文 接口摘要”做第一轮检查等它列出每条问题时再针对具体问题把对应接口定义片段单独喂一次。相当于让它先有个全局印象再针对疑点做精读这样既能控制 token 开销又能提升准确率。2.3 审稿 vs 校对为什么要把两种模式分开我强烈建议不要把“AI 审稿”和“AI 校对”放进同一个 prompt。校对关注的是错别字、标点、中英文空格模型很容易陷入琐碎修改而忽略真正的逻辑问题。我的实际做法是分两条链路一条是常规的拼写和格式检查交给文本规则工具或轻量模型处理另一条才是本文说的语义级审稿交给理解能力更强的大模型处理。两条链路互不干扰结果也更容易管理。有一次我把两条合并让 AI “检查排版和逻辑问题”结果输出的 20 条问题里有 16 条是“建议在中文和英文之间增加空格”这种低级建议真正有价值的逻辑矛盾只找到 2 条。从那之后我再没有合并过。3. 置信度与证据链让 AI 少胡说、多报错AI 审稿最大的风险不是它漏报而是它“言之凿凿地胡说”。尤其当文档内容比较专业、常见模式较少时模型会倾向于把“自己不熟悉”误判为“作者写错了”。这个问题不解决审稿结果就没办法用。3.1 强制 AI 给出置信度和证据位置我在 prompt 里反复强调两件事每一条问题必须引用原文且必须标注置信度。别小看这两个要求它会把 AI 从“写作模式”拉到“审查模式”。加入“引用原文”约束后AI 如果再想当然至少要找一个能自圆其说的地方这会显著减少凭空捏造。加入“置信度”约束后低置信度问题会被单独区分出来人工复核时可以直接跳过或者快速扫一眼。实际跑下来这个机制把误报的干扰降低了大概一半。我给每条问题的置信度分了三档高、中、低。高置信度通常意味着有明确的上下文冲突或接口定义不一致中置信度意味着模型有依据但不确定低置信度一般会被我自己过滤掉不再进入人工复核流程。3.2 温度参数和采样设置也很关键同样一份 prompt把模型的 temperature 调高到 1.0 以上时它会更“发散”容易提出一些很有创意但完全不靠谱的问题调低到 0.2 以下时它会保守很多漏报率也会上升。我实测下来审稿类任务用 temperature 0.3 左右比较合适。如果你用的是支持 seed 等参数的模型建议固定随机种子这样同一篇文档多次审查的结果可复现方便对比不同版本 prompt 的效果。另外如果是英文文档可以把输出语言设在原文档语言如果是中文文档我会要求输出也保持中文因为后续人工复核的同事读起来更顺。3.3 一个真实的误报案例AI 把“正确”当“错误”有一次文档里写“进程启动后如果初始化失败进程会以退出码 1 退出”AI 报了一个高置信度问题说“应该是退出码非 0而不是具体的 1因为不同平台可能不同”。单看这句话AI 说的似乎有道理但该文档描述的是一个特定平台上的特定程序行为实际实现就是固定退出码 1AI 只是没见过这个实现而已。这个案例给我的教训是AI 善于做“通用推理”但技术文档往往是“特定实现”的说明书。所以现在凡是遇到“AI 说某个 API 行为与文档不符”这类问题我一定把真实接口定义调出来二次确认而不是直接信 AI。3.4 交叉评审用两轮结果抵消单模型的偏差为了继续压误报率我还试过让同一个模型从不同角度审两遍或者用两个不同模型各审一遍然后只看两边都指出的问题。这个方法效果不错但成本会翻倍所以我没有把它做成默认流程只在高危文档涉及支付、权限、生产环境配置上启用。你可以这样实现交叉评审第一次用“严苛审稿人”角色第二次用“谨慎工程师”角色两者 prompt 差异要足够大否则得到的结果高度一致就失去交叉的意义了。最后把两轮结果做并集同时只保留置信度都在“中”以上的交集问题。误报类型成因对策把通用模式套到特定实现模型不了解项目私有逻辑注入接口定义、源码片段作为上下文凭语感判断“表达奇怪”缺少语气和语境信息要求必须引用原文描述具体歧义把新版本行为当唯一标准训练数据更新时间差对版本类问题降低置信度人工复核4. 代码示例是高危区AI 读代码不跑代码必须与静态校验联动技术文档里最容易出事故的永远都是代码示例。AI 审稿能看代码、理解代码的意图但它本质上是“读”代码不是“跑”代码。一个示例可能漏了一行 import模型未必看得出来但执行器一跑立刻报错。所以我在整个方案里加了一条独立通道先抽代码块再做可运行性校验最后把执行器报错作为证据回传。4.1 为什么要单独做代码块校验大部分技术文档的代码块不是完整的可运行项目可能是片段、伪代码或为了突出重点删减过。直接拿去执行是不现实的所以我在实际落地时用了一个相对务实的方案把文档中所有带语言标记的代码块抽取出来针对不同语言分别处理。对于 Python、JavaScript 这类解释型语言我优先做语法编译检查和依赖解析对于可以本地执行的片段再补一轮沙箱运行。然后写一个测试脚本把代码块里的关键调用串起来跑一遍看看能否跑通核心路径。下面是抽取与校验的流程示意伪代码import ast import subprocess from pathlib import Path def extract_code_blocks(markdown_text): 从 Markdown 文档中抽取带语言标记的代码块 blocks [] lines markdown_text.splitlines() in_block False lang None buf [] for line in lines: if line.startswith(): if not in_block: in_block True lang line.strip().strip() buf [] else: in_block False blocks.append({lang: lang, code: \n.join(buf)}) elif in_block: buf.append(line) return blocks def validate_code_block(block): lang block[lang] code block[code] if lang python: try: ast.parse(code) return {status: ok, message: } except SyntaxError as e: return {status: error, message: f语法错误: {e}} elif lang bash: result subprocess.run([/bin/bash, -n], inputcode, capture_outputTrue, textTrue) if result.returncode ! 0: return {status: error, message: result.stderr.strip()} return {status: ok, message: } # 其他语言可以继续扩展 return {status: skipped, message: 未支持的语言}这个脚本只需要做一个最基础的语法校验。真正关键的地方在于这一步的结果应该作为上下文喂回给 AI让 AI 针对“执行失败”做二次定位。4.2 把执行器报错回传给 AI 做二次定位每次代码块校验报错我不会直接让执行器输出给用户而是把报错信息和附近代码块一起拼成一个“补审 prompt”让 AI 负责判断这个报错是示例代码本身的问题还是文档描述与代码之间不一致导致的问题。例如某次示例报错AttributeError: Client object has no attribute set_timeoutAI 看完报错后指出了两类问题一是示例代码写的是旧版 SDK 的调用方式二是文档里声称支持超时配置但示例里根本没演示配置步骤。这两个问题如果只靠执行器跑一遍或者只靠 AI 读一遍都不会同时发现。把两者结合起来才能实现“工具负责确定性错误AI 负责语义归因”。4.3 语言配套检查器的选择虽然大模型本身能识别不少代码问题但我还是会依赖配套工具做第一道把关。Python 我用flake8和pyrightJavaScript 用eslintJava 用checkstyleShell 用shellcheck。这些工具基本上都能覆盖大部分语法类和潜在运行时错误。我给一个具体的实操建议把静态检查结果按“错误级别”筛选只把 error 级别和 warning 级别的问题传给 AIinfo 级别全部丢弃否则上下文会被大量废话占满。4.4 为什么这个组合是必要的归根结底一句话AI 在“理解语义、定位矛盾”上远超静态工具但在“确定性校验、代码点火”上远不如执行器。技术文档审稿如果只选一边必然有死角。比如静态工具能抓住未定义变量但它抓不住“文档前后两章的示例互相矛盾”。AI 能抓住后者却又会忽略缺失的 import。所以我把两者设计成流水线静态工具先跑结果作为证据给 AIAI 再基于全文语义做综合判断。这个设计在我自己处理过的两百多篇文档里代码相关问题的实际修正率比单用 AI 或单用工具都高了一截。5. 从单篇到批量审稿流程怎么嵌进上线链路解决了单篇审稿效果之后下一个现实问题是怎么批量用起来。如果每审一篇都要人工复制粘贴 prompt那这套方案很难真正落地。所以我把审稿流程做成了三种接入形态按团队规模不同可以选择。5.1 三种接入形态命令行、CI、发布前置卡口最轻量的形态是一个命令行脚本你传一个 Markdown 文件路径脚本自动抽代码块、拼 prompt、调用模型、输出 JSON 结果。适合个人博主或者小团队临时用。第二种是接进 CI 流程文档仓库每次提交 PR 时自动跑一轮审稿把问题列表发布到 PR 评论区。这种方式的好处是审稿和代码评审同步作者改文档时直接能看到问题。第三种是发布前置卡口文档构建成功后、发布上线的最后一步自动触发审稿审稿结果写入工单系统。只有负责人在系统里确认处理完高置信度问题后才允许正式发布。这种方式约束力最强适合在线文档平台、开发者中心这类发布频率高且影响面广的场景。接入形态适用场景优点缺点命令行脚本个人内容作者、小团队上手快、无侵入需要手动触发CI 自动审稿有代码仓库协作流程的团队每轮变更自动检查需要维护 CI 配置发布前置卡口大型文档平台、对外文档强管控防止带病上线可能拖慢发布节奏5.2 批量处理时最容易忽略的是“文档分块”触发审稿的文档变动一大直接把整篇文档加所有上下文丢给模型很容易超出上下文窗口也容易让 AI 抓不住重点。我的做法是先把文档按章节切块章节过长的再按段落切每块不超过 1500 字左右。分块之后有一个新问题跨章节的逻辑矛盾怎么办我的处理方式是把“全局审查”和“分块审查”分开。先用一个轻量的“全局一致性检查”把整篇文档的标题、参数表、结论性描述丢给模型让它找矛盾点再用“分块审查”对每个块做细粒度检查。两次结果合并才能既覆盖深读又不漏掉跨章节问题。5.3 审稿结果的结构化输出JSON而不是纯文本为了让结果能对接工单系统我要求模型最终输出结构化 JSON而不是大段的 Markdown。JSON 方案有一个好处是后续过滤、排序、去重、状态跟踪都非常方便。一条典型的问题输出长这样{ issues: [ { severity: high, dimension: fact_consistency, quote: 调用 client.connect() 后会自动保持连接, location: docs/quickstart.md:42, description: 当前 SDK 版本中 connect() 需要手动调用 keepalive() 才能保持连接否则 30 秒后超时, suggestion: 补充 keepalive 调用示例或改为异步长连接方式, confidence: high } ] }实际使用里我会把这个 JSON 按严重级别排序高置信度 高严重级别的优先进入人工复核列表其余自动归档。这样整个审稿结果的消耗成本也比纯文本低很多因为后续只处理真正需要人看的部分。5.4 关键教训审稿记录一定要留否则没法复盘我早期犯的错是审完就扔结果过一阵子想统计“这个提示词版本到底误报率是多少”完全没有数据。后来我在每次审稿时都保留完整的三样东西输入文档版本、prompt 版本、AI 原始输出。有了这些才能对比不同版本的效果也才能在误报集中爆发时快速回查根因。我有一点心得要特别分享AI 审稿跑出的结果并不直接等于“文档有问题”。很多时候它是在提醒你“你这里没有被大部分读者理解你最好换个说法”而不是“你这里技术上讲错了”。如果没有这个意识很容易被 AI 带偏把一篇文章改得越来越保守、越来越像模板。另外虽然整套流程叫“AI 审稿”但我最后仍保留了一步“人工复核员”的角色——只是复核员的工作量从原来的逐字逐句变成了只看高置信度问题。这看起来好像不太“AI 驱动”但实际效果反而最好。因为文档审稿本质上是高风险场景人的判断和责任感在最终环节仍然不可替代。大概就是这个过程从踩坑到跑通我前后花了两周多。如果你也在做类似的事情建议不要一开始就追求大而全的自动化先从单篇文档手动调 prompt确认它能帮你找到以前找不到的硬伤之后再逐步把流程变成脚本、变成接口、变成发布链路上的一环。这样每一步都是在已有收益上叠加效率不太容易做成一堆没人用的纸上工具。
前阵子我们组内部文档上线后第二天隔壁同事照着示例代码初始化客户端跑了十分钟一直报“权限校验失败”最后翻源码才发现示例里漏了一行关键调用。这种问题靠人工校对很难抓出来——语法没错、格式也没错错在业务语义层面。也就是从那时候起我开始认真琢磨一件事技术文档上线前能不能让 AI 先做一轮审稿把这些“人眼看不见但真会造成事故”的硬伤提前筛出来。后来我一共往这个方向试了三版方案从手动粘贴 prompt到写脚本批量审再到把审稿结果接进发布流程前前后后折腾了挺久。这篇文章就是把整套思路和踩坑过程整理出来给同样在做技术写作、内容平台、开发者文档或内部知识库的同学一个可以直接落地的参考。我不会只给一个 prompt 让你复制而是会把为什么这样设计 prompt、怎么约束 AI 不乱说、代码示例怎么校验、以及批量审稿时容易忽略的问题都尽量讲透。1. 审稿不止校稿技术文档的硬伤为什么总被漏掉很多人一说到“文档审稿”第一反应是检查错别字、标点、格式统一。这些当然重要但对于技术文档来说它们远不是致命问题。真正的硬伤是什么是“照着文档做做不出来”。1.1 人工审稿的两个典型盲区我复盘过几次线上事故发现人工评审主要卡在两个地方。第一评审者的精力和知识背景有限。文档涉及多个模块时让一个人逐字检查逻辑一致性几乎不可能做到。大家通常会看有没有错别字、格式是否整齐但对“这段描述和另一章的参数表是否冲突”这种跨章节问题默认依赖作者自己负责。可作者恰恰因为太熟悉自己的实现经常看不到表达上的歧义和对新手的误导。第二人很难在“读文档”的同时“跑文档”。尤其是含代码示例的文档语法正确不代表能运行能运行不代表符合当前 SDK 版本。人工评审最多检查缩进和明显的拼写错误真正要验证代码是否正确得把示例摘出来实际执行这在一轮评审里往往没有时间做。所以技术文档的审稿逻辑天然应该分成两层一层是“语言层”检查表达是否清晰另一层是“语义层”检查描述是否与实际实现一致、示例是否可运行、前后文是否有矛盾。AI 审稿的重点恰恰应该放在第二层而不是第一层。1.2 AI 审稿能覆盖的检查维度我在实际设计审稿规则时把检查项拆成了五个维度。这里直接列出来后面设计 prompt 时全部用得上检查维度具体检查内容典型问题示例事实一致性文档描述与真实 API、参数、返回值是否一致文档说接口返回code0表示成功实际返回code200逻辑一致性同一文档内不同章节、步骤、参数表之间是否有矛盾前面说超时时间为 30 秒后面的配置示例里却写 60 秒代码可运行性示例代码是否完整、依赖是否齐全、调用顺序是否正确示例缺少初始化步骤或使用了已废弃的参数名表达歧义性是否存在模棱两可、可能被误解的表述“建议使用默认配置”没有说明默认配置到底指什么版本与兼容性文档是否与当前 SDK、依赖库版本匹配文档还写着旧版字段名新版本已经改名这五个维度里事实一致性、逻辑一致性、代码可运行性是最容易通过 AI 抓出问题的因为 AI 擅长比对上下文和知识库中的模式表达歧义性则相对主观需要靠人工再做判断。1.3 必须先想清楚AI 审稿的目标不是替代人在开始做之前有一条差点让我走偏一开始我总想让 AI 像人一样“判断对错”后来发现方向错了。AI 审稿最适合的定位是“高召回率的过滤网”——它的价值是把人工容易漏掉的大概率问题捞出来哪怕捞出来的 100 条里有 40 条是误报也不要紧只要剩下 60 条是真实问题就已经赢了。如果把 AI 当成最终裁决者要求它精确到每条都正确那 prompt 会变得非常保守最后只会给出“这句话表达可以更清晰”这类正确但没用的废话。反过来让它大胆提出问题、附上证据位置再配合人工复核整个方案才走得通。2. 把审稿标准翻译成提示词一份可以直接抄的审稿指令模板想明白 AI 审稿的定位之后真正决定效果的是 prompt 怎么设计。我见过不少团队直接丢一句“帮我检查一下这篇文档有没有问题”然后拿到的结果要么是空话要么是泛泛的排版建议这其实是提示词里缺少“审稿标准”和“输出约束”导致的。2.1 审稿指令的核心结构我自己用的 prompt 有固定五段结构角色定义、任务描述、检查维度、约束条件、输出格式。每一段都有它存在的理由。角色定义是为了让模型进入“挑剔审稿人”的状态任务描述要明确是发现问题而不是修改文稿检查维度就是上面那张表约束条件是为了限制它不要瞎发挥输出格式则是为了后续脚本能解析结果。下面是一个经过实测、可以直接拿去改的模板。我把其中的变量留成了{文档内容}和{相关上下文}你可以按自己的场景替换。你是一位资深技术文档审稿人专长是发现技术文档中的错误、歧义和逻辑漏洞。 我会给你一篇技术文档的正文以及与该文档相关的接口定义、代码片段或上下文资料。 你的任务不是润色而是找出所有可能让读者误解或照着操作失败的硬伤。 请从以下五个维度逐一检查 1. 事实一致性文档描述是否与给定的接口定义、参数说明、实际行为一致。 2. 逻辑一致性文档内前后章节、步骤、参数表之间是否存在矛盾。 3. 代码可运行性代码示例是否完整、调用顺序是否正确、是否有缺失的初始化步骤。 4. 表达歧义性是否存在会让读者产生多种理解的表述。 5. 版本兼容性文档内容是否与当前依赖库版本匹配有没有明显过时的字段或方法名。 约束条件 - 只报告确定存在的问题不要给出“建议补充更多细节”这类空泛意见。 - 如果某个问题你只有 60% 的把握请明确标注置信度为低不要斩钉截铁地说它错了。 - 每一条问题必须引用原文中的相关句子或行号作为证据。 - 不要直接输出修改后的整篇文档。 输出格式Markdown ## 问题清单 - 严重级别高/中/低 - 检查维度事实一致性/逻辑一致性/代码可运行性/表达歧义性/版本兼容性 - 原文引用具体句子或代码行 - 问题描述为什么这是错的或可能误导读者 - 修正建议只给出关键修正方向不要重写全文 以下是文档正文 {document内容} 以下是相关上下文资料 {相关上下文}注意这段 prompt 里我特意写了一条约束“不要输出修改后的整篇文档”。一开始我没加这条AI 经常直接把整篇文档重写一遍不仅输出冗长而且改完之后我们根本不知道它改了什么增加了人工复核成本。改成只输出问题清单之后效率提升非常明显。2.2 上下文注入让 AI 有“据”可查AI 审稿最怕的就是凭空脑补。比如你在文档里写“调用start()函数即可”AI 如果不知道这个函数真正的签名它只能根据通识来判断很容易把正确写法误报成错误。所以我会尽可能把“相关上下文”喂给模型。最常用的是三类接口定义文件、代码仓库里对应模块的 README 或源码片段、以及该篇文档依赖的配置示例。如果你的接口定义是 OpenAPI 或 protobuf 文件直接把它作为上下文给 AI事实一致性检查会准很多。还有一个细节是上下文长度管理。文档正文加接口定义很容易超过上下文窗口我的处理思路是先让 AI 基于“文档正文 接口摘要”做第一轮检查等它列出每条问题时再针对具体问题把对应接口定义片段单独喂一次。相当于让它先有个全局印象再针对疑点做精读这样既能控制 token 开销又能提升准确率。2.3 审稿 vs 校对为什么要把两种模式分开我强烈建议不要把“AI 审稿”和“AI 校对”放进同一个 prompt。校对关注的是错别字、标点、中英文空格模型很容易陷入琐碎修改而忽略真正的逻辑问题。我的实际做法是分两条链路一条是常规的拼写和格式检查交给文本规则工具或轻量模型处理另一条才是本文说的语义级审稿交给理解能力更强的大模型处理。两条链路互不干扰结果也更容易管理。有一次我把两条合并让 AI “检查排版和逻辑问题”结果输出的 20 条问题里有 16 条是“建议在中文和英文之间增加空格”这种低级建议真正有价值的逻辑矛盾只找到 2 条。从那之后我再没有合并过。3. 置信度与证据链让 AI 少胡说、多报错AI 审稿最大的风险不是它漏报而是它“言之凿凿地胡说”。尤其当文档内容比较专业、常见模式较少时模型会倾向于把“自己不熟悉”误判为“作者写错了”。这个问题不解决审稿结果就没办法用。3.1 强制 AI 给出置信度和证据位置我在 prompt 里反复强调两件事每一条问题必须引用原文且必须标注置信度。别小看这两个要求它会把 AI 从“写作模式”拉到“审查模式”。加入“引用原文”约束后AI 如果再想当然至少要找一个能自圆其说的地方这会显著减少凭空捏造。加入“置信度”约束后低置信度问题会被单独区分出来人工复核时可以直接跳过或者快速扫一眼。实际跑下来这个机制把误报的干扰降低了大概一半。我给每条问题的置信度分了三档高、中、低。高置信度通常意味着有明确的上下文冲突或接口定义不一致中置信度意味着模型有依据但不确定低置信度一般会被我自己过滤掉不再进入人工复核流程。3.2 温度参数和采样设置也很关键同样一份 prompt把模型的 temperature 调高到 1.0 以上时它会更“发散”容易提出一些很有创意但完全不靠谱的问题调低到 0.2 以下时它会保守很多漏报率也会上升。我实测下来审稿类任务用 temperature 0.3 左右比较合适。如果你用的是支持 seed 等参数的模型建议固定随机种子这样同一篇文档多次审查的结果可复现方便对比不同版本 prompt 的效果。另外如果是英文文档可以把输出语言设在原文档语言如果是中文文档我会要求输出也保持中文因为后续人工复核的同事读起来更顺。3.3 一个真实的误报案例AI 把“正确”当“错误”有一次文档里写“进程启动后如果初始化失败进程会以退出码 1 退出”AI 报了一个高置信度问题说“应该是退出码非 0而不是具体的 1因为不同平台可能不同”。单看这句话AI 说的似乎有道理但该文档描述的是一个特定平台上的特定程序行为实际实现就是固定退出码 1AI 只是没见过这个实现而已。这个案例给我的教训是AI 善于做“通用推理”但技术文档往往是“特定实现”的说明书。所以现在凡是遇到“AI 说某个 API 行为与文档不符”这类问题我一定把真实接口定义调出来二次确认而不是直接信 AI。3.4 交叉评审用两轮结果抵消单模型的偏差为了继续压误报率我还试过让同一个模型从不同角度审两遍或者用两个不同模型各审一遍然后只看两边都指出的问题。这个方法效果不错但成本会翻倍所以我没有把它做成默认流程只在高危文档涉及支付、权限、生产环境配置上启用。你可以这样实现交叉评审第一次用“严苛审稿人”角色第二次用“谨慎工程师”角色两者 prompt 差异要足够大否则得到的结果高度一致就失去交叉的意义了。最后把两轮结果做并集同时只保留置信度都在“中”以上的交集问题。误报类型成因对策把通用模式套到特定实现模型不了解项目私有逻辑注入接口定义、源码片段作为上下文凭语感判断“表达奇怪”缺少语气和语境信息要求必须引用原文描述具体歧义把新版本行为当唯一标准训练数据更新时间差对版本类问题降低置信度人工复核4. 代码示例是高危区AI 读代码不跑代码必须与静态校验联动技术文档里最容易出事故的永远都是代码示例。AI 审稿能看代码、理解代码的意图但它本质上是“读”代码不是“跑”代码。一个示例可能漏了一行 import模型未必看得出来但执行器一跑立刻报错。所以我在整个方案里加了一条独立通道先抽代码块再做可运行性校验最后把执行器报错作为证据回传。4.1 为什么要单独做代码块校验大部分技术文档的代码块不是完整的可运行项目可能是片段、伪代码或为了突出重点删减过。直接拿去执行是不现实的所以我在实际落地时用了一个相对务实的方案把文档中所有带语言标记的代码块抽取出来针对不同语言分别处理。对于 Python、JavaScript 这类解释型语言我优先做语法编译检查和依赖解析对于可以本地执行的片段再补一轮沙箱运行。然后写一个测试脚本把代码块里的关键调用串起来跑一遍看看能否跑通核心路径。下面是抽取与校验的流程示意伪代码import ast import subprocess from pathlib import Path def extract_code_blocks(markdown_text): 从 Markdown 文档中抽取带语言标记的代码块 blocks [] lines markdown_text.splitlines() in_block False lang None buf [] for line in lines: if line.startswith(): if not in_block: in_block True lang line.strip().strip() buf [] else: in_block False blocks.append({lang: lang, code: \n.join(buf)}) elif in_block: buf.append(line) return blocks def validate_code_block(block): lang block[lang] code block[code] if lang python: try: ast.parse(code) return {status: ok, message: } except SyntaxError as e: return {status: error, message: f语法错误: {e}} elif lang bash: result subprocess.run([/bin/bash, -n], inputcode, capture_outputTrue, textTrue) if result.returncode ! 0: return {status: error, message: result.stderr.strip()} return {status: ok, message: } # 其他语言可以继续扩展 return {status: skipped, message: 未支持的语言}这个脚本只需要做一个最基础的语法校验。真正关键的地方在于这一步的结果应该作为上下文喂回给 AI让 AI 针对“执行失败”做二次定位。4.2 把执行器报错回传给 AI 做二次定位每次代码块校验报错我不会直接让执行器输出给用户而是把报错信息和附近代码块一起拼成一个“补审 prompt”让 AI 负责判断这个报错是示例代码本身的问题还是文档描述与代码之间不一致导致的问题。例如某次示例报错AttributeError: Client object has no attribute set_timeoutAI 看完报错后指出了两类问题一是示例代码写的是旧版 SDK 的调用方式二是文档里声称支持超时配置但示例里根本没演示配置步骤。这两个问题如果只靠执行器跑一遍或者只靠 AI 读一遍都不会同时发现。把两者结合起来才能实现“工具负责确定性错误AI 负责语义归因”。4.3 语言配套检查器的选择虽然大模型本身能识别不少代码问题但我还是会依赖配套工具做第一道把关。Python 我用flake8和pyrightJavaScript 用eslintJava 用checkstyleShell 用shellcheck。这些工具基本上都能覆盖大部分语法类和潜在运行时错误。我给一个具体的实操建议把静态检查结果按“错误级别”筛选只把 error 级别和 warning 级别的问题传给 AIinfo 级别全部丢弃否则上下文会被大量废话占满。4.4 为什么这个组合是必要的归根结底一句话AI 在“理解语义、定位矛盾”上远超静态工具但在“确定性校验、代码点火”上远不如执行器。技术文档审稿如果只选一边必然有死角。比如静态工具能抓住未定义变量但它抓不住“文档前后两章的示例互相矛盾”。AI 能抓住后者却又会忽略缺失的 import。所以我把两者设计成流水线静态工具先跑结果作为证据给 AIAI 再基于全文语义做综合判断。这个设计在我自己处理过的两百多篇文档里代码相关问题的实际修正率比单用 AI 或单用工具都高了一截。5. 从单篇到批量审稿流程怎么嵌进上线链路解决了单篇审稿效果之后下一个现实问题是怎么批量用起来。如果每审一篇都要人工复制粘贴 prompt那这套方案很难真正落地。所以我把审稿流程做成了三种接入形态按团队规模不同可以选择。5.1 三种接入形态命令行、CI、发布前置卡口最轻量的形态是一个命令行脚本你传一个 Markdown 文件路径脚本自动抽代码块、拼 prompt、调用模型、输出 JSON 结果。适合个人博主或者小团队临时用。第二种是接进 CI 流程文档仓库每次提交 PR 时自动跑一轮审稿把问题列表发布到 PR 评论区。这种方式的好处是审稿和代码评审同步作者改文档时直接能看到问题。第三种是发布前置卡口文档构建成功后、发布上线的最后一步自动触发审稿审稿结果写入工单系统。只有负责人在系统里确认处理完高置信度问题后才允许正式发布。这种方式约束力最强适合在线文档平台、开发者中心这类发布频率高且影响面广的场景。接入形态适用场景优点缺点命令行脚本个人内容作者、小团队上手快、无侵入需要手动触发CI 自动审稿有代码仓库协作流程的团队每轮变更自动检查需要维护 CI 配置发布前置卡口大型文档平台、对外文档强管控防止带病上线可能拖慢发布节奏5.2 批量处理时最容易忽略的是“文档分块”触发审稿的文档变动一大直接把整篇文档加所有上下文丢给模型很容易超出上下文窗口也容易让 AI 抓不住重点。我的做法是先把文档按章节切块章节过长的再按段落切每块不超过 1500 字左右。分块之后有一个新问题跨章节的逻辑矛盾怎么办我的处理方式是把“全局审查”和“分块审查”分开。先用一个轻量的“全局一致性检查”把整篇文档的标题、参数表、结论性描述丢给模型让它找矛盾点再用“分块审查”对每个块做细粒度检查。两次结果合并才能既覆盖深读又不漏掉跨章节问题。5.3 审稿结果的结构化输出JSON而不是纯文本为了让结果能对接工单系统我要求模型最终输出结构化 JSON而不是大段的 Markdown。JSON 方案有一个好处是后续过滤、排序、去重、状态跟踪都非常方便。一条典型的问题输出长这样{ issues: [ { severity: high, dimension: fact_consistency, quote: 调用 client.connect() 后会自动保持连接, location: docs/quickstart.md:42, description: 当前 SDK 版本中 connect() 需要手动调用 keepalive() 才能保持连接否则 30 秒后超时, suggestion: 补充 keepalive 调用示例或改为异步长连接方式, confidence: high } ] }实际使用里我会把这个 JSON 按严重级别排序高置信度 高严重级别的优先进入人工复核列表其余自动归档。这样整个审稿结果的消耗成本也比纯文本低很多因为后续只处理真正需要人看的部分。5.4 关键教训审稿记录一定要留否则没法复盘我早期犯的错是审完就扔结果过一阵子想统计“这个提示词版本到底误报率是多少”完全没有数据。后来我在每次审稿时都保留完整的三样东西输入文档版本、prompt 版本、AI 原始输出。有了这些才能对比不同版本的效果也才能在误报集中爆发时快速回查根因。我有一点心得要特别分享AI 审稿跑出的结果并不直接等于“文档有问题”。很多时候它是在提醒你“你这里没有被大部分读者理解你最好换个说法”而不是“你这里技术上讲错了”。如果没有这个意识很容易被 AI 带偏把一篇文章改得越来越保守、越来越像模板。另外虽然整套流程叫“AI 审稿”但我最后仍保留了一步“人工复核员”的角色——只是复核员的工作量从原来的逐字逐句变成了只看高置信度问题。这看起来好像不太“AI 驱动”但实际效果反而最好。因为文档审稿本质上是高风险场景人的判断和责任感在最终环节仍然不可替代。大概就是这个过程从踩坑到跑通我前后花了两周多。如果你也在做类似的事情建议不要一开始就追求大而全的自动化先从单篇文档手动调 prompt确认它能帮你找到以前找不到的硬伤之后再逐步把流程变成脚本、变成接口、变成发布链路上的一环。这样每一步都是在已有收益上叠加效率不太容易做成一堆没人用的纸上工具。
