命令行与自动化
外部智能体与自动化
ATH 自己不写设备说明、也不写判定规则，它提供规范、项目事实、校验、写入与验证入口；生成与修订交给外部智能体或脚本。
为什么这样分工
- 内容由模型生成，边界由软件守：任何写入都要先通过结构与语义校验，失败就完全不落盘。
- 软件不做判断之外的猜测：格式无效、引用损坏、设备不匹配都会给出可处理的中文诊断。
- 同一套入口既能被人用，也能被脚本用：文本给人看，JSON 给程序读。
两条命令线的共同契约
| 机制 | 解决什么 |
|---|---|
--request-id（UUID 幂等键） | 网络结果不明时，用同一个键和相同内容重试，不会写两次。 |
--expected-sha | 乐观锁：提交时带上读取时的摘要，别人先改过就拒绝，避免互相覆盖。 |
--non-interactive | 不等待任何交互输入，缺参数直接失败 —— 脚本不会卡在提示上。 |
| 分级退出码 | 用 2/4/5/6 区分校验错误、未定、模型不可用与设备不可用。 |
| 诊断信封 | 每条错误都带位置、说明与建议，见 命令行参考。 |
生成设备说明
- 01读规范
ath dd help给出完整的生成规则、命令流程、验证边界与示例；ath dd schema给出候选文件的 JSON Schema。两者都不需要打开项目。 - 02读事实
ath dd info看当前项目与摘要，ath dd sources读项目资料，ath dd devices与ath dd inspect-device只读枚举真实接口与描述符。 - 03校验候选
ath dd validate <文件>检查格式、语义与参考向量，不访问设备。 - 04提交
ath dd submit <文件>通过后保存并登记，声明的功能立即可用； 修订已有说明时加--replace与--expected-sha。 - 05需要时做真机诊断
ath dd verify由智能体主导真机验证（建计划、启动、轮询、转发用户观察、停止），ath dd verify-programmatic做程序化观察。两者都不改变说明内容与可用范围。
生成判定规则
- 01读规范与上下文
ath dr help给出规则语法与诊断对照；ath dr context给出项目句柄、 判定图摘要与最近一次修订；ath dr features列出可被规则引用的输入。 - 02写候选并校验
ath dr schema给出候选的 JSON Schema；ath dr validate做解析、语法、 编译、输入引用与自带用例的校验，不写项目。 - 03提交
ath dr submit把候选并入判定图，按规则 id 覆盖同一条规则，其余不受影响； 离线写入要带上ath dr context给出的--expected-sha， 不一致会返回dr_revision_conflict，此时重读再提交。 - 04复核与回滚
ath dr explain用中文说明一条规则在判什么；ath dr history与ath dr diff看修订；ath dr revert回滚成一条新修订。
一个最小循环
sha=$(ath dr context --json | jq -r .data.graph_sha256)
ath dr validate ./rules.json
ath dr submit ./rules.json --expected-sha "$sha" --request-id "$(uuidgen)"放进 CI
同一条命令既可以本地跑，也可以放进流水线；下面这条链是有意义的顺序：
ath self-test --json # 先确认软件自身可用
ath validate --json # 项目合法性与规范化 IR
ath run ./ci/scenario.yaml # 用固定场景跑一遍判定
ath simulate replay ./ci/capture.jsonl
ath package build --output ./dist/station
ath package verify ./dist/station --json全部只读或只写产物，不会打开窗口、不会访问真机。判定未结束时退出码是 4， 因此「未定」不会被误当成成功。需要设备时用退出码 6 区分「设备不可用」与真正的失败。