add-coder 0.3.34 → 0.3.37

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

@@ -0,0 +1,33 @@
+/*
+ * Memory 子系统稳定错误码（Plan §12.3：MCP 错误采用稳定错误码，不能只返回自由文本）
+ * 契约：code 字符串冻结，变更需走 Review；message 可携带上下文细节。
+ */
+export const MEMORY_ERROR = {
+  ERR_REPOSITORY_MISMATCH: "调用方 repositoryRef 与运行时上下文不一致，越权访问被拒绝",
+  ERR_ORG_SCOPE_DISABLED: "ORGANIZATION scope 首版禁用（Plan §17-7 定案）",
+  ERR_ILLEGAL_TRANSITION: "非法状态迁移",
+  ERR_EVIDENCE_REQUIRED: "进入 ACTIVE 必须至少关联一条 Evidence",
+  ERR_APPROVAL_REQUIRED: "进入 ACTIVE 必须提供 approvedBy/approvedAt",
+  ERR_SUPERSESSION_INVALID: "supersede 需要有效的 supersededById 且 repository/scope 兼容",
+  ERR_INVARIANT: "字段不变量违反（如 importance/confidence 越出 [0,1]）",
+  ERR_FTS_UNAVAILABLE: "FTS 能力不可用且无法降级",
+  ERR_SECRET_DETECTED: "内容命中密钥/凭证模式，拒写",
+  ERR_NOT_FOUND: "记录不存在",
+  ERR_EMBEDDING_DISABLED: "EmbeddingProvider=none，向量能力未启用",
+  ERR_DIMENSION_MISMATCH: "嵌入维度与真源不一致（模型元数据 vs 声明维度），拒绝写入脏向量",
+} as const
+
+export type MemoryErrorCode = keyof typeof MEMORY_ERROR
+
+export class MemoryError extends Error {
+  readonly code: MemoryErrorCode
+  constructor(code: MemoryErrorCode, detail?: string) {
+    super(detail ? `${code}: ${MEMORY_ERROR[code]}（${detail}）` : `${code}: ${MEMORY_ERROR[code]}`)
+    this.name = "MemoryError"
+    this.code = code
+  }
+}
+
+export function isMemoryError(e: unknown): e is MemoryError {
+  return e instanceof MemoryError
+}

package/templates/core/scripts/mcp-server/shared/memory/domain/handoff-digest.ts

@@ -0,0 +1,92 @@
+/*
+ * Handoff Digest 候选构造（Plan §3.1 轮 2 / Spec §3 §HandoffDigest）
+ *
+ * 纯函数：输入 HANDOFF Evidence 行 → 输出可落库的 HANDOFF_DIGEST 候选提案。
+ * 三条不变量：
+ *  1. **绝不直接 ACTIVE**——提案只带 status=CANDIDATE 语义（由调用方落库时体现）；
+ *  2. **幂等**——dedupKey 由「来源引用 + 摘要内容」派生，同一 evidence 重放得到同一键；
+ *  3. **内容是可验证结论**，不是裸数值或空串：excerpt 为空时显式标注「摘要待人工补充」。
+ */
+import { contentHash, normalizeContent } from "./dedup.js"
+
+export const HANDOFF_DIGEST_KIND = "HANDOFF_DIGEST" as const
+
+/** 摘要正文最大字符数（超出截断并标注） */
+export const HANDOFF_EXCERPT_MAX = 300
+
+export interface HandoffDigestInput {
+  /** handoff 文档路径或引用（evidence.sourceRef） */
+  handoffRef: string
+  /** evidence 摘要原文 */
+  excerpt: string
+  /** 关联 Plan 关键词（evidence.planKeyword，可为空） */
+  planKeyword?: string | null
+}
+
+export interface HandoffDigestProposal {
+  kind: typeof HANDOFF_DIGEST_KIND
+  topic: string
+  content: string
+  scopeType: "PLAN" | "REPOSITORY"
+  scopeValue: string
+  contentHash: string
+  dedupKey: string
+  metadata: {
+    handoffRef: string
+    planKeyword: string | null
+    excerptTruncated: boolean
+  }
+}
+
+/** 从 handoff 引用提取主题名（去目录、去扩展名） */
+export function handoffTopicOf(handoffRef: string): string {
+  const base = handoffRef.split(/[\\/]/).pop() ?? handoffRef
+  const stem = base.replace(/\.(md|markdown|txt)$/i, "")
+  return stem.length > 0 ? stem : handoffRef
+}
+
+/**
+ * 构造 HANDOFF_DIGEST 候选提案。
+ *
+ * scope 选择：有 planKeyword → PLAN scope（历史语义，默认召回需显式放行）；
+ * 无 planKeyword → REPOSITORY scope（可被常规召回命中）。
+ */
+export function buildHandoffDigest(
+  input: HandoffDigestInput,
+  opts: { repositoryRef: string; maxExcerpt?: number },
+): HandoffDigestProposal {
+  const maxExcerpt = opts.maxExcerpt ?? HANDOFF_EXCERPT_MAX
+  const topic = handoffTopicOf(input.handoffRef)
+  const normalizedExcerpt = normalizeContent(input.excerpt ?? "")
+  const planKeyword = input.planKeyword && input.planKeyword.trim().length > 0
+    ? input.planKeyword.trim()
+    : null
+
+  const truncated = normalizedExcerpt.length > maxExcerpt
+  const body = truncated
+    ? `${normalizedExcerpt.slice(0, maxExcerpt)}…（已截断）`
+    : normalizedExcerpt
+
+  const content =
+    body.length > 0
+      ? `交接摘要 ${topic}：${body}（来源 ${input.handoffRef}）`
+      : `交接文档 ${input.handoffRef} 已归档，摘要待人工补充（自动摘要为空）。`
+
+  const scopeType: "PLAN" | "REPOSITORY" = planKeyword ? "PLAN" : "REPOSITORY"
+  const scopeValue = planKeyword ?? opts.repositoryRef
+
+  return {
+    kind: HANDOFF_DIGEST_KIND,
+    topic,
+    content,
+    scopeType,
+    scopeValue,
+    contentHash: contentHash(content),
+    dedupKey: contentHash(`${HANDOFF_DIGEST_KIND}|${input.handoffRef}|${normalizedExcerpt}`),
+    metadata: {
+      handoffRef: input.handoffRef,
+      planKeyword,
+      excerptTruncated: truncated,
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/domain/metric-candidate.ts

@@ -0,0 +1,79 @@
+/*
+ * 指标到知识的转换（Plan §10）
+ *
+ * entropy/code quality/Gate score 只写 AddMetricSnapshot；单个数值不能自动成为长期文本记忆。
+ * 候选生成需满足：同 scope 异常连续达阈值 / 多独立证据指向同根因 / 显著偏离基线且有可解释事件。
+ */
+
+export interface MetricPoint {
+  repositoryRef: string
+  metricType: string
+  value: number
+  baseline?: number | null
+  planKeyword?: string | null
+  measuredAt: Date
+  sourceRef: string
+}
+
+export interface MetricCandidateRule {
+  /** 同 scope 连续异常阈值（默认 3 次） */
+  streakThreshold: number
+  /** 显著偏离基线的相对幅度（默认 20%） */
+  deviationRatio: number
+  /** 判定"异常"的方向：高于基线为坏（higher-worse）或低于基线为坏（lower-worse） */
+  direction: "higher-worse" | "lower-worse"
+}
+
+export const DEFAULT_METRIC_RULE: MetricCandidateRule = {
+  streakThreshold: 3,
+  deviationRatio: 0.2,
+  direction: "lower-worse",
+}
+
+export interface MetricCandidateProposal {
+  topic: string
+  content: string
+  evidenceSourceRefs: string[]
+  rule: string
+}
+
+function isAnomaly(p: MetricPoint, rule: MetricCandidateRule): boolean {
+  if (p.baseline == null) return false
+  const dev = Math.abs(p.value - p.baseline) / (Math.abs(p.baseline) || 1)
+  if (dev < rule.deviationRatio) return false
+  return rule.direction === "lower-worse" ? p.value < p.baseline : p.value > p.baseline
+}
+
+/**
+ * 检测「同 scope 连续异常」：按时间排序后尾部连续异常数 ≥ streakThreshold 时生成候选建议。
+ * 纯函数；是否真正创建 Candidate 由调用方（consolidation job / 人工）决定。
+ */
+export function detectAnomalyStreak(
+  points: MetricPoint[],
+  rule: MetricCandidateRule = DEFAULT_METRIC_RULE,
+): MetricCandidateProposal | null {
+  if (points.length < rule.streakThreshold) return null
+  const sorted = [...points].sort((a, b) => a.measuredAt.getTime() - b.measuredAt.getTime())
+  let streak = 0
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    if (isAnomaly(sorted[i], rule)) streak++
+    else break
+  }
+  if (streak < rule.streakThreshold) return null
+  const last = sorted[sorted.length - 1]
+  const streakPoints = sorted.slice(-streak)
+  return {
+    topic: `${last.metricType} 连续 ${streak} 次显著偏离基线`,
+    content:
+      `指标 ${last.metricType} 在最近 ${streak} 次测量中连续偏离基线超过 ${rule.deviationRatio * 100}%` +
+      `（baseline=${streakPoints[0].baseline}, 最新值=${last.value}）。` +
+      `建议人工审核是否形成可验证结论后再转为长期记忆。`,
+    evidenceSourceRefs: streakPoints.map((p) => p.sourceRef),
+    rule: `anomaly-streak>=${rule.streakThreshold} deviation>=${rule.deviationRatio} ${rule.direction}`,
+  }
+}
+
+/** Gate 执行后生成 sourceRef（Review P1 #2 回流：{gate}:{planKeyword}:{runId}） */
+export function metricSourceRef(gate: string, planKeyword: string, runId: string): string {
+  return `${gate}:${planKeyword}:${runId}`
+}

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

@@ -0,0 +1,94 @@
+/*
+ * Memory Scope 规则（Plan §7.2）
+ *
+ * 优先级：symbol > path > module > branch > repository > organization
+ * ORGANIZATION 首版禁用（写入拒绝，§17-7）；PLAN/SPEC 只在对应流程或显式历史查询中参与。
+ */
+import { MemoryError } from "./errors.js"
+
+export type MemoryScopeType =
+  | "ORGANIZATION" | "REPOSITORY" | "BRANCH" | "MODULE"
+  | "PATH" | "SYMBOL" | "PLAN" | "SPEC"
+
+export interface Scope {
+  type: MemoryScopeType
+  value: string
+}
+
+/** 召回时的上下文坐标（由调用方从运行时环境组装） */
+export interface ScopeContext {
+  repository: string
+  branch?: string
+  module?: string
+  paths?: string[]
+  symbols?: string[]
+  planKeyword?: string
+  specRef?: string
+  /** 显式历史查询时放行 PLAN/SPEC scope（默认 false） */
+  includePlanScope?: boolean
+}
+
+const RANK: Record<MemoryScopeType, number> = {
+  SYMBOL: 7,
+  PATH: 6,
+  MODULE: 5,
+  BRANCH: 4,
+  REPOSITORY: 3,
+  PLAN: 2,
+  SPEC: 2,
+  ORGANIZATION: 1,
+}
+
+export function scopeRank(t: MemoryScopeType): number {
+  return RANK[t]
+}
+
+/** 写入守卫：ORGANIZATION 首版禁用 */
+export function assertScopeWritable(scope: Scope): void {
+  if (scope.type === "ORGANIZATION") {
+    throw new MemoryError("ERR_ORG_SCOPE_DISABLED")
+  }
+}
+
+/** 判定一条 Memory 的 scope 在当前上下文是否有效（召回过滤用） */
+export function scopeApplies(memScope: Scope, ctx: ScopeContext): boolean {
+  switch (memScope.type) {
+    case "ORGANIZATION":
+      return false // 首版禁用
+    case "REPOSITORY":
+      return memScope.value === ctx.repository
+    case "BRANCH":
+      return !!ctx.branch && ctx.branch === memScope.value
+    case "MODULE":
+      // module 语义：当前任一路径以该模块目录为前缀
+      return !!ctx.module && ctx.module === memScope.value ||
+        (ctx.paths ?? []).some((p) => p === memScope.value || p.startsWith(memScope.value + "/"))
+    case "PATH":
+      return (ctx.paths ?? []).some(
+        (p) => p === memScope.value || p.startsWith(memScope.value.replace(/\/?$/, "/")),
+      )
+    case "SYMBOL":
+      return (ctx.symbols ?? []).includes(memScope.value)
+    case "PLAN":
+      return !!ctx.includePlanScope && !!ctx.planKeyword && ctx.planKeyword === memScope.value
+    case "SPEC":
+      return !!ctx.includePlanScope && !!ctx.specRef && ctx.specRef === memScope.value
+  }
+}
+
+/**
+ * supersede 兼容性（Plan §4.4）：新旧 Memory 的 repository/scope 必须兼容。
+ * 兼容 = 同类型同值；或 PATH/MODULE 类型间存在前缀覆盖；或一方为 REPOSITORY（全库覆盖）。
+ */
+export function scopesCompatible(a: Scope, b: Scope): boolean {
+  if (a.type === b.type && a.value === b.value) return true
+  if (a.type === "REPOSITORY" || b.type === "REPOSITORY") {
+    return a.type === "REPOSITORY" && b.type === "REPOSITORY" ? a.value === b.value : true
+  }
+  const pathLike = (t: MemoryScopeType) => t === "PATH" || t === "MODULE"
+  if (pathLike(a.type) && pathLike(b.type)) {
+    return a.value.startsWith(b.value.replace(/\/?$/, "/")) ||
+      b.value.startsWith(a.value.replace(/\/?$/, "/"))
+  }
+  return false
+}

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

@@ -0,0 +1,50 @@
+/*
+ * 密钥/凭证扫描（Plan §11：Evidence 摘录在写入前执行秘密与敏感信息检测）
+ * 命中即拒写（ERR_SECRET_DETECTED）。宁可误报，不可漏报。
+ */
+import { MemoryError } from "./errors.js"
+
+export interface SecretHit {
+  pattern: string
+  index: number
+  preview: string
+}
+
+interface SecretPattern {
+  name: string
+  re: RegExp
+}
+
+const PATTERNS: SecretPattern[] = [
+  { name: "private-key-block", re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { name: "aws-access-key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: "github-token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/ },
+  { name: "openai-style-key", re: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
+  { name: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { name: "bearer-token", re: /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}\b/i },
+  { name: "conn-string-password", re: /(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:\s/]+:[^@\s]+@/i },
+  { name: "generic-secret-assign", re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token)\b\s*[:=]\s*["'][^"'\s]{8,}["']/i },
+  { name: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+]
+
+export function scanSecrets(text: string): SecretHit[] {
+  const hits: SecretHit[] = []
+  for (const p of PATTERNS) {
+    const m = p.re.exec(text)
+    if (m) {
+      hits.push({
+        pattern: p.name,
+        index: m.index,
+        preview: text.slice(Math.max(0, m.index - 10), m.index + 20).replace(/\s+/g, " ").slice(0, 40),
+      })
+    }
+  }
+  return hits
+}
+
+export function assertNoSecrets(text: string): void {
+  const hits = scanSecrets(text)
+  if (hits.length > 0) {
+    throw new MemoryError("ERR_SECRET_DETECTED", hits.map((h) => h.pattern).join(","))
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/domain/state-machine.ts

@@ -0,0 +1,90 @@
+/*
+ * Memory 生命周期状态机（Plan §5）
+ *
+ * CANDIDATE → PENDING → ACTIVE → STALE → SUPERSEDED → ARCHIVED
+ *     │          │         │        └──────────────→ ARCHIVED
+ *     └──────────┴─────────┴──────────────────────→ REJECTED
+ *
+ * 首版默认只允许人工或显式治理调用激活（approve 的强制校验在此表达）。
+ */
+import { MemoryError } from "./errors.js"
+
+export type MemoryStatus =
+  | "CANDIDATE" | "PENDING" | "ACTIVE" | "STALE"
+  | "SUPERSEDED" | "REJECTED" | "ARCHIVED"
+
+export type MemoryAction =
+  | "propose" | "submit_review" | "approve" | "reject"
+  | "mark_stale" | "supersede" | "archive" | "restore"
+
+interface Transition {
+  from: MemoryStatus[]
+  to: MemoryStatus
+}
+
+/** 迁移表：propose 是创建语义（无 from），其余均为状态到状态 */
+export const TRANSITIONS: Record<MemoryAction, Transition> = {
+  propose:       { from: [],                              to: "CANDIDATE" },
+  submit_review: { from: ["CANDIDATE"],                   to: "PENDING" },
+  approve:       { from: ["PENDING", "CANDIDATE"],        to: "ACTIVE" },
+  reject:        { from: ["CANDIDATE", "PENDING"],        to: "REJECTED" },
+  mark_stale:    { from: ["ACTIVE"],                      to: "STALE" },
+  supersede:     { from: ["ACTIVE", "STALE"],             to: "SUPERSEDED" },
+  archive:       { from: ["ACTIVE", "STALE", "SUPERSEDED"], to: "ARCHIVED" },
+  restore:       { from: ["ARCHIVED", "REJECTED"],        to: "CANDIDATE" },
+}
+
+/** approve / supersede 的不变量校验输入（DB 查询结果由调用方传入，领域层保持纯函数） */
+export interface TransitionContext {
+  evidenceCount?: number
+  approvedBy?: string | null
+  approvedAt?: Date | null
+  /** supersede 专用：新记忆 id 与 repository/scope 兼容性判定结果 */
+  supersededById?: string | null
+  supersessionCompatible?: boolean
+}
+
+export interface TransitionResult {
+  from: MemoryStatus
+  to: MemoryStatus
+  action: MemoryAction
+}
+
+/** 判定迁移是否合法；非法时抛 MemoryError（ERR_ILLEGAL_TRANSITION / ERR_EVIDENCE_REQUIRED / ...） */
+export function assertTransition(
+  current: MemoryStatus,
+  action: MemoryAction,
+  ctx: TransitionContext = {},
+): TransitionResult {
+  const t = TRANSITIONS[action]
+  if (action === "propose") {
+    // 创建语义：不与现有状态冲突（由调用方决定新建或合并）
+    return { from: current, to: t.to, action }
+  }
+  if (!t.from.includes(current)) {
+    throw new MemoryError("ERR_ILLEGAL_TRANSITION", `${current} --${action}--> ${t.to} 不允许（允许起点: ${t.from.join("/")}）`)
+  }
+  if (action === "approve") {
+    if (!ctx.evidenceCount || ctx.evidenceCount < 1) {
+      throw new MemoryError("ERR_EVIDENCE_REQUIRED")
+    }
+    if (!ctx.approvedBy) {
+      throw new MemoryError("ERR_APPROVAL_REQUIRED", "缺少 approvedBy")
+    }
+  }
+  if (action === "supersede") {
+    if (!ctx.supersededById) {
+      throw new MemoryError("ERR_SUPERSESSION_INVALID", "缺少 supersededById")
+    }
+    if (ctx.supersessionCompatible === false) {
+      throw new MemoryError("ERR_SUPERSESSION_INVALID", "新旧 Memory 的 repository/scope 不兼容")
+    }
+  }
+  return { from: current, to: t.to, action }
+}
+
+/** 默认召回允许的状态集合（Plan §7.1：默认排除 CANDIDATE/PENDING/REJECTED/ARCHIVED/SUPERSEDED/过期项） */
+export const DEFAULT_RECALL_STATUSES: readonly MemoryStatus[] = ["ACTIVE"]
+
+/** 显式诊断模式额外放行 STALE（带警告） */
+export const DIAGNOSTIC_RECALL_STATUSES: readonly MemoryStatus[] = ["ACTIVE", "STALE"]

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

@@ -0,0 +1,117 @@
+/*
+ * Embedding 抽象与降级（Plan §8.1/§8.4，Spec §9）
+ *
+ * 提供者：none（默认，显式不可用）/ local-onnx / openai-compatible（Phase 5 轮 3）。
+ * Vector adapter：pgvector / sqlite-vec（retrieval/vector/），能力检测失败即降级。
+ * 契约：记忆系统任何环节不得因 embedding 缺失而阻塞 Gate（FTS-only 合法降级）。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth, RankedId, RecallFilter } from "../retrieval/types.js"
+
+export interface EmbeddingProvider {
+  readonly id: string // "none" | "local-onnx" | "openai-compatible" | "custom"
+  readonly dimension: number
+  embed(texts: string[]): Promise<number[][]>
+  health(): Promise<ComponentHealth>
+}
+
+export interface VectorSearchAdapter {
+  search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]>
+  upsert(memoryId: string, vector: number[], model: string): Promise<void>
+  health(): Promise<ComponentHealth>
+}
+
+/** 首版唯一 provider：显式不可用。调用方据此走 FTS-only 并标注 degradedMode */
+export function createNoneEmbeddingProvider(): EmbeddingProvider {
+  return {
+    id: "none",
+    dimension: 0,
+    embed: (): Promise<number[][]> => Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED")),
+    health: (): Promise<ComponentHealth> =>
+      Promise.resolve({ component: "embedding", status: "disabled", detail: "EmbeddingProvider=none（首版定案，FTS-only）" }),
+  }
+}
+
+/** Vector adapter capability 存根：health 报告 unavailable，search/upsert 拒绝 */
+export function createUnavailableVectorAdapter(): VectorSearchAdapter {
+  return {
+    search: (): Promise<RankedId[]> =>
+      Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED", "VectorSearchAdapter 未配置（Phase 5 接入）")),
+    upsert: (): Promise<void> =>
+      Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED", "VectorSearchAdapter 未配置（Phase 5 接入）")),
+    health: (): Promise<ComponentHealth> =>
+      Promise.resolve({ component: "vector-search", status: "unavailable", detail: "向量索引未启用（Phase 5 接入 pgvector/sqlite-vec）" }),
+  }
+}
+
+/**
+ * 维度真源校验（Review R5 回流）：provider 上报维度必须与 DB 侧声明维度一致，否则拒写。
+ * declaredDim 来自 AddMemory.embeddingDim（写入路径的真源）。
+ */
+export function assertEmbeddingDimension(providerDim: number, declaredDim: number): void {
+  if (declaredDim <= 0) return // 未声明维度：首写，由 provider 值落库
+  if (providerDim !== declaredDim) {
+    throw new MemoryError(
+      "ERR_DIMENSION_MISMATCH",
+      `嵌入维度不一致：provider=${providerDim} vs 声明=${declaredDim}（拒绝写入，避免脏向量）`,
+    )
+  }
+}
+
+export type EmbeddingMode = "none" | "local-onnx" | "openai-compatible"
+
+export interface EmbeddingEnvConfig {
+  mode?: string
+  model?: string
+  dimension?: number
+  baseUrl?: string
+  apiKey?: string
+  cacheDir?: string
+  remoteHost?: string
+}
+
+/** 从环境变量解析提供者配置（纯函数，便于测试与文档化） */
+export function parseEmbeddingEnv(env: NodeJS.ProcessEnv = process.env): EmbeddingEnvConfig {
+  const mode = (env.ADD_MEMORY_EMBEDDING ?? "none").toLowerCase()
+  const dim = Number(env.ADD_MEMORY_EMBEDDING_DIM ?? "")
+  return {
+    mode,
+    model: env.ADD_MEMORY_EMBEDDING_MODEL,
+    dimension: Number.isFinite(dim) && dim > 0 ? Math.floor(dim) : undefined,
+    baseUrl: env.ADD_MEMORY_EMBEDDING_BASE_URL,
+    apiKey: env.ADD_MEMORY_EMBEDDING_API_KEY,
+    cacheDir: env.ADD_MEMORY_EMBEDDING_CACHE_DIR,
+    remoteHost: env.ADD_MEMORY_EMBEDDING_REMOTE_HOST,
+  }
+}
+
+/**
+ * 按配置装配提供者（默认 none → 行为与首版一致）。
+ * local-onnx / openai-compatible 走动态 import，未配置的路径不加载任何重依赖。
+ */
+export async function createEmbeddingProviderFromConfig(
+  config: EmbeddingEnvConfig = parseEmbeddingEnv(),
+): Promise<EmbeddingProvider> {
+  const mode = (config.mode ?? "none") as EmbeddingMode
+  if (mode === "local-onnx") {
+    const { createLocalOnnxEmbeddingProvider } = await import("./local-onnx.js")
+    return createLocalOnnxEmbeddingProvider({
+      model: config.model,
+      cacheDir: config.cacheDir,
+      remoteHost: config.remoteHost,
+    })
+  }
+  if (mode === "openai-compatible") {
+    if (!config.baseUrl) {
+      throw new MemoryError("ERR_EMBEDDING_DISABLED", "openai-compatible 需要 ADD_MEMORY_EMBEDDING_BASE_URL")
+    }
+    const { createOpenAiCompatibleEmbeddingProvider } = await import("./openai-compatible.js")
+    return createOpenAiCompatibleEmbeddingProvider({
+      baseUrl: config.baseUrl,
+      model: config.model ?? "text-embedding-3-small",
+      apiKey: config.apiKey,
+      dimension: config.dimension,
+    })
+  }
+  return createNoneEmbeddingProvider()
+}

package/templates/core/scripts/mcp-server/shared/memory/embedding/local-onnx.ts

@@ -0,0 +1,105 @@
+/*
+ * 本地 ONNX 嵌入提供者（Plan §3.4 轮 3 Task 3.1 / Spec §6 §VectorCapability）
+ *
+ * 关键约束：
+ *  1. **可选依赖**：@huggingface/transformers 与模型权重都可能在目标机器缺失——加载失败
+ *     必须收敛为 ERR_EMBEDDING_DISABLED（调用方据此走 fts-only），绝不抛裸异常阻塞 Gate；
+ *  2. **维度以模型元数据为真源**：dimension 由首次推理的实际输出长度决定（不硬编码），
+ *     与 DB 侧 AddMemory.embeddingDim 不一致时由调用方拒绝写入（Review R5 回流）；
+ *  3. 惰性加载：不在模块顶层 import/下载模型，首次 embed 时才初始化。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth } from "../retrieval/types.js"
+import type { EmbeddingProvider } from "./index.js"
+
+/** 默认模型：中文小模型（真源维度 512，与 Plan R5「维度真源」一致） */
+export const DEFAULT_LOCAL_ONNX_MODEL = "Xenova/bge-small-zh-v1.5"
+
+export interface LocalOnnxOptions {
+  model?: string
+  /** 显式缓存目录；缺省复用 HF_HUB_CACHE → HF_HOME/hub → ~/.cache/huggingface/hub */
+  cacheDir?: string
+  /** 镜像站（内网/受限网络） */
+  remoteHost?: string
+  /** 测试注入：直接给定 pipeline 工厂 */
+  loadPipeline?: (model: string) => Promise<(texts: string[]) => Promise<number[][]>>
+}
+
+export interface LocalOnnxProvider extends EmbeddingProvider {
+  /** 首次推理后可用；未初始化时为 0（调用方以 assertEmbeddingDimension 校验） */
+  readonly resolvedDimension: number
+}
+
+export function createLocalOnnxEmbeddingProvider(opts: LocalOnnxOptions = {}): LocalOnnxProvider {
+  const model = opts.model ?? DEFAULT_LOCAL_ONNX_MODEL
+  let embedFn: ((texts: string[]) => Promise<number[][]>) | null = null
+  let dimension = 0
+
+  async function ensureLoaded(): Promise<(texts: string[]) => Promise<number[][]>> {
+    if (embedFn) return embedFn
+    try {
+      if (opts.loadPipeline) {
+        embedFn = await opts.loadPipeline(model)
+      } else {
+        const { pipeline, env } = await import("@huggingface/transformers")
+        if (opts.cacheDir) env.cacheDir = opts.cacheDir
+        if (opts.remoteHost) env.remoteHost = opts.remoteHost
+        const extractor = await pipeline("feature-extraction", model)
+        embedFn = async (texts: string[]) => {
+          const result = await extractor(texts, { pooling: "mean", normalize: true })
+          const list = result.tolist() as number[][]
+          return list.length === texts.length ? list : [list as unknown as number[]]
+        }
+      }
+      return embedFn
+    } catch (error) {
+      throw new MemoryError(
+        "ERR_EMBEDDING_DISABLED",
+        `本地 ONNX 模型不可用（model=${model}）：${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  return {
+    id: "local-onnx",
+    get dimension(): number {
+      return dimension
+    },
+    get resolvedDimension(): number {
+      return dimension
+    },
+    async embed(texts: string[]): Promise<number[][]> {
+      if (texts.length === 0) return []
+      const fn = await ensureLoaded()
+      let vectors: number[][]
+      try {
+        vectors = await fn(texts)
+      } catch (error) {
+        throw new MemoryError(
+          "ERR_EMBEDDING_DISABLED",
+          `本地 ONNX 推理失败（model=${model}）：${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+      const dim = vectors[0]?.length ?? 0
+      if (dim === 0) {
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `本地 ONNX 返回空向量（model=${model}）`)
+      }
+      // 维度真源：以模型实际输出为准；同一 provider 内必须自洽
+      if (dimension !== 0 && dimension !== dim) {
+        throw new MemoryError("ERR_DIMENSION_MISMATCH", `provider 维度漂移：${dimension} → ${dim}`)
+      }
+      dimension = dim
+      return vectors
+    },
+    health(): Promise<ComponentHealth> {
+      if (embedFn && dimension > 0) {
+        return Promise.resolve({ component: "embedding", status: "ok", detail: `local-onnx model=${model} dim=${dimension}` })
+      }
+      return Promise.resolve({
+        component: "embedding",
+        status: "degraded",
+        detail: `local-onnx 未初始化（model=${model}）；首次 embed 时加载，失败则降级 fts-only`,
+      })
+    },
+  }
+}