AI 写技术博客的正确方式：从资料调研、代码验证到人工审核

一篇技术博客里有 3 段代码，但没有任何一段经过运行验证；读者照抄后报错，问题不是写得不漂亮，而是事实和代码都没过门禁。

AI 起草的技术文章看起来结构完整，却在版本号、命令参数和输出格式上全靠猜测。有的项目在 package.json 中声明了 "type": "module"，示例却直接使用 require；有的提到”GitHub Actions 每月有 2000 分钟”，却没说明这是特定套餐下私有仓库的包含用量。

技术博客不是把主题丢给模型再润色，而是先拿到资料和可执行证据，再让 AI 组织表达，最后由人做事实、代码和风格审核。这篇文章提供一套可执行的写作-验证-审核流程，明确每个阶段的门禁和责任人，保证事实准确、代码可运行、结论可复现。

先做资料调研，再让 AI 起草正文

哪些内容必须先调研，哪些可以让 AI 自己写？

AI 写技术博客时，需要回答一个核心问题：哪些事实必须从外部获取，哪些可以让模型自己组织。

资料调研分三种场景：

必须先调研的内容包括版本号、API 字段变更、官方文档中的限制、价格/额度、安全配置。这些内容一旦出错，读者照抄就会报错或账单失控。例如，Next.js 当前文档使用 turbopack 配置键，而 13.0.0 至 15.2.x 使用过 experimental.turbo；直接写”配置 Turbopack”而不标注适用版本，读者可能复制到不兼容的版本。

可以让 AI 起草但必须复核的内容包括通用概念、框架用法、最佳实践、常见错误。例如”React hooks 的使用原则”这类内容，AI 通常能写出正确的初稿，但具体的规则数量、命名约定、版本差异需要对照官方文档复核。

可以让 AI 自己写的内容包括纯粹的结构组织、语言润色、格式整理。例如把一段技术解释改得更口语化，或者把多个分散的段落合并成一个章节，这类工作不需要额外调研。

三种调研场景的对比：

调研类型	典型内容	门禁强度	写作阶段适用性
必须先调研	版本号、API 字段、价格/额度、安全配置	高：必须从官方文档提取，标记 [VERIFY]	大纲阶段完成，写作当天复核
AI 起草 + 复核	通用概念、框架用法、最佳实践	中：AI 初稿 + 对照官方文档复核	正文阶段完成，审核阶段复核
AI 自己写	结构组织、语言润色、格式整理	低：不需要额外调研	正文阶段完成

调研决策树：

遇到 X 类型内容
  ↓
是否涉及版本号/API/价格/安全？
  ├─ 是 → 从官方文档提取，标记 [VERIFY]，写作当天复核
  └─ 否 → 是否涉及技术规则或最佳实践？
      ├─ 是 → AI 起草，审核阶段对照官方文档复核
      └─ 否 → AI 自己组织表达

如何把调研结果标记到大纲输入？

调研完成后，需要把结果写入大纲输入（outline input），让 AI 写作阶段能直接引用。

从 research.md 中提取高置信度来源（标记为 high 的官方文档）。例如 Google Search Central 的 helpful content guidance、GitHub Actions Node.js CI 官方示例、Astro Content Collections 官方文档。

对易变事实标记 [VERIFY]。例如：“GitHub Actions 私有仓库的包含用量取决于账户套餐 [VERIFY]”、“目标 Node 版本当前是否仍受支持 [VERIFY]”。

把来源卡片、命令输出、复核结果写入 outline input 的 source_cards 和 risk_notes 字段：

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "内容应提供原创信息、完整描述，不要主要依赖大量自动化"
    }
  ],
  "risk_notes": [
    {
      "fact": "GitHub Actions 免费额度",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

标记完成后，写作阶段不需要重新调研，只需要按标记复核易变事实。

代码示例必须验证，不是”看起来能跑”

四种代码验证场景

技术博客里的代码示例经常”看起来能跑”但实际出错。读者照抄报错后，文章信任度直接归零。

代码验证分四种场景：

本地运行包括安装命令、配置示例、简单脚本。例如 npm install、git clone、配置文件修改。这类命令必须在本地环境实际执行，记录输出。

CI 测试包括构建命令、测试命令、环境依赖。例如 GitHub Actions 中的 npm ci、npm run build、npm test。这类命令适合在 CI 环境中验证，因为 CI 能保证环境一致性。

版本管理包括 Node 版本、依赖版本、API 版本。例如 .nvmrc、package.json、API endpoint 变更。这类内容需要标注版本号，并在文中说明版本差异。环境一致性包括开发环境、生产环境、CI 环境的配置差异，例如环境变量、Docker 镜像、操作系统差异。这类内容需要标注执行环境，避免读者在不同环境下报错。

四种验证场景的对比：

验证场景	典型内容	验证方法	必须提供的证据
本地运行	安装命令、配置文件	本地执行	命令输出文本或截图
CI 测试	构建、测试命令	GitHub Actions 或其他 CI	CI 日志或构建结果截图
版本管理	Node/依赖版本	版本检查命令	node --version 输出 + 版本标注
环境一致性	环境变量、Docker	多环境测试或明确标注	环境标注 + 条件说明

如何记录代码运行证据？

所有代码示例必须提供运行证据，不能只写”运行成功”。下面的命令和输出只演示证据记录格式，不是可复用的实测凭证；写自己的文章时，应替换成目标项目的真实版本和日志。

命令示例（Node.js CI）：

# 本地环境：macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# CI 环境：GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

输出对比：

✅ 正确示例：提供命令输出截图或文本，标注版本号和输出要点。

❌ 错误示例：直接写”运行成功”而不提供输出证据。

代码块最佳实践：

使用 fenced code block（三引号）+ 语言标识（如 bash、typescript）。对于长输出，使用折叠块或只展示主要部分。对于多步骤命令，标注执行环境（本地/CI/Docker）。对于版本检查，提供 node --version 或 npm --version 输出。

示例：

# 执行环境：macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

如果命令输出很长，只展示主要部分：

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

GitHub 官方文档推荐使用 fenced code block 和语法高亮（来源：Creating and highlighting code blocks），技术博客应保持这一标准，而不是把代码伪装成叙述文字。

人工审核不是语言润色，而是事实、代码和结构三层检查

事实审核：版本号、参数、价格都要溯源

人工审核不是语言润色，而是事实、代码和结构三层检查。很多写作者把审核理解成”改改措辞”，结果没发现版本号错误、命令参数错误、代码和结论对不上。

事实审核的核心是溯源：每个版本号、API 字段、命令参数、配置值、价格额度、发布时间都要对照官方文档或实际运行结果。

事实审核检查清单：

检查项	审核方法	失败信号	正确示例
版本号	对照官方 release 或文档	版本号不存在、版本特性描述错误	提供官方文档链接 + node --version 输出
命令参数	对照官方 CLI 文档	参数不存在、参数格式错误	提供官方文档链接 + 命令实际输出
API 字段	对照官方 API 文档	字段不存在、字段类型错误	提供官方 API 文档链接 + 实际请求示例
价格/额度	对照官方定价页	价格错误、未标注公开/私有差异	提供官方定价页链接 + 使用条件标注
发布时间	对照官方公告或博客	时间错误、事件不存在	提供官方公告链接

错误示例：

项目在 package.json 中声明了 "type": "module"，代码示例却直接使用 CommonJS 的 require，也没有改用 .cjs 或说明模块边界。

文章说”GitHub Actions 每月只有 2000 分钟”，但没有说明标准 GitHub-hosted runner 在公开仓库中免费，而私有仓库的包含分钟数取决于账户套餐。

正确示例：

“Node 18 同时支持 ES modules 和 CommonJS；.mjs、.cjs 与 package.json 的 type 字段会影响文件解释方式。运行记录使用 Node 18.20.0，并已保存 node --version 输出（来源：Node.js 官方文档）”

“截至 2026-07-26，公开仓库使用标准 GitHub-hosted runner 免费；私有仓库按账户套餐获得包含分钟数，例如 GitHub Free 为 2000 分钟、GitHub Pro 为 3000 分钟（来源：GitHub Actions billing）“

代码审核：可运行、输出匹配、环境标注

代码审核要检查三个点：命令是否可运行、输出是否匹配正文描述、环境是否标注清楚。

代码审核检查清单：

检查项	审核方法	失败信号	正确示例
命令可运行性	本地或 CI 运行	命令报错、依赖缺失	提供运行日志或截图
输出匹配	对照正文描述	输出与正文描述不一致	正文描述与命令输出一致
环境标注	检查环境说明	未标注 Node 版本/操作系统	标注执行环境：Node 18.20.0 + macOS
依赖版本	检查 package.json	依赖版本与正文不一致	提供 package.json 或版本检查输出

错误示例：

正文说”构建成功，生成 3 个文件”，但 npm run build 实际输出显示生成了 5 个文件。

正文说”本地运行成功”，但代码示例依赖 Docker 环境，未标注差异。

正确示例：

正文描述与命令输出一致：“npm run build 生成了 3 个文件：index.html、index.js、index.css（见命令输出）”

环境标注清楚：“本文在 macOS + Node 18.20.0 环境下测试，Linux 或 Windows 环境可能需要调整路径”

结构与风格审核：H2/H3 一致、内链放置、AI 味清洗

结构与风格审核检查三个点：H2/H3 是否与大纲一致、内链是否按计划放置、AI 味词汇是否清洗。

结构与风格审核检查清单：

检查项	审核方法	失败信号	正确示例
H2/H3 一致性	对照 outline.md	H2/H3 缺失或新增	标注大纲修改理由
内链放置	对照内链计划	内链未放置或锚文本错误	按计划放置内链
AI 味词汇	对照 anti-ai-words.json	出现时代套话、空泛表达	替换为口语化表达或删除

站内配置文件 anti-ai-words.json 定义了两类需要避免的表达（详见配置文件）。审核时对照该文件逐项检查，发现空泛表达、模糊归因或过度承诺时替换或删除。

错误示例：

出现以时代背景开头的表达。

出现”本文将全面解析”这类空泛承诺。

正确示例：

删除时代套话，直接切入问题：“AI 写技术博客时，需要回答一个核心问题：哪些事实必须从外部获取”

删除空泛表达，改成具体判断：“这篇文章提供一套可执行的写作-验证-审核流程”

发布前 QA：用验收清单收口

发布前 QA 清单

写完文章不代表可以发布。发布前 QA 是最后一道门禁，逐项检查调研标记、代码验证、事实溯源、结构一致性、内链放置、AI 味清洗和图片上传。

发布前 QA 清单：

检查项	检查方法	通过条件	失败处理
调研标记是否清理	搜索 [VERIFY]	无未清理标记	回退到调研阶段复核
代码示例是否验证	对照运行日志	所有代码示例有输出证据	回退到代码验证阶段
事实是否可溯源	对照来源卡片	所有事实有来源链接或标注	补来源或删除断言
结构是否一致	对照 outline.md	H2/H3 与大纲一致或有修改说明	更新大纲或标注理由
内链是否放置	对照内链计划	所有内链放置且锚文本正确	补内链或调整计划
AI 味是否清洗	对照 anti-ai-words.json	无 AI 味词汇	替换或重写
图片是否上传	对照图片清单和 Markdown 路径	所有图片路径有效且已处理	上传图片或调整路径

状态标注：

✅ 通过：可以发布

⚠️ 待定：需要复核或补来源

❌ 失败：需要重写或回退到调研/验证阶段

QA 验收流程：

每个检查项逐项验证。发现问题立即标记状态。所有检查项通过后，更新任务表状态为”可发布”。

发现问题怎么回退？

QA 清单发现问题后，需要回退到对应阶段修正，而不是跳过。

回退机制：

事实错误需要回退到调研阶段，补充官方文档来源，删除无法溯源的断言，标记易变事实为 [VERIFY] 并复核。

代码错误需要回退到代码验证阶段，重新运行命令并记录输出，更新正文中的命令示例，标注执行环境。

结构不一致需要更新大纲或标注理由，对照大纲标注哪些 H2/H3 被删除或新增，说明修改理由，更新大纲文件。

内链缺失需要对照 cluster map 和站内库存，找到站内相关文章放置内链，使用描述性锚文本避免”点击这里”。

AI 味未清洗需要对照 anti-ai-words.json 逐项替换，无法替换时重写段落。

回退流程示例：

QA 发现"GitHub Actions 免费额度"未标注公开/私有差异
  ↓
标记为 ❌ 失败
  ↓
回退到调研阶段
  ↓
补充官方定价页来源 + 标注使用条件
  ↓
重新进入 QA 验收

回退机制的核心是发现问题不跳过，而是回到对应阶段修正。这样能保证每个阶段的门禁都有责任人，而不是最后才发现问题却无法追溯。

这些信号说明文章已经偏离事实

偏离事实的 7 个信号

文章偏离事实不是突然发生的，而是逐步累积。识别这些信号能帮助写作者和审核者在发布前发现问题。

偏离事实的 7 个信号：

信号 1：断言无来源。文章提到”最新版本”、“官方推荐”、“最佳实践”，但未提供来源链接或文档引用。例如把某个 Turbopack 配置键写成”所有 Next.js 版本通用”，却没有给出对应版本的官方文档。

信号 2：代码未运行。代码示例没有实际运行输出或日志，只写”运行成功”。例如”执行 npm install 后运行成功”（无输出证据）。

信号 3：版本号/参数错误。版本号虽然存在，但发布线或支持状态写错；命令参数、API endpoint 也可能已经变更。例如把 Node 20.1.0 写成 LTS，但该版本发布时属于 Current。

信号 4：环境不一致。文字声称”本地运行”，代码示例却依赖 CI 环境；环境标注是 Node 18，代码却用了只在目标环境之外验证过的特性。

信号 5：结论不可复现。文章说”性能有明显改善”，但未提供测试方法、数据集和复现步骤。例如”使用 Turbopack 后性能有明显改善”（无测试方法和数据）。

信号 6：内链断裂。内链指向的文章不存在或路径错误。例如链接到 /posts/ai/ai-xxx，但站内无此文章。

信号 7：AI 味词汇。出现时代套话、空泛表达、过度承诺等。例如”本文将全面解析”这类表达。

错误示例汇总：

信号	错误示例	问题所在
断言无来源	”这个 Turbopack 配置键适用于所有 Next.js 版本”	无对应版本的官方文档
代码未运行	”执行 npm install 后运行成功”	无输出证据
版本号错误	”Node 20.1.0 LTS”	20.1.0 发布时属于 Current，不是 LTS
环境不一致	运行记录标注旧环境，代码却依赖只在目标环境之外验证过的特性	版本与验证环境不匹配
结论不可复现	”性能有明显改善”	无测试方法和数据
内链断裂	链接到 /posts/ai/ai-xxx	文章不存在
AI 味词汇	”全面解析 AI 写作”	空泛表达

处理方法：

发现信号后，立即标记 [VERIFY]，回退到对应阶段修正：

断言无来源需回退到调研阶段，补充官方文档链接或删除断言。代码未运行需回退到代码验证阶段，运行命令并记录输出。版本号错误需回退到调研阶段，复核官方 release 页。环境不一致需标注实际执行环境，或删除与环境矛盾的内容。结论不可复现需提供测试方法、数据集和复现步骤，或删除断言。内链断裂需检查站内文章路由，修正路径或删除内链。AI 味词汇需对照 anti-ai-words.json，替换为具体事实或删除。

信号识别的核心是发现问题不拖延，立即标记并回退。这样能避免在发布后才发现错误，又无法追溯责任。

没有实验环境，怎么写得诚实？

三种诚实写法

有时候确实没有完整的实验环境：付费服务、复杂集群、特定操作系统、特定硬件配置。但文章又需要提到这些内容。这时候不能编造运行证据，而是用诚实写法标注前提和限制。

三种诚实写法：

第一种：标注前提和限制。明确说明测试版本、环境和未覆盖范围。例如”示例只在 Node 18.20.0 环境验证，其他版本可能存在差异（参考：Node.js 官方文档）”

第二种：提供替代验证方法。如果无法运行完整环境，提供最小化复现步骤、Mock 数据或官方问题追踪记录。例如”当前没有可用的 Kubernetes 集群，因此只提供最小化复现步骤；这些步骤仍需在真实集群中验证。”

第三种：承认未验证。对于无法验证的断言，标注”截至写作时未验证，建议读者自行测试”或删除断言。例如”当前环境没有复现这项性能结论，因此不把它写成确定结果。”

诚实写法对比表：

场景	不诚实写法	诚实写法
版本差异	”所有版本都支持"	"本文基于 Node 18.20.0 测试，其他版本可能存在差异（参考：Node.js 官方文档）“
环境差异	”在本地运行成功"	"本文在 macOS + Node 18.20.0 环境下测试，Linux/Windows 或其他 Node 版本可能需要调整”
付费服务	”免费使用"	"测试仅覆盖免费层；付费层行为可能不同（参考：官方定价页）“
未验证断言	”性能有明显改善"	"当前环境没有复现这项性能结论，因此不把它写成确定结果”

正确示例：

✅ “本文基于 Cloudflare Workers 免费层测试（每日 100,000 请求），付费层行为可能不同。如需更高额度，请参考官方定价页（https://developers.cloudflare.com/workers/platform/pricing）。”

✅ “本文未在 Kubernetes 集群中测试，但提供了最小化复现步骤（见附录）。建议读者在真实集群中测试，并关注 Pod 资源限制和网络配置差异。”

✅ “当前没有大型项目的实测结果，因此不对 Turbopack 的构建性能下结论。建议读者在自己的项目中记录基线和对比结果。”

错误示例：

❌ “Cloudflare Workers 免费使用。“（未标注额度限制）

❌ “所有环境都能运行。“（未标注环境差异）

❌ “性能有明显改善。“（未提供测试方法和数据）

Google Search Central 建议内容提供原创信息、完整描述和有价值的分析（来源：Creating helpful, reliable, people-first content）。诚实写法不是降低标准，而是明确边界，让读者知道哪些内容已验证、哪些需要自行测试。

什么时候可以直接发布，什么时候必须重写？

发布决策树

AI 写出来的内容什么时候可以直接发布，什么时候必须重写？答案不是看字数或结构，而是看调研、验证、审核和 QA 四个阶段是否通过门禁。

发布决策树：

调研阶段：所有高置信度来源已抓取进入写作；易变事实已标记 [VERIFY] 进入写作；缺少核心来源需补调研。

代码验证阶段：所有代码示例已运行进入审核；代码示例有错误需修正或删除；无法验证的代码需标注前提或删除。

人工审核阶段：事实可溯源进入 QA；事实无来源需补来源或删除；结构一致进入 QA；结构不一致且有修改说明进入 QA；结构不一致且无修改说明需回退到大纲阶段。

发布前 QA：所有检查项通过可发布；有待定项需复核后再发布；有失败项需回退到对应阶段。

判断标准：

可以直接发布的情况：调研充分（所有高置信度来源已抓取，易变事实已标记 [VERIFY] 并复核）；代码验证（所有代码示例已运行并提供输出证据）；人工审核（事实可溯源、结构一致、AI 味已清洗）；QA 通过（发布前 QA 清单所有检查项通过）。

需要补充的情况：缺少来源（某些事实无来源链接或标注）；代码未验证（某些代码示例未提供运行证据）；内链未放置（内链计划未执行）；AI 味未清洗（存在 AI 味词汇）。

必须重写的情况：事实错误（版本号、参数、价格等核心事实错误）；结论不可复现（性能改善、对比结论等无法复现）；结构偏离大纲且无修改说明（H2/H3 与大纲不一致且未说明原因）。

发布决策的核心是每个阶段都有门禁，不能跳过。调研、验证、审核、QA 四个阶段都通过后，才能发布。发现问题不跳过，而是回到对应阶段修正。

回退优先级：

事实错误优先级最高，必须立即修正或删除断言。代码错误次之，影响读者照抄。结构不一致和内链缺失优先级较低，可以在 QA 阶段集中处理。

延伸阅读

如果你要先约束 AI 的项目上下文，可继续阅读用 CLAUDE.md 减少 AI 编码跑偏；如果你正在拆分可复用的写作与审核步骤，可参考用 Claude Code Skill 封装工作流。

站内也有一篇面向通用内容创作者的AI 写作工作流。它侧重写作效率，本篇侧重技术事实、运行证据和发布门禁，两者可以配合使用。