Skip to content
vcqr
pidock
Public

About

PI agent desktop app

Topics

agentagent-skillsagentic-aidesktopdesktop-apppi

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

PiDock

PiDock 是 pi coding agent 的桌面驾驶舱与云端镜像。

本地运行 pi agent 的桌面工具（对标 Codex 桌面版），所有会话状态实时同步到远程 server， 在 web 端以账号身份查看并完全控制（发 prompt / steer / abort / 工具审批）。

完整架构设计、决策理由与踩坑记录见 docs/DESIGN.md。

项目介绍

核心能力

  • 桌面端（Tauri 2 + Vue 3）：多会话管理与项目分组、流式输出、工具实时卡片、 edit/write 红绿 diff 视图、双主题、设置中心（Providers / 模型 / 扩展 / 技能 / MCP）、 专家智能体、系统托盘
  • Web 运行方式（无头服务）：同一套桌面 UI 与核心跑成 pidock-webhost 服务， 浏览器直接访问，可打包成 Docker 镜像部署在服务器/NAS 上
  • 云同步：桌面事件经 sync-agent 上报，Kafka 管道 → ingest → MongoDB 持久化， Redis pub/sub → WebSocket 推送到 web 端，近流式体验
  • Web 端：登录后按账号查看全部节点与会话，可远程发消息、插话、中止、审批工具调用， 支持节点卡片墙、详情浮层、头部搜索过滤
  • 附件数据面：大 payload（>256KB）自动附件化，sha256 内容寻址 + 预览， 全文经 SigV4 presign 直传对象存储（RustFS / S3）
  • 发布：GitHub Actions 多平台矩阵，tag 触发 Windows / macOS / Linux（x64 + ARM64） 安装包构建，pi-host 以 sidecar 形式打包，安装后不依赖本机 Node/Bun

架构

Tauri 2 (Rust core + Vue UI)
  ├─ host-supervisor ── stdio JSONL ── pi-host (bun compile 单 exe)
  │                                     └─ 嵌入 @earendil-works/pi-coding-agent
  │                                        多 session / 三通道事件 / 配置面
  └─ sync-agent ── WSS ── axum server ── Kafka ── ingest ── MongoDB
                                          └─ Redis pub/sub ── web WS 推送

核心运行时抽在 crates/pidock-core（supervisor / 定时任务调度器 / 云同步 agent）， 与 UI 壳解耦，两个壳共用：

  • Tauri 桌面壳：webview 窗口 + 托盘 + 原生对话框；
  • apps/webhost 无头壳：axum 托管同一套桌面前端（编译期嵌入），/ws 把 ipc(cmd, args) 请求桥接到 CoreCtx::handle、事件广播实时推给浏览器—— 与 Tauri invoke/pidock:event 同语义，因此浏览器里就是完整的桌面 UI。

事件模型分三通道：delta 级（message_delta，仅本地 UI）、快照级 （message_snapshot，2s 节流推 web 不落库）、消息级（message_complete / session_meta 等，落库幂等键 (session_id, seq, kind)）。细节见 DESIGN.md。

目录结构

crates/pidock-protocol/  统一线路协议（Rust serde + ts-rs 导出 TS）
crates/pidock-core/      运行时核心：supervisor / 调度器 / 云同步（与 UI 壳解耦）
packages/protocol/       协议 payload 权威 TS 定义（host 与 ui 共用）
host/                    pi-host：stdio 守护进程，嵌入 pi SDK
packages/ui/             桌面与 web 共用的 Vue 组件 + DataBus + store
apps/desktop/            Tauri 2 桌面应用（src-tauri 为 Rust 壳）
apps/webhost/            无头 Web 壳：axum 静态托管桌面 UI + WS IPC 桥（Docker 友好）
apps/web/                web 前端（Vue 3）
apps/server/             axum server（Rust：WS 网关 / Kafka 管道 / REST / 静态托管）
docker/                  kafka + mongo + redis + rustfs + server + webhost 编排
docs/                    架构设计文档与代码审查报告

运行与部署

前置条件

  • Node.js ≥ 22 与 pnpm 10（corepack 可自动管理）
  • Bun（运行 pi-host 源码与编译单文件）
  • Rust stable（rustup，edition 2021）
  • Docker（Windows 建议 WSL 内的 docker）
  • 可用的 LLM API Key（pi provider，如 Anthropic / OpenAI，用于真实会话）

本地运行（开发模式）

# 1. 基础设施（容器 healthy 后即用）
cd docker && docker compose up -d kafka mongo redis rustfs && cd ..

# 2. server（:8080；Windows cmd 示例，bash 用 export）
set PIDOCK_MONGO_URI=mongodb://localhost:27017&& set PIDOCK_REDIS_URL=redis://localhost:6379&& set PIDOCK_KAFKA_BROKERS=localhost:9092&& cargo run -p pidock-server

# 3. web（:5174）
pnpm --filter @pidock/web dev

# 4. 桌面应用（开发模式跑 bun 源码 host）
pnpm --filter @pidock/desktop tauri dev

桌面端环境变量（默认即可用）：PIDOCK_HOST_CMD（默认 bun）、 PIDOCK_HOST_ARGS（默认 src/main.ts）、PIDOCK_HOST_DIR（默认 <repo>/host）。

  • web 端登录页填 server 地址（默认 http://localhost:8080）注册/登录
  • 桌面端 ☁ 面板配置 server 地址开启云同步

Docker 部署 server（生产形态）

# web 前端在镜像内构建并嵌入 server 二进制（单文件），容器同时提供 REST/WS 与 web
cd docker && docker compose up -d --build server

不打 Docker 的话，GitHub Release 页有 pidock-server-x86_64-linux.tar.gz （web 已嵌入，解压即用，附带 pidock.example.toml 配置示例）。

Web 运行方式（无头服务 / Docker）

不需要桌面窗口时（服务器、NAS、Docker），桌面核心可以跑成 pidock-webhost 服务：浏览器打开即完整的桌面 UI（多会话、流式输出、定时任务、专家、设置中心）， pi-host 就在该机器上运行。

# 本地跑（debug 构建直接读 apps/desktop/dist，改前端即生效）
pnpm --filter @pidock/desktop build
cargo run -p pidock-webhost      # http://localhost:8091

# Docker（镜像内构建前端并嵌入，含 pi-host sidecar，单容器即用）
cd docker && docker compose --profile webhost up -d --build webhost
  • 会话与配置持久化在 webhost_data 卷（/data：.pi agent 目录 + .pidock-web 配置）， 重建容器不丢数据
  • 定时任务 cron 按 TZ 本地时区触发（compose 默认 Asia/Shanghai）
  • 公网/不可信网络务必设 PIDOCK_WEB_TOKEN：/ws 需要匹配令牌， 浏览器首次连接会弹窗询问，输入一次即记住（localStorage）
  • pi-host 拉起方式与桌面端一致：release 镜像内默认拉起同目录 sidecar pidock-host，源码调试可用 PIDOCK_HOST_CMD / PIDOCK_HOST_DIR / PIDOCK_HOST_ARGS
  • 形态差异：原生目录/文件选择器、托盘、系统通知在 Web 形态不可用（相关操作自动降级）
  • 云同步可用性不变：webhost 同样能在设置中心配置 server 地址与访问令牌，把本地 会话镜像到云端，由 web 控制台远程查看与控制

server 配置

全部走环境变量即可运行（PIDOCK_MONGO_URI / PIDOCK_REDIS_URL / PIDOCK_KAFKA_BROKERS / PIDOCK_JWT_SECRET / PIDOCK_RUSTFS_* 等，均有默认值）。 要用配置文件：把 pidock.example.toml 复制为 pidock.toml 修改后 ./pidock-server --config pidock.toml（不指定参数时自动读当前目录的 pidock.toml；优先级 环境变量 > 配置文件 > 内置默认值）。

可配置项（docker-compose 已给默认值）：PIDOCK_JWT_SECRET、 RUSTFS_ROOT_USER / RUSTFS_ROOT_PASSWORD、PIDOCK_PIPELINE（kafka，可选 redis 降级）。

注册与邀请码

对外提供服务时注册必须凭邀请码：管理员在 web 控制台首页「邀请码管理」里 生成（可设可用次数/有效天数），使用者注册时填入即可。 首个管理员用引导邀请码创建：部署时设置 PIDOCK_BOOTSTRAP_INVITE=<自定义邀请码> （或配置文件 [server].bootstrap_invite），用它注册的第一个账号自动成为管理员， 产生管理员后该码即失效；老部署升级会自动把最早注册的账号提为管理员。 配套接口：POST/GET /admin/invites、DELETE /admin/invites/{code}（均要求 admin 角色）。

打包桌面安装包

pnpm bundle:app
# 1. pi-host 编译为单 exe → apps/desktop/src-tauri/binaries/pidock-host-<triple>.exe
# 2. tauri build → NSIS 安装包输出 apps/desktop/src-tauri/target/release/bundle/nsis/

安装后的桌面端自动 spawn 同目录的 pidock-host.exe（sidecar），云同步、附件、 远程控制全部可用。

发布

打 tag（v*）推送即触发 GitHub Actions Release 工作流，构建 6 平台矩阵 （Windows x64/ARM64、macOS Intel/Apple Silicon、Linux x64/ARM64）并上传产物。

开发

常用命令

pnpm install                               # 安装依赖
pnpm build                                 # 全仓构建
pnpm -r typecheck                          # 全仓类型检查

pnpm --filter @pidock/host smoke           # host 全链路冒烟（发起真实 LLM 调用）
pnpm --filter @pidock/host smoke:config    # 配置面冒烟（隔离 agent 目录）
pnpm --filter @pidock/host smoke:extension # jiti 扩展 × bun-compile 验证
pnpm --filter @pidock/host e2e:server      # 端到端验收（server 需在跑）

cargo test -p pidock-protocol              # 协议 crate 测试 + 导出 TS 绑定
cargo run -p pidock-server                 # 启动 server

协议同步

线路协议权威定义在 crates/pidock-protocol（Rust），通过 ts-rs 在 cargo test 时 导出 TS 绑定到 packages/protocol，host / ui / web / desktop 共用。改协议后跑 pnpm protocol:gen（即 cargo test -p pidock-protocol）重新生成。

CI

GitHub Actions 双工作流：

  • CI（push main / PR）：全仓 typecheck、ui/web 构建、cargo fmt --check、clippy、Rust 测试
  • Release（tag v*）：6 平台矩阵构建并上传安装包

许可证

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2026 vcqr

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

About

PI agent desktop app

Topics

agentagent-skillsagentic-aidesktopdesktop-apppi

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages