technical-blog-doc

技术博客文档

撰写可复现的技术内容，确保其中的主张、代码、命令和版本均可追溯至证据。

路由

• 产品文档套件或 PRD 层级：转交给 full-stack-doc 技能。安装命令：npx skills add full-stack-skills/document-skills --skill full-stack-doc。
• 仅限 API 的文档：转交给 api-doc-generator 技能。安装命令：npx skills add full-stack-skills/document-skills --skill api-doc-generator。
• 协作撰写提案/RFC：转交给 doc-coauthoring 技能。安装命令：npx skills add full-stack-skills/document-skills --skill doc-coauthoring。

证据模型

撰写前先对材料分类：

标签	含义
官方事实	有当前官方文档或发行说明支持
源码观察	已在检查的代码仓库中确认
运行验证	已在当前环境中通过执行命令或测试确认
推断	合理的解释，但未经直接验证
待确认	信息缺失、冲突或不稳定

不要将 推断 或 待确认 表述为已验证的事实。涉及版本、API、支持矩阵或其他时效性主张时，请查阅权威来源。

工作流

1. 明确读者约定

确定目标读者、预期的起始知识、承诺的成果、目标环境和产物位置。如果文章介绍的是本地实现，请检查实际代码仓库。

2. 建立验证矩阵

记录文章所依赖的事实：

• 操作系统和架构；
• 语言/运行时和包管理器版本；
• 框架、SDK、模型或服务版本；
• 所需凭据和外部服务；
• 必须运行的命令；
• 预期输出和故障模式；
• 基准测试、限制和兼容性主张的来源。

3. 选择结构

需要完整的文章框架时，请复制 assets/technical-blog-template.md。删除无关章节，不要用泛泛的文字填充。

典型结构：

1. 成果和范围
2. 前提条件和已验证环境
3. 架构或请求流程
4. 分步实现
5. 配置和安全
6. 运行和验证
7. 故障排除
8. 限制和生产环境注意事项
9. 验证记录和来源

4. 根据可执行产物撰写

• 优先使用当前代码仓库中的代码和配置，而非重构的代码片段。
• 代码片段应尽量精简，同时保证语法完整。
• 对机密使用占位符，并对令牌、个人数据和内部端点进行脱敏。
• 解释每个步骤的必要性，而不只是说明要粘贴什么。
• 截图和图表应有明确的说明用途。
• Markdown 原生流程图使用 Mermaid；需要精确的 UML/C4 记法时使用 PlantUML。

5. 验证

在获得授权后运行安全的命令和测试。记录实际执行的命令和结果。如果无法执行，请如实说明，并提供准确的验证步骤，不要声称验证成功。

添加验证章节：

## 验证记录

- 验证日期：{YYYY-MM-DD}
- 操作系统：{系统与架构}
- 运行时版本：{版本}
- 框架/SDK 版本：{版本}
- 执行命令：`{命令}`
- 结果：{实际结果}
- 未验证内容：{无/列表}
- 官方资料：{链接列表}

6. 冷读文章

检查没有对话上下文的读者能否识别前提条件、区分命令与输出、复现结果、解决常见故障并验证外部主张。

质量规则

• 使用一个 H1，并保持标题层级连贯。
• 每个围栏代码块都应注明 Shell 或语言。
• 对版本敏感的主张应注明日期和来源。
• 除非允许再分发，否则不要复制官方图片；适当时应链接或重新绘制原创说明图。
• 验证相对链接和本地图片引用。
• 不要仅凭开发示例就提出适用于所有生产环境的主张。
• 保留用户现有的文章结构，除非更改能显著提升可读性。

完成约定

报告输出文件、已验证的命令/测试、使用的源链接、测试环境，以及所有剩余的推断或待确认事项。