| 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. 必读上下文
生成博客前至少读取：
AGENTS.md 或当前对话中提供的项目入口说明- 与用户需求直接相关的
docs/ 文档
- 与用户需求直接相关的真实代码入口
- 如存在对应需求目录，读取
.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 并明确是修订，不新建同名文章。
