@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/plugin-lifecycle.mjs

@@ -0,0 +1,128 @@
+/**
+ * 插件生命周期名单（**唯一真源**，profile-doctor 与 argent-upgrade 共用）。
+ *
+ * 为什么要有这份名单：profile 组合是"多来源手工拼装"的（bundles + cordis.patch.yml +
+ * dependencies + node_modules），任何一处漂移都不立刻报错，只在"下次重启"爆。
+ * 两处知识必须一致，否则 doctor 报红、升级器却以为正常（2026-09-28 客户机 P3 实测）。
+ * 组合目标本身在 plugin-composition.json（连 Python 预检也读它）。
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { npmNameOf } from './plugin-packages.mjs'
+
+/**
+ * 组合目标（**唯一真源** = scripts/plugin-composition.json，JS 升级器与 Python 预检共用）。
+ * 2026-09-28 的教训：预检硬编码「期望 argent-flow」，而升级目标组合里没有它
+ * ⇒ 预检报红、升级器却以为正常。故两边都从这里读。
+ */
+const COMPOSITION_FILE = join(dirname(fileURLToPath(import.meta.url)), '..', 'plugin-composition.json')
+
+/** @returns {{ [type: string]: { patch: string[], bundles: string[] } }} */
+export function targetCombos() {
+  const raw = JSON.parse(readFileSync(COMPOSITION_FILE, 'utf8'))
+  const out = {}
+  for (const [k, v] of Object.entries(raw)) {
+    if (k.startsWith('_')) continue
+    out[k] = { patch: [...(v.patch || [])], bundles: [...(v.bundles || [])] }
+  }
+  return out
+}
+
+/** 某个实例类型要装进 profile 的全部插件（patch 行 + bundle 层）。 */
+export function comboPlugins(type) {
+  const c = targetCombos()[type]
+  if (!c) throw new Error(`未知实例类型 ${type}（见 scripts/plugin-composition.json）`)
+  return [...c.patch, ...c.bundles]
+}
+
+/**
+ * 组合条目 → `cordis.patch.yml` 的行（`{id, name}`）。
+ *
+ * W9（2026-10-12）：`name:` 是 **npm 包名**（`@whyshu/argent-core`），`id:` 仍是裸 id。
+ * 两者分开是插件的结构性事实（口径在 `scripts/lib/plugin-packages.mjs`）；
+ * ⛔ 未知插件（历史/试验行）原样回裸名，⛔ **不**善意补 scope。
+ * @param {string} type 实例类型
+ * @returns {Array<{id:string, name:string}>}
+ */
+export function compositionRows(type) {
+  const c = targetCombos()[type]
+  if (!c) throw new Error(`未知实例类型 ${type}（见 scripts/plugin-composition.json）`)
+  return c.patch.map((id) => ({ id, name: npmNameOf(id) || id }))
+}
+
+/** 插件 id → 组合行的规范 `name:`（npm 名；未知 id ⇒ 原样回）。 */
+export function pluginRowName(id) {
+  return npmNameOf(id) || String(id)
+}
+
+/**
+ * 已迁到 **bundle 层** 的插件：出现在 `cordis.patch.yml` 的 insert 行里即为重复挂载
+ * （加载器报 `duplicate loader entry id` ⇒ dsh web 启动即失败 ⇒ KeepAlive crash loop）。
+ * 它们必须登记在 profile `package.json` 的 `dsh.profile.bundles` 里。
+ */
+export const BUNDLE_LAYER_PLUGINS = [...new Set(Object.values(targetCombos()).flatMap((c) => c.bundles))]
+
+/**
+ * bundle 层名单的 `{id, name}` 配对（**唯一**出口；⛔ 不许在调用方再拼一次名字）。
+ *
+ * W9（2026-10-13）：`dsh.profile.bundles` 的条目是**包名**（`@whyshu/argent-skin`），不是 id。
+ * 名单本身（`plugin-composition.json#*.bundles`）用 id 声明"哪些插件走 bundle 层"，
+ * 名字一律经 `plugin-packages.mjs` 求 —— 两件事分开，是本模块的结构性事实。
+ * 存量机器上是裸名条目（W9 漏迁的第三处）⇒ 读侧用
+ * `plugin-packages.mjs#migrateBundleNames()` 迁，⛔ 不要在这里另写一份映射。
+ */
+export function bundleLayerRows() {
+  return BUNDLE_LAYER_PLUGINS.map((id) => ({ id, name: pluginRowName(id) }))
+}
+
+/** 迁移原因（doctor 报告用）。 */
+export const BUNDLE_LAYER_REASON = '已改为 bundle 层插件（登记在 dsh.profile.bundles）'
+
+/** 必须存在的 patch 行（缺失即补）。 */
+export const REQUIRED_PATCH_ROWS = ['argent-core']
+
+/**
+ * 组合层面退役的插件：patch 层出现这些行就摘掉。判据是「**source 已从仓库删除**或已被
+ * 原生 dsh 覆盖」——不是「不在目标组合里」（后者会误伤活着的插件）。
+ * 2026-09-28 补 kanban/notify/drive：P4-4c 退场时只改了组合生成器，客户机 patch 层
+ * 仍留着 insert 行 ⇒ doctor 报 row-pkg-missing（包根本没装）⇒ 升级卡在体检门禁上。
+ */
+export const RETIRED_PATCH_ROWS = {
+  'argent-files': '已废弃——原生 dsh 已有文件引用（dsh-file-reference / -local / sidebar-files）',
+  'argent-instances': '已退役（P4-4c：实例管理并入 argent-core）',
+  'argent-instances-local': '已退役（P4-4c：实例管理并入 argent-core）',
+  'argent-tool-instances': '已退役（P4-4c：实例管理并入 argent-core）',
+  'argent-packs': '已退役（P4-4c：能力包改由 scripts/ 与 install.json 管理）',
+  'argent-ml': '已退出常驻组合行——按需安装的独立插件（源码保留在 plugins/argent-ml）',
+  'argent-kanban': '已退役（P4-4c：看板退场）',
+  'argent-notify': '已退役（P4-4c：通知并入网关）',
+  'argent-drive': '已退役（P4-4c：云盘能力退场）',
+}
+
+/**
+ * 允许**保留源码**的退役插件：这些名字仍出现在 `plugins/` 下（按需安装 / 曾以 tgz 交付），
+ * 但**不得**出现在任何 profile 的常驻组合行里。
+ * 与「源码已从仓库删除」的退役（kanban/notify/drive…）区分开：字段一个样，
+ * 不变量不一样，混在一起会让门禁假红（2026-09-28 实测：argent-ml 就是这么被抓出来的）。
+ */
+export const LEGACY_PLUGIN_SOURCES = ['argent-ml']
+
+/** 生成 { id: reason } 副本（doctor 用；避免调用方直接改到共享对象）。 */
+export function retiredRowMap() {
+  return { ...RETIRED_PATCH_ROWS }
+}
+
+/** 退役插件 id 集合（升级器摘行用）。 */
+export function retiredRowIds() {
+  return new Set(Object.keys(RETIRED_PATCH_ROWS))
+}
+
+/**
+ * 生成 { id: reason } 形态，供 doctor 的 BUNDLE_MIGRATED 直接使用。
+ */
+export function bundleLayerMap() {
+  const out = {}
+  for (const id of BUNDLE_LAYER_PLUGINS) out[id] = BUNDLE_LAYER_REASON
+  return out
+}

package/engine/scripts/lib/plugin-packages.mjs

@@ -0,0 +1,332 @@
+/**
+ * Argent 插件的 **id ↔ npm 包名** 唯一真源（W9 · 2026-10-12）。
+ *
+ * ## 为什么要有这份名单
+ * W9 把插件从"只靠 `file:` 指向客户机克隆"改成"**发 npm**"（`@whyshu/argent-*`，
+ * 用户名 scope；见 `docs/Argent-插件化评估与实施计划.md` §6 决策点 4）。于是**同一个插件**
+ * 在一个仓库里有两个名字，且**两个名字都必须被接受**：
+ *
+ * | 名字 | 谁在用 | 会不会变 |
+ * |---|---|---|
+ * | **id**（`argent-core`） | 目录名 `plugins/argent-core`、组合条目 `- id:`、`plugin-composition.json`、`agents/catalog.json#plugins`、退役名单、日志前缀 | ⛔ **不变**（改成 scoped 会让存量 profile 的组合行、台账、catalog 一起漂） |
+ * | **npm 名**（`@whyshu/argent-core`） | `package.json#name`、profile `dependencies` 的键、`cordis.patch.yml` 的 `name:`、`dsh plugin add <spec>` | 本批**新增** |
+ *
+ * ⚠️ profile `dependencies` 的**键**由 `file:` 目标自己的 `package.json#name` 决定
+ * （实测 pnpm 11：`pnpm add file:<dir>` 用 target 的 name 建键，**不是**目录名）⇒ 一旦
+ * `package.json#name` 变成 scoped，`file:` 安装**也会**落成 scoped 键 ⇒ 两态收敛到同一个名字。
+ * 这条是本设计的前提，也是"文件名/目录名不动、只动包名"能成立的原因。
+ *
+ * ## 过渡兼容（⛔ 不许把存量客户弄坏）
+ * 存量 profile 里是 `dependencies['argent-core'] = file:…` + 组合行 `name: 'argent-core'` +
+ * `dsh.profile.bundles` 里的裸名条目 `'argent-skin'`（第三处，2026-10-13 真机才补上）。
+ * 本模块提供**双向解析**（`pluginIdOf` / `npmNameOf` 都同时认两个名字）与**幂等迁移**
+ * （`migrateDependencyKeys` / `migrateBundleNames` 在本文件；`migratePluginRowNames` 见 `patch-compose.mjs`）：
+ *   · 安装器**读**存量状态时两个名字都认（⛔ 不把旧裸名当成"未知/悬挂"）；
+ *   · 安装器**写**新状态时一律写 npm 名；
+ *   · 迁移**幂等**（第二次跑零改动）且**有备份 + 回滚**（见 `install-argent.mjs`）。
+ *
+ * ## 纪律
+ * 纯 node 内建（`node:fs` / `node:path`），零第三方、零宿主 import ⇒ 与
+ * `scripts/lib/dsh-versions.mjs` 同档（可被 L1/L2 双侧安全复用）。
+ * ⛔ **不要**在这里加"哪些插件该装"的判据 —— 那是 `plugin-composition.json` /
+ * `agents/catalog.json` 的事，本文件只回答"这个插件的包名是什么、这个名字是谁"。
+ */
+import { readFileSync } from 'node:fs'
+
+/** npm 用户名 scope（npm 账号名 = `whyshu`；⛔ **不是组织**，见计划 §6 决策点 4）。 */
+export const NPM_SCOPE = '@whyshu'
+
+/**
+ * 插件清单（**唯一真源**）。新增插件在这里加一行即可 ——
+ * 安装器 / 组合渲染 / 迁移 / 回归用例都从这里取，⛔ 不许在别处再写一份字面量。
+ *
+ * `id`   = 目录名（`plugins/<id>`）、组合条目 id、日志前缀；
+ * `npm`  = npm 包名（`package.json#name`、`dependencies` 键、组合行 `name:`）。
+ */
+export const PLUGIN_PACKAGES = [
+  { id: 'argent-core', npm: `${NPM_SCOPE}/argent-core` },
+  { id: 'argent-skin', npm: `${NPM_SCOPE}/argent-skin` },
+  { id: 'argent-presets', npm: `${NPM_SCOPE}/argent-presets` },
+  { id: 'argent-flow', npm: `${NPM_SCOPE}/argent-flow` },
+  { id: 'argent-gateway', npm: `${NPM_SCOPE}/argent-gateway` },
+  { id: 'argent-ml', npm: `${NPM_SCOPE}/argent-ml` },
+  // W2（0.6.0）：**壳 bundle** —— 不是第 7 个「代码插件」，而是一次装配 core+skin+presets 的 **bundle**
+  // （零 `src/`、零宿主 import ⇒ `peerDependencies` 结构性为空，见 `plugin-peer-coverage` 的豁免登记表）。
+  // 登记在这里的理由与其它插件**同一条**：
+  //   · 安装器要按**官方路径**装它（`@whyshu/argent-shell@<版本>`）与 `file:` 回退
+  //     （`file:<克隆>/plugins/argent-shell`），两种规格都由本文件产出（⛔ 不再在安装器里拼第二份字面量）；
+  //   · 发布流水线（`scripts/npm-publish-argent.mjs --only argent-shell`）按本清单认包
+  //     —— 不登记 ⇒ Lead 用**官方**发布脚本发不出它。
+  { id: 'argent-shell', npm: `${NPM_SCOPE}/argent-shell` },
+]
+
+/**
+ * **智能体 bundle 的目录名前缀**（W3，0.6.0）：`plugins/argent-agent-<agent-id>`。
+ *
+ * ⚠️ 这里**只认前缀、绝不列名字**：agent id 由 **L0 货架声明**（`agents/catalog.json#agents[].id`）给定，
+ * 其中含**业务线词**（货架上的商品名本身就带它）⇒ 把逐个名字写进引擎面会**当场脏掉**
+ * `scripts/vertical-lint.mjs` 的 engine-words 判据（基线 0 新增 = 判红）。名字的真源仍是货架声明，
+ * 本文件只回答"这个前缀的包名怎么拼"。
+ */
+export const AGENT_BUNDLE_PREFIX = 'argent-agent-'
+
+/**
+ * 是不是**智能体 bundle** 的目录名/id（`argent-agent-<id>`；⛔ 不认路径形态与子路径导出）。
+ * 判据 = 前缀 + 非空 + 单段（含 `/` 的是 scoped 名/路径，走各自的归一分支）。
+ */
+export function isAgentBundleId(ref) {
+  const s = String(ref ?? '').trim()
+  return s.startsWith(AGENT_BUNDLE_PREFIX) && s.length > AGENT_BUNDLE_PREFIX.length && !s.includes('/')
+}
+
+/** 全部插件 id（保序）。 */
+export const PLUGIN_IDS = PLUGIN_PACKAGES.map((p) => p.id)
+
+/** 全部 npm 包名（保序）。 */
+export const PLUGIN_NPM_NAMES = PLUGIN_PACKAGES.map((p) => p.npm)
+
+const BY_ID = new Map(PLUGIN_PACKAGES.map((p) => [p.id, p]))
+const BY_NPM = new Map(PLUGIN_PACKAGES.map((p) => [p.npm, p]))
+
+/** 去掉子路径导出（`argent-core/llm-whyshu` → `argent-core`）。 */
+function baseRef(ref) {
+  const s = String(ref ?? '').trim().replace(/\\/g, '/')
+  if (!s) return ''
+  if (s.startsWith('@')) {
+    const parts = s.split('/')
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : s
+  }
+  return s.split('/')[0]
+}
+
+/** 是不是**已知**的 Argent 插件 id（裸名形态；也接受 `@whyshu/argent-*`）。 */
+export function isKnownPluginId(ref) {
+  return pluginIdOf(ref) !== null
+}
+
+/**
+ * 把**任意一种写法**归一到插件 id —— 认：
+ *   · 裸 id：`argent-core`
+ *   · npm 名：`@whyshu/argent-core`
+ *   · 子路径导出：`argent-core/llm-whyshu`、`@whyshu/argent-core/llm-whyshu`
+ *   · 目录/`file:` 规格里带上的路径尾段：`/x/plugins/argent-core`、`file:/x/plugins/argent-core`
+ * 认不出 ⇒ `null`（⛔ 不猜、不抛）。
+ */
+export function pluginIdOf(ref) {
+  let s = baseRef(String(ref ?? '').replace(/^file:/, ''))
+  if (!s) return null
+  if (BY_ID.has(s)) return s
+  if (BY_NPM.has(s)) return BY_NPM.get(s).id
+  // W3：**智能体 bundle**（`argent-agent-<id>`）—— 按**规则**认（前缀），⛔ 不看名字表（名字带业务线词）
+  if (isAgentBundleId(s)) return s
+  if (s.startsWith(`${NPM_SCOPE}/`)) {
+    const scoped = s.slice(NPM_SCOPE.length + 1)
+    if (isAgentBundleId(scoped)) return scoped
+  }
+  // 路径形态（绝对/相对）：取尾段再判一次
+  const tail = s.split('/').filter(Boolean).pop()
+  if (tail && BY_ID.has(tail)) return tail
+  if (tail && isAgentBundleId(tail)) return tail
+  return null
+}
+
+/**
+ * 插件 id → npm 包名。传进来的若是**已知**的 npm 名则原样回；未知 ⇒ `null`
+ * （⛔ 不"善意补 scope" —— 那会让打错的名字静默变成另一个包）。
+ */
+export function npmNameOf(id) {
+  const i = pluginIdOf(id)
+  if (!i) return null
+  if (BY_ID.has(i)) return BY_ID.get(i).npm
+  // W3：智能体 bundle 的 npm 名 = `@whyshu/<目录名>`（规则，⛔ 不查表）
+  return isAgentBundleId(i) ? `${NPM_SCOPE}/${i}` : null
+}
+
+/** 插件名（id 或 npm 名）→ 清单条目 `{id, npm}`；未知 ⇒ `null`。 */
+export function packageMetaOf(ref) {
+  const i = pluginIdOf(ref)
+  if (!i) return null
+  return BY_ID.has(i) ? BY_ID.get(i) : { id: i, npm: `${NPM_SCOPE}/${i}` }
+}
+
+/** `plugins/<id>` 的绝对路径（`repoRoot` = 仓库根）。 */
+export function pluginPackageDir(repoRoot, ref) {
+  const i = pluginIdOf(ref)
+  if (!i) return null
+  return `${String(repoRoot).replace(/[\\/]+$/, '')}/plugins/${i}`
+}
+
+/** `file:` 规格（离线/送装/无网回退用；pnpm 会按 target 的 `package.json#name` 建键 ⇒ 落 scoped）。 */
+export function fileSpecOf(repoRoot, ref) {
+  const dir = pluginPackageDir(repoRoot, ref)
+  return dir ? `file:${dir.replace(/\\/g, '/')}` : null
+}
+
+/** npm 规格（`@whyshu/argent-core@1.2.3`；不给版本 ⇒ 不带 `@版本`）。 */
+export function npmSpecOf(ref, version = '') {
+  const npm = npmNameOf(ref)
+  if (!npm) return null
+  return version ? `${npm}@${String(version).replace(/^v/, '')}` : npm
+}
+
+/**
+ * 去重归一到 id 列表（保序；未知项**原样保留**在 `unknown` 里给调用方处理，⛔ 不静默丢）。
+ * @returns {{ids: string[], unknown: string[]}}
+ */
+export function normalizePluginRefs(list) {
+  const ids = []
+  const unknown = []
+  for (const raw of list ?? []) {
+    const i = pluginIdOf(raw)
+    if (i) { if (!ids.includes(i)) ids.push(i) } else unknown.push(String(raw))
+  }
+  return { ids, unknown }
+}
+
+/** 读 `plugins/<id>/package.json#version`（读不到 ⇒ `null`；⛔ 不编造）。 */
+export function readPluginVersion(repoRoot, ref, { readFile = readFileSync } = {}) {
+  const dir = pluginPackageDir(repoRoot, ref)
+  if (!dir) return null
+  try {
+    const doc = JSON.parse(readFile(`${dir}/package.json`, 'utf8'))
+    return typeof doc.version === 'string' ? doc.version : null
+  } catch { return null }
+}
+
+/** 读 `plugins/<id>/package.json`（读不到 ⇒ `null`）。 */
+export function readPluginManifest(repoRoot, ref, { readFile = readFileSync } = {}) {
+  const dir = pluginPackageDir(repoRoot, ref)
+  if (!dir) return null
+  try { return JSON.parse(readFile(`${dir}/package.json`, 'utf8')) } catch { return null }
+}
+
+// ── 依赖图迁移（纯函数；安装器与回归用例共用，⛔ 不写第二份）────────────────────
+
+/**
+ * **依赖键迁移**：把存量 profile 里的裸键（`argent-core`）改成 npm 名键（`@whyshu/argent-core`）。
+ *
+ * 语义（刻意保守）：
+ *   · 只碰**本仓已知插件**的键（⛔ 绝不泛化改别人的依赖）；
+ *   · `spec` **原样保留**（`file:` / npm / 版本范围都不动 —— 迁移的是**键**，不是来源）；
+ *   · 两个键都在（迁移跑过一半 / npm add 之后的中间态）⇒ 裸键判为**陈旧别名**，进 `stale`
+ *     由调用方在"组合行已全部迁完"之后决定是否 `pnpm remove`（⛔ 本函数**不动**它）。
+ *   · 幂等：再喂进来 ⇒ `renamed`/`stale` 皆空、`deps` 逐字节等价。
+ * @param {Record<string,string>} deps
+ * @returns {{deps: Record<string,string>, renamed: Array<{from:string,to:string}>, stale: string[]}}
+ */
+export function migrateDependencyKeys(deps) {
+  const out = {}
+  const renamed = []
+  const stale = []
+  const src = deps && typeof deps === 'object' ? deps : {}
+  for (const [k, v] of Object.entries(src)) {
+    const id = pluginIdOf(k)
+    if (!id) { out[k] = v; continue }
+    const npm = BY_ID.get(id).npm
+    // 键已经是 npm 名 ⇒ 本位
+    if (k === npm) { out[k] = v; continue }
+    // 裸键：若 npm 键已在 ⇒ 它是陈旧别名；否则改名（spec 原样）
+    if (Object.prototype.hasOwnProperty.call(src, npm)) {
+      stale.push(k)
+      out[k] = v          // ⛔ 先留着：组合行还没迁完时它是旧行的解析来源
+    } else {
+      out[npm] = v
+      renamed.push({ from: k, to: npm })
+    }
+  }
+  return { deps: out, renamed, stale }
+}
+
+/**
+ * **严格**判据（**改写客户 profile 时用这个**）：只认两种**精确**写法 ——
+ *   · 裸 id：`argent-core`
+ *   · 本仓 npm 名：`@whyshu/argent-core`
+ * ⛔ 不认路径形态、不认"尾段同名"的**别的 scope**（`@acme/argent-skin`）。
+ *
+ * 为什么必须与宽松的 {@link pluginIdOf} 分开：`pluginIdOf` 要认 `file:/x/plugins/argent-core`
+ * 这类**路径**（读侧判"装没装"），而"尾段同名"这条在**写侧**是灾难 —— 它会把**第三方的**
+ * `@acme/argent-skin` 改写成 `@whyshu/argent-skin`（⛔ 把别人的包换成我们的）。
+ * 读侧宽松、写侧严格，是本模块的一条硬边界。
+ */
+export function exactPluginIdOf(ref) {
+  const s = String(ref ?? '').trim()
+  if (!s) return null
+  if (BY_ID.has(s)) return s
+  if (BY_NPM.has(s)) return BY_NPM.get(s).id
+  // W3：智能体 bundle —— 同上，按规则（⛔ 不认"尾段同名"的别的 scope / 路径形态）
+  if (isAgentBundleId(s)) return s
+  if (s.startsWith(`${NPM_SCOPE}/`)) {
+    const scoped = s.slice(NPM_SCOPE.length + 1)
+    if (isAgentBundleId(scoped)) return scoped
+  }
+  return null
+}
+
+/**
+ * **bundles 条目迁移**：`dsh.profile.bundles` 里的裸名（`argent-skin`）⇒ npm 名（`@whyshu/argent-skin`）。
+ *
+ * 为什么必须有它（2026-10-13 真机，W9 漏迁）：`dsh.profile.bundles` 与依赖键/组合行**同属
+ * "profile 面向字符串"**，而 W9 的迁移只做了后者两处 ⇒ 存量机器的 `bundles` 里留着裸名。
+ * 裸名在 profile 里**不可解析**（实体在 `node_modules/@whyshu/argent-skin`）⇒ bundle 加载不到
+ * ⇒ **皮肤/UI 壳静默不加载**（⛔ 安装期零报错；且 `bundles` 的顺序 = 各 bundle patch 的
+ * 应用顺序，基座必须在前且在位）。
+ *
+ * 语义（与 {@link migrateDependencyKeys} 同档，刻意保守）：
+ *   · 只碰**本仓已知插件**（{@link exactPluginIdOf} 认得出：裸 id 或本仓 npm 名）——官方 `@deepseek-ai/*`、
+ *     别人的 scope、路径形态一律**逐字原样保留**
+ *     （⛔ 不越权、不"善意补 scope"、不去重）；
+ *   · 已知插件的**两个名字都在** ⇒ 后面那个判为**陈旧别名**，摘掉（同一个 bundle ⛔ 不许留两个
+ *     名字，否则会重复挂载）；保留**首个出现位置** ⇒ 顺序（= patch 应用顺序）不变；
+ *   · 幂等：再喂回来 ⇒ `renamed`/`stale` 皆空、`bundles` 逐元素相等。
+ * @param {unknown} bundles `dsh.profile.bundles` 的当前值（非数组 ⇒ 当空表）
+ * @returns {{bundles: string[], renamed: Array<{from:string,to:string}>, stale: string[]}}
+ */
+export function migrateBundleNames(bundles) {
+  const src = Array.isArray(bundles) ? bundles : []
+  const out = []
+  const renamed = []
+  const stale = []
+  const landed = new Set()   // 已落位的**规范名**（已知插件）
+  for (const raw of src) {
+    const name = String(raw)
+    const id = exactPluginIdOf(name)                 // 写侧用**严格**判据（⛔ 不认别的 scope/路径尾段）
+    if (!id) { out.push(name); continue }            // 官方/未知：原样（⛔ 不越权）
+    const want = BY_ID.get(id).npm
+    if (landed.has(want)) { stale.push(name); continue }   // 同一条目的第二个名字 ⇒ 摘掉
+    landed.add(want)
+    if (name !== want) renamed.push({ from: name, to: want })
+    out.push(want)
+  }
+  return { bundles: out, renamed, stale }
+}
+
+/** 该引用是不是**已知插件的裸名**（`argent-skin`；scoped 名 / 官方包 / 别的 scope / 未知 ⇒ false）。 */
+export function isBarePluginName(ref) {
+  const s = String(ref ?? '').trim()
+  const id = exactPluginIdOf(s)
+  return !!id && s === id
+}
+
+/**
+ * 把**任意一种写法**归一到写 profile 用的规范名（npm 名）。
+ * 已知插件 ⇒ `@whyshu/argent-<id>`；**未知/官方条目 ⇒ 原样回**（⛔ 不猜）。
+ */
+export function canonicalPluginName(ref) {
+  const id = exactPluginIdOf(ref)
+  return id ? BY_ID.get(id).npm : String(ref ?? '')
+}
+
+/**
+ * 迁移后的**陈旧别名**是否可安全摘掉：仅当组合行里已经没有插件指向裸名。
+ * @param {string} patchText cordis.patch.yml 内容
+ * @param {string[]} staleDeps 待摘的裸依赖键
+ * @returns {string[]} 仍被组合行引用的键（⛔ 这些**不许**摘）
+ */
+export function staleDepsStillReferenced(patchText, staleDeps) {
+  const text = String(patchText ?? '')
+  return (staleDeps ?? []).filter((k) => new RegExp(`^\\s*name:\\s*['"]${escapeRe(k)}['"]\\s*$`, 'm').test(text))
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/engine/scripts/lib/preset-compat.mjs

@@ -0,0 +1,127 @@
+/**
+ * preset 行的跨版本兼容规则（**唯一真源**）。
+ *
+ * 背景（2026-09-28）：0.1.7 除了把 preset 从"目录扫描"改成"组合里的一行插件"，还**删掉了
+ * 若干子包**（preflight 的"消失子包"名单）。我们 13 个 preset 都引用了其中一个 ——
+ * `@deepseek-ai/dsh-workflow-worker-thread` —— 于是行式声明虽然在 0.1.7 上注册成功，
+ * 每个 preset 都带 `broken` 诊断：
+ *
+ *     workflow-worker-thread (@deepseek-ai/dsh-workflow-worker-thread): never started
+ *
+ * 这类"包没了"的问题**不会**在生成阶段暴露（我们只是搬运文本），必须在生成时按目标版本
+ * 改写，并且用"每行包都能解析"的硬门禁兜住（见 scripts/lib/preset-rows-check.mjs）。
+ *
+ * ⚠️ 规则只改**行**（id + name），不动 config —— 语义变化要单独评估并写进 note。
+ */
+
+/** 行改写规则：`from` 匹配 `name:` 行的包名；`idFrom/idTo` 改该行的 `id:`。 */
+export const ROW_RULES = [
+  {
+    from: '@deepseek-ai/dsh-workflow-worker-thread',
+    to: '@deepseek-ai/dsh-workflow-ptc',
+    idFrom: 'workflow-worker-thread',
+    idTo: 'workflow-ptc',
+    note: '0.1.7 起工作流运行时改名：worker-thread → ptc（provider: spawn 语义不变，官方 standard 即此写法）',
+  },
+]
+
+/**
+ * **必填键补齐**（按包）：目标版本把某键改成必填时，缺了会让 preset 挂载失败
+ * （校验器报 `缺必填键`）。取值一律抄**官方 standard preset**的同名行，并在此注明出处。
+ *
+ * 实测（2026-09-28，0.1.7-rc.2）：`@deepseek-ai/dsh-tool-subagent` 新增必填 `maxDepth`，
+ * 我们 13 个角色各有两行（fork / claude-code）缺失 ⇒ 校验器 FAIL 117 项。
+ */
+export const REQUIRED_KEY_DEFAULTS = {
+  '@deepseek-ai/dsh-tool-subagent': {
+    maxDepth: { value: 'provider-managed', source: "0.1.7 官方 dsh-web-app/presets/standard.patch.yml" },
+  },
+}
+
+/** 该行的缩进（用于插键）。 */
+function indentOf(line) {
+  const m = /^(\s*)/.exec(line)
+  return m ? m[1] : ''
+}
+
+/**
+ * 给缺必填键的行补键（逐行处理；插入位置在 `config:` 之后，缩进按该行体）。
+ * @param {string} text
+ * @returns {{ text: string, applied: string[] }}
+ */
+export function applyRequiredKeys(text) {
+  const lines = String(text).split('\n')
+  const out = []
+  const applied = []
+  let i = 0
+  while (i < lines.length) {
+    const rowStart = /^(\s*)- id:\s*(\S+)\s*$/.exec(lines[i])
+    if (!rowStart) { out.push(lines[i]); i += 1; continue }
+    // 收集整块（后续缩进更深的行）
+    const baseIndent = indentOf(lines[i]).length
+    let j = i + 1
+    while (j < lines.length && lines[j].trim() !== '' && indentOf(lines[j]).length > baseIndent) j += 1
+    const block = lines.slice(i, j)
+    const pkgLine = block.findIndex((l) => /^\s*name:\s*'?@/.test(l))
+    const pkg = pkgLine >= 0 ? (/name:\s*'?([^'\s]+)'?/.exec(block[pkgLine]) || [])[1] : null
+    const defaults = pkg ? REQUIRED_KEY_DEFAULTS[pkg] : null
+    if (!defaults) { out.push(...block); i = j; continue }
+    const cfgIdx = block.findIndex((l) => /^\s*config:\s*$/.test(l))
+    const missing = Object.entries(defaults).filter(([k]) => !block.some((l) => new RegExp(`^\\s*${k}:`).test(l)))
+    if (!missing.length) { out.push(...block); i = j; continue }
+    const cfgIndent = cfgIdx >= 0 ? indentOf(block[cfgIdx]) + '  ' : `${' '.repeat(baseIndent + 2)}  `
+    const insertAt = cfgIdx >= 0 ? cfgIdx + 1 : block.length
+    const additions = missing.map(([k, spec]) => `${cfgIndent}${k}: ${spec.value}`)
+    const newBlock = cfgIdx >= 0
+      ? [...block.slice(0, insertAt), ...additions, ...block.slice(insertAt)]
+      : [...block.slice(0, insertAt), `${' '.repeat(baseIndent + 2)}config:`, ...additions, ...block.slice(insertAt)]
+    out.push(...newBlock)
+    for (const [k, spec] of missing) applied.push(`${pkg} 补必填键 ${k}: ${spec.value}（出处：${spec.source}）`)
+    i = j
+  }
+  return { text: out.join('\n'), applied }
+}
+
+/**
+ * 对一份 preset 组合文本应用兼容改写（按行处理，保留注释/缩进/!!js）。
+ * @param {string} text
+ * @returns {{ text: string, applied: string[] }}
+ */
+export function applyRowCompat(text) {
+  const lines = String(text).split('\n')
+  const applied = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = /^(\s*name:\s*)'([^']+)'\s*$/.exec(lines[i])
+    if (!m) continue
+    const rule = ROW_RULES.find((r) => r.from === m[2])
+    if (!rule) continue
+    lines[i] = `${m[1]}'${rule.to}'`
+    applied.push(`${rule.from} → ${rule.to}`)
+    // 上一行的 `- id:` 同步改名（存在才改）
+    for (let j = i - 1; j >= 0 && j >= i - 3; j -= 1) {
+      const idm = /^(\s*- id:\s*)(\S+)\s*$/.exec(lines[j])
+      if (idm) {
+        if (idm[2] === rule.idFrom) lines[j] = `${idm[1]}${rule.idTo}`
+        break
+      }
+    }
+  }
+  const keyFix = applyRequiredKeys(lines.join('\n'))
+  return { text: keyFix.text, applied: [...applied, ...keyFix.applied] }
+}
+
+/**
+ * 抽出一份组合文本里**所有行引用的包名**（`name:` 行；跳过本地文件路径与 cordis: 内置）。
+ * @param {string} text
+ * @returns {string[]} 去重后的包名
+ */
+export function collectRowPackages(text) {
+  const out = new Set()
+  for (const line of String(text).split('\n')) {
+    const m = /^\s*name:\s*'?([^'\n]+?)'?\s*$/.exec(line)
+    if (!m) continue
+    const name = m[1].trim()
+    if (name.startsWith('@') && !name.startsWith('.')) out.add(name)
+  }
+  return [...out].sort()
+}