dsh-plugin-guard
DeepSeek Harness 的插件装载身份守卫。 阻止「不合规的插件挂载行」把每一轮 DeepSeek 请求
打成 REQUEST_EXTENSION。
English README
它防的是什么
@deepseek-ai/dsh-plugin-package-inventory-deepseek 在请求期给每个活跃的 Loader 行解析「包身份」。
当某行的 name 是路径时，它自模块目录向上找最近的 package.json，要求 name 与 version
同时非空，否则 throw：
function identityFromManifest(path, allowAnonymous) {
const manifest = JSON.parse(readFileSync(path, "utf8"));
if (allowAnonymous && manifest.name === void 0) return void 0; // ← 只容忍缺 name
if (typeof manifest.name !== "string" || manifest.name.length === 0
|| typeof manifest.version !== "string" || manifest.version.length === 0)
throw new Error(`... ${path} must declare non-empty name and version`);
return { name: manifest.name, version: manifest.version };
}
dsh-llm-deepseek 再把它包一层：
catch (error) {
throw new LlmError("DeepSeek request extension preparation failed", "REQUEST_EXTENSION", { cause: error });
}
结果：官方 DeepSeek 请求每一轮全部失败，而 UI 只显示被覆盖过的笼统文案，
看起来像模型或账号的问题。
为什么很容易踩中
被命中的 manifest 通常就是 DSH 自己生成的 profile manifest——它有 name，没有 version：
// $DSH_HOME/profiles//package.json ← DSH 生成
{ "name": "dsh-profile-desktop" }
于是任何自身目录没有 package.json 的本地插件都会触发：
# $DSH_HOME/profiles//cordis.patch.yml
- insert:
- id: myplugin
name: "C:/Users//.dsh/profiles//plugins/myplugin/index.ts"
nearestManifest() 从 plugins/myplugin/ → plugins/ → profiles// 一路向上，
正好落在那个没有 version 的 manifest 上。
它与调用方的契约自相矛盾
调用方本来就允许解析失败：
const identity = resolver.resolve(activeEntry);
if (identity === void 0) continue; // 契约：undefined = 跳过该条目
resolve() 的返回类型也写着 ... | undefined。在这里 throw 属于错误分级失当：
尽力而为的诊断性元数据，不该持有请求级否决权。
三道防线
以 DSH 组合包形式发布（dsh.bundle.patch），可直接安装而非手动复制。
写法上逐字复刻上游判定规则，保证守卫永远不会与上游不一致。
| # | 机制 | 时机 | 效果 |
|---|---|---|---|
| ① | 启动自愈 | apply()，早于任何模型请求 |
扫描所有 profile 的 patch 层，给不合规的插件目录补最小合规 package.json |
| ② | 写入即检 | profile 下任何 .yml/.yaml 落盘后 |
立刻复检并自愈，把结果附回工具返回值 |
| ③ | 三个工具 | 随时 | dsh_guard_audit / dsh_guard_repair / dsh_guard_verify |
启动自愈属于整个 profile：加载一次，该 profile 下所有会话都受保护。实测耗时 ~1 ms。
安装
本仓库是一个 DSH 组合包（bundle）：npm 包在 package.json 里声明 dsh.bundle.patch，
profile 把它列进 dsh.profile.bundles 后，插件行会被自动插入。
作为组合包安装（推荐）
# 从本地克隆
dsh plugin --profile add /path/to/dsh-plugin-guard
# 或直接从 git 安装
dsh plugin --profile add github:Linicc/dsh-plugin-guard
dsh plugin 会在 profile 目录内转发给 pnpm，然后因为该包声明了 dsh.bundle，
把它追加进 dsh.profile.bundles。真正插入插件行的是包内的 cordis.patch.yml：
- insert:
- id: plugin-guard
name: dsh-plugin-guard
注意这里按包名引用，不是路径——这正是让 Node 能定位到已安装代码的原因。
它也意味着这一行走的是「裸包名」解析分支，不依赖最近 manifest 上溯，天然规避了本插件要防的那个坑。
作为本地模块挂载（不打包）
如果不想装包，克隆到任意位置，用绝对路径挂载：
# $DSH_HOME/profiles//cordis.patch.yml
- insert:
- id: plugin-guard
name: "<绝对路径>/dsh-plugin-guard/src/index.ts"
> ⚠️ 插件目录必须自带合规的 package.json。挂载一个没有 manifest 的目录，
> 正是本插件要防的那个条件——见它防的是什么。
> 本仓库已经带了，但如果你把源码复制到别处，记得把 manifest 一起复制。
配置
- id: plugin-guard
name: dsh-plugin-guard
config:
autoRepair: true # 启动时自动补 manifest（默认 true）
verbose: false # 打印审计细节
# profileRoot: "..." # 默认 $DSH_HOME/profiles
仓库结构
dsh-plugin-guard/
├─ package.json 声明 dsh.bundle.patch；main → lib/index.js
├─ cordis.patch.yml profile 列出本包时应用的配置层
├─ lib/index.js 编译产物（已提交，使用者无需构建）
├─ src/index.ts 源码
├─ scripts/build.mjs 用 Node 内置类型剥离从 src 重建 lib
├─ README.md / README.zh.md
└─ LICENSE
改完源码后重建：
npm run build # node scripts/build.mjs —— 无需任何依赖
三个工具
| 工具 | 用途 |
|---|---|
dsh_guard_audit |
审计所有 profile 的装载行，列出会抛错的行（含 profile / 行 id / 模块目录 / 具体问题） |
dsh_guard_repair |
为不合规目录补 package.json；幂等，永不覆盖；支持 dryRun |
dsh_guard_verify |
安装前预检：给定插件入口，判断它能否通过官方身份解析 |
实现要点与安全边界
判定规则逐条对照上游（isPathLike / nearestManifest / identityFromManifest），
且刻意比上游更保守：上游只看活跃行，本插件看所有行——代价是偶尔报出「今天没启用、
一启用就会炸」的行，这是期望行为。
安全边界：
- 只在该插件自己的目录里完全没有
package.json时才写；从不修改别的包的 manifest。 - 若问题 manifest 属于上层（如 profile 根），标记
repairable: false交人工处理——
守卫不会去改你的 profile manifest。 - 所有写入与审计都包在
try/catch里：守卫绝不能自己成为它要防的那个故障。 - 每次写入都会在控制台打印，不做静默操作。
已知局限
- 上游缺陷仍在：本插件是用户侧预防，不修
@deepseek-ai/dsh-plugin-package-inventory-deepseek里的identityFromManifest()。
同一条失败路径的其他触发方式（例如残留软链，见上游 discussion #5439）仍会打死请求。
已上报：discussion #4950。 - YAML 解析是容错子集：只抽取
- id:/name:对；锚点、合并键等特殊写法可能看不到。
守卫选择「失败即放行」（什么都不报），而不是让启动失败。 - JSON 解析失败的 manifest 只报告、不修复。
- 没有文件监听：只有 host 启动与工具写入会触发审计；用外部编辑器改的 patch 会在下次启动时生效。
验证
沙箱构造：
profiles/desktop/package.json → { "name": "dsh-profile-desktop" } ← 有 name 无 version
cordis.patch.yml → insert 行指向没有 package.json 的目录
plugins/myplugin/index.ts → 只有入口文件
autoRepair: false
dsh_guard_audit → ok=false, 问题=1 ✅ 能检测
dsh_guard_verify → ok=false + 修复建议 ✅ 能预检
dsh_guard_repair → 创建 package.json ✅ 能修复
再次 audit → ok=true, 问题=0 ✅ 能复验
autoRepair: true（默认）
apply() 约 1 ms 内补齐 manifest ✅ 引爆前拆弹
真实 profile
audit → profile 2 个 · 装载行 8 行 · 问题 0
许可
MIT，见 LICENSE。
