DeepSeek Harness (DSH) 插件：dsh-updater-npm

DSH 采用「一切皆插件」的架构，这意味着核心功能的扩展通常通过插件实现。在开发和运维过程中，保持 DeepSeek Harness（DSH）核心版本的更新以及获取官方文档，往往是两个需要分别处理的环节。dsh-updater-npm 插件将这两个功能整合在一起：它既可以通过 npm 一键更新 DSH 本身，也能增量同步官方文档到本地，并提供搜索与阅读工具。

核心功能¶

该插件主要提供以下能力：

DSH 更新（npm）：自动检查 @deepseek-ai/dsh 的最新版本，支持一键执行 npm install -g @deepseek-ai/dsh@latest，更新过程中显示实时进度。
DSH 文档（官方）：将官方 docs/ 目录增量同步到本地（按 GitHub blob sha 跳过未变文件），支持进度条显示，并提供 dsh_docs_search 和 dsh_docs_read 两个模型工具。
多语言支持：界面与宿主端消息支持中文/English，自动跟随系统语言切换。
插件自检与闸门：插件自身会检查版本并对照 npm 最新版，若自身版本过旧，会提示优先更新插件并禁用 DSH 更新按钮。
运行模式检测：自动识别当前 DSH 是通过 npm 全局安装（npm-global）还是源码树模式（source）运行。
升级安全网：升级前自动备份配置、预设及会话日志（保留最近 5 份），支持暂存安装、回滚机制以及遗留文件清理。

安装与启用¶

安装该插件需要使用 DSH 的插件管理命令。安装完成后需重启 DSH Web 实例，设置页会出现「DSH 更新」和「DSH 文档」两个卡片。

dsh plugin --profile web add dsh-updater-npm

使用说明¶

DSH 更新流程¶

在设置页点击「通过 npm 更新」即可执行更新。该操作会自动检查最新版本，检测到新版本时，设置页左侧导航「DSH 更新」旁会显示红色小圆点。

更新过程会显示实时进度，完成后出现「重启 DSH」按钮。点击后，程序会按原启动命令退出并重新拉起。

版本比较规则：版本比较遵循 semver 风格。如果本地版本比远端新（例如 rc.7 vs rc.6），系统不会误报更新。

插件自身版本检查：卡片会显示插件自身的版本号。若检测到插件自身有新版本，会显示红色提示并提供更新命令，此时「通过 npm 更新」按钮会被禁用。这是为了防止旧版插件的升级流程存在缺陷（如依赖缺失）导致升级失败。

DSH 文档同步¶

文档同步默认关闭，需在设置页开启「自动同步官方文档」开关。

存储位置：文档同步至 $DSH_HOME/docs-sync/，索引文件为 $DSH_HOME/docs-sync/.index.json。
搜索与阅读：开启后可使用 dsh_docs_search 搜索本地索引（中文查询优先中文文档），使用 dsh_docs_read 读取文档（支持按章节聚焦，80KB 截断）。
增量同步：首次同步约 217 篇文档，之后每 24 小时静默增量更新。

运行模式与更新策略¶

插件会根据当前 DSH 的运行模式采取不同的更新策略：

运行模式	更新方式
npm-global	正常部署场景。Windows 上使用 staged 更新（新版本装入独立暂存目录，原子替换后重启），非 Windows 使用原地 `npm install -g`。
source	源码树运行模式（如 `pnpm dsh web`）。此时无法通过 npm 更新，需使用 `git pull`。

升级安全网细节：
在 Windows 环境下，插件会尝试使用 PowerShell 7 (pwsh)。若未安装，会提示一键安装。
对于 npm-global 模式，升级前会自动备份配置文件、预设及会话日志到 $DSH_HOME/upgrade-backups/ 目录。
升级完成后，旧版本目录会被重命名为 dsh.old-* 以保留回滚点。如果升级过程中出现异常，可以根据需要手动回滚。

API 与命令¶

除了设置页的操作，插件还提供了 HTTP 接口和对话指令：

更新检查：GET /dsh-updater-npm/check
执行更新：POST /dsh-updater-npm/update
重启实例：POST /dsh-updater-npm/restart
清理遗留文件：POST /dsh-updater-npm/cleanup
触发文档同步：POST /dsh-updater-npm/docs/sync
文档搜索：GET /dsh-updater-npm/docs/search?q=&lang=&limit=
文档阅读：GET /dsh-updater-npm/docs/read?path=&section=

注意事项¶

Windows 环境：必须安装 PowerShell 7 (pwsh)，否则更新功能可能受限。
源码树模式：在源码树模式下，无法使用 npm 更新，需使用 git pull。
配置文件：文档同步的开关状态保存在 $DSH_HOME/plugin-data/dsh-updater-npm/config.json。

总结¶

dsh-updater-npm 通过将 DSH 的更新管理与官方文档的本地化同步结合，简化了开发者的维护流程。它提供了清晰的进度反馈、完善的备份回滚机制以及对不同运行模式的适配，适合需要在本地深度集成 DSH 官方文档并保持工具链更新的用户。