dsh-thinking-levels-settings 安装与导出教程

DSH Web 自定义插件 · 官方 client-plugin 形态（v3.0.0）· 平台模块由宿主 module table 提供，随 DSH 版本兼容

1. 这是什么

dsh-thinking-levels-settings 给 DSH Web 的 设置 → 思考级别 新增一页， 用于为自定义 llm-pi-ai 提供商的每个模型配置 reasoningEfforts （off / minimal / low / medium / high / xhigh / max），并通过官方 Settings wire 持久化到 ~/.dsh/settings.yaml。

• 三种推理模式：继承目录（不写该字段，由内置目录决定）/ 非推理 （写 false）/ 显式声明档位（档位 → 协议值，留空表示不发参数）。
• 输入能力：在展开区勾选 input: [text, image]；两项都不勾则省略该字段（继承目录）。
• 分组与折叠：按 provider 分组，provider 与模型行两级折叠，折叠状态记在浏览器本地。
• 搜索与筛选：按模型名/ID 搜索；快捷筛选为「全部 / 支持图片」，其余筛选（已配置 / 未配置 / 非推理 / 未保存）与 JSON 导出导入一并收进「更多 ▾」菜单，选中后按钮直接显示筛选名。筛选只展开命中分组，不会自动铺开模型卡片。
• 按 provider 批量保存：一个 provider 一次写入，避免半保存；冲突时提示而不覆盖。
• JSON 导入导出：导出当前配置，或粘贴 JSON 回填为草稿（导入从不直接写入）。
• 内联图标：档位表、输入能力、模型状态徽章与工具栏按钮均配 16px 线性 SVG 图标，与平台自带图标同一套画法（viewBox 0 0 16 16 / currentColor）；图标一律 aria-hidden 并始终伴随文字，不使用 emoji。
• 版本可见：页面底部显示当前插件版本（构建时从 package.json 注入），装机后一眼确认生效的是哪个版本。
• 中英双语：注册 zh/en 词条，跟随平台的 设置 → 通用设置 → 语言，切换即时生效。

它是 纯客户端插件：node 半（lib/index.js）的 apply 为空， 浏览器半（lib/client.js）以官方 window.__ModuleLoader__.load 闭包工厂注册 settings.section 槽位贡献。

它同时支持 官方 publish 文档（打包与安装插件）的两种形态：

• 官方 bundle 形态：package.json 声明 dsh.bundle（patch: ./cordis.patch.yml）。 dsh plugin --profile <name> add <tarball> 一步完成安装 —— pnpm 装包 → reconcile 识别 dsh.bundle → 自动挂进 dsh.profile.bundles → loader 激活 → client-modules 暴露浏览器 bundle。符合 deepseek-harness develop/basic/publish 文档。
• 纯依赖形态（回退）：无 pnpm / 无 dsh CLI 的环境，包作为普通依赖安装， 由 install.sh 在 profile 的 cordis.patch.yml 里追加一行挂载（与官方 client 插件如 dsh-client-ui-settings 的安装方式同构）。

2. 在新 DSH 中安装

按你的环境选一种方式。方式 A/B 需要 dsh CLI 和 pnpm （dsh plugin 是一个 pnpm 转发器），这是 deepseek-harness 官方 publish 文档推荐的安装方式。

先安装 pnpm（方式 A / B 的前置要求）

pnpm --version

corepack enable
corepack prepare pnpm@latest --activate
pnpm --version

npm install --global pnpm
pnpm --version

command -v pnpm

方式 A：#master 直装（推荐，最简；需要 dsh CLI + pnpm）

dsh plugin --profile web add github:blackteaYES/dsh-thinking-levels-settings#master

allowBuilds:
  "<粘贴 pnpm 错误中打印的完整包键>": true

方式 B：Release tarball 安装（稳定通道，版本可锁定）

dsh plugin --profile web add https://github.com/blackteaYES/dsh-thinking-levels-settings/releases/download/v3.0.0/dsh-thinking-levels-settings-3.0.0.tgz

方式 C：一键脚本（无 pnpm 环境）

tar -xzf dsh-thinking-levels-settings-3.0.0.tgz -C /tmp/rel
cd /tmp/rel/package

bash install.sh                    # 默认 profile: web
DSH_PROFILE=web bash install.sh    # 显式指定
DSH_HOME=/path bash install.sh     # 覆盖 DSH home

方式 D：手工（与官方 client 插件同构）

包目录就位 → profile package.json 加 "dsh-thinking-levels-settings": "file:./packages/dsh-thinking-levels-settings" → cordis.patch.yml 追加：

- insert:
    - id: ui-thinking-levels-settings
      name: dsh-thinking-levels-settings

从 ≤2.0 旧版升级：先清理被污染的 profile

cd ~/.dsh/profiles/web
dsh plugin --profile web remove dsh-thinking-levels-settings    # 等价 pnpm remove

3. 在新 DSH 中安装（源码法：可继续开发）

适用：你拿到的是 源码包（含 src/、tsdown.config.ts、tsconfig.json）， 想在这台机器上继续开发和重新构建。前两步与“方式 D 手工”相同（包目录就位 + file: 依赖），第 3 步改为在插件目录内构建：

cd ~/.dsh/profiles/web/packages/dsh-thinking-levels-settings

# 1) 安装构建工具链与官方 @deepseek-ai client 依赖（需要网络，写入项目 node_modules）
npm install --ignore-scripts

# 2) 构建（tsdown 产出 lib/index.js + lib/client.js + map，随后 tsc 产出 lib/types）
npm run bundle

# 3) 开发模式：改 src/ 后自动重建（client-modules 的 HMR 会检测到 client.js rev 变化并热更新）
npm run watch

4. 验证安装是否成功

5. 导出给其他 DSH

把插件迁移到另一台机器的 DSH 安装，本质就是 把包目录打包带走，在新机器上按“第 2 节方式 A/B/C/D”安装。

bash release.sh                # 产出 dsh-thinking-levels-settings-<version>.tgz
OUT_DIR=/path bash release.sh  # 输出到指定目录

cd ~/.dsh/profiles/web/packages/dsh-thinking-levels-settings
npm run bundle   # 确保 lib/ 是最新产物（含 invariant.js 与 types/）

mkdir -p ~/.dsh/profiles/web/packages
cd ~/.dsh/profiles/web/packages
tar -xzf dsh-thinking-levels-settings-3.0.0.tgz   # 解出 package/ 目录
mv package dsh-thinking-levels-settings
ls dsh-thinking-levels-settings/lib/   # 确认 client.js / index.js / invariant.js / types

6. 覆盖更新已安装的插件

新版本到手后，保持 profile 的依赖声明和 patch 行不变，只更新包目录内容：

# 备份旧版（可选）
mv ~/.dsh/profiles/web/packages/dsh-thinking-levels-settings \
   ~/.dsh/profiles/web/packages/dsh-thinking-levels-settings.old

# 放入新版
cp -r dsh-thinking-levels-settings ~/.dsh/profiles/web/packages/

# node_modules 里的符号链接仍指向 ../packages/dsh-thinking-levels-settings，无需重新 install
cd ~/.dsh/profiles/web
npm install --package-lock=false --ignore-scripts   # 仅刷新 lockfile 引用（可选）

# 重启 dsh web + 硬刷新浏览器

如果新版本的 package.json 变了（比如依赖增加），才必须重新执行 profile 级 npm install。

7. 卸载

cd ~/.dsh/profiles/web
# 1) 从 package.json 的 dependencies 删掉 dsh-thinking-levels-settings
# 2) 从 cordis.patch.yml 删掉 - insert: … ui-thinking-levels-settings 段
# 3) 删除包目录与链接：
rm -rf node_modules/dsh-thinking-levels-settings packages/dsh-thinking-levels-settings
# 4) 重启 dsh web，硬刷新浏览器

8. 常见问题

装完打开设置没有“思考级别”入口

• 确认重启了 dsh 进程并硬刷新（不是普通刷新）。
• 跑验证表的 curl 检查：boot 清单里没有该条目 = patch 行没生效或 loader 没扫到； 有条目但页面没有 = 浏览器缓存了旧 bundle。
• 确认 cordis.patch.yml 是顶层 YAML 数组（- insert: 顶格写）。

git 安装报 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED

这是 pnpm ≥10 对 git 依赖 prepare 脚本的首次安全授权，不是下载、代理或插件 manifest 故障。该路径现在仅属于开发者路径（从 main 源码安装）；普通用户请改用 方式 A（#master 预构建产物，无 prepare、无需授权）或方式 B（Release tarball）。 仍要走源码安装时：把 pnpm 打印的完整包键原样加入当前 profile 的 pnpm-workspace.yaml 顶层 allowBuilds，然后锁定同一个 commit 重新执行 add。官方依据： 从 GitHub 安装：构建脚本这道坎。

所有对话报 history unavailable ... reading 'parse'

这是 ≤2.0 旧版插件把宿主包物化进 profile 造成的新旧版本混跑症状，与 dsh 本体无关。 按「从 ≤2.0 旧版升级：先清理被污染的 profile」清理后重装 2.1+ 即可恢复。

页面报“llm-pi-ai 设置尚未加载”

说明当前 profile 没有注册 llm-pi-ai 命名空间（未配置 dsh-llm-pi-ai 提供方）。 这个插件只服务该命名空间；没有 llm-pi-ai 的 provider 配置时页面不会列出模型。

保存提示“设置已在其他位置更新，请刷新后重试”

这是 Settings wire 的 SETTINGS_CONFLICT 冲突保护：另一个窗口/进程改了同一命名空间。 刷新页面后重试即可。

浏览器控制台报模块表 require 错误

例如 Cannot find module 'xxx' —— 说明 client bundle 里出现了非平台模块依赖。 正式形态的 bundle 只允许 react 等平台模块走 require，其余必须内联； 如果你改了 src/client/index.ts 引入了新的 npm 包（非 inline-safe），需要把该包改为内联 或在 tsdown.config.ts 的 EXTERNAL_PLATFORM_MODULES 里声明。

构建时 tsdown 报错

先确认 Node 版本（node -v ≥ 22.19）。npm run bundle 需要能访问 npm registry 拉取 @deepseek-ai/* 依赖；国内网络可用 --registry=https://registry.npmmirror.com 加速。

9. 包结构与官方契约速查