小程序运行时调试助手_开发编程 skill-PHP中文网

小程序运行时调试助手

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

通过 vince-mp CLI 连接微信开发者工具，实时查看页面数据、控制台、点击路径和运行态问题，适合小程序现场调试。

Vince Mini 程序 CLI 支持

功能概述

Vince Mini 程序 CLI 支持是一项面向实际任务的技能，主要用于一条 WeChat Mini 程序通过系统 vince- mp JSON CLI 的实时运行时间( 已安装 npm 软件包, 而非一个销售二进制)；定义的工作流程是 sessio。

核心要点

它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；

结果检查与注意事项

涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

Vince 小程序 CLI 支持

通过 系统级 vince-mp JSON CLI（一个已安装的 npm 包，非 vendored 二进制）调试微信小程序的实时运行时。其核心工作流为 会话优先（session-first）：仅需连接一次，后续所有命令均复用该连接——重复命令近乎瞬时完成，且元素 uid 在多次独立 CLI 调用间保持有效。

能力边界

请使用本能力实现以下操作：连接或启动微信开发者工具会话；检查运行时状态（路由、pageStack、pageData、storage、systemInfo、console）；查询/快照元素后，通过 uid 执行 tap/input 操作（长按通过 step 实现）；截取单元素截图或全屏截图；驱动无摄像头的 scan；运行真实项目的 doctor（执行 tsc + .ts/.js 文件新鲜度检查 + 指定后端域名 + 局域网 IP 验证）；诊断“无法连接 / 模拟器启动失败”问题；切换后端环境并根据 requestId 拉取服务端错误日志；探测 Skyline Canvas/Camera 或模拟媒体行为。

切勿将其用于普通 Web 浏览器自动化、通用前端源码编辑、未结合 DevTools/运行时执行的小程序代码审查，或 Skyline→WebView 渲染器迁移（该场景应使用 mp-groundline）。

会话优先工作流（推荐做法）

vince-mp session start          # 连接一次：自动解析 miniprogramRoot + 确保自动化端口可用（仅当端口未就绪时才启动 `cli auto`），
                                #   然后建立连接。若 DevTools 未运行，可能自动打开/聚焦。
vince-mp doctor                 # 可选健康检查（项目结构 + tsc + .js 新鲜度 + 域名配置）
vince-mp data                   # 读取 pageData —— 瞬时返回（复用当前会话）
vince-mp query .submit-btn      # 生成 uid（例如 "button_0"）
vince-mp tap button_0           # 按 uid 执行操作 —— 此 uid 在本次独立调用中依然有效
vince-mp data                   # 确认操作效果
vince-mp scan PKG-2026-0605     # 无摄像头扫描：触发 onScanCode 事件，携带 {type:"scancode",detail:{result,scanType,type}} 数据
vince-mp console                # 返回自会话启动以来缓存的 console 日志
vince-mp session stop           # 使用完毕后关闭会话（或等待空闲自动回收）

任何其处理器涉及异步操作的触发器（tap/input/scan/step）均在 DevTools 分发（DISPATCHES）调用时即刻解析，而非等到异步任务（如 wx.request→setData）完成后再解析 —— 因此，在读取效果（无论是 data、networkList 还是 mediaList）前，请务必使用 wait 或轮询机制。

每个命令均输出 JSON，并接受 --workspace-root

和 --port 参数（默认端口为 9420；--port 仅在为工作区首次创建新会话时用于指定自动化端口）。会话以 workspace-root 为键进行区分，而非以端口区分 —— 若需同时调试两个项目，请分别为其指定独立的 --workspace-root；仅使用 --port 将复用已有活跃会话，而不会切换目标。

命令映射表（请加载 `references/cli-contract.md` 查看精确 Schema）

完整命令集 —— 包含会话生命周期管理、读/操作/诊断/一次性快捷命令、概览式分组映射、精确步骤列表及错误码定义 —— 均位于 references/cli-contract.md 中。在构建或执行任意 vince-mp 命令前，请务必先加载该文件（其中“概览式命令映射”章节为分组索引；其后的各节则为精确 Schema 定义）。

核心规则

仅使用系统级 vince-mp 命令作为后端入口。
优先采用 会话模式；仅在明确需要一次性操作或显式连接时，才使用 --no-session 或 run --connect。通过 launch 显式打开/聚焦 DevTools（超出 session start 对端口的保障范围）属于 需人工授权 的副作用 —— 必须获得用户明确授权后方可执行。
路径应限定于 cwd/--workspace-root 下；文件输出必须显式指定 --output 或路径参数。
切勿执行导航、reLaunch、媒体/网络埋点或 API 模拟，除非这些副作用已在请求中被明确声明。session start 对自动化端口的保障（以及可能的 DevTools 启动）是唯一预期的连接时副作用。
每次操作均须通过 CLI 返回的 JSON 证据验证；对失败错误码须原样上报（例如 APP_NOT_RUNNING、AUTOMATION_PORT_TIMEOUT、STALE_OR_UNKNOWN_UID）。

文档加载协议

首先阅读本文件。
在运行 vince-mp 或构建工作流 JSON 前，请加载 rules/runtime-protocol.md。
如需查看命令/步骤/错误码的精确 Schema，请加载 references/cli-contract.md。
如需了解 uid 交互或单元素截图相关流程，请加载 rules/ui-element-workflow.md。
如需了解 Skyline Canvas/Camera/媒体相关内容，请加载 references/skyline-media.md。
如需了解连接/会话/快照/console/网络等边缘情况与故障处理，请加载 references/evidence-and-failures.md。

模块说明

rules/runtime-protocol.md —— 会话优先执行协议 + 强制安全规则；运行 CLI 前必读。
rules/ui-element-workflow.md —— uid 与 elementScreenshot 工作流；uid 在会话内持续有效，仅在导航或 DOM 变更后失效。
references/cli-contract.md —— 精确命令集、会话操作、快捷命令、连接/工作流 JSON、步骤列表、错误码定义。
references/skyline-media.md —— Skyline 快照协议 + Canvas/Camera/媒体埋点与模拟方案。
references/evidence-and-failures.md —— 连接/会话边缘情况、uid 生命周期、console/network 注意事项、失败错误码定义。

技能验证方式

node scripts/validate-skill.mjs —— 结构化校验（文件完整性、frontmatter、vince-mp help --json 输出）。
node scripts/run_all.mjs —— 确定性契约校验：对文档中记载的每条命令 / 快捷方式 / 工作流步骤 / 错误码 / 版本约束，均与实际运行的 vince-mp capabilities --json 输出进行比对，确保文档与 CLI 行为严格同步，杜绝静默漂移。--self-test 可验证每一项校验具备区分能力。
node scripts/check_release_gate.mjs —— 发布门禁校验：仅当获得真实执行证据时才放行（逐条执行所引用命令并校验退出码；要求 harness 自测仍能通过）。
node scripts/check_battery_clean.mjs —— 第三阶段对抗性加固门禁：读取缺陷台账（.loop/mp-cli-sup-battery.json），断言存在连续 N 轮干净运行（满足指定轮次形态与绿色回归要求，由 --consecutive N 控制）。若台账缺失或干净轮次不足，则判定为 RED（失败）。