KimiSwitch Dev
0ce89b09d9
- New README_EN.md with full English documentation mirroring the Chinese README - Add language switcher links (English | 中文) at the top of both files
16 KiB
16 KiB
Pi Switch
Windows 桌面端 LLM 供应商配置管理器，让你在 Kimi Code CLI 和 Pi 两个 Agent 之间无缝切换多家 LLM 供应商与模型。
English | 中文
目录
这是什么
Pi Switch 是一个为 LLM CLI 用户打造的 Windows 桌面配置管理工具。它解决两个痛点：
- 多供应商管理繁琐：在 Kimi / Anthropic / OpenAI / Google GenAI / 自建代理 等多家供应商之间切换时，需要反复手改 TOML/JSON，容易出错。
- 多 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 打包（首次构建自动下载） |
安装
npm install
开发模式（热重载）
npm run tauri-dev
会同时启动 Vite 开发服务器（端口 1420）和 Tauri 窗口，修改前端代码会自动刷新，修改 Rust 代码会重新编译。
仅前端开发（无 Tauri 窗口）
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（开发用） |
添加新供应商类型
- 在
src-tauri/src/models.rs的ProviderType枚举里加新变体 - 在
default_base_url()里加默认值 - 在
commands.rs::list_provider_models的match里加分发 - 在
kimi_code_io.rs::provider_type_for_kimi_type和pi_io.rs::provider_type_for_pi_api里加映射 - 在
src/components/ProviderEdit.tsx的 API 格式下拉里加选项 - 在
src/i18n/{zh,en}.ts里加新的 i18n 键
添加新的 Tauri Command
- 在
src-tauri/src/commands.rs里加#[tauri::command] - 在
src-tauri/src/lib.rs的tauri::generate_handler![...]列表里注册 - 前端用
import { invoke } from "@tauri-apps/api/core"调用 - 在
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 单元测试
cd src-tauri
cargo test
当前覆盖：
kimi_code_io::tests— TOML 导入/导出往返pi_io::tests— JSON 往返，包括 advanced fields（headers/compat/cost/extra）
前端
暂无自动化测试。建议手动验证清单：
- 切换 Agent 时配置互不污染
- 删除供应商时关联模型也清掉
- 切换供应商后默认模型正确回填
- 重命名供应商后引用它的模型也跟着改
- JSON 直编后
raw_other不丢字段
打包发布
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 — 兼容的 Agent 之一
- Tauri — 桌面应用框架
- 设计文档见
docs/superpowers/specs/，实施计划见docs/superpowers/plans/
许可证：MIT，详见 LICENSE。Copyright (c) 2026 CodingPlan.site