sillyspec 3.33.8 → 3.33.9

package/eval/knowledge/lib/metrics.mjs

@@ -0,0 +1,56 @@
+/**
+ * eval/knowledge/lib/metrics.mjs — 检索评测指标纯函数（零 IO 零全局状态，可单测）
+ *
+ * 候选与期望的统一单位是「命中键」字符串（file#anchor / D-id / FR-id / 文件路径），
+ * 由 engine 层归一成本模块的输入；本模块只做排名数学。
+ * 浮点输出统一 4 位小数、键序固定——baseline.json 可 diff 的前提。
+ */
+
+/** 期望条目在有序命中列表中的最佳名次（1-based；未命中 = Infinity）。 */
+export function rankOf(hits, expectedKeys) {
+  const want = new Set(expectedKeys || [])
+  let best = Infinity
+  for (let i = 0; i < hits.length; i++) {
+    if (want.has(hits[i])) best = Math.min(best, i + 1)
+  }
+  return best
+}
+
+/** Top-k 命中判定（rank 为 Infinity 视为未命中）。 */
+export function hitAtK(rank, k) {
+  return Number.isFinite(rank) && rank <= k
+}
+
+/** 平均倒数排名（未命中记 0）。 */
+export function mrr(ranks) {
+  if (ranks.length === 0) return 0
+  return ranks.reduce((s, r) => s + (Number.isFinite(r) ? 1 / r : 0), 0) / ranks.length
+}
+
+/** precision@k：前 k 个命中里属于期望集的占比（top 为空记 0）。 */
+export function precisionAtK(hits, expectedKeys, k) {
+  const want = new Set(expectedKeys || [])
+  const top = hits.slice(0, k)
+  if (top.length === 0) return 0
+  return top.filter((h) => want.has(h)).length / top.length
+}
+
+/** 汇总一组 case 的分面指标（键序固定 top1/top3/mrr/n；空集全零）。 */
+export function summarize(ranks) {
+  const n = ranks.length
+  const r4 = (x) => Math.round(x * 10000) / 10000
+  return {
+    top1: n > 0 ? r4(ranks.filter((r) => hitAtK(r, 1)).length / n) : 0,
+    top3: n > 0 ? r4(ranks.filter((r) => hitAtK(r, 3)).length / n) : 0,
+    mrr: r4(mrr(ranks)),
+    n,
+  }
+}
+
+/** 稳定排序：按 score 降序，同分保持原始序（评测输出确定性的前提）。 */
+export function stableSortByScore(items, scoreOf) {
+  return items
+    .map((it, i) => ({ it, i, s: scoreOf(it) }))
+    .sort((a, b) => (b.s - a.s) || (a.i - b.i))
+    .map((x) => x.it)
+}

package/eval/knowledge/lib/probes.mjs

@@ -0,0 +1,98 @@
+/**
+ * eval/knowledge/lib/probes.mjs — 六类缺陷探针执行器
+ *
+ * fixture 物化到 mkdtemp 仓根（<root>/.sillyspec/knowledge/...）后跑真实引擎函数，
+ * 断言按 evaluateCase 语义评估。pass = 修复后期望；缺陷存在时 pass=false（检出缺陷）。
+ * 临时目录 finally 清理；不写仓、不触网络/遥测。
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { PROBE_FIXTURES } from '../fixtures/index.mjs'
+import { runEntries, runDecisions, searchView, runScope, catalogHealth } from './engine.mjs'
+
+/** expected 匹配：含 "#" 精确；否则文件级前缀（hit === exp 或 hit.startsWith(exp + "#")）。 */
+export function hitMatches(hit, expected) {
+  if (String(expected).includes('#')) return hit === expected
+  return hit === expected || String(hit).startsWith(`${expected}#`)
+}
+
+function containsAll(hits, expected) {
+  return (expected || []).every((e) => hits.some((h) => hitMatches(h, e)))
+}
+
+function excludesAll(hits, expected) {
+  return (expected || []).every((e) => !hits.some((h) => hitMatches(h, e)))
+}
+
+/** 物化 fixture 到 mkdtemp 仓根；写入中途失败时清理临时目录再抛（不泄漏）。 */
+export function materialize(fixture) {
+  const root = mkdtempSync(join(tmpdir(), `ek-probe-${fixture.defect}-`))
+  try {
+    const kdir = join(root, '.sillyspec', 'knowledge')
+    for (const [rel, content] of Object.entries(fixture.files || {})) {
+      const p = join(kdir, rel)
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, content)
+    }
+  } catch (e) {
+    rmSync(root, { recursive: true, force: true })
+    throw e
+  }
+  return root
+}
+
+/** 单 case 评估 → { name, pass, detail, hits }。 */
+export async function evaluateCase(repoRoot, c) {
+  const expect = c.expect || {}
+  const fails = []
+  let hits = []
+  if (c.kind === 'entries' || c.kind === 'search' || c.kind === 'decisions' || c.kind === 'scope') {
+    if (c.kind === 'entries') hits = (await runEntries(repoRoot, c.query)).hits
+    else if (c.kind === 'decisions') hits = (await runDecisions(repoRoot, c.query)).hits
+    else if (c.kind === 'scope') hits = runScope(repoRoot, c.scope_files || []).merged
+    else {
+      const rows = await searchView(repoRoot, c.query, Infinity)
+      hits = rows.map((r) => r.file)
+      if (expect.score_contract) {
+        const bad = rows.filter((r) => r.score !== r.matchedTags.length)
+        if (bad.length > 0) fails.push(`score 契约违反：${bad.map((r) => `${r.file} score=${r.score} 命中=${r.matchedTags.length}`).join('；')}`)
+      }
+    }
+    if (!containsAll(hits, expect.contains)) fails.push(`缺少期望命中：${(expect.contains || []).filter((e) => !hits.some((h) => hitMatches(h, e))).join('、')}`)
+    if (!excludesAll(hits, expect.excludes)) fails.push(`出现禁止命中：${(expect.excludes || []).filter((e) => hits.some((h) => hitMatches(h, e))).join('、')}`)
+    if (expect.empty === true && hits.length > 0) fails.push(`期望空命中但得到 ${hits.length} 条`)
+    if (expect.empty === false && hits.length === 0) fails.push('期望非空但零命中')
+  } else if (c.kind === 'catalog') {
+    const health = catalogHealth(repoRoot)
+    hits = [`total=${health.total}`, `anchored=${health.anchored}`, `files=${health.files}`, `linked=${health.linked}`]
+    for (const [k, v] of Object.entries(expect.health || {})) {
+      if (health[k] !== v) fails.push(`catalog.${k}=${health[k]} ≠ 期望 ${v}`)
+    }
+  } else {
+    fails.push(`未知 kind：${c.kind}`)
+  }
+  return {
+    name: c.name || c.kind,
+    pass: fails.length === 0,
+    detail: fails.length === 0 ? `ok（hits=${hits.length}）` : fails.join('；'),
+    hits: hits.slice(0, 8),
+  }
+}
+
+/** 全量探针（六个 fixture 顺序执行；tmp 目录 finally 清理）。 */
+export async function runAllProbes() {
+  const out = []
+  for (const fixture of PROBE_FIXTURES) {
+    let root = ''
+    try {
+      root = materialize(fixture)
+      const cases = []
+      for (const c of fixture.cases) cases.push(await evaluateCase(root, c))
+      out.push({ defect: fixture.defect, pass: cases.every((c) => c.pass), cases })
+    } finally {
+      if (root) rmSync(root, { recursive: true, force: true })
+    }
+  }
+  return out
+}

package/eval/knowledge/lib/report.mjs

@@ -0,0 +1,82 @@
+/**
+ * eval/knowledge/lib/report.mjs — 控制台表与 baseline 对比
+ */
+
+/** 四舍五入 4 位（与 metrics 同口径）。 */
+const r4 = (x) => Math.round(Number(x) * 10000) / 10000
+
+/** 控制台表：每仓每面的 raw/rendered 指标 + probes + self smoke。 */
+export function renderTable(result) {
+  const lines = []
+  lines.push('知识检索评测基线（eval/knowledge）')
+  for (const repo of Object.keys(result.metrics || {})) {
+    const c = result.cases?.[repo] || {}
+    lines.push(`\n[${repo}] organic=${c.organic ?? 0} self=${c.self ?? 0}`)
+    for (const [face, m] of Object.entries(result.metrics[repo])) {
+      lines.push(`  ${face.padEnd(9)} raw top1=${m.raw.top1} top3=${m.raw.top3} mrr=${m.raw.mrr} n=${m.raw.n}`
+        + ` | rendered top1=${m.rendered.top1} top3=${m.rendered.top3} | truncated=${(m.truncated || []).length}`)
+      if (m.subsets) {
+        const parts = Object.entries(m.subsets).map(([k, v]) => `${k}(n=${v.n},top1=${v.top1},top3=${v.top3},reach=${v.reachable})`).join(' ')
+        lines.push(`    subsets: ${parts}`)
+      }
+      if (Array.isArray(m.scope_unreachable) && m.scope_unreachable.length > 0) {
+        lines.push(`    scope_unreachable: ${m.scope_unreachable.join('、')}`)
+      }
+    }
+    const ss = result.self_smoke?.[repo]
+    if (ss && ss.cases > 0) {
+      lines.push(`  self-smoke cases=${ss.cases} own_hit_top3=${ss.own_hit_top3} name_only=${ss.name_only_top3} leak_gap=${ss.leak_gap}`)
+    }
+  }
+  lines.push('\n缺陷探针：')
+  for (const [defect, pass] of Object.entries(result.probes || {})) {
+    lines.push(`  ${pass ? 'GREEN' : 'RED  '} ${defect}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * baseline 对比：快照指纹不一致 → snapshot_mismatch；各面 raw.top3 与 probe 状态变化逐项列出；
+ * baselineSummary 返回基线侧每面 raw/rendered 全量指标（mismatch 时两套指标都要可见）。
+ * @returns {{mismatches: string[], changes: string[], baselineSummary: object}}
+ */
+export function diffBaseline(cur, base) {
+  const mismatches = []
+  const changes = []
+  const baselineSummary = {}
+  if (!base || typeof base !== 'object') return { mismatches, changes, baselineSummary }
+  for (const repo of Object.keys(cur.snapshot || {})) {
+    const b = base.snapshot?.[repo]
+    const c = cur.snapshot[repo]
+    if (!b) continue
+    if (b.head !== c.head || b.knowledge_hash !== c.knowledge_hash) {
+      mismatches.push(`${repo}: snapshot_mismatch（head ${String(b.head).slice(0, 8)}→${String(c.head).slice(0, 8)}）`)
+    }
+  }
+  for (const repo of Object.keys(cur.metrics || {})) {
+    const bm = base.metrics?.[repo] || {}
+    for (const face of Object.keys(cur.metrics[repo])) {
+      const bmFace = bm[face]
+      const c3 = cur.metrics[repo][face].raw.top3
+      if (bmFace && bmFace.raw) {
+        baselineSummary[`${repo}/${face}`] = { raw: bmFace.raw, rendered: bmFace.rendered }
+        const b3 = bmFace.raw.top3
+        if (typeof b3 === 'number' && r4(b3) !== r4(c3)) changes.push(`${repo}/${face} raw.top3 ${b3} → ${c3}`)
+      }
+    }
+  }
+  for (const defect of Object.keys(cur.probes || {})) {
+    if (typeof base.probes?.[defect] === 'boolean' && base.probes[defect] !== cur.probes[defect]) {
+      changes.push(`probe ${defect}: ${base.probes[defect] ? 'GREEN' : 'RED'} → ${cur.probes[defect] ? 'GREEN' : 'RED'}`)
+    }
+  }
+  // self 趋势指标（不进质量门槛，仅 diff 可见——own_hit_top3 变化反映蒸馏→检索链路质量）
+  for (const repo of Object.keys(cur.self_smoke || {})) {
+    const b = base.self_smoke?.[repo]
+    const c = cur.self_smoke[repo]
+    if (b && c && typeof b.own_hit_top3 === 'number' && typeof c.own_hit_top3 === 'number' && r4(b.own_hit_top3) !== r4(c.own_hit_top3)) {
+      changes.push(`self[${repo}] own_hit_top3 ${b.own_hit_top3} → ${c.own_hit_top3}（趋势，非门槛）`)
+    }
+  }
+  return { mismatches, changes, baselineSummary }
+}

package/eval/knowledge/lib/repos.mjs

@@ -0,0 +1,41 @@
+/**
+ * eval/knowledge/lib/repos.mjs — 评测仓参数解析（项目中立：不枚举任何具体项目）
+ *
+ * 约定：--repo 接受逗号分隔的路径列表；每项可写 `<label>:<path>` 显式指定仓标签
+ * （label 用于 organic 数据集匹配与 baseline 键），省略时取路径 basename。
+ * 缺省（不传 --repo）= 当前仓。Windows 盘符（C:/、C:\）不当作 label 分隔符。
+ */
+import { basename, resolve } from 'node:path'
+
+/** 解析单项：`label:path` 或裸 path → { label, path }。盘符形态（`C:\` / `C:/`）不当作 label。 */
+export function parseRepoSpec(item) {
+  const raw = String(item || '').trim()
+  if (!raw) throw new Error('--repo 含空项')
+  if (/^[A-Za-z]:[\\/]/.test(raw)) {
+    const abs = resolve(raw)
+    return { label: basename(abs) || abs, path: abs }
+  }
+  const m = /^([^:/\\]+):(.+)$/.exec(raw)
+  if (m) return { label: m[1], path: resolve(m[2]) }
+  const abs = resolve(raw)
+  return { label: basename(abs) || abs, path: abs }
+}
+
+/**
+ * 解析 --repo 参数 → Map<label, absPath>。
+ * @param {string|null} arg 原始值（逗号分隔；null/''/'all' = 缺省当前仓）
+ * @param {string} cwd 当前仓根
+ * @returns {Map<string,string>}
+ */
+export function parseRepoArgs(arg, cwd) {
+  const items = arg && arg !== 'all' ? String(arg).split(',').map((s) => s.trim()).filter(Boolean) : []
+  const specs = items.length > 0 ? items.map(parseRepoSpec) : [parseRepoSpec(cwd)]
+  const out = new Map()
+  for (const { label, path } of specs) {
+    if (out.has(label) && out.get(label) !== path) {
+      throw new Error(`仓标签冲突：${label}（${out.get(label)} 与 ${path}）——请用 label:path 显式区分`)
+    }
+    out.set(label, path)
+  }
+  return out
+}

package/eval/knowledge/lib/snapshot.mjs

@@ -0,0 +1,55 @@
+/**
+ * eval/knowledge/lib/snapshot.mjs — 评测快照指纹（git HEAD + knowledge 树内容 sha256）
+ *
+ * 指纹口径：相对路径 POSIX 归一后按字典序排序，逐文件喂 "路径\0内容\0" 到单一 sha256。
+ * 目录缺失 = 空树哈希（合法形态：平台仓可能有 knowledge 但无 fr/ 子目录等）。
+ * baseline 对比只在指纹一致时可信——不一致必须显式告警（runner 输出 snapshot_mismatch）。
+ */
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+export function gitHead(repoRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: repoRoot, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
+/** 递归收集文件相对路径（POSIX 归一、字典序稳定；目录缺失 = 空数组）。 */
+function listFiles(dir, base = dir, out = []) {
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) listFiles(p, base, out)
+    else if (e.isFile()) out.push(relative(base, p).replace(/\\/g, '/'))
+  }
+  return out
+}
+
+/** knowledge 树内容哈希（相对路径排序 + \0 分隔喂 sha256）。 */
+export function hashKnowledgeTree(knowledgeDir) {
+  const h = createHash('sha256')
+  for (const rel of listFiles(knowledgeDir).sort()) {
+    h.update(rel)
+    h.update('\0')
+    try { h.update(readFileSync(join(knowledgeDir, rel))) } catch { h.update('<unreadable>') }
+    h.update('\0')
+  }
+  return h.digest('hex')
+}
+
+/** 仓快照指纹（head + knowledge_hash + 文件数，供 baseline 比对与输出）。 */
+export function snapshotFingerprint(repoRoot) {
+  const knowledgeDir = join(repoRoot, '.sillyspec', 'knowledge')
+  return {
+    head: gitHead(repoRoot),
+    knowledge_hash: hashKnowledgeTree(knowledgeDir),
+    knowledge_files: listFiles(knowledgeDir).length,
+  }
+}

package/eval/knowledge/run.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * eval/knowledge/run.mjs — 知识检索评测 runner（变更 0：评测面）
+ *
+ * 通用性（工具中立）：不枚举任何具体项目——`--repo` 接受任意仓路径（逗号分隔，
+ * 可 `<label>:<path>` 显式标签），缺省评当前仓；organic 数据集的 repo 字段是标签，
+ * 与 `--repo` 的 label 或路径 basename 对应。
+ *
+ * 用法：
+ *   node eval/knowledge/run.mjs [--repo <path|label:path>[,<path>…]] [--face entries|decisions|search|scope|all]
+ *                               [--set-baseline] [--json] [--smoke]
+ *
+ * 设计锚：.sillyspec/changes/2026-11-02-knowledge-eval/design.md
+ * 零网络零遥测：强制 SILLYSPEC_KNOWLEDGE_VECTOR=off / SILLYSPEC_HITS_PUSH=0，只调纯读引擎；
+ * 唯一写点是 --set-baseline 的 baseline.json（临时文件+rename 原子落盘）与图派生缓存（可再生）。
+ * 面：entries@3（flow 📚）、decisions@5（rejected 优先）、search@10（cmdSearch 等价）、
+ *     scope@3/20（图遍历）；raw=引擎全量、rendered=消费面切片，per-case 名次进 details。
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { tmpdir } from 'node:os'
+import { loadOrganic, buildSelfCases, validateLabels } from './lib/dataset.mjs'
+import { runDecisions } from './lib/engine.mjs'
+import { snapshotFingerprint } from './lib/snapshot.mjs'
+import { runAllProbes } from './lib/probes.mjs'
+import { renderTable, diffBaseline } from './lib/report.mjs'
+import { runFace, rankWithMatches, FACES, subsetSummaries } from './lib/faces.mjs'
+import { summarize } from './lib/metrics.mjs'
+import { parseRepoArgs } from './lib/repos.mjs'
+
+process.env.SILLYSPEC_KNOWLEDGE_VECTOR = 'off'
+process.env.SILLYSPEC_HITS_PUSH = '0'
+
+const here = fileURLToPath(new URL('.', import.meta.url))
+const repoRoot = join(here, '..', '..')
+const DATASET = join(here, 'datasets', 'organic.jsonl')
+const BASELINE = join(here, 'baseline.json')
+
+const args = process.argv.slice(2)
+const has = (n) => args.includes(n)
+const val = (n) => {
+  const i = args.indexOf(n)
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : null
+}
+
+const facesArg = val('--face') || 'all'
+if (!['all', ...FACES].includes(facesArg)) {
+  console.error(`❌ 未知面：${facesArg}（可选 ${['all', ...FACES].join('|')}）`)
+  process.exit(2)
+}
+let REPO_ROOTS
+try {
+  REPO_ROOTS = parseRepoArgs(val('--repo'), repoRoot)
+} catch (e) {
+  console.error(`❌ ${e.message}`)
+  process.exit(2)
+}
+const wantFaces = facesArg === 'all' ? FACES : [facesArg]
+
+/** self 集 smoke：own 命中率 + name-only 对照（leak_gap = full − name_only，越接近 0 越靠变更名泄漏）。 */
+async function runSelfSmoke(repoPath, repo) {
+  const { cases, skipped } = buildSelfCases(repoPath, repo)
+  if (cases.length === 0) return { cases: 0, skipped: skipped.length }
+  let full = 0
+  let nameOnly = 0
+  for (const c of cases) {
+    const name = c.id.replace(/^self-/, '')
+    const ownHit = async (q) => rankWithMatches((await runDecisions(repoPath, q)).hits, c.own) <= 3
+    if (await ownHit(c.query)) full++
+    if (await ownHit(name)) nameOnly++
+  }
+  const n = cases.length
+  const r4 = (x) => Math.round(x * 10000) / 10000
+  return {
+    cases: n,
+    skipped: skipped.length,
+    own_hit_top3: r4(full / n),
+    name_only_top3: r4(nameOnly / n),
+    leak_gap: r4((full - nameOnly) / n),
+  }
+}
+
+/** --smoke：零数据依赖冒烟（probes + baseline 原子读写往返于 mkdtemp）。 */
+async function runSmoke() {
+  const probes = Object.fromEntries((await runAllProbes()).map((p) => [p.defect, p.pass]))
+  const dir = mkdtempSync(join(tmpdir(), 'ek-smoke-'))
+  try {
+    const f = join(dir, 'baseline.json')
+    const tmp = `${f}.tmp`
+    const payload = { version: 1, probes }
+    writeFileSync(tmp, JSON.stringify(payload, null, 2))
+    renameSync(tmp, f)
+    const back = JSON.parse(readFileSync(f, 'utf8'))
+    if (JSON.stringify(back) !== JSON.stringify(payload)) throw new Error('baseline 读写往返失败')
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+  return probes
+}
+
+async function main() {
+  if (has('--smoke')) {
+    const probes = await runSmoke()
+    const detected = Object.entries(probes).filter(([, p]) => p === false).map(([d]) => d)
+    const out = { ok: true, mode: 'smoke', probes, detected_defects: detected }
+    if (has('--json')) {
+      console.log(JSON.stringify(out, null, 2))
+      return
+    }
+    console.log(renderTable({ metrics: {}, probes }))
+    console.log(detected.length
+      ? `\nℹ️ 检出缺陷 ${detected.length} 类（probe RED = 缺陷仍在，修复后转 GREEN）：${detected.join('、')}`
+      : '\n✅ 全部探针 GREEN')
+    return
+  }
+
+  const { cases: organic, skipped } = loadOrganic(DATASET)
+  const labelIssues = validateLabels(organic, REPO_ROOTS)
+  const result = {
+    version: 1,
+    generated_by: 'eval/knowledge/run.mjs',
+    snapshot: {},
+    cases: {},
+    metrics: {},
+    self_smoke: {},
+    probes: {},
+    label_issues: labelIssues,
+    warnings: [],
+  }
+  for (const [repo, path] of REPO_ROOTS) {
+    const repoCases = organic.filter((c) => c.repo === repo)
+    result.cases[repo] = { organic: repoCases.length, self: 0 }
+    if (!existsSync(join(path, '.sillyspec', 'knowledge'))) {
+      result.warnings.push(existsSync(path)
+        ? `仓无 .sillyspec/knowledge：${repo} → ${path}`
+        : `仓路径不存在：${repo} → ${path}`)
+      result.snapshot[repo] = { head: '', knowledge_hash: '', knowledge_files: 0, missing: true }
+      result.metrics[repo] = {}
+      continue
+    }
+    result.snapshot[repo] = snapshotFingerprint(path)
+    result.metrics[repo] = {}
+    for (const face of wantFaces) {
+      let faceCases = []
+      if (face === 'entries') faceCases = repoCases.filter((c) => c.face === 'entries' && c.subset !== 'fusion')
+      else if (face === 'decisions') faceCases = repoCases.filter((c) => c.face === 'decisions' && c.subset !== 'fusion')
+      else if (face === 'search') faceCases = repoCases.filter((c) => c.face === 'entries' && c.subset !== 'fusion')
+      else if (face === 'fr') faceCases = repoCases.filter((c) => c.face === 'fr')
+      else if (face === 'scope') faceCases = repoCases.filter((c) => Array.isArray(c.scope_files) && c.scope_files.length > 0 && c.face !== 'fr')
+      const faceResult = await runFace(path, face, faceCases)
+      if (face === 'scope') {
+        // 子集单列（FR-05）：frozen（原 5 条）与 added 分开报，禁止用新增 case 掩盖冻结子集
+        faceResult.subsets = subsetSummaries(faceResult, faceCases)
+        faceResult.scope_unreachable = faceResult.details.filter((d) => d.raw_rank === null).map((d) => d.id)
+      } else if (face === 'entries' || face === 'decisions' || face === 'fr') {
+        // fusion / fr prod-approx 子集单列：新增 case 不混入旧 case 聚合解读
+        if (faceCases.some((c) => c.subset)) faceResult.subsets = subsetSummaries(faceResult, faceCases)
+      }
+      result.metrics[repo][face] = faceResult
+    }
+    const self = await runSelfSmoke(path, repo)
+    result.self_smoke[repo] = self
+    result.cases[repo].self = self.cases
+  }
+  const unmatched = organic.filter((c) => !REPO_ROOTS.has(c.repo))
+  result.probes = Object.fromEntries((await runAllProbes()).map((p) => [p.defect, p.pass]))
+
+  let diffs = { mismatches: [], changes: [], baselineSummary: {} }
+  if (has('--set-baseline')) {
+    const tmp = `${BASELINE}.tmp-${process.pid}`
+    writeFileSync(tmp, JSON.stringify(result, null, 2) + '\n')
+    renameSync(tmp, BASELINE) // 原子落盘（中途崩溃不产半截基线）
+  } else if (existsSync(BASELINE)) {
+    try {
+      diffs = diffBaseline(result, JSON.parse(readFileSync(BASELINE, 'utf8')))
+    } catch (e) {
+      diffs.error = `baseline 解析失败：${e.message}——按无基线处理（当前指标仍有效）`
+    }
+  }
+
+  if (has('--json')) {
+    console.log(JSON.stringify({ ok: true, skipped_cases: skipped.length, unmatched_cases: unmatched.length, ...result, diff: diffs }, null, 2))
+    return
+  }
+  console.log(renderTable(result))
+  if (result.warnings.length > 0) console.log(`\n⚠️ ${result.warnings.join('；')}`)
+  if (labelIssues.length > 0) console.log(`\n⚠️ 数据集标签自检 ${labelIssues.length} 条问题（结构性不可命中）：${labelIssues.map((i) => `${i.id}:${i.reason}`).join(' ')}`)
+  if (skipped.length > 0) console.log(`\n⚠️ organic 跳过 ${skipped.length} 条（字段缺失/期望空）：${skipped.map((s) => `${s.id || `L${s.line}`}:${s.reason}`).join(' ')}`)
+  if (unmatched.length > 0) console.log(`\n⚠️ organic 有 ${unmatched.length} 条未匹配本次仓标签（${[...new Set(unmatched.map((c) => c.repo))].join('、')}）——用 --repo label:path 对齐标签或忽略`)
+  if (diffs.error) console.log(`\n⚠️ ${diffs.error}`)
+  if (diffs.mismatches.length > 0) {
+    console.log(`\n⚠️ ${diffs.mismatches.join('；')}——基线与当前快照不一致，两套指标并列如下`)
+    for (const [k, v] of Object.entries(diffs.baselineSummary || {})) {
+      console.log(`   baseline ${k}: raw top1=${v.raw.top1} top3=${v.raw.top3} mrr=${v.raw.mrr}`
+        + ` | rendered top1=${v.rendered.top1} top3=${v.rendered.top3} mrr=${v.rendered.mrr}`)
+    }
+  }
+  if (diffs.changes.length > 0) console.log(`\n📊 相对 baseline 变化：\n  ${diffs.changes.join('\n  ')}`)
+  if (has('--set-baseline')) console.log(`\n✅ baseline 已写入 ${BASELINE}`)
+}
+
+main().catch((e) => {
+  console.error(`❌ 评测失败：${e && e.stack ? e.stack : e}`)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.33.8",
+  "version": "3.33.9",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -28,7 +28,8 @@
     "test": "node test/run-tests.mjs",
     "lint": "node test/check-syntax.mjs",
     "eval:dry": "node eval/run.mjs --dry-run",
-    "eval:pilot": "node eval/run.mjs --pilot"
+    "eval:pilot": "node eval/run.mjs --pilot",
+    "eval:knowledge": "node eval/knowledge/run.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1",

package/src/config-schema.js

@@ -72,12 +72,24 @@ export const LOCAL_YAML_SCHEMA = {
         { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
         { path: 'commands.test_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['resolveTestTimeoutMs (src/verify-postcheck.js)'], desc: 'commands.test 超时秒数（R9 实证 2026-09-23：全量套件实测可达 27min，固定 600s 帽必杀）——优先级 local.yaml 本键 > env SILLYSPEC_TEST_TIMEOUT_MS > 缺省 600。慢仓在此提帽，防真慢套件被当超时失败。', example: '2400' },
         { path: 'commands.lint_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyLintCheck (src/verify-postcheck.js)'], desc: 'commands.lint 超时秒数——优先级 显式调用参 > 本键 > env SILLYSPEC_LINT_TIMEOUT_MS > 缺省 180（快照内 junction I/O 慢，快照路径调用侧显式传 300）。', example: '600' },
+        { path: 'commands.metrics', type: 'string', optional: true, status: 'live', readers: ['runVerifyMetricsCheck (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)'], desc: '【2026-10-29-open-metrics-gate】可选指标门命令——收口实测在隔离快照内执行，非零退出=门红阻断收口；未配置或标 unavailable 跳过留痕（fail-open）。适合复杂度上限/重复率/死代码/覆盖率阈值类秒级检查：命令开放不绑定工具，生态/构建工具检查任务（npx 类零安装、mvn/gradle 检查目标等）或仓内自写脚本均可；执行时注入 SILLYSPEC_CHANGE_FILES（本变更文件清单，POSIX 相对路径换行分隔）供大仓增量门只扫变更面（历史存量债不拦新变更）；变异测试等慢工具建议提帽或放 pre-push/CI 层。', example: 'npx jscpd src' },
+        { path: 'commands.metrics_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyMetricsCheck (src/verify-postcheck.js)'], desc: 'commands.metrics 超时秒数——优先级 显式调用参 > 本键 > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒） > 缺省 180（快照内 junction I/O 慢，快照路径调用侧显式传 300）。', example: '600' },
         { path: 'commands.smoke', type: 'string', optional: true, status: 'live', readers: ['executeVerifyQualityScan (src/run/verify-quality-scan.js)'], desc: '接口冒烟命令——verify 阶段 CLI 亲跑（脚本自理服务生命周期：后台起服+轮询就绪+finally 杀），300s 超时帽，失败/超时只记失败态不阻断本步、触发 PASS 封顶（D-002）；指纹含此键，未变不重跑。', example: 'node scripts/smoke.mjs' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
         { path: 'commands.knowledge-gate', type: 'boolean', optional: true, status: 'live', readers: ['completeStep (src/run/complete.js)'], desc: '【2026-09-28-unclear-req-to-brainstorm FR-03/D-004】brainstorm 方案步（提出 2-3 种方案）--done 知识检索命中回显开关——缺省 true=开（对 --output 与 decisions.md 条目跑既有检索匹配器，命中 warn 回显「须 evidence 回应或说明不复潮」不阻断）；false（或 off）关回显，无命中时输出与现状一致。', example: 'false' },
         { path: 'commands.scan:check', type: 'string', optional: true, status: 'live', readers: ['scan 漂移检查（scripts/scan-drift-check.py 经 scan 流程调用）'], desc: '【2026-10-23-schema-registration-debt 平台仓 dogfood 补登】scan 产物漂移自检命令。', example: 'python scripts/scan-drift-check.py' },
       ],
     },
+    {
+      id: 'metrics_routes',
+      title: '指标门路由（多语言/monorepo）',
+      note: '【2026-10-29-metrics-routes】与 commands.metrics 单命令门共存：按变更文件面 ∩ gate.paths 路径前缀路由，仅执行命中 gate（串行）；语言中立（路径集合，不枚举语言/框架）。段未配置=零变化。',
+      keys: [
+        { path: 'metrics_routes.<name>.paths', type: 'array', optional: true, status: 'live', readers: ['extractMetricsRoutes (src/verify-postcheck.js)'], desc: 'gate 的路径前缀集合（仓根相对）——段全等匹配：frontend/ 不命中 frontend-v2/；引号数组 `["a/", "b/"]` 或逗分裸串均可。', example: '["frontend/", "packages/web/"]' },
+        { path: 'metrics_routes.<name>.command', type: 'string', optional: true, status: 'live', readers: ['runVerifyMetricsRoutesCheck (src/verify-postcheck.js)'], desc: 'gate 的指标门命令——gate 命中（变更文件面 ∩ paths 非空）才执行，非零退出=门红；gate 子进程注入 SILLYSPEC_CHANGE_FILES=该 gate 命中子集（gate 内工具可增量扫）。', example: 'npx --prefix frontend eslint . --max-warnings 0' },
+        { path: 'metrics_routes.<name>.timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyMetricsRoutesCheck (src/verify-postcheck.js)'], desc: 'gate 级超时秒数——优先级 本键 > 调用侧快照帽 > commands.metrics_timeout_sec > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒）> 缺省 180。', example: '300' },
+      ],
+    },
     {
       id: 'checkpoint',
       title: '影子存档（task tick 快照）',
@@ -432,6 +444,16 @@ commands:
   # install: npm install   # worktree 依赖安装命令
   # test_timeout_sec: 2400   # commands.test 超时秒数（慢仓提帽；缺省 600，env SILLYSPEC_TEST_TIMEOUT_MS 同效）
   # lint_timeout_sec: 600    # commands.lint 超时秒数（缺省 180）
+  # metrics: npx jscpd src   # 可选指标门：收口实测非零退出阻断（复杂度/重复/死代码/覆盖率阈值类秒级检查；执行注入 SILLYSPEC_CHANGE_FILES=本变更文件清单可只扫变更面；变异测试类慢工具建议 pre-push/CI）
+  # metrics_timeout_sec: 600   # commands.metrics 超时秒数（缺省 180）
+# metrics_routes:             # 多语言/monorepo 路由门（与上面 metrics 单命令可共存；仅跑变更命中的 gate）
+#   web:
+#     paths: ["frontend/", "packages/web/"]   # 路径前缀集合（段全等：frontend/ 不蹭 frontend-v2/）
+#     command: npx --prefix frontend eslint . --max-warnings 0
+#   jvm:
+#     paths: ["backend/"]
+#     command: mvn -B -f backend/pom.xml pmd:check
+#     timeout_sec: 300         # gate 级超时（缺省 180）；gate 子进程注入 SILLYSPEC_CHANGE_FILES=命中子集
   # knowledge-gate: false    # 方案步 --done 知识检索命中回显开关（缺省 true 开；false 关回显）
 
 # ── 影子存档（task tick 快照；缺省开启零配置，仅在显式调优时写）──