add-coder 0.3.38 → 0.3.40

package/templates/core/scripts/mcp-server/shared/memory/retrieval/cjk-tokenize.ts

@@ -0,0 +1,62 @@
+/*
+ * CJK 分词契约（单一真源）— Plan add-coder-memory-cjk-bigram-baseline Task 1.1 / Spec §1
+ *
+ * 为什么需要它：词法基线要从「pg_trgm 相似度 + to_tsvector('simple')」换成 **bigram 分词后的 FTS**，
+ * 前提是**写入侧与查询侧共用同一套 tokenization**——否则索引里的 token 与查询 token 对不上，
+ * 召回会是"看起来有索引、实际命中不了"。此前 bigram 只存在于查询侧（`query-terms.ts`），
+ * 文档侧无对应展开，故本模块把两侧收敛到同一实现、同一上限。
+ *
+ * 约束（Spec §1 WHEN-THEN）：纯函数、无 IO、无依赖；同一输入幂等；超上限按出现顺序确定性截断。
+ */
+import { normalizeContent } from "../domain/dedup.js"
+
+/** token 上限（与既有 query-terms 的 MAX_TERMS 对齐；确定性截断，不随机抽样） */
+export const MAX_TOKENS = 24
+
+/** CJK 连续段（含扩展 A / 假名，与既有 query-terms 的字符集一致） */
+const CJK_SEGMENT = /[㐀-鿿぀-ヿ]+/g
+
+/** 拉丁/数字词（≥2 字符；1 字符噪声太大，不作为独立 token） */
+const LATIN_WORD = /[a-z0-9_]{2,}/g
+
+/**
+ * 统一分词：拉丁词（≥2 字符，大小写归一）+ CJK 段滑动二元组（单字段保留单字）。
+ * 返回**去重且按出现顺序**的 token 数组；超 `MAX_TOKENS` 截断。
+ */
+export function tokenize(text: string): string[] {
+  const norm = normalizeContent(text)
+  const terms: string[] = []
+  const seen = new Set<string>()
+  const push = (t: string) => {
+    if (!seen.has(t) && terms.length < MAX_TOKENS) {
+      seen.add(t)
+      terms.push(t)
+    }
+  }
+
+  for (const m of norm.matchAll(LATIN_WORD)) push(m[0])
+
+  for (const seg of norm.matchAll(CJK_SEGMENT)) {
+    const s = seg[0]
+    if (s.length === 1) {
+      push(s)
+      continue
+    }
+    for (let i = 0; i < s.length - 1; i++) push(s.slice(i, i + 2))
+  }
+
+  return terms
+}
+
+/**
+ * 文档侧展开：原始文本 → 空格分隔 token 串（写入期落 `searchText`，与查询侧同契约）。
+ * 例：`"新增端口"` → `"新增 增端 端口"`。
+ */
+export function expandForIndex(text: string): string {
+  return tokenize(text).join(" ")
+}
+
+/** 查询侧展开：查询串 → token 数组（与 `expandForIndex` 同一实现、同一上限） */
+export function expandForQuery(query: string): string[] {
+  return tokenize(query)
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/pg.ts

@@ -42,6 +42,36 @@ LIMIT $${5 + terms.length}
   }
 }
 
+/**
+ * 主通道 SQL（轮 3 / Task 3.1）：`searchText` 的 tsvector 表达式索引。
+ * `searchText` 由写入期以**同一 tokenization 契约**产出（jieba 主 / bigram 兜底）⇒ 读写同源。
+ * 与旧实现的区别：旧 B 通道对 `topic||content` 直接 `to_tsvector('simple')`，中文整段落一个 token（等于没索引）。
+ */
+const MAIN_CHANNEL_SQL = `
+SELECT id, ts_rank(to_tsvector('simple', "searchText"), $1::tsquery) AS score
+FROM "AddMemory"
+WHERE "repositoryRef" = $2
+  AND "status"::text = ANY($3)
+  AND ("validUntil" IS NULL OR "validUntil" > $4)
+  AND ($5::text[] IS NULL OR "kind"::text = ANY($5))
+  AND to_tsvector('simple', "searchText") @@ $1::tsquery
+ORDER BY score DESC
+LIMIT $6
+`
+
+/**
+ * 由查询串构造 tsquery：token 用**引号包裹 + OR** 连接（召回优先），并剥离会破坏 tsquery 语法的字符。
+ * 返回 null 表示该查询无法构造有效 tsquery（如纯符号）→ 主通道跳过，由补充通道兜底。
+ */
+function buildTsquery(query: string): string | null {
+  const safe = extractQueryTerms(query)
+    .map((t) => t.replace(/[^\p{L}\p{N}_]/gu, ""))
+    .filter((t) => t.length > 0)
+  if (safe.length === 0) return null
+  return safe.map((t) => `'${t}'`).join(" | ")
+}
+
+/** 补充通道 A：pg_trgm 相似度（子串/模糊召回；不再是基线） */
 const CHANNEL_A_SQL = `
 SELECT id,
        GREATEST(
@@ -97,38 +127,60 @@ export function createPgFtsAdapter(q: RawQuerier): LexicalSearchAdapter & {
   searchChannels(query: string, filter: RecallFilter, limit: number): Promise<RankedId[][]>
 } {
   return {
-    id: "pg-trgm",
+    id: "pg-bigram-fts",
     async search(query, filter, limit) {
       const channels = await this.searchChannels(query, filter, limit)
-      return channels[0] ?? []
+      // 主通道可能因"查询无有效 token"为空（如纯符号）→ 返回首个非空通道，避免整条检索空手而归
+      return channels.find((c) => c.length > 0) ?? []
     },
     async searchChannels(query, filter, limit) {
-      const a = await runChannel(q, CHANNEL_A_SQL, query, filter, limit)
-      let b: RankedId[] = []
-      try {
-        b = await runChannel(q, CHANNEL_B_SQL, query, filter, limit)
-      } catch {
-        // tsquery 通道失败（如查询含特殊字符）不阻断主通道
+      // 主通道：searchText 的 tsvector（读写同源）
+      let main: RankedId[] = []
+      const tsquery = buildTsquery(query)
+      if (tsquery) {
+        try {
+          const rows = await q.query<{ id: string; score: number | string }>(MAIN_CHANNEL_SQL, [
+            tsquery,
+            filter.repositoryRef,
+            [...filter.statuses],
+            filter.now,
+            filter.kinds && filter.kinds.length > 0 ? [...filter.kinds] : null,
+            limit,
+          ])
+          main = rows.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: Number(r.score) }))
+        } catch {
+          // 主通道异常（索引缺失 / tsquery 非法）不阻断补充通道；健康度由 health() 显式上报
+          main = []
+        }
       }
+      // 补充通道 A：pg_trgm（子串/模糊）
+      const a = await runChannel(q, CHANNEL_A_SQL, query, filter, limit)
       let c: RankedId[] = []
       const cc = channelC(query, filter, limit)
       if (cc) {
         const rows = await q.query<{ id: string; score: number | string }>(cc.sql, cc.params)
         c = rows.map((r, i) => ({ memoryId: r.id, rank: i + 1, score: Number(r.score) }))
       }
-      return [a, b, c]
+      return [main, a, c]
     },
     async health(): Promise<ComponentHealth> {
       try {
-        const ext = await q.query<{ count: number | string }>(
-          "SELECT COUNT(*)::int AS count FROM pg_extension WHERE extname = 'pg_trgm'", [])
-        if (Number(ext[0]?.count ?? 0) < 1) {
-          return { component: "pg-fts", status: "degraded", detail: "pg_trgm 扩展缺失" }
+        // 轮 3 / Task 3.1 新判定：**主通道**（searchText 列 + 表达式索引）才决定是否 degraded；
+        // 补充通道（pg_trgm）缺失只影响子串/模糊召回，不再整体降级。
+        const col = await q.query<{ count: number | string }>(
+          "SELECT COUNT(*)::int AS count FROM information_schema.columns WHERE table_name = 'AddMemory' AND column_name = 'searchText'", [])
+        if (Number(col[0]?.count ?? 0) < 1) {
+          return { component: "pg-fts", status: "degraded", detail: "AddMemory.searchText 列缺失（迁移未应用）" }
+        }
+        const mainIdx = await q.query<{ count: number | string }>(
+          "SELECT COUNT(*)::int AS count FROM pg_indexes WHERE tablename = 'AddMemory' AND indexname = 'AddMemory_searchText_tsv_idx'", [])
+        if (Number(mainIdx[0]?.count ?? 0) < 1) {
+          return { component: "pg-fts", status: "degraded", detail: "主通道表达式索引缺失（AddMemory_searchText_tsv_idx），需 reindex" }
         }
-        const idx = await q.query<{ count: number | string }>(
+        const trgm = await q.query<{ count: number | string }>(
           "SELECT COUNT(*)::int AS count FROM pg_indexes WHERE tablename = 'AddMemory' AND indexname LIKE '%trgm%'", [])
-        if (Number(idx[0]?.count ?? 0) < 2) {
-          return { component: "pg-fts", status: "degraded", detail: "trgm GIN 索引缺失，需 reindex" }
+        if (Number(trgm[0]?.count ?? 0) < 2) {
+          return { component: "pg-fts", status: "ok", detail: "补充通道（pg_trgm）索引缺失：子串/模糊召回受限，主通道正常" }
         }
         return { component: "pg-fts", status: "ok" }
       } catch (e) {

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql

@@ -9,10 +9,10 @@
 -- （其要求 INTEGER rowid），故采用独立 FTS 表 + 触发器同步。
 -- 幂等：全部 IF NOT EXISTS，可重复应用。
 
-CREATE VIRTUAL TABLE IF NOT EXISTS add_memory_fts USING fts5(memory_id UNINDEXED, topic, content, tokenize = 'trigram');
+CREATE VIRTUAL TABLE IF NOT EXISTS add_memory_fts USING fts5(memory_id UNINDEXED, searchText, tokenize = 'unicode61');
 
-CREATE TRIGGER IF NOT EXISTS add_memory_fts_ai AFTER INSERT ON "AddMemory" BEGIN INSERT INTO add_memory_fts(memory_id, topic, content) VALUES (new.id, new.topic, new.content); END;
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_ai AFTER INSERT ON "AddMemory" BEGIN INSERT INTO add_memory_fts(memory_id, searchText) VALUES (new.id, new.searchText); END;
 
-CREATE TRIGGER IF NOT EXISTS add_memory_fts_au AFTER UPDATE ON "AddMemory" BEGIN DELETE FROM add_memory_fts WHERE memory_id = old.id; INSERT INTO add_memory_fts(memory_id, topic, content) VALUES (new.id, new.topic, new.content); END;
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_au AFTER UPDATE ON "AddMemory" BEGIN DELETE FROM add_memory_fts WHERE memory_id = old.id; INSERT INTO add_memory_fts(memory_id, searchText) VALUES (new.id, new.searchText); END;
 
 CREATE TRIGGER IF NOT EXISTS add_memory_fts_ad AFTER DELETE ON "AddMemory" BEGIN DELETE FROM add_memory_fts WHERE memory_id = old.id; END;

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

@@ -34,13 +34,24 @@ LIMIT ?
   return { sql, params: [...termParams, filter.repositoryRef, filter.now.toISOString(), limit] }
 }
 
-/** 抽取可参与 trigram MATCH 的片段（连续 CJK/字母数字，≥3 字符），逐段加引号 */
-export function buildTrigramQuery(raw: string): string | null {
-  const segments = raw.match(/[㐀-鿿぀-ヿA-Za-z0-9_]+/g) ?? []
-  const usable = segments.filter((s) => s.length >= 3).map((s) => `"${s}"`)
-  return usable.length > 0 ? usable.join(" OR ") : null
+/**
+ * 构造 FTS5 MATCH 串（轮 3 / Task 3.2）。
+ *
+ * 变更理由：虚表已从 `topic/content + trigram` 改为 **`searchText` + unicode61**（写入期 token 串），
+ * 因此查询侧不再需要"≥3 字符片段"这种 trigram 窗口补偿——直接把查询用**同一 tokenization 契约**
+ * 展开成 token，逐 token 加引号后 `OR` 连接即可（1-2 字中文 token 天然可命中）。
+ */
+export function buildMatchQuery(raw: string): string | null {
+  const tokens = extractQueryTerms(raw)
+    .map((t) => t.replace(/"/g, ""))
+    .filter((t) => t.length > 0)
+  if (tokens.length === 0) return null
+  return tokens.map((t) => `"${t}"`).join(" OR ")
 }
 
+/** @deprecated 旧名（trigram 时代）；等价于 `buildMatchQuery`，保留仅为兼容外部导入 */
+export const buildTrigramQuery = buildMatchQuery
+
 const CHANNEL_A_SQL = `
 SELECT m.id AS id, bm25(add_memory_fts) AS score
 FROM add_memory_fts f
@@ -75,7 +86,7 @@ export function createSqliteFtsAdapter(q: RawQuerier): LexicalSearchAdapter & {
     },
     async searchChannels(query, filter, limit) {
       let a: RankedId[] = []
-      const matchQ = buildTrigramQuery(query)
+      const matchQ = buildMatchQuery(query)
       if (matchQ) {
         const rows = await q.query<{ id: string; score: number }>(
           buildSql(CHANNEL_A_SQL, filter), [matchQ, filter.repositoryRef, filter.now.toISOString(), limit],
@@ -97,6 +108,12 @@ export function createSqliteFtsAdapter(q: RawQuerier): LexicalSearchAdapter & {
         if (rows.length < 1) {
           return { component: "sqlite-fts", status: "unavailable", detail: "add_memory_fts 虚表缺失，需执行 sqlite-fts5.sql" }
         }
+        // 轮 3 / Task 3.2：虚表列必须是 searchText（unicode61 口径）；否则是旧库未升级
+        const cols = await q.query<{ name: string }>("PRAGMA table_info(add_memory_fts)", [])
+        const hasSearchText = cols.some((c) => c.name === "searchText")
+        if (!hasSearchText) {
+          return { component: "sqlite-fts", status: "degraded", detail: "FTS 虚表仍是旧列（topic/content），需执行 sqlite-fts5.sql 重建" }
+        }
         return { component: "sqlite-fts", status: "ok" }
       } catch (e) {
         return { component: "sqlite-fts", status: "unavailable", detail: e instanceof Error ? e.message : String(e) }

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts-fingerprint.ts

@@ -0,0 +1,116 @@
+// fts-fingerprint.ts — 记忆检索「分词器 + 词典」指纹（Plan 轮 2 Task 2.7 真源）
+//
+// 为什么在 templates 侧：指纹要同时被 **MCP 工具（get_memory_health）** 与 **CLI（memory:reindex --probe）** 消费，
+// 而 templates 是随包分发的真源；`src/lib/memory-fts-fingerprint.ts` 只是面向仓根上下文的再导出。
+//
+// 语义：`searchText` 是写入期产出的 token 串。分词器实现或用户词典一变，历史行的 token 就与查询侧不同源
+// —— 表现为"索引在、命中不了"，且**不报错**。指纹给出可判定信号：能否证明历史 token 与当前分词器同源。
+//   ① jieba 版本（未装 → "bigram"）② 用户词典内容哈希（不存在 → "none"）③ tokenization 契约版本
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+
+/** tokenization 规则（滑窗/过滤/上限/检索语义）变更时必须递增 */
+export const TOKENIZATION_CONTRACT_VERSION = 1
+
+export interface FtsFingerprint {
+  value: string
+  parts: { jieba: string; userDict: string; contract: number }
+}
+
+export function computeFtsFingerprint(input: {
+  projectRoot: string
+  magicDir: string
+  jiebaVersion?: string | null
+  userDictPath?: string
+}): FtsFingerprint {
+  const userDictPath =
+    input.userDictPath ?? join(input.projectRoot, input.magicDir, "data", "jieba", "userdict.txt")
+  let userDict = "none"
+  if (existsSync(userDictPath)) {
+    userDict = createHash("sha256").update(readFileSync(userDictPath)).digest("hex").slice(0, 12)
+  }
+  const jieba = input.jiebaVersion ?? detectJiebaVersion()
+  const value = createHash("sha256")
+    .update(`tokenization-v${TOKENIZATION_CONTRACT_VERSION}|${jieba ?? "bigram"}|${userDict}`)
+    .digest("hex")
+    .slice(0, 12)
+  return { value, parts: { jieba: jieba ?? "bigram", userDict, contract: TOKENIZATION_CONTRACT_VERSION } }
+}
+
+/** 探测已安装的 jieba 版本；未安装 → null（表示走 bigram 兜底） */
+export function detectJiebaVersion(): string | null {
+  try {
+    const req = createRequire(import.meta.url)
+    const pkg = req("@node-rs/jieba/package.json") as { version?: string }
+    return pkg.version ?? "unknown"
+  } catch {
+    return null
+  }
+}
+
+export interface RecordedFingerprint {
+  fingerprint: string
+  recordedAt: string
+  parts: FtsFingerprint["parts"]
+}
+
+export function fingerprintMarkerPath(projectRoot: string, magicDir: string): string {
+  return join(projectRoot, magicDir, "memory", "fts-fingerprint.json")
+}
+
+export function readRecordedFingerprint(projectRoot: string, magicDir: string): RecordedFingerprint | null {
+  const p = fingerprintMarkerPath(projectRoot, magicDir)
+  if (!existsSync(p)) return null
+  try {
+    return JSON.parse(readFileSync(p, "utf-8")) as RecordedFingerprint
+  } catch {
+    return null
+  }
+}
+
+export function writeRecordedFingerprint(
+  projectRoot: string,
+  magicDir: string,
+  fingerprint: FtsFingerprint,
+  now: Date = new Date(),
+): string {
+  const p = fingerprintMarkerPath(projectRoot, magicDir)
+  mkdirSync(dirname(p), { recursive: true })
+  const payload: RecordedFingerprint = {
+    fingerprint: fingerprint.value,
+    recordedAt: now.toISOString(),
+    parts: fingerprint.parts,
+  }
+  writeFileSync(p, JSON.stringify(payload, null, 2) + "\n", "utf-8")
+  return p
+}
+
+export interface FingerprintCheck {
+  requiresReindex: boolean
+  reason: string
+  current: FtsFingerprint
+  recorded: RecordedFingerprint | null
+}
+
+/**
+ * 比对当前指纹与已记录指纹：
+ * 未记录（首次部署/标记缺失）→ requiresReindex=true（历史 token 来源未知，不能假定同源）；
+ * 不一致（jieba 版本/词典/契约变化）→ true + 差异明细；一致 → false。
+ */
+export function checkFtsFingerprint(projectRoot: string, magicDir: string): FingerprintCheck {
+  const current = computeFtsFingerprint({ projectRoot, magicDir })
+  const recorded = readRecordedFingerprint(projectRoot, magicDir)
+  if (!recorded) {
+    return { requiresReindex: true, reason: "未记录指纹（无法证明历史 searchText 与当前分词器同源）", current, recorded }
+  }
+  if (recorded.fingerprint !== current.value) {
+    const diff = (["jieba", "userDict", "contract"] as const)
+      .filter((k) => recorded.parts?.[k] !== current.parts[k])
+      .map((k) => `${k}: ${String(recorded.parts?.[k])} → ${String(current.parts[k])}`)
+      .join("; ")
+    return { requiresReindex: true, reason: `指纹不一致（${diff}）`, current, recorded }
+  }
+  return { requiresReindex: false, reason: "指纹一致", current, recorded }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/query-terms.ts

@@ -1,31 +1,15 @@
 /*
- * 查询词项抽取（双后端 LIKE/bigram 通道共用）
+ * 查询词项抽取（双后端 LIKE/bigram 通道共用）—— **薄封装**
  *
- * 背景：trigram 分词器（PG pg_trgm / SQLite FTS5 trigram）是子串语义，
- * 对释义查询（如 "新端口怎么申请" vs 内容 "新增端口"）召回不足。
- * 本模块把查询分解为「拉丁词 + CJK 二元组」词项，供 LIKE 重叠通道计分。
+ * [2026-09-21 收敛] 切分实现已迁到单一真源 `cjk-tokenize.ts`（`expandForQuery`）。
+ * 本文件只保留既有导出名与签名（调用方不变），**禁止在此再写第二份切分实现**。
+ *
+ * 为什么收敛：词法基线换成 bigram 分词 FTS 后，写入侧与查询侧必须共用同一 tokenization；
+ * 两份实现必然漂移，且漂移后表现为"索引在、命中不了"这类难查的召回缺陷。
  */
-import { normalizeContent } from "../domain/dedup.js"
-
-const MAX_TERMS = 24
+import { expandForQuery } from "./cjk-tokenize.js"
 
-/** 拉丁/数字词（≥2 字符）+ CJK 连续段的滑动二元组 */
+/** 拉丁/数字词（≥2 字符）+ CJK 连续段的滑动二元组（委托 `cjk-tokenize.ts`） */
 export function extractQueryTerms(query: string): string[] {
-  const norm = normalizeContent(query)
-  const terms: string[] = []
-  const seen = new Set<string>()
-  const push = (t: string) => {
-    if (!seen.has(t) && terms.length < MAX_TERMS) { seen.add(t); terms.push(t) }
-  }
-
-  // 拉丁词
-  for (const m of norm.matchAll(/[a-z0-9_]{2,}/g)) push(m[0])
-
-  // CJK 连续段 → 滑动二元组（单字段保留单字）
-  for (const seg of norm.matchAll(/[㐀-鿿぀-ヿ]+/g)) {
-    const s = seg[0]
-    if (s.length === 1) { push(s); continue }
-    for (let i = 0; i < s.length - 1; i++) push(s.slice(i, i + 2))
-  }
-  return terms
+  return expandForQuery(query)
 }

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

@@ -5,7 +5,9 @@
  * 因此全部函数必须是同步、纯环境变量读取，禁止任何 IO/DB 访问。
  *
  * 开关：
- * - ADD_MEMORY_RECALL_MODE = off | shadow | inject（默认 shadow：召回可执行并落审计，但 Hook 不注入上下文）
+ * - ADD_MEMORY_RECALL_MODE = off | shadow | inject（**默认 inject**：召回并注入 L1；
+ *   2026-09-21 人类决策 —— 默认 shadow 会让记忆功能形同未启用。非法值回落 shadow（安全侧，且必然打印档位）。
+ *   退回不注入：设 ADD_MEMORY_RECALL_MODE=shadow）
  * - ADD_MEMORY_MAX_TOKENS：L1 注入 token 预算（默认 600）
  * - ADD_MEMORY_EVIDENCE = off | on（默认 on：PostToolUse 白名单采证入队）
  */
@@ -13,7 +15,7 @@
 export type RecallMode = "off" | "shadow" | "inject"
 
 export function recallMode(env: NodeJS.ProcessEnv = process.env): RecallMode {
-  const v = (env.ADD_MEMORY_RECALL_MODE ?? "shadow").toLowerCase()
+  const v = (env.ADD_MEMORY_RECALL_MODE ?? "inject").toLowerCase()
   return v === "off" || v === "inject" ? v : "shadow"
 }
 

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

@@ -1,4 +1,5 @@
 import type { RuntimeContextKey } from "./runtime-context.js"
+import * as z from "zod/v4"
 
 export const PLAN_LIFECYCLE_STATUSES = [
   "DRAFT",
@@ -6,10 +7,13 @@ export const PLAN_LIFECYCLE_STATUSES = [
   "BLOCKED",
   "REJECTED",
   "CLOSED",
+  "REOPENED",
   "ABANDONED",
 ] as const
 
 export type PlanLifecycleStatus = (typeof PLAN_LIFECYCLE_STATUSES)[number]
+/** lifecycle 的**唯一 zod 真源**：工具 inputSchema / db-types / 脚本校验一律 import 它，禁止再抄字面量（2026-09-21 决策） */
+export const PlanLifecycleStatusSchema = z.enum(PLAN_LIFECYCLE_STATUSES)
 export type PlanApprovalStatus = "DRAFT" | "SUBMITTED" | "TONGYI" | "BOHUI"
 
 export interface ScopedPlanStatusRow {
@@ -75,12 +79,21 @@ export interface PlanStatusUnavailable {
 export type PlanStatusResolution = PlanStatusSnapshot | NoActivePlanSnapshot | PlanStatusUnavailable
 
 const ALLOWED_TRANSITIONS: Readonly<Record<PlanLifecycleStatus, readonly PlanLifecycleStatus[]>> = {
+  // 两个状态机不要混：TONGYI/BOHUI 属**审批**状态机（HitlRecord.status）；
+  // 下面是 **Plan 生命周期**状态机（PlanLifecycleStatus），ABANDONED = 放弃该 Plan（非审批结论）。
   DRAFT: ["ACTIVE", "REJECTED", "ABANDONED"],
   ACTIVE: ["BLOCKED", "CLOSED", "ABANDONED"],
   BLOCKED: ["ACTIVE", "CLOSED", "ABANDONED"],
-  REJECTED: ["DRAFT", "ACTIVE", "ABANDONED"],
-  CLOSED: [],
-  ABANDONED: [],
+  // 驳回（BOHUI → REJECTED）= 不继续；后续可 归档(CLOSED) / 重启(REOPENED) / 回起草或施工 / 放弃(ABANDONED)
+  REJECTED: ["DRAFT", "ACTIVE", "CLOSED", "REOPENED", "ABANDONED"],
+  // 可逆 + PUL 重开（2026-09-21 人类决策）：
+  // - CLOSED → REOPENED：策略更新（PUL）或误关场景下重开，reopenCycle +1（与施工轮次 round 分离）
+  // - CLOSED → ACTIVE：直达重开（无需标记代数时的简路径）
+  CLOSED: ["REOPENED", "ACTIVE"],
+  // REOPENED 是**瞬态**：重开后完成新一轮 Step 0 即回 ACTIVE；也允许再次 CLOSED（重开后又关）
+  REOPENED: ["ACTIVE", "CLOSED"],
+  // 接线（2026-09-21 人类决策）：ABANDONED 保留为生命周期状态，且与 CLOSED 同口径**可逆**（放弃后可复活）
+  ABANDONED: ["ACTIVE"],
 }
 
 export function isActiveLifecycle(lifecycle: PlanLifecycleStatus): boolean {

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

@@ -0,0 +1,65 @@
+// MCP Server 能力声明与 instructions（Plan add-coder-multi-host-adapter-alignment Task 2.1 / 2.2）
+//
+// 为什么单独成模块：`mcp-server.ts` 是"进程入口"（import 即启动 main()），
+// 能力声明若内联在那里就无法被单测断言（import 会拉起 stdio server）。
+// 本模块零副作用，供入口与 `tests/mcp-apps-capability.test.ts` 共用同一份真源。
+
+// MCP Apps 官方扩展标识（extensions/apps；客户端矩阵见 modelcontextprotocol.io/extensions/client-matrix）。
+//
+// 声明它的收益：宿主（Codex desktop / VS Code Copilot / Cursor 等）可在扩展协商通过后绑定 widget；
+// 不声明时只能靠工具侧 legacy 位（`_meta.ui.resourceUri` + `openai/outputTemplate`）兼容旧宿主。
+// 两条路径并存——删掉 legacy 位会让老宿主失效，删掉扩展声明则在新宿主收紧协商后全端同时失效。
+export const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui"
+
+// instructions 长度上限（字节）：Claude Code 对 server instructions 与工具描述各截断 2KB
+export const SERVER_INSTRUCTIONS_MAX_BYTES = 2048
+
+// 前缀自包含口径（字符）：Codex 官方要求 instructions 前 512 字符自包含
+export const SERVER_INSTRUCTIONS_PREFIX_CHARS = 512
+
+const INSTRUCTIONS_PART_1 = [
+  "add-coder 治理工具（ADD 范式）。三个必做 WHEN：",
+  "① 新会话或跨轮恢复 → 先 get_project_context(scope:'add-state')；",
+  "② 改完任何文件 → record_dev_operation（ADD-7 审计不可省）；",
+  "③ Plan 启动或评审 → create_hitl，由人类 update_hitl 裁决，未 TONGYI 不得进入实现。",
+].join("\n")
+
+const INSTRUCTIONS_PART_2 = [
+  "工具族分区：",
+  "状态与上下文 get_project_context / find_related_docs / get_db_schema；",
+  "Plan-Review 生命周期 plan_track / plan_status / plan_sync / plan_update / review_track / review_status / review_sync；",
+  "HITL 审批 create_hitl / update_hitl / status_hitl / render_hitl_approval；",
+  "审计 query_audit_logs / record_dev_operation；",
+  "质量门禁 check_dps / check_rahs / check_add_route_status / check_add_route_completeness / check_add_compliance / check_spec_sync；",
+  "记忆 propose_memory / recall_memory / refresh_memory_snapshots / get_memory_health。",
+].join("\n")
+
+const INSTRUCTIONS_PART_3 = [
+  "面板不可用时：用 render_hitl_approval 返回的 fallback（markdownPath / htmlPath）人工确认后调 update_hitl 落库。",
+  "收口前 check_dps 与 check_rahs 均需达标（≥80 / ≥90）再声明收敛。",
+].join("\n")
+
+// server instructions 真源（≤ SERVER_INSTRUCTIONS_MAX_BYTES 字节；首段自包含）。
+// 约束由 tests/mcp-apps-capability.test.ts 守护：超长即测试失败，禁止静默截断。
+export const SERVER_INSTRUCTIONS = [INSTRUCTIONS_PART_1, INSTRUCTIONS_PART_2, INSTRUCTIONS_PART_3].join("\n")
+
+export interface ServerCapabilitiesOptions {
+  capabilities: {
+    tools: Record<string, never>
+    resources: { subscribe: boolean }
+    extensions: Record<string, Record<string, never>>
+  }
+  instructions: string
+}
+
+// 入口 `new McpServer(...)` 的第二参数（供入口与用例共用同一真源）
+export function buildServerOptions(): ServerCapabilitiesOptions {
+  return {
+    capabilities: {
+      tools: {},
+      resources: { subscribe: true },
+      extensions: { [MCP_APPS_EXTENSION_ID]: {} },
+    },
+    instructions: SERVER_INSTRUCTIONS,
+  }
+}

package/templates/core/scripts/mcp-server/tools/audit.ts

@@ -6,6 +6,7 @@ import { prisma } from "../shared/prisma.js"
 import { PROJECT_ID, PROJECT_ROOT, getRuntimeContext } from "../shared/env.js"
 import type { AddUserRow, DevOperationRow } from "../shared/db-types.js"
 import { AddUserRowSchema, DevOperationRowSchema, validatedDelegate } from "../shared/db-types.js"
+import { writeDevOperation, type DevOperationWriterDatabase } from "../shared/dev-operation.js"
 
 export function registerAuditTools(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext()
@@ -82,41 +83,22 @@ export function registerAuditTools(server: ToolRegistrar) {
       try { if (beforeState) parsedBefore = JSON.parse(s(beforeState)); if (afterState) parsedAfter = JSON.parse(s(afterState)) } catch { return errorResponse("beforeState/afterState 必须是有效的 JSON 字符串。") }
       const isStructuredState = (value: unknown): value is Record<string, unknown> | unknown[] => typeof value === "object" && value !== null
       if (!isStructuredState(parsedBefore) || !isStructuredState(parsedAfter)) return errorResponse("beforeState/afterState 必须是非 null 的 JSON 对象或数组。")
-      let systemUser = await userDb.findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
-      if (!systemUser) systemUser = await userDb.create({ data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" } })
-      const operationPayload = {
-        projectKey: runtimeContext.projectKey,
-        producerAdapterKey: runtimeContext.adapterKey,
-        action: s(action),
-        targetType: s(targetType),
-        targetId: tId || "unknown",
-        planKeyword: s(planKeyword) || "unknown",
-        beforeState: parsedBefore,
-        afterState: parsedAfter,
-        reason: s(reason) || null,
-      }
-      const resolvedOperationKey = s(operationKey).trim() || createHash("sha256")
-        .update(JSON.stringify(operationPayload))
-        .digest("hex")
-      const scopedData: Partial<DevOperationRow> = {
-        ...operationPayload,
-        userId: systemUser.id,
-        contextId: runtimeContext.contextId,
-        toolName: "record_dev_operation",
-        operationKey: resolvedOperationKey,
-      }
-      const log = await devDb.upsert({
-        where: {
-          projectKey_producerAdapterKey_toolName_operationKey: {
-            projectKey: runtimeContext.projectKey,
-            producerAdapterKey: runtimeContext.adapterKey,
-            toolName: "record_dev_operation",
-            operationKey: resolvedOperationKey,
-          },
+      // 单一实现（2026-09-21 决策）：写入抽到 shared/dev-operation.ts，与 plan_update / 脚本共用；
+      // 幂等键语义逐字保持不变（hash 载荷不含 toolName，换调用方不产生新审计行）
+      const log = await writeDevOperation(
+        { devOperation: devDb, addUser: userDb } as unknown as DevOperationWriterDatabase,
+        {
+          context: runtimeContext,
+          action: s(action),
+          targetType: s(targetType),
+          targetId: tId,
+          planKeyword: s(planKeyword),
+          beforeState: parsedBefore,
+          afterState: parsedAfter,
+          reason: s(reason) || null,
+          operationKey: s(operationKey),
         },
-        create: scopedData,
-        update: {},
-      })
+      )
       const lines = [`✅ 开发操作已记录`, `  落库项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `  ID: ${log.id}`, `  action: ${s(action)}`, `  targetType: ${s(targetType)}`, `  targetId: ${tId || "unknown"}`, `  planKeyword: ${s(planKeyword) || "unknown"}`, `  beforeState: ${JSON.stringify(log.beforeState)}`, `  afterState: ${JSON.stringify(log.afterState)}`, `  createdAt: ${log.createdAt.toISOString()}`]
       if (pathWarnings.length > 0) { lines.push(""); lines.push(...pathWarnings) }
       lines.push("", `📋 落库回查（必须执行）:`, tId ? `  query_audit_logs({ targetId: "${tId}" }) — 确认本条记录已写入` : "")

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

@@ -17,6 +17,7 @@ import {
   PROJECT_ROOT,
   MAGIC_DIR,
 } from "../../shared/fs.js";
+import { resolvePlanArtifact } from "./plan-resolve.js";
 
 export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
   server.registerTool(
@@ -36,15 +37,26 @@ export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
         if (!existsSync(plansDir))
           return errorResponse(`plans 目录不存在: ${plansDir}`);
         const allFiles = await readdirRecursive(plansDir);
-        const arFile = allFiles.find(
-          (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) &&
-            f.includes("add-route"),
+        // 版本配对（2026-09-18 修复）：与 Plan 同目录同版本优先，不再"去版本取首个匹配"（永远命中 v1）
+        const { plan: resolvedPlan, artifact: resolvedAr } = resolvePlanArtifact(
+          allFiles,
+          pp,
+          "add-route",
         );
+        const arFile = resolvedAr?.file;
         if (!arFile)
           return errorResponse(`未找到匹配的 add-route 文件（关键词: ${pp}）`);
         const content = await readFileSafe(join(plansDir, arFile));
         if (!content) return errorResponse("add-route 文件无法读取");
+        const pairing: string[] = [];
+        if (resolvedPlan)
+          pairing.push(
+            `Plan: ${resolvedPlan.file}${resolvedPlan.version > 0 ? ` (v${resolvedPlan.version})` : ""}`,
+          );
+        pairing.push(
+          `add-route: ${arFile}${resolvedAr && resolvedAr.version > 0 ? ` (v${resolvedAr.version})` : ""} 〔配对依据: ${resolvedAr?.via}〕`,
+        );
+        if (resolvedAr?.warning) pairing.push(`⚠️ ${resolvedAr.warning}`);
         const steps: Record<string, { checked: number; unchecked: number }> =
           {};
         let cur = "";
@@ -71,6 +83,7 @@ export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
         const parts = [
           `=== add-route Step 完成度扫描 ===`,
           `文件: ${MAGIC_DIR}/plans/${arFile}`,
+          ...pairing,
           `整体: ${tu}/${tc} (${tc > 0 ? Math.round((tu / tc) * 100) : 0}%)`,
           "",
         ];