add-coder 0.3.25-0 → 0.3.26

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

@@ -0,0 +1,208 @@
+/*
+ * 数据层结构化类型（MCP server）— zod 托管版（D1）
+ *
+ * 背景：shared/prisma.ts 运行时动态 require 生成的 Prisma client（模板会被复制到任意
+ * 消费方项目，不能静态依赖特定生成类型）——加载点的「无类型」不可避免。
+ *
+ * 本文件职责（边界从「盲信 cast」升级为「运行期验证」）：
+ * 1. zod schema 为单一真源：行类型一律 z.infer 派生（编译期约束不丢）
+ * 2. validatedDelegate 包装 findFirst/findMany/create/update/delete：
+ *    DB 返回行过 schema.parse —— 消费方迁移滞后/schema 漂移时**立即显式报错**，
+ *    而非让 undefined 字段静默漂移到下游
+ * 3. z.looseObject 前瞻兼容（zod v4 替代已弃用的 .passthrough()）：add.prisma 未来加列不误伤旧模板
+ * 4. parse 失败出处方式报错（弱模型可执行），不裸抛 zod issue 堆栈
+ *
+ * 契约：schema 须与 prisma/add.prisma 模型对齐（字段名/可空性）。
+ */
+import * as z from "zod/v4"
+
+// ===== 行 schema（对齐 prisma/add.prisma；looseObject 前瞻兼容） =====
+
+export const PlanRowSchema = z.looseObject({
+  id: z.string(),
+  planName: z.string(),
+  planPath: z.string(),
+  planKeyword: z.string().nullable(),
+  specPath: z.string().nullable(),
+  tasksPath: z.string().nullable(),
+  checklistPath: z.string().nullable(),
+  addRoutePath: z.string().nullable(),
+  totalTasks: z.number(),
+  doneTasks: z.number(),
+  checklistT: z.number(),
+  checklistTDone: z.number(),
+  checklistR: z.number(),
+  dpsStructScore: z.number().nullable(),
+  dpsSemScore: z.number().nullable(),
+  dpsEntropyScore: z.number().nullable(),
+  dpsCpmScore: z.number().nullable(),
+  dpsComposite: z.number().nullable(),
+  contractRole: z.string().nullable(),
+  contractName: z.string().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const HitlRowSchema = z.looseObject({
+  id: z.string(),
+  planName: z.string(),
+  round: z.number(),
+  type: z.enum(["PLAN", "PLAN_REVIEW", "COLLAB_CONTRACT"]),
+  status: z.enum(["DRAFT", "SUBMITTED", "TONGYI", "BOHUI"]),
+  approvedAt: z.date().nullable(),
+  rejectedAt: z.date().nullable(),
+  rejectReason: z.string().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const ReviewRowSchema = z.looseObject({
+  id: z.string(),
+  planName: z.string(),
+  type: z.enum(["PLAN_REVIEW", "IMPLEMENTATION", "RUNTIME"]),
+  reviewPath: z.string().nullable(),
+  p0Count: z.number(),
+  p1Count: z.number(),
+  backflowRate: z.number(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const AuditLogRowSchema = z.looseObject({
+  id: z.string(),
+  action: z.string(),
+  targetType: z.string(),
+  targetId: z.string(),
+  beforeState: z.unknown().nullable(),
+  afterState: z.unknown().nullable(),
+  reason: z.string().nullable(),
+  planKeyword: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+export const DevOperationRowSchema = z.looseObject({
+  id: z.string(),
+  userId: z.string(),
+  planKeyword: z.string(),
+  action: z.string(),
+  targetType: z.string(),
+  targetId: z.string(),
+  beforeState: z.unknown().nullable(),
+  afterState: z.unknown().nullable(),
+  reason: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+// AddUser 仅消费 id（select { id } 场景），username/email 宽容可空
+// （避免 select 裁剪导致必填字段缺失误伤——机器占位机器回刷原则）
+export const AddUserRowSchema = z.looseObject({
+  id: z.string(),
+  username: z.string().optional(),
+  email: z.string().nullable().optional(),
+})
+
+export const CollabContractRowSchema = z.looseObject({
+  id: z.string(),
+  contractName: z.string(),
+  contractPath: z.string(),
+  masterPlanName: z.string(),
+  participants: z.unknown(),
+  abilityMatrix: z.unknown().nullable(),
+  stages: z.unknown(),
+  dependencyGraph: z.string().nullable(),
+  fileBoundaries: z.unknown(),
+  completionCriteria: z.unknown().nullable(),
+  status: z.string(),
+  version: z.number(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+// ===== 类型派生（单一真源：schema → 类型） =====
+
+export type PlanRow = z.infer<typeof PlanRowSchema>
+export type HitlRow = z.infer<typeof HitlRowSchema>
+export type ReviewRow = z.infer<typeof ReviewRowSchema>
+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>
+
+// ===== 查询参数（Prisma 最常用子集，结构化约束 + 运算符支持） =====
+
+export type OrderDirection = "asc" | "desc"
+
+// where 放开为 Record<string, unknown>：Prisma 运算符（contains/gte/OR 等）
+// 动态组合，键名约束会阻碍合法查询（如 review.ts 的 contains、audit.ts 的 OR）
+export interface QueryArgs<T> {
+  where?: Record<string, unknown>
+  orderBy?: { [K in keyof T]?: OrderDirection }
+  take?: number
+  skip?: number
+  include?: Record<string, unknown>
+}
+
+export interface BatchResult { count: number }
+
+// ===== 泛型委托接口：业务层唯一依赖的数据访问契约 =====
+
+export interface TableDelegate<T> {
+  findFirst(args: Pick<QueryArgs<T>, "where" | "orderBy">): Promise<T | null>
+  findMany(args?: QueryArgs<T>): Promise<T[]>
+  findUnique(args: { where: Record<string, unknown>; select?: Record<string, unknown> }): Promise<T | null>
+  create(args: { data: Partial<T> }): Promise<T>
+  update(args: { where: Partial<T>; data: Partial<T> }): Promise<T>
+  updateMany(args: { where: Record<string, unknown>; data: Partial<T> }): Promise<BatchResult>
+  delete(args: { where: Partial<T> }): Promise<T>
+  deleteMany(args: { where: Partial<T> }): Promise<BatchResult>
+}
+
+// ===== 边界升级：validating delegate（无类型收敛单点 + 运行期行校验） =====
+
+/**
+ * 把动态加载的无类型 delegate 包装为**运行期校验**的泛型委托。
+ * - 读路径（findFirst/findMany）与写返回值（create/update/delete）过 schema.parse
+ * - parse 失败 → 可读处方报错（表名 + 首个问题 + 迁移指引），不裸抛 zod 堆栈
+ * - deleteMany 仅返回计数，无行结构可校验，直通
+ */
+export function validatedDelegate<T>(
+  rawDelegate: unknown,
+  rowSchema: z.ZodType<T>,
+  tableName: string,
+): TableDelegate<T> {
+  const raw = rawDelegate as TableDelegate<unknown>
+
+  const parseRow = (row: unknown): T => {
+    const result = rowSchema.safeParse(row)
+    if (!result.success) {
+      const issue = result.error.issues[0]
+      const field = issue?.path?.join(".") || "(未知字段)"
+      throw new Error(
+        `DB 行结构与预期不符（表 ${tableName}）: ${field} — ${issue?.message ?? "校验失败"}\n` +
+        `处方: 检查项目是否已迁移至最新 prisma/add.prisma（bash scripts/db-ensure.sh），或核对 db-types.ts schema 与 add.prisma 是否同步`
+      )
+    }
+    return result.data
+  }
+
+  return {
+    async findFirst(args) {
+      const row = await raw.findFirst(args as never)
+      return row === null ? null : parseRow(row)
+    },
+    async findMany(args) {
+      const rows = await raw.findMany(args as never)
+      return rows.map(parseRow)
+    },
+    async findUnique(args) {
+      if (!raw.findUnique) throw new Error(`表 ${tableName} 不支持 findUnique`)
+      const row = await raw.findUnique(args as never)
+      return row === null ? null : parseRow(row)
+    },
+    async create(args) { return parseRow(await raw.create(args as never)) },
+    async update(args) { return parseRow(await raw.update(args as never)) },
+    async updateMany(args) { return raw.updateMany(args as never) as Promise<BatchResult> },
+    async delete(args) { return parseRow(await raw.delete(args as never)) },
+    async deleteMany(args) { return raw.deleteMany(args as never) as Promise<BatchResult> },
+  }
+}

package/templates/core/scripts/mcp-server/shared/response.ts

@@ -1,10 +1,9 @@
 import type { ToolResponse } from "../types.js"
-import { redact } from "./redact.js"
 
 export function textResponse(text: string): { content: ToolResponse } {
-  return { content: [{ type: "text", text: redact(text) }] }
+  return { content: [{ type: "text", text }] }
 }
 
 export function errorResponse(message: string): { content: ToolResponse; isError: boolean } {
-  return { content: [{ type: "text", text: redact(message) }], isError: true }
+  return { content: [{ type: "text", text: message }], isError: true }
 }

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} 个`);