安装
安装脚本装上 acdev (命令行工具、工程模板和 SDK), 连同和它配对的运行时, 你的应用由它来跑. 安装脚本不经 npm, 不需要 root. 见 运行时.
交给编码 agent
交给编码 agent 一节的链接把这句话交给你的 agent:
Read https://pkgs.dopame.ai/acdev/install.md and follow it to set up acdev on this machine.它读到的那一页会让它检查 Bun 或 Node.js、跑下面的安装脚本、给自己装上 acdev skill, 再汇报哪些已经就绪. 见 编码 agent.
先决条件
先决条件 一节的链接acdev 跑在你已有的 JS 运行时上, 二选一:
两个都有时 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. 各平台上运行时能做的事不完全一样, 见 平台支持.
macOS / Linux
macOS / Linux 一节的链接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) 时重试两次, 还不行就停下, 什么都不装.
不想让它动启动文件:
curl -fsSL https://pkgs.dopame.ai/acdev/install.sh | sh -s -- --no-modify-path装指定版本: sh -s -- --version X.Y.Z.
Windows
Windows 一节的链接在 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 传给它:
$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 安装 一节的链接工具都用 npm 来装的地方 (CI 镜像、容器、由本来就用 npm 的脚本配好的机器), 改从 npm 仓库装 acdev, 不跑安装脚本:
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 = …).
在新终端里运行:
acdev doctor它检查 acdev dev 和 acdev test 需要的东西: PATH 上的 acdev、Bun 和 Node.js、运行时 (找到没有、能不能跑、和这一版 acdev 是否配对, 以及运行时自己对它的文件和 GPU 的检查, 它会在 GPU 上画一帧测试图) 等等. 每行以 ok、warn、error 或 skip 开头, 每个问题下面跟一行以 fix: 开头的修法, 最后一行说是不是都齐了. 见 检查环境.
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 按这个顺序找运行时:
ACDEV_RUNTIME: 一个运行时二进制的路径; 不在 PATH 上查找, 文件不在时 acdev 报错停下;- 安装脚本装在 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 (见 工程结构); 跑运行时用不着它 |
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.
(target=aarch64-apple-darwinbase=https://pkgs.dopame.ai/acdevversion=$(curl -fsSL "$base/latest" | tr -d ' \r\n')mkdir -p ~/.acdev-runtime && cd ~/.acdev-runtimecurl -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 的启动文件, 并在当前终端里也运行一次:
export ACDEV_RUNTIME="$HOME/.acdev-runtime/acdev"Windows 上, 在 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.
升级运行时: 再跑一遍同样的命令. 用一个新工程确认它能用:
acdev new hello --template html --yescd helloacdev dev安装 Dopame 桌面
安装 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):
(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 <那个目录> 把同一个归档解压进去.
然后在你的工程里:
acdev dev --desktop dopame你的应用在桌面的应用列表里, 从那里打开. 桌面的助手要一个不在这份下载里的程序, 所以输出里会有一条关于它的警告 (no assistant); 其余功能都正常. 运行时到哪些地方找包, 见 本机安装.
升级与卸载
升级与卸载 一节的链接升级: 再跑一遍安装命令; 它也会升级运行时. 每个版本装在 ~/.acdev/versions/<版本>, 它的运行时在它的 libexec 里, ~/.acdev/current 指向在用的那个. 安装脚本保留它装的版本和被它换下的版本, 删掉更早的 (每个大约 100 MB); 还有程序在用的版本 (从它启动的 acdev dev) 留到下一次安装.
acdev uninstall 删的是装了的应用和桌面, 不是 acdev 自己 (见 本机安装). 卸载 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-…); 安装脚本会说明, 并在下次运行时删掉它们.