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.mdLIBREOFFICE.md
它不是主要给 Agent 调用时读的。
它更像：
- 设计分析文档
- 软件专项 SOP
- 说明为什么 harness 要这样设计
通常会写：
- 软件本体怎么工作
- GUI 操作怎么映射到 CLI
- 为什么选这种后端策略
- 项目模型如何设计
所以它更偏开发者/维护者视角。
setup.py
它负责：
- 包怎么安装
- 安装后命令叫什么
- 依赖有哪些
也就是把这个 harness 变成一个真正可安装的 CLI 工具。
README.md
这是给人类用户看的使用说明。
通常会写：
- 怎么安装
- 怎么运行
- 有哪些命令
- 示例命令是什么
所以它偏“人类可读”。
<software>_cli.py
这是最关键的运行入口文件。
它负责：
- 定义命令树
- 定义参数
- 解析 CLI 输入
- 调用
core层 - 输出结果
- 处理错误
所以它不是“说明怎么用”的文档，而是：
真的被执行的 CLI 入口代码。
core/
这是业务逻辑层。
里面一般按领域拆模块，例如：
document.pywriter.pyexport.pysession.py
它负责真正的数据处理、状态变化、业务规则和导出策略。
utils/
这是工具层和后端桥接层。
最关键的通常是 backend 文件，例如：
gimp_backend.pylo_backend.py
它负责：
- 找真实软件
- 组装命令
- 调用 subprocess
- 检查输出文件
所以它是 harness 和真实软件之间的桥。
tests/
测试目录一般包括：
test_core.pytest_full_e2e.pyTEST.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是真正执行命令的入口代码
陕公网安备61011302002223号