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