从闭源软件研发 CLI 的工程手册#
本文供实际工作的 Agent 使用。用户通过对话指定软件和有价值的操作集合，Agent 完成研究、实现、验收并交付可复用工具。安装本仓库不自动启动目标研究；已有适配器在版本和能力范围匹配时可以复用。
根据目标发行产物、运行时及所需操作选择分析与接入路线，同时恢复调用契约和可靠执行所需的状态转换。
1. 将需求拆成操作集合#
记录实际输入、预期原生结果、约束及必须保持不变的状态，拆解工作流中的操作和依赖。用后置条件与对象归属界定每项操作；名称相近的函数可能影响不同对象，或处于事务的不同阶段。
使用开发工具建立研究目录。task.json 保存范围，operations.json 分别跟踪每项操作。这些记录由 Agent 维护，不交给用户填表。
每项操作记录：
- 公开自动化接口已有的覆盖，以及具体缺失行为；
- 目标对象、参数单位、可观察后置条件及不应变化的对象；
- 执行模型、状态生命周期、操作效果（观察、计算或修改），以及输入、权限、会话资源等前置条件；
- planned、researching、implemented、verified 或 blocked 状态；
- 实验及验收证据；受阻项还应说明下一步缺少的条件。
已有公开接口足够时直接复用。分别标明公开调用、逆向内部入口、文件格式、外部辅助工具和框架基础能力。软件闭源本身不证明某项操作需要逆向。
完成条件： 明确的操作集合及一条有实际意义的组合流程。第一个实验成功后，继续完成整组需求。
2. 固定目标并选择研究路线#
记录版本、架构、相关产物哈希、运行时和真实存储路径。按请求操作确认就绪条件：可能是可读取产物、可调用库、已初始化进程或可访问服务；按需记录激活和会话要求。进程运行不等于操作就绪，无界面或离线目标无须具备窗口。修改前保留受影响的用户数据，或使用专用样本。
按研究入口指南选择原生分析、托管反编译、元数据、打包脚本、协议或文件格式路线。从命令注册、方法元数据、错误文本、序列化器、导出服务或 UI 处理器等有价值线索出发，围绕请求行为逐步扩展。全量分析大模块只是可选手段，不要反复重启无法完成的分析。
记录工具来源和覆盖范围。部分元数据解析不等于完整反编译；REA 受限后转用定向反编译工具是可行路线，但应保留每条观察实际来自什么工具。普通 CLI 执行不应反复进行研究。
完成条件： 精确目标身份、选定路线、候选入口和能区分假设的首次实验。未知调用约定仍明确标为未知。
3. 恢复完整业务操作#
优先选择能维护软件内部一致性的业务入口。内部命令有价值，但名称或帮助文本不能证明当前会话模式下可执行。沿业务处理链追踪前置条件与完成机制。
每个采用的入口填写接口说明卡：
| 关注点 | 必须查明的内容 |
|---|---|
| 身份 | 模块与版本、定位证据、业务接收对象来源、稳定对象 ID |
| 调用 | 参数类型、顺序、编码、单位、结构布局、调用约定 |
| 执行 | 调用上下文、线程或事件循环、初始化及适用的会话模式 |
| 所有权 | 借用/持有对象、引用增减、回调和缓冲区的生命周期 |
| 业务语义 | 结果含义、副作用、一致性和关联资源；使用事务或通知时查明其要求 |
| 完成 | 与请求相关联的终态信号、失败信号、状态查询 |
| 范围 | 未支持状态、版本限制、撤销和恢复方式 |
按需读取原生与嵌入运行时、托管编辑事务或 WinRT 生命周期。一个软件可组合多条路线；接口清单不能证明任意调用已受支持。
完成条件： 能对正确对象进行一次有限调用，知道如何观察完成，及未完成时如何安全停止后续操作。
4. 证明一条完整路径#
用已知输入通过预期业务入口执行一项请求操作，并独立核查结果。查询操作验证返回值及范围；计算操作对照已知结果并检查输出；修改操作保留基线、回读变化，并验证任务需要的恢复或持久化。界面同步和撤销只在目标及操作提供这些能力时适用。
实验记录包含假设、输入、基线、调用、观察、反证、结果及下一步决策。结果可为 observed、rejected、partial、unknown、not-run。崩溃或挂起提供了候选入口的证据，不意味着可以直接重试同一写操作。
分开记录以下事实：
- 桥接接受请求。
- 正确的原生业务操作完成。
- 返回数据、计算结果或状态变化符合预期后置条件。
- 任务要求时，其他可观察界面或接口同步更新。
- 需要的持久状态或生成产物包含结果；不适用时记录原因。
一个实验可覆盖多个层次，但返回码不能替代这些观察。多个生命周期调整共同解决崩溃时，应记录成功的组合，不能未经隔离实验就把原因归于某一步。
完成条件： 一条有证据、边界明确的成功路径。随后继续实现其他请求操作。
5. 建立目标适配器#
确定目标和范围后再用框架脚手架。原生实现、版本映射、依赖放入独立适配器，通过适配器契约注册；新增软件不应增加核心中的软件名分支。
推荐按实际职责分层：
CLI / 参数契约校验
→ 请求与目标绑定
→ 窄接口桥接 / 会话控制器
→ 软件业务操作
→ 原生观察和关联结果
持久桥接、一次性 worker、已有本地服务或文件传输均可，根据对象生命周期和业务语义选择。独立 Python worker 可隔离自身故障，不能隔离被注入应用的崩溃。
先实现观察，再扩大写入范围。暴露稳定 ID 和明确的目标选择；名称只有在无歧义时才能用于定位。定义单位、坐标系、源位置与目标位置、舍入和不支持的组合。批量写入前校验全部输入，执行后保留逐步结果，因为原生批次可能不具备原子性。
正式接口只暴露已审查的业务操作。任意反射或求值探针留在忽略的研究目录。模块保护、原生地址映射和所有权逻辑属于适配器；不要为了让新版本运行而放宽哈希检查。
完成条件： 可调用命令、相符 schema、有意义的错误和状态观察；研究探针与交付接口分离。
6. 明确状态与恢复#
遵循状态与恢复指南。请求绑定到实际使用的身份：产物或输入版本、构建、进程生命周期、作业、会话或文档；复用的 PID 或相同标题不足以确认身份。按目标语义在生命周期变化后使旧句柄失效，无状态操作无须虚构项目或会话。
框架 journal 提供提交记录、锁和历史回执，并非原生事务。每个适配器定义提交前拒绝、部分变化和未知结果的报告方式，保存输入摘要、创建 ID 和已完成步骤。超时不等于取消；先查询状态，再决定续做、补偿或停止。
预览或导出临时修改也算写操作。保存相关基线、设置临时状态、执行业务，并在确认安全后恢复。恢复无法确认时明确报告，并阻止冲突写入，不能悄悄解除保护。
完成条件： 后续 Agent 无须盲目重复请求，就能区分已经提交什么、确认变化了什么、还有什么未知。
7. 验证原生结果与有用反馈#
遵循验证与观察指南及通用验收层次。扩大实现前就设计检查，使其能区分真实成功与看似合理的假阳性。
使用具有已知数值、标识、编码和预期结构的小型诊断样本。任务需要时再使用真实输入，检查格式差异、数值边界、关联资源和组合行为。记录输入来源；外部准备的输入及辅助工具生成的输出，应与逆向接通的原生执行分别归属。
逐项验证请求操作的原生后置条件与适用的无关状态，通过交付 CLI 运行组合流程，并独立检查实际输出。需要持久化时，区分同会话重开数据与启动新进程；任务要求可编辑性时再检查原生可编辑性。只读或无状态任务无须执行保存重开。
每项检查记录执行时间、构建、输入与结果，没有执行证据的检查标为未验证。不同构建或配置的证据需要明确评估兼容性。报告结构和哈希检查记录完整性，原生断言检查实际行为。
完成条件： 逐操作覆盖、组合流程证据，以及明确未验证或不适用项。不能把静态候选或脚手架检查升级为原生支持。
8. 为下一个 Agent 交付#
提供实现、清单、工具目录、目标 Skill、命令说明、测试构建、依赖、限制与恢复指引。文档生成器从已保存目录和覆盖信息生成说明，不导入 hook、不接触应用。审阅生成内容，并补充 schema 无法表达的原生语义。
按交付与维护指南完成安装、升级及交接。下一个 Agent 应能发现命令、定位所需输入及执行上下文、检查就绪状态、执行任务并核查结果，无须原研究会话或瞬时内存地址。
交付物包含依赖、许可证和必要署名；目标二进制、本机配置及工作中的研究数据留在分发包之外。