@whyshu/argent-engine 0.7.2 → 0.7.4

package/engine/scripts/patches/verify-turn-outside-replace.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * verify-turn-outside-replace —— 补丁 `dsh-session-format-v3-to-v4--turn-outside-replace` 的自检。
+ *
+ * 这个补丁修的是**加载期**问题（不是写路径），它最危险的失效方式是"升级换了新树 ⇒ 补丁没跟着走 ⇒
+ * 某个旧会话突然打不开，而且没有运行期报错提示"（2026-10-17 本机就这么复现了一次）。故门禁要能
+ * 在**升级后立刻**判出"补丁在不在"。
+ *
+ * 判据两层：
+ *   ① 结构（始终跑）：目标模块里**确有**放宽逻辑（`Number.isSafeInteger(t)` + `t >= this.nextTurn` + 标记注释）；
+ *      且**没有**退回成裸 `this.requireTurn(event.type)`。
+ *   ② 行为（可选）：给了 `DSH_TURN_OUTSIDE_SESSION=<一个 v4 日志路径>` 时，用真实加载校验
+ *      （scripts/session-load-check.mjs，`validation:'current'`）证明它现在能过。
+ *      不给就**跳过并明说**（⛔ 不假装验过；本机已知样本：session-06732069 的 seq 30732）。
+ *
+ * 用法：node scripts/patches/verify-turn-outside-replace.mjs
+ *       DSH_TURN_OUTSIDE_SESSION=~/.dsh/sessions/…/session.v4.jsonl.zstd node …（会展开 ~）
+ * 退出码：0 通过（或"结构过 + 行为跳过"）/ 1 结构缺失 / 2 证据不足（scope 探不到）
+ */
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+
+let scope
+try { scope = requireDshScope({ what: '补丁自检（verify-turn-outside-replace）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(2) }
+
+const target = join(scope, 'dsh-session-format-v3-to-v4', 'lib', 'index.js')
+if (!existsSync(target)) {
+  console.error(`  ❌ 目标模块不存在：${target}（上游可能改名/改结构）`)
+  process.exit(1)
+}
+const src = readFileSync(target, 'utf8')
+
+let pass = 0
+let fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+ok(/Argent hotfix（0\.2\.0-rc\.2 移植版/.test(src), '放宽逻辑的标记注释在位（说明"这是本仓库的补丁，不是上游原生行为"）')
+ok(/if \(this\.turn === null\) \{\s*const t = data\["turn"\];\s*if \(!Number\.isSafeInteger\(t\) \|\| t >= this\.nextTurn\) throw new SessionFormatError/.test(src),
+  '放宽口径在位：turn 外只要求 data.turn 是已关闭的历史 turn（安全整数且 < nextTurn）')
+// 反向：不能退回成"一律要求打开 turn"（那样旧会话又会打不开）
+ok(!/if \(event\.type === "tool\/result" && event\["surfaceOp"\] !== "append"\) \{\s*this\.requireTurn\(event\.type\);\s*return;/.test(src),
+  '没有退回成裸 requireTurn（退回去 = 旧会话重新打不开）')
+
+// ② 行为（可选，不假装）
+const fixture = (process.env.DSH_TURN_OUTSIDE_SESSION || '').replace(/^~(?=$|\/)/, homedir())
+if (!fixture) {
+  console.log('  ⏭  行为校验跳过：未给 DSH_TURN_OUTSIDE_SESSION（结构判据已覆盖"补丁在不在"）')
+} else if (!existsSync(fixture)) {
+  console.log(`  ⏭  行为校验跳过：DSH_TURN_OUTSIDE_SESSION 指向的文件不存在（${fixture}）`)
+} else {
+  const r = spawnSync(process.execPath, ['--max-old-space-size=8192', join(import.meta.dirname, '..', 'session-load-check.mjs'), fixture], {
+    encoding: 'utf8', env: { ...process.env, DSH_SCOPE: scope },
+  })
+  const out = `${r.stdout || ''}${r.stderr || ''}`
+  ok(r.status === 0, `行为校验：该会话能过真实加载校验（${fixture}）${r.status === 0 ? '' : `\n     ${out.trim().split('\n').slice(-4).join('\n     ')}`}`)
+}
+
+console.log(`\n${fail === 0 ? '✅' : '❌'} verify-turn-outside-replace：通过 ${pass} / 失败 ${fail}`)
+process.exit(fail === 0 ? 0 : 1)

package/engine/scripts/poll-fulfillment.sh

@@ -102,7 +102,7 @@ pick_py() {
     [ -x "$c" ] || continue
     "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue   # 硬要求：配置/发票生成必需
     "$c" -c 'import PIL, playwright' 2>/dev/null || \
-      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：bash scripts/python-runtime.sh ensure）" >&2
     printf '%s' "$c"; return 0
   done
   return 1

package/engine/scripts/profile-doctor.mjs

@@ -518,7 +518,7 @@ function checkPackIntegrity() {
     const msg = '未找到 install.json（可能未按能力清单安装）'
     line('WARN', msg)
     record('warn', 'pkg-install-json-missing', msg,
-      `按能力安装：node install-argent.mjs --api-key <账号 API Key>（或核对 --dsh-home / ARGENT_INSTALL_JSON=${INSTALL_JSON}）`)
+      `按能力安装：由 @whyshu/argent 启动器安装（或核对 --dsh-home / ARGENT_INSTALL_JSON=${INSTALL_JSON}）`)
     return
   }
   const doc = readInstallJson(INSTALL_JSON)

package/engine/scripts/python-runtime.sh

@@ -23,9 +23,11 @@ case "$(uname -s 2>/dev/null || echo unknown)" in
 esac
 # P0-1（2026-10-08）：体检项 4 → 5（补 selenium）。理由：官方唯一推荐的驱动档位
 # （ZINIAO_MODE=selenium）此前在 venv 里**没装** ⇒ 选型开关静默撒谎、该档位从未运行过一次。
-# ⚠️ 本清单必须与 install-argent.mjs 的 pythonRuntimePlan().pkgs 和
+# ⚠️ 本清单必须与 scripts/lib/python-runtime.mjs 的 venvUsable(pkgs=…) 和
 #    scripts/lib/python-runtime.mjs 的 venvUsable(pkgs=…) 保持一致（缺一就会"体检红但 ensure 空转"）。
 PKGS=(openpyxl yaml PIL playwright selenium)
+# pip 安装名（import 名 ≠ 包名：yaml→pyyaml、PIL→pillow）
+PIP_PKGS=(openpyxl pyyaml pillow playwright selenium)
 # 交付纪律：本清单变更必须与"客户机 venv 补装 selenium（bash scripts/python-runtime.sh ensure）"
 # 同批落地，否则客户机体检会先变红（4/5）。
 
@@ -53,10 +55,20 @@ cmd_check() {
 }
 
 cmd_ensure() {
-  if [ ! -f "$REPO/install-argent.mjs" ]; then
-    echo "  ❌ 找不到 install-argent.mjs（本脚本需在 argent-dsh 仓库内运行）" >&2; return 2
+  # 旧安装器退役（2026-10-18）：直接创建持久 venv 并 pip 安装运行时依赖
+  local venv_dir; venv_dir="$(dirname "$VENV_BIN")"
+  local pybin="${PYTHON_BIN:-$(command -v python3 2>/dev/null || true)}"
+  if [ -z "$pybin" ] || [ ! -x "$pybin" ]; then
+    echo "  ❌ 找不到 python3；请先安装 Python 3.10+" >&2; return 2
   fi
-  node "$REPO/install-argent.mjs" --venv-only --dsh-home "${DSH_HOME:-$HOME/.dsh}" || return $?
+  if [ ! -x "$VENV_PY" ]; then
+    echo "  → 创建 venv：$venv_dir"
+    "$pybin" -m venv "$venv_dir" || return 1
+  fi
+  echo "  → 安装运行时依赖：${PIP_PKGS[*]}"
+  "$VENV_PY" -m pip install --upgrade pip >/dev/null 2>&1 || true
+  "$VENV_PY" -m pip install "${PIP_PKGS[@]}" || return $?
+  echo "  ✅ venv 就绪：$VENV_PY"
 }
 
 cmd_path() {

package/engine/scripts/release-argent.sh

@@ -69,7 +69,8 @@ REMOTE="${ARGENT_RELEASE_REMOTE:-$(git -C "$REPO_DIR" remote | head -1)}"
 # 2026-10-09：补 install.sh —— 官网 macOS/Linux 一行命令 `curl .../dl/install.sh | bash` 的入口
 # （旧的 `curl .../dl/install-argent.mjs | node` 因模块级相对 import 必然 ERR_MODULE_NOT_FOUND，
 #  已被 install.sh 取代）。`install-dsh.sh` 留在这里只为**存量老命令**仍能取到，是**遗留**件。
-CORE_FILES=("install-argent.mjs" "install.sh" "install-dsh.sh" "install.ps1" "argent-setup.md")
+# 旧一句话安装器已退役（2026-10-18）：只保留安装说明页；启动器由 @whyshu/argent 承担
+CORE_FILES=("argent-setup.md")
 # 目录级分发（--full 时启用；服务器对应目录有独立静态资源，非同名覆盖不删旧）
 DIR_FILES=("skills" "plugins")
 
@@ -184,7 +185,7 @@ pick_py() {
     [ -x "$c" ] || continue
     "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue
     "$c" -c 'import PIL, playwright' 2>/dev/null || \
-      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：运行 @whyshu/argent 启动器自检子命令按提示补装；或手动 pip 安装）" >&2
     printf '%s' "$c"; return 0
   done
   return 1
@@ -343,7 +344,7 @@ pick_py() {
     [ -x "$c" ] || continue
     "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue   # 硬要求：配置/发票生成必需
     "$c" -c 'import PIL, playwright' 2>/dev/null || \
-      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：运行 @whyshu/argent 启动器自检子命令按提示补装；或手动 pip 安装）" >&2
     printf '%s' "$c"; return 0
   done
   return 1
@@ -537,7 +538,7 @@ if [[ $FULL -eq 1 ]]; then
 else
   echo "  3. （未指定 --full：skills/ plugins/ 目录不同步——服务器有独立静态资源）"
 fi
-echo "  4. 验证：本地/服务器 md5 + curl -sI ${DL_URL}/install-argent.mjs"
+echo "  4. 验证：本地/服务器 md5 + curl -sI ${DL_URL}/argent-setup.md"
 
 if [[ $DRY_RUN -eq 1 ]]; then
   echo
@@ -594,11 +595,11 @@ for f in "${CORE_FILES[@]}"; do
     VERIFY_OK=0
   fi
 done
-http_code="$(curl -sI -o /dev/null -w '%{http_code}' "${DL_URL}/install-argent.mjs")"
+http_code="$(curl -sI -o /dev/null -w '%{http_code}' "${DL_URL}/argent-setup.md")"
 if [[ "$http_code" == "200" ]]; then
-  echo "  ✓ ${DL_URL}/install-argent.mjs HTTP ${http_code}"
+  echo "  ✓ ${DL_URL}/argent-setup.md HTTP ${http_code}"
 else
-  echo "  ✗ ${DL_URL}/install-argent.mjs HTTP ${http_code}（期望 200）"
+  echo "  ✗ ${DL_URL}/argent-setup.md HTTP ${http_code}（期望 200）"
   VERIFY_OK=0
 fi
 

package/engine/scripts/session-handoff.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// `session-handoff` —— 给老会话产出"续接摘要"（S4 收尾配套）
+// 目的：老格式会话日志一旦退役/升级后打不开，"工作能续上"由**摘要**承担。
+// 真实形状（2026-10-16 实测）：header `{type:"session",version,id,createdAt,cwd,agentPreset}`；
+// 事件 `{type,seq,time,data}`；用户输入在 `agent/inbox/spliced → data.inserted[].content[].text`。
+// 用法：--scan ｜ --write [--format v3|v4|all] [--limit N]
+// ⛔ 只读日志、只写摘要目录；多帧 zstd 按 magic 切帧逐帧解压。
+import { readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { zstdDecompressSync } from 'node:zlib'
+
+const args = process.argv.slice(2)
+const has = (f) => args.includes(f)
+const val = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d }
+const HOME = process.env.HOME || homedir()
+const ROOT = join(HOME, '.dsh', 'sessions')
+const OUT = join(HOME, '.dsh', 'argent', 'session-handoffs')
+const FORMAT = val('--format', 'v3'); const LIMIT = Number(val('--limit', '0')) || 0; const WRITE = has('--write')
+const DAYS = Number(val('--days', '10')) || 0        // 只处理最近 N 天内动过的主会话（0 = 全部）
+const CHILDREN = has('--include-children')          // 默认**排除**子会话（delegationDepth>0）
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+function readText(file) {
+  const buf = readFileSync(file); const pos = []; let i = 0
+  while ((i = buf.indexOf(MAGIC, i)) !== -1) { pos.push(i); i += 4 }
+  if (!pos.length) return ''
+  pos.push(buf.length); let out = ''
+  for (let k = 0; k < pos.length - 1; k++) { try { out += zstdDecompressSync(buf.subarray(pos[k], pos[k + 1])).toString('utf8') } catch { /* 坏帧跳过 */ } }
+  return out
+}
+/** 递归找所有文本块（形状容错：content[]/inserted[]/text） */
+function texts(node, acc = []) {
+  if (!node) return acc
+  if (typeof node === 'string') { if (node.trim()) acc.push(node.trim()); return acc }
+  if (Array.isArray(node)) { for (const x of node) texts(x, acc); return acc }
+  if (typeof node === 'object') {
+    if (typeof node.text === 'string' && node.text.trim()) acc.push(node.text.trim())
+    for (const k of ['content', 'inserted', 'message', 'parts', 'blocks', 'data']) if (node[k] !== undefined) texts(node[k], acc)
+  }
+  return acc
+}
+const clean = (s, n) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, n)
+const isUser = (e) => /inbox|user/.test(String(e.type)) || (e.data && e.data.source && e.data.source.kind === 'user')
+
+function summarize(file, id, project, ver) {
+  const lines = readText(file).split('\n').filter(Boolean)
+  let header = null, ts0 = null, ts1 = null, events = 0
+  const users = [], assistants = [], all = []
+  for (const l of lines) {
+    let e; try { e = JSON.parse(l) } catch { continue }
+    if (e.type === 'session') { header = e; continue }
+    events++
+    const t = e.time || (e.data && e.data.time)
+    if (t) { const iso = new Date(t).toISOString(); ts0 = ts0 || iso; ts1 = iso }
+    const blocks = texts(e.data ?? e)
+    if (!blocks.length) continue
+    const joined = clean(blocks.join(' ｜ '), 600)
+    all.push(joined)
+    if (isUser(e)) users.push(joined); else assistants.push(joined)
+  }
+  const todos = all.join('\n').split(/｜|\n/).map((s) => s.trim()).filter((l) => /(^\s*-\s*\[ \])|TODO|待办|下一步|下一步是/.test(l)).slice(0, 10)
+  return { id, project, ver, file, bytes: statSync(file).size, created: header && header.createdAt ? new Date(header.createdAt).toISOString() : null,
+    ts0, ts1, events, turns: users.length + assistants.length, preset: (header && header.agentPreset) || '', cwd: (header && header.cwd) || '', depth: (header && header.delegationDepth) || 0,
+    title: clean(users[0], 140), lastUser: clean(users[users.length - 1], 400), lastAsst: clean(assistants[assistants.length - 1], 400), todos }
+}
+
+function walk(dir, out = []) {
+  let es = []; try { es = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of es) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) walk(p, out)
+    else {
+      const m = e.name.match(/^session\.(v\d+)\.jsonl\.zstd$/)
+      if (m && (FORMAT === 'all' || m[1] === FORMAT)) out.push({ file: p, ver: m[1], id: (p.match(/session-([0-9a-f-]{8,})/) || [])[1] || p.split('/').slice(-2)[0].replace(/^session[.-]?/, '') || e.name, project: p.replace(ROOT + '/', '').split('/')[0] })
+    }
+  }
+  return out
+}
+
+const CUT = DAYS ? Date.now() - DAYS * 86400000 : 0
+const walkAll = walk(ROOT)
+const recent = DAYS ? walkAll.filter((x) => statSync(x.file).mtimeMs >= CUT) : walkAll
+const all = recent.sort((a, b) => statSync(b.file).mtimeMs - statSync(a.file).mtimeMs)
+const list = LIMIT ? all.slice(0, LIMIT) : all
+const rows = []; let bad = 0
+for (const it of list) { try { rows.push(summarize(it.file, it.id, it.project, it.ver)) } catch { bad++ } }
+const kept = CHILDREN ? rows : rows.filter((r) => !r.depth)
+for (const r of rows) if (!kept.includes(r)) { /* 子会话：跳过（--include-children 可纳入） */ }
+const titled = kept.filter((r) => r.title).length
+console.log(JSON.stringify({ ok: true, days: DAYS, candidates: all.length, childrenExcluded: CHILDREN ? 0 : rows.length - kept.length, kept: kept.length, format: FORMAT, unreadable: bad, withTitle: titled, write: WRITE }))
+if (!WRITE) { console.log(JSON.stringify(kept.slice(0, 3).map((r) => ({ id: r.id.slice(0, 8), ver: r.ver, preset: r.preset, events: r.events, turns: r.turns, title: r.title.slice(0, 70) })), null, 1)); process.exit(0) }
+mkdirSync(OUT, { recursive: true })
+const slug = (s) => s.replace(/[^\w.-]/g, '_')
+for (const r of kept) {
+  writeFileSync(join(OUT, `${slug(r.project)}__${r.id}.${r.ver}.md`), [
+    `# 会话续接摘要｜${r.id}（${r.ver}）`, '',
+    `- 项目：\`${r.project}\`　cwd：\`${r.cwd}\`　preset：\`${r.preset}\``,
+    `- 日志：\`${r.file}\`（${(r.bytes / 1024).toFixed(0)}KB，${r.events} 事件 / ${r.turns} 轮）`,
+    `- 时间：${(r.created || r.ts0 || '?').slice(0, 16).replace('T', ' ')} → ${(r.ts1 || '?').slice(0, 16).replace('T', ' ')}`, '',
+    '## 首轮需求（标题）', '', r.title || '（未提取到）', '',
+    '## 最后一轮用户输入', '', r.lastUser || '（未提取到）', '',
+    '## 最后一条助手输出', '', r.lastAsst || '（未提取到）', '',
+    '## 疑似待办 / 下一步（原文行）', '', ...(r.todos.length ? r.todos.map((t) => `- ${clean(t, 200)}`) : ['（未提取到）']), '',
+    '> ⚠️ 自动提取（best effort）：日志退役后，续接以本摘要 + 仓库文档/提交为准。', ''].join('\n'))
+}
+writeFileSync(join(OUT, 'INDEX.md'), ['# 老会话续接摘要索引', '', `- 生成：${new Date().toISOString().slice(0, 16).replace('T', ' ')}`,
+  `- 范围：format=${FORMAT} ｜ 近 ${DAYS} 天 ｜ 本次 ${kept.length} 条（候选 ${all.length} 条）｜ 有标题 ${titled} 条`, '',
+  '| 会话 | 版本 | preset | 时间 | 标题 | 摘要 |', '|---|---|---|---|---|---|',
+  ...rows.map((r) => `| \`${r.id.slice(0, 8)}\` | ${r.ver} | ${r.preset} | ${(r.created || r.ts0 || '?').slice(0, 10)} | ${(r.title || '').replace(/\|/g, '/').slice(0, 56)} | [md](${slug(r.project)}__${r.id}.${r.ver}.md) |`), ''].join('\n'))
+console.log(`✅ 已写 ${kept.length} 份摘要（有标题 ${titled}）+ INDEX.md ⇒ ${OUT}`)

package/engine/scripts/session-load-check.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * session-load-check —— 用**真实加载路径的校验**回放 session 日志（只读）。
+ *
+ * 与 `scripts/patches/verify-session-migration.mjs` 的分工（两者都必要，别互相替代）：
+ *   · verify-session-migration：跑**格式迁移链**（v0→v4），`validation: 'transformed'`
+ *     ⇒ 只回答"能不能迁移"；v4 文件是恒等迁移，**不会**触发 v4 结构校验。
+ *   · 本工具：`validation: 'current'` ⇒ 触发 `restoreCurrent()`（= 宿主真正加载时走的校验，
+ *     含 turn/step 作用域、surface 折叠、工具生命周期等）。
+ *
+ * 为什么要它（2026-10-17 实测）：主会话 06732069 在 0.2.0 上打不开
+ * （`SessionFormatError: tool/result is outside an open turn`），而 verify-session-migration
+ * 对同一个文件**判绿**——因为迁移校验不跑 v4 结构校验。别再拿迁移绿灯当"会话能打开"的证据。
+ *
+ * 用法：
+ *   DSH_SCOPE=<…/@deepseek-ai> node scripts/session-load-check.mjs <session.vN.jsonl.zstd> [...]
+ *   不给文件 ⇒ 校验"当前用户近 N 天最常打开的几个 v4 会话"（默认 3 个，按 mtime 取最新）。
+ * 退出码：0 全绿 / 1 有失败 / 2 用法或环境错误。
+ *
+ * 边界（诚实）：只做**读取 + 校验**，不迁移、不写任何文件；v3 及更早日志的 v3→v4 迁移需要
+ * 子会话事实，本工具传空数组 ⇒ 对 v3 文件的结论仅作参考（该场景用 verify-session-migration）。
+ */
+import { createRequire } from 'node:module'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { requireDshScope } from './lib/dsh-scope.mjs'
+import { decodeSessionLines } from './lib/zstd-frames.mjs'
+
+let scope
+try { scope = requireDshScope({ what: 'session 加载校验（session-load-check）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(2) }
+const requireGlobal = createRequire(scope.replace(/\/?$/, '/'))
+const { createSessionFormatCatalogWithChildren, sessionFormatCatalog } =
+  requireGlobal('@deepseek-ai/dsh-session-format-catalog')
+
+/** 取最近修改的 v4 日志（默认样本源）。 */
+function recentV4(limit = 3) {
+  const root = join(process.env.DSH_HOME || join(process.env.HOME || '', '.dsh'), 'sessions')
+  const out = []
+  const walk = (dir, depth = 0) => {
+    let entries
+    try { entries = readdirSync(dir) } catch { return }
+    for (const name of entries) {
+      const p = join(dir, name)
+      let st
+      try { st = statSync(p) } catch { continue }
+      if (st.isDirectory()) { if (depth < 2) walk(p, depth + 1); continue }
+      if (/^session\.v4\.jsonl\.zstd$/.test(name)) out.push({ p, mtime: st.mtimeMs })
+    }
+  }
+  walk(root)
+  return out.sort((a, b) => b.mtime - a.mtime).slice(0, limit).map((x) => x.p)
+}
+
+function checkOne(file) {
+  let decoded
+  try { decoded = decodeSessionLines(readFileSync(file)) } catch (e) {
+    return { ok: false, why: `解压失败：${e.message}` }
+  }
+  const { header: headerRaw, lines } = decoded
+  const header = JSON.parse(headerRaw.split('\n')[0])
+  // v3 及更早：v3→v4 迁移需要子会话事实；本工具传空数组 ⇒ 结论仅供参考
+  const catalog = createSessionFormatCatalogWithChildren
+    ? createSessionFormatCatalogWithChildren([])
+    : sessionFormatCatalog
+  let restore
+  try { restore = catalog.createRestore(header, { recovery: 'strict', validation: 'current' }) } catch (e) {
+    return { ok: false, why: `createRestore 失败：${e.message}` }
+  }
+  let n = 0
+  for (const { raw } of lines) {
+    if (!raw.trim()) continue
+    n += 1
+    let ev
+    try { ev = JSON.parse(raw) } catch (e) { return { ok: false, why: `行 ${n} JSON 解析失败：${e.message}` } }
+    try { restore.decodeRow(ev) } catch (e) {
+      return { ok: false, why: `行 ${n} / seq ${ev.seq} / ${ev.type}：${e.name}: ${e.message}` }
+    }
+  }
+  try {
+    const artifact = restore.finish()
+    return { ok: true, detail: `v${header.version} → v${artifact.header.version}，事件 ${artifact.events.length}，行 ${n}`, header }
+  } catch (e) {
+    return { ok: false, why: `finish：${e.name}: ${e.message}` }
+  }
+}
+
+const files = process.argv.slice(2)
+const targets = files.length ? files : recentV4(3)
+if (targets.length === 0) { console.error('  ❌ 没有可校验的会话文件（给个路径，或确认 DSH_HOME/sessions 存在）'); process.exit(2) }
+
+let failed = 0
+for (const file of targets) {
+  const r = checkOne(file)
+  if (r.ok) {
+    console.log(`✅ ${file}`)
+    console.log(`   ${r.detail}`)
+  } else {
+    failed += 1
+    console.log(`❌ ${file}`)
+    console.log(`   ${r.why}`)
+  }
+}
+console.log(`\n${failed === 0 ? '✅' : '❌'} session-load-check：${targets.length - failed} 通过 / ${failed} 失败`)
+process.exit(failed > 0 ? 1 : 0)

package/engine/scripts/sync-scripts.sh

@@ -198,7 +198,7 @@ deliver_faces() {
 # ⚠️ `install-argent.mjs` 同族（2026-10-10 实测）：克隆里它是**旧版**（仓库 ff4069d6 vs 克隆
 #   618f4bbd）⇒ 克隆侧跑 `--agent hr` 报「未知参数: hr」（新 flag 根本不存在）。
 #   它此前只靠 `argent-upgrade.mjs` 自举更新（滞后窗口 = 客户机装到旧安装器的风险）⇒ 一并进根文件清单。
-ROOT_FILES=(VERSION install-argent.mjs)
+ROOT_FILES=(VERSION)
 deliver_root_files() {
   local f
   for f in "${ROOT_FILES[@]}"; do

package/engine/scripts/xzh-browser.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# 鑫中航常驻浏览器：启动/停止/状态（保留一个标签页给登录态）
+set -u
+ROOT="${ARGENT_DSH_HOME:-$HOME/.argent-dsh}"
+DATA="${ARGENT_DATA_DIR:-$HOME/.dsh/argent}"
+PY="$DATA/venv/bin/python3"
+[ -x "$PY" ] || PY="$(command -v python3)"
+LOG="$DATA/xzh-browser.log"
+PORT="${XZH_CDP_PORT:-9223}"
+case "${1:-status}" in
+  start)
+    if curl -s -m 2 "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; then
+      echo "already running: CDP $PORT"; exit 0
+    fi
+    mkdir -p "$DATA"
+    nohup "$PY" "$ROOT/scripts/xzh_browser.py" >>"$LOG" 2>&1 &
+    echo $! > "$DATA/xzh-browser.pid"
+    for i in $(seq 1 20); do
+      if curl -s -m 1 "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; then
+        echo "started: CDP $PORT"; exit 0
+      fi
+      sleep 1
+    done
+    echo "start failed; see $LOG"; tail -20 "$LOG"; exit 1
+    ;;
+  stop)
+    PID_FILE="$DATA/xzh-browser.pid"
+    if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; rm -f "$PID_FILE"; fi
+    # 只杀监听该调试端口的 Chrome（避免误杀用户其它窗口）
+    PIDS=$(lsof -tiTCP:"$PORT" -sTCP:LISTEN 2>/dev/null || true)
+    [ -n "$PIDS" ] && kill $PIDS 2>/dev/null || true
+    echo stopped
+    ;;
+  status)
+    if curl -s -m 2 "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; then echo "running CDP $PORT"; else echo "not running"; exit 1; fi
+    ;;
+esac

package/engine/scripts/xzh_browser.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""鑫中航常驻浏览器：保留一个标签页/登录态；invoice_stageb 通过 CDP 复用。
+
+用法:
+  python3 scripts/xzh_browser.py             # 前台常驻（调试）
+  nohup ... > ~/.dsh/argent/xzh-browser.log 2>&1 &
+启动后监听 127.0.0.1:9223；invoice_stageb 会自动 connect_over_cdp。
+"""
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402
+
+DATA = Path(resolve_data_dir()['dir'])
+CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+PROFILE = str(DATA / "chrome-profile-xinhang")
+PORT = int(os.environ.get("XZH_CDP_PORT", "9223"))
+
+
+def main():
+    from playwright.sync_api import sync_playwright
+    mapping = json.load(open(DATA / "invoice-mapping.json"))
+    url = mapping["xinzhonghang"]["url"]
+    home = url.replace("/Login/VueLoginView", "") + "/home/EleIndex?lang=cn"
+    p = sync_playwright().start()
+    ctx = p.chromium.launch_persistent_context(
+        user_data_dir=PROFILE,
+        executable_path=CHROME,
+        headless=False,
+        viewport={"width": 1440, "height": 900},
+        accept_downloads=True,
+        args=[f"--remote-debugging-port={PORT}"],
+    )
+    page = ctx.pages[0] if ctx.pages else ctx.new_page()
+    try:
+        page.goto(home, timeout=20000, wait_until="domcontentloaded")
+    except Exception as exc:
+        print(f"⚠️ 打开首页失败（保留已开标签）: {exc}", flush=True)
+    print(f"✅ 鑫中航常驻浏览器已启动：CDP http://127.0.0.1:{PORT}｜profile={PROFILE}", flush=True)
+    while True:
+        time.sleep(30)
+
+
+if __name__ == "__main__":
+    main()

package/engine/skills/ml-fulfillment-sop/references/pitfalls.md

@@ -75,3 +75,33 @@
 - **口径变化（有意）**：新文案含「需运营…」⇒ 分类从 `needs_agent`（唤醒角色去猜）
   变为 `needs_human`（落卡等人、运营改商品）。⛔ 这是本事故要的结果，不是副作用。
 
+## 卡票先问 hub 真相；⛔ 别单步硬跑（2026-10-16 现场 79301358）
+
+**症状**：lip 表里一张票 `FULL状态=失败`（如「步骤7 上传箱唛失败」），但门户侧其实**早就全做完了**
+（运营手工做完 / 页面早已下载完标签），反复重跑仍旧失败。
+
+**根因（两条，都要记住）**：
+1. **单步模式会绕过前置判定**：`orchestrator.py --mode step --step 7 …` 直接进步骤，**跳过了**
+   `step1_prepare` 里那句「**先问 hub 真相，再下结论**」——那句会按 hub-v2 三项
+   （预约已取消 ∧ 产品标签已下载 ∧ 箱唛已下载）判定「**运营手动完成**」并结票。
+   ⇒ 用单步"复现失败"会把一张**其实已完成**的票重新打成失败。
+2. **「Declara al menos」不一定是残留**：旧逻辑把点击 `Generar etiquetas` 之前就存在的该提示
+   一律当"残留文案"⇒ 干等 30s 后以"平台侧异常"收口（**冤枉平台**，运营也拿不到可执行信息）。
+   KB-136 起改为：先读 checkbox 勾选进度 + **Andes 勾选态**（`#2/#3`），声明确实没做完时
+   重勾重试、仍不行则以 `[declaration_incomplete] 已声明 N/M` 精确收口。
+   ⚠️ 注意 `checkbox_total` **包含我们故意跳过的 `#1`（bultos）**，所以"勾选数 < 总数"本身
+   **不是**声明未完成的证据（正常态就是 2/4）。
+
+**正确处置顺序（⛔ 不要一上来就 `--mode step`）**：
+```bash
+# ① 先问 hub 真相（只读探针；必须带 --store-name，否则会解析成别的店）
+python3 scripts/orchestrator.py --mode hub-status --record-id <rec> --shipment-id <货件号> \
+        --store-name "<店铺名>"
+# ② 若 operationally_complete=true ⇒ 认定「运营手动完成」并**置位**（2026-10-16 起同时写 FULL状态=已完成）
+python3 scripts/orchestrator.py --mode hub-status --hub-write-note \
+        --record-id <rec> --shipment-id <货件号> --store-name "<店铺名>"
+# ③ 门户/数据侧确实没做完 ⇒ 才进单步或定点续跑（有失败收口时，步骤7 现在会先自己问一次 hub）
+```
+
+**卡住不动的票**（触发器不再认领）：`flow_stale.py --flow <流程> [--requeue]` 回收；
+**流程跑得动但不接票**：`flow_trigger.sh --flow <流程>` 手动一轮（与定时器同一路径）。

package/engine/skills/ml-full-appointment/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ml-full-appointment
+description: 美客多 FULL 抢预约对话与 ERP 任务创建（BOT/gateway 只做桥；真正预约由 ERP worker 执行）。处理 SKU/货件号、字段缺口、任意日期范围、二次确认、停止与不跑步骤5-8。
+---
+
+# 美客多 FULL 抢预约（ml-full-appointment）
+
+## 定位
+
+飞书 @美客多 FULL BOT 只是**对话/确认桥梁**：
+
+- BOT/gateway 负责：识别意图、补齐字段、二次确认、创建 ERP 预约任务、反馈“已受理/已停止”；
+- **BOT/gateway 不轮询、不操作浏览器**；
+- 真正抢预约由 Huangwei 的 **ERP appointment worker** 执行；
+- 成功后通知发起人；**只到预约成功，不进入 FULL 步骤 5–8**。
+
+## 触发意图
+
+用户 @BOT 说类似：
+
+- “抢预约 SKU HW-MX-168，店铺 墨西哥-1店-子账号，10/20 到 10/25”
+- “抢货件 79922453 的预约，今天起 2 天内”
+- “帮我抢 FULL 预约，30 天内的”
+
+## 必须收集的字段
+
+- **店铺**（必填；SKU 可能跨店）
+- **SKU 或货件号**（二选一；货件号优先续传）
+- **日期窗口**：用户本次给的具体要求，两种模式：
+  - 用户说 `最近5天/最近5个可用日` ⇒ `dateMode=available_days`, `availableDays=5`（跳过 disabled，取最近 5 个可选日，不是日历固定 5 天）；
+  - 用户给绝对范围 `2026-10-20 ~ 2026-10-25` ⇒ `dateMode=range`, `dateFrom/dateTo`；
+- 若只给 SKU：**不读取 lip 表**，必须通过对话补齐 FULL 建单所需字段：店铺、SKU、数量 `quantity`、箱数 `boxCount`（产品名可选）；缺什么问什么；
+- 若给货件号：校验该货件存在，店铺/记录一致，当前进度允许预约；
+- 所有参数以任务形式传给 ERP，worker 只使用任务参数；
+- 轮询间隔默认 60 秒（后台参数，不需用户每次提供）。
+
+不要把 7/14 天写成固定变量；**每个任务保存用户本次的 dateFrom/dateTo**。
+
+## 二次确认（必须）
+
+创建任务前回显一段摘要，例如：
+
+> 确认信息：店铺 墨西哥-1店-子账号；SKU HW-MX-168；预约日期 2026-10-20 ~ 2026-10-25；只抢预约，不继续箱唛/发票。回复「开始」才执行。
+
+用户明确说「开始」/「确认」后才创建 ERP 任务；未确认不得创建。
+
+## 创建 ERP 任务
+
+BOT/gateway 通过确定性 CLI 创建任务（不在会话里轮询）：
+
+```bash
+node ~/.argent-dsh/scripts/appointment-create.mjs --json '<任务 JSON>' [--chat-id <当前群> --open-id <发起人open_id>]
+```
+
+返回 `{ ok, id, status }` 后，BOT 回复“已创建任务 #id”。
+
+尽量传 `--chat-id`/`--open-id`，worker 完成/停止时服务端会用 FULL BOT 通知发起人并附逐日结果。
+
+CLI 内部读取 `~/.dsh/argent/config.json` 的 `apiKey`（或 `WHYSHU_API_KEY`），调用：
+
+```
+POST /api/argent/v1/tenants/<tenantAppId>/appointments
+{
+  "store": "...",
+  "sku": "...",            // 或 shipmentNo
+  "shipmentNo": "...",
+  "quantity": 100,          // SKU-only 必填
+  "boxCount": 10,           // SKU-only 必填
+  "productName": "",        // 可选
+  "dateMode": "available_days",
+  "availableDays": 5,
+  // range 模式才填 dateFrom/dateTo
+  "windowText": "10/20-10/25",
+  "pollIntervalSec": 60
+}
+```
+
+返回任务 `queued` 后，BOT 回复：
+
+> 已创建抢预约任务 #<id>，worker 会按 60 秒一轮执行；回复「停止」可终止。
+
+## 用户停止
+
+用户说「停止」时运行：
+
+```bash
+node ~/.argent-dsh/scripts/appointment-stop.mjs <AppointmentTask id>
+```
+
+只置停止请求，worker 收尾；BOT 不轮询任务状态。
+
+## 禁止
+
+- ⛔ 不在 BOT/gateway 会话里执行浏览器操作或循环轮询；
+- ⛔ 不跑 FULL 步骤 5–8（箱唛/标签/发票/完成态）；
+- ⛔ 不把 7/14 天硬编码；不替用户改日期范围；
+- ⛔ 未二次确认不创建任务；
+- ⛔ 同一店铺预约仍走 ERP/编排器的同店步骤4互斥锁，避免与 FULL 任务串预约。

package/engine/version.mjs

@@ -1 +1 @@
-export const VERSION = "0.7.2"
+export const VERSION = "0.7.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyshu/argent-engine",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Argent 引擎（L1）：流程/台账/重试/守卫/审计/浏览器自动化 —— 逐字节来自 argent-dsh 仓库",
   "type": "module",
   "engines": {