add-coder 0.3.26 → 0.3.27

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"

package/templates/core/scripts/mcp-server/shared/plan-lifecycle-events.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from "crypto"
+import * as z from "zod/v4"
+import type { RuntimeContextKey } from "./runtime-context.js"
+
+export const PLAN_LIFECYCLE_CHANNEL = "add_plan_lifecycle_changed_v1"
+
+export const PlanLifecycleChangedEnvelopeSchema = z.object({
+  schemaVersion: z.literal(1),
+  eventId: z.string().min(1),
+  projectKey: z.string().min(1),
+  adapterKey: z.string().min(1),
+  planId: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+})
+
+export type PlanLifecycleChangedEnvelope = z.infer<typeof PlanLifecycleChangedEnvelopeSchema>
+
+export interface PrismaNotifyTransaction {
+  $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>
+}
+
+export function createPlanLifecycleChangedEnvelope(input: {
+  context: RuntimeContextKey
+  planId: string
+  revision: number
+  eventId?: string
+}): PlanLifecycleChangedEnvelope {
+  return {
+    schemaVersion: 1,
+    eventId: input.eventId ?? randomUUID(),
+    projectKey: input.context.projectKey,
+    adapterKey: input.context.adapterKey,
+    planId: input.planId,
+    revision: input.revision,
+  }
+}
+
+export function parsePlanLifecycleChangedEnvelope(payload: string | undefined): PlanLifecycleChangedEnvelope | null {
+  if (!payload) return null
+  try {
+    const parsed: unknown = JSON.parse(payload)
+    const result = PlanLifecycleChangedEnvelopeSchema.safeParse(parsed)
+    return result.success ? result.data : null
+  } catch {
+    return null
+  }
+}
+
+export function isLifecycleEventForContext(
+  envelope: PlanLifecycleChangedEnvelope,
+  context: RuntimeContextKey,
+): boolean {
+  return envelope.projectKey === context.projectKey && envelope.adapterKey === context.adapterKey
+}
+
+export async function publishPlanLifecycleChanged(
+  tx: PrismaNotifyTransaction,
+  envelope: PlanLifecycleChangedEnvelope,
+): Promise<void> {
+  const payload = JSON.stringify(envelope)
+  await tx.$executeRaw`SELECT pg_notify(${PLAN_LIFECYCLE_CHANNEL}, ${payload})`
+}

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

@@ -0,0 +1,78 @@
+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 interface PlanLifecycleMutationRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface PlanLifecycleTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<PlanLifecycleMutationRow | null>
+    update(args: {
+      where: Record<string, unknown>
+      data: { lifecycle: PlanLifecycleStatus; revision: { increment: 1 } }
+    }): Promise<PlanLifecycleMutationRow>
+  }
+}
+
+export interface PlanLifecycleDatabase {
+  $transaction<T>(work: (tx: PlanLifecycleTransaction) => Promise<T>): Promise<T>
+}
+
+export interface TransitionPlanLifecycleInput {
+  context: RuntimeContextKey
+  planName: string
+  to: PlanLifecycleStatus
+  expectedRevision?: number
+}
+
+export async function transitionPlanLifecycle(
+  database: PlanLifecycleDatabase,
+  input: TransitionPlanLifecycleInput,
+): Promise<PlanLifecycleMutationRow> {
+  return database.$transaction(async (tx) => {
+    const current = await tx.planRecord.findFirst({
+      where: {
+        projectKey: input.context.projectKey,
+        adapterKey: input.context.adapterKey,
+        planName: input.planName,
+      },
+    })
+    if (!current) {
+      throw new Error(`当前 RuntimeContextKey 下不存在 Plan: ${input.planName}`)
+    }
+    if (current.projectKey !== input.context.projectKey || current.adapterKey !== input.context.adapterKey) {
+      throw new Error("拒绝迁移 scope 外 Plan lifecycle")
+    }
+    if (input.expectedRevision !== undefined && current.revision !== input.expectedRevision) {
+      throw new Error(`Plan lifecycle revision 冲突: expected=${input.expectedRevision}, actual=${current.revision}`)
+    }
+    assertLifecycleTransition(current.lifecycle, input.to)
+    if (current.lifecycle === input.to) return current
+
+    const updated = await tx.planRecord.update({
+      where: { id: current.id, revision: current.revision },
+      data: { lifecycle: input.to, revision: { increment: 1 } },
+    })
+    if (updated.revision !== current.revision + 1) {
+      throw new Error(`Plan lifecycle revision 未按预期递增: ${current.revision} → ${updated.revision}`)
+    }
+    const envelope = createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: updated.id,
+      revision: updated.revision,
+    })
+    await publishPlanLifecycleChanged(tx, envelope)
+    return updated
+  })
+}