X Article Publisher

1---
2name: x-article-publisher
3description: |
4  Publish Markdown articles to X (Twitter) Articles editor with proper formatting. Use when user wants to publish a Markdown file/URL to X Articles, or mentions "publish to X", "post article to Twitter", "X article", or wants help with X Premium article publishing. Handles cover image upload and converts Markdown to rich text automatically.
5---
6 
7# X Article Publisher
8 
9Publish Markdown content to X (Twitter) Articles editor, preserving formatting with rich text conversion.
10 
11## Prerequisites
12 
13- Playwright MCP for browser automation
14- User logged into X with Premium Plus subscription
15- Python 3.9+ with dependencies:
16  - macOS: `pip install Pillow pyobjc-framework-Cocoa`
17  - Windows: `pip install Pillow pywin32 clip-util`
18- For Mermaid diagrams: `npm install -g @mermaid-js/mermaid-cli`
19 
20## Scripts
21 
22Located in `~/.claude/skills/x-article-publisher/scripts/`:
23 
24### parse_markdown.py
25Parse Markdown and extract structured data:
26```bash
27python parse_markdown.py <markdown_file> [--output json|html] [--html-only]
28```
29Returns JSON with: title, cover_image, content_images, **dividers** (with block_index for positioning), html, total_blocks
30 
31### copy_to_clipboard.py
32Copy image or HTML to system clipboard (cross-platform):
33```bash
34# Copy image (with optional compression)
35python copy_to_clipboard.py image /path/to/image.jpg [--quality 80]
36 
37# Copy HTML for rich text paste
38python copy_to_clipboard.py html --file /path/to/content.html
39```
40 
41### table_to_image.py
42Convert Markdown table to PNG image:
43```bash
44python table_to_image.py <input.md> <output.png> [--scale 2]
45```
46Use when X Articles doesn't support native table rendering or for consistent styling.
47 
48## Pre-Processing (Optional)
49 
50Before publishing, scan the Markdown for elements that need conversion:
51 
52### Tables → PNG
53```bash
54# Extract table to temp file, then convert
55python ~/.claude/skills/x-article-publisher/scripts/table_to_image.py /tmp/table.md /tmp/table.png
56# Replace table in markdown with: ![Table](/tmp/table.png)
57```
58 
59### Mermaid Diagrams → PNG
60```bash
61# Extract mermaid block to .mmd file, then convert
62mmdc -i /tmp/diagram.mmd -o /tmp/diagram.png -b white -s 2
63# Replace mermaid block with: ![Diagram](/tmp/diagram.png)
64```
65 
66### Dividers (---)
67Dividers are automatically detected by `parse_markdown.py` and output in the `dividers` array. They must be inserted via X Articles' **Insert > Divider** menu (HTML `<hr>` tags are ignored by X).
68 
69## Workflow
70 
71**Strategy: "先文后图后分割线" (Text First, Images Second, Dividers Last)**
72 
73For articles with images and dividers, paste ALL text content first, then insert images and dividers at correct positions using block index.
74 
751. **(Optional)** Pre-process: Convert tables/mermaid to images
762. Parse Markdown with Python script → get title, images, **dividers** with block_index, HTML
773. Navigate to X Articles editor
784. Upload cover image (first image)
795. Fill title
806. Copy HTML to clipboard (Python) → Paste with Cmd+V
817. Insert content images at positions specified by block_index
828. **Insert dividers at positions specified by block_index** (via Insert > Divider menu)
839. Save as draft (NEVER auto-publish)
84 
85## 高效执行原则 (Efficiency Guidelines)
86 
87**目标**: 最小化操作之间的等待时间，实现流畅的自动化体验。
88 
89### 1. 避免不必要的 browser_snapshot
90 
91大多数浏览器操作（click, type, press_key 等）都会在返回结果中包含页面状态。**不要**在每次操作后单独调用 `browser_snapshot`，直接使用操作返回的页面状态即可。
92 
93```
94❌ 错误做法：
95browser_click → browser_snapshot → 分析 → browser_click → browser_snapshot → ...
96 
97✅ 正确做法：
98browser_click → 从返回结果中获取页面状态 → browser_click → ...
99```
100 
101### 2. 避免不必要的 browser_wait_for
102 
103只在以下情况使用 `browser_wait_for`：
104- 等待图片上传完成（`textGone="正在上传媒体"`）
105- 等待页面初始加载（极少数情况）
106 
107**不要**使用 `browser_wait_for` 来等待按钮或输入框出现 - 它们在页面加载完成后立即可用。
108 
109### 3. 并行执行独立操作
110 
111当两个操作没有依赖关系时，可以在同一个消息中并行调用多个工具：
112 
113```
114✅ 可以并行：
115- 填写标题 (browser_type) + 复制HTML到剪贴板 (Bash)
116- 解析Markdown生成JSON + 生成HTML文件
117 
118❌ 不能并行（有依赖）：
119- 必须先点击create才能上传封面图
120- 必须先粘贴内容才能插入图片
121```
122 
123### 4. 连续执行浏览器操作
124 
125每个浏览器操作返回的页面状态包含所有需要的元素引用。直接使用这些引用进行下一步操作：
126 
127```
128# 理想流程（每步直接执行，不额外等待）：
129browser_navigate → 从返回状态找create按钮 → browser_click(create)
130→ 从返回状态找上传按钮 → browser_click(上传) → browser_file_upload
131→ 从返回状态找应用按钮 → browser_click(应用)
132→ 从返回状态找标题框 → browser_type(标题)
133→ 点击编辑器 → browser_press_key(Meta+v)
134→ ...
135```
136 
137### 5. 准备工作前置
138 
139在开始浏览器操作之前，先完成所有准备工作：
1401. 解析 Markdown 获取 JSON 数据
1412. 生成 HTML 文件到 /tmp/
1423. 记录 title、cover_image、content_images 等信息
143 
144这样浏览器操作阶段可以连续执行，不需要中途停下来处理数据。
145 
146## Step 1: Parse Markdown (Python)
147 
148Use `parse_markdown.py` to extract all structured data:
149 
150```bash
151python ~/.claude/skills/x-article-publisher/scripts/parse_markdown.py /path/to/article.md
152```
153 
154Output JSON:
155```json
156{
157  "title": "Article Title",
158  "cover_image": "/path/to/first-image.jpg",
159  "cover_exists": true,
160  "content_images": [
161    {"path": "/path/to/img2.jpg", "original_path": "/md/dir/assets/img2.jpg", "exists": true, "block_index": 5, "after_text": "context..."},
162    {"path": "/path/to/img3.jpg", "original_path": "/md/dir/assets/img3.jpg", "exists": true, "block_index": 12, "after_text": "another..."}
163  ],
164  "html": "<p>Content...</p><h2>Section</h2>...",
165  "total_blocks": 45,
166  "missing_images": 0
167}
168```
169 
170**Key fields:**
171- `block_index`: The image should be inserted AFTER block element at this index (0-indexed)
172- `total_blocks`: Total number of block elements in the HTML
173- `after_text`: Kept for reference/debugging only, NOT for positioning
174- `exists`: Whether the image file was found (if false, upload will fail)
175- `original_path`: The path resolved from Markdown (before auto-search)
176- `path`: The actual path to use (may differ from original_path if auto-searched)
177- `missing_images`: Count of images not found anywhere
178 
179Save HTML to temp file for clipboard:
180```bash
181python parse_markdown.py article.md --html-only > /tmp/article_html.html
182```
183 
184## Step 2: Open X Articles Editor
185 
186### 浏览器错误处理
187 
188如果遇到 `Error: Browser is already in use` 错误：
189 
190```
191# 方案1：先关闭浏览器再重新打开
192browser_close
193browser_navigate: https://x.com/compose/articles
194 
195# 方案2：如果 browser_close 无效（锁定），提示用户手动关闭 Chrome
196 
197# 方案3：使用已有标签页，直接导航
198browser_tabs action=list  # 查看现有标签
199browser_navigate: https://x.com/compose/articles  # 在当前标签导航
200```
201 
202**最佳实践**：每次开始前先用 `browser_tabs action=list` 检查状态，避免创建多余空白标签。
203 
204### 导航到编辑器
205 
206```
207browser_navigate: https://x.com/compose/articles
208```
209 
210**重要**: 页面加载后会显示草稿列表，不是编辑器。需要：
211 
2121. **等待页面加载完成**: 使用 `browser_snapshot` 检查页面状态
2132. **立即点击 "create" 按钮**: 不要等待 "添加标题" 等编辑器元素，它们只有点击 create 后才出现
2143. **等待编辑器加载**: 点击 create 后，等待编辑器元素出现
215 
216```
217# 1. 导航到页面
218browser_navigate: https://x.com/compose/articles
219 
220# 2. 获取页面快照，找到 create 按钮
221browser_snapshot
222 
223# 3. 点击 create 按钮（通常 ref 类似 "create" 或带有 create 标签）
224browser_click: element="create button", ref=<create_button_ref>
225 
226# 4. 现在编辑器应该打开了，可以继续上传封面图等操作
227```
228 
229**注意**: 不要使用 `browser_wait_for text="添加标题"` 来等待页面加载，因为这个文本只有在点击 create 后才出现，会导致超时。
230 
231If login needed, prompt user to log in manually.
232 
233## Step 3: Upload Cover Image
234 
2351. Click "添加照片或视频" button
2362. Use browser_file_upload with the cover image path (from JSON output)
2373. Verify image uploaded
238 
239## Step 4: Fill Title
240 
241- Find textbox with "添加标题" placeholder
242- Use browser_type to input title (from JSON output)
243 
244## Step 5: Paste Text Content (Python Clipboard)
245 
246Copy HTML to system clipboard using Python, then paste:
247 
248```bash
249# Copy HTML to clipboard
250python ~/.claude/skills/x-article-publisher/scripts/copy_to_clipboard.py html --file /tmp/article_html.html
251```
252 
253Then in browser:
254```
255browser_click on editor textbox
256browser_press_key: Meta+v
257```
258 
259This preserves all rich text formatting (H2, bold, links, lists).
260 
261## Step 6: Insert Content Images (Text Search Positioning)
262 
263**推荐方法**: 使用 `after_text` 文字搜索定位，比 `block_index` 更直观可靠。
264 
265### 定位原理
266 
267每张图片的 `after_text` 字段记录了它前一个段落的末尾文字（最多80字符）。在编辑器中搜索包含该文字的段落，点击后插入图片。
268 
269### 操作步骤
270 
271For each content image (from `content_images` array), **按 block_index 从大到小的顺序**：
272 
273```bash
274# 1. Copy image to clipboard (with compression)
275python ~/.claude/skills/x-article-publisher/scripts/copy_to_clipboard.py image /path/to/img.jpg --quality 85
276```
277 
278```
279# 2. 在 browser_snapshot 中搜索包含 after_text 的段落
280#    找到该段落的 ref
281 
282# 3. Click the paragraph containing after_text
283browser_click: element="paragraph with target text", ref=<paragraph_ref>
284 
285# 4. **关键步骤**: 按 End 键移动光标到行尾
286#    这一步非常重要！避免点击到段落中的链接导致位置偏移
287browser_press_key: End
288 
289# 5. Paste image
290browser_press_key: Meta+v
291 
292# 6. Wait for upload (only use textGone, no time parameter)
293browser_wait_for textGone="正在上传媒体"
294```
295 
296### 为什么需要按 End 键？
297 
298**问题**: 当段落包含链接时（如 `[链接文字](url)`），点击段落可能会：
299- 触发链接编辑弹窗
300- 将光标定位在链接内部而非段落末尾
301 
302**解决方案**: 点击段落后立即按 `End` 键：
303- 确保光标移动到段落末尾
304- 避免链接干扰
305- 图片将正确插入在该段落之后
306 
307### 定位策略
308 
309在 browser_snapshot 返回的结构中，搜索 `after_text` 的关键词：
310 
311```yaml
312textbox [ref=editor]:
313  generic [ref=p1]:
314    - StaticText: "元旦假期我在家里翻手机相册..."  # 如果 after_text 包含这段文字，点击 p1
315  heading [ref=h1]:
316    - StaticText: "演示"
317  generic [ref=p2]:
318    - StaticText: "这东西到底有多省事儿？"
319    - link [ref=link1]: "Claude Code"  # 注意：段落可能包含链接
320  ...
321```
322 
323### 反向插入示例
324 
325如果有3张图片，block_index 分别为 5, 12, 27：
3261. 先插入 block_index=27 的图片（after_text 搜索 + End + 粘贴）
3272. 再插入 block_index=12 的图片
3283. 最后插入 block_index=5 的图片
329 
330**从大到小插入**可以避免位置偏移问题。
331 
332## Step 6.5: Insert Dividers (Via Menu)
333 
334**重要**: Markdown 中的 `---` 分割线不能通过 HTML `<hr>` 标签粘贴（X Articles 会忽略它）。必须通过 X Articles 的 Insert 菜单插入。
335 
336### 操作步骤
337 
338For each divider (from `dividers` array), in **reverse order of block_index**:
339 
340```
341# 1. Click the block element at block_index position
342browser_click on the element at position block_index in the editor
343 
344# 2. Open Insert menu (Add Media button)
345browser_click on "Insert" or "添加媒体" button
346 
347# 3. Click Divider menu item
348browser_click on "Divider" or "分割线" menuitem
349 
350# Divider is inserted at cursor position
351```
352 
353### 与图片的插入顺序
354 
355建议先插入所有图片，再插入所有分割线。两者都按 block_index **从大到小**的顺序：
356 
3571. 插入所有图片（从最大 block_index 开始）
3582. 插入所有分割线（从最大 block_index 开始）
359 
360## Step 7: Save Draft
361 
3621. Verify content pasted (check word count indicator)
3632. Draft auto-saves, or click Save button if needed
3643. Click "预览" to verify formatting
3654. Report: "Draft saved. Review and publish manually."
366 
367## Critical Rules
368 
3691. **NEVER publish** - Only save draft
3702. **First image = cover** - Upload first image as cover image
3713. **Rich text conversion** - Always convert Markdown to HTML before pasting
3724. **Use clipboard API** - Paste via clipboard for proper formatting
3735. **Block index positioning** - Use block_index for precise image/divider placement
3746. **Reverse order insertion** - Insert images and dividers from highest to lowest block_index
3757. **H1 title handling** - H1 is used as title only, not included in body
3768. **Dividers via menu** - Markdown `---` must be inserted via Insert > Divider menu (HTML `<hr>` is ignored)
377 
378## Supported Formatting
379 
380| Element | Support | Notes |
381|---------|---------|-------|
382| H2 (`##`) | Native | Section headers |
383| Bold (`**`) | Native | Strong emphasis |
384| Italic (`*`) | Native | Emphasis |
385| Links (`[](url)`) | Native | Hyperlinks |
386| Ordered lists | Native | 1. 2. 3. |
387| Unordered lists | Native | - bullets |
388| Blockquotes (`>`) | Native | Quoted text |
389| Code blocks | Converted | → Blockquotes |
390| Tables | Converted | → PNG images (use table_to_image.py) |
391| Mermaid | Converted | → PNG images (use mmdc) |
392| Dividers (`---`) | Menu insert | → Insert > Divider |
393 
394## Example Flow
395 
396User: "Publish /path/to/article.md to X"
397 
398```bash
399# Step 1: Parse Markdown
400python ~/.claude/skills/x-article-publisher/scripts/parse_markdown.py /path/to/article.md > /tmp/article.json
401python ~/.claude/skills/x-article-publisher/scripts/parse_markdown.py /path/to/article.md --html-only > /tmp/article_html.html
402```
403 
4042. Navigate to https://x.com/compose/articles
4053. Upload cover image (browser_file_upload for cover only)
4064. Fill title (from JSON: `title`)
4075. Copy & paste HTML:
408   ```bash
409   python ~/.claude/skills/x-article-publisher/scripts/copy_to_clipboard.py html --file /tmp/article_html.html
410   ```
411   Then: browser_press_key Meta+v
4126. For each content image, **in reverse order of block_index**:
413   ```bash
414   python copy_to_clipboard.py image /path/to/img.jpg --quality 85
415   ```
416   - Click block element at `block_index` position
417   - browser_press_key Meta+v
418   - Wait until upload complete
4197. Verify in preview
4208. "Draft saved. Please review and publish manually."
421 
422## Best Practices
423 
424### 为什么用 block_index 而非文字匹配？
425 
4261. **精确定位**: 不依赖文字内容，即使多处文字相似也能正确定位
4272. **可靠性**: 索引是确定性的，不会因为文字相似而混淆
4283. **调试方便**: `after_text` 仍保留用于人工核验
429 
430### 为什么用 Python 而非浏览器内 JavaScript？
431 
4321. **本地处理更可靠**: Python 直接操作系统剪贴板，不受浏览器沙盒限制
4332. **图片压缩**: 上传前压缩图片 (--quality 85)，减少上传时间
4343. **代码复用**: 脚本固定不变，无需每次重新编写转换逻辑
4354. **调试方便**: 脚本可单独测试，问题易定位
436 
437### 等待策略
438 
439**重要发现**: Playwright MCP 的 `browser_wait_for` 实际行为是 **先等待 time 秒，再检查条件**，而非轮询！
440 
441```javascript
442// 实际执行的代码：
443await new Promise(f => setTimeout(f, time * 1000));  // 先固定等待
444await page.getByText("xxx").waitFor({ state: 'hidden' });  // 再检查
445```
446 
447**正确用法**:
448- ✅ 只用 `textGone`，不设 `time`：让 Playwright 自己轮询等待
449- ✅ 只用 `time`：固定等待指定秒数
450- ❌ 同时用 `textGone` + `time`：会先等 time 秒再检查，浪费时间
451 
452```
453# 推荐：只用 textGone，让它自动等待条件满足
454browser_wait_for textGone="正在上传媒体"
455 
456# 或者：用 browser_snapshot 轮询检查状态
457# 每次操作后检查返回的页面状态，无需额外等待
458```
459 
460### 图片插入效率
461 
462每张图片的浏览器操作从5步减少到2步：
463- 旧: 点击 → 添加媒体 → 媒体 → 添加照片 → file_upload
464- 新: 点击段落 → Meta+v
465 
466### 封面图 vs 内容图
467 
468- **封面图**: 使用 browser_file_upload（因为有专门的上传按钮）
469- **内容图**: 使用 Python 剪贴板 + 粘贴（更高效）
470 
471## 故障排除
472 
473### MCP 连接问题
474 
475如果 Playwright MCP 工具不可用（报错 `No such tool available` 或 `Not connected`）：
476 
477**方案1：重新连接 MCP（推荐）**
478```
479执行 /mcp 命令，选择 playwright，选择 Restart
480```
481 
482**方案2：清理残留进程后重连**
483```bash
484# 杀掉所有残留的 playwright 进程
485pkill -f "mcp-server-playwright"
486pkill -f "@playwright/mcp"
487 
488# 然后执行 /mcp 重新连接
489```
490 
491**配置文件位置**: `~/.claude/mcp_servers.json`
492 
493### 浏览器错误处理
494 
495如果遇到 `Error: Browser is already in use` 错误：
496 
497```bash
498# 方案1：先关闭浏览器再重新打开
499browser_close
500browser_navigate: https://x.com/compose/articles
501 
502# 方案2：杀掉 Chrome 进程
503pkill -f "Chrome.*--remote-debugging"
504# 然后重新 navigate
505```
506 
507### 图片位置偏移
508 
509如果图片插入位置不正确（特别是点击含链接的段落时）：
510 
511**原因**: 点击段落时可能误触链接，导致光标位置错误
512 
513**解决方案**: 点击后**必须按 End 键**移动光标到行尾
514 
515```
516# 正确流程
5171. browser_click 点击目标段落
5182. browser_press_key: End        # 关键步骤！
5193. browser_press_key: Meta+v     # 粘贴图片
5204. browser_wait_for textGone="正在上传媒体"
521```
522 
523### 图片路径找不到
524 
525如果 Markdown 中的相对路径图片找不到（如 `./assets/image.png` 实际在其他位置）：
526 
527**自动搜索**: `parse_markdown.py` 会自动在以下目录搜索同名文件：
528- `~/Downloads`
529- `~/Desktop`
530- `~/Pictures`
531 
532**stderr 输出示例**:
533```
534[parse_markdown] Image not found at '/path/to/assets/img.png', using '/Users/xxx/Downloads/img.png' instead
535```
536 
537**JSON 字段说明**:
538- `original_path`: Markdown 中指定的路径（解析后的绝对路径）
539- `path`: 实际使用的路径（如果自动搜索成功，会不同于 original_path）
540- `exists`: `true` 表示找到文件，`false` 表示未找到（上传会失败）
541 
542**如果仍然找不到**:
5431. 检查 JSON 输出中的 `missing_images` 字段
5442. 手动将图片复制到 Markdown 文件同目录的 `assets/` 子目录
5453. 或修改 Markdown 中的图片路径为绝对路径
546