add-coder 0.3.25 → 0.3.27

package/templates/core/scripts/mcp-server/shared/plan-round-subscriber.ts

@@ -0,0 +1,99 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { LifecycleListenClient, LifecycleListenClientFactory, PgNotification } from "./plan-lifecycle-subscriber.js"
+import type { PlanRoundSnapshot } from "./plan-round-store.js"
+import {
+  isPlanRoundEventForContext,
+  parsePlanRoundChangedEnvelope,
+  PLAN_ROUND_CHANNEL,
+  type PlanRoundChangedEnvelope,
+} from "./plan-round-events.js"
+
+export interface PlanRoundSubscriberOptions {
+  context: RuntimeContextKey
+  clientFactory: LifecycleListenClientFactory
+  queryRounds(input: { context: RuntimeContextKey; planId?: string; reason: "initial" | "notification" | "reconnect" }): Promise<PlanRoundSnapshot>
+  onSnapshot(snapshot: PlanRoundSnapshot, envelope?: PlanRoundChangedEnvelope): void | Promise<void>
+  onError?(error: Error): void
+  reconnectDelayMs?: number
+}
+
+export class PlanRoundSubscriber {
+  readonly #options: PlanRoundSubscriberOptions
+  #client: LifecycleListenClient | null = null
+  #stopping = false
+  #startedOnce = false
+  #reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  #refreshQueue: Promise<void> = Promise.resolve()
+
+  constructor(options: PlanRoundSubscriberOptions) { this.#options = options }
+
+  async start(): Promise<void> {
+    if (this.#client) return
+    this.#stopping = false
+    try { await this.#connectAndHydrate("initial") } catch (error) { this.#scheduleReconnect(); throw error }
+  }
+
+  async stop(): Promise<void> {
+    this.#stopping = true
+    if (this.#reconnectTimer) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = null
+    const client = this.#client
+    this.#client = null
+    if (!client) return
+    client.removeAllListeners()
+    try { await client.query(`UNLISTEN ${PLAN_ROUND_CHANNEL}`) } catch { /* connection may already be gone */ }
+    await client.end().catch(() => undefined)
+    await this.#refreshQueue
+  }
+
+  async #connectAndHydrate(reason: "initial" | "reconnect"): Promise<void> {
+    const client = await this.#options.clientFactory()
+    this.#client = client
+    client.on("notification", (message: PgNotification) => this.#handleNotification(message))
+    client.on("error", (error: Error) => this.#handleDisconnect(client, error))
+    client.on("end", () => this.#handleDisconnect(client, new Error("PostgreSQL PlanRound LISTEN session ended")))
+    try {
+      await client.connect()
+      await client.query(`LISTEN ${PLAN_ROUND_CHANNEL}`)
+      await this.#refresh(undefined, reason)
+      this.#startedOnce = true
+    } catch (error) {
+      if (this.#client === client) this.#client = null
+      client.removeAllListeners()
+      await client.end().catch(() => undefined)
+      const normalized = error instanceof Error ? error : new Error(String(error))
+      this.#options.onError?.(normalized)
+      throw normalized
+    }
+  }
+
+  #handleNotification(message: PgNotification): void {
+    if (this.#stopping || message.channel !== PLAN_ROUND_CHANNEL) return
+    const envelope = parsePlanRoundChangedEnvelope(message.payload)
+    if (!envelope || !isPlanRoundEventForContext(envelope, this.#options.context)) return
+    this.#refreshQueue = this.#refreshQueue
+      .then(() => this.#refresh(envelope, "notification"))
+      .catch((error: unknown) => this.#options.onError?.(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  #handleDisconnect(client: LifecycleListenClient, error: Error): void {
+    if (this.#stopping || this.#client !== client) return
+    this.#client = null
+    client.removeAllListeners()
+    this.#options.onError?.(error)
+    this.#scheduleReconnect()
+  }
+
+  #scheduleReconnect(): void {
+    if (this.#stopping || this.#reconnectTimer) return
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null
+      this.#connectAndHydrate(this.#startedOnce ? "reconnect" : "initial").catch(() => this.#scheduleReconnect())
+    }, this.#options.reconnectDelayMs ?? 1000)
+  }
+
+  async #refresh(envelope: PlanRoundChangedEnvelope | undefined, reason: "initial" | "notification" | "reconnect"): Promise<void> {
+    const snapshot = await this.#options.queryRounds({ context: this.#options.context, planId: envelope?.planId, reason })
+    await this.#options.onSnapshot(snapshot, envelope)
+  }
+}

package/templates/core/scripts/mcp-server/shared/plan-status-store.ts

@@ -0,0 +1,37 @@
+import type { HitlRow, PlanRow } from "./db-types.js"
+import { HitlRowSchema, PlanRowSchema, validatedDelegate } from "./db-types.js"
+import type { PlanStatusStore } from "./plan-lifecycle.js"
+
+/**
+ * 数据库是 lifecycle 真相源。所有查询都强制携带 RuntimeContextKey，禁止同名
+ * Plan 在 adapter 间串线；LISTEN/NOTIFY 只负责唤醒本 store 重新查询。
+ */
+export function createPrismaPlanStatusStore(client: Record<string, unknown>): PlanStatusStore {
+  const plans = validatedDelegate<PlanRow>(client.planRecord, PlanRowSchema, "PlanRecord")
+  const hitls = validatedDelegate<HitlRow>(client.hitlRecord, HitlRowSchema, "HitlRecord")
+
+  return {
+    async findPlan({ context, planName, planId, activeOnly }) {
+      const where: Record<string, unknown> = {
+        projectKey: context.projectKey,
+        adapterKey: context.adapterKey,
+      }
+      if (planName) where.planName = planName
+      if (planId) where.id = planId
+      if (activeOnly) where.lifecycle = { in: ["ACTIVE", "BLOCKED"] }
+      return plans.findFirst({ where, orderBy: { updatedAt: "desc" } })
+    },
+    async findLatestPlanApproval({ context, planName }) {
+      const record = await hitls.findFirst({
+        where: {
+          projectKey: context.projectKey,
+          adapterKey: context.adapterKey,
+          planName,
+          type: "PLAN",
+        },
+        orderBy: { round: "desc" },
+      })
+      return record?.status ?? null
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/plan-tracking-mutation.ts

@@ -0,0 +1,71 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+import type { PlanLifecycleStatus } from "./plan-lifecycle.js"
+
+export interface TrackedPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface PlanTrackingTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<TrackedPlanRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<TrackedPlanRow>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<TrackedPlanRow>
+  }
+}
+
+export interface PlanTrackingDatabase {
+  $transaction<T>(work: (tx: PlanTrackingTransaction) => Promise<T>): Promise<T>
+}
+
+export async function trackPlanAndPublish(
+  database: PlanTrackingDatabase,
+  input: {
+    context: RuntimeContextKey
+    planName: string
+    planPath: string
+    projection: Record<string, unknown>
+  },
+): Promise<{ created: boolean; plan: TrackedPlanRow }> {
+  return database.$transaction(async (tx) => {
+    const scope = {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      planName: input.planName,
+    }
+    const existing = await tx.planRecord.findFirst({ where: scope })
+    const plan = existing
+      ? await tx.planRecord.update({
+          where: { id: existing.id, revision: existing.revision },
+          data: { ...input.projection, planPath: input.planPath, revision: { increment: 1 } },
+        })
+      : await tx.planRecord.create({
+          data: {
+            ...scope,
+            ...input.projection,
+            planPath: input.planPath,
+            lifecycle: "DRAFT",
+            revision: 0,
+          },
+        })
+    const expectedRevision = existing ? existing.revision + 1 : 0
+    if (plan.revision !== expectedRevision) {
+      throw new Error(`Plan track revision 未按预期变化: expected=${expectedRevision}, actual=${plan.revision}`)
+    }
+    await publishPlanLifecycleChanged(tx, createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+      revision: plan.revision,
+    }))
+    return { created: existing === null, plan }
+  })
+}

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

@@ -1,8 +1,8 @@
-import { DATABASE_URL, PROJECT_ROOT } from "./env.js"
-import { join, dirname, resolve as pathResolve } from "path"
+import { DATABASE_URL, PROJECT_ROOT, MAGIC_DIR } from "./env.js"
+import { join, dirname } from "path"
 import { existsSync } from "fs"
-import { fileURLToPath } from "url"
 import { createRequire } from "module"
+import { findUpSync } from "find-up"
 
 const require = createRequire(import.meta.url)
 
@@ -11,14 +11,20 @@ const require = createRequire(import.meta.url)
 // 双库分离项目（add.prisma=postgres + 业务 schema=mysql）需显式设置环境变量
 // PRISMA_CLIENT_DIR=add-prisma，否则会加载业务库 client 导致 provider mismatch
 const clientDir = process.env.PRISMA_CLIENT_DIR || "prisma"
+// 锚点查找兜底（find-up 包）：magicDir 向上查找项目根，替代手算层级（轮次 3）
+const anchorRoot = (() => {
+  const hit = findUpSync(MAGIC_DIR, { cwd: import.meta.dirname, type: "directory" });
+  return hit ? dirname(hit) : null;
+})();
 const candidates = [
   join(PROJECT_ROOT, `src/generated/${clientDir}/client.ts`),
   join(PROJECT_ROOT, `src/generated/${clientDir}/client.js`),
   join(process.cwd(), `src/generated/${clientDir}/client.ts`),
   join(process.cwd(), `src/generated/${clientDir}/client.js`),
-  // 从当前文件位置反推：shared/prisma.ts → 上 4 层到项目根
-  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, `src/generated/${clientDir}/client.ts`) })(),
-  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, `src/generated/${clientDir}/client.js`) })(),
+  ...(anchorRoot ? [
+    join(anchorRoot, `src/generated/${clientDir}/client.ts`),
+    join(anchorRoot, `src/generated/${clientDir}/client.js`),
+  ] : []),
 ]
 // 双库分离项目提示：检测到 add-prisma 客户端但未显式选择时提醒用户自行决策
 if (clientDir === "prisma" && existsSync(join(PROJECT_ROOT, "src/generated/add-prisma/client.ts"))) {

package/templates/core/scripts/mcp-server/shared/project-root-strategy.ts

@@ -4,8 +4,7 @@
 // >>> CAIJUE GENERATED START >>>
 export const PROJECT_ROOT_PRIORITY = ["env_var", "dirname_fallback", "cwd_fallback"] as const;
 export type ProjectRootTier = (typeof PROJECT_ROOT_PRIORITY)[number];
-// <<< CAIJUE GENERATED END <<<
-// >>> USER CODE >>>
+// <<< CAIJUE GENERATED END <<<// >>> USER CODE >>>
 import { resolve, dirname } from "path"
 import { existsSync } from "fs"
 

package/templates/core/scripts/mcp-server/shared/quant-recheck.strategy.ts

@@ -0,0 +1,16 @@
+// ⚠️ 由 caijuehub/transcribe.ts 自动生成，不要手动编辑！
+// 改 *-rules.toml 后重新运行: add-coder generate
+
+// >>> CAIJUE GENERATED START >>>
+export const QUANT_RECHECK_CONFIG = {
+    ANCHOR_WEIGHT: 3,
+    IDF_MIN_DOCS: 5,
+    RRF_K: 10,
+    MIN_ABS_SIMILARITY: 0.25,
+    RRF_MIN_CANDIDATES: 2,
+    EWMA_LAMBDA: 0.3,
+    EWMA_K: 1.5,
+    EWMA_COLD_START: 10,
+    EWMA_BASELINE: 0.16,
+} as const;
+// <<< CAIJUE GENERATED END <<<

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

@@ -0,0 +1,28 @@
+/*
+ * @Author       : xiaomingming wujixmm@gmail.com
+ * @Date         : 2026-08-10 18:41:34
+ * @LastEditors  : xiaomingming wujixmm@gmail.com
+ * @LastEditTime : 2026-08-10 18:41:35
+ * @FilePath     : /farm-agent/home/xmm/ai/add-coder/templates/core/scripts/mcp-server/shared/redact.ts
+ * @Description  : 
+ */
+// 敏感信息脱敏（进程层并发契约 v2：日志/错误不泄露 DATABASE_URL/密码）
+// 统一入口：response.ts 的 textResponse/errorResponse 内部调用，一处封装全覆盖所有工具
+
+const CONNECTION_URL_RE =
+  /(postgres(?:ql)?|mysql|redis|mongodb(?:\+srv)?):\/\/[^\s"'`]+/gi
+
+export function redactUrl(url: string): string {
+  // postgres://user:pass@host:port/db → postgres://user:****@host:port/db
+  return url.replace(/(:\/\/[^:/\s]+:)([^@/\s]+)(@)/, "$1****$3")
+}
+
+export function redact(text: string): string {
+  return text.replace(CONNECTION_URL_RE, (m) => {
+    try {
+      return redactUrl(m)
+    } catch {
+      return m
+    }
+  })
+}

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

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

package/templates/core/scripts/mcp-server/shared/runtime-context.ts

@@ -0,0 +1,77 @@
+import { createHash } from "crypto"
+import { realpathSync } from "fs"
+import { isAbsolute, relative, resolve } from "path"
+
+export const ADAPTER_MAGIC_DIR = Object.freeze({
+  add: ".add",
+  claude: ".claude",
+  codex: ".codex",
+  qoder: ".qoder",
+  trae: ".trae",
+  vscode: ".vscode",
+} as const)
+
+export type AdapterKey = keyof typeof ADAPTER_MAGIC_DIR
+export type AdapterMagicDir = (typeof ADAPTER_MAGIC_DIR)[AdapterKey]
+
+export interface RuntimeContextKey {
+  projectKey: string
+  adapterKey: AdapterKey
+  projectRoot: string
+  magicDir: AdapterMagicDir
+  contextId: string
+}
+
+const MAGIC_DIR_ADAPTER = new Map<AdapterMagicDir, AdapterKey>(
+  Object.entries(ADAPTER_MAGIC_DIR).map(([adapterKey, magicDir]) => [magicDir, adapterKey as AdapterKey]),
+)
+
+export function adapterKeyFromMagicDir(magicDir: string): AdapterKey {
+  const adapterKey = MAGIC_DIR_ADAPTER.get(magicDir as AdapterMagicDir)
+  if (!adapterKey) {
+    throw new Error(`未知 ADD adapter magicDir: ${magicDir}`)
+  }
+  return adapterKey
+}
+
+export function canonicalProjectRoot(projectRoot: string): string {
+  if (!projectRoot.trim()) throw new Error("PROJECT_ROOT 不能为空")
+  return realpathSync.native(resolve(projectRoot))
+}
+
+export function projectKeyFromRoot(projectRoot: string): string {
+  const canonicalRoot = canonicalProjectRoot(projectRoot)
+  return createHash("sha256").update(`add-project\0${canonicalRoot}`).digest("hex")
+}
+
+export function createRuntimeContext(projectRoot: string, magicDir: string): Readonly<RuntimeContextKey> {
+  const adapterKey = adapterKeyFromMagicDir(magicDir)
+  const canonicalRoot = canonicalProjectRoot(projectRoot)
+  const projectKey = projectKeyFromRoot(canonicalRoot)
+  return Object.freeze({
+    projectKey,
+    adapterKey,
+    projectRoot: canonicalRoot,
+    magicDir: ADAPTER_MAGIC_DIR[adapterKey],
+    contextId: `${projectKey}:${adapterKey}`,
+  })
+}
+
+export function runtimeScopeRoot(context: RuntimeContextKey): string {
+  return resolve(context.projectRoot, context.magicDir)
+}
+
+export function isPathInRuntimeScope(context: RuntimeContextKey, candidatePath: string): boolean {
+  const scopeRoot = runtimeScopeRoot(context)
+  const absoluteCandidate = isAbsolute(candidatePath) ? resolve(candidatePath) : resolve(context.projectRoot, candidatePath)
+  const scopedRelative = relative(scopeRoot, absoluteCandidate)
+  return scopedRelative === "" || (!scopedRelative.startsWith("..") && !isAbsolute(scopedRelative))
+}
+
+export function assertPathInRuntimeScope(context: RuntimeContextKey, candidatePath: string): string {
+  const absoluteCandidate = isAbsolute(candidatePath) ? resolve(candidatePath) : resolve(context.projectRoot, candidatePath)
+  if (!isPathInRuntimeScope(context, absoluteCandidate)) {
+    throw new Error(`路径越出当前 ADD adapter scope: ${absoluteCandidate}（scope=${runtimeScopeRoot(context)}）`)
+  }
+  return absoluteCandidate
+}

package/templates/core/scripts/mcp-server/shared/schema-topology.ts

@@ -0,0 +1,159 @@
+import { readdir, readFile } from "fs/promises"
+import { basename, join, relative } from "path"
+
+export type SchemaView = "business" | "add" | "all"
+export type SchemaTopologyMode = "single" | "split"
+export type SchemaBoundary = "shared" | "business" | "add"
+
+export interface PrismaDeclaration {
+  kind: "model" | "enum"
+  name: string
+  sourcePath: string
+  sourceFile: string
+  boundary: SchemaBoundary
+  body: string
+  fieldCount: number
+}
+
+export interface PrismaSchemaFile {
+  path: string
+  file: string
+  boundary: SchemaBoundary
+  declarations: PrismaDeclaration[]
+}
+
+export interface PrismaSchemaTopology {
+  mode: SchemaTopologyMode
+  view: SchemaView
+  schemaRoot: string
+  files: PrismaSchemaFile[]
+  models: PrismaDeclaration[]
+  enums: PrismaDeclaration[]
+}
+
+function extractBlock(source: string, braceIndex: number): string {
+  let depth = 1
+  let cursor = braceIndex + 1
+  while (depth > 0 && cursor < source.length) {
+    if (source[cursor] === "{") depth += 1
+    if (source[cursor] === "}") depth -= 1
+    cursor += 1
+  }
+  if (depth !== 0) throw new Error("Prisma declaration 花括号未闭合")
+  return source.slice(braceIndex, cursor)
+}
+
+export function parsePrismaDeclarations(
+  source: string,
+  sourcePath: string,
+  boundary: SchemaBoundary,
+): PrismaDeclaration[] {
+  const declarations: PrismaDeclaration[] = []
+  const declarationRegex = /^\s*(model|enum)\s+(\w+)\s*\{/gm
+  let match: RegExpExecArray | null
+  while ((match = declarationRegex.exec(source)) !== null) {
+    const braceIndex = source.indexOf("{", match.index)
+    const body = extractBlock(source, braceIndex)
+    const kind = match[1] as "model" | "enum"
+    declarations.push({
+      kind,
+      name: match[2],
+      sourcePath,
+      sourceFile: basename(sourcePath),
+      boundary,
+      body,
+      fieldCount: kind === "model"
+        ? body.split("\n").filter(line => {
+            const trimmed = line.trim()
+            return trimmed.length > 0 && trimmed !== "{" && trimmed !== "}" && !trimmed.startsWith("//") && !trimmed.startsWith("@@")
+          }).length
+        : 0,
+    })
+  }
+  return declarations
+}
+
+function boundaryFor(file: string, mode: SchemaTopologyMode): SchemaBoundary {
+  if (mode === "single") return "shared"
+  return file === "add.prisma" ? "add" : "business"
+}
+
+function includedInView(file: string, view: SchemaView): boolean {
+  if (view === "all") return true
+  return view === "add" ? file === "add.prisma" : file !== "add.prisma"
+}
+
+export async function loadPrismaSchemaTopology(input: {
+  projectRoot: string
+  splitDatabase: boolean
+  view?: SchemaView
+}): Promise<PrismaSchemaTopology> {
+  const schemaRoot = join(input.projectRoot, "prisma")
+  const mode: SchemaTopologyMode = input.splitDatabase ? "split" : "single"
+  const view = input.view ?? "all"
+  let names: string[]
+  try {
+    names = (await readdir(schemaRoot)).filter(file => file.endsWith(".prisma")).sort()
+  } catch {
+    throw new Error(`未找到 Prisma schema 目录: ${schemaRoot}`)
+  }
+  if (names.length === 0) throw new Error(`Prisma schema 目录中没有 *.prisma: ${schemaRoot}`)
+
+  const selected = names.filter(file => includedInView(file, view))
+  if (selected.length === 0) {
+    throw new Error(`Schema view=${view} 没有可扫描文件；mode=${mode}；全部文件=${names.join(", ")}`)
+  }
+  const files: PrismaSchemaFile[] = []
+  for (const file of selected) {
+    const path = join(schemaRoot, file)
+    const boundary = boundaryFor(file, mode)
+    const source = await readFile(path, "utf8")
+    files.push({ path, file, boundary, declarations: parsePrismaDeclarations(source, path, boundary) })
+  }
+  const declarations = files.flatMap(file => file.declarations)
+  const models = declarations.filter(item => item.kind === "model")
+  const enums = declarations.filter(item => item.kind === "enum")
+  if (models.length === 0) {
+    throw new Error(
+      `Schema 诊断: 检测到 ${files.length} 个 Prisma 文件但 view=${view} 解析为 0 个模型；` +
+      `mode=${mode}；扫描=${files.map(file => relative(input.projectRoot, file.path)).join(", ")}`,
+    )
+  }
+
+  const byName = new Map<string, PrismaDeclaration[]>()
+  for (const model of models) {
+    const key = model.name.toLowerCase()
+    byName.set(key, [...(byName.get(key) ?? []), model])
+  }
+  const conflicts = [...byName.entries()].filter(([, entries]) => entries.length > 1)
+  if (conflicts.length > 0) {
+    const details = conflicts.map(([name, entries]) =>
+      `${name}: ${entries.map(entry => `${relative(input.projectRoot, entry.sourcePath)}[${entry.boundary}]`).join(", ")}`,
+    )
+    throw new Error(`Schema 模型冲突（fail closed）: ${details.join("; ")}`)
+  }
+
+  return { mode, view, schemaRoot, files, models, enums }
+}
+
+export function formatSchemaTopology(topology: PrismaSchemaTopology, projectRoot: string): string {
+  const lines = [
+    "=== Prisma Schema 拓扑 ===",
+    `mode: ${topology.mode}`,
+    `view: ${topology.view}`,
+    `databaseBoundaries: ${topology.mode === "single" ? "shared (business + ADD 同库)" : "business, add (分库；all 仅汇总展示，不代表可跨库 join)"}`,
+    `scannedFiles: ${topology.files.length}`,
+  ]
+  for (const file of topology.files) {
+    lines.push(`  - ${relative(projectRoot, file.path)} [${file.boundary}] models=${file.declarations.filter(item => item.kind === "model").length}`)
+  }
+  lines.push("", `模型 (${topology.models.length} 个):`)
+  for (const model of topology.models) {
+    lines.push(`  ${model.name} (${model.fieldCount} 字段) — ${relative(projectRoot, model.sourcePath)} [${model.boundary}]`)
+  }
+  if (topology.enums.length > 0) {
+    lines.push("", `枚举 (${topology.enums.length} 个):`)
+    for (const item of topology.enums) lines.push(`  ${item.name} — ${relative(projectRoot, item.sourcePath)} [${item.boundary}]`)
+  }
+  return lines.join("\n")
+}

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

@@ -1,12 +1,14 @@
 import * as z from "zod/v4"
+import { createHash } from "crypto"
 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 { PROJECT_ID, PROJECT_ROOT, getRuntimeContext } 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) {
+  const runtimeContext = getRuntimeContext()
 
   // 无类型边界单点（zod 托管）：动态 client → 运行期校验的泛型委托
   const devDb = validatedDelegate<DevOperationRow>(prisma.devOperation, DevOperationRowSchema, "DevOperation")
@@ -30,7 +32,10 @@ export function registerAuditTools(server: ToolRegistrar) {
   }, async (args: Record<string, string | number | undefined>, _ctx: unknown) => {
     try {
       const { targetType, action, targetId, planKeyword, keyword, sinceMinutes, limit = 20 } = args
-      const where: Record<string, unknown> = {}
+      const where: Record<string, unknown> = {
+        projectKey: runtimeContext.projectKey,
+        producerAdapterKey: runtimeContext.adapterKey,
+      }
       if (sinceMinutes !== undefined) where.createdAt = { gte: new Date(Date.now() - Number(sinceMinutes) * 60 * 1000) }
       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)
@@ -44,6 +49,7 @@ export function registerAuditTools(server: ToolRegistrar) {
       const lines = [`=== 开发操作审计日志 (条件: ${fl.length > 0 ? fl.join(", ") : "无过滤条件（最近全部）"}) ===`, `服务项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `共 ${logs.length} 条记录`]
       for (let i = 0; i < logs.length; i++) {
         const l = logs[i]; lines.push(`[${i+1}] ${l.createdAt.toISOString()}`, `    action: ${l.action} | targetType: ${l.targetType} | targetId: ${l.targetId || "(无)"}`)
+        lines.push(`    beforeState: ${JSON.stringify(l.beforeState)}`, `    afterState: ${JSON.stringify(l.afterState)}`)
         if (l.reason) lines.push(`    reason: ${l.reason}`); if (l.planKeyword) lines.push(`    planKeyword: ${l.planKeyword}`)
       }
       if (planKeyword) { lines.push("=== Plan 分组 ===", `planKeyword=${planKeyword} 的操作链:`); for (const l of logs) lines.push(`  ${l.createdAt.toISOString().slice(11,19)} ${l.action}`) }
@@ -60,22 +66,58 @@ export function registerAuditTools(server: ToolRegistrar) {
       targetType: z.string().describe("目标类型: 'API_ROUTE', 'COMPONENT', 'SCHEMA', 'RULE', 'DOC', 'PLAN', 'SPEC', 'SKILL', 'AGENT' 等"),
       targetId: z.string().optional().describe("目标标识（相对路径）"),
       planKeyword: z.string().optional().describe("关联 Plan 的关键词"),
-      beforeState: z.string().describe("操作前的状态（JSON 字符串）。必填，记录变更前的文件内容或配置状态，用于审计回溯。"),
-      afterState: z.string().describe("操作后的状态（JSON 字符串）。必填，记录变更后的文件内容或配置状态，用于审计回溯。"),
+      beforeState: z.string().describe("操作前的状态（非 null JSON 对象或数组字符串）。必填，用于审计回溯。"),
+      afterState: z.string().describe("操作后的状态（非 null JSON 对象或数组字符串）。必填，用于审计回溯。"),
       reason: z.string().optional().describe("操作原因"),
+      operationKey: z.string().optional().describe("调用方提供的幂等键；未提供时按本次结构化操作内容计算"),
     }),
   }, async (args: Record<string, string | number | undefined>, _ctx: unknown) => {
     try {
-      const { action, targetType, targetId, planKeyword, beforeState, afterState, reason } = args
+      const { action, targetType, targetId, planKeyword, beforeState, afterState, reason, operationKey } = args
       const tId = s(targetId)
       const pathWarnings: string[] = []
       if (tId && (tId.startsWith("/") || /^[A-Z]:\\/.test(tId))) pathWarnings.push(`⚠️ targetId 使用了绝对路径: "${tId}"。请使用相对路径。`)
+      if (!s(beforeState).trim() || !s(afterState).trim()) return errorResponse("beforeState/afterState 必须提供非空 JSON 字符串。")
       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 字符串。") }
+      const isStructuredState = (value: unknown): value is Record<string, unknown> | unknown[] => typeof value === "object" && value !== null
+      if (!isStructuredState(parsedBefore) || !isStructuredState(parsedAfter)) return errorResponse("beforeState/afterState 必须是非 null 的 JSON 对象或数组。")
       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()}`]
+      const operationPayload = {
+        projectKey: runtimeContext.projectKey,
+        producerAdapterKey: runtimeContext.adapterKey,
+        action: s(action),
+        targetType: s(targetType),
+        targetId: tId || "unknown",
+        planKeyword: s(planKeyword) || "unknown",
+        beforeState: parsedBefore,
+        afterState: parsedAfter,
+        reason: s(reason) || null,
+      }
+      const resolvedOperationKey = s(operationKey).trim() || createHash("sha256")
+        .update(JSON.stringify(operationPayload))
+        .digest("hex")
+      const scopedData: Partial<DevOperationRow> = {
+        ...operationPayload,
+        userId: systemUser.id,
+        contextId: runtimeContext.contextId,
+        toolName: "record_dev_operation",
+        operationKey: resolvedOperationKey,
+      }
+      const log = await devDb.upsert({
+        where: {
+          projectKey_producerAdapterKey_toolName_operationKey: {
+            projectKey: runtimeContext.projectKey,
+            producerAdapterKey: runtimeContext.adapterKey,
+            toolName: "record_dev_operation",
+            operationKey: resolvedOperationKey,
+          },
+        },
+        create: scopedData,
+        update: {},
+      })
+      const lines = [`✅ 开发操作已记录`, `  落库项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `  ID: ${log.id}`, `  action: ${s(action)}`, `  targetType: ${s(targetType)}`, `  targetId: ${tId || "unknown"}`, `  planKeyword: ${s(planKeyword) || "unknown"}`, `  beforeState: ${JSON.stringify(log.beforeState)}`, `  afterState: ${JSON.stringify(log.afterState)}`, `  createdAt: ${log.createdAt.toISOString()}`]
       if (pathWarnings.length > 0) { lines.push(""); lines.push(...pathWarnings) }
       lines.push("", `📋 落库回查（必须执行）:`, tId ? `  query_audit_logs({ targetId: "${tId}" }) — 确认本条记录已写入` : "")
       return textResponse(lines.join("\n"))