技术博客写作规范
Overview
此技能提供一套完整的技术博客写作约束与最佳实践。当用户请求撰写技术博客时，严格按照以下五维规范——结构、风格、格式、输出、交付——生成内容，禁止偏离任何一条规则。
写作约束
一、结构要求
执行以下结构规则：
- 标题：简洁有力，必须包含核心关键词，让读者一眼知道文章在讲什么。
- 开头：用反直觉观点或痛点问题吸引读者。禁止使用「首先让我们来了解…」「本文将介绍…」等平淡句式。开头必须制造好奇心缺口。
- 正文：
- 每个段落不超过 5 句话。
- 专业术语首次出现时，立即用通俗语言解释，不假设读者已经知道。
- 代码示例必须完整可运行，包含所有必要的 import、配置、边界处理。 - 结尾：清晰总结核心要点，并给出具体的下一步行动建议（如：去实践某个项目、阅读某篇延伸资料、运行某个命令）。
二、写作风格
执行以下风格规则：
- 语气：口语化，像朋友聊天。自然、易懂、有温度。不使用书面腔。
- 禁用词：严禁使用「首先、其次、然后、最后、综上所述、总而言之」等机械连接词。用内容本身的逻辑引导阅读，不用连接词堆砌。
- 具象化：多用具体数字和实例。禁止使用「很多、一些、非常、比较、相当」等模糊程度词。每个论点都要有数据或场景支撑。
三、格式规范
执行以下格式规则：
- 全程使用 Markdown，不掺杂纯文本或富文本。
- 代码块必须标注编程语言：```python、```javascript、```java、```go、```rust、```bash、```sql 等。不标注语言视为违规。
- 核心观点和关键结论用粗体强调，使用
**粗体**语法。
四、输出要求
生成博客时，直接输出完整 Markdown 内容。不解释、不铺垫、不出现「好的，我来写一篇…」「以下是…」等元语言。从标题的第一行开始就是博客正文。
五、交付要求：Word (.docx) 导出
生成 Markdown 博客后，立即执行 Word 导出流程。 这是强制步骤，不可跳过。
导出步骤
- 将已生成的博客 Markdown 内容写入临时文件，如
_blog_temp.md。 - 使用
scripts/md_to_docx.py脚本将 Markdown 转换为 Word 文档：
python scripts/md_to_docx.py _blog_temp.md <output_filename>.docx
- 删除临时 Markdown 文件
_blog_temp.md。 - 使用
present_files工具展示生成的.docx文件。 - 告知用户文档已生成，包括文件名和路径。
脚本说明
scripts/md_to_docx.py 支持以下 Markdown 到 Word 的格式映射：
| Markdown | Word 效果 |
|---|---|
# ## ### 标题 |
Word 内置标题样式 |
**粗体** |
加粗字体 |
`行内代码` |
Consolas 红色等宽字体 |
```python ... ``` |
灰色背景代码块，顶部标注语言 |
- 列表项 |
项目符号列表 |
1. 有序项 |
编号列表 |
> 引用 |
缩进灰色斜体引用 |
--- 分割线 |
水平分隔线 |
文件命名规则
Word 文件名基于博客标题自动生成：取标题核心关键词，用下划线连接，去除标点符号。例如：
- 标题「PyTorch 入门指南：从 Tensor 到训练」→ PyTorch入门指南_从Tensor到训练.docx
python-docx 依赖
首次运行前，确保 python-docx 已安装：
pip install python-docx
写作前自查清单
在输出每一篇技术博客前，逐项确认：
- [ ] 标题包含核心关键词且简洁有力？
- [ ] 开头使用了反直觉观点或痛点问题？
- [ ] 正文每个段落 ≤5 句话？
- [ ] 首次出现的专业术语已解释？
- [ ] 所有代码块标注了语言且完整可运行？
- [ ] 没有出现「首先、其次、最后、综上所述」等禁用词？
- [ ] 模糊程度词（很多、一些、非常）已替换为具体数字？
- [ ] 核心结论用了粗体强调？
- [ ] 结尾有核心总结 + 下一步行动建议？
- [ ] 没有输出元语言（如「好的」「以下是」）？
- [ ] 已执行 Word 导出并展示 .docx 文件？
参考示例
以下是符合规范的博客开头与结尾示例，供写作时参考。
开头示例
不符合规范的开头：
> 首先让我们来了解一下 React Hooks 的基本概念。Hooks 是 React 16.8 引入的新特性……
符合规范的开头：
> 90% 的 React 开发者都在用 Hooks，但只有不到 30% 的人真正理解 useEffect 的清理机制。上周我 review 了 47 个 PR，其中 32 个都犯了同一个隐蔽的内存泄漏错误。
结尾示例
不符合规范的结尾：
> 综上所述，本文介绍了 Hooks 的使用方法，希望对大家有所帮助。
符合规范的结尾：
> useEffect 的清理函数不是可选项——它是防止内存泄漏的最后防线。 记住三条规则就行：(1) 副作用产生订阅就返回清理函数，(2) 依赖数组不撒谎，(3) 异步操作考虑竞态。
>
> 现在打开你的项目，全局搜索 useEffect(，逐个检查每个 effect 有没有返回清理函数。修完一个，commmit 一个。
