# Tech Blog Writer

> 技术博客写作与更新。当用户需要撰写或更新中文技术博客文章、技术教程、开发笔记、源码分析、实践总结时使用。支持自动评审（AI味检测、口语化检查、结构评估）和迭代修改。生成的 Markdown 文件自动内嵌 SVG 图解辅助理解复杂概念。

- Skill: `hacxy/tech-blog-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hacxy/tech-blog-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hacxy/tech-blog-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: hacxy (https://skillmd.com/u/hacxy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hacxy/tech-blog-writer

---


# 技术博客写作

## 工作流程

```
用户提示词 → 分析主题 → 规划大纲 → 撰写文章 → 生成 SVG 图解 → 子 Agent 评审 → 迭代修改 → 输出终稿
```

## Step 1: 分析主题与规划

从用户提示词中提取：

- **主题**：写什么技术/框架/工具
- **目标读者**：初学者 / 有经验开发者 / 架构师
- **文章类型**：教程型 / 问题解决型 / 对比型 / 源码分析 / 实践总结
- **深度**：入门 / 进阶 / 深入

基于分析结果规划大纲，遵循渐进式披露原则：先大图，后细节。

## Step 2: 撰写文章

### 文件命名

根据用户提示词生成英文文件名，多个单词以 `-` 分隔：

- "写一篇 React Hooks 的教程" → `react-hooks-tutorial.md`
- "Vue3 响应式原理" → `vue3-reactivity-deep-dive.md`

### 写作规范

详细写作指南见 [references/writing-guide.md](references/writing-guide.md)，核心要点：

**结构**：引言（写给谁、获得什么）→ 背景/问题 → 核心内容（分步骤）→ 总结 → 参考资料

**讲清概念用 ADEPT 方法**：

1. 类比——它像什么？
2. 图解——用 SVG 辅助理解
3. 示例——让读者亲身体验
4. 通俗描述——用自己的话说
5. 技术描述——最后才上术语

**口语化要求**：

- 用"你"而非"读者"、"开发者"
- 像跟同事聊天，不像写论文
- 短句为主，一个句子一个观点
- 用问句引导思考："性能怎么办？"
- 允许口语词："说实话"、"坦白说"、"嗯"

**去 AI 味**：

- 禁用套话："值得注意的是"、"可以说"、"毋庸置疑"
- 禁用三连排比："快速、可靠、可扩展"
- 禁用"不仅是 X，更是 Y"句式
- 段落长度要有变化，不要每段都是 3-4 句
- 结尾不要用"总而言之"、"综上所述"
- 加入真实细节：踩过的坑、报错信息、开发环境
- 承认不确定性："我不确定这是最佳方案"

**外部链接**：

- 引用技术点时必须附上外部链接，指向官方文档或权威来源
- 不要凭空捏造链接，确保链接真实有效
- 格式：`[文档名称](https://...)`

### 代码示例要求

- 最小可运行：只展示核心逻辑
- 关键行加注释，解释"为什么"而不只是"是什么"
- 附上运行结果或预期输出
- 代码块标注语言类型

## Step 3: 生成 SVG 图解

**当文章涉及以下内容时，必须生成 SVG 图解**：

- 系统架构、组件关系
- 数据流、请求链路
- 状态变化、生命周期
- 算法步骤、执行流程
- 抽象概念的可视化解释

### SVG 设计规范

```html
<!-- SVG 模板 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" role="img" aria-label="图表描述">
  <!-- 样式定义 -->
  <defs>
    <style>
      .box { fill: #f0f4ff; stroke: #4a90d9; stroke-width: 2; rx: 8; }
      .text { font-family: system-ui, sans-serif; font-size: 14px; fill: #333; }
      .arrow { stroke: #666; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
      .highlight { fill: #fff3e0; stroke: #f57c00; }
    </style>
    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#666" />
    </marker>
  </defs>
  
  <!-- 内容 -->
  <rect class="box" x="50" y="50" width="150" height="60" />
  <text class="text" x="125" y="85" text-anchor="middle">组件 A</text>
  
  <line class="arrow" x1="200" y1="80" x2="300" y2="80" />
  
  <rect class="box" x="300" y="50" width="150" height="60" />
  <text class="text" x="375" y="85" text-anchor="middle">组件 B</text>
</svg>
```

### 设计原则

- 宽度 600-800px，适配内容区域
- 颜色对比清晰，浅色背景 + 深色边框
- 使用 `aria-label` 添加无障碍描述
- 简洁为主，避免过度装饰
- 中文标注，与文章语言一致

## Step 4: 子 Agent 评审

文章初稿完成后，启动子 Agent 进行评审。

### 评审维度

**1. AI 味检测**（参考 Wikipedia AI 写作特征清单）

- 是否有套话填充词？
- 是否有三连排比？
- 段落长度是否过于均匀？
- 是否有模糊权威引用？
- 是否有过度拔高的语言？

**2. 口语化检查**

- 是否用"你"而非"读者"？
- 是否像跟同事聊天？
- 是否有书面套话？
- 读出来是否自然？

**3. 结构评估**

- 是否遵循渐进式披露？
- 是否有清晰的引言（写给谁、获得什么）？
- 代码示例是否附有说明和输出？
- 是否有外部链接引用？

**4. 内容准确性**

- 技术概念是否正确？
- 代码是否可运行？
- 链接是否有效？

### 评审输出格式

```markdown
## 评审报告

### AI 味评分：X/10（越低越好）
- 问题列表：...

### 口语化评分：X/10（越高越好）
- 问题列表：...

### 结构评分：X/10
- 问题列表：...

### 修改建议
1. 具体建议 1
2. 具体建议 2
...
```

## Step 5: 迭代修改

根据评审报告修改文章：

1. 逐条处理修改建议
2. 重新检查去 AI 味和口语化
3. 如有需要，更新 SVG 图解
4. 输出终稿

## 输出

最终输出包含：

1. Markdown 文章文件（含内嵌 SVG）
2. 评审报告（如用户需要）