MacroCLI 命令行工具 是做什么的？
简介
MacroCLI 将有价值的 GUI 工作流转换为参数化的、可通过 CLI 调用的宏。代理绝不直接操作 GUI — 它们通过这个稳定的 CLI 接口调用宏，运行时系统会自动将执行路由到最佳可用后端（原生插件/API、文件转换、语义化 UI 控制或预编译的 GUI 宏回放）。
安装
cd macrocli/agent-harness
pip install -e .
要求： Python 3.10+、PyYAML、click、prompt-toolkit。
快速入门（面向代理）
# 1. 查看可用的宏
cli-anything-macrocli macro list --json
# 2. 查看宏的参数信息
cli-anything-macrocli macro info export_file --json
# 3. 预检参数（无副作用）
cli-anything-macrocli --dry-run macro run export_file \
--param output=/tmp/test.txt --json
# 4. 执行宏
cli-anything-macrocli macro run export_file \
--param output=/tmp/result.txt --json
# 5. 查看可用后端
cli-anything-macrocli backends --json
命令参考
全局标志
| 标志 | 描述 |
|---|---|
--json | 在标准输出上输出机器可读的 JSON |
--dry-run | 模拟所有步骤，跳过副作用 |
--session-id <id> | 恢复或创建一个命名会话 |
macro 命令组
| 命令 | 描述 |
|---|---|
macro list | 列出所有可用的宏 |
macro info <name> | 显示宏的 schema（参数、步骤、条件） |
macro run <name> --param k=v | 执行一个宏 |
macro dry-run <name> --param k=v | 模拟执行，无副作用 |
macro validate [name] | 结构验证 |
macro define <name> | 创建新的宏 YAML 模板 |
session 命令组
| 命令 | 描述 |
|---|---|
session status | 显示会话统计信息 |
session history | 显示最近的运行历史 |
session save | 将会话持久化到磁盘 |
session list | 列出所有已保存的会话 |
backends
cli-anything-macrocli backends --json
# 显示： native_api, file_transform, semantic_ui, gui_macro, recovery
# 以及每个后端在当前环境中是否可用。
宏参数
使用 --param key=value 传递参数。多个参数重复使用该标志：
cli-anything-macrocli macro run transform_json \
--param file=/path/to/data.json \
--param key=settings.theme \
--param value=dark \
--json
输出格式（--json）
所有命令在设置 --json 后输出 JSON：
{
"success": true,
"macro_name": "export_file",
"output": {
"exported_file": "/tmp/result.txt"
},
"error": "",
"telemetry": {
"duration_ms": 312,
"steps_total": 2,
"steps_run": 2,
"backends_used": ["native_api"],
"dry_run": false
}
}
失败时（"success": false），读取 "error" 字段获取原因。失败时退出码为 1。
执行后端
后端根据宏步骤定义自动选择：
| 后端 | 触发条件 | 使用场景 |
|---|---|---|
native_api | backend: native_api | 子进程 / shell 命令 |
file_transform | backend: file_transform | XML、JSON、文本文件编辑 |
semantic_ui | backend: semantic_ui | 无障碍访问 / 键盘快捷键 |
gui_macro | backend: gui_macro | 预编译坐标回放 |
recovery | backend: recovery | 重试 / 回退编排 |
编写宏
宏是位于 cli_anything/macrocli/macro_definitions/ 目录下的 YAML 文件。使用以下命令创建模板：
cli-anything-macrocli macro define my_macro --output \
cli_anything/macrocli/macro_definitions/examples/my_macro.yaml
最小 schema：
name: my_macro
version: "1.0"
description: 这个宏做什么。
parameters:
output:
type: string
required: true
description: 结果写入位置。
example: /tmp/result.txt
preconditions:
- file_exists: /path/to/input
steps:
- id: step1
backend: native_api
action: run_command
params:
command: [my-app, --export, "${output}"]
timeout_ms: 30000
on_failure: fail # 或： skip, continue
postconditions:
- file_exists: ${output}
- file_size_gt: [${output}, 100]
outputs:
- name: result_file
path: ${output}
agent_hints:
danger_level: safe # safe | moderate | dangerous
side_effects: [creates_file]
reversible: true
代理使用规则
- 始终使用
--json以便程序化处理输出。 - 在执行有副作用的宏之前，先使用
--dry-run验证参数。 - 检查
success字段 — 不要仅凭退出码判断成功。 - 当
success为 false 时，读取error字段 — 它会说明失败原因。 - 在调用
macro run之前，先使用macro info <name>发现参数。 - 所有文件参数使用绝对路径。
示例工作流
# 步骤 1：查看可用宏
cli-anything-macrocli macro list --json
# 步骤 2：transform_json 需要哪些参数？
cli-anything-macrocli macro info transform_json --json
# 步骤 3：安全测试
cli-anything-macrocli --dry-run macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
# 步骤 4：真正执行
cli-anything-macrocli macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
版本
1.0.0