hytime/dsh-thinking-effort

dsh-thinking-effort

为 DSH（DeepSeek Harness） 的 llm-pi-ai 第三方模型补充可配置的思考强度档位，并设置子 agent 的默认思考强度。

npm version
npm downloads
GitHub license

- English README
- 日本語 README
- 한국어 README
- 安装指南
- English installation guide
- 日本語インストールガイド
- 한국어 설치 안내
- 版本更新日志
- 日本語 changelog
- 한국어 changelog

兼容边界： DSH Runtime compatibility 只负责 Settings 传输：新版 DSH 使用 remote.settings，旧版 DSH 使用 connection.api.settings。插件按运行时实际能力进行探测；旧版没有 Remote provider 时不会因此要求可选的 Remote 服务。

Gateway Protocol compatibility 是独立的一层。DSH schema 提供时，插件支持 15 个常用标量 llm-pi-ai.compat 字段，按角色与推理、格式与输出、流式与工具、存储与缓存 4 组组织。boolean 字段可设为「自动」「支持」或「不支持」，enum 字段可设为「自动」或具体取值。DSH 0.1.0-rc.7 不提供网关兼容设置；0.1.0-rc.8 至
DSH 0.1.2-alpha.1 及更高版本通过 LocaleRuntime 支持语言包注册外部 locale ID。本插件会动态注册 ja 和 ko，无需维护 DSH fork。只支持固定内置 locale ID 的旧版 DSH 仍只能使用 zh 和 en。

发布包的运行入口是 lib/index.js（Host）和 lib/client.js（Client）。修改 TypeScript 或 locale 源文件后，运行 npm run build，再启动 DSH 或打包插件。当前 DSH 没有公开的 semver metadata 契约，因此运行时能力探测是权威来源。只有显式 metadata 或测试输入提供时才使用可选版本；未知合法版本仍按实际能力运行。插件同时支持新版 remote.settings 和旧版 connection.api.settings。

Host 在宿主提供 Settings installSection 时用它注册插件自有的 dsh-thinking-effort namespace，否则回退到旧版 register 路径。插件不在运行时依赖 @deepseek-ai/dsh-settings，因此在配置为 autoInstallPeers: false 的 DSH profile 中也能干净安装，不会引入第二份 Cordis 运行时。

DSH 版本兼容

| DSH 范围 | 网关兼容设置 |
| --- | --- |
| 0.1.0-rc.7 | 不支持 |
| 0.1.0-rc.8 至 ，例如 web。

2. 安装最新版本

dsh plugin --profile  add @hytime/dsh-thinking-effort

安装指定版本：

dsh plugin --profile  add @hytime/dsh-thinking-effort@0.3.0

官方 CLI 会同时更新 profile 依赖、锁文件和 dsh.profile.bundles，无需手工追加 YAML。

3. 升级

dsh plugin --profile  update @hytime/dsh-thinking-effort

4. 卸载

dsh plugin --profile  remove @hytime/dsh-thinking-effort
rm -f "${DSH_HOME:-$HOME/.dsh}/thinking-effort-loaded.json"

宿主侧改动需要重启 DSH；浏览器侧刷新 Web 页面。

完整的迁移、验证和排查步骤请查看 INSTALL.md。

从旧包迁移

旧版本可能使用以下依赖：

dsh-thinking-effort
github:hytime/dsh-thinking-effort

如果旧依赖仍然存在，使用官方命令迁移：

dsh plugin --profile  remove dsh-thinking-effort
dsh plugin --profile  add @hytime/dsh-thinking-effort@0.3.0

如果旧依赖已经被其他工具移除，但 profile 的 bundle 列表仍残留旧名称，先从旧 profile 的 pnpm-lock.yaml 找到旧 GitHub commit，再使用官方命令恢复并移除：

dsh plugin --profile  add github:hytime/dsh-thinking-effort#
dsh plugin --profile  remove dsh-thinking-effort
dsh plugin --profile  add @hytime/dsh-thinking-effort@0.3.0

不要把 dsh-thinking-effort 添加到新的 dsh.profile.bundles 中。

快速使用

1. 打开 DSH「设置 → 模型能力与档位」。
2. 使用页面顶部的「页面语言」选择中文、English、日本語或한국어。DSH 默认优先使用已保存的语言，其次使用浏览器语言，最后回退 English；选择会持久化到 DSH。
3. 在「子 agent 默认档位」卡片中选择没有显式值时使用的默认档位，然后点击「应用」。
4. 使用「一键设置」将官方 DeepSeek 风格或通用预设应用到全部模型，或展开供应商和模型进行详细配置。
5. 使用搜索框按模型名称或 ID 筛选。模型行会显示文字/图像输入能力、已声明的上下文长度，以及打开单模型设置的按钮。
6. 勾选需要的标准档位，并填写发送给网关的线上值。例如：

| DSH 档位 | 网关线上值 |
| --- | --- |
| off | 留空，表示不发送 |
| high | ultra |
| max | max |

7. 在模型编辑器中，只有目标模型确实需要 x-opencode-session 时才启用「OpenCode 会话 Header」。它默认关闭，会动态使用当前 DSH 会话 ID，不会在同一路由的其他模型或不同 provider 之间继承；拨动开关即立即保存，没有单独的保存按钮。
8. 回到 Composer，选择对应模型后即可使用推理档位滑块。

Composer 推理档位滑块

当 DSH Web 运行时提供 modelDirectories 服务时，客户端会为可选 conversation.input.model seat 注册低优先级的 shadow 实现，不会修改 Composer 本身。滑块读取当前精确 provider/model 在宿主侧解析后的 reasoning.efforts 数组，因此只显示该模型当前生效的档位。选择档位提交的是普通会话模型选择，不会写入插件的 Settings 文档。

模型声明了 defaultEffort 时，滑块会显示对应档位。模型未声明 defaultEffort 时，面板额外提供「跟随模型默认」；提交时不会设置推理档位覆盖值。控件使用宿主 --dsw-* 语义 token，不维护自己的主题偏好，会跟随当前浅色或深色主题。

运行时未提供 modelDirectories 服务时，不会注册这个 seat；设置页和旧版 Settings 传输回退仍可使用。插件不修改 DSH Composer、ui-conversation 或 ui-model-selection 包。

设置页右下角会显示当前安装版本，例如 v0.1.14。

网关兼容配置

provider 的 compat 区域是该 provider 下全部模型的全局默认值。设置页将 15 个字段按 4 组组织并默认收起。请使用 DSH 官方 YAML 配置结构：

providers:
qwen-gateway:
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: qwen-plus
- id: qwen-thinking
compat:
maxTokensField: max_completion_tokens

逐字段独立按以下顺序取值：model → provider → base/catalog → protocol。URL/hostname 不会作为 compat 来源。模型值只覆盖当前字段。「自动」（Auto）会删除当前层字段，恢复 provider 继承，并让继承链中的下一层生效。provider 默认值会应用到该路由的所有模型，模型级修改只影响当前模型。对同一路由（provider）而言，非空的 models[] 和非空的 modelOverrides 互斥；官方 schema 会拒绝该无效配置，插件遇到异常数据时 fail closed。

设置页的 provider 全局区域用于修改该 provider 下全部模型的默认值。catalog/modelOverrides 模型和 models[] 模型都能展开后编辑单模型 compat：前者只对目标字段使用 modelOverrides..compat 下的字段级 set/unset，后者通过一个完整的 providers..models 数组 set 写回，同时保留其他模型和字段。模型级修改不会影响其他模型。

这些 compat 值属于控制面配置。它们不实现或替代网关 transport；网络请求仍由外部 transport 负责。

OpenCode 会话 Header 兼容

模型编辑器提供独立的「OpenCode 会话 Header」开关。它默认关闭，保存在插件自有的 dsh-thinking-effort Settings namespace 中，不写入 llm-pi-ai.compat。只有确实需要 x-opencode-session 的精确 provider/model 才应启用；同一路由中的其他模型（包括 GPT 模型）不会继承该设置。拨动开关即立即保存，没有单独的保存按钮；重新打开模型时显示的是已持久化的值。

启用后，Host 会在匹配的 llm/stream 请求中发送 x-opencode-session: 。该值跟随当前会话，不写入 Settings，也不会替换成固定值。适配器或调用方已经提供的 x-opencode-session 会保留。该设置不会选择或修改 openai-completions、openai-responses 或 anthropic-messages 协议。

Sub2API、CPA 和其他中转服务必须保留并继续把 x-opencode-session 转发给 OpenCode 上游。llm-pi-ai.providers..headers.x-opencode-session 这类静态 route Header 不能替代本功能：它会让所有会话共用一个值，无法提供按会话路由和提示词缓存亲和性。修改 Host 后需要重启 DSH；修改 Settings 或 Client 后需要刷新 Web 页面。

配置备份与方案

「配置备份与方案」卡片位于语言选择器和「子 agent 默认档位」卡片下方，可以导出当前配置、在本机保存命名方案，并导入先前导出的文件。

1. 点击「导出当前配置」下载 dsh-config-.json。文件按原样包含 llm-pi-ai 与 dsh-thinking-effort 的用户层配置：凭据值不会被导出（provider 只记录保存密钥的环境变量名 apiKeyEnv），但这两个用户层里的值都会原样写入，放在 provider headers 里的明文 token 就是其中之一。请妥善保管。
2. 在「方案库」中输入名称后点击「保存当前配置」，即可把当前配置存为命名方案；「导出」写成文件，「删除」移除方案，最多保存 20 份。「应用」切回方案时走的是与导入相同的预览，默认的「合并」会保留方案里没有的 provider，要完全还原需在预览中改选「替换」。
3. 点击「导入配置」中的「选择文件…」后，「导入预览」会先列出新增 / 覆盖 / 删除的条数，确认之前不会写入任何内容。
4. 导入默认使用「合并」（保留文件里没有的配置）；「替换」必须显式选择，它会删除文件里没有的 provider。点击「确认导入」会先把当前配置存为「导入前的自动备份」，再写入变更；还原这份备份同样走这个预览。

导出与导入复用插件现有的 Settings 通道，因此新版 Remote Settings 与旧版 connection.api.settings 都可以使用。结果显示某个 namespace 需要重启时，重启 DSH 后生效。

设置页界面

页面顶部是语言选择器；其下方的「子 agent 默认档位」卡片控制没有显式档位的请求。「一键设置」负责批量应用预设。供应商和模型列表支持展开/收起；每个模型行显示输入能力、上下文长度，并在设置区域提供网关兼容控件。models[] 保存使用完整数组 set，而不是数组索引 path op。

中文模型能力与档位设置页

完整的中英日韩截图集见 docs/SCREENSHOTS.md。

工作方式

- 宿主侧： 插件读取 llm-pi-ai 设置，在启动和设置变更时扫描 models 与 modelOverrides，只为缺少 reasoningEfforts 的模型补充默认档位；同时读取模型级 OpenCode 会话设置，只在匹配的 llm/stream 请求中注入当前 DSH 会话 ID。
- 客户端： 通过 DSH Settings Remote（ctx.remote.settings）注册设置页；运行时提供 modelDirectories 服务时，为可选 Composer seat 注册低优先级 shadow 实现，并显示宿主已解析的推理档位滑块。模型编辑器把 OpenCode 会话 Header 设置保存在插件自有 namespace，与 llm-pi-ai.compat 分开。四种文案分别维护在 src/locales/zh.json、src/locales/en.json、src/locales/ja.json 和 src/locales/ko.json，发布前生成到客户端 bundle。
- 子 agent： 默认值存储在 llm-pi-ai 用户层的 subagentEffort；agent/request waterfall 只对未显式指定档位的子 agent 请求进行补全。
- 版本信息： 设置页右下角显示当前安装版本，例如 v0.1.14；DSH 插件列表从已安装包的 package.json.version 读取同一版本。

安装验证

grep -n "@hytime/dsh-thinking-effort" \
"${DSH_HOME:-$HOME/.dsh}/profiles//package.json"
dsh --profile  --dump-default-config

组合树应包含：

- id: thinking-effort
name: '@hytime/dsh-thinking-effort'

且不应再包含：

name: dsh-thinking-effort

宿主加载标记位于：

cat "${DSH_HOME:-$HOME/.dsh}/thinking-effort-loaded.json"

重要限制

- DSH 的 llm-pi-ai 适配器固定提供 7 个标准档位：off、minimal、low、medium、high、xhigh、max。插件不能增加第 8 个显示名称，但可以为每个档位填写任意线上值。
- 非 off 档位必须填写线上值；off 留空表示不发送该参数。
- 子 agent 使用的模型必须支持所选档位，否则网关可能返回 UNSUPPORTED_REASONING_EFFORT。
- off 和未设置都可能表现为不发送 reasoning 参数，是否真正关闭思考取决于第三方网关的协议语义。
- Composer 滑块只在 Web 运行时提供可选 modelDirectories 服务时注册。该服务不可用时，不会注册 seat，插件也不会修改 Composer。
- 宿主逻辑修改需要重启 DSH；Settings、locale 和 Client bundle 修改需要刷新 Web 页面。
- 「配置备份与方案」的方案库和导入前的自动备份都保存在插件自有的 dsh-thinking-effort namespace 中，不会随导出文件迁移。要把命名方案带到另一台机器，需要逐个「导出」再在目标机器上导入。

CI 与发布维护

- Pull Request 和推送到 main 会在 Node 22.19.0 与 24.x 上运行质量矩阵。
- workflow 使用 npm ci；依赖变更时，维护者必须提交 package-lock.json。
- 普通 CI workflow 不会发布 npm；发布只由 publish.yml 接收匹配的 v tag 后执行。
- 创建发布 tag 前，维护者先更新 package.json 版本和各语言 CHANGELOG，提交这些变更，再创建匹配的 v tag。tag 指向的提交必须位于 main 历史中。
- npm 包必须配置 GitHub Trusted Publisher：仓库为 hytime/dsh-thinking-effort，workflow 为 publish.yml。发布使用 GitHub OIDC 生成 provenance，不需要 NPM_TOKEN。
- 发布前 workflow 会按 rc7 → rc2 → alpha2 → latest 顺序构建并测试四个官方 DSH 能力代表：dsh-v0.1.0-rc.7（0.1.0-rc.7）、dsh-v0.1.1-rc.2（0.1.1-rc.2）、dsh-v0.1.3-alpha.2（0.1.3-alpha.2）和 dsh-v0.1.6-alpha.1（0.1.6-alpha.1）；通过官方 dsh plugin 命令安装并执行真实兼容检查，最新代表版本还会运行真实浏览器 DOM 探针。
- workflow 不会自动修改版本或任何 CHANGELOG；如果 npm 中已经存在相同版本，发布也会被阻止。

排查

- 官方组合配置失败： 执行 dsh --profile  --dump-default-config，检查是否仍有旧的 name: dsh-thinking-effort。
- 设置页没有出现： 重启 DSH 后刷新 Web 页面，确认 profile 的 bundle 清单包含 @hytime/dsh-thinking-effort。
- 宿主没有补齐： 检查 $DSH_HOME/thinking-effort-loaded.json 是否存在；日志前缀为 [@hytime/dsh-thinking-effort]。
- 写入档位失败： 检查非 off 档位是否填写了线上值，并确认目标模型配置仍然存在。
- 子 agent 报 UNSUPPORTED_REASONING_EFFORT： 改用该模型支持的档位，或恢复为「提供方默认」。

许可证

MIT