工程端 · ATH

设备说明（DD）

设备说明把「怎么认出这台产品、怎么读懂它发来的数据」写下来，让识别与解析不再依赖某一次调试。

一份说明对应一个产品

设备由厂商号、产品号和产品名共同确定，一个设备说明只描述一个产品。项目里可以保存多份说明（同一产品的不同连接模式，或不同型号），运行时按完整标识挑选对应的一份。

写在说明里的内容	用途
产品标识	VID、PID 与产品名，用来确认「插上来的就是这台」。
接口与端点	从哪个 HID 接口、哪个用法页读数据，避免选错接口。
解析规则	报文的字段切分与数值换算，例如把原始字节换算成摇杆位置。
能力清单	对外声明可用的输入与读数，组件与判定规则引用的是这些标识。

生成 → 校验 → 使用 → 修订

生成候选

ath dd help                    # 完整生成规则、流程与示例，不需要打开项目
ath dd schema                  # 内置 JSON Schema（由代码模型生成）
ath dd inspect-device --vendor <VID> --product <PID>
ath dd default-hid             # 没有资料时，按标准 HID 描述符生成默认候选

有资料时，把协议资料导入项目，再让外部智能体按 ath dd help 的规则生成候选； ATH 本身不调用模型。

校验与提交

ath dd validate ./candidate.json    # 结构与语义校验，不访问设备
ath dd submit ./candidate.json      # 校验通过后保存并登记，声明功能立即可用

提交后，说明里声明的输入就能在编辑器里给组件绑定。提交是幂等的：网络结果不明时，用同一个--request-id 与相同内容重试即可。

修订已有说明

ath dd get <DD_ID>                         # 读出原文与 dd_sha256
ath dd submit ./next.json --replace <DD_ID> --expected-sha <dd_sha256>

--expected-sha 是乐观锁：读到的摘要和实际写入时不一致就拒绝，避免两个人同时改同一份说明时把对方的修改覆盖掉。

使用与验证是两件事

说明提交后，声明的功能可以直接使用；真机验证是一项可选诊断，用来确认「按这份说明真的读得对」，而不是授予使用资格。历史验证失败、报告缺失都不会拦着你使用。

ath dd verify                       # 外部智能体主导的真机验证：建计划、启动、轮询、记录观察、停止
ath dd verify-programmatic          # 程序化观察真机输入，或执行一份明确的查询计划
ath dd record                       # 录制同一物理设备的全部 HID 接口
ath dd replay-recording             # 用录制离线回放这份说明，不接触真机
ath dd report <DD_ID>               # 读取验证报告与能力证据

验证报告描述的是「那一次观察」，不改变说明的内容，也不改变可用范围。
录制最长 10 分钟、最大 256 MiB，只读不写，不会向设备发送输出。
离线回放绑定的格式是「DD 端点 → interface-0.jsonl」，方便把接口与录制对上。

规范版本与迁移

设备说明固定它遵循的规范版本（当前提供 1.0、1.1、1.2 三份 Schema）。软件升级不会自动改写旧文件；遇到不支持的版本会明确提示，需要显式迁移。

ath dd list        # 列出项目全部 DD：标识、修订与内容摘要
ath dd rename <DD_ID> --name "手柄主模式"
ath dd delete <DD_ID>

显示名只影响界面，不改变产品标识；删除必须确认，正在使用或验证中的说明会被拒绝删除，历史报告保留。