企业官网建设流程全解析

computer-use-linux是一个专为 AI Agent 打造的 Rust 原生 Linux 桌面控制 MCP 服务器，提供语义化 AT-SPI 可访问性树、有界截图、合成器感知的窗口定位，以及覆盖 GNOME、KDE、Hyprland、niri、COSMIC、i3 和 X11 的点击、输入与滚动能力。对 Pi Coding Agent 用户来说，它最大的不同在于：只需一条pi install命令，就能获得一组懒加载的原生桌面工具——不用手写任何 MCP 配置，还能在 Codemode 脚本里直接把截图变成图片。

一条命令安装：Pi 原生集成与 MCP 配置的区别

传统的 MCP 接入方式需要在mcp.json里写command、args，再配一个适配器。computer-use-linux 的 Pi 扩展走的是另一条路：

• 零 MCP 配置：不需要pi-mcp-adapter，不写mcp.json
• 懒加载：Pi 启动时只看到一个小型加载器工具，真实工具按需激活，不占用初始上下文
• 单进程复用：整个会话只启动一个 computer-use-linux 进程，保证element_index快照与 portal 会话始终有效

安装步骤如下（需要 Pi 0.84.4+ 与 Node.js 22.19+）：

pi install npm:@agent-sh/computer-use-linux

然后重启 Pi 或执行/reload即可。注意这条命令不会把computer-use-linux加入PATH；如果你还想在 shell 里跑doctor等子命令，另行执行npm install -g @agent-sh/computer-use-linux或cargo install computer-use-linux。

扩展查找二进制的顺序是：

1. 环境变量COMPUTER_USE_LINUX_BIN（必须是绝对路径）
2. npm 包内已下载并校验的二进制
3. PATH上的computer-use-linux（来自 npm 全局安装或cargo install）

实现细节可参考 pi/extension/index.ts 中的defaultFindBinary，MCP 会话客户端在 pi/extension/mcp-client.ts。

懒加载机制解析：按需启用，下一回合生效

Pi 启动时唯一可见的是加载器工具computer_use_linux_tools，它有两种用法：

① 按精确名称启用

computer_use_linux_tools({ tools: ["doctor", "list_windows"] })

② 按能力语义搜索（不知道工具名时特别好用）

computer_use_linux_tools({ query: "observe a window and click a control" })

搜索会同时匹配工具名、描述和别名（如click的别名包括 "press button"、"mouse"），返回得分最高的 8 个工具。若什么都不传，则默认启用doctor、list_windows、focused_window、get_app_state、get_tree_page五个观察类工具。

启用后的工具有完整的上游 schema，从下一个模型回合开始出现在工具列表中，并在整个会话内保持激活：

computer_use_linux_doctor({}) computer_use_linux_list_windows({}) computer_use_linux_type_text({ text: "hello", title: "Notes" })

懒加载的核心价值在于时序控制：

这意味着纯写代码的任务里，这个 MCP 服务器一个字节都不会多跑；只有当 Agent 真正需要"看桌面、点桌面"时，它才上线。

Codemode 脚本实战：截图结果直通 image()

Codemode 脚本调用原生工具时，拿到的是结构化结果{ text, images, isError }，其中每个images元素都是标准的 MCP 图片块，可以直接传给image()：

const result = await tools.computer_use_linux_screenshot({}); if (result.isError) throw new Error(result.text); text(result.text); for (const block of result.images) image(block);

这是专门为 codemode 沙箱设计的：Pi 的 codemode 只会把声明了outputSchema的工具的structuredContent传给嵌套调用，否则脚本只能拿到纯文本、图片块会被丢弃。相关输出 schema 定义在 pi/extension/index.ts 的NativeToolOutputSchema中，图片保留行为的集成测试见 pi/test/index.test.ts。

一个实用场景：让 Pi 写一段 codemode 脚本，先get_app_state观察窗口，再用click点击目标元素并带screenshot_after: "window"，把动作后的截图直接渲染回会话中——整个"操作 → 验证"闭环在一次工具调用内完成。

六步安全操作循环

官方 Skill 文档（skills/computer-use-linux/SKILL.md）给出了推荐的操作流程，新手照着做即可：

1. 启用工具：打开get_app_state、list_windows和预期会用到的动作工具
2. 限定范围观察：调用computer_use_linux_get_app_state时务必传app_name_or_bundle_identifier或窗口目标（window_id/pid/app_id/wm_class/title）；无目标的调用会返回整棵桌面树并告警，小上下文窗口很容易被灌爆
3. 看就绪度：返回里自带精简 readiness 块；需要完整诊断再启用doctor
4. 确认目标窗口：用computer_use_linux_list_windows或focused_window按标题、app id 等核实
5. 执行动作：优先用element_index或 role/name/text 语义选择器，而不是裸坐标
6. 动作后重新观察：UI 变化后再次观察，避免基于过期状态继续操作

完整规则见 skills/computer-use-linux/references/pi-setup.md。

迁移旧版与就绪验证

如果你之前用的是基于pi-mcp-adapter的旧版安装：新版不会写 MCP 配置，只会在检测到旧的mcp.json条目时提示迁移。清理步骤是删掉mcp.json里computer-use-linux那一条（pi-mcp-adapter若还给别的 MCP 服务器用就保留），然后/reload。

启用doctor验证环境就绪，理想输出应满足：

• can_register_mcp_tools: true
• can_build_accessibility_tree: true
• can_query_windows: true
• can_send_development_input: true
• blockers: []

截图路线在 doctor 里永远是unverified（它只探测、不截图），需要用get_app_state配合include_screenshot: true做真实验证。若can_build_accessibility_tree为 false，先跑setup_accessibility（或 shell 里的computer-use-linux setup）再重启目标应用。

项目内相关文件速查

掌握"先观察、再动作、动作后复核"这一节奏，再配合懒加载带来的零额外开销，Pi Coding Agent 操作本地 Linux 桌面就既安全又高效了。