Cherry Studio 教程：从零搭建支持多模型 LLM 的开源 AI 桌面助手（完整指南）-育师

Cherry Studio 教程：从零搭建支持多模型 LLM 的开源 AI 桌面助手（完整指南）

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

Cherry Studio 是一款基于 Electron 的开源 AI 生产力工作室：统一接入 OpenAI、Anthropic、Gemini 等云端模型与 Ollama 等本地模型，内置 300+ 预置助手、知识库、MCP 工具调用与本地 API 网关，支持 Windows、macOS、Linux 三平台。

一个典型的痛点：模型太多，入口太散

如果你同时持有 OpenAI、Anthropic 的 Key，本地又跑着 Ollama，想对比几个模型对同一问题的回答，或者想让某个内部脚本像调用 OpenAI 一样调用自己本地的模型——逐个登录各家 Web 控制台，或者自己写一堆 HTTP 客户端，是常见且繁琐的做法。Cherry Studio 把这件事收敛到一个桌面客户端里：统一的模型管理、并排的多模型对话、文档知识检索，外加一个本地 HTTP 网关供其他程序调用。

项目定位速览：它适合谁，不适合谁

Cherry Studio 解决的核心问题是**"多 LLM 提供商的统一接入与本地化 AI 工作流"**，不解决的问题同样明确：

适合：需要频繁切换/对比多家 LLM 的开发者与重度用户；需要私有化对话（本地模型 + 本地知识库）的场景；希望把本地模型暴露成 OpenAI 兼容 API 给其他工具用的集成需求。
不适合：只需要单一模型 API 调用的轻量脚本场景（直接调官方 SDK 更轻）；它本身不做模型训练与微调。

架构上它是标准 Electron 三进程结构（主进程 / preload / 渲染进程），数据落在本地 SQLite，代码按"主进程业务、渲染进程 UI、共享层原语"分域组织，详见 docs/references/architecture/README.md。

最短上手路径：从 clone 到跑起来

环境要求以 package.json 为准：Node.js>=24.11.1 <24.16.0（版本范围锁定在engines字段，.node-version文件给出确切版本），包管理器为 pnpm（版本锁定在packageManager字段）。

git clone https://gitcode.com/GitHub_Trending/ch/cherry-studio cd cherry-studio corepack enable # 自动启用锁定版本的 pnpm nvm install # 按 .node-version 安装匹配的 Node pnpm install cp .env.example .env pnpm dev # 重建 better-sqlite3 并启动开发模式

说明两点：

pnpm dev会先执行rebuild:electron（强制重建 better-sqlite3 原生模块）并下载运行所需的二进制，所以首次启动较慢属于正常现象。
要出正式安装包用pnpm build:win/pnpm build:mac/pnpm build:linux，它们先跑类型检查再调 electron-builder 打包。

完整开发环境说明（包括 IDE 扩展、Zed 配置、Linux 打包细节）在 docs/contrib/development.md。

能力地图：按"它帮你解决什么"来看

1. 多提供商统一接入——解决"每家模型一套配置"的问题云端支持 OpenAI、Gemini、Anthropic 等主流服务，本地支持 Ollama、LM Studio，并集成了 Claude、Perplexity 等 Web 服务。提供商与模型清单不是硬编码散落的，而是集中维护在 packages/provider-registry/（data/providers.json与models.json），端点如何映射到具体 AI SDK 适配器的规则见 docs/references/ai/provider-resolution.md。

2. 300+ 预置助手 + 多模型并发对话——解决"同一问题横向对比"的问题典型场景：把同一个需求分别发给 GPT、Claude 和 Gemini，并排看回答差异。预置助手覆盖不同角色与领域，也可以自定义；多模型同时回答是它的招牌交互。对话域的代码集中在 src/renderer/components/chat/ 与 src/main/ai/messages/。

3. 知识库与文档处理——解决"让模型读懂你的私有资料"的问题支持文本、图片、Office、PDF 等格式的文档入库，对话时可检索引用；数据支持 WebDAV 备份。知识库服务在 src/main/features/knowledge/，底层向量与数据表结构见 docs/references/data/database-patterns.md。

4. MCP 工具调用——解决"模型只能聊天、不能动手"的问题通过 Model Context Protocol 接入外部工具与 API，模型可以在对话中发起工具调用，且工具执行有独立的审批机制（docs/references/ai/tool-approval.md）。MCP 客户端与工具注册表源码在 src/main/ai/mcp/ 和 src/main/ai/tools/。

5. 本地 API 网关——解决"其他程序也想用我的本地模型"的问题docs/references/api-gateway/README.md 描述的本地 HTTP 网关把 Cherry Studio 自身暴露为 OpenAI、Anthropic、Gemini 及 MCP 兼容端点，源码在 src/main/features/apiGateway/。也就是说，你配好的任意提供商都可以被外部脚本当作标准 API 调用。

关键配置：真正影响体验的少数几项

提供商端点配置：接入一家新模型提供商时，核心是端点配置（endpointConfigs）与adapterFamily字段——它决定请求走哪个@ai-sdk包。写路径与解析链的完整规则见 docs/references/ai/adapter-family.md 和 docs/references/ai/provider-state-ownership.md，配置前读一遍能少走弯路。
模型重试与降级：请求失败时可以在用户侧配置同模型重试和备用模型，行为由chat.retry.*偏好项驱动，实现与配置项说明见 docs/references/ai/model-retry.md。
开发多实例数据隔离：默认开发数据目录在 Electron 的 userData 后追加Dev后缀，与正式包数据分离；同时跑多个开发实例时，在.env里给每个实例设置不同的CS_DEV_USER_DATA_SUFFIX，避免两个实例共享同一目录。
界面语言：界面内置 12 种语言（src/main/i18n/locales/），新增语言或校对词条走pnpm i18n:extract等脚本，规则见 docs/references/i18n/README.md。

二次开发入口：从哪个文件开始看

聊天主链路：从渲染进程useChat()经 Electron IPC 到主进程AiStreamManager，再到 AI Core / Claude Agent SDK 流式回传并落库 SQLite。端到端流程先读 docs/references/ai/core-architecture.md，代码入口是 src/main/ai/AiService.ts 与 src/main/ai/streamManager/。
IPC 契约：通道常量集中在 src/shared/IpcChannel.ts，主进程路由在 src/main/ipc/IpcRouter.ts；新增功能的第一站通常是这里加通道定义。
数据层：SQLite + Drizzle，迁移文件在 migrations/sqlite-drizzle/，数据表与偏好、缓存、应用状态的使用决策见 docs/references/data/README.md。
前端 UI：可复用组件库在 packages/ui/src/components/，页面与业务组件在 src/renderer/，主题与 design token 规范见 packages/ui/docs/design-token-system.md。
测试：单测按进程分 project（pnpm test:main、pnpm test:renderer等），端到端测试在 tests/e2e/ 用 Playwright 驱动，写测试的约定见 docs/references/testing/README.md。

常见坑与排障

Node 版本不对，装依赖或启动就报错。engines锁定>=24.11.1 <24.16.0，24 的其他小版本不满足范围。用nvm install（读.node-version）而不是手动装任意 LTS。
Windows 上 clone 后文件同步异常。项目用符号链接同步 AGENTS.md、skills 等文件，Windows 必须先在"设置 → 开发者模式"开启符号链接支持并执行git config --global core.symlinks true，然后再 clone——顺序反了需要重新 clone，详见 docs/contrib/development.md。
用 npm 代替 pnpm。仓库锁定 pnpm 且package.json的prepare/postinstall脚本（如 dsh-bridge 子包构建、prek 安装）依赖 corepack 环境；直接npm install会跳过这些钩子导致构建失败。
pnpm start与pnpm dev搞混。start是rebuild:electron + electron-vite preview，即预览已构建产物；开发期用dev，它带热更新并会下载运行二进制。