cli-anything-macrocli

用途

MacroCLI 用于把有价值的 GUI 工作流转换为参数化、可由 CLI 调用的宏。智能体不直接接触 GUI，而是通过这个稳定的命令行接口调用宏，运行时再把执行路由到当前环境中最合适的后端。

主要能力

宏管理：列出所有可用宏、查看宏的参数与步骤结构（schema）、对宏做结构校验、脚手架式生成新的宏 YAML 文件。
宏执行：运行宏并传入参数，或先做 dry-run 模拟以检查参数而不产生副作用。
会话管理：查看会话状态与运行历史、持久化会话到磁盘、列出已保存的会话。
后端查询：查看当前环境中可用的执行后端。
机器可读输出：所有命令在设置 --json 时以 JSON 输出到 stdout，包含 success、macro_name、output、error 与 telemetry（耗时、步骤总数、已运行步骤、使用的后端、是否 dry-run）等字段；失败时 success 为 false，退出码为 1。

使用方式

安装：

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. 无副作用地 dry-run 检查参数
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（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，显示 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

执行后端

后端根据宏步骤定义自动选择：

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

智能体使用规则

程序化输出时始终使用 --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

适用场景

适合需要让智能体以稳定、可参数化的方式复用 GUI 工作流的场景，例如文件导出、JSON/XML 配置修改、通过无障碍接口或键盘快捷键操作界面，以及需要重试与回退编排的任务。

限制

资料未提供关于收费、价格、平台支持范围、性能指标或具体宏库内容的更多信息。