参考

文件与格式

项目是纯文本，方便版本管理与人读。这一页说明谁负责什么，以及哪些文件不该手工改。

目录一览

路径	职责	能否手工编辑
`app.yaml`	页面、区域、组件与判定图的入口。	可以，但优先用 ath app / ath dr 写入。
`protocol.yaml`	待测设备的选择条件、报文与字段。	同上，优先用 ath protocol。
`manifest.json`	项目标识与基本信息。	不建议：由工具维护。
resources/	导入的协议资料、发现状态、运行期笔记。	资料可以放，状态文件不要改。
versions/	不可变版本快照与生命周期标记。	不建议：用 ath version。
reports/	运行时报告与结构化日志的默认位置。	只读。
`journal.json`	事务日志，保证编辑整体写入。	不要改。
`state.json`	编辑历史状态。	不要改。
`.ath-project.lock`	项目锁，避免并发修改。	不要删：正常退出会释放。

app.yaml

文档头声明规范版本与类型（schema_version、kind: ath.app）与 project_id，主体是页面与判定。

schema_version: "0.1"
kind: ath.app
project_id: <项目标识>
pages:
  - id: p1
    title: 整机测试
    prompt: 请按顺序操作
    layout: { … }
    regions: []
    components:
      - id: c1
        type: button          # 九种主体之一
        label: 启动键
        feature_id: dd:dut:vendor.button_start
        prompt: 按下启动键
        layout: { … }
        properties: { … }
judgment: { … }               # 判定图（唯一来源）
test_rules: []                # 旧格式入口，最终并入判定图

protocol.yaml

协议文档声明 kind: ath.protocol 与 project_id，主体是设备、报文与命令：每个报文有方向、负载长度与字段切分，字段按位偏移与位长描述。

schema_version: "0.1"
kind: ath.protocol
project_id: <项目标识>
devices: []      # 待测设备的选择条件（VID/PID/用法页/接口）
reports:         # 设备上报的报文与字段
  - id: 1
    direction: input
    payload_bytes: 8
    fields:
      - id: axis
        bit_offset: 0
        bit_length: 8
commands: []     # 需要写设备时才用到

设备说明与规范版本

设备说明保存的是「一个产品一份契约」：产品标识、端点与解析方式。它固定所遵循的规范版本，目前提供 1.0、1.1、1.2 三份 Schema（dd.schema.json）。

软件升级不会自动改写旧说明；遇到不支持的版本会明确提示，需要显式迁移。候选文件用 ath dd schema 取到的 Schema 校验，再通过 ath dd submit 写入。

运行期笔记

resources/dd-last-connected.json 记录「这个项目最近一次成功连接用的是哪份说明」。它是运行状态而不是文档：不参与编辑历史，损坏或缺失也不会让项目失效。

版本目录

versions/<版本>/metadata.json      # 快照元数据
versions/<版本>/validation.json    # 校验结果
versions/<版本>/release.json       # 发布标记
versions/<版本>/retirement.json    # 退役标记

快照内容不可变。比较、恢复、分叉都通过 ath version 完成，不要直接改写这些文件，否则历史与校验会对不上。

机器可读输出

需要程序处理时用 --json 或 --format jsonl：成功的数据在 data 段，失败走统一信封（status、error_code、message、diagnostics），字段说明见命令行参考。