从任意目标程序建立 Agent 友好的 CLI#

English · 架构 · 适配器契约 · 验收

流程从用户选择的软件和实际任务开始，不将任何特定软件、文件格式、操作系统、编辑模型或导出类型当作框架前提。安装单独执行：完成配置后，等待用户指定目标，再开展研究。

本文作为阶段清单；具体决策与交付物见工程手册，新建、扩展、恢复和版本适配见工作模式。开发助手与研究模板用于把研究过程保存为可接续的工作记录。

开始目标任务#

1. 从已安装 Skill 或指定仓库确定执行目录，读取本机配置与安装记录，通过 list 查看注册表，研究和注册持续使用该目录。
2. 确认指定软件、平台、构建及可用发行产物或端点，定位实际安装；目标准备属于任务时，获取所需发行版。无法取得目标时记录具体访问阻碍，不替换成其他软件。
3. 描述每项请求的输入、结果、副作用和依赖。明确执行模型（交互进程、服务、批处理程序、库或离线格式）、状态寿命（持久、会话或无状态）及操作效果（观察、计算或修改）。
4. 检查公开接口和已有适配器对这组操作的覆盖，复用足够的接口，为缺口按开发助手的 tools/research.py init 创建研究目录。
5. 确认选定分析器能检查相关产物，再将一项请求追踪到可调用入口。读取工程手册及匹配的运行时指南，记录未支持或未知的绑定，不生成猜测的原生调用。

研究目录保存假设和证据，适配器目录保存可复用实现与清单。将恢复的操作加入入口程序和工具目录，在选定框架中注册清单，再通过 call 执行。适配器契约定义这一连接。安装、创建研究记录、建立适配器骨架是不同步骤。

先定义用户需要的操作集合#

接受用户通过对话指定的软件和所需操作，或根据用户的工作目标拆解操作集合。记录每项操作的输入、预期输出、目标版本和可观察的成功标准，以及这些操作串联后的工作流。确认涉及的原生对象，以及哪些状态必须可编辑或持久化。跟踪请求、实现、验证和受阻的操作，避免用第一个成功调用替代整组需求。

环境准备、研究、CLI 实现、注册和验证由 Agent 执行，用户无须设计命令或运行框架内部步骤。交付物是能完成所需工作的可复用工具集合，不能仅是脚手架或内部函数列表。

检查已有公开自动化能力和适配器，针对缺失部分恢复内部操作。每个工具标明来源：公开接口、逆向内部入口、文件格式操作、外部辅助工具或适配器基础能力。

按产物类型选择方法#

使用 REA 或适合的等价工具，按目标产物选择后端。记录模块哈希和工具版本，区分静态推断与实际原生调用。不要求安装所有后端，也不把某个案例的注入方式套用于全部软件。

开发与证明#

1. 建立基线：确认产物与构建、适用的进程或端点、输入及相关状态；写入前保留受影响数据，无状态任务无须具备文档或运行中的编辑器。
2. 恢复生命周期：明确参数类型与单位、前置条件、对象来源、线程/调度器、所有权与释放、完成及失败信号。
3. 证明最小调用：对一项请求使用已知输入并独立检查结果。修改操作保存基线并检查适用的恢复、持久化；观察或无状态计算则检查返回数据及无意外副作用。
4. 建立适配器：用 init 生成脚手架，实现命令并注册清单。软件路径、ABI 和依赖放在适配器内；脚手架的状态查询不能证明原生能力。
5. 暴露契约：提供校验后的 JSON 输入、对象身份、来源、读写分类及可发现结果，保留结构化失败与能力限制。
6. 处理不确定性：在提交前后保存请求 ID、时间戳和证据。超时不代表取消；继续写入前先查明部分完成或未知结果。
7. 独立验收：针对实际软件编写断言，检查下述适用层次，同时保留成功和失败证据。
8. 交付：CLI、适配器清单、工具 schema、目标 Skill、版本范围、验收报告和用法。增加软件通过注册完成，不修改核心软件名单。

持续实现和验证，直到覆盖全部请求操作及其串联流程，或出现无法继续推进的具体阻碍。逐项报告剩余缺口，区分未实现、已实现但未验证和已验证的能力。后续对话任务复用已生成 CLI 和目标 Skill，无须重新开始开发。

通用验收层次#

由任务决定适用层次。只读操作可能不需要导出或持久化，但必须说明原因；缺少证据应标为 not-run，不能算通过。通用报告格式和证据完整性检查见验收说明。

框架边界#

核心负责发现、JSON 校验、调用、回执和证据管理；适配器负责原生执行、软件就绪、事务、产物验证及恢复语义。工具选择、桌面要求和导出方式由实际目标决定。

在 GitHub 查看本页源文档