technical-manuscript-verification

技术手稿核验

核心视角

技术类非虚构内容必须能在读者的环境中正常使用，而不能只存在于作者的记忆里。核验需要检查命令能否运行、配置是否一致、截图是否与正文相符、链接是否仍然有效、安全边界是否明确，以及读者是否有足够的上下文来应对故障。

使用此技能审查：

• 技术书籍章节和教程。
• 自托管和基础设施指南。
• 代码片段、Shell 命令、Docker Compose 文件、配置示例、图表和截图。
• 依赖当前平台行为或特定版本文档的声明。
• Beta 发布前或正式出版前的技术准确性。

参考资料导航

需求	阅读
核验概念和术语	references/core/knowledge.md
审查规则和证据标准	references/core/rules.md
示例发现和核验表格	references/core/examples.md
快速核验清单	references/core/checklist.md
分步核验流程	workflows/verify-technical-manuscript.md

工作流程

1. 确定核验范围

识别需要核验的内容：

• 命令和代码。
• 配置文件和环境变量。
• 安装和设置步骤。
• 截图、图表和预期输出。
• 链接和外部参考资料。
• 安全、防护、隐私、数据丢失和费用警告。

如果手稿较长，请进行范围较窄的审查。

2. 建立证据表

逐项记录技术内容：

Item | Location | Assumption | Verification method | Result | Fix

对于能够核查的内容，不要仅凭看似合理就作出判断。

3. 在真实或模拟环境中核验

优先运行命令、检查配置、检查链接、渲染示例或查阅一手文档。如果执行不安全或不切实际，请说明所依据的假设以及仍需补充的证据。

4. 按读者风险对发现分类

优先关注：

• 数据丢失、安全暴露、隐私损害或不可逆变更。
• 会失败或产生不同输出的命令。
• 会阻碍读者的前置条件缺失。
• 工具或平台变更导致的时效性信息偏差。
• 具有误导性的截图或图表。

5. 提供作者可直接采用的修正建议

提出具体修改：

• 添加前置条件。
• 修改命令或配置。
• 添加预期输出。
• 添加警告、回滚或故障排查说明。
• 将易变步骤移至配套资源。
• 标记需根据当前文档核验的声明。

输出格式

核验手稿时，请返回：

1. 核验范围和假设。
2. 按读者风险排序的发现。
3. 标明通过／失败／未测试状态的证据表。
4. 手稿的具体修改内容。
5. 需要根据当前一手来源核验的事项。
6. 建议进行的 Beta 读者或专家审查检查。

质量标准

内容应具体且有证据支撑。明确区分“已核验”“可能如此”“未测试”和“在此处不宜测试”。除非确实检查过，或已明确说明限制，否则绝不要暗示某项技术指令能够正常运行。