add-coder 0.3.16 → 0.3.19

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

@@ -0,0 +1,202 @@
+import * as z from "zod/v4"
+import type { ToolRegistrar } from "./registrar.js"
+import { existsSync, readFileSync } from "fs"
+import { join, basename } from "path"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+import { prisma } from "../shared/prisma.js"
+
+const db = {
+  get collabContract() { return prisma.collabContract as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get plan() { return prisma.planRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+}
+
+/** 契约文档结构化解析结果 */
+interface ParsedContract {
+  participants: unknown[]
+  stages: unknown[]
+  fileBoundaries: unknown[]
+  dependencyGraph: string
+  abilityMatrix: unknown
+  completionCriteria: unknown
+}
+
+/** 从契约文档解析结构化字段（markdown 表格/JSON 块简化提取） */
+function parseContractDoc(content: string): ParsedContract {
+  const participants: unknown[] = []
+  const stages: unknown[] = []
+  const fileBoundaries: unknown[] = []
+  let dependencyGraph = ""
+  const abilityMatrix: unknown = null
+  const completionCriteria: unknown = null
+
+  // participants（§二 参与者表）
+  const pMatch = content.match(/\| \*\*Lead Agent\*\*[\s\S]*?\n\n/)
+  if (pMatch) {
+    for (const line of pMatch[0].split("\n")) {
+      const m = line.match(/^\|\s*\*\*(.+?)\*\*\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/)
+      if (m) participants.push({ role: m[1], platformEntity: m[2], boundPlan: m[3], responsibility: m[4] })
+    }
+  }
+
+  // stages（§3.1 触发条件表）
+  const sMatch = content.match(/\| 阶段 \| 专家 \| 触发条件 \| 并行度 \|[\s\S]*?\n\n/)
+  if (sMatch) {
+    for (const line of sMatch[0].split("\n")) {
+      const m = line.match(/^\|\s*([A-Za-z0-9-]+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*([并行串行]+)\s*\|$/)
+      if (m) stages.push({ stage: m[1], expert: m[2], trigger: m[3], parallelism: m[4] === "并行" ? "parallel" : "serial" })
+    }
+  }
+
+  // fileBoundaries（§3.2 文件边界表）
+  const bMatch = content.match(/\| 专家 \| 独占文件域 \| 禁区 \|[\s\S]*?\n\n/)
+  if (bMatch) {
+    for (const line of bMatch[0].split("\n")) {
+      const m = line.match(/^\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/)
+      if (m && !m[1].startsWith("---")) fileBoundaries.push({ expert: m[1], exclusiveDomain: m[2], forbidden: m[3], isolationMode: "file" })
+    }
+  }
+
+  // dependencyGraph（§3.1.1 代码块）
+  const gMatch = content.match(/```\n(依赖:[\s\S]*?)\n```/)
+  if (gMatch) dependencyGraph = gMatch[1]
+
+  return { participants, stages, fileBoundaries, dependencyGraph, abilityMatrix, completionCriteria }
+}
+
+export function registerContractTools(server: ToolRegistrar) {
+
+  // ===== contract_track =====
+  server.registerTool("contract_track", {
+    description: "契约追踪：扫描 plans/ 目录的 *-collab-contract-*.md 文档，解析参与者/阶段/文件边界，写入 CollabContract 表。按 contractName 去重，已存在则增量更新版本。",
+    inputSchema: z.object({
+      contractName: z.string().optional().describe("指定契约名称扫描单个；不传则扫描全部"),
+      scanAll: z.boolean().optional().describe("true 扫描全部契约"),
+    }),
+  }, async (args: Record<string, unknown>) => {
+    try {
+      const { contractName, scanAll: _scanAll } = args as { contractName?: string; scanAll?: boolean }
+      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
+      if (!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
+
+      const allFiles = await readdirRecursive(plansDir)
+      // 契约文档命名：*-collab-contract-*.md
+      // 严格过滤：排除 -plan- / add-route / handoff / .hitl（防止 Plan 体系文档被误扫为契约）
+      let contractFiles = allFiles.filter(f =>
+        f.endsWith(".md") &&
+        !f.endsWith(".hitl.md") &&
+        f.includes("-collab-contract-") &&
+        !f.includes("-plan-") &&
+        !f.includes("add-route") &&
+        !f.includes("handoff"),
+      )
+      if (contractName) {
+        const m = contractFiles.find(f => f.includes(contractName))
+        contractFiles = m ? [m] : []
+      }
+
+      if (contractFiles.length === 0) {
+        return textResponse(`=== 并发协作契约追踪 ===\n\n未找到契约文档（条件: ${contractName || "全部"}）。\n\n扫描规则: plans/ 下 *-collab-contract-*.md 文件（排除 -plan-/add-route/handoff/.hitl）`)
+      }
+
+      const results: string[] = []
+      for (const f of contractFiles) {
+        const name = basename(f, ".md")
+        const path = join(plansDir, f)
+        const content = readFileSync(path, "utf-8")
+
+        // 提取 masterPlan（元信息中"总控 Plan:" 行）
+        const mpMatch = content.match(/总控 Plan:\s*`?([^`\n]+)`?/)
+        const masterPlanName = mpMatch ? mpMatch[1].trim().replace(/\.md$/, "") : ""
+
+        const parsed = parseContractDoc(content)
+        // P3 #6 健壮性：解析结果为空时告警（表头可能不匹配模板），并跳过该文件
+        if (parsed.stages.length === 0 || parsed.fileBoundaries.length === 0) {
+          console.warn(`[contract_track] 解析结果为空——表头可能不匹配模板（${f}）`)
+          results.push(`⚠️ ${name}  解析为空（stages=${parsed.stages.length}, fileBoundaries=${parsed.fileBoundaries.length}），跳过——检查表头是否与模板一致`)
+          continue
+        }
+        // 契约文档必须声明总控 Plan
+        if (!masterPlanName) {
+          console.warn(`[contract_track] 缺少「总控 Plan:」声明（${f}）`)
+          results.push(`⚠️ ${name}  缺少「总控 Plan:」声明，跳过`)
+          continue
+        }
+        const existing = await db.collabContract.findFirst({ where: { contractName: name } }) as Record<string, unknown> | null
+        const version = (existing?.version as number ?? 0) + 1
+
+        const data = {
+          contractName: name,
+          contractPath: path,
+          masterPlanName,
+          participants: parsed.participants as never,
+          abilityMatrix: parsed.abilityMatrix as never,
+          stages: parsed.stages as never,
+          dependencyGraph: parsed.dependencyGraph,
+          fileBoundaries: parsed.fileBoundaries as never,
+          completionCriteria: parsed.completionCriteria as never,
+          status: "ACTIVE",
+          version,
+        }
+
+        if (existing) {
+          await db.collabContract.update({ where: { contractName: name }, data })
+          results.push(`📄 ${name}  ✅ 已更新 (v${version})`)
+        } else {
+          await db.collabContract.create({ data })
+          results.push(`📄 ${name}  ✅ 已创建 (v${version})`)
+        }
+
+        // 若 masterPlan 存在，标记 PlanRecord 角色
+        if (masterPlanName) {
+          await db.plan.updateMany({
+            where: { planName: masterPlanName },
+            data: { contractRole: "MASTER", contractName: name } as never,
+          })
+        }
+      }
+
+      return textResponse(`=== 并发协作契约追踪 ===\n${results.join("\n")}\n\n💡 新契约建议: create_hitl({ planName: "${basename(contractFiles[0], ".md")}", type: "PLAN" }) 走契约审批`)
+    } catch (error) {
+      return errorResponse(`contract_track 失败: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  })
+
+  // ===== contract_status =====
+  server.registerTool("contract_status", {
+    description: "契约进度查询：返回 CollabContract 记录（版本/状态/参与者数/阶段数/边界数 + masterPlan）。",
+    inputSchema: z.object({
+      contractName: z.string().describe("契约名称（如 htc-g13-extra-time-quest-collab-contract-v1）"),
+    }),
+  }, async (args: Record<string, unknown>) => {
+    try {
+      const { contractName } = args as { contractName: string }
+      const contract = await db.collabContract.findFirst({ where: { contractName } }) as Record<string, unknown> | null
+      if (!contract) {
+        return textResponse(`📋 契约: 未跟踪\ncontractName: ${contractName}\n\n操作: contract_track({ contractName: "${contractName}" })`)
+      }
+      const participants = (contract.participants as unknown[]) || []
+      const stages = (contract.stages as unknown[]) || []
+      const boundaries = (contract.fileBoundaries as unknown[]) || []
+      const parallelCount = stages.filter((s) => (s as Record<string, unknown>).parallelism === "parallel").length
+      const serialCount = stages.filter((s) => (s as Record<string, unknown>).parallelism === "serial").length
+      const versionStr = String(contract.version as number ?? "?")
+      const statusStr = String(contract.status as string ?? "?")
+      const masterStr = String(contract.masterPlanName as string ?? "(未绑定)")
+      const depStr = contract.dependencyGraph ? "已声明" : "未声明"
+      const pathStr = String(contract.contractPath as string ?? "(无)")
+      return textResponse(
+        `📊 ${contractName}\n` +
+        `版本:      v${versionStr} (${statusStr})\n` +
+        `MasterPlan: ${masterStr}\n` +
+        `参与者:    ${participants.length} 个\n` +
+        `阶段:      ${stages.length} 个（并行 ${parallelCount} / 串行 ${serialCount}）\n` +
+        `文件边界:  ${boundaries.length} 个\n` +
+        `依赖拓扑:  ${depStr}\n` +
+        `文档:      ${pathStr}`,
+      )
+    } catch (error) {
+      return errorResponse(`contract_status 失败: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  })
+}

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

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { readdir } from "fs/promises"
 import { existsSync } from "fs"
 import { join } from "path"
@@ -7,7 +7,7 @@ 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) {
+export function registerDocsTools(server: ToolRegistrar) {
 
   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/ 文档。`,

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

@@ -7,7 +7,7 @@
  * @Description  : ADD 范式守卫工具：扫描 add-route 文件的 Step 完成度
  */
 import * as z from "zod/v4";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
 import { join } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
@@ -18,7 +18,7 @@ import {
   MAGIC_DIR,
 } from "../../shared/fs.js";
 
-export function registerCheckAddRouteCompleteness(server: McpServer) {
+export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
   server.registerTool(
     "check_add_route_completeness",
     {

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

@@ -7,7 +7,7 @@
  * @Description  : ADD 范式守卫工具：交叉校验 add-route 文件
  */
 import * as z from "zod/v4";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { join } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
 import {
@@ -60,7 +60,7 @@ function scanCheckboxes(content: string) {
   };
 }
 
-export function registerCheckAddRouteStatus(server: McpServer) {
+export function registerCheckAddRouteStatus(server: ToolRegistrar) {
   server.registerTool(
     "check_add_route_status",
     {

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

@@ -7,7 +7,7 @@
  * @Description  : DPS 闸门 — 四维复合评分 + FFT 自适应权重
  */
 import * as z from "zod/v4";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
 import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
@@ -29,7 +29,7 @@ import {
   getEmbeddings,
 } from "./helpers.js";
 
-export function registerCheckDps(server: McpServer) {
+export function registerCheckDps(server: ToolRegistrar) {
   server.registerTool(
     "check_dps",
     {

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

@@ -7,7 +7,7 @@
  * @Description  : RAHS 闸门（Runtime Architecture Health Score）
  */
 import * as z from "zod/v4";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
 import { join } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
@@ -19,7 +19,7 @@ import {
 } from "../../shared/fs.js";
 import { prisma } from "../../shared/prisma.js";
 
-export function registerCheckRahs(server: McpServer) {
+export function registerCheckRahs(server: ToolRegistrar) {
   server.registerTool(
     "check_rahs",
     {

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

@@ -8,7 +8,7 @@
  *                 tasks.md/checklist.md 进度由 plan_track 在 PlanRecord 中维护，此处不再重复扫描。
  */
 import * as z from "zod/v4";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
 import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
@@ -19,7 +19,7 @@ import {
   MAGIC_DIR,
 } from "../../shared/fs.js";
 
-export function registerCheckSpecSync(server: McpServer) {
+export function registerCheckSpecSync(server: ToolRegistrar) {
   server.registerTool(
     "check_spec_sync",
     {

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

@@ -1,13 +1,13 @@
 // gateway/ 子模块拆分入口
 // 各工具文件独立注册，由 registerGatewayTools 统一聚合并导出
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { ToolRegistrar } from "../registrar.js";
 import { registerCheckAddRouteStatus } from "./check_add_route_status.js";
 import { registerCheckSpecSync } from "./check_spec_sync.js";
 import { registerCheckAddRouteCompleteness } from "./check_add_route_completeness.js";
 import { registerCheckDps } from "./check_dps.js";
 import { registerCheckRahs } from "./check_rahs.js";
 
-export function registerGatewayTools(server: McpServer) {
+export function registerGatewayTools(server: ToolRegistrar) {
   registerCheckAddRouteStatus(server);
   registerCheckSpecSync(server);
   registerCheckAddRouteCompleteness(server);

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

@@ -1,5 +1,6 @@
 import * as z from "zod/v4"
-import { inputRequired, acceptedContent, type McpServer } from "@modelcontextprotocol/server"
+import { inputRequired, acceptedContent } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs"
 import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
@@ -11,7 +12,7 @@ const db = {
   get hitl() { return prisma.hitlRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
 }
 
-export function registerHitlTools(server: McpServer) {
+export function registerHitlTools(server: ToolRegistrar) {
 
   // ═══════════════ 辅助：按安装环境裁决交互模式（caijuehub: hitl-interaction-rules.toml） ═══════════════
   const _interaction = (() => {
@@ -102,7 +103,7 @@ export function registerHitlTools(server: McpServer) {
       "type: PLAN=计划审批, PLAN_REVIEW=方案评审",
     inputSchema: z.object({
       planName: z.string().describe("Plan 名称，不含 .md 后缀"),
-      type: z.enum(["PLAN", "PLAN_REVIEW"]).describe("审批类型"),
+      type: z.enum(["PLAN", "PLAN_REVIEW", "COLLAB_CONTRACT"]).describe("审批类型"),
       dimensions: z.array(z.object({
         name: z.string().describe("维度名称，如「实施主体」「数据模型」"),
         content: z.string().optional().describe("LLM 建议的方案内容"),
@@ -287,7 +288,7 @@ export function registerHitlTools(server: McpServer) {
       "已终态（TONGYI/BOHUI）不可再更新，BOHUI 后需 create_hitl 新建 round。",
     inputSchema: z.object({
       planName: z.string().describe("Plan 名称"),
-      type: z.enum(["PLAN", "PLAN_REVIEW"]).describe("审批类型"),
+      type: z.enum(["PLAN", "PLAN_REVIEW", "COLLAB_CONTRACT"]).describe("审批类型"),
       status: z.enum(["SUBMITTED", "TONGYI", "BOHUI"]).optional().describe("降级模式(_fallback)或 genui 模式(_use_genui)必填：目标状态"),
       reason: z.string().optional().describe("驳回原因（降级模式手动传，genui 模式从 widget 回调获取）"),
       _fallback: z.boolean().optional().default(false).describe("降级模式：跳过 inputRequired，按原始代码行为直接写哨兵+更新 DB"),
@@ -419,6 +420,13 @@ export function registerHitlTools(server: McpServer) {
       ].filter(Boolean).join("\n") + "\n"
       for (const n of markerNames) writeFileSync(join(markerDir, markerPrefix + n), markerContent, "utf-8")
       const marker = markerNames.map(n => join(markerDir, markerPrefix + n)).join(", ")
+      // P3 #6：回写 .hitl.md 提案文件状态（DRAFT → TONGYI/BOHUI），保证双通道校验一致
+      const proposalPath = findHitlFile(String(planName))
+      if (proposalPath) {
+        let proposal = readFileSync(proposalPath, "utf-8")
+        proposal = proposal.replace(/(状态:\s*)[A-Z_]+/, `$1${s}`)
+        writeFileSync(proposalPath, proposal, "utf-8")
+      }
       // 响应
       const lines = [
         `✅ update_hitl`,
@@ -445,7 +453,7 @@ export function registerHitlTools(server: McpServer) {
     description: "HITL 审批：查询状态。返回最新 round 的状态、时间戳、拒绝原因等。与 .hitl-tongyi-{planName} 哨兵文件构成双通道校验。\n未发起时返回提示调用 create_hitl。",
     inputSchema: z.object({
       planName: z.string().describe("Plan 名称"),
-      type: z.enum(["PLAN", "PLAN_REVIEW"]).describe("审批类型（默认 PLAN）").default("PLAN"),
+      type: z.enum(["PLAN", "PLAN_REVIEW", "COLLAB_CONTRACT"]).describe("审批类型（默认 PLAN）").default("PLAN"),
     }),
   }, async (args: Record<string, unknown>) => {
     try {

package/templates/core/scripts/mcp-server/tools/hook-event-report.ts

@@ -1,9 +1,9 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { prisma } from "../shared/prisma.js"
 
-export function registerHookEventTools(server: McpServer) {
+export function registerHookEventTools(server: ToolRegistrar) {
 
   server.registerTool("get_hook_events", {
     description:

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

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/server"
 import { registerContextTools } from "./context.js"
 import { registerAuditTools } from "./audit.js"
+import { registerContractTools } from "./contract.js"
 import { registerDocsTools } from "./docs.js"
 import { registerQualityTools } from "./quality.js"
 import { registerGatewayTools } from "./gateway/index.js"
@@ -8,16 +9,34 @@ import { registerHookEventTools } from "./hook-event-report.js"
 import { registerHitlTools } from "./hitl.js"
 import { registerPlanTools } from "./plan.js"
 import { registerReviewTools } from "./review.js"
+import { PROJECT_ID } from "../shared/env.js"
+import type { ToolRegistrar } from "./registrar.js"
 
 export function registerAllTools(server: McpServer) {
-  registerContextTools(server)    // 5 tools
-  registerAuditTools(server)      // 2 tools
-  registerDocsTools(server)       // 1 tool
-  registerQualityTools(server)    // 4 tools
-  registerGatewayTools(server)    // 5 tools
-  registerHookEventTools(server)  // 1 tool: get_hook_events
-  registerHitlTools(server)       // 3 tools: create_hitl / update_hitl / status_hitl
-  registerPlanTools(server)       // 3 tools: plan_track / plan_status / plan_sync
-  registerReviewTools(server)     // 3 tools: review_track / review_status / review_sync
-  // Total: 27 tools
+  // D9 多 MCP 路由安全：派生装饰版 registrar，为所有工具 description 注入项目身份前缀
+  const origRegister = server.registerTool.bind(server)
+  type RegisterTool = ToolRegistrar["registerTool"]
+  type ToolConfig = Parameters<RegisterTool>[1]
+  type ToolCb = Parameters<RegisterTool>[2]
+  const registerTool = ((name: string, config: ToolConfig, cb: ToolCb) => {
+    const c = config as { description?: string }
+    return origRegister(
+      name,
+      { ...config, description: `[项目: ${PROJECT_ID}] ${c.description ?? ""}` },
+      cb,
+    )
+  }) as RegisterTool
+  const registrar: ToolRegistrar = { registerTool }
+
+  registerContextTools(registrar)    // 5 tools
+  registerAuditTools(registrar)      // 2 tools
+  registerContractTools(registrar)   // 2 tools: contract_track / contract_status
+  registerDocsTools(registrar)       // 1 tool
+  registerQualityTools(registrar)    // 4 tools
+  registerGatewayTools(registrar)    // 5 tools
+  registerHookEventTools(registrar)  // 1 tool: get_hook_events
+  registerHitlTools(registrar)       // 3 tools: create_hitl / update_hitl / status_hitl
+  registerPlanTools(registrar)       // 3 tools: plan_track / plan_status / plan_sync
+  registerReviewTools(registrar)     // 3 tools: review_track / review_status / review_sync
+  // Total: 29 tools
 }

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

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { existsSync, readFileSync, writeFileSync } from "fs"
 import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
@@ -10,7 +10,7 @@ const db = {
   get plan() { return prisma.planRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
 }
 
-export function registerPlanTools(server: McpServer) {
+export function registerPlanTools(server: ToolRegistrar) {
 
   // ===== plan_track =====
   server.registerTool("plan_track", {
@@ -136,6 +136,9 @@ export function registerPlanTools(server: McpServer) {
         `planKeyword:  ${plan.planKeyword || "—"}`,
         plan.specPath ? `spec:         ${plan.specPath}` : null,
         plan.addRoutePath ? `addRoute:     ${plan.addRoutePath}` : null,
+        // P3 #5 契约角色展示（PlanRecord 已设置时）
+        plan.contractRole ? `contractRole: ${plan.contractRole}` : null,
+        plan.contractName ? `contractName: ${plan.contractName}` : null,
       ].filter(Boolean)
       return textResponse(lines.join("\n"))
     } catch (e) {

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

@@ -1,8 +1,8 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { textResponse, errorResponse } from "../shared/response.js"
 
-export function registerQualityTools(server: McpServer) {
+export function registerQualityTools(server: ToolRegistrar) {
 
   // ===== check_phase_symmetry (L615-679) =====
   server.registerTool("check_phase_symmetry", {

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

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+
+/**
+ * 工具注册器最小契约（基类接口）。
+ *
+ * 所有 registerXxxTools 只依赖 registerTool 一个成员，而非整个 McpServer：
+ * - 各模块注册函数 = 派生实现，签名收敛到最小依赖
+ * - registerAllTools 可注入装饰版 registrar（如 D9 项目身份前缀），
+ *   无需伪造 McpServer 对象，类型安全
+ */
+export type ToolRegistrar = Pick<McpServer, "registerTool">

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

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { existsSync, readFileSync, writeFileSync } from "fs"
 import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
@@ -30,7 +30,7 @@ function countIssueType(content: string): { p0: number; p1: number; backflow: nu
   return { p0, p1, backflow }
 }
 
-export function registerReviewTools(server: McpServer) {
+export function registerReviewTools(server: ToolRegistrar) {
 
   // ===== review_track =====
   server.registerTool("review_track", {