add-coder 0.3.33 → 0.3.35

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

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

@@ -0,0 +1,87 @@
+/*
+ * OpenAI 兼容嵌入提供者（Plan §3.4 轮 3 Task 3.1）
+ *
+ * 适用于任意 /v1/embeddings 兼容端点（本地 vLLM / 自建网关 / 官方 API）。
+ * 契约同 local-onnx：维度以首次响应为准（配置项 dimension 仅作期望值校验），
+ * 任何失败收敛为 ERR_EMBEDDING_DISABLED，不阻塞 Gate。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth } from "../retrieval/types.js"
+import type { EmbeddingProvider } from "./index.js"
+
+export interface OpenAiCompatibleOptions {
+  baseUrl: string
+  model: string
+  apiKey?: string
+  /** 期望维度（可选）：与首次响应不一致时报 ERR_DIMENSION_MISMATCH */
+  dimension?: number
+  timeoutMs?: number
+  /** 测试注入 */
+  fetchImpl?: typeof fetch
+}
+
+export function createOpenAiCompatibleEmbeddingProvider(
+  opts: OpenAiCompatibleOptions,
+): EmbeddingProvider {
+  const doFetch = opts.fetchImpl ?? fetch
+  const endpoint = `${opts.baseUrl.replace(/\/+$/, "")}/embeddings`
+  let dimension = opts.dimension ?? 0
+  let lastError: string | null = null
+
+  return {
+    id: "openai-compatible",
+    get dimension(): number {
+      return dimension
+    },
+    async embed(texts: string[]): Promise<number[][]> {
+      if (texts.length === 0) return []
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 15_000)
+      let payload: { data?: { embedding?: number[] }[] }
+      try {
+        const res = await doFetch(endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ model: opts.model, input: texts }),
+          signal: controller.signal,
+        })
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`)
+        }
+        payload = (await res.json()) as { data?: { embedding?: number[] }[] }
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error)
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `兼容端点调用失败（${endpoint}）：${lastError}`)
+      } finally {
+        clearTimeout(timer)
+      }
+
+      const vectors = (payload.data ?? []).map((d) => d.embedding ?? []).filter((v) => v.length > 0)
+      if (vectors.length === 0) {
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `兼容端点未返回向量（model=${opts.model}）`)
+      }
+      const dim = vectors[0].length
+      if (dimension !== 0 && dimension !== dim) {
+        throw new MemoryError("ERR_DIMENSION_MISMATCH", `期望维度 ${dimension}，实收 ${dim}`)
+      }
+      dimension = dim
+      lastError = null
+      return vectors
+    },
+    health(): Promise<ComponentHealth> {
+      if (dimension > 0) {
+        return Promise.resolve({ component: "embedding", status: "ok", detail: `openai-compatible model=${opts.model} dim=${dimension}` })
+      }
+      return Promise.resolve({
+        component: "embedding",
+        status: lastError ? "unavailable" : "degraded",
+        detail: lastError
+          ? `兼容端点不可用：${lastError}`
+          : `兼容端点未调用（model=${opts.model}，endpoint=${endpoint}）`,
+      })
+    },
+  }
+}