CLI-Anything for OpenClaw：构建 Agent 原生 GUI 命令行 Harness 的完整方法论-二趣网

CLI-Anything for OpenClaw：构建 Agent 原生 GUI 命令行 Harness 的完整方法论

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

本指南基于macrocli/SKILL.md，系统阐述如何在 OpenClaw（或其他 AI Agent 环境）中以CLI-Anythingbuilder 的角色，将 GUI 应用或源码仓库构建为"有状态、可执行、可验证、JSON 可解析"的命令行 Harness，并通过仓库内的 MacroCLI 实现说明每条规则在真实代码中的落地形态。读完你将掌握 Build / Refine / Test / Validate 四种工作模式的完整操作流程、目录与打包规范，以及状态化 Click CLI、会话、REPL 与多后端路由的底层设计原理。

技能定位与触发场景

macrocli/SKILL.md是一份面向 Agent 的技能定义文件（Frontmatter 中name: cli-anything），其核心用途是：当用户想让 OpenClaw 扮演CLI-Anything的构建者——为一个 GUI 应用或源码仓库"生成、优化、测试或校验"一份 CLI Harness 时触发。它强调的是把 CLI-Anything 方法论文档适配到 OpenClaw，同时不改动所生成 Python Harness 的标准格式，从而保证不同 Agent 宿主下产出的 Harness 结构一致、可被同一套工具链消费。

值得注意的纪律约束：当该技能在CLI-Anything仓库内部使用时，SKILL.md 要求先阅读 cli-anything-plugin/HARNESS.md——这是完整方法论的"权威来源"（source of truth）；若该方法论文件不可用，才退回到 SKILL.md 中的浓缩规则。这与仓库布局中cli-anything-plugin（方法论与工具插件）与各软件目录（具体产物）相互分离的结构一一对应。

输入与软件名推导

技能接受两类输入：

本地源码路径，如./gimp或/path/to/software；
GitHub 仓库 URL。

克隆之后，若用户未指定软件名，则从本地目录名推导软件名（例如目录名为gimp则软件名为gimp，对应 Python 包cli_anything.gimp）。这一规则意味着"目录名即包名"是整个 monorepo 的组织约定，仓库中 skills 目录下的cli-anything-*子目录正是按此命名的。

四种工作模式：Build / Refine / Test / Validate

Build：从零生成新 Harness

当用户需要一个全新的 Harness 时，必须产出如下标准目录结构：

<software>/ └── agent-harness/ ├── <SOFTWARE>.md ├── setup.py └── cli_anything/ └── <software>/ ├── README.md ├── __init__.py ├── __main__.py ├── <software>_cli.py ├── core/ ├── utils/ └── tests/

对照仓库中的具体实例 macrocli/agent-harness，该结构被完整实现：

<SOFTWARE>.md（项目级分析 SOP）→ macrocli/agent-harness/MACROCLI.md；
setup.py提供cli-anything-macrocli控制台入口（见 entry_points 配置）；
macrocli_cli.py即<software>_cli.py的落地，主入口是一个click.group(invoke_without_command=True)的状态化 CLI。

SKILL.md 强调必须实现一个状态化 Click CLI，并具备四个特性：

一次性子命令（one-shot subcommands），供脚本与流水线调用；
REPL 作为默认模式——无子命令参数时直接进入交互式 REPL。实现上采用invoke_without_command=True+ 空子命令时ctx.invoke(repl)，见 macrocli_cli.py#L136-L165 与repl命令实现（其中通过shlex.split解析输入行、以cli.make_context(...)+cli.invoke(...)复用同一套 Click 命令分发，见 macrocli_cli.py#L898-L971）；
--json机器可读输出——macrocli_cli.py的全局_json_output标志配合output()帮助函数，在 JSON 模式输出json.dumps(data, indent=2)，否则输出人类可读的键值树（见 macrocli_cli.py#L56-L83）；
会话状态与 undo/redo——在目标软件支持的场景下提供。MacroCLI 的会话实现位于core/session.py（ExecutionSession+RunRecord），通过session status / history / save / list子命令暴露，并支持--session-id恢复或创建命名会话（见 macrocli_cli.py#L158-L160）。

Refine：在已有 Harness 上做差距分析

当 Harness 已存在时，进入 Refine 模式。流程是：先盘点（inventory）现有命令与测试，再针对目标软件做差距分析（gap analysis）。选点优先级为：

高影响力的缺失功能；
对已有后端 API 或 CLI 的轻量封装（easy wrappers）；
与既有命令组合良好的增量。

同时有一条明确的红线：除非用户明确要求 breaking change，否则不得删除既有命令。这与cli-anything-plugin/HARNESS.md中"项目分析先行、目录化 GUI 操作到 API 调用映射"的 Phase 1 方法论一致。

Test：先计划、后编写、双轨并进

Test 模式要求在写任何测试代码之前先做计划，且始终维护两个测试文件：

test_core.py——单元覆盖（合成数据、无外部依赖）；
test_full_e2e.py——工作流与真实后端校验。

MacroCLI 的测试目录 tests 即包含test_core.py（MACROCLI.md 记载 49 个单测）与test_full_e2e.py（15 个 E2E + CLI 子进程测试），合计 64 个测试。运行方式：

cd macrocli/agent-harness python3 -m pytest cli_anything/macrocli/tests/ -v -s

关键要求是：尽可能通过子进程测试"已安装的命令"cli-anything-<software>，而非仅仅做模块级 import 测试。这与cli-anything-plugin/HARNESS.md中_resolve_cli()辅助函数的设计一致——先shutil.which(name)找已安装命令，找不到再回退python3 -m，并支持CLI_ANYTHING_FORCE_INSTALLED=1强制使用已安装命令。

Validate：逐项校验 Harness 合规性

Validate 模式是质量闸门，逐项核对 Harness 是否满足：

校验项	说明	仓库佐证
命名空间包布局	使用`cli_anything.<software>`	`setup.py`中`find_namespace_packages(include=["cli_anything.*"])`
可安装入口	存在可安装的`setup.py`entry point	`console_scripts`暴露`cli-anything-macrocli`
JSON 输出	支持`--json`	CLI 全局标志 +`output()`分支
REPL 默认路径	有 REPL 默认入口	`invoke_without_command=True`时空子命令进入 repl
文档完备	使用方式与测试均有文档	每目录必含`README.md`与`TEST.md`

Backend 规则：包装真实软件，而非重写

这是全仓库方法论的头号规则，SKILL.md 亦将其列为强制约束：优先使用真实软件后端，不要重写实现。应尽可能在utils/<software>_backend.py中包装真实可执行文件或脚本接口；仅当项目明确要求、或不存在可行的原生后端时，才允许使用合成实现（synthetic reimplementation）。

MacroCLI 把这一思路推向极致——由于目标是 GUI-first/闭源软件，它抽象出7 个执行后端（Execution Backends），由 RoutingEngine 依据优先级自动挑选，Agent 无需关心实际由哪个后端执行（见 MACROCLI.md 的 Layer Mapping）：

后端	优先级	触发字段	用途
`native_api`	100	`backend: native_api`	subprocess / shell 命令
`gui_macro`	80	`backend: gui_macro`	预编译坐标回放（pyautogui）
`visual_anchor`	75	`backend: visual_anchor`	模板匹配点击/输入（需`[visual]`额外依赖）
`file_transform`	70	`backend: file_transform`	XML、JSON、文本文件编辑
`gui_agent`	60	`backend: gui_agent`	视觉模型驱动的自动化（需`[gui_agent]`）
`semantic_ui`	50	`backend: semantic_ui`	无障碍 API + 键盘（xdotool）
`recovery`	10	`backend: recovery`	重试 + 回退编排

RoutingEngine 尊重 step 中显式声明的backend:字段；若该后端不可用，则沿优先级列表向下寻找可用的替代后端。

Packaging 规则

SKILL.md 规定三条打包铁律，仓库的 setup.py 逐条落实：

find_namespace_packages(include=["cli_anything.*"])——只打包命名空间包下的子包；
cli_anything/保持为命名空间包、顶层没有__init__.py——这是 PEP 420 namespace package 的关键，使多个独立安装的 PyPI 包（如cli-anything-gimp、cli-anything-blender、cli-anything-macrocli）能在同一 Python 环境内各自贡献cli_anything/下的一个子包而互不冲突；
通过console_scripts暴露cli-anything-<software>——即cli-anything-macrocli=cli_anything.macrocli.macrocli_cli:cli，同时在__main__.py中支持python3 -m cli_anything.macrocli。

安装命令（含运行时依赖与可选 extras）：

cd macrocli/agent-harness pip install -e . # 运行时：Python 3.10+, PyYAML, click, prompt-toolkit pip install -e ".[visual]" # visual_anchor 后端（mss, Pillow, numpy, pynput） pip install -e ".[gui_agent]" # gui_agent 后端（openai, mss, Pillow） pip install -e ".[all]" # 全部

其中gui_agent后端基于 OpenAI SDK 且兼容任何 OpenAI-compatible API，通过环境变量配置：MACROCLI_MODEL（模型名，必填）、MACROCLI_API_KEY（API 密钥）、MACROCLI_BASE_URL（仅非 OpenAI 宿主需要）。

标准工作流（Workflow）

SKILL.md 将 Harness 生产流程固化为七步：

本地获取源码树（acquire the source tree locally）；
分析架构、数据模型、既有 CLI 与 GUI→API 映射；
设计命令组与状态模型；
实现 Harness；
先写TEST.md，再写测试，最后运行它们；
更新 README 使用文档；
用pip install -e .验证本地安装。

状态化 CLI 与宏执行生命周期：MacroCLI 的运行实例

MacroCLI（见 agent-harness/MACROCLI.md）是 SKILL.md 全部规范在"GUI-first / 闭源软件"场景下的完整实例。它的核心哲学正如 SKILL.md 的整体叙事：Agent 永远不直接触碰 GUI——只发送一条命令：

cli-anything-macrocli macro run export_png --param output=/tmp/out.png --json

其余的一切（参数校验、前置条件检查、后端选择、步骤执行、后置条件验证、结构化结果输出）都由系统完成。

其分层架构（见 MACROCLI.md 架构图）把 SKILL.md 的"状态化 CLI"扩展为七层：L7 Agent 任务接口 → L6 统一 CLI 入口（macrocli_cli.py）→ L5 宏执行运行时（core/runtime.py）→ L4 参数化宏模型（core/macro_model.py+macro_definitions/*.yaml）→ L3 后端路由引擎（core/routing.py）→ L2 七个执行后端 → L1 目标应用。

MacroRuntime.execute()的完整生命周期（见 core/runtime.py 的 docstring 与实现）与 SKILL.md 的"状态化 + 前后条件 + 结构化输出"理念一一对应：

从注册表加载宏定义；
解析并校验参数（resolve_params填充默认值、validate_params做类型检查）；
检查前置条件（preconditions）；
逐 step 执行：先对step.params做${param}替换，再由 RoutingEngine 路由到后端执行，并按on_failure: fail | skip | continue处理失败；
检查后置条件（postconditions）；
收集声明的输出（outputs）；
在ExecutionSession记录遥测（telemetry：duration_ms、steps_total、steps_run、backends_used、dry_run）；
返回ExecutionResult{success, output, error, telemetry}。

从状态化 CLI 到状态机的验证：condition 类型

runtime.py中_check_condition实现的支持条件类型与 MACROCLI.md 的条件表完全一致，且都支持${param}替换：

类型	参数	检查实现
`file_exists`	path	`os.path.exists(path)`
`file_size_gt`	[path, min_bytes]	`os.stat(path).st_size > min_bytes`
`process_running`	name	优先`pgrep -x name`，无 pgrep 则回退 psutil
`env_var`	name	`name in os.environ`
`always`	true/false	常量通过与失败

宏定义格式与一个完整示例

宏以 YAML 文件存放于cli_anything/macrocli/macro_definitions/（examples、demo 与 manifest.yaml 齐备），SKILL.md 的标准产物即可通过如下命令 scaffold：

cli-anything-macrocli macro define my_macro --output \ cli_anything/macrocli/macro_definitions/examples/my_macro.yaml

以仓库真实文件 examples/transform_json.yaml 为例，它演示了"读 JSON → 设嵌套键 → 写回"的完整 schema，可作为自定义宏的参照模板：

name: transform_json version: "1.0" description: Read a JSON file, set a nested key to a new value, and write it back. tags: [json, file_transform, example] parameters: file: type: string required: true description: Path to the JSON file to transform. example: /tmp/config.json key: type: string required: true description: Dot-separated key path to set (e.g. settings.theme). example: settings.theme value: type: string required: true description: Value to write at the key path. example: dark preconditions: - file_exists: ${file} steps: - id: step_set_key backend: file_transform action: json_set params: input_file: ${file} output_file: ${file} path: ${key} value: ${value} timeout_ms: 10000 on_failure: fail postconditions: - file_exists: ${file} outputs: - name: modified_file path: ${file} description: Path to the modified JSON file. agent_hints: danger_level: moderate side_effects: [modifies_file] reversible: false

最小 schema 的必填字段包括：name、version、description、parameters（含 type / required / example）、preconditions、steps（含 backend / action / params / timeout_ms / on_failure）、postconditions、outputs与agent_hints（danger_level: safe | moderate | dangerous、side_effects、reversible）。演示用的 gedit 宏位于 macro_definitions/demo，记录/参数化/LLM 辅助生成等进阶 CLI 能力见macro record、macro parameterize、macro assist、macro capture-template的实现。

Agent 使用规则与输出契约

无论构建者是谁（OpenClaw、Claude Code 或其他），消费一个 Harness 的 Agent 都应遵守 SKILL.md 背后贯穿于cli-anything-plugin/HARNESS.md与skills/SKILL.md（随包安装的副本）中的六条纪律：

程序化输出始终使用--json；
执行有副作用的宏之前，先用--dry-run校验参数；
不要仅凭退出码判断成败，必须检查success字段；
success为 false 时读取error字段获取失败原因（失败时退出码为 1）；
调用macro run前，先用macro info <name>发现参数；
所有文件参数使用绝对路径。

--json的成功输出契约（取自 skills/SKILL.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 } }

输出期望（Output Expectations）

当向用户报告进度或最终结果时，必须包含四项要素，这一要求同样适用于本技能的操作者：

目标软件与源码路径；
新增或变更的文件；
运行过的校验命令（validation commands）；
未决风险或后端限制（open risks / backend limitations）。

这一"透明汇报"纪律保证了 Harness 构建过程可审计、可复现，也是 Validate 模式能够持续推进的前提。

企业官网建设流程全解析