前言¶

用 Agent 寫微信小程序時，常見瓶頸不在「能不能生成代碼」，而在「能不能在真實環境裏跑起來」：要在微信開發者工具裏編譯、預覽、看 console、點模擬器、上傳體驗版。這些步驟往往仍靠人手工切換窗口，Agent 只能停留在改文件。

微信開發者工具 Skills（座標 @tencent-adm/wechatide-skill）是微信小程序團隊在 SkillHub 上發佈的企業級 Skill 包，把上述工作流寫成 Agent 可遵循的 SKILL.md 與場景路由，並通過本機 wechatide CLI 調用官方工具能力。下面介紹它是什麼、能做什麼、如何安裝與典型用法。

這是什麼¶

一句話定位：面向微信開發者工具工作流的根 Skill，覆蓋小程序與小遊戲的創建導入、編譯預覽上傳、登錄與項目管理、頁面自動化、調試取證、雲開發，以及開發者工具的下載安裝更新。

• 維護方：微信小程序團隊（SkillHub 分類 dev-programming，來源 enterprise）
• 當前版本：0.3.2（包內 skill.yaml 與 SkillHub 頁面一致）
• SkillHub：https://www.skillhub.cn/skills/tencent-adm/wechatide-skill（API 入口：https://api.skillhub.cn/tencent-adm/wechatide-skill）
• 標籤：requires_api_key=false（Skill 本身不強制外部 API Key；業務側可能仍需微信開發者工具內的 CLI 訪問令牌，見下文）

Skill 包採用通用 SKILL.md 格式，根入口下再拆多個 scene（如 installer、initializer、compiler 等），由 Agent 按用戶意圖路由，而不是把整份工具表一次性塞給模型。

核心功能¶

以下能力均來自包內 SKILL.md、references/tool-index.md 與 scene 文檔，按工作流歸納。

1. 環境與安裝（installer）¶

• 檢查本機是否已安裝微信開發者工具、NW.js / Electron 版本是否滿足門檻、wechatide CLI 是否可用（check-installation.mjs）
• 按穩定版或 Nightly 渠道解析官方下載鏈接（resolve-download.mjs），引導安裝或更新
• 注意：日常業務會話不會默認跑安裝檢查；僅在 wechatide 命令不可用、用戶明確要求裝/更新，或出現明確版本兼容 blocker 時進入 installer

2. 登錄、開窗與項目上下文（initializer / project-manager）¶

• check_wechatide_status：登錄態、skill 與工具版本關係（versionRelation）、是否啓用 CLI 令牌（tokenRequired）
• login、打開/關閉項目窗口、查詢 AppID 列表
• 項目列表的導入、查詢、從列表移除（不刪磁盤文件）

3. 編譯與預覽上傳（compiler / previewer）¶

• 模擬器打開頁面、刷新、構建 npm、單文件 WXML/WXSS 編譯診斷
• 預覽（含 auto_preview 直推開發者微信）、生成預覽二維碼、上傳體驗版

4. 自動化與調試（automator / debugger）¶

• 模擬器內點擊、輸入、滾動、頁面導航與斷言、生成自動化腳本
• 讀取 console / network（grep 過濾）、截圖取證、mock 或調用 wx API、清理調試緩存

5. 雲開發（cloudbase-operator）¶

• 雲環境列表、雲函數部署與查詢、雲數據庫讀寫、雲存儲管理

6. 本地配置（project-config）¶

• 修改 project.config.json（基礎庫、域名校驗、編譯開關等），不經過 MCP，且不調用 wechatide 時可跳過運行前門禁

7. 地圖相關能力的外鏈¶

小程序地圖組件或騰訊位置服務 Web API 不在本包內處理，文檔指向 SkillHub 上的地圖相關外部 Skill（見 references/map-skill-index.md）。

統一調用形式（包內約定）：

wechatide -c <clientName> <toolName> [flags...] [--token <cliAccessToken>]

-c 的 <clientName> 須與開發者工具授權彈窗中的 client 一致（例如 Cursor、Claude）；工具名爲下劃線風格的位置參數，具體參數以 wechatide <toolName> -h 或 references/tool-index.md 爲準。

安裝與啓用¶

分兩層：Skill 包（給 Agent 讀的工作流）與 微信開發者工具 + wechatide CLI（本機執行面）。

1. 通過 SkillHub 安裝 Skill 包¶

SkillHub 頁面給出的安裝提示爲：按 SkillHub 安裝文檔 安裝 @tencent-adm/wechatide-skill。

若本機尚未安裝 SkillHub CLI，可先執行：

command -v skillhub && skillhub --version

未安裝時（文檔推薦完整安裝或僅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
# 或僅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。SkillHub 文檔中的常用路徑示例：

安裝命令示例（將目錄換成你當前環境對應路徑）：

skillhub install @tencent-adm/wechatide-skill --dir ~/.cursor/skills/

也可把官方提示詞交給編程 Agent，讓其按 skillhub.md 完成上述步驟。

2. 本機微信開發者工具與 wechatide¶

Skill 默認假設本機已可調用 wechatide。命令不存在時，Agent 應進入包內 installer scene，運行：

node skills/installer/scripts/check-installation.mjs

並按診斷結果下載、安裝或更新微信開發者工具。

3. 運行前門禁（Agent 側）¶

需要調用 wechatide 時，每個會話通常先做版本與登錄檢查（check_wechatide_status 不需要 --token）：

wechatide -c Cursor check_wechatide_status --skill-version 0.3.2

<skill-version> 須與已加載包內 skill.yaml 的 version 一致。若返回 loginExpired: true，先 login 再重查；若 tokenRequired: true，後續業務命令須帶用戶在「設置 → 安全」中配置的 CLI 訪問令牌 --token。

典型用法¶

下面示例可在本機已安裝微信開發者工具且 wechatide 可用時復現；路徑與 AppID 需換成你的項目。

1. 會話開始：狀態檢查

wechatide -c Cursor check_wechatide_status --skill-version 0.3.2

根據返回的 versionRelation、loginExpired、tokenRequired 決定是否登錄或補充 --token。

2. 導入項目到工具列表（不自動開窗）

wechatide -c Cursor project_import --project /絕對路徑/你的小程序目錄

3. 編譯並打開指定頁面

先按 Skill 路由打開項目窗口（initializer），再調用 compiler 類工具，例如：

wechatide -c Cursor simulator_open_page --project /絕對路徑/你的小程序目錄 --path pages/index/index

4. 預覽推送到開發者微信

wechatide -c Cursor auto_preview --project /絕對路徑/你的小程序目錄

5. 調試：過濾 console

wechatide -c Cursor get_simulator_console --project /絕對路徑/你的小程序目錄 --command "grep -i error"

涉及上傳、刪除、雲寫等操作時，工具可能返回 pending + taskId；除 login 外，多數場景需用戶在開發者工具內確認，Agent 應記錄 pendingTask 並在繼續前查詢，而不是直接重發同一操作（見包內 references/async-task-polling.md）。

用戶意圖與 scene 的對應關係以根 SKILL.md 路由表爲準，例如：只改 project.config.json → project-config；預覽/上傳 → previewer；雲函數部署 → cloudbase-operator。

適用場景與注意¶

適合誰

• 已用 Cursor、Claude Code、Codex 等支持 Skills 的 Agent，且主要做微信小程序或小遊戲
• 希望 Agent 不僅能改代碼，還能驅動開發者工具完成編譯、預覽、自動化點擊、日誌與網絡排查、體驗版上傳、雲開發運維

限制與注意

1. 雙依賴：僅安裝 Skill 包不夠，本機仍需兼容版本的微信開發者工具及可用的 wechatide CLI。
2. 授權兩層：-c <clientName> 與 CLI 訪問令牌是獨立校驗；啓用令牌後業務命令必須帶 --token。
3. 不要編造工具：工具名與參數以 references/tool-index.md、wechatide-tools/references/tools.yaml 及 wechatide <id> -h 爲準。
4. 異步任務：除登錄外，不要對需用戶確認的 taskId 盲目輪詢或重複提交。
5. SkillHub 數據：頁面展示的評分、下載量會變動；撰寫時 SkillHub 抓取爲評分 100000、下載 10753（以你打開頁面時的數據爲準）。

結尾¶

微信開發者工具 Skills 把小程序開發裏「可操作、可調試、可驗證」的環節收斂成 Agent 可執行的工作流與 wechatide 工具調用，減少 Agent 只改文件、人手工點工具的分工斷層。安裝 Skill 包後，仍須保證本機開發者工具與 CLI 就緒，並遵守包內的運行前門禁與異步任務規則。

官方 SkillHub 地址：https://www.skillhub.cn/skills/tencent-adm/wechatide-skill