add-coder 0.2.7 → 0.2.10

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

@@ -0,0 +1,268 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { join } from "path"
+import { existsSync, watch, readFileSync, statSync } from "fs"
+import { readFile } from "fs/promises"
+import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+import { prisma } from "../shared/prisma.js"
+
+// ── 类型定义 ──
+interface HookEvent {
+  ts: string
+  hook: string
+  decision: string
+  cmd: string
+  reason: string
+  planKeyword: string
+  planStatus: string
+}
+
+interface QueueState {
+  events: HookEvent[]
+  /** 文件 inode（检测轮转） */
+  inode: number
+  /** 文件已读字节数 */
+  bytesRead: number
+  /** flush 定时器 */
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+const REPORT_DIR = join(PROJECT_ROOT, MAGIC_DIR, "reports")
+const JSONL_FILE = join(REPORT_DIR, "hook-events.jsonl")
+const OVERFLOW_FILE = join(REPORT_DIR, "hook-events-overflow.jsonl")
+
+// ── 内存缓冲队列 ──
+const MAX_QUEUE = 50
+let serverRef: McpServer | null = null
+
+function createQueueState(): QueueState {
+  const st = statSync(JSONL_FILE, { throwIfNoEntry: false })
+  return {
+    events: [],
+    inode: st?.ino ?? 0,
+    bytesRead: st?.size ?? 0,
+    timer: null,
+  }
+}
+
+const q: QueueState = createQueueState()
+
+// ── jsonl 解析 ──
+function parseJsonlLine(line: string): HookEvent | null {
+  const trimmed = line.trim()
+  if (!trimmed) return null
+  try {
+    const obj = JSON.parse(trimmed) as HookEvent
+    if (!obj.ts || !obj.hook) return null
+    return obj
+  } catch {
+    return null
+  }
+}
+
+// ── 去重 key ──
+function dedupKey(e: HookEvent): string {
+  return `${e.hook}::${e.ts}::${e.planKeyword}`
+}
+
+// ── 批量落库 ──
+async function flushToDB(events: HookEvent[]): Promise<number> {
+  if (events.length === 0) return 0
+  const seen = new Set<string>()
+  const unique = events.filter(e => {
+    const k = dedupKey(e)
+    if (seen.has(k)) return false
+    seen.add(k)
+    return true
+  })
+  if (unique.length === 0) return 0
+
+  try {
+    // 获取或创建 ai-assistant 用户
+    const au = prisma.addUser as Record<string, (...a: unknown[]) => unknown>
+    let userId: string
+    try {
+      const existing = await au.findUnique({ where: { username: "ai-assistant" }, select: { id: true } }) as { id: string } | null
+      if (existing) {
+        userId = existing.id
+      } else {
+        const created = await au.create({
+          data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" },
+          select: { id: true },
+        }) as { id: string }
+        userId = created.id
+      }
+    } catch {
+      userId = "ai-assistant"
+    }
+
+    const ops = prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
+    const data = unique.map(e => ({
+      userId,
+      action: "HOOK_INTERCEPT",
+      targetType: e.hook,
+      targetId: e.cmd.substring(0, 500),
+      planKeyword: e.planKeyword,
+      reason: `[${e.decision}] ${e.reason}`,
+      afterState: JSON.stringify({ planStatus: e.planStatus }),
+    }))
+
+    await ops.createMany({ data })
+    return unique.length
+  } catch (err) {
+    console.error("[hook-notify] flushToDB 失败:", err instanceof Error ? err.message : String(err))
+    return 0
+  }
+}
+
+// ── 消费溢出文件 ──
+async function drainOverflowFile(): Promise<HookEvent[]> {
+  const events: HookEvent[] = []
+  try {
+    if (!existsSync(OVERFLOW_FILE)) return events
+    const content = await readFile(OVERFLOW_FILE, "utf-8")
+    for (const line of content.split("\n")) {
+      const ev = parseJsonlLine(line)
+      if (ev) events.push(ev)
+    }
+    // 清空溢出文件
+    const { writeFileSync } = await import("fs")
+    writeFileSync(OVERFLOW_FILE, "", "utf-8")
+  } catch {
+    // 忽略，下次 flush 重试
+  }
+  return events
+}
+
+// ── 核心: flush ──
+async function doFlush(): Promise<void> {
+  // 1) drain 内存队列
+  const memEvents = q.events.splice(0)
+  // 2) drain 溢出文件
+  const overflowEvents = await drainOverflowFile()
+  // 3) 合并
+  const allEvents = [...memEvents, ...overflowEvents]
+  if (allEvents.length === 0) return
+
+  const count = await flushToDB(allEvents)
+  if (count > 0 && serverRef) {
+    const noPlanCount = allEvents.filter(e => e.planKeyword === "no-active-plan").length
+    const msg = `[Hook] ${count} 条拦截事件已审计落库（计划: ${[...new Set(allEvents.map(e => e.planKeyword))].join(", ")}）`
+    serverRef.sendLoggingMessage({ level: "warning" as const, data: msg }).catch(() => {})
+  }
+}
+
+// ── 入队 + 触发策略 ──
+function enqueue(event: HookEvent): void {
+  if (q.events.length >= MAX_QUEUE) {
+    // 降级写入溢出文件
+    try {
+      const { appendFileSync } = require("fs") as typeof import("fs")
+      appendFileSync(OVERFLOW_FILE, JSON.stringify(event) + "\n", "utf-8")
+    } catch { /* 静默 */ }
+    return
+  }
+  q.events.push(event)
+
+  if (q.events.length >= MAX_QUEUE) {
+    // 满 50 条立即 flush
+    if (q.timer) { clearTimeout(q.timer); q.timer = null }
+    void doFlush()
+  } else if (!q.timer) {
+    // 调度 2s 后 flush
+    q.timer = setTimeout(() => {
+      q.timer = null
+      void doFlush()
+    }, 2000)
+  }
+}
+
+// ── fs.watch 回调 ──
+function readNewLines(): void {
+  try {
+    const st = statSync(JSONL_FILE, { throwIfNoEntry: false })
+    if (!st) return
+
+    // 检测文件轮转（inode 变化或文件变小）
+    if (st.ino !== q.inode || st.size < q.bytesRead) {
+      q.inode = st.ino
+      q.bytesRead = 0
+    }
+
+    if (st.size <= q.bytesRead) return
+
+    // 只读增量部分
+    const fd = require("fs").openSync(JSONL_FILE, "r")
+    const buf = Buffer.alloc(st.size - q.bytesRead)
+    require("fs").readSync(fd, buf, 0, buf.length, q.bytesRead)
+    require("fs").closeSync(fd)
+
+    const text = buf.toString("utf-8")
+    for (const line of text.split("\n")) {
+      const ev = parseJsonlLine(line)
+      if (ev) enqueue(ev)
+    }
+    q.bytesRead = st.size
+  } catch {
+    // 文件可能被轮转删除，下次重试
+  }
+}
+
+// ── 启动时全量扫描已有文件 ──
+async function initialScan(): Promise<void> {
+  const files = [JSONL_FILE, `${JSONL_FILE}.old`]
+  for (const f of files) {
+    if (!existsSync(f)) continue
+    try {
+      const content = await readFile(f, "utf-8")
+      for (const line of content.split("\n")) {
+        const ev = parseJsonlLine(line)
+        if (ev) enqueue(ev)
+      }
+    } catch { /* skip */ }
+  }
+  // 初始化消费位点
+  const st = statSync(JSONL_FILE, { throwIfNoEntry: false })
+  if (st) {
+    q.inode = st.ino
+    q.bytesRead = st.size
+  }
+}
+
+// ── 注册 ──
+export function registerHookNotifications(server: McpServer) {
+  serverRef = server
+
+  // 启动通知
+  server.sendLoggingMessage({
+    level: "notice" as const,
+    data: "ADD Hooks 治理卡位已激活，拦截事件将自动审计落库"
+  }).catch(() => {})
+
+  // 启动时扫描 + 建立 fs.watch
+  void initialScan().then(() => {
+    // 确保 jsonl 文件存在（fs.watch 要求文件已存在）
+    try {
+      const { mkdirSync, writeFileSync } = require("fs") as typeof import("fs")
+      mkdirSync(REPORT_DIR, { recursive: true })
+      if (!existsSync(JSONL_FILE)) writeFileSync(JSONL_FILE, "", "utf-8")
+    } catch { /* ok */ }
+
+    // 立即消费启动前已有事件
+    void doFlush()
+
+    // fs.watch 监听目录变化（文件可能后来才创建）
+    try {
+      watch(REPORT_DIR, (_event, filename) => {
+        if (filename === "hook-events.jsonl" || filename === "hook-events.jsonl.old") {
+          readNewLines()
+        }
+      })
+    } catch { /* watch 可能不支持 */ }
+  })
+
+  // 进程退出时清空剩余队列
+  const cleanup = () => { void doFlush() }
+  process.on("exit", cleanup)
+  process.on("SIGTERM", cleanup)
+  process.on("SIGINT", cleanup)
+}

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"