初版设计：一个博客上传 Skill 应该怎么拆

上一篇写到，博客自动上传脚本的起点很小：少复制粘贴几次，把 Markdown 稳定放进平台草稿箱。

真正开始设计时，问题很快变成另一种形状。一个发布类 Skill 要先回答几个更基础的问题：什么时候该触发，拿到什么输入，先检查什么，平台差异放在哪里，哪些动作交给脚本，哪些动作留给人确认。

我一开始给它起了一个工程名：blog-publisher。这个名字先服务工程表达：它处理的是博客发布流程，范围比单个平台的一次粘贴动作更大。

最初以为只是写一个上传脚本

最直觉的设计是写一个浏览器脚本。

流程大概长这样：

读取 Markdown
-> 打开知乎写作页
-> 填标题
-> 填正文
-> 保存草稿

这条线确实能解决一部分重复劳动。可只要往下想一步，就会发现脚本需要面对的输入并不稳定。

一篇 Markdown 可能缺标题，可能有本地图片，可能有未闭合代码块，可能没有标签。平台编辑器也会变化，知乎、CSDN、博客园各自有不同入口、格式和发布按钮。更麻烦的是，保存草稿和正式发布属于不同风险级别，脚本需要把这两个动作分开对待。

所以初版设计里，我先把目标收窄成一句话：

先做一个能检查、生成发布材料、保留确认点的博客上传 Skill。

这句话看起来保守，但它给后面的实现留了余地。检查和生成可以先稳定下来，浏览器上传可以后接，多平台也可以逐步加。

拆成 Skill 后，问题变成了模块分工

把它当成 Skill 设计后，目录需要承载流程、规则、脚本和模板。一个发布类 Skill 至少需要四类东西：

模块	作用	放什么
SKILL.md	入口和主流程	触发场景、输入要求、流程顺序、边界规则
references/	平台差异	平台映射、知乎规则、后续 CSDN 和博客园规则
scripts/	确定性动作	Markdown 检查、草稿生成、正文导出、预检
assets/	稳定模板	草稿模板、检查清单模板、结果记录模板

这四类文件对应四种变化速度。

SKILL.md 最稳定。它像入口说明，负责告诉执行者“这件事应该怎么走”。平台页面变化、字段限制变化、脚本参数变化，更适合拆到独立规则或脚本里维护。

references/ 最容易跟着平台变化。比如知乎的编辑器、CSDN 的发布设置、博客园的分类和标签，这些都属于平台规则。它们应该能单独更新。

scripts/ 负责那些重复、确定、容易出错的动作。比如检查图片路径、识别标题、生成草稿文件。这些动作让脚本做更稳，人手工做反而容易漏。

assets/ 放模板。模板的价值是减少输出漂移，让每次生成出来的检查清单和草稿结构尽量一致。

SKILL.md 只做入口和流程

初版最容易失控的地方，是想把所有说明都写进 SKILL.md。

我后来给它定的职责很窄：

• 什么时候触发这个 Skill。
• 输入需要哪些信息。
• 先做哪些检查。
• 目标平台对应哪些规则。
• 哪些步骤调用脚本。
• 哪些情况要停下来。
• 最后给用户什么结果。

它更像流程卡片，保持短、清楚、可执行。

比如一个用户说“帮我把这篇 Markdown 发到知乎”，SKILL.md 需要先把任务识别成博客发布，再要求源文件和目标平台，然后按顺序进入检查、生成、预检和浏览器流程。

这里最关键的是 description。它决定 Skill 会在什么场景下被叫醒。

description 既要覆盖“发布、上传、同步、适配 Markdown 博客到内容平台”这类请求，也要划清边界：写文章、改观点、选题策划、SEO 构思这些任务，应该交给别的写作流程。

这个边界越清楚，后面误触发越少。

references/ 放平台变化

发布平台的规则会变，所以我把平台相关内容放进 references/。

初版先准备一个平台映射文件，再给具体平台单独写规则。这样后续加 CSDN、博客园时，可以优先补平台规则和脚本衔接，主入口保持稳定。

平台映射大概解决三个问题：

问题	说明
用户叫法	用户可能说“知乎”，也可能说 zhihu
内容规则	标题、标签、图片、代码块这些内容要怎么准备
发布规则	浏览器入口、登录态、草稿保存、发布确认怎么处理

这一层还有一个价值：清楚写出哪些平台已经支持，哪些平台还在规划中。

比如第一阶段可以把知乎作为优先验证对象。CSDN 和博客园先放在扩展计划里，等规则、脚本和测试都补齐后再进入已支持列表。

这样做能避免一个常见问题：Skill 描述写得很大，实际支持范围很小，用户一调用就踩空。

scripts/ 放确定性动作

脚本适合做重复、明确、可验证的事情。

第一版里，我希望脚本先处理这些低风险动作：

• 读取 Markdown 标题和基础信息。
• 检查图片路径。
• 检查代码块闭合和语言标注。
• 检查摘要、标签这类发布前信息。
• 生成草稿文件。
• 生成发布前检查清单。

这些动作的共同点是：输入明确，输出可检查，失败原因容易说明。

相比之下，登录、验证码、风控、最终发布按钮这些动作风险更高。它们可以在流程里被识别、被提示、被记录，但最终发布要保留确认点。

这也是发布类 Skill 和普通转换脚本最大的差别。转换脚本只要把 A 变成 B，发布类 Skill 还要考虑“什么时候停下来”。

assets/ 放稳定模板

模板看起来不起眼，但它能减少很多后续混乱。

如果每次检查清单格式都不一样，后续批量上传、失败记录、人工复核都会变麻烦。把草稿模板、检查清单模板、结果模板放进 assets/，可以让输出更稳定。

初版里模板至少要承担三件事：

1. 草稿结构稳定：标题、正文、标签建议、发布备注各放各的位置。
2. 检查结果稳定：blocking 和 warning 分开，让人一眼判断是否进入下一步。
3. 结果记录稳定：成功、失败、截图、下一步修正点有固定位置。

这些模板不需要复杂。只要它们能让每次输出保持一致，后面的调试就会轻很多。

第一版边界：先检查和生成，再谈发布

最后，初版设计里最重要的是边界。

第一版要先把这条链路走稳：

用户给出 Markdown 和目标平台
-> Skill 判断任务是否适用
-> 读取平台规则
-> 运行 Markdown 检查
-> 生成草稿和检查清单
-> 汇报风险项
-> 需要浏览器动作时进入预检
-> 最终发布保留人工确认

这里有几个判断会贯穿整个系列：

• 源 Markdown 由用户提供，脚本只读取和生成发布材料。
• 平台规则先从一个平台做起，支持范围逐步扩大。
• 检查发现阻断问题时，流程停在检查结果上。
• 登录、安全验证和最终发布保留人工介入。
• 每次失败都要留下能定位问题的阶段名和现象。

这样设计之后，blog-publisher 就有了一套可以扩展的发布流程：入口负责判断，规则负责平台差异，脚本负责确定动作，模板负责稳定输出，人工确认负责最后的安全边界。

本篇小结

这一篇的设计结论可以收成三点：

• SKILL.md 只做入口和流程，不把平台细节全塞进去。
• references/、scripts/、assets/ 分别承接平台规则、确定性动作和稳定模板。
• 第一版先检查和生成发布材料，再把浏览器上传放到后面处理。

下一篇开始进入第一版实现：先把 Markdown 检查、草稿生成和知乎单篇上传这条最小链路跑通。