| name | blog-writer |
| description | 当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量 |
| when_to_use | 当用户说'写一篇博客'、'生成博客/技术博客'、'把这个需求/功能/实践写成文章'、'优化博客结构/标题层级'时激活。用户只要 brief/acceptance/technical_design/写代码时转对应 skill。 |
Blog Writer
目标
把用户给出的主题、需求或项目实践写成一篇可以直接发布或内部分享的中文技术博客。文章要让读者理解“为什么做、做了什么、项目里如何落地、有哪些取舍和边界、怎么验证”，而不是把代码、接口或方案文档简单改写成散文。
生成博客时同时满足四个标准：
- 准确覆盖用户需求：讲清业务背景、目标、边界、约束和预期价值。
- 贴合真实项目：所有实现判断都来自当前仓库代码、文档、契约、配置、测试或用户明确提供的信息。
- 易读但不浅：先讲场景和问题，再解释方案与实现；专业概念第一次出现时顺手解释。
- 可追溯：涉及模块、流程、消息、表结构、配置、接口、测试结果时，只写已有证据能支撑的内容。
使用边界
使用本 skill：
- 用户要求写博客、技术博客、项目实践文章、实现解读、架构改造文章、故障复盘文章。
- 用户希望把某个 brief、acceptance、technical_design、implementation_report 或已完成实现整理成面向读者的文章。
- 用户要求文章既说明需求本身，又结合 toLink-Rag 的真实实现讲清楚落地逻辑。
不要使用本 skill：
- 用户要生成需求 brief：转
brief-generator。
- 用户要生成验收契约：转
acceptance-generator。
- 用户要生成技术方案：转
technical-design。
- 用户要实现或修改代码：转
implementation-execution。
- 用户要接口文档、README、用户手册、产品公告或营销文案，除非明确要求写成技术博客。
- 用户明确要求“只在聊天里给草稿，不落文件”时，不要写入
.specs/blog/。
输入澄清
开始写作前，先从用户请求和当前上下文中提取：
- 博客主题或需求对象。
- 目标读者，例如团队内部开发者、业务方、运维交付人员、泛技术读者。
- 文章重点，例如业务背景、实现原理、架构取舍、排障复盘、教程说明或综合介绍。
- 输出文件名或博客标题。
- 是否有指定风格、篇幅、结构、发布渠道或参考材料。
如果缺少博客名称，基于主题生成一个简洁中文文件名。只有在主题本身不明确、目标读者会明显影响写法、篇幅要求无法推断，或同名文件处理需要用户决定时，才向用户追问。
取证规则
写博客前先读最小必要上下文。优先级如下：
- 用户指定的需求、文档、代码、PR、issue 或聊天上下文。
- 同一需求目录下的
brief.md、acceptance.feature、technical_design.md、implementation_report.md。
- 与主题直接相关的
docs/ 文档，尤其是 docs/api/、docs/internals/、docs/ops/。
- 与主题直接相关的真实代码入口，例如
src/api/routes/、src/core/、src/models/、src/config.py、src/core/mq/、src/core/pipeline/。
- 能证明行为的测试、脚本、配置样例、迁移或日志材料。
取证时遵守：
- 不要凭通用 FastAPI、RAG、MQ、向量数据库或工程经验替代项目证据。
- 如果代码和文档不一致，以当前代码为准；博客中可以谨慎说明“文档与实现存在差异”，但不要把不确定内容写成事实。
- 除非用户明确要求参考某篇历史博客，否则不要读取历史博客，也不要模仿历史博客风格。
- 不要为了写博客修改业务代码、迁移、配置或测试。
输出位置
默认输出到：
.specs/blog/《博客名称》.md
文件命名规则：
- 如果用户给出完整路径或文件名，按用户指定路径落文件。
- 如果用户给出的名称已经包含
.md，不要重复追加扩展名。
- 如果用户只给出标题，转换为
.specs/blog/标题.md。
- 文件名可以使用中文，但要移除或替换
/、\、:、*、?、"、<、>、|、换行等不适合作为文件名的字符。
- 如果同名文件已存在，先读取旧文件，再判断是修订、覆盖还是另存为新文件；不允许静默覆盖。
文章结构
文章不必机械使用固定章节名，但内容应覆盖（这些是要写进正文的信息块，不等于每个块各占一个 ##）：
- 背景：用真实业务或工程场景说明问题从哪里来。
- 需求：说明用户要解决什么、范围是什么、不做什么。
- 项目上下文：说明该主题落在 toLink-Rag 的哪条链路、模块、接口、消息或部署场景中。
- 实现逻辑：用流程化语言讲清核心模块、数据流、消息流、状态变化、配置关系或调用链。
- 设计取舍：说明为什么这样做，当前选择解决了什么问题，代价是什么。
- 风险与边界：说明异常场景、兼容性、限制、残留风险或后续演进空间。
- 验证方式：说明如何证明结论成立，可以引用测试、脚本、接口检查、日志、人工核验或未验证项。
- 总结：收束文章价值，不写口号式结尾。
可以使用 Mermaid、表格、短代码片段或列表，但只在能帮助读者理解时使用。代码片段只展示关键逻辑，不大段复制源码。
篇幅与 # 标题：
# 仅用于文章标题一行；正文从 ## 起。- 标题（
#）优先体现问题和价值，例如“从解析任务到召回验证：一次 RAG 链路改造的落地过程”，而不是“RAG 功能技术博客”。
- 默认写成中长篇项目实践文章，信息密度足够但不堆材料；如果用户指定短文、长文、公众号、内部分享稿，按用户指定调整。
- 开头不要铺垫过久，尽快说明场景、冲突或问题；结尾不要重复全文目录，应回到问题本身总结收获。
标题层级与主题分块
常见质量问题：正文里十几个同级 ##，读者像在看平铺目录，看不出哪些段落属于同一主题。 目标不是增加标题数量，而是相同主题收在同一个 ## 下，用少量 ### 划分子节。
层级约定
| 层级 | 用途 | 数量建议（中长篇） |
|---|
# | 文章标题 | 1 |
## | 大主题（读者扫 TOC 时的“章”） | 通常 4～7 个，含「总结」 |
### | 大主题下的子节（机制、步骤、风险项等） | 每个 ## 下 0～4 个，按需 |
#### | 尽量避免；仅当某一 ### 下仍有独立子话题且较长时使用 | 能不用就不用 |
禁止： 把「背景 / 需求 / 模块 A / 模块 B / 取舍 1 / 取舍 2 / 风险 1 / 验证 / 总结」各写成一个同级 ##（除非用户明确要求提纲式短文）。
写作前先规划「主题树」
落笔前在内部（不写入正文）先定 4～7 个 ## 大主题，再把原有信息块归类进去。步骤：
- 列出本文必须回答的问题（问题定义、怎么做、边界、怎么验等）。
- 将相近问题合并为一个大主题（一个
##）。
- 大主题内若有多条并列机制/步骤/风险，用
### 分节；若只是一两段叙述，用粗体引导语或列表即可，不必再开标题。
- 每个
## 下写 1～2 句过渡，说明该章在全文中的位置（尤其架构/治理类文章）。
何时合并为同一个 ##
下列内容应放在同一章，用 ### 或段落区分，而不是拆成多个同级 ##：
- 同一基础设施的不同侧面（例如
docs/ 目录职责 + 文档同步机器规则 → 「长期契约：docs 与机器同步」）。
- 同一工作流的上下游（例如
.specs/ 定位 + spec-as-test 四步 + flow-guard → 「开发期约束：.specs 与 spec-as-test」）。
- 同一执行层的分工与策略（例如 skills 分岗 + L1/L2/L3 车道 → 「协议层：skills 与车道」）。
- 元认知类收尾（硬/软约束 + 风险 + 验证 + 演进 → 「边界与有效性」）。
何时保留独立 ##
- 问题与动机：为何要做、约束从哪来（单独成章，篇幅短也可保留）。
- 总结：单独最后一个
##，收束全文，不与其他章节合并。
何时用 ###，何时不用标题
用 ###： 同一章内有多块并列且各有多段的内容（例如 spec-as-test 的 brief / acceptance / design 各成一节；或「机器层 vs 协议层」下的子表）。
不用标题： 仅 1～2 段说明；或章内三点并列且每点很短——用列表或段首粗体即可（例如 docs 的「读者分层 / 单一来源 / 长期与临时分离」）。
架构 / 治理类文章的参考骨架
主题涉及多模块协作、流程、约束分层时，可优先参考下列章级结构（章名按主题改写，不要照抄）：
# 《具体主题》
（可选）开篇 1 段 + 若有多层架构，此处放 **一张** Mermaid 总览图
## 问题与目标
## 《大主题 A：例如长期契约 / 核心模块》
### 子节 …
## 《大主题 B：例如开发期流程 / 数据链路》
### 子节 …
## 《大主题 C：例如执行策略 / 集成方式》
### 子节 …
## 边界与有效性（或：风险、验证与演进）
### 机器 vs 协议 / 风险 / 如何验证 / 演进方向（按需选子节，不必全有）
## 总结
单次功能改造、排障复盘类文章，可将大主题换成「背景与需求」「链路与实现」「取舍与验证」「总结」，仍保持 4～6 个 ##，不要把每个 pipeline 阶段各提一级。
Mermaid 使用
- 全文通常 0～1 张总览图即可，放在「分层/架构说明」之后、第一个大
## 之前，或该章开头。
- 图下用 1～2 句图例说明线型含义；不要把 Mermaid 当目录替代品。
- 车道表、配置对照等仍用 Markdown 表格，不必强行画图。
反例与正例（章级 ## 数量）
反例（过扁，≈10+ 个同级 ##）：
## 背景
## 为什么用 docs
## 文档同步
## 为什么用 specs
## spec-as-test
## flow-guard
## skills
## L1 L2 L3
## 硬约束
## 风险
## 如何验证
## 总结
正例（合并主题，≈5～6 个 ## + 必要 ###）：
## 问题与目标
## 长期契约：docs 分层与机器同步
### 为什么先搭 docs
### 文档同步的机器门槛
## 开发期约束：specs、spec-as-test 与 flow-guard
### 为什么需要 specs
### spec-as-test 链路
### state.yaml 与 flow-guard
## 协议层：skills 与 L1/L2/L3 车道
## 边界与有效性
## 总结
执行步骤
- 理解请求：提取主题、读者、重点、输出名和特殊要求。
- 定位材料：先找需求/设计/报告，再找相关文档和代码，用真实实现校验文档结论。
- 形成主线：明确文章要回答的核心问题、读者应带走的理解，以及哪些细节必须省略。
- 规划标题树：先定 4～7 个
## 大主题名，把信息块归类进各章，再标出需要的 ###；确认没有「一章一事」式的标题堆砌。
- 撰写正文：按主题树推进叙事（场景 → 实现 → 取舍 → 边界 → 验证）；章与章之间写简短过渡；需要总览时插入 至多一张 Mermaid。
- 落文件：写入
.specs/blog/《博客名称》.md 或用户指定路径。
- 自检修订：见下文「结构自检」+ 事实、证据、输出路径和同名文件处理。
写作风格
- 默认采用“工程叙事型 + 克制专业 + 叙事优先”的语言风格：先把真实场景和工程问题讲清楚，再自然展开方案、实现、取舍、风险和验证。
- 表达要清晰、专业、得体，有判断但不夸张，避免营销感、口号感和过度口语化。
- 让段落服务于叙事，不把文章写成接口文档、PRD、任务清单、会议纪要或代码走读。
- 技术名词可以直接使用，但第一次出现时用一句话解释它在本文中的含义；不要为了显得专业而堆砌术语。
- 每个
## 大主题围绕一个可独立扫读的问题展开；章内用 ### 或段落分节，避免连续多个同级大标题。
- 业务描述和技术实现之间要有自然过渡。
- 对项目中特有的状态、命名、消息、配置、约定或历史原因作必要解释。
- 描述收益时使用可被证据支撑的表达，例如“减少人工排查入口”“让配置漂移更容易被发现”“把测试验证前移到交付前”，不要写无法证明的宏大结论。
- 不暴露 skill 内部过程，例如“我读取了这些文件”“我按照 skill 要求检查了……”。
推荐的默认风格提示词：
请以工程叙事型中文技术博客的风格写作。文章要克制、专业、顺畅，先从真实业务或工程场景切入，讲清问题为什么出现，再展开需求边界、项目上下文、实现逻辑、设计取舍、风险和验证。不要写成接口文档、PRD、代码走读或营销文案；不要堆砌术语，也不要为了通俗而牺牲技术准确性。所有实现判断都必须由当前项目代码、文档、契约、配置、测试或用户明确提供的信息支撑。
读者分层处理：
- 面向团队内部开发者：可以保留模块名、调用链、配置项和测试方式，但要解释这些细节为什么重要。
- 面向业务方或非本模块开发者：减少源码细节，更多解释流程、约束、收益和风险。
- 面向运维/交付人员：突出配置、部署、日志、验证、回滚或排障路径。
- 如果用户没有指定读者，默认面向“熟悉后端/RAG 基础概念，但不了解本模块实现的技术读者”。
证据表达：
- 可以在正文中自然引用模块、配置、消息、接口、测试或文档作为依据，但不要堆砌文件清单。
- 如果某个结论只来自设计文档、尚未看到实现或没有测试验证，要用谨慎表达，例如“设计上计划”“当前文档描述为”“还需要通过测试确认”。
- 如果发现需求、文档和代码存在偏差，文章应描述当前可确认事实，并避免用确定语气覆盖差异。
结构自检
落文件前快速检查标题树：
禁止事项
以下情况会使博客不合格，需要继续修订：
- 只写通用技术介绍，没有结合当前项目实现。
- 没有覆盖用户给出的完整需求或主题边界。
- 只罗列文件和模块，没有解释业务场景、流程和取舍。
- 正文出现 8 个以上同级
##，或明显「一段一个 ##」的扁平结构（用户明确要求提纲式清单除外）。
- 编造不存在的模块、接口、字段、表、消息、配置、测试结果或性能收益。
- 使用“显著提升”“极大优化”“完全解决”等缺少证据的夸张表达。
- 写成资料罗列、流水账、过度模板化文章，导致读者看不到主线。
- 为了易读而省略关键边界，或为了专业感而堆叠大量读者不需要的源码细节。
- 忽略风险、边界、异常场景或验证方式。
- 静默覆盖同名博客文件。
- 输出路径不符合用户要求或默认
.specs/blog/《博客名称》.md 约定。
交付回复
完成后向用户简要说明：
- 博客已写入的路径。
- 文章覆盖的核心主题。
- 使用了哪些类型的依据，例如需求文档、实现代码、测试或契约文档；不要列出冗长文件清单。
- 如果存在未验证或证据不足的内容，明确说明。
