把 GUI 软件改造成 AI 代理可操作的 CLI：HARNESS.md 七阶段完整实战指南

把 GUI 软件改造成 AI 代理可操作的 CLIHARNESS.md 七阶段完整实战指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingCLI-Anything 要解决的问题很具体AI 代理能读写文件、敲命令却点不了鼠标而大量生产力软件只有 GUI。它的 HARNESS.md 给出一套标准操作程序把任意 GUI 软件转成 AI 原生接口的命令行工具让 AI agent 工作流能独立完成命令行自动化。下面按铁律—交付链路—验证体系的顺序讲清其中不可省略的技术事实。 七阶段链路从读代码库一路走到 PyPI先说结论这是一条流水线顺序不能跳。代码库分析找出后端引擎Shotcut 是 MLT、GIMP 底层是 ImageMagick把每个 GUI 动作映射成 API 调用确认项目文件的数据格式XML、JSON、二进制还是数据库列出后端自带的 CLI 工具melt、ffmpeg、convert盘点命令/撤销系统——撤销系统往往就是现成的命令模式直接变成 CLI 操作。CLI 设计定交互模型——有状态 REPL 适合保持上下文的代理子命令 CLI 适合一次性脚本推荐两者都支持命令组按应用逻辑域划分项目管理、核心操作、导入导出、配置、会话状态设计状态模型里哪些必须跨命令持久化输出同时服务人和机器用--json切换。实现数据层先行解析和改写原生项目文件再依次加探测/信息命令、变更命令、后端集成模块utils/software_backend.py负责用shutil.which找可执行文件、subprocess调用、缺失时给出安装指引、渲染导出、会话管理JSON 会话文件加文件锁防并发写坏。测试规划写任何测试代码之前先在agent-harness/cli_anything/software/tests/下落一份 TEST.md计划几个测试文件、每个核心模块测哪些函数、边界条件、要模拟的真实工作流。测试实现按计划在tests/test_full_e2e.py等文件里落四层测试见下文。测试文档全部跑通后向 TEST.md 追加pytest -v输出、统计数字和覆盖缺口形成先计划、后结果的完整记录。PyPI 发布以共享命名空间打包发布下一节。中间还有一步常被漏掉生成skills/cli-anything-software/SKILL.md用 YAML frontmatter 供代理做技能发现正文写清命令结构、--json用法和真实示例让 AI 代理无需读源码就能正确调用这条 CLI。 必须调用真实软件杜绝玩具级 CLIHARNESS.md 的第一铁律渲染和导出必须调用真实软件完成禁止用 Python 重新实现软件功能。反模式长这样拿 Pillow 写一个图像合成器顶替 GIMP或者生成 bpy 脚本却从不调用 Blender。产出的东西处理不了真实工作负载行为还会和真软件越走越远。正确做法拆成三点用软件自带的 CLI/脚本接口当后端libreoffice --headless --convert-to、blender --background --python、gimp -i -b、inkscape --actionsShotcut/Kdenlive 一律走melt project.mlt -consumer avformat:output.mp4。软件是硬性依赖不是可选项没装就报错并打印安装方法而不是换一套库凑合。CLI 的本职是生成合法的项目/中间文件ODF、MLT XML、.blend、SVG再交给真软件渲染。它是对软件的命令行接口不是软件的替代品。数据层直接操作原生项目文件不自造中间格式——这是AI 代理操作软件与代理操作玩具的分界线。 统一目录结构与 PEP 420 命名空间让几十个 CLI 共存gimp、blender、audacity 这些包要装进同一个 Python 环境而不互相冲突关键只有一条cli_anything/目录下不放__init__.py让它成为 PEP 420 命名空间包其下每个子包gimp/、blender/才带__init__.py。每个 harness 的目录长这样software/agent-harness/ ├── SOFTWARE.md # 项目特定分析与 SOP ├── setup.py └── cli_anything/ # 无 __init__.pyPEP 420 └── gimp/ ├── __main__.py # python3 -m cli_anything.gimp ├── gimp_cli.py # Click 主入口 REPL ├── core/ # 按领域拆project/export/session... ├── utils/ │ ├── gimp_backend.py # 封装真实软件调用 │ └── repl_skin.py ├── skills/SKILL.md └── tests/ ├── TEST.md ├── test_core.py └── test_full_e2e.pysetup.py侧用find_namespace_packages(include[cli_anything.*])收集包注册入口点cli-anything-gimpcli_anything.gimp.gimp_cli:main声明python_requires3.10并用package_data把skills/*.md一起发出去保证装到别的机器上代理仍能找到技能文件。 四层测试体系软件缺失时不许跳过更不许伪造测试策略固定为四层各司其职单元测试tests/test_core.py合成数据、零外部依赖每个函数隔离验证快且确定适合 CI。E2E 原生tests/test_full_e2e.py验证 CLI 生成的项目文件本身结构正确——合法 XML、ZIP 结构完整等。E2E 真实后端必须调用真实软件产出最终工件PDF、DOCX、渲染图、视频逐项验证文件存在、大小大于 0、格式正确如 PDF 魔术字节%PDF-、内容符合预期并打印工件路径让人工复核。CLI 子进程全流程subprocess.run调起已安装的cli-anything-software完整走一遍建项目 → 加内容 → 真软件导出 → 验证输出。解析命令用_resolve_cli辅助函数不硬编码解释器路径CI 里设CLI_ANYTHING_FORCE_INSTALLED1确保测的是真装上的命令。无优雅降级是硬规则真实软件没装测试失败而不是跳过更不允许伪造结果——没有那个软件这条 CLI 就没有存在价值。class TestCLISubprocessE2E: CLI_BASE _resolve_cli(cli-anything-libreoffice) def test_full_writer_pdf_workflow(self, tmp_dir): self._run([document, new, -o, proj, --type, writer]) self._run([--project, proj, writer, add-heading, -t, Title]) self._run([--project, proj, export, render, out, -p, pdf, --overwrite]) assert os.path.exists(out) with open(out, rb) as f: assert f.read(5) b%PDF- # 验证魔术字节而非只看退出码️ ReplSkin 统一皮肤交互输出只有一套标准所有 CLI 的交互模式必须复用统一 REPL 皮肤把cli-anything-plugin/repl_skin.py拷进包内utils/repl_skin.py用ReplSkin接管一切终端输出。它的职责包括print_banner()品牌启动框自动检测包内skills/SKILL.md并在横幅里打印绝对路径AI 代理照路径读技能文件即可create_prompt_session()get_input()基于 prompt_toolkit 的输入带历史记录、样式提示行显示项目名与未保存状态help()格式化的命令列表success()/error()/warning()/info()✓ 绿、✗ 红、⚠ 黄、● 蓝四类消息status()键值对状态行table()表格progress()进度条print_goodbye()风格化退出主 Click 组要设invoke_without_commandTrue不带子命令时自动落进 REPL——保证直接敲包名就能进入交互这个约定在所有 CLI 上一致。⚠️ 三条踩出来的经验渲染差距、帧率舍入、输出验证渲染差距GUI 应用的特效通常在渲染阶段才由引擎生效。CLI 把滤镜写进项目文件后若用 ffmpeg concat 这类简单工具出片它只读原始媒体、无视项目级特效——输出和输入一模一样用户根本不知道出过事。解法是加过滤器转换层优先级固定首选应用原生渲染器MLT 项目直接用melt读项目文件时自动应用全部特效次选建转换层把项目格式特效翻译成渲染工具的原生语法MLT 滤镜 → ffmpeg-filter_complex最后手段生成渲染脚本交用户手动执行时间码精度29.97fps 本质是 30000/1001非整数帧率会累积舍入误差。浮点转帧号用round()而不是int()显示一律整数算术往返测试接受 ±1 帧容差。别在这踩坑误差会随时间轴长度放大。输出验证导出没报错不等于正确必须程序化验证——视频用 ffprobe 探具体帧淡入首帧应接近全黑、中间帧亮度饱和度对比源、尾帧接近全黑音频查首尾 RMS 水平确认淡入淡出、比对频谱特性文档格式查魔术字节与 ZIP/OOXML 结构。七条链路、三层铁律、四层测试、三条经验合起来才是一个可交付物底层是真软件在干活测试体系随时可重跑SKILL.md 让代理自助上手pip 一条命令装好。GUI 软件的能力边界到这一步才真正向 AI 代理敞开——这正是 CLI-Anything Making ALL Software Agent-Native 想兑现的承诺。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考