# 命令行

```text
acdev <command> [参数]
```

出错时打一行 `acdev: <原因>`, 退出码 1. 参数错了 (`act` 不认识的动作、`console` 不认识的级别……) 会打一行, 指出哪里不对、该看哪个 `acdev <command> --help`, 比如 `acdev: console: --level loud: one of log, info, warn, error, debug, errors (acdev console --help)`; 选项的值不对时总是 `acdev: <command>: --<option> <value>: <what it takes> (acdev <command> --help)`. 完整的用法只有 `acdev --help` 才打.

每个命令的退出码都一样:

| 退出码 | 意思 |
| --- | --- |
| 0 | 做完了 (空的列表也是, 比如没有记录的 `acdev console`) |
| 1 | 出错: 参数错了、某件事失败了, 或有东西挡着它 (包正在用) |
| 2 | 什么都没做, 但不是错误: 什么都没匹配到 (`acdev query`、`acdev inspect --find`), 或没有可删的 (`acdev uninstall`) |
| 3 | 取消了或没确认: 在 `acdev new` 的提问里或 `acdev sdk update` 期间按了 Ctrl+C、`acdev uninstall` 被拒绝, 或者没有能提问的终端又没有 `--yes` |

命令找到的东西打到 stdout; 什么都没找到的说明、错误和提示打到 stderr, 带 `acdev:` 前缀.

`acdev --version` (或 `-v`, 或 `acdev version`) 第一行打出 acdev 的版本, 然后是构建它时用的 SDK 版本和契约级别, 以及它找到的运行时二进制 (先 `ACDEV_RUNTIME`, 否则安装目录的 `libexec/acdev`) 和这个运行时的版本、契约级别. `acdev --help` (或 `-h`, 或 `acdev help`) 打出每个命令的用法; `acdev <command> --help` 和 `acdev help <command>` 只打出那个命令的. 不带参数的 `acdev` 只打出它的版本、开始一个工程的三条命令, 以及让你去看 `acdev --help` 的一句. 不认识的命令或参数会打出一行, 说明哪里不对、该看哪个 `--help`, 退出码 1. 输出到终端时带颜色; `NO_COLOR` (设了且不为空) 关掉颜色, `FORCE_COLOR` (设了且不是 `0` 或 `false`) 打开颜色. 只有标签带颜色: `acdev:`、`error:`、`warning:`、`acdev doctor` 的状态词和帮助里的标题. 错误是一行 `acdev: <出了什么错>`; 有 `ACDEV_DEBUG=1` 时后面跟着它的调用栈.

## 环境

### acdev doctor

```text
acdev doctor [dir] [--json] [--online] [--fix [--yes]]
```

检查这台机器上 `acdev dev` 和 `acdev test` 需要的东西: PATH 上的 acdev、Bun 和 Node.js、运行时二进制 (找到没有、能不能跑、跑的是不是这一版 acdev 构建的契约级别、是不是和这一版 acdev 配对的版本)、运行时二进制自己的检查 (它的 `doctor`: GPU, Linux 上还有显示环境)、正在跑的 `acdev dev` 和它们在等的批准、`dir` 里的工程 (默认是当前目录; `acdev check`、这个平台、依赖、`.gitignore` 里有没有 `.acde/`), 以及给编码 agent 的 acdev skill. 见 [检查环境](https://docs.dopame.ai/zh/guide/doctor.md).

| 选项 | 说明 |
| --- | --- |
| `--json` | 打一个 JSON 对象而不是一行行文字: `{"ok": …, "checks": [{"id", "title", "status", "summary", "fix", "repair"}]}`; 带 `--fix` 时还有 `"fixed"` |
| `--online` | 再问 acdev 的下载站 (`ACDEV_DIST`) 有没有更新的 acdev |
| `--fix` | 检查完修 acdev 能修的: 有的直接修, 其余的问过再修; 修完再检查一遍. 见 [能修的就修](https://docs.dopame.ai/zh/guide/doctor.md#能修的就修) |
| `--yes` | 和 `--fix` 一起用: 本该先问的修复不问就做 |

每项检查打一行 `<状态> <检查>: <看到了什么>`, 有问题的下一行是 `fix: …`, 最后一行数错误和警告. 状态是 `ok`、`warn`、`error` 或 `skip` (没检查: 这里没有工程, 或者它依赖的检查失败了). 有一项是错误时退出码是 1, 否则是 0. 给的 `dir` 里没有 acde 工程算错误.

带 `--fix` 时, 报告之后对每个修复打 `fixing: <做什么>`、它跑的东西的输出, 然后是 `fixed: <做什么>` 或 `failed: <做什么>: <原因>`; 没被允许的打 `skipped: <做什么>`; 最后打 `acdev doctor: after fixing:` 并再检查一遍, 退出码看第二遍. 没有能修的时说 `acdev doctor: nothing here it can fix; the fix lines say what to do`. 只给 `--yes` 不给 `--fix` 是错误.

## 工程

### acdev new

```text
acdev new [dir] [--template T] [--id ID] [--label NAME] [--backend] [--install|--no-install] [--git] [--pm PM] [--yes]
```

新建工程. 在终端里会问缺的信息; `--yes` 或不在终端里时什么都不问 (这时 `dir` 必填, 模板默认 `html`, 除非给了 `--no-install` 否则装依赖, 除非给了 `--git` 否则不建仓库).

| 参数 | 说明 |
| --- | --- |
| `--template` | `html` `desktop` `react` `vue` `svelte` `solid` `preact` `vanilla` `next` `nuxt` `sveltekit` `astro` |
| `--id` / `--label` | 应用 id 和显示名 |
| `--backend` | 加上 `server.ts`, 一个后端. 对 `html` 和 Vite 模板有效; `next`、`nuxt`、`sveltekit`、`astro` (它们有自己的服务端) 和 `desktop` (它没有服务端) 拒绝它 |
| `--install` / `--no-install` | 用包管理器装依赖 (包括 SDK), 或者不装; 两个都不给时, `acdev new` 在终端里会问, 否则就装 |
| `--git` | `git init` 并做首次提交 (配了 git 用户名和邮箱时) |
| `--pm` | `bun` `npm` `pnpm` `yarn`, 决定工程跑在 Bun 还是 Node.js 上 (默认: acdev 跑在 Bun 上时是 `bun`, 否则是 `npm`; 在终端里且两个都装了时会问) |

### acdev check

```text
acdev check [dir] [--platform windows|macos|linux]
```

检查配置 (id、入口、图标、服务模块、框架) 和 SDK 的清单规则, 或手写包的清单和入口文件, 并对照清单检查 `acde:` 导入. 它在 stderr 上打出 `error:`、`warning:` 和 `note:` 行, 只有存在错误时退出码才是 1. `note:` 标出检查放行但核实不了的导入, 即[桌面服务](https://docs.dopame.ai/zh/guide/services.md#调用)的一个不是服务自己名字的命名空间: `note: src/main.js:1: app "notes": acde:timer resolves only if the service Notes lists ("clock") provides the "timer" namespace`.

它还拿应用声明的能力和一个平台有的对照检查, 在那里跑应用的每种方式各查一次 (`desktop` 和 `standalone`, Linux 上还有 `session`). 这个平台是 `acdev check` 正在跑的平台, 或 `--platform` 指定的那个:

- 平台没有的必需能力是错误: `error: windows (desktop): app "notes" requires network, which this mode lacks`, 后面跟一句怎么把它改成可选的提示.
- 平台没有的可选能力只是一条提示, 不算错误: `note: windows (desktop): app "notes" runs without optional camera, which this mode lacks`.
- 必需的能力一个都不缺时, 最后一行是 `ok: linux (session, desktop, standalone): every required capability is there`.

### acdev build

```text
acdev build [dir] [--out DIR]
```

构建到 `DIR` (默认 `.acde`). 相对的 `--out` 相对被构建的工程. 先检查 `acde:` 导入, 和 `acdev check` 里一样 (有错误就停止构建, `note:` 只打出来), 产物的清单会再检查一遍.

### acdev install

```text
acdev install [dir] [--out DIR]
```

构建后装进 `$XDG_DATA_HOME/acde/packages/<id>`; 没设 `XDG_DATA_HOME` 时是 `~/.local/share/acde/packages/<id>` (Windows 上是 `%USERPROFILE%\.local\share\acdev\packages\<id>`). 见 [本机安装](https://docs.dopame.ai/zh/guide/install.md).

### acdev uninstall

```text
acdev uninstall [id|dir] [--yes] [--data | --keep-data]
```

删掉 `acdev install` 装进包目录的一个包, 按它的 id (它在那里的目录名) 或装它时的工程目录找. 手写的包装的是链接, 只删链接; 它指向的工程留着. 删之前打出要删什么 (`acdev: removes <id>: <path> ...`), 在终端里会问; `--yes` 不问就删, 不在终端里时没有 `--yes` 什么都不删. 有 `acdev dev` 开发会话在跑这个包的桌面或它的某个应用, 或者在跑一个桌面而这个包里有应用时, 它什么都不删, 并说出要先结束的会话 (`acdev stop --session <pid>`). 不带参数时列出装了的包, 每个一行: id 和路径 (链接的话是 `-> <project>`).

这个包里应用和桌面的数据 (`$XDG_DATA_HOME/acde` 下的 `storage/app-<id>/`、`storage/desktop-<id>/` 和 `apps/<id>/`; 存储设了 `ACDE_STORAGE` 时在它下面) 带 `--data` 时删掉, 带 `--keep-data` 时留下; 两个都不带时, 在终端里会问, `--yes` 留下它, 并打出 `acdev: kept its data (…): <paths>`. 两个一起给是参数错误 (退出码 1).

| 退出码 | 意思 |
| --- | --- |
| 0 | 删掉了, 或列出了 |
| 1 | 正被一个 `acdev dev` 开发会话使用, 或参数错了 |
| 2 | 没装 |
| 3 | 没确认 (问了被拒绝, 或者不在终端里又没有 `--yes`) |

### acdev sdk

```text
acdev sdk [update] [dir]
```

显示工程的 `@dopame/acde-api` 和这一版 acdev 配对的 SDK 版本. `acdev sdk update` 把依赖按路径指向这一版 acdev 自带的、在这台机器上的 SDK (`file:...`), 再用工程的包管理器 (按它的 lockfile 或 `packageManager`) 重新安装. 包管理器不在 PATH 上时它什么都不改. 安装失败或被中断 (Ctrl+C) 时, 它把 `package.json`、lockfile 和 `.npmrc` 放回原样并说明这一点, 放不回去的文件会点出名字; 再跑一次安装, 让 `node_modules` 重新跟上. `node_modules` 里的 SDK 版本和 `package.json` 写的不一样时, `acdev check` 也会给出警告. 两个版本不一样时 (比如升级了 acde 之后), `acdev check` 和 `acdev dev` 会给出警告.

### acdev dev

```text
acdev dev [dir...] [--out DIR] [--app ID] [--desktop ID|DIR] [--headless] [--verbose] [--force] [--keep] [--lock]
```

构建、启动 acdev runtime、改了就重建并重载. `--headless` 不开窗口; 在没有显示器的机器上用它. `--verbose` 还打出运行时自己的 info 日志; 默认终端里显示页面和后端打出的东西、每个应用发生了什么, 以及运行时的警告和错误. 在 Linux 上, 没有 `WAYLAND_DISPLAY` 也没有 `DISPLAY` 时, 不带 `--headless` 的 `acdev dev` 会停下, 打出 `acdev: no display here (no WAYLAND_DISPLAY or DISPLAY): run acdev dev --headless`, 退出码 1. 一个工程同一时间只有一个 `acdev dev` 在跑, 两个同时启动时也是这样: 第二个在构建之前以退出码 1 退出, 并点出正在跑的那个 (`acdev: acdev dev <pid> already runs <dir>; stop it first (acdev stop --session <pid>), or pass --force to start another`); `--force` 照样启动它. 应用在 `fs.roots` 里声明的共享位置 (Documents、Downloads 等) 是为这个会话建的文件夹 (在系统临时文件夹下), 不是你自己的; `--keep` 在会话结束后保留它们, 并打出位置. `--lock` 单独打开一个桌面工程的锁屏页 (清单里的 `lock`), 配一个替身 `acde:lock`: `user()` 是一个固定的、没有头像的用户, `unlock('right-password')` 解锁, `wrong-password` 以代码 `auth` 失败, `busy-password` 以 `busy` 失败, `throttled-password` 以 `throttled` 失败且 `retryAfter` 为 3, 其他密码以 `auth` 失败. Ctrl+C、SIGINT 和 SIGTERM 结束会话和它的运行时, 并删掉它的文件; 被杀掉的会话留下的文件由下一个 `acdev dev` 或会话命令删掉. 见 [acdev dev](https://docs.dopame.ai/zh/guide/dev.md) 和 [没有显示器](https://docs.dopame.ai/zh/guide/tools.md#没有显示器).

## 运行中的会话

这些命令要连上一个跑着的 `acdev dev` 开发会话, 都接受 `--session <pid>`, 或者 `--session vm`, 表示 [`acdev vm`](#acdev-vm) 客户机里已登录的会话. `<web>` 是一张页面: `acdev webs` 列出的 web 名、应用 id 或 `desktop`; `<ref>` 是 `acdev inspect` 或 `acdev query` 给元素的编号, 比如 `w1.12`, 一个窗口, 比如 `w1`, 或者窗口标题栏上的一个菜单, 比如 `w1.m1`, 或它的一项, `w1.m1.2`. 见 [调试工具](https://docs.dopame.ai/zh/guide/tools.md).

| 命令 | 说明 |
| --- | --- |
| `acdev webs` | 页面列表 |
| `acdev eval <web> <code\|->` | 在页面里执行, 打印 JSON |
| `acdev shot <web> [-o, --output FILE]` | 窗口截图, 默认 `./<web>.png` |
| `acdev screen [-o, --output FILE]` | 整屏截图, 默认 `./screen.png` |
| `acdev pointer <x> <y>` | 把指针移到屏幕坐标, 和真的移动一样 |
| `acdev inspect [--window W] [--find TEXT] [--all] [--offscreen]` | 屏幕的文字形式 |
| `acdev query <selector> [--window W] [--ref REF] [--limit N]` | CSS 选择器匹配的元素, 每个带 ref |
| `acdev act <ref> <action> [arg]` | 对一个 ref 做动作 |
| `acdev input <web> <events\|->` | 给页面发一个 JSON 数组的原始鼠标和键盘事件, 用页面的 CSS 像素: `move` / `down` / `up` (`x`, `y`, `button`)、`wheel` (`x`, `y`, `dx`, `dy`)、`keydown` / `keyup` (`key`)、`text` (`text`)、`wait` (`ms`, 最多 10000). 相邻的 move 隔一帧, 所以按着按钮的一串 move 画出一条路径; `keydown`、`wait`、`keyup` 按住一个键. `down`、`up` 和 `wheel` 会把指针移到自己的 `x` 和 `y` |
| `acdev console [--web W] [--level L] [--since S] [--follow]` | 页面日志和错误; `--since reload` 或 `--since N` |
| `acdev network [--web W] [--failed] [--since S] [--follow]` | 页面请求; `--since reload` 或 `--since N`. 没有可显示的东西时, `console` 和 `network` 在 stderr 上打出 `acdev: no console entries` / `acdev: no requests`, 退出码 0 |
| `acdev choose <folder\|open\|save> [path...] [--cancel]` | 回答页面打开的下一个文件夹、文件或保存选择器: 一个文件夹、一个或多个文件, 或要写的文件; `--cancel` 回答为取消. 打印 `the next folder picker answers <path>`. headless 会话不显示选择器, 所以要在打开它的动作之前回答 |
| `acdev drop <web> <file...> [--at X,Y]` | 像从系统拖进来一样把文件放到页面上 (带着文件的 `dragenter`、`dragover`、`drop`), 放在页面 CSS 像素的 `X,Y` 处或正中. 打印 `dropped N files onto <web>` |
| `acdev permissions` | 等待回答的摄像头和麦克风提示, 以及已做的决定 |
| `acdev allow [<prompt id> \| <app> <capability>] [--all]` | 允许一个等待中的摄像头或麦克风提示 |
| `acdev deny [<prompt id> \| <app> <capability>] [--all]` | 拒绝一个等待中的摄像头或麦克风提示 |
| `acdev revoke <app> <capability>` | 收回一个决定 |
| `acdev stop` | 结束开发会话和它的 acdev runtime, 见 [结束](https://docs.dopame.ai/zh/guide/dev.md#结束) |
| `acdev devtools [web]` | 在会话的一张页面上打开 Chrome 或 Edge 的 DevTools (web 名、应用 id、`desktop`、窗口标题, 或者 `services` 或某个服务名表示服务; 默认: 焦点所在的页面), 并打出 DevTools 的地址. Windows 上先找 Edge, 再找 Chrome; macOS 上先找 Chrome 应用, 再找 Edge 应用; Linux 上找 `PATH` 上的 `google-chrome`、`chrome`、`chromium`、`microsoft-edge`. 浏览器用 acdev 缓存目录里它自己的一份配置 (`%LOCALAPPDATA%`、`~/Library/Caches` 或 `~/.cache` 下的 `acde/devtools/`), 绝不用你平时用的那份; 它不开自己的窗口, 也不弹同步提示, 只开 DevTools 窗口, 并一直开着留给下一次 `acdev devtools`. `ACDEV_BROWSER` 指定别的浏览器; `ACDEV_BROWSER=none` 什么都不开. 没有浏览器, 或者它启动不了、连不上时, 打出地址和原因, 你把地址粘进 Chrome 或 Edge 的地址栏, 退出码 0. 对一张 DevTools 已经开着的页面再要一次, 会把它们提到最前面. 在 `acdev dev` 的窗口里按 F12 (Mac 键盘上是 fn+F12) 对那个窗口里的页面做同样的事, 页面收不到这个 F12; 带修饰键的 F12 仍然送到页面 |
| `acdev mcp [--session PID\|vm]` | stdio 上的 MCP 服务器, 见 [MCP](https://docs.dopame.ai/zh/guide/mcp.md) |

| 选项 | 说明 |
| --- | --- |
| `--window` | `inspect`、`query`: 用这个窗口 (`w1`), 而不是焦点窗口 |
| `--ref` | `query`: 只在这个元素 (`w1.12`) 下面找 |
| `--limit` | `query`: 最多列出这么多个元素 (1 到 3000, 默认 600) |
| `--all` | `inspect`: 每个没有标 `[minimized]` 的窗口, 以及被 `opacity: 0` 或 `visibility` 隐藏的元素. `allow`、`deny`: 每个等待中的提示 |
| `--cancel` | `choose`: 把选择器回答为取消 |
| `--at` | `drop`: 放在哪里, 页面 CSS 像素的 `X,Y` |

`acdev query` 打出 `N in <window>:` 和每个元素一行 (退出码 0), 或者在 stderr 上打出 `acdev: nothing in <window> matches "<selector>"` (退出码 2). `acdev inspect --find TEXT` 在没有哪个元素的名字或值包含 TEXT 时退出码是 2. 退出码 2 总是表示命令正常执行了, 但什么都没找到; 1 表示出错, 比如窗口或元素不存在. `acdev act` 打出它做了什么、变了什么; 动作没做成时它在 stderr 上打出原因 (`acdev: act <ref>: <reason>`), 退出码 1. ref 已经不存在时说的是 `there is no such element (any more); acdev inspect --find TEXT gives the current refs`.

`acdev permissions` 打出两块, 退出码 0:

```text
pending:
  2  recorder  microphone  (request)
decisions:
  recorder  camera  granted
```

pending 的一行是 `<prompt id>  <app>  <capability>  (<reason>)`; reason 总是 `request` (运行中的应用问的: 它的 `getUserMedia()` 或 `request()` 在等回答); decisions 的一行是 `<app>  <capability>  <granted|denied>`. 空的块是 `pending: none` 或 `decisions: none`.

`acdev allow` 和 `acdev deny` 回答此刻在等的提示. 不带参数时回答唯一在等的那个提示; 有几个在等时一个都不回答, 把它们列出来, 退出码 1. `<prompt id>` 指一个提示, `<app> <capability>` 指那个应用关于那个能力的提示, `--all` 指每个在等的提示. 每回答一个提示, 打出 `allowed <app> <capability> (prompt <id>)` 或 `denied <app> <capability> (prompt <id>)`. 没有提示在等, 或没有匹配的, 就打出一行说明 (`acdev: no approval prompt is waiting`、`acdev: no approval prompt 5 is waiting (waiting: 2)`), 退出码 1.

`acdev revoke <app> <capability>` 打出 `revoked <app> <capability>`; 没有这个决定时它会说明, 退出码 1.

有摄像头或麦克风提示在等时, `acdev webs` 在表后面给每个提示打一行 (应用的窗口是开着的; 它的 `getUserMedia()` 在等): `<app> waits for approval of <capability>: acdev allow (or acdev deny)`. 见 [摄像头和麦克风](https://docs.dopame.ai/zh/guide/tools.md#摄像头和麦克风).

## 编码 agent

```text
acdev skills [install|remove|path] [--agent ID,...] [--dir DIR] [--copy]
```

| 命令 | 说明 |
| --- | --- |
| `acdev skills` | acdev skill 装在哪些地方, 每一处是不是最新的 |
| `acdev skills install` | 把 skill 链接进 `~/.agents/skills` 和找到的每个 agent 的 skills 目录 |
| `acdev skills remove` | 从这些地方删掉, `install` 建的、现在空了的目录也删掉 |
| `acdev skills path` | 打印 acdev 安装目录里 skill 的目录 |

| 选项 | 说明 |
| --- | --- |
| `--agent` | 只给这些 agent (逗号分隔的 id, 如 `claude-code`、`codex`、`cursor`), 而不是找到的那些 |
| `--dir` | 改用这个 skills 目录; skill 装进 `DIR/acde` |
| `--copy` | 拷贝而不是链接 (只用于 `install`) |

见 [编码 agent](https://docs.dopame.ai/zh/guide/agents.md).

## 模拟器

### acdev vm

用 QEMU 跑的一台 Dopame OS 客户机: Linux 上用 KVM, Windows 上用 WHPX (先打开 Windows 虚拟机监控程序平台这项功能), macOS 上用 HVF; 都没有时用模拟 (TCG) 来跑. Windows 上没有 `--share` 和 `--viewer`; macOS 上 QEMU 自己的窗口是 Cocoa, `--gl` 只在 Linux 上有, 在 Apple 芯片 (任何 arm64 主机) 上客户机是 aarch64 (`ACDEV_VM_ARCH` 选 x86_64 或 aarch64; 这时 `fetch` 取 aarch64 镜像). `acdev vm fetch` 下载最新的 x86_64 磁盘镜像; `acdev vm start [--headless | --vnc | --viewer | --sdl | --gtk] [--outputs N] [--vga virtio|std] [--resolution WxH] [--audio none|wav] [--share DIR] [--image FILE] [--fresh] [--wait SECONDS] [--gl]` 在后台、在一块 overlay 磁盘上启动它 (镜像本身不变), 并等到客户机就绪 (`--gl`: virgl, 留作一个选项, 不在路线图上); `acdev vm stop` 关掉它; 还有 `acdev vm status`、`acdev vm wait [SECONDS]`. `acdev vm screenshot FILE.png [--output K]` 截下客户机的屏幕, 没有窗口时也行. `--outputs N` (1 到 16) 给客户机 N 个显示器: QEMU 的窗口每个显示器一个标签页; 带 `--headless` 时 QEMU 拿到它的 D-Bus 显示而不是没有显示, 由 `acdevtool view` 把其余显示器打开 (不然它们一直断开); `screenshot --output K` 截第 K 个显示器 (从 0 起); `--vnc` 和 `--viewer` 只显示第一个, 所以它们拒绝大于 1 的 `--outputs`. `acdev vm start` 还会在客户机里装上设备守护进程 acdevd, Linux 上经 vsock 连它, 别处经 127.0.0.1 上的 QEMU 端口转发连它 (`ACDEV_VM_TRANSPORT=vsock|unix|tcp` 强制用其中一种; `unix` 需要较新的 QEMU, 见 env.md 里的 `ACDEV_VM_TRANSPORT`), 每次启动用一把新的密钥: `acdev vm run -- COMMAND` 在客户机里以 root 跑一条命令, 实时转出它的输出, 并以它的退出码退出 (`--detach`: 在后台跑, 输出在 `/var/log/acdevd/<pid>.log`; `acdev vm kill PID [--force]` 停掉它); `acdev vm shell [-- COMMAND]` 在一个跟着窗口大小变化的 pty 上打开交互终端, 以 shell 的退出码退出 (不给命令: root 的登录 shell); `acdev vm logs [SOURCE] [--follow] [--grep REGEX] [--lines N]` 显示客户机的 journal, 或一个 systemd 单元的、一个客户机文件, 或按进程组 id 显示一个 `--detach` 程序的日志, 先给最后 50 行, `--follow` 时继续跟着, 只留匹配 `--grep` 的行 (不分大小写); `acdev vm dev [DIR] [--bin A,B] [--run COMMAND] [--profile NAME]` 用 `cargo build --profile NAME` 构建 DIR (默认 `.`) 里的 Cargo 工程 (默认: 工程定义了 `guest` 这个 profile 时用它, 否则 `release`), 把它的二进制推到 `/opt/acdev/bin`, 在后台跑 `--run` (默认: 第一个二进制), 那个目录在 `PATH` 上, 并显示它的输出; 之后每次源码变化都重新构建, 构建成功就停掉程序、推上去、再启动; Ctrl+C 停止; `acdev vm push LOCAL [REMOTE]` 把一个文件或目录拷进去 (默认 `/opt/acdev/<name>`); `acdev vm pull REMOTE [LOCAL]` 把客户机里的一个文件或目录连同 rwx 权限位 (不含 setuid、setgid 和 sticky 位) 拷出来 (默认 `./<name>`; LOCAL 是目录时拷到 `LOCAL/<name>`); `acdev vm start --viewer` 在 acdev 自己的窗口 (QEMU 的 D-Bus 显示, 目前只在 Linux 上) 而不是 QEMU 的窗口里显示客户机, `acdev vm view` 在这个窗口关掉后再打开它; `acdev vm mount` 把 `--share` 的目录挂到 `/mnt/acdev`; `acdev vm console` 让客户机的内核从下次启动起把日志打到串口. Linux 上 `start` 的窗口默认是 QEMU 的 SDL 窗口 (`--sdl`): 客户机以 1280x800 启动, 窗口改大小时跟着变; 没有带 SDL 构建的 QEMU 退回 GTK. `--gtk` 选 QEMU 的 GTK 窗口, 它把自己一开始的小尺寸交给客户机, 所以客户机一开始很小, 直到你把窗口拉大; `--outputs` 大于 1 时窗口是 GTK, 每个显示器一个标签页. `--vga virtio` (默认) 是 virtio GPU: 跟着窗口改大小, 支持多显示器和 3D; `--vga std` 是标准 VGA (客户机里是 bochs-drm; 一个固定大小的显示器), 用于睡眠和唤醒, virtio GPU 撑不过这一步. `--resolution WxH` 是客户机启动时的显示大小 (默认 1280x800). `--audio none` (默认) 让客户机声卡不往任何地方放声音, `--audio wav` 放进日志目录里的 `audio.wav`. `--fresh` 也会丢掉 UEFI 变量; 之后要再跑一次 `provision`. `acdev vm usb add IMAGE [--size SIZE]` 把一个磁盘镜像当作 U 盘插进去 (镜像不存在时新建一个, `--size` 如 `256M` 或 `2G`, 默认 `256M`, 格式化成 FAT, 需要 `mkfs.vfat` 或 `mkfs.exfat`); `acdev vm usb remove [IMAGE|ID]` 拔出一个 (默认: 最后插上的那个); `acdev vm usb list` 列出它们. `acdev vm wake` 唤醒进入睡眠 (S3) 的客户机. `acdev vm provision` 把客户机配置成测试用的样子, 可以重复运行: 测试用户 (`--user NAME`, 默认 `tester`; 密码是 `ACDEV_VM_PASSWORD`, 默认 `dopame-dev`)、acdes 登录界面上的 greetd、按 acdes 的 PKGBUILD 摆放的 acdes 和 winman (`--acdes DIR` 是 acdes 的检出, 配上 `--acdes-bin FILE` 和 `--winman-bin FILE`, 它们给客户机的构建)、Dopame 包 (`--dopame DIR`, 已构建的 dopame 检出, `packages/dopame/dist`)、`--libacde DIR` (libacde 的检出, 取它的 LICENSE) 和 `--harness FILE` (dopame-harness 的构建). 默认它重启 greetd, 并启动模拟的 Wi-Fi (经 mac80211_hwsim 的两个接入点)、模拟的蓝牙控制器 (btvirt) 和模拟的电池 (100%, 充电中); `--no-restart`、`--no-wifi`、`--no-bluetooth` 和 `--no-battery` 分别去掉其中一项, `--btvirt FILE` 给客户机一个 btvirt 构建 (没有它时 provision 在客户机里构建一个). `--wifi`、`--bluetooth` 和 `--battery` 照收, 但不起作用, 因为这三样默认都开着. 客户机的驱动裁剪会连同模块包一起去掉 `mac80211_hwsim` (也可能去掉 `bochs`); provision 会试着用 `pacman -S` 把它们装回来 (没有哪个软件源有它们时只给一条警告), `--kernel-pkgs DIR` 改从主机上的一个目录装 (和客户机的 `linux-ackernel` 版本相符的 ackernel 构建里的 `linux-ackernel-<group>-*.pkg.tar.zst`; 版本不同时 provision 停下, 并说出两个版本). 所有东西都在 `$ACDEV_VM_DIR` 里 (默认 `~/.local/share/acdev/vm`): 镜像、overlay 磁盘、socket 和 `logs/serial.log`. 需要 `qemu-system-x86_64`、`qemu-img` 和 OVMF; 没有 `/dev/kvm` 的访问权限时它用模拟来跑, 慢得多.

## 测试

```text
acdev test [dir|file...] [--headed] [-t PATTERN] [--desktop ID|DIR] [--vm] [--timeout MS] [--bail] [--trace] [-u]
          [--workers N] [--retries N] [--video[=on|failed|off]]
```

| 参数 | 说明 |
| --- | --- |
| `--headed` | 开窗口 (默认 headless) |
| `-t`, `--test-name-pattern` | 只跑名字匹配的测试 |
| `--desktop` | 应用跑在这个桌面里 |
| `--vm` | 在 [`acdev vm`](#acdev-vm) 客户机里已登录的会话中运行: 一次一个文件, 所有测试用同一个会话, home 是那个用户的 `HOME`; 先把用户的密码设为 `ACDEV_VM_PASSWORD` (默认 `dopame-dev`), 并重置它的登录失败锁定 |
| `--timeout` | 每个测试的超时, 包括启动它的会话的时间 (毫秒, 默认 60000) |
| `--bail` | 第一个失败就停 |
| `--trace` | 每个测试都留 `trace.html` |
| `-u`, `--update-screenshots` | 重写截图基线 |
| `--workers` | 同时跑几个测试文件 (默认: 核数的一半, 最多 4; 带 `--headed` 或 `--bail` 时是 1) |
| `--retries` | 失败的测试再跑这么多次, 每次都在全新的会话上; 后来通过的测试报告为 flaky (默认 0) |
| `--video` | 给失败的测试留下 `video.png`, 一张屏幕的动画 PNG (和 `--video=failed` 一样); `--video=on` 给每个测试都留, `--video=off` 都不留 (默认) |

运行结束时有一行, 数测试和文件, 并列出失败的文件 (`acdev test: 5 tests in 2 files: 4 passed, 1 failed; failed: e2e/notes.e2e.ts`); 见 [端到端测试](https://docs.dopame.ai/zh/guide/testing.md#命令).
