Cursor 中增量精炼 CLI-Anything Harness：/cli-anything-refine 命令的流程、进度门控与实战规范
Cursor 中增量精炼 CLI-Anything Harness/cli-anything-refine 命令的流程、进度门控与实战规范【免费下载链接】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 生态在 Cursor 桌面端的“增量精炼”命令用于在/cli-anything完成一次完整构建之后持续扩展既有 CLI harness 的覆盖面coverage补齐缺失能力而绝不破坏已有命令。本文以 cursor-plugin/commands/cli-anything-refine.md 为骨架结合 cli-anything-plugin/commands/refine.md 的六步详细流程、cli-anything-plugin/HARNESS.md 的质量规范与仓库内真实 harness 源码如 GIMP harness展开。读完本文你将掌握如何解析 PLUGIN_ROOT、如何用.cli-anything-progress.json做可中断/可恢复的 phase gate、如何使用可选 focus 参数缩小差距分析范围、以及保证“只增不改、新旧测试全绿”的精炼成功标准。背景Refine 在构建流程中的定位CLI-Anything 的核心目标是“让所有软件 Agent-Native”为 GUI 应用生成一套有状态、可通过命令行与 REPL 操控的 harness。完整构建由 cli-anything-plugin/HARNESS.md 定义的标准流程驱动源码获取、代码库分析、CLI 架构设计、实现、测试规划、测试实现、测试文档、打包安装等阶段对应 Cursor 侧命令 cursor-plugin/commands/cli-anything.md。而/cli-anything-refine只用于 harness 已经构建成功之后它不是重建而是“分析软件全量能力与当前 CLI 覆盖之间的差距并迭代式补齐”它永不删除或破坏已有命令——只做添加或增强它可以被反复运行每次专注一批内聚的相关功能逐步把 coverage 做厚。一句话概括两者的分工build 解决“从 0 到 1”refine 解决“从 1 到 N”。第一步永远是解析 PLUGIN_ROOT仅接受绝对路径Cursor 工具解析相对路径时通常以workspace 根目录为基准而不是以插件目录为基准——这是 refine 命令正文反复强调的 CRITICAL 前置条件。因此执行任何精炼动作前必须先以“第一个同时命中references/HARNESS.md的候选项为准”的顺序解析出PLUGIN_ROOT读取发现指针文件单行存放绝对路径Windows 为%USERPROFILE%\.cursor\cli-anything-generator.rootUnix 为~/.cursor/cli-anything-generator.root取该目录作为PLUGIN_ROOT否则读取{default-or-$CURSOR_PLUGINS_HOME}/local/cli-anything/PLUGIN_ROOT.txtCURSOR_PLUGINS_HOME需解析到名为plugins的目录见 cursor-plugin/README.md否则若该候选目录下存在references/HARNESS.md直接采用该目录否则回退到 workspace 中克隆的cli-anything-plugin/。解析完成后必须用绝对路径阅读两份方法论文档{PLUGIN_ROOT}/references/HARNESS.md与{PLUGIN_ROOT}/references/commands/refine.md。这两份文件在本仓库中的源即 cli-anything-plugin/HARNESS.md 与 cli-anything-plugin/commands/refine.mdcursor-plugin 安装脚本会将cli-anything-plugin/的内容 vendor 到安装目录的references/下。禁止使用 workspace 相对的./HARNESS.md形式——这正是许多 Agent 精炼失败的根源。参数约定只收本地路径可选 focus 收窄目标命令用法与/cli-anything-refine完全一致/cli-anything-refine software-path [focus]参数必需性说明software-path必需软件源码的本地路径且必须是当初 build 时使用的同一份源码树如/home/user/gimp、./blender。若目标是 GitHub 仓库须先 clone 后用/cli-anything完成首次构建再对本地副本执行 refine[focus]可选一段自然语言描述指定要聚焦的功能域提供后Agent 跳过宽泛的差距分析直接瞄准该能力区域典型的 focus 写法仓库示例/cli-anything-refine /home/user/shotcut vid-in-vid and picture-in-picture features /cli-anything-refine /home/user/gimp all batch processing and scripting filters /cli-anything-refine /home/user/blender particle systems and physics simulation /cli-anything-refine /home/user/inkscape path boolean operations and clipping当提供[focus]时后续流程中的能力分析步骤仅覆盖指定区域差距分析也只对比聚焦能力与当前覆盖Agent 仍需在动手前向用户呈现scoped 到 focus 的结论。进度门控与断点恢复硬性要求精炼过程必须维护与 build 相同的进度文件{software-root}/agent-harness/.cli-anything-progress.json其中mode字段为refine。基础结构与 cli-anything.md 中给出的 build schema 同源{ software: name, mode: refine, target: absolute software path, phases: { 0: { status: completed, updated_at: ISO-8601 }, 1: { status: in_progress, updated_at: ISO-8601 } }, terminal: false, terminal_status: null }Refine 模式的阶段序列是inventory盘点现有命令→ capability scan能力扫描→ gap analysis差距分析→ implement实现→ test测试→ document文档。门控规则为前一个步骤在进度文件中记录为completed之前不得推进到下一步骤会话中断后再次启动时应恢复未完成的 refine 运行从第一个未完成步骤继续而不是推倒重来除非用户明确要求破坏性变更否则不得移除现有命令当 refine 全部完成或被永久中止时将terminal置为true并记录terminal_statussuccess/failed此后该进度文件即为历史记录只有用户要求重新精炼时才重置或替换。Cursor 工具绑定分工Refine 复用 Cursor 原生能力完成各阶段动作Cursor 工具在 refine 流程中的角色Read / Grep / Glob盘点当前 CLI 覆盖范围映射目标软件 APIShell运行既有测试验证新命令Write / StrReplace新增命令、核心模块与测试六步精炼流程详解cli-anything-plugin/commands/refine.md 给出了每一步的具体动作清单。Step 1盘点当前覆盖Inventory Current Coverage阅读既有 CLI 入口GIMP 场景即software_cli.py仓库示例为 gimp_cli.py及全部 core 模块列出当前已实现的每一个命令、子命令与选项阅读既有测试套件test_core.py、test_full_e2e.py弄清已被测试覆盖的范围构建一份覆盖映射{ 函数名: covered | not_covered }。从仓库结构看GIMP harness 已经形成了“coreproject/layers/filters/canvas/media/export/session utilsgimp_backend/repl_skin tests README”的完整目录这类既有结构正是 refine Step 1 要盘点的对象。Step 2分析软件能力Analyze Software Capabilities在software-path上重新扫描软件源码识别所有公开 API、自带 CLI 工具、脚本化接口与批处理模式优先关注能产生可观察输出的函数渲染、导出、变换、转码/转换按领域归类如 GIMP 可归为 filters、color adjustments、layer ops、selection tools。Step 3差距分析Gap Analysis——先报告再动手将当前 CLI 覆盖与软件全量能力对比并按以下优先级排序待补缺口高影响力High impact软件中常用但 CLI 尚未暴露的函数易摘果实Easy winsAPI 简单、可快速完成薄封装thin wrapper的函数可组合性Composability与既有命令组合后能解锁新工作流的函数。关键纪律实现之前先向用户呈现差距报告并确认要补哪些让用户决定优先级若提供了 focus报告范围应收敛到该区域。这一步是 refine 与“闷头加功能”的本质区别。Step 4实现新命令Implement New Commands为选中的差距新增命令/子命令但必须严格沿用 HARNESS 定义的既有模式见 cli-anything-plugin/HARNESS.md而不是另起炉灶Click 命令组主入口click.group(invoke_without_commandTrue)无子命令时默认进入 REPL——仓库内 gimp_cli.py 即用click.option(--json, ...)与invoke_without_commandTrue实现该模式--json机器可读输出所有命令必须支持--json。GIMP 的实现集中在output()与_print_dict/_print_list帮助函数中JSON 模式下输出结构化数据人类模式下输出缩进键值对会话状态集成复用Session支持 undo/redo、状态持久化统一错误处理handle_error作为装饰器包装命令函数将FileNotFoundError/ValueError/RuntimeError/FileExistsError统一映射为 JSON{error: ..., type: ...}或人类可读错误并在非 REPL 模式下sys.exit(1)——见 gimp_cli.py对应 core 模块函数新增逻辑放进core/或utils/CLI 层只做参数转发与输出格式化。同时遵守 HARNESS 铁律调用真实软件后端薄封装绝不重新实现软件本身见 HARNESS.md 的 Architecture Patterns。精炼建议书也明确指出应“优先高影响缺口、优先对真实后端 API 做薄封装”。Step 5扩展测试——单元、E2E、工作流三层齐上Refine 的纪律是“每个新增命令面都必须有配套的单元/E2E 覆盖”且新旧测试全部运行以确保无回归在test_core.py中为每个新函数补充单元测试合成数据、无外部依赖、确定性在test_full_e2e.py中为新命令补充E2E 测试真实文件、真实后端补充工作流测试把新命令与既有命令组合成多步真实场景多段剪辑、画中画合成、调色管线、undo/redo 压力等见 HARNESS.mdE2E 必须用_resolve_cli(cli-anything-software)以子进程方式调用已安装的 CLIHARNESS.md 提供模板设置环境变量CLI_ANYTHING_FORCE_INSTALLED1强制使用安装命令而非模块回退防止“源码能跑、装完不能用”输出验证绝不只看“命令退出了”要校验 magic bytes如 PDF 的%PDF-、ZIP/OOXML 结构、像素级分析、时长/格式等并打印产物路径供人工检查。仓库 GIMP E2E 即真实创建三色条/渐变测试图后断言像素结果见 test_full_e2e.py运行方式参考 HARNESSCLI_ANYTHING_FORCE_INSTALLED1 python3 -m pytest cli_anything/software/tests/ -v -sStep 6更新文档用新命令与用法示例更新README.md把新测试结果追加到TEST.md在 SOP 文档SOFTWARE.md位于 harness 目录顶层如 GIMP.md中补充新的覆盖说明。Refine 清单与成功标准命令正文给出精炼前后的自检清单动手编码前先盘点现有命令/测试优先高影响缺口并优先对真实后端 API 做薄封装每个新命令面都补充匹配的单元/E2E 覆盖保持 HARNESS 打包规范以及--json/ REPL 标准。可量化的成功标准来自 refine.md全部既有测试仍然通过零回归新命令遵循同一套架构模式HARNESS 定义新测试 100% 通过覆盖率有实质提升新函数经 CLI 暴露文档已同步更新。反复精炼的增量哲学与注意事项Refine 的设计初衷是增量的多次运行 refine 以持续稳步扩展覆盖而不是毕其功于一役每次运行聚焦一组内聚的相关功能而不是试图一次覆盖所有能力动手前先给出差距分析让用户掌握优先级方向盘Refine 永不删除既有命令——它只添加或增强这保证了长期演进中 harness 的稳定性与 Agent 侧可用性通过.cli-anything-progress.json的 phase gate 与断点恢复任何一次长会话中断都不会丢失精炼进度。对于希望把某个 GUI 应用“喂给 AI Agent”的开发者而言/cli-anything-refine是把一次性生成的 harness 打磨成可持续演进、覆盖面完整、可被 Agent 信赖的工程化工具的关键一环——它把“软件能力盘点 → 差距补齐 → 回归验证”固化成一个可重复、可聚焦、可断点续跑的标准化流程。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考