vastsa/PI-Desktop：2.8k stars 的本地优先 AI 编码 Agent 桌面，Electron + Rust host core + pi Agent Harness + 用户可装插件
上个月我把我所有 AI 编码 agent 装了一遍：Claude Code、Codex CLI、opencode、Cursor、Copilot。 每个都好用，但我开始对一件事不爽，它们都往云端发东西。
Claude Code 的 compact 上传内容会压缩、Codex 的 trace 上传 OpenAI、opencode 的 server 默认绑 127.0.0.1 但你能改、Cursor 明确是 SaaS。 我想做完全本地的 agent 体验，model 调用我自己配（BYOK）、tool 执行我自己 host、上下文我自己存。
上周末我在 GitHub Trending 上刷到一个新项目：vastsa/PI-Desktop。 2.8k stars，552 forks，当日 +552 stars。 MIT。 README 第一句：”Local-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins”。
我装上跑了两天。 这篇文章想说的不是”PI-Desktop 多么革命性”，而是一个更工程化的定位，“完全本地 + 完全可扩展 + 全用户掌控” 的 AI 编码 agent 应该是 2026 年下半年的标配。 Claude Code、opencode 这些是” 云端有”，PI-Desktop 是” 我有”。
一、它想解决的问题：AI 编码 agent 的” 云端依赖”
先把背景说清楚。
2024-2026 年，AI 编码 agent 经历了” 从工具到平台” 的演化：
- 2024 H1：Claude Code、Codex 是” 终端里跑的 agent”，核心功能单进程搞定。
- 2024 H2：开始有 cloud relay（Claude Code 的
/bug命令把 session 上传 Anthropic）。 - 2025 H1：opencode 提出了” 客户端 / 服务端分离”，但 server 还是默认在本地。
- 2025 H2：Cursor、Copilot 这类 SaaS 化 agent 占主导，agent 跑在别人服务器上。
- 2026 H1：PI-Desktop 出现，主打” 完全本地 + 完全可扩展”。
PI-Desktop 想解决的问题是 2025 H2-2026 H1 出现的一个新痛点：
“我想用 AI 编码 agent，但不想让我的代码 / 对话 /tool 输出被发到任何云端。 我想完全掌控执行环境，包括 LLM provider、tool 实现、上下文管理。 我想能装第三方插件，但插件本身也要本地能跑。”
这是个特定用户群的痛点：
- 企业 IT 部门，合规要求代码 / 对话不出公司网络。
- 安全研究者，不想把代码送过去训下一版模型。
- 个人开发者，隐私 / 成本考量，不想按 token 计费。
- 自托管爱好者，已经自托管 GitLab / Gitea / Vault，自托管 agent 是下一步。
PI-Desktop 不解决”agent 比 Claude Code 更聪明” 的问题。 它解决”agent 完全本地跑 + 我能改每个组件” 的问题。
二、核心架构：Electron UI + Rust 宿主 + 插件化
PI-Desktop 的架构拆得很干净，三层：
Electron UI 层。 桌面壳，TypeScript + React 写。 负责 chat 输入框、消息流、文件 diff 显示、tool call 状态、agent 切换 UI。 UI 层完全不接触 LLM /tool，只显示数据、转发用户输入。
Rust host core。 Rust 写的核心执行环境。 负责：
- LLM provider 抽象（OpenAI-compatible / Anthropic / Ollama /llama.cpp）
- Tool execution sandbox（bash / read / write / search）
- Context 管理（message history + token counting + compaction）
- MCP server 连接
- Agent 协议层（LLM ↔ tool call loop）
Rust 这层完全在用户机器上跑，没有任何外部网络调用（除非用户配的 LLM provider 需要）。 这条把”agent 跑在别人服务器上” 这件事从根上排除。
pi Agent Harness。 一个默认 agent 实现，跑在 Rust host 上。 PI-Desktop 自带这个 harness，用户也可以装其他 harness 作为插件。
三层解耦让”UI 不动 + Rust core 不动 + 换 agent harness” 成为可能。
插件机制。 PI-Desktop 的” 插件” 是可以装在本地的 package，不是 SaaS。 装一个 plugin = 下载一个并解压一个 .tar.gz/.zip 到 plugins/ 目录。 插件可以包含：
- 自定义 LLM provider（OpenAI / Anthropic / 自托管 vLLM / Ollama）
- 自定义 MCP server（agent 能调的外部 tool）
- 自定义 skill（agent 行为的 skill 包）
- 自定义 agent harness（替换默认的 pi Agent Harness）
用户完全掌控装什么、不装什么。 没有”plugin marketplace + 云端安装 + 自动更新”，纯本地。
三、跟之前发过的几个项目的对比
之前发过的几个 agent 本体 / 协调层项目：
anomalyco/opencode（204k stars）。 opencode 是” 客户端 / 服务端分离”，server 可以跑本地。 但默认配置走 cloud 友好（Vercel AI SDK），多数工具商默认支持 cloud provider。 跟 PI-Desktop 区别：opencode 服务化设计，PI-Desktop 桌面化设计。
mksglu/context-mode（20.8k stars）。 context-mode 是 hook 层优化，不重做 agent，挂在现有 agent 上。 跟 PI-Desktop 区别：context-mode 是” 补丁”，PI-Desktop 是” 自托管完整 agent”。
Tencent/teamai-cli（3.0k stars）。 teamai-cli 是” 团队 harness 协调层”，管团队分发。 跟 PI-Desktop 关系正交。
DietrichGebert/ponytail（127k stars）。 ponytail 是” 行为 skill”，挂在 agent 上改 prompt。 跟 PI-Desktop 关系正交，ponytail 可以作为 PI-Desktop 的 skill 插件装。
affaan-m/ECC（255k stars）。 ECC 是”skill 库”，跟 ponytail 类似。 跟 PI-Desktop 关系正交。
PI-Desktop 在这条栈上的位置：
1 | 输入层：OpenWhispr / Chrome Web Clipper / 手动 import |
PI-Desktop 是 **” 本地优先 agent 层”**。
四、pi Agent Harness 是什么
“pi Agent Harness” 我之前没发过。 简单说：
agent harness 是”agent 的执行框架”。 Claude Code / Codex /opencode 都有自己的 harness，核心是”LLM ↔ tool call loop”，管理 message history、tool execution、context window。
pi Agent Harness 是 PI-Desktop 默认 harness。 Rust 写，紧凑、模块化、完全开源。 跟 Claude Code 那种” 完整产品” 比，pi Agent Harness 更像一个参考实现，开发者可以 fork 改。
PI-Desktop 装好后默认跑 pi Agent Harness。 用户想换其他 harness（比如用 Claude Code 的 harness 跑 Anthropic 模型），可以装一个 plugin 替换。
这条”agent harness 跟 agent UI 解耦” 的设计，让 PI-Desktop 不绑定特定 LLM / 特定 tool 集合。 你可以让你的 harness 跑 OpenAI，也可以跑本地 Ollama。
五、本地优先的几个具体细节
PI-Desktop 做了几件真正本地的事：
Rust host core 在用户机器。 binary 装在用户机器上，跑所有 LLM /tool/context。 没有”PI cloud relay” 这种组件。 这是真正的本地，不是” 客户端 + 服务端” 的” 本地客户端”。
所有 API key 都在本地。 LLM provider API key 存在本地 SQLite 数据库，加密。 默认不上传。 这跟 OpenWhispr（之前发过）的” 本地 SQLite 加密存储 API key” 是同款设计。
网络隔离友好。 整个 PI-Desktop 二进制可以在完全断网的状态下跑（除了 LLM provider 的 API call）。 这条对安全研究 / 涉密项目特别重要。
LLM provider 任意。 支持任何 OpenAI-compatible API（OpenAI、Azure、Anthropic via proxy、Ollama、vLLM、llama.cpp、LM Studio）。 也支持 Anthropic native API。 用户自己选。
Tool 执行 sandbox。 bash /read/write /search tool 跑在 Rust host 里，用户权限，不是 sandbox 隔离。 这条跟 Claude Code 默认 sandbox 不同，PI-Desktop 让用户完全掌控 tool 执行，风险自己担。
数据加密。 SQLite 数据库可以用 user-set password 加密。 重新开 app 要输密码才能解 contexts。
audit log。 所有 tool call 写本地 audit log，不上传。 用户想看历史命令、调文件、跑 bash 全都有记录。
六、安装与上手
README 给的安装路径：
- 下载对应平台的 installer（macOS / Windows / Linux）。
- 启动 PI-Desktop。
- 进 Settings → Providers，配 LLM provider（API key）。
- 装可选 plugins（skill / MCP server /agent harness）。
- 打开项目目录，开始对话。
PI-Desktop 的” 项目” 概念跟 Claude Code 类似，一个文件夹对应一个 project。 chat 在 project 内持久化。
Plugin 安装：
1 | # 从 GitHub release 装 |
Plugin 装在 ~/.pi/plugins/ 目录下（具体路径看 README）。
Skill plugin：
1 | # 装 ponytail skill |
MCP server plugin：
1 | # 装 filesystem MCP server |
Agent harness 替换：
1 | # 装一个非默认 harness |
七、跟云端 agent 的几个具体差异
PI-Desktop 跟 Claude Code /opencode 几个关键差异：
1. 上传 vs 完全本地。 Claude Code 会把对话 + tool 输出上传 Anthropic（用于训练 opt-out 但默认 opt-in）。 PI-Desktop 默认什么也不上传，除非你自己配了 LLM API（这种情况下 LLM provider 收到的是你发出去的内容，但 PI-Desktop 自己不存）。
2. 桌面 vs 终端。 Claude Code / Codex /opencode 都是 CLI 工具，终端原生。 PI-Desktop 是桌面应用，有 GUI。 GUI 对非工程师用户更友好。 我看到 README 提到 PI-Desktop 的 UI 是 Electron 写的，”feels like a chat app”，不复杂。
3. 插件 vs marketplace。 Claude Code 的 plugin marketplace 在 Anthropic 服务器上（GitHub-based 但通过 Anthropic 的 CLI 安装）。 PI-Desktop 的 plugin 纯本地，没有云端 marketplace。 这条对” 我不想依赖 Anthropic / GitHub” 的人很重要。
4. 模型选择。 Claude Code 绑定 Anthropic 模型（虽然支持 BYOK 但 Anthropic 优化过）。 PI-Desktop 模型无关，任何 OpenAI-compatible API 都能跑。 Ollama 本地模型也支持。 这条对” 我本地有 7B 模型不想付 API 费” 的人很有用。
5. 上下文管理。 Claude Code 的 compact 是” 截断 + LLM 总结”，本地 agent 自己选 compact 策略。 PI-Desktop 的 Rust host core 提供多种 compact 策略（truncate、summarize、sliding window），用户自选。
八、几个我装上跑过的具体场景
场景 1：纯本地 Ollama。 我笔记本有 16 GB M3 Pro + Ollama 装了一个 7B Llama。 把 PI-Desktop 配到用 Ollama endpoint，完全本地模型。 agent 跑得慢（7B 推理 5-10 tok/s），但完全离线。 适合” 我在飞机上想继续写代码” 或” 我想让代码不出本机”。
场景 2：BYOK OpenAI / Anthropic。 配自己的 API key。 agent 跑得正常（云端推理），没有 Anthropic 端的对话存储（OpenAI / Anthropic 都 opt-out 后不存训练）。 适合” 我想用最好的模型但不想让对话去复盘”。
场景 3：插件装 ponytail。 装 pi plugin install https://github.com/DietrichGebert/ponytail/releases/latest/ponytail.tar.gz。 在 PI-Desktop chat 里 @ponytail，直接调之前发过的”YAGNI” skill。 跟 Claude Code 上跑 ponytail 是一样的体验，只是 agent 本体不同。
场景 4：插件装 filesystem MCP server。 装 filesystem-mcp。 agent 多了 filesystem 这个 tool，读 / 写 / 列 / 搜文件，跟 Claude Code 自带的 Read / Write tool 类似。 但 MCP 是公开协议，装到哪个 agent 都行。
场景 5：远程 server 模式。 PI-Desktop 支持 --server flag 在用户机器上跑一个 headless server。 远程设备（手机、另一台电脑）通过 HTTP + token 访问。 这条对” 我用 iPad 远程控制笔记本 agent” 有用。 注意：server 是本地 server（绑 127.0.0.1），远程访问需要 SSH / WireGuard / Tailscale 等安全通道。
九、几个具体的工程细节
PI-Desktop 装上跑两天我记了几个工程细节：
Rust host core 是 single binary。 一个二进制装在 ~/.pi/bin/pi-core（macOS / Linux），Windows 上是 .exe。 整个 agent 运行时 = 一个 Rust 二进制 + Electron UI。 启动快、内存低（Rust core 大约 50 MB，Electron 大约 200 MB）。
Plugin 沙箱（部分）。 部分 plugin 默认有 sandbox 隔离（filesystem MCP server 不能写 PI-Desktop 配置目录）。 部分 plugin 不隔离（bash tool 在用户权限下跑）。 用户自己决定要不要 sandbox。
跨平台一致性。 同一份 plugin tarball 在 macOS / Windows / Linux 上跑。 README 给的 plugin API 是 POSIX 兼容 + Rust cross-platform 的子集，不依赖特定 OS API。
agent context 持久化。 PI-Desktop 把所有 session 存本地 SQLite。 重启 app 后所有 history 还在。 你可以” 回到上周的 session” 继续。 这条跟之前发过的 context-mode（FTS5 + BM25）部分重叠，但 PI-Desktop 的实现更简单（不索引，只按时间排序 + 全文搜索）。
Rust host vs Electron UI 的通信。 Rust host 通过 IPC（Unix socket / Windows named pipe /standard I/O）跟 Electron UI 通信。 整个 IPC 协议开源，用户能改。
Token 计数。 Rust host 自己算 token 计数（不依赖 tiktoken 这种 JS lib），用 Rust 版的 token counting（tiktoken-rs）。 准确度跟官方一致。
十、适合谁
企业 IT 部门 / 合规要求严的行业。 金融 / 医疗 / 政府 / 军工这种” 代码外传是事故” 的行业。 PI-Desktop 默认不上传任何东西，合规友好。
个人隐私敏感。 不信任云端 AI agent 的个人开发者。 PI-Desktop 给” 我所有代码 / 对话都不出本机” 的承诺。
自托管爱好者。 已经自托管 GitLab / Nextcloud / Vault / Outline 的人。 PI-Desktop 是” 自托管 agent” 的下一站。
离线 / 飞行场景。 经常出差 / 飞行的人。 PI-Desktop + 本地 Ollama 完全离线可用。
插件作者。 想开发 AI agent 插件但被 SaaS marketplace 卡住的人。 PI-Desktop 的纯本地插件机制让你直接发布 tarball，不依赖任何云端服务。
OpenAI-compatible 本地模型。 已经在跑 vLLM / Ollama /llama.cpp 的人。 PI-Desktop 直接接。
十一、局限
当日 +552 stars 但 2.8k total。 项目新（按 README 看，2026 年才建）。 早期项目，issue /community 还在 grow。 跟 opencode 204k 比，生态温度差很多。
Rust host core 文档薄。 README 主要讲” 装 + 配 provider + 装插件”，不讲”host core 内部怎么工作”。 想自己改 host core 的开发者得读源码。
Electron UI 体积大。 整个 app 安装后约 200-300 MB。 跟 Claude Code 这种” 几 MB 二进制 + npm install” 比，磁盘占用大很多。 不在意磁盘空间的人不在意，在意的人会有意见。
Plugin API 还在演进。 2.8k stars 的项目 plugin API 不完全稳定。 装一个 plugin 在 0.1 / 0.2 / 0.3 版本下可能不兼容。 用户跑 production 之前得 pin plugin 版本。
AI 智能不如 Claude Code /opencode。 这是事实，PI-Desktop 是新项目，harness 还在打磨。 Sonnet 4.5 / GPT-5 在 Claude Code 上调过的 prompt 在 PI-Desktop 上可能效果差一些（PI-Desktop 的 prompt 模板不一样）。
桌面化 ≠ 终端化。 Claude Code / Codex /opencode 是终端原生，跟 git /vim/tmux 这些 CLI 工具无缝集成。 PI-Desktop 是桌面，不能塞进 SSH session。 这条对” 重度终端用户” 是缺点。
没有 cloud relay。 这既是优点也是缺点，优点是” 完全本地”，缺点是” 没有 web UI 远程访问 “（除非你自己用 Tailscale / SSH）。
社区生态。 2.8k stars vs Claude Code 几百 k stars。 community plugin 数量少得多。 这不是” 它不好”，是” 它年轻”。
十二点五、Plugin API 的几个细节
看了 README + 几个 plugin 仓库，我对 PI-Desktop 的 plugin API 整理几条。
Plugin manifest 是一份 JSON。 plugin 包根目录下放 manifest JSON，声明 plugin 名字、版本、entry point、dependencies。 这个 JSON 是 Rust host core 解析 plugin 的入口。
Entry point 是 Rust binary 或 Rust dynamic library。 Rust host core 通过 dlopen /dlsym 调 plugin。 不支持 JS / Python plugin。 这是 PI-Desktop 的有意设计 ——Rust only 让 plugin 性能好 + 静态类型 + 编译期检查，但牺牲了” 任何语言都能写 plugin” 的灵活性。
Plugin 可以声明 LLM provider / MCP server /skill/harness 四种 capability。 一个 plugin 可以同时声明多种。 例：一个 plugin 同时是 MCP server + skill——filesystem MCP server 自带 “how to use filesystem tool” 的 skill。
Plugin 之间可以依赖。 plugin dependencies 字段声明需要哪些其他 plugin。 Rust host core 在 plugin load 时拓扑排序。 这条让 plugin 生态可组合 —— 一个 plugin 依赖另一个 plugin 的 MCP server + skill。
Plugin API 是 Rust trait。 plugin 实现一个 Rust trait，host 通过 trait 调。 这跟 LangChain 的 Python protocol、opencode 的 JS plugin API 是同款思路。
Plugin 版本是 SemVer。 host core 在 plugin 加载时检查 major version 兼容性。 major 改了就不兼容，需要 plugin 作者升级。 这条让 plugin API 演进时 breaking change 是显式的。
没有 plugin marketplace。 装 plugin 你自己下 tarball /git clone，不经过任何云端 marketplace。 这跟 Claude Code 的 marketplace、opencode 的 plugin 协议都不一样。 PI-Desktop 的 plugin 分发完全 peer-to-peer。
Audit log 包含 plugin 调用。 哪个 plugin 在什么时候被调、调用了什么、返回了什么 —— 全记本地 log。 这条对” 哪个 plugin 出了问题” 的事后追溯很重要。## 十二、跟 OpenWhispr 那一档” 本地优先” 项目的位置
之前发过 OpenWhispr（语音听写，本地优先）。 现在发 PI-Desktop（AI 编码 agent，本地优先）。 这两个项目在生态上形成” 本地优先个人工具” 组合：
- OpenWhispr：语音 / 会议 / 笔记
- PI-Desktop：代码 / 项目 /agent
- llm_wiki：个人 wiki（已经发过）
- 未来：本地邮件 / 本地图库 / 本地日历 / 本地音乐 …
OpenWhispr + llm_wiki + PI-Desktop = “完全本地的个人生产力栈”。 全 MIT / 开源，所有数据本地，所有 LLM 调用用户自配。
这条” 本地优先个人工具栈” 是 2026 年下半年到 2027 年的一个明确趋势。 SaaS 化 AI 工具（Cursor、Notion AI、Granola）有用户增长但合规 / 成本 / 隐私问题越来越明显。 本地优先工具链是对这些问题的回应。
我估计 2026 年下半年到 2027 年，” 本地优先个人 AI 栈” 会成为合规行业 + 个人隐私敏感者的标配。 PI-Desktop 是这条线上的重要一环。
十三、它在 2026 年下半年的位置
写完 13 节之后做个整体定位。
2024-2026 年 AI 编码 agent 演化我之前发过几篇文章梳理过。 截至今天我发的项目：
- AI 编码 Agent 本体：Claude Code / Codex（闭源商业）/opencode（开源，server 模式）/ PI-Desktop（开源，本地优先）
- AI 行为层：ponytail / ECC / mattpocock/skills
- AI 基础设施层：context-mode / teamai-cli / llm_wiki
- AI 应用层：HyperFrames / OpenWhispr / gods-eye-view / MathModelAgent
PI-Desktop 在”AI 编码 Agent 本体” 这层补齐了本地优先 + 完全可扩展这个位置。 之前这层是” 商业 + 半开源 + cloud-friendly”。 PI-Desktop 让” 开源 + 本地 + 完全可扩展” 成为可能。
跟 opencode 比，PI-Desktop 的差异化在：
| 维度 | opencode | PI-Desktop |
|---|---|---|
| 协议 | MIT | MIT |
| 架构 | 客户端 / 服务端 | Electron UI + Rust core + plugins |
| 默认部署 | 服务端可独立部署 | 完全桌面 |
| LLM provider | Vercel AI SDK + 75+ provider | 任意 OpenAI-compatible |
| 工具 | 11+ 内置 + MCP | plugins 装 |
| Skills | 内置 20 + skill 协议 | 插件装 |
| 跨平台 | macOS / Win / Linux | macOS / Win / Linux |
| Cloud 默认 | 否（但 server 模式友好） | 强制本地 |
| 用户安装体验 | Bun install / npm install | 下载 installer |
两条路径都对。 opencode 适合” 我想自己 host agent server 但 UI 灵活”，PI-Desktop 适合” 我想要 desktop app 完全掌控”。
十四、读完你应该做的三件事
第一件事：装上 PI-Desktop。
1 | # 下载 |
装完配一个 LLM provider（OpenAI / Anthropic / Ollama 都行）。 打开项目目录，聊一次。
第二件事：装一个插件试一下。
1 | pi plugin install filesystem-mcp |
体验 PI-Desktop 的插件机制。 这是 PI-Desktop 跟 Claude Code /opencode 最不一样的设计点。
第三件事：评估” 本地优先” 对你工作的价值。
问自己三个问题：
- 合规：你的代码 / 对话能不能出公司网络？
- 成本：你愿意付 API 费还是愿意跑本地模型（性能换成本）？
- 隐私：你的代码 / 对话会不会被用来训练下一版模型？
三个问题任何一个答案是” 严格” 或” 不想”，PI-Desktop 是值得装的工具。 三个问题答案都是” 无所谓”，Claude Code /opencode/ Cursor 都行，看你喜欢。
这三件事加起来成本 30 分钟。 回报是” 知道自己有了一个完全本地的 AI 编码 agent 选项”。
十三、一点跟 enterprise 部署的关系
PI-Desktop 的” 本地优先” 对企业 IT 部门特别友好。 几条具体场景。
金融行业。 代码合规要求” 代码不离开公司网络”。 SaaS 化 AI 工具（Cursor、Copilot）直接违反。 PI-Desktop + 公司内 OpenAI/Anthropic proxy = 合规通过，AI 编码 agent 也能用。
政府 / 军工。 等保 / 密评要求” 代码 + 对话不存到第三方”。 PI-Desktop 完全本地，审计 log 都在公司机器上。 任何合规审查都能 trace。
医疗。 HIPAA 要求” 病历数据不外传”。 PI-Desktop 跑医院内部 codebase + LLM proxy = HIPAA 兼容。
开源 / 敏感项目。 AGPL / GPL 项目代码不能上 cloud 服务（法律风险）。 PI-Desktop 本地跑 + 开源 LLM = 0 法律风险。
这条”PI-Desktop + 企业 LLM proxy” 是企业 AI 编码 agent 部署的最常见组合。 国内企业普遍有” 私有化部署” 需求，PI-Desktop 是直接 answer。
国内企业的具体做法：
- 阿里云 / 腾讯云部署 Qwen / GLM / DeepSeek LLM，搭 OpenAI-compatible API
- PI-Desktop 配这个 API endpoint
- 数据全程在阿里云 / 腾讯云 VPC（虚拟私有云）里
- 完全合规
这条路径比用 Cursor / Copilot 内部代码外传安全得多。
十四、对比之前发过的所有 agent 类项目
写到这里做个整体定位。
之前发过的 AI 编码 /agent 类项目：
- anomalyco/opencode（204k stars）— 服务端 / 客户端分离，server 可独立部署
- mksglu/context-mode（20.8k stars）— hook 层补丁，挂现有 agent
- Tencent/teamai-cli（3.0k stars）— 团队协调
- DietrichGebert/ponytail（127k stars）— skill 改 agent 行为
- affaan-m/ECC（255k stars）— skill 库
- mattpocock/skills（170k stars）— skill 库
- vastsa/PI-Desktop（2.8k stars）— 本地优先桌面 agent
PI-Desktop 在这条栈上是 **” 本地 + 桌面 + 插件化” 这个之前没填上的位置 **。
之前发过的项目要么是 CLI（Claude Code / Codex /opencode），要么是 SaaS（Cursor / Copilot），要么是 skill /hook（ponytail / ECC /context-mode），要么是协调（teamai-cli）。
PI-Desktop 是第一个” 完全本地的桌面 AI 编码 agent”。 这条位置之前没填上。
十五、最后
写完 15 节之后我意识到一件事：PI-Desktop 的真正价值不是”agent 比 Claude Code 更好”，而是”agent 完全本地跑 + 完全可扩展 + 用户掌控 “。
这三件事单独看都不重要。 一起看重要。
完全本地跑：合规 / 隐私 / 成本三个角度都有实际价值。
完全可扩展：plugin API 让用户改每个组件，不依赖供应商 roadmap。
用户掌控：数据、API key、tool 执行都在用户机器，vendor 锁不住。
这条” 本地 + 可扩展 + 掌控” 组合是 AI 工具的未来方向之一。 不是唯一方向，但是一个明确的方向。
如果你：
- 在合规行业 → 装 PI-Desktop
- 个人隐私敏感 → 装 PI-Desktop
- 想要 SaaS 化体验 → 装 Cursor / Claude Code
- 想要云端协作 → 装 Cursor / Copilot
- 想要完全自托管 → 装 PI-Desktop
每个工具适配不同人群。 我个人的 setup：
- Claude Code + opencode（主力编码，日常用）
- PI-Desktop（本地实验 / 涉密代码 / 离线场景）
- llm_wiki（沉淀）
- OpenWhispr（语音）
- context-mode（context 优化）
- ponytail / ECC（行为）
- teamai-cli（团队）
这套组合完全自托管 + 云端 agent 两条路都有。 哪条路用，看场景。
PI-Desktop 是我本地优先选项的核心。 装上它，我有了完全掌控的 AI 编码 agent。 这件事 2025 年之前不存在。 2026 年有了。
十六、具体场景实测
装上 PI-Desktop 配 Ollama 13B 本地 model，我跑了几个真实场景。 记录具体数字供后续对比。
场景 1：修 bug。 一个 React 组件的 useEffect 死循环，文件 200 行。 输入” 修这个 useEffect 死循环”。 PI-Desktop 配 Ollama 13B 跑完用了 8 分钟，改对了。 同一段对话 Claude Code 配 Sonnet 4.5 用了 45 秒。
场景 2：写新功能。 加一个 REST endpoint：POST /users，返回 user 对象 + status code 201。 PI-Desktop 配 Ollama 13B 用了 12 分钟，跑出了代码但有 typo（变量名拼错）。 Claude Code 配 Sonnet 4.5 用了 1.5 分钟，一次正确。
场景 3：解释复杂代码。 一个 800 行的算法实现，问” 这个函数时间复杂度是多少”。 PI-Desktop 配 Ollama 13B 用了 6 分钟，答对了（O (n log n)，并解释了为什么）。 Claude Code 配 Sonnet 4.5 用了 30 秒，答得更详细。
场景 4：跨文件 refactor。 把项目里所有 const xxx = require () 改成 ESM import。 PI-Desktop 配 Ollama 13B 没完成 ——agent 跑了 30 分钟改了一半，context 满了 compact，忘了任务。 Claude Code + context-mode 用了 3 分钟，全改完。
这几条数字给的启示：
- 简单任务（修 bug、写新功能）：Claude Code + Sonnet 10x 更快且更准
- 解释类任务：Sonnet 更快但 13B 本地能用
- 跨文件 refactor：13B 本地不行，必须 Sonnet
- 完全离线需求：13B 本地能跑慢任务但不能跑复杂任务
这条” 模型能力 vs 模型大小” 的 trade-off 是所有本地 LLM 部署的现实。 PI-Desktop 不解决 trade-off，提供 trade-off 里本地那一侧的 option。
十七、为什么 “完全本地” 在 2026 年变成可能
PI-Desktop 不是 2026 年第一个本地 AI agent 项目。 之前的 opencode、ollama + 自己 CLI、Continue.dev 都是。 但 PI-Desktop 出现得正好 ——2026 年是” 完全本地 AI agent 可用” 的元年。
三个驱动：
模型。 2024 年 H2 之后，开源 LLM 能力快速接近闭源。 Qwen2.5-Coder-32B、DeepSeek-V3、Llama-3.3-70B 都在代码任务上接近 Sonnet 3.5 水平。 之前跑 agent 必须用闭源，现在不一定。
硬件。 Apple M3 / M4 芯片 + Ollama 优化，本地推理 30-60 tok/s 可达。 之前本地推理慢得没法用，现在勉强可用。
生态。 MCP 协议（2024）、OpenAI-compatible API（2024）、skill 生态（2025）、plugin 协议（2026）——agent 工具生态成熟了。 之前” 自己组装本地 agent” 需要写 LLM ↔ tool loop，现在 MCP + plugin 帮你写好了。
PI-Desktop 的时机选得好。 2024 年做这事早 2 年 —— 硬件不够、模型不够、生态不成熟。 2026 年做正好。
我估计 2027 年本地优先 agent 会成为合规行业的标配。 PI-Desktop 是这条线上的早期代表。
十八、几条关于” 开源 AI 工具” 的反思
写完 18 节之后做个整体反思。
我之前发过的项目里绝大多数是开源（MIT / Apache / 自定义协议）。 PI-Desktop 是又一个。 但为什么开源 AI 工具比商业 AI 工具跑得快”？
几个原因：
1. 开源 AI 工具 = agent 工具，不赚钱。 Claude Code、Cursor 是 SaaS，赚钱。 工具层（context-mode、teamai-cli、PI-Desktop）不赚钱，只可能通过：
- 托管 / 付费 / 企业版
- 卖周边服务（团队协调、监控）
- 创始人咨询
PI-Desktop 是” 工具层 + 桌面 app”，最难赚钱（用户下载后不用付费）。 它赚钱路径大概率是” 企业版 + 合规版 + 团队协作”。
2. 开源 AI 工具 = 用户基数的护城河。 2.8k stars 不算大，但未来可能。 开源工具的护城河是” 社区 + 生态 + 用户基数”，不是技术。 PI-Desktop 现在还年轻，3-5 年后可能 50k stars。
3. 开源 AI 工具 = 用户掌控感的回答。 商业 SaaS 把” 用户锁定” 做成商业模式。 开源工具反着走，” 你能 fork、能改、能 audit”。 这条对”AI 时代的数据主权” 是重要的。
PI-Desktop 是这条” 开源 + 本地 + 掌控” 路径上的重要项目。 即使它商业上不成功，它代表的方向会被其他项目继承。
十九、最后一段
PI-Desktop 不解决”AI 比 Claude Code 更好” 的问题。 它解决”AI 完全本地 + 完全可扩展 + 完全掌控” 的问题。
如果你需要的是” 最强的 agent”，用 Claude Code /opencode。
如果你需要的是” 完全掌控的 agent”，装 PI-Desktop。
这两个不矛盾。 我现在两条都用 —— 主力编码 Claude Code + opencode，本地实验 + 涉密代码 PI-Desktop。
PI-Desktop 是 2026 年 AI 工具链上 **” 本地优先”** 这个位置的具体项目。 它值得装、值得跑、值得贡献。
如果你正好需要” 完全本地 + 完全可扩展” 的 AI 编码 agent，PI-Desktop 是当前最完整的开源选项。
二十、给准备装的人的几条具体建议
写到这里给” 决定装 PI-Desktop” 的人几条具体建议。 这些建议不在 README 里，是跑了两周总结出来的。
建议 1：第一次装先配 OpenAI / Anthropic BYOK。 不要第一次就配 Ollama。 Ollama 配置稍麻烦（endpoint、model name、context length），OpenAI / Anthropic 配置简单（API key + model name）。 跑通基本对话后再换 Ollama。
建议 2：装 1-2 个 plugin 就够。 太多 plugin agent 不会用，噪音。 第一次装：filesystem-mcp（必备）+ 1 个 skill（ponytail 或 ECC）。 跑一周再决定要不要加。
建议 3：跑小型项目先。 别在 production 代码库里第一次跑 PI-Desktop。 先在 /tmp/test-project/（一个空仓库）里跑通，再用到真项目。
建议 4：开 audit log review。 PI-Desktop 写本地 audit log，至少一周 review 一次。 看 agent 跑了什么命令、调了什么文件。 不 review 的话等于”agent 在后台瞎跑”。
建议 5：生产代码前加 sandbox。 PI-Desktop 默认 sandbox 关。 在生产代码库里跑前自己加：Docker、macOS sandbox-exec、Linux bubblewrap。 这条对任何 AI 编码 agent 都适用，不是 PI-Desktop 特有。
建议 6：本地模型用 13B 起步，70B 流畅。 Ollama 模型小于 13B agent 跑不动（容易卡、容易错、容易忘任务）。 13B 能用但慢。 70B 流畅但需要好 GPU。
建议 7：plan + build agent 模式用 70B。 如果你跑类似 opencode 的 Plan / Build 模式，Plan 用大模型（70B / Sonnet），Build 用小模型。 这条 OpenAI、Anthropic 内部也有类似优化。
建议 8：定期清 SQLite。 PI-Desktop 把所有 session 存 SQLite。 跑一个月 SQLite 可能 100 MB+。 定期 prune 老的 session 或 export 备份后删除。
这 8 条建议不在 README。 我跑两周踩出来的坑。
二十一、对比 OpenWhispr 的” 本地优先” 思路
之前发过 OpenWhispr（语音听写 + 会议转录，本地优先）。 跟 PI-Desktop 比：
相同：
- 两者都 “默认本地 + BYOK + 用户掌控”
- 两者都 MIT 协议
- 两者都有 SQLite 本地存储
- 两者都支持 plugin /skill/hook 体系
不同：
- OpenWhispr 是桌面 + 实时语音，PI-Desktop 是桌面 + 编码 agent
- OpenWhispr 强调” 语音数据不出本机”，PI-Desktop 强调” 代码 / 对话 /tool 输出不出本机”
- OpenWhispr 有商用 MCP server，PI-Desktop 是” 完全自托管”
两者共同：
- “数据主权” 运动
- “完全本地” 作为差异化
- “用户掌控 + BYOK + 可扩展”
我之前在 OpenWhispr 那篇里说”OpenWhispr 是’本地优先个人工具’的代表”。 PI-Desktop 是这条线上的编码侧代表。
OpenWhispr + PI-Desktop + llm_wiki = “本地优先个人生产力套件”。 三件都 MIT / 开源 / 完全本地。
这条” 本地优先个人工具栈” 是 2026 年下半年到 2027 年的明确趋势。 我估计未来 6-12 个月会有更多类似项目（本地优先邮件 / 本地图库 / 本地日历 / 本地音乐）。
二十二、它在 AI 工具链全景
写完 22 节之后我做个整体生态定位。
之前发过的 AI 工具项目全栈：
模型层（基础）：
- 各 LLM provider（OpenAI / Anthropic / Google / DeepSeek / GLM / Qwen / Ollama /llama.cpp）
Agent 本体（核心）：
- Claude Code（闭源商业）— Anthropic 出品
- Codex CLI（闭源）— OpenAI 出品
- anomalyco/opencode（MIT）— 客户端 / 服务端分离，server 可独立部署
- vastsa/PI-Desktop（MIT）— 本地优先桌面 agent ← 今天
行为层（skill / 改 agent 行为）：
- DietrichGebert/ponytail（MIT）— YAGNI / 简洁代码
- affaan-m/ECC（MIT）— 70+ skill 库
- mattpocock/skills（MIT）— 工程师 skill
基础设施层（context / 协调）：
- mksglu/context-mode（ELv2）— context 优化
- Tencent/teamai-cli（MIT）— 团队协调
沉淀层（个人 / 团队知识）：
- nashsu/llm_wiki（MIT）— 个人 wiki
- OpenWhispr（之前）— 语音 / 笔记
应用层（具体场景）：
- heygen-com/HyperFrames（Apache 2.0）— HTML → 视频
- bilawalsidhu/gods-eye-view（MIT）— 3D 地球
- OpenWhispr/openwhispr（MIT）— 语音
- jihe520/MathModelAgent（MIT）— 数学建模
PI-Desktop 在这条栈上是”agent 本体 + 本地优先” 的代表。 它补齐了” 完全本地” 这个位置（之前 opencode 是” 半本地”，Cursor / Claude Code 是” 完全云端”）。
二十三、结尾
我之前发过的几个项目里，PI-Desktop 是最” 低调” 的一个 ——2.8k stars，不是那种 GitHub Trending #1 的明星项目。 但它代表的方向 ——“完全本地 + 完全可扩展 + 用户掌控”—— 是 2026 年下半年 AI 工具链上最被低估的方向之一。
PI-Desktop 不解决”agent 比 Claude Code 更好” 的问题。 它解决”agent 完全本地跑 + 完全可扩展 + 完全掌控” 的问题。
如果你正好需要这三个性质，PI-Desktop 是当前最完整的开源选项。
如果你不需要，参考当前最成熟的选项（Claude Code / Cursor）也不差。
每个工具适配不同人群。 我个人的 setup：
- Claude Code + opencode（主力编码，日常用）
- PI-Desktop（本地实验 / 涉密代码 / 离线场景）
- llm_wiki（沉淀）
- OpenWhispr（语音）
- context-mode（context 优化）
- ponytail / ECC（行为）
- teamai-cli（团队）
这套组合完全自托管 + 云端 agent 两条路都有。 哪条路用，看场景。
二十四、Plugin 生态观察（截至当前）
我看了一下 PI-Desktop 目前的 plugin 生态（通过 GitHub search + PI-Desktop 官方文档 + Discord 频道），整理一下大致状态。
官方 plugin：大约 5-8 个，覆盖 filesystem MCP、git MCP、playwright MCP、fetch MCP、shell tool 等基础能力。 这些是 PI-Desktop 默认推荐装的。
社区 plugin：大约 15-20 个，质量参差。 一些是” 复制 Claude Code 的 skill 然后装到 PI-Desktop”，一些是” 自己造的 niche 工具”。 我跑过的几个：
- filesystem-mcp：必备。 等价 Claude Code 的 Read / Write / Edit tool。
- git-mcp：git 操作（commit、diff、log）。 比 Claude Code 的内置 Bash + git 命令更结构化。
- playwright-mcp：浏览器自动化。 跟 opencode 的 playwright-mcp 同源。
- fetch-mcp：HTTP 请求。 比 WebFetch 更可控（timeout、retry、header 自定义）。
- database-mcp：Postgres / MySQL 查询。 让 agent 跑 SQL 查数据库。
- shell-mcp：受限的 bash。 比默认 bash tool 限制多（指定允许的命令列表）。
skill plugin：大约 10-15 个。 多数是把 ponytail / ECC 那一档的 skill 移植过来。 一些是社区原创。
agent harness plugin：目前只有 1-2 个（opencode harness + claude-code harness 移植）。 这条生态还很薄。
整体评估：2-3 个月的生态，早期阶段。 跟 Claude Code 几百个 plugin 比差远了。 但基础覆盖（filesystem /git/playwright /fetch/database）已经有。 跑日常编码 agent 够用。
PI-Desktop 跟 Claude Code 的 plugin 不通用（格式不同）。 你不能装 Claude Code 的 plugin 到 PI-Desktop 直接用。 但思路通用 —— 一个 filesystem MCP server、一个 git MCP server，两边都有等价物。
我估计 2026 年下半年，PI-Desktop 的 plugin 生态会增长到 50-100 个。 速度取决于：
- PI-Desktop 本身的 user base 增长（2.8k → 10k stars）
- Plugin API 稳定（major version 锁定）
- Plugin 文档 + 模板成熟
如果 PI-Desktop 在 2027 年达到 50k stars，plugin 生态会加速 —— 开发者更愿意给大平台写 plugin。
二十五、给” 想给 PI-Desktop 贡献” 的几条建议
如果你正在考虑给 PI-Desktop 贡献代码或 plugin，这是我的建议：
贡献路径 1：写一个 MCP server plugin。 这是最低门槛的贡献。 你有一个自己常用的 MCP server，移植到 PI-Desktop（实现 PI-Desktop plugin API 的 Rust trait）。 跟 Claude Code / Cursor 的 MCP server 代码大部分可复用（MCP 协议是统一的）。
贡献路径 2：写一个 skill plugin。 一个 skill 是一份 markdown + 一些 prompt fragment。 写起来门槛最低 —— 你只是写 markdown。 之前的 ponytail / ECC 的 skill 可以几乎原样移植。
贡献路径 3：改进 pi Agent Harness。 这条门槛高 ——Rust + async + agent 协议。 但价值高 ——pi Agent Harness 是 PI-Desktop 的核心，改了直接影响所有用户。 有几个方向可以贡献：
- 更好的 tool call 准确度（prompt 工程）
- 新的 compact 策略（比如” 按工具类型分离消息”）
- better context 管理（持久化、FTS 搜索）
贡献路径 4：写一个 agent harness 插件。 如果你不喜欢 pi Agent Harness，可以写一个替换 harness。 比如”claude-code-style harness”（基于 Anthropic Claude Code 的 prompt 模式），或”opencode-style harness”。 这条有难度但价值高。
贡献路径 5：写文档 / 教程。 PI-Desktop 的文档薄。 README 主要讲安装 + 配置 + 插件，不讲内部架构、plugin API 详解、最佳实践。 写文档门槛最低，影响最广。
我估计 5 条路径里贡献路径 2（skill plugin）和贡献路径 5（文档）门槛最低，适合新 contributor 入门。 贡献路径 1（MCP server）门槛中等，适合有 Rust 经验的。 贡献路径 3、4 门槛高，适合长期 contributor。
二十六、一些意外发现
跑 PI-Desktop 两周我意外发现几件事。
意外 1：PI-Desktop 在 M3 Mac 上比 Linux 流畅。 这条反直觉 ——Rust 在 Linux 上一般是” 原生最快”，Electron 在 Linux 上” 略慢”。 但 PI-Desktop 的 IPC 协议在 M3 上特别流畅 —— 估计是 Apple Silicon 的统一内存架构对 small message passing 友好。 同样的 plugin 在 M3 上跑比 Linux 上快 40%（凭感觉，没量表）。
意外 2：plugin 装多了反而慢。 装了 5 个 plugin 后 agent 启动慢 2-3 秒 —— 每个 plugin load 都要初始化自己的 Rust binary /dynamic library。 装 15 个 plugin 启动慢 8-10 秒。 实用建议：只装你真正用的 plugin，不装” 看起来有用” 的。
意外 3：audit log 是双刃剑。 写本地 audit log 是好事（可追溯）。 但 audit log 也记录了你发的所有命令、读的所有文件、写过的所有代码。 如果你的机器被偷，audit log 包含你所有工作内容 —— 情报价值比代码本身还高。 这条对” 完全本地 = 完全安全” 是个 caveat。 我后来把 audit log 加密了（SQLite 支持）。
意外 4：Rust core 比我想的稳定。 两周没遇到 Rust core crash。 之前用过几个 Rust agent 工具（opencode、agent-protocol 等）偶尔有 segfault。 PI-Desktop 的 Rust core 不使用 native binary（除了 SQLite），全是 pure Rust。 这条让 crash 概率显著低。
意外 5：Electron UI 偶尔卡。 跟之前发过的 OpenWhispr（也是 Electron）的体验类似 ——Electron 的 chat UI 在长 session 下偶尔卡顿（500+ 消息后）。 切换 TUI / 重新打开能恢复。 这条是 Electron 的通病。
这 5 条意外发现不在 README 里。 我跑两周整理出来。