Blog Md Writer

Blog MD Writer

这个 skill 用来把资料整理成公开可读、适合学习者阅读的中文技术博客。默认交付物是一个本地 .md 文件和一组图片方案；图片可以由 Codex 直接生成，也可以只输出提示词，让用户去别处生成后放回指定路径。是否上传到 CSDN 是可选步骤，必须在本地 Markdown 和图片都完成后再问用户。

核心原则

不要从资料目录出发机械改写，要从读者要解决的问题出发。

输入资料可能是课程笔记、飞书文档、会议记录、代码分析、调试日志、设计文档或零散素材。目标不是照搬原文，而是整理出一篇原创博客：讲清楚心智模型，保留有用的命令和代码，去掉内部信息，用插图帮助读者理解。

工作流程

1. 收集输入并判断读者对象。

   • 如果用户给的是飞书/wiki 链接，用飞书文档能力读取真实文档内容。
   • 如果用户给的是本地文件，直接读取文件。
   • 如果用户只给主题、没有资料，先询问是否补充资料，或是否允许联网/检索资料。
   • 写公开博客前先判断资料边界：去掉内部 Gerrit 链接、公司内网链接、账号密钥、未公开客户信息、内部流程等内容，除非用户明确说这些可以公开。

2. 提炼文章主线。

   • 从资料里提炼 3 到 6 个核心知识点。
   • 优先使用问题驱动结构：遇到什么问题、哪个概念能解释、用什么命令/代码验证、真实工作里怎么选。
   • 不要机械复刻原始文档的大纲。长资料要压缩成清晰的教学路线。

3. 先规划图片，再写最终 Markdown。

   • 一篇正常长博客默认使用 1 张封面图，加几张正文教学图。
   • 正文图必须承担教学任务，例如：数据流、分层架构、时序流程、工具链、排障决策树、概念地图。
   • 不要做纯装饰图。如果图片不能帮助读者理解内容，就不要放。
   • 图片顺序就是文件名顺序：第 1 张封面图固定命名为 1.png，后续正文图依次命名为 2.png、3.png、4.png。Markdown 图片引用、提示词清单、CSDN 上传映射都必须使用同一顺序。
   • 每篇文章只使用一个文章目录：artifacts/<article-slug>/。Markdown、image_prompts.md、图片子目录和 CSDN 发布记录都放在这个目录内，不再把同一篇文章拆到 artifacts/ 和 output/ 两套目录。

4. 生图前必须询问用户选择哪种模式。

   • 询问示例：我已经规划好插图。你要我直接生成图片，还是只输出每张图的提示词和目标路径，你去外部生成后放回来？
   • 如果用户选择“直接生成”，使用 imagegen skill，默认走内置图片生成能力。
   • 如果用户选择“只输出提示词”“我去别处生成”“节省 token”或类似表达，不调用图片生成工具，只输出图片提示词清单和目标文件路径。
   • 不要用 HTML、SVG、Canvas、Playwright 截图或脚本生成博客插图，除非用户明确要求“确定性绘图”或“脚本画图”。

5. 直接生成模式。

   • 每张图单独写一个聚焦的提示词，不要一次让模型生成多张互不相关的图。
   • 最终选中的图片要按提示词顺序复制到文章目录，固定放在 artifacts/<article-slug>/generated/，文件名固定为 1.png、2.png、3.png，不要改成 00_cover_<slug>.png 或 01_<topic>.png 这类语义文件名。
   • 必须检查图片质量。如果图片太抽象、没有标签、文字不可读、教学作用不足，就用更严格的提示词重新直出生图。不要再用脚本补图，除非用户明确要求。

6. 只输出提示词模式。

   • 不调用 imagegen，也不消耗图片生成 token。
   • 生成一个提示词清单文件，例如 artifacts/<article-slug>/image_prompts.md。
   • 提示词清单中的图片顺序是后续命名的唯一依据：第 1 张写 1.png，第 2 张写 2.png，依次递增；每张图都要写清楚图片用途、建议文件名、目标保存路径、Markdown 相对引用路径、alt 文案、尺寸比例、完整提示词。
   • 明确告诉用户：外部生成后按提示词顺序把图片放到 artifacts/<article-slug>/generated/1.png、artifacts/<article-slug>/generated/2.png、artifacts/<article-slug>/generated/3.png，再回来让我继续校验和补齐 Markdown。
   • 可以先写文章正文草稿并引用这些计划路径，但要标记图片校验状态为“待用户放图后校验”。没有真实图片文件前，不要声称图文版已最终完成，也不要进入 CSDN 发布阶段。

7. 编写 Markdown。

   • 文章保存到稳定路径，例如 artifacts/<article-slug>/<article-title>.md。
   • H1 后面马上放封面图，封面图引用固定使用 generated/1.png。
   • 封面图后、开场前加入摘要，格式为 > 摘要：<80 字以内的一句话>；摘要要概括文章核心内容，并有足够吸引力让读者继续读。
   • 正文图片按出现顺序继续引用 generated/2.png、generated/3.png，保持与提示词清单顺序完全一致。
   • 图片引用使用从 Markdown 文件出发的相对路径，默认只使用同目录下的 generated/<n>.png 连续数字文件名，不使用语义文件名，除非用户明确要求另一种命名。
   • 接手旧文章时，如果发现 Markdown 在 artifacts/<slug>/ 但图片在 output/<slug>/generated/，继续编辑前应把图片迁入 artifacts/<slug>/generated/ 并更新 Markdown 与 image_prompts.md 里的相对路径，避免新旧目录策略混用。
   • 在询问是否上传 CSDN 前，先验证所有本地图片引用都存在。

8. 本地交付完成后再询问是否上传 CSDN。

   • 直接问：Markdown 和图片已准备好，要上传到 CSDN 吗？
   • 用户确认前，不要打开 CSDN，不要上传图片，不要发布。
   • 如果用户拒绝或没有回答，就只交付本地 Markdown 和图片路径。

写作风格

默认使用中文。语气要像有经验的工程师在给学习者讲清楚问题：直接、实用、有教学感，但不要闲聊。

推荐写法：

• 开头先讲痛点：普通日志、笔记或直觉回答不了什么问题。
• 用短段落和具体问题引出动机。
• 解释术语时讲它在系统里的角色，而不是堆定义。
• 多建立心智模型：数据流、控制面/数据面、生命周期、时序、边界。
• 多用对比句：它不是 A，而是 B，先别急着背命令，先看数据怎么流动。
• 保留命令、代码、表格和“什么时候用什么”的选择建议。
• 结尾给出读者能直接迁移到开发/调试里的总结。

避免写法：

• 逐段复制原始资料。
• 学术腔、营销腔、空泛总结。
• 大段连续文字，没有代码、表格、图片或决策建议。
• 在公开博客里保留内部链接和内部细节。
• 把图片当装饰图，每张图片都要有学习价值。

推荐文章结构

默认使用下面结构，再按具体主题微调：

# <具体、有搜索价值的标题>

![<封面 alt>](<relative-cover-path>)

> 摘要：<80 字以内，概括文章内容，并吸引读者继续阅读。>

<开场：用 3 到 6 个问题说明为什么需要这篇文章。>

<主线概览：说明本文按哪些层次/步骤展开。>

## 1. <第一个核心概念：先建立心智模型>

![<正文图 alt>](<relative-image-path>)

<解释概念、关键对象、最小命令/代码、常见误解。>

## 2. <第二个核心概念：把动作放到流程里>

...

## 实战选择：遇到问题时怎么选

| 问题 | 推荐路径 |
| --- | --- |

## 常见坑

### <坑点>

## 总结

<用一段数据流、控制流或排障流总结。>

## 参考

- <公开资料链接>

如果是课程章节总结，可以使用这些栏目：章节定位、学习主线建议、核心概念、源码与实验地图、初学者最容易卡住的地方、学完后的迁移方向、资料边界说明。

插图提示词方法

插图要“直出生图”，并且要能教学。提示词要告诉模型：这张图用在哪里、要讲什么概念、必须出现哪些标签、图的结构是什么、不要出现什么问题。

调用图片生成工具时，可以把下面中文模板翻译成英文或中英混写；但图上需要出现的中文标题、中文标签必须保持原文。

图片提示词质量约束

写提示词前先做“文字预算”和“题材适配”，不要把正文表格、长公式、长句子或整套方法论塞进一张图里。图片负责展示对象和关系，细节解释放回 Markdown。

• 文字预算：封面图最多 1 个主标题 + 2 到 4 个短关键词；正文图最多 1 个标题 + 4 到 6 个短标签。单个中文标签优先控制在 8 个字以内，英文/代码标签优先控制在 16 个字符以内。
• 长公式处理：超过一行的公式、超过 20 个汉字的结论、完整 checklist、完整话术、长表格内容都不要要求图片原样呈现。改成 2 到 4 个短节点，完整文字写在正文里。
• “必须出现”克制使用：只把真的需要在图中可见的短标题和短标签写成“必须出现”。如果一个提示词里“必须出现”的文字超过 8 项，必须先删减、合并或拆成多张图。
• 题材适配：技术文章可用终端、代码块、内核层级、工具链等元素；职场、管理、面试、沟通类文章应使用业务决策面板、流程、矩阵、时间线、人物剪影等元素，不要套用“技术海报、终端窗口、代码块”等不匹配元素。
• 风格去同质化：同一篇文章内部可以保持统一视觉语言，但不要在多篇文章之间无脑复用“深色蓝紫商务科技面板”。每篇文章至少明确一个与主题相关的视觉隐喻和 1 到 2 个差异化强调色。
• 可生成性优先：如果要求中文文字绝对准确可读，就减少文字数量、放大标签、保留留白；不要用密集小字、复杂三维图、过多发光边框或多层嵌套卡片牺牲可读性。

如果用户选择“只输出提示词模式”，按下面格式输出并保存到 artifacts/<article-slug>/image_prompts.md：

# <文章标题> 配图提示词

生成说明：请按下面提示词顺序在外部图片工具中生成 16:9 图片。文件名必须按图片顺序命名为 1.png、2.png、3.png……生成后把文件放到“目标保存路径”。放好后回来告诉我，我会校验图片路径并把 Markdown 调整成最终图文版。

## 1. 封面图

- 用途：封面
- 建议文件名：1.png
- 目标保存路径：artifacts/<article-slug>/generated/1.png
- Markdown 引用路径：generated/1.png
- alt 文案：<文章标题> 封面
- 尺寸比例：16:9
- 提示词：

```text
<完整提示词>
```

## 2. <正文图标题>

- 用途：正文教学图，放在 `<章节标题>` 小节下
- 建议文件名：2.png
- 目标保存路径：artifacts/<article-slug>/generated/2.png
- Markdown 引用路径：generated/2.png
- alt 文案：<正文图 alt>
- 尺寸比例：16:9
- 提示词：

```text
<完整提示词>
```

封面图提示词模板

用途：技术博客封面图，16:9，高分辨率。
主题：为中文技术博客《<文章标题>》生成一张有吸引力的封面。
读者：<嵌入式/Linux/Android/驱动/性能分析等目标读者>。
画面构图：要有强视觉主体、明确技术氛围、清晰标题区域、有空间层次和动势，不要像普通流程图。
必须出现的文字："<短标题>"，以及 2 到 4 个关键词："<关键词1>"、"<关键词2>"、"<关键词3>"。
视觉元素：<芯片/开发板/终端窗口/时间线/kernel 层次/工具链/数据流等>。
风格：深色技术海报，高对比，线条清晰，真实或半真实技术组件，不要卡通。
限制：不要虚假 logo，不要水印，不要随机乱码段落，文字尽量少但要清晰可读；不得加入超过上述文字预算的长句或密集小字。

封面可以比正文图更有吸引力，但标题和主题必须准确。如果文字乱码、太素、和主题不匹配，就重新生成。

正文教学图提示词模板

用途：中文技术博客正文教学图，16:9。
主题：给学习者解释 <概念/流程/工具链>。
必须出现的标题文字："<简短中文标题>"。
必须出现的标签："<标签1>"、"<标签2>"、"<标签3>"、"<标签4>"。（最多 6 个短标签）
可选技术片段："<命令/路径/代码关键字1>"、"<命令/路径/代码关键字2>"。（只保留最关键的 1 到 2 个短片段）
图的结构：<从左到右的数据流 / 分层架构 / 时间线 / 决策树 / 工具链管线>。
教学目标：读者看完这张图应该明白 <一句话说明学习目标>。
视觉风格：深色技术教学面板，编号分区，箭头，清晰框图，终端/代码块元素，轻微发光，高对比，中文标签清楚可读。
避免：抽象概念艺术、纯装饰构图、密密麻麻的小字、编造 API、水印、不可读伪文字。

图里放短标签，不要放长句子。详细解释写在 Markdown 里。图片负责展示对象和关系，文章负责讲推理。

具体示例：封面图

用途：技术博客封面图，16:9，高分辨率。
主题：为中文技术博客《Linux/Android 跟踪技术》生成一张有吸引力的封面。
读者：嵌入式 Linux 和 Android 性能调试学习者。
画面构图：Linux kernel 时间线流向 Android 设备和类似 Perfetto 的 trace viewer，背景有终端面板和发光 trace 线。
必须出现的文字："Linux/Android 跟踪技术"、"ftrace"、"TRACE_EVENT"、"Perfetto"。
风格：深色技术海报，高对比，标题区域清晰，有真实调试氛围。
限制：不要虚假 logo，不要水印，不要随机乱码段落，文字要短且清晰。

具体示例：正文教学图

用途：中文技术博客正文教学图，16:9。
主题：解释 ftrace 和 tracefs 如何把事件写入 per-CPU ring buffer，再通过 trace 或 trace_pipe 读取。
必须出现的标题文字："ftrace / tracefs 数据流"。
必须出现的标签："事件源"、"tracefs 开关"、"per-CPU ring buffer"、"trace 快照"、"trace_pipe 流式读取"。
必须出现的技术片段："/sys/kernel/tracing"、"events/sched/sched_switch/enable"、"tracing_on"。
图的结构：从左到右的数据流，带编号区域、箭头、终端命令块和小型 buffer 示意。
教学目标：读者能明白 tracefs 是控制面，ring buffer 是数据路径。
视觉风格：深色技术教学面板，框图和箭头清晰，中文标签可读，轻微发光，不要抽象。
避免：纯装饰图、过小密集文字、随机编造命令、水印、不可读伪文字。

适合做正文图的内容

• 架构图：模块、层次、边界、API 面。
• 数据流：来源 -> 缓冲区 -> 消费者 -> 可视化工具。
• 时间线：开始/结束标记、中断、任务调度、状态变化。
• 工具链：本地命令 -> 设备命令 -> 输出文件 -> 分析界面。
• 排障决策：现象 -> 观察点 -> 命令 -> 下一步判断。
• 代码生命周期：注册 -> enable -> 运行时回调 -> cleanup。

Markdown 质量检查

询问是否上传 CSDN 前，先检查：

• Markdown 文件存在，并且是 UTF-8。
• Markdown、image_prompts.md、generated/ 图片目录和 csdn/ 发布记录都属于同一个 artifacts/<article-slug>/ 文章目录；不要把正文和图片拆到两套目录。
• H1 具体，包含重要搜索关键词。
• 封面图后有 > 摘要：...，摘要不超过 80 字，能概括文章内容且有吸引力。
• 第一张图片是封面图，引用路径必须指向 generated/1.png。
• 所有图片引用按 Markdown 出现顺序使用连续数字文件名：1.png、2.png、3.png，不能缺号、跳号，也不要混用语义文件名。
• 所有图片引用都能在本地解析到文件。
• image_prompts.md 中每张图都通过文字预算检查：封面不超过 1 个标题 + 4 个关键词，正文图不超过 1 个标题 + 6 个短标签；没有长公式、长句子、完整表格或完整话术被要求原样进图。
• 图片提示词的题材、视觉元素和配色与文章主题匹配；不能把技术博客模板直接套到职场/管理/面试文章，也不能多篇文章无差异复用同一套深色蓝紫科技面板。
• 代码块闭合，并使用有用的语言标记，例如 shell、c、cpp、text、protobuf、python、js。
• 没有 TODO、待补充 这类未完成占位。
• 没有内部链接，除非用户明确要求保留。
• 如果主题涉及工具或方案选择，要有“实战选择/怎么选”一类章节。
• 结尾要给出可复用心智模型，不要只写“本文介绍了”。

可选：上传 CSDN

只有用户确认后才进入这个阶段。

1. 优先复用工作区里上次成功的 CSDN 发布方式。

   • 搜索 output/playwright/ 等目录下的旧脚本。
   • 优先沿用用户之前验证过的方式，不要随便切换自动化通道。
   • 默认优先用 Playwright MCP 发布。Playwright MCP 应配置为 headed 模式，方便用户扫码或输入验证码；如果仍然看不到页面，就截图给用户扫码，或改用可见的 headed Playwright CLI 浏览器。
   • 如果上次成功方式是 headed Playwright CLI 浏览器登录，就继续用它，除非用户要求换方式。

2. 发布前校验本地图文。

   • 确认 Markdown 中所有本地图片文件都存在；只统计真正的图片文件，忽略 macOS 生成的 ._* 元数据文件。
   • 确认本地图片按 Markdown 出现顺序连续命名为 1.png、2.png、3.png；如果存在 10.png 这类双位数文件，按数字大小排序，不按字符串排序。
   • 用 file 或等价方式确认图片格式和分辨率合理。
   • 检查代码块闭合、没有 TODO/待补充/内部链接/内部项目名。
   • 如果用户原本选择“只输出提示词”，必须等用户放入图片后再进入 CSDN 发布；没有图片时不要上传 CSDN。

3. 先上传图片到 CSDN 图床。

   • 打开 https://editor.csdn.net/md/?not_checkout=1。
   • 如果跳到登录页，让用户完成登录。Playwright MCP 若不可见，可以先截登录页二维码给用户扫码；不要代替用户输入账号密码。
   • 登录后等待编辑器页面可用，并确认页面存在 window.csdn.upload.uploadImg 和 #import-markdown-file-input。
   • 对每张图片创建临时 <input type="file">，用 Playwright 的 file upload 能力选择本地图片，再在页面上下文调用：

await window.csdn.upload.uploadImg({
  appName: "direct_blog_markdown",
  file,
  imageTemplate: "",
});

• 按数字顺序上传 1.png、2.png、3.png，并记录每张本地图片文件名和返回的 https://i-blog.csdnimg.cn/... URL。
• 不要把 CSDN 图床 URL 写回原始本地 Markdown。

4. 生成 CSDN 发布版 Markdown。

   • 按数字文件名映射把本地图片路径替换成 CSDN 返回的图片 URL，例如只把 generated/1.png 替换为 1.png 对应的图床 URL。
   • 另存一份发布版 Markdown，例如 artifacts/<slug>/csdn/<title>_csdn.md。
   • 保留原始本地 Markdown，不要把本地相对路径版本覆盖掉。
   • 去掉“图片待用户放回后校验”这类只适用于本地草稿的提示。
   • 再次检查发布版 Markdown：图片 URL 数量应等于文章图片数量，且都指向 CSDN 图床；代码块闭合；没有本地图片引用，尤其不能残留旧策略下的 output/<slug>/generated/ 引用。

5. 导入并安全发布。

   • 使用编辑器里的 #import-markdown-file-input 导入 CSDN 发布版 Markdown，而不是把长文手动粘贴进编辑器。
   • 填写文章标题。
   • 点击“发布文章”后，在发布弹窗中检查自动生成的标签、封面、摘要、文章类型和可见范围。除非用户有明确要求，保持 CSDN 默认选项，不随意改分类、活动或同步设置。
   • 点击弹窗里的最终“发布文章”。
   • 等待进入 /creation/success/ 页面；如果第一次点击后弹窗仍在，可以再点一次最终发布按钮。
   • 发布完成后获取“查看文章”链接。

6. 保存发布记录。

   • 在 artifacts/<slug>/csdn/csdn_publish_record.md 记录标题、文章 ID、发布状态、查看文章链接、发布版 Markdown 路径、每张数字编号图片的 CSDN 图床 URL。
   • 如果页面提示“发布成功，正在审核中”，最终状态写为“已发布，CSDN 审核中”。

如果发布因为登录态、编辑器行为或自动化通道失败而中断，要保留本地 Markdown 和 CSDN 发布版 Markdown，并清楚说明卡在哪里。

最终回复格式

完成后报告：

• 本地 Markdown 路径。
• 图片目录和图片数量。
• 如果选择只输出提示词，报告 image_prompts.md 路径、每张图应该按 1.png、2.png、3.png 放到哪里、当前图片校验是否待完成。
• CSDN 状态：未上传、待用户确认、已发布或被阻塞。
• 做过哪些校验。