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

package/lib/server/domain/patch-composition-audit.js

@@ -0,0 +1,218 @@
+// L1 · domain —— patch-composition-audit.js（补丁「行 → 包」可解析性体检；0.5.30 加法）
+//
+// 为什么必须有它（**真机事故 2026-09-28**）：
+//   框架 0.2.0-rc.1 移除了 `@deepseek-ai/dsh-workflow-worker-thread`（引擎重构为 `…-workflow-ptc`），
+//   而 `profiles/web/cordis.patch.yml` 里三处行仍指向旧包名。该行解析失败 → 隔离组里
+//   `workflowEngine` 就没有提供方 → `dsh-tool-workflow` / `dsh-tool-ralph`（`inject` 含 `workflowEngine`）
+//   永久 waiting → 老会话 resume 失败，真机报错原文：
+//     resume failed for session "…": RemoteError: tool-workflow (@deepseek-ai/dsh-tool-workflow):
+//       waiting for workflowEngine tool-ralph (@deepseek-ai/dsh-tool-ralph): waiting for workflowEngine
+//   而现有 format-scan / framework-preflight **只扫「生产方源码里的 API 引用」**，
+//   不扫「补丁里引用的包在当前框架树里还在不在」→ 升级前判「无 blocker」，升级后才炸。
+//
+// 本模块只做三件事（纯函数；`resolve` / `existsFile` 全部可注入，便于离线断言）：
+//   ① 解析补丁行：`- id:` / `name:` / `disabled: true`（嵌套行同样收；缩进语义与 preset-rows.js 同源）；
+//   ② 分类：解析失败=blocker；**已 disabled** 的解析失败=warning；`file://` 目标缺失=blocker；
+//      子路径（`pkg/sub`）解析失败=warning（父包还在，只是导出变了）；
+//   ③ 疑似改名建议：同 scope + 公共 token，纯启发式 —— **只提示，绝不自动改写用户补丁**。
+//
+// 行数预算：独立模块，留在 600 行架构硬顶内。
+
+const ROW_RE = /^(\s*)-\s*id:\s*(\S+)\s*$/u
+const NAME_RE = /^(\s*)name:\s*(.+?)\s*$/u
+const DISABLED_RE = /^(\s*)disabled:\s*true\s*$/u
+const CONFIG_RE = /^(\s*)config:\s*$/u
+
+/** 去引号（单/双）；空串视作未提供。 */
+function unquote(raw) {
+  const text = String(raw ?? '').trim()
+  const quoted = text.length >= 2
+    && ((text.startsWith("'") && text.endsWith("'")) || (text.startsWith('"') && text.endsWith('"')))
+  return quoted ? text.slice(1, -1) : text
+}
+
+/** 解析补丁文本 → 行数组 `{ id, name, disabled, indent, line }`（CRLF 先归一：真机补丁是 CRLF）。 */
+function parsePatchRows(text) {
+  const lines = String(text ?? '').replace(/\r\n/gu, '\n').split('\n')
+  const rows = []
+  let cur = null
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (raw.trim() === '' || /^\s*#/u.test(raw)) continue
+    const item = raw.match(ROW_RE)
+    if (item !== null) {
+      cur = { id: unquote(item[2]), indent: item[1].length, name: null, disabled: false, config: false, keys: 0, line: i + 1 }
+      rows.push(cur)
+      continue
+    }
+    if (cur === null) continue
+    const indent = (raw.match(/^ */u) ?? [''])[0].length
+    if (indent < cur.indent) { cur = null; continue }
+    const name = raw.match(NAME_RE)
+    if (name !== null && indent > cur.indent && cur.name === null) { cur.name = unquote(name[2]); continue }
+    if (DISABLED_RE.test(raw) && indent > cur.indent) cur.disabled = true
+    if (CONFIG_RE.test(raw) && indent > cur.indent) cur.config = true
+    // 行里出现的**任何**键（config / disabled / isolate / …）都说明这是「补丁行」（改已存在条目的配置或开关），
+    // 不是「声明行」—— 声明行才需要 name。真机补丁里 `- id: web-ui-pet` + `disabled: true` 就是这种。
+    const kv = raw.match(/^(\s*)([A-Za-z_][\w-]*):/u)
+    if (kv !== null && indent > cur.indent && kv[2] !== 'id') cur.keys += 1
+  }
+  return rows
+}
+
+/** scope 名（`@a/b` → `@a`；裸名 → 空串）。 */
+function scopeOf(name) {
+  return String(name).startsWith('@') ? String(name).split('/')[0] : ''
+}
+
+/** 词根集合：去掉 scope、按 `-`/`_`/`/` 切，丢弃长度 < 3 的碎片。 */
+function tokensOf(name) {
+  return String(name)
+    .replace(/^@[^/]+\//u, '')
+    .split(/[-_/]/u)
+    .map((t) => t.toLowerCase())
+    .filter((t) => t.length >= 3)
+}
+
+/**
+ * **真机确证的改名片 —— 建议的权威来源**（每条都有真机错误/发布物背书，同 preset-rows.js 的判据文化）。
+ * 表里没有的一律只给「严格启发式候选」，猜不到就不猜（宁缺勿滥）。
+ */
+const KNOWN_RENAMES = [
+  {
+    from: '@deepseek-ai/dsh-workflow-worker-thread',
+    to: '@deepseek-ai/dsh-workflow-ptc',
+    since: '0.2.0-rc.1',
+    evidence: '2026-09-28 真机：升级 0.2.0-rc.1 后 web profile 老会话 resume 失败'
+      + '（RemoteError: tool-workflow … waiting for workflowEngine）；旧包已从 .pnpm store 消失，'
+      + '新引擎 README「最小配置」列出 ptc，且 config.provider 默认 spawn（与旧行一致）',
+  },
+]
+
+/** 疑似改名建议：① 真机确证表命中即权威返回；② 否则严格启发式（同 scope + 前两词根一致 + 交集 ≥ 3）。
+ *  返回 `{ names, source }`，`source: 'known' | 'heuristic' | null`。 */
+function suggestRenames(name, candidates, limit = 3) {
+  const known = KNOWN_RENAMES.filter((r) => r.from === name).map((r) => r.to)
+  if (known.length > 0) return { names: known.slice(0, limit), source: 'known' }
+  const scope = scopeOf(name)
+  const want = tokensOf(name)
+  const scored = []
+  for (const cand of (Array.isArray(candidates) ? candidates : [])) {
+    if (cand === name || scopeOf(cand) !== scope) continue
+    const have = tokensOf(cand)
+    const common = want.filter((t) => have.includes(t)).length
+    const headSame = want.length >= 2 && have.length >= 2 && want[0] === have[0] && want[1] === have[1]
+    if (!headSame || common < 3) continue
+    scored.push({ name: cand, score: common })
+  }
+  scored.sort((a, b) => (b.score - a.score) || a.name.localeCompare(b.name))
+  const names = scored.slice(0, limit).map((s) => s.name)
+  return { names, source: names.length > 0 ? 'heuristic' : null }
+}
+
+/**
+ * 分类体检（纯函数）。`resolve(name)` → `{ ok: true, from }` / `{ ok: false, reason }`；
+ * `existsFile(name)` → boolean（`file://` 目标存在性，未注入则跳过该项）。
+ */
+function classifyPatchRows(rows, { resolve, existsFile = null, candidates = [] } = {}) {
+  const blockers = []
+  const warnings = []
+  const resolvable = []
+  const patchOnly = []
+  for (const row of (Array.isArray(rows) ? rows : [])) {
+    if (typeof row?.name !== 'string' || row.name === '') {
+      // 只改配置的行（`- id: webserver` + `config:`）是**合法的补丁形态**：它在改已存在条目的配置，
+      // 没有 name 可言 —— 真机补丁前 30 行全是这种，判红就是误杀（2026-09-28 真机实测抓到）。
+      if ((row?.keys ?? 0) > 0) { patchOnly.push(row.id ?? null); continue }
+      warnings.push({ code: 'row-without-name', row: row?.id ?? null, line: row?.line ?? null, detail: `行 ${row?.id ?? '?'} 既没有 name 也没有 config`, hint: '补上 name（包名或 file:/// URL），或确认它是配置补丁行' })
+      continue
+    }
+    const name = row.name
+    if (/^file:\/\//iu.test(name)) {
+      if (existsFile === null) continue
+      let present = null
+      try { present = existsFile(name) } catch { present = null }
+      if (present === false) {
+        blockers.push({ code: 'file-target-missing', row: row.id, line: row.line, name, detail: `行 ${row.id} 的 file:// 目标不存在：${name}`, hint: '补齐文件或修正引用（写一行必然加载失败的声明等于把缺陷留给运行期）' })
+      }
+      continue
+    }
+    if (/^\.\.?\//u.test(name) || /^cordis:/iu.test(name)) continue
+    const res = (() => { try { return resolve(name) } catch (error) { return { ok: false, reason: String(error?.message ?? error) } } })()
+    if (res?.ok === true) { resolvable.push(name); continue }
+    const segments = name.split('/')
+    const isSubpath = segments.length > (name.startsWith('@') ? 2 : 1)
+    const entry = {
+      code: isSubpath ? 'subpath-unresolvable' : 'package-unresolvable',
+      row: row.id,
+      line: row.line,
+      name,
+      reason: res?.reason ?? null,
+      ...(() => {
+        const s = isSubpath ? { names: [], source: null } : suggestRenames(name, candidates)
+        return { suggestions: s.names, suggestionSource: s.source }
+      })(),
+      detail: isSubpath
+        ? `行 ${row.id} 的 ${name} 解析不到（父包在，子路径不在？）`
+        : `行 ${row.id} 引用的包 ${name} 在当前框架树里解析不到`,
+      hint: isSubpath
+        ? '该子路径可能已改名/移除 —— 请对照当前框架版本的 exports 修正'
+        : '该包可能已被移除或改名：先确认新包名再改这一行；**在修好之前，依赖它提供的服务的行会永久 waiting**',
+    }
+    if (isSubpath) warnings.push(entry)
+    else if (row.disabled === true) warnings.push({ ...entry, disabled: true })
+    else blockers.push(entry)
+  }
+  return { blockers, warnings, resolvable, patchOnly }
+}
+
+/** 组合入口：文本 + 依赖 → 报告。 */
+function auditPatchText(text, deps = {}) {
+  const rows = parsePatchRows(text)
+  const report = classifyPatchRows(rows, deps)
+  return { rows: rows.length, ...report }
+}
+
+/**
+ * 从行里挑出「随框架版本走」的包名（`@deepseek-ai/*`）并带上行号 ——
+ * 预检要拿它们去**目标版本的 registry** 上核对（真机事故：0.2.0-rc.1 移除了
+ * `@deepseek-ai/dsh-workflow-worker-thread`，而补丁三处仍引用它 → 该行解析失败 →
+ * 隔离组里 workflowEngine 没有提供方 → 老会话 resume 失败）。
+ * 子路径归一成父包（`pkg/sub` → `pkg`）：版本随框架走的是包，不是子路径。
+ */
+function frameworkPackageRows(rows) {
+  const map = new Map()
+  for (const row of (Array.isArray(rows) ? rows : [])) {
+    const name = typeof row?.name === 'string' ? row.name : ''
+    if (!name.startsWith('@deepseek-ai/')) continue
+    if (/^file:\/\//iu.test(name) || /^\.\.?\//u.test(name)) continue
+    const base = name.split('/').slice(0, 2).join('/')
+    if (!map.has(base)) map.set(base, [])
+    map.get(base).push(row.line ?? null)
+  }
+  return [...map.entries()].map(([name, lines]) => ({ name, lines }))
+}
+
+/**
+ * 目标版本可用性判定（纯函数）：`publishedBy` 是 `Map<name, true|false|null>`
+ * （true=目标版本已发布 / false=没有该版本 / null=未知，网络失败或元数据缺失）。
+ * **未知一律不判死**（宁可漏报，也不因为查不动就把用户吓住）——只进 `unknown`。
+ */
+function classifyTargetAvailability(entries, { publishedBy, targetVersion, candidates = [] } = {}) {
+  const missing = []
+  const unknown = []
+  for (const entry of (Array.isArray(entries) ? entries : [])) {
+    const name = entry?.name
+    if (typeof name !== 'string' || name === '') continue
+    const state = publishedBy && typeof publishedBy.get === 'function' ? publishedBy.get(name) : null
+    if (state === true) continue
+    const base = { name, lines: Array.isArray(entry.lines) ? entry.lines : [], targetVersion: targetVersion ?? null }
+    if (state === false) missing.push({ ...base, suggestions: suggestRenames(name, candidates).names })
+    else unknown.push(base)
+  }
+  return { missing, unknown }
+}
+export {
+  KNOWN_RENAMES, auditPatchText, classifyPatchRows, classifyTargetAvailability, frameworkPackageRows,
+  parsePatchRows, scopeOf, suggestRenames, tokensOf, unquote,
+}

package/lib/server/domain/patch.js

@@ -3,9 +3,10 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
+import { frameworkBases, isFrameworkModuleName } from '../infra/framework-root.js'
 import { queuedWrite } from '../infra/fsx.js'
 import { escapeRegExp } from '../infra/mask.js'
-import { resolvePackageJson } from '../infra/paths.js'
+import { makePackageResolver } from '../infra/package-resolve.js'
 
 /** 读取补丁文件并扫描：停用块与 insert 行的 id。 */
 async function readPatchState(patchPath) {
@@ -145,15 +146,39 @@ function parseInsertNames(text) {
 /**
  * 补丁安全自愈（服务永不崩机制）：
  * ① 核心行被误禁用 → 自动移除禁用块恢复；
- * ② 启用态用户 insert 行的模块缺失（如引用未安装包的行）→ 自动禁用（loader 对缺失模块会致命崩溃）。
- * return { healed:[], autoDisabled:[], healedAt } —— healedAt=0 表示本次无修改。
+ * ② 启用态用户 insert 行的模块**确证缺失**（如引用未安装包的行）→ 自动禁用（loader 对缺失模块会致命崩溃）。
+ *
+ * ★ 2026-09-30 改错（真机事故 2026-09-29 01:05:44）：② 过去只用**单基准**
+ *   `resolvePackageJson(name, profileDir)` 判定"缺失"，而框架 0.2.0-rc.1 起 `@deepseek-ai/*` 的实体
+ *   全在 `.pnpm` **内部**那层、profile 顶层只剩旧版残影 → 框架**真存在**的内置包
+ *   `dsh-agent-preset` / `dsh-workflow-ptc` 被判成缺失 → 给它们自动写了 4 个 `disabled: true` 块，
+ *   把用户的 preset-router-spec/standard/react 三条全停掉。
+ *   现在改为**多基准并集**（profile 目录 + 框架运行时根，见 infra/framework-root.js）：
+ *   任一基准能解析即算命中 → 不再误判。
+ *
+ * 语义收紧（三条硬约束）：
+ *   · **确证缺失才禁用**：解析不确定（resolver 报 uncertain / 一个基准都没有 / 解析器抛异常）→ 只报告不写盘；
+ *   · **框架命名空间 `@deepseek-ai/*` 永不自动禁用**：它们是框架自带包（随版本增删由框架自己管），
+ *     写 `disabled: true` 等于用旧判断把新框架的组件停掉 —— 命中一律只报告；
+ *   · **幂等零写盘**：没有真正需要修复的内容时，一个字节都不写（`healedAt=0`），
+ *     且即便算出了新内容也要与原文逐字节比较后才落盘（`GET /state` 每 ≤2min 调一次本函数）。
+ * 写盘失败**如实回报**（`written:false` + `writeError`），绝不静默吞掉。
+ *
+ * return { healed:[], autoDisabled:[], skipped:[], uncertain:[], healedAt, written, writeError }
+ *   healedAt=0 表示本次无修改。
  */
-async function healPatchSafety(patchPath) {
+async function healPatchSafety(patchPath, deps = {}) {
   const profileDir = dirname(patchPath)
+  const readText = deps.readText ?? ((p) => readFile(p, 'utf8'))
+  const writeText = deps.writeText ?? ((p, data) => writeFile(p, data, 'utf8'))
   const { text } = await readPatchState(patchPath)
-  let next = text
   const healed = []
   const autoDisabled = []
+  const skipped = []
+  const uncertain = []
+  let next = text
+
+  // ① 核心行被误禁用 → 恢复（与判据无关，先做）
   for (const id of CORE_PATCH_ROW_IDS) {
     const re = new RegExp(`^- id: ${escapeRegExp(id)}\\s*\\r?\\n {2}disabled: true\\s*\\r?\\n`, 'mu')
     if (re.test(next)) {
@@ -161,23 +186,51 @@ async function healPatchSafety(patchPath) {
       healed.push(id)
     }
   }
+
+  // ② 启用态 insert 行的模块缺失 → 自动禁用（仅在**确证缺失**时）
   if (healed.length === 0) {
     const insertNames = parseInsertNames(next)
-    let require = null
+    const bases = Array.isArray(deps.bases)
+      ? deps.bases.filter((b) => typeof b === 'string' && b !== '')
+      : frameworkBases(deps.baseDir ?? null, profileDir)
+    const resolve = deps.resolve ?? (bases.length > 0 ? makePackageResolver(bases) : null)
     for (const [id, moduleName] of insertNames) {
       if (!moduleName || moduleName.startsWith('cordis:')) continue
-      let ok = true
-      try { ok = resolvePackageJson(moduleName, profileDir) !== null } catch { ok = false }
-      if (!ok && !new RegExp(`^- id: ${escapeRegExp(id)}\\s*\\r?\\n {2}disabled: true\\s*\\r?\\n`, 'mu').test(next)) {
-        next = `${next.trimEnd()}\n- id: ${id}\n  disabled: true\n`
-        autoDisabled.push(id)
-      }
+      const alreadyDisabled = new RegExp(`^- id: ${escapeRegExp(id)}\\s*\\r?\\n {2}disabled: true\\s*\\r?\\n`, 'mu').test(next)
+      if (alreadyDisabled) continue
+      // framework 命名空间：随框架版本走，永不自动禁用（只报告）
+      if (isFrameworkModuleName(moduleName)) { skipped.push({ id, moduleName, reason: 'framework-owned' }); continue }
+      // 没有解析器 / 没有任何基准 → 无法判定，只报告
+      if (resolve === null) { uncertain.push({ id, moduleName, reason: 'no-resolution-base' }); continue }
+      let res = null
+      try { res = resolve(moduleName) } catch (error) { res = { ok: false, uncertain: true, reason: String(error?.message ?? error) } }
+      // 兼容两种 resolver 契约：布尔（旧测试桩）/ `{ ok, uncertain, reason }`（infra/package-resolve.js）
+      const ok = res === true || res?.ok === true
+      if (ok) continue
+      if (res?.uncertain === true) { uncertain.push({ id, moduleName, reason: res?.reason ?? 'uncertain' }); continue }
+      next = `${next.trimEnd()}\n- id: ${id}\n  disabled: true\n`
+      autoDisabled.push(id)
     }
   }
-  if (next !== text) {
-    await writeFile(patchPath, sanitizePatchText(next), 'utf8')
+
+  // ③ 幂等零写盘：没有任何需要修复的内容 / 内容与原文逐字节相同 → 一个字节都不写
+  if (next === text) {
+    return { healed, autoDisabled, skipped, uncertain, healedAt: 0, written: false, writeError: null }
+  }
+  const payload = sanitizePatchText(next)
+  if (payload === text) {
+    return { healed, autoDisabled, skipped, uncertain, healedAt: 0, written: false, writeError: null }
+  }
+  // ④ 写盘失败如实回报（不静默）
+  try {
+    await writeText(patchPath, payload)
+  } catch (error) {
+    return { healed, autoDisabled, skipped, uncertain, healedAt: 0, written: false, writeError: String(error?.message ?? error) }
   }
-  return { healed, autoDisabled, healedAt: next !== text ? Date.now() : 0 }
+  // 读回核实：写盘后重新读一次，只有内容真的落盘才算 healedAt
+  let verified = false
+  try { verified = (await readText(patchPath)) === payload } catch { verified = false }
+  return { healed, autoDisabled, skipped, uncertain, healedAt: Date.now(), written: true, writeError: verified ? null : '写盘后读回内容与期望不一致' }
 }
 
 /** 从「子包版本对齐」记录解析纯包名（如 '@linxin666/dsh-pet@0.2.1（新装）'）。 */

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

@@ -0,0 +1,144 @@
+// L1 · domain —— preset-audit.js（用户预设 ↔ profile 声明行 的跨源对账；0.5.30 加法）
+//
+// 真机背景（2026-09-28）：框架 0.1.7-rc.1 起官方移除了磁盘发现，老会话 resume 靠 profile 补丁里的
+// **声明行**；而预设目录里的 `agent.cordis.yml` 会随后续装配被更新（本机 router-spec 在升级前 1 分钟
+// 被改成 v10），补丁里的行却还是旧的（meta 指向 v1）→ 老会话 resume 到错的模块。
+// 真机证据：`profiles/web/cordis.patch.yml` 指向 `router-bootstrap-v1.mjs`，
+//          而 `router-spec/agent.cordis.yml` 自己写的是 `./router-bootstrap-v10.mjs`。
+//
+// 本模块只做**纯对账**（IO 全注入）：
+//   · parsePresetDeclarations(text)  预设自身声明的 `{ id → 目标 }`（相对引用保留原样）
+//   · auditPresetDeclarations({...}) 与补丁里的 file:/// 行逐条比对，输出四类差异
+//
+// 判据（保守、不猜）：
+//   · **目标按目录归属**匹配 —— 补丁行落在哪个预设目录下就算哪个预设的（router-* 三个预设各有
+//     同名 id `router-bootstrap`，只能靠目录区分，不能靠 id 全局匹配）。
+//   · 只报"能证明不一致"的：id 相同但目标不同（陈旧）、预设里有补丁里没有（缺失）、
+//     补丁里有但预设目录里查无此 id（悬空）、任一目标文件不存在（悬空）。
+//   · 行**显式 disabled** 的，降级为 warning（用户已经关掉它了，不算错，但要看得见）。
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parsePatchRows } from './patch-composition-audit.js'
+
+/** 预设自身声明的模块：`{ id, target, line, disabled }`（只收有 name 的行）。 */
+function parsePresetDeclarations(text) {
+  const lines = String(text ?? '').replace(/\r\n/gu, '\n').split('\n')
+  const out = []
+  let cur = null
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (raw.trim() === '' || /^\s*#/u.test(raw)) continue
+    const item = raw.match(/^(\s*)-\s*id:\s*(\S+)\s*$/u)
+    if (item !== null) {
+      cur = { id: item[2].replace(/^['"]|['"]$/gu, ''), target: null, line: i + 1, disabled: false, indent: item[1].length }
+      out.push(cur)
+      continue
+    }
+    if (cur === null) continue
+    const indent = (raw.match(/^ */u) ?? [''])[0].length
+    if (indent <= cur.indent) continue
+    const name = raw.match(/^\s*name:\s*(.+?)\s*$/u)
+    if (name !== null && cur.target === null) { cur.target = name[1].replace(/^['"]|['"]$/gu, ''); continue }
+    if (/^\s*disabled:\s*true\s*$/u.test(raw)) cur.disabled = true
+  }
+  // 2026-09-28 改错（真机试跑抓到 89 条假"缺失"）：预设里的 `name:` 大量是**包名**（`@deepseek-ai/dsh-persona` 等），
+  // 它们在补丁里也是包名行、不归"按目录归属"的文件匹配管 —— 只有**文件型声明**（相对/绝对路径）
+  // 才会被改写成 `file:///…` 的声明行。这里只收文件型，避免把包名行误判成"声明行缺失"。
+  return out.filter((row) => typeof row.target === 'string' && row.target !== '' && /^(\.\.?[\\/]|[A-Za-z]:[\\/]|file:)/u.test(row.target))
+}
+
+/**
+ * 跨源对账（纯函数，IO 注入）。
+ * 入参：
+ *   · presets: `[{ dir, modules: parsePresetDeclarations(text) }]`
+ *   · patchRows: `[{ id, name, line, disabled }]`（补丁里的行；`name` 可以是 file:/// 也可以是别的）
+ *   · toLocalPath(url) / joinPath(dir, rel) / exists(path) / dirnameOf(path)（可注入，便于离线断言）
+ * 返回 `{ stale, missing, orphan, targetMissing, ok }`。
+ */
+function auditPresetDeclarations({ presets = [], patchRows = [], toLocalPath, joinPath, exists, dirnameOf } = {}) {
+  const stale = []
+  const missing = []
+  const orphan = []
+  const targetMissing = []
+  const patchFileRows = []
+  for (const row of (Array.isArray(patchRows) ? patchRows : [])) {
+    if (row === null || typeof row !== 'object') continue
+    const name = typeof row.name === 'string' ? row.name : ''
+    if (!/^file:\/\//iu.test(name)) continue
+    let local = null
+    try { local = toLocalPath(name) } catch { local = null }
+    if (local === null) continue
+    patchFileRows.push({ id: row.id ?? null, local, line: row.line ?? null, disabled: row.disabled === true })
+  }
+  for (const preset of (Array.isArray(presets) ? presets : [])) {
+    if (preset === null || typeof preset !== 'object' || typeof preset.dir !== 'string') continue
+    const mine = patchFileRows.filter((row) => dirnameOf(row.local) === preset.dir)
+    const declared = Array.isArray(preset.modules) ? preset.modules : []
+    for (const mod of declared) {
+      const target = joinPath(preset.dir, mod.target)
+      const hit = mine.find((row) => row.id === mod.id) ?? null
+      if (hit === null) {
+        missing.push({ preset: preset.dir, id: mod.id, expected: target, declaredAt: mod.line, disabled: mod.disabled === true })
+        continue
+      }
+      if (hit.local !== target) {
+        stale.push({ preset: preset.dir, id: mod.id, declared: target, patchTarget: hit.local, patchLine: hit.line, disabled: hit.disabled })
+        continue
+      }
+      let present = null
+      try { present = exists(target) } catch { present = null }
+      if (present === false) targetMissing.push({ preset: preset.dir, id: mod.id, target, source: 'declaration' })
+    }
+    const ids = new Set(declared.map((m) => m.id))
+    for (const row of mine) {
+      if (ids.has(row.id)) continue
+      orphan.push({ preset: preset.dir, id: row.id, patchTarget: row.local, patchLine: row.line, disabled: row.disabled })
+      let present = null
+      try { present = exists(row.local) } catch { present = null }
+      if (present === false) targetMissing.push({ preset: preset.dir, id: row.id, target: row.local, source: 'patch' })
+    }
+  }
+  const blockers = stale.length + missing.length + orphan.filter((o) => o.disabled !== true).length
+    + targetMissing.length
+  return { stale, missing, orphan, targetMissing, blockers, ok: blockers === 0 }
+}
+
+
+/** IO 收集层（preset-audit 路由与升级前预检共用）：扫磁盘预设 + 读补丁行 → 出报告。 */
+function collectPresetAudit({ presetsRoot, patchPath, deps = {} } = {}) {
+  const {
+    exists = existsSync, readdir = readdirSync, readText = (p) => readFileSync(p, 'utf8'),
+    toLocal = (url) => fileURLToPath(url), joinPath = join, dirOf = dirname,
+  } = deps
+  if (typeof presetsRoot !== 'string' || presetsRoot === '' || !exists(presetsRoot)) {
+    return { ok: false, error: '没有用户预设目录（无需体检）', presetCount: 0, stale: [], missing: [], orphan: [], targetMissing: [], blockers: 0 }
+  }
+  const presets = []
+  try {
+    for (const entry of readdir(presetsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const name = entry.name
+      if (name.startsWith('.') || name.startsWith('_') || name.includes('.bak')) continue
+      const dir = joinPath(presetsRoot, name)
+      const file = joinPath(dir, 'agent.cordis.yml')
+      if (!exists(file)) continue
+      const modules = parsePresetDeclarations(readText(file))
+      if (modules.length > 0) presets.push({ dir, modules })
+    }
+  } catch {}
+  let patchRows = []
+  try { patchRows = parsePatchRows(readText(patchPath)) } catch { patchRows = [] }
+  const report = auditPresetDeclarations({
+    presets,
+    patchRows: patchRows.map((r) => ({ id: r.id, name: r.name, line: r.line, disabled: r.disabled })),
+    toLocalPath: toLocal,
+    joinPath,
+    exists,
+    dirnameOf: dirOf,
+  })
+  return { ok: report.ok, presetCount: presets.length, ...report }
+}
+
+export { auditPresetDeclarations, collectPresetAudit, parsePresetDeclarations }

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

@@ -31,9 +31,10 @@
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { queuedWrite } from '../infra/fsx.js'
 import { validateAgentConfig } from './preset-yaml.js'
+import { migratePluginRowKeys, validatePresetPluginRows } from './preset-rows.js'
 
 /** 声明行指向的模块名（框架侧预设插件，0.1.7-rc.2 起才有）。 */
 const AGENT_PRESET_MODULE = '@deepseek-ai/dsh-agent-preset'
@@ -377,14 +378,40 @@ function buildPresetDeclaration(dir, id, opts = {}) {
   if (verdict.ok !== true) {
     return { ok: false, reason: 'invalid-composition', detail: `agent.cordis.yml 未通过结构校验：${verdict.problems[0] ?? ''}` }
   }
-  const absolutized = absolutizeComposition(composition.text, dir, opts)
+  // ① 插件 config 旧键迁移（**加法**：把框架 schema 根本读不到的旧键改成真键；表见 preset-rows.js）。
+  //    与框架升级那一步**同一张表**（PRESET_CONFIG_KEY_MIGRATIONS），只是判据挂在**写行那一刻** ——
+  //    预设还会经「装预设型子包 / 源码装配 / 手工放文件」落盘，那些路完全不过升级步骤（真机 D-⑦）。
+  //    只动唯一命中、且**该行还没有真键**的那一行；版本判据过不去就一个字都不动。
+  const migrationVersion = opts.frameworkVersion ?? null
+  const migratedKeys = migratePluginRowKeys(composition.text, migrationVersion)
+  // ② 写行**之前**的契约校验：行结构 / `file:///` 目标存在性 / 已确证的框架契约。
+  //    命中即**如实拒绝写入** —— 绝不往用户 profile 里写一行必然「加载失败」的声明。
+  const rowsVerdict = validatePresetPluginRows(migratedKeys.text, {
+    checkFiles: true,
+    presetDir: dir,
+    exists: (localPath) => existsSync(localPath),
+  })
+  if (rowsVerdict.ok !== true) {
+    const first = rowsVerdict.problems[0]
+    return {
+      ok: false,
+      reason: first.code === 'file-target-missing' || first.code === 'file-url-unparsable' || first.code === 'relative-target-missing'
+        ? 'unresolvable-plugin-file'
+        : 'invalid-plugin-rows',
+      detail: `预设的 plugins 行未通过契约校验：${rowsVerdict.problems.map((p) => p.detail).join('；')}`
+        + `（出路：${first.hint}）`,
+      problems: rowsVerdict.problems,
+    }
+  }
+  const absolutized = absolutizeComposition(migratedKeys.text, dir, opts)
   const compositionText = normalizeComposition(absolutized.text)
   const meta = presetDisplayMeta(dir, presetId)
   const config = { id: presetId, name: meta.name, description: meta.description, order: meta.order }
   const rowId = `${PRESET_ROW_PREFIX}${presetId}`
   return {
     ok: true, id: presetId, rowId, dir, config, compositionText,
-    compositionFile: composition.file, rewritten: absolutized.rewritten,
+    compositionFile: composition.file, rewritten: absolutized.rewritten, aliased: migratedKeys.migrated,
+    migrationNote: migratedKeys.skippedReason,
     rowText: renderPresetRow(config, compositionText),
   }
 }
@@ -424,16 +451,17 @@ function declarePresetRow(dir, id, opts = {}) {
   const {
     patchPath = null, profileDir = null, now = Date.now,
     backup = true, verify = true, toFileUrl = pathToFileURL, exists = existsSync,
+    frameworkVersion = null,
   } = opts
-  const built = buildPresetDeclaration(dir, id, { toFileUrl, exists })
+  const built = buildPresetDeclaration(dir, id, { toFileUrl, exists, frameworkVersion })
   if (built.ok !== true) {
-    return { ok: false, status: 'failed', reason: built.reason, detail: built.detail, rowId: null, patchPath: null, backup: null, changed: false, verified: null, rewritten: [], note: built.detail }
+    return { ok: false, status: 'failed', reason: built.reason, detail: built.detail, rowId: null, patchPath: null, backup: null, changed: false, verified: null, rewritten: [], aliased: [], problems: built.problems ?? [], note: built.detail }
   }
   const target = resolvePatchPath({ patchPath, profileDir })
   if (target === null) {
     return {
       ok: false, status: 'skipped', reason: 'no-patch-path', rowId: built.rowId, patchPath: null, backup: null,
-      changed: false, verified: null, rewritten: built.rewritten, config: built.config,
+      changed: false, verified: null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
       note: `未写入声明行：本次调用没有目标 profile（既没有 patchPath 也没有 profileDir）—— `
         + `**文件已就位，但当前框架版本（0.1.7-rc.x 起）需要声明行才能显示**；请在目标 profile 的 cordis.patch.yml 里补一行 preset-${built.id}`,
     }
@@ -443,7 +471,7 @@ function declarePresetRow(dir, id, opts = {}) {
     if (!exists(dirname(target))) {
       return {
         ok: false, status: 'failed', reason: 'no-profile-dir', rowId: built.rowId, patchPath: target, backup: null,
-        changed: false, verified: null, rewritten: built.rewritten, config: built.config,
+        changed: false, verified: null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
         detail: `目标 profile 目录不存在：${dirname(target)}`,
         note: `未写入声明行：目标 profile 目录不存在（${dirname(target)}）—— **文件已就位，但当前框架版本需要声明行才能显示**`,
       }
@@ -456,7 +484,7 @@ function declarePresetRow(dir, id, opts = {}) {
     if (outcome.changed !== true) {
       return {
         ok: true, status: 'unchanged', rowId: built.rowId, patchPath: target, backup: null, changed: false,
-        verified: verify === true ? verifyDeclaredRow(before, built) : null, rewritten: built.rewritten, config: built.config,
+        verified: verify === true ? verifyDeclaredRow(before, built) : null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
         removed: outcome.removed,
         // 与 created/updated 用**同一句**核心文案：幂等重装时用户同样要看懂"它在、重启后可选"，
         // 只多一句"本次未改动任何字节"（诚实交代用户的文件没被动过）。
@@ -471,7 +499,7 @@ function declarePresetRow(dir, id, opts = {}) {
       } catch (error) {
         return {
           ok: false, status: 'failed', reason: 'backup-failed', rowId: built.rowId, patchPath: target, backup: null,
-          changed: false, verified: null, rewritten: built.rewritten, config: built.config,
+          changed: false, verified: null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
           detail: `备份失败（绝不在没备份的情况下改用户补丁）：${error instanceof Error ? error.message : String(error)}`,
           note: '未写入声明行：改前备份失败，已放弃写入（补丁文件一个字节都没动）',
         }
@@ -483,7 +511,7 @@ function declarePresetRow(dir, id, opts = {}) {
     } catch (error) {
       return {
         ok: false, status: 'failed', reason: 'write-failed', rowId: built.rowId, patchPath: target, backup: backupPath,
-        changed: false, verified: null, rewritten: built.rewritten, config: built.config,
+        changed: false, verified: null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
         detail: `写入失败：${error instanceof Error ? error.message : String(error)}`,
         note: `写入声明行失败（${error instanceof Error ? error.message : String(error)}）—— `
           + '**文件已就位，但当前框架版本（0.1.7-rc.x 起）需要声明行才能显示**',
@@ -494,7 +522,7 @@ function declarePresetRow(dir, id, opts = {}) {
     if (readBack === null) {
       return {
         ok: false, status: 'failed', reason: 'readback-failed', rowId: built.rowId, patchPath: target, backup: backupPath,
-        changed: false, verified: null, rewritten: built.rewritten, config: built.config,
+        changed: false, verified: null, rewritten: built.rewritten, aliased: built.aliased, config: built.config,
         detail: '写后读回失败（读不到文件）', note: '写入声明行后读回失败：无法确认是否写成，请人工检查该补丁文件',
       }
     }
@@ -506,10 +534,14 @@ function declarePresetRow(dir, id, opts = {}) {
       reason: ok ? null : 'verify-failed',
       detail: ok ? null : `读回核实不通过：${checked.problems.join('；')}`,
       rowId: built.rowId, patchPath: target, backup: backupPath, changed: true,
-      verified: checked, rewritten: built.rewritten, config: built.config, removed: outcome.removed,
+      verified: checked, rewritten: built.rewritten, aliased: built.aliased, config: built.config, removed: outcome.removed,
       note: ok
         ? presetDeclarationSentence(built.rowId, target)
           + (built.rewritten.length > 0 ? `；composition 里 ${built.rewritten.length} 处相对文件已改写为 file: URL（基准是 profile 目录，不是预设目录）` : '')
+          + (built.aliased.length > 0
+            ? `；composition 里 ${built.aliased.length} 处插件旧键已按框架 schema 迁移（`
+              + `${built.aliased.map((r) => `${r.pkg} 的 ${r.from} → ${r.to}（第 ${r.line} 行）`).join('、')}）`
+            : '')
           + extra
         : `声明行写入后读回核实不通过：${checked.problems.join('；')}（已备份到 ${backupPath}，请人工检查）`,
     }