@whyshu/argent-engine 0.0.0-stage → 0.6.1

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

@@ -0,0 +1,575 @@
+/**
+ * 角色 preset 安装/同步（**按 dsh 机制分派**，唯一真源）。
+ *
+ * 两套机制的安装形态完全不同（见 lib/preset-mechanism.mjs）：
+ *
+ *   目录式（0.1.5 及更早）
+ *     · 拷 `presets/<id>/` → `$DSH_HOME/.agent-presets/<id>/`
+ *     · `settings.yaml` 的 `agent-presets.default` 设默认角色
+ *
+ *   行式（0.1.7+）
+ *     · 拷 `plugins/argent-presets/` → `<profile>/node_modules/argent-presets`
+ *     · 登记进 `<profile>/package.json` 的 `dependencies` + `dsh.profile.bundles`
+ *       （bundle 的 `dsh.bundle.patch` 才会被加载 ⇒ preset 行才被 insert）
+ *     · 用 profile patch 覆盖注册表默认值（`- id: agent-preset-registry` + `config.default`）
+ *     · `~/.dsh/.agent-presets/` **不再使用**（留着也是惰性的）
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { MECHANISM } from './preset-mechanism.mjs'
+import { npmNameOf } from './plugin-packages.mjs'
+
+/** 仓库里的**目录名**（`plugins/argent-presets`）——W9 之后它**不再等于**包名，⛔ 不要混用。 */
+export const BUNDLE_DIR_NAME = 'argent-presets'
+/**
+ * 本 bundle 的 **npm 包名**（W9，2026-10-12）—— profile 里三处**必须**用它：
+ *   · `node_modules/<包名>` 落位路径；· `dependencies` 的**键**；· `dsh.profile.bundles` 的**条目**。
+ * 旧裸名（`argent-presets`）是**存量形态**：读侧一律两个都找（见 {@link resolveBundleDir}），
+ * 写侧一律迁到新名（见 `installPresetRows`）。口径见 `scripts/lib/plugin-packages.mjs`。
+ */
+export const BUNDLE_NPM_NAME = npmNameOf(BUNDLE_DIR_NAME) || BUNDLE_DIR_NAME
+/** 兼容别名：老调用方/夹具里的 `BUNDLE_NAME` 语义 = **包名**（写侧的规范形态）。 */
+const BUNDLE_NAME = BUNDLE_NPM_NAME
+
+/**
+ * profile 里本 bundle 的实际目录（**两个名字都找**；都没落 ⇒ 回**规范名**的路径给调用方判"缺"）。
+ * 为什么要双认：存量机器上是裸名目录，新装是 scoped 目录 —— 读侧任何一处只认一个名字，
+ * 都会在另一半机器上判成"没装"（⛔ 且不报错，只是 preset 静默不挂）。
+ */
+export function resolveBundleDir(profileDir, { exists = existsSync } = {}) {
+  for (const n of [BUNDLE_NPM_NAME, BUNDLE_DIR_NAME]) {
+    const d = join(profileDir, 'node_modules', ...String(n).split('/'))
+    if (exists(d)) return d
+  }
+  return join(profileDir, 'node_modules', ...String(BUNDLE_NPM_NAME).split('/'))
+}
+const REGISTRY_ROW_ID = 'agent-preset-registry'
+/** 落盘集合的唯一留痕文件名（**已装集的唯一判据**，见 `installedSelectionIds`）。 */
+export const SELECTION_FILE = 'presets.selection.json'
+const MARK = '# ── argent-presets：注册表默认角色（由安装器维护，勿手改）──'
+
+/**
+ * 全新 profile 的**基座 bundle**（P0-④，2026-10-08）。
+ *
+ * 为什么是这两条：`@deepseek-ai/dsh-base` 提供 agentPresets / llm / tools / webServer 这些服务，
+ * `@deepseek-ai/dsh-web-app` 提供 web 应用层与界面——**缺了它们，profile 引导根本不知道要组合哪些
+ * bundle**，运行期表现为 `16 entries did not activate`（13 个 preset 行 `waiting for service:
+ * agentPresets`、`llm-whyshu` `waiting for service: llm`…）⇒ 端口通、`/api` 401 正常，但 **Argent
+ * 一个条目都没起来**（实测现场见 docs/Argent-Windows-安装与HR能力验证-2026-10-08.md §3.8）。
+ * dsh 自己的 `initProfile()`（DEFAULT_PROFILE_BUNDLES）只给 dsh-base，这里按 web 实例补齐 web-app。
+ */
+export const BASE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']
+
+function readJson(p, dflt = null) {
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return dflt }
+}
+
+/**
+ * 幂等确保 profile 的 `package.json` 存在且**含基座 bundle**（缺则补在最前，不动其余键）。
+ *
+ * ⚠️ 为什么"补在最前"：`dsh.profile.bundles` 的顺序 = 各 bundle patch 的**应用顺序**（基座先、
+ * preset 行/皮肤后），所以基座不能被 append 到 `argent-presets` 后面。
+ * @returns {{ path: string, created: boolean, added: string[], changed: boolean }}
+ */
+export function ensureBaseBundles(profileDir, { bundles: want = BASE_BUNDLES, log = () => {} } = {}) {
+  const pkgPath = join(profileDir, 'package.json')
+  const created = !existsSync(pkgPath)
+  const pkg = readJson(pkgPath, null) || { name: `dsh-profile-${basename(profileDir)}`, private: true }
+  pkg.name = pkg.name || `dsh-profile-${basename(profileDir)}`
+  if (pkg.private !== true) pkg.private = true
+  pkg.dependencies = pkg.dependencies || {}
+  pkg.dsh = pkg.dsh || {}
+  pkg.dsh.profile = pkg.dsh.profile || {}
+  const list = Array.isArray(pkg.dsh.profile.bundles) ? pkg.dsh.profile.bundles : []
+  const added = want.filter((b) => !list.includes(b))
+  pkg.dsh.profile.bundles = [...added, ...list]
+  const text = `${JSON.stringify(pkg, null, 2)}\n`
+  let before = ''
+  try { before = readFileSync(pkgPath, 'utf8') } catch { /* 新建 */ }
+  if (before !== text) writeFileSync(pkgPath, text)
+  if (added.length) {
+    log(`  profile 基座 bundle 已登记：${added.join(', ')}${created ? '（新建 package.json）' : ''}`)
+  }
+  return { path: pkgPath, created, added, changed: before !== text, bundles: pkg.dsh.profile.bundles }
+}
+
+/** 目录式安装：拷角色目录 + 写 settings.yaml 默认值（0.1.5 行为，原样保留）。 */
+export function installPresetDirectory({ repo, dshHome, presetRoot, presetId = 'argent-general', log = () => {} }) {
+  const src = join(repo, 'presets', presetId)
+  if (!existsSync(src)) return { ok: false, reason: `源角色不存在：${src}` }
+  mkdirSync(presetRoot, { recursive: true })
+  const target = join(presetRoot, presetId)
+  if (existsSync(target)) {
+    cpSync(src, `${target}.new`, { recursive: true })
+    rmSync(target, { recursive: true, force: true })
+    renameSync(`${target}.new`, target)
+  } else {
+    cpSync(src, target, { recursive: true })
+  }
+  log(`  角色已落位（目录式）→ ${target}`)
+
+  // settings.yaml 的默认角色（0.1.5 的默认 mode 机制）
+  const settingsPath = join(dshHome, 'settings.yaml')
+  let text = ''
+  try { text = readFileSync(settingsPath, 'utf8') } catch { /* 不存在则新建 */ }
+  if (!text.includes('agent-presets:')) {
+    writeFileSync(settingsPath, `${text.trimEnd()}\n\nagent-presets:\n  default: ${presetId}\n`)
+    log(`  默认角色已写入 settings.yaml（agent-presets.default = ${presetId}）`)
+  }
+  return { ok: true, target }
+}
+
+/**
+ * 行式 bundle 目录里**当前登记的行**（= `package.json#dsh.bundle.patch` 的内容）。
+ *
+ * ⛔ **不得用作"本机已装集"的判据**（缺陷 1 的机制就在这儿，2026-10-12 真机实测）：
+ * ① 仓库/包**自带**的货架 `plugins/argent-presets/package.json` 里这 14 条**恒在**
+ *    （它是"这个包能提供什么"，不是"这台机器装了什么"）；
+ * ② pnpm 对 `file:` 依赖建的是**指向货架的链接农场**（实测：`node_modules/argent-presets`
+ *    → `.pnpm/…/node_modules/argent-presets`，文件与仓库**同 inode**）⇒ 装完"读这份"读到的
+ *    就是货架的 14 —— 于是"已装集"被判成 14，收窄被自己的安装步骤抹掉。
+ * 要"本机已装了什么"请用 `installedSelectionIds()`（读选择痕迹）。
+ */
+export function installedRowIds(bundleDir) {
+  const pkg = readJson(join(bundleDir, 'package.json'), null)
+  const list = (pkg && pkg.dsh && pkg.dsh.bundle && pkg.dsh.bundle.patch) || []
+  return list.map((rel) => basename(String(rel)).replace(/\.patch\.yml$/, '')).filter(Boolean)
+}
+
+/** 读「落盘选择痕迹」`presets.selection.json`（不存在/坏形状 ⇒ null）。 */
+export function readPresetSelection(bundleDir) {
+  const doc = readJson(join(bundleDir, SELECTION_FILE), null)
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.kept)) return null
+  return doc
+}
+
+/**
+ * bundle 的角色**元数据**（`presets.json` 的键 → 该角色的声明；读不到 ⇒ `{}`）。
+ * 不变式判据（`visibility: internal`）只读这里，⛔ 不另建第二份名单。
+ */
+export function bundleShelfMeta(bundleDir) {
+  const doc = readJson(join(bundleDir, 'presets.json'), null)
+  return doc && typeof doc === 'object' ? doc : {}
+}
+
+/**
+ * `ids` 里**声明为内部**的角色（`visibility: internal`）。
+ *
+ * 判据只有一处：货架/包副本的 `presets.json`。缺声明的角色按**客户可见**处理
+ * （与 `scripts/argent-agents.mjs#presetSelectionForAgents` 的默认值一致 —— 一个判据两处用，
+ * ⛔ 不在这里另立一套默认值，否则两处会各自漂移）。
+ */
+export function internalIdsAmong(bundleDir, ids) {
+  const meta = bundleShelfMeta(bundleDir)
+  return [...ids].filter((id) => (meta[id] || {}).visibility === 'internal')
+}
+
+/** `agents.json` 里各 agent 的 `roles` **并集**（坏形状/缺失 ⇒ 空集）。 */
+export function agentRoleUnion(ledger) {
+  const agents = (ledger && Array.isArray(ledger.agents)) ? ledger.agents : []
+  const out = []
+  for (const a of agents) for (const r of ((a && a.roles) || [])) if (!out.includes(String(r))) out.push(String(r))
+  return out
+}
+
+/** `agents.json#internalRoles === true`（唯一判据；缺文件/坏形状 ⇒ false）。 */
+export function ledgerAllowsInternal(ledger) {
+  return !!(ledger && ledger.internalRoles === true)
+}
+
+/**
+ * **已装集的唯一来源**（升级路径与安装路径共用这一份实现；2026-10-12 追修批）。
+ *
+ * 允许的两个来源，**只有这两个**：
+ *   ① **可信痕迹** `presets.selection.json#kept`；
+ *   ② 痕迹不可用（缺失/坏形状/**不可信**）时 ⇒ `agents.json` 里各 agent 的 `roles` 并集；
+ *   ③ 两者都没有 ⇒ **空集**（= 首次安装语义）。
+ * ⛔ **绝不允许**把"当前 profile 里的 patch 实体 / `presets.json` 行 / `dsh.bundle.patch` 条目"
+ * 当成已装集 —— 那三份都是**货架**（"这个包能提供什么"，恒 14），不是"这台机器装了什么"。
+ * 本缺陷与上一批缺陷的共同机制就是这条：`preset 同步（行式）`这一步把货架铺进 profile **之后**，
+ * 若拿铺进来的那份当"已装"，则 `客户可见 ∪ 已装 ∪ 本智能体` 恒等于货架全集 ⇒ 收窄被自己的安装步骤抹掉。
+ *
+ * ⚠️ **"可信"是有判据的，不是"有文件就信"**（2026-10-12 winpc 现场的真实形态）：
+ * 痕迹里含 `visibility: internal` 的角色、而本机 `internalRoles !== true`（且未给 `--internal-roles`）
+ * ⇒ 该痕迹**只可能由放大缺陷写出来**（现场：`kept` 14 个、`excluded` 空）⇒ 判为**不可信**，
+ * 按"痕迹缺失"处理（退回来源②）。这条**响亮报告**，⛔ 不静默采信、也不静默改痕迹。
+ *
+ * @param {object} o
+ * @param {string} o.bundleDir profile 副本目录（读痕迹 + 读角色元数据判内部角色）
+ * @param {object|null} [o.ledger] `agents.json` 的内容（调用方读；⛔ 本函数不猜 home）
+ * @param {boolean} [o.allowInternal] `--internal-roles` 或 `agents.json#internalRoles`
+ * @returns {{ids:string[], source:'trace'|'agents'|'none', trustedTrace:boolean, rejected:string, internalInTrace:string[], ledgerRoles:string[]}}
+ */
+export function resolveInstalledSelection({ bundleDir, ledger = null, allowInternal = false }) {
+  const ledgerRoles = agentRoleUnion(ledger)
+  const fallback = {
+    ids: ledgerRoles, source: ledgerRoles.length ? 'agents' : 'none',
+    trustedTrace: false, rejected: '', internalInTrace: [], ledgerRoles,
+  }
+  const trace = readPresetSelection(bundleDir)
+  if (!trace) return fallback
+  const kept = trace.kept.map((x) => String(x)).filter(Boolean)
+  const internalInTrace = internalIdsAmong(bundleDir, kept)
+  if (internalInTrace.length && !allowInternal) {
+    return { ...fallback, rejected: `痕迹声称落了 ${internalInTrace.length} 个内部角色（${internalInTrace.join('、')}），`
+      + `但本机 internalRoles≠true 且未给 --internal-roles ⇒ **不可信**（只可能由"收窄被抹掉"的缺陷写出）` }
+  }
+  return { ...fallback, ids: kept, source: 'trace', trustedTrace: true, internalInTrace }
+}
+
+/**
+ * **落盘集合不得含内部角色**的不变式（硬断言；2026-10-12 追修批，防这一类复发）。
+ *
+ * 判据：`keep ∩ {visibility: internal}` 非空 ∧ 未授权 ⇒ 违反。
+ * 授权 = `--internal-roles`（安装路径）或 `agents.json#internalRoles === true`（升级路径），
+ * 由调用方算成 `allowInternal` 传进来（⛔ 本函数不自己读 CLI/账本，避免第二份判据）。
+ * @returns {{ok:boolean, offenders:string[], reason:string}}
+ */
+export function checkNoInternalLanding(bundleDir, keep, { allowInternal = false } = {}) {
+  const offenders = internalIdsAmong(bundleDir, keep)
+  if (!offenders.length || allowInternal) return { ok: true, offenders: [], reason: '' }
+  return {
+    ok: false,
+    offenders,
+    reason: `落盘集合含 ${offenders.length} 个 visibility=internal 的角色（${offenders.join('、')}），`
+      + '但本机未授权内部角色（需 --internal-roles，或 agents.json#internalRoles = true）⇒ 判红并**拒绝写出**',
+  }
+}
+
+/**
+ * **选择痕迹的裸读**（`presets.selection.json#kept`；无痕迹 ⇒ 空集）。
+ *
+ * ⚠️ 它只回答"痕迹上写着什么"，**不判可信性**。要"本机已装集"请用
+ * `resolveInstalledSelection()` —— 那才是唯一入口（可信痕迹 → `agents.json#roles` 并集 → 空集）。
+ *
+ * 为什么必须是痕迹而不是"包里的 patch 清单"：见 `installedRowIds` 的两条机制。
+ * 没有痕迹 ≠ "装了货架全集"，而是**没有可信的已装证据** ⇒ 空集（等价于"首次安装"，
+ * 于是落盘集合精确等于该档的目标集合）。这条同时兜住两件事：
+ *   · 全新机器：无痕迹 ⇒ 只落客户可见集（⛔ 不会因为货架自带 14 个 patch 就落 14 个）；
+ *   · 升级路径：pnpm/doctor 把 profile 副本换回货架（14）之后，**下一轮不会被判成"已装 14"
+ *     而把用户已收窄的集合放大回去**（回归④⑤）。
+ * @returns {string[]}
+ */
+export function installedSelectionIds(bundleDir) {
+  const doc = readPresetSelection(bundleDir)
+  if (!doc) return []
+  return doc.kept.map((x) => String(x)).filter(Boolean)
+}
+
+/** bundle 里的 patch **实体文件**清单（排序；不依赖 package.json）。 */
+export function bundlePatchEntities(bundleDir) {
+  try {
+    return readdirSync(join(bundleDir, 'presets'))
+      .filter((f) => f.endsWith('.patch.yml'))
+      .map((f) => f.replace(/\.patch\.yml$/, ''))
+      .sort()
+  } catch { return [] }
+}
+
+/** `bundleDir` 是不是**软链**（pnpm 的 `file:` 依赖就是这种形态）。 */
+export function isLinkedBundle(bundleDir) {
+  try { return lstatSync(bundleDir).isSymbolicLink() } catch { return false }
+}
+
+/**
+ * 把**软链形态**的 profile 副本**实体化**（删链 + 从货架拷贝），返回是否动过手。
+ *
+ * ⚠️ 为什么必须有这一步（2026-10-12 实测，两条都真会发生）：
+ *   ① pnpm 建的链最终指向货架，而它可能是**硬链接农场** ⇒ 走链**写**（改 `presets.json` /
+ *      `package.json`）会**改到仓库文件本身**（实测 inode 相同、内容当场被改）；
+ *      删文件则只删链、仓库不动 —— 所以"半收窄"（行还在、实体没了）正是这样来的。
+ *   ② 收窄必须落在**真实体**上，否则下次 pnpm/doctor 一跑又回到货架全集。
+ */
+export function materializeBundleDir(bundleDir, shelfSrc) {
+  if (!isLinkedBundle(bundleDir)) return { materialized: false, ok: true }
+  if (!shelfSrc || !existsSync(shelfSrc)) {
+    return { materialized: false, ok: false, reason: `profile 副本是软链，但货架不可用（${shelfSrc || '未给 shelfSrc'}）⇒ 拒绝就地改写（会改到仓库本身）` }
+  }
+  rmSync(bundleDir, { force: true })          // 只删链，不追进去
+  cpSync(shelfSrc, bundleDir, { recursive: true })
+  return { materialized: true, ok: true }
+}
+
+/**
+ * 把 profile 副本**按货架重播**（无论当前是软链还是真目录）。
+ *
+ * 为什么"收尾重施"必须重播而不是就地再收窄一次（2026-10-12 追修批实测）：
+ * `applyPresetSelection` 的 universe 取自**当前副本**的 `presets.json` ⇒ 副本已被收窄到 7 时，
+ * 目标集合即使是 14 也只能落 7（`kept ⊆ universe`）⇒ ① `--internal-roles` 永远装不回来；
+ * ② 收尾自检会拿"期望 14 ≠ 落盘 7"判红（**假红**）。货架是**恒全集**、收窄是"按目标集合"，
+ * 所以收尾这一步的正确姿势 = **货架 → 收窄**，⛔ 不是"在当前副本上再过滤一次"。
+ *
+ * ⚠️ 只删 profile 副本（`rmSync` 不追链）；货架本身一个字节都不动。
+ */
+export function reseedBundleDir(bundleDir, shelfSrc) {
+  if (!shelfSrc || !existsSync(shelfSrc)) {
+    return { ok: false, reseeded: false, reason: `货架不可用（${shelfSrc || '未给 shelfSrc'}）⇒ 拒绝重播（否则 deps 里 file: 指向的目录会被清掉）` }
+  }
+  rmSync(bundleDir, { recursive: true, force: true })
+  mkdirSync(dirname(bundleDir), { recursive: true })
+  cpSync(shelfSrc, bundleDir, { recursive: true })
+  return { ok: true, reseeded: true }
+}
+
+/**
+ * 「三处集合相等」不变量 + 落盘痕迹一致性（回归⑦ / 收尾自检用）。
+ *
+ * 判据：`presets.json` 行 == `package.json#dsh.bundle.patch` == `presets/*.patch.yml` 实体
+ * == `presets.selection.json#kept`（四者相等，⛔ 缺一即"清单里有、注册表里没有"的假红/假绿）。
+ * @returns {{ok:boolean, kept:string[], shelf:string[], rows:string[], entities:string[], problems:string[]}}
+ */
+export function checkPresetSelectionConsistency(bundleDir, expectKept = null) {
+  const shelf = bundleShelfIds(bundleDir)
+  const rows = installedRowIds(bundleDir)
+  const entities = bundlePatchEntities(bundleDir)
+  const sel = readPresetSelection(bundleDir)
+  const kept = sel ? sel.kept.map((x) => String(x)) : []
+  const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i])
+  const sorted = (xs) => [...xs].sort()
+  const problems = []
+  if (!sel) problems.push('缺 presets.selection.json（落盘集合没有痕迹 ⇒ 下一轮会被判成"无已装证据"）')
+  if (shelf.length && !same(shelf, rows)) problems.push(`presets.json 行(${shelf.length}) ≠ package.json#dsh.bundle.patch(${rows.length})`)
+  if (shelf.length && !same(sorted(shelf), sorted(entities))) problems.push(`presets.json 行(${shelf.length}) ≠ patch 实体(${entities.length})`)
+  if (sel && !same(sorted(shelf), sorted(kept))) problems.push(`presets.selection.json#kept(${kept.length}) ≠ 落盘集合(${shelf.length})`)
+  if (expectKept && !same(sorted(expectKept), sorted(shelf))) problems.push(`期望集合(${expectKept.length}) ≠ 落盘集合(${shelf.length})`)
+  return { ok: problems.length === 0, kept, shelf, rows, entities, problems }
+}
+
+/** bundle 的完整角色清单（仓库产物的**货架**：`presets.json` 的键）。 */
+export function bundleShelfIds(bundleDir) {
+  const shelf = readJson(join(bundleDir, 'presets.json'), null)
+  return shelf && typeof shelf === 'object' ? Object.keys(shelf) : []
+}
+
+/**
+ * 把**已落位**的行式 bundle 收窄到 `keep`（A 批，2026-10-10）。
+ *
+ * 为什么改的是 profile 里的**副本**而不是仓库：`dsh.bundle.patch` 决定"哪些 preset 行被 insert
+ * 进注册表"，而用户口径是"选一个智能体装 ⇒ **只落它的角色**，其余不落"。仓库产物是**货架**
+ * （全集，13/14 个），每台机器落哪些是**装机决策** ⇒ 只能写 profile 副本。
+ *
+ * 三处必须**同时**收窄，否则会出现"清单里有、注册表里没有"的假红/假绿：
+ *   ① `package.json#dsh.bundle.patch`（Loader 真正读的那份 —— 删掉即不 insert）；
+ *   ② `presets/<id>.patch.yml` 实体（删掉，防手工/工具把它重新挂回去）；
+ *   ③ `presets.json`（探针 `plugin-bootcheck` 与诊断读它取角色清单）。
+ * 另写 `presets.selection.json` 留痕（谁在什么时候因什么被排除 —— 可复核，且**下一轮
+ * "已装集"的唯一判据**，见 `installedSelectionIds`）。
+ *
+ * ⚠️ `shelfSrc`（货架目录，即仓库 `plugins/argent-presets`）：`bundleDir` 是**软链**时必须给 ——
+ * 本函数会先把它**实体化**再改写；不给则**拒绝动手**（返回 `refused:true`），⛔ 绝不走链写进仓库。
+ *
+ * ## 不变式（2026-10-12 追修批，**每次调用都自检**）
+ * ① **落盘集合不得含 `visibility: internal` 的角色**，除非 `allowInternal`（= `--internal-roles`
+ *    或 `agents.json#internalRoles === true`）；违反 ⇒ `ok:false, refused:true` 且**一个字节都不写**
+ *    （⛔ 不静默剔除、不静默修 —— 静默修正好会掩盖"痕迹不可信/参数没传对"这类真问题）；
+ * ② 写完（或无需收窄时）自检 **patch 实体 == `presets.json` 行 == `dsh.bundle.patch` == 痕迹**
+ *    四者相等，结果放进 `consistency`（调用方据此判红）。
+ *
+ * @param {object} o
+ * @param {boolean} [o.allowInternal=false] 授权内部角色（默认**否** = fail-closed）
+ * @param {boolean} [o.reseedFromShelf=false] 先从 `shelfSrc` **重播**副本再收窄（收尾重施用；见 `reseedBundleDir`）
+ * @returns {{kept: string[], excluded: string[], note: string, ok?: boolean, refused?: boolean,
+ *            materialized?: boolean, reseeded?: boolean, missing?: string[], consistency?: object}}
+ */
+export function applyPresetSelection(bundleDir, keep, { why = '', log = () => {}, shelfSrc = '', allowInternal = false, reseedFromShelf = false } = {}) {
+  let materialized = false
+  let reseeded = false
+  if (reseedFromShelf && shelfSrc) {
+    const rs = reseedBundleDir(bundleDir, shelfSrc)
+    if (!rs.ok) {
+      log(`  ⚠️ preset 落盘集合**未收窄**：${rs.reason}`)
+      return { kept: [], excluded: [], note: rs.reason, refused: true, ok: false }
+    }
+    reseeded = true
+  }
+  if (isLinkedBundle(bundleDir)) {
+    const mat = materializeBundleDir(bundleDir, shelfSrc)
+    if (!mat.ok) {
+      log(`  ⚠️ preset 落盘集合**未收窄**：${mat.reason}`)
+      return { kept: [], excluded: [], note: mat.reason, refused: true, ok: false }
+    }
+    materialized = true
+    log('  ℹ️ profile 副本是软链（pnpm 的 `file:` 形态）⇒ 已实体化再从货架收窄')
+  }
+  const shelf = bundleShelfIds(bundleDir)
+  const current = installedRowIds(bundleDir)
+  const universe = shelf.length ? shelf : current
+  if (!universe.length) return { kept: [], excluded: [], note: 'bundle 里没有角色清单（presets.json/package.json 都读不到）', materialized, reseeded, ok: false }
+  const asked = [...new Set([...keep].map((x) => String(x)).filter(Boolean))]
+  const keepSet = new Set(asked.filter((id) => universe.includes(id)))
+  const kept = universe.filter((id) => keepSet.has(id))
+  const excluded = universe.filter((id) => !keepSet.has(id))
+  const missing = asked.filter((id) => !universe.includes(id))
+
+  // ── 不变式①：落盘集合不得含内部角色（未授权时）。**写之前**判，违反 ⇒ 拒绝写出。──────
+  const inv = checkNoInternalLanding(bundleDir, kept, { allowInternal })
+  if (!inv.ok) {
+    log(`  ✗ preset 落盘集合**被判红并拒绝写出**：${inv.reason}`)
+    return { kept: [], excluded: [], note: inv.reason, refused: true, ok: false, invariant: inv, missing, reseeded, materialized }
+  }
+  if (missing.length) {
+    log(`  ⚠️ 目标集合里有 ${missing.length} 个角色不在本副本（${missing.join('、')}）——⛔ 未被落盘（收尾重施请给 shelfSrc + reseedFromShelf）`)
+  }
+
+  // ⚠️ `presets.selection.json` **无论是否收窄都要写**：它是"这台机器上落了哪些角色"的**唯一留痕**，
+  // 判据（回归/巡检）读它 —— 只在"有排除项"时才写会让"全集落盘"这一态**没有证据**（实测踩到）。
+  const writeSelection = () => writeFileSync(join(bundleDir, SELECTION_FILE), `${JSON.stringify({
+    kept, excluded, at: new Date().toISOString(), why: why || '（未说明）',
+    _note: 'profile 副本的 preset 落盘集合（安装器维护，勿手改）——**下一轮"已装集"的唯一判据**。要装回被排除的角色：给安装器 --internal-roles（内部角色）或 --agent <id> / --capability <id> 点名它的能力。',
+  }, null, 2)}\n`)
+  const done = (note) => {
+    // ── 不变式②：三处集合 + 痕迹必须四者相等（写完即自检，结果交调用方判红）──────────
+    const consistency = checkPresetSelectionConsistency(bundleDir, kept)
+    if (!consistency.ok) log(`  ✗ 三处集合 + 痕迹**不一致**：${consistency.problems.join('；')}`)
+    return { kept, excluded, note, ok: consistency.ok, missing, materialized, reseeded, consistency }
+  }
+  if (!excluded.length) {
+    writeSelection()
+    log(`  preset 落盘集合：${kept.length}/${universe.length}（全部保留，无需收窄）`)
+    return done('')
+  }
+  const pkgPath = join(bundleDir, 'package.json')
+  const pkg = readJson(pkgPath, null)
+  if (pkg) {
+    pkg.dsh = pkg.dsh || {}
+    pkg.dsh.bundle = pkg.dsh.bundle || {}
+    pkg.dsh.bundle.patch = kept.map((id) => `./presets/${id}.patch.yml`)
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+    // ② patch 实体：排除项一律删（否则"文件还在"会被误读成"已装"）
+    for (const id of excluded) rmSync(join(bundleDir, 'presets', `${id}.patch.yml`), { force: true })
+    // ③ 探针/诊断读的清单同步收窄
+    const shelfPath = join(bundleDir, 'presets.json')
+    const full = readJson(shelfPath, null)
+    if (full && typeof full === 'object') {
+      const narrowed = {}
+      for (const id of kept) if (full[id]) narrowed[id] = full[id]
+      writeFileSync(shelfPath, `${JSON.stringify(narrowed, null, 2)}\n`)
+    }
+  }
+  writeSelection()
+  log(`  preset 落盘集合收窄：${kept.length}/${universe.length}；**刻意未落** ${excluded.length} 个（${excluded.join('、')}）`)
+  return done(why)
+}
+
+/**
+ * 行式安装：装 bundle + 登记 bundles/deps + 覆盖注册表默认值（0.1.7+）。
+ *
+ * ⚠️ **本函数落的收窄会被后续 pnpm 覆盖**（2026-10-12 真机实测）：profile 的
+ * `dependencies.argent-presets = file:<仓库>/plugins/argent-presets`，而安装器第 7 步
+ * （`pnpm add file:…` 装 argent-core/skin）会把这个目录**换成指向货架的链**（14 个 patch 全回来、
+ * `presets.selection.json` 消失）⇒ "声称收窄、实际没落"。调用方**必须在所有会动 profile 的步骤
+ * 之后**再收尾施加一次（安装器 `install-argent.mjs` 第 7c2 步 / 升级器第 8 步），
+ * 且施加前先 `materializeBundleDir()`。
+ * @param {object} o
+ * @param {string[]|null} [o.onlyPresets] 给定时**只落**这些角色 id（A 批：按智能体装 / 内部角色策略）；
+ *   `null`/缺省 ⇒ 全部（**与改动前逐字节一致**，向后兼容）。
+ * @param {boolean} [o.allowInternal=false] 授权内部角色（`--internal-roles` / `agents.json#internalRoles`）；
+ *   未授权时落盘集合若含内部角色 ⇒ `applyPresetSelection` 判红并拒绝写出（不变式，见该函数）。
+ * @returns {{ ok: boolean, copied?: string, bundlesAdded?: string[], registryDefault?: string, selection?: object, reason?: string }}
+ */
+export function installPresetRows({ repo, profileDir, presetId = 'argent-general', onlyPresets = null, selectionWhy = '', allowInternal = false, log = () => {} }) {
+  const src = join(repo, 'plugins', BUNDLE_DIR_NAME)
+  if (!existsSync(src)) return { ok: false, reason: `缺行式产物：${src}（先跑 node scripts/gen-preset-rows.mjs）` }
+  const nm = join(profileDir, 'node_modules')
+  mkdirSync(nm, { recursive: true })
+  // ── W9：落位路径/依赖键/bundle 名一律用**包名**（scoped）；旧裸名目录一并清掉并迁移 ──
+  const dest = join(nm, ...String(BUNDLE_NAME).split('/'))
+  rmSync(dest, { recursive: true, force: true })
+  if (BUNDLE_NAME !== BUNDLE_DIR_NAME) {
+    // 存量裸名目录/依赖键/bundles 条目：同一个 bundle 的旧名字 ⇒ 一起迁走（⛔ 留双份 = 重复挂载）
+    rmSync(join(nm, BUNDLE_DIR_NAME), { recursive: true, force: true })
+  }
+  cpSync(src, dest, { recursive: true })
+  log(`  bundle 已落位（行式）→ ${dest}`)
+  let selection = null
+  if (Array.isArray(onlyPresets)) selection = applyPresetSelection(dest, onlyPresets, { why: selectionWhy, log, shelfSrc: src, allowInternal })
+  if (selection && selection.refused) {
+    // 不变式判红 ⇒ **不登记**（否则会留下"注册表里有一行、patch 实体已被清"的半态）
+    return { ok: false, reason: selection.note, selection, refused: true }
+  }
+
+  // package.json：**先**基座 bundle（缺则补、并排在最前），**再**登记本 bundle 与依赖。
+  // ⚠️ P0-④（2026-10-08）：老实现以 `{name, private}` 默认值新建 package.json，**不带**任何
+  // `dsh.profile.bundles` ⇒ 安装器第 7 步那段"补基座"的引导（判据是 package.json 不存在）成了
+  // **死代码** ⇒ 全新机器启动后 `16 entries did not activate`，Argent 整体不工作。
+  ensureBaseBundles(profileDir, { log })
+  const pkgPath = join(profileDir, 'package.json')
+  const pkg = readJson(pkgPath, { name: 'dsh-profile-web', private: true })
+  pkg.dependencies = pkg.dependencies || {}
+  pkg.dependencies[BUNDLE_NAME] = `file:${src}`
+  // W9 迁移：旧裸名依赖键与旧 bundles 条目一起换掉（⛔ 同一个 bundle 不许留两个名字）
+  if (BUNDLE_NAME !== BUNDLE_DIR_NAME) delete pkg.dependencies[BUNDLE_DIR_NAME]
+  pkg.dsh = pkg.dsh || {}
+  pkg.dsh.profile = pkg.dsh.profile || {}
+  const bundles = Array.isArray(pkg.dsh.profile.bundles) ? pkg.dsh.profile.bundles : (pkg.dsh.profile.bundles = [])
+  const bundlesAdded = []
+  const oldIdx = BUNDLE_NAME === BUNDLE_DIR_NAME ? -1 : bundles.indexOf(BUNDLE_DIR_NAME)
+  if (oldIdx >= 0) bundles.splice(oldIdx, 1)   // 原位删旧名（顺序即 patch 应用顺序 ⇒ 不把它挪到末尾）
+  if (!bundles.includes(BUNDLE_NAME)) {
+    if (oldIdx >= 0) bundles.splice(oldIdx, 0, BUNDLE_NAME)
+    else bundles.push(BUNDLE_NAME)
+    bundlesAdded.push(BUNDLE_NAME)
+  }
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  if (bundlesAdded.length) log(`  bundles 已登记：${bundlesAdded.join(', ')}`)
+
+  // 注册表默认角色（profile patch 覆盖该行 config；0.1.7 的默认值机制）
+  const patchPath = join(profileDir, 'cordis.patch.yml')
+  let patch = ''
+  try { patch = readFileSync(patchPath, 'utf8') } catch { /* 新建 */ }
+  patch = upsertRegistryDefault(patch, presetId)
+  writeFileSync(patchPath, patch)
+  log(`  注册表默认角色已设：${presetId}`)
+
+  return { ok: true, copied: dest, bundlesAdded, registryDefault: presetId, selection }
+}
+
+/** 按机制分派。 */
+export function installPresets({ mechanism, ...opts }) {
+  if (mechanism === MECHANISM.ROWS) return { mechanism, ...installPresetRows(opts) }
+  if (mechanism === MECHANISM.DIRECTORY) return { mechanism, ...installPresetDirectory(opts) }
+  return { mechanism, ok: false, reason: `未知 preset 机制（scope 里既无 dsh-agent-preset 也无 dsh-agent-presets）` }
+}
+
+/**
+ * 行式机器上，把**旧机制的残留**说清楚（不删，只报告）：`~/.dsh/.agent-presets/` 里的目录
+ * 在 0.1.7 上不会再被扫描，留着是惰性的；但若有人以为"改目录就生效"会踩坑。
+ */
+export function reportStaleDirectories(presetRoot, exists = existsSync) {
+  if (!exists(presetRoot)) return []
+  try {
+    return readdirSync(presetRoot).filter((d) => d.startsWith('argent-'))
+  } catch { return [] }
+}
+
+/**
+ * 幂等地写入"注册表默认角色"覆盖块。
+ * 逐行 upsert（不用正则）：标记行 + 紧随其后的 `- id: agent-preset-registry` 行块整体替换，
+ * 保证重复安装不会留下第二个块（2026-09-28 实测：非贪婪正则只吃掉标记行、旧块残留 ⇒ 重复定义）。
+ */
+export function upsertRegistryDefault(patchText, presetId, mark = MARK, rowId = REGISTRY_ROW_ID) {
+  const lines = String(patchText || '').split('\n')
+  const block = [mark, `- id: ${rowId}`, '  config:', `    default: ${presetId}`]
+  const out = []
+  let i = 0
+  let done = false
+  while (i < lines.length) {
+    if (lines[i].trim() === mark.trim()) {
+      i += 1
+      // 吃掉旧块：`- id: ...` 行 + 其后的缩进续行（config/default 等）
+      if (i < lines.length && /^- /.test(lines[i])) {
+        i += 1
+        while (i < lines.length && /^\s+\S/.test(lines[i])) i += 1
+      }
+      if (!done) { out.push(...block); done = true }
+      continue
+    }
+    out.push(lines[i])
+    i += 1
+  }
+  if (!done) {
+    while (out.length && out[out.length - 1].trim() === '') out.pop()
+    out.push('', ...block)
+  }
+  return `${out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '')}\n`
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 角色 preset 的两套声明机制（**唯一真源**）。
+ *
+ * dsh 0.1.5 与 0.1.7 的 preset 架构完全不同：
+ *
+ * | | 0.1.5（现网/客户机） | 0.1.7（开发机候选） |
+ * |---|---|---|
+ * | 声明位置 | `~/.dsh/.agent-presets/<id>/agent.cordis.yml`（**扫目录**） | profile 组合里的**一行插件** |
+ * | 载体 | `@deepseek-ai/dsh-agent-presets`（复数） | `@deepseek-ai/dsh-agent-preset`（单数）+ `-registry` |
+ * | 新增角色 | 拷目录 | 改组合（bundle patch 的 `insert` 行） |
+ *
+ * 依据（0.1.7 官方 README 原文）："The registry neither scans directories nor accepts preset
+ * paths. A new preset or an override of a shipped one is a bundle patch: an `insert` of a
+ * `@deepseek-ai/dsh-agent-preset` row"。
+ *
+ * **判定用"能力探测"而不是版本号**：版本字符串会漂（rc 线尤其），而"scope 里有没有
+ * `dsh-agent-preset` 这个包"是事实。0.1.7 实测：装上后 13 个目录式 preset 全部
+ * `Unknown agent preset`（挂载失败），因为没人再扫目录。
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 机制常量。 */
+export const MECHANISM = { ROWS: 'rows', DIRECTORY: 'directory' }
+
+/**
+ * 探测某台机器（某 scope）支持哪套 preset 机制。
+ * @param {string} scopeDir `.../node_modules/@deepseek-ai`
+ * @param {(p: string) => boolean} exists
+ * @returns {'rows'|'directory'|'unknown'}
+ */
+export function detectPresetMechanism(scopeDir, exists = existsSync) {
+  if (!scopeDir) return 'unknown'
+  if (exists(join(scopeDir, 'dsh-agent-preset'))) return MECHANISM.ROWS
+  if (exists(join(scopeDir, 'dsh-agent-presets'))) return MECHANISM.DIRECTORY
+  return 'unknown'
+}
+
+/** 该机制下 preset 的"安装形态"说明（日志/文档用，避免各处自己编词）。 */
+export function mechanismNote(mechanism) {
+  return mechanism === MECHANISM.ROWS
+    ? '行式（profile 组合里的 @deepseek-ai/dsh-agent-preset 行；bundle patch 安装）'
+    : mechanism === MECHANISM.DIRECTORY
+      ? '目录式（~/.dsh/.agent-presets/<id>/agent.cordis.yml，由 dsh-agent-presets 扫描）'
+      : '未知（scope 里既没有 dsh-agent-preset 也没有 dsh-agent-presets）'
+}
+
+/**
+ * 跑某套机制该跑哪套门禁。
+ * @returns {{ schema: 'rows'|'directory'|null, idsFrom: 'composition'|'directory'|null }}
+ */
+export function gatePlan(mechanism) {
+  if (mechanism === MECHANISM.ROWS) return { schema: 'rows', idsFrom: 'composition' }
+  if (mechanism === MECHANISM.DIRECTORY) return { schema: 'directory', idsFrom: 'directory' }
+  return { schema: null, idsFrom: null }
+}