# cc-switch-codearts

**Repository Path**: dtse01/cc-swtich-codearts

## Basic Information

- **Project Name**: cc-switch-codearts
- **Description**: 面向 CodeArts / 码道的自定义模型管理工具。它让码道 CLI 和码道桌面端可以接入自定义模型、第三方模型网关和统一的供应商切换能力，同时保留请求路由、用量统计和诊断工具。
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 码道模型切换助手

面向 CodeArts / 码道的自定义模型管理工具。它让码道 CLI 和码道桌面端可以接入自定义模型、第三方模型网关和统一的供应商切换能力，同时保留请求路由、用量统计和诊断工具。

> 这个仓库的主场是码道。项目基于 [CC Switch](https://github.com/farion1231/cc-switch) 二次开发，保留原有多工具配置管理能力，并把 CodeArts / 码道作为默认重点场景进行增强。

## 下载

- [Windows x64 MSI 安装包（码道定制版 3.18.0）](release/CC-Switch-CodeArts-3.18.0-Windows-x64.msi)

> 安装包适用于 64 位 Windows，并内置码道接入所需的代理、路由和运行时辅助组件。使用桌面接入前，请先安装官方码道 / CodeArts Agent 桌面客户端。

当前安装包未进行商业代码签名，Windows 首次运行时可能显示安全提示。

```text
SHA256: 2f456238f841f69bbaffe6ed7212c668209da7ce0b3df2fffd9da4a943718326
```

## 核心能力

- **码道 CLI 供应商管理**：在桌面应用里维护 CodeArts CLI 的模型供应商、API 地址、鉴权信息和模型目录。
- **码道桌面端接入**：自动检查扩展和本地路由状态，提供一键修复与受管桌面端启动入口。
- **自定义模型接入**：维护模型名称、上游模型、显示名称、模型目录等信息，让码道可以使用非默认模型。
- **一键切换供应商**：把当前选中的供应商同步到码道运行环境；桌面端后续请求会立即使用新供应商。
- **托盘快速操作**：最小化 CC Switch 后，仍可从系统托盘切换码道桌面供应商或启动受管码道。
- **用量统计**：将码道 CLI 与桌面端的 token、请求和费用数据纳入统一统计面板。
- **诊断工具**：检查码道安装路径、代理状态、供应商发现、配置导入导出和运行健康度。
- **保留 CC Switch 能力**：继续支持 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等工具的配置管理。

## 适用场景

- 你主要使用码道，希望把自定义模型配置成可视化、可切换、可回滚的供应商。
- 你有多个第三方模型网关，希望在码道 CLI 和桌面端之间统一管理。
- 你需要查看码道调用的 token、请求量和模型用量。
- 你希望保留 CC Switch 原有能力，同时把码道作为默认工作中心。

## 码道工作流

1. 在顶部应用切换器中选择 `CodeArts CLI` 或 `CodeArts Desktop`。
2. 新增或导入模型供应商，填写 API 地址、密钥、模型名称和模型目录。
3. 点击启用，将供应商写入码道运行环境。切换桌面供应商后，后续请求会立即使用新供应商。
4. 打开“码道桌面接入”，检查接入状态；如有异常，点击“修复接入”。
5. 从“码道桌面接入”页面或系统托盘启动码道。
6. 在使用统计面板中查看码道相关的 token、请求和费用数据。

### 从 3.17.0 升级到 3.18.0

升级安装会自动完成数据库迁移，不需要手动修改 `cc-switch.db`：

- **v13 → v14**：为 Grok Build 增加独立的代理配置，保留已有按应用代理设置。
- **v14 → v15**：兼容 Grok Build 的 MCP / Skills 字段，并把 CodeArts CLI 与 CodeArts Desktop 的供应商目录合并到统一的 CodeArts 目录；重复记录会按 CLI 目录优先处理。
- **v15 → v16**：备份数据库后重建 Codex 会话用量。首次启动时 Codex 历史统计可能先减少，再随着后台同步逐步回填，这是修复旧版双计后的预期表现。

升级前如需回退旧版本，建议先备份 `~/.cc-switch/cc-switch.db`。CodeArts 的新请求会按稳定响应标识、应用来源、模型和 token（含缓存归一化输入）做幂等匹配，网关日志与官方本地记录不会再把同一请求统计两次；升级不会自动清理历史上已经写入的重复行。

### 桌面端切换与启动

- 供应商切换后不需要关闭并重新打开 CC Switch；本地运行清单和请求路由会随切换更新。
- 如果码道里的模型列表没有刷新，请从 CC Switch 的“码道桌面接入”页面或系统托盘重新启动码道。
- 当接入状态显示为受管模式时，请不要使用系统原有的码道快捷方式。原快捷方式启动的是官方未接入版本，不会显示 CC Switch 中的自定义模型。
- 使用码道桌面本地路由期间需要保持 CC Switch 运行。
- 码道桌面供应商也会显示在 CC Switch 的系统托盘菜单中，最小化后仍可直接切换供应商。

## 码道界面截图

在顶部应用切换器中选择 `CodeArts CLI` 或 `CodeArts Desktop` 后，可以直接查看当前供应商，并通过右上角添加按钮新增模型供应商。

### CodeArts CLI

CLI 供应商页用于维护命令行侧使用的模型配置、API 地址和用量查询。

![CodeArts CLI 供应商列表](assets/docs/codearts-cli-provider.png)

### CodeArts Desktop

桌面供应商页使用独立的当前供应商，并可通过左上方的绿色路由开关控制桌面接入。蓝色高亮表示当前正在使用的供应商。

![CodeArts Desktop 供应商列表](assets/docs/codearts-desktop-provider.png)

添加供应商时重点关注下面几项：

- **供应商名称**：自己能看懂的名称，例如 `我的码道模型网关`。
- **供应商标识**：写入码道配置的唯一 key，建议使用小写字母、数字和连字符，例如 `my-codearts-gateway`。
- **API 地址**：第三方模型网关或自建服务的 OpenAI 兼容地址。
- **API Key**：对应供应商的访问密钥。
- **模型目录**：把码道里显示的模型名映射到真实上游模型名。

码道 CLI 和桌面端的调用数据会进入统一的使用统计面板，方便查看 token、请求数和成本。

![码道使用统计](assets/docs/codearts-usage-stats.png)

## 与上游的关系

本项目不是 CC Switch 官方版本，而是一个面向 CodeArts / 码道的定制版本。CC Switch 是基础底座，码道增强是本仓库的主要维护方向。

- 上游项目：`farion1231/cc-switch`
- 当前码道定制仓库：`dtse01/cc-swtich-codearts`
- 当前基础版本：已同步 CC Switch `v3.18.0`，并保留 CodeArts / 码道定制改动
- 当前应用版本：`3.18.0`

如需了解 CC Switch 原始功能、安装包和完整说明，请参考上游仓库及本仓库保留的多语言文档：

- [CC Switch 中文原始文档](CC_SWITCH_ZH.md)
- [README_DE.md](README_DE.md)
- [README_JA.md](README_JA.md)

## 开发环境

需要先准备：

- Node.js 18+
- pnpm 8+
- Rust stable
- Tauri 2 开发环境

安装依赖：

```bash
pnpm install
```

启动开发模式：

```bash
pnpm dev
```

常用命令：

```bash
pnpm typecheck
pnpm test:unit
pnpm format:check
pnpm build
```

## 码道相关目录

当前实现会优先使用码道默认目录：

```text
~/.codeartsdoer
```

码道桌面安装位置默认自动检测。检测顺序涵盖环境覆盖、PATH、默认/常见安装目录、运行中进程、Windows 卸载注册表和开始菜单快捷方式。若自动检测失败，可在“设置 → 高级 → 码道安装位置”选择安装根目录；恢复自动检测时清空该覆盖即可。所选目录需要包含：

```text
codearts-agent.exe
resources\app\extensions\vscode-codebot\out\extension.js
resources\app\extensions\vscode-codebot\product.json
```

打包资源中包含码道代理辅助程序：

```text
src-tauri/resources/codeartsagent
```

这些资源用于码道 CLI 代理、Desktop 网关、供应商同步、模型目录处理与用量统计。调整这部分逻辑时，建议同步检查前端“码道桌面接入”页面、Tauri commands、Rust 服务层和测试用例。

## 分支建议

我建议这个仓库按 fork 长期维护的方式来管理：

```text
main                 本地主要开发分支，对应 Gitee 的 master
feature/codearts-*   码道新功能分支
fix/codearts-*       码道问题修复分支
sync/upstream-*      同步上游 CC Switch 时使用的临时分支
release/*            准备打包或发版时使用
```

远程仓库建议这样命名：

```text
origin    你的 Gitee 仓库
upstream  CC Switch 上游仓库或镜像
```

日常开发流程：

```bash
git checkout main
git pull origin master
git checkout -b feature/codearts-your-change

# 开发、测试、提交后
git push -u origin feature/codearts-your-change
```

同步上游时：

```bash
git fetch upstream
git checkout -b sync/upstream-vX.Y.Z main
git merge upstream/main

# 解决冲突并跑测试后，再合并回 main
```

如果只有你一个人维护，也可以直接在 `main` 上开发；但码道相关变更比较大，后续同步上游会有冲突，使用 `feature/*` 和 `sync/*` 分支会更稳。

## 维护注意事项

- 不建议直接删除上游文档、许可证和贡献说明；它们对 fork 的来源说明和许可证合规有用。
- 码道相关功能横跨前端、Rust 后端和内置 Node 资源，改动时不要只测单侧逻辑。
- 打包前建议至少执行 `pnpm typecheck` 与 `pnpm test:unit`。
- `src-tauri/resources/codeartsagent/node/node.exe` 体积较大，如果后续仓库膨胀明显，可以考虑改为构建或安装阶段下载。

## License

本仓库继承上游项目的 MIT License。详见 [LICENSE](LICENSE)。