PI-Desktop 教程：本地优先的 AI 编码 Agent 桌面工作台

📌 项目日期：2026年9月 | 数据来源：GitHub官方仓库 | 星数：2.8k+

📋 项目简介

PI-Desktop（2.8k 星，单日 +545）是一个本地优先的桌面 AI 编码 Agent 工作台，Early Preview 0.14.x 阶段。它由 Electron + Rust Host Core + pi Agent Sidecar 构成，把 CLI 编码 agent 的能力装进图形化多项目工作台：三种门控模式控制 agent 的自主程度，Subagents 委托拆解任务，任意模型随意接入，会话流式 checkpoint 随时恢复，数据全在本地。想对比其他 Agent 工作区产品，可以阅读 Sim教程：AI Agent中央智能层，构建部署编排Agent工作区。

✨ 核心特性

特性	说明
三种门控模式	Agent（默认直接干活）/ Plan（先冻结实现计划等审批）/ Goal（锁定目标和验收标准，agent 自选路径）
Subagents 委托	主 agent 把任务拆给探索、实现、研究、测试、对抗审查等专职子 agent
多项目多会话	一个窗口管理多个项目，会话可 pin、可分支、流式 checkpoint 可恢复
@ 文件引用	Composer 内 @ 精确引用文件上下文
模型自由	OpenAI/Anthropic/OpenAI 兼容/Ollama/LM Studio，同 provider 多模型，Composer 内直接换
五层扩展	Skills、MCP（PI_DESKTOP_MCP_CONTROL=1）、Subagents、pi extensions、Plugins（.piplug）
本地优先	会话 JSONL+SQLite 存本地，凭证进 OS keychain，零遥测
会话导入	可直接导入 Claude Code/Codex/OpenCode/Pi 的既有会话继续用
跨平台	macOS dmg/zip、Windows NSIS+portable（SignPath 签名）、Linux AppImage/deb/rpm

🏗️ 工作原理

你（Composer 输入 + @文件引用）
   │  选定门控模式
   ▼
┌─ Agent 模式：直接开干（默认）
├─ Plan 模式：生成实现计划 → 你审批 → 冻结执行
└─ Goal 模式：你定目标+验收标准 → agent 自选路径
   │
   ▼
主 Agent ──委托──→ Subagents（探索/实现/研究/测试/对抗审查）
   │                    │
   ▼                    ▼
Rust Host Core（本地会话 JSONL + SQLite · 凭证入 OS keychain）
   │
   ▼
任意模型端点（OpenAI / Anthropic / Ollama / LM Studio / 兼容 API…）

🚀 安装与上手

# 从 GitHub Releases 下载对应平台安装包
#   macOS:  .dmg / .zip        （默认未签名，首次右键→打开）
#   Windows: NSIS 安装器 / portable 便携版（SignPath 代码签名）
#   Linux:  AppImage / .deb / .rpm   （需 glibc 2.35+）

# 安装后：
# 1. 设置里配置任意模型（API key 或本地 Ollama / LM Studio）
# 2. 打开项目文件夹，新建会话
# 3. 选门控模式：小改动用 Agent，大重构用 Plan，开放式任务用 Goal
# 4. 复杂任务让主 agent 派 Subagents；MCP 需设环境变量
#    PI_DESKTOP_MCP_CONTROL=1 后重启启用

已有 Claude Code/Codex/OpenCode/Pi 会话的用户可直接导入，不换工作流只换工作台。项目基于 pi-mono 的 pi-ai 与 pi-agent-core 构建，LGPL-3.0 开源。一个有趣的细节：作者在 README 公开了 token 消耗账单——这个项目本身主要由 GPT-5.6、Claude Opus 等模型写了超过 271 亿 token，堪称"AI 造 AI 工作台"的样本。

💡 使用建议

• 按风险选门控：日常小改动用 Agent 模式省心；动核心架构前切 Plan 模式，先审计划再放行；探索性任务用 Goal 模式锁验收标准。
• 本地模型也顺手：Ollama/LM Studio 接上就是零成本打杂通道，敏感项目代码全程不出本机。
• 用 Subagents 隔离上下文：研究类子任务派给 research subagent，不污染主会话上下文窗口。
• checkpoint 习惯：长会话中途可断点恢复，配合会话分支做方案 A/B 对比。
• 同类工具对比：终端形态可看 Wave Terminal 开源跨平台AI终端使用教程，纯 IDE 形态可看 Trae AI IDE教程，按习惯选型。