add-coder 0.2.8 → 0.2.10

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

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { registerHitlNotifications } from "./hitl.js"
+import { registerHookNotifications } from "./hook.js"
+
+export function registerAllNotifications(server: McpServer) {
+  registerHitlNotifications(server)
+  registerHookNotifications(server)
+}

package/templates/core/scripts/mcp-server/resources/add-coder-version.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { join } from "path"
+import { readFileSafe, PROJECT_ROOT } from "../shared/fs.js"
+import { spawnSync } from "child_process"
+
+interface PkgJson { version?: string }
+
+export function registerVersionResource(server: McpServer) {
+  server.registerResource("add-coder-version", "add-coder://version",
+    { description: "add-coder npm 包版本信息（当前安装 vs 最新发布）", mimeType: "application/json" },
+  async () => {
+    const pkgPath = join(PROJECT_ROOT, "package.json")
+    const pkg = await readFileSafe(pkgPath)
+    let current = "unknown", latest = "unknown", outdated = false
+    if (pkg) {
+      try { current = (JSON.parse(pkg) as PkgJson).version ?? "unknown" } catch { /* intentionally empty */ }
+    }
+    try {
+      const result = spawnSync("npm", ["view", "add-coder", "version"], { encoding: "utf-8", timeout: 10000 })
+      latest = (result.stdout || "").trim() || "unknown"
+      outdated = current !== "unknown" && latest !== "unknown" && current !== latest
+    } catch { /* intentionally empty */ }
+    return { contents: [{ text: JSON.stringify({ current, latest, outdated }), uri: "add-coder://version", mimeType: "application/json" }] }
+  })
+}

package/templates/core/scripts/mcp-server/resources/add-state.ts

@@ -0,0 +1,44 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { join } from "path"
+import { existsSync } from "fs"
+import { readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+
+export function registerAddStateResources(server: McpServer) {
+
+  server.registerResource("plan-status", "add-coder://plan/status",
+    { description: "当前活跃 ADD Plan 的状态信息", mimeType: "application/json" },
+  async () => {
+    const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+    if (!existsSync(plansDir)) return { contents: [{ text: JSON.stringify({ active: false, message: "无 plans 目录" }), uri: "add-coder://plan/status", mimeType: "application/json" }] }
+    const files = (await readdirRecursive(plansDir)).filter(f => f.endsWith(".md") && !f.includes("add-route") && !f.includes("handoff"))
+    const active = files.length > 0 ? files[files.length - 1].replace(".md", "") : null
+    return { contents: [{ text: JSON.stringify({ active, total: files.length }), uri: "add-coder://plan/status", mimeType: "application/json" }] }
+  })
+
+  server.registerResource("review-status", "add-coder://review/status",
+    { description: "当前活跃 ADD Review 的状态信息", mimeType: "application/json" },
+  async () => {
+    const reviewsDir = join(PROJECT_ROOT, MAGIC_DIR, "reviews")
+    if (!existsSync(reviewsDir)) return { contents: [{ text: JSON.stringify({ active: false }), uri: "add-coder://review/status", mimeType: "application/json" }] }
+    const files = (await readdirRecursive(reviewsDir)).filter(f => f.endsWith(".md"))
+    return { contents: [{ text: JSON.stringify({ active: files.length > 0, total: files.length }), uri: "add-coder://review/status", mimeType: "application/json" }] }
+  })
+
+  server.registerResource("route-status", "add-coder://route/status",
+    { description: "ADD Route 执行状态", mimeType: "application/json" },
+  async () => {
+    const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+    if (!existsSync(plansDir)) return { contents: [{ text: JSON.stringify({ found: false }), uri: "add-coder://route/status", mimeType: "application/json" }] }
+    const files = (await readdirRecursive(plansDir)).filter(f => f.includes("add-route"))
+    return { contents: [{ text: JSON.stringify({ found: files.length > 0, files }), uri: "add-coder://route/status", mimeType: "application/json" }] }
+  })
+
+  server.registerResource("specs-status", "add-coder://specs/status",
+    { description: "ADD Specs 状态", mimeType: "application/json" },
+  async () => {
+    const specsDir = join(PROJECT_ROOT, MAGIC_DIR, "specs")
+    if (!existsSync(specsDir)) return { contents: [{ text: JSON.stringify({ found: false }), uri: "add-coder://specs/status", mimeType: "application/json" }] }
+    const dirs = (await readdirRecursive(specsDir)).filter(f => !f.includes("/"))
+    return { contents: [{ text: JSON.stringify({ found: dirs.length > 0, specs: dirs }), uri: "add-coder://specs/status", mimeType: "application/json" }] }
+  })
+}

package/templates/core/scripts/mcp-server/resources/hook-events-report.ts

@@ -0,0 +1,104 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { prisma } from "../shared/prisma.js"
+
+export function registerHookEventResources(server: McpServer) {
+
+  // ── 日报 Resource ──
+  server.registerResource("hook-events-daily", "add-coder://report/hook-events/daily",
+    { description: "过去 24 小时 Hook 拦截事件日报（按小时分组聚合）", mimeType: "application/json" },
+  async () => {
+    try {
+      const ops = prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
+      const since = new Date(Date.now() - 24 * 60 * 60 * 1000)
+      const logs = await ops.findMany({
+        where: { action: "HOOK_INTERCEPT", createdAt: { gte: since } },
+        orderBy: { createdAt: "desc" },
+        take: 500,
+      }) as Array<Record<string, unknown>>
+
+      // 按小时分组
+      const hourly = new Map<string, { total: number; plans: Map<string, number> }>()
+      for (const l of logs) {
+        const hour = (l.createdAt as Date).toISOString().slice(0, 13) + ":00"
+        const kw = (l.planKeyword as string) || "unknown"
+        if (!hourly.has(hour)) hourly.set(hour, { total: 0, plans: new Map() })
+        const entry = hourly.get(hour)!
+        entry.total++
+        entry.plans.set(kw, (entry.plans.get(kw) || 0) + 1)
+      }
+
+      const breakdown: Array<{ hour: string; total: number; plans: Record<string, number> }> = []
+      for (const [hour, entry] of [...hourly.entries()].sort()) {
+        const plans: Record<string, number> = {}
+        for (const [k, v] of entry.plans) plans[k] = v
+        breakdown.push({ hour, total: entry.total, plans })
+      }
+
+      return {
+        contents: [{
+          text: JSON.stringify({ type: "daily", total: logs.length, breakdown }),
+          uri: "add-coder://report/hook-events/daily",
+          mimeType: "application/json",
+        }],
+      }
+    } catch {
+      return {
+        contents: [{
+          text: JSON.stringify({ type: "daily", total: 0, breakdown: [], error: "数据库不可用" }),
+          uri: "add-coder://report/hook-events/daily",
+          mimeType: "application/json",
+        }],
+      }
+    }
+  })
+
+  // ── 周报 Resource ──
+  server.registerResource("hook-events-weekly", "add-coder://report/hook-events/weekly",
+    { description: "过去 7 天 Hook 拦截事件周报（按日分组聚合）", mimeType: "application/json" },
+  async () => {
+    try {
+      const ops = prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
+      const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+      const logs = await ops.findMany({
+        where: { action: "HOOK_INTERCEPT", createdAt: { gte: since } },
+        orderBy: { createdAt: "desc" },
+        take: 2000,
+      }) as Array<Record<string, unknown>>
+
+      // 按日分组
+      const daily = new Map<string, { total: number; plans: Map<string, number> }>()
+      for (const l of logs) {
+        const day = (l.createdAt as Date).toISOString().slice(0, 10)
+        const kw = (l.planKeyword as string) || "unknown"
+        if (!daily.has(day)) daily.set(day, { total: 0, plans: new Map() })
+        const entry = daily.get(day)!
+        entry.total++
+        entry.plans.set(kw, (entry.plans.get(kw) || 0) + 1)
+      }
+
+      const breakdown: Array<{ day: string; total: number; plans: Record<string, number> }> = []
+      for (const [day, entry] of [...daily.entries()].sort()) {
+        const plans: Record<string, number> = {}
+        for (const [k, v] of entry.plans) plans[k] = v
+        breakdown.push({ day, total: entry.total, plans })
+      }
+
+      return {
+        contents: [{
+          text: JSON.stringify({ type: "weekly", total: logs.length, breakdown }),
+          uri: "add-coder://report/hook-events/weekly",
+          mimeType: "application/json",
+        }],
+      }
+    } catch {
+      return {
+        contents: [{
+          text: JSON.stringify({ type: "weekly", total: 0, breakdown: [], error: "数据库不可用" }),
+          uri: "add-coder://report/hook-events/weekly",
+          mimeType: "application/json",
+        }],
+      }
+    }
+  })
+
+}

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

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { registerAddStateResources } from "./add-state.js"
+import { registerRoundTaskResources } from "./round-task.js"
+import { registerVersionResource } from "./add-coder-version.js"
+import { registerHookEventResources } from "./hook-events-report.js"
+
+export function registerAllResources(server: McpServer) {
+  registerAddStateResources(server)
+  registerRoundTaskResources(server)
+  registerVersionResource(server)
+  registerHookEventResources(server)  // 2 resources: hook-events/{daily,weekly}
+}

package/templates/core/scripts/mcp-server/resources/round-task.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { join } from "path"
+import { existsSync } from "fs"
+import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+
+export function registerRoundTaskResources(server: McpServer) {
+  server.registerResource("round-task", "add-coder://round/{round}/task/{task}",
+    { description: "指定轮次的任务完成状态（从 Handoff 文件解析）", mimeType: "application/json" },
+  async (uri) => {
+    const round = uri.pathname.split("/")[2]
+    const task = uri.pathname.split("/")[4]
+    const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+    if (!existsSync(plansDir)) return { contents: [{ text: JSON.stringify({ found: false }), uri: uri.href, mimeType: "application/json" }] }
+    const files = await readdirRecursive(plansDir)
+    const handoff = files.find(f => f.includes("handoff"))
+    if (!handoff) return { contents: [{ text: JSON.stringify({ found: false, reason: "无 Handoff 文件" }), uri: uri.href, mimeType: "application/json" }] }
+    const content = await readFileSafe(join(plansDir, handoff)) || ""
+    const tasks = content.match(/- \[[ x]\]/g) || []
+    const done = tasks.filter(t => t.includes("x")).length
+    return { contents: [{ text: JSON.stringify({ found: true, round, task, done, totalTasks: tasks.length }), uri: uri.href, mimeType: "application/json" }] }
+  })
+}

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

@@ -0,0 +1 @@
+export { createReviewRequest } from "./review.js"

package/templates/core/scripts/mcp-server/sampling/review.ts

@@ -0,0 +1,47 @@
+import { inputRequired, type InputRequiredResult } from "@modelcontextprotocol/server"
+import { join } from "path"
+import { readFileSafe, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+
+/**
+ * HITL Review 触发
+ * ADD-9 方向验证 / ADD-10 语义对齐 / ADD-11 证据持久化
+ *
+ * 流程: 读取 Review 模板 → 生成 HITL 发现总览 temporary.md → 人类拍板 → 写入正式 Review
+ * 参考: add-paradigm SKILL Step 0.6.5（Review 结论回流至 Plan 与 Specs）
+ */
+export async function createReviewRequest(planKeyword: string, reviewType: "plan" | "implementation" | "runtime" = "plan"): Promise<InputRequiredResult> {
+  const templateFile = reviewType === "plan"
+    ? "review-template.md"
+    : reviewType === "implementation"
+      ? "review-implementation-template.md"
+      : "review-runtime-template.md"
+
+  const templatePath = join(PROJECT_ROOT, MAGIC_DIR, "templates", templateFile)
+  const template = await readFileSafe(templatePath)
+
+  const hitlGuide = `
+## HITL 审核流程（两步法）
+
+1. 先写 {review-name}.temporary.md（只含 HITL 发现总览表 + 问题清单）
+2. 人类拍板后 → 生成完整 Review 写入 ${MAGIC_DIR}/reviews/
+3. 将 Review 结论回流至 Plan（Step 0.6.5）
+
+模板:
+${template?.slice(0, 3000) ?? `标准 ${reviewType} Review 模板`}
+`
+
+  const prompt = `请为 Plan "${planKeyword}" 发起 HITL Review（类型: ${reviewType}）。
+先读取 ${MAGIC_DIR}/reviews/ 下已有的 Review 模板，
+然后按 HITL 两步法：先写 temporary.md → 人类拍板 → 生成完整 Review。
+
+${hitlGuide}`
+
+  const sampleRequest = inputRequired.createMessage({
+    messages: [{ role: "user" as const, content: { type: "text" as const, text: prompt } }],
+    maxTokens: 4000
+  })
+
+  return inputRequired({
+    inputRequests: { sample: sampleRequest }
+  })
+}

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

@@ -0,0 +1,26 @@
+import dotenv from "dotenv"
+import { dirname, resolve, basename } from "path"
+import { fileURLToPath } from "url"
+import { existsSync } from "fs"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+export const PROJECT_ROOT = resolve(__dirname, "..", "..", "..", "..")
+export const MAGIC_DIR = basename(resolve(__dirname, "..", "..", ".."))
+export const PROJECT_ID = basename(PROJECT_ROOT)
+
+const ENV_CANDIDATES = [".env.development.local", ".env.development", ".env.local", ".env"]
+let loaded = false
+for (const base of [PROJECT_ROOT, process.cwd()]) {
+  if (loaded) break
+  for (const f of ENV_CANDIDATES) {
+    const p = resolve(base, f)
+    if (existsSync(p)) { dotenv.config({ path: p, override: true }); loaded = true; break }
+  }
+}
+
+export const DATABASE_URL = process.env.DATABASE_URL
+if (!DATABASE_URL) {
+  throw new Error("DATABASE_URL 未设置，请在 .env 中配置数据库连接串")
+}

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

@@ -0,0 +1,40 @@
+import { readFile, readdir } from "fs/promises"
+import { join, relative } from "path"
+import { existsSync } from "fs"
+import { spawnSync } from "child_process"
+import { PROJECT_ROOT, MAGIC_DIR } from "./env.js"
+import type { GuardResult } from "../types.js"
+
+export async function readFileSafe(filePath: string): Promise<string | null> {
+  try { return await readFile(filePath, "utf-8") } catch { return null }
+}
+
+export async function validateDocWithGuard(filePath: string): Promise<GuardResult> {
+  const guardScript = join(PROJECT_ROOT, MAGIC_DIR, "hooks", "doc-format-guard.sh")
+  if (!existsSync(guardScript)) return { ok: true, issues: "" }
+  const content = await readFileSafe(filePath)
+  if (!content) return { ok: false, issues: "文件无法读取" }
+  const guardInput = JSON.stringify({ tool_input: { file_path: filePath, file_content: content } })
+  const result = spawnSync("bash", [guardScript], { input: guardInput, encoding: "utf-8", timeout: 5000 })
+  if (result.status !== 0) return { ok: false, issues: result.stderr || "guard 执行失败" }
+  return { ok: true, issues: "" }
+}
+
+export async function readdirRecursive(baseDir: string): Promise<string[]> {
+  const results: string[] = []
+  async function walk(dir: string) {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(fullPath)
+      } else {
+        results.push(relative(baseDir, fullPath))
+      }
+    }
+  }
+  await walk(baseDir)
+  return results
+}
+
+export { PROJECT_ROOT, MAGIC_DIR }

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

@@ -0,0 +1,35 @@
+import { DATABASE_URL, PROJECT_ROOT } from "./env.js"
+import { join, dirname, resolve as pathResolve } from "path"
+import { existsSync } from "fs"
+import { fileURLToPath } from "url"
+
+// 多路径回退：PROJECT_ROOT 可能因 cwd/沙箱环境算错
+const candidates = [
+  join(PROJECT_ROOT, "src/generated/prisma/client.ts"),
+  join(PROJECT_ROOT, "src/generated/prisma/client.js"),
+  join(process.cwd(), "src/generated/prisma/client.ts"),
+  join(process.cwd(), "src/generated/prisma/client.js"),
+  // 从当前文件位置反推：shared/prisma.ts → 上 4 层到项目根
+  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, "src/generated/prisma/client.ts") })(),
+  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, "src/generated/prisma/client.js") })(),
+]
+let prismaClientPath = candidates[0]
+for (const p of candidates) { if (existsSync(p)) { prismaClientPath = p; break } }
+const prismaModule: Record<string, unknown> = await import(prismaClientPath) as Record<string, unknown>
+const PrismaClient = (prismaModule.PrismaClient || prismaModule.default) as new (opts?: Record<string, unknown>) => Record<string, unknown>
+
+let adapter: Record<string, unknown> | undefined
+if (!DATABASE_URL) throw new Error("DATABASE_URL required")
+const url: string = DATABASE_URL
+if (url.startsWith("postgresql://") || url.startsWith("postgres://")) {
+  try {
+    const pg = await import("@prisma/adapter-pg") as Record<string, unknown>
+    const Pg = pg.PrismaPg as new (opts: Record<string, unknown>) => Record<string, unknown>
+    adapter = new Pg({ connectionString: url })
+  } catch { /* optional dep */ }
+}
+
+export const prisma: Record<string, Record<string, (...a: unknown[]) => unknown>> = new PrismaClient({
+  ...(adapter ? { adapter } : {}),
+  log: process.env.NODE_ENV === "development" ? ["error", "warn"] : ["error"],
+}) as Record<string, Record<string, (...a: unknown[]) => unknown>>

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

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

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

@@ -0,0 +1,2 @@
+export { enqueueTask, getTaskStatus, getAllTasks, runTask, type Task } from "./runner.js"
+export { persistTask } from "./store.js"

package/templates/core/scripts/mcp-server/tasks/runner.ts

@@ -0,0 +1,20 @@
+type TaskStatus = "pending" | "running" | "done" | "failed"
+export interface Task { id: string; type: string; status: TaskStatus; progress: number; result?: string; createdAt: Date }
+
+const taskQueue: Task[] = []
+
+export function enqueueTask(type: string): string {
+  const id = `task-${Date.now()}-${Math.random().toString(36).slice(2,6)}`
+  taskQueue.push({ id, type, status: "pending", progress: 0, createdAt: new Date() })
+  return id
+}
+
+export function getTaskStatus(id: string): Task | undefined { return taskQueue.find(t => t.id === id) }
+
+export function getAllTasks(): Task[] { return [...taskQueue] }
+
+export async function runTask(id: string, handler: () => Promise<string>) {
+  const task = taskQueue.find(t => t.id === id); if (!task) return
+  task.status = "running"; task.progress = 10
+  try { task.result = await handler(); task.status = "done"; task.progress = 100 } catch (e) { task.status = "failed"; task.result = e instanceof Error ? e.message : String(e) }
+}

package/templates/core/scripts/mcp-server/tasks/store.ts

@@ -0,0 +1,20 @@
+import { prisma } from "../shared/prisma.js"
+import type { Task } from "./runner.js"
+
+export async function persistTask(task: Task): Promise<void> {
+  try {
+    const typedPrisma = prisma as Record<string, Record<string, (...a: unknown[]) => unknown>>
+    await typedPrisma.auditLog.create({
+      data: {
+        userId: "system",
+        action: `TASK_${task.status.toUpperCase()}`,
+        targetType: "TASK",
+        targetId: task.id,
+        reason: task.type,
+        afterState: { progress: task.progress, result: task.result ?? null }
+      }
+    })
+  } catch { /* intentionally empty */ }
+}
+
+export type { Task }

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

@@ -0,0 +1,73 @@
+import * as z from "zod/v4"
+import type { McpServer } from "@modelcontextprotocol/server"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { prisma } from "../shared/prisma.js"
+
+export function registerAuditTools(server: McpServer) {
+
+  // ===== query_audit_logs (L992-1109) =====
+  server.registerTool("query_audit_logs", {
+    description: "稀疏查询开发操作审计日志（DevOperation 表，MCP-5 稀疏推理恢复）。支持多维度检索，AI 可在不同对话会话中通过任意维度组合查询之前的开发操作记录，实现跨会话的上下文恢复。\n\n典型用法:\n- query_audit_logs({ targetType: \"API_ROUTE\" }) — 查所有 API 路由改动\n- query_audit_logs({ targetId: \"src/app/api/knowledge/route.ts\" }) — 查特定文件改动\n- query_audit_logs({ keyword: \"pagination\" }) — 按关键词搜索\n- query_audit_logs({ planKeyword: \"add-coder\" }) — 按 Plan 关键词查该 Plan 下所有 devlog\n- query_audit_logs({}) — 查最近的记录（session-init 会话恢复）",
+    inputSchema: z.object({
+      targetType: z.string().optional().describe("按目标类型精确过滤"),
+      action: z.string().optional().describe("按操作类型精确过滤"),
+      targetId: z.string().optional().describe("按目标标识精确过滤"),
+      planKeyword: z.string().optional().describe("按 Plan 关键词过滤"),
+      keyword: z.string().optional().describe("关键词搜索"),
+      sinceMinutes: z.number().optional().describe("时间窗口起始（分钟前）"),
+      limit: z.number().optional().default(20).describe("返回最大条数，默认 20，最大 100"),
+    }),
+  }, 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> = {}
+      if (sinceMinutes !== undefined) where.createdAt = { gte: new Date(Date.now() - sinceMinutes * 60 * 1000) }
+      if (targetType) where.targetType = targetType; if (action) where.action = action; if (targetId) where.targetId = targetId; if (planKeyword) where.planKeyword = planKeyword
+      if (keyword) where.OR = [{ action: { contains: keyword, mode: "insensitive" } },{ targetType: { contains: keyword, mode: "insensitive" } },{ targetId: { contains: keyword, mode: "insensitive" } },{ reason: { contains: keyword, mode: "insensitive" } },{ planKeyword: { contains: keyword, mode: "insensitive" } }]
+      const logs = await prisma.devOperation.findMany({ where, orderBy: { createdAt: "desc" }, take: Math.min(limit, 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 过于严格。`)
+      }
+      const fl: string[] = []; if (targetType) fl.push(`targetType=${targetType}`); if (action) fl.push(`action=${action}`); if (targetId) fl.push(`targetId=${targetId}`); if (planKeyword) fl.push(`planKeyword=${planKeyword}`); if (keyword) fl.push(`keyword="${keyword}"`); if (sinceMinutes !== undefined) fl.push(`最近${sinceMinutes}分钟`)
+      const lines = [`=== 开发操作审计日志 (条件: ${fl.length > 0 ? fl.join(", ") : "无过滤条件（最近全部）"}) ===`, `共 ${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 || "(无)"}`)
+        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}`) }
+      lines.push("", "=== 稀疏推理建议 ===", "基于以上审计日志，可以恢复开发上下文。")
+      return textResponse(lines.join("\n"))
+    } catch (error) { return errorResponse(`查询审计日志失败: ${error instanceof Error ? error.message : String(error)}\n可能原因: 数据库未运行或 AuditLog 表不存在。`) }
+  })
+
+  // ===== record_dev_operation (L1111-1212) =====
+  server.registerTool("record_dev_operation", {
+    description: "记录一次开发操作到 DevOperation 表（ADD-7）。AI 助手在对代码进行任何修改/创建/删除操作后，必须调用此工具记录操作审计。\n\n**targetId 路径格式（强制）**：必须使用相对于 workspace 根目录的路径，禁止绝对路径。\n- ✅ src/middleware.ts\n- ✅ ${MAGIC_DIR}/plans/xxx.md\n- ❌ /absolute/path/to/src/middleware.ts",
+    inputSchema: z.object({
+      action: z.string().describe("操作类型: 'MODIFY', 'CREATE', 'DELETE', 'DOC_UPDATED', 'DOC_CREATED' 等"),
+      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().optional().describe("操作前的状态（JSON 字符串）"),
+      afterState: z.string().optional().describe("操作后的状态（JSON 字符串）"),
+      reason: z.string().optional().describe("操作原因"),
+    }),
+  }, async (args: Record<string, string | number | undefined>, _ctx: unknown) => {
+    try {
+      const { action, targetType, targetId, planKeyword, beforeState, afterState, reason } = args
+      const pathWarnings: string[] = []
+      if (targetId && (targetId.startsWith("/") || /^[A-Z]:\\/.test(targetId))) pathWarnings.push(`⚠️ targetId 使用了绝对路径: "${targetId}"。请使用相对路径。`)
+      let parsedBefore: unknown, parsedAfter: unknown
+      try { if (beforeState) parsedBefore = JSON.parse(beforeState); if (afterState) parsedAfter = JSON.parse(afterState) } catch { return errorResponse("beforeState/afterState 必须是有效的 JSON 字符串。") }
+      let systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
+      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 } })
+      const log = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).create({ data: { userId: systemUser.id, planKeyword: planKeyword || "unknown", action, targetType, targetId: targetId || "unknown", beforeState: parsedBefore ?? null, afterState: parsedAfter ?? null, reason: reason || null } })
+      const lines = [`✅ 开发操作已记录`, `  ID: ${log.id}`, `  action: ${action}`, `  targetType: ${targetType}`, `  targetId: ${targetId || "unknown"}`, `  planKeyword: ${planKeyword || "unknown"}`, `  createdAt: ${log.createdAt.toISOString()}`]
+      if (pathWarnings.length > 0) { lines.push(""); lines.push(...pathWarnings) }
+      lines.push("", `📋 落库回查（必须执行）:`, targetId ? `  query_audit_logs({ targetId: "${targetId}" }) — 确认本条记录已写入` : "")
+      return textResponse(lines.join("\n"))
+    } catch (error) { return errorResponse(`记录开发操作失败: ${error instanceof Error ? error.message : String(error)}`) }
+  })
+
+}