add-coder 0.3.25-0 → 0.3.25

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

@@ -3,9 +3,15 @@ import type { ToolRegistrar } from "./registrar.js"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { prisma } from "../shared/prisma.js"
 import { PROJECT_ID, PROJECT_ROOT } from "../shared/env.js"
+import type { AddUserRow, DevOperationRow } from "../shared/db-types.js"
+import { AddUserRowSchema, DevOperationRowSchema, validatedDelegate } from "../shared/db-types.js"
 
 export function registerAuditTools(server: ToolRegistrar) {
 
+  // 无类型边界单点（zod 托管）：动态 client → 运行期校验的泛型委托
+  const devDb = validatedDelegate<DevOperationRow>(prisma.devOperation, DevOperationRowSchema, "DevOperation")
+  const userDb = validatedDelegate<AddUserRow>(prisma.addUser, AddUserRowSchema, "AddUser")
+
   // args 窄化辅助：MCP 工具参数可能是 string | number | undefined，统一转 string
   const s = (v: string | number | undefined): string => (typeof v === "number" ? String(v) : (v ?? ""))
 
@@ -29,8 +35,7 @@ export function registerAuditTools(server: ToolRegistrar) {
       if (targetType) where.targetType = s(targetType); if (action) where.action = s(action); if (targetId) where.targetId = s(targetId); if (planKeyword) where.planKeyword = s(planKeyword)
       const kw = s(keyword)
       if (kw) where.OR = [{ action: { contains: kw, mode: "insensitive" } },{ targetType: { contains: kw, mode: "insensitive" } },{ targetId: { contains: kw, mode: "insensitive" } },{ reason: { contains: kw, mode: "insensitive" } },{ planKeyword: { contains: kw, mode: "insensitive" } }]
-      type AuditLogRow = { createdAt: Date; action: string; targetType: string; targetId: string | null; reason: string | null; planKeyword: string | null }
-      const logs = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).findMany({ where, orderBy: { createdAt: "desc" }, take: Math.min(Number(limit) || 20, 100), include: { user: { select: { username: true } } } }) as unknown as AuditLogRow[]
+      const logs = await devDb.findMany({ where, orderBy: { createdAt: "desc" }, take: Math.min(Number(limit) || 20, 100), include: { user: { select: { username: true } } } })
       if (logs.length === 0) {
         const f: string[] = []; if (targetType) f.push(`targetType=${targetType}`); if (action) f.push(`action=${action}`); if (targetId) f.push(`targetId=${targetId}`); if (planKeyword) f.push(`planKeyword=${planKeyword}`); if (keyword) f.push(`keyword="${keyword}"`); if (sinceMinutes !== undefined) f.push(`sinceMinutes=${sinceMinutes}`)
         return textResponse(`=== 开发操作审计日志 ===\n\n未找到匹配的审计记录（条件: ${f.length > 0 ? f.join(", ") : "无条件"}）。\n\n可能原因: 数据库未运行、尚无相关开发操作记录、或 filter 过于严格。`)
@@ -67,11 +72,9 @@ export function registerAuditTools(server: ToolRegistrar) {
       if (tId && (tId.startsWith("/") || /^[A-Z]:\\/.test(tId))) pathWarnings.push(`⚠️ targetId 使用了绝对路径: "${tId}"。请使用相对路径。`)
       let parsedBefore: unknown, parsedAfter: unknown
       try { if (beforeState) parsedBefore = JSON.parse(s(beforeState)); if (afterState) parsedAfter = JSON.parse(s(afterState)) } catch { return errorResponse("beforeState/afterState 必须是有效的 JSON 字符串。") }
-      type AddUserRow = { id: string }
-      let systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).findUnique({ where: { username: "ai-assistant" }, select: { id: true } }) as unknown as AddUserRow | null
-      if (!systemUser) systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).create({ data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" }, select: { id: true } }) as unknown as AddUserRow
-      type DevLogRow = { id: string; createdAt: Date }
-      const log = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).create({ data: { userId: systemUser.id, planKeyword: s(planKeyword) || "unknown", action: s(action), targetType: s(targetType), targetId: tId || "unknown", beforeState: parsedBefore ?? null, afterState: parsedAfter ?? null, reason: s(reason) || null } }) as unknown as DevLogRow
+      let systemUser = await userDb.findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
+      if (!systemUser) systemUser = await userDb.create({ data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" } })
+      const log = await devDb.create({ data: { userId: systemUser.id, planKeyword: s(planKeyword) || "unknown", action: s(action), targetType: s(targetType), targetId: tId || "unknown", beforeState: parsedBefore ?? null, afterState: parsedAfter ?? null, reason: s(reason) || null } })
       const lines = [`✅ 开发操作已记录`, `  落库项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `  ID: ${log.id}`, `  action: ${s(action)}`, `  targetType: ${s(targetType)}`, `  targetId: ${tId || "unknown"}`, `  planKeyword: ${s(planKeyword) || "unknown"}`, `  createdAt: ${log.createdAt.toISOString()}`]
       if (pathWarnings.length > 0) { lines.push(""); lines.push(...pathWarnings) }
       lines.push("", `📋 落库回查（必须执行）:`, tId ? `  query_audit_logs({ targetId: "${tId}" }) — 确认本条记录已写入` : "")

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

@@ -8,6 +8,9 @@ import { join, relative } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { readFileSafe, readdirRecursive } from "../shared/fs.js"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+import { prisma } from "../shared/prisma.js"
+import type { PlanRow } from "../shared/db-types.js"
+import { PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
 
 export function registerContextTools(server: ToolRegistrar) {
 
@@ -164,6 +167,22 @@ export function registerContextTools(server: ToolRegistrar) {
             } else { parts.push("Specs: ❌ 缺失") }
           }
 
+          parts.push(""); parts.push("=== 悬空 Plan 对账（记录在、文件缺失） ===")
+          // 孤儿可见性：create_hitl 预置行被中断 / 放弃未清理 → 开局即提示，不静默累积
+          try {
+            // 无类型边界单点（zod 托管）：动态 client → 运行期校验的泛型委托
+            const planDb = validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord")
+            const allPlans = await planDb.findMany({ orderBy: { createdAt: "desc" } })
+            const orphans = allPlans.filter(p => !existsSync(p.planPath))
+            if (orphans.length > 0) {
+              const cutoff = Date.now() - 14 * 86400000
+              for (const o of orphans) {
+                const stale = o.createdAt.getTime() < cutoff
+                parts.push(`${stale ? "🔴" : "·"} ${o.planName} → ${o.planPath}${stale ? "（超 14 天，建议清理）" : ""}`)
+              }
+            } else { parts.push("✅ 无悬空记录") }
+          } catch { parts.push("⚠️ 悬空对账跳过（数据库不可达）") }
+
           parts.push(""); parts.push("=== 待执行 ADD 操作（按流程顺序） ===")
           const todoItems: string[] = []
           if (!activePlan) { todoItems.push("1. [未开始] 用户提出需求 → 生成 Plan") }

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

@@ -5,10 +5,12 @@ import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
+import type { CollabContractRow, PlanRow } from "../shared/db-types.js"
+import { CollabContractRowSchema, PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
 
 const db = {
-  get collabContract() { return prisma.collabContract as unknown as Record<string, (...a: unknown[]) => unknown> },
-  get plan() { return prisma.planRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get collabContract() { return validatedDelegate<CollabContractRow>(prisma.collabContract, CollabContractRowSchema, "CollabContract") },
+  get plan() { return validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord") },
 }
 
 /** 契约文档结构化解析结果 */
@@ -122,7 +124,7 @@ export function registerContractTools(server: ToolRegistrar) {
           results.push(`⚠️ ${name}  缺少「总控 Plan:」声明，跳过`)
           continue
         }
-        const existing = await db.collabContract.findFirst({ where: { contractName: name } }) as Record<string, unknown> | null
+        const existing = await db.collabContract.findFirst({ where: { contractName: name } })
         const version = (existing?.version as number ?? 0) + 1
 
         const data = {
@@ -171,7 +173,7 @@ export function registerContractTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { contractName } = args as { contractName: string }
-      const contract = await db.collabContract.findFirst({ where: { contractName } }) as Record<string, unknown> | null
+      const contract = await db.collabContract.findFirst({ where: { contractName } })
       if (!contract) {
         return textResponse(`📋 契约: 未跟踪\ncontractName: ${contractName}\n\n操作: contract_track({ contractName: "${contractName}" })`)
       }

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

@@ -9,7 +9,7 @@
 import * as z from "zod/v4";
 import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
-import { join, basename } from "path";
+import { join } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
 import {
   readFileSafe,
@@ -42,9 +42,7 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         const pm = apf.find(
           (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) &&
-            f.includes("-plan-v") &&
-            !f.includes(".hitl"),
+            f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
@@ -82,71 +80,6 @@ export function registerCheckRahs(server: ToolRegistrar) {
           })) as Array<{ id: string }>;
           auditScore = Math.min(100, logs.length * 10);
         } catch {}
-        // ── 范围保真度 / Spec 合规 / 阶段对称性：从静态基线改为动态计算（修复：
-        //    三个维度原为固定 80，任何 Plan 的 RAHS 上限 88 永远无法通过）──
-        try {
-          const arFile = apf.find(
-            (f) =>
-              f.toLowerCase().includes(pp.toLowerCase()) &&
-              f.toLowerCase().includes("add-route"),
-          );
-          if (arFile) {
-            const arContent =
-              (await readFileSafe(join(plansDir, arFile))) || "";
-            const checks = arContent.match(/^- \[[ x]\]/gm) || [];
-            const done = checks.filter((c) => c.includes("[x]")).length;
-            // 阶段对称性：add-route Step 产出项勾选率（Handoff/Report Closure 等
-            //    条件项未勾选时按比例折算，不阻塞）
-            symScore = checks.length > 0
-              ? Math.max(70, Math.round((done / checks.length) * 100))
-              : 70;
-          }
-        } catch {}
-        try {
-          // Spec 合规：checklist [T] 项勾选率（[R] 运行时项不计入）
-          const specDir = join(PROJECT_ROOT, MAGIC_DIR, "specs");
-          const sn = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
-          const clPath = join(specDir, sn, "checklist.md");
-          if (existsSync(clPath)) {
-            const cl = (await readFileSafe(clPath)) || "";
-            const tItems = cl.match(/^- \[[ x]\] \[T\]/gm) || [];
-            const tDone = tItems.filter((c) => c.includes("[x]")).length;
-            specScore = tItems.length > 0
-              ? Math.max(70, Math.round((tDone / tItems.length) * 100))
-              : 70;
-          }
-        } catch {}
-        try {
-          // 范围保真度：git diff 变更文件与 add-route 附录清单匹配率
-          const arFile = apf.find(
-            (f) =>
-              f.toLowerCase().includes(pp.toLowerCase()) &&
-              f.toLowerCase().includes("add-route"),
-          );
-          if (arFile) {
-            const arContent =
-              (await readFileSafe(join(plansDir, arFile))) || "";
-            const appendix = (
-              arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) ||
-              []
-            ).map((f: string) => f.replace(/`/g, "").toLowerCase());
-            const diff = runCommand("git", ["diff", "--name-only"], {
-              cwd: PROJECT_ROOT,
-              timeout: 5000,
-            });
-            const diffFiles = diff.stdout
-              .trim()
-              .split("\n")
-              .filter(Boolean)
-              .map((f: string) => f.toLowerCase());
-            if (appendix.length > 0 && diffFiles.length > 0) {
-              const matched = diffFiles.filter((f) =>
-                appendix.some((a) => f === a || f.endsWith(`/${a}`)),
-              ).length;
-              scopeScore = Math.max(70, Math.round((matched / diffFiles.length) * 100));
-            }
-          }
-        } catch {}
         const parts = [
           "=== RAHS：Runtime Architecture Health Score ===",
           `Plan 关键词: "${pp}"`,

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

@@ -69,7 +69,7 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
           // 提取 add-route 附录文件清单
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) || [])
+          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json)`/g) || [])
             .map((f: string) => f.replace(/`/g, ""));
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 

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

@@ -2,14 +2,18 @@ import * as z from "zod/v4"
 import { inputRequired, acceptedContent } from "@modelcontextprotocol/server"
 import type { ToolRegistrar } from "./registrar.js"
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs"
-import { join, basename } from "path"
+import { join, basename, relative } from "path"
 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 type { HitlRow, PlanRow } from "../shared/db-types.js"
+import { HitlRowSchema, PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
 
+// 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
 const db = {
-  get hitl() { return prisma.hitlRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get hitl() { return validatedDelegate<HitlRow>(prisma.hitlRecord, HitlRowSchema, "HitlRecord") },
+  get plan() { return validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord") },
 }
 
 export function registerHitlTools(server: ToolRegistrar) {
@@ -22,18 +26,32 @@ export function registerHitlTools(server: ToolRegistrar) {
 
   // genui 模式客户端（如 Qoder）未声明 elicitation capability，弹框必然失败 → 返回 genui 流程引导
   function _genuiGuide(recallStep: string): string {
+    // D2（Review 回流）：widget 模板多候选探测——sync 实际落脚含 core/ 层级，
+    // toml 原值为源仓路径（消费方不存在），逐候选回退，全 miss 显式告警。
+    // 输出必须为 workspace 相对路径：genui show_widget 实测拒绝绝对路径（2026-08-11 验证）。
     let widgetPath = ""
     if (_interaction.widget_path) {
-      // genui show_widget 仅接受 workspace 相对路径，绝对路径会被拒
-      const bakedRel = join(MAGIC_DIR, "templates", basename(_interaction.widget_path))
-      widgetPath = existsSync(join(PROJECT_ROOT, bakedRel)) ? bakedRel : _interaction.widget_path
+      const base = basename(_interaction.widget_path)
+      const candidates = [
+        join(PROJECT_ROOT, MAGIC_DIR, "templates", "core", "templates", base),
+        join(PROJECT_ROOT, MAGIC_DIR, "templates", base),
+        join(PROJECT_ROOT, _interaction.widget_path),
+      ]
+      const abs = candidates.find((p) => existsSync(p)) ?? ""
+      widgetPath = abs ? relative(PROJECT_ROOT, abs) : ""
     }
-    return [
+    const lines = [
       `⚠️ 当前环境（${MAGIC_DIR}）客户端不支持 elicitation 弹框，交互模式已裁决为 genui。请按以下流程完成：`,
-      `1. 调用 genui show_widget 渲染审批表单${widgetPath ? `（widget_path: ${widgetPath}，workspace 相对路径，维度列表经 data 注入）` : ""}`,
-      `2. 用户在 widget 中逐项拍板`,
-      `3. ${recallStep}`,
-    ].join("\n")
+    ]
+    if (widgetPath) {
+      lines.push(`1. 调用 genui show_widget 渲染审批表单（widget_path: ${widgetPath}，workspace 相对路径，维度列表经 data 注入）`)
+    } else {
+      lines.push(`1. ⚠️ widget 模板缺失（hitl-approval-widget.html 未同步到 ${MAGIC_DIR}/templates/），请先执行 add-coder sync 补齐，再走 genui show_widget 流程`)
+      lines.push(`   - 兜底可用 inline widget_code 渲染；数据契约: window.__WIDGET_DATA__ = { planName, type, dimensions: [{name, content}] }`)
+    }
+    lines.push(`2. 用户在 widget 中逐项拍板`)
+    lines.push(`3. ${recallStep}`)
+    return lines.join("\n")
   }
 
   // ═══════════════ 辅助：解析 inputRequired 响应 ═══════════════
@@ -115,6 +133,19 @@ export function registerHitlTools(server: ToolRegistrar) {
     try {
       const { planName, type, dimensions, _fallback, _use_genui } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean }
 
+      // ── planName 入口强校验（弱模型友好：不合规返回可照抄修正调用，而非让错误漂移） ──
+      const _pnValid = /-(plan|collab-contract)-v\d+$/.test(planName)
+        || /-review(-v\d+|-implementation(-v\d+)?|-runtime(-v\d+)?)?$/.test(planName)
+        || planName.endsWith(".hitl")
+      if (!_pnValid) {
+        const suggested = type === "COLLAB_CONTRACT" ? `${planName}-collab-contract-v1` : `${planName}-plan-v1`
+        return errorResponse(
+          `planName 格式不合规: "${planName}"\n` +
+          `要求: 以 -plan-v{n} / -collab-contract-v{n} / -review-* 结尾（哨兵命名依赖此后缀剥离）\n` +
+          `可照抄修正: create_hitl({ planName: "${suggested}", type: "${type}" })`
+        )
+      }
+
       // ── 最终维度内容（从弹框结果合并） ──
       let finalDims: { name: string; content: string }[] = []
 
@@ -210,21 +241,44 @@ export function registerHitlTools(server: ToolRegistrar) {
       }
 
       // ── 原始业务逻辑（创建 DB + 生成 hitl.md。降级模式也走此路） ──
+      const now = new Date()
+      const yyyyMM = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,"0")}`
+      const dd = String(now.getDate()).padStart(2,"0")
+      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans", yyyyMM, dd)
+      const proposalPath = join(plansDir, `${planName}.hitl.md`)
+
+      // ── FK 断环修复：HitlRecord.planName 外键要求 PlanRecord 先行。
+      //    全新 Plan 首次审批时自动预置占位行（约定式 planPath，文件存在性即指纹），
+      //    Plan 文件写出后由 plan_track 回刷真实路径——机器占位机器回刷，不消耗 LLM 认知。
+      //    D5（Review 回流）：占位路径按 type 分流——PLAN_REVIEW 指向 reviews/ 目录，
+      //    review 文档写出后由 review_track/plan_track 回刷消解（避免永久悬空）。 ──
+      let planProvisioned = false
+      const existingPlan = await db.plan.findFirst({ where: { planName } })
+      if (!existingPlan) {
+        const placeholderPath = type === "PLAN_REVIEW"
+          ? join(PROJECT_ROOT, MAGIC_DIR, "reviews", yyyyMM, dd, `${planName}.md`)
+          : join(plansDir, `${planName}.md`)
+        await db.plan.create({
+          data: {
+            planName,
+            planPath: placeholderPath,
+            planKeyword: String(planName).replace(/-(plan|collab-contract|review)-v\d+$/, ""),
+            totalTasks: 0, doneTasks: 0, checklistT: 0, checklistTDone: 0, checklistR: 0,
+          },
+        })
+        planProvisioned = true
+      }
+
       const rows = await db.hitl.findMany({
         where: { planName },
         orderBy: { round: "desc" },
         take: 1,
-      }) as { round: number | null }[]
+      })
       const round = (rows[0]?.round ?? 0) + 1
       const record = await db.hitl.create({
-        data: { planName, round, type, status: "DRAFT" },
-      }) as { id: string }
+        data: { planName, round, type: type as HitlRow["type"], status: "DRAFT" },
+      })
       // 生成 hitl.md
-      const now = new Date()
-      const yyyyMM = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,"0")}`
-      const dd = String(now.getDate()).padStart(2,"0")
-      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans", yyyyMM, dd)
-      const proposalPath = join(plansDir, `${planName}.hitl.md`)
       const isoNow = now.toISOString()
 
       // 动态生成维度表格行
@@ -270,10 +324,18 @@ export function registerHitlTools(server: ToolRegistrar) {
         `recordId: ${record.id}`,
       ]
       if (finalDims.length > 0) lines.push(`dimensions: ${finalDims.length} 项`)
+      if (planProvisioned) lines.push(`PlanRecord: 自动预置（占位行，Plan 文件写出后 plan_track 回刷真实路径）`)
       if (_fallback) lines.push(`mode:     _fallback (跳过 dialog，原始代码降级)`)
       return textResponse(lines.join("\n"))
     } catch (e) {
-      return errorResponse(`create_hitl 失败: ${e instanceof Error ? e.message : String(e)}`)
+      const msg = e instanceof Error ? e.message : String(e)
+      if (msg.includes("Foreign key")) {
+        return errorResponse(
+          `create_hitl 外键异常（PlanRecord 自动预置可能失败）: ${msg}\n` +
+          `处方: 检查数据库连接与 PlanRecord 表结构，或改用 plan_track({ planName }) 先建立追踪记录后重试`
+        )
+      }
+      return errorResponse(`create_hitl 失败: ${msg}`)
     }
   })
 
@@ -296,7 +358,13 @@ export function registerHitlTools(server: ToolRegistrar) {
     }),
   }, async (args: Record<string, unknown>, ctx: Record<string, unknown>) => {
     try {
-      const { planName, type, status, reason, _fallback, _use_genui } = args as Record<string, string | boolean | undefined>
+      const _raw = args as Record<string, string | boolean | undefined>
+      const planName = String(_raw.planName ?? "")
+      const type = String(_raw.type ?? "")
+      const status = typeof _raw.status === "string" ? _raw.status : undefined
+      const reason = typeof _raw.reason === "string" ? _raw.reason : undefined
+      const _fallback = _raw._fallback === true
+      const _use_genui = _raw._use_genui === true
 
       // ── 交互式确认（非降级模式且非 genui 模式） ──
       let effectiveStatus = status as string | undefined
@@ -384,26 +452,38 @@ export function registerHitlTools(server: ToolRegistrar) {
       // 降级模式必须传 status
 
       // ── 原始业务逻辑（更新 DB + 写哨兵文件。降级模式也走此路） ──
-      const s = effectiveStatus!
+      const s = effectiveStatus as HitlRow["status"]
+      const qType = type as HitlRow["type"]
       const rows = await db.hitl.findMany({
-        where: { planName, type },
+        where: { planName, type: qType },
         orderBy: { round: "desc" },
         take: 1,
-      }) as Record<string, unknown>[]
+      })
       if (!rows.length) return errorResponse(`未找到 HITL 记录: planName=${planName}, type=${type}`)
       const r = rows[0]
-      const prevStatus = r.status as string
+      const prevStatus = r.status
       if (prevStatus === "TONGYI" || prevStatus === "BOHUI") {
         return errorResponse(`HITL 已终态（${prevStatus}），不可再更新。BOHUI 后请用 create_hitl 新建 round。`)
       }
       // 更新
-      const data: Record<string, unknown> = { status: s }
+      const data: Partial<HitlRow> = { status: s }
       if (s === "TONGYI") data.approvedAt = new Date()
       if (s === "BOHUI") {
         data.rejectedAt = new Date()
-        if (reason) data.rejectReason = reason
+        if (reason) data.rejectReason = String(reason)
       }
       await db.hitl.update({ where: { id: r.id }, data })
+      // ── BOHUI 清算：Plan 文件不存在 → 预置 PlanRecord 无存续理由，连同本 plan 全部 HitlRecord 删除（孤儿即时归零）。
+      //    已写出文件的驳回 Plan 保留记录（历史价值）。 ──
+      let orphanCleaned = ""
+      if (s === "BOHUI") {
+        const planRow = await db.plan.findFirst({ where: { planName } })
+        if (planRow && !existsSync(planRow.planPath)) {
+          await db.hitl.deleteMany({ where: { planName } })
+          await db.plan.delete({ where: { id: planRow.id } })
+          orphanCleaned = `预置数据已清算（Plan 文件不存在: ${planRow.planPath}）`
+        }
+      }
       // 写哨兵文件（双命名：原始 planName + pre-tool-use hook §C 剥后缀推导名，保持闸门一致）
       const markerDir = join(PROJECT_ROOT, MAGIC_DIR, "hitl")
       mkdirSync(markerDir, { recursive: true })
@@ -440,7 +520,8 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (s === "BOHUI") {
         lines.push(`marker:   ${marker}`)
         lines.push(`reason:   ${reason || "—"}`)
-        lines.push(``, `💡 驳回后请用 create_hitl 新建 round ${Number(r.round) + 1} 重新发起审批。`)
+        if (orphanCleaned) lines.push(`cleanup:  ${orphanCleaned}`)
+        lines.push(``, `💡 驳回后请用 create_hitl 新建 round ${r.round + 1} 重新发起审批。`)
       }
       return textResponse(lines.join("\n"))
     } catch (e) {
@@ -458,11 +539,12 @@ export function registerHitlTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName, type } = args as { planName: string; type?: string }
+      const qType = (type || "PLAN") as HitlRow["type"]
       const rows = await db.hitl.findMany({
-        where: { planName, type },
+        where: { planName, type: qType },
         orderBy: { round: "desc" },
         take: 1,
-      }) as Record<string, unknown>[]
+      })
       if (!rows.length) {
         return textResponse(
           `📋 HITL: 未发起\n` +
@@ -472,7 +554,7 @@ export function registerHitlTools(server: ToolRegistrar) {
         )
       }
       const r = rows[0]
-      const status = r.status as string
+      const status = r.status
       const icons: Record<string, string> = { DRAFT: "⏳", SUBMITTED: "📤", TONGYI: "✅", BOHUI: "❌" }
       const icon = icons[status] || "❓"
       const lines = [
@@ -481,13 +563,13 @@ export function registerHitlTools(server: ToolRegistrar) {
         `planName:   ${planName}`,
         `type:       ${r.type}`,
         `round:      ${r.round}`,
-        r.createdAt ? `createdAt:  ${(r.createdAt as Date).toISOString()}` : null,
-        r.approvedAt ? `approvedAt: ${(r.approvedAt as Date).toISOString()}` : null,
-        r.rejectedAt ? `rejectedAt: ${(r.rejectedAt as Date).toISOString()}` : null,
+        r.createdAt ? `createdAt:  ${r.createdAt.toISOString()}` : null,
+        r.approvedAt ? `approvedAt: ${r.approvedAt.toISOString()}` : null,
+        r.rejectedAt ? `rejectedAt: ${r.rejectedAt.toISOString()}` : null,
         r.rejectReason ? `reason:     ${r.rejectReason}` : null,
       ].filter(Boolean)
       if (status === "BOHUI") {
-        lines.push(``, `💡 驳回后可 create_hitl 新建 round ${Number(r.round) + 1}。`)
+        lines.push(``, `💡 驳回后可 create_hitl 新建 round ${r.round + 1}。`)
       }
       if (status === "DRAFT" || status === "SUBMITTED") {
         lines.push(``, `操作: update_hitl({ planName: "${planName}", type: "${r.type}", status: "TONGYI|BOHUI" })`)

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

@@ -12,61 +12,6 @@ import { registerReviewTools } from "./review.js"
 import { PROJECT_ID } from "../shared/env.js"
 import type { ToolRegistrar } from "./registrar.js"
 
-// ── 读写分级信号量节流（进程层并发契约 v2 §7：Codex Parallel MCP 真并行兑底） ──
-// 读工具共享 8 并发；写工具共享 4 并发；超限请求排队（MCP 协议允许延迟响应，排队即天然反压）
-const READ_MAX = 8
-const WRITE_MAX = 4
-
-const READ_TOOLS = new Set([
-  "get_project_context", "find_related_docs", "get_db_schema", "query_audit_logs",
-  "plan_status", "review_status", "status_hitl", "contract_status",
-  "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",
-])
-
-function createSemaphore(limit: number) {
-  let active = 0
-  const queue: (() => void)[] = []
-  const acquire = () =>
-    new Promise<void>((resolve) => {
-      if (active < limit) {
-        active++
-        resolve()
-      } else {
-        queue.push(resolve)
-      }
-    })
-  const release = () => {
-    active--
-    const next = queue.shift()
-    if (next) {
-      active++
-      next()
-    }
-  }
-  return { acquire, release }
-}
-
-// 429 指数退避重试（3 次，250ms 起步，倍率 2x）：上游限流不直接透传
-async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
-  let lastErr: unknown
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    try {
-      return await fn()
-    } catch (e) {
-      lastErr = e
-      const msg = e instanceof Error ? e.message : String(e)
-      if (!/429|rate.?limit|限流/i.test(msg)) throw e
-      await new Promise((r) => setTimeout(r, 250 * 2 ** (attempt - 1)))
-    }
-  }
-  throw lastErr
-}
-
-const readSem = createSemaphore(READ_MAX)
-const writeSem = createSemaphore(WRITE_MAX)
-
 export function registerAllTools(server: McpServer) {
   // D9 多 MCP 路由安全：派生装饰版 registrar，为所有工具 description 注入项目身份前缀
   const origRegister = server.registerTool.bind(server)
@@ -75,20 +20,10 @@ export function registerAllTools(server: McpServer) {
   type ToolCb = Parameters<RegisterTool>[2]
   const registerTool = ((name: string, config: ToolConfig, cb: ToolCb) => {
     const c = config as { description?: string }
-    // 读写分级节流 + 429 退避（进程层契约 v2：Codex 并行调用兜底）
-    const sem = READ_TOOLS.has(name) ? readSem : writeSem
-    const throttledCb = (async (...args: unknown[]) => {
-      await sem.acquire()
-      try {
-        return await withRetry(async () => cb(...(args as Parameters<ToolCb>)))
-      } finally {
-        sem.release()
-      }
-    }) as ToolCb
     return origRegister(
       name,
       { ...config, description: `[项目: ${PROJECT_ID}] ${c.description ?? ""}` },
-      throttledCb,
+      cb,
     )
   }) as RegisterTool
   const registrar: ToolRegistrar = { registerTool }