CLI-Anything 的 Pi Coding Agent 扩展：用 5 个斜杠命令把任意 GUI 应用变成 Agent 原生 CLI

导读

CLI-Anything 项目通过一套名为 "Agent Harness"（GUI-to-CLI）的方法论，让 AI Agent 无需显示器与鼠标即可操作原本面向人类的 GUI 软件。本文聚焦仓库中面向 Pi Coding Agent 的官方扩展（位于 .pi-extension/cli-anything/），讲解它的安装方式、5 个斜杠命令（slash command）的用法，以及它如何通过注入 HARNESS.md 方法论与命令规范，驱动 Agent 为任意拥有代码库的软件构建"有状态、可测试、可发布"的 CLI harness。读完本文，你将掌握该扩展的完整使用流程、底层消息注入机制、路径重映射规则，以及扩展的目录结构与二次开发要点。

扩展是什么：把方法论注入 Agent 会话的"桥"

CLI-Anything 的 Pi 扩展本质上是一个编译期上下文注入器。它注册 5 个斜杠命令，当命令被调用时，扩展会读取 HARNESS.md 方法论文档与对应的命令规范（command spec），把二者连同用户输入参数一起组装成一条结构化消息，并通过 Pi 的 Extension API 注入到当前 Agent 会话中，从而让 Agent 能够为任何 GUI 软件构建功能完整的 CLI harness。

扩展默认是全局安装的：安装后 /cli-anything 系列命令在所有 Pi 项目中均可用。其完整说明见 .pi-extension/cli-anything/README.md。

安装与卸载

全局安装（推荐）

在仓库根目录执行：

cd CLI-Anything
bash .pi-extension/cli-anything/install.sh

从 install.sh 的源码可见，脚本会做如下几件事：

1. 定位仓库根目录（优先使用 git rev-parse --show-toplevel，失败则向上逐级查找 .git 或 CONTRIBUTING.md）；
2. 在 $HOME/.pi/agent/extensions/cli-anything/ 下创建 commands/、guides/、scripts/、templates/ 子目录；
3. 复制扩展入口文件 index.ts；
4. 从规范源（canonical source） cli-anything-plugin/ 目录复制命令规范（commands/*.md）、指南（guides/*.md）、模板（templates/*）、HARNESS.md，以及 repl_skin.py、skill_generator.py 和相应 Python 测试。

也就是说，install.sh 承担了"把插件资产汇聚到扩展目录"的分发工作，而 .pi-extension/cli-anything/ 只保留入口点与安装脚本，方法论文档与命令规范的真实源头在 cli-anything-plugin/。

卸载

bash .pi-extension/cli-anything/install.sh --uninstall

脚本会直接删除 $HOME/.pi/agent/extensions/cli-anything/ 目录，若目录不存在则提示"already uninstalled"。

验证安装

安装完成后，在 Pi 中执行 /reload 或重启 Pi，然后输入 /cli-anything。若扩展正常加载，命令即被识别并进入参数处理流程。

5 个斜杠命令一览

命令	功能
/cli-anything <path-or-repo>	为任意 GUI 应用构建完整的 CLI harness
/cli-anything:refine <path> [focus]	精炼已有 harness，提升功能覆盖度
/cli-anything:test <path-or-repo>	运行 harness 的测试并更新 TEST.md
/cli-anything:validate <path-or-repo>	依据 HARNESS.md 标准校验 harness
/cli-anything:list [options]	列出所有 CLI-Anything 工具（已安装与已生成）

从 index.ts 的注册逻辑可以确认：每个命令都调用 pi.registerCommand(name, { description, handler })，handler 会先做 args.trim() 参数检查，无参数时通过 ctx.ui.notify(usage, "warning") 给出用法提示而不会注入会话；参数合法时调用 injectCommandContext() 注入完整上下文。每个命令对应 cli-anything-plugin/commands/ 下的一份命令规范文件（cli-anything.md、refine.md、test.md、validate.md、list.md）。

典型用法示例

# 为本地 GIMP 源码构建 CLI
/cli-anything ./gimp

# 从 GitHub 仓库构建（Agent 会先克隆到本地再分析）
/cli-anything https://github.com/blender/blender

# 精炼已有 harness，并聚焦某块功能
/cli-anything:refine ./gimp "batch processing and filters"

# 运行测试并更新 TEST.md
/cli-anything:test /home/user/gimp

# 校验 harness 是否符合 HARNESS.md 标准
/cli-anything:validate /home/user/gimp

# 列出所有已安装/已生成的 CLI 工具
/cli-anything:list

各命令的职责细分

/cli-anything（构建） 对应 cli-anything.md，接受本地源码路径或 GitHub 仓库 URL（不接受裸软件名如 gimp）。其内部按阶段推进：Phase 0 源码获取（URL 则先 clone）→ Phase 1 代码库分析 → Phase 2 CLI 架构设计 → Phase 3 实现（目录结构、core 模块、Click CLI + REPL、--json 输出）→ Phase 4 测试规划 → Phase 5 测试实现 → Phase 6 测试文档 → Phase 6.5 SKILL.md 生成 → Phase 7 PyPI 打包。产出物包括 <software>/agent-harness/cli_anything/<software>/ 子包、仓库根 skills/cli-anything-<software>/SKILL.md 及兼容副本等。

/cli-anything:refine（精炼） 对应 refine.md，只接受本地路径。执行"盘点当前覆盖 → 重扫软件能力 → 差距分析（按高影响/易实现/可组合性排序）→ 实现新命令 → 扩充测试 → 更新文档"六步。可选的 [focus] 参数（自然语言描述，如 "batch processing and Script-Fu filters"）会把差距分析与实现范围收窄到指定功能区。

/cli-anything:test（测试） 对应 test.md，定位 harness 后用 pytest -v -s --tb=short 运行测试，并从输出中验证 [_resolve_cli] Using installed command: 出现（确认测试跑的是安装后的真实命令），最后把结果追加到 TEST.md 的 Test Results 小节。若测试失败，不会覆写 TEST.md 中此前的通过记录。

/cli-anything:validate（校验） 对应 validate.md，按 8 个维度（目录结构、必需文件、CLI 实现标准、核心模块、测试标准、文档、PyPI 打包、代码质量）逐项核对，最后生成形如 Overall: PASS (52/52 checks) 的报告。

/cli-anything:list（列举） 对应 list.md，支持 --path、--depth、--json 三个选项：用 importlib.metadata.distributions() 扫描以 cli-anything- 开头的已安装发行版，用 glob 模式 **/agent-harness/cli_anything/*/__init__.py 扫描本地生成目录，按软件名去重合并后以表格或 JSON 输出。

命令执行原理：消息构造与注入链路

扩展的核心逻辑全部集中在 index.ts，链路如下：

1. Command Registration（命令注册）：cliAnythingExtension(pi) 默认导出函数在加载时向 Pi 的 Extension API 注册 5 个斜杠命令；
2. Context Injection（上下文注入）：命令被调用时，injectCommandContext() 通过 readAsset("commands", <spec>.md) 读取对应命令规范，再调用 buildCommandMessage() 组装消息；
3. Message Construction（消息组装）：见 index.ts，生成的单条 user message 依次包含：
   • 标题 [CLI-Anything Command: <commandName>]；
   • 置顶的 ## CRITICAL: HARNESS.md — Read First（完整方法论文本，强制 Agent 先读）；
   • ## Command Specification: <commandName>（对应命令规范全文）；
   • ## User Arguments（用户原样输入）；
   • ## Extension Asset Paths（guides/、scripts/、templates/ 在本机的绝对路径，指示 Agent 用 read 工具按需读取）；
   • ## Path Remapping Rules（5 条路径重映射规则）；
   • 结尾指令：严格执行方法论与规范、先读 HARNESS.md、从上述目录读取资源并应用路径重映射。
4. Agent Execution（Agent 执行）：pi.sendUserMessage(message) 把整条消息注入会话，触发一次拥有全部工具的完整 Agent turn；
5. Path Remapping（路径重映射）：自动把规范中的容器路径映射到本地系统路径。

资产读取的安全边界

readAsset()（index.ts）用 join(__dirname, ...paths) 把相对路径解析到扩展自身目录，读取失败时抛出带明确文件名与绝对路径的报错信息。它通过 import.meta.url + dirname/fileURLToPath 计算 __dirname，因此资产必须随 index.ts 同目录存在（由 install.sh 保证）。

路径重映射规则

命令规范与 HARNESS.md 是按容器环境编写的，扩展要求 Agent 应用如下映射：

容器路径	本地路径
/root/cli-anything/<software>/	当前工作目录（软件源码在用户参数指定处）
cli-anything-plugin/repl_skin.py	扩展目录 scripts/repl_skin.py（从 cli-anything-plugin 复制而来）
cli-anything-plugin/skill_generator.py	扩展目录 scripts/skill_generator.py
~/.claude/plugins/cli-anything/	<extension>/（即 $HOME/.pi/agent/extensions/cli-anything/）
HARNESS.md 内相对路径（如 guides/...、templates/...）	基于上述资产目录解析，而非当前工作目录

其中"单点事实源"原则值得注意：repl_skin.py、skill_generator.py 的权威副本位于 cli-anything-plugin/，install.sh 安装时把它们复制进扩展的 scripts/，扩展侧只消费本地副本。

目录结构与规范源

扩展目录

.pi-extension/cli-anything/
├── index.ts                    # 扩展主入口
├── install.sh                  # 全局安装脚本
├── README.md                   # 本说明文件
└── tests/
    └── test_extension.test.ts  # 命令注册测试

安装后的目录

install.sh 会在 ~/.pi/agent/extensions/cli-anything/ 生成：

commands/   # 5 份命令规范（来自 cli-anything-plugin/commands/）
guides/     # 实现指南（来自 cli-anything-plugin/guides/）
scripts/    # repl_skin.py、skill_generator.py
templates/  # SKILL.md.template
tests/      # skill_generator 相关 Python 测试
HARNESS.md  # 方法论（来自 cli-anything-plugin/HARNESS.md）
index.ts

注意：规范源不重复

skill_generator.py 的测试位于 cli-anything-plugin/tests/（与源码同目录），而不是扩展目录内。README 同时强调：命令规范、指南、脚本、模板与 HARNESS.md 的权威版本都在 cli-anything-plugin/，.pi-extension/ 里的内容由 install.sh 安装时拷贝生成，扩展运行时通过 __dirname 从自身目录读取。修改方法论或命令规范，应改 cli-anything-plugin/ 下的对应文件而非扩展目录副本。

测试验证：行为可被自动化保障

tests/test_extension.test.ts 使用 Vitest + 对 node:fs 的 mock 验证扩展行为，可用 npx vitest run tests/test_extension.test.ts 运行。覆盖点包括：

• 默认导出为函数、恰好注册 5 个命令、命令名齐全（cli-anything、cli-anything:refine、cli-anything:test、cli-anything:validate、cli-anything:list）；
• 每个命令都有非空 description 与函数型 handler；
• 注入的 user message 必须同时包含 [CLI-Anything Command: ...]、HARNESS.md 内容、命令规范内容、用户参数、Extension Asset Paths 与 Path Remapping Rules；
• 无参数调用 /cli-anything、:refine、:test、:validate 时只触发 ui.notify 的 warning 而不调用 sendUserMessage；
• /cli-anything:list 无参数时照常注入（参数占位为 (no arguments — scan current directory)），并透传 --json --depth 2 之类的 flag；其 getArgumentCompletions("--j") 返回 --json、未知前缀返回 null。

这些测试直接印证了 README 中描述的"5 步工作流"，可作为理解扩展行为的可执行规格。

方法论衔接：HARNESS.md 在扩展中的作用

README 反复强调"注入 HARNESS.md 方法论"，被注入的正是 cli-anything-plugin/HARNESS.md。它的核心主张贯穿整个扩展体系：

• 通用 SOP：代码库分析 → CLI 架构设计（有状态 REPL / 一次性子命令 / 两者兼有）→ 实现（数据层、探针命令、变更命令、真实软件后端、会话与锁、统一 REPL 皮肤）→ 测试规划（TEST.md Part 1）→ 测试实现 → 测试文档（TEST.md Part 2）→ SKILL.md 生成 → PyPI 发布；
• 两大铁律：第 1 条是"使用真实软件而非重新实现"（CLI 必须调用 libreoffice --headless、blender --background、gimp -i -b 等真实后端）；第 2 条是警惕"渲染落差"（直接操作工程文件时必须处理引擎渲染时应用的效果）；
• 命名空间约定：cli_anything/ 目录不能有 __init__.py（PEP 420 namespace package），各软件子包（gimp/、blender/ 等）必须有；
• 仓库中的 gimp/、blender/、libreoffice/、shotcut/ 等目录即该方法论的实际产出，可用于对照学习。

开发与二次扩展

若要修改或扩展该扩展本身，README 给出的指引是：

1. 修改 .pi-extension/cli-anything/index.ts —— 影响命令行为；
2. 修改 cli-anything-plugin/commands/ 下的 md 文件 —— 影响命令规范；
3. 修改 cli-anything-plugin/HARNESS.md —— 影响方法论（规范源）；
4. 修改 cli-anything-plugin/guides/ —— 影响实现指南。

由于安装脚本每次执行都会从 cli-anything-plugin/ 重新拷贝，开发流程一般是"改规范源 → 重新运行 install.sh → /reload"。

依赖项

• @mariozechner/pi-coding-agent —— 提供 ExtensionAPI、registerCommand、sendUserMessage 等 Pi 扩展接口；
• Node.js 内置模块：fs（readFileSync）、path（join、dirname）、url（fileURLToPath）。

许可证

该扩展沿用 Apache License 2.0（详见仓库根目录 LICENSE）。

延伸阅读

• 方法论权威文档：cli-anything-plugin/HARNESS.md
• 仓库内各软件的 harness 实例，如 gimp/agent-harness、blender/agent-harness
• 仓库内已有的 SKILL 产物，见 skills/
• 贡献指南：CONTRIBUTING.md

总的来说，.pi-extension/cli-anything/ 的价值在于把 HARNESS.md 那套"把软件做成 Agent 原生"的方法论，低成本地接入 Pi Coding Agent：一条安装命令、5 个斜杠命令，即可让 Agent 在任意项目中完成从"给 GUI 软件建 CLI"到"精炼、测试、校验、盘点"的完整闭环。