一图看懂场景依赖:Arbigent graph 命令输出 Mermaid 与 sort 排序实战

原创2026-11-06 11:16:501,848 阅读

一图看懂场景依赖:Arbigent graph 命令输出 Mermaid 与 sort 排序实战

Arbigent 是一个面向 Android、iOS 和 Web 应用的 AI Agent 测试框架,可以把复杂测试目标拆分为相互依赖的场景(scenarios)。当场景越写越多,dependency 依赖链很容易变得难以追踪。本文带你用 arbigent graph 把场景依赖一键输出为 Mermaid 图,再用 arbigent sort 按依赖顺序自动整理 YAML,让测试项目的结构一目了然。

为什么场景依赖需要"一图看懂"

Arbigent 通过 dependency 字段把复杂任务拆成小的依赖链(例如:启动 App → 打开搜索 → 输入关键词),arbigent run 会严格按照 scenarios 列表中的顺序执行。手写 YAML 时常见问题:

  • 场景顺序和依赖关系对不上,执行时才发现漏了前置步骤;
  • 想快速了解某个场景的上游(谁依赖它)和下游(它依赖谁),只能全文搜索;
  • 团队协作后,文件里场景摆放杂乱,注释过期。

arbigent graph 和 arbigent sort 正是为这两个痛点设计的只读/轻量整理命令,不需要 AI API Key,也不需要连接设备。

一键输出:用 arbigent graph 生成 Mermaid 依赖图

在项目目录下执行:

arbigent graph
# 或显式指定项目文件
arbigent graph --project-file=path/to/project.yaml

命令会读取项目 YAML,把场景依赖图打印为 Mermaid 文本,可以直接粘贴到支持 Mermaid 的 Markdown 文档(如 README)中渲染查看。

一个典型输出长这样:

graph LR
  n0["setup"]
  n1["buy"]
  n2[["login (user=paid)"]]:::reusable
  n0 -.-> n2
  n2 --> n1

图的读法有 3 个要点:

元素 含义
矩形节点(id[...]) 一个可运行的场景,副标题是 goal 的摘要
圆角节点(id[[...]],蓝色) 可复用场景(reusable)的一次调用,同一 reusable 在两个地方被调用会生成两个独立节点
实线箭头 --> dependency 依赖边,表示"前者执行完(含它的所有调用)后再跑后者"
虚线箭头 -.-> 场景内对 reusable 场景的调用(uses/steps),按实际执行顺序展开

值得注意的细节:依赖边从"被依赖场景最后执行的节点"出发。例如 setup 场景内部调用了 login,buy 依赖 setup,图里画的是 setup -.-> login --> buy,而不是从 setup 直接分叉——这正是运行时的真实执行顺序,见 ArbigentScenarioGraph.kt 中的 toMermaid() 实现。

同样的图也可以在 UI 里查看:Arbigent 桌面端的 "Scenario graph" 对话框与 CLI 共用同一套图模型,支持拖拽平移和缩放,见 ScenarioGraphDialog.kt。

一键整理:arbigent sort 按依赖深度优先排序

图看懂了,接下来把文件本身整理干净。执行:

arbigent sort

它会把项目文件重写为深度优先的依赖顺序:每个场景紧跟在它依赖的场景之后,整棵子树排在下一个兄弟节点之前;根节点和同级场景保持声明顺序。同时为每个场景刷新一行 # tree: 位置注释,整理后大致是:

scenarios:
# The "# tree:" lines below are generated from `dependency` by `arbigent sort` ...
# tree: launch-app | children: open-search
- id: "launch-app"
  goal: "Launch the app"
# tree: launch-app > open-search | children: type-keyword
- id: "open-search"
  goal: "Open search"
  dependency: "launch-app"

现在随便打开一个场景,不用搜索就能看到它的完整祖先链(launch-app > open-search)和直接依赖它的子场景(children: type-keyword)。

sort 的安全边界做得很克制:只移动 - id: 场景块和 # tree: 注释行,引号、空行、你手写的其他注释都原样保留;写盘前还会重新解析结果,若解码不一致则拒绝修改。实现见 ArbigentScenarioSorter.kt。

CI 防漂移:arbigent sort --diff

手动编辑后文件很容易"漂移"出依赖顺序。在 CI 中加一条只检查、不修改的命令即可拦截:

arbigent sort --diff --project-file=e2e/project.yaml
  • 若文件已排序:输出 Already sorted,退出码 0;
  • 若顺序有变化:打印 unified diff 预览改动,退出码 1,CI 直接失败。

其他常用选项:--comments / --no-comments 控制是否写入位置注释(默认跟随项目 settings.positionComments 设置)。更多参数说明见 arbigent-cli-reference.md。

实战工作流小结

  1. 写场景:用 dependency 声明依赖,用 uses/steps 复用可复用场景(详见 arbigent-yaml-reference.md 的"Scenario order and position comments"一节);
  2. 看图:arbigent graph 生成 Mermaid,粘贴进文档给团队评审,或确认执行顺序是否符合预期;
  3. 排序:arbigent sort 一键整理顺序并刷新 # tree: 注释;
  4. 守护:arbigent sort --diff 进 CI,防止文件顺序再次漂移;
  5. AI 协作:由于这两条命令自描述、无需设备,AI 编码助手(如 Claude Code)也能直接调用 arbigent graph / arbigent sort 来检查和整理项目。

一条命令看图、一条命令理顺序,Arbigent 的场景依赖管理成本被压缩到了最低。

参考资料

登录后查看全文
arbigent