# Blog Md Writer > 从输入资料编写中文技术博客 Markdown，并规划有教学作用的插图。用户给出飞书文档、Markdown、笔记、代码、日志、课程资料、会议材料，或说“写博客”“写 md 博客”“整理成 CSDN 文章”“配图文并茂的博客”“输出博客配图提示词”时使用本 skill。必须先产出本地 blog md 文件和图片方案；生图前要询问用户是直接生成图片，还是只输出提示词让用户去外部生成以节省 token。图片文件和 Markdown 引用默认按提示词顺序命名为 `1.png`、`2.png`、`3.png`。CSDN 上传/发布只是可选二阶段，只有在 Markdown 和图片完成后询问用户并得到确认才执行。 - Skill: `josephcooperhc/blog-md-writer` (Agent Skill) - Install (CLI): `npx skillmds@latest add josephcooperhc/blog-md-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/josephcooperhc/blog-md-writer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: JosephCooperHC (https://skillmd.com/u/josephcooperhc) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/josephcooperhc/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//`。Markdown、`image_prompts.md`、图片子目录和 CSDN 发布记录都放在这个目录内，不再把同一篇文章拆到 `artifacts/` 和 `output/` 两套目录。 4. 生图前必须询问用户选择哪种模式。 - 询问示例：`我已经规划好插图。你要我直接生成图片，还是只输出每张图的提示词和目标路径，你去外部生成后放回来？` - 如果用户选择“直接生成”，使用 `imagegen` skill，默认走内置图片生成能力。 - 如果用户选择“只输出提示词”“我去别处生成”“节省 token”或类似表达，不调用图片生成工具，只输出图片提示词清单和目标文件路径。 - 不要用 HTML、SVG、Canvas、Playwright 截图或脚本生成博客插图，除非用户明确要求“确定性绘图”或“脚本画图”。 5. 直接生成模式。 - 每张图单独写一个聚焦的提示词，不要一次让模型生成多张互不相关的图。 - 最终选中的图片要按提示词顺序复制到文章目录，固定放在 `artifacts//generated/`，文件名固定为 `1.png`、`2.png`、`3.png`，不要改成 `00_cover_.png` 或 `01_.png` 这类语义文件名。 - 必须检查图片质量。如果图片太抽象、没有标签、文字不可读、教学作用不足，就用更严格的提示词重新直出生图。不要再用脚本补图，除非用户明确要求。 6. 只输出提示词模式。 - 不调用 `imagegen`，也不消耗图片生成 token。 - 生成一个提示词清单文件，例如 `artifacts//image_prompts.md`。 - 提示词清单中的图片顺序是后续命名的唯一依据：第 1 张写 `1.png`，第 2 张写 `2.png`，依次递增；每张图都要写清楚图片用途、建议文件名、目标保存路径、Markdown 相对引用路径、alt 文案、尺寸比例、完整提示词。 - 明确告诉用户：外部生成后按提示词顺序把图片放到 `artifacts//generated/1.png`、`artifacts//generated/2.png`、`artifacts//generated/3.png`，再回来让我继续校验和补齐 Markdown。 - 可以先写文章正文草稿并引用这些计划路径，但要标记图片校验状态为“待用户放图后校验”。没有真实图片文件前，不要声称图文版已最终完成，也不要进入 CSDN 发布阶段。 7. 编写 Markdown。 - 文章保存到稳定路径，例如 `artifacts//.md`。 - H1 后面马上放封面图，封面图引用固定使用 `generated/1.png`。 - 封面图后、开场前加入摘要，格式为 `> 摘要：<80 字以内的一句话>`；摘要要概括文章核心内容，并有足够吸引力让读者继续读。 - 正文图片按出现顺序继续引用 `generated/2.png`、`generated/3.png`，保持与提示词清单顺序完全一致。 - 图片引用使用从 Markdown 文件出发的相对路径，默认只使用同目录下的 `generated/.png` 连续数字文件名，不使用语义文件名，除非用户明确要求另一种命名。 - 接手旧文章时，如果发现 Markdown 在 `artifacts//` 但图片在 `output//generated/`，继续编辑前应把图片迁入 `artifacts//generated/` 并更新 Markdown 与 `image_prompts.md` 里的相对路径，避免新旧目录策略混用。 - 在询问是否上传 CSDN 前，先验证所有本地图片引用都存在。 8. 本地交付完成后再询问是否上传 CSDN。 - 直接问：`Markdown 和图片已准备好，要上传到 CSDN 吗？` - 用户确认前，不要打开 CSDN，不要上传图片，不要发布。 - 如果用户拒绝或没有回答，就只交付本地 Markdown 和图片路径。 ## 写作风格 默认使用中文。语气要像有经验的工程师在给学习者讲清楚问题：直接、实用、有教学感，但不要闲聊。 推荐写法： - 开头先讲痛点：普通日志、笔记或直觉回答不了什么问题。 - 用短段落和具体问题引出动机。 - 解释术语时讲它在系统里的角色，而不是堆定义。 - 多建立心智模型：数据流、控制面/数据面、生命周期、时序、边界。 - 多用对比句：`它不是 A，而是 B`，`先别急着背命令，先看数据怎么流动`。 - 保留命令、代码、表格和“什么时候用什么”的选择建议。 - 结尾给出读者能直接迁移到开发/调试里的总结。 避免写法： - 逐段复制原始资料。 - 学术腔、营销腔、空泛总结。 - 大段连续文字，没有代码、表格、图片或决策建议。 - 在公开博客里保留内部链接和内部细节。 - 把图片当装饰图，每张图片都要有学习价值。 ## 推荐文章结构 默认使用下面结构，再按具体主题微调： ```markdown # <具体、有搜索价值的标题> ![<封面 alt>]() > 摘要：<80 字以内，概括文章内容，并吸引读者继续阅读。> <开场：用 3 到 6 个问题说明为什么需要这篇文章。> <主线概览：说明本文按哪些层次/步骤展开。> ## 1. <第一个核心概念：先建立心智模型> ![<正文图 alt>]() <解释概念、关键对象、最小命令/代码、常见误解。> ## 2. <第二个核心概念：把动作放到流程里> ... ## 实战选择：遇到问题时怎么选 | 问题 | 推荐路径 | | --- | --- | ## 常见坑 ### <坑点> ## 总结 <用一段数据流、控制流或排障流总结。> ## 参考 - <公开资料链接> ``` 如果是课程章节总结，可以使用这些栏目：`章节定位`、`学习主线建议`、`核心概念`、`源码与实验地图`、`初学者最容易卡住的地方`、`学完后的迁移方向`、`资料边界说明`。 ## 插图提示词方法 插图要“直出生图”，并且要能教学。提示词要告诉模型：这张图用在哪里、要讲什么概念、必须出现哪些标签、图的结构是什么、不要出现什么问题。 调用图片生成工具时，可以把下面中文模板翻译成英文或中英混写；但图上需要出现的中文标题、中文标签必须保持原文。 ### 图片提示词质量约束 写提示词前先做“文字预算”和“题材适配”，不要把正文表格、长公式、长句子或整套方法论塞进一张图里。图片负责展示对象和关系，细节解释放回 Markdown。 - **文字预算**：封面图最多 1 个主标题 + 2 到 4 个短关键词；正文图最多 1 个标题 + 4 到 6 个短标签。单个中文标签优先控制在 8 个字以内，英文/代码标签优先控制在 16 个字符以内。 - **长公式处理**：超过一行的公式、超过 20 个汉字的结论、完整 checklist、完整话术、长表格内容都不要要求图片原样呈现。改成 2 到 4 个短节点，完整文字写在正文里。 - **“必须出现”克制使用**：只把真的需要在图中可见的短标题和短标签写成“必须出现”。如果一个提示词里“必须出现”的文字超过 8 项，必须先删减、合并或拆成多张图。 - **题材适配**：技术文章可用终端、代码块、内核层级、工具链等元素；职场、管理、面试、沟通类文章应使用业务决策面板、流程、矩阵、时间线、人物剪影等元素，不要套用“技术海报、终端窗口、代码块”等不匹配元素。 - **风格去同质化**：同一篇文章内部可以保持统一视觉语言，但不要在多篇文章之间无脑复用“深色蓝紫商务科技面板”。每篇文章至少明确一个与主题相关的视觉隐喻和 1 到 2 个差异化强调色。 - **可生成性优先**：如果要求中文文字绝对准确可读，就减少文字数量、放大标签、保留留白；不要用密集小字、复杂三维图、过多发光边框或多层嵌套卡片牺牲可读性。 如果用户选择“只输出提示词模式”，按下面格式输出并保存到 `artifacts//image_prompts.md`： ````markdown # <文章标题> 配图提示词 生成说明：请按下面提示词顺序在外部图片工具中生成 16:9 图片。文件名必须按图片顺序命名为 1.png、2.png、3.png……生成后把文件放到“目标保存路径”。放好后回来告诉我，我会校验图片路径并把 Markdown 调整成最终图文版。 ## 1. 封面图 - 用途：封面 - 建议文件名：1.png - 目标保存路径：artifacts//generated/1.png - Markdown 引用路径：generated/1.png - alt 文案：<文章标题> 封面 - 尺寸比例：16:9 - 提示词： ```text <完整提示词> ``` ## 2. <正文图标题> - 用途：正文教学图，放在 `<章节标题>` 小节下 - 建议文件名：2.png - 目标保存路径：artifacts//generated/2.png - Markdown 引用路径：generated/2.png - alt 文案：<正文图 alt> - 尺寸比例：16:9 - 提示词： ```text <完整提示词> ``` ```` ### 封面图提示词模板 ```text 用途：技术博客封面图，16:9，高分辨率。 主题：为中文技术博客《<文章标题>》生成一张有吸引力的封面。 读者：<嵌入式/Linux/Android/驱动/性能分析等目标读者>。 画面构图：要有强视觉主体、明确技术氛围、清晰标题区域、有空间层次和动势，不要像普通流程图。 必须出现的文字："<短标题>"，以及 2 到 4 个关键词："<关键词1>"、"<关键词2>"、"<关键词3>"。 视觉元素：<芯片/开发板/终端窗口/时间线/kernel 层次/工具链/数据流等>。 风格：深色技术海报，高对比，线条清晰，真实或半真实技术组件，不要卡通。 限制：不要虚假 logo，不要水印，不要随机乱码段落，文字尽量少但要清晰可读；不得加入超过上述文字预算的长句或密集小字。 ``` 封面可以比正文图更有吸引力，但标题和主题必须准确。如果文字乱码、太素、和主题不匹配，就重新生成。 ### 正文教学图提示词模板 ```text 用途：中文技术博客正文教学图，16:9。 主题：给学习者解释 <概念/流程/工具链>。 必须出现的标题文字："<简短中文标题>"。 必须出现的标签："<标签1>"、"<标签2>"、"<标签3>"、"<标签4>"。（最多 6 个短标签） 可选技术片段："<命令/路径/代码关键字1>"、"<命令/路径/代码关键字2>"。（只保留最关键的 1 到 2 个短片段） 图的结构：<从左到右的数据流 / 分层架构 / 时间线 / 决策树 / 工具链管线>。 教学目标：读者看完这张图应该明白 <一句话说明学习目标>。 视觉风格：深色技术教学面板，编号分区，箭头，清晰框图，终端/代码块元素，轻微发光，高对比，中文标签清楚可读。 避免：抽象概念艺术、纯装饰构图、密密麻麻的小字、编造 API、水印、不可读伪文字。 ``` 图里放短标签，不要放长句子。详细解释写在 Markdown 里。图片负责展示对象和关系，文章负责讲推理。 ### 具体示例：封面图 ```text 用途：技术博客封面图，16:9，高分辨率。 主题：为中文技术博客《Linux/Android 跟踪技术》生成一张有吸引力的封面。 读者：嵌入式 Linux 和 Android 性能调试学习者。 画面构图：Linux kernel 时间线流向 Android 设备和类似 Perfetto 的 trace viewer，背景有终端面板和发光 trace 线。 必须出现的文字："Linux/Android 跟踪技术"、"ftrace"、"TRACE_EVENT"、"Perfetto"。 风格：深色技术海报，高对比，标题区域清晰，有真实调试氛围。 限制：不要虚假 logo，不要水印，不要随机乱码段落，文字要短且清晰。 ``` ### 具体示例：正文教学图 ```text 用途：中文技术博客正文教学图，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//` 文章目录；不要把正文和图片拆到两套目录。 - 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`。 - 对每张图片创建临时 ``，用 Playwright 的 file upload 能力选择本地图片，再在页面上下文调用： ```js 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//csdn/_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 状态：未上传、待用户确认、已发布或被阻塞。 - 做过哪些校验。