@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/self-sign-license.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * self-sign-license —— **离线自签**一份许可（演练 / 测试 / 无服务端时跑通离线激活闭环），2026-10-03
+ *
+ * ## 它解决什么
+ * 离线激活闭环是「`license request` 拿设备码 → 服务端签发 v2 许可 → `install --file`」。
+ * 没有服务端在场时（开发机、隔离环境、客户现场演练）这条链路跑不通 ⇒ 本工具用**本地密钥**
+ * 按**同一份载荷契约**签一份，让闭环可验（`core/lib/license-file.mjs#signLicenseFile` 是唯一实现，
+ * 本脚本不重写载荷构造）。
+ *
+ * ## ⛔ 三条硬约束（都是刻意的摩擦，不是遗漏）
+ *   ① **密钥必须显式**：只认 `--secret-file`（或 `ARGENT_LICENSE_SECRET`）；**不**读本机已装的
+ *      `license.secret` —— 那会让"拿生产密钥自签"变成一次无意识的默认动作。
+ *   ② **产物路径必须显式**：必须给 `--out <路径>`；`--out` 落在**本机现役许可位**
+ *      （`$ARGENT_DATA_DIR/license.json`）时**拒绝**，除非显式 `--allow-live-target`
+ *      （那条路应该走 `install-license.mjs`，它带备份/读回验收/设备比对）。
+ *   ③ **不扩权**：`capabilities/verticals/seats/expiresAt/graceDays` 全部来自命令行**显式**参数，
+ *      默认最小（无能力、30 天、席位 1）—— 本工具不会"读一份现有许可然后放宽它"。
+ *
+ * ## ⚠️ 它不是"防伪"的一环
+ * 许可签名是 **HMAC-SHA256（对称密钥）**：验签方必须持有同一把密钥 ⇒ 能读 `license.secret` 的人
+ * **本来就能自签**。本工具只是把这件事**摆到明面上**（工具化、留痕、口径唯一），不构成新的能力。
+ * 真防伪造需要**非对称签名**（Ed25519，客户端只拿公钥）—— 见 §3.6③ 与实施方案的服务端方案。
+ *
+ * 用法：
+ *   node scripts/self-sign-license.mjs --user <账号id> --secret-file <密钥文件> --out <许可文件>
+ *        [--cap <能力id>]… [--vertical <业务线id>]… [--seats N] [--days N | --expires <ISO>] [--grace N]
+ *        [--instance <提示串>] [--device-code <64hex> | --device-from-local | --no-device]
+ *        [--sign-v1 | --sign-v2] [--json] [--dry-run] [--force]
+ * 缺省：**v2 + 本机设备码**（D1：新签发默认带 `device`）；`--no-device` ⇒ v2 但不声明设备（unbound，
+ * 缺位一样进签名）；`--sign-v1` ⇒ 旧形态（9 项载荷，**不含** device）。
+ * 退出码：0 已签（含 dry-run）｜ 1 写入失败/自验失败 ｜ 2 用法或环境错误
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { DEVICE_ALGO, currentDevice } from '../core/lib/license-device.mjs'
+import { defaultLicensePath, resolveSecret, signLicenseFile, verifyLicenseFile } from '../core/lib/license-file.mjs'
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const allOf = (f) => argv.reduce((acc, a, i) => (a === f && argv[i + 1] !== undefined ? [...acc, argv[i + 1]] : acc), [])
+const argOf = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] ?? null : null }
+const die = (m) => { console.error(`✗ ${m}`); process.exit(2) }
+const fail = (m) => { console.error(`✗ ${m}`); process.exit(1) }
+
+if (has('--help') || has('-h')) {
+  console.log('用法：node scripts/self-sign-license.mjs --user <id> --secret-file <密钥文件> --out <许可文件>')
+  console.log('      [--cap <id>]… [--vertical <id>]… [--seats N] [--days N|--expires <ISO>] [--grace N] [--instance <hint>]')
+  console.log('      [--device-code <64hex>|--device-from-local|--no-device] [--sign-v1|--sign-v2] [--json] [--dry-run] [--force]')
+  console.log('⚠️ 离线**自签**（演练/测试用）；真实签发在服务端（whyshu-svr）。签名是 HMAC 对称密钥 ⇒ 不是防伪边界。')
+  process.exit(0)
+}
+
+const dryRun = has('--dry-run')
+const jsonOut = has('--json')
+const asJson = jsonOut
+
+const userId = String(argOf('--user') || '').trim()
+if (!userId) die('必须给 --user <账号id>（许可里的 userId；空值会被判 malformed）')
+
+const secretSrc = argOf('--secret-file') ? resolve(argOf('--secret-file')) : null
+if (!secretSrc && !String(process.env.ARGENT_LICENSE_SECRET || '').trim()) {
+  die('必须显式给密钥来源：--secret-file <密钥文件> 或 ARGENT_LICENSE_SECRET'
+    + '（⛔ 不读本机已装的 license.secret：自签必须是**刻意**的动作）')
+}
+if (secretSrc && !existsSync(secretSrc)) die(`密钥文件不存在：${secretSrc}`)
+const key = resolveSecret({ secret: undefined, secretPath: secretSrc || undefined })
+if (!key.secret) die(`读不到密钥：${secretSrc || 'ARGENT_LICENSE_SECRET'}`)
+
+const outArg = argOf('--out')
+if (!outArg) die('必须给 --out <许可文件路径>（本工具**不**默认往数据目录写）')
+const out = resolve(outArg)
+const live = defaultLicensePath()
+if (out === live && !has('--allow-live-target')) {
+  die(`--out 指向**本机现役许可位**（${live}）：这条路请走 \`install-license.mjs\`（带备份 + 读回验收 + 设备比对）；`
+    + '确实要直接覆盖请显式加 --allow-live-target')
+}
+if (existsSync(out) && !has('--force') && !dryRun) die(`--out 已存在：${out}（要覆盖请加 --force）`)
+
+// 版本（缺省 v2 —— D1：新签发默认带 device）
+const signV1 = has('--sign-v1')
+const signV2 = has('--sign-v2')
+if (signV1 && signV2) die('--sign-v1 与 --sign-v2 只能给一个')
+const version = signV1 ? 1 : 2
+
+// 设备声明（v2 才有意义）：缺省 = **本机设备码**
+const noDevice = has('--no-device')
+const deviceCodeArg = argOf('--device-code')
+let device = null
+if (version === 2 && !noDevice) {
+  if (deviceCodeArg) {
+    const code = String(deviceCodeArg).trim()
+    if (!/^[0-9a-f]{64}$/i.test(code)) {
+      die(`--device-code 必须是 64 位十六进制的**设备码**（\`argent license request\` 打印的那串）；`
+        + '⛔ 不要给主机名/MAC/IP（D3：指纹只认硬件 UUID 一项）')
+    }
+    device = { code: code.toLowerCase(), algo: DEVICE_ALGO, issuedAt: new Date().toISOString() }
+  } else {
+    const dev = currentDevice({})
+    if (!dev.ok) {
+      die(`读不到本机设备码（${dev.reason}）：${dev.error} ⇒ 要么 --device-code <64hex>，要么显式 --no-device`)
+    }
+    device = { code: dev.code, algo: dev.algo, issuedAt: dev.issuedAt }
+  }
+}
+
+// 期限：`--days`（缺省 30）或 `--expires`（显式 ISO）
+const now = new Date()
+const days = argOf('--days') === null ? 30 : Number(argOf('--days'))
+if (!Number.isFinite(days) || days <= 0) die(`--days 必须是正数：${argOf('--days')}`)
+const expiresArg = argOf('--expires')
+let expiresAt = new Date(now.getTime() + days * 86400000).toISOString()
+if (expiresArg) {
+  const t = Date.parse(String(expiresArg))
+  if (!Number.isFinite(t)) die(`--expires 不是可解析时间：${expiresArg}`)
+  expiresAt = new Date(t).toISOString()
+}
+const graceDays = argOf('--grace') === null ? 14 : Number(argOf('--grace'))
+if (!Number.isFinite(graceDays) || graceDays < 0) die(`--grace 必须 ≥ 0：${argOf('--grace')}`)
+
+const file = {
+  v: version,
+  userId,
+  capabilities: [...new Set(allOf('--cap').map(String).filter(Boolean))].sort(),
+  verticals: [...new Set(allOf('--vertical').map(String).filter(Boolean))].sort(),
+  seats: argOf('--seats') === null ? 1 : Number(argOf('--seats')),
+  issuedAt: now.toISOString(),
+  expiresAt,
+  graceDays,
+  instanceHint: String(argOf('--instance') || 'self-sign'),
+  ...(device ? { device } : {}),
+}
+if (!Number.isFinite(file.seats) || file.seats < 1) die(`--seats 必须是正数：${argOf('--seats')}`)
+
+const signed = signLicenseFile(file, key.secret, { version })
+if (!signed.ok) fail(`签名失败（${signed.reason}${signed.warning ? `：${signed.warning}` : ''}）`)
+// **自验**：产物必须能在**独立入口**（verifyLicenseFile）验过 —— "我签完了"不算数
+const check = verifyLicenseFile(signed.file, { secret: key.secret, now: now.getTime() })
+if (!check.ok) fail(`自验失败（${check.reason}）：拒绝写出（别把一份自己都验不过的许可交给别人）`)
+
+const result = {
+  ok: true, empty: false, code: 0, reason: null,
+  tool: 'scripts/self-sign-license.mjs',
+  warning: '离线**自签**：真实签发在服务端（whyshu-svr）；签名是 HMAC 对称密钥 ⇒ 本工具不构成安全边界',
+  out, dryRun, written: false,
+  signatureVersion: version,
+  deviceSigned: version === 2,
+  payload: signed.payload,
+  licenseFile: signed.file,
+  keySource: secretSrc ? `secret-file:${secretSrc}` : 'env:ARGENT_LICENSE_SECRET',
+  verified: { ok: check.ok, reason: check.reason, state: check.inGrace ? 'grace' : (check.ok ? 'valid' : 'denied') },
+}
+
+if (!dryRun) {
+  try {
+    mkdirSync(dirname(out), { recursive: true, mode: 0o700 })
+    const tmp = `${out}.tmp`
+    writeFileSync(tmp, JSON.stringify(signed.file, null, 2) + '\n', { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, out)
+    result.written = true
+  } catch (e) {
+    rmSync(`${out}.tmp`, { force: true })
+    fail(`写入失败：${e.message}`)
+  }
+}
+
+if (asJson) {
+  console.log(JSON.stringify(result, null, 2))
+} else {
+  console.log(`${dryRun ? '🔎 [dry-run] 会自签' : '✅ 已自签'}离线许可（v${version}）：→ ${out}`)
+  console.log(`   账号：${userId} ｜ 席位：${file.seats} ｜ 到期：${expiresAt} ｜ 宽限 ${graceDays} 天`)
+  console.log(`   能力：${file.capabilities.join(',') || '(空 ⇒ 客户端拒一切能力)'} ｜ 业务线：${file.verticals.join(',') || '(空 = 不限)'}`)
+  console.log(`   设备：${device ? `已声明（${device.code.slice(0, 12)}…，进签名）` : '未声明（unbound；缺位也已进签名）'}`)
+  console.log(`   自验：${check.reason}（独立入口 verifyLicenseFile）`)
+  console.log(`   ⚠️ ${result.warning}`)
+  console.log('   下一步：node scripts/install-license.mjs --file <该文件> [--dry-run]')
+}
+process.exit(0)

package/engine/scripts/session-health-scan.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * session 全面体检（dry-run）：用当前 dsh 的 adoptSessionEvent 逐事件校验，
+ * **不 fail-fast**，列出全部不合格事件 + 上下文。用于评估一个会话的"修复面"。
+ * 用法：node scripts/session-health-scan.mjs <解压后的session.jsonl>
+ */
+import { readFileSync } from 'node:fs'
+import { requireDshScope } from './lib/dsh-scope.mjs'
+
+// 0.6.0 F1 修复批（2026-10-14）：体检**必须**在真宿主树上跑 ⇒ 拿不到 scope 就响亮失败
+// （⛔ 不用 passthrough 假路径继续 —— 旧写法在 npx 宿主上会 import 一个不存在的树）。
+let SCOPE
+try { SCOPE = requireDshScope({ what: '会话体检（session-health-scan）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const { adoptSessionEvent, foldSurface } = await import(`${SCOPE}/dsh-session/lib/index.js`)
+
+const file = process.argv[2]
+if (!file) { console.error('用法: node scripts/session-health-scan.mjs <session.jsonl>'); process.exit(1) }
+
+const lines = readFileSync(file, 'utf8').split('\n').filter((l) => l.trim())
+const parsed = lines.map((l) => JSON.parse(l))
+// 存储态日志第一行是 header（无 type），事件本身**不带 seq**（位置即序号）。
+// foldSurface 要求 seq 连续 ⇒ 这里去掉 header 行、按行号补 seq（2026-09-29 修：
+// 原实现直接把 parsed 喂给 foldSurface，一律报 "seq undefined is not contiguous"）。
+// header 行的形态实测是 `{type:'session', version:N, id, createdAt}`（**type 是字符串**，
+// 且**没有 seq**）——别用"type 不是字符串"来认它（2026-09-29 实测踩过）。
+const header = parsed[0] && (parsed[0].type === 'session' || typeof parsed[0].seq !== 'number') ? parsed[0] : null
+const events = (header ? parsed.slice(1) : parsed).map((ev, i) => (
+  typeof ev.seq === 'number' ? ev : { ...ev, seq: i }
+))
+if (header) console.log(`header: version=${header.version ?? '?'} id=${String(header.id || '').slice(0, 24)}`)
+console.log(`总事件: ${events.length}`)
+
+const bad = []
+for (const [i, ev] of events.entries()) {
+  try {
+    adoptSessionEvent(structuredClone(ev))
+  } catch (e) {
+    bad.push({ idx: i, seq: ev.seq, type: ev.type, err: e.message.slice(0, 160) })
+  }
+}
+
+console.log(`\n=== 不合格事件: ${bad.length} 个 ===`)
+for (const b of bad.slice(0, 40)) {
+  console.log(`  idx=${b.idx} seq=${b.seq} type=${b.type}`)
+  console.log(`      → ${b.err}`)
+}
+if (bad.length > 40) console.log(`  …还有 ${bad.length - 40} 个`)
+
+// 再跑 foldSurface（引用完整性）
+try {
+  foldSurface(events.map((e) => structuredClone(e)))
+  console.log('\n✅ foldSurface（surface 折叠）通过')
+} catch (e) {
+  console.log(`\n❌ foldSurface 失败: ${e.message.slice(0, 200)}`)
+}
+
+// 统计问题类型
+import { createHash } from 'node:crypto'
+const byType = {}
+for (const b of bad) { const k = `${b.type}: ${b.err.slice(0, 60)}`; byType[k] = (byType[k] || 0) + 1 }
+console.log('\n=== 问题分类 ===')
+for (const [k, v] of Object.entries(byType).sort((a, b) => b[1] - a[1])) console.log(`  ${v}× ${k}`)

package/engine/scripts/session-repair-tool-result-content.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * 会话修复器：把 tool/result 事件里 content 为**非数组**的 tool-result block 改写成
+ * ContentBlock 数组（`[{type:'text',text}]`），让被毒化的会话重新可加载。
+ *
+ * ## 为什么需要它（2026-09-18 事故）
+ * 插件工具的 `output.render` 返回裸字符串 ⇒ dsh-tools 把 render 返回值**直接**当作
+ * tool-result 的 content ⇒ 会话日志里落一条 `content:"…"`。运行中的会话不会立刻发现
+ * （surface 折叠只读内容），但**从磁盘加载时会跑 schema 校验**：
+ *   `dsh-session` → `assertMessageEventShape()` → "message must contain one tool-result block"
+ * ⇒ 该会话**打不开**（Failed to load history: … is corrupt）。
+ * **surface replace 救不了它** —— 校验针对**事件本身**，不是 surface 视图（2026-09-18 实测踩过）。
+ *
+ * ## 安全设计（改这段代码前务必读完）
+ * ① 会话日志是**多帧 zstd**，dsh **逐帧校验**、且**首帧是 header 行、必须恰好一行**
+ *    ⇒ **绝不整体重压成单帧**；只重写"包含目标事件的那一帧"，其余帧字节**原样保留**。
+ * ② 帧边界 = 扫描 zstd magic + 逐切片试解压（压缩数据里偶发假 magic，解不出来的自动并入前一帧）。
+ * ③ 只改目标 block 的 content；该行以外的所有行保持**原字节**（逐行比对验收）。
+ * ④ 写盘前用 **dsh 自己的校验器**终验：`adoptSessionEvent()`（逐事件 schema）+ `foldSurface()`（surface 折叠）。
+ * ⑤ 先写 `.tmp` 校验通过再 `rename` 原子替换；调用方负责先备份（默认 dry-run，不加 `--apply` 不落盘）。
+ * ⑥ **改之前先确认目标会话没有被运行中的服务打开**（否则会与服务写入竞争）。
+ *
+ * ## 用法
+ *   # 扫描所有会话，只报告（默认 dry-run）
+ *   node scripts/session-repair-tool-result-content.mjs --scan
+ *   # 扫描并修复（原子替换，建议先停掉/别打开这些会话）
+ *   node scripts/session-repair-tool-result-content.mjs --scan --apply
+ *   # 只处理指定会话（id 或 session 文件路径）
+ *   node scripts/session-repair-tool-result-content.mjs --session session-06732069-... [--apply]
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { zstdCompressSync } from 'node:zlib'
+import { FRAME_COMPRESS_OPTS, decodeSessionLines, splitFrames as splitFramesImpl } from './lib/zstd-frames.mjs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { requireDshScope } from './lib/dsh-scope.mjs'
+
+const argv = process.argv.slice(2)
+const APPLY = argv.includes('--apply')
+const SCAN = argv.includes('--scan') || !argv.includes('--session')
+const sessionArg = (() => { const i = argv.indexOf('--session'); return i === -1 ? null : argv[i + 1] })()
+// 0.6.0 F1 修复批（2026-10-14）：**必须**有 scope 才能干活 ⇒ 拿不到就响亮失败（⛔ 不用假路径继续）。
+// 旧写法 `const SCOPE = resolveDshScope()` 在 npx 宿主上会拿到一个**不存在**的路径 ⇒ 下面那条
+// 动态 import 报 ERR_MODULE_NOT_FOUND（看着像"dsh 坏了"，其实是探错树）。
+let SCOPE
+try { SCOPE = requireDshScope({ what: '会话修复（session-repair-tool-result-content）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh')
+
+const { adoptSessionEvent, foldSurface } = await import(`${SCOPE}/dsh-session/lib/index.js`)
+
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+// 与 dsh 写帧参数一致（常量也放共享库里，避免本地副本再次漂移）
+const CHECKSUM = FRAME_COMPRESS_OPTS
+
+let pass = 0, fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+// 切帧/解码实现见 lib/zstd-frames.mjs（与升级门禁共用一份；本文件此前是它的唯一副本）
+const splitFrames = (buf) => splitFramesImpl(buf)
+const decodeLines = (buf) => {
+  const { frames, lines } = decodeSessionLines(buf)
+  return { frames, lines }
+}
+
+/** 用 dsh 自己的校验器验收（逐事件 schema + surface 折叠）。 */
+function validateWithDsh(lines) {
+  const events = lines.map((l) => JSON.parse(l.raw))
+  for (const [i, ev] of events.entries()) {
+    if (ev.seq !== i) throw new Error(`事件下标 ${i} 与 seq ${ev.seq} 不一致`)
+    adoptSessionEvent(structuredClone(ev))
+  }
+  const fold = foldSurface(events.map((e) => structuredClone(e)))
+  const bad = fold.nodes.filter((q) => {
+    const ev = events[q]
+    return ev.type === 'tool/result' && !Array.isArray(ev.data.message.content[0].content)
+  })
+  return { events: events.length, surfaceNodes: fold.nodes.length, badSurfaceContent: bad.length }
+}
+
+/** 找出全部非法 tool-result（content 非数组）。 */
+function findPoison(lines) {
+  const hits = []
+  for (const line of lines) {
+    if (!line.raw.includes('"tool/result"')) continue
+    let ev
+    try { ev = JSON.parse(line.raw) } catch { continue }
+    if (ev.type !== 'tool/result') continue
+    const block = ev.data?.message?.content?.[0]
+    if (block?.type !== 'tool-result' || Array.isArray(block.content)) continue
+    hits.push({ line, ev, block })
+  }
+  return hits
+}
+
+function repairFile(path) {
+  console.log('='.repeat(74))
+  console.log(path)
+  const buf = readFileSync(path)
+  const { frames, lines } = decodeLines(buf)
+  const hits = findPoison(lines)
+  const health = validateWithDsh(lines)
+  console.log(`  帧 ${frames.length} 个｜事件行 ${lines.length}｜非法 tool-result ${hits.length} 条`)
+  if (hits.length === 0) {
+    ok(health.badSurfaceContent === 0 && health.events === lines.length,
+      `dsh 校验通过，无需修复（事件 ${health.events}｜surface 节点 ${health.surfaceNodes}｜非数组 content ${health.badSurfaceContent}）`)
+    return { repaired: 0 }
+  }
+
+  const touchedFrames = new Set()
+  for (const { line, ev, block } of hits) {
+    const wasKind = Array.isArray(block.content) ? 'array' : typeof block.content
+    const text = typeof block.content === 'string' ? block.content : JSON.stringify(block.content)
+    block.content = [{ type: 'text', text }]
+    line.raw = JSON.stringify(ev)
+    touchedFrames.add(line.frame)
+    console.log(`  🔧 seq ${ev.seq}（turn ${ev.data.turn} step ${ev.data.step}）：content ${wasKind} → ContentBlock[]（帧 ${line.frame}）`)
+  }
+
+  const rebuilt = new Map()
+  for (const f of touchedFrames) {
+    const raws = lines.filter((l) => l.frame === f).map((l) => l.raw)
+    rebuilt.set(f, zstdCompressSync(Buffer.from(raws.join('\n') + '\n', 'utf8'), CHECKSUM))
+  }
+  const out = Buffer.concat(frames.map((fr, i) => rebuilt.get(i) ?? buf.subarray(fr.start, fr.end)))
+
+  // 验收：结构 + dsh 校验器 + 未改动行逐字节一致
+  const redecoded = decodeLines(out)
+  const verdict = validateWithDsh(redecoded.lines)
+  const fixedSeqs = new Set(hits.map((h) => h.ev.seq))
+  const differ = redecoded.lines.map((l, i) => i).filter((i) => {
+    const seq = JSON.parse(lines[i].raw).seq
+    return !fixedSeqs.has(seq) && lines[i].raw !== redecoded.lines[i].raw
+  })
+  ok(verdict.badSurfaceContent === 0, `dsh 校验器通过（事件 ${verdict.events}｜surface 节点 ${verdict.surfaceNodes}｜surface 上非数组 content ${verdict.badSurfaceContent}）`)
+  ok(differ.length === 0, `除目标行外逐字节一致${differ.length ? `（差异行 ${differ.slice(0, 5)}）` : ''}`)
+  if (verdict.badSurfaceContent > 0 || differ.length > 0) { fail++; console.log('  ❌ 验收未通过，不写盘'); return { repaired: 0 } }
+
+  const tmp = `${path}.repair.tmp`
+  writeFileSync(tmp, out)
+  if (APPLY) { renameSync(tmp, path); console.log(`  ✅ 已原子替换（${buf.length} → ${out.length} 字节）`) }
+  else console.log(`  （dry-run：已写出 ${tmp}，未替换原文件；加 --apply 生效）`)
+  return { repaired: hits.length }
+}
+
+/** 收集目标文件。 */
+let files = []
+if (sessionArg) {
+  if (existsSync(sessionArg)) files = [sessionArg]
+  else {
+    const root = join(DSH_HOME, 'sessions')
+    for (const ws of readdirSync(root)) {
+      const p = join(root, ws, sessionArg, 'session.v3.jsonl.zstd')
+      if (existsSync(p)) files.push(p)
+    }
+    if (files.length === 0) { console.error(`❌ 找不到会话 ${sessionArg}`); process.exit(1) }
+  }
+} else if (SCAN) {
+  const root = join(DSH_HOME, 'sessions')
+  for (const ws of readdirSync(root)) {
+    const wsDir = join(root, ws)
+    if (!statSync(wsDir).isDirectory()) continue
+    for (const id of readdirSync(wsDir)) {
+      const p = join(wsDir, id, 'session.v3.jsonl.zstd')
+      if (existsSync(p)) files.push(p)
+    }
+  }
+}
+
+console.log(`扫描 ${files.length} 个会话文件${APPLY ? '（--apply：会写盘）' : '（dry-run：只报告，不改文件）'}\n`)
+let total = 0
+for (const f of files) {
+  try { total += repairFile(f).repaired } catch (err) { console.log(`  ❌ ${f}: ${err.message}`); fail++ }
+}
+
+console.log('\n' + '='.repeat(74))
+console.log(`合计需要修复的 tool-result：${total} 条｜校验通过 ${pass} / 失败 ${fail}`)
+if (fail > 0) process.exit(1)
+if (total === 0) console.log('✅ 没有发现被毒化的会话')
+else if (!APPLY) console.log('✅ dry-run 完成；确认无误后加 --apply 落盘（记得先备份）')
+else console.log('✅ 修复完成：这些会话现在可以正常加载了')

package/engine/scripts/setup.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# ============================================================
+# setup.sh — ML 卖家角色初始化（薄封装）
+# 核心逻辑已迁移到 init-ml.sh（同目录），本脚本保持向后兼容：
+# 老用户执行 setup.sh 等效于执行 init-ml.sh
+#
+# 用法:
+#   setup.sh                 完整初始化（等价 init-ml.sh）
+#   setup.sh --refresh-stores   仅刷新店铺选项
+#   setup.sh --reconfig      强制重新配置
+# ============================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INIT_ML="$SCRIPT_DIR/init-ml.sh"
+
+if [ ! -f "$INIT_ML" ]; then
+  echo "✗ 未找到 init-ml.sh（${INIT_ML}），请确认脚本完整分发" >&2
+  exit 1
+fi
+
+exec bash "$INIT_ML" "$@"