@local/dsh-plugin-guard —— 插件运维台

把 dsh-compat-vet 的审查修复层与 dsh-forge 的锻造台合成一个插件，
并补上两者都没有的那一格：装载行的 name 能不能被 loader 解析。

一个侧栏入口、一块工作台，三件事：

1. 它补的那一格：装载行解析

这是旧 compat-vet 查不出来的一类故障，也是本插件存在的理由。

故障长什么样

某个插件装在 profile 里、dsh.profile.bundles 里也有它、node_modules 里文件齐全，
但：

• 设置页里没有它的那一项
• 输入框的模型选择器里没有它的分组
• 它该有的数据目录从未被创建
• dsh 日志里一行都不提

为什么

它自带的 cordis.patch.yml 里，装载行写的是裸包名，而包本身是 scoped 安装：

- insert:
- id: our-free-model
name: 'dsh-our-free-model'     # ← 真名是 @ebony-vinyl/dsh-our-free-model
config: {}

loader 拿这一行的 name 去走 Node ESM 解析：

• cordis-plugin-loader/src/config/entry.ts → this.parent.tree.import(name, baseUrl)
• dsh-app-boot 的 HostResolvedRootInclude.import：裸名按 dsh 安装目录解析，
  scoped 名 / 相对路径按 profile 目录解析

裸名在 profile 的 node_modules 与 dsh 安装目录里都不存在（profile 里只有 @ebony-vinyl/ 这一层），
于是 MODULE_NOT_FOUND —— 宿主半身与浏览器半身一起挂不上。

为什么 profile 层 YAML 改不了它

dsh-app-boot/lib/index.js 的 applyEntryPatches：

const { id, insert, name, ...overrides } = patch
...
if (name && name !== target.name) {
warn('patch: name mismatch for %C (expected %C, got %C), skipping', ...)
continue                                   // ← name 只作身份断言
}
for (const [key, value] of Object.entries(overrides)) target[key] = value

name 不是可覆盖字段，它只用来断言「你改的是你以为的那一行」。
所以「往 profile 的 cordis.patch.yml 追加三行就能修好」这条路不存在，
必须落到 bundle 自己的 patch 文件上。

因此自愈分两级

一级（默认）：就地改字节。 只替换那一行 name 的那一段，其它字节、注释、引号风格全不动。

-      name: 'dsh-our-free-model'
+      name: '@ebony-vinyl/dsh-our-free-model'

二级（包目录只读时）：不碰 bundle 字节，改用 profile 层补丁。

这条路径的合法性来自 applyEntryPatches 的另外两条语义：

if (insert) { data.push(...insert); buildMap(insert) }   // 插入的行会进索引
...
target[key] = value                                       // disabled 可覆盖

于是可以「停掉坏行 + 补一条好的」：

- id: our-free-model
disabled: true                       # 停掉原行
- insert:
- id: our-free-model--guard
name: '@ebony-vinyl/dsh-our-free-model'
config: {}

buildMap(insert) 保证后一条 patch 能引用前一条插入的行，所以两段必须按顺序放。

2. 授权闸门：为什么确认必须自建

这台机器上 DSH 的 user-approval 被改成了 decide() => 'allowed-once'，
DSH 原生的确认对话不会弹出来。在这样的环境里，「点一下就改别人包」的按钮等于没有护栏。

所以确认建在协议层，不是界面上的一个弹窗：

plan（只读）─→ planId + 每条：动作 / 目标文件 / 改前改后 / 可逆性 / 是否需重启
│
├─ 用户在面板上逐条勾选 ← 这就是授权
▼
apply(planId, approved[]) ─→ 校验① planId 有效（未过期、未执行）
② 指纹未变
③ 只有 approved 里的条目执行
└→ 任何一条不满足：拒绝，错误码 stale-approval
▼
复检 ─→ 本次批准的那条 issue 是否还在？不在了才算成功
▼
└→ 不在就自动回滚本次改动的全部字节
▼
undo(journalId) ─→ 从备份逐字节写回

指纹为什么要带目标文件的字节哈希

sha256(report.checkedAt + report.summary + package.json 字节 + cordis.patch.yml 字节 + 每条目标文件的字节哈希 + 已装版本)

只校验「报告有没有变」不够：报告证明「当时判过」，字节哈希证明「现在改的还是同一个东西」。
中间可能有人手动改了那个 patch，也可能有别的安装动作重写了 node_modules。

实测：报告一变 → 指纹变 → stale-approval → 不执行。

3. 与 dsh-compat-vet / dsh-forge 的关系

修掉的两个误报（这两个误报会让用户学会忽略报告）

① 内置包被报成未解析。
@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app 在 app.asar 里，
createRequire 解析不到，但它们确实是内置 bundle、确实能挂上。
旧 compat-vet 只按 createRequire 判定，所以每次体检都带两条噪音。

正解是 读安装体的 package.json dependencies（app-boot 自己就这么做）。
它在 asar 里，所以要能读 asar —— lib/asar.js 是最小实现（只读 header 索引，不写、失败返回 undefined）。

实测：本机 version=0.2.1-rc.5，dependencies 305 项，@deepseek-ai/dsh-base 在内。

② peer 判定口径写错会误报所有插件。
unmetRequirements（dsh-app-boot/lib/index.js:279-299）有三条例外，必须一起照抄：

1. 有 engines.dsh → 只看它，peerDependencies 整段忽略
2. peer 名只看 @deepseek-ai/dsh 与 @deepseek-ai/dsh-* 前缀
   （@deepseek-ai/cordis、@deepseek-ai/schemastery 不参与判定）
3. range 对着 runtimeVersion 求值，不是对着 peer 包自己的版本
   （这是 dsh 的独特约定）；workspace:^ / ~ / * 视为当前运行时

按自己直觉写会得出「dsh-plugin@2.2.7 与运行时冲突」的假结论
（它声明 @deepseek-ai/cordis: "4.0.1"，运行时是 4.0.5 —— 但 cordis 根本不在判定范围内）。

4. 配置

cordis.patch.yml 里的 config：

selfHeal: false + tools: true 是一个常用组合：只报告、不自动改盘，
所有改动都要经过你在面板上勾选。

5. 验证

cd "G:\AI PGRM\DSH\plugins\plugin-guard"

# ① 协议正确性（合成 fixture）
node test/e2e.mjs

# ② 真机集成（真实 profile + 真实 asar）
node test/integration.mjs

# ③ 浏览器半协议形状
node test/client-contract.mjs

期望：

e2e.mjs 里有两个坑值得记下来，它们是测试本身最容易写错的地方：

1. 故障包的目录必须是 node_modules/@ebony-vinyl/dsh-our-free-model（scoped 布局）。
   放在 node_modules/dsh-our-free-model 会让裸名恰好可解析，复现不出问题。
2. 修复只改 patch 行，不改 bundles 条目。要是测试场景把 bundles 也写成裸名，
   修完 patch 之后 bundle 级仍然解析不了，复检会（正确）判失败。

6. 安装

$p = "C:\Users\Shinelon\.dsh\profiles\desktop"
# ① 依赖（link: 安装，改动即时生效）
#   package.json → dependencies 里加：
#     "@local/dsh-plugin-guard": "link:G:/AI PGRM/DSH/plugins/plugin-guard"
pnpm install --dir $p

# ② 启用（bundles 末尾加一项）
#   package.json → dsh.profile.bundles 里加 "@local/dsh-plugin-guard"
# ③ 重启 DSH Desktop

与 dsh-compat-vet、dsh-forge 并存是安全的：工具名用 guard_* 前缀，
不会撞 id。但功能重叠——建议启用本插件后停用这两个，避免同一件事有两个入口。

7. 回滚

$p = "C:\Users\Shinelon\.dsh\profiles\desktop"
# ① 停用：从 dsh.profile.bundles 删掉 "@local/dsh-plugin-guard"
# ② 撤销所有自愈改动：自愈账本里每一项都有 beforeHash / afterHash
#    按 journal 撤销面板上执行过的改动：
#      guard_undo(journalId) 或面板「记录」页的「撤销」按钮
# ③ 彻底移除依赖：从 dependencies 删掉那行，pnpm install --dir $p
# ④ 清状态目录：Remove-Item "$p\..\..\plugin-guard" -Recurse -Force

自愈改过的 bundle patch 会在 pnpm install 之后被重写回原样（node_modules 是 pnpm 的产物）。
这不是问题：下次启动自愈会再跑一遍（幂等），所以「彻底不用管」成立的前提是
本插件保持启用。停用之后，那些包的 patch 会退回上游的写法，故障随之回来。

8. 已知边界（诚实声明）

• 只认字面量：tool id 扫描只看 defineTool({ name: 'x' }) / .register({ name: 'x' })。
  拼接出来的名字（name: dynName）不在视野内。
• !!js 表达式的 name 不判：静态判不了，标为 expression 并跳过。
• 相对路径的 name 只查 package.json 存在性，不模拟 loader 的锚点解析完整链。
• 不替你做决定：多包 tool 冲突时只给「隔离其中一个」的选项，不替你选留哪个。
• 升级 / 卸载动作不实现：ACTION.UNINSTALL / UPGRADE 在 plan 里有定义但没有执行体，
  面板会明说「请用官方插件页」。理由：这两个动作的正确性依赖 dsh 自己的 pluginManager，
  自己 spawn pnpm 复现一遍只会多出一个故障源。
• 自愈会改 node_modules：这是它唯一越界的地方，所以默认只在 confidence: high
  （包自己的 package.json name）时动手，并且每次都留字节备份。