Pi Linux Use — 给 Pi 编程 Agent 装上一双"Linux 桌面手眼"

> 一句话版本：一个小项目，让 Pi 编程 Agent（开源的 AI 编程助手）能看 Linux 屏幕、点按钮、打字、滚动——跟刚研究过的 Peekaboo（macOS）做的事情一样，但这是给 Linux 的。

来源: https://github.com/sacenox/pi-linux-use

作者: sacenox（未知背景，个人开发者）

版本: 早期 POC，0 ⭐，无 Release

日期: 2026-05-13

评分: ⭐⭐⭐ (3.0/5)

这是什么？

pi-linux-use 是一个 Pi 编程 Agent 的扩展，让 Pi 获得操作 Linux 桌面的能力。

它只做两件事：

1. desktop_observe — 截图（用 KDE Spectacle），返回图片 + 尺寸信息

2. desktop_input — 发送鼠标/键盘输入（用 dotool），支持 click/move/type/key/scroll/script

第 3 件事是配了一个 linux-desktop-use 技能文件（SKILL.md），教 Agent 观察 → 行动 → 再观察 的工作流。

安装

# 依赖
sudo apt install spectacle
# dotool（需加入 input group + reboot）

然后把 .pi/extensions/linux-use.ts 和 .pi/skills/linux-desktop-use/ 放到你的 Pi 项目里，/reload 即可。

源码分析（192 行 TypeScript）

代码质量意外地不错。几个值得注意的设计：

截图:

• 调用 spectacle -b -n -f -o path（背景模式、无通知、全屏）
• 解析 PNG 头取宽高，存全局 lastScreenshot
• 检查模型是否支持图片输入，不支持时只返回路径

输入:

• 坐标从截图像素坐标映射到 dotool 百分比（pct() 函数）
• 多行文本自动用 type + key enter 分段
• 支持 6 种 action：click / move / type / key / scroll / script

安全性:

• 3000ms 超时 + SIGKILL fallback
• AbortSignal 支持
• dotool 失败时给出清晰错误提示

// 坐标映射：像素 → dotool 百分比
function pct(value: number, max: number) {
  const clamped = Math.max(0, Math.min(value, max - 1));
  return (clamped / Math.max(1, max - 1)).toFixed(6);
}

技能文件（SKILL.md）重点

• 核心循环：observe → act → observe（短循环，每次 action 后重新观察）
• 坐标规则：全桌面坐标（多显示器），窗口变化后必须重新 observe
• 安全实践：点目标窗口前先聚焦、小步前进、避免破坏性操作
• 浏览器浏览模式：用户让"看看打开的 repo"时用可见浏览器窗口操作

关于 Pi 编程 Agent

Pi 是一个开源 AI 编程 Agent，由 Mario Zechner（badlogic）创建：

• 对标 Claude Code / Codex，但完全开源
• 用 TypeScript 扩展系统 + SKILL.md 技能文件
• 支持 Anthropic、OpenAI、Google、Ollama 等多种 provider
• 多个 fork 版本：@badlogic/pi-mono（原版）、@earendil-works/pi-coding-agent（sacenox 用的）、@mariozechner/pi-coding-agent

Pi 的扩展系统非常灵活：把 .ts 扩展文件丢到 .pi/extensions/，把 SKILL.md 丢到 .pi/skills/，Pi 下次启动自动加载。

对比 Peekaboo（刚研究完）

核心差异：Peekaboo 是完整的独立工具（CLI + MCP + Agent + macOS App），pi-linux-use 是 Pi 的一个轻量扩展（两个工具 + 一个 skill）。

评价

这是一个方向的种子，还不是完整产品。Peekaboo 花了很长时间打磨成今天的样子，pi-linux-use 只是证明"Pi 也能做 Linux computer-use"的 POC。

优势：

• 代码干净，设计合理，扩展思想与 OpenClaw 的 Agent Skill 类似
• 跨平台的潜力：如果 Pi 生态成熟，这种 pattern 可以移植到任何桌面

不足：

• KDE/Wayland 专一（Spectacle + dotool）
• 不支持 Accessibility 树（只有截图，无 UI 元素识别）
• 无视觉反馈、无弹窗处理、无窗口管理
• 0 stars，可能烂尾

对我们（OpenClaw 用户）的启示：

• Pi 的扩展模型（TypeScript 扩展 + SKILL.md 技能）跟 OpenClaw 的 Agent Skill 非常相似
• peekspace 是跨平台发展的一个方向参考
• 如果我们想给 OpenClaw Agent 加 Linux 桌面控制，可以从这个项目取经

评分