dsh-soul 0.7.0 → 0.7.2

package/scripts/verify-live-prompt.mjs

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+/**
+ * scripts/verify-live-prompt.mjs — 宿主实现层探针（配置生效链路的底座）
+ *
+ * 为什么需要它：「改配置 → 下一轮生效」依赖两条通道，本脚本钉住其中的底座 ——
+ * section 的 `text` provider 在每次装配时都被重新求值。这属于**宿主行为**：
+ * 一旦宿主改成缓存 section 文本，这条通道会**静默失效**（不报错，只是配置
+ * 不再经它生效 —— 最难排查的一类问题）。
+ *
+ * 注意（0.7.1 的实测教训）：本脚本 20 项全绿，只证明「宿主每次装配都会重新求值
+ * 并提交变化后的文本」这一层成立，**不等于**会话进行中改配置就一定生效 ——
+ * 0.7.1 曾据此移除活动会话注入，实测出现了「会话进行中改配置不生效」，
+ * 因此注入已恢复（见 verify-e2e-prompt.mjs 的 E13 / E16）。本脚本保留为
+ * 宿主行为探针：DSH 升级后跑一次，可确认这条底座机制没有被改掉。
+ *
+ * 三层证据：
+ *   A 真实服务 —— 真实 `SystemPrompt` + 真实 Cordis Context：`assemble()` 每次
+ *      调用都重新求值函数式 `text`（无缓存、不需要重新注册）；
+ *   B 真实投影 —— 原样切片 `dsh-agent-loop` 的 `SystemPromptProjection`：
+ *      文本变化才提交新的 system 快照，相等则不提交（不堆消息）；
+ *   C 源文本契约 —— `preStep` 每个 step 都调 `assemble`、`assemble` 对函数式
+ *      text 不舍缓存。
+ * 每层都配**判断力对照**：把关键条件改坏，对应用例必须失败 —— 否则断言没有判断力。
+ *
+ * 用法：
+ *   node scripts/verify-live-prompt.mjs                # 自动定位 DSH
+ *   node scripts/verify-live-prompt.mjs --dsh <目录>   # 指定 DSH 安装目录
+ * 退出码：0 = 通过（或定位不到 DSH，跳过）；1 = 存在失败项。
+ */
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join, resolve, sep } from 'node:path'
+import { homedir } from 'node:os'
+import { assertCount, skipExit } from './lib/skip-report.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = resolve(HERE, '..')
+
+// 本脚本要跑多少项断言（A 层 6 + A 判断力 2 + B 层 6 + B 判断力 3 + C 层 3）。跳过的
+// 提示与 --strict 都依赖它；B 层若因宿主实现变化而跳过，末尾的校验会让本次运行失败 ——
+// 「宿主改了实现」正是这条链路最需要被通知的事，不该安静地少跑几项还报通过。
+const EXPECTED_ASSERTIONS = 20
+
+const argv = process.argv.slice(2)
+const argValue = (flag) => {
+  const i = argv.indexOf(flag)
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : undefined
+}
+
+// ==================== 定位 DSH ====================
+
+// 锚点顺序决定「这一跑到底验证了哪一份宿主」——此前它是隐式的、且以 process.cwd() 开头，
+// 而 createRequire 会从锚点**向上逐级找 node_modules**：换个目录跑就可能解析到另一份 DSH
+// 安装（本机同时存在 D:\ 下的 0.2.1-alpha.1 与用户主目录 pnpm store 里的 0.1.0-rc.8，
+// 后者不支持 section 的 interpolate 选项）。同一份插件因此在不同目录跑出不同结论 ——
+// 对一份「护栏」脚本来说，这本身就是缺陷。
+//
+// 现在的顺序：显式指定 > 装了本插件的 profile（真正会加载这份代码的运行时）
+// > 其它 profile > 插件自身 node_modules > cwd（最后兜底）。
+function profilesDir() {
+  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'profiles')
+}
+
+function anchors() {
+  const list = [join(PKG_DIR, 'node_modules'), PKG_DIR]
+  const explicit = explicitDshDir()
+  if (explicit) list.unshift(resolve(explicit))
+
+  const profiles = profilesDir()
+  if (existsSync(profiles)) {
+    let names = []
+    try {
+      names = readdirSync(profiles)
+    } catch {
+      /* 读不到就只用其它锚点 */
+    }
+    // 装了 dsh-soul 的 profile 排前面：那份运行时才是这份代码真正的去处
+    const hosts = names.filter((p) => existsSync(join(profiles, p, 'node_modules', 'dsh-soul')))
+    const others = names.filter((p) => !hosts.includes(p))
+    for (const p of [...hosts, ...others]) list.push(join(profiles, p))
+  }
+
+  list.push(process.cwd())
+  return list
+}
+
+function explicitDshDir() {
+  return argValue('--dsh') || process.env.DSH_INSTALL_DIR || null
+}
+
+/** 显式指定的目录是否真的指向一份 DSH 安装（接受三种常见形状）。 */
+function looksLikeDshInstall(dir) {
+  if (!existsSync(dir)) return false
+  if (existsSync(join(dir, 'node_modules', '@deepseek-ai', 'dsh'))) return true
+  const manifest = join(dir, 'package.json')
+  if (!existsSync(manifest)) return false
+  try {
+    return JSON.parse(readFileSync(manifest, 'utf8')).name === '@deepseek-ai/dsh'
+  } catch {
+    return false
+  }
+}
+
+function resolveFrom(anchor, spec) {
+  try {
+    return createRequire(join(anchor, 'noop.js')).resolve(spec)
+  } catch {
+    return null
+  }
+}
+
+/** 返回宿主子包的解析锚点列表：DSH 自身与其嵌套的 @deepseek-ai 依赖目录。 */
+function hostAnchors() {
+  const dshPkg = anchors().map((a) => resolveFrom(a, '@deepseek-ai/dsh/package.json')).find(Boolean)
+  const list = [...anchors()]
+  if (dshPkg) {
+    const dshDir = dirname(dshPkg)
+    list.unshift(join(dshDir, 'node_modules', '@deepseek-ai', 'dsh'), join(dshDir, 'node_modules'), dshDir)
+  }
+  return list
+}
+
+/**
+ * 列出所有能解析出宿主子包的**不同** DSH 副本。
+ * 多于一份时必须打印出来：报告要说清验证的是哪一份实现，否则结论无法复核。
+ */
+function hostCandidates() {
+  const seen = new Map()
+  for (const anchor of hostAnchors()) {
+    const hit = resolveFrom(anchor, '@deepseek-ai/dsh-system-prompt')
+    if (!hit) continue
+    const entry = realDshEntry(hit)
+    if (!seen.has(entry)) seen.set(entry, { entry, anchor })
+  }
+  return [...seen.values()]
+}
+
+/** 从 dsh-system-prompt 的入口回推到所属 DSH 安装根（pnpm store 里的副本也算）。 */
+function realDshEntry(spEntry) {
+  const marker = `${sep}@deepseek-ai${sep}dsh-system-prompt${sep}`
+  const at = spEntry.indexOf(marker)
+  return at === -1 ? spEntry : spEntry.slice(0, at)
+}
+
+// ==================== 极简断言台 ====================
+
+let passed = 0
+const failures = []
+
+function record(name, ok, detail) {
+  if (ok) {
+    passed += 1
+    console.log(`  ✓ ${name}`)
+  } else {
+    failures.push(name)
+    console.log(`  ✗ ${name}${detail ? ` —— ${detail}` : ''}`)
+  }
+}
+
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b)
+
+// ==================== A：真实 SystemPrompt 服务 ====================
+
+/**
+ * 用真实宿主的 `SystemPrompt` 跑一遍「section 文本随配置变化」。
+ * @param opts.staticText - 判断力对照：把 text 退化为静态字符串（应当让可变性用例失败）
+ * @returns 用例结果数组（不直接断言，便于基线 / 对照两种跑法复用）
+ */
+async function partA(SystemPrompt, renderPrompt, Context, opts = {}) {
+  const results = []
+  const push = (name, ok, detail) => results.push({ name, ok, detail })
+
+  const root = new Context()
+  const service = new SystemPrompt(root, {
+    includeHarnessIdentity: true,
+    includeRuntimeContext: true,
+    personaPrefix: '',
+    personaSuffix: '',
+    toolOrder: undefined
+  })
+
+  let backing = 'AAA'
+  // interpolate: false —— 与 dsh-soul 的注册完全一致（R1）
+  const text = opts.staticText ? 'AAA' : () => backing
+  service.section({ name: 'soul:persona', order: 0, interpolate: false, text })
+
+  const read = async () => {
+    const assembly = await service.assemble({})
+    return assembly.sections.find((s) => s.name === 'soul:persona')
+  }
+
+  const first = await read()
+  push('A1 注册一次即可装配出 section', first?.text === 'AAA', `实际 ${JSON.stringify(first?.text)}`)
+
+  backing = 'BBB'
+  const second = await read()
+  push(
+    'A2 改配置后**再次装配**即读到新文本（无需重新注册 section）',
+    second?.text === 'BBB',
+    `实际 ${JSON.stringify(second?.text)}`
+  )
+
+  backing = 'AAA'
+  const third = await read()
+  push(
+    'A3 改回后读到旧文本，且与上一次装配**不同**（双向可变 ⇒ 宿主未缓存）',
+    third?.text === 'AAA' && second?.text !== third?.text,
+    `second=${JSON.stringify(second?.text)} third=${JSON.stringify(third?.text)}`
+  )
+
+  push('A4 interpolate: false 被原样传递到装配结果', third?.interpolate === false, `实际 ${JSON.stringify(third?.interpolate)}`)
+
+  // R1 的等价断言：关掉插值后 {{...}} 按字面保留，renderPrompt 不抛错
+  backing = '模板 {{cwd}} 与 {{ item.name }} 都是字面量'
+  const literal = await read()
+  let renderOk = true
+  let renderErr = ''
+  let rendered = ''
+  try {
+    rendered = renderPrompt(await service.assemble({}))
+  } catch (err) {
+    renderOk = false
+    renderErr = String((err && err.message) || err)
+  }
+  push('A5 关插值后 {{...}} 按字面渲染，renderPrompt 不抛错', renderOk, renderErr)
+  push('A6 新配置确实进入渲染结果', rendered.includes('{{cwd}}'), JSON.stringify(rendered.slice(0, 120)))
+
+  return results
+}
+
+// ==================== B：切片 SystemPromptProjection ====================
+
+/** 从宿主源码里原样取出 textOf + SystemPromptProjection。取不到返回 null（跳过，不算失败）。 */
+function sliceProjection(source) {
+  const textOf = source.match(/function textOf\(message\) \{[\s\S]*?\n\}/)
+  const klass = source.match(/var SystemPromptProjection = class \{[\s\S]*?\n\};/)
+  if (!textOf || !klass) return null
+  return `${textOf[0]}\n${klass[0]}\nreturn SystemPromptProjection`
+}
+
+function makeSession(entries) {
+  const events = new Map(
+    entries.map(([seq, text]) => [
+      seq,
+      { type: 'system/message', data: { message: { content: text === '' ? [] : [{ type: 'text', text }] } } }
+    ])
+  )
+  return { surface: { nodes: entries.map(([seq]) => seq) }, eventAt: (seq) => events.get(seq) }
+}
+
+function partB(build, opts = {}) {
+  const results = []
+  const push = (name, ok, detail) => results.push({ name, ok, detail })
+
+  // createSystemMessage 与断言无关：只用来承载渲染后的文本
+  const compile = (src) =>
+    new Function('createSystemMessage', src)((text) => ({
+      content: text === '' ? [] : [{ type: 'text', text }]
+    }))
+
+  let projection
+  try {
+    projection = compile(build())
+  } catch (err) {
+    push('B0 切片可用', false, String((err && err.message) || err))
+    return results
+  }
+
+  const fresh = new projection(makeSession([]))
+  const firstCommits = fresh.project('AAA', { inHistory: true, startsSeries: false })
+  push('B1 首次装配提交一条 system 消息（即使文本非空）', firstCommits.length === 1, `实际 ${firstCommits.length}`)
+
+  const session = makeSession([[1, 'AAA']])
+  const proj = new projection(session)
+  const changed = proj.project('BBB', { inHistory: true, startsSeries: false })
+  push('B2 文本变化 → 提交新的 system 快照', changed.length === 1, `实际 ${changed.length}`)
+  push(
+    'B3 新增快照走 surfaceOp=append（不覆盖历史）',
+    changed[0]?.intent?.surfaceOp === 'append',
+    JSON.stringify(changed[0]?.intent)
+  )
+
+  const same = proj.project('AAA', { inHistory: true, startsSeries: false })
+  push(
+    'B4 文本未变化 → 不提交（宿主按文本精确比较，不会堆消息）',
+    same.length === 0,
+    `实际 ${same.length}`
+  )
+
+  const cleared = new projection(makeSession([[1, 'AAA'], [2, 'BBB']])).project('', {
+    inHistory: true,
+    startsSeries: false
+  })
+  push('B5 提示词清空（配置停用）→ 归一化：清掉后续节点并清空 head', cleared.length === 2, `实际 ${cleared.length}`)
+
+  const notHistory = new projection(makeSession([[1, 'AAA']])).project('AAA', {
+    inHistory: false,
+    startsSeries: false
+  })
+  push(
+    'B6 不在历史中但文本相同 → 仍不提交（避免无谓重写 head）',
+    notHistory.length === 0,
+    `实际 ${notHistory.length}`
+  )
+
+  return results
+}
+
+// ==================== 主流程 ====================
+
+async function main() {
+  console.log('dsh-soul — 宿主实现层等价性回归（改配置 → 下一轮生效）')
+  console.log('')
+
+  // 显式指定的目录必须真的是一份 DSH 安装：若悄悄退回自动定位，用户以为验证了 A、
+  // 实际验证了 B —— 这正是本脚本最不能出的错。
+  const explicit = explicitDshDir()
+  if (explicit) {
+    const dir = resolve(explicit)
+    if (!looksLikeDshInstall(dir)) {
+      console.log(`✗ --dsh 指定的目录不是一份 DSH 安装：${dir}`)
+      console.log('  该目录下既没有 node_modules/@deepseek-ai/dsh，其 package.json 的 name 也不是 @deepseek-ai/dsh。')
+      console.log('  本脚本不会退回自动定位（否则验证的会是另一份宿主）。')
+      process.exit(1)
+    }
+  }
+
+  const ha = hostAnchors()
+  const spEntry = ha.map((a) => resolveFrom(a, '@deepseek-ai/dsh-system-prompt')).find(Boolean)
+  const cordisEntry = ha.map((a) => resolveFrom(a, '@deepseek-ai/cordis')).find(Boolean)
+  // 包的 exports "." 即 lib/index.js，直接用解析到的主入口当源码读
+  const loopEntry = ha.map((a) => resolveFrom(a, '@deepseek-ai/dsh-agent-loop')).find(Boolean)
+
+  if (!spEntry || !cordisEntry) {
+    skipExit(
+      'verify-live-prompt（宿主等价性回归）',
+      EXPECTED_ASSERTIONS,
+      '未定位到 DSH 的 @deepseek-ai/dsh-system-prompt / cordis',
+      '--dsh <目录> 指定 DSH 安装目录（含 node_modules/@deepseek-ai/dsh）'
+    )
+  }
+
+  // 本机常常装着不止一份 DSH。报告必须说明验证的是哪一份，否则结论没法复核。
+  const candidates = hostCandidates()
+  if (candidates.length > 1) {
+    console.log(`注意：本机解析到 ${candidates.length} 份 DSH 副本，本脚本验证的是第一份（其余仅供对照）：`)
+    for (const [i, c] of candidates.entries()) console.log(`  ${i === 0 ? '→' : ' '} ${c.entry}`)
+    console.log('')
+  }
+  console.log(`宿主模块：${spEntry}`)
+  console.log('')
+
+  const sp = await import(pathToFileURL(spEntry).href)
+  const cordis = await import(pathToFileURL(cordisEntry).href)
+  const Context = cordis.Context || cordis.default
+
+  console.log('A 真实 SystemPrompt + 真实 Cordis Context')
+  const baseA = await partA(sp.SystemPrompt, sp.renderPrompt, Context)
+  for (const r of baseA) record(r.name, r.ok, r.detail)
+
+  // 判断力对照：把函数式 text 退化为静态字符串，可变性用例必须失败
+  const sabA = await partA(sp.SystemPrompt, sp.renderPrompt, Context, { staticText: true })
+  const sticky = sabA.filter((r) => !r.ok).map((r) => r.name)
+  record(
+    'A 判断力对照：text 退化为静态字符串后，A2 / A3 必须失败',
+    sticky.some((n) => n.startsWith('A2')) && sticky.some((n) => n.startsWith('A3')),
+    `实际失败项 ${JSON.stringify(sticky)}`
+  )
+  record(
+    'A 判断力对照：A1 / A4 属结构性事实，不应随之失败',
+    sabA.filter((r) => r.name.startsWith('A1') || r.name.startsWith('A4')).every((r) => r.ok),
+    '对照跑不该让结构断言失败'
+  )
+
+  console.log('')
+  console.log('B 切片 SystemPromptProjection（dsh-agent-loop）')
+  let baseB = null
+  if (!loopEntry) {
+    console.log('  ⚠ 未定位到 @deepseek-ai/dsh-agent-loop，B 层跳过 —— 本次运行将因断言数不足被判为不可信')
+  } else {
+    const loopSource = readFileSync(loopEntry, 'utf8')
+    const src = sliceProjection(loopSource)
+    if (!src) {
+      console.log('  ⚠ 未能在宿主源码中定位 SystemPromptProjection（宿主实现已变），B 层跳过 —— 本次运行将因断言数不足被判为不可信')
+    } else {
+      baseB = partB(() => src)
+      for (const r of baseB) record(r.name, r.ok, r.detail)
+
+      // 判断力对照：删掉「文本相等就不提交」这一句，B4 必须失败
+      const broken = src.replace(/if \(latest\.text === rendered\) return \[\];\n/, '')
+      const sabB = partB(() => broken)
+      const sameness = sabB.find((r) => r.name.startsWith('B4'))
+      record(
+        'B 判断力对照：删掉「文本相等则不提交」后，B4 必须失败',
+        sameness !== undefined && sameness.ok === false,
+        `实际 ${JSON.stringify(sameness)}`
+      )
+      record(
+        'B 判断力对照：其余投影用例不受影响（改坏的是比较而非提交路径）',
+        sabB.filter((r) => !r.name.startsWith('B4')).every((r) => r.ok),
+        '对照跑不应波及无关用例'
+      )
+    }
+  }
+
+  console.log('')
+  console.log('C 源文本契约（宿主每条 step 都重新装配）')
+  const spSource = readFileSync(spEntry, 'utf8')
+  record(
+    'C1 assemble 对函数式 text 直接调用、无缓存',
+    /typeof section\.text === "function" \? section\.text\(context\) : section\.text/.test(spSource),
+    '宿主可能已改为缓存 section 文本 —— 若如此，这条通道会静默失效（此时只剩活动会话注入兜底）'
+  )
+  if (loopEntry) {
+    const loopSource = readFileSync(loopEntry, 'utf8')
+    const preStep = loopSource.match(/async preStep\(target, position\) \{[\s\S]*?\n\t\}/)
+    record('C2 能在宿主源码中定位 preStep', Boolean(preStep))
+    record(
+      'C3 preStep 每个 step 都调用 systemPrompt.assemble',
+      Boolean(preStep) && /systemPrompt\.assemble\(/.test(preStep[0]),
+      'preStep 不再装配系统提示词 ⇒ section 不会每步重新求值'
+    )
+    record(
+      'C4 preStep 在组装后调用 renderPrompt / project 链路（文本变化会被提交）',
+      Boolean(preStep) && /renderContextSections|renderPrompt/.test(loopSource.slice(loopSource.indexOf(preStep[0]) + preStep[0].length)),
+      'preStep 之后未见渲染/投影链路'
+    )
+  }
+
+  console.log('')
+  if (failures.length === 0) {
+    if (!assertCount('verify-live-prompt', passed, EXPECTED_ASSERTIONS)) process.exit(1)
+    console.log(`全部通过：${passed} 项检查`)
+    process.exit(0)
+  }
+  console.log(`失败 ${failures.length} 项：`)
+  for (const name of failures) console.log(`  - ${name}`)
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error('自检脚本异常：', error)
+  process.exit(1)
+})

package/scripts/verify-nav-icon.mjs

@@ -52,9 +52,14 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawnSync } from 'node:child_process'
+import { assertCount, skipExit } from './lib/skip-report.mjs'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
+
+// 本脚本要跑多少项断言（含 6 项判断力自检）。跳过的提示与 --strict 依赖它，
+// 由 report() 在真正跑完时校验。
+const EXPECTED_ASSERTIONS = 16
 const CLIENT_FILE = path.join(ROOT, 'client', 'index.mjs')
 const ICON_FILE = path.join(ROOT, 'assets', 'icon.svg')
 
@@ -91,7 +96,23 @@ function findBrowser(explicit) {
       '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'
     )
   } else {
-    candidates.push('google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge')
+    // Linux 必须用**绝对路径**：`fs.existsSync('google-chrome')` 只按当前工作目录解析
+    // 相对路径，**不做 PATH 查找** —— 实测恒为 false，于是 CI（ubuntu runner 自带
+    // Chrome）上这 16 项永远走「找不到浏览器」的跳过分支，而 ci.yml 却声称「真跑」。
+    // 这里与 verify-trail 的 Linux 分支保持一致。
+    candidates.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/microsoft-edge'
+    )
+    // 兜底：PATH 里逐个目录拼绝对路径（这才是 existsSync 能判定的形态）
+    const pathDirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean)
+    for (const dir of pathDirs) {
+      for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']) {
+        candidates.push(path.join(dir, name))
+      }
+    }
   }
   for (const candidate of candidates) {
     if (!candidate) continue
@@ -387,6 +408,7 @@ function report(result) {
   for (const item of result.items) {
     if (!item.ok) console.log(`  ✗ ${item.name}${item.detail ? ' — ' + item.detail : ''}`)
   }
+  if (!assertCount('verify-nav-icon', result.total, EXPECTED_ASSERTIONS)) return 1
   if (result.failed === 0) {
     console.log(`\n全部通过：${result.total} 项检查`)
     return 0
@@ -415,9 +437,12 @@ function main() {
 
   const browser = findBrowser(opts.chrome)
   if (!browser) {
-    console.log('未找到可用的 Chrome / Edge，跳过导航图标回归。')
-    console.log('可指定浏览器：node scripts/verify-nav-icon.mjs --chrome <可执行文件>')
-    return 0
+    skipExit(
+      'verify-nav-icon（设置导航图标回归）',
+      EXPECTED_ASSERTIONS,
+      '未找到 Chrome / Edge',
+      '--chrome <可执行文件> 指定浏览器；或两段式：--emit <页面> → 手动 --dump-dom → --dump <文件>'
+    )
   }
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-soul-nav-icon-'))
@@ -437,9 +462,12 @@ function main() {
   try {
     if (result.error || result.status !== 0 || !result.stdout) {
       const reason = result.error ? result.error.code || result.error.message : `退出码 ${result.status}`
-      console.log(`无头浏览器未能运行（${reason}）。`)
-      console.log('可改用两段式：--emit 产出页面 → 手动跑浏览器 --dump-dom → --dump 解析')
-      return 0
+      skipExit(
+        'verify-nav-icon（设置导航图标回归）',
+        EXPECTED_ASSERTIONS,
+        `无头浏览器未能运行（${reason}）`,
+        '两段式：--emit <页面> → 手动 --dump-dom → --dump <文件>'
+      )
     }
     return report(parseDump(result.stdout))
   } finally {