需要把 Markdown 文章发布到 X Articles…

将 Markdown 文件或 URL 发布到 X (Twitter) Articles 编辑器，处理 X Premium 格式限制、上传封面图、转换不支持元素并保存草稿。

适用场景

解决思路

1. 开始处理文章前，若不知道用户 X 订阅类型，先询问：X Premium（基础版，$8/月）还是 X Premium+（高级版，$16/月）；中文提示可用「1. X Premium - 基础版 ($8/月) 2. X Premium+ - 高级版 ($16/月) 您使用的是哪个版本？(Premium / Premium+)」。
2. 用户回答后，在本次会话中记住其订阅类型，除非用户明确要求更改，否则不要再次询问。
3. 根据订阅类型决定预处理：X Premium 基础版需要将 H3+ 标题转为 H2 或加粗、表格转 PNG、mermaid 转 PNG；X Premium+ 可保留 H3+ 标题、保留表格原生渲染，但 mermaid 仍需转 PNG。
4. 发布前扫描 Markdown 文件，查找不支持元素：H3+ 标题（###、#### 等）、Markdown 表格（由 | 字符构成表格结构的行）、mermaid 代码块（```mermaid）。
5. 提取表格到临时文件可使用 cat > /tmp/table.md << 'TABLE_EOF' 后粘贴表格内容再以 TABLE_EOF 结束；提取 mermaid 到临时文件可使用 cat > /tmp/diagram.mmd << 'MERMAID_EOF' 后粘贴 mermaid 内容再以 MERMAID_EOF 结束。
6. 将 Markdown 表格转为 PNG：先把表格提取到临时文件（例如 /tmp/table.md），运行 node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table-001.png，然后在 Markdown 中用图片引用替换表格，例如 。
7. 将 Mermaid 图转为 PNG：先把 mermaid 块提取到临时文件（例如 /tmp/diagram.mmd），运行 node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram-001.png，然后在 Markdown 中用图片引用替换 mermaid 块，例如 。
8. diagram-to-image.mjs 可指定主题，例如 node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram.png --theme ocean。
9. 处理深层标题时，若 H3 标题引入某章节下的独立子主题，将其转为加粗文本作为段落开头，以保留视觉层级但不破坏 X 格式。
10. 处理深层标题时，若某个 H3 实际上是主要章节，可考虑提升为 H2，但仅当不会造成扁平、无意义的结构；文章仍应逻辑通顺。
11. 处理 H2→H3→H4 的深层层级时，要合理扁平化：保留 H2 为 H2，将 H3 转为加粗段落，将 H4 转为斜体或自然并入段落。
12. 处理标题时优先保留含义而非机械转换结构；例如 ### Why This Matters 可改成加粗引导句 **Why does this matter?** 后接内容。
13. 阅读内容本身；若 H3 标题只是 Example 或 Note，可能更适合改成引用块或行内强调，而不是独立加粗行。
14. 预处理工作流：先通读文章，理解主要章节及作者如何使用标题组织思路。
15. 预处理工作流：处理表格和 mermaid 图，将它们逐个转成 PNG，并记录应插入的位置。
16. 预处理工作流：按订阅层级适配标题；Premium+ 用户保持标题原样（支持 H3+），Premium 用户按上述指南重构 H3+ 标题并保留文章流程和意图。
17. 预处理工作流：创建修改后的 Markdown，保存到临时文件，准备解析。
18. 不要修改用户原始文件；若需适配，将适配版保存为副本（例如 /tmp/article_adapted.md 或与原文件同目录的 article_for_x.md）。
19. 告知用户做了哪些修改及两个文件的位置，例如：已将 2 个表格转为图片、为更好阅读将 3 个 H3 标题重构为加粗文本；原始文件保留在 /path/to/article.md，适配版在 /path/to/article_for_x.md。
20. 用适配副本继续发布，确保用户可 review 更改且原始作品保持不变。
21. 对 Premium 用户适配时自问：是否有表格？有则逐个转 PNG；是否有 mermaid 图？有则逐个转 PNG；是否有 H3+ 标题？有则按标题指南重构。
22. 对 Premium+ 用户适配时自问：是否有 mermaid 图？有则转 PNG（任何层级都不支持）；表格和 H3+ 标题可保持原样。
23. 转换元素为图片时使用命令：表格转 PNG 可运行 node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table-1.md -o /tmp/table-1.png；Mermaid 转 PNG 可运行 node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram-1.mmd -o /tmp/diagram-1.png；在 Markdown 中原位置替换为图片引用。
24. 脚本位于 ~/.claude/skills/publish-x-article/scripts/：parse_markdown.py、copy_to_clipboard.py；diagram-to-image.mjs 位于 ~/.claude/skills/diagram-to-image/scripts/。
25. 用 parse_markdown.py 解析修改后的 Markdown：python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /path/to/modified_article.md，获取 JSON 输出。
26. 解析 JSON 关键字段：title 标题；cover_image 封面图；content_images 数组含 path、block_index、after_text；dividers 数组含 block_index、after_text；html 富文本；total_blocks HTML 块元素总数。
27. 定位规则：block_index 表示图片或分割线应插入在该 0-indexed 块元素之后；total_blocks 是 HTML 中块元素总数；after_text 仅用于参考/调试，不用于定位；dividers 是分割线位置，Markdown 的 --- 必须通过 X 菜单插入，不能使用 HTML <hr>。
28. 保存 HTML 到临时文件：python parse_markdown.py modified_article.md --html-only > /tmp/article_html.html。
29. 主工作流采用策略「先文后图后分割线」：对含图片和分割线的文章，先粘贴所有文本内容，再按 block_index 在正确位置插入图片和分割线。
30. 主工作流步骤：1) 预处理，转换表格/mermaid 为图片，扁平化深层标题；2) 用 Python 脚本解析修改后的 Markdown，得到 title、images、dividers（均带 block_index）、HTML；3) 导航到 X Articles 编辑器；4) 上传封面图（第一张图）；5) 填写标题；6) 用 Python 复制 HTML 到剪贴板并用 Cmd+V 粘贴；7) 按 block_index 插入内容图片；8) 按 block_index 通过 Insert > Divider 菜单插入分割线；9) 保存为草稿，绝不自动发布。
31. 高效执行原则：避免不必要的 browser_snapshot；大多数浏览器操作（click、type、press_key 等）返回结果已包含页面状态，不要每次操作后单独调用 browser_snapshot，应直接从操作返回结果获取页面状态。
32. 高效执行原则：避免不必要的 browser_wait_for；只在等待图片上传完成（textGone="正在上传媒体"）或极少数页面初始加载时使用，不要用 browser_wait_for 等待按钮或输入框出现，因为它们在页面加载完成后立即可用。
33. 高效执行原则：并行执行独立操作，例如填写标题 browser_type 与复制 HTML 到剪贴板 Bash 可并行，解析 Markdown 生成 JSON 与生成 HTML 文件可并行；有依赖的操作不能并行，例如必须先点击 create 才能上传封面图，必须先粘贴内容才能插入图片。
34. 高效执行原则：连续执行浏览器操作；每个浏览器操作返回的页面状态包含所需元素引用，直接使用这些引用进行下一步，不要每步额外等待。
35. 高效执行原则：准备工作前置；在开始浏览器操作前完成扫描不支持元素、转换表格/Mermaid 为图片、解析 Markdown 获取 JSON、生成 HTML 到 /tmp/、记录 title、cover_image、content_images 等信息，使浏览器操作阶段可连续执行。
36. Step 0：先阅读文章，理解主题、结构和作者想传达的内容。
37. Step 1：用 parse_markdown.py 解析修改后的 Markdown；脚本用法为 python parse_markdown.py <markdown_file> [--output json|html] [--html-only]，返回 title、cover_image、content_images（含 block_index 用于定位）、html、total_blocks。
38. Step 2：打开 X Articles 编辑器，browser_navigate 到 https://x.com/compose/articles；页面加载后显示草稿列表而不是编辑器，需要用 browser_snapshot 检查页面状态，然后立即点击 create 按钮，不要等待「添加标题」等编辑器元素，它们只有点击 create 后才出现；点击后等待编辑器加载；如需登录，提示用户手动登录。
39. Step 3：上传封面图；点击「添加照片或视频」按钮，使用 browser_file_upload 上传封面图路径（来自 JSON 的 cover_image），验证图片已上传。
40. Step 4：填写标题；找到 placeholder 为「添加标题」的 textbox，用 browser_type 输入 title（来自 JSON）。
41. Step 5：粘贴文本内容；用 Python 复制 HTML 到系统剪贴板：python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py html --file /tmp/article_html.html；然后在浏览器中点击编辑器 textbox，执行 browser_press_key: Meta+v；这样可保留 H2、加粗、链接、列表等富文本格式。
42. Step 6：插入内容图片；对 content_images 中每张图片，先运行 python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py image /path/to/img.jpg --quality 85 复制图片到剪贴板；再按 block_index 点击对应块元素（block_index=5 表示点击第 6 个块元素，0-indexed）；然后 browser_press_key: Meta+v 粘贴图片；最后用 browser_wait_for textGone="正在上传媒体" time=2 等待上传完成。
43. Step 6 反向插入：每插入一张图片后，后续图片实际位置会偏移；建议按 block_index 从大到小插入图片。例如 3 张图片 block_index 为 5、12、27，则先插入 27，再插入 12，最后插入 5。
44. Step 6.5：插入分割线；Markdown 中的 --- 不能通过 HTML <hr> 标签粘贴，X Articles 会忽略它，必须通过 X Articles 的 Insert 菜单插入原生分割线。
45. Step 6.5 操作：对 dividers 中每个分割线，按 block_index 从大到小：点击 block_index 位置的块元素；点击 Insert 按钮（Add Media button）；点击 Divider menuitem；分割线会插入到光标位置。
46. Step 6.5 与图片插入顺序：建议先插入所有图片，再插入所有分割线；两者都按 block_index 从大到小顺序执行。
47. Step 7：保存草稿；验证内容已粘贴（检查字数指示）；草稿会自动保存，必要时点击 Save 按钮；点击「预览」验证格式；报告「Draft saved. Review and publish manually.」。
48. 关键规则：绝不发布，只保存草稿。
49. 关键规则：先预处理，再解析；发布前转换表格/mermaid/深层标题。
50. 关键规则：第一张图片作为封面图上传。
51. 关键规则：始终把 Markdown 转成 HTML 再粘贴，并通过剪贴板 API 粘贴以保留格式。
52. 关键规则：使用 block_index 精确定位图片/分割线；图片和分割线都从最高到最低 block_index 反向插入。
53. 关键规则：H1 只用作标题，不包含在正文中。
54. 关键规则：分割线必须通过 Insert > Divider 菜单插入，HTML <hr> 会被忽略。
55. 支持的格式化（预处理后）：H2 原生；Bold（**）原生；Italic（*）原生；Links（[](url)）原生；有序列表原生；无序列表原生；Blockquotes（>）原生；Code blocks 转为 Blockquotes；Tables 转为 PNG 图片；Mermaid 转为 PNG 图片；H3+ 标题转为 H2 或加粗；Dividers（---）通过 Insert > Divider 菜单插入。
56. 最佳实践：为什么用 block_index 而非文字匹配？因为精确定位，不依赖文字内容，即使多处文字相似也能正确定位；索引是确定性的，不会因文字相似而混淆；after_text 仍保留供人工核验。
57. 最佳实践：为什么用 Python 而非浏览器内 JavaScript？因为本地处理更可靠，Python 直接操作系统剪贴板，不受浏览器沙盒限制；可在上传前压缩图片（--quality 85）以减少上传时间；脚本固定不变可复用；脚本可单独测试，问题易定位。
58. 最佳实践：等待策略；browser_wait_for 的 textGone 参数会在文字消失时立即返回，time 只是最大等待时间而非固定等待时间。正确用法：browser_wait_for textGone="正在上传媒体" time=2；错误用法：browser_wait_for time=5（无条件等待 5 秒，浪费时间）。
59. 最佳实践：封面图 vs 内容图；封面图使用 browser_file_upload，因为有专门上传按钮；内容图使用 Python 剪贴板 + 粘贴，更高效。
60. 脚本 copy_to_clipboard.py 用法：复制图片时可运行 python copy_to_clipboard.py image /path/to/image.jpg [--quality 80]；复制 HTML 时可运行 python copy_to_clipboard.py html --file /path/to/content.html。
61. 故障排除：表格未正确渲染时，确保已安装 Pillow（pip install pillow），并检查表格 Markdown 语法有效。
62. 故障排除：Mermaid 转换失败时，检查 diagramless.xyz 是否可达，检查 mermaid 语法有效，可尝试显式类型 --type mermaid。
63. 故障排除：深层标题仍显示时，手动扁平化 ### → ## 或 **bold**，然后重新运行预处理。
64. 故障排除：图片上传超时时，用 --quality 70 压缩图片，并使用更短的 browser_wait_for time=2。

适用边界 · 注意事项

• 没有 X Premium 或 X Premium+ 订阅、未登录 X，或无法访问 X Articles 编辑器时不适用。
• 缺少 Playwright MCP、Python 3.9+ 及依赖（macOS：pip install Pillow pyobjc-framework-Cocoa markdown；Windows：pip install Pillow pywin32 clip-util markdown）、diagram-to-image skill 或 diagramless.xyz API 不可达时，无法完整执行表格和 Mermaid 转换。
• 用户要求直接发布而非只保存草稿，或不允许修改/生成适配副本时不适用，因为该流程只保存草稿并会保留原文件、使用适配副本。