检测：在运行时检查可用工具。如果存在 mcp__chrome-devtools__navigate_page，则使用 Chrome DevTools MCP。如果存在 mcp__playwright__browser_navigate，则使用 Playwright MCP。

关键 URL

• Substack 仪表板：https://{publication}.substack.com/publish
• 文章编辑器：https://{publication}.substack.com/publish/post/{postId}
• 默认出版物：verysmallwoods

编辑器界面

Substack 文章编辑器使用 Tiptap（基于 ProseMirror 的所见即所得编辑器）。

关键元素

• 标题输入框：textbox "title"（占位符："Title"）
• 副标题输入框：textbox "Add a subtitle…"
• 内容区域：.ProseMirror（Tiptap 编辑器，"Start writing..."）
• 保存状态：button "Saved"（自动保存）
• 预览按钮：button "Preview"
• 继续按钮：button "Continue"（发布流程 - 请勿使用）
• 设置侧边栏：button "Settings"（标题、描述、缩略图）

设置侧边栏（左侧面板）

当"Settings"或"File Settings"打开时：

• 标题：textbox "Add a title..."
• 描述：textbox "Add a description..."
• 缩略图：上传按钮（3:2 宽高比）

工具栏

粗体、斜体、删除线、代码、链接、图片、音频、视频、引用、列表（项目符号/有序）、按钮、更多（代码块、分隔线、脚注、LaTeX 等）

内容插入方法

关键：使用剪贴板粘贴 HTML 内容，而非直接填充或粘贴纯 Markdown。

Tiptap 编辑器原生处理 HTML 粘贴并将其渲染为富内容。工作流程如下：

1. 使用 Python 的 markdown 库将 Markdown 转换为 HTML
2. 使用 copy_to_clipboard.py html 将 HTML 复制到系统剪贴板
3. 聚焦编辑器内容区域
4. 按 Cmd+V（macOS）或 Ctrl+V（Windows/Linux）粘贴

为何使用 HTML 粘贴？

• fill 工具 → 内容被视为纯文本，无格式
• 纯 Markdown 粘贴 → Tiptap 在粘贴时不会解析 Markdown
• HTML 粘贴 → Tiptap 将 HTML 渲染为富内容（标题、代码块、链接、粗体等）

已知限制：Substack 的编辑器不支持 HTML 表格。表格将被折叠为纯文本。请参阅步骤 0：预处理以将表格转换为图片。

主要工作流程

步骤 0：预处理 — 将表格转换为图片

Substack 不渲染 HTML 表格。它们会被折叠为纯文本。任何 Markdown 表格都必须转换为 PNG 图片并单独上传。

工作流程：

1. 检测 Markdown 文件中的表格（包含构成表格结构的 | 的行）

2. 使用 diagram-to-image 技能将每个表格转换为 PNG：

# 提取表格到临时文件

cat > /tmp/table1.md << 'TABLE_EOF'
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
TABLE_EOF

# 通过 diagramless.xyz API 转换（自动检测为表格）
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table1.md -o /tmp/table1.png

3. 记录每个表格在文章中的位置以便稍后插入（在哪个标题/段落之后）

1. 从内容中移除表格 Markdown（这样它就不会以纯文本形式出现在粘贴的内容中）

图片上传在主内容粘贴之后进行 — 参见步骤 7。

步骤 1：准备内容

读取 Markdown 文件并提取：

• 标题：来自 YAML frontmatter 的 title 字段，或 H1 标题 # Title，或文件名
• 副标题：来自 YAML frontmatter 的 excerpt 或 description 字段
• 内容：完整的 Markdown 正文（去除 YAML frontmatter 和任何交叉引用链接）

步骤 2：将 Markdown 转换为 HTML

使用 Python 的 markdown 库及 tables 和 fenced_code 扩展：

import markdown
import re

with open('/path/to/article.md', 'r') as f:
    content = f.read()

# 去除 YAML frontmatter
content = re.sub(r'^---\n.*?\n---\n', '', content, flags=re.DOTALL)

# 去除交叉引用链接（例如，英文版本链接）
# 根据您的文章需要调整模式
content = re.sub(r'^> .* available at.*\n\n?', '', content, flags=re.MULTILINE)

# 转换为 HTML
html = markdown.markdown(content, extensions=['tables', 'fenced_code'])

# 写入临时文件
with open('/tmp/substack_article.html', 'w') as f:
    f.write(html)

重要：请勿使用 nl2br 扩展 — 它会将单个换行符转换为 <br> 标签，导致编辑器中出现额外的换行。

步骤 3：导航到 Substack

导航到 Substack 仪表板并创建新文章：

# 导航到 Substack 仪表板
navigate to: https://verysmallwoods.substack.com/publish

如果未登录，提示用户登录：

请先登录 Substack，登录完成后告诉我。
Please log in to Substack first, then let me know.

步骤 4：创建新文章

从仪表板创建新的文本文章：

1. 点击侧边栏中的"Create new"
2. 选择"Text post"（或直接导航到新文章 URL）

或者，如果编辑器已打开且文章为空，则直接进行下一步。

步骤 5：填写标题和副标题

1. 点击标题输入框 (textbox "title")
2. 输入文章标题
3. 点击副标题输入框 (textbox "Add a subtitle…")
4. 输入副标题/摘要

click: title textbox

fill/type: article title

click: subtitle textbox
fill/type: article subtitle

步骤 6：插入 HTML 内容（通过剪贴板粘贴）

关键：请勿使用 fill 工具 — 它会插入无格式的纯文本。

1. 将 HTML 复制到系统剪贴板：

python3 /path/to/copy_to_clipboard.py html --file /tmp/substack_article.html

1. 点击编辑器内容区域（.ProseMirror 或其内部的段落元素）

2. 按 Cmd+V 粘贴：

press_key: Meta+v  (macOS)

press_key: Control+v  (Windows/Linux)

这会触发 Tiptap 的 HTML 粘贴处理器，将内容渲染为具有正确格式的富文本。

步骤 7：插入表格图片

如果文章中的表格在步骤 0 已转换为图片，现在插入它们：

1. 导航到编辑器中的正确位置 — 点击表格应出现的段落或空行（在相关标题/文本之后）

2. 点击图片工具栏按钮 (button "Image") — 出现下拉菜单，包含选项：Image, Gallery, Stock photos, Generate image

3. 点击下拉菜单中的"Image"菜单项 — 打开文件选择器对话框

4. 通过文件选择器上传图片：

   • Playwright MCP：使用图片路径的 browser_file_upload
   • Chrome DevTools MCP：使用图片路径的 upload_file

重要说明：

• 文件路径限制：Playwright MCP 只允许从允许的根目录（项目目录）上传文件。如果您的图片在 /tmp/ 中，请先将其复制到项目目录
• 为每个表格重复：将光标定位在正确位置，然后上传每个表格图片
• 删除残留文本：如果表格内容以纯文本形式粘贴（因为在预处理中未移除），请选中它（三击以选择段落）并在插入图片前删除

步骤 8：验证草稿

粘贴后：

1. 检查"Saved"状态指示器（绿点 + "Saved"文本）
2. 获取快照以验证内容结构
3. 可选地截图进行视觉验证

编辑器会自动保存，因此不需要显式的保存操作。

步骤 9：报告完成

草稿已保存到 Substack。请在 Substack 中预览并手动发布。
Draft saved to Substack. Please preview and publish manually.

Post URL: https://verysmallwoods.substack.com/publish/post/{postId}

完整示例流程

用户："把 /path/to/my-article.md 发布到 Substack"

0. 预处理表格（如果有）
   - 检测 Markdown 表格
   - 为每个表格创建带样式的 HTML
   - 渲染为截图（在浏览器中打开、截图、关闭标签页）
   - 从内容中移除表格 Markdown
   - 记录插入位置

1. 读取 /path/to/my-article.md
   - 从 frontmatter 或 H1 提取标题
   - 从 frontmatter 摘要提取副标题
   - 获取完整的 Markdown 内容（已移除表格）

2. 将 Markdown 转换为 HTML
   - 去除 frontmatter
   - 使用 markdown.markdown() 及 ['tables', 'fenced_code']
   - 写入 /tmp/substack_article.html

3. 导航到 Substack 仪表板或新文章

4. 检查是否已登录
   - 如果未登录，提示用户登录

5. 填写标题和副标题

6. 复制 HTML 到剪贴板 + 粘贴
   - python3 copy_to_clipboard.py html --file /tmp/substack_article.html
   - 点击编辑器内容区域
   - 按 Cmd+V

7. 在正确位置插入表格图片
   - 对于每个表格：点击位置 → Image 按钮 → Image 菜单项 → 文件上传

8. 验证草稿已保存
   - 检查"Saved"状态

9. 报告成功
   - "草稿已保存，请手动预览并发布"

关键规则

1. 切勿点击"Continue" — 这会启动发布流程。只保存为草稿（自动保存会处理此操作）
2. 始终先转换为 HTML — 纯 Markdown 不会被 Tiptap 编辑器解析
3. 使用剪贴板粘贴 — 插入格式化内容的唯一可靠方法
4. 检查登录状态 — 如果需要，提示用户登录
5. 保留原始文件 — 切勿修改源 Markdown 文件
6. 报告完成 — 告知用户草稿已保存并需要手动审核
7. 不使用 nl2br 扩展 — 会导致双倍换行
8. 表格 → 图片 — 在粘贴内容前预处理表格；粘贴后上传图片
9. Playwright 文件路径 — Playwright MCP 限制文件上传到允许的根目录；上传前将临时文件复制到项目目录

故障排除

内容显示为纯文本（无格式）

如果看到原始 HTML 标签或无格式文本：

• 原因：内容使用 fill 工具插入，而非剪贴板粘贴
• 解决方案：使用 copy_to_clipboard.py + Cmd+V 方法（参见步骤 6）

表格未渲染（显示纯文本）

Substack 的 Tiptap 编辑器不支持 HTML 表格。它们会被折叠为内联纯文本。

• 解决方案：通过 diagram-to-image 技能将表格转换为 PNG → 作为图片上传（参见步骤 0 和步骤 7）
• 替代方案：将简单表格重构为格式化列表
• 如果纯文本已粘贴：三击纯文本段落以选中，按 Backspace 删除，然后在该位置插入表格图片

需要登录

如果页面显示登录提示：

请先登录 Substack: https://verysmallwoods.substack.com
登录完成后告诉我。

编辑器未加载

如果编辑器元素不可见：

1. 等待页面完全加载
2. 获取新的快照
3. 如果仍未加载，刷新页面

剪贴板复制失败

如果 copy_to_clipboard.py 失败：

• 确保依赖项：pip install pyobjc-framework-Cocoa (macOS)
• 检查 HTML 文件是否存在且可读
• 先尝试复制一个较小的测试字符串

元素参考

技术细节

编辑器栈

• Tiptap：一个基于 ProseMirror 的无头、框架无关的富文本编辑器
• ProseMirror：底层的富文本编辑框架
• 粘贴处理：Tiptap 原生解析剪贴板中的 HTML 并将其转换为其内部文档模型

内容转换流水线

Markdown file
    ↓ (Python markdown library)
HTML string
    ↓ (copy_to_clipboard.py)
System clipboard (text/html + text/plain)
    ↓ (Cmd+V keyboard shortcut)
Tiptap ProseMirror editor
    ↓ (auto-save)
Substack draft

支持的格式

以下 Markdown 元素在 HTML 转换和粘贴后能正确渲染：

每周安装数

63

仓库

sugarforever/01…t-skills

GitHub 星标数

75

首次出现

Feb 10, 2026

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

codex57

opencode56

cursor56

gemini-cli56

github-copilot55

kimi-cli54