dsh-experience 0.0.0-stage → 1.0.4

package/lib/capture.js

@@ -0,0 +1,663 @@
+/**
+ * dsh-experience / lib/capture.js — deterministic L1 experience capture.
+ *
+ * Pure functions only: no ctx, no fs, no network, no model calls. The caller
+ * (index.js) owns persistence and identity assignment, so everything here is
+ * directly testable with synthetic traces (tools/selftest.mjs).
+ */
+
+const SECRET_PATTERNS = [
+  [/sk-[A-Za-z0-9_-]{16,}/g, '‹redacted›'],
+  [/ghp_[A-Za-z0-9]{20,}/g, '‹redacted›'],
+  [/AKIA[0-9A-Z]{16}/g, '‹redacted›'],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/g, '‹redacted›'],
+  [/Bearer\s+[A-Za-z0-9._-]+/gi, 'Bearer ‹redacted›'],
+  [/([A-Za-z0-9_\-]*(?:api[_-]?key|token|secret|password|passwd|authorization))(\s*[:=]\s*)\S+/gi, '$1$2‹redacted›'],
+  [/(?=[A-Za-z0-9+/]*[A-Z])(?=[A-Za-z0-9+/]*[a-z])(?=[A-Za-z0-9+/]*[0-9])[A-Za-z0-9+/]{40,}={0,2}/g, '‹redacted›'],
+]
+
+const PATH_PATTERNS = [
+  [/[A-Za-z]:\\Users\\[^\\\s]+/gi, '~'],
+  [/[A-Za-z]:\\(?:[^\\\s]+\\){0,4}/g, '<path>/'],
+  [/\\\\[^\\\s]+\\/g, '<unc>/'],
+]
+
+const KNOWN_CONFIG_FILES = new Set([
+  'package.json', 'pyproject.toml', 'tsconfig.json', 'Cargo.toml', 'go.mod', 'requirements.txt',
+])
+
+export const DEFAULT_CONFIG = {
+  dailyLimit: 10,
+  libraryLimit: 200,
+  mergeThreshold: 0.75,
+  scopeMustMatch: true,
+  captureBudgetMs: 20,
+  maxRecordChars: 2000,
+  maxCalls: 40,
+  autoPromote: false,
+  minDistinctSessions: 2,
+  stepsJaccard: 0.7,
+  allowAutoVerified: false,
+  minEffectiveSteps: 2,
+}
+
+export function redact(text) {
+  let out = String(text == null ? '' : text)
+  for (const [pattern, replacement] of SECRET_PATTERNS) out = out.replace(pattern, replacement)
+  for (const [pattern, replacement] of PATH_PATTERNS) out = out.replace(pattern, replacement)
+  return out
+}
+
+export function clip(text, limit = 160) {
+  const source = redact(text).replace(/\s+/g, ' ').trim()
+  if (source.length <= limit) return source
+  return source.slice(0, Math.max(0, limit - 1)) + '…'
+}
+
+/** Truncate without redacting: features (scope, fingerprint) need the real path. */
+export function clipRaw(text, limit = 160) {
+  const source = String(text == null ? '' : text).replace(/\s+/g, ' ').trim()
+  if (source.length <= limit) return source
+  return source.slice(0, Math.max(0, limit - 1)) + '…'
+}
+
+const WRITE_TOOL = /^(write|edit|apply|patch|create|replace)/i
+const READ_TOOL = /^(read|view|open|cat)/i
+const SEARCH_TOOL = /^(grep|glob|search|find|query)/i
+const RUN_TOOL = /^(pwsh|bash|shell|exec|run|command|terminal)/i
+
+function firstString(value) {
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return value.map(firstString).find(Boolean) || ''
+  if (value && typeof value === 'object') {
+    for (const key of ['path', 'file', 'file_path', 'command', 'pattern', 'query', 'cmd']) {
+      const found = firstString(value[key])
+      if (found) return found
+    }
+  }
+  return ''
+}
+
+export function normalizePath(input) {
+  const raw = String(input || '').trim().replace(/^["'`]|["'`]$/g, '')
+  if (!raw) return ''
+  const segments = raw.split(/[\\/]+/).filter(Boolean)
+  const base = segments[segments.length - 1] || ''
+  if (KNOWN_CONFIG_FILES.has(base)) return base
+  const extMatch = base.match(/\.[A-Za-z0-9]+$/)
+  const ext = extMatch ? extMatch[0] : ''
+  const stem = ext ? base.slice(0, -ext.length) : base
+  const keepStem = /^(package|pyproject|index|main|mod)$/i.test(stem)
+  const name = keepStem ? stem : '<name>'
+  const parents = segments.slice(Math.max(0, segments.length - 2), segments.length - 1)
+  return [...parents, name + ext].join('/')
+}
+
+export function normalizeCommand(command) {
+  const raw = clip(command, 120)
+  if (!raw) return ''
+  if (/node\s+--test\b/.test(raw)) return 'node --test'
+  const nodeCall = raw.match(/node\s+([^\s|&;]+)/)
+  if (nodeCall) return `node ${normalizePath(nodeCall[1])}`
+  const parts = raw.split(/\s+/)
+  return parts.slice(0, 2).join(' ')
+}
+
+export function classify(call) {
+  const name = String((call && call.name) || '')
+  const hint = firstString(call && (call.hint || call.argsHint || call.args))
+  let kind = 'other'
+  if (WRITE_TOOL.test(name)) kind = 'write'
+  else if (READ_TOOL.test(name)) kind = 'read'
+  else if (SEARCH_TOOL.test(name)) kind = 'search'
+  else if (RUN_TOOL.test(name)) kind = 'run'
+  let target = ''
+  if (kind === 'run') target = normalizeCommand(hint)
+  else if (kind === 'write' || kind === 'read') target = normalizePath(hint)
+  else if (kind === 'search') target = clip(hint, 60)
+  else target = clip(hint, 40)
+  return { kind, target, name }
+}
+
+export function stepLabel(call) {
+  const { kind, target, name } = classify(call)
+  switch (kind) {
+    case 'write':
+      return target ? `写 ${target}` : '写文件'
+    case 'read':
+      return target ? `读 ${target.split('/').pop()}` : '读文件'
+    case 'run':
+      return target ? `跑 ${target}` : '执行命令'
+    case 'search':
+      return target ? `检索 ${target}` : '检索'
+    default:
+      return target ? `${name}(${target})` : name || '调用工具'
+  }
+}
+
+const EXPLORE_COMMAND = /\b(Get-ChildItem|Get-Content|Get-Item|Test-Path|Select-String|Select-Object|Measure-Object|gci|gc|dir|ls|cat|type|head|tail|find|rg|grep|where|which|stat)\b/i
+const TEST_COMMAND = /\b(test|spec|jest|vitest|mocha|pytest|check|--test)\b/i
+
+/** A successful run whose command looks like a test/verification command. */
+export function isTestCall(call) {
+  if (!call) return false
+  if (classify(call).kind !== 'run') return false
+  const raw = firstString(call.hint || call.argsHint || call.args)
+  return TEST_COMMAND.test(raw)
+}
+
+/**
+ * How much a successful call contributes to the *recipe* (not the transcript):
+ *   4 = execution/test run, 3 = write/edit, 2 = other real commands, 0 = exploration.
+ * Exploration (listing a directory, reading a reference file, grepping) is what an
+ * agent does because it does not know the answer yet; it must not become the
+ * "core steps" of the experience.
+ */
+export function stepPriority(call) {
+  const { kind } = classify(call)
+  if (kind === 'write') return 3
+  if (kind === 'run') {
+    const command = firstString(call && (call.hint || call.argsHint || call.args))
+    if (TEST_COMMAND.test(command)) return 4
+    if (EXPLORE_COMMAND.test(command)) return 0
+    return 2
+  }
+  return 0
+}
+
+/**
+ * A step label is only useful if a human could read it as an instruction.
+ * PowerShell scaffolding (variable assembly, New-Item/Test-Path probes, host
+ * output) is transcript noise: it describes how the agent measured the world,
+ * not what a second run should do.
+ */
+const NOISE_PREFIX = /^(\$|New-Item|New-ItemProperty|New-Object|Test-Path|Get-ChildItem|Get-Item|Set-Location|Push-Location|Pop-Location|Write-Host|Write-Output|Copy-Item|Remove-Item|Move-Item|Rename-Item)\b/
+const ASSIGNMENT = /^[A-Za-z_$][\w$]*\s*=[^=]/
+
+export function isNoiseStep(label) {
+  const text = String(label == null ? '' : label).trim()
+  if (!text) return true
+  if (NOISE_PREFIX.test(text) || ASSIGNMENT.test(text)) return true
+  const body = text.replace(/^(写|读|跑|检索)\s+/, '')
+  if (body !== text && (NOISE_PREFIX.test(body) || ASSIGNMENT.test(body))) return true
+  // a bare token with no action word and no separator is a fragment
+  if (!/\s/.test(text)) return true
+  return false
+}
+
+/** Steps that carry the recipe: successful writes and test/verification runs. */
+export function effectiveSteps(calls) {
+  let count = 0
+  for (const call of calls || []) {
+    if (!call || !call.ok) continue
+    if (stepPriority(call) < 3) continue
+    if (isNoiseStep(stepLabel(call))) continue
+    count++
+  }
+  return count
+}
+
+const ACTION_VERBS = /^(新增|写|跑通|修改|修复|重构|实现|添加|删除|更新|重命名|移动|替换|补|加|改为)/
+
+/** The object of a title must name a concrete artifact, not only <placeholders>. */
+export function actionableTitle(title) {
+  const text = String(title == null ? '' : title).trim()
+  if (!ACTION_VERBS.test(text)) return false
+  const object = text.replace(ACTION_VERBS, '').trim()
+  if (!object) return false
+  if (object.startsWith('$') || object.startsWith('-')) return false
+  // Drop <placeholders> first: what remains must still name something. A title
+  // like "写 src/<name>.js" collapses to "src/.js" — a directory and an
+  // extension with no artifact name — and is therefore rejected.
+  const stripped = object.replace(/<[^>]*>/g, '')
+  const base = stripped.split(/[\\/]+/).filter(Boolean).pop() || ''
+  const stem = base.replace(/\.[^.]+$/, '').replace(/[\s._-]+/g, '')
+  return /[A-Za-z0-9]{2,}/.test(stem)
+}
+
+/**
+ * G7 — refuses captures whose steps or title are not a reusable recipe.
+ * Runs after the G1..G6 chain; the caller writes trace.skipReason = reason.
+ */
+export function gateStepQuality(trace, record, config) {
+  const cfg = { ...DEFAULT_CONFIG, ...(config || {}) }
+  const calls = (trace && trace.calls) || []
+  const effective = effectiveSteps(calls)
+  if (effective < cfg.minEffectiveSteps) {
+    return {
+      ok: false,
+      reason: `G7: 有效步骤 ${effective} < ${cfg.minEffectiveSteps}（只有写操作与测试执行算核心步骤）`,
+      effective,
+    }
+  }
+  const title = String((record && record.title) || '')
+  if (!actionableTitle(title)) {
+    return { ok: false, reason: `G7: 标题「${title}」不含动作+对象，按命令碎片丢弃`, effective }
+  }
+  const when = String((record && record.when) || '')
+  if (/完成一项可复用的改动/.test(when)) {
+    return { ok: false, reason: 'G7: when 是兜底文案，说明任务类型未被识别', effective }
+  }
+  return { ok: true, effective }
+}
+
+export function summarizeCalls(calls) {
+  const steps = []
+  for (const call of calls || []) {
+    if (!call || !call.ok) continue
+    if (stepPriority(call) === 0) continue
+    const label = stepLabel(call)
+    if (!label) continue
+    if (isNoiseStep(label)) continue
+    if (steps[steps.length - 1] === label) continue
+    steps.push(label)
+    if (steps.length >= 8) break
+  }
+  return steps
+}
+
+/**
+ * What the turn actually produced, independent of how many steps it needed.
+ * A second run that only re-reads and re-runs the tests has the same fingerprint
+ * as the first run that scaffolded everything — that is the real "same task".
+ */
+export function outcomeFingerprint(calls) {
+  const list = calls || []
+  const artifactOf = (call) => {
+    const raw = firstString(call && (call.hint || call.argsHint || call.args)) || ''
+    const parts = raw.split(/[\\/]+/).filter(Boolean)
+    return (parts.length >= 2 ? parts.slice(-2).join('/') : parts[0] || '').toLowerCase()
+  }
+  const isCode = (target) => /\.(js|mjs|cjs|ts|tsx|jsx|py|go|rs|java|cs|rb|php)$/.test(target)
+  const writes = list.filter((call) => call && call.ok && classify(call).kind === 'write').map(artifactOf)
+  const reads = list.filter((call) => call && call.ok && classify(call).kind === 'read').map(artifactOf)
+  const testCalls = list.filter((call) => call && isTestCall(call))
+  const tests = testCalls.map((call) => classify(call).target)
+  // A run that failed and then went green still ends green; the failure itself is
+  // captured as a reverse example, not as a reason to refuse the merge.
+  const green = testCalls.length > 0 && testCalls[testCalls.length - 1].ok === true
+  const artifacts = (writes.length ? writes : reads).filter(isCode)
+  return {
+    targets: [...new Set(artifacts)].sort(),
+    tests: [...new Set(tests)].sort(),
+    green,
+    verificationOnly: writes.length === 0,
+  }
+}
+
+/** Same project + same produced artifact + green tests => the same task, whatever the steps. */
+export function fingerprintsMatch(left, right) {
+  const a = left && left.fingerprint
+  const b = right && right.fingerprint
+  if (!a || !b || !a.green || !b.green) return false
+  const have = new Set(a.targets || [])
+  const want = new Set(b.targets || [])
+  if (!have.size || !want.size) return false
+  for (const target of have) if (want.has(target)) return true
+  return false
+}
+
+function errorCode(call) {
+  const text = String((call && (call.errorCode || call.error)) || '')
+  const known = text.match(/\b(EPERM|ENOENT|EACCES|ETIMEDOUT|EEXIST|EISDIR|TypeError|RangeError|SyntaxError|AssertionError)\b/)
+  if (known) return known[1]
+  const exit = text.match(/exit code (\d+)/i)
+  if (exit) return `exit ${exit[1]}`
+  return '错误'
+}
+
+/** The first line of the failure is what a second run actually needs to avoid. */
+function errorDetail(call) {
+  const text = String((call && (call.errorCode || call.error)) || '').replace(/\s+/g, ' ').trim()
+  if (!text) return ''
+  const head = text.split(/(?<=\b(?:Error|EPERM|ENOENT|EACCES|EEXIST|EISDIR)\b)/)[0]
+  return clip(head || text, 80)
+}
+
+export function findRecoveries(calls) {
+  const list = calls || []
+  const recoveries = []
+  const seen = new Set()
+  for (let i = 0; i < list.length; i++) {
+    const failed = list[i]
+    if (!failed || failed.ok) continue
+    const failedLabel = stepLabel(failed)
+    for (let j = i + 1; j < list.length; j++) {
+      const ok = list[j]
+      if (!ok || !ok.ok) continue
+      const failedKind = classify(failed).kind
+      const okKind = classify(ok).kind
+      const sameKind = failedKind === okKind
+      // Compare the *raw* basename: normalization collapses `a.js` and `b.js`
+      // to the same `<name>.js`, which would fake a recovery between two
+      // unrelated files.
+      const rawBase = (call) => {
+        const raw = firstString(call && (call.hint || call.argsHint || call.args))
+        const segment = String(raw).split(/[\\/]+/).filter(Boolean).pop() || ''
+        return segment.replace(/\.[^.]+$/, '').toLowerCase()
+      }
+      const failedBase = rawBase(failed)
+      const okBase = rawBase(ok)
+      // A recovery must be *related* to the failure, otherwise any later success
+      // of the same tool kind would masquerade as one:
+      //   - same kind + same raw basename (normal retry / file moved),
+      //   - same command head for two runs (node --test -> node test/x.mjs).
+      const sameHead =
+        failedKind === 'run' &&
+        okKind === 'run' &&
+        classify(failed).target.split(/\s+/)[0] === classify(ok).target.split(/\s+/)[0]
+      const related = (sameKind && Boolean(failedBase) && failedBase === okBase) || sameHead
+      if (!related) continue
+      const line = `${failedLabel} 失败(${errorDetail(failed) || errorCode(failed)})，改用 ${stepLabel(ok)} 成功`
+      if (!seen.has(line)) {
+        seen.add(line)
+        recoveries.push(line)
+      }
+      break
+    }
+    if (recoveries.length >= 3) break
+  }
+  return recoveries
+}
+
+export function inferTaskType(calls, cwd) {
+  const haystack = (calls || [])
+    .map((call) => `${firstString(call && (call.hint || call.argsHint || call.args))} ${call && call.name ? call.name : ''}`)
+    .join(' ')
+    .toLowerCase()
+  const dir = String(cwd || '').toLowerCase()
+  if (/\.(tsx|jsx|vue|svelte)\b/.test(haystack)) return 'web/frontend'
+  if (/\.(ts)\b/.test(haystack)) return 'web/frontend'
+  if (/\.py\b|pyproject\.toml|requirements\.txt/.test(haystack)) return 'python/module'
+  if (/\.go\b|go\.mod/.test(haystack)) return 'go/module'
+  if (/\.rs\b|cargo\.toml/.test(haystack)) return 'rust/module'
+  if (/package\.json|\.m?js\b|node/.test(haystack) || /node/.test(dir)) return 'node-project/feature'
+  return 'workspace/general'
+}
+
+export function shouldCapture(trace, counts, config) {
+  const cfg = { ...DEFAULT_CONFIG, ...(config || {}) }
+  const calls = (trace && trace.calls) || []
+  const successes = calls.filter((call) => call && call.ok)
+  if (successes.length < 2) return { ok: false, reason: 'G1: 成功工具调用 < 2' }
+
+  const names = calls.map((call) => String((call && call.name) || ''))
+  const query = String((trace && trace.query) || '').trim()
+  if (names.some((name) => name.startsWith('experience_')) || query.startsWith('/memory')) {
+    return { ok: false, reason: 'G2: 本 turn 是经验管理操作，不回灌' }
+  }
+
+  const writes = successes.filter((call) => classify(call).kind === 'write')
+  const recoveries = findRecoveries(calls)
+  // A verification-only turn (re-read the code, run the tests, all green) is valid
+  // independent evidence: it re-proves the recipe without a write operation.
+  const tests = successes.filter((call) => isTestCall(call))
+  const testFailures = calls.filter((call) => call && !call.ok && isTestCall(call))
+  const verifiedGreen = tests.length > 0 && testFailures.length === 0
+  if (!writes.length && !recoveries.length && !verifiedGreen) {
+    return { ok: false, reason: 'G3: 无成功写操作、无失败后成功，且不是全绿验证轨迹' }
+  }
+
+  if ((counts && counts.todayAdded) >= cfg.dailyLimit) {
+    return { ok: false, reason: `G5: 今日自动捕获已达上限 ${cfg.dailyLimit}` }
+  }
+  if ((counts && counts.autoTotal) >= cfg.libraryLimit) {
+    return { ok: false, reason: `G5: 自动经验库已达上限 ${cfg.libraryLimit}` }
+  }
+  return { ok: true, writes, recoveries, verificationOnly: !writes.length && !recoveries.length }
+}
+
+function verbsOf(taskType) {
+  if (taskType === 'node-project/feature') return '新增函数/模块并配用例'
+  if (taskType === 'python/module') return '新增 Python 模块并配测试'
+  if (taskType === 'web/frontend') return '改前端组件'
+  if (taskType === 'go/module') return '新增 Go 包'
+  if (taskType === 'rust/module') return '新增 Rust 模块'
+  return '完成一项可复用的改动'
+}
+
+export function workspaceName(cwd) {
+  const segments = String(cwd || '').split(/[\\/]+/).filter(Boolean)
+  return segments[segments.length - 1] || ''
+}
+
+const GENERIC_DIRS = new Set([
+  'users', 'home', 'desktop', 'documents', 'downloads', 'src', 'test', 'tests',
+  'lib', 'node_modules', 'bin', 'tmp', 'temp', 'app', 'apps', 'workspace', 'workspaces',
+])
+
+/**
+ * Project directories mentioned in the raw task text.
+ * "D:\\w\\acme-app\\src\\pad.js" -> ["acme-app"]; only the deepest non-generic segment is
+ * kept, so a user name or a workspace root can never make two projects look alike.
+ */
+export function mentionedDirs(text, limit = 6) {
+  const found = new Set()
+  for (const match of String(text || '').matchAll(/(?:[A-Za-z]:)?(?:[\\/][A-Za-z0-9_.-]+)+/g)) {
+    // "node-project/feature" is a task type, not a directory.
+    if (/^[a-z][a-z-]*\/[a-z][a-z-]*$/.test(match[0])) continue
+    const parts = match[0].split(/[\\/]+/).filter(Boolean).filter((part) => !/^[A-Za-z]:$/.test(part))
+    // A lone "/feature" is the tail of "task-type/feature", not a path.
+    if (!/^[A-Za-z]:/.test(match[0]) && parts.length < 2) continue
+    if (/^[A-Za-z0-9_.-]+\.[A-Za-z0-9]+$/.test(parts[parts.length - 1] || '')) parts.pop()
+    const dirs = parts.map((part) => part.toLowerCase()).filter((part) => part.length >= 2 && !GENERIC_DIRS.has(part))
+    if (!dirs.length) continue
+    found.add(dirs[dirs.length - 1])
+  }
+  return [...found].slice(0, limit)
+}
+
+/** Idempotent: redacts a record written by an older build that had no redaction. */
+export function scrubRecord(record) {
+  if (!record || typeof record !== 'object') return false
+  let changed = false
+  const fix = (value) => {
+    if (typeof value !== 'string') return value
+    const next = redact(value)
+    if (next !== value) changed = true
+    return next
+  }
+  for (const key of ['title', 'when', 'evidence']) {
+    if (typeof record[key] === 'string') record[key] = fix(record[key])
+  }
+  for (const key of ['steps', 'reverse_examples', 'pitfalls', 'keywords']) {
+    if (Array.isArray(record[key])) record[key] = record[key].map(fix)
+  }
+  return changed
+}
+
+/** Project slugs recorded before `scope` existed, e.g. keywords "acme-app", "acme-app/**". */
+export function scopeOf(record) {
+  if (!record) return []
+  if (Array.isArray(record.scope) && record.scope.length) return record.scope.map((item) => String(item).toLowerCase())
+  const out = []
+  for (const word of record.keywords || []) {
+    const text = String(word)
+    if (/^[a-z][a-z-]*\/[a-z][a-z-]*$/.test(text)) continue // taskType, not a directory
+    const head = text.split(/[\\/*]/)[0].toLowerCase()
+    if (/^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/.test(head)) out.push(head)
+  }
+  return [...new Set(out)]
+}
+
+/** Two records describe different targets when both name a project dir and the names disagree. */
+export function scopeConflicts(existing, draft) {
+  const left = scopeOf(existing)
+  const right = scopeOf(draft)
+  if (!left.length || !right.length) return false
+  return !left.some((item) => right.includes(item))
+}
+
+/** Raw basename of a written artifact, extension stripped ("src/pad.js" -> "pad"). */
+export function artifactName(call) {
+  const raw = firstString(call && (call.hint || call.argsHint || call.args)) || ''
+  const parts = raw.split(/[\\/]+/).filter(Boolean)
+  const base = (parts[parts.length - 1] || '').replace(/\.[^.]+$/, '')
+  return base.replace(/[^A-Za-z0-9_.-]/g, '').trim()
+}
+
+export function buildCandidate(trace, info, config) {
+  const cfg = { ...DEFAULT_CONFIG, ...(config || {}) }
+  const calls = ((trace && trace.calls) || []).slice(0, cfg.maxCalls)
+  const taskType = inferTaskType(calls, info && info.cwd)
+  const steps = summarizeCalls(calls)
+  const recoveries = findRecoveries(calls)
+  const writes = calls.filter((call) => call && call.ok && classify(call).kind === 'write')
+  const runs = calls.filter((call) => call && call.ok && classify(call).kind === 'run')
+
+  const primary = writes.length ? classify(writes[0]).target : runs.length ? classify(runs[0]).target : ''
+  const verb = writes.length ? '写' : '跑通'
+  // Prefer a concrete artifact name (raw basename, before path normalization):
+  // "<path>/<name>.js" cannot name what was produced, "slugify.js" can.
+  const named = writes
+    .map((call) => artifactName(call))
+    .find((name) => /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(name) && /[A-Za-z0-9]{2,}/.test(name))
+  const title = clip(named ? `新增 ${named}` : primary ? `${verb} ${primary}` : verbsOf(taskType), 110)
+  const place = workspaceName(info && info.cwd)
+  const when = clip(place ? `在 ${place} 里 ${verbsOf(taskType)}` : `当需要${verbsOf(taskType)}时`, 160)
+  const keywords = [...new Set([taskType, ...steps.map((step) => step.split(' ')[1] || '').filter(Boolean)])]
+    .filter(Boolean)
+    .slice(0, 12)
+    .map((word) => clip(word, 40))
+
+  const record = {
+    status: 'candidate',
+    // Scope detection needs the raw paths; every rendered field below is normalized.
+    scope: mentionedDirs(
+      [
+        ...(calls || []).map((call) => firstString(call && (call.hint || call.argsHint || call.args))),
+        trace && trace.query,
+      ].join(' '),
+    ),
+    fingerprint: outcomeFingerprint(calls),
+    title,
+    taskType,
+    when,
+    keywords,
+    steps,
+    reverse_examples: recoveries,
+    evidence: `${(info && info.sessionId) || '?'}:turn-${(trace && trace.turn) || '?'} · calls=${calls.length} errors=${calls.filter((call) => call && !call.ok).length}`,
+    source: { auto: true, agentId: (info && info.agentId) || 'unknown', at: new Date().toISOString(), origin: 'l1' },
+    verify: null,
+    confidence: 0.25,
+    uses: 0,
+    lastUsedAt: null,
+    occurrences: 1,
+  }
+
+  if (JSON.stringify(record).length > cfg.maxRecordChars) {
+    record.truncated = true
+    while (record.steps.length > 1 && JSON.stringify(record).length > cfg.maxRecordChars) record.steps.pop()
+    while (record.reverse_examples.length > 1 && JSON.stringify(record).length > cfg.maxRecordChars) {
+      record.reverse_examples.pop()
+    }
+  }
+  return record
+}
+
+export function mergeInto(existing, draft) {
+  existing.occurrences = (existing.occurrences || 1) + 1
+  existing.lastSeenAt = new Date().toISOString()
+  // Older records had no fingerprint; adopt this run's so the next occurrence matches.
+  if (!existing.fingerprint && draft && draft.fingerprint) existing.fingerprint = draft.fingerprint
+  const canonical = existing.reverse_examples || existing.pitfalls || []
+  const seen = new Set(canonical)
+  const added = []
+  for (const item of draft.reverse_examples || []) {
+    if (!seen.has(item)) {
+      seen.add(item)
+      added.push(item)
+    }
+  }
+  existing.reverse_examples = [...canonical, ...added].slice(0, 10)
+  if (existing.pitfalls) existing.pitfalls = existing.reverse_examples
+
+  const stepSeen = new Set(existing.steps || [])
+  const newSteps = []
+  for (const step of draft.steps || []) {
+    if (!stepSeen.has(step) && newSteps.length < 4) {
+      stepSeen.add(step)
+      newSteps.push(step)
+    }
+  }
+  if (newSteps.length) existing.steps = [...(existing.steps || []), ...newSteps].slice(0, 10)
+
+  if (draft.evidence && existing.evidence && !existing.evidence.includes(draft.evidence)) {
+    existing.evidence = clip(`${existing.evidence}; ${draft.evidence}`, 240)
+  }
+  return { added, occurrences: existing.occurrences, newSteps }
+}
+
+export function reviewTargets(experiences) {
+  return (experiences || []).filter((item) => item && (item.status === 'candidate' || item.status === 'auto-verified'))
+}
+
+/**
+ * G8: a recipe that was rejected as rule-conflicting must not be re-adopted.
+ * A new turn that reproduces the same fingerprint would otherwise create a fresh
+ * candidate and wait for the same human to reject it again.
+ */
+export function gateSuperseded(draft, experiences) {
+  const hit = (experiences || []).find(
+    (item) => item && item.status === 'superseded' && fingerprintsMatch(item, draft),
+  )
+  if (!hit) return { ok: true }
+  const rule = (hit.supersede && (hit.supersede.rule || hit.supersede.reason)) || '规则冲突'
+  return { ok: false, hit, reason: `G8: 与已否决经验 ${hit.id} 指纹相同（${rule}）→ 不再收录` }
+}
+
+export function renderReview(experiences) {
+  const candidates = reviewTargets(experiences)
+  const rejected = (experiences || []).filter((item) => item && item.status === 'superseded')
+  if (!candidates.length) {
+    return rejected.length
+      ? `没有待确认的候选经验。\n已否决（规则冲突）${rejected.length} 条，不再收录、也不会召回。`
+      : '没有待确认的候选经验。'
+  }
+  const auto = candidates.filter((item) => item.source && item.source.auto).length
+  const lines = [`候选 ${candidates.length} 条（自动捕获 ${auto} / 手动 ${candidates.length - auto}）｜批准后即可跨会话召回`, '']
+  candidates.forEach((item, index) => {
+    const flags = [item.source && item.source.auto ? 'auto' : 'manual']
+    lines.push(`#${index + 1} ${item.id} [${flags.join('/')}] ${item.title}`)
+    lines.push(`   触发条件: ${item.when || '-'}`)
+    const steps = item.steps || []
+    const shown = steps.slice(0, 3).map((step, i) => `${i + 1}) ${step}`).join('  ')
+    const more = steps.length > 3 ? `  …+${steps.length - 3}` : ''
+    lines.push(`   核心步骤: ${shown || '-'}${more}`)
+    const pitfalls = item.reverse_examples || item.pitfalls || []
+    lines.push(`   避坑点: ${pitfalls.length ? pitfalls.join('；') : '（无）'}`)
+    lines.push(`   id=${item.id}  occurrences=${item.occurrences || 1}`)
+    lines.push('')
+  })
+  if (rejected.length) {
+    lines.push(`已否决（规则冲突）${rejected.length} 条，不再召回，仅用于防止重复收录：`)
+    for (const item of rejected.slice(0, 5)) {
+      const why = (item.supersede && (item.supersede.rule || item.supersede.reason)) || '规则冲突'
+      lines.push(`  ${item.id} ${item.title} · ${why}`)
+    }
+    lines.push('')
+  }
+  lines.push('批量: /memory review --approve-all')
+  lines.push('单条: /memory review approve 1   |   /memory review reject 1')
+  return lines.join('\n')
+}
+/**
+ * Coerce a user-typed config value to the type of its default.
+ * "/memory config set autoPromote true" must store boolean true, not the string "true".
+ */
+export function coerceConfigValue(key, raw, defaults = DEFAULT_CONFIG) {
+  if (!(key in defaults)) throw new Error('未知配置项 ' + key)
+  const fallback = defaults[key]
+  const text = String(raw).trim()
+  if (typeof fallback === 'boolean') {
+    if (/^(true|1|yes|on)$/i.test(text)) return true
+    if (/^(false|0|no|off)$/i.test(text)) return false
+    throw new Error(key + ' 是布尔值，接受 true/false')
+  }
+  if (typeof fallback === 'number') {
+    const num = Number(text)
+    if (!Number.isFinite(num)) throw new Error(key + " 是数字，收到 " + text)
+    return num
+  }
+  return text
+}