MacroCLI 完全指南用 cli-anything-macrocli 把 GUI 工作流封装成 Agent 可调用的参数化宏【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingMacroCLI 是 CLI-Anything 项目中面向GUI 优先/闭源应用场景的统一 CLI 入口它把宝贵的 GUI 操作流程沉淀为参数化的、可直接由命令行调用的宏macro让 AI Agent 永远不必直接接触 GUI只需发出cli-anything-macrocli macro run name --param kv --json一类稳定命令运行时便会自动完成参数校验、后端路由与步骤执行。读完本文你将掌握 MacroCLI 的安装方式、全套子命令与 JSON 输出协议、YAML 宏定义 schema 的每一个字段以及执行运行时MacroRuntime与路由引擎RoutingEngine背后的分层设计与源码实现。本文以 skills/SKILL.md 为核心脉络展开并结合 agent-harness/MACROCLI.mdAgent Harness SOP与cli_anything/macrocli/包内源码进行印证与扩充。MacroCLI 是什么把 GUI 工作流变成稳定 CLI在 skills/SKILL.md 中MacroCLI 的定位被描述得非常清晰将有价值的 GUI 工作流转换为参数化、可被 CLI 调用的宏。Agent绝不直接操作 GUI而是透过这一稳定 CLI 调用宏运行时根据宏步骤的定义将执行路由到当前环境下最可用的后端候选后端包括native plugin/API原生插件/API实为子进程/Shell 命令file transformation文件变换XML、JSON、文本编辑semantic UI control语义化 UI 控制基于无障碍接口与键盘事件precompiled GUI macro replay预编译 GUI 坐标回放。Agent 视角下一条命令、一份 JSON 结果背后却是 L7→L1 的分层架构。MACROCLI.md 给出了完整的层映射表层名称实现L7Agent Task Interface调用方任意 AI AgentL6Unified CLI Entrymacrocli_cli.py — Click CLIL5Macro Execution Runtimecore/runtime.pyL4Parameterized Macro Modelcore/macro_model.py macro_definitions/*.yamlL3Backend Routing Enginecore/routing.pyL2Execution Backendsbackends/7 类后端L1Target Application任意 GUI-first 或闭源应用一次macro run的完整生命周期可以概括为Agent 发出命令 → MacroRuntime 校验参数 → 检查前置条件preconditions→ 逐步骤执行RoutingEngine 按优先级选后端并执行→ 检查后置条件postconditions→ 汇总声明式输出 → 将遥测记录进会话 → 返回{ success, output, error, telemetry }结构化结果。安装与运行环境要求SKILL.md 给出了最小安装方式进入 harness 目录执行可编辑安装即可cd macrocli/agent-harness pip install -e .运行时依赖Python 3.10、PyYAML、click、prompt-toolkit。MACROCLI.md 进一步补充了可选 extra 依赖它们对应不同后端的能力开关pip install -e .[visual] # visual_anchor 后端mss、Pillow、numpy、pynput pip install -e .[gui_agent] # gui_agent 后端openai、mss、Pillow pip install -e .[all] # 全部此外还有几项非 Python 的系统级可选依赖xdotool— Linux 上 semantic_ui 后端需要pyautogui— gui_macro 后端需要psutil— 让process_running条件检测更健壮源码中pgrep优先、psutil 兜底。gui_agent后端基于 OpenAI SDK兼容任何 OpenAI 协议接口通过三个环境变量配置变量说明MACROCLI_MODEL模型名必填例如gpt-4oMACROCLI_API_KEY服务商 API KeyMACROCLI_BASE_URLBase URL仅非 OpenAI 官方主机时需要入口命令cli-anything-macrocli由 setup.py 中的 entry_point 注册。运行测试使用cd macrocli/agent-harness python3 -m pytest cli_anything/macrocli/tests/ -v -s测试分布在 tests/test_core.py单元测试无外部依赖与 tests/test_full_e2e.pyE2E CLI 子进程测试。Agent 快速上手五个必会命令SKILL.md 为 Agent 编排了一条先探查、再检视、后试跑、终执行、再看后端的黄金路径# 1. 查看当前有哪些宏可用 cli-anything-macrocli macro list --json # 2. 检视某个宏的参数 schema 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注意第 3 步中--dry-run放在顶层macro子命令之前这与 CLI 的全局 flag 设计一致——在 macrocli_cli.py 中--json、--dry-run、--session-id都是挂在 Click 根 groupcli上的全局选项。命令参考全局 FlagFlag说明--jsonstdout 输出机器可读 JSON--dry-run模拟全部步骤跳过副作用--session-id id恢复或新建一个命名会话此外macro run与macro dry-run支持--param/-p可重复keyvalue格式macro run还支持--macro-file yaml直接绕过注册表、从指定 YAML 文件执行宏如录制产出物而macro record、macro parameterize、macro assist、macro capture-template等子命令拥有各自的专属选项详见下文从录制到生成。macro子命令组命令说明macro list列出所有可用宏macro info name展示宏 schema参数、步骤、条件macro run name --param kv执行宏macro dry-run name --param kv无副作用模拟macro validate [name]结构校验省略 name 则校验全部macro define name脚手架生成新宏 YAMLsession子命令组命令说明session status显示会话统计session history显示最近运行历史session save将会话持久化到磁盘session list列出所有已保存会话backends顶层命令cli-anything-macrocli backends --json # 显示native_api、file_transform、semantic_ui、gui_macro、recovery # 以及 visual_anchor、gui_agent并标注各后端在当前环境是否 available无参数启动 REPL不带任何子命令直接运行cli-anything-macrocli或显式cli-anything-macrocli repl会进入基于 prompt-toolkit 的交互式 REPL启动时打印 banner并提示当前已加载的宏数量在 REPL 中输入macro list、macro info name、macro run name [--param kv ...]、session status等命令与 CLI 语义完全一致输入quit/exit/q退出输入help/?查看内置帮助。REPL 皮肤与错误处理由 utils/repl_skin.py 提供cli-anything 标准皮肤。宏参数传递规范参数一律通过--param keyvalue传递需要多个参数就重复该选项cli-anything-macrocli macro run transform_json \ --param file/path/to/data.json \ --param keysettings.theme \ --param valuedark \ --json在 CLI 实现中_parse_params会将keyvalue元组拆成 dict按第一个切分两侧 trim若某个--param缺少会被视为格式非法并打印警告后忽略。任何文件类参数建议使用绝对路径——这是 SKILL.md Agent Usage Rules 中明文要求的规则之一能避免工作目录不确定性导致file_exists等条件判断失败。JSON 输出协议--jsonSKILL.md 给出了标准的成功响应示例{ 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 } }该结构与 runtime.py 中ExecutionResult.to_dict()完全对应实际返回还额外包含steps每个步骤的StepResult数组。协议要点失败时success: false必须读取error字段了解原因失败时进程退出码为 1成功时退出码为 0。但 Agent 规则明确要求不要只凭退出码判断成败务必检查success字段——因为 REPL 模式与部分命令路径并不会以退出码表达失败_repl_mode下会抑制sys.exit。CLI 的handle_error装饰器保证非 JSON 模式下错误走 stderrJSON 模式下统一输出{error: ..., type: ...}结构的错误对象not_found、file_not_found、异常类名等。执行后端矩阵与路由原理SKILL.md 中的后端触发表backend: xxx字段直接指定对照 MACROCLI.md 可补充每个后端的优先级priority后端优先级触发方式典型用途native_api100backend: native_api子进程 / Shell 命令gui_macro80backend: gui_macro预编译坐标回放pyautoguivisual_anchor75backend: visual_anchor模板匹配点击/输入需[visual]file_transform70backend: file_transformXML、JSON、文本文件编辑gui_agent60backend: gui_agent视觉模型驱动自动化需[gui_agent]semantic_ui50backend: semantic_ui无障碍 API 键盘xdotoolrecovery10backend: recovery重试 回退编排路由引擎的逻辑值得展开routing.py尊重显式声明如果步骤声明了backend:且该后端在当前环境可用is_available()为真就直接选用按优先级兜底降级若声明的后端不可用例如缺xdotool引擎按优先级从高到低遍历查找第一个可用的后端——recovery永远不会被自动兜底选中select()中显式continue跳过它只能被显式声明触发若全部不可用抛出RuntimeError提示检查缺失工具。7 个后端为什么必要MACROCLI.md 的设计决策部分解释得很直白真实 GUI 应用暴露的控制面五花八门native_api只覆盖有 CLI/API的应用对没有稳定接口的应用visual_anchor用模板匹配做稳健的 UI 元素定位gui_agent则用视觉模型在 UI 状态不可预测时做动态决策semantic_ui走无障碍树加键盘。路由引擎的目标是让Agent 不必关心最终是哪个后端执行了步骤只对结果负责。编写自己的宏YAML Schema 详解宏是以 YAML 文件形式存放在cli_anything/macrocli/macro_definitions/及子目录中的。SKILL.md 建议用脚手架命令生成初始骨架cli-anything-macrocli macro define my_macro --output \ cli_anything/macrocli/macro_definitions/examples/my_macro.yaml不传--output/-o时模板直接打印到 stdout传入路径时自动创建父目录并写入。生成后的模板同样由 CLI 的macro define命令提供见 macrocli_cli.py。下面是最小 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 # 或: 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字段级语义结合 macro_model.py 解析从 macro_model.py 的数据类可以看出各字段的精确定义与约束parametersMacroParametertype支持string | integer | float | boolean | list | dictCLI 的macro define模板注释里也允许用更全的写法transform_json.yaml的示例全部用string也支持简写形式parameter_name: string解析器会将其视为仅声明 type。required必填标志运行时validate_params对缺省必填参数会报错。default可选项resolve_params在运行前用默认值补齐缺失参数schema 之外的额外参数会被透传。enum/min/max对值域进行约束integer 类型参与 min/max 数值比较、enum 做成员校验例如 export_file.yaml 中format参数声明了enum: [plain, json, csv]。description/example供macro info展示与 Agent 自学不是运行时约束。preconditions / postconditionsMacroCondition条件是单键 dict支持的完整类型MACROCLI.md 有表runtime.py 的_check_condition有实现类型参数形式判定逻辑file_exists路径os.path.exists(path)file_size_gt[path, min_bytes]os.stat(path).st_size min_bytesprocess_running进程名pgrep -x name失败后尝试 psutilenv_var环境变量名name in os.environalwaystrue/false恒真/恒假条件参数同样支持${var}替换_check_condition内部先substitute再判定。未知条件类型不会阻断执行仅告警放行。stepsMacroStepid步骤标识缺省自动生成step_ibackendaction后端名与后端专属动作如native_apirun_command、file_transformjson_set/text_replace、visual_anchor 模板动作等params动作参数支持${key}占位符递归替换——substitute()会递归处理 string/list/dict遇到整数、布尔等非字符串类型原样保留timeout_ms默认 30000on_failurefail | skip | continue。三者语义runtime.pyfail立即中断并置宏为失败skip跳过失败步骤继续后续步骤continue无视错误继续。MACROCLI.md 的解释是有些步骤是 best-effort例如确认一个可能不出现的对话框skip/continue 让宏不必为了琐碎弹窗而整体失败重试策略retry_policy: {max_retries, backoff_ms}或顶层retry_max由 RoutingEngine 在execute_step中按 backoff 序列执行带退避的重试。outputsMacroOutput命名输出path或value二选一运行时做${}替换后放进结果outputdict_collect_outputs还会额外塞入_steps键保存每个步骤的原始输出。Agent 从output里取走声明过的产物路径如exported_file即可进行后续处理。agent_hints仅供 Agent 决策使用的元数据danger_levelsafe/moderate/dangerous、side_effects如creates_file、modifies_file、reversible。例如 transform_json.yaml 声明了danger_level: moderate、side_effects: [modifies_file]、reversible: false——因为它是原地改写文件不可逆而 export_file 示例则声明为 safe 且可逆。一个真实的双后端宏示例export_file.yaml 展示了宏内多步骤混用不同后端的写法——第一段用native_api跑导出命令第二段用file_transform的text_replace落盘一个标记文件best-efforton_failure: skipsteps: - id: step_export backend: native_api action: run_command params: # 换成真实应用的导出命令例如 # command: [inkscape, --export-filename, ${output}, ${input}] command: [echo, Exported to ${output} (format${format})] capture_stdout: true timeout_ms: 30000 on_failure: fail - id: step_write_output backend: file_transform action: text_replace params: input_file: /dev/null output_file: ${output} find: replace: on_failure: skip # 写标记文件是 best-effort注册表如何发现宏macro list默认扫描包内macro_definitions/目录registry.py 中Path(__file__).../macro_definitions。扫描策略若存在 manifest.yaml 则按其中显式索引加载否则递归扫描目录下所有*.yaml。manifest.yaml用于声明顺序/白名单。录制产出的宏包可通过--macro-file直接执行绕开注册表——CLI 内部为此构造了一个只含单个宏的临时 registry。Agent 使用规则六条铁律SKILL.md 列出的 Agent 行为准则值得完整保留它们是让 Agent 与 CLI 可靠协作的经验沉淀永远使用--json获取程序化输出避免解析人类可读文本执行有副作用的宏之前先用--dry-run校验参数runtime.execute(..., dry_runTrue)在 BackendContext 中传递dry_run标志各后端据此跳过真实副作用检查success字段——不能只凭退出码假设成败当success为 false 时读取error字段它说明了失败原因调用macro run前先用macro info name发现参数——宏的 schema 是动态的先读后调是避免参数错配的关键所有文件参数使用绝对路径。完整工作流实战transform_json结合仓库内真实定义把整套规则串起来就是 SKILL.md 的 Example Workflow# Step 1: 看有哪些宏 cli-anything-macrocli macro list --json # Step 2: transform_json 需要哪些参数 cli-anything-macrocli macro info transform_json --json # Step 3: 安全试跑 cli-anything-macrocli --dry-run macro run transform_json \ --param file/tmp/config.json \ --param keytheme \ --param valuedark --json # Step 4: 正式执行 cli-anything-macrocli macro run transform_json \ --param file/tmp/config.json \ --param keytheme \ --param valuedark --json对应 transform_json.yaml前置条件file_exists: ${file}保证文件存在唯一步骤用file_transformjson_set把settings.theme这类点分键路径写成新值并原文件落盘后置条件再次file_exists确认输出命名modified_file。这展示了一个读 JSON → 改嵌套键 → 写回的完整可复用数据变更宏。从录制到生成把新 GUI 流程变成宏除手写 YAML 外CLI 还提供四条造宏路径源码见 macrocli_cli.pymacro record name录制 GUI 交互并生成宏包目录name/macro.yamlsnapshots/。支持组合选项--agent-review录制后交互式把某些步骤标记为需要视觉模型的 agent step、--parameterize交互式挑选哪些输入值变成 CLI 参数、--auto-parameterize用 LLM 自动建议参数名需要--api-key或MACROCLI_API_KEY--parameterize与--auto-parameterize互斥。底层由 core/recorder.py 实现需pip install mss Pillow pynput。录制完成后按 CtrlAltS 停止macro parameterize yaml对既有 YAML 中硬编码的type_text步骤做参数化--auto模式下用 LLM 建议参数名并按实际值自动推断类型string/integer/floatmacro assist name --goal ...截屏后发送给视觉模型按自然语言目标直接生成宏 YAML需pip install openai mss Pillow产物若涉及视觉模板会列出待捕获模板清单macro capture-template out.png --x --y --width --height按矩形坐标捕获屏幕区域存为模板 PNG供visual_anchor模板匹配类步骤使用backends/visual_anchor.py。会话与遥测让 Agent 可回溯session子命令组的底层是 core/session.py 的ExecutionSession每次macro run都会生成一条RunRecordmacro 名、参数、成败、输出、错误、耗时、所用后端、步骤数保存在进程内历史中上限 200 条session save通过带文件锁的原子写把会话 JSON 持久化到~/.macrocli/sessions/session_id.json--session-id可让多次调用共享同一命名会话session list按时间倒序列出历史会话及运行数。借助session historyAgent 可以复盘刚才那条宏为什么失败、走了哪个后端、花了多少毫秒。为什么这么设计三处关键权衡MACROCLI.md 的 Design Decisions 部分给出了官方解释这里结合源码略作归纳为什么用 YAML 而非 Python 定义宏YAML 宏不需要运行代码即可被 Agent 阅读可通过macro info检视也可在不动 harness 源码的前提下直接编辑/分享——声明式格式天然适合作为Agent 与自动化之间的契约。为什么要 7 个后端不同 GUI 应用的控制面差异巨大visual_anchor用模板匹配做稳健定位gui_agent在 UI 状态不可预测时交给视觉模型动态决策路由引擎负责挑最可靠且可用的那一个把复杂性收敛在 L2/L3 层。为什么要有前后置条件Agent 运行环境状态不确定前置条件执行前大声失败、后置条件执行后验证把问题暴露成 Agent 可行动的错误信息而非静默的坏结果。加上on_failure: skip/continue让宏能容忍 best-effort 步骤的偶发失败例如一个时有时无的确认对话框。版本与适用边界本包当前版本为1.0.0见 SKILL.md 末尾及 REPL banner 中的ReplSkin(macrocli, version1.0.0)。文中描述的命令、schema 与行为均以当前仓库 macrocli/agent-harness 内代码为准gui_agent、visual_anchor、gui_macro、semantic_ui等后端依赖可选 extra 或系统工具实际可用性以cli-anything-macrocli backends --json的输出为准。若要在自己的环境中运行请先确保满足上文安装与运行环境要求一节列出的依赖再进行录制与执行类操作。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 23:43:26 · 阅读 1.2k MacroCLI 完全指南：用 cli-anything-macrocli 把 GUI 工作流封装成 Agent 可调用的参数化宏
MacroCLI 完全指南用 cli-anything-macrocli 把 GUI 工作流封装成 Agent 可调用的参数化宏【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingMacroCLI 是 CLI-Anything 项目中面向GUI 优先/闭源应用场景的统一 CLI 入口它把宝贵的 GUI 操作流程沉淀为参数化的、可直接由命令行调用的宏macro让 AI Agent 永远不必直接接触 GUI只需发出cli-anything-macrocli macro run name --param kv --json一类稳定命令运行时便会自动完成参数校验、后端路由与步骤执行。读完本文你将掌握 MacroCLI 的安装方式、全套子命令与 JSON 输出协议、YAML 宏定义 schema 的每一个字段以及执行运行时MacroRuntime与路由引擎RoutingEngine背后的分层设计与源码实现。本文以 skills/SKILL.md 为核心脉络展开并结合 agent-harness/MACROCLI.mdAgent Harness SOP与cli_anything/macrocli/包内源码进行印证与扩充。MacroCLI 是什么把 GUI 工作流变成稳定 CLI在 skills/SKILL.md 中MacroCLI 的定位被描述得非常清晰将有价值的 GUI 工作流转换为参数化、可被 CLI 调用的宏。Agent绝不直接操作 GUI而是透过这一稳定 CLI 调用宏运行时根据宏步骤的定义将执行路由到当前环境下最可用的后端候选后端包括native plugin/API原生插件/API实为子进程/Shell 命令file transformation文件变换XML、JSON、文本编辑semantic UI control语义化 UI 控制基于无障碍接口与键盘事件precompiled GUI macro replay预编译 GUI 坐标回放。Agent 视角下一条命令、一份 JSON 结果背后却是 L7→L1 的分层架构。MACROCLI.md 给出了完整的层映射表层名称实现L7Agent Task Interface调用方任意 AI AgentL6Unified CLI Entrymacrocli_cli.py — Click CLIL5Macro Execution Runtimecore/runtime.pyL4Parameterized Macro Modelcore/macro_model.py macro_definitions/*.yamlL3Backend Routing Enginecore/routing.pyL2Execution Backendsbackends/7 类后端L1Target Application任意 GUI-first 或闭源应用一次macro run的完整生命周期可以概括为Agent 发出命令 → MacroRuntime 校验参数 → 检查前置条件preconditions→ 逐步骤执行RoutingEngine 按优先级选后端并执行→ 检查后置条件postconditions→ 汇总声明式输出 → 将遥测记录进会话 → 返回{ success, output, error, telemetry }结构化结果。安装与运行环境要求SKILL.md 给出了最小安装方式进入 harness 目录执行可编辑安装即可cd macrocli/agent-harness pip install -e .运行时依赖Python 3.10、PyYAML、click、prompt-toolkit。MACROCLI.md 进一步补充了可选 extra 依赖它们对应不同后端的能力开关pip install -e .[visual] # visual_anchor 后端mss、Pillow、numpy、pynput pip install -e .[gui_agent] # gui_agent 后端openai、mss、Pillow pip install -e .[all] # 全部此外还有几项非 Python 的系统级可选依赖xdotool— Linux 上 semantic_ui 后端需要pyautogui— gui_macro 后端需要psutil— 让process_running条件检测更健壮源码中pgrep优先、psutil 兜底。gui_agent后端基于 OpenAI SDK兼容任何 OpenAI 协议接口通过三个环境变量配置变量说明MACROCLI_MODEL模型名必填例如gpt-4oMACROCLI_API_KEY服务商 API KeyMACROCLI_BASE_URLBase URL仅非 OpenAI 官方主机时需要入口命令cli-anything-macrocli由 setup.py 中的 entry_point 注册。运行测试使用cd macrocli/agent-harness python3 -m pytest cli_anything/macrocli/tests/ -v -s测试分布在 tests/test_core.py单元测试无外部依赖与 tests/test_full_e2e.pyE2E CLI 子进程测试。Agent 快速上手五个必会命令SKILL.md 为 Agent 编排了一条先探查、再检视、后试跑、终执行、再看后端的黄金路径# 1. 查看当前有哪些宏可用 cli-anything-macrocli macro list --json # 2. 检视某个宏的参数 schema 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注意第 3 步中--dry-run放在顶层macro子命令之前这与 CLI 的全局 flag 设计一致——在 macrocli_cli.py 中--json、--dry-run、--session-id都是挂在 Click 根 groupcli上的全局选项。命令参考全局 FlagFlag说明--jsonstdout 输出机器可读 JSON--dry-run模拟全部步骤跳过副作用--session-id id恢复或新建一个命名会话此外macro run与macro dry-run支持--param/-p可重复keyvalue格式macro run还支持--macro-file yaml直接绕过注册表、从指定 YAML 文件执行宏如录制产出物而macro record、macro parameterize、macro assist、macro capture-template等子命令拥有各自的专属选项详见下文从录制到生成。macro子命令组命令说明macro list列出所有可用宏macro info name展示宏 schema参数、步骤、条件macro run name --param kv执行宏macro dry-run name --param kv无副作用模拟macro validate [name]结构校验省略 name 则校验全部macro define name脚手架生成新宏 YAMLsession子命令组命令说明session status显示会话统计session history显示最近运行历史session save将会话持久化到磁盘session list列出所有已保存会话backends顶层命令cli-anything-macrocli backends --json # 显示native_api、file_transform、semantic_ui、gui_macro、recovery # 以及 visual_anchor、gui_agent并标注各后端在当前环境是否 available无参数启动 REPL不带任何子命令直接运行cli-anything-macrocli或显式cli-anything-macrocli repl会进入基于 prompt-toolkit 的交互式 REPL启动时打印 banner并提示当前已加载的宏数量在 REPL 中输入macro list、macro info name、macro run name [--param kv ...]、session status等命令与 CLI 语义完全一致输入quit/exit/q退出输入help/?查看内置帮助。REPL 皮肤与错误处理由 utils/repl_skin.py 提供cli-anything 标准皮肤。宏参数传递规范参数一律通过--param keyvalue传递需要多个参数就重复该选项cli-anything-macrocli macro run transform_json \ --param file/path/to/data.json \ --param keysettings.theme \ --param valuedark \ --json在 CLI 实现中_parse_params会将keyvalue元组拆成 dict按第一个切分两侧 trim若某个--param缺少会被视为格式非法并打印警告后忽略。任何文件类参数建议使用绝对路径——这是 SKILL.md Agent Usage Rules 中明文要求的规则之一能避免工作目录不确定性导致file_exists等条件判断失败。JSON 输出协议--jsonSKILL.md 给出了标准的成功响应示例{ 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 } }该结构与 runtime.py 中ExecutionResult.to_dict()完全对应实际返回还额外包含steps每个步骤的StepResult数组。协议要点失败时success: false必须读取error字段了解原因失败时进程退出码为 1成功时退出码为 0。但 Agent 规则明确要求不要只凭退出码判断成败务必检查success字段——因为 REPL 模式与部分命令路径并不会以退出码表达失败_repl_mode下会抑制sys.exit。CLI 的handle_error装饰器保证非 JSON 模式下错误走 stderrJSON 模式下统一输出{error: ..., type: ...}结构的错误对象not_found、file_not_found、异常类名等。执行后端矩阵与路由原理SKILL.md 中的后端触发表backend: xxx字段直接指定对照 MACROCLI.md 可补充每个后端的优先级priority后端优先级触发方式典型用途native_api100backend: native_api子进程 / Shell 命令gui_macro80backend: gui_macro预编译坐标回放pyautoguivisual_anchor75backend: visual_anchor模板匹配点击/输入需[visual]file_transform70backend: file_transformXML、JSON、文本文件编辑gui_agent60backend: gui_agent视觉模型驱动自动化需[gui_agent]semantic_ui50backend: semantic_ui无障碍 API 键盘xdotoolrecovery10backend: recovery重试 回退编排路由引擎的逻辑值得展开routing.py尊重显式声明如果步骤声明了backend:且该后端在当前环境可用is_available()为真就直接选用按优先级兜底降级若声明的后端不可用例如缺xdotool引擎按优先级从高到低遍历查找第一个可用的后端——recovery永远不会被自动兜底选中select()中显式continue跳过它只能被显式声明触发若全部不可用抛出RuntimeError提示检查缺失工具。7 个后端为什么必要MACROCLI.md 的设计决策部分解释得很直白真实 GUI 应用暴露的控制面五花八门native_api只覆盖有 CLI/API的应用对没有稳定接口的应用visual_anchor用模板匹配做稳健的 UI 元素定位gui_agent则用视觉模型在 UI 状态不可预测时做动态决策semantic_ui走无障碍树加键盘。路由引擎的目标是让Agent 不必关心最终是哪个后端执行了步骤只对结果负责。编写自己的宏YAML Schema 详解宏是以 YAML 文件形式存放在cli_anything/macrocli/macro_definitions/及子目录中的。SKILL.md 建议用脚手架命令生成初始骨架cli-anything-macrocli macro define my_macro --output \ cli_anything/macrocli/macro_definitions/examples/my_macro.yaml不传--output/-o时模板直接打印到 stdout传入路径时自动创建父目录并写入。生成后的模板同样由 CLI 的macro define命令提供见 macrocli_cli.py。下面是最小 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 # 或: 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字段级语义结合 macro_model.py 解析从 macro_model.py 的数据类可以看出各字段的精确定义与约束parametersMacroParametertype支持string | integer | float | boolean | list | dictCLI 的macro define模板注释里也允许用更全的写法transform_json.yaml的示例全部用string也支持简写形式parameter_name: string解析器会将其视为仅声明 type。required必填标志运行时validate_params对缺省必填参数会报错。default可选项resolve_params在运行前用默认值补齐缺失参数schema 之外的额外参数会被透传。enum/min/max对值域进行约束integer 类型参与 min/max 数值比较、enum 做成员校验例如 export_file.yaml 中format参数声明了enum: [plain, json, csv]。description/example供macro info展示与 Agent 自学不是运行时约束。preconditions / postconditionsMacroCondition条件是单键 dict支持的完整类型MACROCLI.md 有表runtime.py 的_check_condition有实现类型参数形式判定逻辑file_exists路径os.path.exists(path)file_size_gt[path, min_bytes]os.stat(path).st_size min_bytesprocess_running进程名pgrep -x name失败后尝试 psutilenv_var环境变量名name in os.environalwaystrue/false恒真/恒假条件参数同样支持${var}替换_check_condition内部先substitute再判定。未知条件类型不会阻断执行仅告警放行。stepsMacroStepid步骤标识缺省自动生成step_ibackendaction后端名与后端专属动作如native_apirun_command、file_transformjson_set/text_replace、visual_anchor 模板动作等params动作参数支持${key}占位符递归替换——substitute()会递归处理 string/list/dict遇到整数、布尔等非字符串类型原样保留timeout_ms默认 30000on_failurefail | skip | continue。三者语义runtime.pyfail立即中断并置宏为失败skip跳过失败步骤继续后续步骤continue无视错误继续。MACROCLI.md 的解释是有些步骤是 best-effort例如确认一个可能不出现的对话框skip/continue 让宏不必为了琐碎弹窗而整体失败重试策略retry_policy: {max_retries, backoff_ms}或顶层retry_max由 RoutingEngine 在execute_step中按 backoff 序列执行带退避的重试。outputsMacroOutput命名输出path或value二选一运行时做${}替换后放进结果outputdict_collect_outputs还会额外塞入_steps键保存每个步骤的原始输出。Agent 从output里取走声明过的产物路径如exported_file即可进行后续处理。agent_hints仅供 Agent 决策使用的元数据danger_levelsafe/moderate/dangerous、side_effects如creates_file、modifies_file、reversible。例如 transform_json.yaml 声明了danger_level: moderate、side_effects: [modifies_file]、reversible: false——因为它是原地改写文件不可逆而 export_file 示例则声明为 safe 且可逆。一个真实的双后端宏示例export_file.yaml 展示了宏内多步骤混用不同后端的写法——第一段用native_api跑导出命令第二段用file_transform的text_replace落盘一个标记文件best-efforton_failure: skipsteps: - id: step_export backend: native_api action: run_command params: # 换成真实应用的导出命令例如 # command: [inkscape, --export-filename, ${output}, ${input}] command: [echo, Exported to ${output} (format${format})] capture_stdout: true timeout_ms: 30000 on_failure: fail - id: step_write_output backend: file_transform action: text_replace params: input_file: /dev/null output_file: ${output} find: replace: on_failure: skip # 写标记文件是 best-effort注册表如何发现宏macro list默认扫描包内macro_definitions/目录registry.py 中Path(__file__).../macro_definitions。扫描策略若存在 manifest.yaml 则按其中显式索引加载否则递归扫描目录下所有*.yaml。manifest.yaml用于声明顺序/白名单。录制产出的宏包可通过--macro-file直接执行绕开注册表——CLI 内部为此构造了一个只含单个宏的临时 registry。Agent 使用规则六条铁律SKILL.md 列出的 Agent 行为准则值得完整保留它们是让 Agent 与 CLI 可靠协作的经验沉淀永远使用--json获取程序化输出避免解析人类可读文本执行有副作用的宏之前先用--dry-run校验参数runtime.execute(..., dry_runTrue)在 BackendContext 中传递dry_run标志各后端据此跳过真实副作用检查success字段——不能只凭退出码假设成败当success为 false 时读取error字段它说明了失败原因调用macro run前先用macro info name发现参数——宏的 schema 是动态的先读后调是避免参数错配的关键所有文件参数使用绝对路径。完整工作流实战transform_json结合仓库内真实定义把整套规则串起来就是 SKILL.md 的 Example Workflow# Step 1: 看有哪些宏 cli-anything-macrocli macro list --json # Step 2: transform_json 需要哪些参数 cli-anything-macrocli macro info transform_json --json # Step 3: 安全试跑 cli-anything-macrocli --dry-run macro run transform_json \ --param file/tmp/config.json \ --param keytheme \ --param valuedark --json # Step 4: 正式执行 cli-anything-macrocli macro run transform_json \ --param file/tmp/config.json \ --param keytheme \ --param valuedark --json对应 transform_json.yaml前置条件file_exists: ${file}保证文件存在唯一步骤用file_transformjson_set把settings.theme这类点分键路径写成新值并原文件落盘后置条件再次file_exists确认输出命名modified_file。这展示了一个读 JSON → 改嵌套键 → 写回的完整可复用数据变更宏。从录制到生成把新 GUI 流程变成宏除手写 YAML 外CLI 还提供四条造宏路径源码见 macrocli_cli.pymacro record name录制 GUI 交互并生成宏包目录name/macro.yamlsnapshots/。支持组合选项--agent-review录制后交互式把某些步骤标记为需要视觉模型的 agent step、--parameterize交互式挑选哪些输入值变成 CLI 参数、--auto-parameterize用 LLM 自动建议参数名需要--api-key或MACROCLI_API_KEY--parameterize与--auto-parameterize互斥。底层由 core/recorder.py 实现需pip install mss Pillow pynput。录制完成后按 CtrlAltS 停止macro parameterize yaml对既有 YAML 中硬编码的type_text步骤做参数化--auto模式下用 LLM 建议参数名并按实际值自动推断类型string/integer/floatmacro assist name --goal ...截屏后发送给视觉模型按自然语言目标直接生成宏 YAML需pip install openai mss Pillow产物若涉及视觉模板会列出待捕获模板清单macro capture-template out.png --x --y --width --height按矩形坐标捕获屏幕区域存为模板 PNG供visual_anchor模板匹配类步骤使用backends/visual_anchor.py。会话与遥测让 Agent 可回溯session子命令组的底层是 core/session.py 的ExecutionSession每次macro run都会生成一条RunRecordmacro 名、参数、成败、输出、错误、耗时、所用后端、步骤数保存在进程内历史中上限 200 条session save通过带文件锁的原子写把会话 JSON 持久化到~/.macrocli/sessions/session_id.json--session-id可让多次调用共享同一命名会话session list按时间倒序列出历史会话及运行数。借助session historyAgent 可以复盘刚才那条宏为什么失败、走了哪个后端、花了多少毫秒。为什么这么设计三处关键权衡MACROCLI.md 的 Design Decisions 部分给出了官方解释这里结合源码略作归纳为什么用 YAML 而非 Python 定义宏YAML 宏不需要运行代码即可被 Agent 阅读可通过macro info检视也可在不动 harness 源码的前提下直接编辑/分享——声明式格式天然适合作为Agent 与自动化之间的契约。为什么要 7 个后端不同 GUI 应用的控制面差异巨大visual_anchor用模板匹配做稳健定位gui_agent在 UI 状态不可预测时交给视觉模型动态决策路由引擎负责挑最可靠且可用的那一个把复杂性收敛在 L2/L3 层。为什么要有前后置条件Agent 运行环境状态不确定前置条件执行前大声失败、后置条件执行后验证把问题暴露成 Agent 可行动的错误信息而非静默的坏结果。加上on_failure: skip/continue让宏能容忍 best-effort 步骤的偶发失败例如一个时有时无的确认对话框。版本与适用边界本包当前版本为1.0.0见 SKILL.md 末尾及 REPL banner 中的ReplSkin(macrocli, version1.0.0)。文中描述的命令、schema 与行为均以当前仓库 macrocli/agent-harness 内代码为准gui_agent、visual_anchor、gui_macro、semantic_ui等后端依赖可选 extra 或系统工具实际可用性以cli-anything-macrocli backends --json的输出为准。若要在自己的环境中运行请先确保满足上文安装与运行环境要求一节列出的依赖再进行录制与执行类操作。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考