调试工具
一组命令连到正在跑的 acdev dev 开发会话上, 能看页面、执行代码、截图、点按钮. acdev devtools 还能给一张页面打开 Chrome 或 Edge 的 DevTools, 见 DevTools. 在另一个终端里运行:
acdev websNAME KIND APP WINDOW TITLEdesktop desktop - 0 My Desktopnotes#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 |
结束会话, 见 结束 |
acdev devtools [web] |
给一张页面打开 Chrome 或 Edge 的 DevTools, 见 DevTools |
一个 web 就是一张页面: 桌面页, 或一个应用窗口里的页面 (每个窗口一张). <web> 可以是 acdev webs 列出的 web 名 (notes#1048576)、应用 id (那个应用的第一个窗口) 或 desktop. 在 Dopame OS 客户机里, 1.5 秒内没有回答的页面 (它的进程停了或在忙) 照样列出, 标题是 (not answering); 其余页面照常列出.
eval
eval 一节的链接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 没有单引号字符串: 把参数放进双引号里, 里面的双引号写成
\"(下面的第二行).
acdev eval notes 'document.querySelector(\"#x\").textContent'acdev eval notes "document.querySelector(\"#x\").textContent"代码里只有单引号时, 三种 shell 里写法都一样; 从 stdin 传代码则不用管这个问题 (下面是 PowerShell 的写法):
acdev eval notes "document.querySelector('#x').textContent"'document.querySelector("#x").textContent' | acdev eval notes -任何带双引号的参数都是这样, 比如 act ... type.
inspect 和 act
inspect 和 act 一节的链接inspect 给每个元素一个 ref (元素编号), 比如 w1.18 (窗口 w1 里的第 18 号元素); 把它交给 act.
$ 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 clickclicked 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 一次.
单独跑的应用在标题栏上显示窗口菜单 (见 窗口), 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 把它拿回来. 在跑桌面的会话里:
$ acdev act w1 minimizew1 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 clickacdev: act w1.10: w1 is minimized; act restore on it first
$ acdev act w1 restorew1 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 和离它最近的这样一个祖先; 没有这样的祖先时, 后面什么都不跟:
$ acdev inspect --find milkw1 notes "Notes":- text "Buy milk" [w1.22] in list "Saved notes" [w1.7]
$ acdev inspect --find savew1 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
query 一节的链接inspect 列出用户看得到、用得了的东西. query 用 CSS 选择器找元素, 不管它们显示没显示, 并给每个一个 ref, 所以它够得到 inspect 不列的东西: display: none 的元素, 滚出视野的元素, 以及自己没有角色、名字或值的元素 (一个普通的 <div>; inspect 把它里面的东西列在它的位置上).
$ 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 button4 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 navacdev: 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 的 Elements 面板). getComputedStyle 给出页面经过 CSS 层叠之后用的值, getBoundingClientRect 给出元素的盒子, 单位是页面的 CSS 像素:
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). 要看东西是不是画在了你预期的地方, 用 acdev shot 截图; 要找 inspect 不列的元素 (没有尺寸、display: none), 用 acdev query.
console 和 network
console 和 network 一节的链接acdev console --level errors --followacdev network --failed--level 是 log info warn error debug, 或 errors (console.error 加未捕获的错误). --follow 持续输出新的.
页面里的 fetch 以 TypeError: Failed to fetch reject 时, acdev network --failed 里那个请求的一行会说明原因 (CORS 规则、解析不了的名字、被拒绝的连接):
$ 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()) 不算.
acdev console --level errors --since reload每种最多留最近 5000 条.
DevTools
DevTools 一节的链接acdev devtools [web] 给会话里的一张页面打开 Chrome 或 Edge (Linux 上也可以是 Chromium) 的 DevTools: Elements、Console、Network, 以及能下断点的 Sources.
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.
浏览器用的是 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. 本页的每个命令在 headless 会话里都一样能用:
acdev dev --headless &acdev inspect # 窗口和焦点窗口的元素, 文字形式acdev shot notes # ./notes.pngacdev screen # ./screen.png, 所有窗口合在一起headless 会话里没有选择器对话框: 页面打开的文件夹、文件或保存选择器, 除非事先回答过, 否则会失败, 页面看到的是被取消了. 在测试里用 chooseFolder、chooseFiles 或 chooseSaveFile 回答 (端到端测试), agent 用 MCP 工具 choose_folder、choose_files 和 choose_save_file (MCP), 或者在命令行里用 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 会话里, 没有对话框, 所以从命令行回答:
$ acdev permissionspending: 1 recorder microphone (request)decisions: none
$ acdev allowallowed 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.