dsh-mp-automator
微信小程序自动化测试 · DeepSeek Harness (dsh) 插件
WeChat Mini Program automated testing for dsh agents
让 dsh 智能体驱动微信开发者工具里真实运行的小程序：读页面、点元素、截图、看控制台。
你只需要在小程序项目目录里开一个 dsh 会话，然后用自然语言下测试任务：
> 你：测试首页的"立刻开始"按钮能进入扫码页
> agent：(mp_query 确认按钮可见 → mp_act 点击 → 验证路由已跳转 → mp_console 确认无报错)
> ✅ 按钮可见、可点、路由跳转正确、无控制台错误
Eight mp_* tools let a dsh agent drive a real Mini Program in WeChat DevTools.
The correctness discipline is built into the tools — not into prompts the
model may ignore.
目录 · Contents
- 工作原理 · How it works
- 快速开始 · Quick start
- 八个工具 · The eight tools
- 为什么可信：三种静默失败与对应的门 · Why trust it
- 截图：双路径与图片经济 · Screenshots
- 配置 · Configuration
- 配套技能 · Companion skill
- 排障 · Troubleshooting
- 设计笔记 · Design notes
1. 工作原理 · How it works
dsh agent（任意模型；视觉能力可选）
│
│ 调用 mp_* 工具 —— 纪律层：新鲜度门、选择器寻址、字节预算、图片经济
▼
dsh-mp-automator（本插件）
│
│ 驱动 vince-mp CLI —— 全 JSON 契约，首次调用协商版本 >=0.2.0 <0.3.0
▼
微信开发者工具 自动化端口
▼
你的小程序（真实运行时、真实 WXML）
分层职责 · Layering：vince-mp-cli
拥有自动化事实（DevTools 连接、元素解析、路径策略）；本插件拥有面向智能体的纪律
（什么时候拒绝执行、输出多少字节、图片何时该进上下文）。The CLI owns automation
truth; this plugin owns agent-facing discipline.
2. 快速开始 · Quick start
前置 · Prerequisites：macOS ·
微信开发者工具
（在 设置 → 安全设置 里开启服务端口）· Node ≥ 20 · dsh ≥ 0.1.0-rc.5
# ① 安装本插件驱动的自动化 CLI（拥有 DevTools 连接）
npm i -g vince-mp-cli
# ② 把插件装进你的 dsh profile
dsh plugin --profile web add dsh-mp-automator
# ③ 在小程序项目目录里（有 project.config.json 的那层）开 dsh 会话
cd your-miniprogram-project && dsh
④ 直接下测试任务。其余 mp_ 工具会自动起会话；模型不需要任何前置仪式。
Open the session inside the Mini Program project* — tools resolve the
project from the session's working directory — then just describe the test.
3. 八个工具 · The eight tools
| 工具 | 作用 · What it does |
|---|---|
mp_session |
start / status / stop / restart / reconnect 持久 DevTools 会话（其余工具自动起会话，主要用 restart 自救） |
mp_doctor |
项目体检：DevTools cli、tsc --noEmit、编译产物新鲜度 —— 结果喂给新鲜度门 |
mp_inspect |
page / stack / data(+path) / sysinfo / snapshot（元素事实表） |
mp_query |
选择器 → 几何事实表：fully-visible / partial / offscreen / read-failed 标志 + 遮挡候选对，相对当前滚动窗口判定（披露 scrollTop=） |
mp_act |
按选择器执行 tap / input / longpress · 导航 nav / switchTab / reLaunch · 免摄像头 scan 注入 |
mp_screenshot |
PNG 落盘 captures/ + 几何事实表；视觉路由额外附真图；`` 永远写明发生了哪种（见 §5） |
mp_console |
报错优先，然后是最新的日志（自动翻到缓冲区尾部） |
mp_eval |
逃生舱：在页面 appservice VM 里执行 JS —— 受新鲜度门管，配置可一键关闭 |
所有结果自带字节上限且自包含——长测试会话经历上下文压缩后依然可读，不会烂成
"见上文"。Every result is byte-clamped and self-contained, so long sessions
survive context compaction.
4. 为什么可信：三种静默失败与对应的门 · Why trust it
用 LLM 测小程序会以三种安静的方式失败——每种都产出毫无意义的绿色结果。
本插件对每一种都有结构性回答，而不是提示词层面的叮嘱：
| 静默失败 · Silent failure | 结构性回答 · Structural answer |
|---|---|
| uid 过期：DevTools 自动化层在重连/导航/快照/第二客户端接入时无声重编号元素 uid，重放旧 uid 会点到错误元素且不报错 | 选择器寻址 —— mp_act 在同一次独占调用内重新解析元素；uid 永不跨调用存活。Selector-addressed actions: no uid ever crosses a call boundary |
构建过期：编译出的 .js 比 .ts 源码旧，所有断言跑在没人打算发布的代码上 |
新鲜度门（G1） —— 每次执行前跑真实的快速体检（实测 0.10–0.18s，无缓存窗口），产物过期直接拒绝；纯 JS 项目无从判断时如实警告而不是假装通过 |
| 看不见的截图：纯文本模型"截"了一张自己永远看不见的图，然后凭想象描述它 | 双路径 —— 每张截图都产出几何事实表（任何模型可用）；视觉路由额外附真 PNG；`` 一行永远写明到底发生了哪种，模型无法假装看过图 |
失败时的输出也是纪律的一部分：每个 CLI 错误码都映射到下一步该做什么
（见 §8 排障），解析一律 fail-closed——只有严格的
ok === true 算成功。Failure output is part of the contract: every CLI error
code maps to a remedy, and parsing fails closed.
5. 截图：双路径与图片经济 · Screenshots
双路径 · Dual path — 每次 mp_screenshot：
- 任何模型都拿到：PNG 落盘 + 几何事实表（元素、坐标、可见性标志）。
纯文本路由（如 DeepSeek V4）额外得到一行明示："图在磁盘、不在你的上下文"。 - 视觉路由（provider 声明了
input: [text, image]，模板见
docs/PROVIDER-TEMPLATE.yaml）额外把真实
PNG 作为 image block 附进上下文——已用 kimi-k2.7-code 实测从像素读出按钮文字
与页面文案（证据）。
图片经济 · Image economy（0.3.0）— 视觉路由上每张附加的图片会在之后的每次
请求上持续计费，所以附加是被预算管理的：
imageBudget（默认 3）：每个会话最多附加 3 张——预算按会话对象隔离，
多个会话共享插件实例也互不泄漏- sha256 去重：画面没变就不重复附加（免费，披露为"deliberate economy"）
- 预算耗尽是诚实的：超预算后照常给几何事实表 + 计费原因说明，绝不静默跳过
- 实测全链路：attach → dedupe → attach → attach → exhausted，API 请求里恰好
3 个 image block
已实测的边界 · A proven boundary：wx.showLoading / toast 这类原生浮层不进
DevTools 截图（浮层前后 PNG 字节级相同）——不要用截图断言 toast 出现过，
配套技能会教模型这条。
6. 配置 · Configuration
# 你的 profile 的 cordis.patch.yml 里
- id: mp-automator
config:
freshnessMode: block # block(默认) | warn | off —— 新鲜度门行为
enableEval: true # mp_eval 逃生舱开关
imageBudget: 3 # 每会话最多附加的截图数（视觉路由）；0 = 完全禁用附图
screenshotDir: captures # 截图落盘目录（项目内相对路径）
binPath: vince-mp # CLI 不在 PATH 上时给绝对路径
| 键 | 默认 | 说明 |
|---|---|---|
freshnessMode |
block |
block 产物过期拒绝执行；warn 只警告；off 完全关闭（不跑体检进程） |
enableEval |
true |
关掉后 mp_eval 拒绝一切调用 |
imageBudget |
3 |
钳制为非负整数；0 显式禁用附图 |
screenshotDir |
captures |
始终被约束在项目目录内 |
binPath |
vince-mp |
版本窗口 >=0.2.0 <0.3.0，窗口外拒绝并给升级指引 |
7. 配套技能 · Companion skill
skill/mp-testing/SKILL.md 是判断力层：
inspect→act→verify 三拍节奏、选择器纪律、断言配方（fully-visible 才算可见、
partial 不算）、截图经济纪律、诚实的 mp_eval 边界。装进 dsh 读取的任意
skill 根即可——没有它工具照常能用，但测试的质量来自打法。
Tools carry capability and gates; the skill carries judgment.
8. 排障 · Troubleshooting
工具的错误输出自带 remedy 行，下面是最常见的几条 · Most-seen failures and
their built-in remedies:
| 错误码 | 含义 → 该做什么 |
|---|---|
AUTOMATION_PORT_TIMEOUT |
自动化端口没开 → 开发者工具 设置→安全设置 开启服务端口，然后 mp_session restart |
APP_NOT_RUNNING |
小程序没在模拟器里跑 → 先看 DevTools 控制台有没有编译错误，不要盲目重试 |
STEP_TIMEOUT |
单步超时 → mp_session restart；若只有截图反复超时，是 DevTools 渲染进程卡死（实测存在）→ 退出重启开发者工具本体 |
NOT_INSTALLED |
缺 CLI → npm i -g vince-mp-cli |
NO_PROJECT_CWD / INVALID_PROJECT |
会话不在小程序项目目录里 → 到有 project.config.json 的目录重开会话 |
门拒绝：stale |
编译产物比源码旧 → 重新编译（或等 DevTools 编译完）再测；不要为了绿而把门关掉 |
9. 设计笔记 · Design notes
本插件经对抗性迭代产出：五透镜攻击电池（外加跨厂商 DeepSeek 攻击手）击穿第一版
设计（9 个 P1、四个根因），重铸后的版本用结构性设计消灭根因；每个版本发布前由
独立审查 + fix-audit 双重把关。完整台账、红→绿测试证据与四路由真机测试矩阵见
docs/（未打进 npm 包）。Built by adversarial iteration; the full
ledger and live-test matrix live in the repo.
四个结构性决策 · Four structural decisions:
- 不镜像共享状态，改寻址模型 —— uid 表归 daemon 所有且会不可见地重编号，
插件侧任何计数器都必输；所以让选择器成为唯一句柄。 - 处处 fail closed —— 只有严格
ok === true算成功；缺失的体检文档导致
拒绝，而不是假定通过。 - stderr 是契约的另一半 —— CLI 把抛出的错误打到 stderr，两条流都要解析。
- 预算写进代码 —— 字节上限、行数上限、图片预算全部是代码里的钳制 +
显式披露，不是文档里的承诺。
状态归属准则（0.3.0 审查沉淀）：项目属性按项目键控（新鲜度、类型检查），
上下文属性按会话键控（图片预算）——键选错一个维度，正确的缓存就变成跨会话
的谎言。State keyed by what it is a property OF: the project, or the session.
License
MIT © Vincent Jiang
