额度用量统计 Yinxe/dshp

deepseek-harness-plugins

DeepSeek Harness（DSH）插件 Monorepo（pnpm workspaces + TypeScript ESM）。

当前维护 @dshp/vision-bridge 与 @dshp/search-provider。 2026-10-20 起其余插件已归档到 archive/，冻结在归档时的版本，不再适配新版 DSH，也不参与构建、测试与发布。

运行时零依赖 · 构建产物已提交：插件 dependencies 恒为 {}，lib/host.js / lib/client.js 随仓库提交 —— clone 下来即可直接安装，无需先 build。

插件一览

维护中：

| 插件 | 一句话 | 文档 |
| @dshp/vision-bridge | 视觉桥接：让纯文本模型也能“看图”（vision_describe 工具 + 主/备模型自动降级） | README |
| @dshp/search-provider | AI 搜索中枢：用 Tavily / Exa / Firecrawl 接管 web_search（含两个免费后端） | README |

已归档（冻结，不再维护）：

| 插件 | 版本 | 一句话 | 归档位置 |
| @dshp/token-meter | 0.15.0 | Token 额度 + 用量统计 + 在线时长（多供应商额度 + 会话日志聚合） | archive/token-meter |
| @dshp/file-change-viewer | 0.4.0 | edit / write 行的高亮差异视图 + patch 工具 | archive/file-change-viewer |
| @dshp/mcwiki-search | 1.6.0 | Minecraft Wiki 查询（搜索 / 引言 / 全文，清洗成 AI 可读文本） | archive/mcwiki-search |
| @dshp/web-style | 0.5.0 | Web 外观定制（8 套主题 + 背景效果 + 壁纸取色 + 全局圆角） | archive/web-style |
| @dshp/skill-manager | 0.4.0 | 技能管理（全局 + 工作区技能的新建 / 编辑 / 启停 / 复制移动 / 删除） | archive/skill-manager |
| @dshp/mcp-manager | 0.4.0 | MCP 服务器管理（patch 条目 CRUD + 探活，表单 / JSON 双模式） | archive/mcp-manager |
| @dshp/widget-kit | 0.13.0 | 小组件规范与宿主（托盘 + 卡片 + 小面板，不含业务） | archive/widget-kit |

归档件保留源码、文档与已提交的 lib/，可直接从 archive/<name> 本地安装；不参与 CI、不再发版，也不再适配新版 DSH。归档清单与冻结版本见 archive/README.md。

安装到 DSH

方式一（推荐）：克隆仓库安装 —— 更新只需 git pull，旧版 DSH 可 checkout tag

git clone git@github.com:Yinxe/deepseek-harness-plugins.git
cd deepseek-harness-plugins
pnpm install
lib/ 已提交，clone 下来就能用；改了 src 才需要 pnpm build

安装维护中的插件
dsh plugin --profile web add ./plugins/vision-bridge

归档插件仍可本地安装（冻结版本，不再更新；见 archive/README.md）
dsh plugin --profile web add ./archive/token-meter

dsh web # 重启生效

- 更新：仓库内 git pull + dsh web（最快——lib 已提交，未改 src 无需 build）；兼容旧版 DSH：按 compat.json 的 tag git checkout <tag> 后重跑上面的 add。
- 归档插件不随仓库更新：它们的源码与 lib/ 已冻结，装与不装都不影响 vision-bridge。

dsh plugin add 会把包写进 profile 的 dsh.profile.bundles —— 无需手动改配置文件。
各插件的详细安装说明、配置与常见问题见对应 README（上表）。

方式二：从 Release 安装（无需 clone；更新需手动重跑命令）

CI 把维护中的插件打包成 tgz 发布到 Releases，latest 滚动发布固定跟随 main 最新构建（持 Latest 徽标、始终置顶）：

macOS / Linux
dsh --profile web add \
https://github.com/Yinxe/deepseek-harness-plugins/releases/download/latest/dshp-vision-bridge-latest.tgz

Windows PowerShell
dsh --profile web add
'https://github.com/Yinxe/deepseek-harness-plugins/releases/download/latest/dshp-vision-bridge-latest.tgz'

维护中插件的下载与安装命令见 Releases 各预发布说明；滚动更新 = 重跑同一条命令 + dsh web 重启（latest 资产随 main 每次构建滚动重建）。

两个 pnpm 语义坑，遇到别绕远路：

1. dsh plugin … update 对 tarball URL 直装无效——pnpm update 只重解析 semver 范围，URL 是精确 spec（且 lockfile 用 integrity 钉住首次内容），永远 "Already up to date"。滚动更新请重跑同一条 add 命令（或用下面的 Git tag 安装）；
2. remove 后重装同一 URL 若报 ERR_PNPM_MISSING_TARBALL_INTEGRITY（lockfile 残留了无 integrity 的条目），删掉 profile 目录里的 pnpm-lock.yaml 再 add 即可（lockfile 是可再生的本机状态）。

历史版本（兼容旧版 DSH）

维护中的 vision-bridge 永远跟随最新 DSH。老版本 DSH 用户装静态历史版本：按 compat.json 记录的兼容 tag（「DSH 版本 → 推荐 tag」矩阵），到 Releases 找对应版本 Release（v tag 触发，静态存档、永不滚动），资产名 = dshp-<插件名>-<tag>.tgz（历史 tag 里仍含当时尚未归档的插件，checkout 后路径为 plugins/<name>）：

以 v0.1.5-rc.1 为例
dsh --profile web add \
https://github.com/Yinxe/deepseek-harness-plugins/releases/download/v0.1.5-rc.1/dshp-vision-bridge-v0.1.5-rc.1.tgz

方式三：Git 依赖安装 —— 支持 update 一键（可解析较慢，列为备选）

仓库自带一个随 CI 滚动的 latest git tag（每次 main 构建通过门禁后重置到 main HEAD）。装它 = "永远最新"，且 update 一键跟进——spec 永不改变，可变性由 git ref 承担，完全绕开 tarball URL 的语义坑：

安装（一次，此后 spec 永不改）
dsh plugin --profile web add \
"github:Yinxe/deepseek-harness-plugins#latest&path:plugins/vision-bridge"

之后每次更新就这一条：
dsh plugin --profile web update @dshp/<插件名>
dsh web # 重启生效

同一机制的两种变体（换选择器即可）：

- #semver:^1.0.0&path:plugins/vision-bridge —— 跟发版 tag 走的受控升级：只在 push 了匹配范围的新 tag 后 update 才会动；预发布 tag 受 node-semver 元组规则限制，范围必须显式含预发布（如 ^0.1.5-rc.1 只匹配 0.1.5 系列）；
- #main&path:plugins/vision-bridge —— 与 #latest 等价的分支滚动。

注意：

- latest tag 在门禁通过后才移动到 main HEAD，所以 update 拿到的永远是过了门禁的构建；
- 网络慢时，git 解析可能要 2–4 分钟；clone 一次后 pnpm 有本地缓存，重复 update 会快一些；
- 协议取决于你本机的 pnpm 版本，而不是 spec 本身：pnpm ≥ 11.21.0 的 github: 简写走 HTTPS，开箱即用；更早的版本（如 11.7.0）会解析成 git+ssh://git@github.com/…，需先配好 GitHub SSH key，否则报 Permission denied (publickey)。旧版又不想配 key 时，升级 pnpm，或让 Git 把 ssh 重写成 HTTPS（pnpm 只是 shell out 到 git，重写自动生效）：

git config --global url."https://github.com/".insteadOf "git@github.com:"

- 对比：tarball URL 直装（…latest.tgz）的 spec 是精确 URL，update 永远 no-op——这正是 git 依赖方案存在的理由。

多插件统一更新：update 支持一条命令带多个包名（git 与 tarball 混装亦可）：

dsh plugin --profile web update "@dshp/" # 或显式列出：update @dshp/a @dshp/b …

实测耗时（国内网络、SSH 热缓存）：约 35 秒/插件、线性增长（3 个 ≈ 1 分 40 秒；首次冷安装更久，每个都要完整 clone）。插件多且网络差时更新会到分钟级——这是 git 解析的固有成本，根治要等 npm 发布渠道恢复（registry 元数据 + CDN tarball，秒级）。tarball 渠道的多插件重装同样支持一条命令带多个 URL，但在 HTTPS 不稳的网络下可能超时。

卸载

dsh plugin --profile web remove "@dshp/<插件名>"
dsh web # 重启生效

remove 直接转发 pnpm（参数 = 包名），并自动从 dsh.profile.bundles 撤下挂载；写入 profile 条目 config: 的配置按需手动清理。各插件的详细安装/更新/卸载说明见各自 README。

一键 AI 安装

把下面这段发给你的 DSH AI，让它代你装：

帮我从 monorepo Yinxe/deepseek-harness-plugins 安装插件（按需选择子目录）：
1. git clone 仓库并 pnpm install
2. dsh plugin --profile web add ./plugins/vision-bridge
3. 重启 dsh web，确认无报错、设置页出现对应条目

发布与更新约定（CI 自动执行）

| 通道 | 触发 | 行为 |
| latest | 推送 main | 滚动重建到最新提交（正式渠道，持 Latest 徽标置顶），下载地址固定 |
| 版本 Release | 推送 v tag | 静态存档，永不随构建变化 |
| 自定义后缀 | 手动触发（限 main / tag） | 勾选 rolling = 预发布随滚动；不勾 = 静态正式版 |
| 仅门禁 | 推送其他分支 / PR | 不打包、不发布（分支上的构建产物没有意义） |

- 只有 main 与 v tag 能产出发布物：其他分支推送与 PR 只跑门禁；手动触发是唯一的人工发版口，也只在 main（或 v tag）上生效，在别的 ref 上跑只跑门禁并打一条 notice。要给人试新版，用 main 的 latest，或手动触发指定后缀。
- 滚动约定：所有预发布（以及 notes 首行带 标记的 release）都跟随 main——每次 main 推送成功后整体重建到最新提交；停止跟随 = 取消 Pre-release 勾选或删除标记行。latest 每次最后重建并授予 Latest 徽标，始终置顶 Releases 列表。
- 数量约束：除 latest 外同时最多允许 1 个滚动项；出现多个时 CI 立即报错终止（不动任何现有 Release），处理后再推送即可。
- Release 说明由 scripts/gen-release-notes.cjs 生成：逐插件列出包名、版本、双语描述、下载与安装命令。

结构

.
├── plugins/
│ ├── vision-bridge/ # @dshp/vision-bridge（视觉桥接，维护中） │ │ ├── src/host/ # Host TS：types/http/config/cache/vision/index │ │ ├── src/client/ # Client TS：types/styles/api/components/VisionSection/index │ │ ├── lib/ # 单文件构建产物（已提交，DSH git 安装必需） │ │ └── cordis.patch.yml # bundle 声明（id: dshp-vision-bridge） │ └── search-provider/ # @dshp/search-provider（AI 搜索，维护中） │ ├── src/host/ # Host TS：types/http/config/providers/index │ ├── src/client/ # Client TS：types/styles/api/components/SearchSection/index │ ├── lib/ # 单文件构建产物（已提交，DSH git 安装必需） │ └── cordis.patch.yml # bundle 声明（id: dshp-search-provider） ├── archive/ # 冻结的历史插件（源码 + lib + 文档，不参与构建 / 发布） │ ├── token-meter/ # @dshp/token-meter 0.15.0 │ ├── file-change-viewer/ # @dshp/file-change-viewer 0.4.0 │ ├── mcwiki-search/ # @dshp/mcwiki-search 1.6.0 │ ├── web-style/ # @dshp/web-style 0.5.0 │ ├── skill-manager/ # @dshp/skill-manager 0.4.0 │ ├── mcp-manager/ # @dshp/mcp-manager 0.4.0 │ ├── widget-kit/ # @dshp/widget-kit 0.13.0 │ └── README.md # 归档清单、冻结版本与安装说明 ├── AGENT.md # 开发规范·规则版（红线 + 指路） ├── docs/ # 规范细节（脚手架 / TS / package.json / 构建 / Cordis / settings / 路由 / Client / provider / 时区 / 安全 / 门禁 / 发布 / 文档 / 小组件）——旧 AGENT.md §1–§14 的完整下沉 ├── tsconfig.base.json # 共享 TS 配置（NodeNext + strict） ├── tsconfig.json # solution 引用（只含维护中的插件） ├── pnpm-workspace.yaml # packages: plugins/（archive 不在 workspace） ├── compat.json # DSH 版本兼容矩阵 └── .github/workflows/CICD.yml # 门禁 + 打包发布：main→latest 滚动发布，v* tag→版本 Release，其他分支仅门禁

每个插件内部一律是同一套布局：src/host/（Node 半）+ src/client/（浏览器 半）+ lib/（已提交的单文件产物）+ cordis.patch.yml + AGENT.md（本插件的局部规则与事实，指回根规范）。

设置键名约定（全仓统一，改名即 breaking）

每个插件只有一个配置键，四处同名，等于 dshp-<目录名>：

| 位置 | 值（以 vision-bridge 为例） |
| 配置命名空间（条目 Config + volatile / settings.update） | dshp-vision-bridge |
| 同源路由前缀 | /ext/dshp-vision-bridge/ |
| cordis.patch.yml 的 id | dshp-vision-bridge |
| 设置页 settings.section 的 id | dshp-vision-bridge |

插件只读自己的键，不做任何历史键兼容与迁移：不读 dshp-inx- 等旧命名空间、不读 storages/*.json、不读不改写 settings.yaml（旧配置一次性导入是平台的事；规范见 docs/settings.md）。升级时若键名有变，请按各插件 README 的更新日志手工把旧分节改名或重配；配置键改名属 breaking 变更。

环境

- Node >= 20（推荐 24，见 .nvmrc）
- pnpm 11.7.0（见 devEngines）
- 本沙箱全局 store 只读，pnpm-workspace.yaml 已设 storeDir: /tmp/pnpm-store（pnpm v11 必须写这里，.npmrc 会被忽略）

常用命令

pnpm install
pnpm check # 一条流程：build → typecheck → lint → format（提交前跑这个）
pnpm format # prettier 全仓写盘
pnpm format:check # CI 用，只检查不写
pnpm lint # oxlint 全仓（--deny-warnings，警告也算挂）
pnpm typecheck # pnpm -r typecheck
pnpm build # pnpm -r build
pnpm test # pnpm -r test

单个插件
pnpm --filter @dshp/vision-bridge build
pnpm --filter @dshp/vision-bridge typecheck

提交前跑 pnpm check（构建 → 类型检查 → 质量检查 → 格式化一步完成）；CI 仍按严格检查序把关；改了 src/ 必须重新 build 并把 lib/ 一起提交。

加新插件

mkdir -p plugins/<name>/src

照抄 plugins/vision-bridge/{package.json,tsconfig.json}，改 name/version/description

tsconfig.json 里 extends 保持 ../../tsconfig.base.json

根 tsconfig.json references 加一条 { "path": "./plugins/<name>" }

pnpm install

规范分三层：AGENT.md（红线规则版）→ docs/（主题细节，旧 §1–§14 全部下沉在此）→ 各插件 AGENT.md（局部规则与事实）。多服务商分层渲染、接管工具行渲染等专题见 docs/ 对应篇目。