微信开发者工具智能体控制
让智能体直接驱动微信开发者工具：改代码→编译→点页面→看日志→截图→上传发布，全链路不用人来回手动点。
核心前提（不满足就别往下走）
| 前提 | 检查方式 | 不满足的后果 |
|---|---|---|
| 开发者工具已安装 | scripts/preflight.py |
无法启动 |
| 服务端口已开启 | 设置 → 安全设置 → 服务端口 | 最常见的失败原因 |
| IDE 已登录 | scripts/preflight.py 返回 login: true |
CLI 命令报未登录 |
| Node.js ≥ 18 | node -v |
automator 依赖跑不起来 |
MCP weapp-dev 已信任 |
连接器管理页右上角 → 信任 | 智能体看不到工具 |
服务端口没开是最常见坑——表现是连接超时或 Connection refused，代码完全正确也连不上。
执行模式：先判断在哪跑
这是本skill 的第一个决策点，必须先判断，不要默认本地。
| 情况 | 模式 | 做法 |
|---|---|---|
| 本机装了开发者工具、代码在本地 | local | 直接走 MCP weapp-dev 工具 |
| 代码在远程服务器 / CI / 容器 | remote | 见下方「远程模式」 |
| 用户明确说"连服务器" | remote | 先确认服务器上有没有 GUI/开发者工具 |
远程模式的关键限制（必须提前告知用户）
微信开发者工具是桌面 GUI 应用，跑在无图形界面的 Linux 服务器上极其困难。可行路径只有两条：
- 服务器只做代码仓库，编译/预览/上传回到本地 IDE 做（推荐）
- Windows 服务器带桌面会话，通过 RDP 保持 GUI 会话存活，IDE 常驻，再走 SSH 隧道连本地端口
如果判断用户想"在服务器上直接跑 IDE"，先说明这个限制，再问走哪条路。不要闷头尝试。
常用工作流
1. 首次接入：先诊断再动手
python ~/.workbuddy/skills/weapp-dev/scripts/preflight.py
输出会告诉你：CLI 路径、端口、登录状态、项目是否找到、MCP 是否就位。先跑这个再做任何操作，能省掉大量无效尝试。
2. 编译 + 预览 + 真机扫码
# 编译并生成预览二维码（会输出二维码图片路径给用户扫）
python ~/.workbuddy/skills/weapp-dev/scripts/cli_wrap.py preview --project D:/path/to/proj
# 上传为开发版本
python ~/.workbuddy/skills/weapp-dev/scripts/cli_wrap.py upload --project D:/path/to/proj --version 1.0.0 --desc "修复登录页崩溃"
上传是不可逆的外部动作——会真的推到微信后台占一个版本号。执行前必须向用户确认版本号和备注文案。
3. 从代码仓库迭代
用户常把小程序放在 git 仓库里。流程：
- clone 或 pull 到本地工作区
- 确认
project.config.json里的appid与用户目标一致（不要盲改） - 用 IDE 打开项目
- 修改 → 编译 → 自动化验证 → 提交
appid 陷阱：project.config.json 里的 appid 决定了上传到哪个小程序。改错了会上传到别人的小程序或直接失败。永远先读出来跟用户确认。
4. 页面自动化（点/输/截图/日志）
连上 MCP 后的标准动作序列：
navigate_to→ 跳到目标页get_page_data→ 读当前页dataget_element→ 按 CSS 选择器拿元素文本/属性，或直接 tap- 截图 → 给用户看效果
- 读 console 日志 → 定位报错
调试技巧：读取 console 日志强依赖连接状态，中间不要断开重连，否则日志会丢。需要连贯输出时，一次把操作序列跑完再取日志。
远程模式操作手册
详见 references/remote-mode.md。要点：
- SSH 隧道把远端端口映射到本地
- 密钥路径、私钥权限 600
- 生产机封22 端口时走跳板
安全红线
- 上传/发布前必须确认，版本号与备注要用户点头
- 不读改
project.config.json的 appid，除非用户明确要求 - 不打印 AppSecret / privateKeyContent / upload key——只说"已配置"，不输出值
- 上传私钥（
private.wx.<appid>.key）属高敏感文件，不要外传、不要提交进git - 远程模式下的写操作先在测试 appid 上验证
排障速查
| 症状 | 根因 | 修法 |
|---|---|---|
| Connection refused | 服务端口没开 | 设置 → 安全设置 → 开服务端口 |
| islogin 返回 false | IDE 未登录 | CLI login 或扫码登录 |
| CLI 报端口不一致 | IDE 开着但端口不同 | quit 后用 --port 重启 |
| automator 连不上 | 项目未在 IDE 中打开 | 先 open --project |
| npm/npx 超时 | 环境注入了代理变量 | 清 HTTP_PROXY 等，或用绝对路径 node |
| Git Bash 传给原生程序路径出错 | MSYS 路径不识别 | cygpath -w 转换 |
⚠️ 高频坑：截图正常但页面 API 全挂
这是最容易误判为「代码写错了」的情况。
现象：screenshot() 秒回，但 page.data() / page.$() / tap() 全部超时或返回 null。
根因：AppService 层没 ready，渲染层却正常，所以画面看得到、就是点不动。
IDE 日志表现：routeTo appLaunch timeout。
⚠️ 重要更正（2026-10-09 实测）：appid 不是唯一根因。
| appid | currentPage() |
data() / $() / tap() |
|---|---|---|
touristappid |
超时 | 超时 |
| 真实 appid | ✅ 成功返回 pages/index/index |
❌ 仍超时 |
换成真实 appid 后页面句柄能拿到了（明显改善），但元素级交互仍不通。
所以 appid 是必要非充分条件。
已排除的因素（避免重复劳动）：
- 不是 wxss 渐变
- 不是
useIsolateContext/useMultiFrameRuntime/useApiHook/enhance
—— 逐个改 false +close/open重开后现象不变；连setting清成最小值也照旧 - 不是 IDE 未登录、不是项目没打开、不是端口问题
- 不是业务代码问题（页面渲染完整、数据正确，说明 JS 层逻辑是对的）
剩余待验证方向：
- 升级开发者工具 ——
routeTo appLaunch timeout在部分版本是已知问题 - 在 IDE 界面手动打开项目、确认模拟器正常显示后再连自动化
（CLI 开启的通道有时拿不到页面栈） - 检查 IDE 版本与基础库版本的组合
可用降级路径：截图 + CLI 的编译/预览/上传都正常可用，
只是拿不到元素级交互与页面数据。做视觉验收、生成预览码、发布上线不受影响。
诊断命令：
set NODE_PATH=C:/Users/Administrator/.workbuddy/mcp-servers/weapp-dev/node_modules
node diagnose.js ws://localhost:9420 D:/work/myproject
逐项体检连接/页面/数据/元素/截图/点击，每步带超时（automator 本身不会超时，
不套超时的话卡住就是永久挂起）。
automator API 的三个易错点
page.path是属性，不是方法 ——page.path()会报not a functionscreenshot()返回 base64 字符串，不是 Buffer —— 直接Buffer.from(x, 'binary')
会写出坏文件，必须Buffer.from(x, 'base64')。判断是否解码正确：
PNG magic 必须是89504e47miniprogram-automator按脚本所在目录解析 node_modules —— 不按 cwd，
脚本放在项目里跑时要设NODE_PATH，否则Cannot find module
端口会自动变（实测踩过）
IDE 崩溃重启后，服务端口不再是你配置的那个（实测 25773 → 42538）。
脚本已内置自动发现（问 CLI 实际在哪个端口），所以：
- 不用死记端口号，
preflight.py/cli_wrap.py会自己找 - 但 MCP 的
WEAPP_DEVTOOLS_PORT是写死的，端口变了要同步改 preflight.py会检测并提示不一致
其他
项目 appid 与 IDE 实际不一致时，IDE 可能已切项目。用 screenshot 交叉验证
（看标题栏/页面内容是否与目标项目一致）。
⚠️ IDE 起不来：wait IDE port timeout
现象：反复报 IDE may already started at port 25773, trying to connect
+ #initialize-error: wait IDE port timeout，且换端口无效（传 --port 25800
仍报 25773）。端口可能确实 LISTENING，但 CLI 连不上；IDE 进程反复重启，
WeappLog/logs 每十几秒生成一个新日志文件。
别再重试 CLI —— 反复 open 只会加剧进程堆积。正确处置：
- 杀干净：
taskkill //F //IM nw.exe、wechatdevtools.exe、微信开发者工具.exe - 让用户手动双击打开 IDE（GUI 崩溃弹窗只有人能看到）
- 用户手动打开后，再用 CLI 连（此时 CLI 只做客户端，不做启动器）
根因判断：
- 端口假性LISTENING 但进程反复重启 → 多为强杀进程破坏了插件状态
- 日志里伴随 getpluginlistV3 → system error / pluginsRecovered flag:false
→ 插件状态没恢复干净，需要 GUI 侧重启
- User Data/CrashpadMetrics-active.pma 持续更新 → IDE 确实在崩溃
教训：不要用 taskkill 强杀 IDE 的多进程树（当时一次杀了 9 个 nw.exe）。
优先用 CLI quit，实在不行再让用户手动关窗口。
Windows 上给原生程序传路径的坑：Git Bash 里python3 /c/Users/... 会被拼成 c:\c\Users\...。脚本里已用 cygpath 兼容处理，手写命令时注意。
参考文档
references/mcp-tools.md— MCP 工具清单与参数references/remote-mode.md— 远程服务器连接与部署references/cli-reference.md— CLI 命令完整参考references/repo-publish-sop.md— 从代码仓库到发布的完整 SOP（迭代闭环必读）
