add-coder 0.3.33 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/jobs/consolidation.ts

@@ -0,0 +1,226 @@
+/*
+ * Consolidation 异步任务（Spec §10，Plan §9.2 Post-Handoff 行）
+ *
+ * 职责（全部 fail-open 隔离：单步失败不影响他步，错误入报告）：
+ *  1. drainEvidenceQueue —— 采证队列落库
+ *  2. 重复检测 —— 同 repositoryRef+contentHash 多行 → 报告（不自动合并，人审）
+ *  3. 冲突队列 —— CANDIDATE/PENDING 与 ACTIVE 高相似 → 报告（不自动激活，Plan §3）
+ *  4. 指标候选 —— AddMetricSnapshot 连续异常 streak 命中 → 创建 CANDIDATE（幂等）
+ *  5. Handoff Digest —— HANDOFF Evidence → HANDOFF_DIGEST Candidate（幂等，绝不直接 ACTIVE）
+ *  6. 刷新 L1 快照 —— 供 session-start Hook 注入
+ */
+import type {
+  AddMemoryEvidenceRow,
+  AddMemoryEvidenceLinkRow,
+  AddMemoryRow,
+  AddMetricSnapshotRow,
+  TableDelegate,
+} from "../../db-types.js"
+import { detectConflicts, type Conflict } from "../domain/conflicts.js"
+import { contentHash } from "../domain/dedup.js"
+import { detectAnomalyStreak, type MetricPoint } from "../domain/metric-candidate.js"
+import { buildHandoffDigest } from "../domain/handoff-digest.js"
+import { drainEvidenceQueue, type DrainResult } from "./evidence-collector.js"
+import { refreshL1Snapshot, type SnapshotDeps, type SnapshotResult } from "./snapshot.js"
+
+export interface ConsolidationDeps extends SnapshotDeps {
+  memoryDb: TableDelegate<AddMemoryRow>
+  evidenceDb: Pick<TableDelegate<AddMemoryEvidenceRow>, "upsert" | "findMany">
+  linkDb: Pick<TableDelegate<AddMemoryEvidenceLinkRow>, "findFirst" | "create">
+  metricDb: TableDelegate<AddMetricSnapshotRow>
+}
+
+export interface ConsolidationReport {
+  drain: DrainResult
+  duplicates: { contentHash: string; ids: string[] }[]
+  conflictQueue: { candidateId: string; topic: string; conflicts: Conflict[] }[]
+  metricCandidatesCreated: string[]
+  handoffDigestsCreated: string[]
+  snapshot: SnapshotResult | null
+  errors: string[]
+}
+
+export async function runConsolidation(deps: ConsolidationDeps): Promise<ConsolidationReport> {
+  const report: ConsolidationReport = {
+    drain: { processed: 0, skipped: 0, errors: [], newOffset: 0 },
+    duplicates: [],
+    conflictQueue: [],
+    metricCandidatesCreated: [],
+    handoffDigestsCreated: [],
+    snapshot: null,
+    errors: [],
+  }
+
+  // 1. 采证队列落库
+  try {
+    report.drain = await drainEvidenceQueue(deps)
+  } catch (e) {
+    report.errors.push(`drain: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 2/3. 重复检测 + 冲突队列（共享一次全量读取）
+  try {
+    const rows = await deps.memoryDb.findMany({
+      where: { repositoryRef: deps.repositoryRef, status: { notIn: ["REJECTED", "ARCHIVED"] } },
+      take: 500,
+    })
+    const byHash = new Map<string, string[]>()
+    for (const r of rows) {
+      const arr = byHash.get(r.contentHash) ?? []
+      arr.push(r.id)
+      byHash.set(r.contentHash, arr)
+    }
+    for (const [hash, ids] of byHash) {
+      if (ids.length > 1) report.duplicates.push({ contentHash: hash, ids })
+    }
+    const actives = rows.filter((r) => r.status === "ACTIVE")
+    for (const c of rows.filter((r) => r.status === "CANDIDATE" || r.status === "PENDING")) {
+      const conflicts = detectConflicts(c, actives)
+      if (conflicts.length > 0) report.conflictQueue.push({ candidateId: c.id, topic: c.topic, conflicts })
+    }
+  } catch (e) {
+    report.errors.push(`dedup/conflicts: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 4. 指标候选（Plan §10：连续异常 streak 才生成，内容必须是可验证结论）
+  try {
+    const metrics = await deps.metricDb.findMany({
+      where: { repositoryRef: deps.repositoryRef },
+      orderBy: { measuredAt: "asc" },
+      take: 500,
+    })
+    const byType = new Map<string, MetricPoint[]>()
+    for (const m of metrics) {
+      const arr = byType.get(m.metricType) ?? []
+      arr.push({
+        repositoryRef: m.repositoryRef,
+        metricType: m.metricType,
+        value: m.value,
+        baseline: m.baseline,
+        planKeyword: m.planKeyword,
+        measuredAt: m.measuredAt,
+        sourceRef: m.sourceRef,
+      })
+      byType.set(m.metricType, arr)
+    }
+    for (const points of byType.values()) {
+      const proposal = detectAnomalyStreak(points)
+      if (!proposal) continue
+      const hash = contentHash(proposal.content)
+      const existing = await deps.memoryDb.findFirst({
+        where: {
+          repositoryRef: deps.repositoryRef,
+          contentHash: hash,
+          scopeType: "REPOSITORY",
+          scopeValue: deps.repositoryRef,
+          status: { notIn: ["REJECTED", "ARCHIVED"] },
+        },
+      })
+      if (existing) continue // 幂等：已提过同结论
+      const created = await deps.memoryDb.create({
+        data: {
+          kind: "PATTERN",
+          topic: proposal.topic,
+          content: proposal.content,
+          scopeType: "REPOSITORY",
+          scopeValue: deps.repositoryRef,
+          repositoryRef: deps.repositoryRef,
+          contentHash: hash,
+          createdBy: "memory-jobs:consolidation",
+        },
+      })
+      for (const ref of proposal.evidenceSourceRefs) {
+        const ev = await deps.evidenceDb.upsert({
+          where: {
+            repositoryRef_sourceType_sourceRef_contentHash: {
+              repositoryRef: deps.repositoryRef, sourceType: "DPS_GATE", sourceRef: ref, contentHash: contentHash(ref),
+            },
+          },
+          create: {
+            repositoryRef: deps.repositoryRef, sourceType: "DPS_GATE", sourceRef: ref,
+            excerpt: ref.slice(0, 500), contentHash: contentHash(ref),
+          },
+          update: {},
+        })
+        const linked = await deps.linkDb.findFirst({ where: { memoryId: created.id, evidenceId: ev.id } })
+        if (!linked) await deps.linkDb.create({ data: { memoryId: created.id, evidenceId: ev.id } })
+      }
+      report.metricCandidatesCreated.push(created.id)
+    }
+  } catch (e) {
+    report.errors.push(`metric-candidates: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 5. Handoff Digest（Plan §3.1 轮 2）：HANDOFF Evidence → HANDOFF_DIGEST Candidate
+  //    幂等去重靠 dedupKey 派生的 contentHash；绝不直接置 ACTIVE（只产 CANDIDATE）
+  try {
+    const handoffEvidence = await deps.evidenceDb.findMany({
+      where: { repositoryRef: deps.repositoryRef, sourceType: "HANDOFF" },
+      orderBy: { occurredAt: "asc" },
+      take: 200,
+    })
+    for (const ev of handoffEvidence) {
+      const proposal = buildHandoffDigest(
+        { handoffRef: ev.sourceRef, excerpt: ev.excerpt, planKeyword: ev.planKeyword },
+        { repositoryRef: deps.repositoryRef },
+      )
+      const existing = await deps.memoryDb.findFirst({
+        where: {
+          repositoryRef: deps.repositoryRef,
+          contentHash: proposal.contentHash,
+          scopeType: proposal.scopeType,
+          scopeValue: proposal.scopeValue,
+          status: { notIn: ["REJECTED", "ARCHIVED"] },
+        },
+      })
+      if (existing) {
+        // 幂等：同一交接 evidence 的摘要已入队过 → 仅补齐证据关联
+        const linkedAlready = await deps.linkDb.findFirst({
+          where: { memoryId: existing.id, evidenceId: ev.id },
+        })
+        if (!linkedAlready) {
+          await deps.linkDb.create({
+            data: { memoryId: existing.id, evidenceId: ev.id },
+          })
+        }
+        continue
+      }
+      const created = await deps.memoryDb.create({
+        data: {
+          kind: proposal.kind,
+          status: "CANDIDATE", // 绝不直接 ACTIVE
+          topic: proposal.topic,
+          content: proposal.content,
+          scopeType: proposal.scopeType,
+          scopeValue: proposal.scopeValue,
+          repositoryRef: deps.repositoryRef,
+          contentHash: proposal.contentHash,
+          importance: 0.6,
+          confidence: 0.5,
+          createdBy: "memory-jobs:consolidation",
+          metadata: { ...proposal.metadata, dedupKey: proposal.dedupKey, evidenceId: ev.id },
+        },
+      })
+      const linked = await deps.linkDb.findFirst({
+        where: { memoryId: created.id, evidenceId: ev.id },
+      })
+      if (!linked) {
+        await deps.linkDb.create({
+          data: { memoryId: created.id, evidenceId: ev.id },
+        })
+      }
+      report.handoffDigestsCreated.push(created.id)
+    }
+  } catch (e) {
+    report.errors.push(`handoff-digest: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 6. 刷新 L1 快照
+  try {
+    report.snapshot = await refreshL1Snapshot(deps)
+  } catch (e) {
+    report.errors.push(`snapshot: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  return report
+}

package/templates/core/scripts/mcp-server/shared/memory/jobs/evidence-collector.ts

@@ -0,0 +1,153 @@
+/*
+ * Evidence 自动采集（Spec §10/§11，Plan §9.2 PostToolUse 行）
+ *
+ * 两段式：
+ *  ① Hook 侧（同步 ≤200ms，无 DB）：白名单判定 + 事件入队（evidence-queue.jsonl append-only）
+ *     —— classifyEvidenceSource / buildEvidenceEvent 为纯函数，供 post-tool-router 直接引用
+ *  ② Job 侧（异步，可重试）：drainEvidenceQueue 消费队列 → upsert Evidence（幂等键
+ *     repositoryRef+sourceType+sourceRef+contentHash，与 add.prisma @@unique 一一对应）
+ *     消费进度落 evidence-queue.offset（字节偏移），重放幂等：同偏移不重复处理，
+ *     同事件重复消费由 upsert 幂等吸收。
+ */
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, statSync, writeFileSync, renameSync } from "node:fs"
+import { dirname, join } from "node:path"
+import type { AddMemoryEvidenceRow, TableDelegate } from "../../db-types.js"
+import { EVIDENCE_OFFSET_FILE, EVIDENCE_QUEUE_FILE, MEMORY_DIR_NAME } from "../switches.js"
+
+// ── ① Hook 侧纯函数（无 IO 之外的依赖，无 DB） ──
+
+export type EvidenceSourceType = "PLAN" | "SPEC" | "HANDOFF" | "DEV_OPERATION"
+
+export interface EvidenceEvent {
+  dedupKey: string
+  sourceType: EvidenceSourceType
+  sourceRef: string
+  excerpt: string
+  occurredAt: string
+}
+
+/** 白名单分类：命中返回 sourceType，未命中返回 null（spec §10：按白名单采集） */
+export function classifyEvidenceSource(filePath: string): EvidenceSourceType | null {
+  const p = filePath.replace(/\\/g, "/")
+  if (/(^|\/)plans\/[^/]*-plan-v\d+\.md$/.test(p)) return "PLAN"
+  if (/(^|\/)plans\/[^/]*-add-route-v\d+\.md$/.test(p)) return "PLAN"
+  if (/(^|\/)specs\/.+\.md$/.test(p)) return "SPEC"
+  if (/handoff[^/]*\.md$/i.test(p)) return "HANDOFF"
+  if (/(^|\/)reviews\/.+\.md$/.test(p)) return "DEV_OPERATION"
+  return null
+}
+
+/** 构造采证事件（幂等 key = sha256(sourceType|sourceRef|excerpt)）：同文件同内容重复写入被吸收 */
+export function buildEvidenceEvent(filePath: string, excerpt: string, occurredAt = new Date()): EvidenceEvent {
+  const sourceType = classifyEvidenceSource(filePath)
+  if (!sourceType) throw new Error(`非白名单路径: ${filePath}`)
+  const sourceRef = filePath
+  const dedupKey = createHash("sha256")
+    .update(`${sourceType}|${sourceRef}|${excerpt}`, "utf8")
+    .digest("hex")
+    .slice(0, 32)
+  return { dedupKey, sourceType, sourceRef, excerpt: excerpt.slice(0, 500), occurredAt: occurredAt.toISOString() }
+}
+
+// ── ② Job 侧消费（异步、可重试） ──
+
+export interface DrainDeps {
+  projectDir: string
+  magicDir: string
+  repositoryRef: string
+  evidenceDb: Pick<TableDelegate<AddMemoryEvidenceRow>, "upsert">
+}
+
+export interface DrainResult {
+  processed: number
+  skipped: number
+  errors: string[]
+  newOffset: number
+}
+
+/** 读 offset 标记（缺失/损坏 → 0，从头重放；upsert 幂等保证安全） */
+export function readOffset(projectDir: string, magicDir: string): number {
+  try {
+    const f = join(projectDir, magicDir, MEMORY_DIR_NAME, EVIDENCE_OFFSET_FILE)
+    if (!existsSync(f)) return 0
+    const n = Number(readFileSync(f, "utf-8").trim())
+    return Number.isFinite(n) && n >= 0 ? n : 0
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * 消费 evidence 队列：从上次偏移继续，逐行 upsert Evidence。
+ * fail-open 粒度到行：坏行跳过并计入 errors，不阻塞后续。
+ */
+export async function drainEvidenceQueue(deps: DrainDeps): Promise<DrainResult> {
+  const queueFile = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, EVIDENCE_QUEUE_FILE)
+  const result: DrainResult = { processed: 0, skipped: 0, errors: [], newOffset: readOffset(deps.projectDir, deps.magicDir) }
+  if (!existsSync(queueFile)) return result
+
+  const size = (() => { try { return statSync(queueFile).size } catch { return 0 } })()
+  if (size <= result.newOffset) return result // 无增量
+
+  // 按偏移读取增量字节（避免大文件全量加载）
+  const fd = openSync(queueFile, "r")
+  let chunk: string
+  try {
+    const buf = Buffer.alloc(size - result.newOffset)
+    readSync(fd, buf, 0, buf.length, result.newOffset)
+    chunk = buf.toString("utf-8")
+  } finally {
+    closeSync(fd)
+  }
+
+  let cursor = result.newOffset
+  for (const line of chunk.split("\n")) {
+    const lineBytes = Buffer.byteLength(line, "utf-8") + 1 // + '\n'
+    cursor += lineBytes
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let ev: EvidenceEvent
+    try {
+      ev = JSON.parse(trimmed) as EvidenceEvent
+    } catch {
+      result.skipped++
+      result.errors.push(`坏行@${cursor - lineBytes}: JSON 解析失败`)
+      continue
+    }
+    try {
+      await deps.evidenceDb.upsert({
+        where: {
+          repositoryRef_sourceType_sourceRef_contentHash: {
+            repositoryRef: deps.repositoryRef,
+            sourceType: ev.sourceType,
+            sourceRef: ev.sourceRef,
+            contentHash: ev.dedupKey,
+          },
+        },
+        create: {
+          repositoryRef: deps.repositoryRef,
+          sourceType: ev.sourceType,
+          sourceRef: ev.sourceRef,
+          excerpt: ev.excerpt,
+          contentHash: ev.dedupKey,
+          occurredAt: new Date(ev.occurredAt),
+        } as Partial<AddMemoryEvidenceRow>,
+        update: {},
+      })
+      result.processed++
+    } catch (e) {
+      result.skipped++
+      result.errors.push(`落库失败 ${ev.sourceRef}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+
+  // 原子推进 offset（先写后改：offset 落后只会重放，upsert 幂等吸收）
+  result.newOffset = cursor
+  const offsetFile = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, EVIDENCE_OFFSET_FILE)
+  mkdirSync(dirname(offsetFile), { recursive: true })
+  const tmp = `${offsetFile}.tmp-${process.pid}`
+  writeFileSync(tmp, String(cursor), "utf-8")
+  renameSync(tmp, offsetFile)
+  return result
+}

package/templates/core/scripts/mcp-server/shared/memory/jobs/snapshot.ts

@@ -0,0 +1,114 @@
+/*
+ * L1/L2 召回快照生成（Spec §10：session-start 仅注入 repository 级 L1 小上下文）
+ *
+ * 设计约束（Plan §9.3）：同步 Hook ≤200ms 且无 DB 依赖 → Hook 只读本模块预计算的快照文件；
+ * 快照由本 job 异步刷新（consolidation / 手动 CLI / Gate 后触发）。
+ * 原子写：tmp + rename，Hook 读侧永不遇到半文件。
+ */
+import { mkdirSync, renameSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { recallPipeline, type MemoryRowLike } from "../retrieval/pipeline.js"
+import type { RecallAuditStore } from "../retrieval/recall-writer.js"
+import type { LexicalSearchAdapter, RecalledMemory } from "../retrieval/types.js"
+import { L1_SNAPSHOT_FILE, L2_SNAPSHOT_FILE, MEMORY_DIR_NAME, memoryMaxTokens } from "../switches.js"
+
+export interface SnapshotDeps {
+  repositoryRef: string
+  projectDir: string
+  magicDir: string
+  lexical: LexicalSearchAdapter[]
+  fetchByIds(ids: string[]): Promise<MemoryRowLike[]>
+  fetchEvidenceSourceRefs(memoryIds: string[]): Promise<Map<string, string[]>>
+  audit: RecallAuditStore
+  now?: Date
+}
+
+export interface SnapshotResult {
+  path: string
+  itemCount: number
+  injectedTokens: number
+  recallId: string | null
+}
+
+/** 渲染带来源边界标签的注入文本（Plan §9.3：Recall 注入采用明确的数据边界与来源标签） */
+export function renderSnapshotMarkdown(level: "L1" | "L2", items: RecalledMemory[], generatedAt: Date): string {
+  const lines = [
+    `[Memory ${level} · 来源: AddMemory 治理库 · 生成于 ${generatedAt.toISOString()}]`,
+    `<agent-memory source="add-memory" trust="governed">`,
+  ]
+  for (const it of items) {
+    lines.push(
+      `- [${it.kind}] ${it.topic}（置信 ${it.confidence.toFixed(2)}）`,
+      `  ${it.content.length > 120 ? it.content.slice(0, 120) + "…" : it.content}`,
+    )
+    if (it.sourceRefs.length > 0) lines.push(`  来源: ${it.sourceRefs.join(", ")}`)
+  }
+  lines.push(`</agent-memory>`)
+  return lines.join("\n") + "\n"
+}
+
+/** 刷新 L1 快照：repository 级核心约束/决策/陷阱/约定 */
+export async function refreshL1Snapshot(deps: SnapshotDeps): Promise<SnapshotResult> {
+  const maxTokens = memoryMaxTokens()
+  const result = await recallPipeline(
+    {
+      query: "核心约束 关键决策 常见陷阱 项目约定",
+      stage: "session-start",
+      repositoryRef: deps.repositoryRef,
+      scopeCtx: { repository: deps.repositoryRef },
+      maxTokens,
+      kinds: ["CONSTRAINT", "DECISION", "PITFALL", "CONVENTION"],
+      limit: 20,
+      consumerRef: "memory-jobs:refresh-l1",
+    },
+    {
+      lexical: deps.lexical,
+      fetchByIds: deps.fetchByIds,
+      fetchEvidenceSourceRefs: deps.fetchEvidenceSourceRefs,
+      audit: deps.audit,
+      degradedMode: "fts-only(snapshot-job)",
+      now: deps.now,
+    },
+  )
+  const path = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, L1_SNAPSHOT_FILE)
+  atomicWrite(path, renderSnapshotMarkdown("L1", result.items, deps.now ?? new Date()))
+  return { path, itemCount: result.items.length, injectedTokens: result.injectedTokens, recallId: result.recallId }
+}
+
+/** 刷新 L2 快照：按给定 query/stage/scope（供 prompt-router 提示与人工查阅） */
+export async function refreshL2Snapshot(
+  deps: SnapshotDeps,
+  query: string,
+  stage: string,
+  maxTokens = 1200,
+): Promise<SnapshotResult> {
+  const result = await recallPipeline(
+    {
+      query,
+      stage,
+      repositoryRef: deps.repositoryRef,
+      scopeCtx: { repository: deps.repositoryRef },
+      maxTokens,
+      limit: 20,
+      consumerRef: "memory-jobs:refresh-l2",
+    },
+    {
+      lexical: deps.lexical,
+      fetchByIds: deps.fetchByIds,
+      fetchEvidenceSourceRefs: deps.fetchEvidenceSourceRefs,
+      audit: deps.audit,
+      degradedMode: "fts-only(snapshot-job)",
+      now: deps.now,
+    },
+  )
+  const path = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, L2_SNAPSHOT_FILE)
+  atomicWrite(path, renderSnapshotMarkdown("L2", result.items, deps.now ?? new Date()))
+  return { path, itemCount: result.items.length, injectedTokens: result.injectedTokens, recallId: result.recallId }
+}
+
+function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.tmp-${process.pid}`
+  writeFileSync(tmp, content, "utf-8")
+  renameSync(tmp, path)
+}

package/templates/core/scripts/mcp-server/shared/memory/metrics/gate-recall.ts

@@ -0,0 +1,134 @@
+/*
+ * 工具侧阶段确定性召回（Plan §3.1 方案 B1 / Spec §2 §DeterministicRecall）
+ *
+ * 与 stage-words.ts 的分工：
+ *  - stage-words.ts：纯函数，Hook 侧识别阶段词（无 DB）
+ *  - 本模块：有 DB 的工具侧落点，复用既有 recallPipeline（不另起一套召回实现）
+ *
+ * 三条硬约束：
+ *  1. 阶段白名单命中才召回——未命中直接返回，不访问 DB、不写审计；
+ *  2. ADD_MEMORY_RECALL_MODE=off 时整体停用（与 recall_memory 工具同语义）；
+ *  3. fail-open：管线异常只降级为 skippedReason="pipeline-error"，绝不抛出，
+ *     不阻塞调用它的门禁/交接流程。
+ */
+import { recallPipeline, type RecallPipelineDeps, type RecallPipelineResult } from "../retrieval/pipeline.js"
+import { buildContext, estimateTokens } from "../retrieval/context-builder.js"
+import { recallMode, type RecallMode } from "../switches.js"
+import type { ScopeContext } from "../domain/scope.js"
+import { isRecallStage, RECALL_STAGES, type RecallStage } from "./stage-words.js"
+
+/** 默认 token 预算（Spec §10：ADD_MEMORY_MAX_TOKENS 默认 600，此处与 Recall 通道对齐） */
+export const DEFAULT_STAGE_RECALL_MAX_TOKENS = 600
+
+export type StageRecallSkipReason = "stage-not-whitelisted" | "recall-off" | "pipeline-error"
+
+export interface StageRecallInput {
+  /** 调用方声明的阶段；不在白名单内即不召回 */
+  stage: string
+  query: string
+  repositoryRef: string
+  scopeCtx?: Partial<ScopeContext>
+  planKeyword?: string
+  specRef?: string
+  maxTokens?: number
+  limit?: number
+  consumerRef?: string
+  diagnostic?: boolean
+}
+
+export interface StageRecallResult {
+  injected: boolean
+  stage: RecallStage | null
+  context?: string
+  auditId?: string | null
+  degradedMode?: string | null
+  itemCount: number
+  usedTokens: number
+  latencyMs: number
+  skippedReason?: StageRecallSkipReason
+  error?: string
+}
+
+/**
+ * 按阶段执行确定性召回。deps 由调用方（MCP 工具）注入，便于测试与复用。
+ */
+export async function recallForStage(
+  input: StageRecallInput,
+  deps: RecallPipelineDeps,
+  options: { mode?: RecallMode } = {},
+): Promise<StageRecallResult> {
+  const startedAt = Date.now()
+  const empty = (): Omit<StageRecallResult, "skippedReason" | "stage"> => ({
+    injected: false,
+    itemCount: 0,
+    usedTokens: 0,
+    latencyMs: Math.max(0, Date.now() - startedAt),
+  })
+
+  if (!isRecallStage(input.stage)) {
+    return { ...empty(), stage: null, skippedReason: "stage-not-whitelisted" }
+  }
+  const mode = options.mode ?? recallMode()
+  if (mode === "off") {
+    return { ...empty(), stage: input.stage, skippedReason: "recall-off" }
+  }
+
+  const stage = input.stage
+  const maxTokens = input.maxTokens ?? DEFAULT_STAGE_RECALL_MAX_TOKENS
+  const scopeCtx: ScopeContext = {
+    repository: input.repositoryRef,
+    planKeyword: input.planKeyword,
+    specRef: input.specRef,
+    ...input.scopeCtx,
+  }
+
+  try {
+    const result: RecallPipelineResult = await recallPipeline(
+      {
+        query: input.query,
+        stage,
+        repositoryRef: input.repositoryRef,
+        scopeCtx,
+        maxTokens,
+        limit: input.limit ?? 20,
+        consumerRef: input.consumerRef ?? `mcp:stage-recall:${stage}`,
+        diagnostic: input.diagnostic ?? false,
+      },
+      deps,
+    )
+
+    const budget = buildContext(
+      result.items.map((item) => ({
+        memoryId: item.memoryId,
+        kind: item.kind,
+        finalScore: item.scoreBreakdown?.final ?? item.confidence,
+        tokens: estimateTokens(item.content),
+        content: item.content,
+        sourceRefs: item.sourceRefs,
+      })),
+      maxTokens,
+    )
+
+    return {
+      injected: budget.selected.length > 0,
+      stage,
+      context: budget.selected.map((i) => i.content).join("\n\n"),
+      auditId: result.recallId,
+      degradedMode: result.degradedMode,
+      itemCount: budget.selected.length,
+      usedTokens: budget.usedTokens,
+      latencyMs: result.latencyMs,
+    }
+  } catch (error) {
+    // fail-open：召回失败不阻塞门禁/交接；错误信息进审计与返回值
+    return {
+      ...empty(),
+      stage,
+      skippedReason: "pipeline-error",
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/** 供工具/文档展示的白名单（单一事实源来自 stage-words） */
+export { RECALL_STAGES }