jsonlee12138 wechatide-skill
用途
这是面向 微信开发者工具 工作流的根入口。
以下任务应优先使用这个 skill：
- 执行页面自动化、验证和截图
- 排查运行时、页面或日志问题
- 处理云环境、云函数相关动作
- 执行预览、上传、登录等 微信开发者工具 操作
以下任务不应使用这个 skill：
- 通用编码辅助
- 与小程序无关的桌面自动化
- 普通脚本执行或任意命令调用
Skill 安装
在 AI agent 中安装 微信开发者工具 skill 前，先获取当前 微信开发者工具 内置 skill 目录与版本号：
wechatide
或显式执行：
wechatide help
运行前检查（必须）
在进入任何 scene 或直接调用工具前，必须确认环境就绪且用户已登录（游客不可继续）。
第一步：检查 微信开发者工具 状态
wechatide -c <clientName> -t check_wechatide_status --skill-version <skillVersionFromSkillYaml>
其中 <skillVersionFromSkillYaml> 不是固定字符串；调用前应读取当前调用侧 agent 加载的 wechatide-skill/skill.yaml，取该文件顶层 version 字段的值填入。
check_wechatide_status 通过 skill-cli 调用时，如果 微信开发者工具 MCP 服务未启动或当前 client 尚未授权，CLI 会使用同一个 <clientName> 自动执行一次等价的 wechatide auth -c <clientName>，授权完成后重试本次状态检查。授权弹窗仍需用户确认。
根据返回结果处理：
| 返回情况 | 处理 |
|---|---|
返回内容中有 openid |
环境就绪，继续后续操作 |
command not found |
微信开发者工具 CLI 未安装或不在 PATH 中 |
CONNECT_ERROR / AUTH_* |
自动授权或连接重试失败，按错误信息处理；必要时手动执行下方 auth 命令 |
无 openid |
未登录，需要触发扫码登录（见下方） |
skillPath |
当前微信开发者工具内置的 skill 的路径，当内置 skill 版本与本地 agent 使用版本不一致时，根据此路径更新 skill；然后需要重新执行 check_wechatide_status |
注意：check_wechatide_status 只需在会话开始时调用一次。确认返回内容中有 openid 且无 warning 后，后续操作中不要重复调用，直接使用其他工具即可。
Skill 版本检查
check_wechatide_status 会返回当前运行 微信开发者工具 内置的 skill 版本号 skillVersion。入参 version 应填写当前调用侧 agent 加载的 wechatide-skill/skill.yaml 文件中的顶层 version 字段值，工具会对比两者；不要硬编码示例版本。版本不一致时返回中会包含 warning，应按提示中的工具内置 skill 路径安装更新 skill。未传 version 时只检查 微信开发者工具 状态和登录态，不返回版本对比提醒。
微信开发者工具 未启动时
通常无需手动执行；check_wechatide_status 连接失败时会自动用当前 <clientName> 执行一次。需要手动重试时，通过 skill-cli auth 启动工具并授权 CLI 连接：
wechatide auth -c <clientName>
等待工具启动并完成授权后，重新执行第一步。
未登录时
触发扫码登录：
wechatide -c <clientName> -t login
等待用户扫码完成后，再次调用 check_wechatide_status 确认返回内容中有 openid。未确认登录前不得执行其他工具。
调用方式
所有工具统一通过全局命令调用：
wechatide -c <clientName> -t <toolName> [flags...]
wechatide是全局命令，无需知道安装路径-c：当前 agent 简称（如CodeBuddy、Claude）-t：工具名（如open_project_window、cloud_env_list）- 工具参数由
tools.yaml的inputSchema决定，使用--field value形式传递 - 查看某工具全部参数：
wechatide -c <clientName> -t <toolName> --help - 本地文件系统路径字段直接传本机绝对路径；Windows 可传
C:/...，CLI 会转成系统原生路径 object/array类型字段可直接传 JSON：--<field> '{"a":1}'；也可用可选的--<field>-file path.json。二者必填字段只需提供其中一个，不能同时传
首次连接时 微信开发者工具 会弹窗确认授权，授权后该 clientName 后续连接自动通过。
常见调用示例
wechatide -c CodeBuddy -t open_project_window --project <project>
wechatide -c CodeBuddy -t automation_runtime_info --project <project> --action currentPage
wechatide -c CodeBuddy -t check_wechatide_status --skill-version <skillVersionFromSkillYaml>
wechatide -c CodeBuddy -t simulator_open_page --project <project> --page pages/index/index --query id=1
wechatide -c CodeBuddy -t cloud_env_list --project <project>
wechatide -c CodeBuddy -t debug_clear_cache --project <project> --action cleanAll
使用提醒
- 不要猜测或自行编造工具名，调用前必须先确认工具存在（见
wechatide-tools/references/tools.yaml） - 工具名使用下划线分隔（如
open_project_window、automation_viewport_action），不要用点号或驼峰 - 截图通过
automation_viewport_action实现，必须传waitForSelector或waitSeconds之一；优先使用waitForSelector等页面元素出现后再截图 - 预览相关动作如果需要产出二维码或信息文件，应显式提供本地输出路径
路由规则
确认环境就绪后，按任务意图路由：
注意：调用工具前请仔细阅读工具的传参规则，再进行调用，不要编造参数结构
- 页面自动化、交互、断言：
skills/automator/SKILL.md - 运行时排查、日志分析、状态诊断、模拟器状态：
skills/debugger/SKILL.md - 云环境、云函数：
skills/cloudbase-operator/SKILL.md - 编译、构建 npm、编译条件：
skills/compiler/SKILL.md - 预览、真机预览、上传代码包：
skills/previewer/SKILL.md（涉及预览优先使用auto_preview，直接推送到手机） - 微信开发者工具项目列表查询、导入、从列表删除：
skills/project-manager/SKILL.md - 读写/修改项目配置
project.config.json（本地设置、编译开关等，不调 MCP tool）：skills/project-config/SKILL.md - 小程序地图组件、定位、腾讯位置服务 Web 接口：
references/map-skill-index.md（本 skill 不处理，指向对应外部 skill）
当路由有歧义时，优先按「快速判断」中的分类选择。
快速判断
如果只想快速判断该进哪个，可以直接按下面理解：
- 先接管项目、确认登录、读取 AppID 或运行时上下文：
initializer - 需要点击、输入、滚动、截图、断言页面结果：
automator - 需要看 console、network、运行态或模拟器异常：
debugger - 需要编译页面、编译文件、构建 npm、刷新模拟器：
compiler - 需要生成预览码、真机预览、上传代码：
previewer - 需要查询云环境或操作云函数：
cloudbase-operator - 只需管理微信开发者工具项目列表、暂不打开项目窗口：
project-manager - 需要改项目本地设置 /
project.config.json（域名校验、热重载、编译压缩等）：project-config（直接改文件）
选择原则：
- 先按用户当前最主要的目标路由，不要因为顺手能调别的工具就跨 scene 混用
- scene 内如果只需要一两个原子工具，也仍然优先保留 scene 的判断边界
- 如果用户的话术同时覆盖多个目标，先完成 blocker scene，再移交到下一个 scene
标准工作流
- 确认
wechatide命令可用。 - 检查连接、登录态和 skill 版本（必须确认返回内容中有
openid，且skillVersion未落后才继续）。 - 识别项目与任务目标。
- 若仅需管理微信开发者工具项目列表（查询/导入/从列表删除），使用
project-manager；若要编译或调试，再使用initializer打开项目窗口。 - 如果需要打开项目窗口（
open_project_window）：必须先读取项目的project.config.json，确认appid有效后才能调用。 缺失时走open-project-window-guide.md补全流程。 - 选择合适的 scene skill。
- 通过
wechatide执行原子工具。 - 输出结构化结论与下一步建议。
交互处理
如果工具执行过程中出现 DevTools、系统弹窗或用户扫码等交互要求，应停在当前步骤，原样说明当前状态，并等待用户完成交互后再继续。不要在根入口维护具体动作分类清单。
执行约定
- 使用此 skill 时，原子执行入口只有
wechatide - 当执行失败时，不要自行吞掉、改写或继续猜测修复路径，应把错误原样抛给用户，由用户决策下一步
参考资料
- 打开项目前置检查：
wechatide-tools/references/open-project-window-guide.md - 创建小程序项目流程：
wechatide-tools/references/create-project-guide.md - 工具注册表：
wechatide-tools/references/tools.yaml - 交互处理：
references/approval-policy.md - 地图相关外部 skill 索引：
references/map-skill-index.md - 安全边界：
SECURITY.md