@noob-stupid/dsh-plugin-console 0.5.27 → 0.5.29

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

@@ -24,6 +24,7 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSy
 import { basename, dirname, join, relative, sep } from 'node:path'
 import { dshHome } from '../infra/paths.js'
 import { validateAgentConfig } from './preset-yaml.js'
+import { declarePresetRow, presetDeclarationNote } from './preset-declare.js'
 
 /** 预设的判别文件（框架发现预设看的就是这个：`<presetsRoot>/<name>/agent.cordis.yml`）。 */
 const PRESET_MARKER_FILES = ['agent.cordis.yml', 'agent.cordis.yaml']
@@ -90,6 +91,78 @@ function verifyWrittenFiles(dest, srcDir, rels) {
   return { ok: mismatched.length === 0, checked: rels.length, mismatched }
 }
 
+/**
+ * 装配后要不要写**声明行**（框架 0.1.7-rc.x 的机制迁移，见 preset-declare.js 顶部）：
+ *   0.1.5 及更早靠"扫 `$DSH_HOME/.agent-presets/` 目录"发现预设；rc.2 起目录发现被彻底移除，
+ *   注册表只认 profile `cordis.patch.yml` 里的 `preset-<id>` 声明行。所以"只把文件铺上去"在
+ *   新框架上等于**用户看不见这个预设**（桌面端「自定义」为空就是这么来的），老会话 resume 还会
+ *   `RemoteError: Unknown agent preset`。
+ *
+ * 语义边界（默认**不动**用户补丁）：
+ *   · 只在显式给了 `patchPath`/`profileDir` 时才写 —— 离线单测、无 profile 场景不凭空造文件；
+ *   · 写前备份、写后读回核实（preset-declare.js 内部做全）；
+ *   · 写不成 → **如实返回失败原因**，调用方据此生成文案，**绝不**再说"新建会话时选择"。
+ * 返回声明结果对象，或 null（没给目标 profile / 调用方显式关闭）。**异步**：写盘走 fsx 的 queuedWrite
+ * 串行队列（与补丁文件的其它写者互斥），所以调用方必须 await —— 忘了 await 会拿到一个 Promise，
+ * `declaration.ok` 恒为 undefined，于是"明明写成了却报没写成"（自测真抓到过这个形状）。
+ */
+async function runPresetDeclaration(srcDir, name, { patchPath = null, profileDir = null, declare = null, now = Date.now } = {}) {
+  if (typeof declare === 'function') {
+    try { return await declare(srcDir, name) } catch (error) {
+      return { ok: false, status: 'failed', reason: 'declare-threw', detail: error instanceof Error ? error.message : String(error), rowId: null, patchPath: null, backup: null, changed: false, verified: null, rewritten: [] }
+    }
+  }
+  if (patchPath === null && profileDir === null) return null
+  try {
+    return await declarePresetRow(srcDir, name, { patchPath, profileDir, now })
+  } catch (error) {
+    return {
+      ok: false, status: 'failed', reason: 'declare-threw', rowId: null, patchPath: patchPath ?? null, backup: null,
+      changed: false, verified: null, rewritten: [],
+      detail: `写声明行时异常：${error instanceof Error ? error.message : String(error)}`,
+    }
+  }
+}
+
+/** 面板文案里"这个预设到底能不能被看见"的那一句（**按实际结果生成**，绝不无脑说"新建会话时选择"）。
+ *  `null`（调用方没给目标 profile → 根本没尝试声明）也必须**明说**：文件已就位、但当前框架版本
+ *  需要声明行才显示，并给出出路 —— 这正是旧文案"新建会话时选择"撒谎的那一格。 */
+function declarationClause(declaration) {
+  if (declaration === null || declaration === undefined) {
+    return '；**文件已就位，但当前框架版本（0.1.7-rc.x 起预设改为声明行）需要声明行才能在界面上显示** —— '
+      + '本次没有目标 profile 可写，请在目标 profile 的 cordis.patch.yml 里补 `preset-<预设 id>` 声明行'
+  }
+  if (declaration.ok === true) return `；${presetDeclarationNote(declaration)}`
+  return `；⚠️ ${presetDeclarationNote(declaration)}`
+}
+
+/** 多个预设装配报告 → 一句话（**成功逐条点名、失败如实报因**，两类都在，绝不只报好消息）。
+ *  为什么不是"有一个成功就整体乐观"：一次装配可能有 3 个预设，2 个声明成功、1 个写失败 ——
+ *  用户必须知道**哪个**看不见，否则他会对着"已装配"这三个字找不到那一个预设。 */
+function declarationClauseForReports(reports) {
+  const list = (Array.isArray(reports) ? reports : []).filter((r) => r !== null && typeof r === 'object')
+  const decls = list.map((r) => r.declaration).filter((d) => d !== null && d !== undefined)
+  if (decls.length === 0) {
+    return '；**文件已就位，但当前框架版本（0.1.7-rc.x 起预设改为声明行）需要声明行才能在界面上显示** —— '
+      + '本次没有目标 profile 可写，请在目标 profile 的 cordis.patch.yml 里补 `preset-<预设 id>` 声明行'
+  }
+  const okDecls = decls.filter((d) => d.ok === true)
+  const badDecls = decls.filter((d) => d.ok !== true)
+  const parts = []
+  if (okDecls.length > 0) {
+    const rows = okDecls.map((d) => d.rowId).filter((r) => typeof r === 'string' && r !== '')
+    const unchanged = okDecls.filter((d) => d.changed === false).length
+    parts.push(`已声明为预设行 ${rows.join('、')}`
+      + `${unchanged > 0 ? `（其中 ${unchanged} 个此前已声明、内容一致未改动）` : ''}`
+      + `${typeof okDecls[0].patchPath === 'string' ? `（写入 ${okDecls[0].patchPath}）` : ''}；**重启实例后**在新会话可选`)
+  }
+  if (badDecls.length > 0) {
+    parts.push(`${badDecls.length} 个预设**未写成声明行**（${badDecls.map((d) => d.detail ?? d.reason ?? '未知原因').join('；')}）`
+      + '—— 文件已就位，但当前框架版本需要声明行才能显示')
+  }
+  return `；${parts.join('；')}`
+}
+
 /**
  * 装配一个预设到 `<presetsRoot>/<name>`（**唯一实现**）。
  *
@@ -103,9 +176,11 @@ function verifyWrittenFiles(dest, srcDir, rels) {
  * 不通过 → **这个文件不写**，进 `skippedInvalid` 并如实报告（其它文件照常）。
  *
  * 返回 { ok, name, dest, backup, mode, added, skipped, overwritten, identical, conflicts,
- *        skippedInvalid, verified, verifiedConfig, hashes, bytes, files, note, error }。
+ *        skippedInvalid, verified, verifiedConfig, hashes, bytes, files, declaration, note, error }。
+ * `declaration` = 声明行结果（见 preset-declare.js）；**没给目标 profile 时为 null**（那时 note 会
+ * 明说"文件已就位，但当前框架版本需要声明行才能显示"，绝不宣称"新建会话时选择"）。
  */
-function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, overwrite = false, verify = true } = {}) {
+async function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, overwrite = false, verify = true, patchPath = null, profileDir = null, declare = null } = {}) {
   const root = presetsRoot ?? join(dshHome(), '.agent-presets')
   const presetName = String(name ?? basename(srcDir)).trim()
   if (presetName === '' || presetName === '.' || /[\\/]/u.test(presetName)) {
@@ -200,6 +275,13 @@ function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, over
     : { ok: false, problems: ['目标目录里没有 agent.cordis.yml/.yaml'] }
   const mode = overwrite === true ? 'overwrite' : 'add-only'
 
+  // ── 声明行（**框架 0.1.7-rc.x 的机制迁移**的落点）──────────────────────────────────────
+  // 判据：磁盘上的预设配置合法（`destConfigValid.ok`）才声明 —— 声明一个挂不起来的预设会让
+  // 用户在新会话里选中它然后炸掉，比"不声明"更糟。写盘/备份/读回核实全在 preset-declare.js。
+  const declaration = destConfigValid.ok === true
+    ? await runPresetDeclaration(srcDir, presetName, { patchPath, profileDir, declare, now })
+    : null
+
   const noteParts = []
   if (existed !== true) {
     noteParts.push(`预设 ${presetName} 已装配到 ${dest}（新增 ${added.length} 个文件）`)
@@ -215,6 +297,10 @@ function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, over
     }
     if (identical.length > 0) noteParts.push(`另有 ${identical.length} 个文件与你手上的内容一致，未改动`)
   }
+  // 「这个预设到底能不能被看见」必须**按实际结果**说（旧文案无条件说"新建会话时选择"，
+  // 在 rc.2 上是一句谎话：没有声明行的预设根本不会出现在选择器里）
+  const declNote = declarationClause(declaration)
+  if (declNote !== '') noteParts.push(declNote.replace(/^；/u, ''))
   if (skippedInvalid.length > 0) {
     noteParts.push(`${skippedInvalid.length} 个预设配置文件**未通过结构校验、已跳过未写入**：`
       + skippedInvalid.map((s) => `${s.rel}（${s.problems[0]}）`).join('、'))
@@ -240,6 +326,7 @@ function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, over
     skippedInvalid,
     verified,
     verifiedConfig: destConfigValid,
+    declaration,
     hashes: written.map((rel) => ({ rel, sha256: sha256Of(readFileSync(join(dest, ...rel.split('/')))) })),
     bytes,
     files: srcFiles.map((f) => f.rel),
@@ -355,6 +442,7 @@ function presetJobView(job) {
 
 export {
   PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, PRESET_SOURCE_RECORD_LIMIT,
-  assemblePreset, copyTreeStrict, listTreeFiles, presetJobView, presetSourceOf, presetSourcesFile,
-  readPresetSources, recordPresetSource, sha256Of, suggestedOverwritePresetAction, uniqueBackupPath, verifyWrittenFiles,
+  assemblePreset, copyTreeStrict, declarationClause, declarationClauseForReports, listTreeFiles,
+  presetJobView, presetSourceOf, presetSourcesFile, readPresetSources, recordPresetSource,
+  runPresetDeclaration, sha256Of, suggestedOverwritePresetAction, uniqueBackupPath, verifyWrittenFiles,
 }

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/preset-source.js

@@ -23,11 +23,12 @@ import { basename, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { gitCloneRepo, runGitArgs } from './repoland.js'
 import { noteChannel } from './git-channel.js'
+import { readPresetManifest } from './preset-declare.js'
 import { evaluateSourceChannel } from './repo-size.js'
 import { disposeDir } from '../infra/fsx.js'
 import { dshHome } from '../infra/paths.js'
 import {
-  PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, assemblePreset, listTreeFiles,
+  PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, assemblePreset, declarationClauseForReports, listTreeFiles,
   presetSourceOf, recordPresetSource, suggestedOverwritePresetAction,
 } from './preset-install.js'
 
@@ -71,19 +72,10 @@ function looksLikePresetPackageName(name) {
   return /(?:^|[-_/])(?:router|preset)(?:[-_/]|$)/iu.test(String(name ?? '').trim())
 }
 
-/** 读预设清单（preset.yml 的 name/description/order；读不到返回 null，不抛）。 */
-function readPresetManifest(dir) {
-  try {
-    const text = readFileSync(join(dir, PRESET_MANIFEST_FILE), 'utf8')
-    const pick = (key) => {
-      const m = text.match(new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, 'mu'))
-      return m === null ? null : m[1].trim().replace(/^["']|["']$/gu, '')
-    }
-    return { name: pick('name'), description: pick('description'), order: pick('order') }
-  } catch {
-    return null
-  }
-}
+/** 读预设清单（preset.yml 的 name/description/order；读不到返回 null，不抛）。
+ *  实现已搬到 preset-declare.js（那里也要用它，且依赖方向必须单向 preset-source → preset-declare）——
+ *  这里 re-export，既有调用方与测试一个字都不用改。 */
+export { readPresetManifest } from './preset-declare.js'
 
 /** 跑一条 git 命令并取回 stdout（ls-tree/show 要的就是输出）。仍然走 repoland 的 runGitArgs：
  * 那边已经把停滞判据 + kill-tree + wait-for-exit 做完了，这里只转发（`stdout` 由 runGitArgs 采集）。 */
@@ -214,13 +206,19 @@ async function tryPresetSourceChannel({ job, name, source = 'github', limit = 4,
       return { handled: true, installed: false, error: new Error(`预设型子包 ${candidateName}：${why}`), presets: [] }
     }
     const presetsRoot = deps.presetsRoot ?? join(dshHome(), '.agent-presets')
+    // 目标 profile 的补丁文件（可选）：给了就**同时写声明行** —— 框架 0.1.7-rc.x 起预设不再靠目录
+    // 发现，只落文件不写声明行 = 用户看不见（见 preset-declare.js 顶部）。安装路径由 install-job.js
+    // 传 findPatchPath(ports)，线上一律非空；离线单测不传 → 不写、且 note 如实说明。
+    const patchPath = typeof deps.patchPath === 'string' && deps.patchPath !== '' ? deps.patchPath : null
     const reports = []
     const skipped = Math.max(0, presets.length - limit)
     for (const p of presets.slice(0, limit)) {
       // eslint-disable-next-line no-await-in-loop
       // overwrite **永不**在这里为真：安装路径必须走"只补不覆盖"的默认语义。
       // 覆盖只能由用户显式点「覆盖该预设」→ 白名单动作 overwrite-preset 触发（见 plugin-actions.js）。
-      const report = assemblePreset(p, basename(p), { presetsRoot, ...(deps.now === undefined ? {} : { now: deps.now }) })
+      const report = await assemblePreset(p, basename(p), {
+        presetsRoot, patchPath, ...(deps.now === undefined ? {} : { now: deps.now }),
+      })
       reports.push({ ...report, manifest: readPresetManifest(p), sparse: fetched.sparse === true, subdir: fetched.subdir })
     }
     const failed = reports.filter((r) => r.ok !== true)
@@ -235,6 +233,13 @@ async function tryPresetSourceChannel({ job, name, source = 'github', limit = 4,
         skipped: Array.isArray(r.skipped) ? r.skipped : [],
         skippedInvalid: Array.isArray(r.skippedInvalid) ? r.skippedInvalid : [],
         verified: r.verified === null || r.verified === undefined ? null : r.verified.ok === true,
+        // 声明行结果（0.5.28 加法）：面板据此显示"已声明为 preset-x（重启实例后可选）"，
+        // 或如实显示"文件已就位但没写成声明行" —— 结构字段 + note 两处都下发，绝不只在一处叙述。
+        declaration: r.declaration === null || r.declaration === undefined ? null : {
+          ok: r.declaration.ok === true, status: r.declaration.status ?? null, rowId: r.declaration.rowId ?? null,
+          patchPath: r.declaration.patchPath ?? null, backup: r.declaration.backup ?? null,
+          reason: r.declaration.reason ?? null, detail: r.declaration.detail ?? null,
+        },
       }))
       job.presetSource = { repo, subdir: fetched.subdir, sparse: fetched.sparse === true, downgraded: fetched.downgraded === true, root: fetched.root }
       // 源码出处落盘：`overwrite-preset` 动作据此**重新取源码**（临时 clone 目录在 finally 里已清理，
@@ -264,7 +269,8 @@ async function tryPresetSourceChannel({ job, name, source = 'github', limit = 4,
     const skippedFiles = reports.reduce((sum, r) => sum + (r.skipped?.length ?? 0), 0)
     const invalidFiles = reports.reduce((sum, r) => sum + (r.skippedInvalid?.length ?? 0), 0)
     const backedUp = reports.filter((r) => r.ok === true && typeof r.backup === 'string' && r.backup !== '')
-    const note = `预设已装配：${okNames.join('、')}（落盘 ${presetsRoot}；**新建会话时选择**）`
+    const note = `预设已装配：${okNames.join('、')}（落盘 ${presetsRoot}）`
+      + declarationClauseForReports(reports)
       + (fetched.sparse === true ? '；源码用稀疏取源码（--filter=blob:none --sparse + sparse-checkout set），只取该子包目录' : '')
       + (skipped > 0 ? `；该仓库还有 ${skipped} 个预设本次未装配（单次上限 ${limit} 个）` : '')
       // 默认语义必须在面板上说清（用户要先知道"你的文件没被动过"，才谈得上要不要覆盖）
@@ -343,7 +349,10 @@ async function overwritePreset({ presetName, deps = {} } = {}) {
       return { ok: false, status: 200, name: raw, repo, error: `仓库 ${repo} 的 ${fetched.subdir} 里没有找到预设目录` }
     }
     // 覆盖的永远是**用户点名的那一个**名字（不是源目录的 basename）：用户点的是哪个就改哪个
-    const report = assemblePreset(pick, raw, { presetsRoot, overwrite: true, ...(deps.now === undefined ? {} : { now: deps.now }) })
+    const patchPath = typeof deps.patchPath === 'string' && deps.patchPath !== '' ? deps.patchPath : null
+    const report = await assemblePreset(pick, raw, {
+      presetsRoot, overwrite: true, patchPath, ...(deps.now === undefined ? {} : { now: deps.now }),
+    })
     if (report.ok !== true) {
       return { ok: false, status: 200, name: raw, repo, backup: report.backup ?? null, error: report.error ?? '覆盖失败（文件未改动）', report }
     }
@@ -367,7 +376,7 @@ async function overwritePreset({ presetName, deps = {} } = {}) {
 
 export {
   PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, GIT_READ_TIMEOUT_MS,
-  findPresetDirs, isPresetDir, looksLikePresetPackageName, readPresetManifest, listTreeFiles,
+  findPresetDirs, isPresetDir, looksLikePresetPackageName, listTreeFiles,
   assemblePreset, locateSubpackageViaGit, fetchPresetSource, gitCapture, tryPresetSourceChannel,
   overwritePreset,
 }

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/domain/suite.js

@@ -282,14 +282,20 @@ async function runSuiteInstallJob(job, ports, deps = {}) {
       // 用户手上的同名预设；现在改为"先整目录备份、再逐文件合并"，并把备份路径与覆盖清单写进报告。
       const presets = findPresetDirs(subDir, 2)
       for (const p of presets) {
-        const assembled = assemblePreset(p, basename(p))
+        // 声明行同源（0.5.28 加法）：目标 profile 就是本次套装的 profileDir —— 框架 0.1.7-rc.x 起
+        // 预设必须作为声明行出现在 cordis.patch.yml 里，只铺文件用户看不见（见 preset-declare.js 顶部）。
+        const assembled = await assemblePreset(p, basename(p), { profileDir })
         report.push({
           component: sub.name,
           type: 'preset',
           ok: assembled.ok === true,
-          note: assembled.ok === true ? `${assembled.note}（新建会话时选择）` : `预设装配失败：${assembled.error}`,
+          // 文案按**实际声明结果**生成（旧文案无条件说"新建会话时选择"，在 rc.2 上是一句谎话）
+          note: assembled.ok === true
+            ? assembled.note
+            : `预设装配失败：${assembled.error}`,
           presetPath: assembled.dest ?? null,
           backup: assembled.backup ?? null,
+          declaration: assembled.declaration ?? null,
         })
         if (assembled.ok === true) handled = true
       }
@@ -320,7 +326,19 @@ async function runSuiteInstallJob(job, ports, deps = {}) {
     const okCount = report.filter((r) => r.ok).length
     const failCount = report.filter((r) => !r.ok).length
     const bundleCount = report.filter((r) => r.type === 'bundle' && r.ok).length
-    job.suiteNote = `套装安装完成：${okCount} 个组件成功${failCount > 0 ? `，${failCount} 个失败（详见报告）` : ''}${bundleCount > 0 ? '。bundle 组件需重启服务生效' : ''}；预设需新建会话时选择。`
+    // 预设的可见性按**实际声明结果**说（0.5.28 改错）：框架 0.1.7-rc.x 起预设不再靠目录发现，
+    // 只有落进 profile 补丁的 `preset-<id>` 声明行才会出现在选择器里 —— 旧文案"预设需新建会话时选择"
+    // 对新框架是错的（没有声明行时新建多少次会话都选不到）。有声明失败的条目就点名。
+    const presetRows = report.filter((r) => r.type === 'preset')
+    const presetDeclared = presetRows.filter((r) => r.declaration?.ok === true).length
+    const presetUndeclared = presetRows.filter((r) => r.ok === true && r.declaration?.ok !== true).length
+    const presetFailed = presetRows.filter((r) => !r.ok).length
+    job.suiteNote = `套装安装完成：${okCount} 个组件成功${failCount > 0 ? `，${failCount} 个失败（详见报告）` : ''}${bundleCount > 0 ? '。bundle 组件需重启服务生效' : ''}`
+      + (presetDeclared > 0 ? `；${presetDeclared} 个预设已声明为声明行（重启实例后在新会话可选）` : '')
+      + (presetUndeclared > 0
+        ? `；⚠️ ${presetUndeclared} 个预设**文件已就位，但当前框架版本（0.1.7-rc.x 起预设改为声明行）需要声明行才能在界面上显示**`
+        : '')
+      + (presetFailed > 0 ? `；${presetFailed} 个预设装配失败（详见报告）` : '')
   } catch (error) {
     job.status = 'failed'
     job.error = error instanceof Error ? error.message : String(error)

package/lib/server/routes/components.js

@@ -109,7 +109,9 @@ async function routeRepoLandConfig(req, res, rc) {
   const body = rc.body
     const dir = typeof body.dir === 'string' ? body.dir.trim() : ''
     if (dir === '' || !/^[A-Za-z]:[\\/]/.test(dir) && !/^\\\\/.test(dir)) {
-      sendError(res, 400, '保存路径不合法：请提供绝对路径（如 D:\\dsh\\repos）')
+      // 0.5.28 改错：示例原本写成本机真实目录 `D:\dsh\repos`（把开发者的目录当成了通用示例）。
+      // 换成中性的任意绝对路径示例，并说明"任意绝对路径"——判据是形状（盘符/UNC），不是具体目录。
+      sendError(res, 400, '保存路径不合法：请提供绝对路径（任意绝对路径均可，如 C:\\repos 或 \\\\server\\share\\repos）')
       return
     }
     try {

package/lib/server/routes/framework-preflight.js

@@ -23,9 +23,18 @@ const REGISTRY = 'https://registry.npmmirror.com'
 
 /** 预检的两个扫描面：用户预设目录 + profile 内每个已装插件包。
  *  框架自带包（解析到 profile 之外，即 npx 缓存里的 @deepseek-ai/*）标成 kind='framework'：
- *  仍然扫（能暴露框架自身的契约不一致），但**只报告不改**——改它等于污染框架安装树。 */
+ *  仍然扫（能暴露框架自身的契约不一致），但**只报告不改**——改它等于污染框架安装树。
+ *
+ *  ★ 2026-09-27 改错（真 bug）：用户预设目录写成了 `join(dshHome(), 'agent-presets')` —— **少一个点**。
+ *  框架的目录是 `<DSH_HOME>/.agent-presets`（旧 discovery 的 `USER_PRESET_DIR = '.agent-presets'`），
+ *  所以这一路**一直指向一个不存在的目录**：静默扫到 0 个文件，预设里的 V3 生产方从来没被预检看见
+ *  （升级前"0 blocker"的结论因此是**假绿**）。现在由 `userPresetsRoot()` 单点推导，配断言钉死。 */
+function userPresetsRoot(home = undefined) {
+  return join(home ?? dshHome(), '.agent-presets')
+}
+
 function preflightRoots(ports, profileDir) {
-  const roots = [{ root: join(dshHome(), 'agent-presets'), kind: 'preset' }]
+  const roots = [{ root: userPresetsRoot(), kind: 'preset' }]
   // 控制台自身排除在外：它是工具、不是会话消息生产方，而它的报错文案/文档里本身就含
   // `kind: 'plugin'`、`.volatile(` 这类字样 —— 发版门槛自扫时正是这些字串报出了无意义条目。
   let selfName = null
@@ -161,4 +170,4 @@ async function routeFrameworkPreflightPatch(req, res, rc) {
   })
 }
 
-export { routeFrameworkPreflight, routeFrameworkPreflightPatch, preflightRoots, resolveTargetVersion, resolveCurrentVersion }
+export { routeFrameworkPreflight, routeFrameworkPreflightPatch, preflightRoots, resolveTargetVersion, resolveCurrentVersion, userPresetsRoot }