@whyshu/argent-engine 0.0.0-stage → 0.6.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" "$@"