baoyu-post-to-wechat

發布到微信公眾號

使用者輸入工具

當此技能提示使用者時，請遵循以下工具選擇規則（優先順序）：

1. 優先使用目前代理執行環境提供的內建使用者輸入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 備用方案：如果沒有此類工具，則發出編號的純文字訊息，並要求使用者回覆每個問題的選擇編號/答案。
3. 批次處理：如果工具支援單次呼叫多個問題，則將所有適用的問題合併為一次呼叫；如果僅支援單一問題，則依優先順序逐一詢問。

以下具體的 AskUserQuestion 參考僅為範例 — 請在其他執行環境中替換為對應的本地工具。

語言

以使用者的語言回覆。如果使用者使用中文，則以中文回覆；如果使用英文，則以英文回覆。保留技術性詞彙（路徑、旗標、欄位名稱）為英文。

腳本目錄

{baseDir} = 此 SKILL.md 所在的目錄。解析 ${BUN_X}：優先使用 bun；否則使用 npx -y bun；否則建議執行 brew install oven-sh/bun/bun。

腳本	用途
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）

依序檢查以下路徑，第一個找到的優先使用：

路徑	範圍
.baoyu-skills/baoyu-post-to-wechat/EXTEND.md	專案
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-post-to-wechat/EXTEND.md	XDG
$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md	使用者家目錄

找到 → 讀取、解析、套用。未找到 → 在進行任何其他操作前，先執行首次設定（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: browser
default_author: 寶玉
need_open_comment: 1
only_fans_can_comment: 0
chrome_profile_path: /path/to/chrome/profile

# 遠端 API 發布（選用）— 僅在微信 IP 白名單
# 排除本機時設定。請參閱下方「遠端 API 方法」。
# remote_publish_host: server.example.com
# remote_publish_user: deploy
# remote_publish_port: 22
# remote_publish_identity_file: ~/.ssh/id_ed25519
# remote_publish_known_hosts_file: ~/.ssh/known_hosts
# remote_publish_strict_host_key_checking: accept-new
# remote_publish_connect_timeout: 10
# remote_publish_proxy_jump: bastion.example.com

原始 ssh / scp 選項刻意不支援；僅上述指定鍵值有效。認證僅支援 SSH 金鑰（無密碼）。

主題選項：default、grace、simple、modern。顏色預設：blue、green、vermilion、yellow、purple、sky、rose、olive、black、gray、pink、red、orange（或十六進位色碼）。

值優先順序：CLI 參數 → frontmatter → EXTEND.md（帳戶層級 → 全域）→ 技能預設值。

多帳戶支援

EXTEND.md 支援 accounts: 區塊，用於管理多個公眾號。當有 2 個以上項目時，工作流程會插入步驟 0.5，提示選擇帳戶（或根據 default: true 或 --account <alias> 自動選擇）。

完整細節 — 相容性規則、各帳戶鍵值、憑證解析、各帳戶 Chrome 設定檔、CLI 用法 — 請參閱 references/multi-account.md。

起飛前檢查（選用）

在首次使用前，建議進行環境檢查（使用者可跳過）：

${BUN_X} {baseDir}/scripts/check-permissions.ts

檢查項目：Chrome、設定檔隔離、Bun、輔助使用、剪貼簿、貼上按鍵、API 憑證、Chrome 衝突。

檢查失敗	修正方式
Chrome	安裝 Chrome 或設定 WECHAT_BROWSER_CHROME_PATH
設定檔目錄	共用設定檔位於 baoyu-skills/chrome-profile
Bun 執行環境	brew install oven-sh/bun/bun 或 npm install -g bun
輔助使用（macOS）	系統設定 → 隱私權與安全性 → 輔助使用 → 啟用終端機應用程式
剪貼簿複製	確保 Swift/AppKit（macOS：xcode-select --install）
貼上按鍵（Linux）	安裝 xdotool（X11）或 ydotool（Wayland）
API 憑證	依照步驟 2 的引導設定，或在 .baoyu-skills/.env 中設定

圖文貼文（貼圖）

包含多張圖片（最多 9 張）的短貼文：

${BUN_X} {baseDir}/scripts/wechat-browser.ts --markdown article.md --images ./images/
${BUN_X} {baseDir}/scripts/wechat-browser.ts --title "標題" --content "內容" --image img.png --submit

詳細資訊：references/image-text-posting.md。

文章發布工作流程（文章）

- [ ] 步驟 0：載入偏好設定（EXTEND.md）
- [ ] 步驟 0.5：解析帳戶（僅多帳戶 — 請參閱 references/multi-account.md）
- [ ] 步驟 1：判斷輸入類型
- [ ] 步驟 2：選擇方法並設定憑證
- [ ] 步驟 3：解析主題/顏色並驗證中繼資料
- [ ] 步驟 4：發布到微信
- [ ] 步驟 5：回報完成

步驟 0：載入偏好設定

檢查並載入 EXTEND.md（請參閱上方「偏好設定」）。如果未找到，請在提出任何其他問題前完成首次設定。解析並快取後續步驟所需的設定：default_theme、default_color、default_author、need_open_comment、only_fans_can_comment。

步驟 1：判斷輸入類型

輸入	偵測方式	下一步
HTML 檔案	路徑結尾為 .html，檔案存在	跳至步驟 3
Markdown 檔案	路徑結尾為 .md，檔案存在	步驟 2
純文字	不是檔案路徑，或檔案不存在	儲存為 markdown，然後步驟 2

純文字處理方式：

1. 產生 slug（前 2-4 個有意義的單字，kebab-case；中文翻譯為英文以產生 slug）。
2. 儲存至 post-to-wechat/YYYY-MM-DD/<slug>.md（必要時建立目錄）。
3. 繼續作為 markdown 檔案處理。

步驟 2：選擇發布方法並設定

詢問方法，除非已在 EXTEND.md 或 CLI 中指定：

方法	速度	需求
api（建議）	快	API 憑證（本機 IP 已加入白名單）
browser	慢	Chrome + 已登入的工作階段
remote-api	快	API 憑證 + 可透過 SSH 連線的伺服器，其 IP 在微信白名單中

選擇 API 但缺少憑證 → 依照 references/api-setup.md 執行引導式設定（寫入 .baoyu-skills/.env）。

remote-api 方法：微信的「公眾號設定 → IP 白名單」通常將 API 存取限制為一或兩個固定 IP。如果本機 IP 不在該清單中，但雲端伺服器的 IP 在清單中，請使用 remote-api：所有 markdown 渲染、圖片處理、草稿組裝和 HTML 重寫仍在本地進行，僅對 api.weixin.qq.com 的 HTTPS 呼叫（token、uploadimg、add_material、draft/add）透過 SSH SOCKS5 動態埠轉發（ssh -N -D）進行隧道傳輸，使微信將遠端伺服器視為來源 IP。不會在遠端主機上寫入任何檔案；AppSecret 永遠不會離開本機程序。僅需遠端主機上執行 sshd 並具備對外網路連線 — 無需 Python，無需代理程序。請參閱下方「遠端 API 方法」。

步驟 3：解析主題/顏色並驗證中繼資料

1. 主題：CLI --theme → EXTEND.md default_theme → default（第一個符合者優先；若已解析則不詢問）。
2. 顏色：CLI --color → EXTEND.md default_color → 省略（套用主題預設值）。
3. 驗證中繼資料（markdown 的 frontmatter，HTML 的 meta 標籤）：

欄位	缺少時 →
標題	詢問，或按 Enter 從內容自動產生
摘要	Frontmatter description → summary → 詢問或自動產生
作者	CLI --author → frontmatter author → EXTEND.md default_author
來源網址	CLI --source-url → frontmatter sourceUrl/contentSourceUrl/content_source_url

自動產生：標題 = 第一個 H1/H2 或第一個句子；摘要 = 第一個段落，截斷至 120 字元。

4. 封面圖片（API article_type=news 時必填）：CLI --cover → frontmatter（coverImage / featureImage / cover / image）→ imgs/cover.png → 第一張內嵌圖片 → 若仍缺少則停止並要求提供。

步驟 4：發布

重要 — 切勿預先將 markdown 轉換為 HTML。 發布腳本會在內部處理轉換，且兩種方法對圖片的渲染方式不同：API 會為上傳的圖片渲染 <img> 標籤，瀏覽器則使用佔位符進行貼上與取代。傳入預先轉換的 HTML 會破壞其中一種方法。

Markdown 引用預設行為：對於 markdown 輸入，一般外部連結預設會轉換為底部引用。僅在使用者明確希望保留內嵌連結時，才使用 --no-cite。現有的 HTML 輸入則保持原樣。

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

${BUN_X} {baseDir}/scripts/wechat-api.ts <file> --theme <theme> [--color <color>] [--title <title>] [--summary <summary>] [--author <author>] [--cover <cover_path>] [--source-url <url>] [--no-cite]

即使主題為 default，也務必傳入 --theme。僅在使用者或 EXTEND.md 明確設定顏色時，才傳入 --color。

遠端 API 方法（相同腳本，加上 --remote）：

${BUN_X} {baseDir}/scripts/wechat-api.ts <file> --theme <theme> --remote [--remote-host <host>] [--remote-user <user>] [--remote-port <port>] [--remote-identity-file <path>] [--remote-known-hosts-file <path>] [--remote-strict-host-key-checking yes|no|accept-new] [--remote-connect-timeout <s>] [--remote-proxy-jump <spec>]

任何 --remote-* 旗標都隱含 --remote。CLI 值會覆蓋 EXTEND.md 中帳戶層級再來全域的 remote_publish_* 鍵值。將 default_publish_method: remote-api 設為預設值時，即使不帶 --remote 也會啟用遠端模式。

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），即使 CLI 未公開這些參數
• 對於 news，可選擇性包含 content_source_url（原文網址，顯示為「閱讀原文」連結，最大 1KB）。透過 CLI 旗標 --source-url 或 frontmatter sourceUrl/contentSourceUrl/content_source_url 提供

瀏覽器方法（接受 --markdown 或 --html）：

${BUN_X} {baseDir}/scripts/wechat-article.ts --markdown <markdown_file> --theme <theme> [--color <color>] [--no-cite]
${BUN_X} {baseDir}/scripts/wechat-article.ts --html <html_file>

步驟 5：完成回報

微信發布完成！

輸入： [類型] - [路徑]
方法： [API | 瀏覽器]
主題： [主題] [顏色（若有設定）]

文章：
• 標題： [標題]
• 摘要： [摘要]
• 圖片： [N] 張內嵌
• 留言： [開啟/關閉]， [僅粉絲/所有人]    ← 僅 API 方法

結果：
✓ 草稿已儲存至微信公眾號
• media_id： [media_id]                         ← 僅 API 方法

後續步驟（API）：
→ 管理草稿：https://mp.weixin.qq.com（登入後進入「內容管理」→「草稿箱」）

已建立的檔案：
[• post-to-wechat/YYYY-MM-DD/slug.md（若為純文字輸入）]
[• slug.html（已轉換）]

功能比較

功能	圖文貼文	文章（API）	文章（遠端 API）	文章（瀏覽器）
純文字輸入	✗	✓	✓	✓
HTML 輸入	✗	✓	✓	✓
Markdown 輸入	標題/內容	✓	✓	✓
多張圖片	✓（最多 9 張）	✓（內嵌）	✓（內嵌）	✓（內嵌）
主題	✗	✓	✓	✓
自動產生中繼資料	✗	✓	✓	✓
預設封面備用（imgs/cover.png）	✗	✓	✓	✗
留言控制	✗	✓	✓	✗
需要 Chrome	✓	✗	✗	✓
需要 API 憑證	✗	✓	✓	✗
需要可透過 SSH 連線且 IP 已加入白名單的伺服器	✗	✗	✓	✗
速度	中等	快	快	慢

疑難排解

問題	修正方式
缺少 API 憑證	依照步驟 2 的引導設定
Access token 錯誤	確認憑證有效且未過期
未登入（瀏覽器）	首次執行會開啟瀏覽器 — 掃描 QR code 登入。設定 TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID 以透過 Telegram 接收 QR 圖片
找不到 Chrome	設定 WECHAT_BROWSER_CHROME_PATH
缺少標題/摘要	使用自動產生或手動提供
無封面圖片	在 frontmatter 中加入封面，或在文章目錄中放置 imgs/cover.png
留言預設值錯誤	檢查 EXTEND.md 中的 need_open_comment / only_fans_can_comment
貼上失敗	檢查系統剪貼簿權限
Remote publish host is required	設定 --remote-host 或在 EXTEND.md 中設定 remote_publish_host
SOCKS proxy on 127.0.0.1:… not ready	SSH 無法啟動隧道 — 檢查金鑰、主機、StrictHostKeyChecking，或使用 --remote-connect-timeout
遠端發布時 ssh exited early	確認使用者可以非互動方式 ssh 到伺服器；若連線較慢，請調高 --remote-connect-timeout
遠端 API 呼叫回傳 errcode 40164（IP 無效）	遠端伺服器的出口 IP 不在微信白名單中；請在「公眾號設定 → IP 白名單」中新增

參考資料

檔案	內容
references/image-text-posting.md	圖文貼文參數、自動壓縮
references/article-posting.md	文章主題、圖片處理
references/multi-account.md	多帳戶相容性、憑證、Chrome 設定檔、CLI
references/api-setup.md	引導式憑證設定
references/config/first-time-setup.md	首次 EXTEND.md 設定

擴充支援

透過 EXTEND.md 進行自訂設定。請參閱「偏好設定」以了解路徑與支援的選項。