CLI-Anything for OpenClaw构建 Agent 原生 GUI 命令行 Harness 的完整方法论【免费下载链接】CLI-AnythingCLI-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/softwareGitHub 仓库 URL。克隆之后若用户未指定软件名则从本地目录名推导软件名例如目录名为gimp则软件名为gimp对应 Python 包cli_anything.gimp。这一规则意味着目录名即包名是整个 monorepo 的组织约定仓库中 skills 目录下的cli-anything-*子目录正是按此命名的。四种工作模式Build / Refine / Test / ValidateBuild从零生成新 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.mdsetup.py提供cli-anything-macrocli控制台入口见 entry_points 配置macrocli_cli.py即software_cli.py的落地主入口是一个click.group(invoke_without_commandTrue)的状态化 CLI。SKILL.md 强调必须实现一个状态化 Click CLI并具备四个特性一次性子命令one-shot subcommands供脚本与流水线调用REPL 作为默认模式——无子命令参数时直接进入交互式 REPL。实现上采用invoke_without_commandTrue 空子命令时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, indent2)否则输出人类可读的键值树见 macrocli_cli.py#L56-L83会话状态与 undo/redo——在目标软件支持的场景下提供。MacroCLI 的会话实现位于core/session.pyExecutionSessionRunRecord通过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.pyMACROCLI.md 记载 49 个单测与test_full_e2e.py15 个 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_INSTALLED1强制使用已安装命令。Validate逐项校验 Harness 合规性Validate 模式是质量闸门逐项核对 Harness 是否满足校验项说明仓库佐证命名空间包布局使用cli_anything.softwaresetup.py中find_namespace_packages(include[cli_anything.*])可安装入口存在可安装的setup.pyentry pointconsole_scripts暴露cli-anything-macrocliJSON 输出支持--jsonCLI 全局标志 output()分支REPL 默认路径有 REPL 默认入口invoke_without_commandTrue时空子命令进入 repl文档完备使用方式与测试均有文档每目录必含README.md与TEST.mdBackend 规则包装真实软件而非重写这是全仓库方法论的头号规则SKILL.md 亦将其列为强制约束优先使用真实软件后端不要重写实现。应尽可能在utils/software_backend.py中包装真实可执行文件或脚本接口仅当项目明确要求、或不存在可行的原生后端时才允许使用合成实现synthetic reimplementation。MacroCLI 把这一思路推向极致——由于目标是 GUI-first/闭源软件它抽象出7 个执行后端Execution Backends由 RoutingEngine 依据优先级自动挑选Agent 无需关心实际由哪个后端执行见 MACROCLI.md 的 Layer Mapping后端优先级触发字段用途native_api100backend: native_apisubprocess / 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重试 回退编排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-macroclicli_anything.macrocli.macrocli_cli:cli同时在__main__.py中支持python3 -m cli_anything.macrocli。安装命令含运行时依赖与可选 extrascd 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_KEYAPI 密钥、MACROCLI_BASE_URL仅非 OpenAI 宿主需要。标准工作流WorkflowSKILL.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.pymacro_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记录遥测telemetryduration_ms、steps_total、steps_run、backends_used、dry_run返回ExecutionResult{success, output, error, telemetry}。从状态化 CLI 到状态机的验证condition 类型runtime.py中_check_condition实现的支持条件类型与 MACROCLI.md 的条件表 完全一致且都支持${param}替换类型参数检查实现file_existspathos.path.exists(path)file_size_gt[path, min_bytes]os.stat(path).st_size min_bytesprocess_runningname优先pgrep -x name无 pgrep 则回退 psutilenv_varnamename in os.environalwaystrue/false常量通过与失败宏定义格式与一个完整示例宏以 YAML 文件存放于cli_anything/macrocli/macro_definitions/examples、demo 与 manifest.yaml 齐备SKILL.md 的标准产物即可通过如下命令 scaffoldcli-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_hintsdanger_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 模式能够持续推进的前提。延伸阅读cli-anything-plugin/HARNESS.md —— 完整方法论权威来源Phase 1-7、架构反模式、目录结构、跨软件适配表、预览与实时预览规范macrocli/agent-harness/MACROCLI.md —— MacroCLI 项目级分析 SOP架构、Layer Mapping、7 后端、关键设计决策macrocli/agent-harness/cli_anything/macrocli/skills/SKILL.md —— 随包安装、面向 Agent 的命令参考与 JSON 契约macrocli/agent-harness/setup.py —— 命名空间打包、extras 与 console_scripts 配置范例macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py —— 状态化 Click CLI REPL 默认路径的参考实现macrocli/agent-harness/cli_anything/macrocli/core/runtime.py —— 宏执行生命周期与 condition 校验源码macro_definitions 目录 —— 可直接参考的宏定义 YAML 集合。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考