# Notes To Blog

> Only invoke when explicitly requested via "@notes-to-blog"、"博客知识提取"、"笔记整理成博客". Do NOT auto-trigger. Manual-only skill for turning notes, debugging records, design summaries, code snippets, or rough drafts into a Chinese technical blog.

- Skill: `unix2dos/notes-to-blog` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add unix2dos/notes-to-blog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unix2dos/notes-to-blog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unix2dos (https://skillmd.com/u/unix2dos)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/unix2dos/notes-to-blog

---


# 博客知识提取

## 用途

用这个 skill 把源材料写成中文技术博客。必须分两阶段执行：

1. 先提取并评估“上位知识簇”。
2. 等用户确认文章方向后，再写最终正文。

文章首先要讲清楚一个可迁移的技术能力，不要把项目经历复述成流水账。

默认目标读者：有编程经验、能看懂基础代码和命令，但第一次系统学习这个技术点的初学者。

## 输入

用户可能提供：

- 源材料：笔记、排障记录、设计总结、代码片段、草稿。
- 项目背景：技术栈、业务场景、代码路径、约束条件。
- 目标读者：缺失时使用默认读者。
- 代码约束：语言、框架、版本、是否必须使用真实项目代码。

如果缺少源材料或项目背景，先一次性提问，不要写正文。

如果缺少目标读者，默认按“有编程经验的初学者”处理。

如果没有代码库或真实项目代码，不要编造。围绕推荐知识簇检索官方资料，优先使用官方文档、官方示例、API reference、release note，其次使用权威技术资料。

## 核心原则

一篇文章只讲一个可迁移的技术能力。判断标准是：

> 读者看完后，能不能脱离当前项目，在自己的项目里复用这个知识点？

推荐文章前，必须先在内部检查：

> 这些知识簇是否共同回答同一个更大的读者问题？

如果答案是“是”，必须合并成一个上位知识簇。不要把主知识点、子机制、章节材料、项目案例平铺成候选文章。

默认推荐 1 篇。只有当多个知识簇都能独立成文且互不依赖时，才建议拆成 2-3 篇。最多推荐 3 篇。

## 合并与拆分规则

满足以下任一条件，默认合并：

- 同一读者问题。
- 同一技术对象。
- 上下游强依赖。
- 同一学习目标。
- 同一最小模型。
- 其中一个只是机制，不是完整主题。

只有满足以下任一条件，才允许拆成第二篇：

- 读者问题不同。
- 学习目标不同。
- 最小模型不同。
- 目标读者不同。
- 合并后必须讲 5 个以上必讲机制，或明显超过 3000 字。
- 某个知识点自己也能完整回答“是什么 / 最小模型 / 机制 / 建议 / 边界”。

## 阶段一：上位知识簇评估

阶段一只输出上位知识簇评估、推荐文章和文章骨架。阶段一结束后必须停下来等待用户确认，未确认前不要写正文。

内部可以先提取原始候选点，但不要展示完整原始候选点表。展示时只展示归并后的上位知识簇。

每个上位知识簇按 6 个维度评分，每项 1-5 分：

| 维度 | 1 分 | 3 分 | 5 分 |
|---|---|---|---|
| 可迁移性 | 只对当前项目有意义 | 同类项目可参考 | 脱离项目也能复用 |
| 认知增量 | 常识或表层命令 | 能纠正常见误解 | 解释初学者常卡住的机制 |
| 技术深度 | 只有用法 | 有机制和配置 | 有机制、边界、取舍、反例 |
| 材料证据 | 只有作者说法 | 有少量配置/命令 | 有真实代码、配置、错误或官方资料支撑 |
| 成文完整度 | 只能写片段 | 能写成短文 | 能完整讲“是什么/怎么跑/怎么落地/边界” |
| 学习必要性 | 可有可无，删掉不影响主知识 | 有助于理解，可作为补充 | 不讲它，读者无法理解主知识 |

阈值：

- `>= 25`：推荐独立成文。
- `21-24`：可作为章节或项目案例。
- `< 21`：不建议独立成文。

评分阈值用于判断知识簇本身的成文潜力，但不能覆盖上位知识簇合并规则。若某个高分知识簇与主推荐文章存在强依赖，不要给它自定义建议标签。`建议` 列只能使用 `推荐成文`、`作为章节`、`不推荐` 三种值；依赖关系和不单独拆篇的理由写进 `为什么合并`、`推荐理由` 或 `不推荐单独成文的内容`。

每个推荐知识簇必须分成 4 类：

- 必讲机制：不讲它，读者无法理解主知识。
- 可选补充：有助于理解，但可以压缩或放到提示里。
- 项目案例：用来落地，不抢主线。
- 删除内容：有趣但会分散主线，正文不写。

## 阶段一输出

使用这个格式：

```markdown
## 上位知识簇评估

| 上位知识簇 | 共同回答的读者问题 | 包含内容 | 为什么合并 | 可迁移性 | 认知增量 | 技术深度 | 材料证据 | 成文完整度 | 学习必要性 | 总分 | 建议 |
|---|---|---|---|---:|---:|---:|---:|---:|---:|---:|---|
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | 推荐成文 / 作为章节 / 不推荐 |

## 推荐文章

建议写 N 篇：

1. 《短主标题：可选副标题》
   主知识簇：...
   推荐理由：...

   知识簇结构：
   - 必讲机制：...
   - 可选补充：...
   - 项目案例：...
   - 删除内容：...

   文章骨架：
   1. ...
   2. ...
   3. ...

## 不推荐单独成文的内容

- `内容 A`：为什么不单独成文，放到哪里。
- `内容 B`：为什么不单独成文，放到哪里。

请确认是否按推荐文章写。
```

## 标题规则

每个推荐知识簇只给一个最终文章标题，不给多个备选。

标题采用“短主标题 + 可选副标题”：

- 主标题优先 12-20 个中文字符。
- 主标题表达核心思想，不把所有子机制塞进标题。
- 副标题补充范围。
- 不用“为什么我们”“踩坑”“工程内幕”“半天排查”“一次事故”。

示例：

- 《用 Firehose 搬运日志：从 CloudWatch Logs 到 S3》
- 《把 Terraform 收进平台：从 YAML 到 apply》
- 《一次性 Runner 怎么跑：Gitea Actions 的 workflow_job 模型》
- 《ECS Secret 注入机制》

## 阶段二：最终正文

只有在用户确认知识簇和文章方向后，才进入阶段二。

如果没有代码库可验证，内部检索官方或权威资料。不要单独输出“知识依据摘要”。检索只服务正文严谨性。最终文章文末保留简短参考资料。

默认正文结构：

```markdown
# 知识点标题：读者收益

开头 2-4 段：
- 用一个通用问题引入，不要一上来讲作者项目。
- 说明这篇文章讲什么技术点。
- 给一句明确的默认建议。

## 先用一句话理解它

## 最小模型：先看它怎么跑起来

## 核心机制一：...

## 核心机制二：...

## 项目案例：它在项目里怎么落地

## 明确建议：直接这样选

## 常见误区和边界

## 小结

## 参考资料
```

正文硬性要求：

- 必须有 `最小模型`。
- 至少有 2 个 `核心机制` 章节。
- 必须有 `项目案例`；如果源材料没有项目案例，改成 `实践案例`。
- 必须有 `明确建议`，用命令式表达，不用“看情况”收尾。
- 必须有 `常见误区和边界`。
- 必须有 `参考资料`，只放 2-5 个官方或权威来源。
- 全文目标 1500-3000 字，可根据知识点复杂度微调。
- 使用 Markdown，标题最多到 `#`、`##`、`###`。
- 关键名词第一次出现必须解释。
- 代码、配置、命令、图表、表格前后必须解释“它说明什么机制”。

## 最小模型

每篇文章必须有一个“最小理解载体”。不强制是代码，可以是：

- 最小代码片段。
- 最小配置。
- 最小命令。
- 最小流程图。
- 输入输出对照。
- 对比表格。

只保留理解主知识点所需的内容。不要引入完整项目上下文，也不要在读者建立模型前塞入项目专有名词。

## 明确建议

每篇文章必须给出明确、可执行的绝对建议，但建议要绑定前提：

- 开头给一句短结论。
- 给出默认选择。
- 用命令式表达。
- 明确前提：这个建议在哪类场景下成立。
- 明确反例：什么条件下不要套用这个建议。

示例：

```text
如果目标是把 CloudWatch Logs 批量落到 S3 做离线搜索，默认使用 Firehose -> S3，buffer 从 64 MiB / 300 秒开始。不要把它当实时 tail 工具。
```

## 写作要求

- 短句优先。
- 一段只讲一个意思。
- 不要让个人排障过程成为主线。
- 项目经历只用作短引入、落地案例、反例或踩坑补充。
- 不写“面试考点”“面试速记”。
- 不编造 API、版本、云厂商行为或项目代码。
- 如果源材料和官方资料冲突，以官方资料为准，并在正文里修正。

禁止使用：

- 标志着
- 见证了
- 充满活力
- 深入一层
- 更深地说
- 从 X 到 Y 的闭环
- 赋能
- 抓手

最终判断标准：

> 这句话我会不会真的这样讲给一个聪明朋友听？

不会，就重写。

## 阶段二输出

阶段二输出最终文章正文，然后附带写作自评。自评不是文章正文，不参与发布。正文和自评之间用分隔线隔开：

```markdown
---

## 写作自评

| 维度 | 分数 | 说明 |
|---|---:|---|
| 主知识点单一 | 1-5 | ... |
| 学习台阶清楚 | 1-5 | ... |
| 初学者友好 | 1-5 | ... |
| 技术严谨 | 1-5 | ... |
| 明确建议 | 1-5 | ... |
| 项目案例克制 | 1-5 | ... |

结论：可发布 / 可发布但建议小修 / 必须重写
```

自评阈值：

- 平均分 `>= 4.5`：可发布。
- 平均分 `4.0-4.4`：可发布但建议小修。
- 平均分 `< 4.0`：必须重写。
- 任一项 `< 4`：必须说明怎么改。