前言¶
DeepSeek Harness (DSH) 的插件挂载机制在运行时通过 identityFromManifest 函数解析包身份。当插件挂载行中的 name 为路径时，系统会向上查找最近的 package.json，并要求 name 和 version 字段均非空。如果缺失或为空，DSH 会抛出 REQUEST_EXTENSION 错误，导致每个官方 DeepSeek 请求失败。这种错误通常被误认为是模型或账号问题。
dsh-plugin-guard 是针对此场景的防护插件，旨在防止因挂载配置不当导致的请求中断。
插件简介¶
名称：dsh-plugin-guard
维护者：Linicc
分类：admin-security
许可证：MIT
该插件通过镜像上游解析规则，实现三层防御机制，确保插件挂载配置符合规范。
核心功能¶
插件提供以下核心能力：
-
Startup self-heal
在插件apply()时，扫描所有配置文件的补丁层。对于不符合规范的插件模块，在旁边写入一个最小化的合规package.json。此过程是全配置文件范围的，每会话成本约 1ms。 -
Check-on-write
监听配置文件的写入操作（.yml/.yaml）。每次写入后立即重新审计并修复，将结果输出到控制台。 -
三个命令行工具
-dsh_guard_audit：列出所有可能抛出错误的配置行。
-dsh_guard_repair：为不合规的插件目录写入缺失的package.json（幂等，不会覆盖现有文件）。
-dsh_guard_verify：在挂载前检查插件条目是否能通过上游解析规则。
安装与配置¶
推荐以 DSH bundle 的形式安装。该插件声明了 dsh.bundle.patch，安装后会自动将插件行插入到配置中。
dsh plugin --profile <profile> add github:Linicc/dsh-plugin-guard
安装后，需要在配置中启用插件并设置参数：
- id: plugin-guard
name: dsh-plugin-guard
config:
autoRepair: true # 自动修复缺失的 package.json (默认: true)
verbose: false # 是否输出审计详情到控制台
# profileRoot: "..." # 默认扫描路径为 $DSH_HOME/profiles
使用示例¶
-
审计当前配置
运行dsh_guard_audit查看哪些行会导致解析失败。 -
修复配置
运行dsh_guard_repair自动为缺失package.json的目录生成文件。 -
预检查
在挂载新插件前，使用dsh_guard_verify确认其能通过解析规则。
实现细节与安全边界¶
插件完全镜像上游的解析规则（包括路径判断、manifest 查找、字段校验），确保不会出现不一致。
安全边界：
- 仅当插件目录完全没有 package.json 时才写入，不会修改其他包的 manifest。
- 如果违规的 manifest 属于祖先目录（如 profile 根目录），该问题标记为 repairable: false，交由人工处理，插件不会自动修改。
- 所有审计和写入操作均包裹在 try/catch 中，确保插件自身不会成为导致请求失败的元凶。
适用场景¶
- 本地开发时，直接挂载文件路径而非包名。
- 插件目录缺少
package.json文件。 - 需要严格保证插件挂载配置与上游解析规则一致。
总结¶
dsh-plugin-guard 通过启动自愈、写入监听和命令行工具，为 DeepSeek Harness 插件挂载提供了安全网。它将原本会导致全局请求失败的配置错误，转化为可审计、可修复的本地问题。
