dsh-structured 0.0.0-stage → 0.7.4

package/scripts/desktop-check.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Desktop 兼容性预检（只读）。
+ *
+ * 目标 profile 默认就是 `desktop`。这个脚本在安装前检查：
+ *   - 插件只依赖宿主的 systemPrompt 服务（commands 可选），不使用 Electron/headless 专有 API；
+ *   - bundle 清单、files、main/exports 能让 desktop 的 boot 层正确装配；
+ *   - 默认开启、状态落在 $DSH_HOME，不写死 profile 名或盘符；
+ *   - desktop profile 的 bundle 栈里确实有提供 systemPrompt/commands 的 dsh-base。
+ *
+ * 用法：
+ *   node scripts/desktop-check.mjs
+ *   node scripts/desktop-check.mjs --entry "C:\...\profiles\desktop\node_modules\dsh-structured"
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+let entry = process.cwd()
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--entry') entry = resolve(args[++i])
+  else if (args[i] === '--help' || args[i] === '-h') {
+    process.stdout.write('用法: node scripts/desktop-check.mjs [--entry <插件目录>]\n')
+    process.exit(0)
+  } else {
+    process.stderr.write('desktop-check: 未知参数 ' + args[i] + '\n')
+    process.exit(2)
+  }
+}
+
+const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+const profileDir = join(home, 'profiles', 'desktop')
+const rows = []
+const check = (name, ok, detail = '') => rows.push({ name, ok, detail })
+
+function readJson(file) {
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+// 1. desktop profile 的 bundle 栈
+const profileManifestFile = join(profileDir, 'package.json')
+let profileManifest = null
+try {
+  profileManifest = readJson(profileManifestFile)
+  const bundles = profileManifest?.dsh?.profile?.bundles ?? []
+  check('desktop profile 已初始化', true, profileManifestFile)
+  check('desktop bundle 栈含 dsh-base', bundles.includes('@deepseek-ai/dsh-base'), 'dsh-base 提供 systemPrompt / commands')
+  check('desktop bundle 栈含 dsh-web-app', bundles.includes('@deepseek-ai/dsh-web-app'), 'desktop 的 Web 表层')
+} catch {
+  rows.push({ name: 'desktop profile 已初始化', ok: null, detail: '未找到 ' + profileManifestFile + '（先启动一次 Desktop）' })
+}
+
+// 2. 插件清单
+let pkg = null
+try {
+  pkg = readJson(join(entry, 'package.json'))
+  check('插件 package.json 可读', true, entry)
+} catch (error) {
+  check('插件 package.json 可读', false, String(error))
+  report()
+  process.exit(1)
+}
+
+const patchRel = pkg?.dsh?.bundle?.patch
+check('声明 dsh.bundle.patch', typeof patchRel === 'string', patchRel ?? '缺失')
+const patchFile = patchRel && isAbsolute(patchRel) ? patchRel : join(entry, patchRel ?? '')
+check('cordis.patch.yml 存在', Boolean(patchRel) && existsSync(patchFile), patchFile)
+const files = Array.isArray(pkg.files) ? pkg.files : []
+check('files 含 cordis.patch.yml', files.includes('cordis.patch.yml'), 'npm pack 不会漏掉装配清单')
+check('files 含 lib / src', files.includes('lib') && files.includes('src'), files.join(', '))
+check('main 指向 lib/index.js', pkg.main === 'lib/index.js', pkg.main ?? '缺失')
+check('exports . 指向 lib/index.js', pkg.exports?.['.'] === './lib/index.js', String(pkg.exports?.['.'] ?? '缺失'))
+check('桌面 client 半区已声明', pkg?.dsh?.client?.platform === 'web', 'dsh.client.platform = web')
+check('exports ./client 指向 lib/client.js', pkg.exports?.['./client'] === './lib/client.js', String(pkg.exports?.['./client'] ?? '缺失'))
+check('engines.dsh 声明兼容范围', typeof pkg?.engines?.dsh === 'string', pkg?.engines?.dsh ?? '缺失')
+check('dsh.compatibility 声明兼容版本', Boolean(pkg?.dsh?.compatibility?.dshReleases), JSON.stringify(pkg?.dsh?.compatibility?.dshReleases ?? {}))
+
+// 3. patch 内容
+let patchText = ''
+try {
+  patchText = readFileSync(patchFile, 'utf8')
+} catch {}
+check('patch 含 dsh-structured 行', /id:\s*dsh-structured/.test(patchText), '')
+check('patch 默认 defaultEnabled: true', /defaultEnabled:\s*true/.test(patchText), '')
+
+// 4. 运行时入口：只允许 node: 内置模块 + 无 profile 分支
+const libFile = join(entry, 'lib', 'index.js')
+let libText = ''
+try {
+  libText = readFileSync(libFile, 'utf8')
+  check('lib/index.js 存在', true, libFile)
+} catch {
+  check('lib/index.js 存在', false, libFile)
+}
+const clientFile = join(entry, 'lib', 'client.js')
+let clientText = ''
+try {
+  clientText = readFileSync(clientFile, 'utf8')
+  check('lib/client.js 存在', true, clientFile)
+} catch {
+  check('lib/client.js 存在', false, clientFile)
+}
+check('client 模块 id 与包名一致', /id:\s*'dsh-structured'/.test(clientText), '')
+check('client 模块是纯 DOM 增强（无 React 强依赖）', !/require\(['"]react['"]\)/.test(clientText), '')
+const imports = [...libText.matchAll(/from\s+['"]([^'"]+)['"]/g)].map((match) => match[1])
+const nonNodeImports = imports.filter((spec) => !spec.startsWith('node:'))
+check('运行时只 import node: 内置模块', nonNodeImports.length === 0, nonNodeImports.join(', ') || 'ok')
+check('inject 只硬依赖 systemPrompt', /export const inject = \['systemPrompt'\]/.test(libText), 'commands 缺失时只降级命令')
+check('没有 desktop/structured-test 分支', !/['"](?:desktop|structured-test)['"]/.test(libText), '')
+check('状态目录走 DSH_HOME', /process\.env\.DSH_HOME/.test(libText), '')
+check('没有 Electron 专有 API', !/electron|process\.versions\.electron/.test(libText), '')
+
+// 5. 版本与运行时
+const nodeMajor = Number(process.versions.node.split('.')[0])
+check('Node >= 22', nodeMajor >= 22, process.versions.node)
+
+function report() {
+  for (const row of rows) {
+    const tag = row.ok === true ? 'PASS' : row.ok === false ? 'FAIL' : 'WARN'
+    process.stdout.write(tag.padEnd(5) + '  ' + row.name + (row.detail ? '  — ' + row.detail : '') + '\n')
+  }
+  const failed = rows.filter((row) => row.ok === false).length
+  process.stdout.write('\n' + (failed === 0 ? 'desktop 兼容性预检通过' : failed + ' 项失败') + '\n')
+}
+
+report()
+if (rows.some((row) => row.ok === false)) process.exitCode = 1

package/scripts/lib/session-log.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * DSH v4 会话日志读取器（无依赖）。
+ *
+ * 物理格式：独立 Zstandard 帧的标准拼接——一个只含 header 行的校验和帧，之后每个 append 批次一个帧。
+ * Node 的 zstdDecompressSync 只解第一帧，所以这里先按帧头 + block header 精确算出帧长，再逐帧解压。
+ */
+
+import fs from 'node:fs'
+import { join } from 'node:path'
+import zlib from 'node:zlib'
+
+const ZSTD_MAGIC = 0xfd2fb528
+
+/**
+ * 计算 [offset, offset+frameLength) 这一帧的字节长度。
+ * @param {Buffer} buf
+ * @param {number} offset
+ * @returns {number}
+ */
+export function frameLength(buf, offset) {
+  if (buf.readUInt32LE(offset) !== ZSTD_MAGIC) throw new Error('bad zstd magic at ' + offset)
+  let p = offset + 4
+  const descriptor = buf[p++]
+  const contentSizeFlag = descriptor >> 6
+  const singleSegment = (descriptor >> 5) & 1
+  const checksumFlag = (descriptor >> 2) & 1
+  const dictionaryFlag = descriptor & 3
+  if (!singleSegment) p += 1 // Window descriptor
+  if (dictionaryFlag === 3) p += 4
+  else if (dictionaryFlag === 2) p += 2
+  else if (dictionaryFlag === 1) p += 1
+  if (contentSizeFlag === 0) {
+    if (singleSegment) p += 1
+  } else if (contentSizeFlag === 1) p += 2
+  else if (contentSizeFlag === 2) p += 4
+  else p += 8
+
+  for (;;) {
+    if (p + 3 > buf.length) throw new Error('truncated zstd block header')
+    const header = buf[p] | (buf[p + 1] << 8) | (buf[p + 2] << 16)
+    p += 3
+    const last = header & 1
+    const type = (header >> 1) & 3
+    const size = header >>> 3
+    if (type === 0 || type === 2) p += size
+    else if (type === 1) p += 1
+    else throw new Error('reserved zstd block type')
+    if (p > buf.length) throw new Error('truncated zstd block body')
+    if (last) break
+  }
+  if (checksumFlag) p += 4
+  return p - offset
+}
+
+/**
+ * 读取一个会话日志，返回全部 JSONL 事件（header 事件 + 持久事件）。
+ * @param {string} file
+ * @returns {any[]}
+ */
+export function readSessionLog(file) {
+  const buf = fs.readFileSync(file)
+  const events = []
+  let offset = 0
+  while (offset < buf.length) {
+    const length = frameLength(buf, offset)
+    const text = zlib.zstdDecompressSync(buf.subarray(offset, offset + length)).toString('utf8')
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue
+      events.push(JSON.parse(line))
+    }
+    offset += length
+  }
+  return events
+}
+
+/**
+ * 在 sessions 根目录下递归找某个 session id 的日志，取最高版本。
+ * @param {string} sessionsRoot
+ * @param {string} sessionId
+ * @returns {string | null}
+ */
+export function findSessionLog(sessionsRoot, sessionId) {
+  if (!fs.existsSync(sessionsRoot)) return null
+  for (const group of fs.readdirSync(sessionsRoot, { withFileTypes: true })) {
+    if (!group.isDirectory()) continue
+    const dir = join(sessionsRoot, group.name, sessionId)
+    if (!fs.existsSync(dir)) continue
+    const candidates = fs
+      .readdirSync(dir)
+      .filter((name) => /^session(?:\.v\d+)?\.jsonl(?:\.zstd)?$/.test(name))
+      .sort((a, b) => versionOf(b) - versionOf(a))
+    if (candidates.length > 0) return join(dir, candidates[0])
+  }
+  return null
+}
+
+function versionOf(name) {
+  const match = /^session(?:\.v(\d+))?\.jsonl(?:\.zstd)?$/.exec(name)
+  return match?.[1] === undefined ? 0 : Number(match[1])
+}
+
+/**
+ * 列出 sessions 根目录下全部会话日志（可选时间窗）。
+ * @param {string} sessionsRoot
+ * @param {{ sinceDays?: number }} [options]
+ * @returns {Array<{ file: string, sessionId: string, group: string, mtimeMs: number }>}
+ */
+export function listSessionLogs(sessionsRoot, options = {}) {
+  if (!fs.existsSync(sessionsRoot)) return []
+  const cutoff = options.sinceDays ? Date.now() - options.sinceDays * 86_400_000 : 0
+  const out = []
+  for (const group of fs.readdirSync(sessionsRoot, { withFileTypes: true })) {
+    if (!group.isDirectory()) continue
+    const groupDir = join(sessionsRoot, group.name)
+    for (const session of fs.readdirSync(groupDir, { withFileTypes: true })) {
+      if (!session.isDirectory()) continue
+      const dir = join(groupDir, session.name)
+      const candidates = fs
+        .readdirSync(dir)
+        .filter((name) => /^session(?:\.v\d+)?\.jsonl(?:\.zstd)?$/.test(name))
+        .sort((a, b) => versionOf(b) - versionOf(a))
+      if (candidates.length === 0) continue
+      const file = join(dir, candidates[0])
+      const mtimeMs = fs.statSync(file).mtimeMs
+      if (mtimeMs < cutoff) continue
+      out.push({ file, sessionId: session.name, group: group.name, mtimeMs })
+    }
+  }
+  return out.sort((a, b) => a.mtimeMs - b.mtimeMs)
+}
+
+/**
+ * 逐轮提取「用户可见最终回复」：每轮最后一条含文本、且不含 tool-call 的 assistant 消息。
+ * @param {any[]} events
+ * @returns {Array<{ turn: number, text: string }>}
+ */
+export function finalReplies(events) {
+  const byTurn = new Map()
+  let turn = 0
+  for (const event of events) {
+    if (event.type === 'turn/start') turn = event.data?.turn ?? turn + 1
+    if (event.type !== 'assistant/message') continue
+    const message = event.data?.message
+    const content = Array.isArray(message?.content) ? message.content : []
+    const hasToolCall = content.some((block) =>
+      ['tool-call', 'tool-call-delta', 'tool_use', 'toolCalls'].includes(block?.type),
+    )
+    const text = content
+      .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('')
+    if (hasToolCall || text.trim() === '') continue
+    byTurn.set(turn, { turn, text })
+  }
+  return [...byTurn.values()].sort((a, b) => a.turn - b.turn)
+}
+
+/**
+ * 会话日志里所有 system/message 的文本。
+ * @param {any[]} events
+ * @returns {string[]}
+ */
+export function systemTexts(events) {
+  return events
+    .filter((event) => event.type === 'system/message')
+    .map((event) => {
+      const content = event.data?.message?.content
+      if (!Array.isArray(content)) return ''
+      return content
+        .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('')
+    })
+    .filter((text) => text.length > 0)
+}

package/scripts/measure-prose.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * 散文率统计：实质回复里「该结构化却写成散文」的比例。
+ * 口径固定、可复跑，README 与 docs/METRICS.md 有完整说明。
+ *
+ * 判定：
+ *   实质回复   = 去掉代码块后可见字符 >= 120，且句子数 >= 2
+ *   首屏结构化 = 回复前 300 个字符内出现 >=2 行表格 | >=2 个清单项 | >=2 个标题 | >=1 个 dsh-ui 块
+ *   散文违规   = 实质回复 && 首屏不结构化 && 句子数 >= 3
+ *   散文率     = 散文违规数 / 实质回复数（主口径）
+ *
+ * 另给整篇口径作对照：整篇任意位置出现结构即算结构化。两个口径都输出，避免只挑好看的数。
+ *
+ * 用法：
+ *   node scripts/measure-prose.mjs --since-days 14 --verbose
+ *   node scripts/measure-prose.mjs --sessions session-a,session-b --json
+ *   node scripts/measure-prose.mjs --first-screen 500
+ *   node scripts/measure-prose.mjs --whole
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { finalReplies, readSessionLog, findSessionLog, listSessionLogs } from './lib/session-log.mjs'
+
+const SUBSTANTIVE_CHARS = 120
+const MIN_SENTENCES = 2
+const PROSE_SENTENCES = 3
+const DEFAULT_FIRST_SCREEN = 300
+
+function parseArgs(argv) {
+  const args = {
+    dir: process.env.DSH_HOME ? join(process.env.DSH_HOME, 'sessions') : join(homedir(), '.dsh', 'sessions'),
+    firstScreen: DEFAULT_FIRST_SCREEN,
+    whole: false,
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--dir') args.dir = argv[++i]
+    else if (arg === '--sessions') args.sessions = String(argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+    else if (arg === '--since-days') args.sinceDays = Number(argv[++i])
+    else if (arg === '--before') args.before = argv[++i]
+    else if (arg === '--limit') args.limit = Number(argv[++i])
+    else if (arg === '--first-screen') args.firstScreen = Number(argv[++i])
+    else if (arg === '--whole') args.whole = true
+    else if (arg === '--json') args.json = true
+    else if (arg === '--verbose') args.verbose = true
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else throw new Error('unknown argument: ' + arg)
+  }
+  if (!Number.isFinite(args.firstScreen) || args.firstScreen < 40) args.firstScreen = DEFAULT_FIRST_SCREEN
+  return args
+}
+
+const HELP = `用法: node scripts/measure-prose.mjs [选项]
+
+  --dir <path>          sessions 根目录（默认 $DSH_HOME/sessions）
+  --sessions <ids>      只统计指定会话，逗号分隔
+  --since-days <n>      只统计最近 n 天有写入的会话
+  --before <iso>        只统计写入时间早于该时刻的会话（做干净的改前基线）
+  --first-screen <n>    首屏口径的字符数（默认 300）
+  --whole               改用整篇口径（任意位置有结构即算结构化）
+  --limit <n>           最多统计 n 条实质回复
+  --json                输出机器可读结果
+  --verbose             列出每条违规回复
+  -h, --help            显示本帮助
+`
+
+/**
+ * 解析回复的可见结构信号。
+ * @param {string} text
+ * @returns {{ chars: number, sentences: number, tableRows: number, listItems: number, headings: number, dshUiBlocks: number, withoutCode: string }}
+ */
+export function analysisText(text) {
+  const dshUiBlocks = (text.match(/```dsh-ui/g) ?? []).length
+  const withoutCode = text.replace(/```[\s\S]*?```/g, '\n')
+  const lines = withoutCode.split('\n')
+  const visible = withoutCode.replace(/\s+/g, '')
+  const tableRows = lines.filter((line) => /^\s*\|.*\|\s*$/.test(line)).length
+  const listItems = lines.filter((line) => /^\s*(?:[-*+]|\d+[.)])\s+\S/.test(line)).length
+  const headings = lines.filter((line) => /^\s*#{1,6}\s+\S/.test(line)).length
+  const cardLines = lines.filter(
+    (line) =>
+      /^\s*>\s*\*\*[^*]+\*\*\s*$/.test(line) ||
+      /^\s*>\s*\*\*(?:结论|判断|决策|指标|重点|风险|注意|下一步|行动|验收|通过)\*\*/.test(line),
+  ).length
+  const sentences = withoutCode
+    .split(/[。！？!?;；\n]+|\.\s+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length >= 6).length
+  return { chars: visible.length, sentences, tableRows, listItems, headings, cardLines, dshUiBlocks, withoutCode }
+}
+
+/**
+ * 首屏是否出现结构。按字符数截断而不是按行数，避免长段落把结构推到屏幕外。
+ * dsh-ui 组件块在原文里识别；普通代码块不算结构（先剥掉，避免代码里的 | / - 被误判）。
+ * @param {string} text
+ * @param {number} limit
+ * @returns {boolean}
+ */
+export function firstScreenStructured(text, limit = DEFAULT_FIRST_SCREEN) {
+  const head = text.slice(0, limit)
+  if (head.includes('```dsh-ui')) return true
+  // 非 dsh-ui 的 fenced block：从开栅栏起整段丢弃（含未闭合到首屏末尾的情况）。
+  const cleaned = head.replace(/```(?!dsh-ui)[^\n]*\n[\s\S]*?(?:```|$)/g, '\n')
+  const lines = cleaned.split('\n')
+  const tableRows = lines.filter((line) => /^\s*\|.*\|\s*$/.test(line)).length
+  const listItems = lines.filter((line) => /^\s*(?:[-*+]|\d+[.)])\s+\S/.test(line)).length
+  const headings = lines.filter((line) => /^\s*#{1,6}\s+\S/.test(line)).length
+  const cardLines = lines.filter(
+    (line) =>
+      /^\s*>\s*\*\*[^*]+\*\*\s*$/.test(line) ||
+      /^\s*>\s*\*\*(?:结论|判断|决策|指标|重点|风险|注意|下一步|行动|验收|通过)\*\*/.test(line),
+  ).length
+  return cardLines >= 1 || tableRows >= 2 || listItems >= 2 || headings >= 2
+}
+
+/**
+ * 单条回复的判定。
+ * @param {string} text
+ * @param {{ firstScreen?: number, whole?: boolean }} [options]
+ * @returns {ReturnType<typeof analysisText> & { substantive: boolean, structured: boolean, structuredWhole: boolean, prose: boolean }}
+ */
+export function classify(text, options = {}) {
+  const a = analysisText(text)
+  const substantive = a.chars >= SUBSTANTIVE_CHARS && a.sentences >= MIN_SENTENCES
+  const structuredWhole = a.tableRows >= 2 || a.listItems >= 2 || a.headings >= 2 || a.cardLines >= 1 || a.dshUiBlocks >= 1
+  const structured = options.whole
+    ? structuredWhole
+    : firstScreenStructured(text, options.firstScreen ?? DEFAULT_FIRST_SCREEN)
+  const prose = substantive && !structured && a.sentences >= PROSE_SENTENCES
+  return { ...a, substantive, structured, structuredWhole, prose }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    process.stdout.write(HELP)
+    return
+  }
+
+  let logs
+  if (args.sessions) {
+    logs = args.sessions.map((id) => {
+      const file = findSessionLog(args.dir, id)
+      if (!file) throw new Error('找不到会话：' + id)
+      return { file, sessionId: id }
+    })
+  } else {
+    logs = listSessionLogs(args.dir, { sinceDays: args.sinceDays })
+    if (args.before) {
+      const cutoff = Date.parse(args.before)
+      if (!Number.isFinite(cutoff)) throw new Error('无法解析 --before：' + args.before)
+      logs = logs.filter((log) => log.mtimeMs <= cutoff)
+    }
+  }
+
+  const rows = []
+  for (const log of logs) {
+    const events = readSessionLog(log.file)
+    for (const reply of finalReplies(events)) {
+      const verdict = classify(reply.text, { firstScreen: args.firstScreen, whole: args.whole })
+      rows.push({ sessionId: log.sessionId, turn: reply.turn, ...verdict })
+    }
+  }
+
+  const substantive = rows.filter((row) => row.substantive)
+  const selected = args.limit ? substantive.slice(-args.limit) : substantive
+  const selectedProse = selected.filter((row) => row.prose)
+  const wholeProse = selected.filter((row) => !row.structuredWhole && row.sentences >= PROSE_SENTENCES)
+  const rate = (value) => (selected.length === 0 ? 0 : Number(((value / selected.length) * 100).toFixed(1)))
+
+  const summary = {
+    dir: args.dir,
+    sessions: logs.length,
+    replies: rows.length,
+    substantive: selected.length,
+    structured: selected.filter((row) => row.structured).length,
+    prose: selectedProse.length,
+    proseRate: rate(selectedProse.length),
+    wholeProse: wholeProse.length,
+    wholeProseRate: rate(wholeProse.length),
+    metric: {
+      mode: args.whole ? 'whole' : 'first-screen',
+      firstScreenChars: args.whole ? null : args.firstScreen,
+      substantiveChars: SUBSTANTIVE_CHARS,
+      proseSentences: PROSE_SENTENCES,
+    },
+    violations: selectedProse.map((row) => ({
+      sessionId: row.sessionId,
+      turn: row.turn,
+      chars: row.chars,
+      sentences: row.sentences,
+      firstLine: row.withoutCode.trim().split('\n').find((line) => line.trim() !== '')?.slice(0, 120) ?? '',
+    })),
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n')
+    return
+  }
+
+  process.stdout.write(
+    'sessions=' + summary.sessions +
+      ' replies=' + summary.replies +
+      ' substantive=' + summary.substantive +
+      ' structured=' + summary.structured +
+      ' prose=' + summary.prose +
+      ' proseRate=' + summary.proseRate + '%' +
+      ' wholeProseRate=' + summary.wholeProseRate + '%' +
+      ' mode=' + summary.metric.mode + '\n',
+  )
+  if (args.verbose && summary.violations.length > 0) {
+    process.stdout.write('违规回复：\n')
+    for (const row of summary.violations) {
+      process.stdout.write('  ' + row.sessionId + ' turn ' + row.turn + ' · ' + row.chars + ' 字符 / ' + row.sentences + ' 句 · ' + row.firstLine + '\n')
+    }
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('measure-prose.mjs')) {
+  try {
+    main()
+  } catch (error) {
+    process.stderr.write('measure-prose: ' + String(error?.message ?? error) + '\n')
+    process.exitCode = 2
+  }
+}

package/scripts/session-inspect.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * 读一个 DSH 会话日志，用来验证 system prompt 注入是否生效。
+ *
+ * 用法：
+ *   node scripts/session-inspect.mjs --session session-xxxx --grep "结构化输出（本会话已启用"
+ *   node scripts/session-inspect.mjs --session session-xxxx --grep "结构化输出" --json
+ *   node scripts/session-inspect.mjs                 # 默认看最近一个会话
+ *
+ * 退出码：0 = 正常读取（--grep 的命中数在输出里）；2 = 参数或读取错误。
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import {
+  finalReplies,
+  findSessionLog,
+  listSessionLogs,
+  readSessionLog,
+  systemTexts,
+} from './lib/session-log.mjs'
+
+function parseArgs(argv) {
+  const args = { dir: process.env.DSH_HOME ? join(process.env.DSH_HOME, 'sessions') : join(homedir(), '.dsh', 'sessions') }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--session') args.session = argv[++i]
+    else if (arg === '--dir') args.dir = argv[++i]
+    else if (arg === '--grep') args.grep = argv[++i]
+    else if (arg === '--json') args.json = true
+    else if (arg === '--replies') args.replies = true
+    else if (arg === '--last-system') args.lastSystem = true
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else throw new Error('unknown argument: ' + arg)
+  }
+  return args
+}
+
+const HELP = `用法: node scripts/session-inspect.mjs [选项]
+
+  --session <id>  指定会话 id；省略时取最近写入的会话
+  --dir <path>    sessions 根目录（默认 $DSH_HOME/sessions）
+  --grep <text>   在 system/message 里搜这段文本，输出命中数与位置
+  --last-system   只检查最新一条 system/message（用于验证「关掉后下一轮 0 命中」）
+  --replies       同时列出每轮最终回复的首行与长度
+  --json          输出机器可读 JSON
+  -h, --help      显示本帮助
+`
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    process.stdout.write(HELP)
+    return
+  }
+
+  let file
+  if (args.session) {
+    file = findSessionLog(args.dir, args.session)
+    if (!file) throw new Error('找不到会话日志：' + args.session + '（根目录 ' + args.dir + '）')
+  } else {
+    const latest = listSessionLogs(args.dir).at(-1)
+    if (!latest) throw new Error('目录下没有会话日志：' + args.dir)
+    file = latest.file
+  }
+
+  const events = readSessionLog(file)
+  const header = events.find((event) => event.type === 'session') ?? {}
+  const sessionId = header.id ?? args.session ?? '(unknown)'
+  const systems = systemTexts(events)
+  const scopedSystems = args.lastSystem ? systems.slice(-1) : systems
+  const hits = args.grep ? scopedSystems.filter((text) => text.includes(args.grep)) : []
+  const replies = args.replies ? finalReplies(events) : []
+
+  if (args.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          file,
+          sessionId,
+          events: events.length,
+          systemMessages: systems.length,
+          systemChars: systems.reduce((sum, text) => sum + text.length, 0),
+          scopedToLastSystem: args.lastSystem === true,
+          grep: args.grep ?? null,
+          hits: hits.length,
+          replies: replies.map((reply) => ({
+            turn: reply.turn,
+            chars: reply.text.length,
+            firstLine: reply.text.trim().split('\n')[0].slice(0, 120),
+          })),
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return
+  }
+
+  process.stdout.write('会话：' + sessionId + '\n')
+  process.stdout.write('日志：' + file + '\n')
+  process.stdout.write('事件：' + events.length + ' 条；system/message：' + systems.length + ' 条，共 ' + systems.reduce((sum, text) => sum + text.length, 0) + ' 字符\n')
+  if (args.grep) {
+    process.stdout.write('搜索：' + JSON.stringify(args.grep) + ' → 命中 ' + hits.length + ' 条 system/message\n')
+    for (const text of hits) {
+      const index = text.indexOf(args.grep)
+      process.stdout.write('  …' + text.slice(Math.max(0, index - 40), index + args.grep.length + 60).replace(/\n/g, ' ⏎ ') + '…\n')
+    }
+  }
+  if (args.replies) {
+    process.stdout.write('最终回复：' + replies.length + ' 轮\n')
+    for (const reply of replies) {
+      process.stdout.write('  turn ' + reply.turn + ' · ' + reply.text.length + ' 字符 · ' + reply.text.trim().split('\n')[0].slice(0, 80) + '\n')
+    }
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  process.stderr.write('session-inspect: ' + String(error?.message ?? error) + '\n')
+  process.exitCode = 2
+}