工程端 · ATH
项目与目录
项目就是一个普通文件夹。工程人员理解它的内容，交接、归档、排错都会容易很多。
新建与打开
点「新建项目」时选一个目录，ATH 把项目文件直接写进去，不额外建子目录，也没有单独的项目名字段： 项目和目录一一对应。界面里显示的项目名取自目录名，重命名目录后不需要改名，只要用「添加已有项目」 重新指一次新位置即可。
ath project init ./my-product # 新建
ath project inspect # 不打开窗口检查项目
ath project status # 完整性与候选版本
ath project digest # 内容摘要同名目录不会互相覆盖：项目按完整路径区分，界面上的提示会给出所在路径。
目录里有什么
| 文件 / 目录 | 作用 |
|---|---|
app.yaml | 界面定义：页面、区域、组件，以及判定图的入口。项目里「长什么样」和「什么算通过」都从这里读。 |
protocol.yaml | 协议文档：待测设备的选择条件、报文与字段。没有协议资料时可以是空的，后面再补。 |
manifest.json | 项目清单：项目标识与基本信息，ART 用它确认打开的是同一个项目。 |
| resources/ | 导入的协议资料、发现状态，以及运行期笔记（例如最近一次成功连接用的是哪个 DD）。 |
| versions/ | 不可变版本快照，用于比较、分叉、恢复与发布标记。 |
| reports/ | 运行时报告与结构化日志的默认位置。 |
journal.json | 事务日志：一次编辑要么整体写入，要么完全不落盘。 |
state.json | 编辑历史状态，支撑撤销与重做。 |
.ath-project.lock | 项目锁，避免两个进程同时改同一个项目。 |
复制、迁移与交接
- 整个目录复制走即可：文件之间用相对路径引用，换台电脑照常打开。
- ATH 记住的是「当前打开的项目」，ART 记住的是「工位配置的项目」，两者都存路径，不是项目内容。
- 交接给同事时，除了目录，最好一并说明用哪台设备、接在哪个接口；设备相关设置见 设备与连接。
- 归档时连同 versions/ 一起保留，以后需要比较或回滚时才有依据。
版本快照
版本是项目内不可变的快照，和 Git 相互独立：一次快照记录当前项目内容，之后可以比较、恢复、 分叉或标记生命周期。
ath version create --name "首版"
ath version list
ath version diff <A> <B>
ath version fork --output ../my-product-v2 # 把已发布项目复制成新的可编辑候选
ath version validate / release / retire # 校验 → 发布 → 退役什么时候需要快照
产线换版、判定规则调整、同一产品多个客户配置时。判定规则本身也有规则级修订历史， 可以精确到「哪一条规则被谁改成了什么」，见 判定规则。
打不开或校验不过
ath project status --format json
ath validate
ath project refreshstatus 会指出缺失或不一致的字段；refresh 重建派生状态与缓存。校验不过时不要手工改 YAML：优先用 ath app、ath dr 这类带校验的命令写入，避免留下半合法文件。