@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/gen-agent-bundles.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * 智能体 **bundle** 生成器（0.6.0 W3，2026-10-13）：`agents/catalog.json` → `plugins/argent-agent-<id>/`。
+ *
+ * ## 为什么需要它（与 `gen-preset-rows.mjs` 同因，同一套纪律）
+ * W3 的口径是「**agent = 一个 bundle**」：`--agent <id>` 装的不再是"角色/技能/定时器三件散件"，
+ * 而是**一个包** `@whyshu/argent-agent-<id>`（`dependencies` = 壳 + 该智能体声明的插件；
+ * `dsh.bundle` = 该智能体的补丁层；包内**声明字段** = 该智能体要装的能力包与档位）。
+ *
+ * ⛔ **只有一份真源**：`agents/catalog.json`（L0 货架声明）是**作者格式**，本脚本把它**机械投影**成
+ * 6 个包的 `package.json`；安装器读的是**包内声明**（分发形态），⛔ 不在安装器里再写一份映射。
+ * 三处判据（同一份真源）：
+ *   ① 本脚本 `--check`：产物与声明**逐字节**一致 + catalog 的每个 agent ⟺ **恰好一个** bundle
+ *      （缺件 / 多件都判红）+ 目录声明本身过 `validateCatalog()`/`validateHostAssets()`；
+ *   ② 安装器：把**包内声明**与货架投影**逐字比对**，不一致 ⇒ 零写入判红（`install-argent.mjs`）；
+ *   ③ 门禁：`scripts/tests/agent-bundle-generation.test.mjs`（含"手改产物 / 加删 agent 必须判红"的牙）。
+ *
+ * ## 产物形态（`plugins/argent-agent-<id>/package.json`，**纯 bundle**：零 JS）
+ * ```
+ * name            @whyshu/argent-agent-<id>      ← 与目录名同源（门禁 P6 判据）
+ * version         0.1.0
+ * license/repository/engines.node/publishConfig   npm 发布就绪（⛔ 不设 private）
+ * files           ['package.json']               ← 闭合（本包真的只有清单）
+ * dependencies    @whyshu/argent-shell + 该 agent 声明的**非壳**插件（npm 名取自唯一真源）
+ * dsh.bundle.patch []                            ← 本 bundle 的补丁层（见下）
+ * argent.agent    { id,title,payload{capabilities,plan},flows,roles,skills,integrations,credentials,scheduler,plugins }
+ * ```
+ *
+ * ## 为什么今天的 6 个包 `dsh.bundle.patch` 都是**空数组**
+ * `dsh.bundle.patch` 是「该 bundle 往组合里 insert 哪些插件行」的声明位。今天**没有一个智能体需要
+ * insert 行**：`argent-core`/`argent-skin` 由**壳**（W2）负责 insert，`argent-gateway`/`argent-flow`/
+ * `argent-ml` 的挂载面仍是**整装 + 设置页**（W3 ⛔ 不改既有装配语义、⛔ 不改 `--plan-only` 回执口径）。
+ * ⇒ 写成 `[]`（**合法的空 bundle 层**：宿主侧 `bundlePatchFiles()` 认数组，空数组 = 零 patch 文件），
+ * ⛔ 不是"空 `- insert:`"那种病态形态（那会在启动期报 `patch: id is required`）。
+ * 有了它，包在 `dsh plugin add` 之后**就是** profile 的一层（否则宿主会打印
+ * `declares no dsh.bundle — installed as a plain dependency`）—— 将来某个智能体真的需要 insert 行时，
+ * 只需改本文件的 `insertRowsFor()`（声明驱动，⛔ 不许手改产物）。
+ *
+ * 用法：
+ *   node scripts/gen-agent-bundles.mjs           # 生成/刷新
+ *   node scripts/gen-agent-bundles.mjs --check   # 只校验（CI/门禁；不一致 exit 1）
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { npmNameOf } from './lib/plugin-packages.mjs'
+// 判据复用 L1 的**同一份**实现（⛔ 不在这里另写一套目录校验）：
+//   · `argent-agents.mjs` = 货架声明的解析/校验（安装器与门禁也用它）；
+//   · `lib/plugin-packages.mjs` = 插件 id ↔ npm 包名的唯一真源。
+import { SHARED_SHELL_PLUGINS, buildContext, findAgent, validateCatalog, validateHostAssets } from './argent-agents.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = join(HERE, '..')
+
+/** 真源（**只此一处**）：货架声明。 */
+export const CATALOG_REL = 'agents/catalog.json'
+/** 产物根：`plugins/`。 */
+export const PLUGINS_DIR = join(REPO, 'plugins')
+/** bundle 目录名前缀 —— 安装器与门禁按它认"这是智能体 bundle"。 */
+export const BUNDLE_PREFIX = 'argent-agent-'
+/** bundle 版本（包自身语义化版本；与平台版本、能力包版本是三条轴）。 */
+export const BUNDLE_VERSION = '0.1.1'
+/** `@whyshu/argent-*` 依赖的兼容区间（⛔ 不是宿主 peer —— 那套区间判据只认 `@deepseek-ai/dsh*`）。 */
+export const ARGENT_PLUGIN_RANGE = '>=0.1.0 <0.3'
+/** 宿主 node 门槛（与安装器 `MIN_NODE` 对齐；与既有插件 `engines.node` 的写法逐字同源）。 */
+export const ENGINES_NODE = '>=24.2.0'
+/** npm 元数据（与既有 6 个插件逐字同源）。 */
+export const REPO_URL = 'git+https://whyshu.com/git/argent-dsh.git'
+
+/** 读货架声明（读不到 ⇒ null，由调用方响亮报错，⛔ 不静默补一份）；`root` 可注入（夹具用）。 */
+export function loadCatalogDoc(root = REPO) {
+  try { return JSON.parse(readFileSync(join(root, CATALOG_REL), 'utf8')) } catch { return null }
+}
+
+/** 货架里**在册智能体** id（保序 = 声明顺序）。 */
+export function listCatalogAgentIds(doc = loadCatalogDoc()) {
+  return ((doc && doc.agents) || []).map((a) => (a && a.id ? String(a.id) : '')).filter(Boolean)
+}
+
+/** 盘上**已存在的** bundle 目录名（`argent-agent-*`）。 */
+export function listBundleDirs(dir = PLUGINS_DIR) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((d) => d.startsWith(BUNDLE_PREFIX)).sort()
+}
+
+/**
+ * 目录条目 → **包内声明**（唯一投影；安装器读它、生成器写它、门禁比对它）。
+ *
+ * ⚠️ 字段名与来源（⛔ 不新增第二份真源）：
+ *   · `payload.capabilities` ← `agent.capability` 或 `agent.capabilities`（二者二选一，⛔ 不在包内再存一份平铺的能力名）；
+ *   · `payload.plan`         ← `agent.minPlan`（安装器的 `plan.minPlan` 由它映射，⛔ 不两处各存一份档位）；
+ *   · `flows/roles/skills/integrations/credentials/scheduler/plugins` ← 各自同名声明（逐字）。
+ * @param {object} agent `agents/catalog.json#agents[n]`
+ * @returns {object}
+ */
+export function declarationFor(agent) {
+  const capabilities = Array.isArray(agent.capabilities) ? agent.capabilities.map(String) : [String(agent.capability)]
+  const credentials = (agent.credentials || []).map((c) => ({ slot: String(c.slot), target: String(c.target), why: String(c.why) }))
+  return {
+    id: String(agent.id),
+    title: String(agent.title || ''),
+    payload: { capabilities, plan: String(agent.minPlan || '') },
+    flows: (agent.flows || []).map(String),
+    roles: (agent.roles || []).map(String),
+    skills: (agent.skills || []).map(String),
+    integrations: (agent.integrations || []).map(String),
+    credentials,
+    scheduler: agent.scheduler === true,
+    plugins: (agent.plugins || []).map(String),
+  }
+}
+
+/**
+ * 该智能体**需要 insert 的插件行**（`dsh.bundle.patch` 的判据）。
+ *
+ * 今天恒为 `[]`（见文件头「为什么今天 6 个包都是空数组」）：壳负责 core/skin，其余插件的挂载面是
+ * 整装 + 设置页。函数留着是为了**声明驱动**：将来要挂行时改这里 + 生成 `cordis.patch.yml`，
+ * ⛔ 不要手改产物。
+ * @returns {string[]} 插件 id（需要 insert 的）
+ */
+export function insertRowsFor(agent) {
+  const plugins = (agent.plugins || []).map(String)
+  // 「壳负责的插件」不是本 bundle 的行；「声明了但不在共享壳里」的插件今天也**不**由本层挂（见文件头）。
+  // ⇒ 判据保留、取值恒空：一旦要改为"由 agent bundle 挂行"，只需把下面这行换成
+  //   `plugins.filter((p) => !SHARED_SHELL_PLUGINS.includes(p))` 并同批生成 cordis.patch.yml。
+  void plugins
+  return []
+}
+
+/** 该 bundle 的 `dependencies`（壳 + 该 agent 声明的**非壳**插件；npm 名取自 `plugin-packages.mjs`）。 */
+export function dependenciesFor(agent) {
+  const out = {}
+  const shell = npmNameOf('argent-shell')
+  if (!shell) throw new Error('`scripts/lib/plugin-packages.mjs` 里没有 argent-shell 的 npm 名 —— 无法生成 bundle 依赖')
+  out[shell] = ARGENT_PLUGIN_RANGE
+  for (const id of (agent.plugins || []).map(String)) {
+    if (SHARED_SHELL_PLUGINS.includes(id)) continue          // core/skin 由壳带（⛔ 不重复声明）
+    if (id === 'argent-shell') continue
+    const npm = npmNameOf(id)
+    if (!npm) throw new Error(`未知插件 id \`${id}\`（在册：见 scripts/lib/plugin-packages.mjs）—— 无法生成 bundle 依赖`)
+    if (out[npm]) continue
+    out[npm] = ARGENT_PLUGIN_RANGE
+  }
+  return out
+}
+
+/** 渲染 `package.json` 文本（键顺序固定 ⇒ 逐字节稳定）。 */
+export function renderBundlePackageJson(agent) {
+  const name = `${BUNDLE_PREFIX}${String(agent.id)}`
+  const doc = {
+    name: `@whyshu/${name}`,
+    version: BUNDLE_VERSION,
+    description: `Argent on DSH 智能体 bundle —— ${String(agent.title || agent.id)}（由 agents/catalog.json 生成，⛔ 不要手改）`,
+    license: 'MIT',
+    repository: { type: 'git', url: REPO_URL, directory: `plugins/${name}` },
+    engines: { node: ENGINES_NODE },
+    files: ['package.json'],
+    publishConfig: { access: 'public' },
+    dependencies: dependenciesFor(agent),
+    dsh: { bundle: { patch: insertRowsFor(agent).map((id) => `./${id}.patch.yml`) } },
+    argent: { agent: declarationFor(agent) },
+  }
+  return `${JSON.stringify(doc, null, 2)}\n`
+}
+
+/**
+ * 生成/校验 6 个 bundle。
+ * @param {{check?: boolean}} [o]
+ * @returns {{ids: string[], changed: string[], errors: string[]}}
+ */
+export function generate({ check = false, root = REPO } = {}) {
+  const doc = loadCatalogDoc(root)
+  const pluginsDir = join(root, 'plugins')
+  const changed = []
+  const errors = []
+  if (!doc) return { ids: [], changed, errors: [`读不到货架声明：${CATALOG_REL}`] }
+  const agents = (doc.agents || []).filter((a) => a && a.id)
+  const ids = agents.map((a) => String(a.id))
+  const files = new Map()
+  for (const a of agents) {
+    const dir = join(pluginsDir, `${BUNDLE_PREFIX}${a.id}`)
+    files.set(join(dir, 'package.json'), renderBundlePackageJson(a))
+  }
+  // 清理已不在货架上的 bundle（多出来的产物 = 陈旧件 ⇒ --check 判红）
+  for (const d of listBundleDirs(pluginsDir)) {
+    const id = d.slice(BUNDLE_PREFIX.length)
+    if (ids.includes(id)) continue
+    if (check) changed.push(`（应删除）plugins/${d}`)
+    else { rmSync(join(pluginsDir, d), { recursive: true, force: true }); changed.push(`删除 plugins/${d}`) }
+  }
+  for (const [path, content] of files) {
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : null
+    if (cur === content) continue
+    if (check) changed.push(path.replace(`${root}/`, ''))
+    else {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, content, 'utf8')
+      changed.push(path.replace(`${root}/`, ''))
+    }
+  }
+  // 双向一致性：货架每个 agent ⟺ **恰好一个** bundle 目录
+  const dirs = listBundleDirs(pluginsDir)
+  for (const id of ids) if (!dirs.includes(`${BUNDLE_PREFIX}${id}`)) errors.push(`货架有 agent \`${id}\`，但盘上没有 plugins/${BUNDLE_PREFIX}${id}/`)
+  for (const d of dirs) {
+    const id = d.slice(BUNDLE_PREFIX.length)
+    if (!ids.includes(id)) errors.push(`盘上有 plugins/${d}/，但货架里没有 agent \`${id}\``)
+  }
+  // 目录声明自洽（与门禁 `check-agent-catalog.mjs` 同一条判据；缺注册表时只报告不拦）
+  try {
+    const ctx = buildContext(root, (m) => errors.push(m))
+    const v = validateCatalog(doc, ctx)
+    errors.push(...v.errors)
+    errors.push(...validateHostAssets(ctx).errors)
+  } catch (e) {
+    errors.push(`目录声明自检失败：${String(e && e.message).split('\n')[0]}`)
+  }
+  return { ids, changed, errors }
+}
+
+/**
+ * **包内声明 ⟺ 货架投影** 的逐字比对（安装器与门禁用**同一份**判据）。
+ * @param {string[]} ids 要比对的 agent id（缺省 = 全部）
+ * @returns {string[]} 差异清单（空 = 一致）
+ */
+export function compareBundlesToCatalog(ids = null, { root = REPO } = {}) {
+  const doc = loadCatalogDoc(root)
+  const out = []
+  if (!doc) return [`读不到货架声明：${CATALOG_REL}`]
+  const want = ids && ids.length ? ids.map(String) : listCatalogAgentIds(doc)
+  for (const id of want) {
+    const agent = findAgent(doc, id)
+    if (!agent) { out.push(`货架里没有 agent \`${id}\``); continue }
+    const p = join(root, 'plugins', `${BUNDLE_PREFIX}${id}`, 'package.json')
+    if (!existsSync(p)) { out.push(`缺包内声明：plugins/${BUNDLE_PREFIX}${id}/package.json`); continue }
+    let m = null
+    try { m = JSON.parse(readFileSync(p, 'utf8')) } catch { out.push(`plugins/${BUNDLE_PREFIX}${id}/package.json 不是合法 JSON`); continue }
+    const got = JSON.stringify(m.argent && m.argent.agent)
+    const exp = JSON.stringify(declarationFor(agent))
+    if (got !== exp) out.push(`plugins/${BUNDLE_PREFIX}${id}/package.json 的包内声明与货架声明**逐字不一致**：`
+      + `\n      包内：${got}\n      货架：${exp}`)
+    const wantName = `@whyshu/${BUNDLE_PREFIX}${id}`
+    if (String(m.name || '') !== wantName) out.push(`plugins/${BUNDLE_PREFIX}${id}/package.json#name = ${JSON.stringify(m.name)}（应为 ${JSON.stringify(wantName)}）`)
+  }
+  return out
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+if (process.argv[1] && process.argv[1].endsWith('gen-agent-bundles.mjs')) {
+  const check = process.argv.includes('--check')
+  const { ids, changed, errors } = generate({ check })
+  const cross = compareBundlesToCatalog(ids)
+  if (!ids.length) {
+    console.error('✗ 货架里一个智能体都没有（agents/catalog.json#agents）')
+    process.exit(1)
+  }
+  if (check) {
+    const bad = [...new Set([...errors, ...cross])]
+    if (changed.length || bad.length) {
+      if (changed.length) {
+        console.error(`✗ bundle 产物与货架声明不一致（${changed.length} 处）—— 跑 node scripts/gen-agent-bundles.mjs 刷新：`)
+        for (const c of changed) console.error(`    · ${c}`)
+      }
+      for (const e of bad) console.error(`✗ ${e}`)
+      process.exit(1)
+    }
+    console.log(`✅ 智能体 bundle 与货架声明一致（${ids.length} 个：${ids.join('、')}；每个 agent ⟺ 恰好一个 bundle，包内声明逐字一致）`)
+    process.exit(0)
+  }
+  if (errors.length) {
+    for (const e of errors) console.error(`✗ ${e}`)
+    console.error('⛔ 货架声明有错 ⇒ 已生成产物但不代表可用（先修声明再重跑）')
+    process.exit(1)
+  }
+  console.log(`✅ 已生成 ${ids.length} 个智能体 bundle → plugins/${BUNDLE_PREFIX}<id>/`)
+  for (const c of changed) console.log(`    · ${c}`)
+}

package/engine/scripts/gen-preset-rows.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * 角色 preset 生成器：目录式（0.1.5 源） → **行式**（0.1.7 bundle patch）。
+ *
+ * 为什么需要它：0.1.7 起 preset **不再扫目录**，必须变成 profile 组合里的一行
+ * `@deepseek-ai/dsh-agent-preset`（`config.plugins` = 原来的行列表）。我们 13 个角色的
+ * 作者格式（`presets/<id>/agent.cordis.yml` + `preset.yml`）保持不变（客户机 0.1.5 还在用），
+ * 行式产物由本脚本**从作者格式生成**，保证两边不会各写一份而漂移。
+ *
+ * 产物（全部落在 `plugins/argent-presets/`，作为一个 bundle 供 0.1.7 机器挂载）：
+ *   presets/<id>.patch.yml   —— 一个 insert 行（官方标准：每个 preset 一个 patch 文件）
+ *   package.json             —— dsh.bundle.patch = 上述文件数组
+ *   presets.json             —— id → {name, description, order}（门禁与探针读它取角色清单）
+ *
+ * 用法：
+ *   node scripts/gen-preset-rows.mjs            # 生成/刷新
+ *   node scripts/gen-preset-rows.mjs --check     # 只校验是否与源一致（CI/门禁；不一致 exit 1）
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { applyRowCompat } from './lib/preset-compat.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = join(HERE, '..')
+
+/** 源：作者格式目录（presets/<id>/{agent.cordis.yml,preset.yml}）。 */
+export const SRC_DIR = join(REPO, 'presets')
+/** 产物：bundle 插件。 */
+export const OUT_DIR = join(REPO, 'plugins', 'argent-presets')
+/** 子包 indent：`plugins:` 下的行要缩进到 10 空格（与官方 standard.patch.yml 一致）。 */
+const INDENT = ' '.repeat(10)
+
+/**
+ * 极简 front-matter 解析（`preset.yml`）。
+ *
+ * A 批（2026-10-10）起除 `name`/`description` 外还承载**归属与内外划分**：
+ *   · `capability`  —— 该角色属于哪个能力包（"装哪个智能体就只落哪些角色"的判据之一）；
+ *   · `visibility`  —— `customer`（默认；可落客户机）/ `internal`（我方内部角色，**默认不落**，
+ *                      需安装器显式 `--internal-roles`）；
+ *   · `always`      —— 恒装（`argent-general`）；
+ *   · `rolesFor`    —— 显式点名"这个角色归哪些智能体"（列表；无 flow 的能力如 hr 用它）。
+ * 生成器把它们写进 `plugins/argent-presets/presets.json`（门禁/安装器读它，⛔ 不再另立名单）。
+ * 支持三种写法：标量 `k: v`、内联列表 `k: [a, b]`、块列表（`k:` 后跟 `  - a`）。
+ */
+export function readPresetMeta(dir) {
+  const p = join(dir, 'preset.yml')
+  const out = {}
+  if (!existsSync(p)) return out
+  const lines = readFileSync(p, 'utf8').split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i])
+    if (!m) continue
+    const key = m[1]
+    const raw = m[2].trim()
+    if (raw === '') {
+      const items = []
+      for (let j = i + 1; j < lines.length; j++) {
+        const im = /^\s+-\s*(.+?)\s*$/.exec(lines[j])
+        if (!im) break
+        items.push(unquote(im[1]))
+        i = j
+      }
+      out[key] = items.length ? items : ''
+      continue
+    }
+    if (/^\[.*\]$/.test(raw)) {
+      out[key] = raw.slice(1, -1).split(',').map((x) => unquote(x.trim())).filter(Boolean)
+      continue
+    }
+    out[key] = unquote(raw)
+  }
+  return out
+}
+
+function unquote(s) {
+  return String(s).replace(/^['"]|['"]$/g, '')
+}
+
+/**
+ * `presets.json` 条目的**归一形状**（它是判据面：门禁与安装器都按这些键读 ⇒ 形状必须稳定）。
+ * `capability` 与 `rolesFor` 缺省**不写键**（缺席 = 无该归属，避免"空串 ≠ 无"这类第二口径）。
+ */
+export function normalizePresetMeta(meta) {
+  const out = { name: meta.name || '', description: meta.description || '' }
+  if (meta.capability) out.capability = String(meta.capability)
+  out.visibility = meta.visibility === 'internal' ? 'internal' : 'customer'
+  out.always = meta.always === true || meta.always === 'true'
+  const rf = Array.isArray(meta.rolesFor) ? meta.rolesFor.map(String).filter(Boolean) : []
+  if (rf.length) out.rolesFor = rf
+  return out
+}
+
+/** 列出作者格式里的所有角色（目录名 + 必需文件齐备）。 */
+export function listSourcePresets(srcDir = SRC_DIR) {
+  if (!existsSync(srcDir)) return []
+  return readdirSync(srcDir)
+    .filter((d) => {
+      try { return statSync(join(srcDir, d)).isDirectory() && existsSync(join(srcDir, d, 'agent.cordis.yml')) } catch { return false }
+    })
+    .sort()
+}
+
+/** 把一份 agent.cordis.yml 嵌进 `plugins:` 之下（**纯缩进**，保留注释与 !!js、不做 YAML 重排）。 */
+export function indentComposition(text) {
+  return text.replace(/\n+$/, '\n').split('\n').map((l) => (l.trim() === '' ? '' : INDENT + l)).join('\n')
+}
+
+/** 生成单个角色的 patch 文件内容（含跨版本行改写；改写记录写进文件头便于审计）。 */
+export function renderPatch({ id, meta, composition, order }) {
+  const compat = applyRowCompat(composition)
+  const name = (meta.name || id).replace(/'/g, "''")
+  const desc = (meta.description || '').replace(/'/g, "''")
+  const head = [
+    `# Agent preset ${id} — 由 scripts/gen-preset-rows.mjs 从 presets/${id}/ 生成，**不要手改**。`,
+    `# 改作者格式（presets/${id}/agent.cordis.yml 或 preset.yml）后重跑生成器。`,
+    `# 0.1.7 起 preset 是"组合里的一行插件"（不再扫目录）：name 固定为 @deepseek-ai/dsh-agent-preset。`,
+    ...(compat.applied.length
+      ? [`# 行级兼容改写（lib/preset-compat.mjs）：${compat.applied.join('；')}`]
+      : []),
+    '- insert:',
+    `    - id: preset-${id}`,
+    `      name: '@deepseek-ai/dsh-agent-preset'`,
+    `      config:`,
+    `        id: ${id}`,
+    `        name: '${name}'`,
+  ]
+  if (desc) head.push(`        description: '${desc}'`)
+  head.push(`        order: ${order}`)
+  head.push(`        plugins:`)
+  return `${head.join('\n')}\n${indentComposition(compat.text)}`
+}
+
+/**
+ * 生成 package.json 内容。
+ *
+ * ⚠️ 本文件**拥有** `plugins/argent-presets/package.json`（`--check` 逐字节比对 ⇒ 手改产物必红）。
+ * 所以 npm 元数据与 `peerDependencies` 必须写在这里 —— 2026-10-12 W1（插件声明补全）：
+ *   · `files`/`repository`/`engines`/`publishConfig` = npm 发布就绪（⛔ 本批不发布；scope 落地属 W9）；
+ *   · `peerDependencies` 的来源与**宿主兼容区间**推导见
+ *     `docs/Argent-插件化评估与实施计划.md` §4.1.1（下界 = 安装器已验证版本基线 ∪ 已晋级快照的最低版本；
+ *     上界必须写 `<0.3` 而不是 `<0.3.0`，否则 `includePrerelease` 下会把 `0.3.0-rc.1` 也算满足）。
+ *   防漂移门禁 = `node scripts/tests/plugin-peer-coverage.test.mjs`（范围写窄/写宽/漏件都会当场判红）。
+ */
+export function renderPackageJson(ids) {
+  return JSON.stringify({
+    name: '@whyshu/argent-presets',
+    version: '0.1.0',
+    description: 'Argent on DSH — 角色 preset 行式声明（dsh 0.1.7+；bundle patch 形态）',
+    type: 'module',
+    main: 'src/index.js',
+    exports: { '.': './src/index.js', './package.json': './package.json' },
+    license: 'MIT',
+    repository: {
+      type: 'git',
+      url: 'git+https://whyshu.com/git/argent-dsh.git',
+      directory: 'plugins/argent-presets',
+    },
+    engines: { node: '>=24.2.0' },
+    files: ['src/', 'presets/', 'presets.json'],
+    publishConfig: { access: 'public' },
+    peerDependencies: {
+      '@deepseek-ai/cordis': '~4.0.4',
+      '@deepseek-ai/dsh-agent-preset': '>=0.1.0-rc.6 <0.3',
+    },
+    dsh: {
+      plugin: { displayName: 'Argent 角色预设（0.1.7 行式）' },
+      bundle: { patch: ids.map((id) => `./presets/${id}.patch.yml`) },
+    },
+  }, null, 2) + '\n'
+}
+
+/** 生成插件入口（bundle 的 patch 就是全部内容，入口只做自述，避免"空插件"告警）。 */
+export function renderIndex(ids) {
+  return `/**
+ * argent-presets —— 角色 preset 的**行式**声明（dsh 0.1.7+）。
+ *
+ * 本插件的实质内容是 \`presets/*.patch.yml\`（由 package.json 的 \`dsh.bundle.patch\` 数组加载）：
+ * 每个文件往组合里 insert 一行 \`@deepseek-ai/dsh-agent-preset\`，其 \`config.plugins\` 即该角色的
+ * 组合（原 \`presets/<id>/agent.cordis.yml\`）。源码入口本身不注册任何服务/工具。
+ *
+ * 生成器：scripts/gen-preset-rows.mjs（作者格式 → 本目录，禁止手改产物）。
+ */
+export const name = 'argent-presets'
+export const inject = []
+
+/** 角色清单（诊断用；与 presets.json 同源）。 */
+export const presetIds = ${JSON.stringify(ids, null, 2)}
+
+export function apply() {
+  // patch 由 Loader 在装配期应用；这里无需运行时动作。
+}
+`
+}
+
+/** 生成/校验。返回 { ids, changed: string[] }。 */
+export function generate({ check = false } = {}) {
+  const ids = listSourcePresets()
+  const changed = []
+  const files = new Map()
+  const manifest = {}
+  ids.forEach((id, i) => {
+    const dir = join(SRC_DIR, id)
+    const meta = readPresetMeta(dir)
+    const composition = readFileSync(join(dir, 'agent.cordis.yml'), 'utf8')
+    files.set(join(OUT_DIR, 'presets', `${id}.patch.yml`), renderPatch({ id, meta, composition, order: i + 1 }))
+    manifest[id] = { ...normalizePresetMeta({ ...meta, name: meta.name || id }), order: i + 1 }
+  })
+  files.set(join(OUT_DIR, 'package.json'), renderPackageJson(ids))
+  files.set(join(OUT_DIR, 'src', 'index.js'), renderIndex(ids))
+  files.set(join(OUT_DIR, 'presets.json'), JSON.stringify(manifest, null, 2) + '\n')
+
+  // 清理已不存在的角色的产物
+  const staleDir = join(OUT_DIR, 'presets')
+  if (existsSync(staleDir)) {
+    for (const f of readdirSync(staleDir)) {
+      if (!f.endsWith('.patch.yml')) continue
+      const id = f.replace(/\.patch\.yml$/, '')
+      if (!ids.includes(id)) {
+        const p = join(staleDir, f)
+        if (check) changed.push(`（应删除）${p.replace(REPO + '/', '')}`)
+        else { rmSync(p); changed.push(`删除 ${p.replace(REPO + '/', '')}`) }
+      }
+    }
+  }
+
+  for (const [path, content] of files) {
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : null
+    if (cur === content) continue
+    if (check) changed.push(path.replace(REPO + '/', ''))
+    else {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, content, 'utf8')
+      changed.push(path.replace(REPO + '/', ''))
+    }
+  }
+  return { ids, changed }
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+if (process.argv[1] && process.argv[1].endsWith('gen-preset-rows.mjs')) {
+  const check = process.argv.includes('--check')
+  const { ids, changed } = generate({ check })
+  if (!ids.length) {
+    console.error('✗ 没找到任何作者格式 preset（presets/<id>/agent.cordis.yml）')
+    process.exit(1)
+  }
+  if (check) {
+    if (changed.length) {
+      console.error(`✗ 行式产物与作者格式不一致（${changed.length} 处）—— 跑 node scripts/gen-preset-rows.mjs 刷新：`)
+      for (const c of changed) console.error(`    · ${c}`)
+      process.exit(1)
+    }
+    console.log(`✅ 行式产物与作者格式一致（${ids.length} 个角色）`)
+    process.exit(0)
+  }
+  console.log(`✅ 已生成 ${ids.length} 个角色的行式声明 → plugins/argent-presets/`)
+  for (const c of changed) console.log(`    · ${c}`)
+}