CLI-Anything Refine 命令完全指南如何对已有 GUI 应用 CLI Harness 进行增量补全【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读cli-anything-refine是 CLI-Anything 方法论中负责增量演进的命令当一个 GUI 应用已经通过/cli-anything构建出第一版命令行 harness 之后它并不停步于此而是由 Agent 持续分析软件真实能力与当前 CLI 覆盖范围之间的差距迭代式地补齐缺失命令、扩展测试与更新文档。本文以该命令的完整规格为骨架结合仓库内cli-anything-plugin/HARNESS.md的统一规范与 GIMP harness 的真实实现讲解 refine 的两个参数、六步工作流、差距优先级判定标准、实现新命令必须遵循的架构模式以及成功的验收条件——读完你将掌握如何让一个已经可用的 CLI harness 持续逼近软件全部能力的完整实战方法。Refine 是什么构建之后的能力补全循环在 cli-anything.md 中/cli-anything命令负责从零构建一个完整、有状态的 CLI harness其核心产出是一套位于agent-harness/cli_anything/software/下的 Click 命令行、核心模块core/、工具层utils/、测试套件tests/以及软件专属 SOP 文档。而cli-anything-refine明确声明其使用时机是aftera CLI harness has already been built——它不负责创建只负责补全。两者在方法论上是同一枚硬币的两面build 覆盖 Phase 07 的一次性全量交付refine 则开启一个可持续迭代的循环。文档明确指出 refine 的定位分析软件的全部能力与当前 CLI 覆盖范围之间的差距然后迭代式地扩展覆盖如果给了 focus 参数则将分析与实现收窄到该特定功能域。一个关键边界是refine 永不删除已有命令只做增量添加或增强。这保证了每一次 refine 运行都是向前兼容的不会因重构破坏 Agent 与用户已经习惯的调用方式。参数详解$1 软件路径与 $2 聚焦领域$1软件路径必填$1是软件的本地源码路径且必须与当初构建时使用的源码树一致Must be the same source tree used during the original build。例如/home/user/gimp或./blender。这一点至关重要因为 refine 的第二步Analyze Software Capabilities需要重新扫描源码来建立真实能力清单——如果源码树换了版本或分支差距分析的结果就会失真。文档特别强调只接受本地路径如果需要处理 GitHub 仓库必须先通过/cli-anything克隆到本地再对本地副本执行 refine。$2聚焦领域可选$2用自然语言描述希望重点补强的功能区域文档给出的示例包括vid-in-vid and picture-in-picture features视频类软件的画中画能力all batch processing and scripting filters批量处理与脚本化滤镜particle systems and physics simulation粒子系统与物理模拟path boolean operations and clipping路径布尔运算与裁剪当提供了 focus 时整个流程被收窄**Step 2能力分析**只分析指定区域**Step 3差距分析**只将该区域的能力与当前覆盖做对比Agent 仍然需要在实现前向用户展示发现但范围限定在聚焦域内。这一设计让 refine 可以分而治之与其一次试图覆盖整个软件的几百个 API不如一次聚焦一个内聚的功能子集这与文档 Notes 中Each run should focus on a coherent set of related functions的建议完全呼应。六步工作流从盘点现状到文档收尾Step 1盘点当前覆盖Inventory Current Coveragerefine 的第一步不是看软件而是先看自己。Agent 需要读取现有 CLI 入口software_cli.py与所有核心模块列出当前已实现的每个 command、subcommand 与 option阅读现有测试套件理解已覆盖的行为构建一张覆盖地图{ function_name: covered | not_covered }。以仓库中的 gimp_cli.py 为例一个典型的 harness 入口会包含多个 Click command group如project、layer、filter、canvas、media、export全局--json、--project、--dry-run选项以及一个handle_error装饰器统一兜底错误见 gimp_cli.py。盘点阶段就要把这张命令清单完整罗列出来作为后续差距对比的已知项。Step 2分析软件真实能力Analyze Software Capabilities随后 Agent 重新扫描软件源码目标是穷举所有公开 APIpublic APIs自带的 CLI 工具CLI tools脚本化接口scripting interfaces如 GIMP 的 Script-Fu、Blender 的 bpy批处理模式操作batch-mode operations。文档给出一个重要的筛选准则优先关注能产生可观察输出observable output的函数——渲染、导出、变换、格式转换renders, exports, transforms, conversions。这类函数是 CLI 封装价值最高的部分因为它们对应着用户/Agent 真正想要的结果物。随后按领域归类domain例如对 GIMP 而言是filters滤镜、color adjustments颜色调整、layer ops图层操作、selection tools选区工具。归类的好处是让差距报告结构化也便于后续按聚焦域分批实现。这一步还隐含了 HARNESS.md 的方法论要求HARNESS.md 的 Phase 1 强调先识别后端引擎、把 GUI 动作映射到 API 调用、识别数据模型、寻找既有 CLI 工具如libreoffice --headless、blender --background、melt、gimp -i -b这些能力清单正是 refine 差距分析的数据基础。Step 3差距分析Gap Analysis将软件能力全集与CLI 当前覆盖做差集后按三个维度确定优先级优先级维度含义判断要点High impact高影响软件中常用、但 CLI 缺失的功能用户/Agent 最常调用的操作没有命令行入口价值损失最大Easy wins易实现API 简单、可快速封装的功能直接映射到单个后端调用的函数封装成本低、见效快Composability可组合性与已有命令组合能解锁新工作流的功能单独看价值有限但能串联起多步流水线的能力文档明确要求先把差距报告gap report呈现给用户确认要处理哪些差距之后再动手Present the gap report to the user and confirm which gaps to address。这是一个先规划后实施的强制门禁与 Step 2 中 focus 场景下present findings before implementing, but scoped to the focus area的要求一致——用户始终掌握优先级方向盘。Step 4实现新命令Implement New Commands对选定的差距向 CLI 添加新命令/子命令且必须沿用 HARNESS.md 中既有命令的同一套模式。文档明确列出了四条不可妥协的架构约束Click command groups——命令必须是分组结构而非扁平命令--json输出支持——每个命令都必须能输出机器可读的 JSON会话状态集成session state integration——新命令要接入全局 Session 状态用handle_error做错误处理——统一错误兜底与 JSON 化错误输出。同时对应的核心模块函数要落在core/或utils/中而不是把逻辑堆在 CLI 入口里。这些约束都能在仓库源码中找到对应实现。以 GIMP harness 为例handle_error装饰器在 gimp_cli.py 中捕获FileNotFoundError、ValueError/IndexError/RuntimeError、FileExistsError在--json模式下输出{error: ..., type: ...}在 REPL 模式下不退出、一次性命令模式下sys.exit(1)全局会话通过get_session()惰性创建Session实例并用auto_save_on_exit回调在一次性命令结束后自动落盘见 gimp_cli.py输出层output()根据_json_output标志决定输出 JSON 还是人类可读的缩进字典/列表见 gimp_cli.py。从源码结构看refine 新增的每一个命令都会自然地落入这套骨架在 Click group 下挂新子命令、调用core/中的新函数、经由output()与handle_error完成统一出口。Step 5扩展测试Expand Tests测试是 refine 的硬性质量闸门文档要求三层测试同步扩展单元测试——每个新函数在test_core.py中增加测试E2E 测试——新命令在test_full_e2e.py中增加端到端测试工作流测试——把新命令与既有命令组合成多步工作流进行验证。最后运行全部测试旧 新确保无回归。这与 HARNESS.md 的四层测试策略一脉相承单元测试合成数据、无外部依赖→ 中间文件 E2E验证 CLI 生成的工程文件结构正确→ 真实后端 E2E必须调用真实软件产出真实文件校验 magic bytes / ZIP 结构 / 像素级结果→ CLI 子进程测试以真实用户方式调用已安装的cli-anything-software命令。特别是子进程测试必须使用_resolve_cli()辅助函数而绝不硬编码路径。仓库中 test_full_e2e.py 给出了标准实现_resolve_cli优先用shutil.which定位已安装命令并打印[_resolve_cli] Using installed command: ...未安装时回退到python -m cli_anything.software.software_cli当环境变量CLI_ANYTHING_FORCE_INSTALLED1时强制要求已安装命令否则抛错。TestCLISubprocess类的CLI_BASE _resolve_cli(cli-anything-gimp)即是对该约定的直接运用且子进程调用不设置cwd保证已安装命令从任何目录都能工作。真实 E2E 测试还要求不做优雅降级软件未安装时测试应该失败而非跳过No graceful degradation因为 CLI 离开真实软件就没有意义。GIMP 的 E2E 测试用 Pillow 构造条纹图、渐变图作为真实输入然后在导出后做像素级断言见 test_full_e2e.py 的test_brightness_increases_pixels。Step 6更新文档Update Documentation实现与测试闭环之后文档必须同步跟上更新README.md——补充新命令与用法示例更新TEST.md——追加新测试结果更新 SOP 文档SOFTWARE.md——补充新的覆盖说明。在仓库中每个 harness 目录都遵循这一约定例如 GIMP harness 的 tests/TEST.md 承载测试计划与结果SOFTWARE.md如gimp/agent-harness/GIMP.md承载软件专属 SOP。文档更新是覆盖地图的写回动作——让下一个 refine 周期的 Step 1 能基于最新事实做盘点。成功标准什么样的 refine 才算完成文档给出五条可验证的成功标准Success Criteria既有测试全部通过无回归——增量添加不能破坏任何旧行为新命令遵循同一架构模式——以 HARNESS.md 为准新测试 100% 通过率覆盖有意义的提升——新功能确实通过 CLI 暴露出来而不是实现了但没入口文档同步更新——README、TEST、SOP 三件套反映变化。配合 cli-anything-validate.md 的校验视角refine 的产出还可以用一套 52 项检查清单复核目录结构、必需文件、CLI 实现标准、核心模块标准、测试标准、文档标准、PyPI 打包标准、代码质量最终输出形如Overall: PASS (52/52 checks)的报告。也就是说refine 负责做加法validate 负责验成色两者构成迭代闭环的质量双闸。迭代节奏与最佳实践文档 Notes 部分给出了三个操作性很强的实践准则Refine 是增量的——可以多次运行逐步稳定地扩大覆盖run it multiple times to steadily expand coverage每次运行聚焦一组内聚的相关功能——而不是试图一次覆盖所有东西Each run should focus on a coherent set of related functions rather than trying to cover everything at once实现前必须展示差距分析——让用户能引导优先级The agent should present the gap analysis before implementing, so the user can steer priorities永不删除既有命令——refine 只添加或增强Refine never removes existing commands — it only adds or enhances。这条小而内聚、用户掌舵、只增不删的节奏本质上是把把一个 GUI 应用完整搬上命令行这个庞大任务切分成若干轮可验证、可回滚、可审计的增量提交。与 cli-anything-test.md 的失败处理策略测试失败时不更新 TEST.md、保留上一次通过记录、给出修复建议配合整个 CLI-Anything 工作流在构建、补全、校验、回归四个环节都具备清晰的可观测性。结合仓库源码refine 产出的架构样板要理解 refine 应该长成什么样仓库中已有多套完全符合 HARNESS.md 规范的 harness 可供对照。以 GIMP 为例其目录结构即 refine 迭代的目标形态gimp/agent-harness/cli_anything/gimp/ ├── gimp_cli.py # Click 入口命令组 --json --project REPL ├── core/ │ ├── project.py # 工程创建/打开/保存/info 画布 PROFILES │ ├── layers.py # 图层操作 │ ├── filters.py # 滤镜注册表 │ ├── canvas.py # 画布尺寸/模式 │ ├── media.py # 图片探测 │ ├── export.py # 渲染管线 EXPORT_PRESETS │ └── session.py # 会话 undo/redo 文件锁 ├── utils/ │ ├── gimp_backend.py # 调用真实 GIMPScript-Fu │ └── repl_skin.py # 统一 REPL 皮肤 └── tests/ ├── test_core.py # 单元测试 ├── test_full_e2e.py # 真实文件 E2E TestCLISubprocess └── TEST.md # 测试计划与结果几个可直接复用的refine 样板细节画布预设core/project.py的 PROFILES 定义了hd1080p、4k、a4_300dpi、instagram_post、youtube_thumb等 14 种常用画布规格refine 新增工程类命令时可直接复用这类预设字典模式导出预设core/export.py的 EXPORT_PRESETS 将 png/jpeg/webp/tiff/gif/pdf/ico 等格式的编码参数压缩级别、质量、无损标志集中声明refine 扩展导出能力时新增一个预设条目即可接入既有渲染管线会话与文件锁core/session.py的_locked_save_json见 session.py用fcntl.flock对 session JSON 做独占锁写入r打开 → 加锁 → 截断 → 写 JSON → 解锁Session类内置MAX_UNDO 50的撤销栈见 session.py。HARNESS.md 专门为此提供 session-locking.md 指南refine 新增任何会修改状态的命令时都应当经过snapshot()进入撤销栈从而保持会话一致性渲染后端分层core/export.py的render()见 export.py先尝试utils/gimp_backend.py中的 GIMP Script-Fu 原生渲染gimp -i -b不可用时才回退到 Pillow——这是调用真实软件、不要用 Python 重实现原则在 harness 内的落地。refine 为渲染类功能补命令时应当接入这一分层而不是另起炉灶。从这些实现可以推断refine 新增一个功能的典型落点就是在core/加模块函数 在software_cli.py挂命令 在test_core.py与test_full_e2e.py加测试 更新 README/TEST/SOP四步一一对应 Step 46架构上几乎无学习成本。与 CLI-Anything 命令生态的协同refine 不是孤立存在的它与仓库中其余命令形成完整的工作流闭环命令定位与 refine 的关系cli-anything.md从零构建完整 harness7 个 Phaserefine 的前置步骤产出待补全的基线cli-anything-refine.md本文增量补全已有 harness负责持续的覆盖率增长cli-anything-validate.md按 HARNESS.md 标准做 52 项合规校验refine 的质检闸门cli-anything-test.md运行测试并回写 TEST.mdrefine Step 5 的标准化执行器cli-anything-list.md列出所有已安装/已生成的 CLI 工具帮助判断哪些软件已有 harness、可进入 refine 轮次其中 validate 与 refine 的互补最值得注意validate 报告里Overall: PASS (52/52 checks)只代表符合架构规范不代表覆盖了软件全部能力而 refine 恰恰是让覆盖率从合规走向完整的手段。一套健康的仓库状态是先用 build 建出合规基线再用 refine 多轮迭代把高价值功能逐一补上每轮之后用 validate 守住架构底线、用 test 守住回归底线。总结cli-anything-refine定义了 CLI-Anything 方法论的第二曲线构建只是起点补全才是常态。它通过盘点现状 → 分析能力 → 差距排序 → 增量实现 → 测试扩展 → 文档更新的六步闭环让 Agent 能够在用户确认优先级的前提下持续将一个 GUI 应用的可命令行化能力稳定地暴露出来。其核心纪律——聚焦内聚子集、实现前先汇报差距、只增不删、严格遵循 HARNESS.md 模式、三层测试无回归——确保每一次 refine 都是可审计、可回滚、可验证的增量。仓库中的 HARNESS.md 与 GIMP 等成熟 harness 为这套流程提供了可直接对照的架构样板任何为开源 GUI 软件构建 Agent-Native CLI 的团队都可以照此推进。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考