dsh-engine-switch

Readme

# dsh-engine-switch

<!-- Hero -->
<div align="center">
  <b style="font-size: 1.15em;">给 DSH 会话换「引擎」——按预设决定由谁来驱动</b><br /><br />
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a><br /><br />
  <img alt="按预设选引擎" src="https://img.shields.io/badge/-按预设选引擎-4d6bfe" /> <img alt="发消息前可切换" src="https://img.shields.io/badge/-发消息前可切换-4d6bfe" /> <img alt="预设自动装好" src="https://img.shields.io/badge/-预设自动装好-4d6bfe" /><br /><br />
  <b>DSH 默认只用 DeepSeek</b>。装上本插件 + 一个引擎插件，<br />
  就能在同一个客户端里按预设切换驱动（DeepSeek ↔ Claude Code ↔ 自定义），不用全局替换、不用改 DSH。
</div>

<div align="center">
  🌏 <a href="./README.md"><b>中文</b></a> · <a href="./README_EN.md">English</a>
</div>

## ✨ 能干什么

- **🔀 按预设选引擎**：每个会话用哪个引擎，由它当前的预设决定。优先级从高到低：预设自己声明 → 配置里点名 → 预设名等于引擎名 → 默认 DeepSeek。
- **🔁 发消息前可切换**：在会话里发第一条消息之前切换预设，会当场换成对应的引擎（两个方向都行），不用重开会话、不用重启。
- **📦 预设自动装好**：引擎装好后，它自带的预设会被自动复制进 DSH 的预设目录，立刻出现在预设列表里。
- **🤝 引擎和会话互不打扰**：引擎不知道「预设」这回事，会话也不知道「被换过引擎」——两边各自干自己的事。
- **🌐 子代理始终用 DeepSeek**：不管顶层会话选了谁，子代理都照旧走 DeepSeek。
- **⏯️ 续聊自动还原**：接着上次的会话聊，会按日志里记下的预设自动找回对应的引擎。

> 🔌 **一句话**：本插件本身**不带任何引擎、也不带任何预设**。它只规定「引擎怎么接入」，然后负责三件事——按预设选引擎、发消息前切换、把预设装好。真正的引擎由别的插件通过 `ctx.engineSwitch.register(engine)` 注册进来。`deepseek` 是个特殊名字，意思是「退回 DeepSeek 原来的循环」。

## 🚀 安装

```sh
dsh plugin --profile web add github:Yuki-takuya-kun/dsh-engine-switch
# 再装至少一个引擎插件，例如：
dsh plugin --profile web add github:Yuki-takuya-kun/dsh-claude-code
```

## ⚙️ 启用

编辑 `~/.dsh/profiles/web/cordis.patch.yml`：

```yaml
- id: dsh-engine-switch
  config:
    enabled: true
```

重启 web 应用。引擎插件带来的预设会出现在预设列表里；选中它 → 用该引擎，选其它 → 用 DeepSeek。

## 🎯 预设怎么指定引擎

大多数时候**什么都不用做**：引擎自带的预设，它的目录名就是引擎名，会自动对上（比如 `dsh-claude-code` 的预设目录叫 `claude-code`，引擎也叫 `claude-code`）。

想手动指定，有两种方式（优先级从高到低）：

1. **在预设里写**：编辑该预设的 `agent.cordis.yml`，加一条 `dsh-engine-switch` 并写 `engine`：

   ```yaml
   # ~/.dsh/.agent-presets/<预设名>/agent.cordis.yml
   - name: dsh-engine-switch
     config:
       engine: claude-code   # 这个预设用 claude-code 引擎
   ```

2. **在配置里点名**：在 `engineByPreset` 里写「预设名 → 引擎名」，不用改预设文件：

   ```yaml
   config:
     engineByPreset:
       research: claude-code
   ```

都没写时，退回 `defaultEngine`（默认 `deepseek`，即 DeepSeek）。

## 🔌 引擎怎么注册

写一个插件，`inject: ["engineSwitch"]`，然后在 `apply` 里调用 `ctx.engineSwitch.register(...)` 注册一个引擎：

```js
export const inject = ["engineSwitch"];
export function apply(ctx) {
  ctx.engineSwitch.register({
    id: "claude-code",              // 引擎名 = 它自带预设的目录名
    name: "Claude Code",
    description: "…",
    presetDir: fileURLToPath(new URL("./presets/claude-code/", import.meta.url)),
    makeAgent(loopCtx, id, options, session, engineConfig) {
      return new ClaudeCodeAgent(loopCtx, id, options, session, engineConfig);
    },
  });
}
```

`presetDir` 里放 `agent.cordis.yml` + `preset.yml`，框架会自动把它装到 `~/.dsh/.agent-presets/<id>/`。引擎要实现的完整接口见 [引擎 API](docs/reference/engine-api.md)。

> 参考引擎：[dsh-claude-code](https://github.com/Yuki-takuya-kun/dsh-claude-code) —— 一个真实注册了 `claude-code` 引擎的插件，用本机 Claude Code CLI 驱动会话。

## ⚙️ 配置

| 键 | 默认 | 含义 |
|---|---|---|
| enabled | false | 总开关：false = 插件不生效，所有会话照旧走 DeepSeek |
| defaultEngine | "deepseek" | 没指定引擎的预设（以及没有预设的会话）用谁；deepseek = 退回 DeepSeek |
| engineByPreset | {} | 「预设名 → 引擎名」的点名表 |
| engines | {} | 「引擎名 → 引擎自己的配置」（原样转给引擎，插件不解析） |

## 🔍 原理（可选阅读）

- 启动时，插件换掉 DSH 原来的「会话驱动工厂」，改成按预设决定引擎的路由器。
- 创建会话、续聊、切换预设时，都会按上面的优先级算出该用哪个引擎，再造出对应的驱动。
- `deepseek` 不是真引擎，而是「退回 DSH 原来的 DeepSeek 循环」。

## 📄 许可证

MIT。见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。