add-coder 0.3.34 → 0.3.35

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

@@ -0,0 +1,31 @@
+/*
+ * 查询词项抽取（双后端 LIKE/bigram 通道共用）
+ *
+ * 背景：trigram 分词器（PG pg_trgm / SQLite FTS5 trigram）是子串语义，
+ * 对释义查询（如 "新端口怎么申请" vs 内容 "新增端口"）召回不足。
+ * 本模块把查询分解为「拉丁词 + CJK 二元组」词项，供 LIKE 重叠通道计分。
+ */
+import { normalizeContent } from "../domain/dedup.js"
+
+const MAX_TERMS = 24
+
+/** 拉丁/数字词（≥2 字符）+ CJK 连续段的滑动二元组 */
+export function extractQueryTerms(query: string): string[] {
+  const norm = normalizeContent(query)
+  const terms: string[] = []
+  const seen = new Set<string>()
+  const push = (t: string) => {
+    if (!seen.has(t) && terms.length < MAX_TERMS) { seen.add(t); terms.push(t) }
+  }
+
+  // 拉丁词
+  for (const m of norm.matchAll(/[a-z0-9_]{2,}/g)) push(m[0])
+
+  // CJK 连续段 → 滑动二元组（单字段保留单字）
+  for (const seg of norm.matchAll(/[㐀-鿿぀-ヿ]+/g)) {
+    const s = seg[0]
+    if (s.length === 1) { push(s); continue }
+    for (let i = 0; i < s.length - 1; i++) push(s.slice(i, i + 2))
+  }
+  return terms
+}

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

@@ -0,0 +1,87 @@
+/*
+ * Recall 审计写入（Plan §4.3/§7.1-10：每次召回记录候选、评分、选择，可重放）
+ */
+import type { RecalledMemory } from "./types.js"
+
+export interface RecallAuditRecord {
+  repositoryRef: string
+  query: string
+  stage: string
+  consumerRef?: string
+  scopeContext: unknown
+  candidateIds: string[]
+  items: RecalledMemory[]
+  excluded: { memoryId: string; reason: string }[]
+  rankingVersion: string
+  tokenBudget: number
+  injectedTokens: number
+  latencyMs: number
+  degradedMode?: string
+}
+
+export interface RecallAuditStore {
+  createRecall(data: {
+    repositoryRef: string
+    query: string
+    stage: string
+    consumerRef: string | null
+    scopeContext: unknown
+    candidateIds: unknown
+    selectedIds: unknown
+    scoreBreakdown: unknown
+    exclusionReasons: unknown
+    rankingVersion: string
+    tokenBudget: number
+    injectedTokens: number
+    latencyMs: number
+    degradedMode: string | null
+  }): Promise<{ id: string }>
+  createRecallItem(data: {
+    recallId: string
+    memoryId: string
+    selected: boolean
+    rank: number | null
+  }): Promise<unknown>
+}
+
+/** 落库一次召回（Recall + 每候选一条 RecallItem），返回 recallId */
+export async function writeRecallAudit(
+  store: RecallAuditStore,
+  rec: RecallAuditRecord,
+): Promise<string> {
+  const selectedIds = rec.items.map((i) => i.memoryId)
+  const scoreBreakdown: Record<string, Record<string, number>> = {}
+  for (const item of rec.items) scoreBreakdown[item.memoryId] = item.scoreBreakdown
+
+  const recall = await store.createRecall({
+    repositoryRef: rec.repositoryRef,
+    query: rec.query,
+    stage: rec.stage,
+    consumerRef: rec.consumerRef ?? null,
+    scopeContext: rec.scopeContext,
+    candidateIds: rec.candidateIds,
+    selectedIds,
+    scoreBreakdown,
+    exclusionReasons: rec.excluded,
+    rankingVersion: rec.rankingVersion,
+    tokenBudget: rec.tokenBudget,
+    injectedTokens: rec.injectedTokens,
+    latencyMs: rec.latencyMs,
+    degradedMode: rec.degradedMode ?? null,
+  })
+
+  // 候选全集 = 选中 + 被排除（重放完整性）
+  const selectedSet = new Set(selectedIds)
+  const rankOf = new Map(selectedIds.map((id, i) => [id, i + 1]))
+  const excludedReason = new Map(rec.excluded.map((e) => [e.memoryId, e.reason]))
+  for (const id of rec.candidateIds) {
+    await store.createRecallItem({
+      recallId: recall.id,
+      memoryId: id,
+      selected: selectedSet.has(id),
+      rank: rankOf.get(id) ?? null,
+    })
+    void excludedReason.get(id) // reason 已落 Recall.exclusionReasons（JSON），Item 层不重复
+  }
+  return recall.id
+}

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

@@ -0,0 +1,116 @@
+/*
+ * 治理重排（Plan §7.3）
+ *
+ * finalScore = rrfScore
+ *   + scopeBoost + kindBoost + importanceBoost + confidenceBoost + mandatoryConstraintBoost
+ *   - stalePenalty - conflictPenalty - redundancyPenalty
+ *
+ * 权重与 rankingVersion 配置化；首版默认权重经评测校准，未评测前不作为不可变产品规则。
+ */
+import { scopeRank, type ScopeContext } from "../domain/scope.js"
+import type { MemoryStatus } from "../domain/state-machine.js"
+
+export const RANKING_VERSION = "memory-rank-v1"
+/** hybrid（lexical + vector 双通道）排序版本：Plan §3.4 轮 3「rankingVersion v2」 */
+export const RANKING_VERSION_HYBRID = "memory-rank-v2"
+
+/**
+ * RRF 分数放大系数（Plan 轮 3 融合迭代）。
+ *
+ * 问题：RRF 单通道差值约 1/61−1/80 ≈ 0.004，而治理 boost 量级为 0.1–0.5 —— boost 完全主导排序，
+ * 相关性（RRF）只起微调作用，表现为「重要度高的无关记忆排在相关记忆之前」。
+ * 处理：把 RRF 分数放大到与 boost 可比的量级（×100），使**相关性主导、治理项做同分位微调**。
+ * 该系数进入 rankingVersion 快照（权重变更即版本变更）。
+ */
+export const RRF_SCORE_SCALE = 1000
+
+export interface RerankWeights {
+  scopeBoost: number
+  kindBoost: Record<string, number>
+  importanceBoost: number
+  confidenceBoost: number
+  mandatoryConstraintBoost: number
+  stalePenalty: number
+  conflictPenalty: number
+  redundancyPenalty: number
+}
+
+/** 默认权重（v1）：强约束信号最强，stale/冲突/冗余显著惩罚 */
+export const DEFAULT_WEIGHTS: RerankWeights = {
+  scopeBoost: 0.15, // × (scopeRank/7)
+  kindBoost: { CONSTRAINT: 0.25, DECISION: 0.15, FAILURE: 0.1, PITFALL: 0.1, CONVENTION: 0.05 },
+  importanceBoost: 0.2, // × importance
+  confidenceBoost: 0.1, // × confidence
+  mandatoryConstraintBoost: 0.5, // 适用 scope 内的 ACTIVE CONSTRAINT
+  stalePenalty: 0.3,
+  conflictPenalty: 0.2,
+  redundancyPenalty: 0.1,
+}
+
+export interface RerankInput {
+  memoryId: string
+  rrfScore: number
+  kind: string
+  status: MemoryStatus
+  importance: number
+  confidence: number
+  scopeType: string
+  scopeValue: string
+  /** 与已选高分项近重复（由 context-builder 阶段标记，重排阶段先打罚分） */
+  redundant?: boolean
+  /** 与其他候选项存在未决冲突 */
+  conflicted?: boolean
+}
+
+export interface RerankResult {
+  memoryId: string
+  finalScore: number
+  scoreBreakdown: Record<string, number>
+  whySelected: string[]
+}
+
+export function rerankOne(
+  input: RerankInput,
+  scopeCtx: ScopeContext,
+  weights: RerankWeights = DEFAULT_WEIGHTS,
+): RerankResult {
+  const rank = scopeRank(input.scopeType as Parameters<typeof scopeRank>[0]) / 7
+  const scopeBoost = weights.scopeBoost * rank
+  const kindBoost = weights.kindBoost[input.kind] ?? 0
+  const importanceBoost = weights.importanceBoost * input.importance
+  const confidenceBoost = weights.confidenceBoost * input.confidence
+  const mandatory =
+    input.kind === "CONSTRAINT" && input.status === "ACTIVE" ? weights.mandatoryConstraintBoost : 0
+  const stalePenalty = input.status === "STALE" ? weights.stalePenalty : 0
+  const conflictPenalty = input.conflicted ? weights.conflictPenalty : 0
+  const redundancyPenalty = input.redundant ? weights.redundancyPenalty : 0
+
+  const finalScore =
+    input.rrfScore + scopeBoost + kindBoost + importanceBoost + confidenceBoost + mandatory
+    - stalePenalty - conflictPenalty - redundancyPenalty
+
+  const why: string[] = [`rrf=${input.rrfScore.toFixed(4)}`]
+  if (scopeBoost > 0) why.push(`scopeBoost(${input.scopeType}:${input.scopeValue})`)
+  if (kindBoost > 0) why.push(`kindBoost(${input.kind})`)
+  if (mandatory > 0) why.push("mandatoryConstraint")
+  if (stalePenalty > 0) why.push("stalePenalty（诊断模式）")
+  if (conflictPenalty > 0) why.push("conflictPenalty")
+  if (redundancyPenalty > 0) why.push("redundancyPenalty")
+
+  return {
+    memoryId: input.memoryId,
+    finalScore,
+    scoreBreakdown: {
+      rrfScore: input.rrfScore,
+      scopeBoost,
+      kindBoost,
+      importanceBoost,
+      confidenceBoost,
+      mandatoryConstraintBoost: mandatory,
+      stalePenalty: -stalePenalty,
+      conflictPenalty: -conflictPenalty,
+      redundancyPenalty: -redundancyPenalty,
+    },
+    whySelected: why,
+  }
+}

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

@@ -0,0 +1,52 @@
+/*
+ * 检索管线公共类型（Plan §7/§8.1）
+ */
+import type { MemoryStatus } from "../domain/state-machine.js"
+import type { ScopeContext } from "../domain/scope.js"
+
+export interface RankedId {
+  memoryId: string
+  rank: number
+  score?: number
+}
+
+export interface RecallFilter {
+  repositoryRef: string
+  statuses: readonly MemoryStatus[]
+  scopeCtx: ScopeContext
+  kinds?: string[]
+  /** validUntil 过滤基准时刻 */
+  now: Date
+}
+
+export interface ComponentHealth {
+  component: string
+  status: "ok" | "degraded" | "unavailable" | "disabled"
+  detail?: string
+}
+
+export interface LexicalSearchAdapter {
+  readonly id: string
+  search(query: string, filter: RecallFilter, limit: number): Promise<RankedId[]>
+  health(): Promise<ComponentHealth>
+}
+
+/** 最小原生 SQL 查询接口：PG/SQLite adapter 与测试桩共用（生产由 prisma.$queryRawUnsafe 适配） */
+export interface RawQuerier {
+  query<T = Record<string, unknown>>(sql: string, params: unknown[]): Promise<T[]>
+}
+
+/** recall_memory 返回项（Plan §6.2：必须结构化，不依赖模型从自由文本推断） */
+export interface RecalledMemory {
+  memoryId: string
+  kind: string
+  topic: string
+  content: string
+  scope: { type: string; value: string }
+  confidence: number
+  importance: number
+  sourceRefs: string[]
+  whySelected: string[]
+  scoreBreakdown: Record<string, number>
+  supersedes: string[]
+}

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

@@ -0,0 +1,143 @@
+/*
+ * pgvector 向量检索适配器（Plan §3.4 轮 3 Task 3.2 / Spec §6 §VectorCapability）
+ *
+ * 设计要点：
+ *  1. **Prisma schema 不表达向量列**（架构文档定案）：扩展/表/索引由本适配器的原生 DDL 管理，
+ *     `ensureSchema()` 幂等可重放；对应 migration 只负责首次交付（见 3.4）；
+ *  2. **能力检测优先**：`capability()` 先看扩展、再看表；任一缺失都返回 unavailable/degraded，
+ *     调用方据此走 fts-only，绝不因向量缺失阻塞召回；
+ *  3. **维度真源**：表按 provider 维度建列；写入前校验向量长度，禁止脏向量进库。
+ */
+import type { ComponentHealth, RankedId, RecallFilter, RawQuerier } from "../types.js"
+import { MemoryError } from "../../domain/errors.js"
+import type { VectorSearchAdapter } from "../../embedding/index.js"
+
+export const PG_VECTOR_TABLE = "add_memory_vector"
+export const PG_VECTOR_EXTENSION = "vector"
+
+/** 向量字面量（pgvector 接受 '[1,2,3]' 形式） */
+export function pgVectorLiteral(vector: readonly number[]): string {
+  return `[${vector.map((v) => (Number.isFinite(v) ? v : 0)).join(",")}]`
+}
+
+export function pgVectorSchemaDdl(dimension: number, table = PG_VECTOR_TABLE): string[] {
+  if (!Number.isFinite(dimension) || dimension <= 0) {
+    throw new MemoryError("ERR_DIMENSION_MISMATCH", `非法向量维度：${dimension}`)
+  }
+  return [
+    `CREATE EXTENSION IF NOT EXISTS vector;`,
+    `CREATE TABLE IF NOT EXISTS "${table}" (
+  "memory_id" text PRIMARY KEY,
+  "model" text NOT NULL,
+  "dim" integer NOT NULL,
+  "embedding" vector(${dimension}) NOT NULL,
+  "updated_at" timestamptz NOT NULL DEFAULT now()
+);`,
+    `CREATE INDEX IF NOT EXISTS "${table}_embedding_hnsw" ON "${table}" USING hnsw ("embedding" vector_cosine_ops);`,
+  ]
+}
+
+export interface PgVectorAdapterOptions {
+  querier: RawQuerier
+  /** 维度真源（来自 provider 元数据） */
+  dimension: number
+  /** 模型标识：检索时按模型过滤，避免混用不同模型向量 */
+  model: string
+  table?: string
+}
+
+export interface PgVectorAdapter extends VectorSearchAdapter {
+  capability(): Promise<ComponentHealth>
+  ensureSchema(): Promise<{ statements: number }>
+}
+
+export function createPgVectorAdapter(opts: PgVectorAdapterOptions): PgVectorAdapter {
+  const table = opts.table ?? PG_VECTOR_TABLE
+
+  function assertDim(vector: readonly number[]): void {
+    if (vector.length !== opts.dimension) {
+      throw new MemoryError(
+        "ERR_DIMENSION_MISMATCH",
+        `向量维度不符：实际 ${vector.length} vs 期望 ${opts.dimension}`,
+      )
+    }
+  }
+
+  async function capability(): Promise<ComponentHealth> {
+    try {
+      const ext = await opts.querier.query<{ name: string }>(
+        `SELECT extname AS name FROM pg_extension WHERE extname = $1`,
+        [PG_VECTOR_EXTENSION],
+      )
+      if (ext.length === 0) {
+        return {
+          component: "vector-search",
+          status: "unavailable",
+          detail: `pgvector 扩展未安装（table=${table}）→ 降级 fts-only`,
+        }
+      }
+      const tbl = await opts.querier.query<{ name: string | null }>(
+        `SELECT to_regclass($1)::text AS name`,
+        [`public.${table}`],
+      )
+      if (!tbl[0]?.name) {
+        return {
+          component: "vector-search",
+          status: "degraded",
+          detail: `pgvector 已装但表 ${table} 缺失 → 需 ensureSchema()`,
+        }
+      }
+      return { component: "vector-search", status: "ok", detail: `pgvector table=${table} dim=${opts.dimension}` }
+    } catch (error) {
+      return {
+        component: "vector-search",
+        status: "unavailable",
+        detail: `pgvector 探测失败：${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  }
+
+  return {
+    async ensureSchema(): Promise<{ statements: number }> {
+      const ddl = pgVectorSchemaDdl(opts.dimension, table)
+      for (const sql of ddl) await opts.querier.query(sql, [])
+      return { statements: ddl.length }
+    },
+
+    async upsert(memoryId: string, vector: number[], model: string): Promise<void> {
+      assertDim(vector)
+      await opts.querier.query(
+        `INSERT INTO "${table}" ("memory_id", "model", "dim", "embedding")
+         VALUES ($1, $2, $3, $4::vector)
+         ON CONFLICT ("memory_id") DO UPDATE
+           SET "model" = EXCLUDED."model",
+               "dim" = EXCLUDED."dim",
+               "embedding" = EXCLUDED."embedding",
+               "updated_at" = now()`,
+        [memoryId, model, vector.length, pgVectorLiteral(vector)],
+      )
+    },
+
+    async search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]> {
+      assertDim(vector)
+      const rows = await opts.querier.query<{ memory_id: string; score: number | string }>(
+        `SELECT v."memory_id" AS memory_id, 1 - (v."embedding" <=> $1::vector) AS score
+         FROM "${table}" v
+         JOIN "AddMemory" m ON m."id" = v."memory_id"
+         WHERE m."repositoryRef" = $2
+           AND m."status"::text = ANY($3)
+           AND v."model" = $4
+         ORDER BY v."embedding" <=> $1::vector
+         LIMIT $5`,
+        [pgVectorLiteral(vector), filter.repositoryRef, [...filter.statuses], opts.model, limit],
+      )
+      return rows.map((r, i) => ({ memoryId: r.memory_id, rank: i + 1, score: Number(r.score) }))
+    },
+
+    async health(): Promise<ComponentHealth> {
+      return capability()
+    },
+
+    capability,
+  }
+}

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

@@ -0,0 +1,118 @@
+/*
+ * sqlite-vec 向量检索适配器（Plan §3.4 轮 3 Task 3.2 / Spec §6 §VectorCapability）
+ *
+ * ⚠️ 平台说明（诚实登记）：sqlite-vec 是原生扩展，**本仓库当前环境未安装**，因此本文件的
+ * SQL 路径只在扩展存在时才被执行（capability 探测先行）。DDL 与函数名集中在文件顶部常量，
+ * 便于在具备扩展的环境上校正；未安装时 `capability()` 返回 unavailable，召回走 fts-only。
+ *
+ * 与 pgvector 适配器同契约：能力检测 → 幂等 ensureSchema → 维度校验 → upsert/search。
+ */
+import type { ComponentHealth, RankedId, RecallFilter, RawQuerier } from "../types.js"
+import { MemoryError } from "../../domain/errors.js"
+import type { VectorSearchAdapter } from "../../embedding/index.js"
+
+export const SQLITE_VEC_TABLE = "add_memory_vector"
+/** 能力探测：vec0 模块是否注册（只读） */
+export const SQLITE_VEC_CAPABILITY_SQL = `SELECT 1 AS ok FROM pragma_module_list WHERE name = 'vec0'`
+/** 距离函数（余弦距离，越小越近） */
+export const SQLITE_VEC_DISTANCE_FN = "vec_distance_cosine"
+
+export function sqliteVecSchemaDdl(dimension: number, table = SQLITE_VEC_TABLE): string[] {
+  if (!Number.isFinite(dimension) || dimension <= 0) {
+    throw new MemoryError("ERR_DIMENSION_MISMATCH", `非法向量维度：${dimension}`)
+  }
+  return [
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${table} USING vec0(memory_id text primary key, embedding float[${dimension}]);`,
+    `CREATE TABLE IF NOT EXISTS ${table}_meta (memory_id text PRIMARY KEY, model text NOT NULL, dim integer NOT NULL, updated_at text NOT NULL DEFAULT (datetime('now')));`,
+  ]
+}
+
+export interface SqliteVecAdapterOptions {
+  querier: RawQuerier
+  dimension: number
+  model: string
+  table?: string
+}
+
+export interface SqliteVecAdapter extends VectorSearchAdapter {
+  capability(): Promise<ComponentHealth>
+  ensureSchema(): Promise<{ statements: number }>
+}
+
+export function createSqliteVecAdapter(opts: SqliteVecAdapterOptions): SqliteVecAdapter {
+  const table = opts.table ?? SQLITE_VEC_TABLE
+
+  function assertDim(vector: readonly number[]): void {
+    if (vector.length !== opts.dimension) {
+      throw new MemoryError(
+        "ERR_DIMENSION_MISMATCH",
+        `向量维度不符：实际 ${vector.length} vs 期望 ${opts.dimension}`,
+      )
+    }
+  }
+
+  async function capability(): Promise<ComponentHealth> {
+    try {
+      const rows = await opts.querier.query<{ ok: number }>(SQLITE_VEC_CAPABILITY_SQL, [])
+      if (rows.length === 0) {
+        return {
+          component: "vector-search",
+          status: "unavailable",
+          detail: "sqlite-vec(vec0) 未安装 → 降级 fts-only",
+        }
+      }
+      return { component: "vector-search", status: "ok", detail: `sqlite-vec table=${table} dim=${opts.dimension}` }
+    } catch (error) {
+      return {
+        component: "vector-search",
+        status: "unavailable",
+        detail: `sqlite-vec 探测失败：${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  }
+
+  return {
+    async ensureSchema(): Promise<{ statements: number }> {
+      const ddl = sqliteVecSchemaDdl(opts.dimension, table)
+      for (const sql of ddl) await opts.querier.query(sql, [])
+      return { statements: ddl.length }
+    },
+
+    async upsert(memoryId: string, vector: number[], model: string): Promise<void> {
+      assertDim(vector)
+      // vec_f32 接受 JSON 文本形式；绑定为字符串参数
+      await opts.querier.query(
+        `INSERT INTO ${table}(memory_id, embedding) VALUES (?, vec_f32(?))
+         ON CONFLICT(memory_id) DO UPDATE SET embedding = vec_f32(?)`,
+        [memoryId, JSON.stringify(vector), JSON.stringify(vector)],
+      )
+      await opts.querier.query(
+        `INSERT INTO ${table}_meta(memory_id, model, dim) VALUES (?, ?, ?)
+         ON CONFLICT(memory_id) DO UPDATE SET model = excluded.model, dim = excluded.dim`,
+        [memoryId, model, vector.length],
+      )
+    },
+
+    async search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]> {
+      assertDim(vector)
+      const rows = await opts.querier.query<{ memory_id: string; distance: number | string }>(
+        `SELECT v.memory_id AS memory_id, ${SQLITE_VEC_DISTANCE_FN}(v.embedding, vec_f32(?)) AS distance
+         FROM ${table} v
+         JOIN ${table}_meta meta ON meta.memory_id = v.memory_id
+         JOIN "AddMemory" m ON m.id = v.memory_id
+         WHERE m.repositoryRef = ?
+           AND meta.model = ?
+         ORDER BY distance ASC
+         LIMIT ?`,
+        [JSON.stringify(vector), filter.repositoryRef, opts.model, limit],
+      )
+      return rows.map((r, i) => ({ memoryId: r.memory_id, rank: i + 1, score: 1 - Number(r.distance) }))
+    },
+
+    async health(): Promise<ComponentHealth> {
+      return capability()
+    },
+
+    capability,
+  }
+}

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

@@ -0,0 +1,39 @@
+/*
+ * Memory 子系统发布开关（Spec §10，Plan §9.3）
+ *
+ * 约束：governance Hook（同步 spawn 子进程，≤200ms 预算）与 jobs（异步）共用本模块，
+ * 因此全部函数必须是同步、纯环境变量读取，禁止任何 IO/DB 访问。
+ *
+ * 开关：
+ * - ADD_MEMORY_RECALL_MODE = off | shadow | inject（默认 shadow：召回可执行并落审计，但 Hook 不注入上下文）
+ * - ADD_MEMORY_MAX_TOKENS：L1 注入 token 预算（默认 600）
+ * - ADD_MEMORY_EVIDENCE = off | on（默认 on：PostToolUse 白名单采证入队）
+ */
+
+export type RecallMode = "off" | "shadow" | "inject"
+
+export function recallMode(env: NodeJS.ProcessEnv = process.env): RecallMode {
+  const v = (env.ADD_MEMORY_RECALL_MODE ?? "shadow").toLowerCase()
+  return v === "off" || v === "inject" ? v : "shadow"
+}
+
+export function memoryMaxTokens(env: NodeJS.ProcessEnv = process.env): number {
+  const n = Number(env.ADD_MEMORY_MAX_TOKENS ?? 600)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 600
+}
+
+export function evidenceEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.ADD_MEMORY_EVIDENCE ?? "on").toLowerCase() !== "off"
+}
+
+/** 记忆工作目录（快照 + 事件队列所在）：${magicDir}/memory/ */
+export const MEMORY_DIR_NAME = "memory"
+/** L1/L2 快照文件名 */
+export const L1_SNAPSHOT_FILE = "l1-context.md"
+export const L2_SNAPSHOT_FILE = "l2-context.md"
+/** PostToolUse 采证事件队列（jsonl，append-only，由 consolidation job 消费） */
+export const EVIDENCE_QUEUE_FILE = "evidence-queue.jsonl"
+/** evidence 队列消费进度标记（已处理字节偏移） */
+export const EVIDENCE_OFFSET_FILE = "evidence-queue.offset"
+/** L1 快照新鲜度上限（毫秒，默认 7 天）：过期不注入 */
+export const L1_SNAPSHOT_TTL_MS = 7 * 24 * 60 * 60 * 1000

package/templates/core/scripts/mcp-server/shared/review-files.ts

@@ -0,0 +1,22 @@
+/*
+ * 审查文档命名识别（纯函数；2026-09-14 从 tools/review.ts 抽出）
+ *
+ * 抽出原因：① 纯函数不该和 prisma/工具注册绑在一起（拖进来就要求 DB 依赖，测试得打 mock）；
+ * ② 仓库里并存两套命名，识别规则需要被用例直接钉住：
+ *    - `{planPrefix}-review-v1.md`（历史）
+ *    - `{planPrefix}-plan-v1-review.md`（create_hitl 的占位路径落点／现行）
+ *    旧匹配要求包含 `-review-`（review 后必须紧跟连字符），会把后一整类漏掉。
+ */
+import { basename } from "path"
+
+/** 从文件列表里挑出审查文档（.md 且文件名含 review，大小写不敏感） */
+export function pickReviewFiles(files: readonly string[]): string[] {
+  return files.filter((f) => f.endsWith(".md") && basename(f).toLowerCase().includes("review"))
+}
+
+/** 从审查文件名推导 planName 前缀（两种命名都要剥干净） */
+export function derivePlanNameFromReviewFile(file: string): string {
+  return basename(file, ".md")
+    .replace(/-review-(implementation|runtime).*$/, "") // 变体后缀
+    .replace(/-review.*$/, "")                          // 普通 review 后缀（含 -review-v1 / -review）
+}