参考

日志与诊断

排错从读日志开始：软件会把失败写进标准日志，问题往往不需要再复现一次。

日志放在哪

默认在用户日志目录下，可以用 --log-dir 或 --project-dir 指定。
ART 默认把结构化日志写进项目的 reports/ 目录。
按天滚动，保留最近 14 份；写入跟不上时会统计并报告被丢弃的行数，而不是静默丢失。

先跑 doctor

ath doctor --json

输出里的 logs 段给出日志目录、文件清单、丢弃行数和最近 10 条失败 —— 大多数情况下，看完这一段就知道该往哪里看。其余部分覆盖版本、组件与设备状态。

字段	用途
logs.directory	日志目录；用 jq / grep 继续检索的入口。
logs.files	当前保留的文件清单。
logs.dropped_lines	被丢弃的行数；非零说明写入压力过大。
logs.recent_failures	最近 10 条失败，含事件名、错误码与建议。

失败记录长什么样

日志是标准 JSON Lines：一行一个事件。用户可见的失败会以固定事件写入，字段如下。

target: agentx_testhub::failure
event:  operation.failed
operation / sequence / total   # 哪个操作、第几步、共几步
code / path                    # 错误码与文件或字段位置
message / suggestion / detail  # 中文说明、下一步建议、原始细节

也就是说：界面或命令行给用户看的每一条失败，日志里都有对应的一条，不需要用户复述现象。

一次典型的排错

01读 doctor先看 ath doctor --json 的 logs 段，确认时间与错误码。
02检索日志用 jq 按错误码、操作或时间过滤；需要上下文时按 --correlation-id 把同一次操作的事件串起来。
03给结论日志已能定位时直接给结论；日志不足时先补记录点，再请用户配合操作。

ath doctor --json | jq '.logs.recent_failures'
grep '"code":"device_unavailable"' ~/Library/Logs/…/*.jsonl | tail -20

工位侧的诊断

art diagnostic --json            # 版本、平台、项目与能力报告，不访问设备
art diagnostic --probe-hid       # 顺带枚举 HID 接口，不打开、不发送报文

ART 界面里的运行时诊断对话框显示的是同一份信息：版本、平台、架构、进程号、WebView 版本、日志目录与被丢弃的日志行数。操作员上报问题时带上它就够用，见操作员排障。