Desktop Control 默认启用

Computer Use 桌面自动化 — get_app_state、click、set_value、键盘/指针操作。统一技能，用于所有 UI 自动化，根据目标在 CDP（浏览器 DOM）和 Computer Use（桌面应用）之间自动路由。

快速参考

执行路径

操作类别

意图路由

该技能在执行操作之前决定执行路径。每个任务的第一行必须声明 path=cdp、path=computer-use 或 path=cdp+cu。

决策表

解析顺序

1. 显式指定： 消息包含 $computer-use 或 /computer-use → 立即使用 Computer Use 路径。如果工具不可用，停止并报告 precondition failed: computer-use unavailable。
2. 目标能否通过 cli-jaw browser snapshot --interactive 引用来定位？ → CDP。
3. 非 DOM 的 Web 组件（Canvas、WebGL、iframe）在 get_app_state 截图中可见？ → Computer Use click(x, y)。
4. 目标在任何网页之外（应用窗口、菜单栏、系统对话框）？ → Computer Use。
5. 用户直接给出的像素坐标？ → Computer Use pointer-action。
6. 需要 DOM 来定位，但用户坚持使用真实光标点击？ → 混合模式。
7. 应用名称不明确？ → 先调用 list_apps()，再调用 get_app_state(app)。
8. 以上均不匹配 → 停止并报告 needs boss follow-up: ambiguous target。

绝对规则

这些规则不可违反。违反任何一条都会导致错误的记录或浪费操作。

1. 操作前声明路径。 每个任务的第一行必须是 path=cdp、path=computer-use 或 path=cdp+cu。
2. 状态优先规则。 Computer Use 每次助手回合总是先调用 get_app_state(app) 再进行交互。在收到过期警告时、UI 发生变化的操作之后、以及置信度下降时都需要重新调用。
3. 每个有意义的操作都要记录 action_class。 类别包括：state-read、element-action、value-injection、keyboard-action、pointer-action、pointer-action+vision。
4. 禁止静默回退。 如果所需路径不可用，停止并报告哪个前置条件失败。
5. 禁止声称光标可见。 当前版本中光标覆盖层是尽力而为的。
6. 不确定时，先截图。 禁止在不确定的情况下连续执行操作。如果连续两个操作产生了模糊的状态，下一次调用必须是 state-read。

Computer Use 工具接口

Computer Use 路径通过活跃的运行时暴露以下工具：

CDP 路径 — cli-jaw browser

适用于所有可通过 Chrome DOM 定位的内容：页面文本、表单字段、页面内的按钮。处理 Web 内容时比 Computer Use 快 10 倍。

会话命令

cli-jaw browser status                         # 会话是否活跃？
cli-jaw browser start --agent                  # 无头自动化会话
cli-jaw browser start --headless               # 手动无头模式（WSL/CI/Docker）
cli-jaw browser start                          # 可见窗口（仅在用户要求时使用）
cli-jaw browser navigate "https://example.com" # 导航到 URL
cli-jaw browser open "https://example.com"     # 在新标签页中打开
cli-jaw browser tabs                           # 列出标签页

快照 + 操作

cli-jaw browser snapshot --interactive   # 列出可点击元素（e1、e2、...）
cli-jaw browser click e3                 # 通过引用点击
cli-jaw browser type e5 "query" --submit # 输入 + 回车
cli-jaw browser press Enter              # 备用按键
cli-jaw browser screenshot               # 保存 PNG 截图
cli-jaw browser text                     # 输出可见文本

CDP 操作类别映射

前置条件

Computer Use 路径

• 平台： 仅限 macOS。
• 活跃的代理运行时必须暴露所有 Computer Use 工具（list_apps、get_app_state、click、drag、press_key、scroll、set_value、type_text、perform_secondary_action）。
• TCC 无障碍权限和 AppleEvents 必须授予控制应用。
• 在打包安装中，可能需要 /Applications/Jaw.app 和 /Applications/Codex Computer Use.app 用于 TCC 归属。
• 如果应用名称未知，先调用 list_apps()。

CDP 路径

• cli-jaw serve 必须正在运行（通过 cli-jaw browser status 检查）。
• 浏览器会话必须处于活跃状态（通过 cli-jaw browser start --agent 启动）。

记录格式

每个操作都会记录在结构化记录中。上级会解析这些记录 — 请勿省略 path= 行。

CDP 记录

path=cdp
url=https://example.com
action=click e3
result=ok

Computer Use 记录

path=computer-use
app=Google Chrome
action_class=element-action
action=click(element_index=730)
stale_warning=no
result=ok

混合模式记录

path=cdp+cu
lookup=cli-jaw browser snapshot -> bbox of "Play"
action_class=pointer-action
action=click(x=812, y=514)
result=ok

错误记录

path=computer-use
app=Finder
action_class=element-action
action=click(element_index=34)
stale_warning=yes
result=error: stale element tree

过期恢复模式

当返回 stale_warning=yes 时，元素树已发生变化。请严格按照以下顺序操作：

1. get_app_state(app) — 重新定位；记录目标的真实 element_index。
2. 记录 action_class=stale-recovery（CU-06），附带一行说明（reason=disambiguation）。
3. 使用最新的 element_index 重新执行目标操作。
4. 操作完成后，再次调用 get_app_state(app) 确认效果。

# 收到过期警告
path=computer-use
app=Google Chrome
action_class=stale-recovery
action=get_app_state("Google Chrome")
stale_warning=no
result=ok (52 elements -- tree changed)

# 使用新索引重试
path=computer-use
app=Google Chrome
action_class=element-action
action=click(element_index=38)   # 同一目标，新索引
stale_warning=no
result=ok

Vision-Click 集成

Vision-click 是更广泛的 UI 目标定位问题中的一种特定策略。它是旧版方案，通常已被从截图直接进行坐标点击所取代。

决策顺序

1. cli-jaw browser snapshot --interactive 是否返回了引用？ → CDP click。
2. Computer Use 可用且目标在截图中可见？ → 直接使用 click(x, y) pointer-action（首选）。
3. 没有引用且直接坐标不适用 → cli-jaw browser vision-click（仅限 Codex，旧版）。

# CDP vision-click（在 Chrome 内，仅限 Codex）
cli-jaw browser vision-click "Submit button"
cli-jaw browser vision-click "Play button" --double

# 桌面 vision-click（CU-05）
# 1. get_app_state(app) 获取截图
# 2. 视觉模型识别坐标
# 3. 通过 Computer Use 执行 click(x=vx, y=vy)

完整示例：Chrome → Spotify 跟踪记录

一个真实的端到端跟踪记录，展示了状态优先、元素定位、过期恢复和 CDP 速度切换。

1. 状态优先

path=computer-use
app=Google Chrome
action_class=state-read
action=get_app_state("Google Chrome")
stale_warning=no
result=ok (47 elements, focused tab: open.spotify.com)

2. 元素索引定位（非仅焦点输入）

# 点击搜索输入框
path=computer-use
app=Google Chrome
action_class=element-action
action=click(element_index=12)
stale_warning=no
result=ok

# 确定性地设置搜索值
path=computer-use
app=Google Chrome
action_class=value-injection
action=set_value(element_index=12, value="Daft Punk")
stale_warning=no
result=ok

3. 过期警告 → 恢复

# 搜索结果异步加载 -- 元素树变化
path=computer-use
app=Google Chrome
action_class=element-action
action=click(element_index=34)
stale_warning=yes
result=error: stale element tree

# 正确的恢复方式
path=computer-use
app=Google Chrome
action_class=stale-recovery
action=get_app_state("Google Chrome")
result=ok (52 elements -- tree changed)

path=computer-use
app=Google Chrome
action_class=element-action
action=click(element_index=38)   # 同一结果，新索引
stale_warning=no
result=ok

4. 切换到 CDP 获得 10 倍速度

# 发现所有目标都是 DOM 节点 -- 切换到 CDP
path=cdp
url=https://open.spotify.com
action=cli-jaw browser snapshot --interactive
result=ok (ref IDs: e1..e89)

path=cdp
url=https://open.spotify.com
action=click e42   # "Shuffle Play" 按钮
result=ok

常见故障与正确响应

契约 ID 参考

所有路由都映射到内部 Computer Use 规范中定义的能力契约。在记录中需要契约名称时使用这些 ID。

"~해줘" 使用示例

触发 desktop-control 技能的自然韩语请求。路由系统能理解韩语和英语。

规则：禁止事项

• 不要"以防万一"尝试错误的路径 — 这会浪费 TCC 提示并扰乱日志。
• 不要在未更新操作类别的情况下静默从 state-read 升级到 element-action。
• 不要省略 path= 行。上级会解析它。
• 不要使用 curl/wget 来"读取页面" — 务必使用 CDP。
• 不要仅仅为了查看日志而打开可见浏览器窗口 — 使用 Web UI 调试控制台。
• 不要在引用存在时使用坐标点击 — 使用引用。
• 不要假设光标可见。只报告操作的成功/失败。
• 不要因为"记得按钮在哪里"就跳过 get_app_state。元素索引在每次状态变化后都会漂移。
• 不要在两次 Computer Use 操作之间不重新读取状态，如果前一次操作改变了任何内容。
• 不要通过试错来解决不确定性。"让我点击 342，如果不行再试 357"是被禁止的 — 先截图。
• 不要将 type_text(app, text) 作为定向表单输入的快捷方式，除非在最新状态中已验证焦点。
• 不要用不同措辞重试 vision-click — 每次调用只尝试一次；失败时报告并停止。

相关技能