# 检查环境

`acdev doctor` 检查这台机器上 `acdev dev` 和 `acdev test` 需要的东西, 并说明有问题的该怎么修; `acdev doctor --fix` 把 acdev 自己能修的修掉. 装完之后、在要开始写的工程里, 以及 `acdev dev`、`acdev test` 或 MCP 的 `start` 起不来的时候, 都跑一下.

```sh
acdev doctor
```

```text
ok     acdev: X.Y.Z on Bun 1.4.4 (/Users/me/.acdev/versions/X.Y.Z)
ok     PATH: acdev on PATH is this one (/Users/me/.acdev/bin/acdev)
ok     Bun and Node.js: Bun 1.4+ at /Users/me/.bun/bin/bun; Node.js 22.3+ at /opt/homebrew/bin/node
ok     runtime: acdev X.Y.Z (contract level 1) at /Users/me/.acdev/versions/X.Y.Z/libexec/acdev (installed next to acdev)
ok     contract level: level 1 on both sides (acdev runtime X.Y.Z, SDK X.Y.Z)
ok     gpu: Apple M3 Pro (Metal, integrated GPU): drew a test frame in 38 ms
ok     acdev dev sessions: none running
ok     project: notes, app (acde.config.jsonc): acdev check finds nothing wrong
ok     platform: macos (desktop, standalone) has every required capability
ok     dependencies: installed with bun (runs on Bun 1.4+), @dopame/acde-api X.Y.Z
ok     git: .acde/ (the build output) is ignored
ok     agent skill: current in /Users/me/.agents/skills/acdev, /Users/me/.claude/skills/acdev
acdev doctor: everything acdev needs is here
```

每行是 `<状态> <检查>: <看到了什么>`:

| 状态 | 意思 |
| --- | --- |
| `ok` | 没问题 |
| `warn` | 能用, 但有东西会碍事; 下面跟一行 `fix:` |
| `error` | `acdev dev` 或 `acdev test` 跑不了; 有修法时下面跟一行 `fix:` |
| `skip` | 没检查: 这里没有工程, 或者它依赖的检查失败了 |

最后一行数错误和警告. 有一项是错误时退出码是 1, 否则是 0. `acdev doctor <dir>` 检查 `<dir>` 里的工程而不是当前目录 (这时目录里没有 acde 工程算错误), `--online` 再查一下有没有更新的 acdev.

## 检查哪些

| 检查 | 看什么 |
| --- | --- |
| `acdev` | acdev 的版本和它跑在哪个 JavaScript 运行时上 |
| `PATH` | PATH 上的 `acdev` 是不是这一个, 而不是别的安装或检出 |
| `Bun and Node.js` | PATH 上有没有 Bun 1.4+ 和 Node.js 22.3+; `acdev test` 和用 bun 的工程要 Bun |
| `runtime` | `acdev dev` 会跑的运行时二进制 (`ACDEV_RUNTIME`, 否则安装目录的 `libexec/acdev`), 以及它能不能跑 |
| `contract level` | 运行时跑的契约级别是不是这一版 acdev 构建的级别, 以及它是不是和这一版 acdev 配对的版本 |
| `gpu`、`display` | 运行时二进制自己的检查 (`libexec/acdev doctor`): GPU (画一小帧再读回来), Linux 上还有能不能开宿主窗口 |
| `acdev dev sessions`、`approval` | 正在跑的 `acdev dev`, 以及每个在等回答的摄像头或麦克风提示 |
| `project` | 工程的 `acdev check` |
| `platform` | 这个平台有没有工程里的应用要求的全部能力 |
| `dependencies` | 工程的依赖装了没有 (workspace 把它们放在上层目录里也算), 它的运行时在不在 PATH 上, 它的 `@dopame/acde-api` (`package.json` 里写的和装了的) 是不是这一版 acdev 构建时用的版本; 较旧的 SDK 在这里报一次, 用 `acdev sdk update` 修好 (`acdev doctor` 带了目录时, 后面跟上那个目录) |
| `git` | git 是否忽略了 `.acde/` |
| `agent skill` | acdev skill 有没有装给编码 agent、是不是最新的 |
| `latest release` | 带 `--online` 时: 有没有更新的 acdev |

## 常见的结果

没有运行时:

```text
error  runtime: acdev dev needs the Dopame runtime (libexec/acdev of an install) and found none: no /Users/me/.acdev/versions/X.Y.Z/libexec/acdev, which the acdev installer puts there: run the installer again, or set ACDEV_RUNTIME to the runtime binary (target/release/acdev of an acdev checkout)
       fix: run the installer again: curl -fsSL https://pkgs.dopame.ai/acdev/install.sh | sh (it puts the acdev runtime that pairs with acdev next to it)
```

起不来的运行时会说明原因: 缺系统库 (`it exited with code 127: … error while loading shared libraries: …`)、文件没有执行权限 (`EACCES`), 或者在 macOS 上下载时被留在隔离区里的二进制, 修法是 `xattr -d com.apple.quarantine <path>`.

画不出来的运行时是 `gpu` 那项的错误, 原因和 `acdev dev` 启动时在 `web layer unavailable:` 后面记的一样. Linux 上没有 GPU 的 Vulkan 驱动时:

```text
error  gpu: the system has a GPU (card0, kernel driver xe) but no usable Vulkan driver was found: install the GPU's Vulkan driver (for example vulkan-intel, vulkan-radeon, nvidia-utils) or point VK_DRIVER_FILES at its ICD (wgpu: No suitable graphics adapter found; …)
```

装上驱动 (见 [运行时](https://docs.dopame.ai/zh/start/install.md#运行时)). 只有软件驱动 (lavapipe) 时, `gpu` 是一个警告: 页面在 CPU 上渲染, 整屏都在动的页面 (动态壁纸) 每秒只能出几帧. 能用时这一行写出 GPU、图形接口和驱动, 比如 `ok     gpu: Intel(R) Graphics (PTL) (Vulkan, integrated GPU, driver Intel open-source Mesa driver Mesa 26.2.5-arch3.1): drew a test frame in 41 ms`.

Linux 上在没有图形会话的 shell 里 (比如经 SSH):

```text
warn   display: neither WAYLAND_DISPLAY nor DISPLAY is set, so acdev app and acdev desktop cannot open a host window here: they would try to start a session on the screen (DRM) instead
       fix: run acdev dev --headless, or run it inside a graphical session
```

在等回答的摄像头或麦克风提示:

```text
warn   approval: recorder waits for approval of microphone in acdev dev 4242, so its getUserMedia waits until the prompt is answered
       fix: acdev allow (or acdev deny): approving is the user's decision
```

## 能修的就修

`acdev doctor --fix` 跑完检查、打出结果, 然后修它能修的, 再检查一遍:

| 修法 | 什么时候 | 先问吗 |
| --- | --- | --- |
| `acdev skills install` | acdev skill 没装给任何编码 agent, 或装过的已过期、链接断了 | 不问 |
| 往工程的 `.gitignore` 里加 `.acde/` | git 没有忽略构建产物 | 不问 |
| 删掉会话目录再建 | 它是链接或文件, 不是目录 | 不问 |
| 再跑一次这一版 acdev 的安装脚本 (`install.sh --version <这一版> --no-modify-path`, Windows 上是 `install.ps1 -Version … -NoModifyPath`) | acdev 旁边的运行时缺了、跑不了、契约级别或版本不对; 只对装好的 acdev, 并且 `ACDEV_RUNTIME` 没有指定运行时 | 问: 它要下载运行时并替换安装, 和安装脚本平时一样, 要么全成要么不动 |
| 工程的安装 (`bun install`、`npm install`…) | 工程的依赖没装 | 问: 它要下载包并跑它们的安装脚本 |
| `acdev stop --session <pid>` | 一个正在跑的 `acdev dev` 不响应 | 问: 它要结束你起的进程 |

在终端里, 最后一列写着「问」的每一项它都会问. 不在终端里 (脚本、编码 agent) 时, 除非给了 `--yes`, 它跳过这些并说明: `skipped: … (it asks first: pass --yes to allow it)`. 编码 agent 只在用户同意后才传 `--yes`.

该由用户决定的它一概不碰: 摄像头或麦克风的提示、GPU 驱动或系统库、macOS 隔离区里的二进制、PATH 上别的 acdev、工程的代码和配置. 这些只留下 `fix:` 那一行.

```text
fixing: install the acdev skill for the coding agents found here (acdev skills install)
acdev: skill linked to /Users/me/.agents/skills/acdev (Cline, Codex, …)
fixed: install the acdev skill for the coding agents found here (acdev skills install)
skipped: install the project's dependencies (bun install in /Users/me/notes) (it asks first: pass --yes to allow it)
acdev doctor: after fixing:
ok     acdev: X.Y.Z on Bun 1.4.4 (/Users/me/.acdev/versions/X.Y.Z)
…
```

## acdev dev 会指向这里

`acdev dev` 找不到运行时时, 报错末尾是 `(acdev doctor checks the whole setup)`. 运行时在会话就绪之前退出时, `acdev dev` 先打出运行时的那行日志, 然后是:

```text
acdev: acdev runtime exited (1) before it was ready; acdev doctor checks the runtime, the GPU and this setup
```

## 在脚本和 agent 里

`acdev doctor --json` 打出一个对象:

```json
{
  "ok": false,
  "checks": [
    { "id": "runtime.binary", "title": "runtime", "status": "error", "summary": "…", "fix": "…" }
  ]
}
```

有一项是错误时 `ok` 为 false. `--fix` 能修的检查带 `"repair": {"action", "target", "ask", "does"}` (先问的那几种 `ask` 为 true); 带 `--fix` 时对象里还有 `"fixed": [{"repair", "result", "said"}]`, `result` 是 `fixed`、`failed` 或 `skipped`, 过程中的那些行改打到 stderr. id 有 `acdev`、`path`、`runtimes`、`runtime.binary` (运行时二进制; 它的 title 是 `runtime`)、`contract`、`runtime` (运行时自己的检查跑不了时)、`runtime.host`、`runtime.gpu`、`runtime.display`、`sessions`、`approval`、`project`、`platform`、`dependencies`、`gitignore`、`skill` 和 `latest`; 没有修法时不带 `fix`. MCP 服务器的 `doctor` 工具做同样的检查, 不用问的修复是 `doctor_fix` (其余的它点名, 留给用户); 见 [MCP](https://docs.dopame.ai/zh/guide/mcp.md).

运行时那部分也可以单独跑: 运行时二进制的 `doctor` (安装目录里的 `libexec/acdev doctor`, 或 `libexec/acdev doctor --json`), 退出码一样.
