如何让 AI 真正使用 miniprogram-minium-cli

# 如何让 AI 真正使用 miniprogram-minium-cli

miniprogram-minium-cli 这个项目从一开始就不是写给“人手点命令”用的。

更准确地说，它是一个给 AI Agent 准备的小程序自动化执行层。它的职责很克制，也很明确：

Agent 负责理解任务和生成 plan
CLI 负责校验 plan、执行 plan、产出结构化结果
Agent 再基于结果继续分析、修正和迭代

所以如果要介绍这个项目，我觉得最值得写的并不是“人怎么上手”，而是：

怎样让 AI 真正把它用起来。

这篇文章就只回答这个问题。

# 1. 先理解它在 Agent 工作流里的位置

一句话概括：

miniprogram-minium-cli 是一个面向 Agent 的小程序自动化执行器，不是 planner，也不是聊天机器人。

它基于 Minium (opens new window) 作为底层自动化引擎，负责的事情主要有：

接收结构化 plan
校验 plan 格式和步骤是否合法
准备托管运行时
连接微信开发者工具
执行点击、输入、等待、断言、手势等动作
产出 summary.json、result.json、comparison.json 和截图

这件事非常重要，因为它决定了 Agent 应该如何接入它：

不要把它当成自然语言入口
不要让它自己理解“帮我测一下登录”
不要往里面塞未定义的 shell 步骤或自创动作

正确姿势是：

Agent 先把目标翻译成结构化 plan
再调用 miniprogram-minium-cli exec
再读取结构化产物继续推理

如果用架构图表示，大概是这样：

# 2. Agent 接入时，最重要的不是命令，而是边界

我觉得这个项目最容易被误用的地方，就是很多人会下意识把它想成“一个会跑小程序的 AI 工具”。

但它其实不是。

它是一个严格受协议约束的执行层，所以 Agent 在调用前，必须先接受几个边界：

# 2.1 它吃的是结构化 plan，不是自然语言

CLI 支持两种输入方式：

--plan <file>
--plan-json <json>

对 Agent 来说，--plan-json 往往更自然，因为它可以在一轮推理里直接生成 JSON 然后立刻执行。

# 2.2 它不是 planner

它不会替你拆测试思路，不会自动把一句自然语言变成动作序列，也不会帮你发散探索页面。

Agent 必须自己负责这些上游工作：

明确当前目标
决定要验证什么
生成满足协议约束的 plan

# 2.3 它只接受支持的步骤类型

当前支持的 step type 有这些：

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 生成了自创步骤，比如：

shell.exec
page.scroll
assert.network
llm.reflect

这种 plan 就不应该被当成可执行 plan。

# 3. 一个 Agent 应该怎样使用它

如果让我给 Agent 设计一条标准工作流，我会建议按下面这个顺序来。

# 3.1 第一步：先安装 skill，而不是只记命令

这个包本身就带有 skill，目的就是让 Agent 更稳定地理解它的能力边界。

可以直接安装：

miniprogram-minium-cli install --skills

也可以通过 npx：

npx miniprogram-minium-cli install --skills

如果 Agent 生态支持开放的 skills 工具，也可以直接从仓库安装：

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

这一层很重要，因为 skill 不只是“文档快捷方式”，它本质上是在告诉 Agent：

这个工具的职责是什么
哪些命令是官方支持的
哪些 plan 字段可以用
哪些运行产物值得优先读取

# 3.2 第二步：从示例 plan 出发，而不是空想协议

Agent 最稳妥的起点不是凭空造 JSON，而是从仓库里的示例 plan 出发。

例如：

examples/placeholder-login.plan.json
examples/demo-regression/*.plan.json

这样做的好处很直接：

可以复用已验证过的字段结构
可以少犯路径解析错误
可以避免生成不被支持的步骤类型

对于 Agent 来说，“先从 canonical example 改起”几乎总是比“从空白 JSON 开始写”更稳。

# 3.3 第三步：生成 plan 时严格遵守顶层约束

一个可执行 plan 至少要满足这些条件：

{
  "version": 1,
  "kind": "miniapp-test-plan",
  "metadata": {
    "name": "login-check",
    "draft": false
  },
  "environment": {
    "projectPath": "./miniapp",
    "artifactsDir": null,
    "wechatDevtoolPath": null,
    "testPort": 9420,
    "language": "zh-CN",
    "runtimeMode": "auto",
    "autoScreenshot": "off"
  },
  "execution": {
    "mode": "serial",
    "failFast": true
  },
  "steps": []
}

其中最容易被 Agent 生成错的几个点是：

version 必须是 1
kind 必须是 miniapp-test-plan
execution.mode 目前只能是 serial
metadata.draft 想执行时必须是 false
steps 必须非空

如果这些字段不对，最好在 Agent 侧就把 plan 视为“待修正草稿”，而不是强行执行。

# 3.4 第四步：优先用 `--plan-json` 跑即时闭环

如果 Agent 正处在“生成 -> 执行 -> 分析 -> 再生成”的回路里，最适合的方式通常是：

miniprogram-minium-cli exec --plan-json '<json>' --json

这套方式的优点是：

不需要中间落文件
更适合单轮 agentic workflow
可以把 stdout 里的结构化结果直接接回下一步推理

而当 plan 需要沉淀、复查或纳入仓库时，再切回 --plan <file> 会更合适。

# 3.5 第五步：分析结果时优先读产物，不要迷信终端日志

这一点非常关键。

对 Agent 来说，真正应该优先消费的不是原始日志，而是运行目录下的这些文件：

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

因为这些产物才是下一轮推理最稳定的输入。

一个更合理的分析顺序应该是：

先看 summary.json 确认整体成功/失败
再看 result.json 定位失败步骤
再看 comparison.json 理解预期和实际差异
最后结合截图做视觉和交互取证

# 4. 让 Agent 写 plan 时，我更推荐的思路

如果你是自己在搭 Agent，我建议不要只告诉它“去调用这个 CLI”，而是把工作方式也一起约束住。

我更推荐的提示方式是这种：

你是 miniprogram-minium-cli 的上游 planner。你的职责是根据目标生成可执行 plan，而不是直接发明命令。
只使用文档里支持的顶层字段和步骤类型。
优先参考仓库示例 plan。
当计划仍不完整时，将 metadata.draft 设为 true，不要假装它可执行。
执行结束后优先读取 summary.json、result.json、comparison.json 和截图，而不是只总结日志。

这个思路的本质是：

让 Agent 明确自己是 planner
让 CLI 明确自己是 executor
让产物明确自己是下一轮上下文

三者职责分开以后，整个系统会稳定很多。

# 5. 一个适合 Agent 的最小可执行示例

如果只是为了验证执行链路是否通了，一个最小 plan 可以长这样：

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

Agent 可以直接把它塞进：

miniprogram-minium-cli exec --plan-json '<json>' --json

然后先验证一件事：

执行器能否在当前环境里正常起会话、正常收尾、正常产出结构化结果。

这个动作比一上来就写复杂断言更有价值，因为它能先把环境问题和协议问题剥离出来。

# 6. Agent 最容易踩的几个坑

# 6.1 把它当成自然语言工具

这是最常见的误区。

如果 Agent 的工作流是：

接一句自然语言
直接调用 CLI
希望 CLI 自己补全细节

那基本从一开始就走偏了。

它应该先生成 plan，再执行。

# 6.2 发明未支持的步骤

Agent 很擅长“脑补一个看起来合理的协议”，但执行器不会因为它看起来合理就支持它。

所以只要字段或步骤不在文档和示例里，就不要假设可用。

# 6.3 忽略路径解析规则

这个 CLI 有两套路径解析规则：

命令行文件路径，比如 --plan，按当前执行目录解析
plan 内部相对路径：
- 使用 --plan 时，按 plan 文件所在目录解析
- 使用 --plan-json 时，按当前执行目录解析

这件事对 Agent 很容易出错，因为它经常“逻辑上理解正确”，但在路径解析上踩坑。

# 6.4 失败后只看日志，不读结构化结果

如果失败了，最不推荐的事情就是只盯着终端输出总结一段自然语言。

更好的方式是：

去拿运行目录
读 summary.json
读 result.json
看截图

只有这样，下一轮修正才会更稳。

# 6.5 在 `draft` 状态下强行执行

draft plan 作为数据可以合法存在，但 exec 只接受可执行计划。

所以如果 Agent 自己都知道上下文还没补齐，就应该把它当草稿，而不是强行跑。

# 7. 我为什么坚持把它做成这种样子

我自己越来越相信一件事：

Agent 时代真正需要的，不是把所有能力都混进一个大模型对话框里，而是把每一层职责拆清楚。

在 miniprogram-minium-cli 里，这个拆分大概是：

Agent 负责理解和规划
CLI 负责执行和沉淀
产物负责把这次执行变成下一轮输入

这也是为什么我没有把它做成一个“什么都想做”的 AI 产品。

因为一旦执行层开始承担 planner 的职责，边界就会迅速变糊，稳定性也会跟着下降。

而对小程序自动化这类场景来说，稳定比花哨更重要。

# 8. 最后

如果你只是把 miniprogram-minium-cli 当成一个命令行工具，那它的价值其实只发挥了一半。

它真正适合的位置，是放进一个完整的 Agent 工作流里：

上游负责生成结构化 plan
中间负责真实执行
下游负责消费结构化结果继续推理

从这个角度看，它不是一个“给人点点点用的脚本”，而是一个让 AI 能真正接入小程序自动化执行闭环的基础设施组件。