VincentJiang06/dsh-mp-automator

dsh-mp-automator

微信小程序自动化测试 · DeepSeek Harness (dsh) 插件
WeChat Mini Program automated testing for dsh agents

npm
license
tests

让 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

1. 工作原理 · How it works
2. 快速开始 · Quick start
3. 八个工具 · The eight tools
4. 为什么可信：三种静默失败与对应的门 · Why trust it
5. 截图：双路径与图片经济 · Screenshots
6. 配置 · Configuration
7. 配套技能 · Companion skill
8. 排障 · Troubleshooting
9. 设计笔记 · Design notes

1. 工作原理 · How it works

dsh agent（任意模型；视觉能力可选）
│
│  调用 mp_ 工具 —— 纪律层：新鲜度门、选择器寻址、字节预算、图片经济
▼
dsh-mp-automator（本插件）
│
│  驱动 vince-mp CLI —— 全 JSON 契约，首次调用协商版本 >=0.2.0  永远写明发生了哪种（见 §5）|
| mp_console | 报错优先，然后是最新的日志（自动翻到缓冲区尾部）|
| mp_eval | 逃生舱：在页面 appservice VM 里执行 JS —— 受新鲜度门管，配置可一键关闭 |

所有结果自带字节上限且自包含——长测试会话经历上下文压缩后依然可读，不会烂成
“见上文”。每个结果都受字节钳制且自包含，因此长会话
能在上下文压缩后存活。

4. 为什么可信：三种静默失败与对应的门 · Why trust it

用 LLM 测小程序会以三种安静的方式失败——每种都产出毫无意义的绿色结果。
本插件对每一种都有结构性回答，而不是提示词层面的叮嘱：

| 静默失败 · Silent failure | 结构性回答 · Structural answer |
|---|---|
| uid 过期：DevTools 自动化层在重连/导航/快照/第二客户端接入时无声重编号元素 uid，重放旧 uid 会点到错误元素且不报错 | 选择器寻址 —— mp_act 在同一次独占调用内重新解析元素；uid 永不跨调用存活。选择器寻址动作：没有 uid 会跨越调用边界 |
| 构建过期：编译出的 .js 比 .ts 源码旧，所有断言跑在没人打算发布的代码上 | 新鲜度门（G1） —— 每次执行前跑真实的快速体检（实测 0.10–0.18s，无缓存窗口），产物过期直接拒绝；纯 JS 项目无从判断时如实警告而不是假装通过 |
| 看不见的截图：纯文本模型“截”了一张自己永远看不见的图，然后凭想象描述它 | 双路径 —— 每张截图都产出几何事实表（任何模型可用）；视觉路由额外附真 PNG； 一行永远写明到底发生了哪种，模型无法假装看过图 |

失败时的输出也是纪律的一部分：每个 CLI 错误码都映射到下一步该做什么
（见 §8 排障），解析一律 fail-closed——只有严格的
ok === true 算成功。失败输出也是契约的一部分：每个 CLI 错误
码都映射到补救措施，且解析失败即关闭。

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
yaml
你的 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 根即可——没有它工具照常能用，但测试的质量来自打法。
工具承载能力与门禁；技能承载判断力。

8. 排障 · Troubleshooting

工具的错误输出自带 remedy 行，下面是最常见的几条 · 最常见的失败及其
内置补救措施：

| 错误码 | 含义 → 该做什么 |
|---|---|
| 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 包）。由对抗性迭代构建；完整台账与真机测试矩阵存于仓库中。

四个结构性决策 · 四个结构性决策：

1. 不镜像共享状态，改寻址模型 —— uid 表归 daemon 所有且会不可见地重编号，
插件侧任何计数器都必输；所以让选择器成为唯一句柄。
2. 处处 fail closed —— 只有严格 ok === true 算成功；缺失的体检文档导致
拒绝，而不是假定通过。
3. stderr 是契约的另一半 —— CLI 把抛出的错误打到 stderr，两条流都要解析。
4. 预算写进代码 —— 字节上限、行数上限、图片预算全部是代码里的钳制 +
显式披露，不是文档里的承诺。

状态归属准则（0.3.0 审查沉淀）：项目属性按项目键控（新鲜度、类型检查），
上下文属性按会话键控（图片预算）——键选错一个维度，正确的缓存就变成跨会话
的谎言。状态按其所属对象键控：项目，或会话。

License

MIT © Vincent Jiang