企业官网建设流程全解析

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能

在构建多Agent系统时，多个AI助理往往需要操作同一个桌面：一个负责观察、一个负责执行、一个负责校验。agent-desktop 是一个用 Rust 编写的桌面 computer-use 工具，它让 Agent 通过操作系统原生的无障碍树（Accessibility Tree）真实地"看见"并操作任意应用的 UI，而不是靠像素猜测。它的两大杀手级特性——**共享会话（Shared Session）**与Cursor Overlay 光标覆盖层——正是为多Agent协作而生的。本文将带你从零理解并上手这两个能力。

🤔 为什么需要多Agent共享桌面

单个 Agent 操作桌面时，流程很简单：snapshot → 决策 → act → 再 snapshot。但当你让3 个 Agent 同时操作一台 Mac（比如"研究员"看资料、"写手"改文档、"评审"查结果），会遇到两个核心难题：

1. 状态割裂：每个 Agent 各自记录 UI 状态，彼此不知道对方点了什么、改了哪块，容易造成 ref 过期、重复点击。
2. 看不见谁在干啥：默认操作是"无头"（headless）的——不移动真实光标、不抢占焦点。多 Agent 并行时，人类观察者完全不知道哪个光标正在操作哪块界面。

agent-desktop 的架构图清晰地展示了这条链路：Agent 发起命令 → 中间的 CLI + C 库做原生访问 → 桌面应用通过 OS 无障碍 API 返回 UI 树与结果。

共享会话解决了状态割裂，Cursor Overlay解决了"看得见谁在操作"。二者配合，就是多Agent共享桌面的完整方案。

📡 共享会话（Shared Session）工作原理

一次session start会创建一个带manifest的会话，默认开启 trace 记录（trace: on），并把会话 ID 返回给你。之后所有命令通过全局--session <id>或环境变量AGENT_DESKTOP_SESSION=<id>接入这个会话，就能自动获得两个关键收益（见 SKILL.md）：

• 自动 JSONL 轨迹：命令执行细节自动落到~/.agent-desktop/sessions/<id>/trace/，无需每条命令都加--trace。
• 共享最新快照命名空间：会话内共享"最新快照"的 ref 命名空间，多个 Agent 在同一坐标系里工作。

会话的核心结构定义在 manifest.rs 中，其中trace、artifacts、cursor_overlay都是会话级别的开关——这正是多Agent协作的配置中心。

创建并接入共享会话

# 1. 每个 Agent 运行周期只启动一次会话 agent-desktop session start --name release-fix # 记下 data.session_id export AGENT_DESKTOP_SESSION=<session_id> # 2. 各 Agent 用同一会话 ID 工作 agent-desktop snapshot --app Xcode -i --compact agent-desktop wait --element @s8f3k2p9:e9 --predicate actionable --timeout 5000 agent-desktop click @s8f3k2p9:e9 # 3. 收尾 agent-desktop session end "$AGENT_DESKTOP_SESSION" agent-desktop session gc

⚠️ 关键区别：裸的--session <id>（没有先执行session start生成 manifest）只会限定快照命名空间，不写 trace 文件；只有通过session start创建的"有 manifest"的会话才会记录轨迹。

多 Agent 如何接入同一个会话

针对不同协作模式，接入方式略有差异：

这种"命名空间隔离 + ref 重新识别"机制保证了即便 UI 变化，STALE_REF/AMBIGUOUS_TARGET也会明确报错，而不是随意猜一个目标。

🖱️ Cursor Overlay 光标覆盖层实战

Cursor Overlay（Agent 光标）是一个纯展示层的虚拟光标——它显示 Agent 接下来要做什么，但绝不移动或拦截真实的 OS 指针。默认关闭，仅在 macOS 原生渲染，Windows/Linux 继承适配层的 no-op。

它的行为很有"人味"：

• 光标以 90–320ms 走一段人类化的弧线（不旋转、不变形）；
• 点击时播放涟漪（ripple）+ 元素高亮描边 0.9s；
• 拖拽跟随光标的曲线运动，按住时留下强调色轨迹，松开后淡出；
• 空闲 6 秒自动淡出，下一条命令又会把它带回来；
• 每次操作额外开销约 150–300ms，全部是可见的移动时间。

单 Agent 启用光标

# 启动会话时直接带 --cursor（默认外观） session_id=$(agent-desktop session start --cursor | jq -r '.data.session_id') export AGENT_DESKTOP_SESSION="$session_id" agent-desktop snapshot --app Finder -i agent-desktop click <qualified-ref-from-snapshot> # 光标的弧线 + 涟漪可见 agent-desktop cursor-overlay disable # 随时关掉，无需结束会话

对已存在的会话，用cursor-overlay enable打开；样式命令只是"为下次展示保存配置"，本身不创建光标。

多 Agent 独立光标

这是 Cursor Overlay 最炫的地方：每个不同的 Agent ID 拥有自己独立的光标。三个 ID 就产生三个光标，且没有额外的"协调者"光标，也无需注册步骤。

# 1. 启动共享会话并开启多Agent模式 session_id=$(agent-desktop session start --cursor --multi-agent | jq -r '.data.session_id') export AGENT_DESKTOP_SESSION="$session_id" # 2. 给每个子Agent一个稳定 ID（或用全局 --agent-id，优先级更高） export AGENT_DESKTOP_AGENT_ID=researcher agent-desktop cursor-overlay enable --label "Checking details" --accent "#FF3B7B" # 其他子Agent分别用 writer / reviewer + 不同配色 agent-desktop --agent-id writer cursor-overlay enable --label "Updating draft" --fill "#FFE080" agent-desktop --agent-id reviewer cursor-overlay enable --label "Reviewing result" --accent "#49C98A" # 3. 各自快照 + 操作（用各自 snapshot 的 qualified ref） agent-desktop snapshot --app Finder -i agent-desktop click <qualified-ref-from-snapshot>

Agent ID 规则：1–64 位的字母、数字、-或_。在多Agent模式下，桌面 UI 操作必须带 ID；而观察（observation）、剪贴板操作、会话管理则不需要。

💡 再次强调：多个光标不等于并发操作同一应用就是安全的。光标的独立只是"看得见"，真正的并发协调（尤其是物理输入）仍要靠上层的 harness 来安排依赖顺序——内部通过interaction lease（交互租约）串行化对共享 OS 指针的访问。

光标样式参数一览

配置校验逻辑（如标签最长 512 字节、字数 1–12）见 config.rs，光标控制指令（Enable / Present / Hide / Show / Disable）定义在 control.rs。

关闭所有光标

• cursor-overlay disable：立即移除该会话下所有光标（即使带了某个 agent ID 也一样）；
• session end：结束会话时同样会清掉所有光标。

🧩 多 Agent 协作最佳实践

1. 一个运行周期只session start一次，把返回的 ID 通过AGENT_DESKTOP_SESSION传下去，不要隐式激活后续进程。
2. 各 Agent 操作自己snapshot的 qualified ref——共享会话里"最新快照"不是跨 Agent 的保证，用@<snapshot_id>:<eN>显式钉住。
3. UI 会变的场景，动作后重新 drill 该区域，靠作用域失效（scoped invalidation）保住其他区域的 ref。
4. 物理输入靠 harness 协调，Cursor Overlay 只负责"可视化"，不要把它当作并发安全机制。
5. 敏感字段自动脱敏：trace 中的text、password、token、url等字段会被替换为{ "redacted": true }，可放心导出。

📚 相关源码与文档

• 会话清单与开关定义：manifest.rs
• 光标配置校验：config.rs
• 光标控制指令：control.rs
• 系统命令参考（session / cursor-overlay）：commands-system.md
• 完整 Agent 指南：SKILL.md
• 项目主文档：README.md

❓ 常见问题

Q：多 Agent 共享会话时，ref 会不会互相干扰？不会。ref 是按快照作用域的，每个 Agent 应使用自己snapshot返回的 qualified ref。快照查找只发生在所选会话命名空间内，不会跨会话搜索。

Q：Cursor Overlay 会不会抢走我的真实鼠标？不会。它是纯展示层，"never moves or intercepts the OS pointer"（从不移动或拦截 OS 指针）。真实指针的并发访问由 interaction lease 串行化。

Q：Windows / Linux 支持 Cursor Overlay 吗？当前 macOS 原生渲染，Windows 与 Linux 继承适配层的 no-op（占位），核心契约相同，后续可各自接入渲染器。

✅ 总结

agent-desktop 用两个精巧的设计把"多 Agent 共享桌面"这件事变得可靠且直观：

• 共享会话：一次session start，多 Agent 接入同一 trace + 快照命名空间，状态不再割裂，ref 稳定可重试；
• Cursor Overlay：每个 Agent 一个带弧线的可视化光标，让你和人类观察者都能看清"谁在操作哪里"，而绝不干扰真实指针。

配合 Rust 带来的高性能与原生无障碍访问，这两个能力让多Agent系统从"各自为战"升级为"协同办公"。动手试试吧！

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能