publish-zsxq-article

发布 Zsxq 文章

将 Markdown 内容发布到 Zsxq（知识星球）文章编辑器的 Markdown 模式中，并保存为草稿，供用户审核后再发布。

前提条件

• 浏览器自动化 MCP（二选一）：
  • Chrome DevTools MCP（mcp__chrome-devtools__*）
  • Playwright MCP（mcp__playwright__*）
• 用户已登录 Zsxq（知识星球）

浏览器 MCP 工具映射

此技能同时适用于 Chrome DevTools MCP 和 Playwright MCP：

操作	Chrome DevTools MCP	Playwright MCP
导航	navigate_page	browser_navigate
获取快照	take_snapshot	browser_snapshot
截取屏幕截图	take_screenshot	browser_take_screenshot
点击元素	click	browser_click
填写文本	fill	browser_type
上传文件	upload_file	browser_file_upload
按键	press_key	browser_press_key
执行 JS	evaluate_script	browser_evaluate

优先级：默认使用 Playwright MCP。只有在 Playwright MCP 不可用时才使用 Chrome DevTools MCP。

检测：运行时优先使用 mcp__playwright__browser_navigate。只有在 Playwright 工具不可用时，才回退到 mcp__chrome-devtools__navigate_page。

关键 URL

• 登录页面：https://wx.zsxq.com/login
• 文章编辑器：https://wx.zsxq.com/article?groupId={groupId}

群组 ID 解析

要导航到文章编辑器，必须提供 Zsxq 群组 ID（URL 参数 groupId=）。不要硬编码默认值。

进行任何导航前，请按以下顺序解析群组 ID：

1. 技能参数 — 如果用户调用技能时提供了群组 ID，则使用该 ID。
2. 环境变量 — 检查 ZSXQ_GROUP_ID（可选，适用于反复向同一群组发布的用户）。
3. 如果两者都没有，询问用户：

   请提供知识星球的 group ID（在星球 URL 里 groupId= 之后那串数字）。

未解析出群组 ID 前，不要继续执行步骤 2（导航）。

编辑器界面

Zsxq 文章编辑器有两种模式：

富文本模式（默认）

• 带格式工具栏的标准所见即所得编辑器
• 点击“切换到 Markdown 模式 (内测)”进行切换

Markdown 模式（首选）

• 使用 Milkdown（基于 ProseMirror 的所见即所得 Markdown 编辑器）
• 将 Markdown 渲染为格式化内容（标题、粗体、链接、列表）
• 点击“切换到富文本模式”切回

重要：内容插入方式 Milkdown 编辑器要求通过粘贴事件插入内容，不能直接填写：

• fill 工具 → 内容会被视为纯文本，不会渲染 Markdown
• 粘贴事件 → Milkdown 会解析 Markdown 并正确渲染

Markdown 模式中的关键元素

• 标题输入框：文本框“请在这里输入标题”
• 内容区域：ProseMirror 编辑器（.ProseMirror 类）
• 保存按钮：“保存”（保存为草稿）
• 预览按钮：“预览”
• 发布按钮：“发布”（不要使用——始终保存为草稿）
• 标签：“添加标签”

主要工作流

步骤 1：准备内容

读取 Markdown 文件并提取：

• 标题：取自 YAML frontmatter 的 title 字段、H1 标题 # Title，或文件名
• 内容：Markdown 正文，移除以下内容：
  • YAML frontmatter（文件顶部由 --- 分隔的区块）
  • H1 标题行（已用作文章标题）
  • HTML 注释（``）
  • 水平分隔线（---） — Milkdown 的粘贴处理器会错误解析 ---，导致后续标题和格式出错（例如，## 会被渲染为粗体的 ** 文本，而不是 H2）。粘贴前移除所有 --- 行。

# Read the markdown file
cat /path/to/article.md

步骤 2：导航到文章编辑器

# Navigate to the article editor with the resolved group ID (see Group ID Resolution above)
navigate_page: https://wx.zsxq.com/article?groupId={groupId}

如果尚未登录，页面会重定向到登录页面。提示用户手动登录：

请先登录知识星球，登录完成后告诉我。
Login URL: https://wx.zsxq.com/login

步骤 3：切换到 Markdown 模式

页面加载后，通过查找“切换到富文本模式”文本，检查是否已处于 Markdown 模式。

如果处于富文本模式（显示“切换到 Markdown 模式”）：

1. 点击“切换到 Markdown 模式 (内测)”
2. 点击“确定”确认对话框

// Check current mode
const switchBtn = document.querySelector('[class*="switch"]');
if (switchBtn && switchBtn.innerText.includes('切换到 Markdown')) {
  // Need to switch to Markdown mode
}

步骤 4：填写标题

1. 查找占位符为“请在这里输入标题”的标题文本框
2. 点击以聚焦
3. 输入标题

click: title textbox
fill: title textbox with article title

步骤 5：插入 Markdown 内容（通过粘贴事件）

关键：不要使用 fill 工具——它会插入纯文本，不会渲染 Markdown。

请改用 evaluate_script 模拟粘贴事件：

// Simulate paste event to trigger Milkdown's Markdown parsing
() => {
  const markdownContent = `YOUR_MARKDOWN_CONTENT_HERE`;

  const editorEl = document.querySelector('.ProseMirror');
  if (!editorEl) return { error: 'Editor not found' };

  // Focus the editor
  editorEl.focus();

  // Create and dispatch paste event
  const clipboardData = new DataTransfer();
  clipboardData.setData('text/plain', markdownContent);

  const pasteEvent = new ClipboardEvent('paste', {
    bubbles: true,
    cancelable: true,
    clipboardData: clipboardData
  });

  editorEl.dispatchEvent(pasteEvent);

  return { success: true, charCount: markdownContent.length };
}

此方法：

1. 使用 Markdown 内容创建 ClipboardEvent
2. 将其派发到 ProseMirror 编辑器
3. Milkdown 的粘贴处理程序会解析并渲染 Markdown

步骤 6：添加标签（可选）

1. 点击“添加标签”
2. 输入标签文本
3. 确认

步骤 7：保存为草稿

重要：始终保存为草稿，绝不要点击“发布”

1. 点击“保存”按钮以保存为草稿
2. 确认保存成功

click: "保存" button

步骤 8：验证并报告

保存后：

1. 检查是否出现成功消息或草稿状态
2. 向用户报告：

草稿已保存。请在知识星球中预览并手动发布。
Draft saved. Please review in Zsxq and publish manually.

完整示例流程

用户：“把 /path/to/my-article.md 发布到知识星球”

1. Read /path/to/my-article.md
   - Extract title from frontmatter or H1
   - Strip frontmatter, H1 title, HTML comments, and horizontal rules (`---`)
   - Get cleaned content

2. Navigate to https://wx.zsxq.com/article?groupId={resolved groupId}

3. Check if logged in
   - If not, prompt user to login

4. Switch to Markdown mode if needed
   - Click "切换到 Markdown 模式 (内测)"
   - Confirm dialog

5. Fill title
   - Click title input
   - Use `fill` tool to set title text

6. Insert content via paste event
   - Use `evaluate_script` to simulate paste event
   - This triggers Milkdown to parse and render Markdown

7. Save as draft
   - Click "保存"

8. Report success
   - "草稿已保存，请手动预览并发布"

关键规则

1. 绝不要点击“发布”——只能使用“保存”保存为草稿
2. 始终使用 Markdown 模式——如果处于富文本模式，则切换模式
3. 检查登录状态——如有需要，提示用户登录
4. 保留原始文件——绝不要修改源 Markdown 文件
5. 报告完成情况——告知用户草稿已保存，仍需手动审核
6. 先解析群组 ID——绝不要对群组 ID 进行硬编码。导航前先通过技能参数、ZSXQ_GROUP_ID 环境变量或询问用户来解析（参见“群组 ID 解析”）
7. 优先使用 Playwright MCP——默认使用 Playwright MCP；仅在 Playwright 不可用时使用 Chrome DevTools MCP

故障排除

Markdown 未渲染（显示原始语法）

如果看到原始 Markdown 语法，例如 **bold** 或 [link](url)，而不是渲染后的格式：

• 原因：使用 fill 工具而非粘贴事件插入了内容
• 解决方法：使用 evaluate_script 方法模拟粘贴事件（参见步骤 5）

Milkdown 编辑器仅会在粘贴内容时解析 Markdown，直接设置内容时不会解析。

水平分隔线（---）导致格式错乱

如果标题显示为带有 ** 标记的粗体文本，或 --- 行之后的格式错乱：

• 原因：Milkdown 的粘贴处理程序错误解析了 ---（水平分隔线），导致后续 Markdown 元素损坏
• 解决方法：粘贴前从内容中移除所有 --- 行。文章可以使用标题来分隔章节。

需要登录

如果页面跳转或显示登录提示：

请先登录知识星球: https://wx.zsxq.com/login
登录完成后告诉我。

内容过长

Zsxq 的字符数上限为 100,000。如果内容超出上限：

文章内容超过100000字符限制，请考虑拆分文章。

切换模式对话框

切换到 Markdown 模式时，会出现确认对话框：

• 消息：“确定要切换编辑器？当前内容将不会同步至新编辑器”
• 点击“确定”以确认

编辑器未加载

如果看不到编辑器元素：

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

元素参考

元素	选择器/标识符	说明
标题输入框	textbox "请在这里输入标题"	文章标题（最多 60 个字符）
内容区域	.ProseMirror（Milkdown 编辑器）	Markdown 内容（最多 100000 个字符）
保存按钮	"保存"	保存为草稿
预览按钮	"预览"	预览文章
发布按钮	"发布"	请勿使用
模式切换	"切换到 Markdown 模式" / "切换到富文本模式"	切换编辑器模式
标签	"添加标签"	添加文章标签
字数统计	"正文字数：X /100000"	字符计数器

图片上传

在富文本模式和 Markdown 模式下，都可以使用 upload_file 工具上传图片。

前提条件

• 首先检查图片文件大小：如果大于 500KB，则压缩为 WebP 或降低画质
• 使用 ls -la /path/to/image.png 检查文件大小

图片上传工作流

在两种编辑器模式下，都可以通过图片按钮上传图片：

1. 获取快照以查找图片按钮的 ref/uid

   • 富文本模式：button "image"
   • Markdown 模式：generic description="Add image"

2. 上传图片

   Chrome DevTools MCP：

   upload_file:
     uid: <image button uid>
     filePath: /path/to/image.png
   

   Playwright MCP：

   browser_file_upload:
     ref: <image button ref>
     paths: ["/path/to/image.png"]
   

3. 验证上传——截取屏幕截图，确认图片已显示在编辑器中

图片上传的关键元素

模式	图片按钮	快照中的选择器
富文本	button "image"	button "image"
Markdown	添加图片	generic description="Add image"

图片上传示例（Markdown 模式）

# 1. Take verbose snapshot to find image button
take_snapshot(verbose=true)

# 2. Find "Add image" button (e.g., uid=26_59)
# Look for: generic description="Add image"

# 3. Upload image directly to the button
upload_file:
  uid: 26_59  # (example uid for "Add image" button)
  filePath: /Users/user/Downloads/image.png

# 4. Verify with screenshot
take_screenshot

图片上传示例（富文本模式）

# 1. Take snapshot to find image button
take_snapshot

# 2. Find image button (e.g., uid=12_7)
# Look for: button "image"

# 3. Upload image to the button
upload_file:
  uid: 12_7  # (example uid for image button)
  filePath: /Users/user/Downloads/image.png

# 4. Verify with screenshot
take_screenshot

图片大小限制

• 建议的最大大小：每张图片 500KB
• 对于更大的图片，请先使用 ImageMagick 或 sips 等工具压缩：

  # Check size
  ls -la /path/to/image.png
  
  # Compress if needed (macOS)
  sips -s format jpeg -s formatOptions 80 /path/to/image.png --out /path/to/image_compressed.jpg
  

图片上传故障排除

上传后图片未显示：

• 重新获取详细快照，以获取图片按钮的正确 uid
• 确认图片文件存在且可访问
• 检查字数指示器——上传成功后，字数应有所增加

查找正确的按钮 uid：

• 使用 take_snapshot(verbose=true) 查看元素描述
• 在 Markdown 模式下，查找 generic description="Add image"
• 在富文本模式下，查找 button "image"

技术详情

Zsxq 文章编辑器使用两种不同的编辑器：

富文本模式（Quill）

• Quill：现代所见即所得编辑器
• 图片上传：通过 upload_file 工具上传到 button "image"
• 工具栏：包含图片按钮在内的标准格式设置按钮

Markdown 模式（Milkdown）

• Milkdown：由插件驱动的所见即所得 Markdown 编辑器
• ProseMirror：底层富文本编辑框架
• 粘贴处理：Milkdown 会拦截粘贴事件并解析 Markdown 内容
• 图片上传：通过 upload_file 工具上传到 generic description="Add image"

这就是用户通过 md.bytenote.net 使用的工作流能够正常运作的原因——从任何来源粘贴内容都会触发 Milkdown 的 Markdown 解析器，从而正确渲染内容。