Pinvou/pinvou-agent · 上手攻略

  • 仓库：Pinvou/pinvou-agent
  • 链接：https://github.com/Pinvou/pinvou-agent
  • 分类：桌面 AI Agent · 多 Agent 协作 · MCP
  • 作者：Tom
  • 更新：2026-08-23

这是什么

Pinvou Agent 是一个开源桌面 AI Agent 工作空间，基于 Tauri 2 + React + Vite 构建。不是聊天窗口，而是把日常办公、视觉设计、软件开发都收进一个桌面应用——用工具、操作文件、构建个人知识库，把 prompt 变成可继续编辑的真实成果。

核心定位：让 AI agent 真正交付结果，而不只是生成一段文字。

支持本地模型（完全隐私闭环）、任何 OpenAI 兼容端点，可通过 MCP 服务器、CLI 连接器、Skills 和 workflows 扩展。通过 ACP 协议接入 Codex、Claude Code、Kimi 等编码 Agent，实现在同一桌面工作空间里操作真实项目。

解决什么问题

现有 AI 工具的常见困境：

  • 聊天结束 = 工作结束：大多数 AI 对话产出一段文字，没有后续
  • 工具分散：浏览器、IDE、知识库、聊天窗口来回切换
  • Agent 能力断在沙盒里：能跑代码但改不了真实项目文件
  • 隐私与便利难以兼得：本地模型安全但能力弱，云端模型强但数据外流

Pinvou Agent 的解法： - artifact 面板：Agent 创建或编辑的每个文件自动收集在一个面板，支持预览、定位、直接打开 - 多 Agent 协作：通过 ACP 在同一工作空间跑 Codex / Claude Code / Kimi，多个 agent 协同完成复杂任务 - 本地优先：本地 vLLM + 本地工具 = 完全本地闭环；需要云端模型时也支持 - 知识库 + 记忆：本地向量库 + 长期记忆 center，不需要每次从头说明上下文

快速安装

前置要求

  • Git（支持 submodule）
  • Node.js + npm
  • Rust toolchain（当前）
  • Tauri 2 系统依赖（官方前置文档）
  • 一个可访问的 OpenAI 兼容模型端点

构建（Linux / macOS / Windows）

git clone --recursive https://github.com/Pinvou/pinvou-agent.git
cd pinvou-agent/pinvou3-app
npm ci
cd ..
./pinvou3-app/run-dev.sh

如果 clone 时没有 submodule：

git submodule update --init --recursive

开发调试命令

# Lint UI
(cd pinvou3-app && npm run lint:ui)

# 构建 UI
(cd pinvou3-app && npm run build:ui)

# 运行测试
(cd pinvou3-app && npm run test)

# Rust lib 测试（单线程）
(cd pinvou3-app/src-tauri && cargo test --lib -- --test-threads=1)

# Fork 安全检查
./scripts/fork-guard.sh --fast

本地 vLLM 配置

# 环境变量方式
export DEEPSEEK_BASE_URL="http://127.0.0.1:8000/v1"
export DEEPSEEK_API_KEY="local-no-auth"
export DEEPSEEK_MODEL="your-model-name"

# 或直接在应用设置中配置端点、模型名、API key
# 支持自定义兼容端点（非回环地址需设置 DEEPSEEK_ALLOW_INSECURE_HTTP=1）

内置模板覆盖：本地 vLLM、DeepSeek、Kimi、Qwen、Doubao、MiniMax、Zhipu、MiMo。

支持的平台

  • Linux：Ubuntu 22.04+（glibc 2.35+），x86_64 和 arm64；需 WebKitGTK 2.40+
  • macOS：Apple Silicon，macOS 11+
  • Windows：Tauri 2 官方支持

核心架构

React + Vite UI
     ↕（Tauri commands / events）
pinvou3-app（桌面编排）
     ↕（EngineHandle / AgentHarness）
CodeWhale（Agent 引擎 submodule）
  ├─ OpenAI 兼容模型服务
  ├─ MCP servers + CLI 连接器
  └─ Skills · Commands · Hooks · Compaction

扩展边界：

目标 放入位置
新增领域 agent 或工具包 SKILL.md 包
连接外部 API 独立 MCP server 或连接器
指导模型行为 指令包（instructions.md）
改桌面 UI 或系统集成 pinvou3-app/

核心用法

多 Session 工作区

  • 每个 Session 绑定独立工作空间，消息、工具调用、artifact 持久化
  • 支持标题搜索，Session 可在重启后继续
  • Plan / YOLO 两种模式：复杂任务先看计划再执行，清晰任务直接跑

Artifact 面板

Agent 创建或编辑的每个文件自动进入 artifact 面板： - 预览、定位、在系统中打开 - 支持直接编辑 Markdown artifact，选中文本让 agent 修订

编码 Agent（ACP 协议）

通过 ACP 接入 Codex / Claude Code / Kimi：

# 配置示例（在应用设置或环境变量）
# ACP 协议让编码 agent 能读写真实项目文件
  • Agent 可以操作真实项目或独立临时工作空间
  • 运行命令并回传计划、工具步骤、权限请求、文件变更
  • Session 绑定工作空间，重启后继续

本地知识库

  • 文件管理 + 全文检索 + 向量检索
  • 多个 collection 可Attach 到同一聊天，独立开关
  • 回答中保留 collection 和文件来源信息

记忆中心（Memory Center）

  • 长期偏好和上下文记忆
  • 明确的候选记忆审核和确认流程

MCP 工具生态

  • 本地 MCP servers
  • 远程 MCP servers
  • CLI 工具
  • API 连接器

内置连接器：飞书（Lark）、钉钉、企业微信、腾讯会议、腾讯ima、Obsidian、企业知识库、法律/企业数据服务。

手机遥控

扫描桌面二维码，用手机查看和操控当前工作空间。

典型适用场景

  1. 本地隐私 AI 工作站：完全本地模型 + 本地工具，数据不离开机器
  2. 复杂多步骤任务：文件生成 → 修改 → 保存 → artifact 管理全链路
  3. 编码 Agent 接入真实项目：通过 ACP 让 Claude Code / Codex 操作生产代码库
  4. 多工具联动：MCP 接入飞书、钉钉等企业工具，Agent 直接读写业务系统
  5. 视觉生成 + 继续编辑：prompt 生成海报/数据可视化 → design mode 继续微调

坑与注意

  1. macOS 初始版仅支持 Apple Silicon：Intel Mac 版尚未发布
  2. Linux 要求 WebKitGTK 2.40+：Ubuntu 22.04 标准更新仓库可满足，但需确认系统版本
  3. 数据是否离开本机取决于你开启的工具：本地模型+本地工具=完全本地；云端模型+远程 MCP=数据出境
  4. CodeWhale 是 submodule：clone 时 --recursive 或后续 git submodule update --init --recursive，否则 engine 缺失
  5. fork-guard.sh --fast 是开发安全检查：提 PR 前应通过此检查
  6. 非回环 HTTP 端点需显式设置 DEEPSEEK_ALLOW_INSECURE_HTTP=1：仅限可信开发网络
  7. Session 数据保存在 ~/.pinvou3/：包括设置、知识库、运行时扩展，重装前记得备份
  8. Windows 需 Tauri 2 前置依赖：参考官方文档提前安装 Rust 和必要工具链
  9. 连接器（飞书/钉钉等）需要额外配置 OAuth/SSO：应用内设置向导引导完成

与同类对比

方案 平台 编码 Agent 本地模型 扩展方式
Pinvou Agent 桌面（Tauri 2） Codex/Claude Code/Kimi（ACP） vLLM MCP + Skills + CLI
ChatGPT（桌面） Web/桌面 无 无 Plugins
Claude（桌面） Web/桌面 无 无 Artifacts
VS Code + Copilot IDE 部分（Copilot Chat） 无 Extensions
Cursor IDE 是（Composer） 部分 Plugins
Continue（IDE plugin） VS Code/JetBrains 是 是 MCP

Pinvou Agent 的差异化在于真正的桌面 Agent 工作空间——不是 IDE 插件，是独立桌面应用；不是单 Agent，是 ACP 协议下的多 Agent 协作；artifact 面板让产出从"文字"变成"文件"。

一句话推荐结论

桌面 AI Agent 的完整工作空间——Tauri 2 跨平台应用，artifact 交付真实文件，本地 vLLM 保证隐私，ACP 协议接入 Codex/Claude Code 作用于真实代码库，适合需要 AI 真正完成工作而非只生成文字的用户。（⚠️ macOS 版仅 Apple Silicon；非回环 HTTP 端点需额外配置；clone 时勿忘 --recursive）

来源：GitHub README (https://github.com/Pinvou/pinvou-agent) · Web 搜索（补充 Tauri 2 / MCP 相关 2026）

待验证：具体 ACP 协议配置步骤、飞书/钉钉连接器 OAuth 配置详细流程、CodeWhale submodule 独立仓库地址及版本策略。