tuzi-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/md-to-wechat.ts	将 Markdown 转换为适配微信公众号的 HTML，并添加图片占位符
scripts/check-permissions.ts	验证环境和权限

偏好设置（EXTEND.md）

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

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

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

┌────────────────────────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ .tuzi-skills/tuzi-post-to-wechat/EXTEND.md │ 项目目录 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.tuzi-skills/tuzi-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_color: blue
default_publish_method: api
default_author: 宝玉
need_open_comment: 1
only_fans_can_comment: 0
chrome_profile_path: /path/to/chrome/profile

主题选项：default、grace、simple、modern

颜色预设：blue、green、vermilion、yellow、purple、sky、rose、olive、black、gray、pink、red、orange（或十六进制值）

值的优先级：

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 凭据	按照步骤 2 中的引导完成设置，或手动在 .tuzi-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: Select method and configure credentials
- [ ] Step 3: Resolve theme/color and validate metadata
- [ ] Step 4: Publish to WeChat
- [ ] Step 5: Report completion

步骤 0：加载偏好设置

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

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

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

• default_theme（默认值为 default）
• default_color（如果未设置则省略——应用主题默认值）
• default_author
• need_open_comment（默认值为 1）
• only_fans_can_comment（默认值为 0）

步骤 1：确定输入类型

输入类型	判断方式	操作
HTML 文件	路径以 .html 结尾，且文件存在	跳至步骤 3
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：选择发布方式并配置

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

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

如果选择 API——检查凭据：

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

# Check user-level
test -f "$HOME/.tuzi-skills/.env" && grep -q "WECHAT_APP_ID" "$HOME/.tuzi-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: .tuzi-skills/.env (this project only)
B) User-level: ~/.tuzi-skills/.env (all projects)

选择位置后，提示用户填写值并写入 .env：

WECHAT_APP_ID=<user_input>
WECHAT_APP_SECRET=<user_input>

第 3 步：解析主题/颜色并验证元数据

1. 解析主题（匹配到第一个即停止；如果已解析，则不要询问用户）：

   • CLI --theme 参数
   • EXTEND.md default_theme（在第 0 步加载）
   • 回退值：default

2. 解析颜色（匹配到第一个即停止）：

   • CLI --color 参数
   • EXTEND.md default_color（在第 0 步加载）
   • 如果未设置则省略（应用主题默认值）

3. 验证 frontmatter（Markdown）或 HTML meta 标签（HTML 输入）中的元数据：

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

自动生成逻辑：

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

4. 封面图片检查（API 的 article_type=news 必需）：
   1. 如果提供了 CLI --cover，则使用它。
   2. 否则使用 frontmatter（coverImage、featureImage、cover、image）。
   3. 否则检查文章目录中的默认路径：imgs/cover.png。
   4. 否则回退为正文中的第一张图片。
   5. 如果仍然缺失，则停止并要求在发布前提供封面图片。

第 4 步：发布到 WeChat

重要：发布脚本会在内部处理 Markdown 转换。不要预先将 Markdown 转换为 HTML——直接传入原始 Markdown 文件。这样可确保 API 方法将图片渲染为 <img> 标签（用于 API 上传），而浏览器方法使用占位符（用于粘贴并替换的工作流）。

API 方法（接受 .md 或 .html）：

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

重要：始终包含 --theme 参数。即使使用 default，也绝不能省略。仅当用户或 EXTEND.md 明确设置了 --color 时才包含它。

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 请求正文包含已解析的值。

浏览器方法（接受 --markdown 或 --html）：

npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown <markdown_file> --theme <theme> [--color <color>]
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --html <html_file>

第 5 步：完成报告

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

WeChat Publishing Complete!

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

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] [color if set]

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 输入	标题/内容	✓	✓
多张图片	✓（最多 9 张）	✓（正文内）	✓（正文内）
主题	✗	✓	✓
自动生成元数据	✗	✓	✓
默认封面回退（imgs/cover.png）	✗	✓	✗
评论控制（need_open_comment、only_fans_can_comment）	✗	✓	✗
需要 Chrome	✓	✗	✓
需要 API 凭据	✗	✓	✗
速度	中	快	慢

前置条件

API 方法：

• WeChat Official Account API 凭据
• 在第 2 步中按引导完成设置，或手动设置到 .tuzi-skills/.env

浏览器方法：

• Google Chrome
• 首次运行：登录 WeChat Official Account（会保留会话）

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

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

故障排除

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

扩展支持

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