我做了一个 AI First 的小程序自动化 CLI：miniprogram-minium-cli

# 我做了一个 AI First 的小程序自动化 CLI：miniprogram-minium-cli

最近我在做一类很具体的问题：如何让 AI Agent 真正接入小程序验收和自动化执行，而不是只停留在“会写测试思路”或者“能输出一段伪代码”。

很多时候，Agent 已经能把需求理解得七七八八，也能规划出操作步骤，但真正落地时，往往还缺一个足够稳定的执行层：

能接收结构化的执行计划
能连接微信开发者工具
能执行点击、输入、等待、断言、手势这些动作
能把结果以机器可读的形式产出来，方便下一轮继续交给 Agent 分析

所以我做了 miniprogram-minium-cli (opens new window)。

它不是一个“聊天式测试工具”，而是一个更偏基础设施的命令行产品：把 Agent 产出的 plan，变成真实可执行的小程序自动化流程。

# 1. 它是什么

一句话概括：

miniprogram-minium-cli 是一个面向 Agent 的小程序自动化执行层 CLI。

它基于 Minium (opens new window) 作为底层自动化引擎，主要做这几件事：

接收结构化 plan
校验 plan 是否符合约束
准备托管运行时
连接微信开发者工具
执行自动化步骤
输出结构化结果、对比结果和截图产物

它的产品定位非常明确：

它是执行层，不是规划层。

也就是说，我刻意没有把“自然语言理解”和“测试规划”硬塞进这个 CLI 里，而是把职责拆开：

Agent 负责生成 plan
CLI 负责校验和执行 plan
运行结果再反馈给 Agent 做下一轮分析

这样做的好处是，职责边界很清晰，CLI 会更稳定，也更容易被不同 Agent 体系复用。

# 2. 为什么说它是 AI First

我这里说的 AI First，不是“套一层 AI 壳”，而是从输入、执行到输出，整个链路都是围绕 Agent 协作来设计的。

# 2.1 输入不是自然语言，而是结构化 plan

这个工具的核心输入不是 prompt，而是结构化 JSON plan。

这意味着它更适合接在 Agent 后面，当作一个可靠执行器来使用，而不是让 CLI 自己去猜用户想做什么。

比如它支持两种输入方式：

--plan：执行磁盘上的计划文件
--plan-json：直接执行内联 JSON

其中 --plan-json 这个能力，对 Agent 特别友好。因为 Agent 可以在一轮推理里直接生成 plan，然后立即调用 CLI 执行，不需要中间再手工落文件。

# 2.2 输出不是一段日志，而是一组结构化产物

执行完成后，默认会在 .minium-cli/runs 下生成独立的运行目录，包含：

plan.json
summary.json
result.json
comparison.json
截图文件

这件事很关键。

因为对 Agent 来说，最有价值的并不是“终端里那几行文本”，而是这些可继续消费的结构化产物。它们可以直接进入下一轮分析，例如：

断言失败后自动定位失败步骤
对比预期与实际结果
结合截图做视觉回看
基于 summary.json 生成测试总结

# 2.3 内置了 skill 安装能力

除了执行 plan，这个包还内置了 skill 分发能力，可以直接把随包附带的 skill 安装到本地 agent skills 目录中：

miniprogram-minium-cli install --skills

也支持：

npx miniprogram-minium-cli install --skills

或者通过开放的 skills 生态从仓库安装：

npx skills add diaz-zeng/miniprogram-minium-cli --skill miniprogram-minium-cli

这意味着它不只是一个“命令工具”，也是一个能被 Agent 生态直接接入的执行能力包。

# 2.4 运行时管理尽量对用户无侵入

这个项目会按需准备并复用自己的私有 uv 托管 Python 运行时。

这背后的目标很直接：尽量不要让用户为了跑一个 CLI，再去手工维护一套全局 Python 环境。

也就是说，它会尽量做到：

不污染全局 Python
不改全局 pip
不改 PATH
不动 shell 配置

对于命令行工具来说，这类“无侵入运行时管理”其实非常重要。因为一旦要让 Agent 或团队成员大规模接入，安装和环境成本往往比功能本身更容易劝退人。

# 3. 当前已经支持什么

目前 miniprogram-minium-cli 已经覆盖了一套比较完整的小程序自动化执行面：

通过 --plan 执行文件计划
通过 --plan-json 执行内联 JSON 计划
精确定位与模糊文本匹配
点击、输入、等待与断言
显式截图与自动截图
单指与多指手势
结构化执行结果输出

如果再往下拆，它支持的步骤类型包括：

session.start
page.read
element.query
element.click
element.input
wait.for
assert.pagePath
assert.elementText
assert.elementVisible
gesture.touchStart
gesture.touchMove
gesture.touchTap
gesture.touchEnd
artifact.screenshot
session.close

这套设计的思路不是“什么都做”，而是先把 Agent 自动化最常见、最稳定、最容易结构化的动作面打实。

# 4. 一个典型工作流长什么样

我比较推荐的使用方式是下面这个链路：

Agent 先根据需求或页面状态生成 plan
用 miniprogram-minium-cli 校验并执行 plan
CLI 产出结构化结果和截图
Agent 再基于产物做分析、总结或下一轮修正

如果用命令来表达，大概是这样：

# 4.1 先预热运行时

miniprogram-minium-cli prepare-runtime

# 4.2 执行一个 plan 文件

miniprogram-minium-cli exec \
  --plan ./plans/login-check.json \
  --wechat-devtool-path /path/to/wechat-devtools-cli

# 4.3 或者直接执行 Agent 生成的内联 plan

miniprogram-minium-cli exec --plan-json '{
  "version": 1,
  "kind": "miniapp-test-plan",
  "metadata": { "draft": false, "name": "inline-demo" },
  "execution": { "mode": "serial", "failFast": true },
  "environment": {
    "projectPath": "./miniapp",
    "artifactsDir": null,
    "wechatDevtoolPath": null,
    "testPort": 9420,
    "language": "zh-CN",
    "runtimeMode": "placeholder",
    "autoScreenshot": "off"
  },
  "steps": [
    {
      "id": "step-1",
      "type": "session.start",
      "input": { "projectPath": "./miniapp" }
    },
    {
      "id": "step-2",
      "type": "session.close",
      "input": {}
    }
  ]
}' --json

如果你已经在做 Agent 驱动测试，这种调用方式其实会很顺手，因为它天然适合“生成即执行”的闭环。

# 5. 我最看重的几个设计点

# 5.1 把规划层和执行层分开

很多 AI 工具喜欢把所有东西塞进一个大而全的产品里，但我越来越觉得，Agent 时代更重要的是模块边界清晰。

miniprogram-minium-cli 不负责替你理解自然语言，也不负责假装自己是万能测试平台。它只做执行层该做的事：

校验计划
启动运行时
驱动小程序
生成产物

这种拆分方式的好处是：

更容易被不同 Agent 复用
更容易做稳定性治理
更容易做协议和产物约束

# 5.2 计划格式先约束，再执行

这个项目里对 plan 的 kind、version、execution.mode、steps、step.type 都有明确校验。

这件事看起来很“工程化”，但我认为它对 Agent 时代反而更重要。

因为 Agent 会生成内容，就意味着系统必须更早做约束，不能把所有问题都拖到运行时才暴露。越早校验，越容易把错误收束在协议层，而不是演化成一段难以排查的执行事故。

# 5.3 对结果做结构化沉淀，而不是只打印日志

终端日志当然有用，但它不够“可编排”。

如果希望 Agent 能继续基于执行结果工作，就必须产出稳定的数据结构。summary.json、result.json、comparison.json 和截图，其实就是为了让“执行”不成为链路终点，而是下一轮分析的输入。

# 5.4 skill 不是附属功能，而是产品的一部分

我自己越来越倾向于把 skill 视为 AI 工具产品的一等公民。

因为在 Agent 生态里，一个工具是否好接入，很多时候并不取决于它有没有官网，而取决于它有没有：

清晰的命令契约
稳定的输入输出
可安装的 skill
可引用的文档

从这个角度说，install --skills 并不是一个“顺手加的功能”，而是这个产品能够真正进入 Agent 工作流的关键一环。

# 6. 适合谁用

如果你符合下面几类场景，我觉得这个工具会比较有价值：

你在做微信小程序相关的自动化验收
你希望让 Agent 生成结构化执行计划，再交给命令行落地
你不想把“测试规划”和“测试执行”耦合在一个黑盒里
你希望保留截图、执行摘要和结构化结果，方便回放和分析
你正在构建自己的 Agent 工作流或技能体系

尤其是当你已经不满足于“AI 帮我写一段测试代码”，而是想让它进入可执行、可验证、可追踪的工程闭环时，这类执行层工具会比单纯的 prompt demo 更实用。

# 7. 当前边界和限制

这个项目也有意保留了一些边界。

比如目前它：

不是 MCP Server
不内置自然语言 planner
更强调结构化 plan 驱动，而不是自由聊天驱动

另外，针对仍然使用 touristappid 的项目，真实运行结果应视为受限验证，像 wx.showModal 这类依赖原生能力的流程，不适合把结果直接当成完整代表性结论。

我觉得把这些边界讲清楚，比“看起来什么都能做”更重要。因为只有知道它不做什么，大家才更容易把它放到正确的位置上。

# 8. 相关地址

GitHub：diaz-zeng/miniprogram-minium-cli (opens new window)
npm：miniprogram-minium-cli (opens new window)

如果你想快速试一下，可以先从下面两步开始：

npm install -g miniprogram-minium-cli
miniprogram-minium-cli prepare-runtime

# 9. 最后

我做这个工具，并不是想再造一个“大而全”的测试平台，而是想把 Agent 工作流里最容易缺失的一块补上：

让 AI 产出的结构化计划，能够真正进入稳定、可验证、可回放的执行闭环。

如果你也在做 AI Agent + 小程序自动化 相关的事情，欢迎直接去仓库看看，也欢迎提 issue 或交流使用场景。

#AI Agent #CLI #微信小程序 #Minium #自动化测试

上次更新: 2026/04/05, 14:52:23