cli-anything-macrocli

MacroCLI CLI

这是什么

MacroCLI 将有价值的 GUI 工作流转换为参数化、 可通过 CLI 调用的宏。Agent 从不直接接触 GUI——它们通过这个稳定的 CLI 调用宏， 运行时会将执行路由到最佳可用后端（原生插件/API、文件转换、语义 UI 控制或 预编译的 GUI 宏回放）。

安装

cd macrocli/agent-harness
pip install -e .

要求： Python 3.10+、PyYAML、click、prompt-toolkit。

快速开始（面向 Agent）

# 1. See what macros are available
cli-anything-macrocli macro list --json

# 2. Inspect a macro's parameters
cli-anything-macrocli macro info export_file --json

# 3. Dry-run to check params without side effects
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

# 4. Execute a macro
cli-anything-macrocli macro run export_file \
    --param output=/tmp/result.txt --json

# 5. See what backends are available
cli-anything-macrocli backends --json

命令参考

全局标志

标志	描述
--json	在 stdout 输出机器可读的 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
# Shows: native_api, file_transform, semantic_ui, gui_macro, recovery
# and whether each is available in the current environment.

宏参数

使用 --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: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    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  # or: 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

Agent 使用规则

1. 始终使用 --json 以获得程序化输出。
2. 在执行有副作用的宏之前，使用 --dry-run 验证参数。
3. 检查 success 字段——不要仅凭退出码就假定成功。
4. 当 success 为 false 时，读取 error 字段——它说明了失败原因。
5. 在调用 macro run 之前，使用 macro info <name> 发现参数。
6. 所有文件参数使用绝对路径。

示例工作流

# Step 1: What's available?
cli-anything-macrocli macro list --json

# Step 2: What params does transform_json need?
cli-anything-macrocli macro info transform_json --json

# Step 3: Test safely
cli-anything-macrocli --dry-run macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

# Step 4: Execute for real
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

版本

1.0.0