add-coder 0.3.25 → 0.3.27

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

@@ -1,9 +1,21 @@
 import type { McpServer } from "@modelcontextprotocol/server"
 import { join } from "path"
-import { existsSync, watch, readFileSync, statSync } from "fs"
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  statSync,
+  watch,
+  writeFileSync,
+} from "fs"
 import { readFile } from "fs/promises"
+import { createHash } from "crypto"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
+import { getRuntimeContext } from "../shared/env.js"
 
 // ── 类型定义 ──
 interface HookEvent {
@@ -29,6 +41,7 @@ interface QueueState {
 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 runtimeContext = getRuntimeContext()
 
 // ── 内存缓冲队列 ──
 const MAX_QUEUE = 50
@@ -98,6 +111,13 @@ async function flushToDB(events: HookEvent[]): Promise<number> {
     const ops = prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
     const data = unique.map(e => ({
       userId,
+      projectKey: runtimeContext.projectKey,
+      producerAdapterKey: runtimeContext.adapterKey,
+      contextId: runtimeContext.contextId,
+      toolName: "hook-event-notification",
+      operationKey: createHash("sha256")
+        .update(`${runtimeContext.contextId}\0${dedupKey(e)}\0${e.decision}\0${e.cmd}`)
+        .digest("hex"),
       action: "HOOK_INTERCEPT",
       targetType: e.hook,
       targetId: e.cmd.substring(0, 500),
@@ -106,7 +126,7 @@ async function flushToDB(events: HookEvent[]): Promise<number> {
       afterState: JSON.stringify({ planStatus: e.planStatus }),
     }))
 
-    await ops.createMany({ data })
+    await ops.createMany({ data, skipDuplicates: true })
     return unique.length
   } catch (err) {
     console.error("[hook-notify] flushToDB 失败:", err instanceof Error ? err.message : String(err))
@@ -125,7 +145,6 @@ async function drainOverflowFile(): Promise<HookEvent[]> {
       if (ev) events.push(ev)
     }
     // 清空溢出文件
-    const { writeFileSync } = await import("fs")
     writeFileSync(OVERFLOW_FILE, "", "utf-8")
   } catch {
     // 忽略，下次 flush 重试
@@ -145,7 +164,6 @@ async function doFlush(): Promise<void> {
 
   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(() => {})
   }
@@ -156,7 +174,6 @@ 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
@@ -191,10 +208,10 @@ function readNewLines(): void {
     if (st.size <= q.bytesRead) return
 
     // 只读增量部分
-    const fd = require("fs").openSync(JSONL_FILE, "r")
+    const fd = 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)
+    readSync(fd, buf, 0, buf.length, q.bytesRead)
+    closeSync(fd)
 
     const text = buf.toString("utf-8")
     for (const line of text.split("\n")) {
@@ -242,7 +259,6 @@ export function registerHookNotifications(server: McpServer) {
   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 */ }

package/templates/core/scripts/mcp-server/resources/hitl-approval-widget.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
+import {
+  HITL_APPROVAL_WIDGET_FILE,
+  HITL_APPROVAL_WIDGET_MIME,
+  HITL_APPROVAL_WIDGET_URI,
+} from "../shared/hitl-ui.js"
+
+export function registerHitlApprovalWidgetResource(server: McpServer) {
+  server.registerResource(
+    "hitl-approval-widget",
+    HITL_APPROVAL_WIDGET_URI,
+    {
+      title: "ADD HITL Approval",
+      description: "逐项审核 ADD HITL 提案的 core 标准 widget",
+      mimeType: HITL_APPROVAL_WIDGET_MIME,
+    },
+    (uri) => {
+      const widgetPath = join(PROJECT_ROOT, MAGIC_DIR, "templates", HITL_APPROVAL_WIDGET_FILE)
+      if (!existsSync(widgetPath)) {
+        throw new Error(`HITL widget 缺失: ${widgetPath}。请重新执行 add-coder sync。`)
+      }
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: HITL_APPROVAL_WIDGET_MIME,
+          text: readFileSync(widgetPath, "utf-8"),
+        }],
+      }
+    },
+  )
+}

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

@@ -1,7 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/server"
 import { prisma } from "../shared/prisma.js"
+import { getRuntimeContext } from "../shared/env.js"
 
 export function registerHookEventResources(server: McpServer) {
+  const runtimeContext = getRuntimeContext()
 
   // ── 日报 Resource ──
   server.registerResource("hook-events-daily", "add-coder://report/hook-events/daily",
@@ -11,7 +13,12 @@ export function registerHookEventResources(server: McpServer) {
       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 } },
+        where: {
+          action: "HOOK_INTERCEPT",
+          projectKey: runtimeContext.projectKey,
+          producerAdapterKey: runtimeContext.adapterKey,
+          createdAt: { gte: since },
+        },
         orderBy: { createdAt: "desc" },
         take: 500,
       }) as Array<Record<string, unknown>>
@@ -60,7 +67,12 @@ export function registerHookEventResources(server: McpServer) {
       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 } },
+        where: {
+          action: "HOOK_INTERCEPT",
+          projectKey: runtimeContext.projectKey,
+          producerAdapterKey: runtimeContext.adapterKey,
+          createdAt: { gte: since },
+        },
         orderBy: { createdAt: "desc" },
         take: 2000,
       }) as Array<Record<string, unknown>>

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

@@ -3,10 +3,12 @@ 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"
+import { registerHitlApprovalWidgetResource } from "./hitl-approval-widget.js"
 
 export function registerAllResources(server: McpServer) {
   registerAddStateResources(server)
   registerRoundTaskResources(server)
   registerVersionResource(server)
   registerHookEventResources(server)  // 2 resources: hook-events/{daily,weekly}
+  registerHitlApprovalWidgetResource(server)
 }

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

@@ -6,7 +6,8 @@ import { readFileSafe, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
  * HITL Review 触发
  * ADD-9 方向验证 / ADD-10 语义对齐 / ADD-11 证据持久化
  *
- * 流程: 读取 Review 模板 → 生成 HITL 发现总览 temporary.md → 人类拍板 → 写入正式 Review
+ * 方案/实现 Review: 读取模板 → 整理 dimensions → create_hitl → update_hitl → status_hitl → 写入正式 Review
+ * Runtime Review: [T] 全部通过后按模板直接生成，不走 HITL
  * 参考: add-paradigm SKILL Step 0.6.5（Review 结论回流至 Plan 与 Specs）
  */
 export async function createReviewRequest(planKeyword: string, reviewType: "plan" | "implementation" | "runtime" = "plan"): Promise<InputRequiredResult> {
@@ -18,23 +19,37 @@ export async function createReviewRequest(planKeyword: string, reviewType: "plan
 
   const templatePath = join(PROJECT_ROOT, MAGIC_DIR, "templates", templateFile)
   const template = await readFileSafe(templatePath)
+  const requiresHitl = reviewType !== "runtime"
+  const reviewPlanName = reviewType === "plan"
+    ? `${planKeyword}-review-v1`
+    : `${planKeyword}-review-${reviewType}`
 
-  const hitlGuide = `
-## HITL 审核流程（两步法）
+  const workflowGuide = requiresHitl ? `
+## HITL 审核流程
 
-1. 先写 {review-name}.temporary.md（只含 HITL 发现总览表 + 问题清单）
-2. 人类拍板后 → 生成完整 Review 写入 ${MAGIC_DIR}/reviews/
-3. 将 Review 结论回流至 Plan（Step 0.6.5）
+1. 根据模板与审查证据，将待拍板发现整理为 dimensions
+2. 调用 create_hitl({ planName: "${reviewPlanName}", type: "PLAN_REVIEW", dimensions })
+3. 人类审核提案后调用 update_hitl 完成 TONGYI/BOHUI 拍板
+4. 通过 status_hitl 确认 TONGYI 后，生成完整 Review 写入 ${MAGIC_DIR}/reviews/
+5. 将 Review 结论回流至 Plan 与 Specs（Step 0.6.5）
 
 模板:
 ${template?.slice(0, 3000) ?? `标准 ${reviewType} Review 模板`}
+` : `
+## Runtime Review 流程
+
+1. 确认 implementation checklist 的 [T] 项已全部通过
+2. 按模板直接生成 Runtime Review 写入 ${MAGIC_DIR}/reviews/
+3. 持久化运行时证据，并将发现回流至 Plan、Specs 或 runtime-fix Plan
+
+模板:
+${template?.slice(0, 3000) ?? "标准 runtime Review 模板"}
 `
 
-  const prompt = `请为 Plan "${planKeyword}" 发起 HITL Review（类型: ${reviewType}）。
-先读取 ${MAGIC_DIR}/reviews/ 下已有的 Review 模板，
-然后按 HITL 两步法：先写 temporary.md → 人类拍板 → 生成完整 Review。
+  const prompt = `请为 Plan "${planKeyword}" 生成 Review（类型: ${reviewType}）。
+先读取 ${MAGIC_DIR}/templates/${templateFile}，再严格执行下述流程。
 
-${hitlGuide}`
+${workflowGuide}`
 
   const sampleRequest = inputRequired.createMessage({
     messages: [{ role: "user" as const, content: { type: "text" as const, text: prompt } }],

package/templates/core/scripts/mcp-server/shared/db-types.ts

@@ -20,7 +20,11 @@ import * as z from "zod/v4"
 
 export const PlanRowSchema = z.looseObject({
   id: z.string(),
+  projectKey: z.string(),
+  adapterKey: z.string(),
   planName: z.string(),
+  lifecycle: z.enum(["DRAFT", "ACTIVE", "BLOCKED", "REJECTED", "CLOSED", "ABANDONED"]),
+  revision: z.number(),
   planPath: z.string(),
   planKeyword: z.string().nullable(),
   specPath: z.string().nullable(),
@@ -45,6 +49,8 @@ export const PlanRowSchema = z.looseObject({
 
 export const HitlRowSchema = z.looseObject({
   id: z.string(),
+  projectKey: z.string(),
+  adapterKey: z.string(),
   planName: z.string(),
   round: z.number(),
   type: z.enum(["PLAN", "PLAN_REVIEW", "COLLAB_CONTRACT"]),
@@ -58,6 +64,8 @@ export const HitlRowSchema = z.looseObject({
 
 export const ReviewRowSchema = z.looseObject({
   id: z.string(),
+  projectKey: z.string(),
+  adapterKey: z.string(),
   planName: z.string(),
   type: z.enum(["PLAN_REVIEW", "IMPLEMENTATION", "RUNTIME"]),
   reviewPath: z.string().nullable(),
@@ -70,6 +78,9 @@ export const ReviewRowSchema = z.looseObject({
 
 export const AuditLogRowSchema = z.looseObject({
   id: z.string(),
+  projectKey: z.string(),
+  producerAdapterKey: z.string(),
+  contextId: z.string(),
   action: z.string(),
   targetType: z.string(),
   targetId: z.string(),
@@ -83,6 +94,11 @@ export const AuditLogRowSchema = z.looseObject({
 export const DevOperationRowSchema = z.looseObject({
   id: z.string(),
   userId: z.string(),
+  projectKey: z.string(),
+  producerAdapterKey: z.string(),
+  contextId: z.string(),
+  toolName: z.string(),
+  operationKey: z.string(),
   planKeyword: z.string(),
   action: z.string(),
   targetType: z.string(),
@@ -103,9 +119,13 @@ export const AddUserRowSchema = z.looseObject({
 
 export const CollabContractRowSchema = z.looseObject({
   id: z.string(),
+  projectKey: z.string(),
+  ownerAdapterKey: z.string(),
   contractName: z.string(),
   contractPath: z.string(),
   masterPlanName: z.string(),
+  masterProjectKey: z.string(),
+  masterAdapterKey: z.string(),
   participants: z.unknown(),
   abilityMatrix: z.unknown().nullable(),
   stages: z.unknown(),
@@ -151,6 +171,7 @@ export interface TableDelegate<T> {
   findMany(args?: QueryArgs<T>): Promise<T[]>
   findUnique(args: { where: Record<string, unknown>; select?: Record<string, unknown> }): Promise<T | null>
   create(args: { data: Partial<T> }): Promise<T>
+  upsert(args: { where: Record<string, unknown>; create: Partial<T>; update: Partial<T> }): Promise<T>
   update(args: { where: Partial<T>; data: Partial<T> }): Promise<T>
   updateMany(args: { where: Record<string, unknown>; data: Partial<T> }): Promise<BatchResult>
   delete(args: { where: Partial<T> }): Promise<T>
@@ -187,22 +208,26 @@ export function validatedDelegate<T>(
 
   return {
     async findFirst(args) {
-      const row = await raw.findFirst(args as never)
+      const row = await raw.findFirst(args)
       return row === null ? null : parseRow(row)
     },
     async findMany(args) {
-      const rows = await raw.findMany(args as never)
+      const rows = await raw.findMany(args)
       return rows.map(parseRow)
     },
     async findUnique(args) {
       if (!raw.findUnique) throw new Error(`表 ${tableName} 不支持 findUnique`)
-      const row = await raw.findUnique(args as never)
+      const row = await raw.findUnique(args)
       return row === null ? null : parseRow(row)
     },
-    async create(args) { return parseRow(await raw.create(args as never)) },
-    async update(args) { return parseRow(await raw.update(args as never)) },
-    async updateMany(args) { return raw.updateMany(args as never) as Promise<BatchResult> },
-    async delete(args) { return parseRow(await raw.delete(args as never)) },
-    async deleteMany(args) { return raw.deleteMany(args as never) as Promise<BatchResult> },
+    async create(args) { return parseRow(await raw.create(args)) },
+    async upsert(args) {
+      if (!raw.upsert) throw new Error(`表 ${tableName} 不支持 upsert`)
+      return parseRow(await raw.upsert(args))
+    },
+    async update(args) { return parseRow(await raw.update(args)) },
+    async updateMany(args) { return raw.updateMany(args) },
+    async delete(args) { return parseRow(await raw.delete(args)) },
+    async deleteMany(args) { return raw.deleteMany(args) },
   }
 }

package/templates/core/scripts/mcp-server/shared/dps-scoring.strategy.ts

@@ -30,4 +30,4 @@ export const DPS_SCORING_CONFIG = {
     THRESHOLD_WARN: 65,
     EMBEDDING_MODEL: "Xenova/bge-small-zh-v1.5",
 } as const;
-// <<< CAIJUE GENERATED END <<<
+// <<< CAIJUE GENERATED END <<<

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

@@ -1,29 +1,49 @@
 import dotenv from "dotenv"
-import { dirname, resolve, basename } from "path"
-import { fileURLToPath } from "url"
+import { dirname, resolve, basename, join } from "path"
 import { existsSync } from "fs"
-import { resolveProjectRoot } from "./project-root-strategy.js"
+import { resolveProjectRoot } from "./project-root-strategy.js";
+import { createRuntimeContext, type RuntimeContextKey } from "./runtime-context.js"
 
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
+const __dirname = import.meta.dirname
 
 // 集中裁决层驱动：PROJECT_ROOT 推导由 project-root-rules.toml → project-root-strategy.ts 定义
 export const PROJECT_ROOT = resolveProjectRoot(__dirname)
 
-export const MAGIC_DIR = process.env.MAGIC_DIR || basename(resolve(__dirname, "..", "..", ".."))
+// find-up 锚点（轮次 3）：向上找含 scripts/mcp-server 结构的目录 = magicDir（不手算层级）
+// magicDir 结构探测（轮次 3）：从当前文件位置向上逐级找首个 magic 结构目录（.xxx 且含 scripts/mcp-server）
+// —— 命中当前运行副本，多副本共存无歧义，不 hardcode 目录名
+export const MAGIC_DIR = process.env.MAGIC_DIR || (() => {
+  try {
+    let d = __dirname;
+    for (;;) {
+      const base = basename(d);
+      if (base.startsWith(".") && existsSync(join(d, "scripts", "mcp-server"))) return base;
+      const parent = dirname(d);
+      if (parent === d) break;
+      d = parent;
+    }
+  } catch { /* 探测失败走兜底 */ }
+  return basename(resolve(__dirname, "..", "..", "..", ".."));
+})()
 export const PROJECT_ID = basename(PROJECT_ROOT)
 
+let runtimeContext: Readonly<RuntimeContextKey> | undefined
+export function getRuntimeContext(): Readonly<RuntimeContextKey> {
+  runtimeContext ??= createRuntimeContext(PROJECT_ROOT, MAGIC_DIR)
+  return runtimeContext
+}
+
 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 }
+    if (existsSync(p)) { dotenv.config({ path: p, override: true, quiet: true }); loaded = true; break }
   }
 }
 
-export const DATABASE_URL = process.env.DATABASE_URL
+export const DATABASE_URL: string = process.env.DATABASE_URL ?? ""
 if (!DATABASE_URL) {
   throw new Error("DATABASE_URL 未设置，请在 .env 中配置数据库连接串")
 }

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

@@ -43,3 +43,6 @@ export async function readdirRecursive(baseDir: string): Promise<string[]> {
 }
 
 export { PROJECT_ROOT, MAGIC_DIR }
+
+/** magic 目录前缀（git diff 过滤等场景用）：当前环境 magicDir + 分发镜像（与 sync 分发同源） */
+export const MAGIC_PREFIXES = [MAGIC_DIR, ".qoder", ".claude", ".vscode", ".trae", ".codex", ".add", ".backup"];

package/templates/core/scripts/mcp-server/shared/hitl-interaction.strategy.ts

@@ -8,11 +8,10 @@ export const HITL_INTERACTION_CONFIG = {
     claude: { mode: "inputRequired" as const },
     vscode: { mode: "inputRequired" as const },
     trae: { mode: "inputRequired" as const },
-    codex: { mode: "inputRequired" as const }
+    codex: { mode: "mcpApps" as const }
 } as const;
 
 export type HitlInteractionMode = (typeof HITL_INTERACTION_CONFIG)[keyof typeof HITL_INTERACTION_CONFIG]["mode"];
-// <<< CAIJUE GENERATED END <<<
-// >>> USER CODE >>>
+// <<< CAIJUE GENERATED END <<<// >>> USER CODE >>>
 // 在此添加自定义配置覆盖
 // <<< USER CODE <<<

package/templates/core/scripts/mcp-server/shared/hitl-lifecycle-mutation.ts

@@ -0,0 +1,129 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import { assertLifecycleTransition, type PlanLifecycleStatus } from "./plan-lifecycle.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+
+export type HitlDecisionStatus = "SUBMITTED" | "TONGYI" | "BOHUI"
+export type HitlDecisionType = "PLAN" | "PLAN_REVIEW" | "COLLAB_CONTRACT"
+
+export interface HitlMutationRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  round: number
+  type: HitlDecisionType
+  status: "DRAFT" | HitlDecisionStatus
+  approvedAt: Date | null
+  rejectedAt: Date | null
+  rejectReason: string | null
+}
+
+export interface HitlPlanMutationRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface HitlLifecycleTransaction extends PrismaNotifyTransaction {
+  hitlRecord: {
+    findFirst(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<HitlMutationRow | null>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<HitlMutationRow>
+  }
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<HitlPlanMutationRow | null>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<HitlPlanMutationRow>
+  }
+}
+
+export interface HitlLifecycleDatabase {
+  $transaction<T>(work: (tx: HitlLifecycleTransaction) => Promise<T>): Promise<T>
+}
+
+export interface DecideHitlInput {
+  context: RuntimeContextKey
+  planName: string
+  type: HitlDecisionType
+  status: HitlDecisionStatus
+  reason?: string
+}
+
+export interface DecideHitlResult {
+  previousStatus: HitlMutationRow["status"]
+  hitl: HitlMutationRow
+  plan: HitlPlanMutationRow
+}
+
+function targetLifecycle(
+  type: HitlDecisionType,
+  status: HitlDecisionStatus,
+  current: PlanLifecycleStatus,
+): PlanLifecycleStatus {
+  if (type !== "PLAN" || status === "SUBMITTED") return current
+  return status === "TONGYI" ? "ACTIVE" : "REJECTED"
+}
+
+/**
+ * 审批写入、Plan revision/lifecycle 与 NOTIFY 必须在同一 Prisma transaction。
+ * NOTIFY payload 只是唤醒提示；订阅端收到后必须再按自身 RuntimeContextKey 查库。
+ */
+export async function decideHitlAndPublish(
+  database: HitlLifecycleDatabase,
+  input: DecideHitlInput,
+): Promise<DecideHitlResult> {
+  return database.$transaction(async (tx) => {
+    const scope = {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      planName: input.planName,
+    }
+    const current = await tx.hitlRecord.findFirst({
+      where: { ...scope, type: input.type },
+      orderBy: { round: "desc" },
+    })
+    if (!current) throw new Error(`未找到当前 RuntimeContextKey 的 HITL: ${input.planName}/${input.type}`)
+    if (current.status === "TONGYI" || current.status === "BOHUI") {
+      throw new Error(`HITL 已终态（${current.status}），不可再次更新`)
+    }
+
+    const plan = await tx.planRecord.findFirst({ where: scope })
+    if (!plan) throw new Error(`未找到当前 RuntimeContextKey 的 PlanRecord: ${input.planName}`)
+    if (plan.projectKey !== input.context.projectKey || plan.adapterKey !== input.context.adapterKey) {
+      throw new Error("拒绝修改 scope 外 Plan")
+    }
+
+    const now = new Date()
+    const hitlData: Record<string, unknown> = { status: input.status }
+    if (input.status === "TONGYI") hitlData.approvedAt = now
+    if (input.status === "BOHUI") {
+      hitlData.rejectedAt = now
+      hitlData.rejectReason = input.reason ?? null
+    }
+    const hitl = await tx.hitlRecord.update({ where: { id: current.id }, data: hitlData })
+
+    const nextLifecycle = targetLifecycle(input.type, input.status, plan.lifecycle)
+    assertLifecycleTransition(plan.lifecycle, nextLifecycle)
+    const planData: Record<string, unknown> = { revision: { increment: 1 } }
+    if (nextLifecycle !== plan.lifecycle) planData.lifecycle = nextLifecycle
+    const updatedPlan = await tx.planRecord.update({
+      where: { id: plan.id, revision: plan.revision },
+      data: planData,
+    })
+    if (updatedPlan.revision !== plan.revision + 1) {
+      throw new Error(`Plan revision 未按预期递增: ${plan.revision} → ${updatedPlan.revision}`)
+    }
+
+    await publishPlanLifecycleChanged(tx, createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: updatedPlan.id,
+      revision: updatedPlan.revision,
+    }))
+    return { previousStatus: current.status, hitl, plan: updatedPlan }
+  })
+}

package/templates/core/scripts/mcp-server/shared/hitl-proposal-mutation.ts

@@ -0,0 +1,98 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PlanLifecycleStatus } from "./plan-lifecycle.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+import type { HitlDecisionType } from "./hitl-lifecycle-mutation.js"
+
+export interface HitlProposalPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface HitlProposalRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  round: number
+  type: HitlDecisionType
+  status: "DRAFT"
+}
+
+export interface HitlProposalTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<HitlProposalPlanRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<HitlProposalPlanRow>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<HitlProposalPlanRow>
+  }
+  hitlRecord: {
+    findFirst(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<HitlProposalRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<HitlProposalRow>
+  }
+}
+
+export interface HitlProposalDatabase {
+  $transaction<T>(work: (tx: HitlProposalTransaction) => Promise<T>): Promise<T>
+}
+
+/** Advisory xact lock makes max(round)+1 atomic per scoped plan/type. */
+export async function createHitlProposalAndPublish(
+  database: HitlProposalDatabase,
+  input: {
+    context: RuntimeContextKey
+    planName: string
+    planPath: string
+    planKeyword: string
+    type: HitlDecisionType
+  },
+): Promise<{ planProvisioned: boolean; plan: HitlProposalPlanRow; hitl: HitlProposalRow }> {
+  return database.$transaction(async (tx) => {
+    const lockKey = `${input.context.contextId}:${input.planName}:${input.type}`
+    await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${lockKey}))`
+    const scope = {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      planName: input.planName,
+    }
+    const existing = await tx.planRecord.findFirst({ where: scope })
+    const plan = existing
+      ? await tx.planRecord.update({
+          where: { id: existing.id, revision: existing.revision },
+          data: { revision: { increment: 1 } },
+        })
+      : await tx.planRecord.create({
+          data: {
+            ...scope,
+            planPath: input.planPath,
+            planKeyword: input.planKeyword,
+            lifecycle: "DRAFT",
+            revision: 0,
+          },
+        })
+    const latest = await tx.hitlRecord.findFirst({
+      where: { ...scope, type: input.type },
+      orderBy: { round: "desc" },
+    })
+    const hitl = await tx.hitlRecord.create({
+      data: {
+        ...scope,
+        type: input.type,
+        round: (latest?.round ?? 0) + 1,
+        status: "DRAFT",
+      },
+    })
+    await publishPlanLifecycleChanged(tx, createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+      revision: plan.revision,
+    }))
+    return { planProvisioned: existing === null, plan, hitl }
+  })
+}

package/templates/core/scripts/mcp-server/shared/hitl-ui.ts

@@ -0,0 +1,3 @@
+export const HITL_APPROVAL_WIDGET_URI = "ui://add-coder/hitl-approval"
+export const HITL_APPROVAL_WIDGET_MIME = "text/html;profile=mcp-app"
+export const HITL_APPROVAL_WIDGET_FILE = "hitl-approval-widget.html"