跳转到内容
选择主题
选择语言简体中文

检查环境

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

终端窗口
acdev doctor
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

没有运行时:

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 驱动时:

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; …)

装上驱动 (见 运行时). 只有软件驱动 (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):

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

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

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: 那一行.

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 doctor checks the whole setup). 运行时在会话就绪之前退出时, acdev dev 先打出运行时的那行日志, 然后是:

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

acdev doctor --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.

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