> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/cherry-studio/installation/v1-v2-feature-differences.md).

# 功能差异

V2 调整了数据结构和多项功能入口。升级前先看需要重新配置的项目；具体步骤见 [【V1 升级到 V2】](/cherry-studio/installation/v1-to-v2-migration.md)。

## V2.0.2 迁移变化

| 情况        | V2.0.2 的处理方式            | 注意事项                           |
| --------- | ----------------------- | ------------------------------ |
| 首次从 V1 迁移 | 可以从 V1.9.13 直接安装 V2.0.2 | 不再需要先安装 V2.0.0。                |
| 正常升级 V2   | 直接升级并继续使用当前 V2 数据       | 不要点击【重新迁移】。                    |
| 重新迁移 V1   | 在【设置】→【数据】选择【重新迁移】      | 当前 V2 数据会被永久删除，只用于此前迁移失败或遗漏数据。 |

{% hint style="danger" %}
【重新迁移】不会把 V1 数据补充合并到当前 V2。它会先删除当前 V2 数据，再从保留的 V1 数据重新导入。不是 V1 迁移失败或遗漏数据时，一定不要点击。
{% endhint %}

## 数据如何处理

| 处理方式 | 数据范围                                                                  | 升级后要做什么       |
| ---- | --------------------------------------------------------------------- | ------------- |
| 自动迁移 | 设置、模型服务与模型、助手与分组、会话与消息、Agent 与会话、MCP、知识库及有效索引、文件、绘画、翻译、笔记、提示词、用量记录    | 抽查常用项目能否正常打开。 |
| 需要复核 | Anthropic 凭据、网络搜索默认服务、Agent 工具权限与知识库绑定、提示词顺序、知识库失败项、自定义 CSS、侧栏收藏、缺失文件 | 按下表重新确认。      |
| 不会继承 | Agent 定时任务历史记录、旧版站点地图展开结果、部分临时图片引用、笔记当前打开状态、已移除功能的配置                  | 需要时重新创建。      |

{% hint style="info" %}
迁移不会删除 V1 原始数据。V2 新数据不会同步回 V1，两个版本的备份也不能相互恢复。
{% endhint %}

## 主要差异

| 功能              | V1                              | V2                                            | 升级后要做什么                          |
| --------------- | ------------------------------- | --------------------------------------------- | -------------------------------- |
| 助手与提示词          | 独立助手库；快捷短语可与助手关联                | 助手在聊天和 Agent 中管理；快捷短语合并为全局提示词                 | 检查助手分组和提示词顺序。                    |
| Agent           | 部分配置和工作区跟随会话；旧授权可自动批准工具         | 身份、记忆和主要配置归 Agent；会话创建后工作区固定；工具可能重新请求授权       | 检查模型、工作区、工具和权限。                  |
| Agent 知识库       | 知识工具可能访问全局知识库                   | 只访问显式绑定的知识库                                   | 为每个 Agent 重新核对知识库绑定。             |
| 知识库检索           | 可手动选择检索模式和站点地图来源                | 无嵌入模型时使用 BM25，有嵌入模型时使用混合检索；站点地图按普通网址处理        | 检查嵌入与重排序模型；重建失败来源。               |
| 网络搜索            | 可在助手或输入区选择服务；含本地搜索、RAG 压缩和订阅黑名单 | 在【设置】→【网络搜索】分别配置关键词搜索和网址读取；相关旧选项移除            | 重新选择两项默认服务并检查凭据。                 |
| MCP             | 已添加服务和第三方发现市场并存                 | 已添加服务继续迁移；旧第三方发现市场不再提供                        | 检查服务状态；新服务从当前市场或 JSON 添加。        |
| 模型服务            | Anthropic 可保存 OAuth 凭据          | Anthropic OAuth 不迁移；AWS Bedrock 区域保留；新增服务默认关闭 | 为 Anthropic 重新填写 API Key，按需启用服务。 |
| 文件              | 文件副本与业务对象的引用关系较弱                | 托管文件按引用管理；最后一个引用删除后会延迟清理托管副本                  | 长期保留的文件放入【文件】或导出；用户原文件不会被删除。     |
| 绘画、Mini App 与侧栏 | 参数和入口位于旧版区域                     | 绘画参数移到提示词工具栏；Mini App 在顶部标签栏；侧栏收藏重置           | 熟悉新入口并重新设置收藏。                    |
| 自定义 CSS         | V1 选择器直接生效                      | 内容保留，但迁移后默认禁用                                 | 按 V2 选择器适配后再启用。                  |
| Code CLI        | 可选择 iFlow                       | iFlow 由 Qoder 替代                              | 需要相关工作流时改用 Qoder。                |

## 开发者兼容性

<details>

<summary>API 与外部集成有哪些变化？</summary>

* API Gateway 的模型标识由 `provider::model` 改为 `provider:model`。
* Knowledge API 返回条目使用 V2 字段。
* MCP-over-HTTP 端点已移除，不影响应用内 MCP。
* SSE 启动失败可能直接返回普通 HTTP 错误，客户端需同时兼容 HTTP 与 SSE 错误路径。
* 定时任务接口参数已变化，历史运行记录不会迁移。

</details>

## 参考资料

* [V1 升级到 V2](/cherry-studio/installation/v1-to-v2-migration.md)
* [Cherry Studio V2 官方下载](https://cherryai.com.cn/download)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/cherry-studio/installation/v1-v2-feature-differences.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.