命令行与自动化

命令行参考

界面里的能力，命令行同样开放：批量改造、脚本化验证、以及在没有人盯着的情况下跑一遍，都用这里。

通用约定

不带子命令运行时打印帮助，不会打开窗口。
--format text 给人看，--format json / jsonl 给脚本读；--json 是前者的简写。
--project-dir 指定要操作的项目；省略时用 ATH 当前打开的项目（各命令自己决定是否必需）。
--non-interactive 不等待任何交互输入，缺参数直接失败，适合脚本与外部智能体。
--correlation-id 会把同一次操作的日志串起来；--log-dir 指定日志目录。
--seed 固定随机种子让仿真可重复；--timeout 限制单次操作时长。

失败时的输出

{
  "status": "failed",
  "command": "app.validate",
  "error_code": "missing_field",
  "message": "缺少 id。",
  "device_accessed": false,
  "diagnostics": [
    { "path": "app.yaml", "code": "missing_field",
      "message": "缺少 id。", "suggestion": "补充 id 后重试。", "detail": null }
  ]
}

每条诊断都带 path（文件或字段位置）、message（中文说明）与 suggestion（下一步怎么做）；device_accessed 说明这次是否真的访问了设备。

退出码

码	含义
0	成功。
1	运行时错误。
2	校验错误：项目或候选文件不合法。
4	未定（pending）：判定还没结论。
5	模型不可用：需要模型的操作没跑起来。
6	设备不可用：没找到或打不开设备。

看设备

什么时候用：确认设备到底有没有接上、选的接口对不对、设备究竟发了什么。

ath device list                       # 系统里全部 HID 接口，不筛选、不打开
ath device describe --vendor … --product …
ath device capture --output ./cap.jsonl
ath device watch                      # 实时原始报文
ath device trace                      # 按当前 DD 解码后的输入变化
ath dd interfaces                     # 接口背后的物理设备与位置

输出：文本模式逐行描述接口与变化；json/jsonl 下每行是一条事件，包含时间戳与字段值，适合直接喂给脚本或另存为证据。

发现输入

什么时候用：想在没有协议文档的情况下，先把设备上有什么输入弄清楚。

ath discover devices                  # 发现工作区可选的接口
ath discover replay ./cap.jsonl       # 用录制做确定性发现
ath discover restore <INPUT_ID>       # 恢复被隐藏的输入
ath discover reset                    # 清空自动发现的输入与历史

输出：发现的输入标识与归属；reset 与 restore 会报告受影响的数量。

设备说明（DD）

什么时候用：要把「怎么识别、怎么解析」固定下来，或让外部智能体生成/修订说明。

ath dd help                           # 完整生成规则与流程，不需要打开项目
ath dd schema                         # JSON Schema（由代码模型生成）
ath dd info / paths / list / get      # 当前项目、保存位置、条目与原文
ath dd sources / devices / inspect-device
ath dd default-hid                    # 无资料时按标准描述符生成默认候选
ath dd validate ./candidate.json
ath dd submit ./candidate.json [--replace <ID> --expected-sha <sha> --request-id <uuid>]
ath dd record / recordings / replay-recording
ath dd verify / verify-programmatic / report
ath dd rename / delete / apply / simulate / replay

命令	典型输出字段
dd list	每个 DD 的标识、修订 id、显示名与内容摘要。
dd get	DD 原文、完整产品标识、规范版本与验证报告。
dd submit	登记结果与新的 dd_sha256，用于后续 --expected-sha 修订。
dd validate	诊断列表：格式、语义与参考向量逐项结论。
dd report	验证报告与能力证据；历史报告可用原 candidate_id 查询。

判定规则

什么时候用：写、改、审、跑判定；以及让外部智能体按契约提交规则。

ath dr help / schema / context / features
ath dr list / get / explain           # 读规则与用人话解释
ath dr validate ./rules.json
ath dr submit ./rules.json [--request-id <uuid>]   # 离线写入需 --expected-sha
ath dr test <RULE_ID> --case <CASE_ID>
ath dr history / diff / revert / graph

ath judgment validate / explain / evidence
ath judgment export / check / sync / import / replay

命令	典型输出字段
dr context	data.project_id、data.graph_sha256、data.rule_count、data.input_count、data.page_owned_rule_count、data.latest_revision。
dr submit	data.added、data.changed、data.graph_sha256、data.revision_id、data.cases。
dr features	当前项目里可被规则引用的输入标识。
judgment replay	每条规则的状态与整次判定结论。

项目与界面

什么时候用：批量搭页面、对齐组件、修正字段，或者只想检查项目是否完整。

ath project init / inspect / status / digest / refresh
ath app validate / inspect / export / normalize
ath app page-add / page-update / page-delete
ath app region-add / region-ungroup
ath app component-add / component-update / component-duplicate
ath app component-align / component-group / component-delete
ath app undo / redo
ath app rule-list / rule-add / rule-update / rule-delete

输出：inspect 给出页面、组件与规则数量；validate 给出诊断列表；normalize 用共享的确定性序列化器重写文件，适合让 diff 保持干净。

协议资料

什么时候用：手上有厂商资料，想把它变成项目能用的结构。

ath protocol import ./docs            # 导入资料到项目资料目录
ath protocol validate / inspect / normalize
ath protocol extract                  # 提取确定性事实并校验模型候选
ath protocol apply                    # 明确确认后应用已校验的候选

输出：报文、字段与命令数量的摘要；extract 会给出候选与校验结论。

仿真、验证与预览

什么时候用：没有真机时验证逻辑，或在改动前后比较同一份输入的结果。

ath validate [--output-ir ./ir.json]
ath run ./scenario.yaml [--replay-speed 2]
ath simulate list / inspect / replay / run
ath preview --page <PAGE_ID> [--scenario ./scenario.yaml]

输出：run 与 simulate run 给出判定结论与每条规则的状态；validate --output-ir 原子写入规范化 IR，适合做差异比较。

版本与交付

什么时候用：冻结一版、交付工位、或需要回滚。

ath version create / list / diff / fork / restore
ath version validate / release / retire
ath package build --output ./dist/station
ath package verify ./dist/station
ath publish --output ./my-product.art

输出：版本标识与生命周期状态；package 与 publish 给出产物路径与校验结果。

反馈与诊断

什么时候用：排错、收工位反馈、确认本机装的是什么。

ath doctor --json                     # 版本、日志、组件与设备状态
ath self-test                         # 软件层自检
ath feedback add / list / import / analyze
ath feedback review / apply / reject
ath frontend                          # ATH 交给界面的数据（不回溯历史）

doctor 的 logs 段给出日志目录、文件清单、丢弃行数与最近 10 条失败，细节见日志与诊断。

让模型帮忙起草（可选）

只有这两条命令会调用模型，其余命令都不联网、不调用模型：

ath generate "描述产品与测试需求" --source ./docs   # 按需求生成项目文件
ath agent ...                                        # 模型生成与修订的内部入口

想完全离线时，用 --recorded-llm 提供预先录制的模型回复，或用 --dry-run 只校验不写盘。

art 命令

产线侧的七条命令，都不需要打开窗口。

命令	什么时候用	输出
`art diagnostic`	确认工位机上装了什么、项目和平台能力如何。	版本、平台、项目与能力报告；--probe-hid 可附带接口枚举。
`art validate`	部署前校验项目及其规范化 IR。	诊断列表。
`art inspect`	看加载后的 app 与 protocol 文档摘要。	页面、组件与协议摘要。
`art preview`	只看界面视图模型，或先回放一份场景。	指定页面的视图模型。
`art run`	跑一次测试：给场景文件就用虚拟设备，省略就用真机。	运行时报告与判定结论。
`art dd interfaces`	确认工位机看到的 HID 接口与物理位置。	接口列表。
`art feedback`	把操作员的观察导出成反馈包。	反馈包文件路径。

art run --project-dir ./my-product
art run --bundle ./my-product.art --capture ./session.jsonl
art diagnostic --json