notes-to-blog

name	notes-to-blog
description	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 把源材料写成中文技术博客。必须分两阶段执行：

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

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

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

输入

用户可能提供：

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

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

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

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

核心原则

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

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

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

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

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

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

合并与拆分规则

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

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

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

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

阶段一：上位知识簇评估

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

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

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

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

阈值：

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

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

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

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

阶段一输出

使用这个格式：

## 上位知识簇评估

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

## 推荐文章

建议写 N 篇：

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

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

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

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

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

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

标题规则

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

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

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

示例：

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

阶段二：最终正文

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

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

默认正文结构：

# 知识点标题：读者收益

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

## 先用一句话理解它

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

## 核心机制一：...

## 核心机制二：...

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

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

## 常见误区和边界

## 小结

## 参考资料

正文硬性要求：

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

最小模型

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

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

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

明确建议

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

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

示例：

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

写作要求

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

禁止使用：

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

最终判断标准：

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

不会，就重写。

阶段二输出

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

---

## 写作自评

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

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

自评阈值：

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