add-coder 0.3.34 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/retrieval/context-builder.ts

@@ -0,0 +1,89 @@
+/*
+ * Token-budget 上下文构建（Plan §7.4）
+ *
+ * - 先保留强约束和高优先级决策，再选择 failure/pitfall/convention
+ * - 同源/语义近重复项合并为一条带多个 sourceRef 的条目
+ * - 超预算时返回被排除项及原因，不静默截断关键约束
+ */
+import { charBigrams, jaccardSimilarity } from "../domain/dedup.js"
+
+/** 粗略 token 估算：CJK 按 1 token/字，其余按 4 字符/token */
+export function estimateTokens(text: string): number {
+  let cjk = 0
+  let other = 0
+  for (const ch of text) {
+    // CJK 统一表意文字 + 平片假名 + 常用标点区
+    if (/[぀-ヿ㐀-䶿一-鿿豈-﫿＀-￯]/.test(ch)) cjk++
+    else other++
+  }
+  return cjk + Math.ceil(other / 4)
+}
+
+export interface BudgetItem {
+  memoryId: string
+  kind: string
+  finalScore: number
+  tokens: number
+  content: string
+  sourceRefs: string[]
+}
+
+export interface BudgetResult {
+  selected: BudgetItem[]
+  excluded: { memoryId: string; reason: string }[]
+  usedTokens: number
+}
+
+const KIND_PRIORITY: Record<string, number> = {
+  CONSTRAINT: 0,
+  DECISION: 1,
+  FAILURE: 2,
+  PITFALL: 3,
+  CONVENTION: 4,
+  LESSON: 5,
+  PATTERN: 5,
+  FACT: 6,
+  HANDOFF_DIGEST: 7,
+  HYPOTHESIS: 8,
+}
+
+/** 近重复合并阈值（字符二元组 Jaccard） */
+const DUP_THRESHOLD = 0.75
+
+export function buildContext(items: BudgetItem[], maxTokens: number): BudgetResult {
+  // 排序：kind 优先级 → 分数
+  const sorted = [...items].sort((a, b) => {
+    const ka = KIND_PRIORITY[a.kind] ?? 9
+    const kb = KIND_PRIORITY[b.kind] ?? 9
+    if (ka !== kb) return ka - kb
+    return b.finalScore - a.finalScore
+  })
+
+  const selected: BudgetItem[] = []
+  const excluded: { memoryId: string; reason: string }[] = []
+  const selectedVecs: Set<string>[] = []
+  let used = 0
+
+  for (const item of sorted) {
+    // 近重复合并：合并到已选项（追加 sourceRef），不重复占预算
+    const vec = charBigrams(item.content)
+    const dupIdx = selectedVecs.findIndex((v) => jaccardSimilarity(v, vec) >= DUP_THRESHOLD)
+    if (dupIdx >= 0) {
+      selected[dupIdx].sourceRefs = [...new Set([...selected[dupIdx].sourceRefs, ...item.sourceRefs])]
+      excluded.push({ memoryId: item.memoryId, reason: `近重复合并进 ${selected[dupIdx].memoryId}` })
+      continue
+    }
+    if (used + item.tokens > maxTokens) {
+      // 强制约束不可静默截断：CONSTRAINT 超额时显式标记
+      excluded.push({
+        memoryId: item.memoryId,
+        reason: item.kind === "CONSTRAINT" ? "超预算（强制约束，调用方必须知悉）" : "超预算",
+      })
+      continue
+    }
+    selected.push(item)
+    selectedVecs.push(vec)
+    used += item.tokens
+  }
+  return { selected, excluded, usedTokens: used }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/pg.ts

@@ -0,0 +1,139 @@
+/*
+ * PostgreSQL FTS 适配器（Plan §8.2，§17-3 定案：pg_trgm 支持 CJK）
+ *
+ * 双通道候选（RRF 融合用）：
+ *  - 通道 A：pg_trgm similarity（`%` 操作符 + similarity() 排序）
+ *  - 通道 B：websearch_to_tsquery('simple') 全文匹配（拉丁词强、CJK 弱，作为补充信号）
+ * 短查询（<3 字符）pg_trgm 命中率低 → ILIKE 兜底（Plan §17-3 衍生意图一致）
+ *
+ * 降级：扩展/索引缺失 → health() 报 degraded，调用方切换受限结构化查询。
+ */
+import type { LexicalSearchAdapter, RankedId, RecallFilter, RawQuerier, ComponentHealth } from "../types.js"
+import { extractQueryTerms } from "../query-terms.js"
+
+/**
+ * 通道 C：词项重叠计分（拉丁词 + CJK 二元组的 ILIKE 命中比例）
+ * 弥补 trigram 子串语义对释义查询的召回不足（如 "新端口怎么申请" → 命中 "新增端口"）
+ */
+function channelC(query: string, filter: RecallFilter, limit: number): { sql: string; params: unknown[] } | null {
+  const terms = extractQueryTerms(query)
+  if (terms.length === 0) return null
+  // 参数布局：$1 repo, $2 statuses, $3 now, $4 kinds, $5..$(4+n) terms, $(5+n) limit
+  const expr = terms
+    .map((_, i) => `CASE WHEN topic ILIKE '%' || $${5 + i} || '%' OR content ILIKE '%' || $${5 + i} || '%' THEN 1 ELSE 0 END`)
+    .join(" + ")
+  const sql = `
+SELECT * FROM (
+  SELECT id, (${expr})::float / ${terms.length} AS score
+  FROM "AddMemory"
+  WHERE "repositoryRef" = $1
+    AND "status"::text = ANY($2)
+    AND ("validUntil" IS NULL OR "validUntil" > $3)
+    AND ($4::text[] IS NULL OR "kind"::text = ANY($4))
+) t WHERE score > 0
+ORDER BY score DESC
+LIMIT $${5 + terms.length}
+`
+  return {
+    sql,
+    params: [filter.repositoryRef, [...filter.statuses], filter.now,
+      filter.kinds && filter.kinds.length > 0 ? [...filter.kinds] : null,
+      ...terms, limit],
+  }
+}
+
+const CHANNEL_A_SQL = `
+SELECT id,
+       GREATEST(
+         similarity(topic || ' ' || content, $1),
+         CASE WHEN topic ILIKE '%' || $1 || '%' OR content ILIKE '%' || $1 || '%' THEN 0.01 ELSE 0 END
+       ) AS score
+FROM "AddMemory"
+WHERE "repositoryRef" = $2
+  AND "status"::text = ANY($3)
+  AND ("validUntil" IS NULL OR "validUntil" > $4)
+  AND ($5::text[] IS NULL OR "kind"::text = ANY($5))
+  AND (topic % $1 OR content % $1
+       OR topic ILIKE '%' || $1 || '%' OR content ILIKE '%' || $1 || '%')
+ORDER BY score DESC
+LIMIT $6
+`
+
+const CHANNEL_B_SQL = `
+SELECT id, ts_rank(to_tsvector('simple', topic || ' ' || content), websearch_to_tsquery('simple', $1)) AS score
+FROM "AddMemory"
+WHERE "repositoryRef" = $2
+  AND "status"::text = ANY($3)
+  AND ("validUntil" IS NULL OR "validUntil" > $4)
+  AND ($5::text[] IS NULL OR "kind"::text = ANY($5))
+  AND to_tsvector('simple', topic || ' ' || content) @@ websearch_to_tsquery('simple', $1)
+ORDER BY score DESC
+LIMIT $6
+`
+
+function params(query: string, filter: RecallFilter, limit: number): unknown[] {
+  return [
+    query,
+    filter.repositoryRef,
+    [...filter.statuses],
+    filter.now,
+    filter.kinds && filter.kinds.length > 0 ? [...filter.kinds] : null,
+    limit,
+  ]
+}
+
+async function runChannel(
+  q: RawQuerier,
+  sql: string,
+  query: string,
+  filter: RecallFilter,
+  limit: number,
+): Promise<RankedId[]> {
+  const rows = await q.query<{ id: string; score: number | string }>(sql, params(query, filter, limit))
+  return rows.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: Number(r.score) }))
+}
+
+export function createPgFtsAdapter(q: RawQuerier): LexicalSearchAdapter & {
+  searchChannels(query: string, filter: RecallFilter, limit: number): Promise<RankedId[][]>
+} {
+  return {
+    id: "pg-trgm",
+    async search(query, filter, limit) {
+      const channels = await this.searchChannels(query, filter, limit)
+      return channels[0] ?? []
+    },
+    async searchChannels(query, filter, limit) {
+      const a = await runChannel(q, CHANNEL_A_SQL, query, filter, limit)
+      let b: RankedId[] = []
+      try {
+        b = await runChannel(q, CHANNEL_B_SQL, query, filter, limit)
+      } catch {
+        // tsquery 通道失败（如查询含特殊字符）不阻断主通道
+      }
+      let c: RankedId[] = []
+      const cc = channelC(query, filter, limit)
+      if (cc) {
+        const rows = await q.query<{ id: string; score: number | string }>(cc.sql, cc.params)
+        c = rows.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: Number(r.score) }))
+      }
+      return [a, b, c]
+    },
+    async health(): Promise<ComponentHealth> {
+      try {
+        const ext = await q.query<{ count: number | string }>(
+          "SELECT COUNT(*)::int AS count FROM pg_extension WHERE extname = 'pg_trgm'", [])
+        if (Number(ext[0]?.count ?? 0) < 1) {
+          return { component: "pg-fts", status: "degraded", detail: "pg_trgm 扩展缺失" }
+        }
+        const idx = await q.query<{ count: number | string }>(
+          "SELECT COUNT(*)::int AS count FROM pg_indexes WHERE tablename = 'AddMemory' AND indexname LIKE '%trgm%'", [])
+        if (Number(idx[0]?.count ?? 0) < 2) {
+          return { component: "pg-fts", status: "degraded", detail: "trgm GIN 索引缺失，需 reindex" }
+        }
+        return { component: "pg-fts", status: "ok" }
+      } catch (e) {
+        return { component: "pg-fts", status: "unavailable", detail: e instanceof Error ? e.message : String(e) }
+      }
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql

@@ -0,0 +1,29 @@
+-- Agent Memory FTS 原生层（SQLite 后端）
+-- Plan §8.3 + §17-3 定案：FTS5 trigram 分词器（CJK 友好，≥3 字符 n-gram 匹配；
+-- 短于 3 字符的查询由 adapter 层回退 LIKE —— 见 retrieval/fts/sqlite.ts）
+--
+-- 说明：AddMemory 主键为 cuid 字符串，无法使用 FTS5 external-content 模式
+-- （其要求 INTEGER rowid），故采用独立 FTS 表 + 触发器同步。
+-- 幂等：全部 IF NOT EXISTS，可重复应用。
+
+CREATE VIRTUAL TABLE IF NOT EXISTS add_memory_fts USING fts5(
+  memory_id UNINDEXED,
+  topic,
+  content,
+  tokenize = 'trigram'
+);
+
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_ai AFTER INSERT ON "AddMemory" BEGIN
+  INSERT INTO add_memory_fts(memory_id, topic, content)
+  VALUES (new.id, new.topic, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_au AFTER UPDATE ON "AddMemory" BEGIN
+  DELETE FROM add_memory_fts WHERE memory_id = old.id;
+  INSERT INTO add_memory_fts(memory_id, topic, content)
+  VALUES (new.id, new.topic, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_ad AFTER DELETE ON "AddMemory" BEGIN
+  DELETE FROM add_memory_fts WHERE memory_id = old.id;
+END;

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite.ts

@@ -0,0 +1,106 @@
+/*
+ * SQLite FTS5 适配器（Plan §8.3，trigram 分词器，schema 见同目录 sqlite-fts5.sql）
+ *
+ * trigram 限制：查询词 <3 字符无法产生匹配 → 由 LIKE 通道兜底。
+ * 双通道候选：A = FTS5 MATCH + bm25 排序；B = 词项重叠 LIKE 计分（覆盖短查询与释义查询）。
+ */
+import type { LexicalSearchAdapter, RankedId, RecallFilter, RawQuerier, ComponentHealth } from "../types.js"
+import { extractQueryTerms } from "../query-terms.js"
+
+/** 通道 B：词项重叠计分（拉丁词 + CJK 二元组的 LIKE 命中比例），覆盖短查询与释义查询 */
+function channelB(query: string, filter: RecallFilter, limit: number): { sql: string; params: unknown[] } | null {
+  const terms = extractQueryTerms(query)
+  if (terms.length === 0) return null
+  const expr = terms
+    .map(() => `CASE WHEN topic LIKE '%' || ? || '%' OR content LIKE '%' || ? || '%' THEN 1 ELSE 0 END`)
+    .join(" + ")
+  const statuses = filter.statuses.map((s) => `'${s}'`).join(",")
+  const kinds = filter.kinds && filter.kinds.length > 0
+    ? `kind IN (${filter.kinds.map((k) => `'${k}'`).join(",")})`
+    : "1=1"
+  const sql = `
+SELECT * FROM (
+  SELECT id, (${expr}) * 1.0 / ${terms.length} AS score
+  FROM "AddMemory"
+  WHERE repositoryRef = ?
+    AND status IN (${statuses})
+    AND (validUntil IS NULL OR validUntil > ?)
+    AND (${kinds})
+) WHERE score > 0
+ORDER BY score DESC
+LIMIT ?
+`
+  const termParams = terms.flatMap((t) => [t, t])
+  return { sql, params: [...termParams, filter.repositoryRef, filter.now.toISOString(), limit] }
+}
+
+/** 抽取可参与 trigram MATCH 的片段（连续 CJK/字母数字，≥3 字符），逐段加引号 */
+export function buildTrigramQuery(raw: string): string | null {
+  const segments = raw.match(/[㐀-鿿぀-ヿA-Za-z0-9_]+/g) ?? []
+  const usable = segments.filter((s) => s.length >= 3).map((s) => `"${s}"`)
+  return usable.length > 0 ? usable.join(" OR ") : null
+}
+
+const CHANNEL_A_SQL = `
+SELECT m.id AS id, bm25(add_memory_fts) AS score
+FROM add_memory_fts f
+JOIN "AddMemory" m ON m.id = f.memory_id
+WHERE add_memory_fts MATCH ?
+  AND m.repositoryRef = ?
+  AND m.status IN (STATUS_PLACEHOLDER)
+  AND (m.validUntil IS NULL OR m.validUntil > ?)
+  AND (KIND_PLACEHOLDER)
+ORDER BY score
+LIMIT ?
+`
+
+function buildSql(template: string, filter: RecallFilter): string {
+  const statuses = filter.statuses.map((s) => `'${s}'`).join(",")
+  const kinds = filter.kinds && filter.kinds.length > 0
+    ? `m.kind IN (${filter.kinds.map((k) => `'${k}'`).join(",")})`
+    : "1=1"
+  return template
+    .replace("STATUS_PLACEHOLDER", statuses)
+    .replace("KIND_PLACEHOLDER", kinds)
+}
+
+export function createSqliteFtsAdapter(q: RawQuerier): LexicalSearchAdapter & {
+  searchChannels(query: string, filter: RecallFilter, limit: number): Promise<RankedId[][]>
+} {
+  return {
+    id: "sqlite-fts5",
+    async search(query, filter, limit) {
+      const channels = await this.searchChannels(query, filter, limit)
+      return channels[0] ?? []
+    },
+    async searchChannels(query, filter, limit) {
+      let a: RankedId[] = []
+      const matchQ = buildTrigramQuery(query)
+      if (matchQ) {
+        const rows = await q.query<{ id: string; score: number }>(
+          buildSql(CHANNEL_A_SQL, filter), [matchQ, filter.repositoryRef, filter.now.toISOString(), limit],
+        )
+        a = rows.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: -Number(r.score) }))
+      }
+      let b: RankedId[] = []
+      const cb = channelB(query, filter, limit)
+      if (cb) {
+        const rowsB = await q.query<{ id: string; score: number }>(cb.sql, cb.params)
+        b = rowsB.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: Number(r.score) }))
+      }
+      return [a, b]
+    },
+    async health(): Promise<ComponentHealth> {
+      try {
+        const rows = await q.query<{ name: string }>(
+          "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'add_memory_fts'", [])
+        if (rows.length < 1) {
+          return { component: "sqlite-fts", status: "unavailable", detail: "add_memory_fts 虚表缺失，需执行 sqlite-fts5.sql" }
+        }
+        return { component: "sqlite-fts", status: "ok" }
+      } catch (e) {
+        return { component: "sqlite-fts", status: "unavailable", detail: e instanceof Error ? e.message : String(e) }
+      }
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fusion.ts

@@ -0,0 +1,43 @@
+/*
+ * RRF 融合（Plan §7.3）：RRF(d) = Σ 1 / (k + rank_i(d))
+ * 避免强行比较 PG、SQLite 和不同 FTS 实现的原始分值。
+ * k 可配置化（写入 Recall.rankingVersion 的配置快照）。
+ */
+import type { RankedId } from "./types.js"
+
+export const DEFAULT_RRF_K = 10
+
+/**
+ * 加权 RRF：score(d) = Σ_i w_i / (k + rank_i(d))
+ * 通道权重让「高精度通道」主导、低精度通道只做补充（Plan 轮 3 融合迭代）。
+ * weights 缺省为 1（退化为经典 RRF，保持向后兼容）。
+ */
+export function rrfFuse(
+  lists: RankedId[][],
+  k: number = DEFAULT_RRF_K,
+  weights?: readonly number[],
+): Map<string, number> {
+  const scores = new Map<string, number>()
+  lists.forEach((list, i) => {
+    const w = weights?.[i] ?? 1
+    if (w <= 0) return
+    for (const item of list) {
+      const prev = scores.get(item.memoryId) ?? 0
+      scores.set(item.memoryId, prev + w / (k + item.rank))
+    }
+  })
+  return scores
+}
+
+/** 便捷入口：融合后按分数降序返回有序 id 列表 */
+export function rrfRank(
+  lists: RankedId[][],
+  k: number = DEFAULT_RRF_K,
+  weights?: readonly number[],
+): RankedId[] {
+  const scores = rrfFuse(lists, k, weights)
+  return [...scores.entries()]
+    .map(([memoryId, score]) => ({ memoryId, rank: 0, score }))
+    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+    .map((r, i) => ({ ...r, rank: i + 1 }))
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/pipeline.ts

@@ -0,0 +1,285 @@
+/*
+ * Hybrid Recall 编排管线（Plan §7.1 十步流水线）
+ *
+ *  1. Repository/tenant 边界校验（调用方前置，此处防御性复核）
+ *  2. Lifecycle 过滤（默认仅 ACTIVE；诊断模式放行 STALE）
+ *  3. Scope 过滤与强约束匹配
+ *  4. FTS/BM25 候选生成（双后端 adapter）
+ *  5. Vector 候选生成（能力可用时；首版 none）
+ *  6. Reciprocal Rank Fusion
+ *  7. 治理重排
+ *  8. 冲突、重复和多样性处理
+ *  9. Token-budget 摘要与裁剪
+ * 10. 写入 AddMemoryRecall
+ */
+import { DEFAULT_RECALL_STATUSES, DIAGNOSTIC_RECALL_STATUSES, type MemoryStatus } from "../domain/state-machine.js"
+import { scopeApplies, type ScopeContext } from "../domain/scope.js"
+import { rrfFuse, DEFAULT_RRF_K } from "./fusion.js"
+import {
+  rerankOne,
+  DEFAULT_WEIGHTS,
+  RANKING_VERSION,
+  RANKING_VERSION_HYBRID,
+  RRF_SCORE_SCALE,
+  type RerankWeights,
+} from "./reranker.js"
+import { buildContext, estimateTokens } from "./context-builder.js"
+import { writeRecallAudit, type RecallAuditStore } from "./recall-writer.js"
+import type { LexicalSearchAdapter, RankedId, RecallFilter, RecalledMemory } from "./types.js"
+
+/** 向量通道默认权重与候选预算（Plan 轮 3 融合迭代：低精度通道不与词法等权） */
+export const DEFAULT_VECTOR_WEIGHT = 0.3
+export const DEFAULT_VECTOR_TOP_K = 5
+
+/** 管线需要的记忆行字段子集（与 AddMemoryRow 对齐） */
+export interface MemoryRowLike {
+  id: string
+  kind: string
+  status: string
+  topic: string
+  content: string
+  summary: string | null
+  scopeType: string
+  scopeValue: string
+  repositoryRef: string
+  importance: number
+  confidence: number
+  validUntil: Date | null
+  supersedes?: { id: string }[]
+}
+
+export interface RecallPipelineInput {
+  query: string
+  stage: string
+  repositoryRef: string
+  scopeCtx: ScopeContext
+  maxTokens: number
+  kinds?: string[]
+  limit?: number
+  consumerRef?: string
+  /** 诊断模式：放行 STALE（带警告标记），默认 false */
+  diagnostic?: boolean
+}
+
+export interface RecallPipelineDeps {
+  lexical: LexicalSearchAdapter[]
+  /** Vector 候选（可选；首版不传即 FTS-only） */
+  vector?: { search(query: string, filter: RecallFilter, limit: number): Promise<RankedId[]> } | null
+  /** 向量通道权重（RRF 加权；默认 DEFAULT_VECTOR_WEIGHT —— 低精度通道不与词法等权） */
+  vectorWeight?: number
+  /** 向量候选预算（默认 DEFAULT_VECTOR_TOP_K —— 不按总 limit 灌入，避免稀释词法信号） */
+  vectorTopK?: number
+  /** 补位模式阈值：仅当词法候选数 < 该值时启用向量通道（缺省=始终补充） */
+  vectorFallbackThreshold?: number
+  fetchByIds(ids: string[]): Promise<MemoryRowLike[]>
+  fetchEvidenceSourceRefs(memoryIds: string[]): Promise<Map<string, string[]>>
+  audit?: RecallAuditStore | null
+  weights?: RerankWeights
+  rrfK?: number
+  rankingVersion?: string
+  degradedMode?: string
+  now?: Date
+}
+
+export interface RecallPipelineResult {
+  items: RecalledMemory[]
+  recallId: string | null
+  degradedMode: string | null
+  /** 实际参与融合的候选通道（Spec §7 RecallResultMeta） */
+  fusedChannels: ("lexical" | "vector")[]
+  excluded: { memoryId: string; reason: string }[]
+  candidateCount: number
+  injectedTokens: number
+  latencyMs: number
+  rankingVersion: string
+}
+
+export async function recallPipeline(
+  input: RecallPipelineInput,
+  deps: RecallPipelineDeps,
+): Promise<RecallPipelineResult> {
+  const start = Date.now()
+  const now = deps.now ?? new Date()
+  const statuses: readonly MemoryStatus[] = input.diagnostic ? DIAGNOSTIC_RECALL_STATUSES : DEFAULT_RECALL_STATUSES
+  const limit = input.limit ?? 20
+
+  // Step 1（防御性复核）：repository 边界
+  if (input.scopeCtx.repository !== input.repositoryRef) {
+    throw new Error(`ERR_REPOSITORY_MISMATCH: scopeCtx.repository=${input.scopeCtx.repository} 与 repositoryRef 不一致`)
+  }
+
+  const filter: RecallFilter = {
+    repositoryRef: input.repositoryRef,
+    statuses,
+    scopeCtx: input.scopeCtx,
+    kinds: input.kinds,
+    now,
+  }
+
+  // Step 4/5：候选生成（FTS 多通道 + 可选 Vector）
+  const channelLists: RankedId[][] = []
+  let lexicalChannels = 0
+  for (const adapter of deps.lexical) {
+    const multi = adapter as LexicalSearchAdapter & {
+      searchChannels?(q: string, f: RecallFilter, l: number): Promise<RankedId[][]>
+    }
+    if (typeof multi.searchChannels === "function") {
+      const channels = await multi.searchChannels(input.query, filter, limit)
+      channelLists.push(...channels)
+      lexicalChannels += channels.length
+    } else {
+      channelLists.push(await adapter.search(input.query, filter, limit))
+      lexicalChannels += 1
+    }
+  }
+  let vectorUsed = false
+  const channelWeights: number[] = channelLists.map(() => 1) // 词法通道权重恒为 1
+  if (deps.vector) {
+    const lexicalCandidates = new Set(channelLists.flat().map((c) => c.memoryId)).size
+    const fallbackOnly = deps.vectorFallbackThreshold != null
+    const shouldUseVector = !fallbackOnly || lexicalCandidates < (deps.vectorFallbackThreshold as number)
+    try {
+      if (shouldUseVector) {
+        const vectorCandidates = await deps.vector.search(
+          input.query,
+          filter,
+          Math.min(deps.vectorTopK ?? DEFAULT_VECTOR_TOP_K, limit),
+        )
+        channelLists.push(vectorCandidates)
+        channelWeights.push(deps.vectorWeight ?? DEFAULT_VECTOR_WEIGHT)
+        vectorUsed = true
+      }
+    } catch {
+      // Vector 故障不阻塞 FTS（Plan §8.4）
+    }
+  }
+  const fusedChannels: ("lexical" | "vector")[] = [
+    ...(lexicalChannels > 0 ? (["lexical"] as const) : []),
+    ...(vectorUsed ? (["vector"] as const) : []),
+  ]
+  // rankingVersion：向量通道真正参与融合才记 v2；否则保持 v1（可被调用方显式覆盖）
+  const effectiveRankingVersion =
+    deps.rankingVersion ?? (vectorUsed ? RANKING_VERSION_HYBRID : RANKING_VERSION)
+
+  // Step 6：RRF 融合
+  const fused = rrfFuse(channelLists, deps.rrfK ?? DEFAULT_RRF_K, channelWeights)
+  const candidateIds = [...fused.keys()]
+  if (candidateIds.length === 0) {
+    const empty: RecallPipelineResult = {
+      items: [], recallId: null, degradedMode: deps.degradedMode ?? null,
+      fusedChannels,
+      excluded: [], candidateCount: 0, injectedTokens: 0,
+      latencyMs: Date.now() - start, rankingVersion: effectiveRankingVersion,
+    }
+    if (deps.audit) {
+      empty.recallId = await writeRecallAudit(deps.audit, {
+        repositoryRef: input.repositoryRef, query: input.query, stage: input.stage,
+        consumerRef: input.consumerRef, scopeContext: input.scopeCtx,
+        candidateIds: [], items: [], excluded: [],
+        rankingVersion: empty.rankingVersion, tokenBudget: input.maxTokens,
+        injectedTokens: 0, latencyMs: empty.latencyMs, degradedMode: empty.degradedMode ?? undefined,
+      })
+    }
+    return empty
+  }
+
+  // Step 2/3：取行 + lifecycle/scope 防御性复核（SQL 已过滤，此处兜底语义一致性）
+  const rows = await deps.fetchByIds(candidateIds)
+  const rowById = new Map(rows.map((r) => [r.id, r]))
+  const eligible = rows.filter((r) => {
+    if (r.repositoryRef !== input.repositoryRef) return false
+    if (!statuses.includes(r.status as MemoryStatus)) return false
+    if (r.validUntil && r.validUntil <= now) return false
+    return scopeApplies(
+      { type: r.scopeType as Parameters<typeof scopeApplies>[0]["type"], value: r.scopeValue },
+      input.scopeCtx,
+    )
+  })
+  const scopeExcluded = candidateIds
+    .filter((id) => rowById.has(id) && !eligible.some((r) => r.id === id))
+    .map((id) => ({ memoryId: id, reason: "lifecycle/scope/有效期过滤" }))
+
+  // Step 7/8：治理重排
+  const reranked = eligible.map((r) => ({
+    row: r,
+    rr: rerankOne({
+      memoryId: r.id,
+      // 相关性主导：RRF 放大到与治理 boost 可比量级（见 RRF_SCORE_SCALE 注释）
+      rrfScore: (fused.get(r.id) ?? 0) * RRF_SCORE_SCALE,
+      kind: r.kind,
+      status: r.status as MemoryStatus,
+      importance: r.importance,
+      confidence: r.confidence,
+      scopeType: r.scopeType,
+      scopeValue: r.scopeValue,
+    }, input.scopeCtx, deps.weights ?? DEFAULT_WEIGHTS),
+  }))
+
+  // Step 9：token 预算
+  const budgetItems = reranked.map(({ row, rr }) => ({
+    memoryId: row.id,
+    kind: row.kind,
+    finalScore: rr.finalScore,
+    tokens: estimateTokens(row.summary ?? row.content),
+    content: row.content,
+    sourceRefs: [] as string[],
+    _why: rr.whySelected,
+    _breakdown: rr.scoreBreakdown,
+  }))
+  const budget = buildContext(budgetItems, input.maxTokens)
+
+  const evidenceRefs = await deps.fetchEvidenceSourceRefs(budget.selected.map((s) => s.memoryId))
+  const items: RecalledMemory[] = budget.selected.map((s) => {
+    const row = rowById.get(s.memoryId)!
+    const extra = budgetItems.find((b) => b.memoryId === s.memoryId)!
+    return {
+      memoryId: s.memoryId,
+      kind: row.kind,
+      topic: row.topic,
+      content: row.content,
+      scope: { type: row.scopeType, value: row.scopeValue },
+      confidence: row.confidence,
+      importance: row.importance,
+      sourceRefs: evidenceRefs.get(s.memoryId) ?? s.sourceRefs,
+      whySelected: extra._why,
+      scoreBreakdown: extra._breakdown,
+      supersedes: (row.supersedes ?? []).map((x) => x.id),
+    }
+  })
+
+  const excluded = [...scopeExcluded, ...budget.excluded]
+  const latencyMs = Date.now() - start
+  const injectedTokens = budget.usedTokens
+
+  // Step 10：审计落库
+  let recallId: string | null = null
+  if (deps.audit) {
+    recallId = await writeRecallAudit(deps.audit, {
+      repositoryRef: input.repositoryRef,
+      query: input.query,
+      stage: input.stage,
+      consumerRef: input.consumerRef,
+      scopeContext: input.scopeCtx,
+      candidateIds,
+      items,
+      excluded,
+      rankingVersion: effectiveRankingVersion,
+      tokenBudget: input.maxTokens,
+      injectedTokens,
+      latencyMs,
+      degradedMode: deps.degradedMode,
+    })
+  }
+
+  return {
+    items,
+    recallId,
+    degradedMode: deps.degradedMode ?? null,
+    fusedChannels,
+    excluded,
+    candidateCount: candidateIds.length,
+    injectedTokens,
+    latencyMs,
+    rankingVersion: effectiveRankingVersion,
+  }
+}