# 调试工具

一组命令连到正在跑的 `acdev dev` 开发会话上, 能看页面、执行代码、截图、点按钮. `acdev devtools` 还能给一张页面打开 Chrome 或 Edge 的 DevTools, 见 [DevTools](#devtools). 在另一个终端里运行:

```sh
acdev webs
```

```text
NAME           KIND     APP    WINDOW   TITLE
desktop        desktop  -      0        My Desktop
notes#1048576  app      notes  1048576  Notes
```

## 选会话

这些命令找开发会话的顺序: `--session <pid>`; 否则工程目录包含当前目录的那个; 否则, 不在任何工程里时, 只有一个就用它 (这时命令在 stderr 上点出它: `acdev: using acdev dev <pid> (...), the only one running`); 否则报错并列出所有会话. `acdev test` 为它的测试启动的会话不参与这个选择 (列出时, 它们跑的东西后面带着 `acdev test`); 只有 `--session <pid>` 能连到它们.

## 命令

| 命令 | 作用 |
| --- | --- |
| `acdev webs` | 列出正在跑的页面 (每个窗口一张) |
| `acdev eval <web> <代码>` | 在页面里执行代码, 打印 JSON 结果; Promise 会等它完成. 代码写 `-` 时从 stdin 读 |
| `acdev shot <web> [-o FILE]` | 一个窗口里页面的截图 (PNG); 对 `desktop` 来说不含它钉住的面板 (Dock、菜单栏), 那些要看 `acdev screen` |
| `acdev screen [-o FILE]` | 整个屏幕的截图, 所有窗口合在一起 |
| `acdev pointer <x> <y>` | 把指针移到屏幕上的一个点, 是一次真的移动: 悬停效果和屏幕边缘的事件 (桌面在边缘显示它的 Dock) 随之发生. 在宿主窗口里, 屏幕就是它的内容区 |
| `acdev inspect [--window W] [--find TEXT] [--all] [--offscreen]` | 把屏幕变成文字: 窗口列表和焦点窗口的元素树 (`--all`: 所有没有标 `[minimized]` 的窗口, 以及被 `opacity: 0` 或 `visibility` 隐藏的元素) |
| `acdev query <选择器> [--window W] [--ref REF] [--limit N]` | 用 CSS 选择器找元素, 包括 `inspect` 不列的那些, 给每个打出一个 ref |
| `acdev act <ref> <动作> [参数]` | 按 `inspect` 或 `query` 给的 ref 点击、输入、按键…… |
| `acdev console [--web W] [--level L] [--since S] [--follow]` | 页面的 `console.*` 和未捕获的错误 |
| `acdev network [--web W] [--failed] [--since S] [--follow]` | 页面的 fetch / XHR / WebSocket / EventSource 请求, 以及页面载入的图片、样式表和字体; kind 一列说明是哪一种 |
| `acdev permissions` | 列出等待回答的摄像头和麦克风提示, 以及已做的决定, 见 [摄像头和麦克风](#摄像头和麦克风) |
| `acdev allow` / `acdev deny` `[<提示 id> \| <应用> <能力>] [--all]` | 回答一个等待中的摄像头或麦克风提示 |
| `acdev revoke <应用> <能力>` | 收回一个决定 |
| `acdev stop` | 结束会话, 见 [结束](https://docs.dopame.ai/zh/guide/dev.md#结束) |
| `acdev devtools [web]` | 给一张页面打开 Chrome 或 Edge 的 DevTools, 见 [DevTools](#devtools) |

一个 **web** 就是一张页面: 桌面页, 或一个应用窗口里的页面 (每个窗口一张). `<web>` 可以是 `acdev webs` 列出的 web 名 (`notes#1048576`)、应用 id (那个应用的第一个窗口) 或 `desktop`. 在 Dopame OS 客户机里, 1.5 秒内没有回答的页面 (它的进程停了或在忙) 照样列出, 标题是 `(not answering)`; 其余页面照常列出.

### eval

```sh
acdev eval notes 'document.title'
acdev eval notes 'import("acde:fs").then(m => m.fs.roots())'
echo 'localStorage.length' | acdev eval notes -
```

Windows 上 `acdev` 是 `acde.cmd`, 所以到达命令行工具的是 cmd 处理过的参数. 各种 shell 传来的不一样:

- PowerShell (5.1 和 7) 给 `.cmd` 传参数时会丢掉参数里的双引号; 把它们写成 `\"` (下面的第一行).
- cmd 没有单引号字符串: 把参数放进双引号里, 里面的双引号写成 `\"` (下面的第二行).

```powershell
acdev eval notes 'document.querySelector(\"#x\").textContent'
```

```bat
acdev eval notes "document.querySelector(\"#x\").textContent"
```

代码里只有单引号时, 三种 shell 里写法都一样; 从 stdin 传代码则不用管这个问题 (下面是 PowerShell 的写法):

```powershell
acdev eval notes "document.querySelector('#x').textContent"
'document.querySelector("#x").textContent' | acdev eval notes -
```

任何带双引号的参数都是这样, 比如 `act ... type`.

### inspect 和 act

`inspect` 给每个元素一个 **ref** (元素编号), 比如 `w1.18` (窗口 `w1` 里的第 18 号元素); 把它交给 `act`.

```sh
$ acdev inspect
- window "Notes" [app=notes] [focused] [fullscreen] [w1]
  - heading "Notes" [level=1] [w1.16]
  - form [w1.6]
    - text "Title" [w1.17]
    - textbox "Title": "" [w1.18]
    - text "Email" [w1.19]
    - textbox "Email": "" [w1.20]
    - button "Save" [w1.21]
  - list "Saved notes" [w1.7]
    - listitem [w1.22]
      - text "Buy milk" [w1.22]
  - text "1 note" [w1.8]
  (1 more outside the visible area; scroll, or add offscreen)

$ acdev act w1.18 type "Weekly report"
typed, the value is now "Weekly report"

(windows unchanged)
- window "Notes" [app=notes] [focused] [fullscreen] [w1]
  ~ - textbox "Title": "Weekly report" [focused] [w1.18]
  (1 more outside the visible area; scroll, or add offscreen)

$ acdev act w1.21 click
clicked 55,202

(windows unchanged)
- window "Notes" [app=notes] [focused] [fullscreen] [w1]
  ~ - textbox "Title": "" [w1.18]
  ~ - button "Save" [focused] [w1.21]
  + - listitem [w1.23]
  + - text "Weekly report" [w1.23]
  ~ - text "2 notes" [w1.8]
  (1 more outside the visible area; scroll, or add offscreen)
```

不带 `--find` 时, 这段文字总是这种英文格式: 每个窗口一行, 最上层的在前 (`- window "Notes" [app=notes] [focused] [w1]`, 桌面是 `- desktop`), 列出内容的窗口下面是它的元素, 每层缩进两个空格, 写成 `- role "name": "value" [states] [ref]` (值只在元素有值时才有). 括号里的说明讲的是哪些被略去、哪些没有变, 比如 `(empty)`、`(no changes)` 和 `(windows unchanged)`.

`act` 在第一行打出它做了什么 (`clicked 55,202` 是它点的那个点, 用窗口坐标), 等页面安静下来, 再把窗口和那个窗口的内容打一遍. 那个窗口它之前列过的话, 只打出此后变了的: `~` 是变了的一行, `+` 是新的一行, `-` 是没了的一行; `(windows unchanged)` 表示窗口列表没变. 所以做下一步之前, 通常只读 `act` 的输出就够了. 滚出视野的元素会先被滚进视野, 所以 `inspect --offscreen` 或 `query` 给的 ref, 不管元素在页面的哪里都能用.

动作做成了, `act` 的退出码是 0. 没做成时, 它在 stderr 上打一行 `acdev: act <ref>: <原因>`, 退出码 1. 原因有: `the element is not displayed` (它是 `display: none`, 或被 `visibility` 隐藏)、`covered by another element: <div> (27)`、`cannot type into this element`、`there is no such element (any more); acdev inspect --find TEXT gives the current refs` (元素没了, 见下文)、`w1 is minimized; act restore on it first` (对最小化的窗口或它里面的元素做点击或别的指针动作).

只要元素还在, 它的 ref 就不变: 移动它、改它的文字或属性、重排列表, ref 都不变. 页面用一个新元素换掉它时 (比如设 `innerHTML`), 新元素得到新的 ref, 对旧 ref 做动作会失败 (`acdev: act w1.23: there is no such element (any more); …`); 这时重新 `inspect` 一次.

单独跑的应用在标题栏上显示窗口菜单 (见 [窗口](https://docs.dopame.ai/zh/guide/window.md#菜单)), `inspect` 把它们列在最前面: `menubar [w1.m]`, 每个菜单一个 `menuitem "文件" [collapsed] [w1.m1]`, 打开的那个下面是它的各项和快捷键, `menuitem "新建": "ctrl+n" [w1.m1.1]` (分隔线也占一个号). `acdev act w1.m1 click` 打开菜单, `acdev act w1.m1.1 click` 需要时先打开再选中这一项 (`chose 文件 › 新建`), `acdev act w1 key escape` 关上. 禁用的项不选 (`acdev: act w1.m1.4: w1.m1.4 (打印) is disabled`).

默认情况下, 树里不列看不见的元素: `display: none`、`aria-hidden`、`inert`、`opacity: 0` 和 `visibility` 隐藏的. `--all` 列出窗口列表里所有没有标 `[minimized]` 的窗口, 并保留被 `opacity: 0` 隐藏的元素 (标 `transparent`; 它们仍然点得到) 和被 `visibility` 隐藏的元素 (标 `invisible`; 它们点不到); `display: none`、`aria-hidden` 和 `inert` 的总是不列.

不在屏幕上的窗口在窗口列表里标 `[minimized]`: 状态是 `minimized` 的窗口 (`act w1 minimize`、应用自己的 `minimize()` 或桌面的 `windows.requestState(id, 'minimized')` 之后), 以及桌面用 `windows.hide(id)` 藏起来的窗口. 它的元素不列出来: `--all` 和 `--find` 跳过它, `--window w1` 在它那一行下面打出 `(empty)` 和 `(minimized; act restore on it to see its elements)`. 对它的指针动作 (`click`、`double`、`right`、`hover`、`scroll`, 以及从它拖出或拖到它上面的 `drag`) 会被拒绝, `act w1 restore` 把它拿回来. 在跑桌面的会话里:

```sh
$ acdev act w1 minimize
w1 is minimized (the windows changed)

- window "Tools" [app=tools] [minimized] [w1]
- desktop [focused] [fullscreen] [w0]
  - navigation "Apps" [w0.6]
    - button "Tools" [w0.10]

$ acdev act w1.10 click
acdev: act w1.10: w1 is minimized; act restore on it first

$ acdev act w1 restore
w1 is in front (the windows changed)

- window "Tools" [app=tools] [focused] [w1]
  + - heading "Tools" [level=1] [w1.10]
- desktop [fullscreen] [w0]
```

`--find TEXT` 在每个没有标 `[minimized]` 的窗口里找 (或只在 `--window W` 里), 只打出名字或值包含这段文字的元素 (不分大小写). 它的输出有自己的格式: 每个有匹配的窗口一行 `<window ref> <app id> "<title>":` (桌面是 `w0 desktop:`), 下面每个元素一行. 元素在有名字的祖先里面时, 后面跟着 `in` 和离它最近的这样一个祖先; 没有这样的祖先时, 后面什么都不跟:

```sh
$ acdev inspect --find milk
w1 notes "Notes":
- text "Buy milk" [w1.22]  in list "Saved notes" [w1.7]

$ acdev inspect --find save
w1 notes "Notes":
- button "Save" [w1.21]
- list "Saved notes" [w1.7]
```

什么都没匹配到时, 它在 stderr 上说明 (`acdev: no element's name or value contains "milk"; elements scrolled out of view need --offscreen`), 退出码 2. 滚出视野的元素要加 `--offscreen` 才找得到; 不加时, 树下面有一条说明, 写着略去了多少个 (`(1 more outside the visible area; scroll, or add offscreen)`).

动作: `click` `double` `right` `hover` `scroll` `type` `settext` `select` `key` `drag` `focus`; 窗口 ref (`w1`) 还能 `close` `minimize` `restore` `fill` `fullscreen`. `fill` 让窗口铺满桌面的工作区, `fullscreen` 让它盖满整个宿主窗口; `restore` 把这两种都还原成普通状态. 两者都不接受桌面 (`the desktop cannot be made filled`、`... fullscreen`) 和已经铺满宿主窗口的窗口 (`w1 already fills the host window`). 对不能最小化的窗口做 `minimize` 什么都不变, 它会说明原因, 退出码 1; 只跑一个应用的会话里, 在 macOS 上和 headless 时, 应用自己的窗口就是这样: `w1 cannot be minimized: it fills the host window, which only the host window's own controls minimize here`. `key` 的参数像 `"ctrl+a backspace"`; `drag` 的参数是目标 ref. 关掉一个窗口使 acdev runtime 结束时 (`acdev dev` 只跑一个应用时的应用窗口), `acdev dev` 也跟着结束; 这时 `act w1 close` 会说明这一点, 退出码 0.

#### 键名

`key` 的参数 (以及测试里的 `press()`) 是用空格隔开的一个或多个组合键; 一个组合键是用 `+` 连起来的几个键, 按顺序按下, 按相反的顺序松开. 键指的是美式键盘布局上的物理键. 不分大小写, 只是单个大写字母 (`A`) 会加上 `shift`:

- 修饰键: `ctrl` (`control`)、`shift`、`alt`、`super` (`meta`、`win`)
- 字母 `a` … `z`, 数字 `0` … `9`, `f1` … `f12`
- `enter` (`return`)、`escape` (`esc`)、`tab`、`space`、`backspace`、`delete` (`del`)、`insert`、`home`、`end`、`pageup`、`pagedown`、`up`、`down`、`left`、`right`、`menu`
- 可打印的字符照原样写: `-` `=` `[` `]` `;` `'` `` ` `` `\` `,` `.` `/`, 以及要按 shift 才打得出的 `!` `@` `#` `$` `%` `^` `&` `*` `(` `)` `_` `+` `{` `}` `|` `:` `"` `<` `>` `?` `~`, 它们自己会加上 `shift` (`*` 就是 `shift+8`). `+` 单独出现, 或在组合键的最后时 (`ctrl++`), 是 `+` 键
- 一些字符的名字: `plus` (`+`)、`multiply`、`asterisk`、`star` (`*`)、`minus` (`-`)、`divide` (`/`)、`period` (`.`)、`comma` (`,`); 它们是主键盘上的键, 不是小键盘上的
- 小键盘: `Numpad0` … `Numpad9`、`NumpadAdd`、`NumpadSubtract`、`NumpadMultiply`、`NumpadDivide`、`NumpadDecimal`、`NumpadEnter`
- 其他键用 DOM 的 `KeyboardEvent.code` 名, 比如 `KeyA`、`Digit8`、`Minus`、`ArrowUp`、`CapsLock`、`ShiftRight`

整个参数在按下任何键之前先检查: 有不认识的键就失败, 报 `unknown key: …`, 什么都不按. 空格这个字符写 `space` (空格用来隔开组合键). 要输入文字, 改用 `type`.

### query

`inspect` 列出用户看得到、用得了的东西. `query` 用 CSS 选择器找元素, 不管它们显示没显示, 并给每个一个 ref, 所以它够得到 `inspect` 不列的东西: `display: none` 的元素, 滚出视野的元素, 以及自己没有角色、名字或值的元素 (一个普通的 `<div>`; `inspect` 把它里面的东西列在它的位置上).

```sh
$ acdev query 'form input[type=email]'
1 in w1:
- textbox "Email": "" [w1.20] <input>

$ acdev query '[data-testid="menu"] li'
2 in w1:
- generic "Rename" [w1.25] <li> [hidden]
- generic "Delete" [w1.26] <li> [hidden]

$ acdev query button
4 in w1:
- button "Save" [focused] [w1.21] <button>
- button "Undo" [transparent] [w1.10] <button> [hidden]
- button [invisible] [w1.24] <button> [hidden]
- button "Load more" [w1.11] <button>

$ acdev query nav
acdev: nothing in w1 matches "nav"
```

每一行是元素的角色、名字、值、标题的级别、状态和 ref, 和 `inspect` 打出的完全一样 (`- heading "Notes" [level=1] [w1.16] <h1>`), 然后是它的标签. 标签后面的 `[hidden]` 标出看不见的元素: 它没有尺寸, 或者是 `display: none`、被 `visibility` 隐藏, 或者透明, 或者它的窗口最小化了. `transparent` 和 `invisible` 这两个标记就是 `inspect --all` 给的那两个: 透明的元素仍然接得到点击, 对用户来说也是这样; `invisible` 或 `display: none` 的元素, 在页面把它显示出来之前, `act` 都回 `the element is not displayed`. 判断不出角色的元素列成 `generic`; 标签说明它是什么.

这些 ref 和 `inspect` 给的一样, 可以交给 `act`: `acdev act w1.20 type "me@example.com"`. `query` 在焦点窗口里找; `--window w2` 换一个窗口, `--ref w1.6` 只在那个元素下面找, `--limit N` 最多列出 N 个元素 (1 到 3000, 默认 600; 第一行数的仍然是全部). 什么都没匹配到时, 它在 stderr 上说明 (`acdev: nothing in w1 matches "nav"`), 退出码是 2; 否则是 0.

### 样式和布局

要看样式和盒子, 用 `eval` 问页面 (或用 [DevTools](#devtools) 的 Elements 面板). `getComputedStyle` 给出页面经过 CSS 层叠之后用的值, `getBoundingClientRect` 给出元素的盒子, 单位是页面的 CSS 像素:

```sh
acdev eval notes "getComputedStyle(document.querySelector('h1')).color"
acdev eval notes "(({ display, fontSize, margin }) => ({ display, fontSize, margin }))(getComputedStyle(document.querySelector('.card')))"
acdev eval notes "(({ x, y, width, height }) => ({ x, y, width, height }))(document.querySelector('.card').getBoundingClientRect())"
```

像上面这样把要的属性复制进一个普通对象, JSON 结果里才有它们. 代码里只有单引号, 所以在 sh、PowerShell 和 cmd 里写法都一样 (见 [eval](#eval)). 要看东西是不是画在了你预期的地方, 用 `acdev shot` 截图; 要找 `inspect` 不列的元素 (没有尺寸、`display: none`), 用 `acdev query`.

### console 和 network

```sh
acdev console --level errors --follow
acdev network --failed
```

`--level` 是 `log` `info` `warn` `error` `debug`, 或 `errors` (`console.error` 加未捕获的错误). `--follow` 持续输出新的.

页面里的 `fetch` 以 `TypeError: Failed to fetch` reject 时, `acdev network --failed` 里那个请求的一行会说明原因 (CORS 规则、解析不了的名字、被拒绝的连接):

```sh
$ acdev network --failed
   1 GET    ERR https://nonexistent.invalid/  (fetch 158 ms; Failed to connect to host: Failed resolving hostname: failed to lookup address information: nodename nor servname provided, or not known) notes#1048576
```

页面重载后条目还留着, 所以改动之前的错误仍然会列出来. 第一列是条目的编号. `--since reload` 只列 `acdev dev` 最近一次重建并重载之后的条目 (还没重载过就是全部); `--since N` 列第 `N` 条和之后的. 页面自己做的重载 (`location.reload()`) 不算.

```sh
acdev console --level errors --since reload
```

每种最多留最近 5000 条.

## DevTools

`acdev devtools [web]` 给会话里的一张页面打开 Chrome 或 Edge (Linux 上也可以是 Chromium) 的 DevTools: Elements、Console、Network, 以及能下断点的 Sources.

```sh
acdev devtools            # 焦点所在的页面
acdev devtools notes      # web 名、应用 id、desktop 或窗口标题
acdev devtools services   # 桌面的服务 (或按名字指定一个服务)
```

它在 stdout 上打出 DevTools 的地址, 在 stderr 上打出 `acdev: opened DevTools for <page> in <browser>`. 对一张 DevTools 已经开着的页面再要一次, 它改为把 DevTools 拿到最前面 (`acdev: brought DevTools for <page> to the front in <browser>`). 在 `acdev dev` 的宿主窗口里按 F12, 对那个窗口里的页面做的是同一件事; 见 [acdev dev](https://docs.dopame.ai/zh/guide/dev.md#devtools).

浏览器用的是 acdev 自己的一份 profile, 不是你平时用的那份. `ACDEV_BROWSER` 指定另一个浏览器 (它的路径). 没有 Chrome 或 Edge, 或者设了 `ACDEV_BROWSER=none` 时, 什么都不打开: 把打出的地址贴进这台机器上 Chrome 或 Edge 的地址栏.

Elements 显示元素树、计算后的样式和盒模型, 都是只读的. 它不列出匹配一个元素的 CSS 规则 (只列它的内联样式); 改样式要从页面代码或 Console 里改.

## 没有显示器

在没有显示器的机器上, 比如经 ssh 连上的服务器, 用 `acdev dev --headless` 起会话. Linux 上不带它的 `acdev dev` 在 `WAYLAND_DISPLAY` 和 `DISPLAY` 都没设时马上停下, 并说要加上 `--headless`; 见 [acdev dev](https://docs.dopame.ai/zh/guide/dev.md). 本页的每个命令在 headless 会话里都一样能用:

```sh
acdev dev --headless &
acdev inspect          # 窗口和焦点窗口的元素, 文字形式
acdev shot notes       # ./notes.png
acdev screen           # ./screen.png, 所有窗口合在一起
```

headless 会话里没有选择器对话框: 页面打开的文件夹、文件或保存选择器, 除非事先回答过, 否则会失败, 页面看到的是被取消了. 在测试里用 `chooseFolder`、`chooseFiles` 或 `chooseSaveFile` 回答 ([端到端测试](https://docs.dopame.ai/zh/guide/testing.md#网络文件选择器剪贴板)), agent 用 MCP 工具 `choose_folder`、`choose_files` 和 `choose_save_file` ([MCP](https://docs.dopame.ai/zh/guide/mcp.md)), 或者在命令行里用 `acdev choose folder ~/Notes`、`acdev choose open a.md b.md` 或 `acdev choose save out.md` (`--cancel` 是取消). `acdev drop <web> <file...>` 把文件拖放到页面上, 和从文件管理器拖进来一样. 会话的输出会点出缺的是哪个回答: `no folder chooser without a host window (ACDE_HEADLESS): answer it beforehand with the MCP tool choose_folder or acde.chooseFolder() in a test`. headless 会话还有自己的剪贴板, 也没有摄像头和麦克风的对话框 (见下文).

## 摄像头和麦克风

应用声明的能力不问就给, 摄像头、麦克风和空闲检测 (`idleDetection`) 除外. 页面第一次要用其中一样时 (`getUserMedia`、`IdleDetector.requestPermission()`) 才问用户, 这次调用等着回答. 只跑一个应用的会话里, 宿主窗口在 Windows 上用一个对话框问, 在 macOS 上用一个带 `Don't Allow` 和 `Allow` 的 sheet 问, 在 Linux 上用一条带同样两个按钮的通知问 (在桌面的通知服务显示按钮的地方). 别的情况下, 以及 headless 会话里, 没有对话框, 所以从命令行回答:

```sh
$ acdev permissions
pending:
  1  recorder  microphone  (request)
decisions: none

$ acdev allow
allowed recorder microphone (prompt 1)
```

不带参数时, `acdev allow` 和 `acdev deny` 回答唯一在等的那个提示. 有几个在等时, 它们一个都不回答, 把它们列出来; 用 id 指定一个 (`acdev allow 2`), 或用应用和能力指定 (`acdev allow recorder microphone`), 或用 `--all` 全部回答.

决定按应用保存 (在 `$XDG_CONFIG_HOME/acde/permissions.json` 里), 所以不会再问用户. 回答是用户的决定: 替别人运行这些命令时, 只允许他们要求过或同意过的, 并告诉他们你允许了什么. `acdev revoke <应用> <能力>` 去掉一个决定, 于是应用下次要用时会再问. 被拒绝或收回的能力让 `getUserMedia` 以 `NotAllowedError` reject, 和浏览器里一样.

## 出错

命令失败时打 `acdev: <原因>`, 退出码 1. 会话已经退出时会说 `acdev dev <pid> is gone`. 什么都没找到的 `inspect --find` 和 `query` 不算失败; 它们的退出码是 2.
