add-coder 0.3.26 → 0.3.28

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

@@ -0,0 +1,143 @@
+import { createHash } from "crypto"
+import type { RuntimeContextKey } from "./runtime-context.js"
+import {
+  createPlanRoundChangedEnvelope,
+  publishPlanRoundChanged,
+} from "./plan-round-events.js"
+import type { PrismaNotifyTransaction } from "./plan-lifecycle-events.js"
+
+export interface PlanRoundPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: string
+  revision: number
+}
+
+export interface PlanRoundOperationRow {
+  id: string
+  projectKey: string
+  producerAdapterKey: string
+  contextId: string
+  toolName: string
+  operationKey: string
+  planKeyword: string
+  action: string
+  targetType: string
+  targetId: string
+  beforeState: unknown
+  afterState: unknown
+  reason: string | null
+  createdAt: Date
+}
+
+export interface PlanRoundTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<PlanRoundPlanRow | null>
+  }
+  addUser: {
+    findUnique(args: { where: Record<string, unknown>; select: Record<string, unknown> }): Promise<{ id: string } | null>
+    create(args: { data: Record<string, unknown> }): Promise<{ id: string }>
+  }
+  devOperation: {
+    upsert(args: { where: Record<string, unknown>; create: Record<string, unknown>; update: Record<string, unknown> }): Promise<PlanRoundOperationRow>
+  }
+}
+
+export interface PlanRoundDatabase {
+  $transaction<T>(work: (tx: PlanRoundTransaction) => Promise<T>): Promise<T>
+}
+
+export interface ClosePlanRoundInput {
+  context: RuntimeContextKey
+  planName: string
+  round: number
+  beforeState: Record<string, unknown> | unknown[]
+  afterState: Record<string, unknown> | unknown[]
+  reason?: string
+  operationKey?: string
+}
+
+export interface ClosePlanRoundResult {
+  plan: PlanRoundPlanRow
+  operation: PlanRoundOperationRow
+}
+
+export function defaultPlanRoundOperationKey(input: {
+  context: RuntimeContextKey
+  planId: string
+  round: number
+}): string {
+  return createHash("sha256")
+    .update(`${input.context.contextId}:${input.planId}:ROUND_CLOSED:${input.round}`)
+    .digest("hex")
+}
+
+export async function closePlanRoundAndPublish(
+  database: PlanRoundDatabase,
+  input: ClosePlanRoundInput,
+): Promise<ClosePlanRoundResult> {
+  if (!Number.isInteger(input.round) || input.round < 1) throw new Error("round 必须是大于 0 的整数")
+
+  return database.$transaction(async (tx) => {
+    const plan = await tx.planRecord.findFirst({
+      where: {
+        projectKey: input.context.projectKey,
+        adapterKey: input.context.adapterKey,
+        planName: input.planName,
+      },
+    })
+    if (!plan) throw new Error(`当前 RuntimeContextKey 下不存在 Plan: ${input.planName}`)
+    if (plan.projectKey !== input.context.projectKey || plan.adapterKey !== input.context.adapterKey) {
+      throw new Error("拒绝关闭 scope 外 PlanRound")
+    }
+
+    let user = await tx.addUser.findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
+    if (!user) {
+      user = await tx.addUser.create({
+        data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" },
+      })
+    }
+    const baseOperationKey = defaultPlanRoundOperationKey({
+      context: input.context,
+      planId: plan.id,
+      round: input.round,
+    })
+    const operationKey = input.operationKey?.trim()
+      ? createHash("sha256").update(`${baseOperationKey}:${input.operationKey.trim()}`).digest("hex")
+      : baseOperationKey
+    const operation = await tx.devOperation.upsert({
+      where: {
+        projectKey_producerAdapterKey_toolName_operationKey: {
+          projectKey: input.context.projectKey,
+          producerAdapterKey: input.context.adapterKey,
+          toolName: "plan_round_close",
+          operationKey,
+        },
+      },
+      create: {
+        userId: user.id,
+        projectKey: input.context.projectKey,
+        producerAdapterKey: input.context.adapterKey,
+        contextId: input.context.contextId,
+        toolName: "plan_round_close",
+        operationKey,
+        planKeyword: input.planName,
+        action: "ROUND_CLOSED",
+        targetType: "PLAN_ROUND",
+        targetId: `${input.planName}::round${input.round}`,
+        beforeState: input.beforeState,
+        afterState: input.afterState,
+        reason: input.reason ?? null,
+      },
+      update: {},
+    })
+
+    await publishPlanRoundChanged(tx, createPlanRoundChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+    }))
+    return { plan, operation }
+  })
+}

package/templates/core/scripts/mcp-server/shared/plan-round-store.ts

@@ -0,0 +1,47 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PlanRoundOperationRow } from "./plan-round-mutation.js"
+
+export interface PlanRoundReadClient {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<{ id: string; planName: string } | null>
+  }
+  devOperation: {
+    findMany(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<PlanRoundOperationRow[]>
+  }
+}
+
+export interface PlanRoundSnapshot {
+  context: RuntimeContextKey
+  planId: string | null
+  planName: string | null
+  rounds: PlanRoundOperationRow[]
+}
+
+export async function queryPlanRounds(
+  client: PlanRoundReadClient,
+  input: { context: RuntimeContextKey; planName?: string; planId?: string; round?: number },
+): Promise<PlanRoundSnapshot> {
+  const explicitPlan = Boolean(input.planName || input.planId)
+  const plan = await client.planRecord.findFirst({
+    where: {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      ...(input.planName ? { planName: input.planName } : {}),
+      ...(input.planId ? { id: input.planId } : {}),
+      ...(!explicitPlan ? { lifecycle: { in: ["ACTIVE", "BLOCKED"] } } : {}),
+    },
+    orderBy: { updatedAt: "desc" },
+  })
+  if (!plan) return { context: input.context, planId: null, planName: null, rounds: [] }
+
+  const where: Record<string, unknown> = {
+    projectKey: input.context.projectKey,
+    producerAdapterKey: input.context.adapterKey,
+    toolName: "plan_round_close",
+    action: "ROUND_CLOSED",
+    planKeyword: plan.planName,
+  }
+  if (input.round !== undefined) where.targetId = `${plan.planName}::round${input.round}`
+  const rounds = await client.devOperation.findMany({ where, orderBy: { createdAt: "asc" } })
+  return { context: input.context, planId: plan.id, planName: plan.planName, rounds }
+}

package/templates/core/scripts/mcp-server/shared/plan-round-subscriber.ts

@@ -0,0 +1,99 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { LifecycleListenClient, LifecycleListenClientFactory, PgNotification } from "./plan-lifecycle-subscriber.js"
+import type { PlanRoundSnapshot } from "./plan-round-store.js"
+import {
+  isPlanRoundEventForContext,
+  parsePlanRoundChangedEnvelope,
+  PLAN_ROUND_CHANNEL,
+  type PlanRoundChangedEnvelope,
+} from "./plan-round-events.js"
+
+export interface PlanRoundSubscriberOptions {
+  context: RuntimeContextKey
+  clientFactory: LifecycleListenClientFactory
+  queryRounds(input: { context: RuntimeContextKey; planId?: string; reason: "initial" | "notification" | "reconnect" }): Promise<PlanRoundSnapshot>
+  onSnapshot(snapshot: PlanRoundSnapshot, envelope?: PlanRoundChangedEnvelope): void | Promise<void>
+  onError?(error: Error): void
+  reconnectDelayMs?: number
+}
+
+export class PlanRoundSubscriber {
+  readonly #options: PlanRoundSubscriberOptions
+  #client: LifecycleListenClient | null = null
+  #stopping = false
+  #startedOnce = false
+  #reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  #refreshQueue: Promise<void> = Promise.resolve()
+
+  constructor(options: PlanRoundSubscriberOptions) { this.#options = options }
+
+  async start(): Promise<void> {
+    if (this.#client) return
+    this.#stopping = false
+    try { await this.#connectAndHydrate("initial") } catch (error) { this.#scheduleReconnect(); throw error }
+  }
+
+  async stop(): Promise<void> {
+    this.#stopping = true
+    if (this.#reconnectTimer) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = null
+    const client = this.#client
+    this.#client = null
+    if (!client) return
+    client.removeAllListeners()
+    try { await client.query(`UNLISTEN ${PLAN_ROUND_CHANNEL}`) } catch { /* connection may already be gone */ }
+    await client.end().catch(() => undefined)
+    await this.#refreshQueue
+  }
+
+  async #connectAndHydrate(reason: "initial" | "reconnect"): Promise<void> {
+    const client = await this.#options.clientFactory()
+    this.#client = client
+    client.on("notification", (message: PgNotification) => this.#handleNotification(message))
+    client.on("error", (error: Error) => this.#handleDisconnect(client, error))
+    client.on("end", () => this.#handleDisconnect(client, new Error("PostgreSQL PlanRound LISTEN session ended")))
+    try {
+      await client.connect()
+      await client.query(`LISTEN ${PLAN_ROUND_CHANNEL}`)
+      await this.#refresh(undefined, reason)
+      this.#startedOnce = true
+    } catch (error) {
+      if (this.#client === client) this.#client = null
+      client.removeAllListeners()
+      await client.end().catch(() => undefined)
+      const normalized = error instanceof Error ? error : new Error(String(error))
+      this.#options.onError?.(normalized)
+      throw normalized
+    }
+  }
+
+  #handleNotification(message: PgNotification): void {
+    if (this.#stopping || message.channel !== PLAN_ROUND_CHANNEL) return
+    const envelope = parsePlanRoundChangedEnvelope(message.payload)
+    if (!envelope || !isPlanRoundEventForContext(envelope, this.#options.context)) return
+    this.#refreshQueue = this.#refreshQueue
+      .then(() => this.#refresh(envelope, "notification"))
+      .catch((error: unknown) => this.#options.onError?.(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  #handleDisconnect(client: LifecycleListenClient, error: Error): void {
+    if (this.#stopping || this.#client !== client) return
+    this.#client = null
+    client.removeAllListeners()
+    this.#options.onError?.(error)
+    this.#scheduleReconnect()
+  }
+
+  #scheduleReconnect(): void {
+    if (this.#stopping || this.#reconnectTimer) return
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null
+      this.#connectAndHydrate(this.#startedOnce ? "reconnect" : "initial").catch(() => this.#scheduleReconnect())
+    }, this.#options.reconnectDelayMs ?? 1000)
+  }
+
+  async #refresh(envelope: PlanRoundChangedEnvelope | undefined, reason: "initial" | "notification" | "reconnect"): Promise<void> {
+    const snapshot = await this.#options.queryRounds({ context: this.#options.context, planId: envelope?.planId, reason })
+    await this.#options.onSnapshot(snapshot, envelope)
+  }
+}

package/templates/core/scripts/mcp-server/shared/plan-status-store.ts

@@ -0,0 +1,37 @@
+import type { HitlRow, PlanRow } from "./db-types.js"
+import { HitlRowSchema, PlanRowSchema, validatedDelegate } from "./db-types.js"
+import type { PlanStatusStore } from "./plan-lifecycle.js"
+
+/**
+ * 数据库是 lifecycle 真相源。所有查询都强制携带 RuntimeContextKey，禁止同名
+ * Plan 在 adapter 间串线；LISTEN/NOTIFY 只负责唤醒本 store 重新查询。
+ */
+export function createPrismaPlanStatusStore(client: Record<string, unknown>): PlanStatusStore {
+  const plans = validatedDelegate<PlanRow>(client.planRecord, PlanRowSchema, "PlanRecord")
+  const hitls = validatedDelegate<HitlRow>(client.hitlRecord, HitlRowSchema, "HitlRecord")
+
+  return {
+    async findPlan({ context, planName, planId, activeOnly }) {
+      const where: Record<string, unknown> = {
+        projectKey: context.projectKey,
+        adapterKey: context.adapterKey,
+      }
+      if (planName) where.planName = planName
+      if (planId) where.id = planId
+      if (activeOnly) where.lifecycle = { in: ["ACTIVE", "BLOCKED"] }
+      return plans.findFirst({ where, orderBy: { updatedAt: "desc" } })
+    },
+    async findLatestPlanApproval({ context, planName }) {
+      const record = await hitls.findFirst({
+        where: {
+          projectKey: context.projectKey,
+          adapterKey: context.adapterKey,
+          planName,
+          type: "PLAN",
+        },
+        orderBy: { round: "desc" },
+      })
+      return record?.status ?? null
+    },
+  }
+}

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

@@ -0,0 +1,71 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+import type { PlanLifecycleStatus } from "./plan-lifecycle.js"
+
+export interface TrackedPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface PlanTrackingTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<TrackedPlanRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<TrackedPlanRow>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<TrackedPlanRow>
+  }
+}
+
+export interface PlanTrackingDatabase {
+  $transaction<T>(work: (tx: PlanTrackingTransaction) => Promise<T>): Promise<T>
+}
+
+export async function trackPlanAndPublish(
+  database: PlanTrackingDatabase,
+  input: {
+    context: RuntimeContextKey
+    planName: string
+    planPath: string
+    projection: Record<string, unknown>
+  },
+): Promise<{ created: boolean; plan: TrackedPlanRow }> {
+  return database.$transaction(async (tx) => {
+    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: { ...input.projection, planPath: input.planPath, revision: { increment: 1 } },
+        })
+      : await tx.planRecord.create({
+          data: {
+            ...scope,
+            ...input.projection,
+            planPath: input.planPath,
+            lifecycle: "DRAFT",
+            revision: 0,
+          },
+        })
+    const expectedRevision = existing ? existing.revision + 1 : 0
+    if (plan.revision !== expectedRevision) {
+      throw new Error(`Plan track revision 未按预期变化: expected=${expectedRevision}, actual=${plan.revision}`)
+    }
+    await publishPlanLifecycleChanged(tx, createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+      revision: plan.revision,
+    }))
+    return { created: existing === null, plan }
+  })
+}

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

@@ -1,8 +1,8 @@
-import { DATABASE_URL, PROJECT_ROOT } from "./env.js"
-import { join, dirname, resolve as pathResolve } from "path"
+import { DATABASE_URL, PROJECT_ROOT, MAGIC_DIR } from "./env.js"
+import { join, dirname } from "path"
 import { existsSync } from "fs"
-import { fileURLToPath } from "url"
 import { createRequire } from "module"
+import { findUpSync } from "find-up"
 
 const require = createRequire(import.meta.url)
 
@@ -11,14 +11,20 @@ const require = createRequire(import.meta.url)
 // 双库分离项目（add.prisma=postgres + 业务 schema=mysql）需显式设置环境变量
 // PRISMA_CLIENT_DIR=add-prisma，否则会加载业务库 client 导致 provider mismatch
 const clientDir = process.env.PRISMA_CLIENT_DIR || "prisma"
+// 锚点查找兜底（find-up 包）：magicDir 向上查找项目根，替代手算层级（轮次 3）
+const anchorRoot = (() => {
+  const hit = findUpSync(MAGIC_DIR, { cwd: import.meta.dirname, type: "directory" });
+  return hit ? dirname(hit) : null;
+})();
 const candidates = [
   join(PROJECT_ROOT, `src/generated/${clientDir}/client.ts`),
   join(PROJECT_ROOT, `src/generated/${clientDir}/client.js`),
   join(process.cwd(), `src/generated/${clientDir}/client.ts`),
   join(process.cwd(), `src/generated/${clientDir}/client.js`),
-  // 从当前文件位置反推：shared/prisma.ts → 上 4 层到项目根
-  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, `src/generated/${clientDir}/client.ts`) })(),
-  (() => { const d = dirname(fileURLToPath(import.meta.url)); const root = pathResolve(d, "..", "..", "..", ".."); return join(root, `src/generated/${clientDir}/client.js`) })(),
+  ...(anchorRoot ? [
+    join(anchorRoot, `src/generated/${clientDir}/client.ts`),
+    join(anchorRoot, `src/generated/${clientDir}/client.js`),
+  ] : []),
 ]
 // 双库分离项目提示：检测到 add-prisma 客户端但未显式选择时提醒用户自行决策
 if (clientDir === "prisma" && existsSync(join(PROJECT_ROOT, "src/generated/add-prisma/client.ts"))) {

package/templates/core/scripts/mcp-server/shared/project-root-strategy.ts

@@ -4,8 +4,7 @@
 // >>> CAIJUE GENERATED START >>>
 export const PROJECT_ROOT_PRIORITY = ["env_var", "dirname_fallback", "cwd_fallback"] as const;
 export type ProjectRootTier = (typeof PROJECT_ROOT_PRIORITY)[number];
-// <<< CAIJUE GENERATED END <<<
-// >>> USER CODE >>>
+// <<< CAIJUE GENERATED END <<<// >>> USER CODE >>>
 import { resolve, dirname } from "path"
 import { existsSync } from "fs"
 

package/templates/core/scripts/mcp-server/shared/quant-recheck.strategy.ts

@@ -0,0 +1,16 @@
+// ⚠️ 由 caijuehub/transcribe.ts 自动生成，不要手动编辑！
+// 改 *-rules.toml 后重新运行: add-coder generate
+
+// >>> CAIJUE GENERATED START >>>
+export const QUANT_RECHECK_CONFIG = {
+    ANCHOR_WEIGHT: 3,
+    IDF_MIN_DOCS: 5,
+    RRF_K: 10,
+    MIN_ABS_SIMILARITY: 0.25,
+    RRF_MIN_CANDIDATES: 2,
+    EWMA_LAMBDA: 0.3,
+    EWMA_K: 1.5,
+    EWMA_COLD_START: 10,
+    EWMA_BASELINE: 0.16,
+} as const;
+// <<< CAIJUE GENERATED END <<<

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

@@ -0,0 +1,28 @@
+/*
+ * @Author       : xiaomingming wujixmm@gmail.com
+ * @Date         : 2026-08-10 18:41:34
+ * @LastEditors  : xiaomingming wujixmm@gmail.com
+ * @LastEditTime : 2026-08-10 18:41:35
+ * @FilePath     : /farm-agent/home/xmm/ai/add-coder/templates/core/scripts/mcp-server/shared/redact.ts
+ * @Description  : 
+ */
+// 敏感信息脱敏（进程层并发契约 v2：日志/错误不泄露 DATABASE_URL/密码）
+// 统一入口：response.ts 的 textResponse/errorResponse 内部调用，一处封装全覆盖所有工具
+
+const CONNECTION_URL_RE =
+  /(postgres(?:ql)?|mysql|redis|mongodb(?:\+srv)?):\/\/[^\s"'`]+/gi
+
+export function redactUrl(url: string): string {
+  // postgres://user:pass@host:port/db → postgres://user:****@host:port/db
+  return url.replace(/(:\/\/[^:/\s]+:)([^@/\s]+)(@)/, "$1****$3")
+}
+
+export function redact(text: string): string {
+  return text.replace(CONNECTION_URL_RE, (m) => {
+    try {
+      return redactUrl(m)
+    } catch {
+      return m
+    }
+  })
+}

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

@@ -1,9 +1,10 @@
 import type { ToolResponse } from "../types.js"
+import { redact } from "./redact.js"
 
 export function textResponse(text: string): { content: ToolResponse } {
-  return { content: [{ type: "text", text }] }
+  return { content: [{ type: "text", text: redact(text) }] }
 }
 
 export function errorResponse(message: string): { content: ToolResponse; isError: boolean } {
-  return { content: [{ type: "text", text: message }], isError: true }
+  return { content: [{ type: "text", text: redact(message) }], isError: true }
 }

package/templates/core/scripts/mcp-server/shared/runtime-context.ts

@@ -0,0 +1,77 @@
+import { createHash } from "crypto"
+import { realpathSync } from "fs"
+import { isAbsolute, relative, resolve } from "path"
+
+export const ADAPTER_MAGIC_DIR = Object.freeze({
+  add: ".add",
+  claude: ".claude",
+  codex: ".codex",
+  qoder: ".qoder",
+  trae: ".trae",
+  vscode: ".vscode",
+} as const)
+
+export type AdapterKey = keyof typeof ADAPTER_MAGIC_DIR
+export type AdapterMagicDir = (typeof ADAPTER_MAGIC_DIR)[AdapterKey]
+
+export interface RuntimeContextKey {
+  projectKey: string
+  adapterKey: AdapterKey
+  projectRoot: string
+  magicDir: AdapterMagicDir
+  contextId: string
+}
+
+const MAGIC_DIR_ADAPTER = new Map<AdapterMagicDir, AdapterKey>(
+  Object.entries(ADAPTER_MAGIC_DIR).map(([adapterKey, magicDir]) => [magicDir, adapterKey as AdapterKey]),
+)
+
+export function adapterKeyFromMagicDir(magicDir: string): AdapterKey {
+  const adapterKey = MAGIC_DIR_ADAPTER.get(magicDir as AdapterMagicDir)
+  if (!adapterKey) {
+    throw new Error(`未知 ADD adapter magicDir: ${magicDir}`)
+  }
+  return adapterKey
+}
+
+export function canonicalProjectRoot(projectRoot: string): string {
+  if (!projectRoot.trim()) throw new Error("PROJECT_ROOT 不能为空")
+  return realpathSync.native(resolve(projectRoot))
+}
+
+export function projectKeyFromRoot(projectRoot: string): string {
+  const canonicalRoot = canonicalProjectRoot(projectRoot)
+  return createHash("sha256").update(`add-project\0${canonicalRoot}`).digest("hex")
+}
+
+export function createRuntimeContext(projectRoot: string, magicDir: string): Readonly<RuntimeContextKey> {
+  const adapterKey = adapterKeyFromMagicDir(magicDir)
+  const canonicalRoot = canonicalProjectRoot(projectRoot)
+  const projectKey = projectKeyFromRoot(canonicalRoot)
+  return Object.freeze({
+    projectKey,
+    adapterKey,
+    projectRoot: canonicalRoot,
+    magicDir: ADAPTER_MAGIC_DIR[adapterKey],
+    contextId: `${projectKey}:${adapterKey}`,
+  })
+}
+
+export function runtimeScopeRoot(context: RuntimeContextKey): string {
+  return resolve(context.projectRoot, context.magicDir)
+}
+
+export function isPathInRuntimeScope(context: RuntimeContextKey, candidatePath: string): boolean {
+  const scopeRoot = runtimeScopeRoot(context)
+  const absoluteCandidate = isAbsolute(candidatePath) ? resolve(candidatePath) : resolve(context.projectRoot, candidatePath)
+  const scopedRelative = relative(scopeRoot, absoluteCandidate)
+  return scopedRelative === "" || (!scopedRelative.startsWith("..") && !isAbsolute(scopedRelative))
+}
+
+export function assertPathInRuntimeScope(context: RuntimeContextKey, candidatePath: string): string {
+  const absoluteCandidate = isAbsolute(candidatePath) ? resolve(candidatePath) : resolve(context.projectRoot, candidatePath)
+  if (!isPathInRuntimeScope(context, absoluteCandidate)) {
+    throw new Error(`路径越出当前 ADD adapter scope: ${absoluteCandidate}（scope=${runtimeScopeRoot(context)}）`)
+  }
+  return absoluteCandidate
+}