# @desklink/axi 中文文档

规范地址：https://npmcn.com/package/%40desklink/axi/

版本：0\.5\.17
npm 元数据更新时间：2026-10-31T14:00:43.752Z
中文译文更新时间：2026-11-13T03:50:33.371Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40desklink/axi
原文对照：https://npmcn.com/package/%40desklink/axi/?lang=original
项目主页：https://github.com/umeranjum17/desklink#readme
源码仓库：https://github.com/umeranjum17/desklink

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：152 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2026-09-30T10:38:35.332Z
- 最新版本发布：2026-10-31T14:00:43.412Z
- 近 30 天下载量：2366（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

读取并驱动桌面链接的代理化 CLI

## 安装

```sh
npm install @desklink/axi
```

也可以使用：`pnpm add @desklink/axi`、`yarn add @desklink/axi`、`bun add @desklink/axi`

## README

# @ desklink/ axi

[![npm](https://img.shields.io/npm/v/@desklink/axi?style=flat)](https://www.npmjs.com/package/@desklink/axi) [![CI](https://img.shields.io/github/actions/workflow/status/umeranjum17/desklink/ci.yml?style=flat&branch=main)](https://github.com/umeranjum17/desklink/actions/workflows/ci.yml) [![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-666?style=flat)](https://github.com/umeranjum17/desklink/blob/main/LICENSE) ![Linux and macOS (preview)](https://img.shields.io/badge/Linux%20%7C%20macOS%20%28preview%29-111?style=flat)

**查看并驱动代理服务器的活桌面:文本先行,按请求显示像素.**  
一个桌面CLI,用于桌面链接引擎上的编码代理. 它用OCR文本进行回答,校对以点击并更改区域,并且仅在被问到时返回一个图像裁剪,所以一个转弯会花费文本符号而不是截图.

## 安装

从 npm 安装; 上面的徽章跟踪注册版本 :

```sh
npm install -g @desklink/axi
```

`desklink-axi --version` 编辑 `--help` 页眉显示已安装的版本,包括任何dev/release后缀.

或者从寄存器根建立 `npm install && npm run build`。 。 。 . 删除已复制 `*.tsbuildinfo` 在重建被移动的工作树之前. 引擎通过 `@desklink/host`; 见其 [安装指南](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/README.md#install-and-run) 用于支持平台和 [macOS 设置](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/README.md#macos-preview)。 。 。 . 设定 `DESKLINK_AXI_ENGINE` 用于匹配源构建。 将新AXI指向0.3.x引擎的超接功能不支持;主机和引擎版本必须匹配.

Linux 桌面 AXI 预览有 macOS 。 它运行每个会话的私人桥, 抓取只读帧通过 `@desklink/host` 协议 v3, 仅通过 WebRTC 发送输入 `control` 频道. 桥的Unix套接字住在 `$XDG_RUNTIME_DIR/desklink-axi` (或OS临时目录) `DESKLINK_AXI_SESSION` 选择一个孤立的套接字。 它打开一个单独的引擎会话; 在别人控制时不要驱动桌面.

对于macOS源先决条件,签名和许可归属,遵循 [主机设置指南](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/README.md#macos-preview)1\. 通过其经签字的当地装置启动第XI号决议 `open -n /absolute/DesklinkHost.app --args axi-bridge /absolute/path/to/packages/axi/bin/desklink-axi.js` 从登录的Mac会话。 OCR 需要可选选项 `tesseract` 可执行文件( e)`brew install tesseract`, (中文(简体) ), `sudo pacman -S tesseract` 或者说 `sudo apt install tesseract-ocr`; 在macOS AXI上,当发射服务公司从PATH中省略出Homebrew的标准安装路径时,也会找到Homebrew的标准安装路径. `look` 工作没有它.

```
desklink-axi start --source x11 --display :97
desklink-axi screen --query "Budget"
desklink-axi tree --query "Save"
desklink-axi type "hello" --into @a3.10
desklink-axi click @a3.7
desklink-axi marks
desklink-axi click 100,120
desklink-axi type "hello"
desklink-axi batch '[{"verb":"snapshot","name":"ui"},{"verb":"click","args":["@ui.2"]},{"verb":"assert","args":["Saved"]}]'
desklink-axi diff
desklink-axi look @r1
desklink-axi stop
```

`start --cursor hidden` 选择为无光标捕获; 省略已有的行为 。 使用 `desklink-axi cursor` 排出源坐标光标样本(`x`, (中文(简体) ), `y`, (中文(简体) ), `visible`, (中文(简体) ), `timestamp_us`附加时 `hotspot` 作曲者在现场报告时; `dropped:N` 报告更古老的样本 在它的一万个样本缓冲器填满后被覆盖 在Wayland,当没有位置时,隐藏的会话仍然在运行,并说为什么在 `cursor.limitation`; 见 [光标协议](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/docs/PROTOCOL.md#cursor-free-capture)。 。 。 .

`health` 报告捕捉状态,最新帧序列, 和流停止 理由没有OCR. `start` 允许其同一用户配对的消费者使用所有可用的访问; Linux 使用门户, 除非 `--source x11 --display :N` ,而macOS使用主显示,除非 `--source display --display <id>` 给出。 门户可以要求桌面同意提示;其单用途还原符被保存在其中 `$XDG_STATE_HOME/desklink-axi/<session>.portal-token` (否则) `~/.local/state/desklink-axi/<session>.portal-token`),在每次赠款后,在解剖学上取而代之的是0600模式; `<session>` 实值 `DESKLINK_AXI_SESSION`,与会话的套接字和浏览器状态使用的名称相同,因此两条道从不将对方的赠款交给自己的消费者. 设定 `DESKLINK_AXI_RESTORE_TOKEN_FILE` 用不同的路径。 macOS 屏幕记录和无障碍属于启动桥和其引擎子的应用程序. 不要在别人的展出上不小心运行它。 输入和剪贴板不需要应用程序授权; 不可用的OS后端每个动作失败 。 遗产 `start --control` 被接受和忽略。 见 [剪贴板协议](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/docs/PROTOCOL.md#clipboard-over-the-local-protocol) 用于X11目标、转移限制和选择寿命. `stop` 释放有投入。 确认的行动 `input: applied` 立即,不等待一个框架。 每项行动( A)`click`, (中文(简体) ), `type`, (中文(简体) ), `press`, (中文(简体) ), `scroll`, (中文(简体) ), `drag`接受 `--wait settle|change|none|<milliseconds>`; 应用输入返回后的框架超时 `input: applied; frame: timed out` 成功状态. `batch` jSON 数组为 1 - 30 `[verb, ...args]` 步骤(点击/类型/press/scroll/wait/snapshot/sert/tree/marks),按一次套接字往返的顺序运行,在第一个失败的步骤上停下来,并返回一个紧凑的每步结果。 OCR refs 仅在文本和位置仍然匹配新收件时才能存活到推进帧数;需要移动或模糊的文本 `screen --query`。 。 。 . `screen --query` 重用目标作物的先前匹配文本位置,然后返回完整的OCR,并报告估计文本符号。 开始 `screen --query` 或者说 `--region` 在此之前 `--full`。对于网页,如果有DOM/浏览器自动化功能,则倾向于DOM/浏览器自动化;AXI是用于本地应用程序或全桌面任务. `wait change` 财务报告和审定财务报表 `wait settle` 而不是投票. `diff` \* 报告一再单独改变区域,作为 `animating`· ; `diff --include-animating` 将它们包括在普通变化中. `look` 写一个PNG收成. `--help` 列出命令及其旗帜。 错误结构化, CLI 不提示 . 引导不输入的人,使用 `desklink-axi point 400,300 --label "Here" --timeout 3000`,或 `desklink-axi point --clear`见 [主机协议参考](https://github.com/umeranjum17/desklink/blob/main/packages/desktop-host/docs/PROTOCOL.md#point-on-the-host-desktop) 用于支持源、坐标和限制.

## 浏览器道( opt- in, 仅循环)

对于网页,浏览器道通过语义控制 [剧作家核心](https://www.npmjs.com/package/playwright-core) 超过 CDP; 桌面道保留用于本地应用程序和全桌面任务 。 任何内容都没有隐含地附上:

```
desklink-axi browser attach --cdp 127.0.0.1:9222   # a Chromium YOU started with --remote-debugging-port (loopback only)
desklink-axi browser launch --profile /tmp/task-profile   # or: isolated task-owned Chromium, debug port on loopback only
desklink-axi browser tabs          # 'selected' = this lane's page, 'front' = the browser's actual activated tab
desklink-axi browser snapshot      # compact accessibility snapshot with [ref=eN] elements; no screenshots
desklink-axi browser click @e12 / fill @e5 "text" / upload @e9 /tmp/report.pdf / press Enter
desklink-axi browser select 1 / open <url> / navigate <url> / close 1 / detach
```

非落下端点被拒绝; `launch` 打开 `$DISPLAY` (X11)所以它从不遵循 `WAYLAND_DISPLAY` 到另一个桌面,以及 `--arg <chromium flag>` (可重复)通过诸如 `--arg=--window-size=1280,640`。快照参考器被重新生成到每个命令,并被拒绝为 `stale-ref` 当页面改变. `upload` 只设置文件于 `<input type=file>`; 对于OS级对话框, 它返回 `not-supported` 并命名桌面车道(`desklink-axi click/type`),这也是真实的本土-对话导航的路线——DOM上传不等于完成本土文件对话框. `detach` 仅在该道启动时停止浏览器; 通过 `--profile` 目录被保存,一个车道创建的临时配置被删除.

在 Linux 上,一个行道启动浏览器所记录的 PID 和启动时间必须匹配 在连接或清理之前。 旧版本未设置的缓存会话 拒绝录制开始时间; 使用新鲜 `DESKLINK_AXI_SESSION` 和简介. 清理验证辅助器 PID/启动时间对接私人发射标记 在发出信号之前 所附浏览器 `--cdp` 仍为呼叫者所有.

## 批量结果

`batch` 步骤是 `[verb, ...args]` 数组或 `{verb, args?, name?, wait?}` 有动词的对象 `click, type, press, scroll, wait, snapshot, assert, tree, marks`。一个命名的快照步骤会绑定其OCR项目,以便以后的步骤能够瞄准 `@name.n`· ; `assert` 步骤使成功取决于所观察到的屏幕文本;每行分开 `input: applied` (运输确认) `effect: change observed | none within timeout`,脚印上说 `effects: asserted[n]` 或者说 `effects: unverified (input acknowledgements only)` ——输入确认绝不是经过核实的结果,因此错误的焦点打字或不点击会失败批次而不是报告成功.

## 证据和测量

带有任务所建引擎的寄存器根( R)`DESKLINK_AXI_ENGINE`继续 Linux, 跟着 [私人实验室指导](https://github.com/umeranjum17/desklink/blob/main/README.md#develop)数字 :

-   `node packages/axi/test/smoke.mjs` ——清洁树木重建主机+axi,然后 `batch` 财务报告和审定财务报表 `click` (b) 声称没有属于任务所属的幸存者.
-   `node packages/axi/test/flow.mjs` – 完整的桌面证明(帧/损坏,点坐标/出站/清空而无指针或焦点变化,点击通过,输入,和弦,批量结果,注入失败清理).
-   `node packages/axi/test/browser-flow.mjs` ——通过浏览器道的开口/出道/出道/出道-出道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-取道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道-道--道-道-----道-.
-   `node packages/axi/test/bench.mjs [runs]` – 比较 p50/p95( 默认 20 运行于 3 warums 后) 浏览器道对 AXI 倒置于 open/form/tabs/ native 固定装置之上; text-token 代理 `ceil(stdout chars/4)`一个代理,而不是一个象征性的.

以一台由任务拥有的Chromium 151 (Xvfb) 所测量的单相机1280x720 Xvfb`--window-position=0,0 --window-size=1280,640`,在3次热身后每任务20次测量跑道,每跑道CLI墙壁时间

| 任务 | 车道 | p50 ms (英语) | p95 分钟 | 呼叫/运行 | 重试 | 文本脚本代理/运行 | 失败 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 本地输入 | 轴 | 页:1 | 68国 | 1.0 国家 | 0 个 | 22个 | 第1/23号决议 |
| 打开 + 验证标题 | 浏览器 | 532个 | 558 (韩语) | 2.0 数据 | 0 个 | 149个 | 0/23 (英语) |
| 打开 + 验证标题 | 轴 | 6043 (英语) | 第8659号 | 2.0 数据 | 0 个 | 107国 | 0/23 (英语) |
| 表格填充+保存+验证 | 浏览器 | 1735 (英语) | 6082号 | 4.0 (韩语) | 0 个 | 290国 | 0/23 (英语) |
| 两个标签同时读取 | 浏览器 | 第5176条 | 6007 (英语) | 17.0 (中文(简体) ) | 0 个 | 900个 | 0/23 (英语) |
| 表格填充+保存+验证 | 轴 | 未完成 —— OCR 单词目标步骤 (`--into Name`, (中文(简体) ), `click Save`板凳序列呈片状;孤立地通过同样的台阶,批/装机在流.mjs中得到证明。 后继:稳定后再进行再测量. |  |  |  |  |  |
| 两个标签同时读取 | 轴 | 未完成 —— 弹出- 链接点击器上相同的 OCR 字- 目标限制; 孤立工作, 尚未在被测量的序列中进行. |  |  |  |  |  |

浏览器道用紧凑的文本快照完成了每条网络任务23/23;桌面道的OCR倒置对本土证明保持可靠,并在小网络文本上降解,与2026-09-27计算机使用基准中的双行道排名相匹配.

对于一个远程签名的Mac桥,启动一次 **在许可的应用程序内**,然后将其Unix套接字转发到一个持续的SSH连接上: `ssh -N -L "$LOCAL_RUNTIME/desklink-axi/default.sock:$REMOTE_RUNTIME/desklink-axi/default.sock" mac-host`设置 `XDG_RUNTIME_DIR=$LOCAL_RUNTIME` 客户端( 创建) `$LOCAL_RUNTIME/desklink-axi` 模式 0700,先运行 `desklink-axi screen`, (中文(简体) ), `batch`等当地. SSH 登录不启动引擎, 转发的套接字授权控制: 使用私有目录, 完成后关闭 SSH 。 不运行本地 `start` 对接转发的套接字。 切换和重签每个运行的可执行文件 。 使用相同的密钥更新整个应用程序的现有路径 `packages/desktop-host/release/install-mac-app.sh`;更新后核实赠款.

`desklink-axi setup hooks` 加一个克劳德 `SessionStart` 钩入 `.claude/settings.local.json` ;它不开始抓取.

为孤立的融合证明运行 `DESKLINK_AXI_ENGINE=/path/to/engine CARGO_TARGET_DIR=/tmp/task-owned-target node packages/axi/test/flow.mjs` 从寄存器根。 它通过精确的PID发射并杀死自己的Xvfb进程. `test/a11y-flow.mjs` 是可访问性+标记证明:它也开始一个私有的D-Bus会话总线,一个私有的AT-SPI总线,以及一个GTK3固定应用程序(所有任务拥有,私人 `XDG_RUNTIME_DIR`),声称语义-ref驱动窗体控件和文件对话框,每个命令的打印p50/p95 `--measure 20`它跳过自己,当 `busctl`编号 :`dbus-daemon`编号 :`at-spi2-core`/GTK缺席,从来不会触碰用户的无障碍巴士.

对于200个字的OCR和查询证明,添加 `DESKLINK_OCR_SCALE=1` 或者说 `DESKLINK_OCR_SCALE=1.5` 财务报告和审定财务报表 `DESKLINK_OCR_EVIDENCE=/absolute/output/directory` 到那个命令。 后者采用1.5级的私人3840×2160显示. 每次运行都会保存地面真相,OCR,单词diff,截图和每个可见标签查询. 添加 `DESKLINK_OCR_UPDATE_README=1` 到 1x 运行以直接以 CLI 输出取代 README 记录;没有记录行是手编辑的。 使用 `DESKLINK_OCR_SHOWCASE_ONLY=1` 与 1x 命令重放编辑并重出原样,而不重复标签-query 检查。 这个证据需要铬和宇宙魔方 2.5 s 的输入内读取下个框(多至1.3 s后)并画出细细的柱子相闪烁在二者之间,所以文本护栏不读作后缀 `|`永不切入窗口的护身符仍然可以读取。 全帧OCR在宇宙魔方之前的软件上提升了3x,因此一个3840x2160帧的瞬间需要11520x6480(~74.6M px,~298MB RGBA)缓冲器外加PNG编码外加放大图像上的宇宙魔方.

要检查 CLI 对 AXI 规格, 运行 `axi-axi validate "node bin/desklink-axi.js" --dir .` 从 `packages/axi`。 。 。 .

在1280x720 Xvfb客户端上测量: `diff → click 100,100 → look @r1 → type abc` 返回 79+ 79+ 39+ 30= **227个文本符号** (单位:千美元)`@anthropic-ai/tokenizer` 0.0.4),外加~5个令牌,用于64×64作物. 四张完整截图将花费~4×1,229= **4 916个图像符号** 在同一公布的宽度x高/750估计值(~21x相差)下。 这是一个短暂的合成任务,而不是生产-工作量基准;表示器是遗留的,所以绝对数是相近的.

## 无障碍树`tree`)——Linux AT-SPI (英语)

`tree` 在 D- Bus 上读取桌面的 AT- SPI 访问树, 返回绑定的 TON 行 `ref,role,name,value,x,y,w,h,states`。读取和输入动作共享相同的对齐会话。 参考文献为生成标记( Q)`@a<gen>.<n>`),在较新的快照中保持可用,并在使用时重新验证:其角色、名称或屏幕范围改变或对象消失的参考文献返回 `stale-ref` 而不是装瞎.

-   能力探测器: 总线从 `AT_SPI_BUS_ADDRESS`,则 `org.a11y.Bus.GetAddress` 在会话总线。 无法获取 + 结构 `a11y-unavailable` 错误; 每个其它命令继续工作 。 macOS AX 是 **未执行** 并贴上这样的标签.
-   值:文本和值部件在 `value` 栏(Text/Value 接口),所以可以不使用像素来验证一个已输入的条目.
-   国家包括: `enabled`, (中文(简体) ), `showing`, (中文(简体) ), `focused`, (中文(简体) ), `editable`, (中文(简体) ), `checked`; 对已禁用或隐藏的参考返回采取行动 `not-actionable`。 。 。 .
-   `click @a<gen>.<n>` 执行部件自己的 AT- SPI 动作( U)`input: applied (atspi action "Click")`); 没有动作接口的节点会回落到其中心点击的坐标上(`coordinate fallback`) (中文(简体) ). `type "text" --into @a<n>` 首先抓取AT-SPI焦点(`atspi focus`; 工具包拒绝时坐标回落)。 原始截图/坐标/OCR路径不变.
-   `tree --query <words>` 按名称/作用/值过滤;输出范围为40行,除非 `--full`· ; `--fields` 选择列. `tree` 财务报告和审定财务报表 `marks` 可用作 `batch` 步骤.

测量事实(私营Xvfb + 私营公共汽车,2026年9月); `test/a11y-flow.mjs`:

-   GTK3 (3.24, atk-bridge):完全暴露. 已命名的角色, 边框, 状态, 值, 和行动全部在 D- Bus 上工作; 语义点击会带真实效果( fixture- 校验文件导出) 。 期间a `GtkDialog.run()` 模式循环开始, atk- bridge 答案 **没有** AT-SPI方法调用(测量了25分超时)——对话框必须读取后才能打开或非模式显示.
-   Qt6 (6.11, QtAtSpi): 用重复的注册条目在 a11y 总线上注册应用程序(一个应用程序有3个根,两个共享一个总线名称),其命名的形式控件可见于行走 (3/3 in the fixture); 一些根拒绝 `GetChildCount` 方法(只有财产),行走可以容忍。 将每个工具Kit角色拼写("按下按钮"与"按钮")处理,并复制根作为正常输入.
-   Wayland/portal:11y总线是显示-protocol独立的,但通过compositor的门户/permission路径曝光是 **未测量** 在这项任务中(没有拥有Wayland固定); 范围之前依赖它.
-   测量出20多条暖跑道(1280x720 Xvfb,GTK3固定道,私人公交): `tree --full` p50 472 ms / p95 573 ms,语义学 `click` p50 69 ms / p95 85 ms, (英语), `type --into` p50 69 ms / p95 83 ms, (英语), `marks` p50 657 ms / p95 774 ms, 0 stale-ref retries 横跨整个套房. 每个 `tree`编号 :`marks` 行走是受约束的(~100-400受约束的busctl产卵,每个水平平行).

## 标记( E)`marks`)——编号为可视倒置

`marks` 将数字框覆盖在可操作候选人的作物上——AT-SPI节点并加上OCR文本——并返回图像路径和一个紧凑 `mark,ref,label,role` 地图。 从已编号的图像中选择一个控件, 然后按其可读性行事; 没有像素猜测 。 成本线报告作物的尺寸和估计的图像符号(`dimensions=1280x720 cost: ~1229 tokens`) (中文(简体) ). 地图中的折射器会失效 就像 `tree` 参考:已更改的几何或内容返回 `stale-ref` 在使用时. `--region x,y,w,h` 扩大作物范围; `--out <path>` 选择文物路径(默认写在会话旁边)。 覆盖图是纯粹的缓冲操作( P)`src/marks.ts`没有捆绑的探测器.

## 常见问题

### @desklink/axi 是什么？

读取并驱动桌面链接的代理化 CLI

### 如何安装 @desklink/axi？

在项目目录运行 npm install @desklink/axi，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 desklink-axi，可以用 npx desklink-axi 直接运行。

### @desklink/axi 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/desklink\_\_axi 是否存在。

### @desklink/axi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @desklink/axi 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @desklink/axi 可以商用吗？

@desklink/axi 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @desklink/axi 的下载量有多少？

根据 npm 官方下载统计，@desklink/axi 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,366 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @desklink/axi 还在维护吗？

最新版本 0\.5\.17 发布于 2026/10/31（13 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。