pi-web-switch
pi 编码代理的 Web 管理面板 — 实时配置管理、会话浏览与记忆查看
🇬🇧 English ·
🇨🇳 中文 ·
🇯🇵 日本語
灵感来源于 cc-switch —— 可视化管理你的 pi 编码代理的提供商、模型、Token 用量、会话和设置。
直接从 ~/.pi/agent/ 读取真实数据 —— 无需模拟数据、无需数据库、无需额外后端。
---
## ✨ 功能特性
### 📊 仪表盘
- **使用统计** — 全部/当天/7天/30天/自定义日期范围 + 自动刷新（5s/10s/30s/60s）
- **全部来源总览** — 将本地支持的所有用量来源合并统计，同时保留 Pi 与 ChatGPT/Codex 的独立视图
- **Token 明细** — 精确值 + 约等于显示（如 `1,631,022 ≈ 163.1万`），含输入/输出/缓存命中/缓存创建占比
- **成本追踪** — 逐日成本图 + Provider/Model 统计选项卡
- **缓存命中率** — 直观的进度条展示缓存效率
- **请求日志** — 详细日志表（时间、供应商、模型、Token、成本）
- **货币切换** — 美元/人民币实时换算（1 USD = 7.2 CNY）
- **小时/天粒度** — 当天视图按小时展示；7天/30天按天展示
### 📦 模型管理
- **模型网格** — 按提供商浏览所有模型，支持搜索和筛选
- **启用/禁用** — 切换模型开关，对应 `enabledModels` 配置
- **编辑模型** — 更新能力、成本、上下文窗口、最大 Token
- **添加模型** — 创建新模型，绑定到任意提供商
- **删除模型** — 移除自定义模型
### 🔌 提供商管理
- **提供商列表** — 可展开卡片展示所有内置和自定义提供商
- **自定义提供商** — 添加 Ollama、vLLM、LM Studio 或任意 OpenAI 兼容提供商
- **API Key 管理** — 为每个提供商设置/删除 API Key（保存到 `auth.json`）
- **提供商配置** — baseUrl、API 类型、自定义请求头、认证方式
- **已启用模型面板** — 跨提供商汇总所有已启用模型，支持一键禁用/全部禁用，并与各提供商内的模型开关实时同步
- **在线获取模型** — 从提供商的 `/models` 端点拉取实时模型列表，一键导入
### 💬 会话浏览
- **项目分组** — 自动将会话目录名解码为项目路径
- **会话浏览器** — 查看所有 100+ 个会话
- **会话详情** — 名称、时间、消息数、持续时间、使用的提供商/模型
- **搜索筛选** — 按项目名称过滤会话
- **删除会话** — 删除旧的会话文件（近 3 天有更新的会话受保护）
### 🧠 记忆查看 (pi-hermes-memory)
- **项目记忆** — 查看 `MEMORY.md` 内容，支持 Markdown 渲染
- **用户画像** — 显示 `USER.md` 偏好和设置
- **故障记录** — 浏览 `failures.md` 已知问题
- **实时同步** — 记忆文件在磁盘变更时内容即时更新
### 🌐 多语言
- **English** 🇬🇧 — 英文
- **简体中文** 🇨🇳 — 中文
- **繁體中文** 🇭🇰 — 繁体中文
- **日本語** 🇯🇵 — 日文
- 侧栏底部语言切换器，选择后跨会话保持
### ⚙️ 设置
- **默认值** — 默认提供商、模型、思考级别、项目信任级别
- **主题** — 浅色 / 深色 / 跟随系统，即时切换（CSS 变量双主题）
- **界面缩放** — 按百分比缩放整个界面（50%–200%），并提供字体大小调节
- **扩展与包** — 管理 pi 的 packages 列表
- **导入/导出** — 下载完整配置为 JSON，从备份恢复
- **重置** — 恢复空白默认配置
### 🖥️ Native macOS 菜单栏
- **两个轻量原生应用** — 分别统计 Pi 和 ChatGPT/Codex，用 Swift/AppKit 实现，不依赖 Electron、WebView 或常驻 Web 服务
- **Pi 用量应用** — 显示 Pi 今日/近 7 日用量、成本、缓存命中率和提供商统计
- **ChatGPT 用量应用** — 显示本地 ChatGPT/Codex 会话用量和 Codex 官方额度
- **后台刷新** — 在后台读取本地会话并刷新额度，不阻塞菜单栏交互
- **独立显示开关** — 设置页通过 `~/.pi/agent/settings.json` 分别控制两个菜单栏应用
需要 macOS 和 Swift Command Line Tools。在项目目录中运行：
```bash
npm run native:build # 构建 release/ 下的两个 .app
npm run native:open # 构建并启动两个菜单栏应用
```
## 🌗 主题支持
完整的浅色和深色模式，支持跟随系统。主题通过 CSS 自定义属性即时切换——无需刷新页面。所有组件均适配，包括侧栏、弹窗、表单、图表和滚动条。
## 🧱 内置提供商
内置提供商与模型目录**直接读取本机 pi 安装**——与 pi 自带、[pi.dev/models](https://pi.dev/models) 展示的是同一份数据（`@earendil-works/pi-ai/dist/providers/data/*.json`）。升级 pi 即升级本面板；以 pi `0.85.1` 为例是 **37 个提供商、1153 个模型**，其中 733 个支持图片输入。结果缓存 5 分钟，重启 dev server 后刷新。
找不到本机 pi 安装时（例如刚 clone 下来），会回退到 `src/data/builtin-providers.ts` 里手工维护的精简目录——10 个提供商 / 38 个模型，覆盖 Anthropic、OpenAI、DeepSeek、Google、OpenCode Zen（及 Zen Go）、OpenRouter、Mistral、GitHub Copilot、Groq。
你新增或导入的模型会写入 `~/.pi/agent/models.json` 并合并到目录之上：id 与内置提供商相同（例如 `mistral`）时是补充该提供商，而不是多出一个重复条目；在该文件里设置的显示名优先于目录名。
## 🚀 快速开始
### 前置要求
- **pi 编码代理** 已安装并配置（确保 `~/.pi/agent/` 目录存在）
- Node.js 18+
### 安装与运行
```bash
git clone https://github.com/Raingor/pi-web-switch.git
cd pi-web-switch
npm install
npm run dev # 启动开发服务器（自动读取 ~/.pi/agent/）
npm run build # 构建生产版本
npm run preview # 预览生产构建
```
## 🖥️ 姊妹项目 — pi-of-cindy
pi-web-switch 跑在浏览器里。如果你想要更完整的 **桌面端、手机端和 AI Agent 工作台**，可以了解它的姊妹项目：
> **[pi-of-cindy](https://github.com/Raingor/pi-of-cindy)** — CINDY 客户端的 pi-only 改造分支，包含 Electron 桌面端、Expo / React Native 手机端及共享 packages。
> 它以本机 [pi](https://github.com/earendil-works/pi) CLI 为唯一工作台，提供 Pi 供应商、仪表盘、任务、记忆、Subagents 和本地会话导入，并与本机 pi CLI 共用 `~/.pi/agent/` 配置。
>
> pi-of-cindy 的主要特点：
> - **多端 Agent 工作台** — 桌面端、手机端与共享能力统一在一个 pnpm monorepo 中
> - **Harness × 模型自由组合** — 支持 Claude Code、Codex 等 Agent Harness，任务可规划、并行执行和独立 review
> - **真实环境执行** — 可以操作浏览器、电脑和手机，使用本机文件及已登录应用完成任务
> - **Pi-only 本地工作流** — 导入的 pi CLI 会话可以直接继续，提供商和模型配置与终端保持一致
> - **Apache-2.0 开源** — 客户端源码开放，支持自行构建和二次开发
>
> 下载与完整说明请查看 **[pi-of-cindy README](https://github.com/Raingor/pi-of-cindy)**。
**两者共用本机 `~/.pi/agent/` 配置**，在任一端改动的提供商、模型和记忆，都可在另一端及终端 `pi` 中继续使用。
| | pi-web-switch（本项目） | pi-of-cindy |
|---|---|---|
| 形态 | 浏览器面板（Vite 开发服务器） | Electron 桌面端 + Expo / React Native 手机端 |
| 侧重 | 配置管理 — 仪表盘 / 提供商 / 会话 / 记忆多页并列 | 多端 AI Agent 工作台 — 任务执行、Harness 编排和本地会话 |
| Pi 集成 | Pi 扩展包 / 本地配置面板 | 以本机 pi CLI 为核心，共用 `~/.pi/agent/` |
| 开源协议 | MIT | Apache-2.0 |
| 开发方式 | `npm run dev` | `pnpm install` + `pnpm restart:desktop:remote` |
## 🏗️ 技术栈
React 19 + TypeScript 5.8 + Vite 6 + Tailwind CSS v4 + Zustand + Recharts + Lucide React + React Router v7
## 📦 Pi 扩展包
pi-web-switch 可安装为 **pi 编码代理扩展**，在 pi 会话中直接启动/停止仪表盘。
### 安装
在 `~/.pi/agent/settings.json` 的 packages 列表中添加 `npm:pi-web-switch`：
```json
{
"packages": ["npm:pi-web-switch"]
}
```
### 命令
安装后在 pi 会话中可用以下命令：
| 命令 | 说明 |
|------|------|
| `/pi-switch start` | 启动仪表盘 http://localhost:5173 |
| `/pi-switch stop` | 娶止服务器 |
| `/pi-switch status` | 查看运行状态 |
| `/pi-usage` | 在终端打印使用量摘要（今日 + 7 天）—— tokens / 成本 / 请求数 / 每日 sparkline，无需启动仪表盘 |
`/pi-usage` 命令直接读取 `~/.pi/agent/sessions/*.jsonl` 并聚合今日 + 最近 7 天统计，让你在任何 pi 会话中一眼看到使用量。
### 包结构
```
pi-web-switch/
├── package.json # npm 包 + pi.extensions + pi.skills
├── pi-package/
│ ├── index.ts # 扩展入口：注册 /pi-switch、/pi-usage 命令
│ └── skills/
│ └── pi-web-switch/
│ └── SKILL.md # 使用文档
├── server/
│ └── pi-reader.ts # 服务端：读取 ~/.pi/agent/ 文件
├── native/
│ ├── NativeUsageSupport.swift # 共用用量读取和格式化
│ ├── PiUsageMenuBar.swift # Pi 用量菜单栏应用
│ └── ChatGPTUsageMenuBar.swift # ChatGPT/Codex 用量菜单栏应用
├── scripts/
│ └── build-native-menubar.sh
└── src/ # React 前端
```
## 💬 交流群
有任何疑问、建议或 bug 反馈，欢迎加入 **Telegram 交流群**：
👉 **[加入 pi-web-switch Telegram 交流群](https://t.me/+ODpy7_7NlOE4NzA1)**
提问时请附上：
1. 你的系统（macOS / Windows / Linux）
2. 版本号 —— `npm view @raingor/pi-web-switch version`
3. 清晰的问题描述，以及报错截图或日志
## 🔗 相关链接
- **姊妹项目（CINDY pi-only 客户端）：** [github.com/Raingor/pi-of-cindy](https://github.com/Raingor/pi-of-cindy)
- **个人主页：** [raingor.github.io/my-blog](https://raingor.github.io/my-blog/)
- **GitHub：** [github.com/Raingor](https://github.com/Raingor)
## 📄 许可证
MIT