dsh-plugin-hub

dsh-plugin-hub

简体中文 | English

DSH（DeepSeek Harness）Web GUI 插件集，npm 分发：一键装全家桶，或按需单装。

• 聚合包：@wingsky-1/dsh-plugins-all（一键装齐全部插件）
• 单插件：@wingsky-1/dsh-*（按需安装）

快速导航

使用前须知 · 最短上手 · 插件列表 · 常用配置与维护 · 验证与排障 · 详细参考 · 开发与架构

使用前须知

版本适配（只适配 rc）

本插件集只适配 DeepSeek Harness 的 rc（候选发布）版本，不对 alpha 版本适配。

• 当前全部插件锚定 dsh 0.1.5-rc.1（官方类型层 catalog 与各包 peerDependencies 一致锁定）
• 安装/更新时若 dsh 版本不匹配，npm/pnpm 会给出 peer 提示——请先将 dsh 本体升级到对应 rc 版本
• 每版的具体适配基线、破坏性变更与升级指南见 Release Notes
• 官方发布新版 rc 后本插件集跟随升级；alpha 版本不受支持，请勿在 alpha 环境安装（或自行评估兼容风险）

独立安装与全家桶：二选一（0.1.5 起）

独立包与聚合包的 patch id 相同（ui-*）。请只选一种安装方式—— 同时装 dsh-plugins-all 与任一 @wingsky-1/dsh-lan-proxy 等独立包会导致同名 entry 重复，dsh web 启动时报 duplicate 错误（可发现，不代表损坏）。需要调整时： 卸载聚合包，或卸载对应独立包，重启即可。

逐插件安全说明

• dsh-lan-proxy 装完即在 0.0.0.0 开放 HTTP/HTTPS 端口，局域网所有设备可访问你的 dsh——不需要时请卸载
• dsh-lan-proxy 的启动令牌自动注入（injectToken）默认开启：局域网内任何能访问该端口的设备免 token 获得完整 dsh 控制权（等效信任整个局域网，bash 直通宿主机）——仅在可信内网开启，不可信网段务必在设置卡片关闭
• dsh-mcp-manager 的 stdio 子进程继承宿主权限，只配置可信的 MCP 服务器
• 插件管理路由有 loopback 围栏（非回环 403 / 方法错 405）；经 dsh-lan-proxy 转发的请求按设计视为受信，并不隔离局域网客户端。
• dsh-notifier 自持配置文件；设置响应掩码频道凭据，但通知正文与出口错误详情不打码，可能进入日志、历史与推送服务。
• dsh-provider-usage 的 API 密钥留在宿主端，不进浏览器。
• dsh-verify-isolated 使用临时 DSH_HOME、独立 profile、端口与浏览器实例；这是验证隔离边界，不是全局安全承诺。
• dsh-worktree-sidebar 只改变侧栏根目录；会话 cwd、@ 引用与 present 仍锚定 cwd。

各插件的威胁模型与加固细节见其 README 安全章节。

最短上手

前提：已安装 DeepSeek Harness 且 dsh web 可正常启动（未全局安装 dsh 见下方「未全局安装 dsh」）。

安装插件（add）

# 一键装全家桶（推荐）
dsh plugin --profile web add @wingsky-1/dsh-plugins-all

# 或单独安装（按需）
dsh plugin --profile web add @wingsky-1/dsh-notifier
dsh plugin --profile web add @wingsky-1/dsh-lan-proxy

安装 / 卸载 / 更新后都需重启一次 dsh web（bundle 层只在启动时组合），侧边栏/设置页才反映变化。

访问与验证

重启 dsh web，打开启动时给出的 URL，在「设置 → 插件」确认已安装插件的卡片。notifier 可发送测试通知；局域网访问按 lan-proxy 访问与健康检查 验证。

插件列表

常用配置与维护

在「设置 → 插件」进入对应卡片；各插件的配置与存储边界不同，请按对应 README 操作。

卸载插件（remove）

dsh plugin --profile web remove @wingsky-1/dsh-notifier

更新插件（update）

# 更新单个插件到最新
dsh plugin --profile web update @wingsky-1/dsh-notifier

# 更新全家桶（聚合包 + 其拉齐的子包）到最新
dsh plugin --profile web update @wingsky-1/dsh-plugins-all

# 更新当前 profile 下全部插件
dsh plugin --profile web update

安装 / 卸载 / 更新后都需重启一次 dsh web（bundle 层只在启动时组合），侧边栏/设置页才反映变化。

验证与排障

安装后未出现插件时先重启 dsh web；出现 duplicate entry 时，检查是否同时安装聚合包与独立包。

从 0.1.5 之前的 dsh 升级上来，出现历史会话打不开？ 报 cannot safely transform unclassified message source 的会话，是 dsh-mcp-manager 早期版本 注入的能力目录消息触发的宿主迁移闸门拒载（产物完好，只是读不出）。一条命令可救回：

# 落盘前先停 dsh web；正在写入的日志不保证可安全重写
node scripts/maintenance/repair-mcp-catalog-sessions.mjs          # 预演，列受影响会话
node scripts/maintenance/repair-mcp-catalog-sessions.mjs --apply  # 落盘（自动备份），随后重启 dsh web

详见 修复方案 · issue #723

升级须知与修复：历史会话打不开（mcp-catalog）

症状：从 0.1.5 之前的 dsh 升级上来后，某些历史会话在 GUI 里报

历史加载失败：failed to observe session "session-…":
cannot safely transform unclassified message source;
source v0 artifact remains unchanged (raw log: …/session.jsonl.zstd)（gateway/internal）

且该会话目录下始终不出现 session.v3.jsonl.zstd，每次打开都同样失败。

原因（不是会话损坏）：dsh-mcp-manager 0.2.x 及更早把能力目录注入消息写成 source.kind = "mcp-catalog"，而 dsh 0.1.5 的 session format v2→v3 迁移对 surface 消息的 source.kind 有一份封闭白名单，自造值不在其中 → 迁移被拒；产物按宿主设计原样保留 （未损坏）。v3 读取路径本身不校验该字段，所以只有"升级前的旧会话 + 装过本插件并触发过目录 注入"的用户会命中，升级后的新会话不受影响。

修复：本插件新版已改用宿主词表内的通用 source 形态（今后不再产生此类消息）； 已落盘的旧产物用一次性脚本就地修复（只改 source 元数据，正文与事件序列不动）：

# 先停掉 dsh web（正在写入的日志不保证可安全重写）
node scripts/maintenance/repair-mcp-catalog-sessions.mjs          # 预演：只列受影响会话与处数
node scripts/maintenance/repair-mcp-catalog-sessions.mjs --apply  # 落盘：先留 .bak-<时间戳>，写入原子
# 重启 dsh web，打开原会话

• 默认只读 <DSH_HOME>（--home <dir> / DSH_HOME 可覆盖）；--session <id> 只处理单个会话
• 幂等；写后自检（帧结构 + 逐行 JSON + 零遗留旧 kind）；回滚 = 用 .bak-<时间戳> 覆盖回去
• v3 会话默认一起修：v3 里同样可能两种 kind 并存（升级前创建、升级后继续写入）， 宿主将来给 v3→v4 迁移加同类闸门时会重演这次的永久拒载；改写只换 source 元数据， v3 语义零变化。--legacy-only 可退回只修 v0/v1/v2
• 不产出 v3 产物：v0/v1/v2 修复后仍由 dsh 自己完成迁移
• 细节与验证证据见 dsh-mcp-manager README 与 issue #723

详细参考

功能详解

• 任务事件通知中心：提问 / 审批 / 完成 / 子代理完成 / 错误 / 轮次完成 6 类任务事件 双通道提醒（浏览器通知 + 系统 toast），经 Bark / Webhook 可推送到手机；免打扰时段与 紧急例外、按通道独立的弹窗/声音开关（4 音色）、宿主能力自检（/diagnostics）
• 上下文成本可控的 MCP 管理：项目级 MCP 默认经中间层收敛为 ws_mcp_list / ws_mcp_detail / ws_mcp_search / ws_mcp_call 四个原子工具，项目级接入规模 不再膨胀上下文（middleware: all 可把全局服务器也收进中间层，设置页热切换）； 分工作目录维护项目级/全局两级配置，多仓库各配各的 MCP，互不串台
• 可扩展的用量统计框架：支持多 provider 用量统计与自定义数据源接入；覆盖每日 用量推算、使用趋势、峰谷倒计时与日/周/月报告
• 工程质量背书：每个插件自带 smoke 断言（路由围栏 / 客户端契约），构建契约 + 打包校验等全部门禁在 CI 全量执行

@wingsky-1/dsh-notifier

任务事件通知中心：6 类事件（提问/审批/完成/子代理完成/错误/轮次完成），双通道（浏览器通知 + 宿主系统 toast）+ Bark/Webhook 推送频道（ntfy、Gotify、自建网关）；免打扰时段与紧急例外、按通道独立弹窗/声音（4 音色）、宿主能力自检（/diagnostics 给可用性与处置建议）

@wingsky-1/dsh-provider-usage

多 provider 用量统计框架（v2 适配器契约）：常驻胶囊 + 详情面板；内置 DeepSeek 官方（区间记账法推算每日用量 + 峰谷倒计时徽标，官方无用量接口也能算）与 OpenCode Go 开箱即用；自写一个 mjs 即可接入任意数据源、设置页热插拔；日/周/月用量报告（经宿主 llm 生成，含目录与时段维度观察）；密钥只在宿主端不进浏览器

@wingsky-1/dsh-lan-proxy

局域网访问 dsh web UI：HTTP/HTTPS/WS 转发 + TLS（自签名/自定义证书）；HTTP（Brotli/gzip 自适应）与 WebSocket（permessage-deflate）双压缩；WS 半开探活，移动端切后台不僵死；启动令牌自动注入，LAN 设备免手工拿 token；DNS 重绑定防护 + 回环目标白名单

@wingsky-1/dsh-mcp-manager

MCP 服务器管理器（stdio / streamable-http）：项目级/全局两级配置分工作目录维护；全部 MCP 经中间层收敛为 4 个原子工具（模型不可见 mcp__ 直呼工具）；工作空间隔离防串台；配置只存 ${ENV} 引用不落盘密钥；提供运行时注册接口供其他插件注入 MCP；可选 MCP 调用统计与 debug 模式（metadata-only，默认关）

@wingsky-1/dsh-verify-isolated

DSH 插件开发的隔离环境浏览器验证 skill：临时 DSH_HOME + 独立 profile + 独立端口 + 独立浏览器实例四重隔离，一键拉起、退出自动清理；自带 raw CDP 零依赖浏览器驱动（快照/点击/截图/求值，支持设备视口模拟），可选隔离审计；首启弹窗默认跳过

@wingsky-1/dsh-worktree-sidebar

给 agent 三个工具（register / create / remove），把某个 git worktree 登记给当前会话，让该会话右侧栏文件树指向那个 worktree，而会话 cwd 不变（@ 引用、present 落点仍锚 cwd）；子 agent 会话继承父会话的登记；只在「打开页签 / 点官方刷新 / 窗口重新可见」时重读，不轮询

# 安装指定版本（而非 latest）
dsh plugin --profile web add @wingsky-1/dsh-notifier@<版本号>

# 更新到指定版本
dsh plugin --profile web update @wingsky-1/dsh-notifier@<版本号>

# 装全家桶
npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-plugins-all

# 单独安装（带版本号）
npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-notifier@<版本号>

# 卸载 / 更新（同理，把 add 换成 remove / update）
npx @deepseek-ai/dsh plugin --profile web remove @wingsky-1/dsh-notifier
npx @deepseek-ai/dsh plugin --profile web update @wingsky-1/dsh-plugins-all

dsh plugin --profile web remove @wingsky-1/dsh-skill-explorer
dsh plugin --profile web remove @wingsky-1/dsh-idle-archive
dsh plugin --profile web remove @wingsky-1/dsh-subagent-model-inherit
dsh plugin --profile web remove @wingsky-1/dsh-codegraph
dsh plugin --profile web remove @wingsky-1/dsh-mem0
dsh plugin --profile web remove @wingsky-1/dsh-web-file-preview

dsh plugin --profile web remove @wingsky-1/dsh-gzip
dsh plugin --profile web add @wingsky-1/dsh-lan-proxy

dsh plugin --profile web remove @wingsky-1/dsh-opencode-usage
dsh plugin --profile web add @wingsky-1/dsh-provider-usage

相关项目

• dsh-web-mobile（npm：@dsh-external/dsh-mobile-nav）— DSH web 移动端适配：窄屏自动收起侧栏、目录以抽屉方式展开。本项目的大部分开发与排障基于它在手机/平板上的远程使用完成。
• dsh-web-ui — DSH web UI 皮肤集合。从中学习了很多优秀实践，也是 DSH 插件开发的启蒙项目。
• dsh-routing-suite / dsh-router-standard — 提供 Router Standard agent preset（任务感知的推理模式路由：spec / mixed / react），供会话选择预设使用。

开发与架构

要求：Node ≥ 23.6（测试用原生 type stripping 直跑 TS）、pnpm ≥ 11。

构建 / 契约 / 测试 / 打包命令、目录结构、宿主端与客户端写法规范，统一见 DEVELOPMENT.md（从 §0 构建总览开始）；贡献流程见 CONTRIBUTING.md；issue 处理流程见 ISSUE-WORKFLOW.md；各插件架构图解（功能 / 原理 / 使用方式， 含 SVG 架构图与 Mermaid 时序图）见 插件架构文档。

插件迁入本仓库前均经过开源前审查（构建自包含、隐私清理、安全加固、元数据完整）。

贡献

见 CONTRIBUTING.md：Conventional Commits 提交规范、功能分支 + PR 流程、 提交前检查（敏感信息/发布物边界）。

License

MIT