@twinsearth/dsh-master 3.2.9 → 3.3.0

package/worker/edg.ts

@@ -0,0 +1,424 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · B1 `edg`（可执行决策图，设计 §7）。
+ *
+ * 一条边 = 「精确动作 + 确定性参数来源 + 守卫」，这是 HarnessMM 的核心资产：
+ * 慢模型只需在**作者步骤**写一次，之后由守卫命中直接复用。
+ *
+ * 硬约束（写死在实现里）：
+ *   * `schemaHash` 与当前工具 schema 不一致 ⇒ **整图作废**（不得复用旧决策）；
+ *   * 参数只能来自回执的**确定性提取**（literal / regex / jsonpath）——
+ *     解析不出来就直接判定该边不可用（**禁止模型幻觉参数**）；
+ *   * `destructive: true` 的边**默认不入池**（validate 直接拒）；
+ *   * 生命周期 `draft → validated → active → exhausted → archived`，非法跃迁一律拒绝；
+ *   * 图来源两种：慢模型作者步骤（`parseDraftFromModel`）或人工/AI 预置模板库。
+ *
+ * 作者成本**单独记**：`phase:'authoring'` + `account:'governance'`（由宿主记账，见 cost-optimizer）。
+ */
+
+import crypto from 'node:crypto'
+
+export type EdgState = 'draft' | 'validated' | 'active' | 'exhausted' | 'archived'
+export type ArgSourceKind = 'literal' | 'regex' | 'jsonpath'
+export type GuardKind = 'regex' | 'jsonpath' | 'equals'
+export type EdgSource = 'author' | 'template'
+
+export interface EdgArgSource {
+  arg: string
+  from: ArgSourceKind
+  expr: string
+}
+
+export interface EdgGuard {
+  kind: GuardKind
+  expr: string
+  negate?: boolean
+}
+
+export interface EdgEdge {
+  id: string
+  toolName: string
+  schemaHash: string
+  argSource: EdgArgSource[]
+  guard: EdgGuard
+  destructive: boolean
+  dependsOn?: string[]
+}
+
+export interface EdgGraph {
+  id: string
+  taskId: string
+  createdAt: number
+  source: EdgSource
+  state: EdgState
+  model?: string
+  /** 冻结后才可被 enforce 引用（§7 B4：RSI 产出候选，冻结后上线）。 */
+  frozen: boolean
+  edges: EdgEdge[]
+  /** 作者步骤消耗的 token（记 governance，不算节省） */
+  authorTokens: number
+  reason?: string
+}
+
+/** 当前工具 schema 的稳定哈希（tools 列表变化即整图作废）。 */
+export function schemaHashOf(toolName: string, parameters: unknown, description?: string): string {
+  const body = JSON.stringify({ toolName, parameters: parameters ?? {}, description: description ?? '' })
+  return `sha256:${crypto.createHash('sha256').update(body).digest('hex').slice(0, 16)}`
+}
+
+const tokensOf = (text: string): number => (text.length > 0 ? Math.ceil(text.length / 4) : 0)
+
+/* ------------------------------------------------------------------ *
+ * 确定性提取（禁止幻觉参数）
+ * ------------------------------------------------------------------ */
+
+/** 极简 JSONPath：`$.a.b` / `$.a[0].b`（够用即止，不做完整实现）。 */
+export function jsonPathGet(value: unknown, expr: string): unknown {
+  const path = String(expr ?? '').trim()
+  if (!path.startsWith('$')) return undefined
+  const segments: Array<string | number> = []
+  const body = path.slice(1)
+  const re = /\.([A-Za-z_$][\w$]*)|\[(\d+)\]/gu
+  let match: RegExpExecArray | null
+  let consumed = 0
+  while ((match = re.exec(body)) !== null) {
+    if (match.index !== consumed) return undefined
+    consumed = match.index + match[0].length
+    segments.push(match[2] === undefined ? match[1] : Number(match[2]))
+  }
+  if (consumed !== body.length) return undefined
+  let current: unknown = value
+  for (const segment of segments) {
+    if (current === null || current === undefined) return undefined
+    if (typeof segment === 'number') {
+      if (!Array.isArray(current)) return undefined
+      current = current[segment]
+    } else {
+      if (typeof current !== 'object') return undefined
+      current = (current as Record<string, unknown>)[segment]
+    }
+  }
+  return current
+}
+
+/** 把回执文本按需解析成 JSON（失败返回 undefined，不猜）。 */
+function asJson(text: string): unknown {
+  const raw = String(text ?? '')
+  try { return JSON.parse(raw) } catch { /* 继续尝试提取 JSON 片段 */ }
+  // 回执常带前缀（如 shell 的 STDOUT: 或说明行）：在**确定性位置**截取首个 { 到末个 }
+  // 再解析。这仍然是确定性的文本提取，不是猜测。
+  const start = raw.indexOf('{')
+  const end = raw.lastIndexOf('}')
+  if (start < 0 || end <= start) return undefined
+  try { return JSON.parse(raw.slice(start, end + 1)) } catch { return undefined }
+}
+
+/**
+ * 解析单个 argSource。**失败返回 undefined**（调用方据此判定该边不可用），
+ * 绝不回退到"模型给的参数"或默认值。
+ */
+export function resolveArg(source: EdgArgSource, receiptText: string): unknown {
+  const expr = String(source?.expr ?? '')
+  if (source?.from === 'literal') {
+    // literal 就是字面量本身（不做变量替换，避免"看起来像模板"的幻觉空间）
+    return expr
+  }
+  if (source?.from === 'regex') {
+    // expr 形如 `/(?<v>...)/` 或裸正则；取第一个捕获组，没有捕获组则取整个匹配。
+    const trimmed = expr.trim()
+    const body = trimmed.startsWith('/') && trimmed.lastIndexOf('/') > 0
+      ? trimmed.slice(1, trimmed.lastIndexOf('/'))
+      : trimmed
+    let re: RegExp
+    try { re = new RegExp(body, 'u') } catch { return undefined }
+    const match = re.exec(receiptText)
+    if (!match) return undefined
+    return match.groups?.value ?? match[1] ?? match[0]
+  }
+  if (source?.from === 'jsonpath') {
+    const json = asJson(receiptText)
+    if (json === undefined) return undefined
+    return jsonPathGet(json, expr)
+  }
+  return undefined
+}
+
+/** 解析整条边的参数；任一参数解析失败 ⇒ null（该边不可用于本次回执）。 */
+export function resolveEdgeArgs(edge: EdgEdge, receiptText: string): Record<string, unknown> | null {
+  const args: Record<string, unknown> = {}
+  for (const source of edge.argSource) {
+    const value = resolveArg(source, receiptText)
+    if (value === undefined) return null
+    args[source.arg] = value
+  }
+  return args
+}
+
+/* ------------------------------------------------------------------ *
+ * 守卫
+ * ------------------------------------------------------------------ */
+
+/** 守卫求值：命中返回 true。表达式非法 ⇒ false（宁可不命中，也不误替换）。 */
+export function evaluateGuard(guard: EdgGuard, receiptText: string): boolean {
+  if (!guard || typeof guard !== 'object') return false
+  let result = false
+  if (guard.kind === 'regex') {
+    const trimmed = String(guard.expr ?? '').trim()
+    const body = trimmed.startsWith('/') && trimmed.lastIndexOf('/') > 0
+      ? trimmed.slice(1, trimmed.lastIndexOf('/'))
+      : trimmed
+    try { result = new RegExp(body, 'u').test(receiptText) } catch { return false }
+  } else if (guard.kind === 'equals') {
+    result = receiptText.trim() === String(guard.expr ?? '').trim()
+  } else if (guard.kind === 'jsonpath') {
+    const json = asJson(receiptText)
+    if (json === undefined) return false
+    const value = jsonPathGet(json, String(guard.expr ?? ''))
+    result = value !== undefined && value !== null && value !== false && value !== '' && value !== 0
+  } else {
+    return false
+  }
+  return guard.negate === true ? !result : result
+}
+
+/* ------------------------------------------------------------------ *
+ * 图 store 与生命周期
+ * ------------------------------------------------------------------ */
+
+const LEGAL_TRANSITIONS: Record<EdgState, EdgState[]> = {
+  draft: ['validated', 'archived'],
+  validated: ['active', 'archived'],
+  active: ['exhausted', 'archived'],
+  exhausted: ['archived', 'active'],
+  archived: ['active'],
+}
+
+export interface ValidateOptions {
+  /** 当前工具 schema 哈希表：工具名 → schemaHash。 */
+  schemas: Record<string, string>
+  /** 允许入池的工具（默认全部）。 */
+  allowedTools?: string[]
+  /** 允许破坏性动作入池（默认 false）。 */
+  allowDestructive?: boolean
+  maxEdges?: number
+}
+
+export interface EdgStore {
+  addDraft(input: { taskId: string; edges: Array<Partial<EdgEdge> & { id?: string }>; source?: EdgSource; model?: string; authorText?: string }): EdgGraph
+  validate(graphId: string, options: ValidateOptions): { ok: boolean; state: EdgState; reason?: string }
+  activate(graphId: string): { ok: boolean; state: EdgState; reason?: string }
+  exhaust(graphId: string, reason?: string): { ok: boolean; state: EdgState }
+  archive(graphId: string): { ok: boolean; state: EdgState }
+  get(graphId: string): EdgGraph | null
+  list(state?: EdgState): EdgGraph[]
+  /** schema 变化的整图作废：返回被作废的图 id 列表。 */
+  invalidateBySchema(schemas: Record<string, string>): string[]
+  /** 作者成本合计（记 governance 用）。 */
+  authorCost(): { graphs: number; authorTokens: number }
+  reset(): void
+}
+
+export function createEdgStore(options: { now?: () => number; idFactory?: () => string } = {}): EdgStore {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  let seq = 0
+  const idFactory = typeof options.idFactory === 'function' ? options.idFactory : () => `edg_${now().toString(36)}_${(seq += 1).toString(36)}`
+  const graphs = new Map<string, EdgGraph>()
+
+  const clone = (graph: EdgGraph): EdgGraph => Object.freeze({ ...graph, edges: graph.edges.map((edge) => Object.freeze({ ...edge, argSource: edge.argSource.map((item) => ({ ...item })) })) }) as EdgGraph
+
+  function transition(graph: EdgGraph, to: EdgState, reason?: string): { ok: boolean; state: EdgState; reason?: string } {
+    if (!LEGAL_TRANSITIONS[graph.state].includes(to)) {
+      return { ok: false, state: graph.state, reason: `illegal-transition:${graph.state}->${to}` }
+    }
+    graph.state = to
+    if (reason !== undefined) graph.reason = reason
+    return { ok: true, state: graph.state }
+  }
+
+  function addDraft(input: { taskId: string; edges: Array<Partial<EdgEdge> & { id?: string }>; source?: EdgSource; model?: string; authorText?: string }): EdgGraph {
+    const edges = (Array.isArray(input?.edges) ? input.edges : []).map((edge, index) => Object.freeze({
+      id: String(edge?.id ?? `edge_${index + 1}`),
+      toolName: String(edge?.toolName ?? ''),
+      schemaHash: String(edge?.schemaHash ?? ''),
+      argSource: Array.isArray(edge?.argSource) ? edge.argSource.map((item) => Object.freeze({ arg: String(item?.arg ?? ''), from: String(item?.from ?? 'literal') as ArgSourceKind, expr: String(item?.expr ?? '') })) : [],
+      guard: Object.freeze({
+        kind: String(edge?.guard?.kind ?? 'regex') as GuardKind,
+        expr: String(edge?.guard?.expr ?? ''),
+        negate: edge?.guard?.negate === true,
+      }),
+      destructive: edge?.destructive === true,
+      dependsOn: Array.isArray(edge?.dependsOn) ? edge.dependsOn.map((item) => String(item)) : undefined,
+    }))
+    const graph: EdgGraph = {
+      id: idFactory(),
+      taskId: String(input?.taskId ?? ''),
+      createdAt: now(),
+      source: input?.source === 'template' ? 'template' : 'author',
+      state: 'draft',
+      model: input?.model === undefined ? undefined : String(input.model),
+      frozen: false,
+      edges,
+      authorTokens: tokensOf(String(input?.authorText ?? '')),
+    }
+    graphs.set(graph.id, graph)
+    return clone(graph)
+  }
+
+  function validate(graphId: string, opts: ValidateOptions): { ok: boolean; state: EdgState; reason?: string } {
+    const graph = graphs.get(String(graphId))
+    if (!graph) return { ok: false, state: 'draft', reason: 'graph-not-found' }
+    const allowed = Array.isArray(opts?.allowedTools) && opts.allowedTools.length > 0 ? new Set(opts.allowedTools) : null
+    const maxEdges = Math.max(1, Number(opts?.maxEdges ?? 32) || 32)
+    const ids = new Set(graph.edges.map((edge) => edge.id))
+    for (const edge of graph.edges) {
+      if (!edge.toolName) return { ok: false, state: graph.state, reason: 'edge-missing-tool' }
+      if (allowed && !allowed.has(edge.toolName)) return { ok: false, state: graph.state, reason: `tool-not-allowed:${edge.toolName}` }
+      // schema 校验：拿不到当前哈希 ⇒ 视为不一致（fail-closed）
+      const current = opts?.schemas?.[edge.toolName]
+      if (!current || current !== edge.schemaHash) return { ok: false, state: graph.state, reason: `schema-mismatch:${edge.toolName}` }
+      for (const source of edge.argSource) {
+        if (!source.arg) return { ok: false, state: graph.state, reason: 'arg-source-missing-arg' }
+        if (!['literal', 'regex', 'jsonpath'].includes(source.from)) return { ok: false, state: graph.state, reason: `arg-source-invalid:${source.from}` }
+      }
+      if (!['regex', 'jsonpath', 'equals'].includes(edge.guard.kind)) return { ok: false, state: graph.state, reason: `guard-kind-invalid:${edge.guard.kind}` }
+      // 破坏性动作默认不入池
+      if (edge.destructive && opts?.allowDestructive !== true) return { ok: false, state: graph.state, reason: `destructive-not-allowed:${edge.toolName}` }
+      for (const dep of edge.dependsOn ?? []) {
+        if (!ids.has(dep)) return { ok: false, state: graph.state, reason: `dependency-missing:${dep}` }
+      }
+    }
+    if (graph.edges.length === 0) return { ok: false, state: graph.state, reason: 'graph-empty' }
+    if (graph.edges.length > maxEdges) return { ok: false, state: graph.state, reason: 'graph-too-large' }
+    return transition(graph, 'validated')
+  }
+
+  function activate(graphId: string) {
+    const graph = graphs.get(String(graphId))
+    if (!graph) return { ok: false, state: 'draft' as EdgState, reason: 'graph-not-found' }
+    return transition(graph, 'active')
+  }
+
+  function exhaust(graphId: string, reason?: string) {
+    const graph = graphs.get(String(graphId))
+    if (!graph) return { ok: false, state: 'draft' as EdgState }
+    return transition(graph, 'exhausted', reason)
+  }
+
+  function archive(graphId: string) {
+    const graph = graphs.get(String(graphId))
+    if (!graph) return { ok: false, state: 'draft' as EdgState }
+    return transition(graph, 'archived')
+  }
+
+  /** schema 变化 ⇒ 整图作废（有边的 schemaHash 与当前不符即整图归档）。 */
+  function invalidateBySchema(schemas: Record<string, string>): string[] {
+    const invalidated: string[] = []
+    for (const graph of graphs.values()) {
+      if (graph.state === 'archived') continue
+      const bad = graph.edges.find((edge) => schemas?.[edge.toolName] !== edge.schemaHash)
+      if (!bad) continue
+      graph.state = 'archived'
+      graph.reason = `schema-drift:${bad.toolName}`
+      invalidated.push(graph.id)
+    }
+    return invalidated
+  }
+
+  function get(graphId: string): EdgGraph | null {
+    const graph = graphs.get(String(graphId))
+    return graph ? clone(graph) : null
+  }
+
+  function list(state?: EdgState): EdgGraph[] {
+    return [...graphs.values()].filter((graph) => (state === undefined ? true : graph.state === state)).map((graph) => clone(graph))
+  }
+
+  function authorCost(): { graphs: number; authorTokens: number } {
+    let authorTokens = 0
+    let count = 0
+    for (const graph of graphs.values()) {
+      if (graph.source !== 'author') continue
+      count += 1
+      authorTokens += graph.authorTokens
+    }
+    return { graphs: count, authorTokens }
+  }
+
+  function reset(): void {
+    graphs.clear()
+  }
+
+  return Object.freeze({ addDraft, validate, activate, exhaust, archive, get, list, invalidateBySchema, authorCost, reset })
+}
+
+/* ------------------------------------------------------------------ *
+ * 作者步骤：从慢模型输出里抽候选图（确定性解析，不猜）
+ * ------------------------------------------------------------------ */
+
+/**
+ * 从模型输出中抽取 `{ "edges": [...] }` JSON 块。
+ * 只接受 `edges` 数组里的合法字段；解析不出来返回 null（**不生成空图、不猜参数**）。
+ */
+export function parseDraftFromModel(text: string): { edges: Array<Partial<EdgEdge> & { id?: string }>; authorText: string } | null {
+  const raw = String(text ?? '')
+  if (raw.trim() === '') return null
+  const blocks = [...raw.matchAll(/```(?:json)?\s*([\s\S]*?)```/gu)].map((match) => match[1])
+  const candidates = blocks.length > 0 ? blocks : [raw]
+  for (const candidate of candidates) {
+    const start = candidate.indexOf('{')
+    const end = candidate.lastIndexOf('}')
+    if (start < 0 || end <= start) continue
+    let parsed: unknown
+    try { parsed = JSON.parse(candidate.slice(start, end + 1)) } catch { continue }
+    if (!parsed || typeof parsed !== 'object') continue
+    const edges = (parsed as { edges?: unknown }).edges
+    if (!Array.isArray(edges) || edges.length === 0) continue
+    const cleaned = edges
+      .filter((edge): edge is Record<string, unknown> => Boolean(edge) && typeof edge === 'object')
+      .map((edge) => ({
+        toolName: String(edge.toolName ?? ''),
+        schemaHash: String(edge.schemaHash ?? ''),
+        argSource: Array.isArray(edge.argSource) ? edge.argSource as EdgArgSource[] : [],
+        guard: (edge.guard && typeof edge.guard === 'object' ? edge.guard : { kind: 'regex', expr: '' }) as EdgGuard,
+        destructive: edge.destructive === true,
+        dependsOn: Array.isArray(edge.dependsOn) ? edge.dependsOn.map((item) => String(item)) : undefined,
+      }))
+      .filter((edge) => edge.toolName !== '')
+    if (cleaned.length === 0) continue
+    return { edges: cleaned, authorText: raw }
+  }
+  return null
+}
+
+/* ------------------------------------------------------------------ *
+ * 预置模板库（可选来源）
+ * ------------------------------------------------------------------ */
+
+export interface EdgTemplate {
+  id: string
+  description: string
+  edges: Array<Partial<EdgEdge> & { id?: string }>
+}
+
+export interface TemplateLibrary {
+  list(): EdgTemplate[]
+  find(id: string): EdgTemplate | null
+  /** 按工具名挑模板（供作者步骤参考）。 */
+  forTool(toolName: string): EdgTemplate[]
+}
+
+export function createTemplateLibrary(templates: EdgTemplate[] = []): TemplateLibrary {
+  const items = (Array.isArray(templates) ? templates : []).filter((item) => item && typeof item === 'object' && item.id)
+  return Object.freeze({
+    list: () => items.map((item) => ({ ...item, edges: item.edges.map((edge) => ({ ...edge })) })),
+    find: (id: string) => {
+      const found = items.find((item) => item.id === String(id))
+      return found ? { ...found, edges: found.edges.map((edge) => ({ ...edge })) } : null
+    },
+    forTool: (toolName: string) => items
+      .filter((item) => item.edges.some((edge) => String(edge.toolName ?? '') === String(toolName)))
+      .map((item) => ({ ...item, edges: item.edges.map((edge) => ({ ...edge })) })),
+  })
+}

package/worker/gdr.ts

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · B2 `gdr`（守卫决策复用，设计 §7）。
+ *
+ * 「守卫」二字的全部含义就是**匹配顺序**，任一环不满足即 miss、回落慢模型：
+ *
+ *   ① 工具名 → ② schemaHash → ③ 依赖边完成 → ④ 守卫表达式 → ⑤ 参数可确定性提取
+ *
+ * 只有五步全过才算 `hit`。miss 的原因必须**可归因**（`schema-drift` / `guard-miss` /
+ * `arg-unextractable` / `dependency-incomplete` / `tool-mismatch`），
+ * 命中率与未命中分布进报表，用于 RSI 改进（B4）。
+ *
+ * 安全取向：任何一步异常/歧义都判 miss —— 宁可回落慢模型，也不误替换。
+ */
+
+import type { Edg, EdgEdge, GuardVerdict } from './cost-spi.ts'
+import { evaluateGuard, resolveEdgeArgs } from './edg.ts'
+
+export type GdrStage = 'toolName' | 'schemaHash' | 'dependencies' | 'guard' | 'args'
+
+export type GdrMissReason =
+  | 'no-edge'
+  | 'tool-mismatch'
+  | 'schema-drift'
+  | 'dependency-incomplete'
+  | 'guard-miss'
+  | 'arg-unextractable'
+
+export interface GdrMatch extends GuardVerdict {
+  hit: boolean
+  edgeId?: string
+  reason?: GdrMissReason
+  /** 在第几环失败（命中时为 null）。 */
+  stage: GdrStage | null
+  receiptDigest: string
+  /** 命中时：确定性提取出的参数（可直接交给原生派发器）。 */
+  args?: Record<string, unknown>
+  wouldSaveTokens?: number
+  at: number
+}
+
+export interface GdrMatchInput {
+  receipt: { toolName: string; text: string; digest: string }
+  graph: Edg
+  /** 本任务已完成的边 id（依赖检查用）。 */
+  completed?: Set<string> | string[]
+  /** 当前工具 schema 哈希（缺省用边自身的 schemaHash ⇒ 视为一致）。 */
+  schemaHashOf?: (toolName: string) => string | undefined
+  /** 命中后的收益估算（供 shadow 对照；不给则不计）。 */
+  estimateSavedTokens?: (edge: EdgEdge, args: Record<string, unknown>) => number
+}
+
+export interface GdrStats {
+  matches: number
+  hits: number
+  hitRate: number
+  byReason: Record<GdrMissReason, number>
+  byTool: Record<string, { matches: number; hits: number }>
+  byStage: Record<GdrStage, number>
+  lastAt: number | null
+}
+
+const EMPTY_REASONS = (): Record<GdrMissReason, number> => ({
+  'no-edge': 0,
+  'tool-mismatch': 0,
+  'schema-drift': 0,
+  'dependency-incomplete': 0,
+  'guard-miss': 0,
+  'arg-unextractable': 0,
+})
+
+const EMPTY_STAGES = (): Record<GdrStage, number> => ({
+  toolName: 0,
+  schemaHash: 0,
+  dependencies: 0,
+  guard: 0,
+  args: 0,
+})
+
+export interface Gdr {
+  match(input: GdrMatchInput): GdrMatch
+  stats(): GdrStats
+  /** 报表用：命中率 + miss 分布 + 每个工具表现（RSI 的输入）。 */
+  report(): { stats: GdrStats; suggestions: string[] }
+  reset(): void
+}
+
+export function createGdr(options: { now?: () => number } = {}): Gdr {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  let matches = 0
+  let hits = 0
+  let lastAt: number | null = null
+  const byReason = EMPTY_REASONS()
+  const byStage = EMPTY_STAGES()
+  const byTool = new Map<string, { matches: number; hits: number }>()
+
+  function toolRow(toolName: string) {
+    if (!byTool.has(toolName)) byTool.set(toolName, { matches: 0, hits: 0 })
+    return byTool.get(toolName)!
+  }
+
+  function miss(reason: GdrMissReason, stage: GdrStage, receiptDigest: string, toolName: string): GdrMatch {
+    matches += 1
+    byReason[reason] += 1
+    byStage[stage] += 1
+    const row = toolRow(toolName)
+    row.matches += 1
+    lastAt = now()
+    return { hit: false, reason, stage, receiptDigest, at: lastAt }
+  }
+
+  /**
+   * 五步匹配。**顺序不可调换**：先便宜的后昂贵的，且 schema 漂移必须早于守卫判定——
+   * 否则旧图可能在新 schema 上"命中"，那是最危险的误替换。
+   */
+  function match(input: GdrMatchInput): GdrMatch {
+    const receipt = input?.receipt ?? { toolName: '', text: '', digest: '' }
+    const graph = input?.graph
+    const toolName = String(receipt.toolName ?? '')
+    const digest = String(receipt.digest ?? '')
+    const edges = Array.isArray(graph?.edges) ? graph.edges : []
+
+    // ① 工具名
+    if (edges.length === 0) return miss('no-edge', 'toolName', digest, toolName)
+    const candidates = edges.filter((edge) => String(edge?.toolName ?? '') === toolName)
+    if (candidates.length === 0) return miss('tool-mismatch', 'toolName', digest, toolName)
+
+    const completed = input?.completed instanceof Set
+      ? input.completed
+      : new Set(Array.isArray(input?.completed) ? input.completed : [])
+
+    // 逐条候选走完 ②③④⑤；任一条全过即命中。
+    let firstMiss: { reason: GdrMissReason; stage: GdrStage } | null = null
+    for (const edge of candidates) {
+      // ② schemaHash：漂移即整图作废（不匹配就直接 miss，绝不继续）
+      const current = typeof input?.schemaHashOf === 'function' ? input.schemaHashOf(edge.toolName) : undefined
+      if (current !== undefined && current !== edge.schemaHash) {
+        if (!firstMiss) firstMiss = { reason: 'schema-drift', stage: 'schemaHash' }
+        continue
+      }
+      // ③ 依赖边完成
+      const deps = Array.isArray(edge.dependsOn) ? edge.dependsOn : []
+      if (deps.some((dep) => !completed.has(String(dep)))) {
+        if (!firstMiss) firstMiss = { reason: 'dependency-incomplete', stage: 'dependencies' }
+        continue
+      }
+      // ④ 守卫表达式
+      if (!evaluateGuard(edge.guard, String(receipt.text ?? ''))) {
+        if (!firstMiss) firstMiss = { reason: 'guard-miss', stage: 'guard' }
+        continue
+      }
+      // ⑤ 参数可确定性提取
+      const args = resolveEdgeArgs(edge, String(receipt.text ?? ''))
+      if (args === null) {
+        if (!firstMiss) firstMiss = { reason: 'arg-unextractable', stage: 'args' }
+        continue
+      }
+      // 五步全过 ⇒ 命中
+      matches += 1
+      hits += 1
+      const row = toolRow(toolName)
+      row.matches += 1
+      row.hits += 1
+      lastAt = now()
+      const wouldSaveTokens = typeof input?.estimateSavedTokens === 'function'
+        ? Math.max(0, Number(input.estimateSavedTokens(edge, args)) || 0)
+        : 0
+      return {
+        hit: true,
+        edgeId: edge.id,
+        stage: null,
+        receiptDigest: digest,
+        args,
+        wouldSaveTokens,
+        at: lastAt,
+      }
+    }
+
+    const reason = firstMiss ?? { reason: 'guard-miss' as GdrMissReason, stage: 'guard' as GdrStage }
+    return miss(reason.reason, reason.stage, digest, toolName)
+  }
+
+  function stats(): GdrStats {
+    return {
+      matches,
+      hits,
+      hitRate: matches > 0 ? hits / matches : 0,
+      byReason: { ...byReason },
+      byTool: Object.fromEntries([...byTool.entries()].map(([tool, row]) => [tool, { ...row }])),
+      byStage: { ...byStage },
+      lastAt,
+    }
+  }
+
+  /** 报表 + 可执行的改进建议（喂给 RSI：哪一环最该优化）。 */
+  function report(): { stats: GdrStats; suggestions: string[] } {
+    const current = stats()
+    const suggestions: string[] = []
+    if (current.matches === 0) suggestions.push('样本为空：先跑 shadow 累积回执再评估')
+    if (current.byReason['schema-drift'] > 0) {
+      suggestions.push(`schema-drift ${current.byReason['schema-drift']} 次：优先复算 schemaHash 并回收旧图`)
+    }
+    if (current.byReason['guard-miss'] > 0) {
+      suggestions.push(`guard-miss ${current.byReason['guard-miss']} 次：守卫表达式过严或回执形态变化`)
+    }
+    if (current.byReason['arg-unextractable'] > 0) {
+      suggestions.push(`arg-unextractable ${current.byReason['arg-unextractable']} 次：参数来源应改为 jsonpath/regex 可命中的字段`)
+    }
+    if (current.byReason['dependency-incomplete'] > 0) {
+      suggestions.push(`dependency-incomplete ${current.byReason['dependency-incomplete']} 次：依赖链过长，考虑拆分图`)
+    }
+    if (current.byReason['tool-mismatch'] > 0) {
+      suggestions.push(`tool-mismatch ${current.byReason['tool-mismatch']} 次：图里缺少该工具的边`)
+    }
+    if (current.matches >= 20 && current.hitRate < 0.5) {
+      suggestions.push(`命中率 ${(current.hitRate * 100).toFixed(1)}% 偏低：建议先扩充图或放宽守卫`)
+    }
+    return { stats: current, suggestions }
+  }
+
+  function reset(): void {
+    matches = 0
+    hits = 0
+    lastAt = null
+    Object.assign(byReason, EMPTY_REASONS())
+    Object.assign(byStage, EMPTY_STAGES())
+    byTool.clear()
+  }
+
+  return Object.freeze({ match, stats, report, reset })
+}