企业官网建设流程全解析

CLI-Anything refine 命令详解：增量扩展 GUI 软件 CLI 覆盖面的完整工作流

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

refine是 CLI-Anything 插件体系（cli-anything-plugin/commands/refine.md）中的第二梯队命令，与负责"从零构建"的/cli-anything不同，它专门用于在已有 CLI harness 之上做增量式能力扩展：分析软件完整功能与当前 CLI 覆盖之间的差距（gap），然后按优先级迭代补充新命令、新测试与新文档。读完本文，你将掌握 refine 命令的完整参数语义、六步工作流的每一步产物，以及它如何依托 HARNESS.md 的质量基线保证"新增命令与原有命令同标准"，从而把一次性的 harness 构建变成可持续演进的过程。

1. 定位：refine 在命令体系中的位置

CLI-Anything 插件为 GUI 软件生成"agent 可用的有状态 CLI"，其核心命令族包括：

refine 的使用前提很明确：它必须在/cli-anything已经构建出 harness 之后运行。官方文档原话是 "This command is used after a CLI harness has already been built with/cli-anything"——它不做架构设计，只回答一个问题：软件还有哪些能力没有被 CLI 暴露出来，以及应该先补哪些。

另一个关键约束是：refine 开始前必须先读HARNESS.md（插件根目录下的 HARNESS.md）。文档将其列为 "CRITICAL" 级要求："All new commands and tests must follow the same standards as the original build. HARNESS.md is the single source of truth for architecture, patterns, and quality requirements." 这决定了 refine 不是随意加几个函数，而是按既有架构模式（Click 命令组、--json输出、会话状态、统一错误处理）做一致性扩展。

2. 用法与参数

2.1 基本语法

/cli-anything:refine <software-path> [focus]

2.2 参数说明

• <software-path>（必填）：软件源代码的本地路径，例如/home/user/gimp、./blender。

  • 必须是原始构建时使用的同一棵源码树，否则差距分析（Step 3）对比的"软件完整能力集"就失去了基准；
  • 只接受本地路径。文档明确说明：如果需要从 GitHub 仓库工作，应先用/cli-anythingclone 到本地，然后再 refine（refine 不像/cli-anything那样直接接受 GitHub URL）。

• [focus]（可选）：用自然语言描述要聚焦的功能领域。提供 focus 后，agent跳过宽泛的差距分析，改为定向处理指定能力域，具体表现为：

  • Step 2（分析软件能力）收窄到指定领域；
  • Step 3（差距分析）只对比 focus 范围内的能力与当前覆盖；
  • 实现前仍会先呈报分析结果，但范围限定在 focus 区域内。

文档给出的 focus 示例覆盖了多个已构建的 harness：

/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"

2.3 宽泛模式 vs 聚焦模式

# 宽泛精化 —— agent 自动发现全部能力域中的差距 /cli-anything:refine /home/user/gimp # 聚焦精化 —— agent 只针对特定功能领域 /cli-anything:refine /home/user/shotcut "vid-in-vid and picture-in-picture compositing" /cli-anything:refine /home/user/gimp "batch processing and Script-Fu filters" /cli-anything:refine /home/user/blender "particle systems and physics simulation" /cli-anything:refine /home/user/inkscape "path boolean operations and clipping masks"

两种模式的取舍在 Notes 一节有明确指引：每次 refine 应聚焦一组内聚的相关功能，而不是一次覆盖所有东西（"Each run should focus on a coherent set of related functions rather than trying to cover everything at once"）。

3. 六步工作流详解

refine 的核心是一个六步流程。下面逐节展开，并结合仓库中真实存在的 harness（以 shotcut 为例，因为它是 refine 文档里 focus 示例的主角）说明每一步的输入与产物。

3.1 Step 1：盘点当前覆盖（Inventory Current Coverage）

这一步的目标是建立一份覆盖映射表（coverage map），键为软件功能名，值为covered | not_covered。具体动作：

1. 读取现有 CLI 入口<software>_cli.py及所有核心模块——对应真实 harness 中的 shotcut_cli.py 与core/下的project.py、session.py、export.py、filters.py、timeline.py等模块（见 shotcut/core）；
2. 列出每一个已实现的命令、子命令与选项；
3. 通读现有测试套件（test_core.py/test_full_e2e.py），弄清哪些行为已被测试约束——这决定了新增命令时哪些回归必须守住。

产物{ function_name: covered | not_covered }是后续 Step 3 差距分析的数据基础。注意这一步是"以 CLI 现状为中心"的盘点，与 Step 2 的"以软件为中心"的扫描形成互补视角。

3.2 Step 2：分析软件能力（Analyze Software Capabilities）

回到<software-path>指定的软件源码重新扫描，识别：

• 所有公开 API、CLI 工具、脚本化接口、批处理模式操作；
• 重点筛选能产生可观测输出的功能（渲染、导出、变换、转换）——这与 HARNESS.md 中 "Focus on functions that produce observable output" 的原则一致，因为只有可验证的输出才能被 E2E 测试约束；
• 按领域归类。文档以 GIMP 为例：滤镜、色彩调整、图层操作、选择工具。

若指定了[focus]，这一步的扫描范围收窄到 focus 描述的能力域。对 Shotcut 而言，"vid-in-vid and picture-in-picture" 这类 focus 会引导 agent 重点考察 MLT 框架中多轨道 tractor 与合成（compositing）相关能力——从源码结构看，现有 shotcut/core/compositing.py 与 SHOTCUT.md 中对 MLT XML tractor/multitrack 结构的分析，正是这类领域归类的现成素材。

3.3 Step 3：差距分析与优先级排序（Gap Analysis）

将 Step 1 的覆盖映射与 Step 2 的软件能力全集做差集，并按三条标准给差距排序：

1. 高影响（High impact）——常用但缺失的函数；
2. 快赢（Easy wins）——API 简单、可以快速包装的函数；
3. 可组合性（Composability）——与现有命令组合后能解锁新工作流的函数。

排序完成后的关键纪律是：先把差距报告呈给用户，确认要处理哪些差距后再动手（"Present the gap report to the user and confirm which gaps to address"）。这意味着 refine 是"人机协同决策"的流程，agent 不会未经确认就大规模改写 CLI——用户可以在实现前调整优先级。

3.4 Step 4：实现新命令（Implement New Commands）

对确认的差距，向 CLI 添加新命令/子命令，且必须遵循 HARNESS.md 定义的既有模式：

• Click 命令组（command groups，而非扁平命令）；
• --json输出支持——HARNESS.md 规定 "Every command MUST support--jsonfor machine parsing"，保证 agent 可程序化消费新命令的输出；
• 会话状态集成（session state integration）——新命令要正确挂入全局会话，参与 undo/redo 快照；
• handle_error统一错误处理——真实 harness 中 shotcut_cli.py#L163 定义了handle_error装饰器，并被大量命令（L263 起）一致引用；validate 命令也把 "Hashandle_errordecorator for consistent error handling" 列为校验项之一（见 validate.md）。

实现层面，新命令的底层函数应添加到core/（领域模块）或utils/（工具模块）。这里同时隐含了 HARNESS.md 的第一铁律：渲染与导出必须调用真实软件（melt/ffmpeg之于 Shotcut，gimp -i -b之于 GIMP），而不是用 Python 重新实现；新增导出类命令时，必须复用utils/<software>_backend.py这类后端包装模块（如 shotcut/utils/melt_backend.py）。

3.5 Step 5：扩展测试（Expand Tests）

新增功能必须配套三层测试，全部运行（旧 + 新）以保证无回归：

这与 HARNESS.md 的四层测试策略（单元 / 原生 E2E / 真后端 E2E / CLI 子进程）完全对齐。值得注意的是子进程测试层：真实 harness 的test_full_e2e.py使用_resolve_cli("cli-anything-<software>")解析已安装命令，支持CLI_ANYTHING_FORCE_INSTALLED=1强制走安装路径——refine 新增命令后，这些既有测试机制会自动把新命令纳入"以真实用户视角"的回归范围。

3.6 Step 6：更新文档（Update Documentation）

refine 收尾必须同步三份文档，保持"代码、测试、文档"三态一致：

• README.md（harness 包内，如 shotcut/cli_anything/shotcut/README.md）：补充新命令与用法示例；
• TEST.md：更新测试计划与最新测试结果（shotcut 的位于 shotcut/agent-harness/TEST.md）；
• SOP 文档<SOFTWARE>.md：更新覆盖说明（如 SHOTCUT.md 中的架构分析与命令地图），让后续的 refine 轮次能从文档而非仅凭代码重建软件全貌认知。

4. 成功标准与运行守则

refine 命令文档给出了明确的验收标准，可与 validate.md 的合规检查互为印证：

• 所有既有测试仍然通过（无回归）；
• 新命令遵循与原有命令相同的架构模式（以 HARNESS.md 为准）；
• 新测试100% 通过；
• 覆盖面有实质性提升（新功能真正经由 CLI 暴露，而非只写了 core 函数）;
• 文档已随变更更新。

运行守则（Notes）四条，值得在实操前牢记：

1. refine 是增量式的——可多轮运行，逐步扩大覆盖；
2. 每轮聚焦一组内聚的相关功能，不要试图一次覆盖全部；
3. 实现前必须呈报差距分析，让用户掌握优先级决策权；
4. refine 从不删除既有命令——只新增或增强（"Refine never removes existing commands — it only adds or enhances"）。这条"只增不删"的不变式保证了 harness 的向后兼容性：已发布的 PyPI 包、已生成的 SKILL.md 中引用的旧命令在多轮 refine 后依然有效。

5. 与 test / validate 的组合使用

一次完整的 refine 周期之后，通常还建议：

1. 运行/cli-anything:test <software-path>：以-v -s --tb=short执行测试，确认输出中出现[_resolve_cli] Using installed command:（证明测的是已安装命令而非源码回退），并把结果追加到 TEST.md——若测试失败，test 命令不会覆盖 TEST.md 中上一次通过的记录，避免污染结果历史；
2. 运行/cli-anything:validate <software-path>：按目录结构、必需文件、CLI 实现标准、核心模块标准、测试标准、文档标准、PyPI 打包、代码质量共 8 大类 52 项检查，确认 refine 的增量改动没有破坏 HARNESS.md 基线。

三者组合形成了 "build（cli-anything）→ refine（增量扩展）→ test + validate（回归与合规）" 的闭环，这也是插件 README 版本历史中所说的 iterative development 思路（参见 cli-anything-plugin/README.md）。

6. 小结

/cli-anything:refine的价值在于把 CLI harness 从"一次生成物"转变为"可演进资产"：它以覆盖映射为现状基线、以软件源码重扫为能力全集、以"高影响 → 快赢 → 可组合"三档优先级驱动决策，并强制新命令、新测试、新文档三同步更新。由于 refine.md 将 HARNESS.md 定位为唯一事实来源，配合 validate.md 的可重复校验，多轮 refine 后的 harness 在架构一致性上始终可验证——这正是 CLI-Anything "Making ALL Software Agent-Native" 方法论中"持续贴近软件真实能力"的关键机制。

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