PI-Desktop 新手教程

1这是什么

一句话：PI-Desktop 是一个把 AI 编程 Agent 装进「独立桌面工作台」的开源应用——不是又一个聊天窗口，也不是编辑器插件。

大多数编程 Agent 住在终端、编辑器扩展或托管服务里。PI-Desktop 的做法是给 Agent 工作流一个自己的工作区：项目、会话、文件、Diff、预览、模型、权限、插件、长任务，全都放在一个桌面环境里——不绑编辑器，不绑模型厂商，不绑云端。它的 Agent 引擎来自 badlogic 的 pi-mono 生态（pi-ai / pi-agent-core），官方的一句话总结是：Pi 负责让 Agent 跑起来，PI-Desktop 负责让 Agent 真正变成一个长期可用的桌面工作台。

2为什么需要它

你已经有一堆能干活的 Agent 了，为什么还要一个「工作台」？先看三条现成路线各自卡在哪。

PI-Desktop 的核心洞察是：Agent 引擎和模型都是可替换的零件，工作台才是常量。引擎用 pi（想换随时可以关注生态），模型走 BYOM 随便换，而项目、会话、权限、Review 这些「长期资产」沉淀在一个独立的桌面应用里——换模型不用重建会话，换编辑器不用搬家，审查和批准永远在同一个地方发生。

3核心流程：四进程架构

PI-Desktop 把「好看的 UI」和「有权限的运行时」拆成四个进程——理解这张图，后面所有设计都顺了。

一次「对话 + 工具调用」的完整路径：

4安装

唯一入口是 GitHub Releases。别从第三方下载站拿安装包。

# 下载最新版（浏览器打开）
open https://github.com/vastsa/PI-Desktop/releases/latest

两条易混淆的路，先分清：

平台注意事项：

• macOS（未签名）：首次打开若被 Gatekeeper 拦截（提示「已损坏」或无法验证），放行隔离标记即可：

  xattr -r -d com.apple.quarantine /Applications/PI-Desktop.app

• Linux：要求 glibc 2.35+（Ubuntu 22.04 及以上等）。
• Windows：内置 Bash 工具依赖 Git for Windows（安装包不捆绑 bash），没装会在执行命令时报 SHELL_NOT_FOUND。

5环境自检与模型接入

装完只完成了一半——PI-Desktop 不带模型，你得自己接一个。官方的「5 步开始干活」如下。

第 ② 步支持的 provider 类型（官方不维护「指定模型列表」，任何 OpenAI 兼容端点都行）：

每个模型可单独配置：Context Window、Max Output、Reasoning / Thinking Level、Temperature、模型专属参数。上下文窗口配小了会出现莫名其妙的截断，建议按 provider 官方标称值填。

权限模式三选一（Agent 模式下生效，决定写文件 / 跑命令要不要你点头）：

6第一次实战：走一遍 Plan 工作流

推荐新手第一次就用 Plan 模式——先看方案再放行，是建立信任最快的方式。

场景：让 Agent 给一个小工具库新增一个函数并补测试。全程不碰终端：

1. 添加项目：侧边栏 → 添加你的项目目录（任意本地 git 仓库或文件夹）。
2. 新建会话，模式选 Plan。描述需求，例如：阅读 src/utils/ 的现有结构，提出为 parseDuration 新增毫秒解析函数的方案，包含测试计划，先不要改代码。
3. Agent 在 Plan 模式下调研并产出方案。此时它不能写文件——Write/Edit 在 host 层被硬拒绝，不是「它自觉不动手」。
4. Agent 调用 SubmitPlan：方案原文以字节级保真写入 .pi/plan/*.md 工件，并弹出审批卡片。点开卡片看到的就是那个 md 文件本身。
5. 你审批：Approve → 会话原子切换到 Agent 模式并排队一个新的执行 turn；Reject → 不产生任何执行能力。
6. Review 面板：逐文件看 diff、看命令输出、用 BrowserPreview 预览页面，继续在会话里迭代。

7产物结构：它在你磁盘上写了什么

Local-first 意味着一切都有迹可循。这张表就是 PI-Desktop 的全部「 footprint 」。

设计原则有两条值得留意：

• 双轨落盘，可审计可回溯。方案以文件形式留在项目里（可以 commit、可以 diff），审批与执行记录留在 SQLite——出问题时两边对得上。
• 状态权威在 host。Renderer 重载后只能通过 plans.pending 拿回「仍然待审」的记录，拿不回（也伪造不了）已终态的审批。

8日常怎么用

跑通第一个 Plan 之后，这些是你会天天摸的操作。

• @ 引用文件：在 Composer 里 @ 项目文件，精确把上下文喂给 Agent。
• 斜杠命令：输入 / 唤出命令菜单（含插件与扩展注册的命令）。
• 排队 prompt：Agent 正在跑也能继续输入，任务会排队执行，不用干等。
• Composer 切模型：同一会话直接换模型，不重建会话、不丢上下文。
• 会话管理：pin / archive / branch / 全文搜索；长会话可用 new_context 工具在轮次边界开新上下文窗口省 token。
• checkpoint 恢复：流式响应有检查点，中断的工作尽量可恢复。
• BrowserPreview：内置浏览器面板直接预览工作区内的页面（只读检查）。

9进阶：Skills / MCP / Subagents / 插件

核心保持克制，能力交给生态扩展——插件是 PI-Desktop 的第二条主线。

Skills：把常用 Prompt、工作流和执行规范做成可复用能力，全局安装或只在某个项目启用。

MCP servers：通过 Model Context Protocol 接入外部工具，在设置里配置，或由插件声明：

{
  "id": "docs",
  "transport": "stdio",
  "command": "bin/docs-server",
  "args": ["--stdio"]
}

Subagents 与背景委托：主 Agent 可以把子任务委托给 Subagent（Task 工具，仅 Agent 模式可用），也可以把长任务丢到后台跑。

pi extensions：为 pi CLI 写的扩展可以不经修改直接跑在 PI-Desktop 的 Agent 里。插件通过 contributes.agentExtensions 贡献它们（需要高风险的 agent.extension 权限）：

// src/index.ts —— pi ExtensionAPI，jiti 直接加载 TS，无需构建
import { Type } from "typebox";
import { defineTool } from "@earendil-works/pi-coding-agent";

export default function (pi) {
  // 1. 注册一个 Agent 工具
  pi.registerTool(defineTool({
    name: "fx_add", label: "Add", description: "Adds two numbers",
    parameters: Type.Object({ a: Type.Number(), b: Type.Number() }),
    async execute(_id, { a, b }) {
      return { content: [{ type: "text", text: String(a + b) }], details: {} };
    },
  }));

  // 2. 每次工具调用的钩子：这里拦掉所有 Bash
  pi.on("tool_call", (event) =>
    event.toolName === "Bash" ? { block: true, reason: "not here" } : undefined
  );

  // 3. 斜杠命令：出现在 Composer 的 / 菜单
  pi.registerCommand("greet", {
    description: "Say hello",
    async handler(args, ctx) {
      const name = await ctx.ui.input("Your name?");
      ctx.ui.notify(`Hello ${name} ${args}`);
    },
  });
}

插件（Plugin）：本地安装或经市场分发，打包成 .piplug（store-only ZIP）。清单文件长这样：

{
  "schemaVersion": 1,
  "id": "local.my-first-plugin",
  "name": "My First Plugin",
  "version": "0.1.0",
  "main": "main.js",
  "contributes": { "agentExtensions": ["src/index.ts"] },
  "permissions": ["agent.extension"],
  "engines": { "piDesktop": ">=0.1.0" }
}

插件能贡献的能力面很宽：commands（命令面板动作）、views（工作面板）、agentTools（Agent 工具）、skills、themes、mcpServers、services（常驻后台）、bus（插件间通信）、settings、agentExtensions。权限模型要求最小化声明——文件访问用 fs 白名单、网络用 net.domains 域名白名单：

{
  "fs":  { "read": { "scope": ["**/*"] }, "write": { "scope": ["docs/**"] } },
  "net": { "domains": ["api.example.com"] }
}

会话导入：Settings → Import 可以把已有的本地会话带进来，支持 Claude Code、Codex、OpenCode、Pi。（注意：不支持 Cursor——原因见下一节。）

10集成 Cursor CLI：可行路径与边界

直接给结论：「把 Cursor CLI 塞进 PI-Desktop 当引擎」走不通，但反过来「用 Cursor CLI 驾驶 PI-Desktop」是官方支持的正式能力。集成方式取决于你想接在哪一层。

控制层是唯一值得认真做的集成，拓扑如下——注意方向：Cursor CLI 是客户端，PI-Desktop 是被控端：

四步接通（以 macOS 为例，Windows / Linux 同理）：

第 1 步：带环境变量启动 PI-Desktop。注意坑：open -a 经 launchd 启动，环境变量传不进去，要直接运行可执行文件：

# macOS：直接跑 binary（open 命令传不了 env）
PI_DESKTOP_MCP_CONTROL=1 /Applications/PI-Desktop.app/Contents/MacOS/PI-Desktop &

# Linux（AppImage）
PI_DESKTOP_MCP_CONTROL=1 ./PI-Desktop.AppImage &

# Windows PowerShell（Portable 示例；安装版把路径换成安装目录下的 exe）
$env:PI_DESKTOP_MCP_CONTROL = "1"
& ".\PI-Desktop.exe"

第 2 步：读取连接清单拿 endpoint 和 token。启用后 Electron 会在 user-data 目录生成 mcp-control.json（含回环端点 + 256-bit bearer token，文件权限 0600）：

# macOS
cat ~/Library/Application\ Support/PI-Desktop/mcp-control.json
# Linux
cat ~/.config/PI-Desktop/mcp-control.json
# Windows PowerShell
Get-Content "$env:APPDATA\PI-Desktop\mcp-control.json"

文件里的字段名以你机器上实际生成的为准（端点形如 http://127.0.0.1:<端口>/...）。找不到就到应用数据目录里搜 mcp-control.json。

第 3 步：在 Cursor CLI 侧注册这个 MCP server（全局 ~/.cursor/mcp.json 或项目 .cursor/mcp.json）：

{
  "mcpServers": {
    "pi-desktop": {
      "url": "http://127.0.0.1:<端口>/<mcp 路径>",
      "headers": { "Authorization": "Bearer <mcp-control.json 里的 token>" }
    }
  }
}

第 4 步：在 Cursor CLI 里遥控。之后 cursor-agent 就能调用控制面暴露的工具，完成建项目、开会话、发 prompt、查状态等操作，例如对它说：「连接 pi-desktop，把 ~/WorkBuddy/Demo 项目加进去，开一个会话让 Agent 先出个重构方案」。Cursor 侧对 Streamable HTTP 型 server 的字段名以 Cursor 当前版本文档为准。

11运行边界与成本

官方没有发布性能基准，这里给的是写进 spec 的硬边界——都是设计值，不是实测跑分。

成本结构很简单：模型费用 BYOM 自付，PI-Desktop 没有中继、没有抽成、没有强制账号；本地模型（Ollama / LM Studio）则是零 API 成本换零上传。真正要留心的是 Early Preview 的时间成本——接口和打包行为仍在演进，把它当主力工具前，先在非关键项目上跑一两周。

12FAQ / 踩坑

每一条都给可执行的解法，不给「重启试试」。

13许可与安全边界

两件小事，用之前值得知道。

• 许可：LGPL-3.0。可以自由使用和分发；对库部分做修改时需遵守 LGPL 的回传条款，集成开发前过一眼仓库 LICENSE。
• Local-first 的准确含义。项目和会话数据留在本机；模型请求直连你配置的 provider——换句话说，你的代码会以 prompt 形式发给你选择的那家模型服务，但不经过 PI-Desktop 的任何中继（它也没有中继）。合规上等同于直接用该 provider 的 CLI / API。
• 自动化面只有一扇门。MCP Control 默认关闭、仅回环、不暴露 secret 通道；除此之外没有任何远程控制入口（远程 Agent Control 属于 post-MVP 规划，尚未实现）。

本教程基于 2026-09 的官方 README 与 spec（host 协议 v11 / 存储结构 v16）整理；项目处于早期预览，接口可能变化，落地前以官方文档为准。

14参考链接

官方资源清单，按深入程度排序。

• GitHub 仓库 vastsa/PI-Desktop（含 中文 README）
• Releases 下载
• 官方文档站
• Specification 索引（架构 / 运行时 / 安全 / 插件四条阅读路径）
• 架构 spec · 安全 spec
• 插件开发指南
• 仓库 Agent 指南（AGENTS.md）——想给它写代码先读这个
• pi-mono 上游生态（Agent 引擎与 pi CLI 扩展体系）