@huaqiu/dsh-log 0.0.0-stage → 1.1.2

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@huaqiu/dsh-log",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.2",
+  "description": "DSH plugin: external API calls + whitelisted script execution with structured audit logging (v1.1.2)",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "audit-core.ts",
+    "dsh-log.yml",
+    "tools/audit-log.mjs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node --test test/audit-core.test.ts && node --import ./test/register-stubs.mjs --test test/plugin.test.ts && node --test test/audit-log.test.ts",
+    "demo": "node --import ./test/register-stubs.mjs demo.ts",
+    "log": "node tools/audit-log.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  }
+}

package/tools/audit-log.mjs

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+/**
+ * audit-log.mjs — read the dsh-log host audit log (channel 1).
+ *
+ * The host log is the only place the FULL lifecycle of a tool call is observable:
+ * the trajectory channel receives just the terminal record, so a call that begins
+ * and never returns is invisible there. This reader makes the richer channel
+ * actually usable — filter by call/session/tool, dump statistics, and detect
+ * invocations that LOST a record (`--incomplete`).
+ *
+ * Usage:
+ *   node tools/audit-log.mjs                        # newest day: header + last 20 records
+ *   node tools/audit-log.mjs --stats                # aggregate statistics
+ *   node tools/audit-log.mjs --errors               # ERROR records only
+ *   node tools/audit-log.mjs --call 8b47827d        # one invocation (callId prefix ok)
+ *   node tools/audit-log.mjs --session sess-abc     # one session
+ *   node tools/audit-log.mjs --tool run_external_script
+ *   node tools/audit-log.mjs --incomplete           # calls missing start or terminal
+ *   node tools/audit-log.mjs --tail 100 --json      # raw JSON lines of the last 100
+ *   node tools/audit-log.mjs --file <path.jsonl>    # explicit file
+ *   node tools/audit-log.mjs --all                  # every rotated file, not just newest day
+ *
+ * Default directory: $DSH_HOME/logs, falling back to ~/.dsh/logs.
+ * Zero dependencies; plain Node ESM (works on the same Node the plugin needs).
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const PLUGIN = 'dsh-log'
+const DEFAULT_TAIL = 20
+
+const HELP = `audit-log.mjs — 读取 dsh-log 主机审计日志
+
+用法: node tools/audit-log.mjs [选项]
+
+选项:
+  --file <path>       指定日志文件（默认读 $DSH_HOME/logs 下最新一天的文件）
+  --dir <path>        指定日志目录（默认 $DSH_HOME/logs 或 ~/.dsh/logs）
+  --all               读取所有轮转文件，而不只是最新一天
+  --call <id>         只看某个调用（callId 前缀即可）
+  --session <id>      只看某个会话
+  --tool <name>       call_external_api | run_external_script
+  --errors            只看 ERROR 级记录
+  --incomplete        只看记录不完整的调用（缺 start 或缺终态）
+  --tail <n>          只显示最后 n 条（默认 ${DEFAULT_TAIL}；带过滤条件时默认全部）
+  --stats             打印统计汇总
+  --json              输出原始 JSON 行
+  --help              显示本帮助
+
+示例:
+  node tools/audit-log.mjs --errors --tail 50
+  node tools/audit-log.mjs --call 8b47827d
+  node tools/audit-log.mjs --incomplete
+`
+
+// ---------------------------------------------------------------- arg parsing
+
+function parseArgs(argv) {
+  const o = {
+    file: null, dir: null, all: false, call: null, session: null, tool: null,
+    errors: false, incomplete: false, tail: null, stats: false, json: false, help: false,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    const need = () => {
+      const v = argv[i + 1]
+      if (v === undefined || v.startsWith('--')) throw new Error(`${a} 需要一个参数值`)
+      i += 1
+      return v
+    }
+    switch (a) {
+      case '--file': o.file = need(); break
+      case '--dir': o.dir = need(); break
+      case '--all': o.all = true; break
+      case '--call': o.call = need(); break
+      case '--session': o.session = need(); break
+      case '--tool': o.tool = need(); break
+      case '--errors': o.errors = true; break
+      case '--incomplete': o.incomplete = true; break
+      case '--tail': o.tail = Number(need()); break
+      case '--stats': o.stats = true; break
+      case '--json': o.json = true; break
+      case '--help': case '-h': o.help = true; break
+      default: throw new Error(`未知选项: ${a}（用 --help 查看用法）`)
+    }
+  }
+  if (o.tail !== null && (!Number.isInteger(o.tail) || o.tail < 0)) throw new Error('--tail 需要非负整数')
+  return o
+}
+
+// ------------------------------------------------------------ file discovery
+
+/** Default audit-log directory: $DSH_HOME/logs, else ~/.dsh/logs. */
+function defaultLogDir() {
+  const home = (process.env.DSH_HOME || '').trim() || path.join(os.homedir(), '.dsh')
+  return path.join(home, 'logs')
+}
+
+const FILE_RE = new RegExp(`^${PLUGIN}-(\\d{4})-(\\d{2})-(\\d{2})(-part\\d+)?\\.jsonl$`)
+
+/**
+ * Resolve which files to read. Without --all, returns every rotated file of the
+ * NEWEST day (rotation splits one day across -partN siblings, so one day is the
+ * smallest complete unit).
+ */
+function resolveFiles(o) {
+  if (o.file) {
+    statSync(o.file) // throws with a clear message when missing
+    return [path.resolve(o.file)]
+  }
+  const dir = o.dir ? path.resolve(o.dir) : defaultLogDir()
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    throw new Error(`日志目录不存在或不可读: ${dir}\n（用 --file 直接指定文件，或用 --dir 指定目录）`)
+  }
+  const matched = entries.filter(e => FILE_RE.test(e))
+  if (matched.length === 0) throw new Error(`目录中没有 ${PLUGIN}-*.jsonl 文件: ${dir}`)
+  let picked = matched
+  if (!o.all) {
+    const newest = matched.map(e => e.match(FILE_RE)).map(m => `${m[1]}-${m[2]}-${m[3]}`).sort().at(-1)
+    picked = matched.filter(e => e.startsWith(`${PLUGIN}-${newest}`))
+  }
+  return picked.sort().map(e => path.join(dir, e))
+}
+
+// ---------------------------------------------------------------- reading
+
+/** Read one file into { file, line, record } entries; unparsable lines are kept with record=null. */
+function readFile(file) {
+  const text = readFileSync(file, 'utf8')
+  const out = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]
+    if (line.trim() === '') continue
+    let record = null
+    try { record = JSON.parse(line) } catch { /* surfaced by --json / stats as corrupt */ }
+    out.push({ file, line, lineNo: i + 1, record })
+  }
+  return out
+}
+
+/**
+ * Phase of one record. Prefers the explicit `phase` field (plugin >= 1.0.1) and
+ * falls back to field-presence inference so logs written by older builds — like
+ * the ones already on disk — still analyse correctly.
+ */
+function phaseOf(r) {
+  if (typeof r.phase === 'string') return r.phase
+  if (r.level === 'ERROR') return 'error'
+  if (r.response !== undefined || r.code !== undefined) return 'finished'
+  return 'start'
+}
+
+const isAudit = r => r !== null && typeof r === 'object' && typeof r.callId === 'string'
+const isEvent = r => r !== null && typeof r === 'object' && typeof r.event === 'string'
+
+// ---------------------------------------------------------------- filtering
+
+function applyFilters(entries, o) {
+  return entries.filter(({ record: r }) => {
+    if (o.errors && !(isAudit(r) && r.level === 'ERROR')) return false
+    if (o.call && !(isAudit(r) && String(r.callId).startsWith(o.call))) return false
+    if (o.session && !(isAudit(r) && String(r.sessionId).includes(o.session))) return false
+    if (o.tool && !(isAudit(r) && r.tool === o.tool)) return false
+    return true
+  })
+}
+
+/**
+ * Group audit records by callId and report every invocation whose record set is
+ * incomplete. Two failure modes, both invisible on the trajectory channel:
+ *   - `缺终态`: the call started and never reported back — process killed
+ *     mid-flight, a broken sink, or simply a call still in progress.
+ *   - `首条记录丢失` / `seq 不连续`: the log's own `seq` proves a record should
+ *     exist and does not (start lost, gap in the chain).
+ * Lost-record detection deliberately requires `seq` evidence: without it a missing
+ * `start` cannot be told apart from a call that failed before it ever started
+ * (which is a complete story, not a lost record). Legacy records without `seq`
+ * therefore only yield the `缺终态` check.
+ */
+function analyzeCalls(entries) {
+  const calls = new Map()
+  for (const { record: r } of entries) {
+    if (!isAudit(r)) continue
+    let c = calls.get(r.callId)
+    if (!c) {
+      c = { callId: r.callId, sessionId: r.sessionId, tool: r.tool, records: [], seqs: [] }
+      calls.set(r.callId, c)
+    }
+    c.records.push(r)
+    if (typeof r.seq === 'number') c.seqs.push(r.seq)
+  }
+  const list = [...calls.values()].map(c => {
+    const phases = c.records.map(phaseOf)
+    const hasTerminal = phases.some(p => p === 'finished' || p === 'error')
+    const problems = []
+    if (!hasTerminal) problems.push('缺终态')
+    const seqs = c.seqs.length === c.records.length ? c.seqs.slice().sort((a, b) => a - b) : null
+    if (seqs !== null && seqs.length > 0) {
+      if (seqs[0] !== 1) problems.push('首条记录丢失（缺 seq1）')
+      else if (!seqs.every((s, i) => s === i + 1)) problems.push(`seq 不连续 (${seqs.join(',')})`)
+    }
+    const last = c.records.at(-1)
+    return {
+      ...c,
+      phases,
+      complete: problems.length === 0,
+      problems,
+      costMs: typeof last?.costMs === 'number' ? last.costMs : undefined,
+      errorType: c.records.map(r => r.errorType).find(Boolean),
+      ts: c.records.at(-1)?.ts,
+    }
+  })
+  return list.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0))
+}
+
+// ---------------------------------------------------------------- rendering
+
+/**
+ * Display width of a string in terminal cells: CJK and fullwidth code points
+ * occupy two cells, everything else one. Plain `String.length` padding produces
+ * ragged columns the moment a header contains Chinese.
+ */
+function width(s) {
+  let n = 0
+  for (const ch of String(s)) {
+    const cp = ch.codePointAt(0)
+    const wide = (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf)
+      || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff)
+      || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60) || (cp >= 0xffe0 && cp <= 0xffe6)
+    n += wide ? 2 : 1
+  }
+  return n
+}
+
+const pad = (s, w) => String(s) + ' '.repeat(Math.max(0, w - width(s)))
+const padL = (s, w) => ' '.repeat(Math.max(0, w - width(s))) + String(s)
+
+/** Local wall-clock time of a record, `HH:MM:SS.mmm`. */
+function clockOf(ts) {
+  if (typeof ts !== 'number') return '--:--:--.---'
+  const d = new Date(ts)
+  const p = (n, w = 2) => String(n).padStart(w, '0')
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`
+}
+
+const short = (id, n = 8) => (typeof id === 'string' ? id.slice(0, n) : '-')
+
+function renderRecord({ record: r }) {
+  if (isEvent(r)) {
+    // Lifecycle events (plugin-started, exporter-unavailable) share the audit
+    // column layout so a mixed dump stays readable; the event name takes the
+    // errorType column and a false `persistentLog` is called out explicitly.
+    return [
+      pad(clockOf(r.ts), 12),
+      pad(r.level ?? '-', 6),
+      pad('(event)', 19),
+      pad('-', 9),
+      padL('-', 3),
+      padL('-', 9),
+      pad('-', 5),
+      pad(r.event, 15),
+      r.persistentLog === false ? '未持久化!' : '',
+    ].join(' ')
+  }
+  if (!isAudit(r)) {
+    return [
+      pad(clockOf(r?.ts), 12),
+      pad('?', 6),
+      pad('(无法解析)', 19),
+      pad('-', 9),
+      padL('-', 3),
+      padL('-', 9),
+      pad('-', 5),
+      pad('-', 15),
+      r === null ? 'JSON 解析失败' : JSON.stringify(r).slice(0, 60),
+    ].join(' ')
+  }
+  return [
+    pad(clockOf(r.ts), 12),
+    pad(r.level, 6),
+    pad(r.tool, 19),
+    pad(phaseOf(r), 9),
+    padL(r.seq ?? '-', 3),
+    padL(r.costMs ?? '-', 7) + 'ms',
+    pad(r.code ?? '-', 5),
+    pad(r.errorType ?? '-', 15),
+    short(r.callId),
+  ].join(' ')
+}
+
+function renderTable(entries) {
+  const head = [
+    pad('时间', 12), pad('级别', 6), pad('工具', 19), pad('阶段', 9),
+    padL('seq', 3), padL('耗时', 9), pad('code', 5), pad('errorType', 15), 'callId',
+  ].join(' ')
+  return [head, '-'.repeat(width(head)), ...entries.map(renderRecord)].join('\n')
+}
+
+function renderStats(entries) {
+  const audits = entries.filter(e => isAudit(e.record)).map(e => e.record)
+  const events = entries.filter(e => isEvent(e.record)).map(e => e.record)
+  const corrupt = entries.filter(e => e.record === null).length
+  const calls = analyzeCalls(entries)
+  const byTool = {}, byLevel = {}, byError = {}, byPhase = {}
+  for (const r of audits) {
+    byTool[r.tool] = (byTool[r.tool] ?? 0) + 1
+    byLevel[r.level] = (byLevel[r.level] ?? 0) + 1
+    byPhase[phaseOf(r)] = (byPhase[phaseOf(r)] ?? 0) + 1
+    if (r.errorType) byError[r.errorType] = (byError[r.errorType] ?? 0) + 1
+  }
+  const costs = audits.map(r => r.costMs).filter(n => typeof n === 'number').sort((a, b) => a - b)
+  const pct = p => (costs.length === 0 ? '-' : `${costs[Math.min(costs.length - 1, Math.floor(costs.length * p))]}ms`)
+  const ts = audits.map(r => r.ts).filter(n => typeof n === 'number')
+  const incomplete = calls.filter(c => !c.complete)
+  const kv = obj => Object.entries(obj).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k}=${v}`).join('  ') || '-'
+  const lines = [
+    `文件           ${[...new Set(entries.map(e => path.basename(e.file)))].join(', ') || '-'}`,
+    `记录           ${audits.length} 条审计 + ${events.length} 条事件${corrupt ? ` + ${corrupt} 条无法解析` : ''}`,
+    `调用           ${calls.length} 个（完整 ${calls.length - incomplete.length}，不完整 ${incomplete.length}）`,
+    `时间范围       ${ts.length ? `${clockOf(Math.min(...ts))} → ${clockOf(Math.max(...ts))}` : '-'}`,
+    `按工具         ${kv(byTool)}`,
+    `按阶段         ${kv(byPhase)}`,
+    `按级别         ${kv(byLevel)}`,
+    `按错误类型     ${kv(byError)}`,
+    `耗时           p50=${pct(0.5)}  p95=${pct(0.95)}  max=${costs.at(-1) ?? '-'}ms`,
+  ]
+  if (incomplete.length > 0) {
+    lines.push('', '不完整的调用:')
+    for (const c of incomplete) lines.push(`  ! ${short(c.callId)}  ${c.tool}  记录 ${c.records.length} 条  ${c.problems.join(' + ')}`)
+  }
+  return lines.join('\n')
+}
+
+function renderIncomplete(entries) {
+  const calls = analyzeCalls(entries).filter(c => !c.complete)
+  const head = [pad('callId', 10), pad('工具', 19), padL('记录', 5), pad('问题', 22), 'sessionId'].join(' ')
+  const body = calls.map(c => [pad(short(c.callId), 10), pad(c.tool, 19), padL(c.records.length, 5), pad(c.problems.join(' + '), 22), short(c.sessionId, 18)].join(' '))
+  const all = analyzeCalls(entries)
+  return [
+    `共 ${all.length} 个调用，其中 ${calls.length} 个记录不完整`,
+    '',
+    ...(calls.length === 0 ? ['（没有发现缺失记录的情况）'] : [head, '-'.repeat(width(head)), ...body]),
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------- main
+
+function main() {
+  const o = parseArgs(process.argv.slice(2))
+  if (o.help) { process.stdout.write(HELP); return 0 }
+
+  const files = resolveFiles(o)
+  const entries = files.flatMap(readFile)
+  if (o.json) {
+    const filtered = applyFilters(entries, o)
+    const tail = o.tail ?? (o.call || o.session || o.tool || o.errors ? filtered.length : DEFAULT_TAIL)
+    for (const e of tail > 0 ? filtered.slice(-tail) : filtered) process.stdout.write(`${e.line}\n`)
+    return 0
+  }
+  if (o.incomplete) { process.stdout.write(`${renderIncomplete(entries)}\n`); return 0 }
+  if (o.stats) { process.stdout.write(`${renderStats(entries)}\n`); return 0 }
+
+  const filtered = applyFilters(entries, o).filter(e => !o.errors || !isEvent(e.record))
+  const tail = o.tail ?? (o.call || o.session || o.tool || o.errors ? filtered.length : DEFAULT_TAIL)
+  const shown = tail > 0 ? filtered.slice(-tail) : filtered
+  const all = analyzeCalls(entries)
+  const bad = all.filter(c => !c.complete).length
+  const audits = filtered.filter(e => isAudit(e.record)).length
+  process.stdout.write([
+    `文件   ${files.map(f => path.basename(f)).join(', ')}`,
+    `筛选   ${shown.length}/${filtered.length} 条${o.call || o.session || o.tool || o.errors ? '（已应用过滤条件）' : `（默认最近 ${DEFAULT_TAIL} 条）`} · 命中审计记录 ${audits} 条 · 全文件不完整调用 ${bad} 个`,
+    '',
+    renderTable(shown),
+    '',
+    bad > 0 ? `提示: 有 ${bad} 个调用记录不完整，用 --incomplete 查看详情。` : '提示: 未发现记录不完整的调用。',
+  ].join('\n') + '\n')
+  return 0
+}
+
+try {
+  process.exitCode = main()
+} catch (err) {
+  process.stderr.write(`audit-log: ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exitCode = 1
+}