前言¶
用 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 版本是否满足门槛、
wechatideCLI 是否可用（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 或调用
wxAPI、清理调试缓存
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 文档中的常用路径示例：
| Agent / 客户端 | Skills 目录 |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或项目下 .agents/skills/ |
安装命令示例（将目录换成你当前环境对应路径）：
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 不仅能改代码，还能驱动开发者工具完成编译、预览、自动化点击、日志与网络排查、体验版上传、云开发运维
限制与注意
- 双依赖：仅安装 Skill 包不够，本机仍需兼容版本的微信开发者工具及可用的
wechatideCLI。 - 授权两层：
-c <clientName>与 CLI 访问令牌是独立校验；启用令牌后业务命令必须带--token。 - 不要编造工具：工具名与参数以
references/tool-index.md、wechatide-tools/references/tools.yaml及wechatide <id> -h为准。 - 异步任务：除登录外，不要对需用户确认的
taskId盲目轮询或重复提交。 - SkillHub 数据：页面展示的评分、下载量会变动；撰写时 SkillHub 抓取为评分 100000、下载 10753（以你打开页面时的数据为准）。
结尾¶
微信开发者工具 Skills 把小程序开发里「可操作、可调试、可验证」的环节收敛成 Agent 可执行的工作流与 wechatide 工具调用，减少 Agent 只改文件、人手工点工具的分工断层。安装 Skill 包后，仍须保证本机开发者工具与 CLI 就绪，并遵守包内的运行前门禁与异步任务规则。
官方 SkillHub 地址：https://www.skillhub.cn/skills/tencent-adm/wechatide-skill
