CLI-Anything 的技术真相：它没有写一行"引擎代码"，全靠一份提示词

❝上一篇介绍了 CLI-Anything 能做什么。这一篇掀开底牌——它到底是怎么做到的？答案可能会让你意外。❞

先破个幻觉

看完上一篇文章，很多人可能以为 CLI-Anything 是一个庞大的代码生成引擎——里面有 AST 解析器、有模板系统、有各种软件的适配层……

「不是的。」

CLI-Anything 的核心是一份 Markdown 文档——HARNESS.md，大约 600 行。

没有代码生成引擎。没有 AST 解析。没有模板。

它的技术本质就是：

❝「一份极其精心设计的提示词（SOP） + AI Agent 自身的编码能力 = 自动生成完整的 CLI 工具」 ❞

你在 Claude Code 里输入 /cli-anything ./gimp，本质上就是把 HARNESS.md 这份 SOP 喂给了 Agent，然后 Agent 按照这份 SOP 一步步分析源码、设计架构、写代码、写测试、打包发布。

「Agent 干了所有的活。HARNESS.md 只是告诉它"怎么干"。」

那 HARNESS.md 里到底写了什么？

它是一份给 AI Agent 看的"施工手册"。我们看看它的骨架：

7 个阶段，一条流水线

Phase 1: 源码分析 → 找到后端引擎、API映射、数据模型
Phase 2: 架构设计 → 命令分组、状态模型、输出格式
Phase 3: 代码实现 → Click CLI + 核心模块 + 后端桥接 + REPL
Phase 4: 测试规划 → 先写TEST.md，再写代码
Phase 5: 测试实现 → 单元测试 + 端到端测试 + 子进程测试
Phase 6: 文档化   → 测试结果回写文档
Phase 6.5: SKILL.md → 自动生成AI可发现的技能描述
Phase 7: 打包发布 → setup.py + pip install

这 7 个阶段不是代码逻辑，是「纯文本指令」。Agent 读完之后，自己决定怎么实现。

铁律和约束

除了流程，HARNESS.md 花了大量篇幅定义「不可违反的规则」。这才是这份提示词真正的功力所在：

「规则一：必须用真实软件，禁止重写。」

❝"The CLI MUST call the actual software for rendering — not reimplement the software's functionality in Python." ❞

这条规则防止 Agent 走捷径。如果不写这条，Agent 很可能会用 Pillow 重写一个"GIMP 渲染器"——能跑，但丢了 GIMP 90% 的功能。

「规则二：后端缺失时测试必须失败，不允许跳过。」

❝"No graceful degradation. Tests must NOT skip or fake results when the software is missing." ❞

这防止 Agent 写出"看起来全绿但什么都没验证"的测试套件。

「规则三：不信任退出码，必须独立验证输出。」

❝"Don't trust that export works just because it exits successfully. Verify: magic bytes, ZIP structure, pixel analysis, audio RMS levels." ❞

这条来自真实的血泪教训——GIMP 进程返回 0，但输出文件可能是空的或格式错误的。

「规则四：每个命令必须支持 --json 输出。」

这确保生成的 CLI 天然对 Agent 友好——结构化数据，不需要解析人类可读的输出。

「规则五：REPL 必须是默认行为。」

直接输入 cli-anything-gimp 不带任何参数时，必须进入交互式 REPL，而不是打印帮助信息。

你会发现，这些规则不是技术实现，而是「经验沉淀」。它们来自团队在实际构建 20+ 个 CLI 过程中踩过的坑——每踩一次，就往 HARNESS.md 里加一条约束，让 Agent 下次不再犯同样的错。

为什么一份提示词就够了？

这里有一个关键洞察：「Agent 本身已经具备了写完整 Python 项目的能力。」

它会用 Click 框架写 CLI、会用 subprocess 调用外部程序、会写 pytest 测试、会生成 setup.py、会操作 JSON/XML/ZIP 文件……这些技能不需要 CLI-Anything 教它。

CLI-Anything 做的事情是：

1. 「告诉 Agent 该分析什么」——不是漫无目的地读代码，而是聚焦于"后端引擎在哪"、"GUI 动作怎么映射到 API"、"项目文件是什么格式"
2. 「给出架构模板」——三层结构（CLI 入口 → 核心逻辑 → 后端桥接）、命令分组方式、状态管理模式
3. 「定义质量底线」——那些铁律和约束，确保 Agent 不走捷径、不偷懒、不自欺欺人
4. 「提供参考实现」——通过已有的 20+ 个 harness（GIMP、Blender、LibreOffice……），Agent 可以参考它们的代码风格和模式

本质上，HARNESS.md 是一个**"把 Agent 从 60 分拉到 90 分的提示词工程杰作"**。

不写 HARNESS.md，Agent 也能给你生成一个 CLI——但大概率会重写软件功能而不是调用真实后端、会跳过测试而不是验证输出、会生成一堆 mock 数据而不是真正渲染。

有了 HARNESS.md，Agent 被约束在正确的路径上，产出质量直接提升一个等级。

那些"不是代码但极其重要"的东西

理解了"提示词 + Agent 能力"这个本质之后，我们再看 CLI-Anything 仓库里那些真正有价值的资产：

1. HARNESS.md（600行）—— 方法论

这是核心资产。定义了流水线的 7 个阶段、架构模式、铁律规则、每种软件类型的桥接策略。

它不是一次写成的——每次构建新软件的 CLI 遇到问题，就往里面加一条规则。比如：

• 构建 Shotcut 的 CLI 时发现"渲染鸿沟"问题（特效被静默丢弃），加入了"滤镜翻译层"的指导
• 构建 Kdenlive 的 CLI 时发现时间码精度问题（29.97fps 导致累积舍入），加入了"用 round() 不用 int()"的规则
• 构建 Browser 的 CLI 时发现没有传统 CLI 可调，加入了 MCP 后端模式的指导

「HARNESS.md 是一份活的文档，它在随着每次实战不断进化。」

2. repl_skin.py（520行）—— 统一交互体验

这是仓库里少数几份真正的"代码资产"之一。它提供统一的 REPL 界面——品牌横幅、风格化提示符、彩色消息、表格输出、命令历史。

Agent 生成新 CLI 时，直接复制这个文件到 utils/ 目录，所有 CLI 的交互体验就自动统一了。

3. skill_generator.py（530行）—— 元数据提取

另一份代码资产。它用正则从 Click 装饰器中提取命令元数据，生成标准化的 SKILL.md。这让生成的 CLI 能被其他 AI Agent 自动发现和使用。

4. 20+ 个已有的 harness —— 参考实现

GIMP、Blender、LibreOffice、Shotcut、Inkscape……每一个都是 Agent 下次构建新 CLI 时的参考。

当你让 Agent 为一个新软件生成 CLI 时，它不仅读 HARNESS.md，还会参考已有 harness 的代码——"GIMP 是这样处理滤镜映射的"、"Blender 是这样生成 bpy 脚本的"、"LibreOffice 是这样验证 PDF 魔术字节的"。

「这就是"飞轮效应"——每多一个 harness，下一个就更容易做好。」

一个更深的问题：为什么提示词工程能做到这种程度？

有人可能会问：一份 Markdown 提示词，凭什么能产出 1900+ 测试全部通过的生产级代码？

我觉得有三个原因：

「1. 任务的本质是"结构化的重复"。」

给不同软件生成 CLI，表面上千差万别，但底层模式高度一致：找到后端 → 设计命令 → 写桥接代码 → 测试验证。HARNESS.md 把这个模式提炼出来了。Agent 只需要在固定框架里填充不同软件的具体细节。

「2. 约束比自由更能产出质量。」

Agent 什么都能做，但"什么都能做"往往意味着"什么都做得一般"。HARNESS.md 的铁律大幅收窄了 Agent 的行动空间——你必须调用真实软件、你必须验证输出、你必须支持 JSON——这些约束反而让产出质量飙升。

这和人类开发中的 coding standard 是一个道理：不是约束了你的创造力，而是让你不犯低级错误。

「3. 前沿模型的代码能力已经足够强。」

CLI-Anything 明确说了它依赖"Claude Opus 4.6、Sonnet 4.6 或 GPT-5.4 级别的模型"。在这个能力水平上，Agent 完全有能力独立完成一个中等复杂度的 Python 项目——前提是你告诉它做什么、怎么做、什么不能做。

HARNESS.md 就是那个"前提"。

对我们的启示

CLI-Anything 的实现方式给所有做"AI 辅助开发"的人一个重要启示：

「与其写一个复杂的代码生成框架，不如写一份好的 SOP 提示词。」

HARNESS.md 之所以有效，是因为它做到了：

• 「足够具体」——不是"请生成一个好的 CLI"，而是精确到"Phase 3 第 4 步要写一个 utils/<software>_backend.py，用 shutil.which() 查找可执行文件"
• 「足够有约束」——不是"尽量验证输出"，而是"必须检查魔术字节，测试必须 FAIL 不能 SKIP"
• 「持续进化」——每次踩坑就加一条规则，文档是活的
• 「有参考实现」——不是空谈方法论，20+ 个 harness 摆在那里当例子

如果你正在做类似的事情——让 Agent 自动生成某类代码——最值得投资的可能不是更复杂的工具链，而是一份更好的 SOP。

一份 SOP，怎么接入 6 个编程 Agent？

理解了"核心就是一份提示词"之后，你可能会好奇：它是怎么同时支持 Claude Code、Codex、OpenClaw、Qodercli、OpenCode、Copilot CLI 这么多平台的？

答案依然简洁得出人意料：「每个平台的"接入"，本质上就是把 HARNESS.md 包装成那个平台能理解的格式。」

每个 AI 编程工具都有自己的"扩展机制"——Claude Code 叫插件（Plugin），OpenClaw 叫技能（Skill），Codex 也叫 Skill，OpenCode 叫斜杠命令（Commands），Qodercli 也是插件。虽然叫法不同，但本质都是一个东西：「一段预置的指令文本，在用户触发时注入给 Agent。」

CLI-Anything 对每个平台做的事情，就是写一份"适配文件"，告诉该平台的 Agent：

1. 先去读 HARNESS.md（方法论的唯一权威来源）
2. 按照 7 个阶段执行
3. 遵守所有铁律

我们具体看看每个平台的适配方式：

「Claude Code —— 插件（Plugin）」

这是"一等公民"级别的接入。仓库里有一个 cli-anything-plugin/ 目录，里面包含 commands/cli-anything.md、commands/refine.md 等命令定义。每个文件的第一句话就是：

❝"Before doing anything else, you MUST read ./HARNESS.md." ❞

用户输入 /cli-anything ./gimp，Claude Code 就把这份命令定义 + HARNESS.md 喂给 Agent，Agent 开始干活。安装方式也极简——/plugin marketplace add HKUDS/CLI-Anything 一行搞定。

「OpenClaw —— 技能（SKILL.md）」

OpenClaw 的扩展机制是 SKILL.md 文件。CLI-Anything 的适配方式就是写一份 openclaw-skill/SKILL.md，把 HARNESS.md 的核心规则浓缩进去——目录结构、实现要求、后端规则、打包规则，全在一个 110 行的 Markdown 里。

用户说 @cli-anything build a CLI for ./gimp，OpenClaw 加载这份 SKILL.md，Agent 按指示执行。

「Codex —— 技能（SKILL.md）」

和 OpenClaw 几乎一模一样。codex-skill/SKILL.md 的内容和 OpenClaw 版本高度相似——同样的结构、同样的规则，只是开头的触发描述适配了 Codex 的格式。外加一个 install.sh 脚本把文件复制到 Codex 的技能目录。

「OpenCode —— 斜杠命令（Commands）」

OpenCode 的扩展方式是把 .md 文件放到命令目录。CLI-Anything 在 opencode-commands/ 里放了 5 个文件：cli-anything.md、cli-anything-refine.md 等。和 Claude Code 版本的唯一区别是：文件头多了一个 subtask: true 标记（OpenCode 的格式要求），以及用 $1 代替命令参数。

「Qodercli —— 插件注册」

Qodercli 复用了 Claude Code 的插件格式。它的适配就是一个 setup-qodercli.sh 脚本，作用是把 cli-anything-plugin/ 的路径注册到 ~/.qoder.json 配置文件里。之后 Qodercli 就能像 Claude Code 一样使用 /cli-anything:cli-anything 命令了。

「GitHub Copilot CLI —— 同样复用插件」

直接 copilot plugin install ./cli-anything-plugin，安装的是和 Claude Code 同一套插件文件。

看出规律了吗？

「HARNESS.md 是唯一的"真相来源"。」 6 个平台的适配文件，都只是不同形状的"信封"，里面装的"信"是同一封。有的信封是 Plugin 格式，有的是 SKILL.md 格式，有的是 Commands 格式——但内容的核心永远指向同一份 HARNESS.md。

这也反过来印证了本文的主题：「当你的核心资产是一份提示词而不是代码时，跨平台适配就变得异常简单。」 不需要重写逻辑，不需要适配 API，只需要换个"信封"。

最后总结一句

CLI-Anything 的技术真相，出乎意料地简单：

「它没有写一行"引擎代码"。它写了一份极其精良的施工手册，然后让 AI Agent 按手册干活。」

21 款软件、1900+ 测试、6 个平台支持——全部是 Agent 按照这份手册生成的。

这可能是目前为止，"提示词工程"最有说服力的一个大规模实战案例。