★ FEATURED ARTICLE 技术文档上线前最怕的就是“自己写的东西自己看不出毛病”。我做了几年开发自己也写过不少技术文档、接口说明、内部Wiki有一个感受特别深文档写完那一刻你觉得自己写得清清楚楚、逻辑严密但用户一读就懵或者运维照着文档操作直接踩坑。问题往往不是出在“写”上而是出在“审”上。人工审稿当然要做但人的注意力有天花板尤其是面对几百行参数表格、一大段配置步骤的时候眼睛一花就滑过去了。所以我从去年开始养成了一个习惯所有技术文档上线前先让 AI 帮忙做一轮审稿然后再人工复核。这套流程用下来文档返工率降了不少一些低级错误在发布前就被拦住了。这篇就分享一下我怎么把 AI 审稿嵌入到技术文档的上线流程里包括工具选型、提示词设计、分轮审稿的节奏以及实际运行中最容易踩的坑。不管你是开发、运维还是技术写作这套思路都可以直接拿去用至少能帮你省掉不少“发出去之后被用户追问”的尴尬时间。1. AI 审稿到底在审什么先理清四类常见文档问题想用好 AI 审稿第一步不是先找工具而是先搞清楚技术文档最常见的毛病集中在哪些地方。我把自己经手过的文档问题整理了一遍发现无非是四类事实性错误、一致性偏差、可读性障碍、规范性缺失。事实性错误最容易理解就是文档里写的和真实情况对不上。比如某个接口的返回字段写错了类型某个配置项的默认值标错了某个命令的参数顺序写反了。这类问题最致命因为读者照着文档操作轻则功能不对重则数据出问题。人工审稿不是发现不了而是容易“惯性阅读”——自己写的时候就是这么想的审的时候也会顺着这个思路结果错误就被“默认正确”了。一致性偏差更隐蔽。一份大型技术文档往往不是一次性写完的可能是多人协作也可能隔了好几天分几次补充。结果就出现这种情况前面章节说配置文件名是app.yaml后面示例代码里写的是config.yaml正文里讲某个接口需要三个参数示例代码里只传了两个。这类前后矛盾的问题人工审稿经常漏因为审稿人往往会分段读很少有人从头到尾把上下文一遍捋完。可读性障碍则更多是“感觉”问题。句子太长、概念没解释就使用、逻辑跳得太快、步骤之间缺少衔接。这些问题技术背景强的人往往无感因为自己脑内会“自动补全”那些省略的上下文但对新读者来说就是天书。规范性缺失比较杂有的是代码块没标注语言有的是标题层级不统一有的是关键词大小写不一致有的是表格里缺单位。单独看每条都不严重但堆在一起就让文档显得粗糙。传统审稿流程的问题在于人不可能在同一轮里同时盯住这四个维度。看内容的时候格式就顾不上了核对格式的时候逻辑连贯性又看不过来了。AI 审稿最大的价值就是把“查错”和“润色”这两个动作从人的脑袋里拆出来AI 先按提示词指定的维度把疑点全部扫一遍生成结构化的问题清单人再把精力集中在筛选疑点、判断真伪上。这才是人机协作的正确姿势。2. 工具选型与上下文准备决定 AI 审稿质量的两块基石2.1 选通用大模型还是专用审稿工具我一开始也想过找那种“专门审技术文档”的工具试了一圈效果不太理想。不是说那些工具不行而是它们对文档内容的上下文理解太浅很多时候只能做拼写检查和格式检查对“逻辑连贯性”和“事实一致性”这种需要深度理解的任务输出质量明显不够。后来把重心转向通用大模型发现上限高很多。原因很简单审稿这件事本质上是一个“阅读理解知识比对”的任务通用大模型在自然语言理解上的能力储备天然适合干这个。而且技术文档的写法相对规范AI 不需要太多创造力只需要严谨地对照、核查、挑毛病这恰好是大模型表现最稳定的场景。至于选哪个具体模型我的建议是不要迷信某一个主要看你手上的文档类型和你能接受的成本。处理公开技术栈的文档几个主流模型的表现差距不大处理公司内部私有项目的文档带长上下文的模型会更合适因为内部文档往往需要同时参照大量背景材料才能判断对错。我一个比较实用的做法是同一篇文档在发布前用两个不同的模型各跑一轮然后人工合并两边的结果——侧重点往往不太一样A 模型漏掉的 B 模型能发现反之亦然。2.2 “审稿上下文包”AI 审稿效果的分水岭直接甩一篇文档给 AI 让它“帮忙看看”十有八九会得到一个泛泛而谈的回复——“内容整体清晰建议加强某些部分的表达”这种输出几乎没有价值。问题不在 AI 能力在于你给它的上下文太少了。它根本不知道你这篇文档给谁看、要解决什么问题、有哪些是故意这么写的约定。我后来总结出一个概念叫“审稿上下文包”即每次让 AI 审稿之前除了文档本身还给它配套提供至少四类补充信息读者画像这篇文档是给谁看的新手用户、运维人员、还是二次开发者不同的读者对象文档的详略和术语使用标准完全不同。写作约定清单项目里有没有遗留的专有名词写法比如这个服务叫user-svc还是user_service约定用“客户端”还是用“Client”这些约定需要人先列出来AI 才能按这个标准去审。参考文档清单如果文档里涉及接口定义、配置参数最好把对应的接口定义文件、配置样例一起喂给 AI让它可以交叉比对而不是凭“常识”猜测。审稿目标侧重这一轮重点是抓事实错误还是重点优化表达目标不同提示词要走完全不同的路子。这套上下文包听起来麻烦其实真正常用的就是读者画像和写作约定清单这两项。我第一次搭好模板之后后面每篇新文档只需要改几个关键词五分钟内就能完成配置但审稿准确率的提升是非常明显的。3. 分轮审稿实操把一次大检查拆成四轮小检查把整个文档一次性塞给 AI让它“全面检查”效果通常不好。模型在单次回答中能调用的注意力是有限的检查维度一多每个维度都只能浅尝辄止。所以我习惯把审稿拆成四轮每轮只让 AI 专注干一件事。3.1 第一轮事实核查第一轮的目标是找事实性错误。这一轮的核心是给 AI 足够的“参照物”——接口定义、配置模板、官方文档摘要都喂进去然后明确要求它只找“文档写的内容和参照物不一致”的地方不要提表达建议不要夸内容好输出格式统一为“原文位置 原文内容 不一致的地方 建议修改”四段式。举个例子我审过一篇部署文档里面写MAX_CONNECTIONS500但配置模板里实际默认值是200AI 第一轮就把它揪出来了。这种交叉验证正是 AI 最擅长的事因为它能同时“记住”两处信息并做逐字比对人却很容易因为对数字不敏感而放过。实际使用中的注意事项代码块内容最容易误报。如果代码里的变量名、字符串值、参数名被文档正文引用AI 可能因为“名字不完全一致”就报错。所以这一轮的结果我会建议做一次“代码块排除”预处理或者干脆在提示词里写明“代码块中的内容不作为比对基准只比对正文描述”。3.2 第二轮一致性校验第二轮专门查前后矛盾。我的做法是让 AI 把文档中所有“同义概念”抽取出来列成一张对照表然后查找同一个概念在不同章节是否有不同的表述。比如某个服务名如果前文写user-api后文写user_apiAI 就能发现拼写风格不一致。更进一步的用法是让 AI 生成一份“术语一致性检查表”列出每个核心概念在不同章节出现的所有名称人工只需要快速扫一遍这张表就能发现需要统一的地方。这个思路在多人协作的长文档里尤其好使——每个人写自己那一块时都用自己习惯的叫法人工通读根本顾不上逐个比对AI 十几秒就扫完了。第二轮输出建议直接用表格格式概念名称出现位置原文表述建议统一表述优先级有了这个矩阵人工复核的时候一眼扫过去就能决定哪些要改、哪些是“故意这样写”的例外效率比翻文档找快太多了。3.3 第三轮可读性优化事实和一致性都过了第三轮开始处理“读者读起来顺不顺”的问题。我会把读者画像重点强调给 AI比如提示词里写清楚“读者是刚接触该框架三天的初级开发者不熟悉内部术语请标记所有未解释的专业名词和隐含逻辑跳跃之处。”这一轮 AI 会做这几件事找出没有解释就使用的缩写标出超过两行的长难句标记缺少过渡语导致上下文断裂的段落圈出不直观的小标题。这些都是从“作者视角”转向“读者视角”才能发现的问题作者自己很难跳出写作时的思维惯性。但这里要特别提醒AI 的改写建议不能直接采纳。技术文档有自己的“技术腔”AI 很容易把严谨的表述改成“更通顺”但丢失精确性的表述。我在实践中发现第三轮最有价值的部分不是 AI 给的修改文本而是它“标记出哪些地方读者可能读不懂”的能力。标记本身就是在替作者模拟一遍新读者的阅读体验。至于怎么改还是人说了算。3.4 第四轮规范性检查最后一轮做的是“交规式”检查不涉及内容理解只看文档是否符合格式规范。这一轮可以交给能力稍弱的轻量模型。检查项包括标题层级是否连续、所有代码块是否标注了语言、表格是否包含表头和必要的单位、图片是否有编号和说明文字、关键术语大小写是否保持一致以及是否缺少版本号和更新日期。我最初觉得这轮价值不大后来发现恰恰相反——规范性问题是文档“专业感”最直接的来源。读者可能说不清哪里不对但一份标题层级混乱、代码块没有语法高亮的文档就是会给人一种“这文档不太可靠”的直觉。AI 在这一轮可以稳定地输出一张格式问题清单比如“第四章缺少三级标题”“第 12 个代码块未标注语言”人工照着清单逐个修就行基本不需要判断。四轮审完把四张问题清单汇总成一份审稿报告再进入人工复核环节。4. 提示词模板与自动化脚本搭建你的 AI 审稿工作流4.1 一个可以直接用的基础提示词模板下面是我调试过很多版、目前稳定使用的一套提示词结构。你可以直接复制然后替换其中的项目占位符。需要说明的是这套模板适用的是多轮对话式审稿建议每轮新建会话避免模型受到上一轮输出风格的影响。你是一名资深技术文档审稿专家。我将给你提供一篇技术文档【文档全文】以及对应的【参考材料】。请你仅执行【本轮审稿目标】中的任务不要做任何额外的事。 【文档全文】 在此粘贴文档正文 【参考材料】 在此粘贴接口定义/配置模板/官方文档摘录等 【读者画像】 本文档的读者是如负责部署该服务的运维工程师具备基本的 Linux 操作能力但对该项目的内部架构不熟悉 【写作约定清单】 - 项目名统一写作如>import re from pathlib import Path def split_document_by_headers(md_text: str): 按二级标题切分 Markdown 文档返回标题, 内容片段列表 lines md_text.splitlines() sections [] current_title 前言 current_content [] for line in lines: if re.match(r^## , line): if current_content: sections.append((current_title, \n.join(current_content))) current_title line.strip(#).strip() current_content [line] else: current_content.append(line) if current_content: sections.append((current_title, \n.join(current_content))) return sections def call_model(messages): 通用模型调用函数替换为你的实际 API 调用 # 这里以 OpenAI 兼容接口为例仅示意 # import openai # client openai.OpenAI(api_keyyour-key, base_urlyour-endpoint) # resp client.chat.completions.create( # modelyour-model-name, # messagesmessages, # temperature0.2, # ) # return resp.choices[0].message.content pass def review_section(title: str, content: str, context: str) - str: 对单个章节执行一轮审稿 messages [ { role: system, content: 你是资深技术文档审稿专家。 }, { role: user, content: ( f以下是文档章节【{title}】的内容\n\n{content}\n\n f全文其他章节摘要供上下文理解\n{context[:1000]}\n\n 请按本轮审稿目标仅检查事实性问题。输出格式 原文位置 | 原文内容 | 问题类型 | 修改建议 ) } ] return call_model(messages) if __name__ __main__: doc_path Path(deploy-guide.md) doc_text doc_path.read_text(encodingutf-8) sections split_document_by_headers(doc_text) full_text_summary doc_text[:2000] # 用作上下文摘要 all_results [] for title, content in sections: # 片段超过长度则截断或自行扩展为递归切块 result review_section(title, content[:3000], full_text_summary) all_results.append(f {title} \n{result}) output_path doc_path.with_suffix(.review.md) output_path.write_text(\n\n.join(all_results), encodingutf-8) print(f审稿结果已写入{output_path})这个脚本的思路很直接按二级标题把长文档拆成片段一次只审一节每节附带全文开头两千字做上下文摘要避免模型“断片”。实际操作里我会根据文档长度调整截断阈值保证每段不超过模型建议的最大输入长度的一半留出足够的空间给输出。4.3 审稿报告标准化让问题清单可以直接派单AI 跑完四轮输出的内容格式可能比较乱所以我在脚本里加了一层后处理把四轮结果统一转成一份五列的 Markdown 表格然后人工在表格里填“处理结果”列这就成了可以跟踪的审稿台账。表格列定义问题ID所属章节问题类型原文摘要AI 建议人工裁定这里说的“人工裁定”不是填“已修改”就完事而是要填具体的处理动作接受修改、拒绝并写明原因、需要进一步确认。这份表格在发布评审会上直接就是一份很扎实的审稿证据谁提的问题、为什么改、为什么没改一目了然不会出现“文档改了但没人知道为什么改”的情况。5. 常见误区与翻车现场AI 审稿最容易出错的五个环节任何工具都有边界AI 审稿也不例外。我跑了上百篇文档之后总结出五个高频翻车点每一个背后都是我实际踩过的坑。5.1 事实交叉验证需要“喂材料”不能考 AI 的“记忆”第一个大坑是把 AI 当成活的搜索引擎。有些人直接让 AI“检查文档里的接口参数是否正确”但并没有提供接口定义文件AI 就只能调用它训练数据里的“常识”。对开源技术栈的通用内容这个“常识”可能不出错但公司内部自定义的接口、冷门配置项、刚升级的新版本参数AI 的“记忆”是滞后的、甚至是编的。解决思路特别朴素凡是文档里出现的具体参数、路径、命令、版本号必须把对应的原始材料接口定义、配置文件、官方更新日志喂给 AI。AI 是优秀的“找不同”选手不是可靠的“百科词典”——你让它对照着查准确率会高很多你让它凭记忆写它可能用幻觉来补全。5.2 幻觉AI 会把“没有的内容”补充成“应有的内容”第二个坑更隐蔽AI 在审稿过程中偶尔会“脑补”一个不存在的错误然后一本正经地建议你修改。比如在某篇文档里原文正确地写了handler.process(data, retry3)AI 却报了一个“缺少超时参数”的问题理由是“类似场景通常还需要 timeout 参数”。这种就是模型基于训练数据里的“常见模式”做推断把模式泛化成了规则。应对方法很直接所有 AI 报出的“缺失项”必须在提示词或人工复核环节里追问一句“缺失的依据是什么”。如果 AI 只能给出“通常应该这样”拿不出具体来源比如参考材料里有或公认规范里有那就直接标记为“不采纳”。人工复核最大的价值就是做这个裁决。5.3 新旧版本混用文档参照了多个时代的“正确”第三个坑和我的实际项目经历密切相关。有一次审一篇部署文档AI 连续报了好几个“参数不存在”的错误我一开始以为是误报后来核对参考材料才发现AI 参照的配置模板是旧版本的文档里写的几个参数在新版本刚改过名。问题不出在 AI而在于我喂给它的参考材料过期了。这个教训让我后来在每一轮审稿开始前都会加一条约定清单“参考材料以最新发布分支为准旧版本文件仅作为兼容性说明不作为错误判据。”这不仅提高了准确率也减少了 AI 因为参考材料打架而纠结的时间。5.4 同一批提示词反复用模型会“疲”很多人觉得提示词一旦调好就可以一直复用但实际用下来不是这样。同一套提示词连着给同一个模型跑几十次输出质量会肉眼可见地变差——倒不是说它“学会偷懒”了而是模型在对话中对任务的定义会逐渐固化输出的问题越来越趋同、越来越浅层。我自己的习惯是每次审稿之前把提示词里的“本轮审稿目标”部分做一点微调——换个说法、加一个新的检查维度、调整输出格式要求。哪怕是微小的变化输出质量就能保持在线。5.5 只信 AI 的输出丢掉了“人审”的尾巴最后一个坑是流程层面的有人跑完 AI 审稿把问题清单往群里一发就当作审稿工作完成了这是绝对不行的。我反复强调一个观点——AI 的输出永远是“候选发现”不是“最终结论”。事情性错误、规范性问题AI 的准确率确实已经很高但涉及业务逻辑、产品决策、历史包袱、兼容性考量的问题AI 没有判断依据它甚至不知道那是问题。所以我的流程永远是先 AI 扫再人来裁定最后才是修改。AI 负责“把网撒大、尽量不漏”人负责“把网收回来、筛选真正需要处理的”。两步都不可或缺少了哪一步文档质量都不托底。6. 从个人习惯到团队规范把 AI 审稿固化到上线流程最后讲一讲我后来是怎么把这件事从“个人小技巧”变成“团队默认动作”的。不是写个规范要求大家遵守那么简单而是要解决团队协作里的实际问题否则这东西用两天就会被人悄悄放弃。6.1 接入文档发布流程的关键节点三件事很关键在文档修改提交之前强制跑一轮 AI 审稿脚本。不通过不能提交到评审环节这一点可以写进提交检查清单里。AI 审稿报告和文档一起提交。评审人不仅看文档本身还要看 AI 发现了哪些问题、作者怎么处理的——这会逼着提交者认真对待 AI 的输出而不能只看完就算了。把常见问题沉淀成写作约定文档。每周从 AI 审稿报告里挑出出现频率最高的五类问题补进写作约定里下一轮审稿时把这些约定作为提示词的一部分传进去。这样整个团队的文档质量会一轮比一轮高相当于有一个自动升级的检查标准。6.2 如何防止同事“假用、滥用、弃用”推动团队成员用 AI 审稿最大的阻碍不是技术而是心态。开发同事普遍觉得“文档能跑就行写那么认真干嘛”运维同事可能认为“AI 胡说八道还得给它解释更累”。应对的核心是让 AI 审稿的“收益感”快速显性化跑一次脚本几分钟出一份问题清单直接复制粘贴到文档修改记录里这个“低成本高产出”的体验一旦建立后面就不需要人催了。如果是团队已有文档评审流程可以把 AI 审稿嵌入为评审前的强制一步把审稿报告作为评审会材料的固定附件。不多花十分钟但会上的讨论焦点就不再是“标题层级乱不乱”这种基础问题而是真正的内容问题了——这才是审稿本该有的样子。6.3 我个人对 AI 审稿边界的三条判断这个部分是我一年多反复调整后总结出来的边界感全部基于个人实操未必对所有团队适用但可以参考AI 适合查“对外一致性”和参考材料不一致、和官方规范不一致、和自己前后文不一致。AI 适合查“共识性规范”代码块标注、标题层级、术语大小写这类有明确标准的问题。AI 不适合裁决“产品性判断”要不要支持某个旧参数、某个接口的弃用策略怎么定、某个配置项默认值改不改——这些事 AI 没有足够的上下文也没有资格拍板。你如果刚开始尝试 AI 审稿我最大的建议是不要一上来就对 AI 的输出抱有 100% 的信任也不要因为一次误报就全盘否定它。把它当成一个“读过大量技术资料的实习生”它能在几分钟内帮你把一篇几百行的文档通读一遍标注出所有疑点——但最终改不改、怎么改你才是那个要对文档负责的人。先小范围用起来积累几次真实的审稿报告你就能找到自己的最佳使用姿势了。
阅读完成 · 觉得有帮助？
