2026/9/20 14:21:40
FEATURED · 精选文章 
pi-computer-use strict AX模式阻止操作headless下的应对策略【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-usepi-computer-use 是一个让 AI 智能体操作 macOS、Windows、Linux 桌面应用的 Pi 扩展它能看到窗口、理解按钮和文本并执行点击、输入、滚动等操作。开启headless: true即 strict AX 严格无障碍模式后智能体被限制在后台语义操作内——任何依赖原始鼠标坐标、全局键盘或抢占焦点的动作都会被直接拦截。本文讲清楚 strict AX 模式到底阻止了什么、为什么这样设计以及 5 个经过源码验证的应对策略 什么是 strict AX 模式headless: trueheadless是 pi-computer-use 的配置项默认为false。设为true后所有动作必须保持在后台执行以下能力被明确阻止见 docs/configuration.md操作类型headless: truestrict AXheadless: false默认按元素 ref 语义点击 / 按键✅ 允许✅ 允许可访问文本框内容替换setText✅ 允许✅ 允许按图像坐标点击原始指针事件❌ 阻止✅ 允许原始键盘事件❌ 阻止✅ 允许可前台重试强制窗口获得焦点EWMH❌ 阻止✅ 仅 X11代理光标覆盖层agent cursor❌ 强制抑制✅ 仅 macOS实现上strict 模式会把投递策略锁定为ax_onlysrc/bridge.ts 中headless ? ax_only : background并且失败后不会自动升级到前台重试src/actions.ts 中canRetryInForeground对 headless 直接返回false。为什么操作会被阻止语义优先、失败封闭strict AX 模式的设计原则是优先使用平台的无障碍语义通道拿不到语义结果就失败而不是悄悄退回到物理输入fail closed。原因很直接——物理输入是全局的原始指针/键盘事件会移动你真正的鼠标、往你当前聚焦的应用里打字EWMH 强制焦点会改变你正在看的窗口这些行为在后台无人看管时可能干扰用户会话。各平台的语义通道macOS 用 AX、Windows 用 UIA、Linux 用 AT-SPI2。特别地在 Linux X11 上XTEST 物理输入和 EWMH 焦点只在非 headless 策略下可用headless: true或ax_only/background策略下辅助进程从不调用它们不支持的语义输入直接失败docs/linux.md。原生 Wayland 则始终是纯语义没有任何物理回退。 注意区分这里的headless是输入投递策略不是 Chromium 的--headless显示开关两者无关。操作被阻止时的 5 个应对策略官方排障文档对 Strict accessibility mode blocks an action 给出的核心建议是使用最新observe_ui结果中的 refs如果工作流确实需要原始事件就关闭 strict 模式docs/troubleshooting.md。具体可以按以下顺序操作策略一从坐标点击切换到元素 ref 操作这是最常见的触发原因模型想对pictureOnly节点或无无障碍元素的区域按图像坐标点击被 strict 模式拦截。解法是改用observe_ui返回的eN元素 ref用press、setText、click(ref)等语义动作{ action: press, ref: e12 }只要目标应用导出了无障碍接口按钮、文本框、菜单项等strict 模式下就能正常完成点击与输入完全不碰物理输入。策略二ref 或 stateId 过期时重新观察坐标和 ref 都属于最新一次观察到的状态。如果窗口尺寸变了、目标窗口变了、或捕获了新观察旧的坐标/ref 会失效写入还会因资源纪元epoch校验被拒绝。做法简单重新调用observe_ui拿到新的stateId再用新 ref 重试。策略三给操作加上 expect 后置条件strict 模式下事件送达不等于操作成功所以要把完成信号放进同一事务让智能体等待真正的 UI 变化{ actions: [{ action: press, ref: e12 }], expect: { text: Saved, timeoutMs: 3000 } }验证结果为verified/preexisting/failed三种之一应用吞掉了事件时会明确报didnt而不是给你虚假的成功。策略四确实需要原始输入时关闭 strict 模式有些工作流如没有无障碍接口的画布应用确实需要坐标点击或原始键盘。此时把 strict 模式关掉即可三个配置层级任选其一项目配置覆盖全局环境变量覆盖两者层级位置全局配置~/.pi/agent/extensions/pi-computer-use.json项目配置.pi/computer-use.json环境变量PI_COMPUTER_USE_HEADLESS0{ headless: false }在 Pi 里运行/computer-use可随时查看当前生效的配置及其来源docs/configuration.md。策略五确认目标应用支持语义Linux 的能力矩阵中多数操作是 Capability-gated——目标必须导出对应的 AT-SPI 接口docs/linux.md。如果应用本身不暴露无障碍接口strict 模式下没有任何投递路径此时要么换用支持更好的应用/接口要么按策略四关闭 strict 模式。如何检查与切换模式在 Pi 中输入/computer-use查看当前headless状态与来源修改项目级.pi/computer-use.json是推荐做法避免影响其他项目环境变量PI_COMPUTER_USE_HEADLESS1会禁止一切前台回退适合 CI 或无人值守会话配置解析逻辑见 src/config.ts。常见问题 ⚠️Qstrict 模式会阻止观察吗不会。observe_ui、search_ui、read_text、wait_for等只读/观察类工具完全不受影响strict 只约束写入类动作的投递方式。Q失败了为什么不能悄悄重试物理输入这是有意设计不确定结果的动作从不盲目重放strict 调用保持原子的批量事务语义docs/architecture.md。宁可明确失败让你重新观察也不冒干扰用户会话的风险。QLinux 上 strict 模式还能做什么AT-SPI 语义按压/点击、可编辑文本替换、文本读取与等待、窗口截图X11、以及受管浏览器页面的 CDP 操作——都可用被禁用的只有 XTEST 物理输入与 EWMH 强制焦点。一句话总结strict AX 模式阻止的不是能力而是不受控的全局副作用。把坐标换成 ref、把状态刷新到最新、把结果交给 expect 验证绝大多数被阻止的操作都能在 strict 模式下安全完成 【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pi-computer-use strict AX模式阻止操作：headless下的应对策略
pi-computer-use strict AX模式阻止操作headless下的应对策略【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-usepi-computer-use 是一个让 AI 智能体操作 macOS、Windows、Linux 桌面应用的 Pi 扩展它能看到窗口、理解按钮和文本并执行点击、输入、滚动等操作。开启headless: true即 strict AX 严格无障碍模式后智能体被限制在后台语义操作内——任何依赖原始鼠标坐标、全局键盘或抢占焦点的动作都会被直接拦截。本文讲清楚 strict AX 模式到底阻止了什么、为什么这样设计以及 5 个经过源码验证的应对策略 什么是 strict AX 模式headless: trueheadless是 pi-computer-use 的配置项默认为false。设为true后所有动作必须保持在后台执行以下能力被明确阻止见 docs/configuration.md操作类型headless: truestrict AXheadless: false默认按元素 ref 语义点击 / 按键✅ 允许✅ 允许可访问文本框内容替换setText✅ 允许✅ 允许按图像坐标点击原始指针事件❌ 阻止✅ 允许原始键盘事件❌ 阻止✅ 允许可前台重试强制窗口获得焦点EWMH❌ 阻止✅ 仅 X11代理光标覆盖层agent cursor❌ 强制抑制✅ 仅 macOS实现上strict 模式会把投递策略锁定为ax_onlysrc/bridge.ts 中headless ? ax_only : background并且失败后不会自动升级到前台重试src/actions.ts 中canRetryInForeground对 headless 直接返回false。为什么操作会被阻止语义优先、失败封闭strict AX 模式的设计原则是优先使用平台的无障碍语义通道拿不到语义结果就失败而不是悄悄退回到物理输入fail closed。原因很直接——物理输入是全局的原始指针/键盘事件会移动你真正的鼠标、往你当前聚焦的应用里打字EWMH 强制焦点会改变你正在看的窗口这些行为在后台无人看管时可能干扰用户会话。各平台的语义通道macOS 用 AX、Windows 用 UIA、Linux 用 AT-SPI2。特别地在 Linux X11 上XTEST 物理输入和 EWMH 焦点只在非 headless 策略下可用headless: true或ax_only/background策略下辅助进程从不调用它们不支持的语义输入直接失败docs/linux.md。原生 Wayland 则始终是纯语义没有任何物理回退。 注意区分这里的headless是输入投递策略不是 Chromium 的--headless显示开关两者无关。操作被阻止时的 5 个应对策略官方排障文档对 Strict accessibility mode blocks an action 给出的核心建议是使用最新observe_ui结果中的 refs如果工作流确实需要原始事件就关闭 strict 模式docs/troubleshooting.md。具体可以按以下顺序操作策略一从坐标点击切换到元素 ref 操作这是最常见的触发原因模型想对pictureOnly节点或无无障碍元素的区域按图像坐标点击被 strict 模式拦截。解法是改用observe_ui返回的eN元素 ref用press、setText、click(ref)等语义动作{ action: press, ref: e12 }只要目标应用导出了无障碍接口按钮、文本框、菜单项等strict 模式下就能正常完成点击与输入完全不碰物理输入。策略二ref 或 stateId 过期时重新观察坐标和 ref 都属于最新一次观察到的状态。如果窗口尺寸变了、目标窗口变了、或捕获了新观察旧的坐标/ref 会失效写入还会因资源纪元epoch校验被拒绝。做法简单重新调用observe_ui拿到新的stateId再用新 ref 重试。策略三给操作加上 expect 后置条件strict 模式下事件送达不等于操作成功所以要把完成信号放进同一事务让智能体等待真正的 UI 变化{ actions: [{ action: press, ref: e12 }], expect: { text: Saved, timeoutMs: 3000 } }验证结果为verified/preexisting/failed三种之一应用吞掉了事件时会明确报didnt而不是给你虚假的成功。策略四确实需要原始输入时关闭 strict 模式有些工作流如没有无障碍接口的画布应用确实需要坐标点击或原始键盘。此时把 strict 模式关掉即可三个配置层级任选其一项目配置覆盖全局环境变量覆盖两者层级位置全局配置~/.pi/agent/extensions/pi-computer-use.json项目配置.pi/computer-use.json环境变量PI_COMPUTER_USE_HEADLESS0{ headless: false }在 Pi 里运行/computer-use可随时查看当前生效的配置及其来源docs/configuration.md。策略五确认目标应用支持语义Linux 的能力矩阵中多数操作是 Capability-gated——目标必须导出对应的 AT-SPI 接口docs/linux.md。如果应用本身不暴露无障碍接口strict 模式下没有任何投递路径此时要么换用支持更好的应用/接口要么按策略四关闭 strict 模式。如何检查与切换模式在 Pi 中输入/computer-use查看当前headless状态与来源修改项目级.pi/computer-use.json是推荐做法避免影响其他项目环境变量PI_COMPUTER_USE_HEADLESS1会禁止一切前台回退适合 CI 或无人值守会话配置解析逻辑见 src/config.ts。常见问题 ⚠️Qstrict 模式会阻止观察吗不会。observe_ui、search_ui、read_text、wait_for等只读/观察类工具完全不受影响strict 只约束写入类动作的投递方式。Q失败了为什么不能悄悄重试物理输入这是有意设计不确定结果的动作从不盲目重放strict 调用保持原子的批量事务语义docs/architecture.md。宁可明确失败让你重新观察也不冒干扰用户会话的风险。QLinux 上 strict 模式还能做什么AT-SPI 语义按压/点击、可编辑文本替换、文本读取与等待、窗口截图X11、以及受管浏览器页面的 CDP 操作——都可用被禁用的只有 XTEST 物理输入与 EWMH 强制焦点。一句话总结strict AX 模式阻止的不是能力而是不受控的全局副作用。把坐标换成 ref、把状态刷新到最新、把结果交给 expect 验证绝大多数被阻止的操作都能在 strict 模式下安全完成 【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
