开始使用

安装与更新

首次执行完成安装，以后执行同一条命令更新到最新发布版。ATH、ART 的桌面应用和命令行同步更新。

安装或更新

macOS（Apple Silicon）

curl -fsSL https://agentx.plus/ath/install.sh | bash

Windows x64（PowerShell）

irm https://agentx.plus/ath/install.ps1 | iex

只要其中一个应用时加参数：macOS 用 --app ath 或 --app art，Windows 用 -App ath 或 -App art，具体命令见下面的「换安装位置，或只装一个应用」。

装到哪里

更新时沿用已有位置：命令行优先识别 PATH 中的程序，桌面应用识别已有安装记录与系统常用位置（Windows 还会读取开始菜单快捷方式）。首次安装的默认位置如下；用参数指定的位置会被记住，下次无需重复填写。

平台	桌面应用	命令行
macOS	~/Applications/ATH.app、~/Applications/ART.app	~/.local/bin/ath、~/.local/bin/art
Windows	%LOCALAPPDATA%\AgentX TestHub\ATH\ATH.exe 与 ART\ART.exe	%LOCALAPPDATA%\AgentX TestHub\bin\ath.exe 与 art.exe

macOS 上如果 ~/.local/bin 不在 PATH 里，脚本会把一行 export PATH 写进你的 shell 配置（~/.zshrc、~/.bashrc 或 ~/.profile），并提示你新开终端或source 一次。Windows 上会把命令行目录加入当前用户的 PATH，并建立开始菜单快捷方式。

安装过程做了什么

安装脚本依次完成以下步骤：

读取 https://agentx.plus/ath/latest.json，得到当前版本与各平台清单的位置。
Windows 上先检查 WebView2 运行时：桌面应用依赖它，缺失时自动从微软官方地址安装，见下面的「Windows：WebView2 运行时」。
下载该平台的清单，取出安装包地址与 SHA-512 摘要。
下载安装包，逐字节校验摘要；不一致就报错停下，不会装入来源不明的文件。
先解压到临时目录并核对版本，全部通过后才替换原程序；失败时恢复旧文件。macOS 的包是 .7z，用系统自带的 tar 解开； Windows 的包是 .zip，用系统自带的 Expand-Archive（PowerShell 5.0 以上）解开，7-Zip 只是后备。
运行一次 ath --version / art --version 自检，确认装进去的程序能启动且版本与清单一致；桌面应用也核对内嵌版本号。

只下载所选应用。较大的安装包会分片下载，逐片校验后重组，再核对整包 SHA-512；脚本自动完成，无需额外安装下载工具。Windows 仍使用系统自带的 ZIP 解压能力。

Windows：WebView2 运行时

ATH 与 ART 的界面由 WebView2 渲染。Windows 10/11 通常已经带上它，但较老的系统、长期未更新的机器和 Windows Server 上可能没有，这时桌面应用打不开。

安装脚本会先查一遍（注册表里 WebView2 的安装记录与版本号），没有装就用微软官方的 Evergreen 引导程序自动安装：

检测到已安装时只打印一行版本号，不会重复安装。
自动安装会弹出管理员授权（UAC）；拒绝授权会停止安装，并给出官网手动安装的地址。
运行前会校验下载到的引导程序数字签名，确认来自微软；不是就直接停止，不会执行。
已经集中管理 WebView2 的环境可以跳过这一步：先执行 $env:ATH_INSTALL_SKIP_WEBVIEW2="1"，再运行安装命令。只有桌面应用依赖 WebView2，命令行程序不受影响。

确认装好了

ath --version
art --version
ath doctor --json

前两条应打印版本号。ath doctor 会给出更多信息：日志目录、最近的失败记录、设备与组件状态，细节见日志与诊断。

如果命令找不到

说明命令行目录不在 PATH 里。macOS 确认 ~/.local/bin 是否在 PATH；Windows 确认 %LOCALAPPDATA%\AgentX TestHub\bin，改完 PATH 后需要新开一个终端。

更新

保存工作并退出需要更新的应用和命令行，然后重新运行上面的安装命令即可，不需要先卸载。默认同时安装或更新 ATH、ART；只需要其中一个时指定应用。脚本每次读取最新发布清单，即使已经是最新版，也可以重复执行来修复程序文件。

项目、偏好设置、工位配置与测试结果保持不变。Windows 便携安装目录内自行放置的项目文件也会保留。下载、校验或解压失败时原程序不变；替换或版本自检失败时恢复本次更新前的程序。如果操作系统阻止恢复，提示会给出旧文件的备份位置，请保留备份并按提示处理。更新完成后重新打开应用，正在运行的旧进程不会被强制关闭。

安装失败时

安装失败时脚本会用中文说明原因，并把同样一段说明写进一个日志文件。按下面的顺序处理：先留下现场（提示 + 日志），再按症状自查，最后才是换目录或手动安装。

第一步：把提示和日志留下来

屏幕上的「详细记录」就是日志路径：Windows 是 %TEMP%\agentx-testhub-install.log， macOS 是 $TMPDIR 下的同名文件。日志会记录时间和失败原因；Windows 还记录 PowerShell 版本、系统与架构。

# Windows（PowerShell）
type "$env:TEMP\agentx-testhub-install.log"

# macOS
cat "$TMPDIR/agentx-testhub-install.log"

Windows 上也可以直接 notepad "$env:TEMP\agentx-testhub-install.log"，然后把内容复制出来。

Windows：让窗口不关，看清红字

如果窗口一闪就关了：早期版本的脚本在失败时调用了 exit，而 irm … | iex 是在当前 PowerShell 会话里执行 —— 会话一结束，窗口就关了。当前版本已经不再结束会话；如果你用的是旧版本，用下面任一方式运行。

保持窗口打开

powershell -NoExit -Command "irm https://agentx.plus/ath/install.ps1 | iex"

把整个过程录进文件

Start-Transcript -Path "$env:TEMP\ath-install.log"
irm https://agentx.plus/ath/install.ps1 | iex

macOS：保留完整输出

curl … | bash 里 bash 是子进程，失败不会关掉终端。想看到每一步执行到哪，先把脚本存下来再带追踪运行：

curl -fsSL https://agentx.plus/ath/install.sh -o install.sh
bash -x install.sh 2>&1 | tee install.log

第二步：按症状自查

症状 / 提示	先检查什么	怎么处理
无法下载安装清单或安装包	网络、代理与 DNS：浏览器或 curl 能否打开 https://agentx.plus/ath/latest.json	放行 agentx.plus；使用代理时确认代理允许该域名，必要时设置 HTTPS_PROXY 后重试。
HTTPS 连接失败（Windows PowerShell 5.1）	系统时间是否准确；系统是否为较老的 Windows	当前脚本已主动启用 TLS 1.2；仍失败时先校准系统时间，并确认没有安全软件拦截 HTTPS。
解压失败（Windows）	系统是否过旧：PowerShell 是否有 Expand-Archive；安装包是否为 .zip	Windows 10 1803 以上、PowerShell 5.0 以上可直接解压；仍失败时装 7-Zip 后重试：winget install --id 7zip.7zip。
WebView2 自动安装失败	是否拒绝了 UAC 授权；能否访问微软的下载地址	用管理员身份重跑，或按「Windows：WebView2 运行时」里的链接手动安装；已统一管理 WebView2 的机器可设 ATH_INSTALL_SKIP_WEBVIEW2=1 跳过。
安装包校验失败	下载是否被代理或安全软件改写	重新下载；反复失败时换网络，或用手动安装并核对清单里的 sha512。
ATH / ART 正在运行	任务管理器 / 程序坞里是否还开着	保存并退出应用后重试；脚本不会强杀正在运行的程序。
安装目录不可写	目标目录是否属于当前用户	用 --apps-dir / --cli-dir（Windows 用 -AppsDir / -CliDir）换到自己的目录。
命令找不到	PATH 里有没有命令行目录	macOS 检查 ~/.local/bin，Windows 检查 %LOCALAPPDATA%\AgentX TestHub\bin；改完新开终端。
macOS 提示应用「已损坏」或被系统拦下	应用是否带有隔离属性	执行 xattr -dr com.apple.quarantine ~/Applications/ATH.app，或在访达里右键选择「打开」。
Windows 提示「已保护你的电脑」	文件是否来自官方下载地址	确认来源后点「更多信息 → 仍要运行」；无法确认来源时不要继续。

第三步：换安装位置，或只装一个应用

把脚本先存下来再带参数运行，可以绕开权限问题，也能只装 ATH 或只装 ART：

macOS

curl -fsSL https://agentx.plus/ath/install.sh -o install.sh
bash install.sh --app ath --apps-dir "$HOME/Applications" --cli-dir "$HOME/bin"

Windows

irm https://agentx.plus/ath/install.ps1 -OutFile install.ps1
powershell -NoExit -ExecutionPolicy Bypass -File .\install.ps1 -App ath -CliDir "$env:USERPROFILE\bin"

也可以先用环境变量指定：macOS 用 ATH_INSTALL_APPS、ATH_INSTALL_APPS_DIR、ATH_INSTALL_CLI_DIR、ATH_INSTALL_BASE_URL；Windows 使用相同变量名，通过 $env:变量名 设置。

第四步：手动安装

脚本完全跑不起来时，可以按清单里的信息自己下载、校验、解压和复制。

01读清单打开 https://agentx.plus/ath/latest.json，记下 latestVersion 与 manifests 里对应平台的路径；再打开那份平台清单，取出 archives 中的下载地址、sha512 与 installs。
02下载并核对摘要下载 releases/<版本>/…（macOS 是 .7z，Windows 是 .zip），用清单里的 sha512 逐字对比。Windows 上应用与命令行各一个包，都要下载与校验；有 parts 时按清单顺序下载全部分片并用二进制方式拼接，再核对整包摘要。对不上就重新下载，不要继续安装。
03解压macOS 自带 tar 可以直接解 7z：tar -xf ath.7z； Windows 用 PowerShell 解 zip： Expand-Archive -Path ath.zip -DestinationPath .，也可以用 7-Zip 右键解压。
04放到安装位置macOS：把 ATH.app 放进 ~/Applications，把 bin/ath 放进 ~/.local/bin 并 chmod 755，再执行 xattr -dr com.apple.quarantine 去掉隔离属性。 Windows：把完整的 ATH 文件夹与 bin 内文件（包括相邻 DLL）复制到 %LOCALAPPDATA%\AgentX TestHub 下对应的子目录，并把 bin 加入 PATH。
05自检运行 ath --version 与 ath doctor --json 确认可用，见日志与诊断。

第五步：上报时带上这些

屏幕上的提示原文（红字那一段），以及日志文件的内容。
系统与版本：Windows 或 macOS 的版本、处理器架构（x64 / arm64）。
PowerShell 版本（$PSVersionTable.PSVersion）或 macOS 的 shell 类型。
是否使用代理、公司网络或安全软件；失败发生的大致时间。
脚本停在哪一步：下载、校验、解压、替换还是恢复；如有备份路径也请提供。

有了这几样，大多数安装问题不需要你反复复现就能定位。日志本身的结构见日志与诊断。

卸载

删除桌面应用：macOS 删除 ~/Applications/ATH.app 与 ~/Applications/ART.app；Windows 删除 %LOCALAPPDATA%\AgentX TestHub。
删除命令行：macOS 删除 ~/.local/bin/ath 与 ~/.local/bin/art。
清理安装位置记录：macOS 的 ~/Library/Application Support/AgentX TestHub/installer，Windows 的 %LOCALAPPDATA%\AgentX TestHub Installer。
清理 PATH：删掉安装脚本写进 shell 配置或用户 PATH 的那一行。

项目目录与日志目录不在卸载范围内，需要时自行删除；它们的默认位置见文件与格式与日志与诊断。

平台前置条件

平台	条件
macOS	Apple Silicon（arm64）。当前不提供 Intel 版本，脚本在 Intel 机器上会说明原因并退出。
Windows	64 位 Windows 与 PowerShell 5.0 以上即可解压安装包，不需要额外装 7-Zip；桌面应用还需要 WebView2 运行时，缺失时安装脚本会自动装好。
Linux	尚未提供发布产物。

设备连接还需要系统权限：macOS 与 Windows 都要求当前用户能访问 USB HID 接口。设备被虚拟机接管时会表现为「设备不在」，处理办法见设备与连接。