Reasonix 下的 CLI-Anything：让编码 Agent 构建 Agent-Native CLI Harness 的完整技能适配指南-创锋一号

Reasonix 下的 CLI-Anything：让编码 Agent 构建 Agent-Native CLI Harness 的完整技能适配指南

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

导读

本文围绕 reasonix-skill/SKILL.md 展开，讲解如何将 CLI-Anything 的 Harness 构建方法论完整适配到 Reasonix 编码 Agent 上，使 Reasonix 能够像 CLI-Anything Builder 一样，针对任意 GUI 应用或源码仓库完成**构建（Build）、精化（Refine）、测试（Test）、校验（Validate）**四类任务。读完本文，你将掌握：该 Skill 的安装与调用方式、Reasonix 内置工具与 Harness 工作流的绑定关系、完整的 7 阶段构建流程、四模式的操作规范、后端与打包的硬性规则，以及 Step Budget 配置对构建成败的关键影响。

该 Skill 位于 reasonix-skill/，是 CLI-Anything 仓库中继 Codex、Hermes 等适配器之后的又一个 Agent 适配层，其核心设计原则是：在不改变生成的 Python Harness 格式的前提下，把 CLI-Anything 的方法论“移植”到 Reasonix 的工具集上。

Skill 的定位与元数据

reasonix-skill/SKILL.md的 YAML Frontmatter 直接定义了该 Skill 的触发条件与执行模型：

--- name: cli-anything description: Use when the user wants Reasonix to build, refine, test, or validate a CLI-Anything harness for a GUI application or source repository. Adapts the CLI-Anything methodology to Reasonix without changing the generated Python harness format. runAs: subagent ---

关键信息有三点：

name：cli-anything，是 Reasonix 中该 Skill 的全局注册名；
description：明确了 Skill 的适用场景——当用户希望 Reasonix 针对 GUI 应用或源码仓库构建/精化/测试/校验 Harness 时触发；
runAs: subagent：表示该 Skill 以子代理（subagent）身份运行，这与 README 中提到的run_skill隔离执行路径一致（详见下文"两种调用方式"）。

与之配套的 agents/reasonix.yaml 提供了 Agent 接口元数据，包括展示名CLI-Anything、短描述以及默认提示词Use CLI-Anything to build, refine, test, or validate a harness for the user's target software or source repository.，这是 Reasonix 侧识别与加载该 Skill 的入口。

安装与两种调用方式

安装脚本与安装目标

仓库提供了跨平台的安装脚本：

macOS / Linux：执行 scripts/install.sh；
Windows (PowerShell)：执行 scripts/install.ps1。

从脚本源码可以确认其行为：

install.sh将 Skill 目录整体复制到${HOME}/.reasonix/skills/cli-anything（install.ps1对应%USERPROFILE%\.reasonix\skills\cli-anything）；
若目标目录已存在，脚本拒绝覆盖并提示手动删除后重装（install.sh中if [[ -e "${DEST_DIR}" ]]; then ... exit 1，install.ps1中if (Test-Path $destDir) { Write-Error ... }）；
安装完成后需要重启 Reasonix才能加载新 Skill。

两种调用方式

安装后有两种使用方式（见 reasonix-skill/README.md）：

方式一：斜杠命令（Slash Invocation）——将 Skill 内联进父级 Reasonix 循环：

/cli-anything https://github.com/GNOME/gimp

方式二：run_skill 子代理执行——需要隔离执行时使用：

run_skill({ name: "cli-anything", arguments: "/path/to/software" })

输入参数有两种形式：本地源码路径（如./gimp、/path/to/software）或 GitHub 仓库 URL；若使用 URL，克隆后以本地目录名推导软件名。

方法论的来源优先级：先读 HARNESS.md

Skill 明确要求：动手实现之前，必须先获取 CLI-Anything 方法论的全量事实来源（source of truth），按以下优先级进行：

若当前工作区就是 CLI-Anything 仓库，读取cli-anything-plugin/HARNESS.md；
若 Reasonix 正从本适配目录运行，检查../cli-anything-plugin/HARNESS.md；
若上述本地文件均不可用，克隆或下载cli-anything-plugin仓库后，使用其中的HARNESS.md及其周边资源；
仅当本地与网络获取全部失败时，才回退到 SKILL.md 中内嵌的精简规则。

这一设计保证了 Reasonix 生成的 Harness 与 CLI-Anything 官方 SOP 完全一致。cli-anything-plugin/HARNESS.md中定义了完整的 7 阶段 SOP（见下文），是任何 Harness 构建的"宪法"。

Reasonix 工具绑定：一张表看懂 Harness 工作流

SKILL.md 的核心内容之一是Reasonix Tool Bindings表，它将 Reasonix 内置工具与 Harness 工作流中的角色一一对应：

Reasonix 工具	在 Harness 工作流中的角色
`bash`	运行 Shell 命令、安装依赖包、执行 CLI 工具、运行测试、克隆仓库
`write_file`	生成 Python 文件（Click CLI、后端模块、测试、setup.py）
`edit_file`	对生成的代码做定点编辑（单次替换）
`multi_edit`	一次通过中批量对单个文件施加多个原子编辑
`read_file`	读取目标软件源码、已有 Harness 代码、测试结果
`grep`	跨目标软件代码库搜索模式（API、CLI 工具、数据模型）
`glob`	在源码树中按模式查找文件（.py、.xml、*.json 等）
`ls`	列出目录内容，理解项目结构
`mcp__codegraph__search`/`mcp__codegraph__context`	可选的代码图谱分析（CodeGraph 启用时可用；Reasonix 会剥离`codegraph_`原始前缀，因此模型可见名称不带此前缀）
`web_fetch`	从网络抓取文档、API 参考或远端文件

各阶段工具编排建议

SKILL.md 给出了按阶段使用工具的推荐编排：

Phase 1（分析）：用ls+glob扫描源码树，用grep定位 API 表面与 CLI 入口点，用read_file检查关键文件；若 CodeGraph 已启用且工具可用，用mcp__codegraph__search/mcp__codegraph__context做更深入的符号与架构分析。
Phase 2-3（设计与实现）：用write_file创建新的 Harness 文件，用edit_file/multi_edit精化生成的代码，用bash执行pip install -e .完成本地安装。
Phase 4-6（测试）：用bash运行pytest并捕获结果，用read_file检查测试输出，用write_file更新TEST.md。
Phase 7（打包）：用write_file编写setup.py，用bash执行pip install -e .并用which cli-anything-<software>验证安装产物。

相比 Codex 适配器的"文件操作走execute_code"模式，Reasonix 提供了更细粒度的write_file/edit_file/multi_edit文件操作集，并且支持可选的 CodeGraph 符号图谱分析，这是它在工具绑定上的显著差异（对比表见 reasonix-skill/README.md 的 "How It Compares to Other Agent Adapters" 一节）。

Step Budget：决定构建能否跑完的关键配置

一个完整的 Harness 构建通常需要25–40 轮工具调用（架构检查、10+ 个文件写入、安装、多次测试运行）。通过run_skill调用时，子代理会继承由父代理reasonix.toml中agent.max_steps设置推导出的步数预算：

max_steps = 0（默认值，表示无限）时，子代理也无步数上限——这是 CLI-Anything 工作流推荐的配置；
若max_steps设置为有限值，子代理只能获得一半预算（下限 5），这可能在复杂构建完成之前就将其截断。

因此，凡是配置了有限max_steps的用户，在运行 CLI-Anything 构建前，应确保其值为0或足够大（例如 ≥ 64），以保证子代理有足够的轮次完成全部 7 个阶段。

四模式操作规范

SKILL.md 定义了四个工作模式，分别对应 Harness 生命周期中的不同任务。

Build：从零构建新 Harness

当用户需要一个新的Harness 时使用。产出结构如下：

<repo-root>/ ├── skills/ │ └── cli-anything-<software>/ │ └── SKILL.md └── <software>/ └── agent-harness/ ├── <SOFTWARE>.md ├── setup.py └── cli_anything/ └── <software>/ ├── README.md ├── __init__.py ├── __main__.py ├── <software>_cli.py ├── core/ ├── utils/ ├── tests/ └── skills/ └── SKILL.md

需要实现一个有状态的 Click CLI，必须具备：

一次性子命令（one-shot subcommands）；
REPL 模式作为无子命令时的默认行为；
--json机器可读输出；
在目标软件支持的情况下提供带 undo/redo 的会话状态。

Refine：精化已有 Harness

当 Harness 已存在时使用。流程是：先盘点当前命令与测试，再针对目标软件做差距分析（gap analysis）。优先级建议：

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

除非用户明确要求破坏性变更，否则不得移除现有命令。

Test：测试规划与执行

在写测试代码之前先规划。保持两类测试并存：

test_core.py：单元覆盖；
test_full_e2e.py：工作流与后端验证。

在可能的情况下，通过子进程测试已安装的命令cli-anything-<software>，而不仅限于模块导入。

Validate：Harness 合规性检查

校验 Harness 是否满足以下约束：

使用cli_anything.<software>命名空间包布局；
具备可安装的setup.py入口点；
支持 JSON 输出；
有 REPL 默认路径；
规范版（canonical）与包内（package-local）两份SKILL.md文件内容一致；
有使用文档与测试文档。

后端规则：优先真实软件，禁止重实现

Backend Rules是 CLI-Anything 方法论的第一铁律：优先使用真实软件后端，而不是用 Python 重实现软件功能。具体做法是把真实可执行程序或脚本接口封装在utils/<software>_backend.py中；只有当项目明确要求或不存在可用的原生后端时，才使用合成（synthetic）重实现。

cli-anything-plugin/HARNESS.md对此有更详尽的展开，列举了各软件的后端调用模式：

软件	后端 CLI	原生格式	CLI 如何使用它
LibreOffice	`libreoffice --headless`	.odt/.ods/.odp (ODF ZIP)	生成 ODF → 转换为 PDF/DOCX/XLSX/PPTX
Blender	`blender --background --python`	.blend-cli.json	生成 bpy 脚本 → Blender 渲染为 PNG/MP4
GIMP	`gimp -i -b '(script-fu ...)'`	.xcf	Script-Fu 命令 → GIMP 处理并导出
Inkscape	`inkscape --actions="..."`	.svg (XML)	操作 SVG → Inkscape 导出为 PNG/PDF
Shotcut/Kdenlive	`melt`或`ffmpeg`	.mlt (XML)	构建 MLT XML → melt/ffmpeg 渲染视频
Audacity	`sox`	.aup3	生成 sox 命令 → sox 处理音频
OBS Studio	`obs-websocket`	scene.json	WebSocket API → OBS 捕获/录制

底层实现模式恒定不变：构建数据 → 调用真实软件 → 验证输出。后端模块（如 LibreOffice 示例中的utils/lo_backend.py）通常负责：用shutil.which()定位可执行程序、用subprocess.run()以正确参数调用、在未找到时抛出带安装指引的清晰错误。

打包规则：PEP 420 命名空间包

Packaging Rules规定了 Harness 必须遵循的打包约束：

使用find_namespace_packages(include=["cli_anything.*"])；
cli_anything/作为命名空间包，顶层不放置__init__.py（这是 PEP 420 的关键：多个独立安装的 PyPI 包可以各自向cli_anything/贡献子包而不冲突，例如cli-anything-gimp贡献cli_anything/gimp/，cli-anything-blender贡献cli_anything/blender/）；
通过console_scripts暴露cli-anything-<software>命令；
将cli_anything.<software>/skills/SKILL.md纳入 package data（package_data={"cli_anything.<software>": ["skills/*.md"]}），确保 pip 安装后仍随包附带本地 Skill 文件。

七步工作流与七阶段方法论

SKILL.md 的 Workflow 节给出了构建 Harness 的 7 个步骤：

在本地获取源码树（克隆或使用已有路径）；
分析架构、数据模型、已有 CLI 与 GUI 到 API 的映射；
设计命令组与状态模型；
实现 Harness；
先写TEST.md，再写测试并运行；
更新 README 使用文档，并同时生成skills/cli-anything-<software>/SKILL.md与cli_anything/<software>/skills/SKILL.md两份 Skill；
用pip install -e .验证本地安装。

这与 reasonix-skill/README.md 中总结的CLI-Anything 7 阶段方法论一一对应：

Codebase Analysis— 扫描目标软件的架构、数据模型与 API 表面；
CLI Architecture Design— 设计命令组、状态模型与输出格式；
Implementation— 生成基于 Click 的 Python CLI，带 REPL、JSON 输出与会话状态；
Test Planning— 创建包含完整测试计划的TEST.md；
Test Implementation— 编写单元测试与真实后端调用的 E2E 测试；
Test Documentation— 运行全部测试并记录结果（追加回TEST.md）；
PyPI Packaging— 创建setup.py并验证pip install -e .。

七阶段中的关键实现要点（HARNESS.md 补充）

Phase 3 的 REPL 默认行为：在主 Click 组上使用invoke_without_command=True，无子命令时调用repl命令——这保证了无参数运行cli-anything-<software>即进入 REPL。
Phase 4 的 TEST.md 规划：在写任何测试代码前创建TEST.md，必须包含测试清单计划、单元测试计划（模块/函数/边界情况/预期数量）、E2E 测试计划（真实工作流、真实文件、输出属性验证、格式校验）以及多步骤真实工作流场景。
Phase 5 的四层测试策略：单元测试（合成数据、无外部依赖）；原生 E2E（验证中间文件结构正确）；真实后端 E2E（调用真实软件，验证输出存在、大小 > 0、magic bytes 正确如%PDF-，并打印产物路径供人工检查）；CLI 子进程测试（通过_resolve_cli辅助函数以真实用户/Agent 的方式调用已安装的cli-anything-<software>命令）。不做优雅降级——软件未安装时测试应失败而非跳过。
Phase 6.5 的 SKILL.md 生成：规范版 Skill 位于skills/cli-anything-<software>/SKILL.md，兼容副本写入cli_anything/<software>/skills/SKILL.md；可用skill_generator.py自动提取 CLI 元数据生成，或用templates/SKILL.md.template的 Jinja2 模板定制。
Phase 7 的命名空间包规则：cli_anything/无__init__.py，子包（gimp/、blender/等）各有自己的__init__.py。

已有 Harness 参考与 Registry

SKILL.md 提示：需要最新的 Harness 支持列表及其后端模式时，可定位 CLI-Anything 仓库根目录的registry.json。当前仓库的 registry.json 收录了数十个 Harness 条目，每个条目包含名称、显示名、版本、描述、依赖（requires）、安装命令（pip install git+...#subdirectory=<software>/agent-harness）、入口点（cli-anything-<software>）、Skill 路径（skills/cli-anything-<software>/SKILL.md）与贡献者等信息；对应的skills/目录下（见 skills/）已经就位了 70 余份cli-anything-<software>/SKILL.md，覆盖 GIMP、Blender、LibreOffice、Shotcut、QGIS、Zotero 等广泛领域，可作为新 Harness 的结构与深度参考。

输出期望：进度与结果的汇报规范

无论汇报进度还是最终结果，都必须包含：

目标软件与源码路径；
新增或变更的文件；
已运行的验证命令；
开放风险或后端限制。

这套汇报规范保证了 Reasonix 父代理能持续跟踪子代理的构建进度，并在发现后端限制时及时介入。

小结

reasonix-skill/SKILL.md是一个结构完整、可直接投入实战的 Agent 适配技能：它以 CLI-Anything 官方 HARNESS.md 为方法论事实来源，将 Reasonix 的内置工具逐一映射到 Harness 构建工作流，明确定义了 Build/Refine/Test/Validate 四模式、后端真实调用原则、PEP 420 打包约束与 Step Budget 配置要求。任何 Reasonix 用户在完成安装（install.sh/install.ps1→~/.reasonix/skills/cli-anything）并将agent.max_steps设为0或 ≥ 64 后，即可通过/cli-anything或run_skill让 Reasonix 为任意 GUI 软件生成符合官方标准的 Agent-Native CLI Harness。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析