# 安装

安装脚本装上 acdev (命令行工具、工程模板和 SDK), 连同和它配对的运行时, 你的应用由它来跑. 安装脚本不经 npm, 不需要 root. 见 [运行时](#运行时).

## 交给编码 agent

把这句话交给你的 agent:

```text
Read https://pkgs.dopame.ai/acdev/install.md and follow it to set up acdev on this machine.
```

它读到的那一页会让它检查 Bun 或 Node.js、跑下面的安装脚本、给自己装上 acdev skill, 再汇报哪些已经就绪. 见 [编码 agent](https://docs.dopame.ai/zh/guide/agents.md).

## 先决条件

acdev 跑在你已有的 JS 运行时上, 二选一:

- [Bun](https://bun.sh) 1.4 或更新
- [Node.js](https://nodejs.org) 22.3 或更新

两个都有时 acdev 用 Bun. 安装脚本不会替你装它们.

`acdev test` (端到端测试) 只能在 Bun 上跑. 只有 Node.js 时, 其余命令都能用.

## 支持的平台

| 系统 | CPU |
| --- | --- |
| macOS | Apple 芯片 (arm64)、Intel (x86_64) |
| Linux | x86_64 |
| Windows | x64 |

acdev 本身是 JavaScript; 上表是运行时有构建的平台 (`aarch64-apple-darwin`、`x86_64-apple-darwin`、`x86_64-unknown-linux-gnu`、`x86_64-pc-windows-msvc`), 在别的平台上安装脚本会停下并给出这份列表. Windows 的安装脚本只支持 x64. 各平台上运行时能做的事不完全一样, 见 [平台支持](https://docs.dopame.ai/zh/reference/platforms.md).

## macOS / Linux

```sh
curl -fsSL https://pkgs.dopame.ai/acdev/install.sh | sh
```

装进 `~/.acdev` (用 `ACDEV_INSTALL` 改), 并在这台机器上每种 shell 的启动文件里把 `~/.acdev/bin` 加进 PATH, 每个文件只加一次, 并列出它们: `~/.profile` (sh、dash、ksh 和登录 shell)、`~/.bashrc` 和已有的 `~/.bash_profile` 或 `~/.bash_login` (bash)、`~/.zshrc` 和 `~/.zprofile` (zsh)、`~/.config/fish/conf.d/acdev.fish` (fish)、`~/.cshrc` 和已有的 `~/.tcshrc` (csh、tcsh), 以及 nushell 的 `env.nu`. 在 sh 一族的文件里, 这一行只在 PATH 里还没有 `~/.acdev/bin` 时才加, 所以读好几个这种文件的 shell (登录的 zsh 读 `.zprofile` 和 `.zshrc`) 里也只有一份; 以前安装留下的不带这个判断的那一行会被原地替换. 每个下载开始前打出文件名和大小; 在终端里运行时每个下载都有进度条; 每下完一个, 以及输出被接走时 (coding agent、CI), 都打一行文件的大小和 SHA-256 核对结果. 下载卡住 (30 秒不到 1 KB/s) 时重试两次, 还不行就停下, 什么都不装.

不想让它动启动文件:

```sh
curl -fsSL https://pkgs.dopame.ai/acdev/install.sh | sh -s -- --no-modify-path
```

装指定版本: `sh -s -- --version X.Y.Z`.

## Windows

在 PowerShell 里:

```powershell
irm https://pkgs.dopame.ai/acdev/install.ps1 | iex
```

装进 `%USERPROFILE%\.acdev`, 并把它加进用户的 `Path`. 和 macOS / Linux 的安装器一样, 在终端里每个下载都显示进度 (大小、速度、剩余时间), 每个文件打一行大小和 SHA-256 核对结果, 某个下载 30 秒收不到数据时试满三次就停下. 你关掉过进度显示 (`$ProgressPreference = 'SilentlyContinue'`) 的话, 它也不显示.

在经典的 Windows 控制台 (单独启动的 powershell.exe 或 cmd.exe) 里, `acdev new` 和其他提示画的方框和边框用 ASCII 字符 (`+`、`-`、`|`); Windows Terminal 和 VS Code 的终端里显示制表线字符. 两种用起来一样; 推荐 Windows Terminal.

`irm | iex` 传不了参数. 在它之前设好环境变量, 或者把脚本当作脚本块来运行, 把它的参数 `-Version` 和 `-NoModifyPath` 传给它:

```powershell
$env:ACDEV_VERSION = 'X.Y.Z'; $env:ACDEV_NO_MODIFY_PATH = '1'
irm https://pkgs.dopame.ai/acdev/install.ps1 | iex

& ([scriptblock]::Create((irm https://pkgs.dopame.ai/acdev/install.ps1))) -Version X.Y.Z -NoModifyPath
```

## 用 npm 安装

工具都用 npm 来装的地方 (CI 镜像、容器、由本来就用 npm 的脚本配好的机器), 改从 npm 仓库装 acdev, 不跑安装脚本:

```sh
npm install -g @dopame/acdev
```

这要 Node.js 22.3 或更新: npm 放到 PATH 上的 `acdev` 命令用 Node.js 启动. 它装上 `@dopame/acdev`, 并经由它装上这个平台的包 (`@dopame/acdev-linux-x64`、`@dopame/acdev-darwin-arm64`、`@dopame/acdev-darwin-x64` 或 `@dopame/acdev-win32-x64`), 包里是 acdev 和运行时二进制, 摆放方式和安装脚本装出来的一样, 所以 acdev 在自己旁边就能找到运行时, `acdev doctor` 也照同样的方式检查它. 平台就是上面那几个; 别的平台的包 npm 会跳过. 版本就是安装脚本发布的那些版本: `npm install -g @dopame/acdev@X.Y.Z` 装那一版, 再跑一遍这条命令就把 acdev 和运行时一起升级. 不改任何 shell 启动文件; acdev 在 npm 放全局命令的地方 (`npm prefix -g`). 卸载: `npm uninstall -g @dopame/acdev`.

没有 npm 的机器仍然用下面的安装脚本, 这几页其余的内容也都假定用的是它 (`~/.acdev`、PATH 那几行、升级说明).

## 安装脚本的选项

两个安装脚本的选项相同, 各有各的写法:

| 选项 | `install.sh` | `install.ps1` |
| --- | --- | --- |
| 装指定版本 (和它的运行时) | `--version X.Y.Z` | `-Version X.Y.Z` 或 `ACDEV_VERSION` |
| 不动启动文件 / 用户的 `Path` | `--no-modify-path` | `-NoModifyPath`, 或把 `ACDEV_NO_MODIFY_PATH` 设成任意值 |
| 装到 `~/.acdev` 以外的地方 | `ACDEV_INSTALL` | `ACDEV_INSTALL` |

在 PowerShell 里, 这样设的环境变量在那个终端里一直留着; 之后的安装要用默认值的话, 装完把它们去掉 (`Remove-Item Env:ACDEV_VERSION`).

## 检查

> **先新开一个终端.** 安装脚本改的 `PATH` 只对之后新开的终端生效, 所以在刚才跑安装的那个终端里, `acdev` 会报 `command not found`. 一定要用那个终端的话, 先运行安装脚本打出来的最后一行 (`export PATH=…`, PowerShell 里是 `$env:Path = …`).

在新终端里运行:

```sh
acdev doctor
```

它检查 `acdev dev` 和 `acdev test` 需要的东西: PATH 上的 acdev、Bun 和 Node.js、运行时 (找到没有、能不能跑、和这一版 acdev 是否配对, 以及运行时自己对它的文件和 GPU 的检查, 它会在 GPU 上画一帧测试图) 等等. 每行以 `ok`、`warn`、`error` 或 `skip` 开头, 每个问题下面跟一行以 `fix:` 开头的修法, 最后一行说是不是都齐了. 见 [检查环境](https://docs.dopame.ai/zh/guide/doctor.md).

`acdev --version` 只打版本: acdev、构建它时用的 SDK 和契约级别, 以及它找到的运行时和运行时的版本、契约级别.

## 运行时

`acdev dev` 和 `acdev test` 在运行时里跑你的应用. 安装脚本把和这一版 acdev 配对的那一版运行时装在它旁边, 二进制是 `libexec/acdev` (Windows 上是 `acdev.exe`), 按那个版本的 `SHA256SUMS` 核对过. 配对关系记在 acdev 的每个版本里, 所以装 acdev 的指定版本 (安装脚本的 `--version X.Y.Z`, Windows 上是 `-Version X.Y.Z`) 也就装上那个版本配对的运行时. 运行时装不上时 (你的平台没有构建, 下载或校验失败), 安装脚本什么都不装, 原来有的保持不动.

acdev 按这个顺序找运行时:

1. `ACDEV_RUNTIME`: 一个运行时二进制的路径; 不在 PATH 上查找, 文件不在时 acdev 报错停下;
2. 安装脚本装在 acdev 旁边的运行时, 即安装目录的 `libexec/acdev`.

没有别的地方了: acdev 不找它旁边的源码检出里构建出的运行时, 即使 acdev 自己是从源码跑的; 要用那样的运行时, 设 `ACDEV_RUNTIME`.

两样都没有时, `acdev dev` 停下并说明原因 (`acdev dev needs the Dopame runtime (libexec/acdev of an install) and found none: …`), `acdev doctor` 说出它找过哪些地方、该怎么办.

运行时在 GPU 上绘制页面, 要一块能用的 GPU (macOS Metal, Windows DirectX 12, Linux Vulkan). 在 Linux 上, 这指的是这台机器的 GPU 的硬件 Vulkan 驱动 (Mesa: Arch 上是 `vulkan-intel` 或 `vulkan-radeon`, Debian、Ubuntu 和 Fedora 上是 `mesa-vulkan-drivers`; NVIDIA: 厂商的驱动). 软件 Vulkan 驱动 (lavapipe, `vulkaninfo` 里显示为 `llvmpipe`) 只在没有 GPU 驱动时才用: 这时页面在 CPU 上绘制, 动画很慢, `acdev doctor` 会对此给出警告. WSL 里 GPU 的 Vulkan 驱动是 Dozen (跑在 Direct3D 12 上的 Vulkan), 它不是合规的驱动, 所以除非设了 `WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER=1`, 会跳过它改用软件驱动. 完全没有驱动时, `acdev dev` 一启动就失败, 日志里有一行以 `web layer unavailable:` 开头, 写着 `no usable Vulkan driver was found: install the GPU's Vulkan driver …`: 装上驱动, 再确认 `vulkaninfo --summary` 列出了这块 GPU. 启动任何东西之前, `acdev doctor` 的 `gpu` 那项就会以错误报出同一行.

### 手动安装运行时

只在安装脚本装不了运行时的时候这样做, 比如这台机器访问不了 `https://pkgs.dopame.ai/`. 装出来的是运行时二进制 `acdev` (Windows 上是 `acdev.exe`); 把 `ACDEV_RUNTIME` 设成它的路径 (下面的命令里是 `~/.acdev-runtime/acdev`). 运行时和 acdev 一起发布, 放在 `https://pkgs.dopame.ai/acdev/<版本>/`, 最新版本号在 `https://pkgs.dopame.ai/acdev/latest` 里. 一个版本里有:

| 文件 | 是什么 |
| --- | --- |
| `acdevrt-aarch64-apple-darwin.tar.xz` | macOS (Apple 芯片) 的运行时 |
| `acdevrt-x86_64-apple-darwin.tar.xz` | macOS (Intel) 的运行时 |
| `acdevrt-x86_64-unknown-linux-gnu.tar.xz` | Linux x86_64 的运行时 |
| `acdevrt-x86_64-pc-windows-msvc.tar.gz` | Windows x64 的运行时 |
| `acdevtools-<triple>.tar.xz` (Windows 上是 `.tar.gz`) | `acdevtool`, `acdev vm` 的辅助程序 |
| `acdev-guest-<版本>.tar.gz` | acdevd, `acdev vm` 放进客户机的设备守护进程, x86_64 和 aarch64 各一份 |
| `acdev-<版本>.tar.gz` | acdev 本身 (安装脚本放进 `~/.acdev` 的东西) |
| `acde-api-<版本>.tar.gz` | SDK, 即工程作为开发依赖安装的 `@dopame/acde-api` (见 [工程结构](https://docs.dopame.ai/zh/start/project.md#sdk)); 跑运行时用不着它 |
| `SHA256SUMS` | 上面这些文件的校验和 |

每个运行时归档里只有运行时二进制 `acdev` (Windows 上是 `acdev.exe`).

下载你的平台的归档和 `SHA256SUMS`, 核对后解压. Linux 上解 `.tar.xz` 要有 `xz` (`xz` 或 `xz-utils` 包).

macOS 或 Linux 上, 把下面几行粘贴进终端, `target` 按你的平台改 (外面的括号让终端留在原来的目录): Apple 芯片是 `aarch64-apple-darwin`, Intel 的 Mac 是 `x86_64-apple-darwin`, Linux 是 `x86_64-unknown-linux-gnu`.

```sh
(
target=aarch64-apple-darwin
base=https://pkgs.dopame.ai/acdev
version=$(curl -fsSL "$base/latest" | tr -d ' \r\n')
mkdir -p ~/.acdev-runtime && cd ~/.acdev-runtime
curl -fsSLO "$base/$version/acdevrt-$target.tar.xz" -O "$base/$version/SHA256SUMS"
grep -E " acdevrt-$target\.tar\.xz\$" SHA256SUMS | sha256sum -c - &&
  tar -xJf "acdevrt-$target.tar.xz"
)
```

`sha256sum` 打出 `OK`; 不是的话什么都不会解压. 然后告诉 acdev 它在哪: 把这一行加进 shell 的启动文件, 并在当前终端里也运行一次:

```sh
export ACDEV_RUNTIME="$HOME/.acdev-runtime/acdev"
```

Windows 上, 在 PowerShell 里:

```powershell
& {
  $ProgressPreference = 'SilentlyContinue'
  $base = 'https://pkgs.dopame.ai/acdev'
  $version = (Invoke-RestMethod "$base/latest").Trim()
  $dir = "$env:USERPROFILE\.acdev-runtime"
  New-Item -ItemType Directory -Force $dir | Out-Null
  $files = @('acdevrt-x86_64-pc-windows-msvc.tar.gz')
  foreach ($f in $files + 'SHA256SUMS') { Invoke-WebRequest "$base/$version/$f" -OutFile "$dir\$f" }
  $sums = Get-Content "$dir\SHA256SUMS"
  foreach ($f in $files) {
    $want = (($sums | Where-Object { $_ -like "* $f" }) -split ' ')[0]
    if ((Get-FileHash "$dir\$f").Hash -ne $want) { throw "checksum mismatch: $f" }
  }
  tar -xzf "$dir\acdevrt-x86_64-pc-windows-msvc.tar.gz" -C $dir
  [Environment]::SetEnvironmentVariable('ACDEV_RUNTIME', "$dir\acdev.exe", 'User')
  $env:ACDEV_RUNTIME = "$dir\acdev.exe"
}
```

它给你的用户和当前终端都设上 `ACDEV_RUNTIME`.

升级运行时: 再跑一遍同样的命令. 用一个新工程确认它能用:

```sh
acdev new hello --template html --yes
cd hello
acdev dev
```

### 安装 Dopame 桌面

`acdev dev` 默认只跑你的应用. 想让它跑在 Dopame 的桌面里 (`acdev dev --desktop dopame`、`acdev test --desktop dopame`), 还要装上 `dopame` 这个桌面包. 它和 acdev、运行时分开发布, 在 `pkgs.dopame.ai` 上: `https://pkgs.dopame.ai/acde-dopame/latest.json` 给出最新的构建: 其中的 `base` 是放 `dopame.tar.gz` 和 `SHA256SUMS` 的目录. 归档里是一个包目录 `dopame/`, 把它解压进包目录 `$XDG_DATA_HOME/acde/packages` (默认 `~/.local/share/acde/packages`):

```sh
(
base=$(curl -fsSL https://pkgs.dopame.ai/acde-dopame/latest.json | sed -n 's/.*"base": *"\([^"]*\)".*/\1/p')
packages="${XDG_DATA_HOME:-$HOME/.local/share}/acde/packages"
mkdir -p "$packages" && cd "$(mktemp -d)"
curl -fsSLO "${base}dopame.tar.gz" -O "${base}SHA256SUMS"
sha256sum -c SHA256SUMS &&
  rm -rf "$packages/dopame" && tar -xzf dopame.tar.gz -C "$packages"
)
```

Windows 上包目录是 `%USERPROFILE%\.local\share\acde\packages`, 用 `tar -xzf dopame.tar.gz -C <那个目录>` 把同一个归档解压进去.

然后在你的工程里:

```sh
acdev dev --desktop dopame
```

你的应用在桌面的应用列表里, 从那里打开. 桌面的助手要一个不在这份下载里的程序, 所以输出里会有一条关于它的警告 (`no assistant`); 其余功能都正常. 运行时到哪些地方找包, 见 [本机安装](https://docs.dopame.ai/zh/guide/install.md#找包).

## 升级与卸载

升级: 再跑一遍安装命令; 它也会升级运行时. 每个版本装在 `~/.acdev/versions/<版本>`, 它的运行时在它的 `libexec` 里, `~/.acdev/current` 指向在用的那个. 安装脚本保留它装的版本和被它换下的版本, 删掉更早的 (每个大约 100 MB); 还有程序在用的版本 (从它启动的 `acdev dev`) 留到下一次安装.

`acdev uninstall` 删的是装了的应用和桌面, 不是 acdev 自己 (见 [本机安装](https://docs.dopame.ai/zh/guide/install.md#卸载)). 卸载 acdev: 装过 skill 的话先 `acdev skills remove`, 删掉 `~/.acdev`, 再从 shell 的启动文件里去掉安装脚本加进去的 `# acdev` 那几行 (它列出过是哪些文件); Windows 上从用户的 `Path` 里去掉 `%USERPROFILE%\.acdev\current\bin`, 并删掉用户变量 `ACDEV_INSTALL`. 按上面手动装过运行时或装过桌面的话, 再删掉 `~/.acdev-runtime`, 并去掉 `ACDEV_RUNTIME` 那一行.

acdev 和运行时在安装目录之外还存着数据. 要全部去掉, 把这些也删掉; 不然以后再装时, 旧的应用、桌面和它们的数据又会被找到. macOS 上用的也是这些路径; Windows 上没有 `XDG_*` 变量时, 它们在 `%USERPROFILE%` 下, 名字相同 (`%USERPROFILE%\.local\share\acdev` 等等):

| 目录 | 里面是什么 |
| --- | --- |
| `$XDG_DATA_HOME/acde` (`~/.local/share/acde`) | 装了的应用和桌面 (`packages/`)、应用的后端数据 (`apps/<id>/`)、存储 (`storage/app-<id>/`、`storage/desktop-<id>/`) 和私有文件 (`files/<id>/`)、skill 的安装记录 (`skills.json`) |
| `$XDG_STATE_HOME/acde` (`~/.local/state/acde`) | 窗口位置、文件夹授权 (`grants/<id>.json`)、上次的桌面和其他会话状态 |
| `$XDG_CONFIG_HOME/acde` (`~/.config/acde`) | 批准的决定 (`permissions.json`) |
| `$XDG_CONFIG_HOME/acde-mimeapps.list` 和 `$XDG_CONFIG_HOME/acde-extensions.list` (`~/.config/…`) | 给文件类型或扩展名选的默认应用 |
| `$XDG_CACHE_HOME/acde` (`~/.cache/acde`) | 缓存 (只在没设 `XDG_RUNTIME_DIR` 时) |
| `~/Library/Caches` (macOS)、`%LOCALAPPDATA%` (Windows) 或 `$XDG_CACHE_HOME` (`~/.cache`, Linux) 下的 `acde/devtools` | `acdev devtools` 和 F12 打开 DevTools 用的浏览器配置 |

Windows 上, 在 `acdev dev` 跑着时重装同一个版本, 会把正在用的文件挪到一边 (`versions/<版本>.old-…`); 安装脚本会说明, 并在下次运行时删掉它们.
