add-coder 0.3.33 → 0.3.35

package/templates/core/scripts/mcp-server/tools/gateway/check_rahs.ts

@@ -20,6 +20,14 @@ import {
 import { prisma } from "../../shared/prisma.js";
 import { runCommand } from "../../shared/run-command.js";
 import { getRuntimeContext } from "../../shared/env.js";
+import {
+  buildGateCaptureDetail,
+  createGateWriterDeps,
+  deriveGateRunId,
+  formatGateCaptureSummary,
+  writeGateMetric,
+  GATE_METRIC_TYPE,
+} from "../../shared/memory/metrics/gate-writer.js";
 
 export function registerCheckRahs(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext();
@@ -50,6 +58,8 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
+        // Plan 正文在多个维度（Spec 引用解析、采证 seed）共用，提到此处只读一次
+        const planContent = (await readFileSafe(join(plansDir, pm))) || "";
         let scopeScore = 80,
           typeScore = 80,
           auditScore = 80,
@@ -115,7 +125,6 @@ export function registerCheckRahs(server: ToolRegistrar) {
           const rahsCandidates = rahsVersionSuffix
             ? [`${rahsPlanBase}-${rahsVersionSuffix}`, rahsPlanBase]
             : [rahsPlanBase];
-          const planContent = (await readFileSafe(join(plansDir, pm))) || "";
           const rahsSpecRef = planContent.match(/specs\/([^/`\s]+)/);
           if (rahsSpecRef) rahsCandidates.push(rahsSpecRef[1]);
           const sn =
@@ -181,6 +190,36 @@ export function registerCheckRahs(server: ToolRegistrar) {
           `=== RAHS = ${rahs}  ${rahs >= 90 ? "🟢 PASS" : rahs >= 70 ? "🟡 WARN" : "🔴 BLOCKED"} ===`,
         );
         if (rahs < 70) parts.push("  动作: 注意力漂移严重，返工回退");
+
+        // ── Gate 采证（Spec §GateMetric）：与评分解耦，失败旁路不阻塞返回 ──
+        const rahsSeed = `${planContent}\n${scopeScore}|${typeScore}|${auditScore}|${specScore}|${symScore}`;
+        const rahsCaptureInput = {
+          gate: "check_rahs" as const,
+          planKeyword: pp,
+          runId: deriveGateRunId("check_rahs", pp, rahsSeed),
+          metricType: GATE_METRIC_TYPE.check_rahs,
+          score: rahs,
+          repository: runtimeContext.projectKey,
+          dimensionScores: {
+            scope: scopeScore,
+            type: typeScore,
+            audit: auditScore,
+            spec: specScore,
+            symmetry: symScore,
+          },
+          baseline: 90,
+          unit: "score",
+        };
+        const rahsCapture = await writeGateMetric(
+          rahsCaptureInput,
+          createGateWriterDeps((prisma as Record<string, unknown>).addMetricSnapshot),
+        );
+        parts.push(
+          "",
+          "=== Gate 采证（MetricSnapshot）===",
+          `  ${formatGateCaptureSummary(buildGateCaptureDetail(rahsCaptureInput, rahsCapture))}`,
+        );
+
         return textResponse(parts.join("\n"));
       } catch (e) {
         return errorResponse(

package/templates/core/scripts/mcp-server/tools/gateway/check_spec_sync.ts

@@ -76,8 +76,8 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
         } else {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
-          // 提取 add-route 附录文件清单（toml 纳入：sync-magic-rules.toml 等控制面文件，2026-08-18 修复）
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml|toml)`/g) || [])
+          // 提取 add-route 附录文件清单
+          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) || [])
             .map((f: string) => f.replace(/`/g, ""));
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 

package/templates/core/scripts/mcp-server/tools/hitl.ts

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import { inputRequired, acceptedContent } from "@modelcontextprotocol/server"
+import { inputRequired, acceptedContent, type ElicitInputParams } from "@modelcontextprotocol/server"
 import type { ToolRegistrar } from "./registrar.js"
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs"
 import { join, basename, relative } from "path"
@@ -7,6 +7,7 @@ import { textResponse, errorResponse } from "../shared/response.js"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
 import { HITL_INTERACTION_CONFIG } from "../shared/hitl-interaction.strategy.js"
+import { shouldSkipHitlCreateDialog } from "../shared/hitl-create-policy.js"
 import type { HitlRow } from "../shared/db-types.js"
 import { HitlRowSchema, validatedDelegate } from "../shared/db-types.js"
 import { getRuntimeContext } from "../shared/env.js"
@@ -18,6 +19,10 @@ import {
   createHitlProposalAndPublish,
   type HitlProposalDatabase,
 } from "../shared/hitl-proposal-mutation.js"
+import {
+  buildHitlProposalMarkdown,
+  applyHitlDecisionToProposal,
+} from "../shared/hitl-proposal-content.js"
 import { HITL_APPROVAL_WIDGET_URI } from "../shared/hitl-ui.js"
 
 // 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
@@ -25,6 +30,23 @@ const db = {
   get hitl() { return validatedDelegate<HitlRow>(prisma.hitlRecord, HitlRowSchema, "HitlRecord") },
 }
 
+/**
+ * 表单式 elicitation 的 `requestedSchema`（2026-09-14：替换 4 处 `as any`）。
+ *
+ * 为什么需要一个函数：属性表是**运行时按维度动态构造**的（`dim_0_content`/`dim_0_decision`…），
+ * 而 SDK 的 `ElicitInputParams["requestedSchema"]` 是静态 JSON Schema 形状 —— 字面量直接赋值
+ * 会因索引签名不匹配而报错。这里把**唯一的窄化点**收在一处，类型取自 SDK 而非 `any`。
+ */
+/** 表单里单个属性的形状（本仓库只用字符串型 + 可选枚举） */
+type ElicitFormProperty = { type: "string"; enum?: string[]; description?: string }
+
+function elicitFormSchema(
+  properties: Record<string, ElicitFormProperty>,
+  required: string[],
+): ElicitInputParams["requestedSchema"] {
+  return { type: "object", properties, required } as ElicitInputParams["requestedSchema"]
+}
+
 export function registerHitlTools(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext()
 
@@ -123,9 +145,15 @@ export function registerHitlTools(server: ToolRegistrar) {
     filePath: string,
     status: HitlRow["status"],
     dimensions?: { name: string; content?: string }[],
+    reason?: string,
   ): void {
     let proposal = readFileSync(filePath, "utf-8")
-    proposal = proposal.replace(/(状态:\s*)[A-Z_]+/, `$1${status}`)
+    // 状态行 + 「审批结论」行（2026-09-14：原实现只改状态行，裁决结论不回写文档）
+    proposal = applyHitlDecisionToProposal(proposal, {
+      status,
+      at: new Date().toISOString(),
+      reason,
+    })
 
     if (dimensions?.length) {
       const byName = new Map(dimensions.map((d) => [d.name.trim(), d.content ?? ""]))
@@ -187,16 +215,60 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (!dimensions.length) {
         return errorResponse(`HITL 提案缺少可渲染维度: ${proposalPath ?? planName}`)
       }
+      // 产物-进程新鲜度（覆盖全 adapter；判定不确定 → "unknown"，不误报"需重启"）
+      const { computeFreshness } = await import("../shared/runtime-freshness.js")
+      const { writeHitlInstanceHtml } = await import("../shared/hitl-widget-instance.js")
+      const stale = computeFreshness(MAGIC_DIR, PROJECT_ROOT)
+      // 确定性降级入口：markdown 提案 + 已落盘实例 HTML（无 UI 能力/进程陈旧时仍可完成审批）
+      const toRel = (abs: string): string => abs.replace(`${PROJECT_ROOT}/`, "")
+      const markdownPath = proposalPath ? toRel(proposalPath) : ""
+      let htmlPath = ""
+      try {
+        htmlPath = toRel(
+          writeHitlInstanceHtml({
+            projectRoot: PROJECT_ROOT,
+            magicDir: MAGIC_DIR,
+            planName,
+            type,
+            round: current.round,
+            status: current.status,
+            dimensions,
+          }).htmlPath,
+        )
+      } catch {
+        htmlPath = "" // 模板缺失等 → 仍保留 markdown 降级路径（fail-open）
+      }
       const output = {
         planName,
         type,
         round: current.round,
         status: current.status,
         dimensions,
+        stale,
+        // 服务端无法得知客户端是否真的渲染了 widget —— 如实标注 unknown，不谎报
+        ui: { resourceUri: HITL_APPROVAL_WIDGET_URI, rendered: "unknown" as const },
+        fallback: { markdownPath, htmlPath },
       }
+      const fallbackHint = markdownPath || htmlPath
+      const text =
+        stale.stale === true
+          ? `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。⚠️ 当前 server 进程早于产物更新（需重启）；widget 若未显示，降级入口：${fallbackHint}`
+          : `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。widget 若未显示，降级入口：${fallbackHint}`
       return {
-        content: [{ type: "text" as const, text: `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。请在 widget 中拍板。` }],
+        content: [{ type: "text" as const, text }],
         structuredContent: output,
+        /*
+         * 结果侧 `_meta`（Apps SDK 兼容补位，2026-09-14）：
+         * 宿主实际读的是**工具定义**的 `_meta.ui.resourceUri`（`tools/list` 时解析，
+         * 实测 `thread_items` 里已带 `mcpAppResourceUri`，而 `result._meta` 仍为 null 也照常绑定）；
+         * 这里补一份结果侧 `_meta` 不改变行为，只为兼容同时读结果位的客户端。
+         * 真正的渲染前提是：客户端 MCP Apps 能力开关（Codex: `/experimental` 的 enable_mcp_apps）
+         * + 资源 mimeType 为 `text/html;profile=mcp-app` + 资源存在 + dimensions 非空。
+         */
+        _meta: {
+          ui: { resourceUri: HITL_APPROVAL_WIDGET_URI },
+          "openai/outputTemplate": HITL_APPROVAL_WIDGET_URI,
+        },
       }
     } catch (e) {
       return errorResponse(`render_hitl_approval 失败: ${e instanceof Error ? e.message : String(e)}`)
@@ -208,9 +280,11 @@ export function registerHitlTools(server: ToolRegistrar) {
     description: "HITL 审批：创建提案。写入 HitlRecord（status=DRAFT，自动递增 round），并生成 hitl.md 提案文件供人工审核。\n" +
       "交互模式按安装环境自动裁决（caijuehub: hitl-interaction-rules.toml）：\n" +
       "- genui 模式环境（如 Qoder，客户端未声明 elicitation capability）：MUST 直接走 genui 流程——先用 genui show_widget 渲染逐项决策表单，用户拍板后以 _use_genui=true + 最终 dimensions 调用本工具。不带模式参数调用会返回 genui 引导而非弹框。\n" +
+      "- MCP Apps 模式环境（如 Codex）：MUST NOT 展开高维 inputRequired——创建阶段直接落 DRAFT，审批走 render_hitl_approval 打开的 core widget（其回调以 update_hitl(_use_widget=true) 落库）。不带模式参数时按环境自动走该路径；也可用 _mcp_apps=true 强制。\n" +
       "- 支持 elicitation 的客户端（2026-07-28+ 协议）：inputRequired 弹框，含逐项决策（LLM 传 dimensions）或简单弹框两种模式。\n" +
       "降级模式（_fallback=true）：genui 与弹框均不可用时兜底，跳过弹框直接以传入的 dimensions 创建，人工审核 hitl.md。\n" +
       "_use_genui=true：genui widget 回调后使用，跳过所有弹框，直接以传入的 dimensions 创建 DB+文件。\n" +
+      "_mcp_apps=true：强制 MCP Apps 流程（落 DRAFT 不弹框，审批走 core widget）。\n" +
       "planName 示例: add-coder-hitl-mcp-hook-plan-v1\n" +
       "type: PLAN=计划审批, PLAN_REVIEW=方案评审",
     inputSchema: z.object({
@@ -222,10 +296,11 @@ export function registerHitlTools(server: ToolRegistrar) {
       })).optional().describe("决策维度列表（LLM 根据对话生成）。不传则按模板默认 8 维度"),
       _fallback: z.boolean().optional().default(false).describe("降级模式：跳过 inputRequired，按原始代码行为直接创建 DB 记录+hitl.md"),
       _use_genui: z.boolean().optional().default(false).describe("genui 模式：genui widget 回调后使用，跳过所有弹框直接创建（dimensions 需传最终确认值）"),
+      _mcp_apps: z.boolean().optional().default(false).describe("Codex MCP Apps 强制模式：落 DRAFT 不弹 inputRequired，审批走 render_hitl_approval core widget（update_hitl(_use_widget=true)）"),
     }),
   }, async (args: Record<string, unknown>, ctx: Record<string, unknown>) => {
     try {
-      const { planName, type, dimensions, _fallback, _use_genui } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean }
+      const { planName, type, dimensions, _fallback, _use_genui, _mcp_apps } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean; _mcp_apps?: boolean }
 
       // ── planName 入口强校验（弱模型友好：不合规返回可照抄修正调用，而非让错误漂移） ──
       const _pnValid = /-(plan|collab-contract)-v\d+$/.test(planName)
@@ -243,13 +318,14 @@ export function registerHitlTools(server: ToolRegistrar) {
       // ── 最终维度内容（从弹框结果合并） ──
       let finalDims: { name: string; content: string }[] = []
 
-      // ── genui/降级模式：无弹框环节，直接采用传入的 dimensions（降级丢维度会退化成默认空模板） ──
-      if (_use_genui || _fallback) {
+      // ── genui/降级/mcpApps 模式：无弹框环节，直接采用传入的 dimensions（降级丢维度会退化成默认空模板） ──
+      const skipDialog = shouldSkipHitlCreateDialog(_interaction.mode, { fallback: _fallback, useGenui: _use_genui, mcpApps: _mcp_apps })
+      if (skipDialog) {
         finalDims = (dimensions || []).map(d => ({ name: d.name, content: d.content || "" }))
       }
 
       // ── 交互式确认（非降级模式且非 genui 模式） ──
-      if (!_fallback && !_use_genui) {
+      if (!skipDialog) {
         // 环境裁决：genui 模式下不发起注定失败的 elicitation，引导 LLM 走 widget 流程
         if (_interaction.mode === "genui") {
           const dimDesc = (dimensions || []).map((d, i) => `${i + 1}. ${d.name}: ${d.content || ""}`).join("\n")
@@ -266,7 +342,7 @@ export function registerHitlTools(server: ToolRegistrar) {
 
           if (!decResp) {
             // 首次调用 — 构建扁平逐项弹框
-            const props: Record<string, unknown> = {
+            const props: Record<string, ElicitFormProperty> = {
               globalAction: {
                 type: "string", enum: ["", "同意全部", "驳回全部"],
                 description: "同意全部=通过所有(含已调整行); 驳回全部=驳回提案; 留空=逐项"
@@ -290,7 +366,7 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `确认创建 HITL 提案\n\nplan: ${planName}\ntype: ${type}\n\n共 ${dimensions.length} 个决策维度：\n${dimDesc}`,
-                  requestedSchema: { type: "object", properties: props, required: requiredKeys } as any
+                  requestedSchema: elicitFormSchema(props, requiredKeys),
                 })
               }
             })
@@ -322,7 +398,10 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `确认创建 HITL 提案？\n\nplan: ${planName}\ntype: ${type}`,
-                  requestedSchema: { type: "object", properties: { action: { type: "string", enum: ["同意", "取消"], description: "同意=确认创建提案, 取消=取消操作" } }, required: ["action"] } as any
+                  requestedSchema: elicitFormSchema(
+                    { action: { type: "string", enum: ["同意", "取消"], description: "同意=确认创建提案, 取消=取消操作" } },
+                    ["action"],
+                  ),
                 })
               }
             })
@@ -361,34 +440,14 @@ export function registerHitlTools(server: ToolRegistrar) {
       // 生成 hitl.md
       const isoNow = now.toISOString()
 
-      // 动态生成维度表格行
-      const tableRows = finalDims.length > 0
-        ? finalDims.map((d, i) => `| ${i + 1} | ${d.name} | ${d.content} | 同意/驳回 |`).join("\n")
-        : [
-            "| 1 | 实施主体 | | 同意/驳回 |",
-            "| 2 | 数据模型 | | 同意/驳回 |",
-            "| 3 | MCP 工具 | | 同意/驳回 |",
-            "| 4 | 文件命名 | | 同意/驳回 |",
-            "| 5 | 模板 + schema | | 同意/驳回 |",
-            "| 6 | 新增依赖 | | 同意/驳回 |",
-            "| 7 | 预计文件数 | | 同意/驳回 |",
-            "| 8 | 预计轮次 | | 同意/驳回 |",
-          ].join("\n")
-
-      const tpl = [
-        `# ${planName} — HITL 提案 (round ${round})`,
-        "",
-        `> 创建: ${isoNow}  |  类型: ${type}  |  状态: DRAFT`,
-        "",
-        "## HITL 计划总览",
-        "",
-        "请填写以下决策维度，人工审核后点击 update_hitl 弹框选择「同意/驳回」完成审批：",
-        "",
-        "| # | 维度 | 方案内容 | 决策 |",
-        "|---|------|----------|:----:|",
-        tableRows,
-        "",
-      ].join("\n")
+      // 生成提案文档（真源 hitl-template.md：HITL 计划总览 + 审批结论 两章节齐备）
+      const tpl = buildHitlProposalMarkdown({
+        planName: String(planName),
+        round,
+        type: String(type),
+        createdAt: isoNow,
+        dimensions: finalDims,
+      })
       mkdirSync(plansDir, { recursive: true })
       writeFileSync(proposalPath, tpl, "utf-8")
 
@@ -406,6 +465,10 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (finalDims.length > 0) lines.push(`dimensions: ${finalDims.length} 项`)
       if (proposal.planProvisioned) lines.push(`PlanRecord: 自动预置（占位行，Plan 文件写出后 plan_track 回刷真实路径）`)
       if (_fallback) lines.push(`mode:     _fallback (跳过 dialog，原始代码降级)`)
+      if ((_interaction.mode === "mcpApps" || _mcp_apps) && !_fallback) {
+        lines.push(`mode:     mcpApps (Codex：不展开 inputRequired${_mcp_apps ? "，_mcp_apps 显式强制" : ""})`)
+        lines.push(``, `➡️ 下一步：调用 render_hitl_approval({ planName: "${planName}", type: "${type}" }) 打开审批 widget，由用户拍板。`)
+      }
       return textResponse(lines.join("\n"))
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
@@ -489,7 +552,7 @@ export function registerHitlTools(server: ToolRegistrar) {
           const decResp = _parseDecisions(ctx)
 
           if (!decResp) {
-            const props: Record<string, unknown> = {
+            const props: Record<string, ElicitFormProperty> = {
               globalAction: {
                 type: "string", enum: ["", "同意全部", "驳回全部"],
                 description: "同意全部=通过所有维度; 驳回全部=驳回提案; 留空=逐项"
@@ -512,7 +575,7 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `HITL 审批决策\n\nplan: ${planName}\ntype: ${type}\n\n逐项决策以下 ${dims.length} 个维度：\n${dimDesc}`,
-                  requestedSchema: { type: "object", properties: props, required: requiredKeys } as any
+                  requestedSchema: elicitFormSchema(props, requiredKeys),
                 })
               }
             })
@@ -536,7 +599,10 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `HITL 审批决策\n\nplan: ${planName}\ntype: ${type}`,
-                  requestedSchema: { type: "object", properties: { action: { type: "string", enum: ["同意", "驳回", "取消"], description: "同意=通过审批, 驳回=驳回重做, 取消=暂不操作" } }, required: ["action"] } as any
+                  requestedSchema: elicitFormSchema(
+                    { action: { type: "string", enum: ["同意", "驳回", "取消"], description: "同意=通过审批, 驳回=驳回重做, 取消=暂不操作" } },
+                    ["action"],
+                  ),
                 })
               }
             })
@@ -585,7 +651,7 @@ export function registerHitlTools(server: ToolRegistrar) {
       // P3 #6：回写 .hitl.md 提案文件状态（DRAFT → TONGYI/BOHUI），保证双通道校验一致
       const proposalPath = findHitlFile(String(planName))
       if (proposalPath) {
-        updateHitlProposal(proposalPath, s, (_use_widget || _use_genui) ? dimensions : undefined)
+        updateHitlProposal(proposalPath, s, (_use_widget || _use_genui) ? dimensions : undefined, reason)
       }
       // 响应
       const lines = [

package/templates/core/scripts/mcp-server/tools/index.ts

@@ -9,6 +9,8 @@ import { registerHookEventTools } from "./hook-event-report.js"
 import { registerHitlTools } from "./hitl.js"
 import { registerPlanTools } from "./plan.js"
 import { registerReviewTools } from "./review.js"
+import { registerMemoryTools } from "./memory.js"
+import { registerMemoryCompatTools } from "./memory-compat.js"
 import { PROJECT_ID } from "../shared/env.js"
 import type { ToolRegistrar } from "./registrar.js"
 
@@ -24,6 +26,8 @@ const READ_TOOLS = new Set([
   "check_dps", "check_rahs", "check_add_route_status", "check_spec_sync",
   "check_add_route_completeness", "check_phase_symmetry", "check_failure_path",
   "check_add_compliance", "get_hook_events",
+  "recall_memory", "get_memory", "list_memories", "review_memory", "get_memory_health",
+  "search_memory", "read_memory", "memory_stats",
 ])
 
 function createSemaphore(limit: number) {
@@ -104,5 +108,7 @@ export function registerAllTools(server: McpServer) {
   registerHitlTools(registrar)       // 4 tools: create_hitl / update_hitl / status_hitl / render_hitl_approval
   registerPlanTools(registrar)       // 3 tools: plan_track / plan_status / plan_sync
   registerReviewTools(registrar)     // 3 tools: review_track / review_status / review_sync
-  // Total: 30 tools
+  registerMemoryTools(registrar)     // 8 tools: propose_memory / recall_memory / get_memory / list_memories / review_memory / resolve_memory / feedback_memory / get_memory_health
+  registerMemoryCompatTools(registrar) // 6 tools: 5 个 v1 弃用门面（append_memory/search_memory/read_memory/link_memory/memory_stats）+ forget_memory（合规清除）
+  // Total: 44 tools
 }

package/templates/core/scripts/mcp-server/tools/memory-compat.ts

@@ -0,0 +1,258 @@
+/*
+ * Memory 兼容面与合规清除（Plan §3.4 轮 2 / Spec §4 §CompatAndPurge）
+ *
+ * 两部分：
+ *  A. v1 shim —— 5 个旧工具名注册为**弃用门面**：正常受理调用、把参数映射到 v2 语义、
+ *     返回 `deprecated: true` + 目标工具 + 迁移指引，不重复实现 v2 逻辑（避免与 memory.ts 双源漂移）。
+ *     ⚠️ 溯源声明：v1 工具名在仓库内**零命中**（CHANGELOG / docs / 五个 magic 目录均无），
+ *     名字集合按 Plan §3.4 的「append/search/read/link/stats」字面构造。真实 v1 名单若不同，
+ *     只需改下方 SHIM_TABLE 一行。
+ *     执行转发（真正跑 v2 逻辑）需要把 memory.ts 的操作层抽成共享 ops 模块，按轮次边界
+ *     （memory.ts 仅轮 3 装配）不在本轮改动，已登记为待补项。
+ *  B. forget_memory —— 合规清除：物理删除记忆行，并清理三类外键占用（证据关联 / 召回记录 /
+ *     被 supersede 指向），最后写 AuditLog 留痕（ADD-5：不落库的清除视为未发生）。
+ *     普通废弃仍走状态机（resolve_memory 的 archive/reject/supersede），不物理删除。
+ */
+import * as z from "zod/v4"
+import type { ToolRegistrar } from "./registrar.js"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { prisma } from "../shared/prisma.js"
+import { getRuntimeContext } from "../shared/env.js"
+import {
+  validatedDelegate,
+  AddMemoryRowSchema,
+  AddMemoryEvidenceLinkRowSchema,
+  AddMemoryRecallItemRowSchema,
+  AuditLogRowSchema,
+  AddUserRowSchema,
+  type AddMemoryRow,
+  type AddMemoryEvidenceLinkRow,
+  type AddMemoryRecallItemRow,
+  type AuditLogRow,
+  type AddUserRow,
+  type TableDelegate,
+} from "../shared/db-types.js"
+import { MemoryError, isMemoryError } from "../shared/memory/domain/errors.js"
+
+/** v1 → v2 映射表（表驱动：真实名单变化时只改这里） */
+export interface ShimEntry {
+  v1: string
+  mappedTo: string
+  note: string
+}
+
+export const SHIM_TABLE: readonly ShimEntry[] = [
+  { v1: "append_memory", mappedTo: "propose_memory", note: "候选写入语义：落 CANDIDATE，绝不直接 ACTIVE" },
+  { v1: "search_memory", mappedTo: "recall_memory", note: "受治理混合召回：RRF 融合 + 治理重排 + token 预算，返回 degradedMode" },
+  { v1: "read_memory", mappedTo: "get_memory", note: "单条详情 + 证据链 + supersession 链" },
+  { v1: "link_memory", mappedTo: "get_memory", note: "关联改由证据链承载（AddMemoryEvidenceLink），无独立链接工具" },
+  { v1: "memory_stats", mappedTo: "get_memory_health", note: "backlog / leakage / provider / FTS 健康度" },
+] as const
+
+/** 弃用响应体（纯函数，便于测试） */
+export function buildShimPayload(v1: string, args: Record<string, unknown>) {
+  const entry = SHIM_TABLE.find((s) => s.v1 === v1)
+  return {
+    deprecated: true,
+    v1,
+    mappedTo: entry?.mappedTo ?? null,
+    mappedArgs: args,
+    note: entry?.note ?? null,
+    executed: false,
+    hint: entry
+      ? `v1 工具 ${v1} 已弃用：请改用 ${entry.mappedTo}（参数同上表映射）。`
+      : `未知的 v1 工具名 ${v1}。`,
+  }
+}
+
+export type PurgeReason = "secret" | "privacy" | "compliance"
+
+export interface PurgeResult {
+  deleted: true
+  memoryId: string
+  reason: PurgeReason
+  ftsCleared: true
+  vectorCleared: boolean
+  clearedLinks: number
+  clearedRecallItems: number
+  clearedSupersedePointers: number
+  auditId: string
+}
+
+export interface PurgeDeps {
+  /** 目标仓库（= 运行时 projectKey，越库直接拒绝） */
+  repositoryRef: string
+  context: { projectKey: string; adapterKey: string; contextId: string }
+  memoryDb: Pick<TableDelegate<AddMemoryRow>, "findUnique" | "delete" | "updateMany">
+  linkDb: Pick<TableDelegate<AddMemoryEvidenceLinkRow>, "deleteMany">
+  recallItemDb: Pick<TableDelegate<AddMemoryRecallItemRow>, "deleteMany">
+  auditDb: Pick<TableDelegate<AuditLogRow>, "create">
+  ensureUserId: () => Promise<string>
+}
+
+/**
+ * 合规清除（物理删除）。仅限 secret / privacy / compliance 三类原因；
+ * FTS 索引随行删除自动维护（PG GIN 索引与 SQLite FTS5 触发器均为行级同步），故 ftsCleared 恒为 true；
+ * 向量列由 embeddingState 决定：首版 provider=none → 无向量可清（vectorCleared=false）。
+ */
+export async function purgeMemory(
+  deps: PurgeDeps,
+  input: { memoryId: string; repositoryRef: string; reason: PurgeReason; actor?: string },
+): Promise<PurgeResult> {
+  if (input.repositoryRef !== deps.context.projectKey) {
+    throw new MemoryError("ERR_REPOSITORY_MISMATCH", `越库清除被拒绝：${input.repositoryRef}`)
+  }
+  const row = await deps.memoryDb.findUnique({ where: { id: input.memoryId } })
+  if (!row) throw new MemoryError("ERR_NOT_FOUND", `memoryId=${input.memoryId}`)
+  if (row.repositoryRef !== deps.context.projectKey) {
+    throw new MemoryError("ERR_REPOSITORY_MISMATCH", `memoryId=${input.memoryId} 属于 ${row.repositoryRef}`)
+  }
+
+  // 外键占用清理顺序：证据关联 → 召回记录 → 被指向的 supersede 指针 → 行本身
+  const links = await deps.linkDb.deleteMany({ where: { memoryId: row.id } })
+  const recItems = await deps.recallItemDb.deleteMany({ where: { memoryId: row.id } })
+  const pointers = await deps.memoryDb.updateMany({
+    where: { supersededById: row.id },
+    data: { supersededById: null },
+  })
+
+  const vectorCleared = String(row.embeddingState ?? "DISABLED") !== "DISABLED"
+  const userId = await deps.ensureUserId()
+  const log = await deps.auditDb.create({
+    data: {
+      userId,
+      projectKey: deps.context.projectKey,
+      producerAdapterKey: deps.context.adapterKey,
+      contextId: deps.context.contextId,
+      action: "MEMORY_PURGE",
+      targetType: "AddMemory",
+      targetId: row.id,
+      beforeState: {
+        status: row.status,
+        kind: row.kind,
+        topic: row.topic,
+        contentHash: row.contentHash,
+        scopeType: row.scopeType,
+        scopeValue: row.scopeValue,
+        embeddingState: row.embeddingState ?? null,
+        evidenceLinks: links.count ?? 0,
+        recallItems: recItems.count ?? 0,
+        supersedePointers: pointers.count ?? 0,
+      },
+      afterState: {
+        deleted: true,
+        ftsCleared: true,
+        vectorCleared,
+        reason: input.reason,
+        actor: input.actor ?? null,
+      },
+      reason: input.reason,
+    },
+  })
+
+  await deps.memoryDb.delete({ where: { id: row.id } })
+
+  return {
+    deleted: true,
+    memoryId: row.id,
+    reason: input.reason,
+    ftsCleared: true,
+    vectorCleared,
+    clearedLinks: links.count ?? 0,
+    clearedRecallItems: recItems.count ?? 0,
+    clearedSupersedePointers: pointers.count ?? 0,
+    auditId: log.id,
+  }
+}
+
+export function registerMemoryCompatTools(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext()
+
+  const memoryDb = validatedDelegate<AddMemoryRow>(prisma.addMemory, AddMemoryRowSchema, "AddMemory")
+  const linkDb = validatedDelegate<AddMemoryEvidenceLinkRow>(
+    prisma.addMemoryEvidenceLink, AddMemoryEvidenceLinkRowSchema, "AddMemoryEvidenceLink",
+  )
+  const recallItemDb = validatedDelegate<AddMemoryRecallItemRow>(
+    prisma.addMemoryRecallItem, AddMemoryRecallItemRowSchema, "AddMemoryRecallItem",
+  )
+  const auditDb = validatedDelegate<AuditLogRow>(prisma.auditLog, AuditLogRowSchema, "AuditLog")
+  const userDb = validatedDelegate<AddUserRow>(prisma.addUser, AddUserRowSchema, "AddUser")
+
+  function fail(e: unknown) {
+    if (isMemoryError(e)) return errorResponse(e.message)
+    return errorResponse(`ERR_INTERNAL: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  async function ensureSystemUser(): Promise<string> {
+    let u = await userDb.findUnique({ where: { username: "ai-assistant" } })
+    if (!u) {
+      u = await userDb.create({
+        data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" },
+      })
+    }
+    return u.id
+  }
+
+  // ===== A. v1 shim（5 个弃用门面） =====
+  for (const entry of SHIM_TABLE) {
+    server.registerTool(
+      entry.v1,
+      {
+        description: `[已弃用] v1 兼容门面 → 请改用 ${entry.mappedTo}。${entry.note}`,
+        inputSchema: z.looseObject({}),
+      },
+      (args: Record<string, unknown>) => {
+        try {
+          return Promise.resolve(textResponse(JSON.stringify(buildShimPayload(entry.v1, args))))
+        } catch (e) {
+          return Promise.resolve(fail(e))
+        }
+      },
+    )
+  }
+
+  // ===== B. forget_memory（合规清除，非 shim：v2 新增运维工具） =====
+  server.registerTool(
+    "forget_memory",
+    {
+      description:
+        "合规清除（物理删除 + 清证据/召回/supersede 占用 + AuditLog 留痕）。仅限 reason=secret|privacy|compliance；" +
+        "普通废弃请用 resolve_memory 的 archive/reject/supersede（状态机，不物理删除）。必须显式 confirm=true。",
+      inputSchema: z.object({
+        repositoryRef: z.string().describe("仓库标识（必须等于运行时 projectKey）"),
+        memoryId: z.string(),
+        reason: z.enum(["secret", "privacy", "compliance"]).describe("清除原因（决定审计口径）"),
+        actor: z.string().optional().describe("操作者标识"),
+        confirm: z.boolean().describe("必须为 true：物理删除不可恢复"),
+      }),
+    },
+    async (args: Record<string, unknown>, _ctx: unknown) => {
+      try {
+        if (args.confirm !== true) {
+          return errorResponse("ERR_INVARIANT: 物理清除必须显式 confirm=true")
+        }
+        const result = await purgeMemory(
+          {
+            repositoryRef: runtimeContext.projectKey,
+            context: {
+              projectKey: runtimeContext.projectKey,
+              adapterKey: runtimeContext.adapterKey,
+              contextId: runtimeContext.contextId,
+            },
+            memoryDb, linkDb, recallItemDb, auditDb,
+            ensureUserId: ensureSystemUser,
+          },
+          {
+            memoryId: args.memoryId as string,
+            repositoryRef: args.repositoryRef as string,
+            reason: args.reason as PurgeReason,
+            actor: args.actor as string | undefined,
+          },
+        )
+        return textResponse(JSON.stringify(result))
+      } catch (e) {
+        return fail(e)
+      }
+    },
+  )
+}