blog-writer

name	blog-writer
description	当用户要求基于某个需求、功能、改造、技术方案或项目实践生成博客文章时使用；必须结合用户给出的完整需求、当前项目真实实现逻辑、业务场景和代码/文档上下文做深入分析，输出通俗易懂且专业的 Markdown 博客到 `.specs/blog/《博客名称》.md`。
when_to_use	当用户说'写一篇博客'、'生成博客'、'把这个需求写成文章'、'写技术博客'、'根据这个功能写博客'、'把项目实现讲清楚'，或希望把 toLink-Service 项目的某个需求、实现、设计、治理实践、故障处理、技术取舍整理成面向读者的文章时激活。若用户只是要生成 brief / acceptance / technical_design，转对应 skill；若用户要求参考历史博客风格，只有在明确指定时才读取历史博客，否则不得参考历史博客。

Blog Writer

1. 定位

本 skill 用于根据用户提出的需求或主题，生成一篇面向读者的项目技术博客。

博客必须同时做到：

• 完整表达用户需求：读者能理解用户最初想解决什么问题、为什么需要这篇文章、需求边界是什么。
• 结合项目真实实现：基于当前仓库代码、文档、架构、数据流、消息流、配置和测试，不写脱离项目的泛泛文章。
• 通俗易懂：用清晰叙事解释背景、问题、方案和效果，让非本模块开发者也能读懂。
• 不失专业性：准确使用技术概念，讲清关键设计取舍、实现细节、风险和验证方式。

它不负责：

• 生成需求 brief（转 brief-generator）
• 生成验收契约（转 acceptance-generator）
• 生成技术方案（转 technical-design）
• 编写或修改业务代码
• 参考历史博客，除非用户明确要求参考某篇文章

2. 触发边界

2.1 适合使用

• 用户给出一个需求，希望写成技术博客或项目实践文章。
• 用户给出某个功能、模块、问题治理、架构改造，希望讲清楚它的背景、实现和价值。
• 用户要求博客既面向普通读者，又能体现项目实现细节。
• 用户希望文章输出到 .specs/blog/《博客名称》.md。

2.2 不适合使用

• 用户只要求写开发文档、接口文档、技术方案或验收用例。
• 用户要求的是营销文案、产品公告、README 或用户手册。
• 用户没有给出主题或需求，且无法从上下文推断博客对象。
• 用户明确要求"不要落文件，只在聊天里给草稿"时，不写入 .specs/blog/。

3. 输入前提

执行前必须明确：

• 博客主题或需求对象是什么。
• 目标读者是谁：技术读者、业务方、团队内部开发者、运维/交付人员，或泛技术读者。
• 博客输出名称是什么。

如果用户没有提供博客名称，应根据主题生成一个简洁中文名称；若名称会影响语义或用户可能有偏好，可以先询问。

如果用户需求描述不完整，但可以通过仓库文档、代码和上下文补齐，应先读取上下文再判断；只有关键主题不明确时才追问。

4. 必读上下文

生成博客前至少读取：

1. AGENTS.md 或当前对话中提供的项目入口说明
2. 与用户需求直接相关的 docs/ 文档
3. 与用户需求直接相关的真实代码入口
4. 如存在对应需求目录，读取 .specs/<需求名>/brief.md、.specs/<需求名>/acceptance.feature、.specs/<需求名>/technical_design.md

按需读取（根据博客主题选择相关模块）：

• Controller 层：link-api/src/main/java/com/qingluo/link/api/controller/
• 业务 Service 层：link-service/src/main/java/com/qingluo/link/service/
• 数据模型：link-model/src/main/java/com/qingluo/link/model/
• Mapper 层：link-mapper/src/main/java/com/qingluo/link/mapper/
• MQ 组件：link-components/toLink-components-mq/
• Redis 组件：link-components/toLink-components-redis/
• OSS 组件：link-components/toLink-components-oss/
• 核心工具：link-core/src/main/java/com/qingluo/link/core/
• 数据库脚本：scripts/db/init.sql、link-api/src/main/resources/schema.sql
• 测试：link-service/src/test/、link-api/src/test/

读取原则：

• 只读支撑博客分析所需的最小上下文。
• 不得凭通用 Spring Boot、MQ 或缓存经验直接写项目实现。
• 不参考历史博客，除非用户明确要求参考某篇历史博客。
• 如果代码和文档不一致，以真实代码为准，在博客中谨慎表述差异，不把不确定内容写成事实。

5. 输出位置

默认输出到：

.specs/blog/《博客名称》.md

规则：

• 如果用户给出的名称已经包含 .md，不要重复追加扩展名。
• 如果用户指定了完整文件名，按用户指定名称落文件。
• 博客名称可以是中文，避免使用 /、:、换行等不适合作为文件名的字符。
• 若同名文件已存在，必须先读取旧文件，判断是覆盖、修订还是生成新文件；不允许静默覆盖。

6. 博客内容要求

博客必须包含以下信息，但不要求机械使用这些章节名：

• 标题：清楚表达文章主题，不写空泛标题。
• 开篇背景：用具体场景说明为什么会有这个需求。
• 需求说明：通俗介绍用户提出的完整需求，包括做什么、不做什么、约束和预期效果。
• 项目上下文：说明该需求落在 toLink-Service 的哪个业务链路、模块或集成场景中。
• 实现逻辑分析：结合真实代码/文档讲清核心流程、关键模块、数据流、消息流、状态变化或配置关系。
• 设计取舍：说明为什么这样做，替代方案是什么，当前选择解决了什么问题。
• 风险与边界：说明实现中的风险、限制、异常情况、兼容性或后续演进空间。
• 验证与结果：说明如何验证这件事做对了，可以引用测试、接口、日志、脚本或人工检查方式。
• 总结：收束文章价值，避免口号式结尾。

写作要求：

• 面向人写，不写成接口文档、PRD 或技术方案堆砌。
• 先讲场景和问题，再讲方案和实现。
• 复杂实现要用类比、流程拆解或小节递进解释。
• 专业名词第一次出现时要解释清楚。
• 可以使用 Mermaid 图、表格、代码片段，但只在能帮助理解时使用。
• 代码片段要短，只展示关键逻辑；不要大段复制源码。
• 不编造不存在的模块、接口、字段、表或测试结果。
• 不写"显著提升""极大优化"等无法支撑的夸张表达。
• 不暴露 skill 内部执行过程，例如"我读取了哪些文件"。

7. 工作步骤

步骤 1：理解用户需求

从用户输入中提取：

• 博客主题
• 完整需求内容
• 目标读者
• 期望重点：业务背景、实现原理、排障复盘、架构取舍、使用教程或综合介绍
• 博客名称
• 是否要求特定风格、篇幅或结构

如果缺少博客名称，可以根据主题生成；如果缺少主题，必须追问。

步骤 2：读取项目上下文

根据主题定位相关材料：

• 先查 docs/ 中是否已有需求目录或模块文档。
• 再查相关 Java 代码目录，确认真实实现逻辑。
• 若涉及 MQ、数据库、缓存、OSS、文件解析、任务投递或外部集成，必须读取对应模块或契约文档。
• 若涉及已完成需求，优先读取 .specs/<需求名>/brief.md、.specs/<需求名>/technical_design.md，再用代码校验关键结论。

步骤 3：形成文章主线

写作前先在内部确定文章主线：

• 这篇文章要回答的核心问题是什么？
• 读者读完应理解哪条业务流程或技术链路？
• 哪些实现细节必须讲，哪些可以省略？
• 哪些内容来自用户需求，哪些来自项目实现？
• 有哪些不确定内容不能写死？

主线不清晰时，不要急着落文件，应继续读上下文或追问。

步骤 4：撰写博客

按"场景 → 需求 → 项目上下文 → 实现逻辑 → 取舍 → 风险 → 验证 → 总结"的叙事顺序组织。

正文应做到：

• 每个小节围绕一个明确问题展开。
• 业务描述和技术实现之间有过渡，不突然跳到代码细节。
• 关键实现用流程解释清楚，而不是只列文件名。
• 对读者可能困惑的点主动解释。
• 对项目中特有的历史约定、命名、状态、消息或配置作必要说明。

步骤 5：自检与修订

落文件前自检：

• 是否覆盖用户给出的完整需求。
• 是否结合了当前项目真实实现逻辑和场景。
• 是否通俗易懂，而不是只堆技术名词。
• 是否保持专业准确，没有编造事实。
• 是否有清晰标题和自然结构。
• 是否包含风险、边界或验证方式。
• 是否输出到了 .specs/blog/《博客名称》.md。

不合格则继续修订。

8. 质量门禁

以下任一情况出现，博客不合格：

• 没有结合当前项目实现，只写通用技术介绍。
• 没有讲清用户提出的完整需求。
• 只罗列模块和文件，没有解释业务场景与流程。
• 内容过于口语化，缺少专业判断和技术准确性。
• 内容过于技术文档化，普通技术读者读不懂。
• 编造不存在的实现、测试结果或性能收益。
• 忽略风险、边界、异常场景或验证方式。
• 输出路径不符合 .specs/blog/《博客名称》.md。

9. 与其他 skill 的衔接

• 用户要求写博客或技术文章：使用本 skill。
• 用户要求先理清需求：转 brief-generator。
• 用户要求生成验收场景：转 acceptance-generator。
• 用户要求技术方案：转 technical-design。
• 用户要求实现代码：转 implementation-execution。
• 用户要求把已有博客改得更好：仍可使用本 skill，但必须先读取 .specs/blog/<博客名称>.md 并明确是修订，不新建同名文章。