canghe-post-to-wechat

发布到微信公众号

语言

匹配用户使用的语言：使用与用户相同的语言回复。用户使用中文时，请用中文回复；用户使用英文时，请用英文回复。

脚本目录

Agent 执行：将此 SKILL.md 所在目录确定为 SKILL_DIR，然后使用 ${SKILL_DIR}/scripts/<name>.ts。

脚本	用途
scripts/wechat-browser.ts	图文
scripts/wechat-article.ts	通过浏览器发布文章
scripts/wechat-api.ts	通过 API 发布文章
scripts/check-permissions.ts	检查环境和权限

偏好设置（EXTEND.md）

使用 Bash 按优先顺序检查 EXTEND.md 是否存在：

# Check project-level first
test -f .canghe-skills/canghe-post-to-wechat/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.canghe-skills/canghe-post-to-wechat/EXTEND.md" && echo "user"

┌────────────────────────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ .canghe-skills/canghe-post-to-wechat/EXTEND.md │ 项目目录 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.canghe-skills/canghe-post-to-wechat/EXTEND.md │ 用户主目录 │ └────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 结果 │ 操作 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 找到 │ 读取、解析并应用设置 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 未找到 │ 执行首次设置（references/config/first-time-setup.md）→ 保存 → 继续 │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持：默认主题 | 默认发布方式（api/browser）| 默认作者 | 默认开启评论开关 | 默认仅粉丝评论开关 | Chrome 配置文件路径

首次设置：references/config/first-time-setup.md

最低限度支持的键（不区分大小写，接受 1/0 或 true/false）：

键	默认值	映射
default_author	空	CLI/frontmatter 未提供时，作为 author 的备用值
need_open_comment	1	draft/add 请求中的 articles[].need_open_comment
only_fans_can_comment	0	draft/add 请求中的 articles[].only_fans_can_comment

推荐的 EXTEND.md 示例：

default_theme: default
default_publish_method: api
default_author: 苍何
need_open_comment: 1
only_fans_can_comment: 0
chrome_profile_path: /path/to/chrome/profile

值的优先级：

1. CLI 参数
2. Frontmatter
3. EXTEND.md
4. 技能默认值

使用前检查（可选）

首次使用前，建议运行环境检查。用户可以选择跳过。

npx -y bun ${SKILL_DIR}/scripts/check-permissions.ts

检查项目：Chrome、配置文件隔离、Bun、辅助功能、剪贴板、粘贴按键、API 凭据、Chrome 冲突。

如果任何检查失败，请针对相应项目提供修复指导：

检查项	修复方法
Chrome	安装 Chrome，或设置 WECHAT_BROWSER_CHROME_PATH 环境变量
配置文件目录	确保 ~/.local/share/wechat-browser-profile 可写
Bun 运行时	curl -fsSL https://bun.sh/install | bash
辅助功能（macOS）	系统设置 → 隐私与安全性 → 辅助功能 → 启用终端应用
复制到剪贴板	确保 Swift/AppKit 可用（macOS Xcode 命令行工具：xcode-select --install）
粘贴按键（macOS）	同上方辅助功能修复方法
粘贴按键（Linux）	安装 xdotool（X11）或 ydotool（Wayland）
API 凭据	按照步骤 5 中的引导设置，或手动在 .canghe-skills/.env 中设置

图文发布

适用于包含多张图片（最多 9 张）的短帖：

npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./images/
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "标题" --content "内容" --image img.png --submit

详情请参阅 references/image-text-posting.md。

文章发布工作流（文章）

复制此清单，并在完成每项后勾选：

Publishing Progress:
- [ ] Step 0: Load preferences (EXTEND.md)
- [ ] Step 1: Determine input type
- [ ] Step 2: Check markdown-to-html skill
- [ ] Step 3: Convert to HTML
- [ ] Step 4: Validate metadata (title, summary, cover)
- [ ] Step 5: Select method and configure credentials
- [ ] Step 6: Publish to WeChat
- [ ] Step 7: Report completion

步骤 0：加载偏好设置

检查并加载 EXTEND.md 设置（参见上方的“偏好设置”部分）。

重要：如果未找到，请先完成首次设置，再执行任何其他步骤或提问。

解析并保存以下默认值，供后续步骤使用：

• default_author
• need_open_comment（默认值为 1）
• only_fans_can_comment（默认值为 0）

步骤 1：确定输入类型

输入类型	检测方式	操作
HTML 文件	路径以 .html 结尾，且文件存在	跳至步骤 4
Markdown 文件	路径以 .md 结尾，且文件存在	继续步骤 2
纯文本	不是文件路径，或文件不存在	保存为 Markdown 文件，然后执行步骤 2

纯文本处理：

1. 根据内容生成 slug（前 2-4 个有意义的词，使用 kebab-case）
2. 创建目录并保存文件：

mkdir -p "$(pwd)/post-to-wechat/$(date +%Y-%m-%d)"
# Save content to: post-to-wechat/yyyy-MM-dd/[slug].md

3. 继续按 Markdown 文件处理

Slug 示例：

• “Understanding AI Models” → understanding-ai-models
• “人工智能的未来” → ai-future（为 slug 翻译成英文）

步骤 2：检查 Markdown 转 HTML 技能

跳过条件：输入为 .html 文件

技能发现：

# Check if canghe-markdown-to-html exists
test -f skills/canghe-markdown-to-html/SKILL.md && echo "found"

结果	操作
找到	阅读其 SKILL.md，继续步骤 3
找到多个技能	使用 AskUserQuestion 选择
未找到	显示安装建议

未找到时：

No markdown-to-html skill found.

Suggested installation:
https://github.com/JimLiu/canghe-skills/blob/main/skills/canghe-markdown-to-html/SKILL.md

Options:
A) Cancel - install the skill first
B) Continue - provide HTML file manually

步骤 3：将 Markdown 转换为 HTML

跳过条件：输入为 .html 文件

1. 询问主题偏好（除非已在 EXTEND.md 或 CLI 中指定）：

主题	描述
default	经典主题 - 传统排版，标题居中并带底边，二级标题白字彩底
grace	优雅主题 - 文字阴影、圆角卡片、精致引用块
simple	简洁主题 - 现代极简风格、不对称圆角、清爽留白

2. 执行转换（使用已发现的技能）：

npx -y bun ${MD_TO_HTML_SKILL_DIR}/scripts/main.ts <markdown_file> --theme <theme>

3. 解析 JSON 输出，获取：htmlPath、title、author、summary、contentImages

步骤 4：验证元数据

检查步骤 3 中提取的元数据（如果直接输入 HTML，则检查 HTML meta 标签）。

字段	缺失时的处理
Title	提示：“输入标题，或按 Enter 根据内容自动生成”
Summary	提示：“输入摘要，或按 Enter 自动生成（建议用于 SEO）”
Author	使用回退顺序：CLI --author → frontmatter author → EXTEND.md default_author

自动生成逻辑：

• 标题：第一个 H1/H2 标题，或第一句话
• 摘要：第一段，截断至 120 个字符

封面图片检查（article_type=news 时必需）：

1. 如果提供了 CLI --cover，则使用该图片。
2. 否则使用 frontmatter（coverImage、featureImage、cover、image）。
3. 否则检查文章目录中的默认路径：imgs/cover.png。
4. 否则回退使用第一张正文图片。
5. 如果仍未找到，则停止并请求提供封面图片后再发布。

步骤 5：选择发布方式并配置

询问发布方式（除非已在 EXTEND.md 或 CLI 中指定）：

方式	速度	要求
api（推荐）	快	API 凭据
browser	慢	Chrome、登录会话

选择 API 时 - 检查凭据：

# Check project-level
test -f .canghe-skills/.env && grep -q "WECHAT_APP_ID" .canghe-skills/.env && echo "project"

# Check user-level
test -f "$HOME/.canghe-skills/.env" && grep -q "WECHAT_APP_ID" "$HOME/.canghe-skills/.env" && echo "user"

缺少凭据时 - 指引设置：

WeChat API credentials not found.

To obtain credentials:
1. Visit https://mp.weixin.qq.com
2. Go to: 开发 → 基本配置
3. Copy AppID and AppSecret

Where to save?
A) Project-level: .canghe-skills/.env (this project only)
B) User-level: ~/.canghe-skills/.env (all projects)

选择位置后，提示输入值并写入 .env：

WECHAT_APP_ID=<user_input>
WECHAT_APP_SECRET=<user_input>

步骤 6：发布到 WeChat

API 方式：

npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts <html_file> [--title <title>] [--summary <summary>] [--author <author>] [--cover <cover_path>]

draft/add 请求参数规则：

• 使用端点：POST https://api.weixin.qq.com/cgi-bin/draft/add?access_token=ACCESS_TOKEN
• article_type：news（默认值）或 newspic
• 对于 news，需要包含 thumb_media_id（必须提供封面）
• 始终解析并发送：
  • need_open_comment（默认值为 1）
  • only_fans_can_comment（默认值为 0）
• author 解析顺序：CLI --author → frontmatter author → EXTEND.md default_author

如果脚本参数未公开这两个评论字段，仍需确保最终 API 请求正文包含解析后的值。

浏览器方式：

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --html <html_file>

步骤 7：完成报告

对于 API 方式，包含草稿管理链接：

WeChat Publishing Complete!

Input: [type] - [path]
Method: API
Theme: [theme name]

Article:
• Title: [title]
• Summary: [summary]
• Images: [N] inline images
• Comments: [open/closed], [fans-only/all users]

Result:
✓ Draft saved to WeChat Official Account
• media_id: [media_id]

Next Steps:
→ Manage drafts: https://mp.weixin.qq.com (登录后进入「内容管理」→「草稿箱」)

Files created:
[• post-to-wechat/yyyy-MM-dd/slug.md (if plain text)]
[• slug.html (converted)]

对于浏览器方式：

WeChat Publishing Complete!

Input: [type] - [path]
Method: Browser
Theme: [theme name]

Article:
• Title: [title]
• Summary: [summary]
• Images: [N] inline images

Result:
✓ Draft saved to WeChat Official Account

Files created:
[• post-to-wechat/yyyy-MM-dd/slug.md (if plain text)]
[• slug.html (converted)]

详细参考

主题	参考
图文参数、自动压缩	references/image-text-posting.md
文章主题、图片处理	references/article-posting.md

功能对比

功能	图文	文章（API）	文章（浏览器）
纯文本输入	✗	✓	✓
HTML 输入	✗	✓	✓
Markdown 输入	标题/内容	✓（通过 skill）	✓（通过 skill）
多张图片	✓（最多 9 张）	✓（行内）	✓（行内）
主题	✗	✓	✓
自动生成元数据	✗	✓	✓
默认封面回退（imgs/cover.png）	✗	✓	✗
评论控制（need_open_comment、only_fans_can_comment）	✗	✓	✗
需要 Chrome	✓	✗	✓
需要 API 凭据	✗	✓	✗
速度	中	快	慢

前提条件

对于 API 方式：

• 微信公众号 API 凭据
• 按照步骤 5 的引导进行设置，或手动设置在 .canghe-skills/.env 中

对于浏览器方式：

• Google Chrome
• 首次运行：登录微信公众号（会保留会话）

对于 Markdown 转换：

• Markdown 转 HTML skill（例如 canghe-markdown-to-html）
• 如果未安装，工作流会建议安装

配置文件位置（按优先级排序）：

1. 环境变量
2. <cwd>/.canghe-skills/.env
3. ~/.canghe-skills/.env

故障排除

问题	解决方案
没有 Markdown 转 HTML skill	从建议的 URL 安装 canghe-markdown-to-html
缺少 API 凭据	按照步骤 5 的引导进行设置
访问令牌错误	检查 API 凭据是否有效且未过期
未登录（浏览器）	首次运行时会打开浏览器，扫描二维码登录
找不到 Chrome	设置 WECHAT_BROWSER_CHROME_PATH 环境变量
缺少标题/摘要	使用自动生成，或手动提供
没有封面图片	添加 frontmatter 封面，或将 imgs/cover.png 放入文章目录
评论默认设置错误	检查 EXTEND.md 中的 need_open_comment 和 only_fans_can_comment 键
粘贴失败	检查系统剪贴板权限

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参见偏好设置部分。