add-coder 0.2.8 → 0.2.10

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

@@ -0,0 +1,337 @@
+import * as z from "zod/v4"
+import type { McpServer } from "@modelcontextprotocol/server"
+import { readFile } from "fs/promises"
+import { readdir } from "fs/promises"
+import { stat } from "fs/promises"
+import { existsSync } from "fs"
+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"
+
+export function registerContextTools(server: McpServer) {
+
+  // ===== get_project_context (L166-430) =====
+  server.registerTool(
+    "get_project_context",
+    {
+      description: `获取项目的完整上下文信息：目录结构、技术栈、包管理信息、项目规则（ADD 范式约束）、${MAGIC_DIR}/ 工作流产物（templates/specs/reviews/plans）。AI 助手在 MCP-1（上下文优先）中应在生成代码前调用此工具获取项目真实信息，避免幻觉。\n\nscope='add-state' 返回 ADD 工作流状态快照：当前活跃 Plan、Review 未闭环问题、DPS 门禁状态、待执行操作清单。用于空白对话开局时快速介入 ADD 范式。`,
+      inputSchema: z.object({
+        scope: z.string().optional().describe("获取信息的范围: 'structure' 仅目录结构, 'rules' 仅项目规则, 'package' 仅包信息, 'add-state' ADD 工作流状态, 'all' 全部"),
+      }),
+    },
+    async (args: { scope?: string }) => {
+      try {
+        const scope = args?.scope || "all"
+        const parts: string[] = []
+
+        if (scope === "all" || scope === "package") {
+          const pkg = await readFileSafe(join(PROJECT_ROOT, "package.json"))
+          if (pkg) {
+            const parsed = JSON.parse(pkg)
+            parts.push("=== 项目信息 ===")
+            parts.push(`名称: ${parsed.name}`)
+            parts.push(`版本: ${parsed.version}`)
+            parts.push(`技术栈: Next.js ${parsed.dependencies?.next || "unknown"} + TypeScript + Prisma + LangGraph`)
+            parts.push("")
+            parts.push("核心依赖:")
+            const keyDeps = [
+              "next", "@langchain/langgraph", "@prisma/client", "prisma",
+              "zustand", "@tanstack/react-query", "chromadb", "zod",
+            ]
+            for (const dep of keyDeps) {
+              const ver = parsed.dependencies?.[dep] || parsed.devDependencies?.[dep]
+              if (ver) parts.push(`  ${dep}: ${ver}`)
+            }
+            parts.push("")
+            parts.push("可用脚本:")
+            for (const [name, script] of Object.entries(parsed.scripts || {})) {
+              parts.push(`  ${name}: ${String(script)}`)
+            }
+            parts.push("")
+          }
+        }
+
+        if (scope === "all" || scope === "rules") {
+          const rules = await readFileSafe(join(PROJECT_ROOT, MAGIC_DIR, "rules", "project_rules.md"))
+          if (rules) {
+            parts.push("=== 项目规则 (ADD 范式强制约束) ===")
+            const lines = rules.split("\n")
+            let inCodeBlock = false
+            for (const line of lines) {
+              if (line.startsWith("```")) { inCodeBlock = !inCodeBlock; continue }
+              if (inCodeBlock) continue
+              if (line.startsWith("## ADD-") || line.startsWith("## 项目")) { parts.push(""); parts.push(line) }
+              else if (line.startsWith("###") || line.startsWith("####")) { parts.push(line) }
+            }
+            parts.push("")
+          }
+        }
+
+        if (scope === "all" || scope === "structure" || scope === "add-state") {
+          parts.push("=== ADD 工作流状态 ===")
+          const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+          const reviewsDir = join(PROJECT_ROOT, MAGIC_DIR, "reviews")
+          const specsDir = join(PROJECT_ROOT, MAGIC_DIR, "specs")
+
+          let activePlan = ""
+          let activePlanPath = ""
+          if (existsSync(plansDir)) {
+            const planFiles = (await readdirRecursive(plansDir))
+              .filter(f => f.endsWith(".md") && !f.includes("add-route") && !f.includes("handoff"))
+              .sort()
+            if (planFiles.length > 0) {
+              activePlan = planFiles[planFiles.length - 1]
+              activePlanPath = join(plansDir, activePlan)
+              parts.push(`最近 Plan: ${activePlan}`)
+              const allPlanFiles = await readdirRecursive(plansDir)
+              const addRouteFile = allPlanFiles.find(f => f.includes("add-route"))
+              const planKeyword = activePlan.replace(/-plan-v\d+\.md$/, "")
+              const handoffFiles = allPlanFiles.filter(f => f.includes("handoff"))
+              const hasHandoff = handoffFiles.some(f => f.toLowerCase().includes(planKeyword.toLowerCase()))
+              parts.push(` add-route: ${addRouteFile ? "✅ " + addRouteFile : "❌ 缺失（需回退 Step 0.5）"}`)
+              parts.push(` handoff: ${hasHandoff ? "✅ 已生成" : "❌ 缺失（需回退 Step 0.5）"}`)
+            } else { parts.push("最近 Plan: 无") }
+          } else { parts.push("最近 Plan: 无") }
+
+          let reviewFileName = ""; let reviewP0Count = 0; let reviewP1Count = 0; let reviewBackflowRate = 0
+          if (existsSync(reviewsDir) && activePlan) {
+            const reviewFiles = await readdir(reviewsDir)
+            const planKeyword = activePlan.replace(/-plan-v\d+\.md$/, "")
+            const matchingReview = reviewFiles.find(f => f.toLowerCase().includes(planKeyword.toLowerCase()) && f.includes("-review-v"))
+              || reviewFiles.find(f => f.toLowerCase().includes(planKeyword.toLowerCase()))
+            if (matchingReview) {
+              reviewFileName = matchingReview
+              const reviewContent = await readFileSafe(join(reviewsDir, matchingReview)) || ""
+              const reviewLines = reviewContent.split("\n")
+              let inP0 = false, inP1 = false
+              for (const line of reviewLines) {
+                if (line.match(/P0|ADD.*合规|阻断/)) { inP0 = true; inP1 = false; continue }
+                if (line.match(/P1|架构设计.*缺口/)) { inP0 = false; inP1 = true; continue }
+                if (line.match(/P2|中等|影响评估|决策结论|方案对比/)) { inP0 = false; inP1 = false; continue }
+                if ((inP0 || inP1) && line.trim().startsWith("|") && !line.includes("---")) {
+                  const cols = line.split("|").map(c => c.trim()).filter(Boolean)
+                  if (cols.length >= 4 && cols[0].match(/^\d+$/)) {
+                    if (inP0) reviewP0Count++; else if (inP1) reviewP1Count++
+                  }
+                }
+              }
+              const planContent = await readFileSafe(activePlanPath) || ""
+              if ((reviewP0Count + reviewP1Count) > 0 && planContent) {
+                const indicators = ["add-route", "specs/", "handoff", "Task Group", "perExpertTopK", "agri_tech", "ChromaCollectionManager", "迁移路线图", "8 个 Expert", "冗余策略"]
+                let hit = 0
+                for (const ind of indicators) { if (planContent.toLowerCase().includes(ind.toLowerCase())) hit++ }
+                reviewBackflowRate = Math.min(100, Math.round((hit / Math.max(reviewP0Count + reviewP1Count, 1)) * 100))
+              }
+              parts.push(""); parts.push(`关联 Review: ${matchingReview}`)
+              parts.push(`  P0 问题: ${reviewP0Count} 个, P1 问题: ${reviewP1Count} 个`)
+              parts.push(`  回流状态: 约 ${reviewBackflowRate}%`)
+              parts.push(reviewBackflowRate < 70 ? "  ⚠️ Review 结论未充分回流至 Plan — 需执行 0.6.5 卡位" : "  ✅ Review 结论基本回流至 Plan")
+            } else { parts.push(""); parts.push("关联 Review: 无（该 Plan 尚未生成方案评审）") }
+          }
+
+          if (activePlan) {
+            const planKeyword = activePlan.replace(/-plan-v\d+\.md$/, "")
+            const specDirs = existsSync(specsDir) ? await readdir(specsDir) : []
+            const matchingSpec = specDirs.find(d => d.toLowerCase().includes(planKeyword.toLowerCase()))
+            parts.push("")
+            if (matchingSpec) {
+              const hasSpec = existsSync(join(specsDir, matchingSpec, "spec.md"))
+              const hasTasks = existsSync(join(specsDir, matchingSpec, "tasks.md"))
+              const hasChecklist = existsSync(join(specsDir, matchingSpec, "checklist.md"))
+              parts.push(`Specs: ${matchingSpec}/`)
+              parts.push(`  spec.md:      ${hasSpec ? "✅" : "❌"}`)
+              parts.push(`  tasks.md:     ${hasTasks ? "✅" : "❌"}`)
+              parts.push(`  checklist.md: ${hasChecklist ? "✅" : "❌"}`)
+            } else { parts.push("Specs: ❌ 缺失") }
+          }
+
+          parts.push(""); parts.push("=== 待执行 ADD 操作（按流程顺序） ===")
+          const todoItems: string[] = []
+          if (!activePlan) { todoItems.push("1. [未开始] 用户提出需求 → 生成 Plan") }
+          else {
+            if (!reviewFileName) { todoItems.push("1. [Step 0] 生成 Plan Review（ADD-9 方案评审）") }
+            else if (reviewP0Count + reviewP1Count > 0 && reviewBackflowRate < 70) {
+              todoItems.push("1. [0.6.5] Review 结论回流至 Plan — P0/P1 未写入 Plan 体")
+              todoItems.push("2. [check_dps] DPS 门禁预计不通过（回流完整度 < 70%）")
+            }
+            const allPlanDir = await readdirRecursive(plansDir)
+            const hasAddRoute = allPlanDir.some(f => f.includes("add-route"))
+            if (!hasAddRoute && reviewBackflowRate >= 70) { todoItems.push("2. [Step 0.5] 生成 add-route") }
+            const planKw = activePlan.replace(/-plan-v\d+\.md$/, "")
+            const sd = existsSync(specsDir) ? await readdir(specsDir) : []
+            if (!sd.some(d => d.toLowerCase().includes(planKw.toLowerCase())) && reviewBackflowRate >= 70) { todoItems.push("3. [Step 0] 生成 Specs 三元组") }
+            if (todoItems.length === 0) { todoItems.push("✅ ADD 就绪 — check_dps ≥ 85 后可进入 Step 1") }
+          }
+          for (const item of todoItems) parts.push(item)
+          parts.push(""); parts.push("快速指令: 说「执行 add-paradigm Step 0」进入文档先行流程")
+          parts.push("          说「将 Review 结论回流至 Plan」触发 0.6.5 卡位")
+        }
+
+        if (scope === "all" || scope === "structure") {
+          parts.push("=== 项目目录结构（顶层） ===")
+          const topDirs = [MAGIC_DIR, "src", "prisma", "scripts", "docs", "data", "public"]
+          for (const dir of topDirs) {
+            const fullPath = join(PROJECT_ROOT, dir)
+            if (existsSync(fullPath)) { const entries = await readdir(fullPath); parts.push(`  ${dir}/ (${entries.length} 项)`) }
+          }
+          parts.push(""); parts.push("=== src/ 子目录结构 ===")
+          const srcDirs = ["agents", "app", "components", "lib", "services", "stores", "types"]
+          for (const dir of srcDirs) {
+            const fullPath = join(PROJECT_ROOT, "src", dir)
+            if (existsSync(fullPath)) {
+              const entries = await readdir(fullPath)
+              const items = (await Promise.all(entries.slice(0, 15).map(async (e) => { const s = await stat(join(fullPath, e)); return s.isDirectory() ? `${e}/` : e }))).join(", ")
+              parts.push(`  src/${dir}/ (${entries.length} 项): ${items})`)
+            }
+          }
+          parts.push(""); parts.push(`=== ${MAGIC_DIR}/ ADD 工作流产物 ===`)
+          const magicDirs = [
+            { dir: "templates", desc: "ADD 文档模板（11 个）" }, { dir: "specs", desc: "specs 三元组（spec+tasks+checklist）" },
+            { dir: "reviews", desc: "方案审查 + 实现审查 + 运行时审查" }, { dir: "plans", desc: "Plan + handoff 交接手册" },
+            { dir: "rules", desc: "项目规则 + 理论→实践映射" }, { dir: "skills", desc: "SKILL 行为定义（add-paradigm / session-init）" },
+            { dir: "scripts", desc: "工具脚本 + MCP 服务器" },
+          ]
+          for (const { dir, desc } of magicDirs) {
+            const fullPath = join(PROJECT_ROOT, MAGIC_DIR, dir)
+            if (existsSync(fullPath)) { const entries = await readdir(fullPath); parts.push(`  ${MAGIC_DIR}/${dir}/ (${entries.length} 项) — ${desc}`) }
+          }
+        }
+        return textResponse(parts.join("\n"))
+      } catch (error) { return errorResponse(`获取项目上下文失败: ${error instanceof Error ? error.message : String(error)}`) }
+    }
+  )
+
+  // ===== get_db_schema (L433-522) =====
+  server.registerTool(
+    "get_db_schema",
+    {
+      description: "获取 Prisma 数据库 Schema 定义（MCP-1 上下文优先）。返回指定模型的结构、字段、关系。AI 助手在编写数据库查询代码时应调用此工具获取真实的 Schema 信息，避免凭记忆假设。",
+      inputSchema: z.object({ model: z.string().optional().describe("可选的模型名称（不区分大小写）。不指定则返回所有模型概况。指定则返回该模型的完整字段定义。") }),
+    },
+    async (args: { model?: string }) => {
+      try {
+        const schemaPath = join(PROJECT_ROOT, "prisma", "schema.prisma")
+        const schema = await readFileSafe(schemaPath)
+        if (!schema) return errorResponse("未找到 prisma/schema.prisma 文件")
+        const modelName = args?.model?.toLowerCase()
+        if (modelName) {
+          const modelRegex = new RegExp(`model\\s+${modelName}\\s*\\{`, "i")
+          const match = schema.match(modelRegex)
+          if (match) {
+            const startIdx = match.index ?? 0; const braceIdx = schema.indexOf("{", startIdx)
+            if (braceIdx !== -1) { let depth = 1; let endIdx = braceIdx + 1; while (depth > 0 && endIdx < schema.length) { if (schema[endIdx] === "{") depth++; else if (schema[endIdx] === "}") depth--; endIdx++ }; return textResponse(`=== Model: ${args.model} ===\n\nmodel ${args.model} ${schema.slice(braceIdx, endIdx)}`) }
+          }
+          const enumMatch = schema.match(new RegExp(`enum\\s+${modelName}\\s*\\{`, "i"))
+          if (enumMatch) return textResponse(`=== Enum: ${args.model} ===\n\n可用的枚举值见不传参调用结果。`)
+          return errorResponse(`未找到模型或枚举: ${args.model}。可用模型见不传参调用结果。`)
+        }
+        const models: Array<{ name: string; fieldCount: number }> = []
+        const modelRegex = /model\s+(\w+)\s*\{/g; let m
+        while ((m = modelRegex.exec(schema)) !== null) {
+          const startIdx = m.index; const braceIdx = schema.indexOf("{", startIdx)
+          if (braceIdx !== -1) { let depth = 1; let endIdx = braceIdx + 1; while (depth > 0 && endIdx < schema.length) { if (schema[endIdx] === "{") depth++; else if (schema[endIdx] === "}") depth--; endIdx++ }; const body = schema.slice(braceIdx, endIdx); const fieldCount = body.split("\n").filter((l: string) => l.trim() && !l.trim().startsWith("//") && !l.trim().startsWith("@@")).length; models.push({ name: m[1], fieldCount }) }
+        }
+        const enums: string[] = []; const enumRegex = /enum\s+(\w+)\s*\{/g
+        while ((m = enumRegex.exec(schema)) !== null) { enums.push(m[1]) }
+        const parts = ["=== Prisma Schema 概况 ===", "", `模型 (${models.length} 个):`]
+        for (const model of models) parts.push(`  ${model.name} (${model.fieldCount} 字段)`)
+        if (enums.length > 0) { parts.push(""); parts.push(`枚举 (${enums.length} 个): ${enums.join(", ")}`) }
+        parts.push("", '提示: 指定 model 参数获取完整字段定义，例如: get_db_schema({ model: "User" })')
+        return textResponse(parts.join("\n"))
+      } catch (error) { return errorResponse(`获取 Schema 失败: ${error instanceof Error ? error.message : String(error)}`) }
+    }
+  )
+
+  // ===== get_audit_logger_pattern (L524-612) =====
+  server.registerTool(
+    "get_audit_logger_pattern",
+    {
+      description: "获取指定域的审计日志器完整代码或模式（MCP-1 上下文优先）。历史域（'knowledge-base', 'agent'）返回已有的混合式日志器代码；新域返回三层分离式模板（ADD-4 三层可插拔架构）:\n- Layer 1 开发审计（dev-logger）: console + file + DB metadata，可插拔\n- Layer 2 运行时审计（audit）: console + AuditLog 表，始终开启\n- Layer 3 调试日志: console only，LOG_LEVEL 控制\n新业务域必须使用三层分离模式。",
+      inputSchema: z.object({ domain: z.string().describe("审计日志器域: 'knowledge-base', 'agent'（历史混合式），或新域如 'personnel'（三层分离式）") }),
+    },
+    async (args: { domain: string }) => {
+      try {
+        const domain = args?.domain; if (!domain) return errorResponse("domain 参数不能为空")
+        const filePath = (() => { switch(domain) { case "knowledge-base": return join(PROJECT_ROOT, "src", "lib", "audit-logger.ts"); case "agent": return join(PROJECT_ROOT, "src", "lib", "agent-audit-logger.ts"); default: return "" } })()
+        if (filePath) {
+          const content = await readFileSafe(filePath); if (!content) return errorResponse(`未找到 ${domain} 审计日志器文件: ${filePath}`)
+          const meta: Record<string, { prefix: string; logDir: string; logFile: string }> = { "knowledge-base": { prefix: "[KB-AUDIT]", logDir: "logs/knowledge-base/", logFile: "kb-audit.log" }, "agent": { prefix: "[AGENT-AUDIT]", logDir: "logs/agent/", logFile: "agent-audit.log" } }
+          const m = meta[domain]
+          const parts = [`=== ${domain} 审计日志器（历史混合式，Layer 1 + Layer 2 未分离） ===`, `前缀: ${m.prefix}`, `日志目录: ${m.logDir}`, `日志文件: ${m.logFile}`, `文件路径: ${relative(PROJECT_ROOT, filePath)}`, "", "=== 完整代码 ===", content, "", "=== 模式要点 ===", "1. PREFIX 常量: [DOMAIN-AUDIT] 格式", `2. LOG_DIR: logs/domain/ 目录 (当前: ${m.logDir})`, "3. AuditPhase 类型: 枚举所有业务阶段", "4. audit() / auditPhaseStart() / auditPhaseEnd() 三函数", "5. readRecentLogs() / clearLogs() 读写函数", "6. ENABLE_FILE_LOG 环境变量控制，开发环境默认启用", "7. 三通道输出: console.log + fs.appendFile + 数据库回写", "", "⚠️ 注意: 这是历史混合式模式。新建业务域应使用三层分离模式（调用 generate_audit_logger 生成）。"]
+          return textResponse(parts.join("\n"))
+        }
+        const featureCap = domain.split("-").map((s: string) => s.charAt(0).toUpperCase() + s.slice(1)).join("")
+        const fnPrefix = featureCap.charAt(0).toLowerCase() + featureCap.slice(1)
+        return textResponse(`=== ${domain} 三层分离式审计日志器（新模式，ADD-4） ===\n\n新建 ${domain} 业务域应调用 generate_audit_logger 生成两个文件：\n\n--- 文件1: src/lib/${domain}-dev-logger.ts (Layer 1 开发审计，可插拔) ---\n仅在 NODE_ENV=development 时生效，用于 AI 合规检查。\nADD-4 三通道输出:\n  1. console.log — ${fnPrefix}Audit / ${fnPrefix}AuditPhaseStart / ${fnPrefix}AuditPhaseEnd\n  2. fs.appendFile — writeToFile（自动）\n  3. DB metadata — build${featureCap}DevAudit() 构建记录 → 业务服务层 saveAuditData 写入\n包含函数: auditPhaseStart / auditPhaseEnd / audit / buildXxxDevAudit / readRecentLogs / clearLogs\n\n--- 文件2: src/lib/${domain}-audit.ts (Layer 2 运行时业务审计，不可插拔) ---\n始终开启，用于业务记录和前端查询。\nADD-4 三通道输出:\n  1. console.log — record${featureCap}Audit\n  2. fs.appendFile — (AuditLog 表替代文件写入)\n  3. DB AuditLog 表 — prisma.auditLog.create\n包含函数: record${featureCap}Audit()\n\n新建业务域必须使用三层分离模式（而非历史混合式）。详见项目规则 ADD-4「三层可插拔架构」。`)
+      } catch (error) { return errorResponse(`获取审计日志器失败: ${error instanceof Error ? error.message : String(error)}`) }
+    }
+  )
+
+  // ===== get_add_template (L1718-1780) =====
+  server.registerTool(
+    "get_add_template",
+    {
+      description: "获取 ADD 工作流的文档模板（ADD-0.1 广义文档先行）。ADD 范式要求每次生成文档产物前必须先读取对应模板，禁止凭记忆生成——模板可能在迭代中已更新。\n\n可用模板（12 个）:\n- plan-template.md — 需求方案\n- add-route-template.md — Plan→ADD 九阶段执行映射（轻量模式，适合前端/小项目）\n- add-route-template-heavyweight.md — Plan→ADD 九阶段执行映射（重型模式，适合后端/管线/合规场景，强制 check_spec_sync 文档-代码交叉校验）\n- spec-template.md — 功能规格\n- tasks-template.md — 任务拆分\n- checklist-template.md — 验收清单\n- review-template.md — 方案审查（ADD-9）\n- review-implementation-template.md — 实现审查（ADD-10）\n- review-runtime-template.md — 运行时纠偏（ADD-11）\n- handoff-template.md — 交接总览索引\n- handoff-single-round-template.md — 单轮交接（9 章节）\n- handoff-multi-round-template.md — 多轮交接（13 子章节/轮）\n\n本项目默认使用重型 add-route 模板。",
+      inputSchema: z.object({ template: z.string().describe("模板名称（不含 .md 后缀），如 'plan-template', 'add-route-template', 'spec-template', 'review-template'。传 'list' 获取所有模板列表。") }),
+    },
+    async (args: { template: string }) => {
+      try {
+        const { template } = args; if (!template) return errorResponse("template 参数不能为空")
+        const templatesDir = join(PROJECT_ROOT, MAGIC_DIR, "templates")
+        if (template === "list") {
+          const entries = await readdir(templatesDir); const mdFiles = entries.filter(f => f.endsWith(".md"))
+          const parts = [`=== ADD 模板列表（${mdFiles.length} 个） ===`, ""]
+          for (const f of mdFiles) { const content = await readFileSafe(join(templatesDir, f)); const firstLine = content?.split("\n")[0] || ""; const title = firstLine.replace(/^#+\s*/, "").trim() || f; parts.push(`  ${f.replace(".md", "")} — ${title}`) }
+          parts.push("", '用法: get_add_template({ template: "plan-template" })'); return textResponse(parts.join("\n"))
+        }
+        const fileName = template.endsWith(".md") ? template : `${template}.md`
+        const filePath = join(templatesDir, fileName)
+        if (!existsSync(filePath)) return errorResponse(`未找到模板: ${fileName}\n可用模板请调用: get_add_template({ template: "list" })`)
+        const content = await readFile(filePath, "utf-8")
+        return textResponse([`=== ADD 模板: ${fileName} ===`, `路径: ${MAGIC_DIR}/templates/${fileName}`, "", content, "", "=== 使用提示 ===", "1. 复制模板到目标路径，替换 {占位符} 为实际内容", "2. 禁止凭记忆生成——模板可能在迭代中已更新", "3. 生成文档后调用 record_dev_operation 记录（targetType 视产物类型而定）"].join("\n"))
+      } catch (error) { return errorResponse(`获取 ADD 模板失败: ${error instanceof Error ? error.message : String(error)}`) }
+    }
+  )
+
+  // ===== get_spec_context (L1782-1873) =====
+  server.registerTool(
+    "get_spec_context",
+    {
+      description: `获取 ${MAGIC_DIR}/specs/ 下指定任务的 specs 三元组上下文（spec.md + tasks.md + checklist.md）。ADD 工作流中每个原子事务对应一个 specs 三元组目录，形成「需求→执行→验收」闭环。\n\nAI 助手在 ADD 范式 Step 3 执行业务逻辑时，应调用此工具获取当前任务的 spec/tasks/checklist 上下文，确保实现与规格一致。`,
+      inputSchema: z.object({
+        task: z.string().describe(`任务名（即 ${MAGIC_DIR}/specs/ 下的目录名），如 'co-agent-response-strategy'。传 'list' 获取所有任务列表。`),
+        file: z.string().optional().describe("指定读取三元组中的某个文件: 'spec', 'tasks', 'checklist'。不传则返回全部三个文件。"),
+      }),
+    },
+    async (args: { task: string; file?: string }) => {
+      try {
+        const { task, file } = args; if (!task) return errorResponse("task 参数不能为空")
+        const specsDir = join(PROJECT_ROOT, MAGIC_DIR, "specs")
+        if (task === "list") {
+          const entries = await readdir(specsDir, { withFileTypes: true }); const dirs = entries.filter(e => e.isDirectory()).map(e => e.name)
+          const parts = [`=== Specs 任务列表（${dirs.length} 个） ===`, ""]
+          for (const dir of dirs) {
+            const specPath = join(specsDir, dir, "spec.md"); const content = await readFileSafe(specPath)
+            const firstLine = content?.split("\n")[0] || ""; const title = firstLine.replace(/^#+\s*/, "").trim() || dir
+            const hasTasks = existsSync(join(specsDir, dir, "tasks.md")); const hasChecklist = existsSync(join(specsDir, dir, "checklist.md"))
+            parts.push(`  ${(hasTasks && hasChecklist) ? "✅" : "⚠️ 不完整"} ${dir} — ${title}`)
+          }
+          parts.push("", '用法: get_spec_context({ task: "co-agent-response-strategy" })'); return textResponse(parts.join("\n"))
+        }
+        const taskDir = join(specsDir, task)
+        if (!existsSync(taskDir)) return errorResponse(`未找到 specs 任务: ${task}\n可用任务请调用: get_spec_context({ task: "list" })`)
+        const trinity: Record<string, string> = { spec: "spec.md", tasks: "tasks.md", checklist: "checklist.md" }
+        const parts = [`=== Specs 三元组: ${task} ===`, `路径: ${MAGIC_DIR}/specs/${task}/`, ""]
+        if (file && trinity[file]) {
+          const fp = join(taskDir, trinity[file]); const content = await readFileSafe(fp)
+          if (content) { parts.push(`=== ${trinity[file]} ===`); parts.push(content) } else { parts.push(`⚠️ ${trinity[file]} 不存在`) }
+        } else {
+          for (const [_key, fn] of Object.entries(trinity)) { const fp = join(taskDir, fn); const content = await readFileSafe(fp); if (content) { parts.push(`=== ${fn} ===`); parts.push(content); parts.push("") } else { parts.push(`⚠️ ${fn} 不存在（三元组不完整）`); parts.push("") } }
+        }
+        return textResponse(parts.join("\n"))
+      } catch (error) { return errorResponse(`获取 Spec 上下文失败: ${error instanceof Error ? error.message : String(error)}`) }
+    }
+  )
+
+}

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

@@ -0,0 +1,42 @@
+import * as z from "zod/v4"
+import type { McpServer } from "@modelcontextprotocol/server"
+import { readdir } from "fs/promises"
+import { existsSync } from "fs"
+import { join } from "path"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { readFileSafe } from "../shared/fs.js"
+import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+
+export function registerDocsTools(server: McpServer) {
+
+  server.registerTool("find_related_docs", {
+    description: `搜索与当前变更相关的项目文档（ADD-0.1 广义文档先行）。搜索范围:\n1. docs/ 目录 — 需求文档、架构文档、规范文档\n2. ${MAGIC_DIR}/ 产物 — plans/(Plan+add-route+handoff)、specs/(三元组)、reviews/(方案审查+实现审查+运行时审查)\n\nAI 助手在 ADD 范式 Step 0 中应调用此工具查找需要更新的 docs/ 文档。`,
+    inputSchema: z.object({
+      query: z.string().describe("搜索关键词"),
+      category: z.string().optional().describe("文档类别过滤: 'requirement', 'architecture', 'standard', 'plan', 'add-route', 'spec', 'review', 'handoff'"),
+    }),
+  }, async (args, _ctx) => {
+    try {
+      const { query, category } = args
+      const docsDir = join(PROJECT_ROOT, "docs")
+      const catPrefixes: Record<string, string[]> = { requirement: ["00-需求"], architecture: ["01-架构","02-架构"], standard: ["02-规范","03-规范"] }
+      const magicCat: Record<string, string> = { plans: "plan", specs: "spec", reviews: "review" }
+      const allFiles: Array<{ path: string; relativePath: string; category: string }> = []
+      const walk = async (dir: string, rel: string, src: "docs" | "magic" = "docs") => {
+        try { for (const e of await readdir(dir, { withFileTypes: true })) { const fp = join(dir, e.name); const rp = rel ? `${rel}/${e.name}` : e.name; if (e.isDirectory()) await walk(fp, rp, src); else if (e.name.endsWith(".md") || e.name.endsWith(".html")) { let c = "unknown"; if (src === "magic") { const td = rp.split("/")[0]; c = magicCat[td] || "unknown"; if (td === "plans" && e.name.includes("handoff")) c = "handoff"; if (td === "plans" && e.name.includes("add-route")) c = "add-route" } else { for (const [cat, pf] of Object.entries(catPrefixes)) if (pf.some(p => rp.includes(p))) { c = cat; break } }; allFiles.push({ path: fp, relativePath: rp, category: c }) } } } catch { /* fallthrough */ }
+      }
+      await walk(docsDir, "", "docs")
+      for (const md of ["plans","specs","reviews"]) { const p = join(PROJECT_ROOT, MAGIC_DIR, md); if (existsSync(p)) await walk(p, md, "magic") }
+      let filtered = allFiles
+      if (category) { const ac: Record<string, string[]> = { ...catPrefixes, plan: ["plan"], "add-route": ["add-route"], spec: ["spec"], review: ["review"], handoff: ["handoff"] }; if (ac[category]) filtered = allFiles.filter(f => f.category === category) }
+      const ql = query.toLowerCase(); const matches: Array<{ path: string; relativePath: string; category: string; title: string; relevance: number }> = []
+      for (const d of filtered) { let r = 0; if (d.relativePath.toLowerCase().includes(ql)) r += 3; let t = ""; try { const c = await readFileSafe(d.path); if (c) { const m = c.match(/^#\s+(.+)/m); t = m ? m[1].trim() : c.split("\n")[0].replace(/^#+\s*/,"").replace(/[#*]/g,"").trim(); if (c.toLowerCase().includes(ql)) r += 2 } } catch { /* fallthrough */ }; if (r > 0) matches.push({ ...d, title: t || d.relativePath.split("/").pop()!, relevance: r }) }
+      matches.sort((a,b) => b.relevance - a.relevance)
+      const p: string[] = [`=== 项目文档搜索: "${query}" ===`, `匹配文档数: ${matches.length}`, ""]
+      if (!matches.length) { p.push("未找到匹配的文档。"); p.push("=== 可用文档列表 ==="); for (const d of allFiles) p.push(`  [${d.category}] ${d.relativePath}`) }
+      else { for (const d of matches) p.push(`  [相关度 ${d.relevance}] ${d.relativePath}\n  标题: ${d.title}\n`) }
+      return textResponse(p.join("\n"))
+    } catch (error) { return errorResponse(`搜索文档失败: ${error instanceof Error ? error.message : String(error)}`) }
+  })
+
+}

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

@@ -0,0 +1,135 @@
+import * as z from "zod/v4"
+import type { McpServer } from "@modelcontextprotocol/server"
+import { existsSync } from "fs"
+import { join, basename } from "path"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+import { prisma } from "../shared/prisma.js"
+
+export function registerGatewayTools(server: McpServer) {
+
+  // ===== check_add_route_status (L1448-1716) =====
+  server.registerTool("check_add_route_status", {
+    description: `ADD 范式守卫工具：交叉校验 add-route 文件的审计日志记录与文件系统存在性，并扫描文件内容统计 Step 完成度。\n必须在 Plan 进入 Handoff 或 Step 3 前调用。\n\n返回状态:\n- 'normal' — 审计日志有记录、文件存在、Step 全部闭环\n- 'warn_step_incomplete' — 文件存在但存在未勾选的 Step 产出项\n- 'file_missing' — 审计日志有记录但文件不存在\n- 'never_generated' — 审计日志无记录且文件不存在，禁止进入 Step 3`,
+    inputSchema: z.object({ planKeyword: z.string().describe("Plan 文件的关键词") }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const planKeyword = args.planKeyword; if (!planKeyword) return errorResponse("planKeyword 参数不能为空")
+      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+      let auditHasRecord = false; const auditRecords: Array<{action:string;targetId:string;createdAt:Date}> = []
+      try { const logs = await (prisma.auditLog as Record<string, (...a: unknown[]) => unknown>).findMany({ where: { OR: [{targetId:{contains:"add-route",mode:"insensitive"}},{targetId:{contains:planKeyword,mode:"insensitive"}},{reason:{contains:"add-route",mode:"insensitive"}}] }, orderBy:{createdAt:"desc"}, take:20 })
+        const pl = planKeyword.toLowerCase()
+        for (const l of logs) { const ti=(l.targetId||"").toLowerCase(); const r=(l.reason||"").toLowerCase(); if ((ti.includes("add-route")&&ti.includes(pl))||(r.includes("add-route")&&r.includes(pl))) { auditHasRecord=true; auditRecords.push({action:l.action,targetId:l.targetId||"unknown",createdAt:l.createdAt}) } }
+      } catch { /* empty */ }
+      let fileExists=false; const matchedFiles:string[]=[]
+      try { const entries=await readdirRecursive(plansDir); for(const e of entries) { const el=e.toLowerCase(); if(el.includes("add-route")&&el.includes(planKeyword.toLowerCase())) { fileExists=true; matchedFiles.push(e) } } } catch { /* empty */ }
+      const parts=[`=== ADD 守卫：add-route 存在性交叉校验 ===`,`Plan 关键词: "${planKeyword}"`,`预期路径: ${MAGIC_DIR}/plans/{需求域名}-{核心内容}-add-route-v1.md`,""]
+      const scanCheckboxes=(content:string)=>{ let t=0,c=0,u=0; const inc:string[]=[]; const ss:Array<{step:string;checked:number;unchecked:number}>=[]; let cs=""; for(const l of content.split("\n")){ const sm=l.match(/^##\s+Step\s+(\d+(?:\.\d+)?)/); if(sm){ if(cs&&(c>0||u>0)) ss.push({step:cs,checked:c,unchecked:u}); cs=sm[1]; c=0; u=0; continue } const cm=l.match(/^\s*-\s+\[([ xX])\]\s/); if(cm){ t++; if(cm[1]==="x"||cm[1]==="X") c++; else { u++; if(cs&&!inc.includes(cs)) inc.push(cs) } } } if(cs&&(c>0||u>0)) ss.push({step:cs,checked:c,unchecked:u}); return {total:t,checked:c,unchecked:u,incomplete:inc,statuses:ss} }
+      if(auditHasRecord&&fileExists){ const sc=scanCheckboxes(await readFileSafe(join(plansDir,matchedFiles[0]))||""); const ok=sc.unchecked===0; parts.push(`状态: ${ok?"✅ normal":"⚠️ warn_step_incomplete"}`,ok?"操作: 继续执行后续流程":"操作: ⚠️ 存在未闭环 Step",""); parts.push("=== 审计记录 ==="); for(const r of auditRecords.slice(0,5)) parts.push(`  [${r.createdAt.toISOString()}] ${r.action} → ${r.targetId}`); parts.push(""); parts.push("=== 匹配文件 ==="); for(const f of matchedFiles) parts.push(`  ${MAGIC_DIR}/plans/${f}`); parts.push("","=== Step 完成度扫描 ==="); if(sc.total===0) parts.push("  ⚠️ 未检测到 checkbox"); else { const rate=Math.round((sc.checked/sc.total)*100); parts.push(`  整体: ${sc.checked}/${sc.total} (${rate}%)`); for(const s of sc.statuses) parts.push(`  Step ${s.step}: ${s.unchecked===0?"✅":"⬜"} ${s.checked}/${s.checked+s.unchecked}`); if(sc.incomplete.length>0){ parts.push("",`  ⚠️ 未闭环 Step: ${sc.incomplete.join(", ")}`) } } return textResponse(parts.join("\n")) }
+      if(auditHasRecord&&!fileExists){ parts.push("状态: ❌ file_missing — add-route 文件丢失","操作: 中断推理，询问用户原因","","审计日志显示 add-route 曾经存在但文件系统中找不到。","","=== 审计记录 ==="); for(const r of auditRecords.slice(0,5)) parts.push(`  [${r.createdAt.toISOString()}] ${r.action} → ${r.targetId}`); return errorResponse(parts.join("\n")) }
+      if(!auditHasRecord&&!fileExists){ parts.push("状态: ❌ never_generated — add-route 文件从未生成","操作: 禁止进入 Step 3，强制回退至 Step 0.5","",`在 ${MAGIC_DIR}/plans/ 下未找到包含 "${planKeyword}" 和 "add-route" 的文件。`,"","=== 必须执行的步骤 ===","1. 回退到 Step 0.5","2. 调用 get_add_template({ template: \"add-route-template\" })","3. 按模板填充",`4. 保存为 ${MAGIC_DIR}/plans/{需求域名}-{核心内容}-add-route-v1.md`,"5. 调用 record_dev_operation 记录","6. 重新调用本工具验证"); return errorResponse(parts.join("\n")) }
+      const scW=scanCheckboxes(await readFileSafe(join(plansDir,matchedFiles[0]))||""); const wOk=scW.unchecked===0; parts.push(`状态: ⚠️ warn${scW.total>0&&!wOk?"_step_incomplete":""} — 文件存在但审计日志无记录`,"操作: 允许继续，但建议补记录","","=== 匹配文件 ==="); for(const f of matchedFiles) parts.push(`  ${MAGIC_DIR}/plans/${f}`); if(scW.total>0){ parts.push("","=== Step 完成度扫描 ===",`  整体: ${scW.checked}/${scW.total} (${Math.round((scW.checked/scW.total)*100)}%)`); if(scW.incomplete.length>0) parts.push(`  ⚠️ 未闭环 Step: ${scW.incomplete.join(", ")}`) }; parts.push("","=== 建议 ===","1. 调用 record_dev_operation 补记录"); if(scW.incomplete.length>0) parts.push("2. 调用 check_add_route_completeness 获取详细清单"); return textResponse(parts.join("\n"))
+    } catch(e) { return errorResponse(`add-route 存在性校验失败: ${e instanceof Error?e.message:String(e)}`) }
+  })
+
+  // ===== check_spec_sync (L2103-2580) =====
+  server.registerTool("check_spec_sync", {
+    description: "ADD 重型模式文档-代码交叉校验工具。扫描 Plan → tasks.md → checklist.md → git diff → ADD-7 审计记录，报告四者之间的不一致。",
+    inputSchema: z.object({ planKeyword: z.string().describe("Plan 文件的关键词") }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const plansDir=join(PROJECT_ROOT,MAGIC_DIR,"plans"), specsDir=join(PROJECT_ROOT,MAGIC_DIR,"specs"); const lines:string[]=["=== check_spec_sync 文档-代码交叉校验 ===",""]
+      if(!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
+      const planFiles=(await readdirRecursive(plansDir)).filter(f=>f.endsWith(".md"))
+      let planMatch=planFiles.find(f=>f.toLowerCase().includes(args.planKeyword.toLowerCase())&&f.includes("-plan-v"))
+      if(!planMatch) planMatch=planFiles.find(f=>f.toLowerCase().includes(args.planKeyword.toLowerCase()))
+      if(!planMatch) return errorResponse(`未找到匹配的 Plan 文件（关键词: ${args.planKeyword}）`)
+      const planPath=join(plansDir,planMatch); const planContent=await readFileSafe(planPath); lines.push(`Plan: ${planMatch}`)
+      let specDirName=""
+      if(planContent){ const sm=planContent.match(/Spec[:|\s`]+\.?(qoder|claude|add|vscode)\/specs\/([^/`\s]+)/); if(sm) specDirName=sm[2] }
+      if(!specDirName){ const tm=planContent?.match(/Tasks[:|\s`]+\.?(qoder|claude|add|vscode)\/specs\/([^/`\s]+)/); if(tm) specDirName=tm[2] }
+      if(!specDirName) specDirName=basename(planMatch).replace(/-plan-v\d+\.md$/,"")
+      lines.push(`Spec: ${specDirName}`,"")
+      let ut=0,ct=0; const tp=join(specsDir,specDirName,"tasks.md"); const tc=await readFileSafe(tp)||""; if(tc){ ut=(tc.match(/^- \[ \] Task/gm)||[]).length; ct=(tc.match(/^- \[x\] Task/gm)||[]).length; lines.push(`tasks.md: ${ct} 已完成 / ${ut} 未完成`) } else lines.push("tasks.md: 不存在")
+      let uc=0,cc=0; const cp=join(specsDir,specDirName,"checklist.md"); const clc=await readFileSafe(cp)||""; if(clc){ uc=(clc.match(/^- \[ \] /gm)||[]).length; cc=(clc.match(/^- \[x\] /gm)||[]).length; lines.push(`checklist.md: ${cc} 已勾选 / ${uc} 未勾选`) } else lines.push("checklist.md: 不存在")
+      lines.push(""); if(ut===0&&uc===0) lines.push("  ✅ tasks.md 和 checklist.md 全部项已勾选"); else { if(ut>0) lines.push(`  📝 tasks.md 有 ${ut} 个未完成 Task`); if(uc>0) lines.push(`  📝 checklist.md 有 ${uc} 个未勾选项`) }
+      try{ const {spawnSync}=await import("child_process"); const diff=spawnSync("git",["diff","--name-only"],{cwd:PROJECT_ROOT,encoding:"utf-8",timeout:5000}); const cf=(diff.stdout||"").trim().split("\n").filter(Boolean); lines.push(`Git diff: ${cf.length} 个变更文件`) } catch{ lines.push("Git diff: 无法获取") }
+      return textResponse(lines.join("\n"))
+    } catch(e) { return errorResponse(`check_spec_sync 失败: ${e instanceof Error?e.message:String(e)}`) }
+  })
+
+  // ===== check_add_route_completeness (L2582-2775) =====
+  server.registerTool("check_add_route_completeness", {
+    description: "ADD 范式守卫工具：扫描 add-route 文件的 Step 完成度。统计 add-route 中每个 Step 的 [ ] 和 [x] 勾选项数量，返回逐 Step 完成率及整体状态。",
+    inputSchema: z.object({ planKeyword: z.string().describe("Plan 文件的关键词") }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const pp=args.planKeyword; if(!pp) return errorResponse("planKeyword 参数不能为空")
+      const plansDir=join(PROJECT_ROOT,MAGIC_DIR,"plans"); if(!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
+      const allFiles=await readdirRecursive(plansDir); const arFile=allFiles.find(f=>f.toLowerCase().includes(pp.toLowerCase())&&f.includes("add-route"))
+      if(!arFile) return errorResponse(`未找到匹配的 add-route 文件（关键词: ${pp}）`)
+      const content=await readFileSafe(join(plansDir,arFile)); if(!content) return errorResponse("add-route 文件无法读取")
+      const steps:Record<string,{checked:number;unchecked:number}>= {}; let cur=""; let tc=0,tu=0
+      for(const l of content.split("\n")){ const sm=l.match(/^##\s+Step\s+(\d+(?:\.\d+)?)/); if(sm){ cur=sm[1]; steps[cur]={checked:0,unchecked:0}; continue }; const cm=l.match(/^\s*-\s+\[([ xX])\]\s/); if(cm){ tc++; if(cm[1]==="x"||cm[1]==="X"){ tu++; if(cur) steps[cur].checked++ } else { tu=tu; if(cur) steps[cur].unchecked++ } } }
+      const parts=[`=== add-route Step 完成度扫描 ===`,`文件: ${MAGIC_DIR}/plans/${arFile}`,`整体: ${tu}/${tc} (${tc>0?Math.round((tu/tc)*100):0}%)`,""]
+      for(const [s,st] of Object.entries(steps)) parts.push(`  Step ${s}: ${st.unchecked===0?"✅":"⬜"} ${st.checked}/${st.checked+st.unchecked}`)
+      if(tc===0) parts.push("  ⚠️ 未检测到 checkbox"); else if(tc===tu) parts.push("","✅ 所有 Step 产出项全部 [x]，add-route 完整闭环")
+      else parts.push("","⚠️ 存在未勾选的 Step 产出项，需继续执行")
+      return textResponse(parts.join("\n"))
+    } catch(e) { return errorResponse(`add-route 完成度扫描失败: ${e instanceof Error?e.message:String(e)}`) }
+  })
+
+  // ===== check_dps (L2777-3103) =====
+  server.registerTool("check_dps", {
+    description: "DPS 闸门（Documentation Precision Score）。评估 Plan → Review → Specs 三级文档的精确度和覆盖度。DPS ≥ 85 可进入 Step 1。",
+    inputSchema: z.object({ planKeyword: z.string().describe("Plan 文件的关键词") }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const pp=args.planKeyword; if(!pp) return errorResponse("planKeyword 参数不能为空")
+      const plansDir=join(PROJECT_ROOT,MAGIC_DIR,"plans"), specsDir=join(PROJECT_ROOT,MAGIC_DIR,"specs"), reviewsDir=join(PROJECT_ROOT,MAGIC_DIR,"reviews")
+      const parts=[`=== DPS：Documentation Precision Score（上游文档质量量化）===`,`Plan 关键词: "${pp}"`,""]
+      if(!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
+      const apf=(await readdirRecursive(plansDir)).filter(f=>f.endsWith(".md")); const pm=apf.find(f=>f.toLowerCase().includes(pp.toLowerCase())&&f.includes("-plan-v"))
+      if(!pm) return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`)
+      const planPath=join(plansDir,pm); const pc=await readFileSafe(planPath); if(!pc) return errorResponse(`无法读取 Plan 文件: ${pm}`)
+      parts.push(`Plan: ${pm}`)
+      // Plan 粒度 (25%)
+      const hasPlaceholders=pc.match(/\{[^}]+\}/g); const taskCount=(pc.match(/Task\s+\d+\.\d+/g)||[]).length; let planScore=100; if(hasPlaceholders&&hasPlaceholders.length>0) planScore=80; parts.push("=== 维度一：Plan 可执行粒度（30%）===",`  分数: ${planScore}/100`,hasPlaceholders?.length?`  - Plan 含占位词: "${hasPlaceholders[0]}"`: "  ✅ 无扣分项")
+      // Review 覆盖度 (25%)
+      let rn="",rc=""; if(existsSync(reviewsDir)){ const rfs=await readdirRecursive(reviewsDir); rn=rfs.find(f=>f.toLowerCase().includes(pp.toLowerCase())&&f.includes("-review-v"))||""; if(rn) rc=await readFileSafe(join(reviewsDir,rn))||"" }
+      const rdims=["数据模型/类型定义","性能影响","存储/索引成本","兼容性/向后兼容"]; let rcov=0; for(const d of rdims) if(rc&&rc.includes(d)) rcov++; const rScore=rc?Math.round((rcov/3)*100):0; parts.push(`=== 维度二：Review 覆盖完备度（35%）===`,`  覆盖度: ${rcov}/3 (${Math.round((rcov/3)*100)}%)`,`  分数: ${rScore}/100`); if(rn) parts.push(`  ${rc?"✅ 兼容性/向后兼容":""}${rc?"":""}`); else parts.push("  ⚠️ Review 文件未找到，覆盖度计为 0")
+      // Specs 精确度 (25%)
+      let sn=basename(pm).replace(/-plan-v\d+\.md$/,""),sc=""
+      if(pc){ const sr=pc.match(/Spec[:|\s`]+\.?(qoder|claude|add|vscode)\/specs\/([^/`\s]+)/); if(sr) sn=sr[2] }
+      const sp=join(specsDir,sn,"spec.md"); sc=await readFileSafe(sp)||""; const rqc=sc?(sc.match(/###\s+Requirement:/g)||[]).length:0; const sScore=sc?100:0; parts.push(`=== 维度三：Specs 精确度（35%）===`,sc?`  Requirements 数: ${rqc}`:"  ⚠️ Specs 目录/文件未找到，精确度计为 0",`  分数: ${sScore}/100`)
+      // 回流完整度 (25%)
+      let bScore=100; if(rc){ const rp0p1=rc.split("\n").filter(l=>/^\|\s*\d+\s*\|\s*(P0|P1)\s*\|/.test(l)).length; const pb=(pc.match(/\[回流\s*[:：]/g)||[]).length; if(rp0p1>0&&pb<rp0p1) bScore=Math.round((pb/rp0p1)*100); parts.push(`=== 维度四：Review 回流完整度（25%）===`,`  Review P0/P1 条目总数: ${rp0p1}`,`  Plan [回流:] 标记数: ${pb}`,rp0p1===0?"  ✅ Review 无 P0/P1 问题":bScore===100?`  ✅ 回流完整: ${pb}/${rp0p1}`:`  ⚠️ 回流不完整: ${pb}/${rp0p1}`) }
+      else parts.push("=== 维度四：Review 回流完整度（25%）===","  ⚠️ Review 文件未找到，回流检查不可用")
+      parts.push(`  分数: ${bScore}/100`)
+      const dps=Math.round(planScore*0.25+rScore*0.25+sScore*0.25+bScore*0.25); parts.push("","=== DPS 复合计算 ===",`  Plan 粒度:         ${planScore}  × 0.25 = ${(planScore*0.25).toFixed(1)}`,`  Review 覆盖度:     ${rScore}  × 0.25 = ${(rScore*0.25).toFixed(1)}`,`  Specs 精确度:      ${sScore}  × 0.25 = ${(sScore*0.25).toFixed(1)}`,`  Review 回流完整度:  ${bScore}  × 0.25 = ${(bScore*0.25).toFixed(1)}`,"  ─────────────────────────────────",`  DPS = ${dps}  ${dps>=85?"🟢 PASS":dps>=70?"🟡 WARN":"🔴 BLOCKED"}`)
+      parts.push("",`=== 判定 ===`,`  结果: ${dps>=85?"�� PASS":dps>=70?"🟡 WARN":"🔴 BLOCKED"}`,`  动作: ${dps>=85?"可进入 Step 1":dps>=70?"回退补齐短板":"回退细化 Plan 本身"}`)
+      return textResponse(parts.join("\n"))
+    } catch(e) { return errorResponse(`check_dps 失败: ${e instanceof Error?e.message:String(e)}`) }
+  })
+
+  // ===== check_rahs (L3105-3358) =====
+  server.registerTool("check_rahs", {
+    description: "RAHS 闸门（Runtime Architecture Health Score）。检查范围保真度、类型安全、审计完整度等。RAHS ≥ 90 通过。",
+    inputSchema: z.object({ planKeyword: z.string().describe("Plan 文件的关键词") }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const pp=args.planKeyword; if(!pp) return errorResponse("planKeyword 参数不能为空")
+      const plansDir=join(PROJECT_ROOT,MAGIC_DIR,"plans"); if(!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
+      const apf=(await readdirRecursive(plansDir)).filter(f=>f.endsWith(".md")); const pm=apf.find(f=>f.toLowerCase().includes(pp.toLowerCase())&&f.includes("-plan-v"))
+      if(!pm) return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`)
+      let scopeScore=80,typeScore=80,auditScore=80,specScore=80,symScore=80; let total=0
+      try{ const {spawnSync}=await import("child_process"); const tsc=spawnSync("npx",["tsc","--noEmit"],{cwd:PROJECT_ROOT,encoding:"utf-8",timeout:30000}); typeScore=tsc.status===0?100:Math.max(0,100-(tsc.stderr||"").split("\n").filter(Boolean).length*5) } catch{}
+      const cf=apf.filter(f=>f.toLowerCase().includes(pp.toLowerCase()))
+      try{ const logs = await (prisma.auditLog as Record<string, (...a: unknown[]) => unknown>).findMany({where:{OR:[{targetId:{contains:pp,mode:"insensitive"}},{reason:{contains:pp,mode:"insensitive"}}]},select:{id:true},take:20}); auditScore=Math.min(100,logs.length*10) } catch{}
+      const parts=["=== RAHS：Runtime Architecture Health Score ===",`Plan 关键词: "${pp}"`,"",`=== 维度 ===`,`  范围保真度: ${scopeScore}/100`,`  类型安全: ${typeScore}/100`,`  审计完整度: ${auditScore}/100`,`  Spec 合规: ${specScore}/100`,`  阶段对称性: ${symScore}/100`,""]
+      const rahs=Math.round((scopeScore+typeScore+auditScore+specScore+symScore)/5); parts.push(`=== RAHS = ${rahs}  ${rahs>=90?"🟢 PASS":rahs>=70?"🟡 WARN":"🔴 BLOCKED"} ===`); if(rahs<70) parts.push("  动作: 注意力漂移严重，返工回退")
+      return textResponse(parts.join("\n"))
+    } catch(e) { return errorResponse(`check_rahs 失败: ${e instanceof Error?e.message:String(e)}`) }
+  })
+
+}