推理等级配置 qmy777/dsh-ui-models-reasoning

简体中文 · English

一个分节，逐模型配置推理等级。

dsh-ui-models-reasoning 在 DeepSeek Harness 的设置对话框里新增一个独立的 推理等级 分节，用来配置 OpenAI 兼容第三方提供方（pi-ai 路由）的逐模型 reasoningEfforts 映射——模型提供哪些档位、每个档位发送什么线格式值——全程不修改任何内置源码。

内置「模型」页保持原样、保持启用。插件注册的是自己的设置分节，因此启用、停用或移除它都不会与出厂 UI 冲突。

为什么选择它？

| 能力 | 带来的改变 |
| 逐模型档位 | 每个模型独立声明 off / 最低 / 低 / 中 / 高 / 极高 / 最高——同一提供方下各模型接受的档位并不一致，因此不做提供方级控件。 |
| 线格式值映射 | 每个档位携带端点期望的拼写（high: high、max: ultra），网关的词汇差异在配置层适配，请求代码零改动。 |
| 与适配器规则对齐的校验 | 写入前逐条执行 llm-pi-ai 的校验规则：off 可留空（「支持但不发送」）、其余档位必须有非空发送值、至少声明一个非 off 档位。 |
| 天生可插拔 | 一行 patch 挂载，注释掉即停用；不编辑任何内置文件，harness 升级不会破坏它。 |
| 冲突安全的写入 | 保存携带 settings revision，并发修改以 settings-conflict 拒绝而非静默覆盖。 |
| 只读感知 | 只读设置部署下，整个分节自动禁用。 |

用 AI 安装（复制即用）

把下面整段文字发给你的 AI 编码助手（dsh、Claude Code、Codex 等），它会读完本 README 并自动完成安装：

请帮我安装 dsh-ui-models-reasoning 插件（含随插件分发的 supportsDeveloperRole 兼容补丁）。
仓库位置：本仓库目录（README 所在目录）。
安装要求：
1. 按 README.md 的「安装」章节完成插件本体安装（在目标 profile 的 package.json 声明 file: 依赖、在 cordis.patch.yml 追加挂载行、pnpm install）；
2. 按 README.md 的「兼容补丁」章节运行补丁安装与自检（scripts/install-compat.mjs、scripts/verify-compat.mjs）；
3. 完成后告诉我需要重启哪个 profile 的 dsh。

提示：也可直接把本仓库的 README.md 丢给 AI 阅读，它在「安装」与「兼容补丁」两节有全部细节。

安装

[!NOTE]
需要已安装 DeepSeek Harness （DSH Desktop 或 dsh web）且配有 profile——本指南以 desktop profile 为例。

1. 添加依赖

在 ~/.dsh/profiles/desktop/package.json 中声明本地目录依赖：

"dependencies": {
"dsh-ui-models-reasoning": "file:/path/to/dsh-ui-models-reasoning"
}

该包必须能从 profile 目录解析（在 ~/.dsh/profiles/desktop/node_modules/ 内做指向项目目录的符号链接即可；pnpm install 会按 file: 依赖落盘）。

2. 挂载插件行

在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加：

- insert:
- id: dsh-ui-models-reasoning
name: dsh-ui-models-reasoning

3. 重启

重启 DSH Desktop（或刷新 web UI）。设置对话框在「模型」之后出现 推理等级 分节。

停用 / 卸载

编辑 ~/.dsh/profiles/desktop/cordis.patch.yml，注释掉插入的行（或改为 disabled: true），然后重启：

- insert:
- id: dsh-ui-models-reasoning
name: dsh-ui-models-reasoning

彻底移除还需删除 package.json 里的依赖与 node_modules 链接。无论启用还是停用，内置「模型」页都不受影响。

工作原理

1. 打开分节时读取 llm-pi-ai settings namespace，列出所有已配置模型的路由。
2. 每个模型行把存储的 reasoningEfforts 呈现为三种状态：跟随适配器默认 （字段缺省）、关闭思考（false）、自定义等级（档位 → 发送值字典）。
3. off 留空存储为无值形式（off:），pi-ai 读作「支持但不发送该参数」。
4. 保存按「整数组替换」语义改写路由的生效 models 数组——与内置模型页一致——本分节不展示的字段原样保留。
5. 写入携带 namespace revision；任何位置的并发修改都会以 settings-conflict 拒绝，而不是被静默覆盖。
6. 输入框的模型选择器随后只为该模型提供已声明的档位：

分节在打开时和每次保存后重新加载数据。如果在「模型」页新增了厂商或模型，打开分节后点击标题右侧的 刷新 按钮即可立即拉取最新的路由与模型列表，无需关闭设置对话框。

默认推理等级（参考）

以下映射取自当前 ~/.dsh/settings.yaml 中 bailian-token 路由的实测配置，可作为百炼平台（openai-completions + thinkingFormat: qwen）的参考默认值。off 表示「支持但不发送该参数」；未列出的档位在模型选择器中不出现。

| 模型 | 档位 → 发送值 |
| deepseek-v4-pro | off（不发送）· high: high · max: max |
| deepseek-v4-flash-0731 | off（不发送）· high: high · max: max |
| glm-5.2 | off（不发送）· low: high · medium: high · high: high · max: max |
| qwen3.8-max | off（不发送）· low: low · medium: medium · high: high · max: max |

配置

分节写入的是标准 llm-pi-ai profile 字段，适配器接受的任何形态都可表达。当前会话默认模型即使用百炼推理模型：

llm-pi-ai:
providers:
bailian-token:
apiKeyEnv: BAILIAN_TOKEN_API_KEY
api: openai-completions
baseURL: https://<your-bailian-endpoint>/compatible-mode/v1
compat:
thinkingFormat: qwen
supportsDeveloperRole: false
models:
- id: deepseek-v4-flash-0731
name: DeepSeek V4 Flash
reasoningEfforts:
off:
high: high
max: max
compat:
thinkingFormat: qwen
supportsDeveloperRole: false
- id: glm-5.2
name: GLM 5.2
reasoningEfforts:
off:
low: high
medium: high
high: high
max: max
compat:
thinkingFormat: qwen
supportsDeveloperRole: false
agent-default-model:
provider: bailian-token
model: deepseek-v4-flash-0731
reasoningEffort: max

- reasoningEfforts —— 逐模型的档位与线格式值，由本插件编辑。
- compat.thinkingFormat —— 推理分发的线格式（如 qwen），仍由 settings.yaml 管理。
- compat.supportsDeveloperRole —— 端点不接受 OpenAI developer 角色时设为 false （见故障排查）。
- agent-default-model.reasoningEffort —— 会话默认推理档位，需是该模型已声明的档位之一。

支持的 DeepSeek Harness 版本

自以下版本起记录（验证于该版本，向下兼容性未回溯验证）：

| 版本 | 提交 | 验证日期 | 说明 |
| 0.1.0-rc.7 | bb4ca698d6 | 2026-08-18 | 首个验证版本，验证于 deepseek-harness 工作区构建 |

已测试平台

[!IMPORTANT]
目前仅测试了阿里云百炼平台。其它 OpenAI 兼容平台尚未测试；线格式值、推理格式与角色支持可能需要按平台单独调整。

边界

- 只列出已配置模型的路由；由内置目录提供模型的路由会提示先到「模型」页添加模型。
- 路由级 compat 开关与 reasoning 默认值仍归 settings.yaml。
- 档位表（off/minimal/low/medium/high/xhigh/max）是 llm-pi-ai/catalog.ts 中 THINKING_LEVELS 的镜像；pi-ai 升级新增档位时需同步更新 src/client/validate.ts。
- 草稿按路由保存、刷新不打断；分节在打开时与每次保存后重新加载。

兼容补丁：supportsDeveloperRole 透传（随插件分发）

本插件不止管设置分节，同时托管一个兼容补丁，用来修复内置适配器缺陷 —— 与插件共存在仓库内（compat/dsh-llm-pi-ai/ + scripts/install-compat.mjs / verify-compat.mjs），随插件一起维护，无需单独安装别的补丁。

它修什么

400 错误 developer is not one of ['system','assistant','user','tool','function']：内置适配器 @deepseek-ai/dsh-llm-pi-ai 的 settings schema 缺少 supportsDeveloperRole 字段，你在 settings.yaml 里写的 compat.supportsDeveloperRole: false 会被校验丢弃，底层 pi-ai 按 baseURL 自动检测，误判端点支持 developer 角色；开启思考力度后 system 提示词以 developer 角色发送，兼容端点（如百炼）拒绝。

为什么必须装

产物本体在 compat/dsh-llm-pi-ai/（修改版适配器完备包）：settings schema 增加 supportsDeveloperRole、resolveModelCompat 透传该开关，与 pi-ai 的 ?? detected 合并语义配合，false 即强制 system 角色。

不装 = 设置 UI 正常但一开思考力度就 400；装完两者都正常。

安装 / 自检 / 回退

node scripts/install-compat.mjs # 部署到 $DSH_HOME/profiles/<全部>/node_modules，幂等
node scripts/verify-compat.mjs # 自检：部署存在、产物含补丁标记、解析命中副本

- 支持 --profile <name> 指定单个 profile（默认全部，排除 profiles/node_modules 平铺目录）。
- 生效：重启对应 profile 的 dsh。
- 原理：loader 的 baseUrl 是 profile 目录，解析 @deepseek-ai/dsh-llm-pi-ai 时 profile 的 node_modules 优先于安装树，副本遮蔽内置包；peer 依赖仍解析到应用自带包。
- 回退：删除对应 profile 下 node_modules/@deepseek-ai/dsh-llm-pi-ai/ 目录即还原原版行为。
- 升级安全：harness 重建/升级不影响副本；唯一注意点是 harness 升级后若想更新补丁内容，重新跑一次 install-compat.mjs。

注：当前 deepseek-harness 工作区已采用源码直修（等价改动，未提交），使用源码构建的安装无需部署补丁。

故障排查

400 ... "developer is not one of ['system', 'assistant', 'user', 'tool', 'function']"

OpenAI 兼容端点会被自动探测为支持 developer 角色；开启推理后 system 提示词以 developer 角色发送，部分端点（如百炼兼容模式）会拒绝：

修复：在路由或模型上声明 compat.supportsDeveloperRole: false，并部署能透传该开关的适配器补丁：

- ~/.dsh/profiles/desktop/node_modules/@deepseek-ai/dsh-llm-pi-ai/ —— 内置适配器的副本，已把 supportsDeveloperRole 加入 settings schema 与 resolveModelCompat （profile 的 node_modules 遮蔽内置包；依赖仍解析到应用自带的 pi-ai/dsh-llm）。
- 删除该目录即可还原内置行为；应用升级后如出现异常也先删它排查。

开发

从源码构建客户端 bundle（在 harness 工作区目录下执行，以便解析工作区工具链）：

cd <你的 deepseek-harness 工作区>
pnpm exec tsc -p <本仓库路径>/tsconfig.json # 仅类型检查，不写仓库
pnpm exec tsdown --config <本仓库路径>/tsdown.config.ts # 产出 lib/client.js

然后重启应用。bundle 从 profile 链接伺服，无需重建应用侧。

dsh-ui-models-reasoning/
├── src/
│ ├── index.ts # 节点半（空 apply） │ └── client/ │ ├── index.ts # 插件入口：注册 settings.section 分节 │ ├── ReasoningEffortsSection.tsx # 分节：路由列表、模型行、保存流程 │ ├── ReasoningEffortsEditor.tsx # 档位编辑器（独立副本，零内置包依赖） │ ├── validate.ts # 纯校验逻辑（与适配器规则对齐，可单测） │ ├── locales.ts # 中英文案 │ └── section.module.css ├── assets/ │ ├── readme/ # README 横幅图 │ └── screenshots/ # 真实界面截图 ├── lib/ # 构建产物（lib/client.js 由宿主伺服） ├── package.json # dsh.client 清单（platform: web） ├── tsconfig.json # 类型检查配置（noEmit） └── tsdown.config.ts # 复用 harness 的 clientBundle 预设

许可证

MIT