publisher-wechatsync

name	publisher-wechatsync
description	Use when the user has a finished blog master draft and wants to publish it to multiple content platforms (知乎/掘金/CSDN/公众号 等) via the @wechatsync/cli tool. Handles pre-flight auth checks, platform selection, dry-run preview, and the actual sync. Do NOT use for writing, rewriting, compliance rewriting, or topic selection — this skill only publishes existing drafts as-is.

Publisher Wechatsync

这个 skill 只负责一件事：把已经写完的博客母稿通过 @wechatsync/cli 发到多个平台的草稿箱。

边界很明确：

• 负责：预检、平台选择、dry-run、真正同步、结果汇报
• 不负责：改写正文
• 不负责：大陆合规脱敏
• 不负责：生成平台版标题、摘要、封面图
• 不负责：替换母稿里的外链
• 不负责：删除或修改源文件

一句话原则：这一层只做"把现有 md 送到各家草稿箱"这一段,改写是另一个 skill 的事。

Working Scope

适用场景:

• 用户说"把这篇发到知乎和掘金"
• 用户说"同步到公众号草稿箱"
• 用户说"这篇母稿写完了,帮我发出去"
• 用户说"先 dry-run 一下看看能发到哪里"

不适用场景:

• 用户说"帮我改成公众号风格"
• 用户说"过一下合规"
• 用户说"帮我补摘要/封面/标题"
• 用户说"从 URL 抓取正文"

以上任意一种都不在这个 skill 的边界内。停住,告诉用户"发布 skill 不做改写,这是另一段流程"。

Required Inputs

每次执行前至少要拿到:

1. 源文件路径:一个已写完的 .md 文件路径(例如 path/to/your-article.md)
2. 目标平台列表:逗号分隔的平台名(例如 zhihu,juejin,csdn)

可选补充:

• --title:显式覆盖标题(默认从 frontmatter 或首个 # 提取)
• --cover:封面图 URL 或本地路径(知乎/公众号/小红书需要)

Preconditions

开始前必须先确认这 3 件事:

1. CLI 已安装
   • 执行 which wechatsync 能拿到路径
   • 执行 wechatsync --version 不报错
   • 如果没装,告诉用户运行 npm install -g @wechatsync/cli 再回来
2. Chrome 扩展已连通
   • 用户需要安装 Wechatsync Chrome 扩展,并开启「同步桥接 / MCP Connection」
   • 扩展里会显示一个 Token
   • 用户把 Token 写进环境变量:export WECHATSYNC_TOKEN="xxx"
   • 端口默认 9527,如果占用,用 SYNC_WS_PORT 覆盖
3. 目标平台已登录
   • 用户需要先在 Chrome 里登录目标平台(知乎、掘金、CSDN 等)的网页版
   • 扩展用的是当前浏览器的 Cookie,没登录就发不了
   • 用 wechatsync platforms -a 查各平台登录状态

如果上面任何一条没满足,停住报错,不要试图绕过。

Output Contract

这个 skill 的标准输出:

1. 预检报告(CLI 版本、Token 是否配置、目标平台登录状态)
2. dry-run 预览(将要发到哪几个平台、文件路径、标题)
3. 用户确认后的真正同步结果(每个平台是否成功、草稿链接或 id)
4. 一句总结,告诉用户下一步要去哪些平台后台审核

不生成任何中间文件。不修改源文件。不写入仓库任何位置。

Workflow

Step 1: 接收输入并自检

先做这几件事:

1. 读 CLAUDE.md / AGENTS.md,确认当前仓库流程允许发布
2. 确认用户要发的文件确实存在
3. 运行 which wechatsync,确认 CLI 可用
4. 运行 echo $WECHATSYNC_TOKEN | wc -c,确认 Token 非空

任意一条失败就停住,别继续。

Step 1.5: 规整化图片路径(预处理)

Obsidian 写出的 markdown 默认会把图片路径 URL 编码(空格变 %20,中文字符也被编码),wechatsync CLI 不会自动 decode,直接发会导致图片全部跳过。

每次发布前必须先跑预处理:

python3 scripts/normalize_image_paths.py "<md 文件路径>" --dry-run

看预览:

• 如果 找不到: 0,跑一次去掉 --dry-run 的版本,原地修正
• 如果 找不到 大于 0,停住,先排查图片文件到底在哪。不要带着 broken 图去发
• 如果 已修复: 0,说明这篇不需要预处理,直接进下一步

脚本做的事:

• URL decode 所有 markdown 图片链接
• 解析到实际文件(先按相对路径,再按仓库根)
• 重写为 markdown 文件所在目录的相对路径
• 外链(http/https/data)不动

预处理对 Obsidian 完全兼容 —— Obsidian 既接受编码路径也接受未编码路径,改完继续在 Obsidian 里看没问题。

Step 2: 列出并确认目标平台

如果用户没指定平台,默认只发 zhihu,juejin 两个技术平台:

• 知乎、掘金的合规门槛最低
• CSDN 需要手动过审,可以加
• 公众号需要提前准备封面图和摘要,要单独确认
• 小红书、头条对标题和封面要求更硬,单独确认

推荐分组:

• tech-min: zhihu,juejin — 默认,合规成本最低
• tech-full: zhihu,juejin,csdn,segmentfault,oschina — 技术平台全家桶
• with-wechat: 在上面基础上加 wechat,但要同时传 --cover 和确认标题
• social: xiaohongshu,weibo,toutiao — 社交向,注意平台对风格差异敏感

跑一次 wechatsync platforms -a 把当前登录状态调出来,不要直接假设。

Step 3: 先跑 dry-run

必须先 dry-run,不允许直接实跑。

wechatsync sync "path/to/your-article.md" -p zhihu,juejin --dry-run

把 dry-run 输出完整贴给用户,让用户确认:

• 解析到的标题对不对
• 目标平台列表对不对
• 文件路径没搞错

只要用户说"不对",停住,别修正后直接跑。先问清楚问题在哪。

Step 4: 用户确认后实跑

用户明确说"可以"或"发"之后,去掉 --dry-run 再跑一次同样的命令:

wechatsync sync "path/to/your-article.md" -p zhihu,juejin

如果要传封面或自定义标题:

wechatsync sync "path/to/your-article.md" \
  -p zhihu,juejin,wechat \
  -t "可能改过的标题" \
  --cover "path/to/cover.png"

Step 5: 汇报结果

同步完成后,按每个平台列一行结果:

• ✓ 成功:平台名 + 草稿 id 或链接
• ✗ 失败:平台名 + 错误原因

错误最常见的几类:

• 未登录:让用户去那个平台网页版登录后重试
• 超时:Chrome 扩展掉线,重启扩展或重开浏览器
• 图片上传失败:正文里有外链图片,某些平台拉不到
• 内容超长/过短:平台有字数限制

Step 6: 收尾提示

给用户一句收尾话:

• 告诉用户每个平台的草稿箱在哪里手动审核
• 提醒这是草稿,需要在平台后台预览 → 配封面 → 手动点发布
• 不要替用户去点「发布」按钮

Hard Constraints

• 禁止未经用户确认就跑非 dry-run
• 禁止跳过 Step 1.5 的图片路径预处理
• 禁止发布前改写正文(那是另一个 skill 的事)
  • 注意:预处理只改图片路径,不算改写正文
• 禁止自动补合规脱敏
• 禁止替用户在平台后台点「发布」
• 禁止跳过 wechatsync platforms -a 就假设平台已登录
• 禁止把失败结果悄悄吞掉,要完整透传错误

Reference Commands

# 安装
npm install -g @wechatsync/cli

# 版本检查
wechatsync --version

# 平台列表(带登录状态)
wechatsync platforms -a

# 查某个平台登录状态
wechatsync auth zhihu

# 预览(dry-run,不实跑)
wechatsync sync article.md -p zhihu,juejin --dry-run

# 实跑
wechatsync sync article.md -p zhihu,juejin

# 带标题和封面
wechatsync sync article.md -p zhihu,juejin,wechat -t "自定义标题" --cover ./cover.png

# 从当前浏览器页面反向抽取(不常用)
wechatsync extract -o out.md

Environment Variables

• WECHATSYNC_TOKEN:和 Chrome 扩展里的 Token 保持一致,必填
• SYNC_WS_PORT:WebSocket 端口,默认 9527,只有端口冲突时才改

Troubleshooting

报错	原因	解法
已有实例正在运行但 Chrome Extension 未连接	扩展没开同步桥接	打开扩展 → 启用 MCP Connection → 确认 Token
连接超时	扩展挂了 / Token 不一致	重启扩展,重新导出 Token,重新 export
未登录 zhihu	当前 Chrome 没登录	去 zhihu.com 登录后,再跑 wechatsync auth zhihu -r 刷新
图片上传失败	正文外链图片拉不到	图片先本地化到 assets/,再重跑

Workflow Position

• 上游:一份已经写完、改完、确认可发的 .md 母稿(写作工具不限)
• 本层:只做同步,不改写
• 下游:用户到各平台后台手动点「预览 → 发布」

一句话定位:这是创作链路的终点,不是终稿的润色层。