智能体运行时解锁 Tengzhe-Liu/cherry-studio-unlock

本项目告吹，官方从代码层面删除了 dsh

Cherry Studio Unlock

解锁 Cherry Studio 隐藏的智能体运行时，并管理你已有的智能体。 Unlock the agent runtimes Cherry Studio hides, and manage your agents.

⚠️ 非官方工具。会修改 Cherry Studio 的本地数据（数据库或 app.asar）。
所有写操作都会先自动备份，且大部分操作可一键撤销。请仍然自行留意备份。

中文 ｜ English

它解决什么问题

在 Cherry Studio v1.13.8（app.asar 内 CherryStudio@2.1.6）里可以看到：

运行时确实被实现了，并注册进了驱动表（out/main/main.js）：

runtimeDriverRegistry.register(new LazyClaudeCodeRuntimeDriver());
runtimeDriverRegistry.register(new PiRuntimeDriver());
runtimeDriverRegistry.register(new DshRuntimeDriver()); // ← dsh 在

AGENT_RUNTIME_CAPABILITIES 里也有完整的一项，界面文案是「DeepSeek Harness」。

但新建智能体的选择器把它过滤掉了（out/renderer/assets/EditDialogShared-.js）：

var RUNTIMES = Object.keys(AGENT_RUNTIME_CAPABILITIES).filter((runtime) => runtime !== "dsh");

于是「运行时模式」只剩 Claude Agent 和 Pi 两个可选项。

本工具做两件事，二选一或都做：

| 方式 | 做法 | 效果 |
| 打补丁（推荐） | 把 runtime !== "dsh" 换成等长的恒真表达式 | Cherry Studio 原生界面里直接能新建 dsh 智能体 |
| 写数据库 | 直接往 agent 表插一行 type='dsh' | 不用改程序文件，升级后通常仍可用 |

快速开始

下载即用

到 Releases 下载对应平台的文件，双击运行，浏览器会自动打开界面。

| 平台 | 文件 |
| Windows | cherry-studio-unlock_windows_amd64.exe |
| macOS (Apple Silicon) | cherry-studio-unlock_darwin_arm64 |
| macOS (Intel) | cherry-studio-unlock_darwin_amd64 |
| Linux | cherry-studio-unlock_linux_amd64 |

无依赖，不需要装 Node、Python 或任何运行时。

命令行

cherry-studio-unlock # 自动探测环境并打开界面 cherry-studio-unlock --status # 只打印自检结果 cherry-studio-unlock --lang en # 以英文界面启动 cherry-studio-unlock --port 8765 # 指定端口 cherry-studio-unlock --no-open # 不自动开浏览器 cherry-studio-unlock --data-dir DIR # 手动指定数据目录 cherry-studio-unlock --asar FILE # 手动指定 app.asar

界面语言

界面右上角可以在 中文 / English 之间切换，选择会被记住。
切换是整体生效的：UI 文案、运行时状态判定、以及后端返回的错误信息都会跟着切换，不会出现"界面是英文、报错是中文"的割裂。

命令行同样支持：--lang zh|en。未指定时的优先级是 命令行参数 → 配置文件 → 环境变量（LANG / LC_ALL）→ 中文。

从源码构建

git clone <this repo>
cd cherry-studio-unlock
make build # 或：go build .
make release # 交叉编译五个平台到 dist/

只需要 Go 1.22+，不需要 cgo（SQLite 用的是纯 Go 实现）。

使用步骤

1. 完全退出 Cherry Studio —— 包括右下角托盘图标 → 退出。
它在内存里缓存了智能体列表，运行中写入会被覆盖。工具会检测并拒绝写操作。
2. 运行本工具。
3. 在「运行时」一栏确认 dsh 显示为「被隐藏」。
4. 点 打补丁解锁（或跳过这步，直接用下面的「新建智能体」）。
5. 重新打开 Cherry Studio —— 新建智能体时就能选到 DeepSeek Harness 了。

如果你更想走数据库那条路：直接在工具里点「新建智能体」，运行时选 dsh 即可。

想改回去？点「撤销补丁」，或用任意一条备份一键恢复。

遇到问题

「运行时」是空的 / 选不了运行时

原因：没找到 app.asar。 运行时列表是从 app.asar 里扫出来的，扫不到就列不出来。

Cherry Studio 装在标准位置（如 Program Files）时工具能自动找到；装在自定义目录（如 C:\app\AI\Cherry Studio）时，工具按这个顺序找：

1. 上次记住的路径（存在数据目录下的 cherry-studio-unlock.json）
2. 正在运行的进程 —— 但写数据前你必须先退出 Cherry Studio，这条路就断了
3. Windows 注册表的卸载项
4. 常见安装位置

如果都没命中，在「环境」一栏手动填入路径即可，填一次会记住：

<Cherry Studio 安装目录>\resources\app.asar

不确定装在哪？在 Cherry Studio 里看「关于」，或从开始菜单快捷方式上右键 → 打开文件所在位置。

v0.1 的初版有过这个 bug：只靠「运行中的进程 + 常见路径」两条线，于是用户按提示退出 Cherry Studio 之后反而找不到 app.asar，而退出恰恰是唯一允许写数据的场景。现已加入注册表反查与路径记忆，并有端到端回归测试（TestAsarLookupDoesNotDependOnRunningProcess）锁住这个行为。

保存按钮是灰的

- Cherry Studio 正在运行 —— 请完全退出（含托盘图标）后重开本工具。
- 上方有红框提示列不出运行时 —— 需要先指定 app.asar，或明确勾选「跳过运行时校验」（不推荐，可能创建跑不起来的 Agent）。

打了补丁但界面里还是没有 dsh

1. 确认补丁状态显示「已生效」；
2. 重启 Cherry Studio —— 补丁改的是启动时加载的文件；
3. 如果重启后仍没有，说明这个版本的过滤方式变了，请跑一次 --status 并把结果贴到 issue。

安全设计

这个工具会碰你的数据，所以设计上做了这些事：

- 写前必备份。 每次写操作前把 cherrystudio.sqlite（连同 -wal/-shm）复制到 <数据目录>/backups-manual/cherry-studio-unlock/，并写一份 manifest.json。
- 撤销本身也可撤销。 从备份恢复前，会先把当前状态再存一份，所以点错也能回头。
- 等长替换。 打补丁只把 runtime !== "dsh" 这 17 个字节换成 true /unlocked/——长度完全相同，因此不需要重写整个 288MB 的归档，也不会改变文件大小。
补丁记录只保存被替换的那几个字节，撤销成本极低。
- 撤销前校验上下文。 Cherry Studio 升级后 app.asar 会变，旧偏移量就失效了。
撤销前会比对改动位置两侧各 32 字节的哈希，不一致就拒绝执行，而不是把文件改坏。
- 拒绝往不认识的库里写。 打开数据库时先校验 agent 表的列是否齐全；对不上就明确报错，绝不将错就错地塞数据。
- 拒绝创建跑不起来的 Agent。 写入前会扫描 app.asar，确认目标运行时确实被实现了。
- 本地回环。 服务只监听 127.0.0.1，同网段和外网都碰不到。
- 校验 Host 与 Origin。 只监听回环还不够：恶意网页可以用不触发 CORS 预检的「简单请求」向 127.0.0.1:端口 发 POST，虽然读不到响应，但删除 Agent、打补丁这些副作用已经发生了。所以改数据的请求会校验 Origin 必须同源，Host 必须指向本机（后者同时挡住 DNS rebinding）。

它是怎么工作的

internal/
├── asar/ 纯 Go 解析 Electron 的 .asar 归档（含 poke 式的原地改写支持） ├── cherry/ 环境探测：数据目录、进程状态、运行时扫描、备份 ├── store/ SQLite 读写 + fractional-indexing 排序键算法 ├── patch/ app.asar 补丁（等长替换 + 可撤销） ├── service/ 用例编排：备份 → 校验 → 写 → 建目录 → 自检 └── web/ 本地 HTTP 服务 + 内嵌界面

两个值得一提的地方：

排序键算法是逐行移植的。 Cherry Studio 用 fractional-indexing@3.2.0 生成 order_key。
我们自己造一套键的话，新 Agent 会和 App 后续新建的 Agent 抢位置。所以这里把上游实现完整移植到 Go，并用从真实 app.asar 里提取的那份 JS 实现生成 94 条测试向量逐条比对——断言的是"和 Cherry Studio 生成的键完全一致"，不是"看起来差不多"。

运行时是扫出来的，不是写死的。 工具不认 dsh 这个名字，而是从 app.asar 里解析出 AGENT_RUNTIME_CAPABILITIES 的键集合、runtimeDriverRegistry.register(...) 的驱动列表，以及给新建界面做过滤的那条语句。以后 Cherry Studio 藏了别的运行时，工具会自动发现。

已知限制

- Cherry Studio 升级后补丁会失效。 升级会覆盖 app.asar，重新跑一次即可。
- 数据库表结构大改时「写数据库」那条路会失效，届时工具会明确报错而不是写坏数据。
- 只处理 runtime !== "X" 形式的过滤。 如果某版本改用 === 白名单形式，工具会拒绝打补丁并说明原因（不会瞎改）。
- 不做 diff 式重打包。 需要改变文件长度时（例如过滤语句结构变化）目前不支持。

Roadmap

- [ ] 注入全新的第三方运行时（opencode 等）。
这不是「解锁」而是「实现」——需要对着 Cherry Studio 未公开的内部接口写完整驱动，并补丁主进程与渲染进程。可行性评估见 docs/runtime-injection.md。
- [ ] 备份自动清理（保留最近 N 份）
- [ ] Agent 导入/导出

贡献

欢迎 issue 与 PR。特别是：在别的 Cherry Studio 版本上跑一次 --status，把结果贴出来——不同版本的打包产物结构可能不一样，这能帮工具适配得更广。

go test ./... # 单元测试
CHERRY_ASAR=/path/to/app.asar go test ./... -run Real -v # 对着真实归档做集成测试
CHERRY_DB=/path/to/cherrystudio.sqlite go test ./... -run CRUD -v

集成测试都会先复制一份再到副本上操作，不会碰你的正式数据。

免责声明

本项目与 Cherry Studio 官方无关，未获其授权或认可，也不代表其立场。
项目名与文档中出现的 "Cherry Studio" 仅用于说明兼容对象，不构成任何官方关联的暗示。
本项目不包含也不分发 Cherry Studio 的任何代码或二进制。

为什么官方要隐藏 dsh？——我们不知道，也不猜

工具只描述可观察到的现象（app.asar 里那行 .filter((runtime) => runtime !== "dsh")），
不替官方解释动机。有一个值得注意的技术细节：

"claude-code": { ..., heartbeat: true, ... },
pi: { ..., heartbeat: true, ... },
dsh: { ..., heartbeat: false, ... }, // ← 只有它是 false

heartbeat 为 false 意味着该运行时不被支持用于定时任务（心跳）。
这可能说明 dsh 在那个版本里还不够完备——但这是推测，不是结论。

本工具不会改变这一点。 它只是把创建入口打开，运行时的成熟度仍取决于官方实现。
是否要在重要场景里使用 dsh Agent，请自行判断。

风险

- 修改的是你自己机器上、你自己的数据；
- 所有写操作前都会自动备份，且大部分可撤销——但没有任何担保，请仍然自行保留备份；
- 打补丁改的是程序文件，每次 Cherry Studio 升级后需要重新打一次；
- 若官方后续开放了这个运行时的创建入口，本工具即可功成身退。

致谢

这个工具是站在别人肩膀上做出来的：

- Cherry Studio —— 宿主应用。本工具所做的一切，都建立在它已经内置了 dsh 运行时这个事实之上。
- DeepSeek Harness（dsh，MIT） —— 本工具存在的理由。它不是我们写的；我们只是把 Cherry Studio 里已经装好、却在界面上被藏起来的入口打开。
- fractional-indexing（Rocicorp，MIT）—— Cherry Studio 用它生成 order_key。本工具逐行移植了这份实现，确保两边生成的键完全一致。
- modernc.org/sqlite（BSD-3-Clause）—— 纯 Go 的 SQLite 实现，让本工具不需要 cgo 就能交叉编译。

特别说明：以上项目与本工具没有隶属或认可关系。列在这里是为了说明技术来源，不构成任何关联的宣称。

License

本项目代码以 MIT 授权。
第三方组件的许可与出处见 THIRD-PARTY-NOTICES.md。

解锁 Cherry Studio 藏起来的智能体运行时，顺便管理你的智能体。

Cherry Studio 内置了 DeepSeek Harness（dsh）运行时——驱动、能力表、工具、图标、翻译，一应俱全——但你在新建智能体对话框里选不到它。
本工具打开这道人为封锁，顺带给你一个智能体管理器。

⚠️ 非官方工具。它会改动 Cherry Studio 的本地数据（数据库，或 app.asar）。
每次写入前都会自动备份，大部分操作一键即可撤销。
但还是请你自己留好备份。

中文 ｜ English

它解决什么问题

在 Cherry Studio v1.13.8（app.asar 内的 CherryStudio@2.1.6）里：

运行时确实已经实现并注册（out/main/main.js）：

runtimeDriverRegistry.register(new LazyClaudeCodeRuntimeDriver());
runtimeDriverRegistry.register(new PiRuntimeDriver());
runtimeDriverRegistry.register(new DshRuntimeDriver()); // ← dsh is right here

AGENT_RUNTIME_CAPABILITIES 里也有它的完整条目，标签是「DeepSeek Harness」。

但新建对话框把它过滤掉了（out/renderer/assets/EditDialogShared-.js）：

var RUNTIMES = Object.keys(AGENT_RUNTIME_CAPABILITIES).filter((runtime) => runtime !== "dsh");

于是「运行时模式」只提供 Claude Agent 和 Pi。

本工具做两件事——任选其一，或两者都用：

| 方式 | 做什么 | 结果 |
| 打补丁（推荐） | 把 runtime !== "dsh" 换成等长的恒真表达式 | dsh 在 Cherry Studio 自己的对话框里可选 |
| 数据库写入 | 向 agent 表插入一行，type='dsh' | 不改动任何程序文件，通常能扛过更新 |

快速开始

下载并运行

从 Releases 下载对应平台的文件，运行后浏览器会自动打开界面。

| 平台 | 文件 |
| Windows | cherry-studio-unlock_windows_amd64.exe |
| macOS（Apple 芯片） | cherry-studio-unlock_darwin_arm64 |
| macOS（Intel） | cherry-studio-unlock_darwin_amd64 |
| Linux（x86_64） | cherry-studio-unlock_linux_amd64 |
| Linux（ARM64） | cherry-studio-unlock_linux_arm64 |

零依赖——不用装 Node，不用装 Python，也不用装运行时。

命令行

cherry-studio-unlock # detect the environment and open the UI
cherry-studio-unlock --status # print the self-check and exit
cherry-studio-unlock --lang en # start with the English UI
cherry-studio-unlock --port 8765 # pick a port
cherry-studio-unlock --no-open # do not open a browser
cherry-studio-unlock --data-dir DIR # set the data directory manually
cherry-studio-unlock --asar FILE # set app.asar manually

界面语言

右上角可在中文 / English 之间切换，选择会被记住。切换是全局的：界面文字、运行时判定、后端报错都跟着变——不会出现英文界面却抛中文错误的情况。

命令行也支持：--lang zh|en。不传时按 参数 → 配置文件 → 环境变量（LANG / LC_ALL）→ 中文 的顺序决定。

从源码构建

git clone <this repo>
cd cherry-studio-unlock
make build # or: go build .
make release # cross-compile all five platforms into dist/

只需要 Go 1.22+。不用 cgo——SQLite 是纯 Go 实现。

操作步骤

1. 彻底退出 Cherry Studio——包括托盘图标 → 退出。
它会把智能体列表缓存在内存里，覆盖掉你的改动；工具能检测到这种情况，并拒绝写入。
2. 运行本工具。
3. 在 Runtimes 卡片里确认 dsh 显示为 Hidden。
4. 点 Unlock with patch（也可以跳过这步，改用下面的「New agent」）。
5. 重新打开 Cherry Studio——创建智能体时已经能选到 DeepSeek Harness。

更想走数据库这条路？直接在本工具里点 New agent，选 dsh 就行。

想还原？点 Revert patch，或者一键恢复任意备份。

疑难排查

Runtimes 列表是空的 / 选不到运行时

原因：没找到 app.asar。 运行时列表是从 app.asar 里扫出来的。

Cherry Studio 装在标准位置（比如 Program Files）时，工具会自动找到。否则按下面的顺序尝试：

1. 上次记住的路径（数据目录里的 cherry-studio-unlock.json）
2. 正在运行的进程——但写入前你必须退出 Cherry Studio，所以这条基本走不通
3. Windows 注册表里的卸载项
4. 常见安装位置

如果都没找到，就在「环境」卡片里手动设置路径 —— 设置一次之后会记住：

<Cherry Studio install dir>\resources\app.asar

不确定装在哪？打开 Cherry Studio 里的「关于」看看，或者右键开始菜单快捷方式 → 打开文件所在位置。

v0.1 首个版本有这个 bug：只认「运行中的进程 + 标准路径」，于是照着说明先退出 Cherry Studio 的用户反而找不到 app.asar —— 而退出恰恰是唯一允许写入的场景。现在加了注册表查找和路径记忆，并由端到端回归测试锁死（TestAsarLookupDoesNotDependOnRunningProcess）。

保存按钮是灰的

- Cherry Studio 正在运行 —— 彻底退出（包括托盘图标），再重新打开本工具。
- 红框提示无法列出运行时 —— 先设置 app.asar，或者显式勾选「跳过运行时检查」（不推荐；可能创建出跑不起来的智能体）。

补丁打上了，对话框里还是没有 dsh

1. 确认补丁状态显示为 active；
2. 重启 Cherry Studio —— 补丁改的是启动时加载的文件；
3. 还是没有，说明这个版本的过滤方式不一样。运行 --status，把输出贴到 issue 里。

安全设计

本工具会动你的数据，所以：

- 每次写入前先备份。 cherrystudio.sqlite（连同 -wal/-shm）复制到 /backups-manual/cherry-studio-unlock/，并附一份 manifest.json。
- 撤销本身也能撤销。 恢复备份之前，先把当前状态也存一份。
- 等长替换。 补丁把 runtime !== "dsh" 这 17 个字节换成 true /unlocked/ —— 长度完全一致。这样就不必重写整个 288 MB 的归档，文件大小也不变。只备份被替换的那几个字节。
- 回退前先校验上下文。 Cherry Studio 更新会改动 app.asar，旧偏移量随之失效。回退之前，工具会计算改动位置两侧各 32 字节的哈希，对不上就拒绝执行 —— 而不是把文件写坏。
- 拒绝未知表结构。 打开数据库时先校验 agent 表的列；对不上直接报错，绝不半盲插入。
- 拒绝创建跑不起来的智能体。 写入前先扫描 app.asar，确认目标运行时确实有实现。
- 只监听回环地址。 服务监听 127.0.0.1，其他机器访问不到。
- 校验 Host 和 Origin。 光有回环还不够：恶意网页可以用 CORS 简单请求向 127.0.0.1:port 发 POST。它读不到响应，但副作用 —— 删除智能体、打补丁 —— 已经发生了。所以写操作的请求必须带同源 Origin，Host 必须指向本机（这同时挡住了 DNS 重绑定）。

工作原理

internal/
├── asar/ Electron .asar 归档的纯 Go 解析器（支持原地修改） ├── cherry/ 环境：数据目录、进程状态、运行时扫描、备份 ├── store/ SQLite 访问 + 分数索引排序键算法 ├── patch/ app.asar 补丁（等长替换，可回滚） ├── service/ 用例编排：备份 → 校验 → 写入 → 创建目录 → 验证 └── web/ 本地 HTTP 服务器 + 内嵌 UI

有两点值得特别说明：

排序键算法是逐行移植的。 Cherry Studio 用 fractional-indexing@3.2.0 生成 order_key。自己造一套键，新智能体会和 app 之后创建的智能体撞车。所以上游实现被完整移植到 Go，并用 94 个测试向量校验——这些向量从真实 app.asar 里抽出的 JS 实现生成。断言是「与 Cherry Studio 生成的字节完全一致」，不是「差不多就行」。

运行时靠扫描，不写死。 工具并不认识 dsh 这个名字；它从 app.asar 里解析 AGENT_RUNTIME_CAPABILITIES 的键、runtimeDriverRegistry.register(...) 的驱动列表，以及守卫创建对话框的过滤语句。Cherry Studio 以后要是再藏一个运行时，工具自己就能找出来。

已知限制

- Cherry Studio 更新会破坏补丁。 更新会覆盖 app.asar；重新跑一遍就行。
- 数据库结构大改会破坏数据库路线——工具会明确报错，而不是写入坏数据。
- 只处理 runtime !== "X" 这种过滤写法。 如果某个版本改成 === 白名单，工具会拒绝打补丁并说明原因（它不会瞎猜）。
- 不支持 diff 式重新打包。 改变文件长度（比如过滤语句结构变了）暂不支持。

路线图

- [ ] 注入全新的第三方运行时（opencode 等）。
这不算「解锁」，而是「实现」：针对 Cherry Studio 未公开的内部结构写完整驱动，并同时给主进程和渲染进程的 bundle 打补丁。可行性报告见 docs/runtime-injection.md。
- [ ] 自动清理备份（保留最近 N 份）
- [ ] 智能体导入/导出

参与贡献

欢迎提 Issue 和 PR。尤其欢迎：在另一个 Cherry Studio 版本上跑 --status，把输出贴过来——不同版本的 bundle 布局不一样，这正是工具能适配的原因。

go test ./... # unit tests
CHERRY_ASAR=/path/to/app.asar go test ./... -run Real -v # integration vs. a real archive
CHERRY_DB=/path/to/cherrystudio.sqlite go test ./... -run CRUD -v

每个集成测试都会先复制归档/数据库，再在副本上操作——你的真实数据永远不会被动到。

免责声明

本项目与 Cherry Studio 无关联、未获其授权、也未获其背书，且不表明其立场。「Cherry Studio」在此出现，仅用于说明本工具兼容的对象。本项目不包含、也不分发 Cherry Studio 的任何代码或二进制文件。

厂商为什么隐藏 dsh？—— 我们不知道，也不猜

本工具只描述可观察到的事实（app.asar 里那行 .filter((runtime) => runtime !== "dsh")），不推断动机。不过有个细节值得注意：

"claude-code": { ..., heartbeat: true, ... },
pi: { ..., heartbeat: true, ... },
dsh: { ..., heartbeat: false, ... }, // ← the only one that is false

heartbeat: false 表示该运行时不支持定时任务（心跳）。这或许说明 dsh 在那个版本里还没做完 —— 但这只是猜测，不是结论。

本工具改变不了这些。 它只打开创建入口；运行时成熟与否，仍取决于厂商的实现。要不要把重要的事交给 dsh 智能体，你自己判断。

风险

- 它会修改你自己机器上的你自己的数据；
- 每次写入前都会先备份，多数操作可以回退 —— 但不提供任何担保。请自行保留备份；
- 打补丁会改动程序文件，每次更新 Cherry Studio 后都必须重新打；
- 如果厂商重新启用这个运行时，本工具就完成了使命，可以退役了。

致谢

本工具站在别人的肩膀上：

- Cherry Studio —— 宿主应用。本工具做的一切，都建立在它已经内置 dsh 运行时这一事实上。
- DeepSeek Harness（dsh，MIT） —— 本工具存在的原因。它不是我们写的；我们只是打开了一个入口，而这个入口早已装在 Cherry Studio 里，只是被藏在 UI 中。
- fractional-indexing（Rocicorp，MIT）—— Cherry Studio 用它生成 order_key。我们逐行移植了实现，让两边生成的键完全一致。
- modernc.org/sqlite（BSD-3-Clause）—— 纯 Go 的 SQLite 实现，让本工具无需 cgo 即可交叉编译。

注意：以上项目均与本工具无隶属关系，也未为其背书。列出它们是为了标明技术来源，而非声称任何关联。

许可证

MIT —— 见 LICENSE。
第三方组件及其许可证：THIRD-PARTY-NOTICES.md。