blog-writer

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/。

输入澄清

开始写作前，先从用户请求和当前上下文中提取：

• 博客主题或需求对象。
• 目标读者，例如团队内部开发者、业务方、运维交付人员、泛技术读者。
• 文章重点，例如业务背景、实现原理、架构取舍、排障复盘、教程说明或综合介绍。
• 输出文件名或博客标题。
• 是否有指定风格、篇幅、结构、发布渠道或参考材料。

如果缺少博客名称，基于主题生成一个简洁中文文件名。只有在主题本身不明确、目标读者会明显影响写法、篇幅要求无法推断，或同名文件处理需要用户决定时，才向用户追问。

取证规则

写博客前先读最小必要上下文。优先级如下：

1. 用户指定的需求、文档、代码、PR、issue 或聊天上下文。
2. 同一需求目录下的 brief.md、acceptance.feature、technical_design.md、implementation_report.md。
3. 与主题直接相关的 docs/ 文档，尤其是 docs/api/、docs/internals/、docs/ops/。
4. 与主题直接相关的真实代码入口，例如 src/api/routes/、src/core/、src/models/、src/config.py、src/core/mq/、src/core/pipeline/。
5. 能证明行为的测试、脚本、配置样例、迁移或日志材料。

取证时遵守：

• 不要凭通用 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. 将相近问题合并为一个大主题（一个 ##）。
3. 大主题内若有多条并列机制/步骤/风险，用 ### 分节；若只是一两段叙述，用粗体引导语或列表即可，不必再开标题。
4. 每个 ## 下写 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 车道
## 边界与有效性
## 总结

执行步骤

1. 理解请求：提取主题、读者、重点、输出名和特殊要求。
2. 定位材料：先找需求/设计/报告，再找相关文档和代码，用真实实现校验文档结论。
3. 形成主线：明确文章要回答的核心问题、读者应带走的理解，以及哪些细节必须省略。
4. 规划标题树：先定 4～7 个 ## 大主题名，把信息块归类进各章，再标出需要的 ###；确认没有「一章一事」式的标题堆砌。
5. 撰写正文：按主题树推进叙事（场景 → 实现 → 取舍 → 边界 → 验证）；章与章之间写简短过渡；需要总览时插入 至多一张 Mermaid。
6. 落文件：写入 .specs/blog/《博客名称》.md 或用户指定路径。
7. 自检修订：见下文「结构自检」+ 事实、证据、输出路径和同名文件处理。

写作风格

• 默认采用“工程叙事型 + 克制专业 + 叙事优先”的语言风格：先把真实场景和工程问题讲清楚，再自然展开方案、实现、取舍、风险和验证。
• 表达要清晰、专业、得体，有判断但不夸张，避免营销感、口号感和过度口语化。
• 让段落服务于叙事，不把文章写成接口文档、PRD、任务清单、会议纪要或代码走读。
• 技术名词可以直接使用，但第一次出现时用一句话解释它在本文中的含义；不要为了显得专业而堆砌术语。
• 每个 ## 大主题围绕一个可独立扫读的问题展开；章内用 ### 或段落分节，避免连续多个同级大标题。
• 业务描述和技术实现之间要有自然过渡。
• 对项目中特有的状态、命名、消息、配置、约定或历史原因作必要解释。
• 描述收益时使用可被证据支撑的表达，例如“减少人工排查入口”“让配置漂移更容易被发现”“把测试验证前移到交付前”，不要写无法证明的宏大结论。
• 不暴露 skill 内部过程，例如“我读取了这些文件”“我按照 skill 要求检查了……”。

推荐的默认风格提示词：

请以工程叙事型中文技术博客的风格写作。文章要克制、专业、顺畅，先从真实业务或工程场景切入，讲清问题为什么出现，再展开需求边界、项目上下文、实现逻辑、设计取舍、风险和验证。不要写成接口文档、PRD、代码走读或营销文案；不要堆砌术语，也不要为了通俗而牺牲技术准确性。所有实现判断都必须由当前项目代码、文档、契约、配置、测试或用户明确提供的信息支撑。

读者分层处理：

• 面向团队内部开发者：可以保留模块名、调用链、配置项和测试方式，但要解释这些细节为什么重要。
• 面向业务方或非本模块开发者：减少源码细节，更多解释流程、约束、收益和风险。
• 面向运维/交付人员：突出配置、部署、日志、验证、回滚或排障路径。
• 如果用户没有指定读者，默认面向“熟悉后端/RAG 基础概念，但不了解本模块实现的技术读者”。

证据表达：

• 可以在正文中自然引用模块、配置、消息、接口、测试或文档作为依据，但不要堆砌文件清单。
• 如果某个结论只来自设计文档、尚未看到实现或没有测试验证，要用谨慎表达，例如“设计上计划”“当前文档描述为”“还需要通过测试确认”。
• 如果发现需求、文档和代码存在偏差，文章应描述当前可确认事实，并避免用确定语气覆盖差异。

结构自检

落文件前快速检查标题树：

• 全文 # 仅 1 个；## 数量在 4～7（极短文可 3，长文不超过 8），没有把每个信息块都提成同级 ##。
• 同一主题（同一机制/同一流程/同一评估维度）只对应 一个 ##，子话题用 ### 或列表。
• 每个 ## 下有过渡句；相邻章之间读者能感到递进（问题 → 方案 → 边界），而非词条罗列。
• ### 未滥用：短内容没有为凑结构而开三级标题。
• 若有多层架构，开篇或首章有 0～1 张 Mermaid 总览（非必须，但架构/治理类优先考虑）。

禁止事项

以下情况会使博客不合格，需要继续修订：

• 只写通用技术介绍，没有结合当前项目实现。
• 没有覆盖用户给出的完整需求或主题边界。
• 只罗列文件和模块，没有解释业务场景、流程和取舍。
• 正文出现 8 个以上同级 ##，或明显「一段一个 ##」的扁平结构（用户明确要求提纲式清单除外）。
• 编造不存在的模块、接口、字段、表、消息、配置、测试结果或性能收益。
• 使用“显著提升”“极大优化”“完全解决”等缺少证据的夸张表达。
• 写成资料罗列、流水账、过度模板化文章，导致读者看不到主线。
• 为了易读而省略关键边界，或为了专业感而堆叠大量读者不需要的源码细节。
• 忽略风险、边界、异常场景或验证方式。
• 静默覆盖同名博客文件。
• 输出路径不符合用户要求或默认 .specs/blog/《博客名称》.md 约定。

交付回复

完成后向用户简要说明：

• 博客已写入的路径。
• 文章覆盖的核心主题。
• 使用了哪些类型的依据，例如需求文档、实现代码、测试或契约文档；不要列出冗长文件清单。
• 如果存在未验证或证据不足的内容，明确说明。