@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/config-explain.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * config-explain.mjs —— **「我改了到底生效没」一眼可见**（只读；2026-10-09，配置地基第三批次）
+ *
+ * 契约：`docs/Argent-宿主适配契约.md` §7.11「生效来源」可见化 + 冲突告警。
+ * 读取器/判据（**唯一实现**）：`core/lib/config-catalog.mjs` 的
+ * `resolveEffective()`（纯函数）+ `createReader().effectiveOf()`（取各级现值）。
+ * 本文件**只打印**：⛔ 不另写一份解析链、⛔ 不写任何配置、⛔ 不联网、⛔ 不改读取顺序。
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 它回答的问题
+ * ──────────────────────────────────────────────────────────────────────────
+ * 「很多变量存放在不同地方，读取的时候不是会容易混淆吗？」
+ * 「我在设置页改了，但更靠前的那一级还在生效？」
+ * 静态提示（"两套链不同序"）答不了这个 —— 必须**逐项**说清：这一项此刻
+ * **哪几级有值** / **谁赢了** / **谁被压住、为什么** / **每一级的落点在哪**。
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 用法
+ * ──────────────────────────────────────────────────────────────────────────
+ *   node scripts/config-explain.mjs --key <key>          # 一项的完整解析（人读）
+ *   node scripts/config-explain.mjs --key <key> --json   # 同上，机器可读
+ *   node scripts/config-explain.mjs --all                # **只列有冲突的项**（≥2 级同时有值）
+ *   node scripts/config-explain.mjs --all --json         # 冲突清单（机器可读）
+ *   node scripts/config-explain.mjs --list               # 全部项一行的总览（谁赢了 + 有无冲突）
+ *   node scripts/config-explain.mjs --list --conflict    # 总览里只留冲突项
+ *   node scripts/config-explain.mjs                      # 不带参数 = `--all`
+ *   node scripts/config-explain.mjs --root <dir> [--data-dir <dir>]   # 夹具（只读）
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 退出码（**这就是它作为巡检判据的语义**）
+ * ──────────────────────────────────────────────────────────────────────────
+ *   `0`  **无冲突**（或 `--list` 跑通）—— 没有"有值被压住"的项
+ *   `2`  **有冲突**：查询本身**成功**，2 只是一个信号（`--all` 时有 ≥1 项；`--key` 时该项 conflict）
+ *        ⇒ 接巡检时：`0` 安静、`2` 值得看一眼；⛔ `2` **不是**报错、也不代表配置坏了
+ *   `1`  **用法/环境错误**：缺 `--key`、key 未声明、目录文件不合法、数据目录读不出来
+ *   ⚠️ 冲突数是**动态**的（取决于这台机器此刻各级有没有值），所以别把 `2` 接成"红灯告警"，
+ *      它是"有一项被别处压着，去看看吧"。
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 脱敏（硬要求）
+ * ──────────────────────────────────────────────────────────────────────────
+ *   `secret: true` 的项：**任何**输出位（生效值 / 被压住的值 / 长度）只出现
+ *   `❰已设置(长度N)❱`，**永不含明文**（脱敏发生在 L1 的 `resolveEffective()` 里，
+ *   本文件拿到的就已经是占位符 —— 不是"打印时记得别打"）。回归用诱饵值做子串断言钉住。
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 纪律
+ * ──────────────────────────────────────────────────────────────────────────
+ *   · **只读**：源码里零写 API（回归 `scripts/tests/config-effective.test.mjs` 静态断言）；
+ *   · **不含业务词**（`vertical-lint` 会扫 `scripts/`）：分类/key/归属一律从目录**读**出来；
+ *   · ⛔ **不碰 `todayChain`、不改任何读取顺序**（那是迁移批次的活）—— 这里只**如实展示**
+ *     "规范链此刻谁赢"，以及"今天代码按登记的旧链先读哪一级、那一级现在有没有值"。
+ */
+
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { RESOLUTION_ORDER, createReader, redactSecret, validateCatalog } from '../core/lib/config-catalog.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const argOf = (name, dflt = null) => {
+  const i = argv.indexOf(name)
+  return i >= 0 ? argv[i + 1] ?? dflt : dflt
+}
+
+/** 层级 → 人话（只在这里写一份；页面侧的同名映射在 `plugins/argent-skin/dist/client.js`）。 */
+const LEVEL_ZH = {
+  env: '进程环境变量',
+  envfile: 'env 文件',
+  json: 'config.json',
+  machine: '机器本地文件',
+  server: '服务端（预留）',
+  default: '声明 default',
+}
+const zh = (l) => (l ? `${l}（${LEVEL_ZH[l] || '未知层级'}）` : '（无）')
+/** 密钥占位形态（与 L1 `redactSecret()` 的输出同形）：已是占位就不再脱敏（幂等，否则长度会说谎）。 */
+const SECRET_MARK_RE = /^❰已设置\(长度\d+\)❱$/
+
+/** 一行摘要里的生效来源（含"覆盖了谁"）。 */
+function fromText(eff) {
+  if (!eff.from) return '无值（五级链全未命中）'
+  if (eff.from === 'default') return 'default（声明里的默认值）'
+  const over = eff.shadowed.map((s) => s.level)
+  return zh(eff.from) + (over.length ? `（覆盖了 ${over.join('、')}）` : '')
+}
+
+/** 把一项的完整解析渲染成文本行（人读；⛔ 不含明文密钥）。 */
+function explainLines(key, eff, opts = {}) {
+  const out = []
+  out.push(`【${key}】${eff.declared ? '' : ' ⚠️ 目录里没有这一项（未声明）'}`)
+  out.push(`  声明链（规范链，恒按它解析）  ${eff.chain.join(' → ')}`)
+  out.push(`  本项 binding 真会读的级      ${eff.applicable.join(' → ') || '（无）'}`)
+  if (eff.todayChain) {
+    out.push(`  今日链（todayChain，**登记**的今天代码优先级，本批不按它解析）  ${eff.todayChain.join(' → ')}`)
+  } else {
+    out.push('  今日链（todayChain）         （未登记 ⇒ 与规范链同序）')
+  }
+  out.push('  各级现值（**脱敏**；✗ = 本级没值）')
+  for (const level of eff.chain) {
+    if (!eff.applicable.includes(level)) {
+      out.push(`    · ${level.padEnd(8)} —  本项 binding 不读这一级${level === 'server' ? '（`server` 来源本批预留、无读取实现）' : ''}`)
+      continue
+    }
+    const detail = (eff.levelDetail && eff.levelDetail[level]) || ''
+    const hit = level === eff.from || (eff.present || []).includes(level)
+    out.push(`    · ${level.padEnd(8)} ${hit ? '✓' : '✗'}  ${detail}`)
+  }
+  out.push(`  ➜ 生效级：${zh(eff.from)}`)
+  if (eff.from && eff.from !== 'default') out.push(`     落点：${eff.detail || '（未取到落点）'}`)
+  if (eff.from) {
+    out.push(eff.secret
+      ? `     生效值：${String(eff.value)}（密钥项：只给"已设置(长度)"，**永不含明文**）`
+      : `     生效值：${JSON.stringify(eff.value)}`)
+  }
+  if (eff.shadowed.length) {
+    for (const s of eff.shadowed) {
+      out.push(`  ➜ 被压住：${zh(s.level)} —— ${s.why}`)
+      out.push(`     它的值：${JSON.stringify(s.value)}${eff.secret ? '（密钥项：只给"已设置(长度)"）' : ''}`)
+      out.push(`     落点：${(eff.levelDetail && eff.levelDetail[s.level]) || '（未取到落点）'}`)
+    }
+  } else {
+    out.push('  ➜ 被压住：（无 —— 只有一个级有值）')
+  }
+  if (eff.invalid && eff.invalid.length) {
+    for (const x of eff.invalid) out.push(`  ⚠️ 有值但取不动：${zh(x.level)} —— ${x.why}`)
+  }
+  if (eff.todayFirst) {
+    out.push(`  ➜ 今天代码按登记的 todayChain **先读** ${zh(eff.todayFirst)}（当前${eff.todayFirstPresent ? '**有值**' : '无值'}）`)
+  }
+  if (eff.divergent) {
+    out.push('  ⚠️ **两套口径答案不同**：规范链给 ' + eff.from + '，今天代码先读 ' + eff.todayFirst
+      + '（它此刻有值）⇒ 按老代码跑出来的值与上面「生效级」不是同一个。迁移（批 3）完成前以运行时为准。')
+  }
+  if (opts.note !== false) out.push(`  ℹ️ ${eff.note}`)
+  return out
+}
+
+function main() {
+  const root = resolve(argOf('--root', REPO))
+  const dataDir = argOf('--data-dir', null)
+  const asJson = has('--json')
+  const key = argOf('--key', null)
+  const wantAll = has('--all') || (!key && !has('--list'))
+  const wantList = has('--list')
+  const onlyConflict = has('--conflict')
+
+  if (key && (wantList || has('--all'))) {
+    console.error('✗ `--key` 与 `--all` / `--list` 不能同时用（一次只做一件事）')
+    process.exit(1)
+  }
+  // `--key` 写了却没给值 ⇒ **用法错误**（⛔ 不许静默退化成 `--all` —— 那会让"我查这一项"变成"扫全部"而没人发现）
+  if (has('--key') && !key) {
+    console.error('✗ `--key` 需要一个 key（如 `--key ml.daily.hour`）；看全部：`--list` / 只看冲突：`--all`')
+    process.exit(1)
+  }
+
+  const reader = createReader({ root, ...(dataDir ? { dataDir } : {}) })
+
+  // 目录形状自检：声明本身不合法 ⇒ 判"环境错误"（exit 1），⛔ 不拿坏目录装作能解释
+  const problems = validateCatalog(reader.catalog())
+  if (problems.length) {
+    if (asJson) console.log(JSON.stringify({ ok: false, error: '配置目录不合法', problems }, null, 2))
+    else {
+      console.error(`✗ 配置目录不合法（${problems.length} 条）—— 先跑 node scripts/check-config-catalog.mjs --strict`)
+      for (const p of problems.slice(0, 10)) console.error(`  · ${p}`)
+    }
+    process.exit(1)
+  }
+
+  const effOf = (k) => {
+    const e = reader.effectiveOf(k)
+    // 出门前再过一道脱敏闸：即便 L1 出了岔子，这里也不会把 `secret` 项的真值打出去。
+    // ⚠️ **必须幂等**：L1（`resolveEffective()`）已把值换成 `❰已设置(长度N)❱`；若无条件再脱敏一次，
+    //    N 会变成**占位串自己的长度**（恒 11）—— 实测踩过。用户会拿这个数字去比对"密钥换没换"，
+    //    那就把「如实展示」变成了如实说谎。判据 = 形态已经是占位就直接放过（含被压住的那几级）。
+    if (e.secret) {
+      if (e.value !== null && e.value !== undefined && !SECRET_MARK_RE.test(String(e.value))) e.value = redactSecret(e.value)
+      for (const s of e.shadowed || []) {
+        if (!SECRET_MARK_RE.test(String(s.value))) s.value = redactSecret(s.value)
+      }
+    }
+    return e
+  }
+
+  if (key) {
+    const item = reader.all().find((i) => String(i.key) === String(key))
+    if (!item) {
+      const near = reader.all().map((i) => i.key).filter((k) => k.includes(String(key).slice(0, 4)))
+      if (asJson) console.log(JSON.stringify({ ok: false, error: `目录里没有 ${key}（未声明）`, near }, null, 2))
+      else {
+        console.error(`✗ 目录里没有 ${key} —— 配置目录是**声明真源**，没声明就无法解释它的来路。`)
+        if (near.length) console.error(`  相近的 key：${near.slice(0, 8).join('、')}`)
+        console.error('  · 看全部：node scripts/config-explain.mjs --list')
+      }
+      process.exit(1)
+    }
+    const eff = effOf(key)
+    if (asJson) console.log(JSON.stringify({ ok: true, key, effective: eff }, null, 2))
+    else {
+      console.log(`配置生效来源解释（root=${root}｜数据目录=${reader.dataDir()}）\n`)
+      console.log(explainLines(key, eff).join('\n'))
+      console.log('')
+      console.log(eff.conflict
+        ? '结论：⚠️ 有冲突（≥2 级同时有值 ⇒ 有值被压住）。被压住的那一级"改了不生效"。'
+        : '结论：✅ 无冲突（只有一个级有值）。')
+    }
+    process.exit(eff.conflict ? 2 : 0)
+  }
+
+  if (wantList) {
+    const items = reader.all().map((it) => effOf(it.key))
+    const rows = onlyConflict ? items.filter((e) => e.conflict) : items
+    if (asJson) {
+      console.log(JSON.stringify({
+        ok: true, root, dataDir: reader.dataDir(), resolutionOrder: [...RESOLUTION_ORDER],
+        total: items.length, conflicts: items.filter((e) => e.conflict).length,
+        items: rows.map((e) => ({
+          key: e.key, from: e.from, present: e.present,
+          shadowed: e.shadowed.map((s) => s.level), conflict: e.conflict,
+          divergent: e.divergent, todayFirst: e.todayFirst, todayFirstPresent: e.todayFirstPresent,
+          detail: e.detail, secret: e.secret, note: e.note,
+        })),
+      }, null, 2))
+    } else {
+      console.log(`配置生效来源总览（root=${root}｜数据目录=${reader.dataDir()}）`)
+      console.log(`  规范链：${RESOLUTION_ORDER.join(' → ')}｜声明 ${items.length} 项｜有冲突 ${items.filter((e) => e.conflict).length} 项\n`)
+      for (const e of rows) {
+        const flag = e.conflict ? '⚠️ 冲突' : '  —  '
+        console.log(`  ${flag}  ${String(e.key).padEnd(34)} 生效 ${fromText(e)}${e.divergent ? '  ｜ ⚠️ 今天代码先读 ' + e.todayFirst : ''}`)
+      }
+      if (onlyConflict && !rows.length) console.log('  （没有冲突项）')
+    }
+    const conflicts = items.filter((e) => e.conflict).length
+    process.exit(conflicts ? 2 : 0)
+  }
+
+  if (wantAll) {
+    const all = reader.all().map((it) => effOf(it.key))
+    const conflicts = all.filter((e) => e.conflict)
+    const divergent = all.filter((e) => e.divergent)
+    if (asJson) {
+      console.log(JSON.stringify({
+        ok: true, root, dataDir: reader.dataDir(), resolutionOrder: [...RESOLUTION_ORDER],
+        total: all.length, conflicts: conflicts.length, divergent: divergent.length,
+        items: conflicts.map((e) => ({
+          key: e.key, from: e.from, present: e.present, shadowed: e.shadowed,
+          conflict: true, divergent: e.divergent, detail: e.detail, note: e.note,
+          todayChain: e.todayChain, todayFirst: e.todayFirst, todayFirstPresent: e.todayFirstPresent,
+        })),
+        divergentItems: divergent.map((e) => ({ key: e.key, from: e.from, todayFirst: e.todayFirst, note: e.note })),
+      }, null, 2))
+    } else {
+      console.log(`配置冲突巡检（root=${root}｜数据目录=${reader.dataDir()}）`)
+      console.log(`  规范链：${RESOLUTION_ORDER.join(' → ')}｜声明 ${all.length} 项`)
+      console.log(`  有冲突 ${conflicts.length} 项（≥1 级有值被压住）｜两套口径答案不同 ${divergent.length} 项\n`)
+      if (!conflicts.length) {
+        console.log('  ✅ 没有任何项被别处压住（每一级的"谁赢"都是唯一的）')
+      } else {
+        for (const e of conflicts) {
+          console.log(explainLines(e.key, e, { note: false }).join('\n'))
+          console.log('')
+        }
+      }
+      if (divergent.length && !conflicts.length) {
+        for (const e of divergent) console.log(`  ⚠️ ${e.key}：规范链给 ${e.from}，今天代码先读 ${e.todayFirst}`)
+      }
+    }
+    process.exit(conflicts.length ? 2 : 0)
+  }
+}
+
+if (isDirectRun(import.meta.url)) main()

package/engine/scripts/configure-provider.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# encoding: UTF-8
+# configure-provider.rb — 写入/合并 DSH settings.yaml 的 whyshu 代理 provider 配置
+# 用法: ruby configure-provider.rb <settings.yaml 路径> [api_base]
+require 'yaml'
+
+path = ARGV[0] || File.join(Dir.home, '.dsh', 'settings.yaml')
+api_base = ARGV[1] || 'https://whyshu.com/api/argent/v1'
+
+doc = File.exist?(path) ? (YAML.load_file(path) || {}) : {}
+# ⚠️ contextWindow 与 maxTokens **成对自洽**（2026-10-02，与 provider-switch.sh 同源）：
+#    dsh-compaction-basic 的 resolveCompactSpec 要求
+#      contextWindow - maxTokens > 0  且  上式 - headroomTokens(默认 65536) > 0，
+#    否则抛 TargetPressureConfigError，而它在 agent/pre-step 被 catch ⇒ **只 warn 一次、
+#    此后每步静默跳过压缩**（比"不压缩"更难发现）。旧值 131072/131072 余量为 0 ⇒ 正是这种失能形态。
+WINDOW = 131_072
+MAX_OUT = 32_768   # 窗口 131072 下输出上限的安全取值（压缩阈值 = 32768）
+doc['llm-deepseek'] = {
+  'baseURL' => api_base,
+  'apiKeyEnv' => 'WHYSHU_API_KEY',
+  'models' => [
+    { 'id' => 'deepseek-v4-pro', 'name' => 'DeepSeek V4 Pro（问述代理）', 'contextWindow' => WINDOW, 'maxTokens' => MAX_OUT },
+    { 'id' => 'deepseek-chat', 'name' => 'DeepSeek Chat（问述代理）', 'contextWindow' => WINDOW, 'maxTokens' => MAX_OUT },
+  ],
+}
+doc['agent-default-model'] = { 'provider' => 'deepseek-official', 'model' => 'deepseek-v4-pro' }
+File.write(path, YAML.dump(doc))
+puts "  ✓ provider 已配置: #{path} → #{api_base}"

package/engine/scripts/customer-config-migrate.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * customer-config-migrate —— **在客户机上**把 gateway.json 迁到新形状（P5 步骤，2026-09-18 准备稿）。
+ *
+ * 为什么要有它：客户机的 `gateway.json` 是旧形状（只有 2 个角色），新插件要 12 个角色
+ * （各自 preset / skills / mentionNames / model）。而**凭据与机器相关**（botAppId/botSecret/
+ * chatId 只存在于客户机本机，且 gateway.json 含密钥 ⇒ 绝不能从开发机拷）。
+ * 故本脚本：拿仓库里的**结构模板**（`deploy/customer/roles.spec.json`，已剔除凭据）
+ * + 客户机**现有** gateway.json 里同角色的凭据 ⇒ 合并出新文件。
+ *
+ * 安全设计：
+ *   · **默认 dry-run**（只打印将要发生什么），`--apply` 才落盘；
+ *   · 落盘前把原文件备份为 `gateway.json.bak-<时间戳>`；
+ *   · 缺失凭据的角色 → botAppId 留空 = 主 Bot 兜底（并在报告里点名，便于后续补配）；
+ *   · 只写 `gateway.json`；`roles.json` 交给既有生成器（`check-role-mapping.mjs --write`），
+ *     避免两处各写一份映射（历史踩过：漏改一处 ⇒ 角色拿不到工具）。
+ *
+ * 用法（在客户机上，仓库已 pull 到最新）：
+ *   node scripts/customer-config-migrate.mjs                 # dry-run（默认）
+ *   node scripts/customer-config-migrate.mjs --apply         # 落盘（自动备份）
+ *   node scripts/customer-config-migrate.mjs --spec <路径> --data-dir <路径>
+ * 退出码：0 成功（含 dry-run）；2 参数/读取错误。
+ */
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { loadRegistryDoc } from './lib/registry.mjs'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const argv = process.argv.slice(2)
+const argVal = (n, d) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] : d }
+const APPLY = argv.includes('--apply')
+const ENV_ONLY = argv.includes('--env-only')   // 只做 env 键迁移（gateway.json 已迁过时用）
+const SPEC = argVal('--spec', join(REPO, 'deploy', 'customer', 'roles.spec.json'))
+const DATA = argVal('--data-dir', resolveDataDir({ env: process.env }).dir)   // 缺省 = 内核三级链
+
+const KEEP_FROM_EXISTING = ['botAppId', 'botSecret', 'chatId']   // 机器/凭据相关：按角色名保留
+const log = (m) => console.log(m)
+function fail(m) { console.error(`✗ ${m}`); process.exit(2) }
+
+const { listLarkProfiles, findBaseReader, parseEnvKeys, applyEnvKeys, realRun } = await import('./lib/customer-env.mjs')
+
+if (ENV_ONLY) {
+  migrateEnvKeys()
+  process.exit(0)
+}
+
+if (!existsSync(SPEC)) fail(`找不到结构模板：${SPEC}（客户机需先 git pull 到含 deploy/customer/ 的版本）`)
+const spec = JSON.parse(readFileSync(SPEC, 'utf8'))
+const specRoles = spec.roles || []
+if (!specRoles.length) fail('模板里没有 roles')
+
+const gwPath = join(DATA, 'gateway.json')
+let cur = { roles: [] }
+if (existsSync(gwPath)) {
+  try { cur = JSON.parse(readFileSync(gwPath, 'utf8')) } catch (e) { fail(`现有 gateway.json 解析失败：${e.message}`) }
+} else {
+  log(`  ⚠️ 未找到现有 ${gwPath} —— 将按模板从零生成（所有角色走主 Bot 兜底）`)
+}
+const curByRole = new Map((cur.roles || []).map((r) => [r.role, r]))
+
+log(`  ── 客户机配置迁移（${APPLY ? '落盘' : 'dry-run'}）──`)
+log(`  模板 ${specRoles.length} 个角色｜现有 ${curByRole.size} 个角色｜数据目录 ${DATA}`)
+
+// --only <role,role,...>：只保留**本客户实际要跑**的角色。
+// 由来（2026-09-28 P10）：模板是"全角色舰隊"版（pet-dev / lktop-pm / hr-office… 客户用不到）；
+// 全量灌进客户 gateway.json 会给每个角色建一条 Bot 路由（缺凭据的走主 Bot 兜底），
+// 客户群里可能被无关角色回话。按流程注册表声明的角色裁剪更稳。
+const onlyArg = (argVal('--only', '') || '').split(',').map((x) => x.trim()).filter(Boolean)
+const wanted = onlyArg.length ? specRoles.filter((r) => onlyArg.includes(r.role)) : specRoles
+const droppedByFilter = onlyArg.length ? specRoles.filter((r) => !onlyArg.includes(r.role)).map((r) => r.role) : []
+if (onlyArg.length) {
+  const missing = onlyArg.filter((r) => !specRoles.some((s2) => s2.role === r))
+  if (missing.length) fail(`--only 里的角色不在模板中：${missing.join(', ')}`)
+  log(`  · --only 裁剪：保留 ${wanted.length} 个（${wanted.map((r) => r.role).join(', ')}）`)
+}
+
+const out = []
+const kept = [], fallback = [], added = []
+for (const s of wanted) {
+  const prev = curByRole.get(s.role)
+  const merged = { ...s }
+  for (const k of KEEP_FROM_EXISTING) {
+    if (prev && prev[k]) merged[k] = prev[k]
+  }
+  if (prev && prev.botAppId) kept.push(s.role)
+  else if (!prev) added.push(s.role)
+  else fallback.push(s.role)
+  out.push(merged)
+}
+const droppedRoles = [...curByRole.keys()].filter((r) => !wanted.some((s) => s.role === r))
+
+log(`  · 保留现有 Bot 凭据：${kept.length ? kept.join(', ') : '（无）'}`)
+log(`  · 主 Bot 兜底（未配 bot）：${fallback.length ? fallback.join(', ') : '（无）'}`)
+log(`  · 新增角色（原配置里没有）：${added.length ? added.join(', ') : '（无）'}`)
+if (droppedRoles.length) log(`  · 将被移除的角色：${droppedRoles.join(', ')}（新架构已退役/本次未选）`)
+const models = new Set(out.map((r) => r.model || '(继承默认)'))
+log(`  · 角色模型：${[...models].join(', ')}`)
+const missingProfiles = [...new Set(out.map((r) => r.larkProfile).filter(Boolean))]
+log(`  · larkProfile 引用：${missingProfiles.join(', ') || '（无）'}（需在客户机 lark-cli 里已配置）`)
+
+const next = { ...cur, roles: out }
+const body = JSON.stringify(next, null, 2) + '\n'
+
+if (!APPLY) {
+  log(`  [dry-run] 将写入 ${gwPath}（${body.length} bytes）；加 --apply 落盘`)
+  log(`  [dry-run] roles.json 请随后用：node scripts/check-role-mapping.mjs --write`)
+  migrateEnvKeys()
+  process.exit(0)
+}
+
+const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)
+if (existsSync(gwPath)) {
+  const bak = `${gwPath}.bak-${ts}`
+  copyFileSync(gwPath, bak)
+  log(`  ✅ 已备份 ${bak}`)
+}
+writeFileSync(gwPath, body, 'utf8')
+log(`  ✅ 已写入 ${gwPath}（${out.length} 个角色）`)
+log('  下一步：node scripts/check-role-mapping.mjs --write && node scripts/check-role-mapping.mjs')
+log('  ⚠️ 网关会监听该文件热重载；若角色数变化后行为异常，重启 dsh web。')
+migrateEnvKeys()
+
+/**
+ * env 键迁移：把流程部署文件（fulfillment.env）里**缺的**键按**实测**补齐。
+ *
+ * 为什么不写死取值：各机器 lark-cli 的 profile 命名不一致（开发机 `lip-customer`，
+ * 客户机用 appId `cli_aaf7cafb66b85ccc`），且**同名不同 app**：客户机的 `ml-fulfillment`
+ * 指向缺 `base:record:read` 的 app（99991672）—— 只能真读一次表才知道谁能用。
+ * 探测只读（1 条记录）；取值命中不了就**不写**、只报缺口，绝不猜。
+ */
+function migrateEnvKeys() {
+  // P2a：env 规范位置是 `verticals/<id>/env/`（旧平铺路径保留给已装机器）。
+  // 规则：规范目录存在 ⇒ 写规范位置；否则沿用平铺（老机器零改动）。
+  const envName = 'fulfillment.env'
+  // P2a：env 规范位置从**注册表声明**派生（引擎里不写业务线名 —— vertical-lint 会拦「引擎不掺业务」）。
+  // 规则：注册表里哪条流程声明了这个 env 文件，就用它的目录；规范位置存在就写那儿，否则沿用平铺。
+  const _doc = loadRegistryDoc()
+  const _declared = Object.values(_doc.flows || {})
+    .map((f) => String((f.source || {}).envFile || ''))
+    .find((rel) => rel.endsWith(`/${envName}`))
+  const _relDir = _declared ? _declared.slice(0, _declared.lastIndexOf('/')) : ''
+  const envPath = (_relDir && existsSync(join(DATA, _relDir)))
+    ? join(DATA, _relDir, envName)
+    : join(DATA, envName)
+  log('\n── env 键迁移（流程读客户 Base 的身份）──')
+  if (!existsSync(envPath)) { log(`  ⚠️ 找不到 ${envPath}，跳过`); return }
+  const before = readFileSync(envPath, 'utf8')
+  const keys = parseEnvKeys(before)
+  const mode = (process.env.FULL_TABLE_MODE || keys.FULL_TABLE_MODE || 'lip').trim()
+  // P2a：经加载器合并（base + 业务线）
+  const req = loadRegistryDoc()
+  const variant = ((req.flows?.full?.source?.variants) || {})[mode] || {}
+  const baseToken = process.env[variant.baseEnv || ''] || keys[variant.baseEnv || ''] || keys.BASE_TOKEN
+  const tableId = process.env[variant.tableEnv || ''] || keys[variant.tableEnv || ''] || keys.TABLE_ID
+  log(`  · 模式 ${mode}：base=${(baseToken || '(缺)').slice(0, 12)}… table=${tableId || '(缺)'}`)
+  if (!baseToken || !tableId) { log('  ⚠️ base/table 未解析（先补 FULL_BASE_TOKEN / FULL_TABLE_ID），跳过身份探测'); return }
+
+  const profiles = listLarkProfiles(realRun)
+  log(`  · 候选身份 ${profiles.length} 个：${profiles.join(', ') || '(无)'}`)
+  const found = findBaseReader({ run: realRun, baseToken, tableId, profiles })
+  for (const t of found.tried) {
+    log(`    ${t.ok ? '✅' : '✗'} ${t.profile}${t.ok ? '' : `（${t.code || ''} ${t.msg || ''}）`}`)
+  }
+  const patch = { FULL_LARK_PROFILE: found.profile, FULL_NOTIFY_MODE: 'final' }
+  if (!found.profile) log('  ❌ 没有任何身份能读该表 —— 需先在开放平台给某个 app 申请 base:record:read 并加进该 Base')
+  const res = applyEnvKeys(before, patch, { force: argv.includes('--force') })
+  for (const k of res.added) log(`  ${APPLY ? '✅ 已写' : '[dry-run] 将写'} ${k}=${patch[k]}`)
+  for (const s2 of res.skipped) log(`  · 跳过 ${s2.key}：${s2.reason}`)
+  if (!res.added.length) { log('  · env 无改动'); return }
+  if (!APPLY) { log('  [dry-run] 加 --apply 落盘（自动备份，保持 600）'); return }
+  const bak = `${envPath}.bak-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`
+  copyFileSync(envPath, bak)
+  writeFileSync(envPath, res.text, { encoding: 'utf8', mode: 0o600 })
+  log(`  ✅ 已写入 ${envPath}（备份 ${bak.split('/').pop()}）`)
+}