OpenCLI 学习 04：Harness 目录与文件分工

1. 为什么我在这一部分容易混乱

因为一个 harness 目录里通常会同时出现：

• 设计文档
• README
• Skill
• CLI 入口
• core 业务模块
• utils 后端桥接
• tests

如果不先按职责区分，很容易把这些文件都看成“某种说明文档”或者“某种脚本入口”。

2. 一个标准 harness 的结构

我目前可以把一个标准 harness 粗略理解成：

<software>/
└── agent-harness/
    ├── <SOFTWARE>.md
    ├── setup.py
    └── cli_anything/
        └── <software>/
            ├── __main__.py
            ├── README.md
            ├── <software>_cli.py
            ├── core/
            ├── utils/
            ├── tests/
            └── skills/

3. 每一层是干什么的

<SOFTWARE>.md

例如：

• GIMP.md
• LIBREOFFICE.md

它不是主要给 Agent 调用时读的。

它更像：

• 设计分析文档
• 软件专项 SOP
• 说明为什么 harness 要这样设计

通常会写：

• 软件本体怎么工作
• GUI 操作怎么映射到 CLI
• 为什么选这种后端策略
• 项目模型如何设计

所以它更偏开发者/维护者视角。

setup.py

它负责：

• 包怎么安装
• 安装后命令叫什么
• 依赖有哪些

也就是把这个 harness 变成一个真正可安装的 CLI 工具。

README.md

这是给人类用户看的使用说明。

通常会写：

• 怎么安装
• 怎么运行
• 有哪些命令
• 示例命令是什么

所以它偏“人类可读”。

<software>_cli.py

这是最关键的运行入口文件。

它负责：

• 定义命令树
• 定义参数
• 解析 CLI 输入
• 调用 core 层
• 输出结果
• 处理错误

所以它不是“说明怎么用”的文档，而是：

真的被执行的 CLI 入口代码。

core/

这是业务逻辑层。

里面一般按领域拆模块，例如：

• document.py
• writer.py
• export.py
• session.py

它负责真正的数据处理、状态变化、业务规则和导出策略。

utils/

这是工具层和后端桥接层。

最关键的通常是 backend 文件，例如：

• gimp_backend.py
• lo_backend.py

它负责：

• 找真实软件
• 组装命令
• 调用 subprocess
• 检查输出文件

所以它是 harness 和真实软件之间的桥。

tests/

测试目录一般包括：

• test_core.py
• test_full_e2e.py
• TEST.md

作用分别是：

• 单元测试
• 端到端测试
• 测试计划与测试结果记录

这部分是为了证明 harness 不是“看起来能用”，而是真的可验证。

skills/SKILL.md

这个才是真正偏给 Agent 读的说明文档。

它主要告诉 Agent：

• 这个 harness 是干什么的
• 适合什么场景
• 什么时候应该调用
• 有哪些命令组
• 调用时有哪些注意事项

所以它更偏 Agent 视角。

4. 我目前对三个关键文档的区分

<SOFTWARE>.md

• 回答：为什么这样设计
• 偏开发/维护视角

README.md

• 回答：人类怎么使用
• 偏用户视角

SKILL.md

• 回答：Agent 什么时候该调用、如何调用
• 偏 Agent 视角

5. 我目前对 <software>_cli.py 的理解

它不是文档，而是执行入口。

也就是说，当用户或 Agent 真的输入：

cli-anything-libreoffice export render report.pdf

最后就是 libreoffice_cli.py 里对应的命令函数被执行。

所以它负责的是：

• 接受命令
• 调用业务逻辑
• 返回结果

6. 当前我的一句话总结

一个 harness 目录本质上是在把“设计说明、运行入口、业务逻辑、后端桥接、测试验证、Agent 说明”打包到一起。

而我现在最重要的区分是：

• <SOFTWARE>.md 不是给 Agent 主要调用时读的
• SKILL.md 才是更偏给 Agent 使用的说明
• <software>_cli.py 是真正执行命令的入口代码