add-coder 0.3.33 → 0.3.35

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

@@ -0,0 +1,217 @@
+/*
+ * Gate → MetricSnapshot 幂等采证（Plan §3.1 方案 A1 / Spec §1 §GateMetric）
+ *
+ * 设计要点：
+ *  1. 与评分解耦：评分逻辑保持只读，采证在评分完成后单独提交（Review P0 #1 / Plan §2.1）；
+ *  2. 幂等键：sourceRef = `{gate}:{planKeyword}:{runId}`，配合表级唯一键
+ *     (repositoryRef, metricType, sourceRef) —— 同 runId 重放不产生重复快照；
+ *  3. fail-open：任何异常都不向上抛，返回 outcome="bypassed" + degradedReason，
+ *     由调用方保证评分照常返回（验收项「采证失败旁路」）；
+ *  4. 失败路径审计密度不低于成功路径（ADD-6）：buildGateCaptureDetail 对三种 outcome
+ *     返回同构字段集。
+ */
+import type { AddMetricSnapshotRow, TableDelegate } from "../../db-types.js"
+import { AddMetricSnapshotRowSchema, validatedDelegate } from "../../db-types.js"
+import { MemoryError } from "../domain/errors.js"
+import { createHash } from "node:crypto"
+
+export type GateKind = "check_dps" | "check_rahs"
+export type GateWriteOutcome = "written" | "skipped_duplicate" | "bypassed"
+
+/** 门禁指标类型字面量（Spec §10 契约登记表） */
+export const GATE_METRIC_TYPE = {
+  check_dps: "DPS_TOTAL",
+  check_rahs: "RAHS_TOTAL",
+  latency: "GATE_LATENCY_MS",
+} as const
+
+/** 采证耗时增量上限（ms）——验收项「工具响应耗时增量 ≤50ms」 */
+export const GATE_CAPTURE_TOLERANCE_MS = 50
+
+export interface GateMetricWriteInput {
+  gate: GateKind
+  planKeyword: string
+  runId: string
+  metricType?: string
+  score: number
+  repository: string
+  dimensionScores?: Record<string, number>
+  baseline?: number | null
+  unit?: string | null
+  specRef?: string | null
+  commitSha?: string | null
+}
+
+export interface GateMetricWriteResult {
+  outcome: GateWriteOutcome
+  sourceRef: string
+  metricId?: string
+  degradedReason?: string
+  elapsedMs: number
+}
+
+export interface GateWriterDeps {
+  /** 采证目标表；测试可注入内存实现 */
+  metricDb: Pick<TableDelegate<AddMetricSnapshotRow>, "findUnique" | "upsert">
+  /** 时钟注入（测试用），默认 Date.now */
+  now?: () => number
+}
+
+/**
+ * 幂等键构造。空值归一为 "-"，避免出现 `::` 与前缀碰撞。
+ */
+export function buildGateSourceRef(gate: GateKind, planKeyword: string, runId: string): string {
+  const norm = (v: string | undefined | null): string => {
+    const t = (v ?? "").trim()
+    return t.length > 0 ? t : "-"
+  }
+  return `${gate}:${norm(planKeyword)}:${norm(runId)}`
+}
+
+/**
+ * 由被评分产物的内容派生 runId。
+ *
+ * 语义：同一份文档重复跑同一门禁 → 同一幂等键 → 判定为重复采证（skipped_duplicate）；
+ * 文档内容变化 → 新幂等键 → 产生新的证据快照。这样「重放」不会因为时间戳不同而假性去重，
+ * 也不需要调用方额外传参（门禁工具入参契约保持不变）。
+ */
+export function deriveGateRunId(gate: GateKind, planKeyword: string, seed: string): string {
+  const digest = createHash("sha256")
+    .update(`${gate}|${planKeyword}|${seed}`)
+    .digest("hex")
+  return `auto-${digest.slice(0, 12)}`
+}
+
+/** 唯一键参数（与 prisma @@unique([repositoryRef, metricType, sourceRef]) 对应） */
+function uniqueWhere(repositoryRef: string, metricType: string, sourceRef: string) {
+  return { repositoryRef_metricType_sourceRef: { repositoryRef, metricType, sourceRef } }
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  const code = (error as { code?: string } | null)?.code
+  return code === "P2002"
+}
+
+/**
+ * 写入一次门禁指标快照。**不抛异常**：失败返回 bypassed，由调用方继续返回评分。
+ */
+export async function writeGateMetric(
+  input: GateMetricWriteInput,
+  deps: GateWriterDeps,
+): Promise<GateMetricWriteResult> {
+  const now = deps.now ?? Date.now
+  const startedAt = now()
+  const metricType = input.metricType ?? GATE_METRIC_TYPE[input.gate]
+  const sourceRef = buildGateSourceRef(input.gate, input.planKeyword, input.runId)
+  const elapsed = () => Math.max(0, now() - startedAt)
+
+  try {
+    if (!input.repository || input.repository.trim().length === 0) {
+      throw new MemoryError("ERR_REPOSITORY_MISMATCH", "repositoryRef 为空，拒绝采证")
+    }
+    if (!Number.isFinite(input.score)) {
+      throw new MemoryError("ERR_INVARIANT", "score 非有限数值，拒绝采证")
+    }
+
+    const existing = await deps.metricDb.findUnique({
+      where: uniqueWhere(input.repository, metricType, sourceRef),
+    })
+    if (existing) {
+      // 同 runId 重放：既有快照是证据，不覆写
+      return { outcome: "skipped_duplicate", metricId: existing.id, sourceRef, elapsedMs: elapsed() }
+    }
+
+    const created = await deps.metricDb.upsert({
+      where: uniqueWhere(input.repository, metricType, sourceRef),
+      create: {
+        repositoryRef: input.repository,
+        metricType,
+        value: input.score,
+        baseline: input.baseline ?? null,
+        delta: input.baseline == null ? null : input.score - input.baseline,
+        unit: input.unit ?? null,
+        planKeyword: input.planKeyword || null,
+        specRef: input.specRef ?? null,
+        commitSha: input.commitSha ?? null,
+        sourceRef,
+        metadata: {
+          gate: input.gate,
+          runId: input.runId,
+          dimensionScores: input.dimensionScores ?? null,
+          capture: "gate-writer",
+        },
+        measuredAt: new Date(now()),
+      },
+      // 幂等：并发下由唯一键裁定，update 不改写既有证据
+      update: {},
+    })
+    return { outcome: "written", metricId: created.id, sourceRef, elapsedMs: elapsed() }
+  } catch (error) {
+    if (isUniqueViolation(error)) {
+      return { outcome: "skipped_duplicate", sourceRef, elapsedMs: elapsed() }
+    }
+    // fail-open：采证失败绝不阻塞门禁返回评分
+    return {
+      outcome: "bypassed",
+      sourceRef,
+      degradedReason: error instanceof Error ? error.message : String(error),
+      elapsedMs: elapsed(),
+    }
+  }
+}
+
+/**
+ * 审计明细（ADD-6：成功/去重/旁路三态返回同构字段集，失败路径不得更稀疏）。
+ */
+export function buildGateCaptureDetail(
+  input: GateMetricWriteInput,
+  result: GateMetricWriteResult,
+): Record<string, unknown> {
+  return {
+    gate: input.gate,
+    planKeyword: input.planKeyword,
+    runId: input.runId,
+    metricType: input.metricType ?? GATE_METRIC_TYPE[input.gate],
+    sourceRef: result.sourceRef,
+    outcome: result.outcome,
+    metricId: result.metricId ?? null,
+    score: input.score,
+    dimensionCount: input.dimensionScores ? Object.keys(input.dimensionScores).length : 0,
+    baseline: input.baseline ?? null,
+    degradedReason: result.degradedReason ?? null,
+    elapsedMs: result.elapsedMs,
+    overTolerance: result.elapsedMs > GATE_CAPTURE_TOLERANCE_MS,
+  }
+}
+
+/** 单行摘要：供 MCP 工具在响应末尾追加（三态均返回非空文本） */
+export function formatGateCaptureSummary(detail: Record<string, unknown>): string {
+  const bits = [
+    `结果: ${String(detail.outcome)}`,
+    `幂等键: ${String(detail.sourceRef)}`,
+    `耗时: ${String(detail.elapsedMs)}ms`,
+  ]
+  if (typeof detail.metricId === "string" && detail.metricId.length > 0) {
+    bits.push(`metricId: ${detail.metricId}`)
+  }
+  if (typeof detail.degradedReason === "string" && detail.degradedReason.length > 0) {
+    bits.push(`旁路原因: ${detail.degradedReason}（评分不受影响）`)
+  }
+  if (detail.overTolerance === true) {
+    bits.push(`⚠️ 超出 ${GATE_CAPTURE_TOLERANCE_MS}ms 容差`)
+  }
+  return bits.join(" | ")
+}
+
+/**
+ * 便捷装配：把 MCP 工具侧的 prisma delegate 包装为通过行校验的采证依赖。
+ */
+export function createGateWriterDeps(rawMetricDelegate: unknown): GateWriterDeps {
+  return {
+    metricDb: validatedDelegate<AddMetricSnapshotRow>(
+      rawMetricDelegate,
+      AddMetricSnapshotRowSchema,
+      "AddMetricSnapshot",
+    ),
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/metrics/stage-words.ts

@@ -0,0 +1,69 @@
+/*
+ * 阶段词识别（Plan §9.1 / Spec §2 §DeterministicRecall）
+ *
+ * 本模块是**纯函数**：零运行时依赖、零 IO、零 DB。
+ * 存在意义：governance Hook（同步 spawn、≤200ms 预算、无 DB 访问权限）需要识别
+ * 「现在处于哪个 ADD 阶段」，以便产出确定性召回提示；而真正的召回落点在有 DB 的
+ * MCP 工具侧（gate-recall.ts）。两者共用同一份阶段白名单，避免 Hook 与工具侧漂移。
+ */
+
+export const RECALL_STAGES = ["plan-start", "spec-start", "dps", "rahs", "handoff"] as const
+export type RecallStage = (typeof RECALL_STAGES)[number]
+
+export function isRecallStage(value: string): value is RecallStage {
+  return (RECALL_STAGES as readonly string[]).includes(value)
+}
+
+export const STAGE_LABEL: Record<RecallStage, string> = {
+  "plan-start": "Plan 起草",
+  "spec-start": "Spec 起草",
+  dps: "DPS 门禁",
+  rahs: "RAHS 门禁",
+  handoff: "Handoff 交接",
+}
+
+/**
+ * 阶段词模式。按特异性从高到低排列——先命中者为准（handoff/rahs/dps 比 plan 更具体，
+ * 避免「交接 plan」被判成 plan-start）。
+ */
+const STAGE_PATTERNS: ReadonlyArray<{ stage: RecallStage; re: RegExp }> = [
+  { stage: "handoff", re: /handoff|交接(手册|文档|说明)?|交接给/i },
+  { stage: "rahs", re: /rahs|注意力漂移|执行健康度/i },
+  { stage: "dps", re: /dps|文档质量闸门|质量闸门|门禁(评分|检查)?/i },
+  { stage: "spec-start", re: /(生成|写|新建|起草|补)\s*(spec|规格|三元组)|specs?\s*三元组|WHEN-?THEN/i },
+  { stage: "plan-start", re: /(生成|写|新建|起草|补)\s*(plan|计划|方案)|plan\s*阶段|规划阶段/i },
+]
+
+/** 识别提示词所属的 ADD 阶段；无法判定返回 null（不猜测） */
+export function detectRecallStage(prompt: string): RecallStage | null {
+  if (!prompt) return null
+  for (const { stage, re } of STAGE_PATTERNS) {
+    if (re.test(prompt)) return stage
+  }
+  return null
+}
+
+export type RecallModeLike = "off" | "shadow" | "inject"
+
+/**
+ * 阶段召回提示文本（Hook 侧输出）。
+ * - off：返回 null（不提示、不召回）
+ * - shadow：提示可显式调用，并说明 Hook 不注入
+ * - inject：提示调用后将注入上下文
+ */
+export function buildStageRecallHint(
+  stage: RecallStage,
+  mode: RecallModeLike,
+): string | null {
+  if (mode === "off") return null
+  const label = STAGE_LABEL[stage]
+  const tail =
+    mode === "shadow"
+      ? "（当前 shadow 模式：Hook 不注入上下文，召回结果需显式消费）"
+      : "（当前 inject 模式：调用后上下文将被注入）"
+  return (
+    `[Memory] 检测到${label}阶段 → 建议调用 ` +
+    `recall_memory({ stage: "${stage}", query: <本阶段意图>, planKeyword: <Plan 关键词> }) ` +
+    `获取受治理的历史上下文（含来源与评分）。${tail}\n`
+  )
+}

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) }
+      }
+    },
+  }
+}