dsh-plugin-reasoning-efforts

Readme

# dsh-plugin-reasoning-efforts

给 DeepSeek Harness (dsh) 的第三方中转模型补上「推理等级」选择器 —— 和官方模型在聊天框里的体验完全一致。

## 它解决什么问题

dsh 聊天框里的推理等级选择器只在模型上报了 `reasoning.efforts` 能力时出现。官方 DeepSeek 通道自带这个能力;但通过 `llm-pi-ai` 手工声明的第三方中转模型(比如各类公益站)默认没有,选择器也就不出现 —— 而 Web 设置页又没有暴露 `reasoningEfforts` 这个字段,想配都没地方配。

本插件监听 `llm-pi-ai` 设置段,按**规则**给匹配的模型自动补写能力声明。写入走 settings 服务正规通道(和 Web 设置页同一条路),改动落在 `~/.dsh/settings.yaml` 里,完全透明可见。合并是幂等的:只补缺失字段,从不覆盖已有声明,已处理过的段落不会再写,不会形成回环。

## 安装后的效果

**默认给所有模型提供统一的 6 档等级,由使用者自己选择合适档位;后端不支持的档位会在请求时报错,换一档即可。**

| 模型族 | 匹配 | 等级 | 默认 | 线上参数 |
|---|---|---|---|---|
| DeepSeek / Reasoner | ID 含 `deepseek` 或 `reasoner` | Off / Low / Medium / High / Xhigh / Max | High | `thinking:{type:"disabled"}`(Off)或 `reasoning_effort` |
| 其他所有模型 | 默认 `.`(全部) | Off / Low / Medium / High / Xhigh / Max | High | `reasoning_effort` |

- DeepSeek 系保持专属方言(Off 才能真正关闭思考),其他模型统一走通用 `reasoning_effort`
- 同一个中转路由上混合多个模型族也没问题:思考方言(`thinkingFormat`)按**模型**写入,不会互相污染
- 之后在中转路由里**新增**任何模型,插件自动跟上,无需再配置

## 环境要求

- dsh 0.1.x(`dsh --version` 确认)
- pnpm(`dsh plugin` 命令依赖;没有就 `npm install -g pnpm`)

## 安装（任选一种）

**方式一：从 GitHub 直接安装（推荐）**

```bash
dsh plugin --profile web add github:chuling-lingling/dsh-plugin-reasoning-efforts
```

**方式二：从 Release tarball 安装**（若网络受限或离线使用）

```bash
dsh plugin --profile web add /path/to/dsh-plugin-reasoning-efforts-0.3.0.tgz
```

**方式四:从本地文件夹安装**

> 注意:文件夹安装是 link 模式,pnpm 不会自动带依赖,需先在插件目录里装一次依赖。

```bash
cd dsh-plugin-reasoning-efforts && pnpm install   # 只需一次
dsh plugin --profile web add /path/to/dsh-plugin-reasoning-efforts
```

安装后**重启 `dsh web`** 即生效,无需任何配置。

## 使用

1. 启动 `dsh web`,打开任意会话
2. 点聊天框底部的「选择模型」按钮
3. 在模型列表里选中转分组下的模型
4. 再点「推理等级」,选择想要的档位
5. 发送消息,等级随每次请求生效

等级选择是会话级的,每个会话可以独立设置。

## 配置(可选)

规则放在 `~/.dsh/settings.yaml` 的 `reasoning-efforts` 段,全部有默认值:

```yaml
reasoning-efforts:
  # 基础规则:默认匹配所有模型(.),统一 6 档 + 通用 reasoning_effort 方言
  patterns: ['.']                  # 模型 ID 匹配(不区分大小写的正则)
  levels: [off, low, medium, high, xhigh, max]
  default: high
  thinkingFormat: openai
  setCompat: true                  # 是否给匹配模型补 thinkingFormat
  providers: []                    # 只处理这些路由;空 = 全部
  # 附加规则:数组顺序即优先级,先命中先生效;都不命中才回落到基础规则
  rules:                           # 内置默认:DeepSeek 系用专属方言
    - patterns: [deepseek, reasoner]
      levels: [off, low, medium, high, xhigh, max]
      default: high
      thinkingFormat: deepseek
```

**按模型族定制方言/档位示例**(默认已覆盖全部模型;只有想给某族换方言或收窄档位时才需要):

```yaml
reasoning-efforts:
  rules:
    # 保留 DeepSeek 内置规则(不写则失去 Off 的真关闭语义)
    - patterns: [deepseek, reasoner]
      levels: [off, low, medium, high, xhigh, max]
      default: high
      thinkingFormat: deepseek
    # 智谱 GLM 系改用 zai 方言(thinking: {type: enabled/disabled} + reasoning_effort)
    - patterns: [glm]
      levels: [off, low, high]
      default: high
      thinkingFormat: zai
```

可选等级全集:`off / minimal / low / medium / high / xhigh / max`。改动保存后自动重新合并,无需重启。

**路由默认等级说明**:插件只会在"该路由上所有已获等级的模型都支持默认值"时才写路由级 `reasoning`(因为不支持的模型会在请求时报错)。混合路由(比如 Grok 和 GLM 同站)如果拿不到默认档,给每条规则配一个共同支持的 `default`,或手动在路由上写 `reasoning:`。

## 卸载

```bash
dsh plugin --profile web remove dsh-plugin-reasoning-efforts
```

已写入 `settings.yaml` 的 `reasoningEfforts` 等字段会保留(它们本身就是合法配置),不需要的话手动删掉即可。

## 已知边界

- 只处理路由里**手工声明**的模型(`models:` 列表);目录路由(pi-ai 自带模型目录)本就有完整能力元数据,无需处理。
- 插件只补缺失字段,不覆盖已有声明:想改某个模型的档位,直接编辑 `settings.yaml`(或删掉该模型的 `reasoningEfforts` 让插件按当前规则重新生成)。
- 扩展档位(Medium / Xhigh 等)以 `reasoning_effort: "<等级>"` 原样发给后端;如果中转不支持某个值,选择后会在请求时报错,切回其他档即可。
- 自定义规则的等级集合请确认中转真实支持,插件无法预先验证。

## 包内容

| 文件 | 说明 |
|---|---|
| `lib/index.js` | 插件代码 |
| `cordis.patch.yml` | profile 层叠补丁(把插件注册进 profile) |
| `package.json` | 包清单;`files` 字段限定发布内容,`node_modules` 不会进包 |
| `README.md` / `LICENSE` / `.gitignore` | 文档与发布辅助 |

发布前检查:`npm pack --dry-run` 应只列出上述核心文件(约 7 kB)。

## 发布指南(维护者)

**发布前一次性检查**(已做过,改代码后重做):

```bash
cd dsh-plugin-reasoning-efforts
node --check lib/index.js      # 语法
npm pack --dry-run             # 检查发布内容
```

**方式一:发布到 npm**(推荐,别人一条命令安装)

```bash
npm login                      # 首次需要,注册:https://www.npmjs.com/signup
cd dsh-plugin-reasoning-efforts
npm publish
```

发布后别人执行 `dsh plugin --profile web add dsh-plugin-reasoning-efforts` 即可。更新版本时:

```bash
npm version patch              # 0.3.0 -> 0.3.1(minor/major 同理)
npm publish
```

**方式二:发布到 GitHub**

```bash
cd dsh-plugin-reasoning-efforts
git init && git add . && git commit -m "dsh-plugin-reasoning-efforts 0.3.0"
git remote add origin https://github.com/<用户名>/dsh-plugin-reasoning-efforts.git
git push -u origin main
```

别人执行 `dsh plugin --profile web add github:<用户名>/dsh-plugin-reasoning-efforts`。

**方式三:直接分发 tarball**

```bash
npm pack        # 生成 dsh-plugin-reasoning-efforts-0.3.0.tgz
```

把 `.tgz` 发给别人,对方执行 `dsh plugin --profile web add <路径>.tgz`(依赖自动装好)。

## 变更记录

- **0.3.0** 默认全部模型统一 6 档(off/low/medium/high/xhigh/max,默认 high)+ 通用 `reasoning_effort` 方言;DeepSeek 系保持专属方言;移除 Grok 特殊规则(并入通用默认)
- **0.2.0** 规则引擎:按模型族的多组有序规则(内置 DeepSeek + Grok);`thinkingFormat` 改为按模型写入,混合路由不再互相污染;路由默认等级只在全路由支持时写入;修复 0.1 中路由级配置泄漏到未匹配路由的问题
- **0.1.0** 初始版本:DeepSeek 系模型自动补推理等级

## 许可证

MIT