# acdev dev

```sh
acdev dev
```

做的事:

1. 构建工程 (到 `.acde/`);
2. 启动 acdev runtime, 由它在你的电脑上开**一个**窗口: **宿主窗口**, 相当于一台 Dopame OS 机器的屏幕;
3. 盯着工程的文件, 改了就重新构建、重新载入受影响的窗口.

一个跑着的 `acdev dev` 就是一个**开发会话**: [调试命令](https://docs.dopame.ai/zh/guide/tools.md)、[MCP](https://docs.dopame.ai/zh/guide/mcp.md) 和 `acdev test` 都要连上一个开发会话才能工作.

## 跑什么

| 命令 | 跑出来的 |
| --- | --- |
| `acdev dev` (应用工程) | 只有这个应用, 窗口铺满宿主窗口; 关掉应用就结束 |
| `acdev dev` (桌面工程) | 这个桌面 |
| `acdev dev --app ID` | 工程里有多个应用时挑一个 |
| `acdev dev ./a ./b` | 几个工程一起, 跑在一个桌面里 |
| `acdev dev ./app --desktop ./my-desktop` | 应用跑在指定的桌面工程里 |
| `acdev dev ./app --desktop dopame` | 应用跑在 `dopame` 桌面里 (要先 [装上它](https://docs.dopame.ai/zh/start/install.md#安装-dopame-桌面)) |

几个工程或给了 `--desktop` 时, 用哪个桌面: `--desktop` 的值; 否则这些工程里唯一的桌面工程; 否则 `dopame`. `--desktop` 的值像路径 (含 `/`, 或是 `.` / `..`), 或当前目录下有同名工程时, 当作又一个工程.

在工程目录里运行的 `acdev webs` 列出应用的页面时, 会话就绪了. 声明了能力就得到它, 所以应用马上开窗口. 摄像头和麦克风要等一个回答, 在另一个终端里用 `acdev allow` 或 `acdev deny` 给出: 只有要用其中一样的页面才等. 见 [摄像头和麦克风](https://docs.dopame.ai/zh/guide/tools.md#摄像头和麦克风).

`--headless` 不开窗口 (这样的会话叫 **headless 会话**), 适合脚本和 CI; 页面照常渲染, 截图照常能拍. 在没有 GPU 的 Linux 上, 它经软件 Vulkan 驱动 (lavapipe) 用 CPU 画, 比较慢; 见 [平台支持](https://docs.dopame.ai/zh/reference/platforms.md).

在没有显示器的机器上, 比如经 ssh 连上的 Linux 服务器, 用 `--headless`, 再用 `acdev shot`、`acdev screen` 和 `acdev inspect` 看会话 (见 [没有显示器](https://docs.dopame.ai/zh/guide/tools.md#没有显示器)). Linux 上不带 `--headless` 的 `acdev dev` (以及 `acdev test --headed`) 在 `WAYLAND_DISPLAY` 和 `DISPLAY` 都没设时马上停下, 并说明原因. 如果 acdev runtime 还是出错退出了, `acdev dev` 会在 acdev runtime 自己的消息后面加上同样的 `--headless` 提示.

headless 会话可以和带窗口的会话同时跑, 比如主检出上的窗口给你自己用, 一个 git worktree 上的 headless 会话给 agent 构建、测试和查看. 不同目录上的会话互不干扰; 同一个目录上的第二个会话要 `--force`. 两个运行时共用存在你用户目录里的网页存储、窗口位置、文件夹授权和权限决定; 给 agent 的会话带上 `ACDE_STORAGE=` (空) 启动, 它的存储、位置和授权就只在内存里, 再给它单独的 `XDG_CONFIG_HOME`, 权限决定也分开. 工具挑跑着当前目录的那个会话, 或者用 `--session <pid>` 指定.

## 重新载入

- 改了文件, 150 ms 内的改动合并成一次构建, 只重建改到的那个工程.
- 应用: 关掉它的窗口, 按原来的位置和尺寸重新打开 (配置的 `size` 变了按新的). 桌面: 重载桌面页面, 服务不重启.
- 一次构建只改了样式表和脚本时 (除了 `<style>`、`<link rel="stylesheet">` 和 `<script>` 标签, HTML 一样), `acdev dev` 让运行时把它们换进开着的页面, 不重新载入: 样式原地替换, 模块脚本里改了的函数体在页面继续运行时替换. 运行时换不了的改动 (页面的 HTML、模块的顶层代码、经典脚本、正在运行的函数) 照下面说的重新载入页面. 后端和桌面服务的脚本从来不换.
- 手写的包 (`package.json` 里有 `acde` 字段, 由你自己的脚本构建) 里, 它的清单点名的目录 (比如 `dist/`) 也会被盯着, 尽管别处会跳过 `dist` 和 `build`; 它的其他文件 (源码) 改了不会重新载入什么, 直到你的构建写出新的产物.
- 重载时保留状态: 表单的值、滚动位置、焦点和选区会尽量放回去. 页面本身是重新载入的: 没有模块热替换, 所以组件状态 (React 的计数器、Vue 的状态、内存里的值) 从头开始; 见 [前端框架](https://docs.dopame.ai/zh/guide/frameworks.md#在-acdev-dev-里保存).
- 构建失败只打一行错误, 窗口保持上一次的样子.
- `node_modules`、`.acde`、`.git`、`dist` / `build` / `.next` 等框架的输出目录、`*.e2e.*` 测试文件、`__screenshots__` 里的变化不触发构建.

## 产物

默认构建到工程的 `.acde/`. `--out DIR` 改位置: 绝对路径直接用, 相对路径相对**被构建的工程**. 开发会话的构建只经 `ACDE_PATH` 交给 acdev runtime, **不会**装进本机的包目录.

## 结束

Ctrl+C、关掉窗口, 或 acdev runtime 退出, `acdev dev` 都会结束, 退出码跟 acdev runtime 一致. 带窗口的会话出了错也继续跑: acdev runtime 崩溃时它重新启动它 (一分钟内最多三次; 第四次崩溃结束会话), 第一次构建失败时它打出错误, 等下一次改动, 而不是退出. 带 `--headless` 时 (以及在 `acdev test` 里), 这两种情况都会结束会话, 好让脚本和 agent 看到. 要结束一个在后台跑的 `acdev dev`, 在工程目录里运行 `acdev stop` (或 `acdev stop --session <pid>`): 它让 acdev runtime 退出, 等 `acdev dev` 退出, 再打出 `acdev: stopped acdev dev <pid>`.

## 日志

终端里能看到: 构建和重载、页面的 `console.*` (像 `6975.356 I acdev js: …` 这样的行) 和未捕获的错误 (`[<应用>#<窗口>] page error: …`)、后端的输出 (`[<应用>#backend] …`)、应用发生了什么 (它的后端启动或停止了、重载后状态放回去了、一个 `alert()`、一个在等回答的批准提示), 以及运行时的警告和错误 (像 `14.383 W main …` 这样的行). 运行时自己的 info 日志 (启动耗时、GPU 之类: `14.382 I main …`) 不显示, `acdev dev --verbose` 才把它也显示出来.

想在另一个终端里看、或者让脚本读, 用 [调试工具](https://docs.dopame.ai/zh/guide/tools.md) 的 `acdev console` / `acdev network`.

## DevTools

在宿主窗口里按 **F12** (Mac 键盘上是 fn+F12), 给那个窗口里的页面打开 Chrome 或 Edge 的 DevTools: Elements、Console、Network, 以及能下断点的 Sources. 终端里会打出 `acdev: opened DevTools for <page> in <browser>`; 再按一次 F12 把那个 DevTools 窗口拿到最前面. 在另一个终端里, `acdev devtools [web]` 做同样的事 (见 [DevTools](https://docs.dopame.ai/zh/guide/tools.md#devtools)). 页面收不到这个 F12; 带 Ctrl、Shift、Alt 或 Cmd 的 F12 仍然交给页面.

DevTools 开在 acdev 自己的一份浏览器 profile 里, 不是你平时用的那份. `ACDEV_BROWSER` 指定另一个浏览器; 没有 Chrome 或 Edge, 或者设了 `ACDEV_BROWSER=none` 时, 终端改为打出地址, 让你贴进浏览器里.

## 运行时

`acdev dev` 跑 `ACDEV_RUNTIME` 指的运行时二进制 (一个路径; 文件不在时报错停下), 没设就用安装脚本装在 acdev 旁边的那个 (安装目录的 `libexec/acdev`); 两样都没有时报错停下. `acdev --version` 显示它找到的是哪个, `acdev doctor` 检查它在这台机器上能不能跑; 见 [运行时](https://docs.dopame.ai/zh/start/install.md#运行时) 和 [检查环境](https://docs.dopame.ai/zh/guide/doctor.md).

acdev runtime 在会话就绪之前就退出时 (比如用不了 GPU), `acdev dev` 先打出它的那行日志, 再打 `acdev: acdev runtime exited (1) before it was ready; acdev doctor checks the runtime, the GPU and this setup`, 并以同一个退出码退出.
