@noob-stupid/dsh-plugin-console 0.5.28 → 0.5.30

package/lib/server/domain/preset-rows.js

@@ -0,0 +1,285 @@
+// L1 · domain —— preset-rows.js（预设 **plugins 行**的契约校验 + 已知别名归一；0.5.29 改错+加法）
+//
+// 为什么必须有它（**真机缺陷 D-⑦**，2026-09-27 定位）：
+//   `preset-declare.js` 把 `.agent-presets/<id>/agent.cordis.yml` 原样搬成 profile 补丁里的
+//   `plugins:` —— 但**只做结构校验**（preset-yaml.js：空文件 / tab / 未闭合引号 / 缩进跳级）。
+//   于是这样一份**结构完全合法、框架却挂不上**的 composition 被照写不误：
+//       - id: persona
+//         name: '@deepseek-ai/dsh-persona'
+//         config:
+//           text: You are a helpful software engineer assistant.   # ← 该插件不认 text
+//   框架侧 `@deepseek-ai/dsh-persona` 的 Config 是 `prefix: z.string().required()`，
+//   装配时抛 `$.prefix missing required value`；注册表 `activate()` 把它吞成 `record.broken`，
+//   界面那张卡片就永远顶着一枚红框「加载失败」（框架自己的 `brokenBadge`），用户点也点不动。
+//   而**改前判据一条都拦不住**：YAML 合法、文件都在、包名都在。
+//
+// 本模块只做三件事，全部**证据驱动、可离线判定**（判据表见 PLUGIN_ROW_CONSTRAINTS）：
+//   ① 行结构：不是映射 / 没有非空 `name`（框架 `entryListProblem` 同样会拒）；
+//   ② `file:///` 引用目标**必须存在**（不存在 → 如实拒绝，绝不写一行必然加载失败的声明）；
+//   ③ **已确证的框架契约**逐条核（缺必填键 / 用了别名键）。命中即拒绝并给可执行出路。
+//
+// ⚠️ 判据表**故意不猜**：只收「本机拿真机错误 + 框架真 schema 双向确证过」的条目。
+//   没有证据的插件一律放行 —— 宁可漏判，也绝不因为猜错而把一个**本来可用**的预设挡在门外
+//   （那是把缺陷换个方向，与 preset-yaml.js 的宽严分寸同一取舍）。
+//
+// 分层：L1 domain —— 纯函数、无 IO、无 ctx；文件存在性 / 路径解码 / 包解析均可注入（便于离线断言）。
+// 行数预算：本模块独立于 preset-declare.js，两者各自留在 600 行架构硬顶内。
+
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 已知插件的行契约。每条都必须有**真机错误原文**背书（见文件头 D-⑦）。 */
+const PLUGIN_ROW_CONSTRAINTS = [
+  {
+    /** 行 `name:` 精确匹配该插件的行才受这条约束。 */
+    module: '@deepseek-ai/dsh-persona',
+    /** 必填键（缺了框架 schema 直接抛 `$.<key> missing required value`）。 */
+    required: ['prefix'],
+    /** 报错时给用户的可执行出路。 */
+    hint: '@deepseek-ai/dsh-persona 只认 prefix/suffix/complete/includeRuntimeContext；'
+      + 'config.text 是旧版字段（0.1.5 起改名为 prefix），框架 schema 读不到它 → 请把 config.text 改名为 config.prefix',
+  },
+]
+
+/**
+ * **插件 config 键改名迁移表 —— 全仓唯一出处。**
+ *
+ * ⚠️ 这张表原本只在 `presets.js`（`PRESET_CONFIG_MIGRATIONS`）里，**只在框架升级那一步**跑。
+ * 真实缺口：预设的来源不止"框架升级"一条 —— 装一个预设型子包 / 源码装配 / 手工放文件，
+ * 都会把 `agent.cordis.yml` 落到 `.agent-presets/`，**完全不经过升级步骤**，于是旧键原样留下。
+ * 本机事实（2026-09-27）：`router-spec/agent.cordis.yml` 是当天 21:27 装配落盘的，
+ * 内容里仍是 `text:` → 声明行照写 → 卡片永远「加载失败」。所以判据要挂在**写行那一刻**。
+ *
+ * `presets.js` 从这里取同一张表，两处判据不会再分叉。
+ */
+const PRESET_CONFIG_KEY_MIGRATIONS = [
+  { pkg: '@deepseek-ai/dsh-persona', from: 'text', to: 'prefix', since: '0.1.5' },
+]
+
+/** 粗粒度版本解析（只认 `maj.min.pat`，`-rc.n` 之类预发布尾缀忽略）；不可解析返回 null。 */
+function parseDottedVersion(value) {
+  const m = String(value ?? '').match(/(\d+)\.(\d+)\.(\d+)/u)
+  return m === null ? null : { maj: Number(m[1]), min: Number(m[2]), pat: Number(m[3]) }
+}
+
+/** `target >= since`？任一侧不可解析 → false（**不敢迁移**比乱迁移安全）。 */
+function isVersionAtLeast(target, since) {
+  const t = parseDottedVersion(target)
+  const s = parseDottedVersion(since)
+  if (t === null || s === null) return false
+  if (t.maj !== s.maj) return t.maj > s.maj
+  if (t.min !== s.min) return t.min > s.min
+  return t.pat >= s.pat
+}
+
+/**
+ * 纯文本版的键改名迁移（不碰盘）：只改 `name:` 精确命中 `mig.pkg` 的行，且**仅当该行 config
+ * 里还没有真键**（已有 `prefix` 就一个字节都不动 —— 绝不覆盖用户自己写的值）。
+ * 返回 `{ text, migrated: [{ pkg, from, to, line }], skippedReason }`。
+ *
+ * ⚠️ `targetVersion` 为 `null`/不可解析时的取舍（**很要紧，别随手改**）：
+ *   声明行这套机制**只在框架 0.1.7-rc.x 起才存在**（0.1.5 及更早靠目录发现，写行没有意义），
+ *   能走到本函数的场景必然 ≥ 0.1.7，因此**未知版本按「全部迁移都适用」处理**。
+ *   反过来若按 `isVersionAtLeast(null, …) === false` 处理，就会在"拿不到版本"时静默不动 ——
+ *   于是又写出那行必然「加载失败」的声明，把本函数存在的意义整条抹掉。
+ *   真机 D-⑦ 的现场正是"拿不到版本"（装配服务不知道框架版本）。
+ */
+function migratePluginRowKeys(compositionText, targetVersion, opts = {}) {
+  const rules = opts.rules ?? PRESET_CONFIG_KEY_MIGRATIONS
+  const unknownVersion = parseDottedVersion(targetVersion) === null
+  const apply = unknownVersion ? [...rules] : rules.filter((r) => isVersionAtLeast(targetVersion, r.since))
+  const lines = String(compositionText ?? '').replace(/\r\n/gu, '\n').split('\n')
+  const migrated = []
+  if (apply.length === 0) {
+    return { text: lines.join('\n'), migrated, skippedReason: `目标版本 ${JSON.stringify(String(targetVersion ?? ''))} 低于全部迁移的引入版本 —— 不动用户配置` }
+  }
+  let rowName = null
+  let configIndent = -1
+  let rowIndent = -1
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (raw.trim() === '' || /^\s*#/u.test(raw)) continue
+    const indent = (raw.match(/^ */u) ?? [''])[0].length
+    const item = raw.match(/^(\s*)- id:\s*(\S+)\s*$/u)
+    if (item !== null) { rowIndent = indent; rowName = null; configIndent = -1; continue }
+    if (rowIndent < 0) continue
+    if (indent <= rowIndent) { rowName = null; configIndent = -1; continue }
+    const kv = raw.match(/^(\s*)([A-Za-z_][\w-]*):(.*)$/u)
+    if (kv === null) continue
+    const directKey = indent === rowIndent + 2
+    if (directKey && kv[2] === 'name') { rowName = kv[3].trim().replace(/^['"]|['"]$/gu, ''); configIndent = -1; continue }
+    if (directKey && kv[2] === 'config' && kv[3].trim() === '') { configIndent = indent; continue }
+    if (configIndent < 0 || indent <= configIndent) continue
+    for (const rule of apply) {
+      if (rule.pkg !== rowName || rule.from !== kv[2]) continue
+      // 该行 config 里已有真键 → 本次跳过（绝不覆盖用户自己的值）
+      let hasNew = false
+      for (let j = configIndent + 1; j < lines.length; j += 1) {
+        const l = lines[j]
+        if (l.trim() === '') continue
+        const ind = (l.match(/^ */u) ?? [''])[0].length
+        if (ind <= configIndent) break
+        if (new RegExp(`^\\s*${rule.to}:`, 'u').test(l)) { hasNew = true; break }
+      }
+      if (hasNew) continue
+      lines[i] = `${kv[1]}${rule.to}:${kv[3]}`
+      migrated.push({ pkg: rule.pkg, from: rule.from, to: rule.to, line: i + 1 })
+    }
+  }
+  return { text: lines.join('\n'), migrated, skippedReason: null }
+}
+
+/** 值归一：去引号、折行、`''`→`'`；空串一律视作**未提供**（框架 schema 对 `''` 与缺失的处理不同，这里只判存在性）。 */
+/** 行解析：composition 里的 `- id:` / `name:` / `config:` + config 直属子键（只认缩进语义，不做通用 YAML）。 */
+function parseCompositionRows(text) {
+  // ⚠️ 必须先归一 CRLF：真机磁盘上的 agent.cordis.yml 就是 CRLF（本机三个预设全是），
+  //    行尾的 `\r` 会让 `^(\s*)- id:\s*(\S+)\s*$` 这类判据整体失配（自测真抓到过：归一一条都不命中）。
+  const lines = String(text ?? '').replace(/\r\n/gu, '\n').split('\n')
+  const rows = []
+  let row = null
+  let configIndent = null
+  let blockKey = null
+  let blockIndent = 0
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index]
+    if (raw.trim() === '' || /^\s*#/u.test(raw)) {
+      if (blockKey !== null && row !== null) row.config[blockKey] += '\n'
+      continue
+    }
+    const indent = (raw.match(/^ */u) ?? [''])[0].length
+    if (blockKey !== null && indent > blockIndent) {
+      row.config[blockKey] += `${raw}\n`
+      continue
+    }
+    blockKey = null
+    const item = raw.match(/^(\s*)- id:\s*(\S+)\s*$/u)
+    if (item !== null) {
+      row = {
+        id: item[2].replace(/^['"]|['"]$/gu, ''),
+        indent,
+        name: null,
+        config: {},
+        line: index + 1,
+      }
+      rows.push(row)
+      configIndent = null
+      continue
+    }
+    if (row === null) continue
+    const kv = raw.match(/^\s*([A-Za-z_][\w-]*):\s*(.*)$/u)
+    if (kv === null) continue
+    const key = kv[1]
+    const value = kv[2].trim()
+    if (indent <= row.indent) { row = null; configIndent = null; continue }
+    if (indent === row.indent + 2 && key === 'name') { row.name = value.replace(/^['"]|['"]$/gu, ''); configIndent = null; continue }
+    if (indent === row.indent + 2 && key === 'config' && value === '') { configIndent = indent; continue }
+    if (key === 'id') continue
+    // config 直属子键：缩进必须比 `config:` 更深
+    if (configIndent !== null && indent > configIndent) {
+      row.config[key] = value
+      if (/^[|>][-+]?\d*$/u.test(value)) { blockKey = key; blockIndent = indent }
+    }
+  }
+  return rows
+}
+
+/** 默认解码器：`file:` URL → 磁盘路径（Node 自己的实现会拒绝坏百分号编码）。 */
+const defaultToLocalPath = (url) => fileURLToPath(url)
+/** 默认路径拼接（相对引用以预设目录为基准）。 */
+const defaultJoinPath = (dir, relative) => join(dir, relative)
+
+/** 值归一：去引号、折行、`''`→`'`；空串一律视作**未提供**（框架 schema 对 `''` 与缺失的处理不同，这里只判存在性）。 */
+function normalizeConfigValue(raw) {
+  if (raw === undefined || raw === null) return null
+  const text = String(raw).trim()
+  if (text === '') return null
+  if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) return text.slice(1, -1).replace(/''/gu, "'")
+  if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) return text.slice(1, -1)
+  return text
+}
+
+/**
+ * ① 行结构 + ② `file:///` 目标存在性 + ③ 已确证契约。返回 `{ ok, problems: [{ code, row, detail, hint }] }`。
+ * `exists` 可注入（离线断言用）；`checkFile` 为 false 时跳过 ②（只想要契约判据时用）。
+ */
+function validatePresetPluginRows(compositionText, opts = {}) {
+  // `exists` 吃**磁盘路径**（不是 URL）；`toLocalPath` / `joinPath` 可注入，便于离线断言。
+  const {
+    exists = null, checkFiles = true, presetDir = null,
+    toLocalPath = defaultToLocalPath, joinPath = defaultJoinPath,
+  } = opts
+  const problems = []
+  const rows = parseCompositionRows(compositionText)
+
+  if (rows.length === 0) {
+    problems.push({ code: 'no-plugin-rows', row: null, detail: 'composition 里没有任何 `- id:` 插件行', hint: '框架挂载空预设没有意义，请检查 agent.cordis.yml' })
+    return { ok: false, problems, rows: 0 }
+  }
+
+  for (const row of rows) {
+    // ① 结构：框架 `entryListProblem` 会先拒掉没有 name 的行
+    if (typeof row.name !== 'string' || row.name === '') {
+      problems.push({ code: 'row-names-no-plugin', row: row.id, detail: `行 ${row.id} 没有 name（框架要求非空字符串）`, hint: '补上 `name:`（包名或 file:/// URL）' })
+      continue
+    }
+    // ② file:/// 目标必须存在 —— 写一行指向不存在文件的声明，等于必然「加载失败」
+    if (checkFiles && /^file:\/\//iu.test(row.name)) {
+      let localPath = null
+      try {
+        const url = new URL(row.name)
+        if (url.protocol !== 'file:') throw new Error('不是 file: 协议')
+        // 必须真的解码成磁盘路径：坏百分号编码（`%zz`）在 URL 层是"合法"的，
+        // 到加载器才知道读不了 —— 那正是要在**写行之前**拦下的形状。
+        localPath = toLocalPath(url)
+      } catch (error) {
+        problems.push({ code: 'file-url-unparsable', row: row.id, detail: `行 ${row.id} 的 file: 引用无法解析成磁盘路径：${row.name}（${error.message}）`, hint: '改成合法的 file:/// 绝对 URL（路径片段要按 URL 规则百分号编码）' })
+        continue
+      }
+      let present = null
+      try { present = exists === null ? null : exists(localPath) } catch { present = null }
+      if (present === false) {
+        problems.push({ code: 'file-target-missing', row: row.id, detail: `行 ${row.id} 引用的文件不存在：${localPath}`, hint: '该预设引用了磁盘上没有的文件 —— 请补齐文件或修正引用（绝不写必然加载失败的行）' })
+      }
+    }
+    // ②′ 相对引用（`./x.mjs` / `../x.mjs`）：声明行落在 **profile 补丁**里，相对基准变成 profile 目录，
+    //     所以预设目录里不存在同名文件的相对引用**改不过去、留着也必然加载失败**。
+    //     改前行为是"照写、留给读回核实判红" —— 那已经**写坏用户补丁**了（自测真抓到过这个形状：
+    //     ok:false + verify-failed + 补丁已被改动）。契约校验必须在**动手写之前**拦下它。
+    if (checkFiles && /^\.\.?\//u.test(row.name) && presetDir !== null) {
+      const target = joinPath(presetDir, row.name)
+      let present = null
+      try { present = exists === null ? null : exists(target) } catch { present = null }
+      if (present === false) {
+        problems.push({
+          code: 'relative-target-missing',
+          row: row.id,
+          detail: `行 ${row.id} 用相对引用 \`${row.name}\`，但预设目录里没有这个文件（${target}）`,
+          hint: '相对引用在 profile 补丁里以 **profile 目录**为基准、且预设目录里没有该文件可改写 —— '
+            + '请补齐该文件，或把这一行改成真实存在的包名 / file:/// 绝对 URL（绝不写必然加载失败的行）',
+        })
+      }
+    }
+    // ③ 已确证的框架契约
+    for (const rule of PLUGIN_ROW_CONSTRAINTS) {
+      if (row.name !== rule.module) continue
+      const keys = Object.keys(row.config)
+      const present = keys.filter((k) => normalizeConfigValue(row.config[k]) !== null)
+      const missing = rule.required.filter((k) => !present.includes(k))
+      if (missing.length > 0) {
+        problems.push({
+          code: 'missing-required-config',
+          row: row.id,
+          detail: `行 ${row.id}（${row.name}）缺少必填 config 键 ${missing.map((k) => `\`${k}\``).join('、')}`
+            + `（现有键：${keys.length === 0 ? '无' : keys.map((k) => `\`${k}\``).join('、')}）—— 框架 schema 会抛 \`$.${missing[0]} missing required value\``,
+          hint: rule.hint,
+        })
+      }
+    }
+  }
+  return { ok: problems.length === 0, problems, rows: rows.length }
+}
+
+export {
+  PLUGIN_ROW_CONSTRAINTS, PRESET_CONFIG_KEY_MIGRATIONS, isVersionAtLeast, migratePluginRowKeys,
+  normalizeConfigValue, parseCompositionRows, parseDottedVersion, validatePresetPluginRows,
+}

package/lib/server/domain/presets.js

@@ -6,6 +6,7 @@ import { join } from 'node:path'
 import { isVersionAtLeast } from './framework.js'
 import { escapeRegExp } from '../infra/mask.js'
 import { dshHome } from '../infra/paths.js'
+import { PRESET_CONFIG_KEY_MIGRATIONS } from './preset-rows.js'
 
 /**
  * 预设/组合文件的配置迁移门禁（2026-09-10 事故）：
@@ -13,10 +14,12 @@ import { dshHome } from '../infra/paths.js'
  * 适配门只扫「已装插件包源码」，**预设不在其中**（~/.dsh/.agent-presets/<name>/agent.cordis.yml），
  * 于是升级后预设挂载失败 → 服务/会话起不来（这次就是这么挂的）。
  * 升级前按目标版本扫描并自动迁移（写 .bak 备份），返回迁移清单供步骤展示。
+ *
+ * ⚠️ 0.5.29 起这张表**搬到 preset-rows.js**（全仓唯一出处）：升级只是预设落盘的五条路之一，
+ * 装预设型子包 / 源码装配 / 手工放文件都不经过这里，于是旧键会原样留下、声明行照写、卡片永远「加载失败」
+ * （真机 D-⑦）。preset-declare.js 现在在**写行那一刻**用同一张表做纯文本迁移，判据不会再分叉。
  */
-const PRESET_CONFIG_MIGRATIONS = [
-  { pkg: '@deepseek-ai/dsh-persona', from: 'text', to: 'prefix', since: '0.1.5' },
-]
+const PRESET_CONFIG_MIGRATIONS = PRESET_CONFIG_KEY_MIGRATIONS
 
 /** 待扫描的 agent 配置文件：所有预设 + profile 的 host 组合。 */
 function collectAgentConfigFiles(profileDir) {

package/lib/server/infra/exec.js

@@ -33,14 +33,35 @@ const CMD_META_RE = /[\^&|<>()]/gu
  *     · `"a" "b"`   + windowsVerbatimArguments → `/s` 会把首尾两个引号一起剥掉 → 也失败
  *     · `""a" "b""` + windowsVerbatimArguments → 正确解析成两个参数 ✓（含空格 / `&` / `|` / `>` 的参数
  *       在段内加 `^` 转义后也原样到达）
- *   所以本函数产出的是"**内层**命令字符串"（形如 `"corepack" "pnpm" "add" "x"`，**永不含 `\"`**），
+ *   所以本函数产出的是"**内层**命令字符串"（形如 `corepack pnpm add x`，**永不含 `\"`**；只有含空白的段才带引号 —— 2026-09-28 改错，见函数内注释），
  *   最外层那对引号由 cmdShellArgv 负责加。
  * 已知边界（如实记，不假装覆盖）：`%VAR%` 与开启延迟展开时的 `!VAR!` 是 cmd 自己的展开，
  *   **任何引号/`^` 都挡不住**；我们生成的 argv（包名、registry、布尔选项、绝对路径）不含这两个字符，
  *   真出现时该通道会失败并如实报错（不会静默跑成别的命令）。 */
 function cmdCommandLine(parts) {
   return parts
-    .map((part) => `"${String(part).replace(CMD_META_RE, (ch) => `^${ch}`)}"`)
+    .map((part) => String(part))
+    .map((text) => {
+      // 2026-09-28 改错（真机：`cmd-corepack` 一条都跑不动 → pnpm-runners / suite-fallback /
+      // install-smoke 三套红，报 `cmd-corepack :: status=1 out=""`）：
+      //   `corepack` 在本机是 **cmd 批处理 shim**（`D:\nvm4w\nodejs\corepack.cmd` →
+      //   `node …\corepack\dist\corepack.js %*`）。对批处理，cmd **不会剥掉参数外层的引号**，
+      //   引号会随 `%*` 一路进到 node 的 argv —— 于是 corepack 收到的是 `"pnpm"` / `"--version"`
+      //   （带引号当成了包管理器名）→ 直接崩：status=1、stdout 空。
+      //   真 cmd.exe + windowsVerbatimArguments 实测（同一台机）：
+      //     · `""corepack" "pnpm" "--version""` → status=1、stdout=""（现行形态，坏）
+      //     · `"corepack pnpm --version"`      → status=0、stdout="11.21.0"（按需引号，好）
+      //   所以**只为含空白的段加引号**；其余裸串 + `^` 转义 cmd 元字符（裸串里 `^` 是标准且可靠的转义）。
+      //   含空白的段仍走「引号 + 段内 ^ 转义」，与既有行为一致，不改语义。
+      // 已知边界（如实记）：段内含 `"` 时无法在 cmd 里安全表达 —— 我们生成的 argv（包名/registry/布尔
+      //   选项/绝对路径）不含裸引号；真出现时该通道会失败并如实报错，不会静默跑成别的命令。
+      // 「干净 token」（无空白、无 cmd 元字符）→ 裸串。**只有这种情况**能去引号：
+      //   含空白的段必须带引号；含 `& | < > ( ) ^` 的段，实测**裸串 + `^` 转义会失效**
+      //   （真机 ⑥：裸的 `a^&b` 被 cmd 当分隔符断开，收到 `[a`），必须沿用「引号 + 段内 ^」的既有形态。
+      const clean = !/[\s]/u.test(text) && !/[\^&|<>()]/u.test(text)
+      if (clean) return text
+      return `"${text.replace(CMD_META_RE, (ch) => `^${ch}`)}"`
+    })
     .join(' ')
 }
 

package/lib/server/infra/framework-root.js

@@ -0,0 +1,99 @@
+// L0 · infra —— framework-root.js（框架运行时解析基准；0.5.30 加法）
+//
+// 为什么必须有它（**真机事故 2026-09-28 / 2026-09-29**）：
+//   框架 0.2.0-rc.1 把 `@deepseek-ai/*` 的实体全部搬进 `.pnpm` **内部**那层，profile 顶层
+//   projection 还停在旧版（本机实测：顶层 239 个 `@deepseek-ai` 目录仍是 0.1.5-rc.2 的残影）。
+//   任何"只拿 profileDir 当解析基准"的判断都会把**真存在的框架内置包**（`dsh-agent-preset`、
+//   `dsh-workflow-ptc`）判成"缺失" —— 实测后果：`healPatchSafety()` 给它们自动写了 4 个
+//   `disabled: true` 块（2026-09-29 01:05:44），把用户的 preset-router-* 三条全停掉。
+//
+// 所以「框架内置包在不在」必须走**多基准并集**：任一基准能解析即算命中。
+// 本模块把该判据集中一处，供只读体检（routes/patch-audit.js）与补丁自愈（domain/patch.js）共用 ——
+// 两处若各写一份，下次框架再挪目录就会只有一处被修好。
+//
+// 行数预算：独立小模块，留在 600 行架构硬顶内。
+
+import { existsSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+import { resolvePackageJson } from './paths.js'
+
+/** 框架命名空间：`@deepseek-ai/*` 随框架版本走，承载者永远是框架安装树。 */
+const FRAMEWORK_SCOPE = '@deepseek-ai/'
+
+/** 包名归一：`@scope/name/sub` → `@scope/name`；裸名原样。 */
+function basePackageName(moduleName) {
+  const text = String(moduleName ?? '')
+  if (text.startsWith('@')) {
+    const parts = text.split('/')
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : text
+  }
+  return text.split('/')[0]
+}
+
+/** 归一后的包名是否属于框架命名空间（`@deepseek-ai/dsh-*`）。 */
+function isFrameworkModuleName(moduleName) {
+  const name = basePackageName(moduleName)
+  return name === FRAMEWORK_SCOPE.slice(0, -1) || name.startsWith(FRAMEWORK_SCOPE)
+}
+
+/** 路径是否落在给定根目录内（大小写不敏感，Windows 与 POSIX 都成立）。 */
+function isUnder(childPath, rootDir) {
+  if (typeof childPath !== 'string' || childPath === '' || typeof rootDir !== 'string' || rootDir === '') return false
+  let child = resolve(childPath).toLowerCase()
+  let root = resolve(rootDir).toLowerCase()
+  if (!root.endsWith(sep)) root += sep
+  if (!child.endsWith(sep)) child += sep
+  return child.startsWith(root)
+}
+
+/**
+ * 框架运行时解析基准（**有序**，先准后宽）：
+ *   ① `@deepseek-ai/dsh` 所在的那层 `node_modules`（= `.pnpm` 实体内部，框架内置包的真正家）
+ *   ② 从 ① 向上逐级找到的第一个含 `.pnpm` 的目录（与 ① 同层时去重）
+ *   ③ `@deepseek-ai/dsh` 解析不出来时的兜底：`baseDir` / `profileDir` 自身（供离线测试桩使用）
+ * 返回去重后的绝对路径数组；一个都拿不到时返回 `[]`（调用方必须把空数组当"无法判定"而非"缺失"）。
+ */
+function frameworkBases(baseDir, profileDir) {
+  const out = []
+  const push = (dir) => {
+    if (typeof dir !== 'string' || dir === '' || !isAbsolute(dir)) return
+    const norm = resolve(dir)
+    if (!out.includes(norm)) out.push(norm)
+  }
+  let found = null
+  // base 有两种合法写法（`…/profiles/web` 这种**含 node_modules 的目录**，或 `…/.pnpm/<pkg>/node_modules`
+  // 这种 **node_modules 本身**）；resolvePackageJson 只认前者，所以后者要退一级再试 ——
+  // 否则框架基准这一路永远解析不到 `@deepseek-ai/dsh`，整个框架基准列表会退化成兜底值。
+  for (const base of [baseDir, profileDir]) {
+    if (typeof base !== 'string' || base === '') continue
+    for (const cand of [base, dirname(base)]) {
+      if (typeof cand !== 'string' || cand === '') continue
+      try {
+        found = resolvePackageJson('@deepseek-ai/dsh', cand, profileDir)
+      } catch { found = null }
+      if (found !== null) break
+    }
+    if (found !== null) break
+  }
+  if (found !== null) {
+    // ★ 2026-09-30 改错（本批修 A 事故时抓到）：这里过去是 `dirname(dirname(pkgPath))` ——
+    //   pkgPath 形如 `<…>/node_modules/@deepseek-ai/dsh/package.json`，两层 dirname 只退到
+    //   **scope 目录** `<…>/node_modules/@deepseek-ai`（实测 `existsSync(inner@deepseek-ai)` = false），
+    //   拿它当解析基准必然解析不到任何包。正确是**三层**：package.json → dsh → @deepseek-ai → node_modules。
+    const inner = dirname(dirname(dirname(found)))
+    push(inner)
+    let dir = inner
+    for (let i = 0; i < 6; i += 1) {
+      if (existsSync(join(dir, '.pnpm'))) { push(dir); break }
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  }
+  // 兜底：框架树找不到时，至少把 profile 目录本身当基准 —— 否则 `bases` 为空会让
+  // 自愈把所有 insert 行都判成"无法确认"（宁缺勿滥，但那会让真缺失的行不再被停用）。
+  if (out.length === 0) { push(profileDir); push(baseDir) }
+  return out
+}
+
+export { FRAMEWORK_SCOPE, basePackageName, frameworkBases, isFrameworkModuleName, isUnder }

package/lib/server/infra/package-resolve.js

@@ -0,0 +1,73 @@
+// L0 · infra —— package-resolve.js（Node 解析器封装：包名可解析性 + 可用包名枚举；0.5.30 加法）
+//
+// 为什么不用「store 目录名」判断包在不在（真机教训 2026-09-28）：
+//   pnpm 会**截断超长目录名**（`@deepseek-ai+dsh-workflow-ptc` → `@deepseek-ai+dsh-workflow-p_<hash>`），
+//   按目录名前缀匹配会把**存在的包**误判成不存在 —— 本机实测：`dsh-workflow-ptc`、`dsh-agent-preset`
+//   两个真存在的包都被目录名法误报。所以体检一律走 **Node 自己的解析器**（与框架加载补丁行同一套解析），
+//   并在多个基准上取并集：① profile 目录（第三方插件在这里）② 框架运行时根（`@deepseek-ai/*` 在这里）。
+
+import { createRequire } from 'node:module'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * 基准目录 → `createRequire` 的探针位置。
+ * base 有两种合法写法，本函数把两者都收下（判据：base 自己是不是就叫 node_modules）：
+ *   · base 是**含 node_modules 的目录**（如 profile 目录 `<…>/profiles/web`）→ 探针 `<base>/__patch_audit_probe__.js`
+ *   · base 本身就是 **node_modules 目录**（如 `…/.pnpm/@deepseek-ai+dsh@…/node_modules`）→ 探针放它内部
+ * 为什么必须兼容第二种：框架内置包的实体只存在于 `.pnpm/<pkg>/node_modules/` 这一层，
+ * 说"框架基准"时最自然的写法就是那层本身；若一律拼 `<base>/node_modules/…`，
+ * 就会去找 `<…>/node_modules/node_modules` —— **真存在的包被判成不存在**（本套 ① 段即是回归）。
+ */
+function probePathOf(base) {
+  return base.replace(/[\\/]+$/u, '').toLowerCase().endsWith('node_modules')
+    ? join(base, '__patch_audit_probe__.js')
+    : join(base, 'node_modules', '__patch_audit_probe__.js')
+}
+
+/** 造多基准解析器：任一基准能解析即算命中（`from` 如实回带，便于报告里说明"从哪解析到的"）。 */
+function makePackageResolver(bases) {
+  const reqs = []
+  for (const base of (Array.isArray(bases) ? bases : [])) {
+    if (typeof base !== 'string' || base === '') continue
+    try { reqs.push(createRequire(probePathOf(base))) } catch {}
+  }
+  return (name) => {
+    for (const req of reqs) {
+      try { return { ok: true, from: req.resolve(name) } } catch {}
+    }
+    return { ok: false, reason: '所有基准都解析不到（包可能已被移除/改名，或该子路径不存在）' }
+  }
+}
+
+/** 枚举一个 node_modules 目录下可见的包名（含 scope 内一层）。 */
+function listPackageNames(nodeModulesDir, limit = 4000) {
+  const out = []
+  try {
+    for (const entry of readdirSync(nodeModulesDir, { withFileTypes: true })) {
+      if (out.length >= limit) break
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+      if (entry.name.startsWith('@')) {
+        for (const sub of readdirSync(join(nodeModulesDir, entry.name), { withFileTypes: true })) {
+          if (out.length >= limit) break
+          if (sub.isDirectory() && !sub.name.startsWith('.')) out.push(`${entry.name}/${sub.name}`)
+        }
+        continue
+      }
+      out.push(entry.name)
+    }
+  } catch {}
+  return out
+}
+
+/** 合并多个 node_modules 目录下的包名（去重）—— 供「疑似改名」当候选集。 */
+function listAvailablePackages(dirs) {
+  const set = new Set()
+  for (const dir of (Array.isArray(dirs) ? dirs : [])) {
+    if (typeof dir !== 'string' || dir === '' || !existsSync(dir)) continue
+    for (const name of listPackageNames(dir)) set.add(name)
+  }
+  return [...set]
+}
+
+export { listAvailablePackages, listPackageNames, makePackageResolver }

package/lib/server/infra/registry-versions.js

@@ -0,0 +1,64 @@
+// L0 · infra —— registry-versions.js（registry 元数据探针：包名 → 某版本是否已发布；0.5.30 加法）
+//
+// 用途：**升级前**核对「profile 补丁里引用的框架包，在目标版本里还在不在」。
+// 真机事故 2026-09-28：0.2.0-rc.1 移除了 `@deepseek-ai/dsh-workflow-worker-thread`（引擎改为 ptc），
+// 补丁仍指向旧包 → 升级后 `workflowEngine` 无提供方 → 老会话 resume 失败。
+// 这类「官方移除/改名」在升级前**只能用 registry 元数据看见**（目标版本还没装到本机）。
+//
+// 三个取舍：
+//   ① 同一次预检里**同一个包只查一次**（内存缓存）—— 补丁里同名包可能出现在多处；
+//   ② 网络失败/元数据缺失 → 返回 **null（未知）**，绝不当作「不存在」；
+//   ③ 小并发（默认 4）+ 单请求超时，避免预检被 30 个包串行拖死。
+
+import { fetchJsonUrl } from './http.js'
+
+/** 包名 → URL 片段（`@a/b` → `@a%2fb`）。 */
+function encodePackageName(name) {
+  return String(name).replace('/', '%2f')
+}
+
+/** 造版本探针：`(name) => { ok, versions?, error? }`（带内存缓存）。 */
+function makeVersionProbe({ registry, fetchJson, timeoutMs = 9000, cache = new Map() } = {}) {
+  const fetchImpl = typeof fetchJson === 'function' ? fetchJson : (url, t) => fetchJsonUrl(url, t)
+  return async (name) => {
+    if (cache.has(name)) return cache.get(name)
+    let result
+    try {
+      const meta = await fetchImpl(`${registry}/${encodePackageName(name)}`, timeoutMs)
+      const versions = meta && typeof meta === 'object' && meta.versions !== null && typeof meta.versions === 'object'
+        ? Object.keys(meta.versions)
+        : []
+      result = { ok: true, versions }
+    } catch (error) {
+      result = { ok: false, error: String(error?.message ?? error) }
+    }
+    cache.set(name, result)
+    return result
+  }
+}
+
+/** 批量核对：`[{name, lines}]` → `[{name, lines, published: true|false|null}]`（小并发，保序）。 */
+async function checkPublishedVersions(entries, { probe, version, concurrency = 4 } = {}) {
+  const list = Array.isArray(entries) ? entries : []
+  const width = Math.max(1, Number.isFinite(concurrency) && concurrency > 0 ? Math.floor(concurrency) : 4)
+  const out = new Array(list.length)
+  let cursor = 0
+  const worker = async () => {
+    for (;;) {
+      const index = cursor
+      cursor += 1
+      if (index >= list.length) return
+      const entry = list[index]
+      let published = null
+      try {
+        const res = await probe(entry.name)
+        if (res?.ok === true) published = Array.isArray(res.versions) ? res.versions.includes(version) : null
+      } catch { published = null }
+      out[index] = { name: entry.name, lines: Array.isArray(entry.lines) ? entry.lines : [], published }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(width, list.length) }, () => worker()))
+  return out.filter((x) => x !== undefined)
+}
+
+export { checkPublishedVersions, encodePackageName, makeVersionProbe }

package/lib/server/routes/compat.js

@@ -13,6 +13,7 @@
 
 import { dirname } from 'node:path'
 import { compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
+import { NOTICE_MODES, detectCompat, readCompatAck, readCompatGate, writeCompatAck, writeCompatGate } from '../domain/compat.js'
 import { currentFrameworkVersion } from '../domain/framework.js'
 import { applyDependencyBackfill, planDependencyBackfill } from '../domain/manifest.js'
 import { preferredRegistries } from '../domain/sources.js'
@@ -127,4 +128,43 @@ async function routeDeclareInstalled(req, res, rc) {
   }
 }
 
-export { routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled }
+/** 兼容提示：手动关闭 / 设定展示模式（2026-09-28 加法）。
+ *
+ *  背景（用户实测）：面板顶部那句「当前 DSH web 包版本 X 不在受支持的 0.1.x 系列内…」是**披露**，
+ *  但它以前**关不掉** —— 纯 `<p>`、没有关闭入口、也没有持久化。用户诉求：可以手动关。
+ *
+ *  两种入参（互斥，按字段判断）：
+ *    · `{ webAppVersion }` → 记住"这个版本我看过了"：同版本不再提示，**框架版本一变重新提示**
+ *    · `{ mode }`         → 展示模式 `always` / `once-per-version`（默认）/ `off`
+ *
+ *  ⚠ 硬约束：**只影响展示，不改 `supported`** —— 门控判定与"该不该拦"一个字都不变，
+ *    披露不能被关成"看不见的风险"。版本还会校验：只接受**当前探测到**的那一个，
+ *    避免把 ack 记到别的版本上（否则升到新版本时会被误吞）。
+ */
+async function routeCompatAck(req, res, rc) {
+  const body = rc.body ?? {}
+  if (typeof body.mode === 'string') {
+    const mode = body.mode.trim().toLowerCase()
+    if (!NOTICE_MODES.includes(mode)) {
+      sendError(res, 400, `未知的提示模式：${body.mode}（可选 ${NOTICE_MODES.join(' / ')}）`)
+      return
+    }
+    const gate = writeCompatGate({ noticeMode: mode })
+    sendJson(res, 200, { ok: true, noticeMode: gate.noticeMode, ack: readCompatAck() })
+    return
+  }
+  const version = typeof body.webAppVersion === 'string' ? body.webAppVersion.trim() : ''
+  if (version === '' || !/^\d+\.\d+\.\d+/u.test(version)) {
+    sendError(res, 400, 'webAppVersion 缺失或格式不对（形如 0.2.0-rc.1）')
+    return
+  }
+  let detected = null
+  try { detected = (await detectCompat(rc?.ctx?.baseUrl ?? 'file:///')).webAppVersion } catch {}
+  if (detected !== null && detected !== version) {
+    sendError(res, 400, `版本不匹配：当前探测到 ${detected}，请求里是 ${version}（请刷新后重试）`)
+    return
+  }
+  const ack = writeCompatAck(version)
+  sendJson(res, 200, { ok: true, ack, noticeMode: readCompatGate().noticeMode })
+}
+export { routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled }