pi-computer-use原生Helper构建指南：build:native与build:linux快速上手
pi-computer-use原生Helper构建指南build:native与build:linux快速上手【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-usepi-computer-use是一个让 AI Agent 直接操作 macOS、Windows 与 Linux 桌面应用的 Pi 扩展Agent 可以看见应用窗口、理解按钮与文本并执行点击、输入、滚动等操作。它的底层由一个平台原生 Helper辅助进程驱动而build:native与build:linux两个 npm 脚本正是构建这个 Helper 的入口。本指南带你从环境准备到产物验证完整走一遍原生构建流程。为什么需要构建原生 Helpernpm 包里已经附带了预构建产物如 prebuilt/macos/arm64/bridge普通用户直接安装即可。但以下场景建议自己构建️修改了原生源码比如改动了 native/macos/bridge.swift 或 native/linux/bridge-rs/src/lib.rs需要特定架构例如为 Apple Silicon 和 Intel 同时构建universal/arm64/x64发行版打包为 Linux 社区发布本地化二进制签名需求macOS 上用自己的签名身份重签 Helper构建入口统一在 scripts/build-native.mjs它会根据平台自动选择 SwiftmacOS或 Rust CargoWindows/Linux工具链。环境准备各平台依赖清单平台工具链前置要求源码位置macOSxcrunswiftcXcode Command Line ToolsmacOS 14native/macos/LinuxRust / Cargorustup 安装完成native/linux/bridge-rs/WindowsRust / CargoMSVC 工具链native/windows/bridge-rs/通用要求Node.js ≥ 20.6见 package.json然后克隆仓库并安装依赖git clone https://gitcode.com/GitHub_Trending/pi/pi-computer-use cd pi-computer-use npm install Linux 的 Rust 依赖包括zbusD-Bus/AT-SPI2、x11rbX11 合成与输入等清单见 native/linux/bridge-rs/Cargo.toml。一键构建步骤macOS 的 build:native在 macOS 上无需任何参数即可构建当前架构的 Helpernpm run build:native这条命令等价于node scripts/build-native.mjs脚本定义见 package.json。构建流程分为三步编译swiftc以-O优化编译 bridge.swift、agent_cursor.swift 等源码目标为 macOS 14.0链接 AppKit、ScreenCaptureKit 等框架落盘产物输出到prebuilt/macos/arch/bridge签名默认使用 ad-hoc 签名-可通过--sign-identity指定 Developer ID 身份常用变体# 构建 Intel 版本 npm run build:native -- --arch x64 # 构建 Universalx64 arm64 合并版本 node scripts/build-native.mjs --arch universal # 只编译、跳过签名快速迭代 node scripts/build-native.mjs --no-sign 注意macOS 的 TCC 权限辅助功能、屏幕录制与签名身份绑定。ad-hoc 签名在每次重新构建后可能需要在系统设置中重新授权发布版建议使用 Developer ID 证书详见 docs/development.md 的 Release signing 章节。一键构建步骤Linux 的 build:linux在 Linux 上安装好 Rust 后一条命令完成构建npm run build:linux它等价于node scripts/build-native.mjs --platform linux默认构建当前机器架构产物输出到prebuilt/linux/arch/linux-bridge。也可以显式指定架构# 只构建 x64x86_64-unknown-linux-gnu node scripts/build-native.mjs --platform linux --arch x64 # 只构建 arm64aarch64-unknown-linux-gnu node scripts/build-native.mjs --platform linux --arch arm64 # 两种架构都构建 node scripts/build-native.mjs --platform linux --arch all构建脚本会做两次防伪校验检查产物是否为合法的ELF 可执行文件并核对机器类型码与目标架构一致见 scripts/build-native.mjs——防止交叉编译时把错误的二进制误当作目标架构发布。构建后验证三步确认 Helper 可用1. 安装 Helper 到用户目录node scripts/setup-helper.mjs --platform linux安装目标位置为~/.pi/agent/helpers/pi-computer-use/linux-bridge见 docs/linux.md。Linux 安装默认不自动触发构建找不到预构建产物时会明确报错——这正是脚本检查项之一scripts/check-linux-build-scripts.mjs。2. 运行静态检查npm run test:linux # 平台行为检查 npm run test:linux-scripts # 构建脚本一致性检查3.可选运行真实环境测试实时检查必须运行在目标用户的图形化 D-Bus 会话内PI_CU_LIVE1 npm run test:linux-live在 macOS 上则直接运行npm test即可它会串联类型检查、工具模式校验、架构不变量与原生 Helper 检查见 docs/development.md。常见问题速查❓构建报 Refusing to label a host binary as WindowsWindows Helper 必须在 Windows 上构建或显式传入--target交叉编译三元组scripts/build-native.mjs❓--arch universal在 Linux 上报错Linux 不支持 universal只能选x64、arm64或all❓改完 Swift 代码没生效macOS 上修改原生代码后必须重新执行npm run build:native并重启 Pi❓Linux 权限与 Wayland 限制AT-SPI2 语义操作优先Wayland 下仅提供只读诊断不支持截屏与物理输入完整能力矩阵见 docs/linux.md小结命令平台产物路径npm run build:nativemacOSprebuilt/macos/arch/bridgenpm run build:windowsWindowsprebuilt/windows/windows-bridge.exenpm run build:linuxLinuxprebuilt/linux/arch/linux-bridge掌握build:native与build:linux之后你既能跟进上游的原生改动也能为自己的桌面环境打造专属的 pi-computer-use Helper。更多架构细节可阅读 docs/architecture.md平台后端实现分别位于 src/platform/linux/、src/platform/macos/ 与 src/platform/windows/。【免费下载链接】pi-computer-useLet Pi control your apps on MacOS Windows项目地址: https://gitcode.com/GitHub_Trending/pi/pi-computer-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考