Compare commits
4
Commits
4d120ad2bb
...
Dev_260708
| Author | SHA1 | Date | |
|---|---|---|---|
 KimiSwitch Dev
|
0ce89b09d9 | ||
|
KimiSwitch Dev
|
0bf0f50aaa | ||
|
KimiSwitch Dev
|
dd22d769f4 | ||
|
KimiSwitch Dev
|
c32f3f458f |
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 CodingPlan.site
|
||||
|
||||
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.
|
||||
@@ -1,5 +1,330 @@
|
||||
# KimiSwitch
|
||||
# Pi Switch
|
||||
|
||||
A Windows x64 desktop config manager for Kimi Code CLI, built with Tauri v2, React, TypeScript, and Tailwind CSS.
|
||||
> Windows 桌面端 LLM 供应商配置管理器，让你在 **Kimi Code CLI** 和 **Pi** 两个 Agent 之间无缝切换多家 LLM 供应商与模型。
|
||||
|
||||
KimiSwitch helps you manage multiple LLM provider configurations and switch between configuration profiles for Kimi Code CLI.
|
||||
[English](./README_EN.md) | **中文**
|
||||
|
||||
[](https://tauri.app)
|
||||
[](https://react.dev)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](https://www.rust-lang.org)
|
||||
[](./LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [这是什么](#这是什么)
|
||||
- [核心特性](#核心特性)
|
||||
- [架构总览](#架构总览)
|
||||
- [支持的供应商类型](#支持的供应商类型)
|
||||
- [数据存储位置](#数据存储位置)
|
||||
- [快速上手](#快速上手)
|
||||
- [开发指南](#开发指南)
|
||||
- [键盘快捷键](#键盘快捷键)
|
||||
- [国际化](#国际化)
|
||||
- [测试](#测试)
|
||||
- [打包发布](#打包发布)
|
||||
- [常见问题](#常见问题)
|
||||
- [安全提示](#安全提示)
|
||||
|
||||
---
|
||||
|
||||
## 这是什么
|
||||
|
||||
**Pi Switch** 是一个为 LLM CLI 用户打造的 Windows 桌面配置管理工具。它解决两个痛点：
|
||||
|
||||
1. **多供应商管理繁琐**：在 Kimi / Anthropic / OpenAI / Google GenAI / 自建代理 等多家供应商之间切换时，需要反复手改 TOML/JSON，容易出错。
|
||||
2. **多 Agent 配置割裂**：同时使用 **Kimi Code CLI** 和 **Pi** 两个 Agent 的开发者，每个 Agent 都有一套独立的配置格式，改一处要改两份。
|
||||
|
||||
Pi Switch 提供统一的图形界面：
|
||||
|
||||
- 统一图形界面，分别管理 Kimi Code 和 Pi 两套 Agent 配置，顶部 Tab 切换
|
||||
- 一键切换供应商，自动写入对应 Agent 的原生配置
|
||||
- 一键拉取模型列表（OpenAI / Anthropic / Google GenAI）
|
||||
- 切换后给出 `/reload` 提示，确保 Kimi Code 会话立即生效
|
||||
|
||||
## 核心特性
|
||||
|
||||
| 分类 | 功能 |
|
||||
| --- | --- |
|
||||
| **多 Agent** | 同时管理 Kimi Code 和 Pi 两套配置，互不干扰，顶部 Tab 切换 |
|
||||
| **多供应商** | Kimi / Anthropic / OpenAI / OpenAI Responses / Google GenAI / Vertex AI |
|
||||
| **模型映射** | 别名 ↔ 实际模型 ID，支持显示名、上下文长度、角色（Sonnet/Opus/Fable/Haiku）、1M 上下文声明 |
|
||||
| **一键发现** | 根据供应商 API 自动拉取可用模型列表 |
|
||||
| **托管供应商** | 标记 OAuth/managed 供应商，跳过凭证校验，保留 `oauth` 段写入 Kimi Code 配置 |
|
||||
| **Env 凭证** | 既支持 `api_key` 字段，也支持 `env` 表里的环境变量名（如 `OPENAI_API_KEY`） |
|
||||
| **全局设置** | 思考开关/等级、循环重试、后台任务、权限规则、生命周期钩子（仅 Kimi Code） |
|
||||
| **JSON 直编** | 高级用户可手动编辑完整配置 JSON（保留未知字段，不会丢字段） |
|
||||
| **i18n** | 简体中文 / English，运行时切换 |
|
||||
| **自动备份** | 写入 Kimi Code / Pi 原生配置前自动备份，按时间戳命名，保留最近 7 天（见 `src-tauri/src/config_io.rs`） |
|
||||
| **快捷键** | Ctrl+S 保存、Ctrl+R 重载、Ctrl+O 打开配置目录 |
|
||||
| **校验（预留）** | i18n 已定义错误文案（名称重复、凭证缺失、Vertex 字段缺失等），后端 `validators.rs` 为占位实现，尚未接线 |
|
||||
| **未保存提示** | 关闭窗口前检测未保存修改，标题栏加 `*` 前缀 |
|
||||
|
||||
## 架构总览
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ Pi Switch (Tauri v2) │
|
||||
│ │
|
||||
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ React Frontend (TS) │ │ Rust Backend (lib.rs) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ src/App.tsx │◄──►│ src-tauri/src/ │ │
|
||||
│ │ src/components/ │ Tauri ├── commands.rs │ │
|
||||
│ │ ProviderList │ invoke ├── db.rs │ │
|
||||
│ │ ProviderEdit │ ├── kimi_code_io │ │
|
||||
│ │ AgentSettingsPanel │ ├── pi_io.rs │ │
|
||||
│ │ src/hooks/useConfig │ ├── config_io.rs │ │
|
||||
│ │ src/i18n/{zh,en}.ts │ ├── validators.rs │ │
|
||||
│ │ src/types/index.ts │ └── profile_manager│ │
|
||||
│ └──────────────────────────┘ └──────────────────────────┘ │
|
||||
│ │ │ │
|
||||
└──────────────────┼──────────────────────────────┼──────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────────┐
|
||||
│ SQLite │ │ Agent 原生配置文件 │
|
||||
│ ~/.pi-switch/ │ │ ├─ ~/.kimi-code/ │
|
||||
│ pi-switch.db │ │ │ └─ config.toml │
|
||||
│ │ │ └─ ~/.pi/agent/ │
|
||||
│ (Pi Switch 内部状态) │ │ ├─ models.json │
|
||||
└──────────────────────┘ │ └─ settings.json │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**关键设计**：
|
||||
|
||||
- Pi Switch 维护自己的 SQLite 数据库存**完整配置**（所有供应商 + 所有模型，含未激活的）
|
||||
- 点「切换使用」时只把**当前激活的供应商**写入 Agent 原生配置，其他不写
|
||||
- 这样 Kimi Code / Pi 始终只看到一个活跃供应商，不会被托管/OAuth 默认值干扰
|
||||
- `raw_other` 字段透传未知键，保证前后往返不丢字段
|
||||
|
||||
## 支持的供应商类型
|
||||
|
||||
| 类型 | 标识符 | 默认 base_url | 模型发现 | 凭证 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Kimi | `kimi` | `https://api.openai.com/v1` | ✅ OpenAI 协议 | `KIMI_API_KEY` 或 `env.KIMI_API_KEY` |
|
||||
| Anthropic | `anthropic` | — | ✅ `/v1/models` | `ANTHROPIC_API_KEY` 或 `env` |
|
||||
| OpenAI | `openai` | `https://api.openai.com/v1` | ✅ `/models` | `OPENAI_API_KEY` 或 `env` |
|
||||
| OpenAI Responses | `openai_responses` | `https://api.openai.com/v1` | ✅ `/models` | `OPENAI_API_KEY` 或 `env` |
|
||||
| Google GenAI | `google-genai` | `https://generativelanguage.googleapis.com` | ✅ `/v1beta/models` | `GOOGLE_API_KEY` 或 `env` |
|
||||
| Vertex AI | `vertexai` | — | ⚠️ 待实现 | `VERTEXAI_API_KEY` + `GOOGLE_CLOUD_PROJECT` + `GOOGLE_CLOUD_LOCATION` |
|
||||
|
||||
凭证优先级：`api_key` 字段 > `env` 表里的同名键。
|
||||
|
||||
## 数据存储位置
|
||||
|
||||
| 文件 | 用途 | 备份 |
|
||||
| --- | --- | --- |
|
||||
| `%USERPROFILE%\.pi-switch\pi-switch.db` | Pi Switch 自己的 SQLite 数据库，存全量配置 | — |
|
||||
| `%USERPROFILE%\.kimi-code\config.toml` | Kimi Code CLI 的 TOML 配置（**切换时写入**） | 同目录下 `backups/config.toml.bak.{YYYYMMDD_HHMMSS}`，保留 7 天 |
|
||||
| `%USERPROFILE%\.pi\agent\models.json` | Pi 的供应商+模型配置（**切换时写入**） | 同目录下 `backups/models.json.bak.{YYYYMMDD_HHMMSS}`，保留 7 天 |
|
||||
| `%USERPROFILE%\.pi\agent\settings.json` | Pi 的默认供应商/模型（**切换时写入**） | 同目录下 `backups/settings.json.bak.{YYYYMMDD_HHMMSS}`，保留 7 天 |
|
||||
| `localStorage[pi-switch-agent]` | 前端记住上次选中的 Agent（kimi_code / pi） | — |
|
||||
|
||||
环境变量覆盖：
|
||||
|
||||
- `KIMI_CODE_HOME` 覆盖 Kimi Code 配置目录（默认 `~/.kimi-code`）
|
||||
- `PI_CODING_AGENT_DIR` 覆盖 Pi Agent 配置目录（默认 `~/.pi/agent`）
|
||||
|
||||
## 快速上手
|
||||
|
||||
### 前置依赖
|
||||
|
||||
| 工具 | 版本 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Node.js | ≥ 18 | 前端构建 |
|
||||
| Rust | stable 最新版（edition 2021） | Tauri 后端编译 |
|
||||
| WebView2 Runtime | Windows 10/11 默认已装 | Tauri v2 运行时 |
|
||||
| Microsoft C++ Build Tools | 最新版 | Rust 编译依赖 |
|
||||
| WiX Toolset 3.14 | `src-tauri/wix314-binaries/` 目录 | MSI 打包（首次构建自动下载） |
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 开发模式（热重载）
|
||||
|
||||
```bash
|
||||
npm run tauri-dev
|
||||
```
|
||||
|
||||
会同时启动 Vite 开发服务器（端口 1420）和 Tauri 窗口，修改前端代码会自动刷新，修改 Rust 代码会重新编译。
|
||||
|
||||
### 仅前端开发（无 Tauri 窗口）
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
适用于纯 UI 调试。
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
.
|
||||
├── src/ # React 前端
|
||||
│ ├── App.tsx # 主组件，路由 ProviderList/ProviderEdit
|
||||
│ ├── main.tsx # React 入口 + ErrorBoundary + I18nProvider
|
||||
│ ├── components/
|
||||
│ │ ├── ProviderList.tsx # 供应商列表 + 切换按钮
|
||||
│ │ ├── ProviderEdit.tsx # 编辑供应商 + 模型映射 + JSON 直编
|
||||
│ │ └── AgentSettingsPanel.tsx# 全局设置（思考/循环/权限/钩子）
|
||||
│ ├── hooks/
|
||||
│ │ └── useConfig.ts # 加载/保存配置 hook
|
||||
│ ├── lib/
|
||||
│ │ ├── agent-settings.ts # AgentSettings 解析/序列化
|
||||
│ │ └── model-defaults.ts # 模型默认上下文大小
|
||||
│ ├── types/index.ts # Provider/Model/Config 类型定义
|
||||
│ ├── i18n/
|
||||
│ │ ├── zh.ts # 中文翻译（143 条目）
|
||||
│ │ ├── en.ts # 英文翻译
|
||||
│ │ └── index.tsx # useTranslation hook + Provider
|
||||
│ └── index.css # Tailwind 入口
|
||||
│
|
||||
├── src-tauri/ # Rust 后端
|
||||
│ ├── src/
|
||||
│ │ ├── lib.rs # Tauri Builder + invoke_handler 注册
|
||||
│ │ ├── main.rs # 二进制入口
|
||||
│ │ ├── commands.rs # 7 个 Tauri Command
|
||||
│ │ ├── db.rs # SQLite 持久化
|
||||
│ │ ├── kimi_code_io.rs # ~/.kimi-code/config.toml 读写
|
||||
│ │ ├── pi_io.rs # ~/.pi/agent/*.json 读写
|
||||
│ │ ├── config_io.rs # 文件备份工具
|
||||
│ │ ├── models.rs # Config/Provider/Model 数据结构
|
||||
│ │ ├── profile_manager.rs # 多 Profile 管理（占位）
|
||||
│ │ └── validators.rs # 配置校验
|
||||
│ ├── capabilities/ # Tauri 权限声明
|
||||
│ ├── icons/ # 应用图标（脚本生成）
|
||||
│ └── tauri.conf.json # Tauri 配置（窗口/打包/CSP）
|
||||
│
|
||||
├── scripts/generate-icons.py # 从 SVG 生成各尺寸图标
|
||||
├── public/pi.svg # 应用图标源（蓝紫渐变 π）
|
||||
└── docs/superpowers/ # 设计规范与实施计划
|
||||
```
|
||||
|
||||
### Tauri Commands（前端 ↔ 后端）
|
||||
|
||||
| 命令 | 说明 |
|
||||
| --- | --- |
|
||||
| `load_agent_config_command(agent)` | 加载配置：优先 SQLite，为空则从 Agent 原生配置导入 |
|
||||
| `save_agent_config_command(agent, config)` | 保存全量配置到 SQLite |
|
||||
| `activate_agent_config_command(agent)` | 把当前激活的供应商写入 Agent 原生配置 |
|
||||
| `open_agent_config_dir(agent)` | 用系统资源管理器打开 Agent 配置目录 |
|
||||
| `get_app_version()` | 返回 `Cargo.toml` 版本号 |
|
||||
| `list_provider_models(provider)` | 调供应商 API 拉取模型列表（异步） |
|
||||
| `debug_log(message)` | 把前端日志打到 stderr（开发用） |
|
||||
|
||||
### 添加新供应商类型
|
||||
|
||||
1. 在 `src-tauri/src/models.rs` 的 `ProviderType` 枚举里加新变体
|
||||
2. 在 `default_base_url()` 里加默认值
|
||||
3. 在 `commands.rs::list_provider_models` 的 `match` 里加分发
|
||||
4. 在 `kimi_code_io.rs::provider_type_for_kimi_type` 和 `pi_io.rs::provider_type_for_pi_api` 里加映射
|
||||
5. 在 `src/components/ProviderEdit.tsx` 的 API 格式下拉里加选项
|
||||
6. 在 `src/i18n/{zh,en}.ts` 里加新的 i18n 键
|
||||
|
||||
### 添加新的 Tauri Command
|
||||
|
||||
1. 在 `src-tauri/src/commands.rs` 里加 `#[tauri::command]`
|
||||
2. 在 `src-tauri/src/lib.rs` 的 `tauri::generate_handler![...]` 列表里注册
|
||||
3. 前端用 `import { invoke } from "@tauri-apps/api/core"` 调用
|
||||
4. 在 `src-tauri/capabilities/default.json` 里加权限（如需访问文件系统）
|
||||
|
||||
## 键盘快捷键
|
||||
|
||||
| 快捷键 | 作用 |
|
||||
| --- | --- |
|
||||
| `Ctrl + S` | 保存当前修改到 SQLite |
|
||||
| `Ctrl + R` | 重新读取配置（未保存时会提示） |
|
||||
| `Ctrl + O` | 打开当前 Agent 的配置目录 |
|
||||
|
||||
## 国际化
|
||||
|
||||
- 翻译源文件：`src/i18n/zh.ts`（源）和 `src/i18n/en.ts`（目标）
|
||||
- 新增 key 时**先在 `zh.ts` 里加**，`en.ts` 的 `Record<TranslationKey, string>` 类型会自动校验缺失条目（编译时报错）
|
||||
- 运行时通过右上角下拉切换语言，记忆在组件内 state（未持久化到 SQLite）
|
||||
|
||||
## 测试
|
||||
|
||||
### Rust 单元测试
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo test
|
||||
```
|
||||
|
||||
当前覆盖：
|
||||
|
||||
- `kimi_code_io::tests` — TOML 导入/导出往返
|
||||
- `pi_io::tests` — JSON 往返，包括 advanced fields（headers/compat/cost/extra）
|
||||
|
||||
### 前端
|
||||
|
||||
暂无自动化测试。建议手动验证清单：
|
||||
|
||||
- [ ] 切换 Agent 时配置互不污染
|
||||
- [ ] 删除供应商时关联模型也清掉
|
||||
- [ ] 切换供应商后默认模型正确回填
|
||||
- [ ] 重命名供应商后引用它的模型也跟着改
|
||||
- [ ] JSON 直编后 `raw_other` 不丢字段
|
||||
|
||||
## 打包发布
|
||||
|
||||
```bash
|
||||
npm run tauri-build
|
||||
```
|
||||
|
||||
产物位置：
|
||||
|
||||
- `src-tauri/target/release/bundle/msi/Pi Switch_0.1.0_x64_en-US.msi`
|
||||
|
||||
Windows 安装包（MSI），含 WebView2 bootstrapper 自动下载。`nsis` 已禁用，目前只产 MSI。
|
||||
|
||||
### 首次打包
|
||||
|
||||
首次运行会下载：
|
||||
|
||||
- WiX Toolset 3.14 binaries → `src-tauri/wix314-binaries/`
|
||||
- WebView2 bootstrapper → 打包进 MSI
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 切换供应商后 Kimi Code 没生效？**
|
||||
A: 在 Kimi Code 会话里执行 `/reload`（Kimi Code CLI 才会重新读取 `~/.kimi-code/config.toml`）。应用会在 UI 上提示。
|
||||
|
||||
**Q: 改了配置但忘了保存就关了窗口？**
|
||||
A: 关闭窗口前会弹原生 `beforeunload` 提示，标题栏也会显示 `*` 前缀。
|
||||
|
||||
**Q: 怎么备份/迁移我的配置？**
|
||||
A: 备份 `%USERPROFILE%\.pi-switch\pi-switch.db` 即可，里面存了全量配置（含未激活的供应商）。
|
||||
|
||||
**Q: Vertex AI 为什么不能拉取模型列表？**
|
||||
A: Vertex 需要 GCP project/location 凭证，当前实现留了 TODO，等 GCP SDK 集成后再补。
|
||||
|
||||
**Q: 支持 macOS / Linux 吗？**
|
||||
A: 代码不依赖 Windows 专属 API，但 `tauri.conf.json` 的 bundle 目标目前只配了 `msi`。理论上把 `bundle.targets` 改成 `["app", "dmg"]` 等即可跨平台，但未验证。
|
||||
|
||||
## 安全提示
|
||||
|
||||
- API Key 以明文存储在本地 SQLite 和 Agent 原生配置里——**不要在共享电脑上保存**
|
||||
- 不要把 `pi-switch.db`、`config.toml`、`models.json` 提交到 Git
|
||||
- 应用 CSP 已收紧（`default-src 'self'`），但 WebView2 仍可能缓存表单内容，注意在公共电脑用完退出
|
||||
|
||||
---
|
||||
|
||||
## 附录：相关项目
|
||||
|
||||
- [Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli) — 兼容的 Agent 之一
|
||||
- [Tauri](https://tauri.app) — 桌面应用框架
|
||||
- 设计文档见 `docs/superpowers/specs/`，实施计划见 `docs/superpowers/plans/`
|
||||
|
||||
---
|
||||
|
||||
许可证：MIT，详见 [LICENSE](./LICENSE)。Copyright (c) 2026 CodingPlan.site
|
||||
+330
@@ -0,0 +1,330 @@
|
||||
# Pi Switch
|
||||
|
||||
> A Windows desktop LLM provider config manager that lets you switch between multiple LLM providers and models across the **Kimi Code CLI** and **Pi** agents.
|
||||
|
||||
**English** | [中文](./README.md)
|
||||
|
||||
[](https://tauri.app)
|
||||
[](https://react.dev)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](https://www.rust-lang.org)
|
||||
[](./LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What Is This](#what-is-this)
|
||||
- [Key Features](#key-features)
|
||||
- [Architecture Overview](#architecture-overview)
|
||||
- [Supported Provider Types](#supported-provider-types)
|
||||
- [Data Storage Locations](#data-storage-locations)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Development Guide](#development-guide)
|
||||
- [Keyboard Shortcuts](#keyboard-shortcuts)
|
||||
- [Internationalization](#internationalization)
|
||||
- [Testing](#testing)
|
||||
- [Build & Release](#build--release)
|
||||
- [FAQ](#faq)
|
||||
- [Security Notes](#security-notes)
|
||||
|
||||
---
|
||||
|
||||
## What Is This
|
||||
|
||||
**Pi Switch** is a Windows desktop configuration tool built for LLM CLI users. It solves two pain points:
|
||||
|
||||
1. **Tedious multi-provider management**: switching between Kimi / Anthropic / OpenAI / Google GenAI / self-hosted proxies requires repeatedly hand-editing TOML/JSON, which is error-prone.
|
||||
2. **Fragmented multi-agent configs**: developers using both **Kimi Code CLI** and **Pi** have to maintain two independent config formats, duplicating every change.
|
||||
|
||||
Pi Switch provides a unified GUI:
|
||||
|
||||
- One unified interface to manage two separate agent configs (Kimi Code and Pi), switched via a top tab
|
||||
- One-click provider switching that writes the active provider into the target agent's native config
|
||||
- One-click model-list fetching (OpenAI / Anthropic / Google GenAI)
|
||||
- A `/reload` hint after switching so Kimi Code sessions take effect immediately
|
||||
|
||||
## Key Features
|
||||
|
||||
| Category | Feature |
|
||||
| --- | --- |
|
||||
| **Multi-agent** | Manage Kimi Code and Pi configs independently without interference, via a top tab |
|
||||
| **Multi-provider** | Kimi / Anthropic / OpenAI / OpenAI Responses / Google GenAI / Vertex AI |
|
||||
| **Model mapping** | Alias ↔ real model ID, with display name, context size, role (Sonnet/Opus/Fable/Haiku), and 1M-context declaration |
|
||||
| **One-click discovery** | Auto-fetch available model lists from the provider API |
|
||||
| **Managed providers** | Flag OAuth/managed providers to skip credential validation and preserve the `oauth` section in Kimi Code config |
|
||||
| **Env credentials** | Supports both the `api_key` field and env-table keys (e.g. `OPENAI_API_KEY`) |
|
||||
| **Global settings** | Thinking toggle/level, loop retries, background tasks, permission rules, lifecycle hooks (Kimi Code only) |
|
||||
| **Raw JSON editing** | Power users can hand-edit the full config JSON (unknown fields are preserved, never dropped) |
|
||||
| **i18n** | Simplified Chinese / English, switched at runtime |
|
||||
| **Auto backup** | Before writing the Kimi Code / Pi native configs, back up with timestamp-based names and keep the last 7 days (see `src-tauri/src/config_io.rs`) |
|
||||
| **Shortcuts** | Ctrl+S save, Ctrl+R reload, Ctrl+O open config dir |
|
||||
| **Validation (reserved)** | i18n error strings are defined (duplicate names, missing credentials, missing Vertex fields, etc.), but the backend `validators.rs` is a stub and not yet wired |
|
||||
| **Unsaved-changes prompt** | Detects unsaved edits before closing the window and prefixes the title bar with `*` |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ Pi Switch (Tauri v2) │
|
||||
│ │
|
||||
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ React Frontend (TS) │ │ Rust Backend (lib.rs) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ src/App.tsx │◄──►│ src-tauri/src/ │ │
|
||||
│ │ src/components/ │ Tauri ├── commands.rs │ │
|
||||
│ │ ProviderList │ invoke ├── db.rs │ │
|
||||
│ │ ProviderEdit │ ├── kimi_code_io │ │
|
||||
│ │ AgentSettingsPanel │ ├── pi_io.rs │ │
|
||||
│ │ src/hooks/useConfig │ ├── config_io.rs │ │
|
||||
│ │ src/i18n/{zh,en}.ts │ ├── validators.rs │ │
|
||||
│ │ src/types/index.ts │ └── profile_manager│ │
|
||||
│ └──────────────────────────┘ └──────────────────────────┘ │
|
||||
│ │ │ │
|
||||
└──────────────────┼──────────────────────────────┼──────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────────┐
|
||||
│ SQLite │ │ Agent native configs │
|
||||
│ ~/.pi-switch/ │ │ ├─ ~/.kimi-code/ │
|
||||
│ pi-switch.db │ │ │ └─ config.toml │
|
||||
│ │ │ └─ ~/.pi/agent/ │
|
||||
│ (Pi Switch internal)│ │ ├─ models.json │
|
||||
└──────────────────────┘ │ └─ settings.json │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Key design points**:
|
||||
|
||||
- Pi Switch keeps its own SQLite database for the **full config** (all providers + all models, including inactive ones)
|
||||
- Clicking "Switch to" writes **only the active provider** into the agent's native config; the others are not written
|
||||
- This way Kimi Code / Pi always see exactly one active provider and are never confused by managed/OAuth defaults
|
||||
- The `raw_other` field passes unknown keys through untouched, so round-trips never lose fields
|
||||
|
||||
## Supported Provider Types
|
||||
|
||||
| Type | Identifier | Default base_url | Model discovery | Credentials |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Kimi | `kimi` | `https://api.openai.com/v1` | ✅ OpenAI protocol | `KIMI_API_KEY` or `env.KIMI_API_KEY` |
|
||||
| Anthropic | `anthropic` | — | ✅ `/v1/models` | `ANTHROPIC_API_KEY` or `env` |
|
||||
| OpenAI | `openai` | `https://api.openai.com/v1` | ✅ `/models` | `OPENAI_API_KEY` or `env` |
|
||||
| OpenAI Responses | `openai_responses` | `https://api.openai.com/v1` | ✅ `/models` | `OPENAI_API_KEY` or `env` |
|
||||
| Google GenAI | `google-genai` | `https://generativelanguage.googleapis.com` | ✅ `/v1beta/models` | `GOOGLE_API_KEY` or `env` |
|
||||
| Vertex AI | `vertexai` | — | ⚠️ Not yet implemented | `VERTEXAI_API_KEY` + `GOOGLE_CLOUD_PROJECT` + `GOOGLE_CLOUD_LOCATION` |
|
||||
|
||||
Credential precedence: the `api_key` field wins over the same-named key in the `env` table.
|
||||
|
||||
## Data Storage Locations
|
||||
|
||||
| File | Purpose | Backup |
|
||||
| --- | --- | --- |
|
||||
| `%USERPROFILE%\.pi-switch\pi-switch.db` | Pi Switch's own SQLite database holding the full config | — |
|
||||
| `%USERPROFILE%\.kimi-code\config.toml` | Kimi Code CLI's TOML config (**written on switch**) | `backups/config.toml.bak.{YYYYMMDD_HHMMSS}` next to it, kept 7 days |
|
||||
| `%USERPROFILE%\.pi\agent\models.json` | Pi's provider+model config (**written on switch**) | `backups/models.json.bak.{YYYYMMDD_HHMMSS}` next to it, kept 7 days |
|
||||
| `%USERPROFILE%\.pi\agent\settings.json` | Pi's default provider/model (**written on switch**) | `backups/settings.json.bak.{YYYYMMDD_HHMMSS}` next to it, kept 7 days |
|
||||
| `localStorage[pi-switch-agent]` | Frontend remembers the last selected agent (kimi_code / pi) | — |
|
||||
|
||||
Environment-variable overrides:
|
||||
|
||||
- `KIMI_CODE_HOME` overrides the Kimi Code config dir (default `~/.kimi-code`)
|
||||
- `PI_CODING_AGENT_DIR` overrides the Pi agent config dir (default `~/.pi/agent`)
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
| Tool | Version | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Node.js | ≥ 18 | Frontend build |
|
||||
| Rust | Latest stable (edition 2021) | Tauri backend compilation |
|
||||
| WebView2 Runtime | Bundled with Windows 10/11 | Tauri v2 runtime |
|
||||
| Microsoft C++ Build Tools | Latest | Rust compile dependency |
|
||||
| WiX Toolset 3.14 | `src-tauri/wix314-binaries/` | MSI bundling (auto-downloaded on first build) |
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Dev mode (hot reload)
|
||||
|
||||
```bash
|
||||
npm run tauri-dev
|
||||
```
|
||||
|
||||
Starts both the Vite dev server (port 1420) and the Tauri window. Frontend edits hot-reload; Rust edits trigger a recompile.
|
||||
|
||||
### Frontend-only dev (no Tauri window)
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Good for pure UI debugging.
|
||||
|
||||
## Development Guide
|
||||
|
||||
### Project structure
|
||||
|
||||
```
|
||||
.
|
||||
├── src/ # React frontend
|
||||
│ ├── App.tsx # Root component routing ProviderList/ProviderEdit
|
||||
│ ├── main.tsx # React entry + ErrorBoundary + I18nProvider
|
||||
│ ├── components/
|
||||
│ │ ├── ProviderList.tsx # Provider list + switch button
|
||||
│ │ ├── ProviderEdit.tsx # Edit provider + model mapping + raw JSON
|
||||
│ │ └── AgentSettingsPanel.tsx# Global settings (thinking/loop/permissions/hooks)
|
||||
│ ├── hooks/
|
||||
│ │ └── useConfig.ts # Config load/save hook
|
||||
│ ├── lib/
|
||||
│ │ ├── agent-settings.ts # AgentSettings parse/serialize
|
||||
│ │ └── model-defaults.ts # Default model context sizes
|
||||
│ ├── types/index.ts # Provider/Model/Config type definitions
|
||||
│ ├── i18n/
|
||||
│ │ ├── zh.ts # Chinese translations (143 keys)
|
||||
│ │ ├── en.ts # English translations
|
||||
│ │ └── index.tsx # useTranslation hook + Provider
|
||||
│ └── index.css # Tailwind entry
|
||||
│
|
||||
├── src-tauri/ # Rust backend
|
||||
│ ├── src/
|
||||
│ │ ├── lib.rs # Tauri Builder + invoke_handler registration
|
||||
│ │ ├── main.rs # Binary entry
|
||||
│ │ ├── commands.rs # 7 Tauri commands
|
||||
│ │ ├── db.rs # SQLite persistence
|
||||
│ │ ├── kimi_code_io.rs # ~/.kimi-code/config.toml read/write
|
||||
│ │ ├── pi_io.rs # ~/.pi/agent/*.json read/write
|
||||
│ │ ├── config_io.rs # File backup utilities
|
||||
│ │ ├── models.rs # Config/Provider/Model data structures
|
||||
│ │ ├── profile_manager.rs # Multi-profile management (stub)
|
||||
│ │ └── validators.rs # Config validation
|
||||
│ ├── capabilities/ # Tauri permission declarations
|
||||
│ ├── icons/ # App icons (script-generated)
|
||||
│ └── tauri.conf.json # Tauri config (window/bundle/CSP)
|
||||
│
|
||||
├── scripts/generate-icons.py # Generate all icon sizes from SVG
|
||||
├── public/pi.svg # App icon source (blue-purple gradient π)
|
||||
└── docs/superpowers/ # Design specs & implementation plans
|
||||
```
|
||||
|
||||
### Tauri commands (frontend ↔ backend)
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `load_agent_config_command(agent)` | Load config: SQLite first, falling back to the agent's native config on first use |
|
||||
| `save_agent_config_command(agent, config)` | Save the full config to SQLite |
|
||||
| `activate_agent_config_command(agent)` | Write the active provider into the agent's native config |
|
||||
| `open_agent_config_dir(agent)` | Open the agent's config dir in the system file manager |
|
||||
| `get_app_version()` | Return the `Cargo.toml` version |
|
||||
| `list_provider_models(provider)` | Fetch model list from the provider API (async) |
|
||||
| `debug_log(message)` | Forward frontend logs to stderr (dev use) |
|
||||
|
||||
### Adding a new provider type
|
||||
|
||||
1. Add a new variant to the `ProviderType` enum in `src-tauri/src/models.rs`
|
||||
2. Add a default in `default_base_url()`
|
||||
3. Add a dispatch arm in `commands.rs::list_provider_models`
|
||||
4. Add mappings in `kimi_code_io.rs::provider_type_for_kimi_type` and `pi_io.rs::provider_type_for_pi_api`
|
||||
5. Add an option to the API-format dropdown in `src/components/ProviderEdit.tsx`
|
||||
6. Add new i18n keys in `src/i18n/{zh,en}.ts`
|
||||
|
||||
### Adding a new Tauri command
|
||||
|
||||
1. Add a `#[tauri::command]` in `src-tauri/src/commands.rs`
|
||||
2. Register it in the `tauri::generate_handler![...]` list in `src-tauri/src/lib.rs`
|
||||
3. Call it from the frontend with `import { invoke } from "@tauri-apps/api/core"`
|
||||
4. Add a permission in `src-tauri/capabilities/default.json` (if filesystem access is needed)
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| `Ctrl + S` | Save current changes to SQLite |
|
||||
| `Ctrl + R` | Reload config (prompts if unsaved) |
|
||||
| `Ctrl + O` | Open the current agent's config dir |
|
||||
|
||||
## Internationalization
|
||||
|
||||
- Translation sources: `src/i18n/zh.ts` (source) and `src/i18n/en.ts` (target)
|
||||
- When adding a key, **add it to `zh.ts` first** — the `Record<TranslationKey, string>` type in `en.ts` will flag any missing entry at compile time
|
||||
- Language is switched at runtime via the top-right dropdown and held in component state (not persisted to SQLite)
|
||||
|
||||
## Testing
|
||||
|
||||
### Rust unit tests
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo test
|
||||
```
|
||||
|
||||
Currently covered:
|
||||
|
||||
- `kimi_code_io::tests` — TOML import/export round-trips
|
||||
- `pi_io::tests` — JSON round-trips, including advanced fields (headers/compat/cost/extra)
|
||||
|
||||
### Frontend
|
||||
|
||||
No automated tests yet. Suggested manual checklist:
|
||||
|
||||
- [ ] Switching agents doesn't cross-contaminate configs
|
||||
- [ ] Deleting a provider also deletes its models
|
||||
- [ ] The default model restores correctly after switching providers
|
||||
- [ ] Renaming a provider updates models that reference it
|
||||
- [ ] Raw-JSON editing preserves `raw_other` fields
|
||||
|
||||
## Build & Release
|
||||
|
||||
```bash
|
||||
npm run tauri-build
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
- `src-tauri/target/release/bundle/msi/Pi Switch_0.1.0_x64_en-US.msi`
|
||||
|
||||
A Windows installer (MSI) with the WebView2 bootstrapper embedded for auto-download. `nsis` is disabled; only MSI is produced.
|
||||
|
||||
### First build
|
||||
|
||||
The first run downloads:
|
||||
|
||||
- WiX Toolset 3.14 binaries → `src-tauri/wix314-binaries/`
|
||||
- WebView2 bootstrapper → embedded into the MSI
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Kimi Code didn't pick up the change after switching providers?**
|
||||
A: Run `/reload` inside the Kimi Code session (the CLI only re-reads `~/.kimi-code/config.toml` on reload). The app shows this hint in the UI.
|
||||
|
||||
**Q: I edited the config but closed the window without saving?**
|
||||
A: A native `beforeunload` prompt appears before closing, and the title bar shows a `*` prefix.
|
||||
|
||||
**Q: How do I back up / migrate my config?**
|
||||
A: Back up `%USERPROFILE%\.pi-switch\pi-switch.db`; it holds the full config (including inactive providers).
|
||||
|
||||
**Q: Why can't Vertex AI fetch the model list?**
|
||||
A: Vertex requires GCP project/location credentials. The current implementation leaves a TODO pending GCP SDK integration.
|
||||
|
||||
**Q: macOS / Linux support?**
|
||||
A: The code doesn't depend on Windows-only APIs, but `tauri.conf.json` only targets `msi` for bundling. In theory, changing `bundle.targets` to `["app", "dmg"]` etc. would enable cross-platform builds, but this is unverified.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- API keys are stored in plaintext in the local SQLite database and agent native configs — **do not store them on shared computers**
|
||||
- Do not commit `pi-switch.db`, `config.toml`, or `models.json` to Git
|
||||
- The app CSP is tightened (`default-src 'self'`), but WebView2 may still cache form content — log out when finished on public machines
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Related Projects
|
||||
|
||||
- [Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli) — one of the compatible agents
|
||||
- [Tauri](https://tauri.app) — the desktop app framework
|
||||
- Design specs in `docs/superpowers/specs/`, implementation plans in `docs/superpowers/plans/`
|
||||
|
||||
---
|
||||
|
||||
License: MIT, see [LICENSE](./LICENSE). Copyright (c) 2026 CodingPlan.site
|
||||
Reference in New Issue
Block a user