| 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 把源材料写成中文技术博客。必须分两阶段执行：
- 先提取并评估“上位知识簇”。
- 等用户确认文章方向后，再写最终正文。
文章首先要讲清楚一个可迁移的技术能力，不要把项目经历复述成流水账。
默认目标读者：有编程经验、能看懂基础代码和命令，但第一次系统学习这个技术点的初学者。
输入
用户可能提供：
- 源材料：笔记、排障记录、设计总结、代码片段、草稿。
- 项目背景：技术栈、业务场景、代码路径、约束条件。
- 目标读者：缺失时使用默认读者。
- 代码约束：语言、框架、版本、是否必须使用真实项目代码。
如果缺少源材料或项目背景，先一次性提问，不要写正文。
如果缺少目标读者，默认按“有编程经验的初学者”处理。
如果没有代码库或真实项目代码，不要编造。围绕推荐知识簇检索官方资料，优先使用官方文档、官方示例、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：必须说明怎么改。
