add-coder 0.3.33 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/retrieval/vector/pgvector.ts

@@ -0,0 +1,143 @@
+/*
+ * pgvector 向量检索适配器（Plan §3.4 轮 3 Task 3.2 / Spec §6 §VectorCapability）
+ *
+ * 设计要点：
+ *  1. **Prisma schema 不表达向量列**（架构文档定案）：扩展/表/索引由本适配器的原生 DDL 管理，
+ *     `ensureSchema()` 幂等可重放；对应 migration 只负责首次交付（见 3.4）；
+ *  2. **能力检测优先**：`capability()` 先看扩展、再看表；任一缺失都返回 unavailable/degraded，
+ *     调用方据此走 fts-only，绝不因向量缺失阻塞召回；
+ *  3. **维度真源**：表按 provider 维度建列；写入前校验向量长度，禁止脏向量进库。
+ */
+import type { ComponentHealth, RankedId, RecallFilter, RawQuerier } from "../types.js"
+import { MemoryError } from "../../domain/errors.js"
+import type { VectorSearchAdapter } from "../../embedding/index.js"
+
+export const PG_VECTOR_TABLE = "add_memory_vector"
+export const PG_VECTOR_EXTENSION = "vector"
+
+/** 向量字面量（pgvector 接受 '[1,2,3]' 形式） */
+export function pgVectorLiteral(vector: readonly number[]): string {
+  return `[${vector.map((v) => (Number.isFinite(v) ? v : 0)).join(",")}]`
+}
+
+export function pgVectorSchemaDdl(dimension: number, table = PG_VECTOR_TABLE): string[] {
+  if (!Number.isFinite(dimension) || dimension <= 0) {
+    throw new MemoryError("ERR_DIMENSION_MISMATCH", `非法向量维度：${dimension}`)
+  }
+  return [
+    `CREATE EXTENSION IF NOT EXISTS vector;`,
+    `CREATE TABLE IF NOT EXISTS "${table}" (
+  "memory_id" text PRIMARY KEY,
+  "model" text NOT NULL,
+  "dim" integer NOT NULL,
+  "embedding" vector(${dimension}) NOT NULL,
+  "updated_at" timestamptz NOT NULL DEFAULT now()
+);`,
+    `CREATE INDEX IF NOT EXISTS "${table}_embedding_hnsw" ON "${table}" USING hnsw ("embedding" vector_cosine_ops);`,
+  ]
+}
+
+export interface PgVectorAdapterOptions {
+  querier: RawQuerier
+  /** 维度真源（来自 provider 元数据） */
+  dimension: number
+  /** 模型标识：检索时按模型过滤，避免混用不同模型向量 */
+  model: string
+  table?: string
+}
+
+export interface PgVectorAdapter extends VectorSearchAdapter {
+  capability(): Promise<ComponentHealth>
+  ensureSchema(): Promise<{ statements: number }>
+}
+
+export function createPgVectorAdapter(opts: PgVectorAdapterOptions): PgVectorAdapter {
+  const table = opts.table ?? PG_VECTOR_TABLE
+
+  function assertDim(vector: readonly number[]): void {
+    if (vector.length !== opts.dimension) {
+      throw new MemoryError(
+        "ERR_DIMENSION_MISMATCH",
+        `向量维度不符：实际 ${vector.length} vs 期望 ${opts.dimension}`,
+      )
+    }
+  }
+
+  async function capability(): Promise<ComponentHealth> {
+    try {
+      const ext = await opts.querier.query<{ name: string }>(
+        `SELECT extname AS name FROM pg_extension WHERE extname = $1`,
+        [PG_VECTOR_EXTENSION],
+      )
+      if (ext.length === 0) {
+        return {
+          component: "vector-search",
+          status: "unavailable",
+          detail: `pgvector 扩展未安装（table=${table}）→ 降级 fts-only`,
+        }
+      }
+      const tbl = await opts.querier.query<{ name: string | null }>(
+        `SELECT to_regclass($1)::text AS name`,
+        [`public.${table}`],
+      )
+      if (!tbl[0]?.name) {
+        return {
+          component: "vector-search",
+          status: "degraded",
+          detail: `pgvector 已装但表 ${table} 缺失 → 需 ensureSchema()`,
+        }
+      }
+      return { component: "vector-search", status: "ok", detail: `pgvector table=${table} dim=${opts.dimension}` }
+    } catch (error) {
+      return {
+        component: "vector-search",
+        status: "unavailable",
+        detail: `pgvector 探测失败：${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  }
+
+  return {
+    async ensureSchema(): Promise<{ statements: number }> {
+      const ddl = pgVectorSchemaDdl(opts.dimension, table)
+      for (const sql of ddl) await opts.querier.query(sql, [])
+      return { statements: ddl.length }
+    },
+
+    async upsert(memoryId: string, vector: number[], model: string): Promise<void> {
+      assertDim(vector)
+      await opts.querier.query(
+        `INSERT INTO "${table}" ("memory_id", "model", "dim", "embedding")
+         VALUES ($1, $2, $3, $4::vector)
+         ON CONFLICT ("memory_id") DO UPDATE
+           SET "model" = EXCLUDED."model",
+               "dim" = EXCLUDED."dim",
+               "embedding" = EXCLUDED."embedding",
+               "updated_at" = now()`,
+        [memoryId, model, vector.length, pgVectorLiteral(vector)],
+      )
+    },
+
+    async search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]> {
+      assertDim(vector)
+      const rows = await opts.querier.query<{ memory_id: string; score: number | string }>(
+        `SELECT v."memory_id" AS memory_id, 1 - (v."embedding" <=> $1::vector) AS score
+         FROM "${table}" v
+         JOIN "AddMemory" m ON m."id" = v."memory_id"
+         WHERE m."repositoryRef" = $2
+           AND m."status"::text = ANY($3)
+           AND v."model" = $4
+         ORDER BY v."embedding" <=> $1::vector
+         LIMIT $5`,
+        [pgVectorLiteral(vector), filter.repositoryRef, [...filter.statuses], opts.model, limit],
+      )
+      return rows.map((r, i) => ({ memoryId: r.memory_id, rank: i + 1, score: Number(r.score) }))
+    },
+
+    async health(): Promise<ComponentHealth> {
+      return capability()
+    },
+
+    capability,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/vector/sqlite-vec.ts

@@ -0,0 +1,118 @@
+/*
+ * sqlite-vec 向量检索适配器（Plan §3.4 轮 3 Task 3.2 / Spec §6 §VectorCapability）
+ *
+ * ⚠️ 平台说明（诚实登记）：sqlite-vec 是原生扩展，**本仓库当前环境未安装**，因此本文件的
+ * SQL 路径只在扩展存在时才被执行（capability 探测先行）。DDL 与函数名集中在文件顶部常量，
+ * 便于在具备扩展的环境上校正；未安装时 `capability()` 返回 unavailable，召回走 fts-only。
+ *
+ * 与 pgvector 适配器同契约：能力检测 → 幂等 ensureSchema → 维度校验 → upsert/search。
+ */
+import type { ComponentHealth, RankedId, RecallFilter, RawQuerier } from "../types.js"
+import { MemoryError } from "../../domain/errors.js"
+import type { VectorSearchAdapter } from "../../embedding/index.js"
+
+export const SQLITE_VEC_TABLE = "add_memory_vector"
+/** 能力探测：vec0 模块是否注册（只读） */
+export const SQLITE_VEC_CAPABILITY_SQL = `SELECT 1 AS ok FROM pragma_module_list WHERE name = 'vec0'`
+/** 距离函数（余弦距离，越小越近） */
+export const SQLITE_VEC_DISTANCE_FN = "vec_distance_cosine"
+
+export function sqliteVecSchemaDdl(dimension: number, table = SQLITE_VEC_TABLE): string[] {
+  if (!Number.isFinite(dimension) || dimension <= 0) {
+    throw new MemoryError("ERR_DIMENSION_MISMATCH", `非法向量维度：${dimension}`)
+  }
+  return [
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${table} USING vec0(memory_id text primary key, embedding float[${dimension}]);`,
+    `CREATE TABLE IF NOT EXISTS ${table}_meta (memory_id text PRIMARY KEY, model text NOT NULL, dim integer NOT NULL, updated_at text NOT NULL DEFAULT (datetime('now')));`,
+  ]
+}
+
+export interface SqliteVecAdapterOptions {
+  querier: RawQuerier
+  dimension: number
+  model: string
+  table?: string
+}
+
+export interface SqliteVecAdapter extends VectorSearchAdapter {
+  capability(): Promise<ComponentHealth>
+  ensureSchema(): Promise<{ statements: number }>
+}
+
+export function createSqliteVecAdapter(opts: SqliteVecAdapterOptions): SqliteVecAdapter {
+  const table = opts.table ?? SQLITE_VEC_TABLE
+
+  function assertDim(vector: readonly number[]): void {
+    if (vector.length !== opts.dimension) {
+      throw new MemoryError(
+        "ERR_DIMENSION_MISMATCH",
+        `向量维度不符：实际 ${vector.length} vs 期望 ${opts.dimension}`,
+      )
+    }
+  }
+
+  async function capability(): Promise<ComponentHealth> {
+    try {
+      const rows = await opts.querier.query<{ ok: number }>(SQLITE_VEC_CAPABILITY_SQL, [])
+      if (rows.length === 0) {
+        return {
+          component: "vector-search",
+          status: "unavailable",
+          detail: "sqlite-vec(vec0) 未安装 → 降级 fts-only",
+        }
+      }
+      return { component: "vector-search", status: "ok", detail: `sqlite-vec table=${table} dim=${opts.dimension}` }
+    } catch (error) {
+      return {
+        component: "vector-search",
+        status: "unavailable",
+        detail: `sqlite-vec 探测失败：${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  }
+
+  return {
+    async ensureSchema(): Promise<{ statements: number }> {
+      const ddl = sqliteVecSchemaDdl(opts.dimension, table)
+      for (const sql of ddl) await opts.querier.query(sql, [])
+      return { statements: ddl.length }
+    },
+
+    async upsert(memoryId: string, vector: number[], model: string): Promise<void> {
+      assertDim(vector)
+      // vec_f32 接受 JSON 文本形式；绑定为字符串参数
+      await opts.querier.query(
+        `INSERT INTO ${table}(memory_id, embedding) VALUES (?, vec_f32(?))
+         ON CONFLICT(memory_id) DO UPDATE SET embedding = vec_f32(?)`,
+        [memoryId, JSON.stringify(vector), JSON.stringify(vector)],
+      )
+      await opts.querier.query(
+        `INSERT INTO ${table}_meta(memory_id, model, dim) VALUES (?, ?, ?)
+         ON CONFLICT(memory_id) DO UPDATE SET model = excluded.model, dim = excluded.dim`,
+        [memoryId, model, vector.length],
+      )
+    },
+
+    async search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]> {
+      assertDim(vector)
+      const rows = await opts.querier.query<{ memory_id: string; distance: number | string }>(
+        `SELECT v.memory_id AS memory_id, ${SQLITE_VEC_DISTANCE_FN}(v.embedding, vec_f32(?)) AS distance
+         FROM ${table} v
+         JOIN ${table}_meta meta ON meta.memory_id = v.memory_id
+         JOIN "AddMemory" m ON m.id = v.memory_id
+         WHERE m.repositoryRef = ?
+           AND meta.model = ?
+         ORDER BY distance ASC
+         LIMIT ?`,
+        [JSON.stringify(vector), filter.repositoryRef, opts.model, limit],
+      )
+      return rows.map((r, i) => ({ memoryId: r.memory_id, rank: i + 1, score: 1 - Number(r.distance) }))
+    },
+
+    async health(): Promise<ComponentHealth> {
+      return capability()
+    },
+
+    capability,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/switches.ts

@@ -0,0 +1,39 @@
+/*
+ * Memory 子系统发布开关（Spec §10，Plan §9.3）
+ *
+ * 约束：governance Hook（同步 spawn 子进程，≤200ms 预算）与 jobs（异步）共用本模块，
+ * 因此全部函数必须是同步、纯环境变量读取，禁止任何 IO/DB 访问。
+ *
+ * 开关：
+ * - ADD_MEMORY_RECALL_MODE = off | shadow | inject（默认 shadow：召回可执行并落审计，但 Hook 不注入上下文）
+ * - ADD_MEMORY_MAX_TOKENS：L1 注入 token 预算（默认 600）
+ * - ADD_MEMORY_EVIDENCE = off | on（默认 on：PostToolUse 白名单采证入队）
+ */
+
+export type RecallMode = "off" | "shadow" | "inject"
+
+export function recallMode(env: NodeJS.ProcessEnv = process.env): RecallMode {
+  const v = (env.ADD_MEMORY_RECALL_MODE ?? "shadow").toLowerCase()
+  return v === "off" || v === "inject" ? v : "shadow"
+}
+
+export function memoryMaxTokens(env: NodeJS.ProcessEnv = process.env): number {
+  const n = Number(env.ADD_MEMORY_MAX_TOKENS ?? 600)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 600
+}
+
+export function evidenceEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.ADD_MEMORY_EVIDENCE ?? "on").toLowerCase() !== "off"
+}
+
+/** 记忆工作目录（快照 + 事件队列所在）：${magicDir}/memory/ */
+export const MEMORY_DIR_NAME = "memory"
+/** L1/L2 快照文件名 */
+export const L1_SNAPSHOT_FILE = "l1-context.md"
+export const L2_SNAPSHOT_FILE = "l2-context.md"
+/** PostToolUse 采证事件队列（jsonl，append-only，由 consolidation job 消费） */
+export const EVIDENCE_QUEUE_FILE = "evidence-queue.jsonl"
+/** evidence 队列消费进度标记（已处理字节偏移） */
+export const EVIDENCE_OFFSET_FILE = "evidence-queue.offset"
+/** L1 快照新鲜度上限（毫秒，默认 7 天）：过期不注入 */
+export const L1_SNAPSHOT_TTL_MS = 7 * 24 * 60 * 60 * 1000

package/templates/core/scripts/mcp-server/shared/review-files.ts

@@ -0,0 +1,22 @@
+/*
+ * 审查文档命名识别（纯函数；2026-09-14 从 tools/review.ts 抽出）
+ *
+ * 抽出原因：① 纯函数不该和 prisma/工具注册绑在一起（拖进来就要求 DB 依赖，测试得打 mock）；
+ * ② 仓库里并存两套命名，识别规则需要被用例直接钉住：
+ *    - `{planPrefix}-review-v1.md`（历史）
+ *    - `{planPrefix}-plan-v1-review.md`（create_hitl 的占位路径落点／现行）
+ *    旧匹配要求包含 `-review-`（review 后必须紧跟连字符），会把后一整类漏掉。
+ */
+import { basename } from "path"
+
+/** 从文件列表里挑出审查文档（.md 且文件名含 review，大小写不敏感） */
+export function pickReviewFiles(files: readonly string[]): string[] {
+  return files.filter((f) => f.endsWith(".md") && basename(f).toLowerCase().includes("review"))
+}
+
+/** 从审查文件名推导 planName 前缀（两种命名都要剥干净） */
+export function derivePlanNameFromReviewFile(file: string): string {
+  return basename(file, ".md")
+    .replace(/-review-(implementation|runtime).*$/, "") // 变体后缀
+    .replace(/-review.*$/, "")                          // 普通 review 后缀（含 -review-v1 / -review）
+}

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

@@ -0,0 +1,235 @@
+/*
+ * 产物-进程新鲜度（Plan hitl-widget-runtime-gap §Freshness）
+ *
+ * 背景：`npm run sync` 会重写 `{magicDir}/scripts/mcp-server.ts` 等产物，但不会重启正在运行的
+ * server 进程 → 出现「产物是新的、跑的是旧代码」的静默陈旧（实测：进程 Sep 12 11:49 vs 产物 09-13 09:47）。
+ *
+ * 覆盖面：**6 个 adapter 各自都有 server 副本**，因此检测范围是全部 magic 目录，不限于 .codex。
+ * 判定不确定时一律返回 "unknown"（宁可漏报，不误报"需重启"）。
+ */
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { execSync } from "node:child_process"
+
+export const RESTART_MARKER_FILE = ".mcp-restart-required"
+export const DEFAULT_MAGIC_DIRS = [".codex", ".add", ".qoder", ".claude", ".vscode", ".trae"] as const
+
+export interface RunningServer {
+  magicDir: string
+  pid: number
+  ppid: number
+  command: string
+  startedAt?: Date
+  /**
+   * 启动者已死（ppid 指向 init/systemd）——**残留族**（2026-09-14 新增）：
+   * 实测成因：IDE/app 退出时通常只杀直接子进程（`npx`），
+   * `npm exec → sh -c → tsx → node` 这几代被 reparent 到 systemd 继续存活
+   * （同一逻辑 server 5 个进程；旧实例的 server 在 app 重启后仍活了 20+ 分钟）。
+   * 这类进程的 stdio 对端已消失，属可回收垃圾；也不应参与新鲜度判定。
+   */
+  orphan?: boolean
+}
+
+export interface FreshnessInfo {
+  stale: boolean | "unknown"
+  magicDir: string
+  processStartedAt?: string
+  artifactMtime?: string
+  markerPath?: string
+  detail: string
+}
+
+export interface FreshnessDeps {
+  /** 测试注入：ps 输出（`ps -eo pid=,etimes=,args=` 形式） */
+  psOutput?: string
+  listServers?: () => RunningServer[]
+  mtimeOf?: (path: string) => Date | null
+  markerExists?: (path: string) => boolean
+  now?: () => Date
+}
+
+/** 扫描全部 adapter 的运行中 MCP server（解析失败返回空数组，不抛） */
+export function listRunningMcpServers(deps: Pick<FreshnessDeps, "psOutput" | "now"> = {}): RunningServer[] {
+  let out = deps.psOutput
+  if (out === undefined) {
+    try {
+      out = execSync("ps -eo pid=,ppid=,etimes=,args=", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] })
+    } catch {
+      return []
+    }
+  }
+  const now = (deps.now ?? (() => new Date()))()
+  const lines = out.split("\n")
+  // 启动者已死的判定依据：ppid 落在 init / systemd 上（reparent 的结果）
+  const supervisorPids = new Set<number>()
+  const allPids = new Set<number>()
+  for (const line of lines) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/)
+    if (!m) continue
+    allPids.add(Number(m[1]))
+    if (/(^|\/)(systemd|init)(\s|$)/.test(m[4])) supervisorPids.add(Number(m[1]))
+  }
+  const servers: RunningServer[] = []
+  for (const line of lines) {
+    if (!line.includes("mcp-server.ts")) continue
+    if (line.includes("mcp-restart-notice")) continue // 跳过本脚本自身
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/)
+    if (!m) continue
+    const ppid = Number(m[2])
+    const cmd = m[4]
+    /*
+     * 噪声过滤（2026-09-14 收窄）：
+     * 旧实现是 `cmd.includes("node_modules") → skip`，把**我们自己的 tsx 启动层**也一并挡掉
+     * （`node …/node_modules/.bin/../tsx/dist/cli.mjs <magicDir>/scripts/mcp-server.ts`）——
+     * 后果是回收只能杀掉表层 npx/npm，深层 node/tsx 残部继续存活（实测：回收后仍留
+     * `135292/135310`、`135897/135913` 两族残部）。
+     * 现在只排除「安装副本」：dot 目录直接位于 node_modules 树内
+     * （如 `node_modules/<pkg>/.codex/scripts/mcp-server.ts`），其余照常纳入。
+     */
+    if (/(^|[/\s])node_modules\/(?:[^/\s]+\/)*\.[a-z][a-z0-9-]*\/scripts\/mcp-server\.ts/.test(cmd)) continue
+    // magic 段必须以点开头（.codex/.qoder…），且路径后是行尾或参数分隔
+    const magic = cmd.match(/(?:^|[/\s])(\.[a-z][a-z0-9-]*)\/scripts\/mcp-server\.ts(?:\s|$)/)
+    if (!magic) continue
+    const etimes = Number(m[3])
+    servers.push({
+      magicDir: magic[1],
+      pid: Number(m[1]),
+      ppid,
+      command: cmd,
+      startedAt: Number.isFinite(etimes) ? new Date(now.getTime() - etimes * 1000) : undefined,
+      orphan: false, // 先按 o 标记，稍后按"整族"传播（见下）
+    })
+  }
+  /*
+   * 孤儿按**整族**传播：链上后几代（npm exec / sh -c / tsx / node）的 ppid 指向族内进程，
+   * 单看自身 ppid 判不出来 —— 只有族根（其 ppid 不在族内）能反映"启动者是否还在"。
+   * 族根判定为孤儿时，整族标记（含 rootPpid 不存在＝父进程已消失的情形）。
+   */
+  const byPid = new Map(servers.map((s) => [s.pid, s]))
+  const childrenOf = new Map<number, number[]>()
+  for (const s of servers) {
+    if (!byPid.has(s.ppid)) continue
+    childrenOf.set(s.ppid, [...(childrenOf.get(s.ppid) ?? []), s.pid])
+  }
+  for (const s of servers) {
+    if (byPid.has(s.ppid)) continue // 不是族根
+    const rootParentGone = s.ppid === 1 || supervisorPids.has(s.ppid) || !allPids.has(s.ppid)
+    if (!rootParentGone) continue
+    const stack = [s.pid]
+    while (stack.length > 0) {
+      const pid = stack.pop() as number
+      const node = byPid.get(pid)
+      if (!node || node.orphan) continue
+      node.orphan = true
+      stack.push(...(childrenOf.get(pid) ?? []))
+    }
+  }
+  return servers
+}
+
+/**
+ * 残留族清单（供 `scripts/mcp-restart-notice.ts` 回收）：
+ * 只按 adapter 取**全部孤儿 pid**（含 npx/npm/sh/tsx/node 各代），非孤儿一律不动。
+ */
+export function orphanPidsToReap(servers: readonly RunningServer[]): number[] {
+  return [...new Set(servers.filter((s) => s.orphan).map((s) => s.pid))].sort((a, b) => a - b)
+}
+
+/**
+ * 按 adapter 聚合：同一 adapter 常同时存在多条进程记录（npx / npm exec / sh -c / tsx 包装链）。
+ * 取**最早的启动时间**（最保守判定）合成一条，避免一个逻辑 server 被报成十几条。
+ */
+export function earliestPerAdapter(servers: RunningServer[]): Map<string, RunningServer> {
+  const out = new Map<string, RunningServer>()
+  for (const s of servers) {
+    const prev = out.get(s.magicDir)
+    if (!prev) {
+      out.set(s.magicDir, s)
+      continue
+    }
+    const prevAt = prev.startedAt?.getTime() ?? Number.POSITIVE_INFINITY
+    const curAt = s.startedAt?.getTime() ?? Number.POSITIVE_INFINITY
+    if (curAt < prevAt) out.set(s.magicDir, s)
+  }
+  return out
+}
+
+/** 判定单个 adapter 的新鲜度（未知一律 "unknown"） */
+export function computeFreshness(
+  magicDir: string,
+  projectRoot: string,
+  deps: FreshnessDeps = {},
+): FreshnessInfo {
+  const artifactPath = join(projectRoot, magicDir, "scripts", "mcp-server.ts")
+  const markerPath = join(projectRoot, magicDir, RESTART_MARKER_FILE)
+  const mtime = deps.mtimeOf
+    ? deps.mtimeOf(artifactPath)
+    : existsSync(artifactPath)
+      ? statSync(artifactPath).mtime
+      : null
+  const hasMarker = deps.markerExists ? deps.markerExists(markerPath) : existsSync(markerPath)
+  const base: Omit<FreshnessInfo, "stale" | "detail"> = {
+    magicDir,
+    ...(mtime ? { artifactMtime: mtime.toISOString() } : {}),
+    ...(hasMarker ? { markerPath } : {}),
+  }
+  if (!mtime) {
+    return { ...base, stale: "unknown", detail: "产物不存在，无法判定新鲜度" }
+  }
+  const allServers = deps.listServers ? deps.listServers() : listRunningMcpServers()
+  // 残留族（启动者已死）不参与新鲜度判定：否则"孤儿进程"会把判定带偏
+  // （实测：旧实例的 server 让新鲜度报出错误的 pid / 错误的 stale 值）
+  const perAdapter = earliestPerAdapter(allServers.filter((s) => s.magicDir === magicDir && !s.orphan))
+  const server = perAdapter.get(magicDir)
+  if (!server) {
+    return { ...base, stale: false, detail: `${magicDir} 无运行中 server` }
+  }
+  if (!server.startedAt) {
+    return { ...base, stale: "unknown", detail: `进程 pid=${server.pid} 启动时间不可得` }
+  }
+  const stale = server.startedAt.getTime() < mtime.getTime()
+  return {
+    ...base,
+    processStartedAt: server.startedAt.toISOString(),
+    stale,
+    detail: stale
+      ? `${magicDir} server(pid ${server.pid}) 启动早于产物更新，需重启`
+      : `${magicDir} server(pid ${server.pid}) 晚于产物，已最新`,
+  }
+}
+
+/** 写重启标记（失败返回 null，调用方 fail-open） */
+export function writeRestartRequiredMarker(
+  magicDir: string,
+  projectRoot: string,
+  info: { reason: string; pid?: number; artifactMtime?: string },
+): string | null {
+  const markerPath = join(projectRoot, magicDir, RESTART_MARKER_FILE)
+  try {
+    writeFileSync(
+      markerPath,
+      JSON.stringify({ magicDir, at: new Date().toISOString(), ...info }, null, 2),
+      "utf-8",
+    )
+    return markerPath
+  } catch {
+    return null
+  }
+}
+
+export function readRestartRequiredMarker(magicDir: string, projectRoot: string): string | null {
+  const markerPath = join(projectRoot, magicDir, RESTART_MARKER_FILE)
+  try {
+    return existsSync(markerPath) ? readFileSync(markerPath, "utf-8") : null
+  } catch {
+    return null
+  }
+}
+
+export function clearRestartRequiredMarker(magicDir: string, projectRoot: string): void {
+  try {
+    rmSync(join(projectRoot, magicDir, RESTART_MARKER_FILE), { force: true })
+  } catch {
+    /* fail-open */
+  }
+}

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

@@ -29,7 +29,14 @@ import {
   getEmbeddings,
 } from "./helpers.js";
 import { getRuntimeContext } from "../../shared/env.js";
-import { extractSpecRef } from "../../shared/dps-spec-ref.js";
+import {
+  buildGateCaptureDetail,
+  createGateWriterDeps,
+  deriveGateRunId,
+  formatGateCaptureSummary,
+  writeGateMetric,
+  GATE_METRIC_TYPE,
+} from "../../shared/memory/metrics/gate-writer.js";
 
 export function registerCheckDps(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext();
@@ -80,8 +87,10 @@ export function registerCheckDps(server: ToolRegistrar) {
         let sn = basename(pm).replace(/-plan-v\d+\.md$/, ""),
           sc = "";
         if (pc) {
-          const specRef = extractSpecRef(pc);
-          if (specRef) sn = specRef.specDir;
+          const sr = pc.match(
+            /Spec[:|\s`]+\.?(qoder|claude|add|vscode)\/specs\/([^/`\s]+)/,
+          );
+          if (sr) sn = sr[2];
         }
         const sp = join(specsDir, sn, "spec.md");
         sc = (await readFileSafe(sp)) || "";
@@ -561,6 +570,35 @@ export function registerCheckDps(server: ToolRegistrar) {
           /* 非阻塞：回写失败不影响 DPS 判定 */
         }
 
+        // ── Gate 采证（Spec §GateMetric）：评分已完成 → 独立提交 MetricSnapshot；
+        //    runId 由被评分内容派生（同内容重放 = 重复采证）；旁路不阻塞评分返回 ──
+        const gateSeed = `${pc}\n${sc}\n${rc}`;
+        const captureInput = {
+          gate: "check_dps" as const,
+          planKeyword: pp,
+          runId: deriveGateRunId("check_dps", pp, gateSeed),
+          metricType: GATE_METRIC_TYPE.check_dps,
+          score: dps,
+          repository: runtimeContext.projectKey,
+          dimensionScores: {
+            semantic: semScore,
+            entropy: entropyScore,
+            cpm: cpmScore,
+            structure: structFinal,
+          },
+          baseline: CFG.THRESHOLD_PASS,
+          unit: "score",
+        };
+        const capture = await writeGateMetric(
+          captureInput,
+          createGateWriterDeps((prisma as Record<string, unknown>).addMetricSnapshot),
+        );
+        parts.push(
+          "",
+          "=== Gate 采证（MetricSnapshot）===",
+          `  ${formatGateCaptureSummary(buildGateCaptureDetail(captureInput, capture))}`,
+        );
+
         return textResponse(parts.join("\n"));
       } catch (e) {
         return errorResponse(