add-coder 0.3.33 → 0.3.35

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

@@ -138,6 +138,118 @@ export const CollabContractRowSchema = z.looseObject({
   updatedAt: z.date(),
 })
 
+// ===== Agent Memory 行 schema（对齐 prisma/add.prisma，Plan: add-coder-agent-memory-plan-v2） =====
+
+export const MemoryKindSchema = z.enum([
+  "DECISION", "CONSTRAINT", "PITFALL", "FAILURE", "LESSON",
+  "PATTERN", "CONVENTION", "FACT", "HANDOFF_DIGEST", "HYPOTHESIS",
+])
+export const MemoryStatusSchema = z.enum([
+  "CANDIDATE", "PENDING", "ACTIVE", "STALE", "SUPERSEDED", "REJECTED", "ARCHIVED",
+])
+export const MemoryScopeTypeSchema = z.enum([
+  "ORGANIZATION", "REPOSITORY", "BRANCH", "MODULE", "PATH", "SYMBOL", "PLAN", "SPEC",
+])
+export const MemorySourceTypeSchema = z.enum([
+  "PLAN", "SPEC", "DPS_GATE", "DEV_OPERATION", "RAHS_GATE", "HANDOFF", "MANUAL", "IMPORT",
+])
+export const EmbeddingStateSchema = z.enum(["DISABLED", "PENDING", "READY", "FAILED", "STALE"])
+export const RecallOutcomeSchema = z.enum([
+  "UNKNOWN", "USED", "USEFUL", "IRRELEVANT", "OUTDATED", "CONTRADICTED", "HARMFUL",
+])
+
+export const AddMemoryRowSchema = z.looseObject({
+  id: z.string(),
+  kind: MemoryKindSchema,
+  status: MemoryStatusSchema,
+  topic: z.string(),
+  content: z.string(),
+  summary: z.string().nullable(),
+  scopeType: MemoryScopeTypeSchema,
+  scopeValue: z.string(),
+  repositoryRef: z.string(),
+  importance: z.number(),
+  confidence: z.number(),
+  validFrom: z.date(),
+  validUntil: z.date().nullable(),
+  supersededById: z.string().nullable(),
+  contentHash: z.string(),
+  embeddingModel: z.string().nullable(),
+  embeddingDim: z.number().nullable(),
+  embeddingState: EmbeddingStateSchema,
+  createdBy: z.string().nullable(),
+  approvedBy: z.string().nullable(),
+  approvedAt: z.date().nullable(),
+  metadata: z.unknown().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const AddMemoryEvidenceRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  sourceType: MemorySourceTypeSchema,
+  sourceRef: z.string(),
+  planKeyword: z.string().nullable(),
+  excerpt: z.string(),
+  contentHash: z.string(),
+  occurredAt: z.date().nullable(),
+  metadata: z.unknown().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMemoryEvidenceLinkRowSchema = z.looseObject({
+  memoryId: z.string(),
+  evidenceId: z.string(),
+  relation: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMetricSnapshotRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  metricType: z.string(),
+  value: z.number(),
+  baseline: z.number().nullable(),
+  delta: z.number().nullable(),
+  unit: z.string().nullable(),
+  planKeyword: z.string().nullable(),
+  specRef: z.string().nullable(),
+  commitSha: z.string().nullable(),
+  sourceRef: z.string(),
+  metadata: z.unknown().nullable(),
+  measuredAt: z.date(),
+})
+
+export const AddMemoryRecallRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  query: z.string(),
+  stage: z.string(),
+  consumerRef: z.string().nullable(),
+  scopeContext: z.unknown(),
+  candidateIds: z.unknown(),
+  selectedIds: z.unknown(),
+  scoreBreakdown: z.unknown(),
+  exclusionReasons: z.unknown().nullable(),
+  rankingVersion: z.string(),
+  tokenBudget: z.number(),
+  injectedTokens: z.number(),
+  latencyMs: z.number().nullable(),
+  degradedMode: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMemoryRecallItemRowSchema = z.looseObject({
+  recallId: z.string(),
+  memoryId: z.string(),
+  selected: z.boolean(),
+  rank: z.number().nullable(),
+  outcome: RecallOutcomeSchema,
+  feedback: z.string().nullable(),
+  updatedAt: z.date(),
+})
+
 // ===== 类型派生（单一真源：schema → 类型） =====
 
 export type PlanRow = z.infer<typeof PlanRowSchema>
@@ -147,6 +259,12 @@ export type AuditLogRow = z.infer<typeof AuditLogRowSchema>
 export type DevOperationRow = z.infer<typeof DevOperationRowSchema>
 export type AddUserRow = z.infer<typeof AddUserRowSchema>
 export type CollabContractRow = z.infer<typeof CollabContractRowSchema>
+export type AddMemoryRow = z.infer<typeof AddMemoryRowSchema>
+export type AddMemoryEvidenceRow = z.infer<typeof AddMemoryEvidenceRowSchema>
+export type AddMemoryEvidenceLinkRow = z.infer<typeof AddMemoryEvidenceLinkRowSchema>
+export type AddMetricSnapshotRow = z.infer<typeof AddMetricSnapshotRowSchema>
+export type AddMemoryRecallRow = z.infer<typeof AddMemoryRecallRowSchema>
+export type AddMemoryRecallItemRow = z.infer<typeof AddMemoryRecallItemRowSchema>
 
 // ===== 查询参数（Prisma 最常用子集，结构化约束 + 运算符支持） =====
 
@@ -159,6 +277,7 @@ export interface QueryArgs<T> {
   orderBy?: { [K in keyof T]?: OrderDirection }
   take?: number
   skip?: number
+  cursor?: Record<string, unknown>
   include?: Record<string, unknown>
 }
 

package/templates/core/scripts/mcp-server/shared/hitl-create-policy.ts

@@ -0,0 +1,27 @@
+/*
+ * create_hitl 的交互裁决（手写模块；**不要放进 hitl-interaction.strategy.ts**——
+ * 那是 `hitl-interaction-rules.toml` 的生成产物，任何手写逻辑都会被 generate 覆盖）。
+ *
+ * 背景（2026-09-14 修复 Codex 空转）：
+ * 客户端按安装环境裁决交互方式：Qoder=genui、Codex=mcpApps、其余=inputRequired。
+ * `update_hitl` 早已有 `mcpApps` 分支（引导走 core widget），但 `create_hitl` **漏了这一支**，
+ * 于是 Codex 下走 elicitation 弹框 → 客户端不展示 → 一直"还在要输入" →
+ * 连续 8 轮后以 `inputRequired.maxRounds` 失败（实测报 `still required input after 8 rounds`）。
+ */
+
+/**
+ * create_hitl 是否需要跳过"创建确认弹框"：
+ * - `_fallback` / `_use_genui`：调用方显式声明的无弹框路径（既有语义）；
+ * - **`mcpApps`（Codex）**：审批交互在 core widget（`render_hitl_approval`）里完成，
+ *   此处直接产出 DRAFT 提案，再由 widget 供用户拍板。
+ */
+export function shouldSkipHitlCreateDialog(
+  mode: string, // 运行期取 toml 裁决值，收窄到 string 边界
+  flags: { fallback?: boolean; useGenui?: boolean; mcpApps?: boolean } = {},
+): boolean {
+  /*
+   * `_mcp_apps` 显式开关（2026-09-14 自 farm-agent 回灌）：环境裁决之外再给调用方一个强制入口——
+   * 适配其它客户端/build、或需要确定性地走 widget 流程时不必依赖 toml 探测结果。
+   */
+  return Boolean(flags.useGenui || flags.fallback || flags.mcpApps) || mode === "mcpApps"
+}

package/templates/core/scripts/mcp-server/shared/hitl-proposal-content.ts

@@ -0,0 +1,110 @@
+/*
+ * HITL 提案文档内容（生成 + 裁决回写）
+ *
+ * 为什么抽出来（2026-09-14 修复"生成器不满足自身 schema"）：
+ * `create_hitl` 原先把 markdown 直接内联在工具体里拼字符串，产物**缺 `## 审批结论`**，
+ * 而真源 `templates/core/templates/hitl-template.md` 与 `hitl-template.schema.json`
+ * 都把它列为必需章节；同时 `update_hitl` 只改状态行与维度列，**裁决结论不回写文档**——
+ * 结果 6/6 `*.hitl.md` 不满足自身 schema，"文件通道"残缺（结论只在 DB 与哨兵里）。
+ * 抽成纯函数后：生成物可用同一校验层直接断言（tests/hitl-proposal-content.test.ts）。
+ */
+
+/** 真源模板中的必需章节名（改这里必须同时改 hitl-template.md / .schema.json） */
+export const HITL_VERDICT_HEADING = "## 审批结论"
+
+export interface HitlDimension {
+  name: string
+  content?: string
+}
+
+export interface BuildHitlProposalInput {
+  planName: string
+  round: number
+  type: string
+  createdAt: string
+  dimensions?: HitlDimension[]
+}
+
+const escapeCell = (value: string) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>")
+
+/** 生成 HITL 提案 markdown（与 `hitl-template.md` 章节对齐） */
+export function buildHitlProposalMarkdown(input: BuildHitlProposalInput): string {
+  const dims = input.dimensions ?? []
+  const tableRows = dims.length > 0
+    ? dims.map((d, i) => `| ${i + 1} | ${d.name} | ${escapeCell(d.content ?? "")} | 同意/驳回 |`).join("\n")
+    : [
+        "| 1 | 实施主体 | | 同意/驳回 |",
+        "| 2 | 数据模型 | | 同意/驳回 |",
+        "| 3 | MCP 工具 | | 同意/驳回 |",
+        "| 4 | 文件命名 | | 同意/驳回 |",
+        "| 5 | 模板 + schema | | 同意/驳回 |",
+        "| 6 | 新增依赖 | | 同意/驳回 |",
+        "| 7 | 预计文件数 | | 同意/驳回 |",
+        "| 8 | 预计轮次 | | 同意/驳回 |",
+      ].join("\n")
+
+  return [
+    `# ${input.planName} — HITL 提案 (round ${input.round})`,
+    "",
+    `> 创建: ${input.createdAt}  |  类型: ${input.type}  |  状态: DRAFT`,
+    "",
+    "## HITL 计划总览",
+    "",
+    "请填写以下决策维度，人工审核后点击 update_hitl 弹框选择「同意/驳回」完成审批：",
+    "",
+    "| # | 维度 | 方案内容 | 决策 |",
+    "|---|------|----------|:----:|",
+    tableRows,
+    "",
+    HITL_VERDICT_HEADING,
+    "",
+    "> **tongyi**：方案通过。",
+    "> **bohui**：方案驳回，需修正后重新 create_hitl 发起下一轮。",
+    "",
+    "| 时间 | 决策 | 原因 |",
+    "|------|:----:|------|",
+    "| | | |",
+    "",
+  ].join("\n")
+}
+
+export interface HitlVerdict {
+  status: string
+  at: string
+  reason?: string
+}
+
+/** 结论表骨架（DRAFT 状态下为空白行；与 buildHitlProposalMarkdown 产出同形） */
+export const HITL_VERDICT_TABLE = [
+  "| 时间 | 决策 | 原因 |",
+  "|------|:----:|------|",
+] as const
+
+/** 保证「审批结论」章节存在（历史产物/旧生成器产物补骨架，不改动已有结论行） */
+export function ensureHitlVerdictSection(content: string): string {
+  if (content.includes(HITL_VERDICT_HEADING)) return content
+  return content.trimEnd() + "\n\n" + [HITL_VERDICT_HEADING, "", ...HITL_VERDICT_TABLE, "| | | |", ""].join("\n")
+}
+
+/**
+ * 把裁决回写进提案：刷新状态行 + 在「审批结论」表写入（或覆盖）一行。
+ * 幂等：同一提案重复调用只保留最后一行，不追加重复行。
+ */
+export function applyHitlDecisionToProposal(content: string, verdict: HitlVerdict): string {
+  const withStatus = ensureHitlVerdictSection(content).replace(/(状态:\s*)[A-Z_]+/, `$1${verdict.status}`)
+  const row = `| ${verdict.at} | ${verdict.status} | ${escapeCell(verdict.reason ?? "")} |`
+  const idx = withStatus.indexOf(HITL_VERDICT_HEADING)
+  const freshSection = [HITL_VERDICT_HEADING, "", "| 时间 | 决策 | 原因 |", "|------|:----:|------|", row, ""].join("\n")
+  if (idx < 0) {
+    // 历史产物（生成器修复前）没有该章节 → 补章节再写行，保证"文件通道"完整
+    return withStatus.trimEnd() + "\n\n" + freshSection
+  }
+  const lines = withStatus.slice(idx).split("\n")
+  const headerIdx = lines.findIndex((l) => l.startsWith("| 时间 |"))
+  if (headerIdx < 0) return withStatus.slice(0, idx) + freshSection
+  // 保留到分隔行，替换全部数据行；其后非表格内容（如追加说明）原样保留
+  const kept = lines.slice(headerIdx + 2).filter((l) => !l.trim().startsWith("|"))
+  while (kept.length > 0 && kept[0].trim() === "") kept.shift()
+  const head = withStatus.slice(0, idx) // 标题/元信息/维度表等「审批结论」之前的内容
+  return head + [...lines.slice(0, headerIdx + 2), row, ...(kept.length > 0 ? ["", ...kept] : [])].join("\n")
+}

package/templates/core/scripts/mcp-server/shared/hitl-widget-instance.ts

@@ -0,0 +1,85 @@
+/*
+ * HITL 审批实例 HTML（Plan hitl-widget-runtime-gap §WidgetInstance / §RenderFallback）
+ *
+ * 为什么需要：MCP Apps 类客户端（Codex）才渲染 widget；其余环境（Qoder/弹框/无 UI）下
+ * 审批必须仍有确定性入口。本模块把 core widget 模板 + 本次提案的维度数据落成一份**可直接打开**的
+ * 实例 HTML（文件面板/浏览器均可），并把路径回给调用方（render_hitl_approval 的 fallback）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+export const HITL_INSTANCE_DIR = "hitl"
+
+export interface HitlInstanceInput {
+  planName: string
+  type: string
+  round: number
+  status: string
+  dimensions: { name: string; content: string }[]
+  templateHtml: string
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}
+
+/** 生成实例 HTML：在模板 </body> 前注入 JSON 载荷 + 人类可读维度表（模板无占位符，故用注入而非替换） */
+export function buildHitlInstanceHtml(input: HitlInstanceInput): string {
+  const payload = {
+    planName: input.planName,
+    type: input.type,
+    round: input.round,
+    status: input.status,
+    dimensions: input.dimensions,
+  }
+  const rows = input.dimensions
+    .map(
+      (d, i) =>
+        `<tr><td>${i + 1}</td><td>${escapeHtml(d.name)}</td><td>${escapeHtml(d.content)}</td><td>同意 / 驳回</td></tr>`,
+    )
+    .join("")
+  const injected = [
+    `<script id="hitl-instance-payload" type="application/json">${JSON.stringify(payload).replace(/</g, "\\u003c")}</script>`,
+    `<section id="hitl-fallback-panel" data-plan="${escapeHtml(input.planName)}" data-round="${input.round}">`,
+    `<h2>HITL 审批（${escapeHtml(input.planName)} · ${escapeHtml(input.type)} round ${input.round}）</h2>`,
+    `<p>状态：${escapeHtml(input.status)} · 共 ${input.dimensions.length} 个维度。逐项确认后，把裁决结果告知 AI 即可落库（本页面为只读降级入口，不直接改库）。</p>`,
+    `<table><thead><tr><th>#</th><th>维度</th><th>方案内容</th><th>决策</th></tr></thead><tbody>${rows}</tbody></table>`,
+    `</section>`,
+  ].join("\n")
+
+  const bodyClose = input.templateHtml.match(/<\/body>/i)
+  if (bodyClose && bodyClose.index !== undefined) {
+    return (
+      input.templateHtml.slice(0, bodyClose.index) + injected + "\n" + input.templateHtml.slice(bodyClose.index)
+    )
+  }
+  return `${input.templateHtml}\n${injected}\n`
+}
+
+export interface WriteHitlInstanceResult {
+  htmlPath: string
+  created: boolean
+}
+
+/**
+ * 落盘实例 HTML（幂等：同 plan+round 覆盖写）。
+ * 模板缺失 → 抛明确错误（禁止静默返回空 HTML）。
+ */
+export function writeHitlInstanceHtml(
+  input: Omit<HitlInstanceInput, "templateHtml"> & { projectRoot: string; magicDir: string },
+): WriteHitlInstanceResult {
+  const templatePath = join(input.projectRoot, input.magicDir, "templates", "hitl-approval-widget.html")
+  if (!existsSync(templatePath)) {
+    throw new Error(`HITL widget 模板缺失: ${templatePath}（请执行 add-coder sync）`)
+  }
+  const dir = join(input.projectRoot, input.magicDir, HITL_INSTANCE_DIR)
+  mkdirSync(dir, { recursive: true })
+  const htmlPath = join(dir, `${input.planName}-round${input.round}.html`)
+  const html = buildHitlInstanceHtml({ ...input, templateHtml: readFileSync(templatePath, "utf-8") })
+  writeFileSync(htmlPath, html, "utf-8")
+  return { htmlPath, created: true }
+}

package/templates/core/scripts/mcp-server/shared/memory/calibration/batch-fit.ts

@@ -0,0 +1,250 @@
+/*
+ * 冷启动批量拟合（Plan rank-calibration Task 2.1 / Spec §2 §BatchFit）
+ *
+ * 三工具分工里"**从无到有**"的那一件：给定一批带 ground truth 的样本 → 输出一个**点估计**权重。
+ * 不做在线跟踪（那是 Kalman），不做频谱诊断（那是 FFT）。
+ *
+ * 两个关键约束：
+ *  1. **train/test 切分**：标注集派生的样本必须按 query 维度切分，拟合只用 train，
+ *     验收只在 test —— 用验收集拟合会虚高 MRR（Spec §2 [2026-09-13 修订]）；
+ *  2. **目标函数可注入**：本模块默认用内置代理目标（按通道位次加权的命中率），
+ *     真实校准由 `rank-calibrate.ts` 注入"跑 recallPipeline + 算 MRR"的目标函数。
+ *     这样模块保持纯函数可测，而线上用真指标而非代理指标。
+ */
+import { createHash } from "node:crypto"
+import type { FeedbackChannel } from "./feedback-stats.js"
+
+export const DEFAULT_MIN_SAMPLES = 5
+
+/** 现行排序常数（无快照时的回落值 = 改造前行为，必须保持一致） */
+export const DEFAULT_WEIGHTS_V3 = {
+  vectorWeight: 0.3,
+  boostScale: 1,
+  rrfK: 10,
+} as const
+
+export interface FitWeights {
+  vectorWeight: number
+  boostScale: number
+  rrfK: number
+}
+
+/** 一条样本：query 归属 + ground truth + 各通道位次 */
+export interface FitSample {
+  queryId: string
+  memoryId: string
+  relevant: boolean
+  /** 该条在各通道中的位次（未命中该通道则不出现） */
+  ranks: Partial<Record<FeedbackChannel, number>>
+}
+
+export interface FitSplit {
+  splitId: string
+  trainQueries: string[]
+  testQueries: string[]
+}
+
+export interface WeightFitResult {
+  weights: FitWeights
+  /** 1 − 目标函数最优值（目标函数应返回 0..1 的归一化收益） */
+  residual: number
+  samples: number
+  trainSamples: number
+  testSamples: number
+  method: "default" | "grid"
+  splitId: string
+  /** 最优解落在搜索空间边界（提示空间可能过窄） */
+  boundaryHit: boolean
+}
+
+export interface SearchSpace {
+  vectorWeight: number[]
+  boostScale: number[]
+  rrfK: number[]
+}
+
+export const DEFAULT_SEARCH_SPACE: SearchSpace = {
+  vectorWeight: [0, 0.1, 0.2, 0.3, 0.5, 0.8],
+  boostScale: [0.5, 1, 2],
+  rrfK: [5, 10, 20, 60],
+}
+
+/** 目标函数：返回 0..1 的归一化收益（越大越好），由调用方决定是代理指标还是真实 MRR */
+export type FitObjective = (weights: FitWeights, samples: readonly FitSample[]) => number
+
+/**
+ * 切分分组 = **Plan 业务闭包**（架构事实，非算法聚类）。
+ * 见 Spec §2.2：单元素自身迭代（单元内）与跨单元流转（跨单元）是两条不同数据流，
+ * 用临时聚类代替 Plan 闭包会让"防泄漏"退化成口径游戏。
+ */
+export interface QueryGroup {
+  /** = planKeyword（业务闭包标识） */
+  groupId: string
+  queryIds: string[]
+  /** 单元状态：未收敛单元的样本默认不进训练集（Spec §2.2） */
+  unitState?: "closed" | "in-flight"
+}
+
+export interface GroupFold {
+  testGroupId: string
+  trainGroups: string[]
+  testQueries: string[]
+  trainQueries: string[]
+}
+
+export interface GroupedSplit {
+  mode: "leave-one-group-out" | "single-holdout"
+  folds: GroupFold[]
+  splitId: string
+  /** 簇数 < 3 → 结论不稳（明示，不隐瞒） */
+  lowGroupCount: boolean
+}
+
+function hashId(input: string): string {
+  return createHash("sha256").update(input).digest("hex").slice(0, 8)
+}
+
+/**
+ * 按 query 维度确定性切分（同输入 → 同 split，可复现）。
+ * 切分单位是 **query** 而非样本：同一 query 的样本不能跨集，否则信息泄漏。
+ */
+export function splitByQuery(queryIds: readonly string[], opts: { testRatio?: number } = {}): FitSplit {
+  const testRatio = opts.testRatio ?? 0.4
+  const unique = [...new Set(queryIds)]
+  // 以 queryId 哈希排序 → 与传入顺序无关，可复现
+  const ordered = [...unique].sort((a, b) => hashId(a).localeCompare(hashId(b)))
+  const testCount = Math.max(1, Math.round(ordered.length * testRatio))
+  const testQueries = ordered.slice(0, Math.min(testCount, Math.max(0, ordered.length - 1)))
+  const testSet = new Set(testQueries)
+  const trainQueries = ordered.filter((q) => !testSet.has(q))
+  return {
+    splitId: hashId(`split|${ordered.join(",")}|${testRatio}`),
+    trainQueries,
+    testQueries,
+  }
+}
+
+/**
+ * 按**业务闭包**切分（Spec §2.1/§2.2）。
+ *
+ * - 默认 `leave-one-group-out`：逐簇留出作 test、其余作 train（每折的 test query 一条都不在 train 中）
+ * - `single-holdout`：按簇哈希确定性挑 test 簇（用于簇数不足时的退化路径）
+ * - 未收敛单元（`unitState:"in-flight"`）参与分组但**默认不进训练集**，避免把"进行中的偏差"学进权重
+ */
+export function splitByGroup(
+  groups: readonly QueryGroup[],
+  opts: { mode?: "leave-one-group-out" | "single-holdout"; testRatio?: number; includeInFlight?: boolean } = {},
+): GroupedSplit {
+  const usable = groups.filter((g) => opts.includeInFlight === true || (g.unitState ?? "closed") === "closed")
+  const all = usable.length > 0 ? usable : groups
+  const mode = opts.mode ?? "leave-one-group-out"
+  const splitId = hashId(`groupsplit|${mode}|${all.map((g) => g.groupId).sort().join(",")}`)
+  const lowGroupCount = all.length < 3
+
+  if (mode === "single-holdout") {
+    const testRatio = opts.testRatio ?? 0.4
+    const ordered = [...all].sort((a, b) => hashId(a.groupId).localeCompare(hashId(b.groupId)))
+    const testCount = Math.max(1, Math.min(ordered.length - 1, Math.round(ordered.length * testRatio)))
+    const testGroups = ordered.slice(0, Math.max(0, testCount))
+    const trainGroups = ordered.slice(testGroups.length)
+    return {
+      mode,
+      splitId,
+      lowGroupCount,
+      folds: [
+        {
+          testGroupId: testGroups.map((g) => g.groupId).join("+"),
+          trainGroups: trainGroups.map((g) => g.groupId),
+          testQueries: testGroups.flatMap((g) => g.queryIds),
+          trainQueries: trainGroups.flatMap((g) => g.queryIds),
+        },
+      ],
+    }
+  }
+
+  return {
+    mode,
+    splitId,
+    lowGroupCount,
+    folds: all.map((test) => ({
+      testGroupId: test.groupId,
+      trainGroups: all.filter((g) => g.groupId !== test.groupId).map((g) => g.groupId),
+      testQueries: [...test.queryIds],
+      trainQueries: all.filter((g) => g.groupId !== test.groupId).flatMap((g) => g.queryIds),
+    })),
+  }
+}
+
+/** 内置代理目标：按通道位次加权命中率（AA 于 recall 的粗略替代，仅用于无注入场景与测试） */
+export function surrogateObjective(weights: FitWeights, samples: readonly FitSample[]): number {
+  if (samples.length === 0) return 0
+  let good = 0
+  let total = 0
+  for (const s of samples) {
+    const lexical = s.ranks.lexical != null ? (1 - weights.vectorWeight) / (weights.rrfK + s.ranks.lexical) : 0
+    const vector = s.ranks.vector != null ? weights.vectorWeight / (weights.rrfK + s.ranks.vector) : 0
+    const score = lexical + vector
+    total += 1
+    if (s.relevant && score > 0) good += 1
+    else if (!s.relevant && score === 0) good += 1
+  }
+  return total === 0 ? 0 : Number((good / total).toFixed(6))
+}
+
+export function fitWeights(
+  samples: readonly FitSample[],
+  split: FitSplit,
+  opts: { minSamples?: number; space?: SearchSpace; objective?: FitObjective } = {},
+): WeightFitResult {
+  const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES
+  const trainSet = new Set(split.trainQueries)
+  const testSet = new Set(split.testQueries)
+  const train = samples.filter((s) => trainSet.has(s.queryId))
+  const test = samples.filter((s) => testSet.has(s.queryId))
+
+  const base = {
+    samples: samples.length,
+    trainSamples: train.length,
+    testSamples: test.length,
+    splitId: split.splitId,
+  }
+
+  // 冷启动门控：样本不足 → 回落现行常数，且**不产出"拟合结果"**
+  if (train.length < minSamples) {
+    return { ...base, weights: { ...DEFAULT_WEIGHTS_V3 }, residual: 1, method: "default", boundaryHit: false }
+  }
+
+  const space = opts.space ?? DEFAULT_SEARCH_SPACE
+  const objective = opts.objective ?? surrogateObjective
+  let best: FitWeights = { ...DEFAULT_WEIGHTS_V3 }
+  let bestScore = -Infinity
+  let hit = false
+
+  for (const vectorWeight of space.vectorWeight) {
+    for (const boostScale of space.boostScale) {
+      for (const rrfK of space.rrfK) {
+        const weights: FitWeights = { vectorWeight, boostScale, rrfK }
+        const score = objective(weights, train)
+        if (score > bestScore) {
+          bestScore = score
+          best = weights
+          hit =
+            vectorWeight === space.vectorWeight[0] ||
+            vectorWeight === space.vectorWeight[space.vectorWeight.length - 1] ||
+            boostScale === space.boostScale[0] ||
+            boostScale === space.boostScale[space.boostScale.length - 1] ||
+            rrfK === space.rrfK[0] ||
+            rrfK === space.rrfK[space.rrfK.length - 1]
+        }
+      }
+    }
+  }
+
+  return {
+    ...base,
+    weights: best,
+    residual: Number((1 - Math.max(0, Math.min(1, bestScore))).toFixed(6)),
+    method: "grid",
+    boundaryHit: hit,
+  }
+}