add-coder 0.3.34 → 0.3.35

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(

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

@@ -20,6 +20,14 @@ import {
 import { prisma } from "../../shared/prisma.js";
 import { runCommand } from "../../shared/run-command.js";
 import { getRuntimeContext } from "../../shared/env.js";
+import {
+  buildGateCaptureDetail,
+  createGateWriterDeps,
+  deriveGateRunId,
+  formatGateCaptureSummary,
+  writeGateMetric,
+  GATE_METRIC_TYPE,
+} from "../../shared/memory/metrics/gate-writer.js";
 
 export function registerCheckRahs(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext();
@@ -50,6 +58,8 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
+        // Plan 正文在多个维度（Spec 引用解析、采证 seed）共用，提到此处只读一次
+        const planContent = (await readFileSafe(join(plansDir, pm))) || "";
         let scopeScore = 80,
           typeScore = 80,
           auditScore = 80,
@@ -115,7 +125,6 @@ export function registerCheckRahs(server: ToolRegistrar) {
           const rahsCandidates = rahsVersionSuffix
             ? [`${rahsPlanBase}-${rahsVersionSuffix}`, rahsPlanBase]
             : [rahsPlanBase];
-          const planContent = (await readFileSafe(join(plansDir, pm))) || "";
           const rahsSpecRef = planContent.match(/specs\/([^/`\s]+)/);
           if (rahsSpecRef) rahsCandidates.push(rahsSpecRef[1]);
           const sn =
@@ -181,6 +190,36 @@ export function registerCheckRahs(server: ToolRegistrar) {
           `=== RAHS = ${rahs}  ${rahs >= 90 ? "🟢 PASS" : rahs >= 70 ? "🟡 WARN" : "🔴 BLOCKED"} ===`,
         );
         if (rahs < 70) parts.push("  动作: 注意力漂移严重，返工回退");
+
+        // ── Gate 采证（Spec §GateMetric）：与评分解耦，失败旁路不阻塞返回 ──
+        const rahsSeed = `${planContent}\n${scopeScore}|${typeScore}|${auditScore}|${specScore}|${symScore}`;
+        const rahsCaptureInput = {
+          gate: "check_rahs" as const,
+          planKeyword: pp,
+          runId: deriveGateRunId("check_rahs", pp, rahsSeed),
+          metricType: GATE_METRIC_TYPE.check_rahs,
+          score: rahs,
+          repository: runtimeContext.projectKey,
+          dimensionScores: {
+            scope: scopeScore,
+            type: typeScore,
+            audit: auditScore,
+            spec: specScore,
+            symmetry: symScore,
+          },
+          baseline: 90,
+          unit: "score",
+        };
+        const rahsCapture = await writeGateMetric(
+          rahsCaptureInput,
+          createGateWriterDeps((prisma as Record<string, unknown>).addMetricSnapshot),
+        );
+        parts.push(
+          "",
+          "=== Gate 采证（MetricSnapshot）===",
+          `  ${formatGateCaptureSummary(buildGateCaptureDetail(rahsCaptureInput, rahsCapture))}`,
+        );
+
         return textResponse(parts.join("\n"));
       } catch (e) {
         return errorResponse(

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

@@ -76,8 +76,8 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
         } else {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
-          // 提取 add-route 附录文件清单（toml 纳入：sync-magic-rules.toml 等控制面文件，2026-08-18 修复）
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml|toml)`/g) || [])
+          // 提取 add-route 附录文件清单
+          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) || [])
             .map((f: string) => f.replace(/`/g, ""));
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 

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

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import { inputRequired, acceptedContent } from "@modelcontextprotocol/server"
+import { inputRequired, acceptedContent, type ElicitInputParams } from "@modelcontextprotocol/server"
 import type { ToolRegistrar } from "./registrar.js"
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs"
 import { join, basename, relative } from "path"
@@ -7,6 +7,7 @@ import { textResponse, errorResponse } from "../shared/response.js"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
 import { HITL_INTERACTION_CONFIG } from "../shared/hitl-interaction.strategy.js"
+import { shouldSkipHitlCreateDialog } from "../shared/hitl-create-policy.js"
 import type { HitlRow } from "../shared/db-types.js"
 import { HitlRowSchema, validatedDelegate } from "../shared/db-types.js"
 import { getRuntimeContext } from "../shared/env.js"
@@ -18,6 +19,10 @@ import {
   createHitlProposalAndPublish,
   type HitlProposalDatabase,
 } from "../shared/hitl-proposal-mutation.js"
+import {
+  buildHitlProposalMarkdown,
+  applyHitlDecisionToProposal,
+} from "../shared/hitl-proposal-content.js"
 import { HITL_APPROVAL_WIDGET_URI } from "../shared/hitl-ui.js"
 
 // 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
@@ -25,6 +30,23 @@ const db = {
   get hitl() { return validatedDelegate<HitlRow>(prisma.hitlRecord, HitlRowSchema, "HitlRecord") },
 }
 
+/**
+ * 表单式 elicitation 的 `requestedSchema`（2026-09-14：替换 4 处 `as any`）。
+ *
+ * 为什么需要一个函数：属性表是**运行时按维度动态构造**的（`dim_0_content`/`dim_0_decision`…），
+ * 而 SDK 的 `ElicitInputParams["requestedSchema"]` 是静态 JSON Schema 形状 —— 字面量直接赋值
+ * 会因索引签名不匹配而报错。这里把**唯一的窄化点**收在一处，类型取自 SDK 而非 `any`。
+ */
+/** 表单里单个属性的形状（本仓库只用字符串型 + 可选枚举） */
+type ElicitFormProperty = { type: "string"; enum?: string[]; description?: string }
+
+function elicitFormSchema(
+  properties: Record<string, ElicitFormProperty>,
+  required: string[],
+): ElicitInputParams["requestedSchema"] {
+  return { type: "object", properties, required } as ElicitInputParams["requestedSchema"]
+}
+
 export function registerHitlTools(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext()
 
@@ -123,9 +145,15 @@ export function registerHitlTools(server: ToolRegistrar) {
     filePath: string,
     status: HitlRow["status"],
     dimensions?: { name: string; content?: string }[],
+    reason?: string,
   ): void {
     let proposal = readFileSync(filePath, "utf-8")
-    proposal = proposal.replace(/(状态:\s*)[A-Z_]+/, `$1${status}`)
+    // 状态行 + 「审批结论」行（2026-09-14：原实现只改状态行，裁决结论不回写文档）
+    proposal = applyHitlDecisionToProposal(proposal, {
+      status,
+      at: new Date().toISOString(),
+      reason,
+    })
 
     if (dimensions?.length) {
       const byName = new Map(dimensions.map((d) => [d.name.trim(), d.content ?? ""]))
@@ -187,16 +215,60 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (!dimensions.length) {
         return errorResponse(`HITL 提案缺少可渲染维度: ${proposalPath ?? planName}`)
       }
+      // 产物-进程新鲜度（覆盖全 adapter；判定不确定 → "unknown"，不误报"需重启"）
+      const { computeFreshness } = await import("../shared/runtime-freshness.js")
+      const { writeHitlInstanceHtml } = await import("../shared/hitl-widget-instance.js")
+      const stale = computeFreshness(MAGIC_DIR, PROJECT_ROOT)
+      // 确定性降级入口：markdown 提案 + 已落盘实例 HTML（无 UI 能力/进程陈旧时仍可完成审批）
+      const toRel = (abs: string): string => abs.replace(`${PROJECT_ROOT}/`, "")
+      const markdownPath = proposalPath ? toRel(proposalPath) : ""
+      let htmlPath = ""
+      try {
+        htmlPath = toRel(
+          writeHitlInstanceHtml({
+            projectRoot: PROJECT_ROOT,
+            magicDir: MAGIC_DIR,
+            planName,
+            type,
+            round: current.round,
+            status: current.status,
+            dimensions,
+          }).htmlPath,
+        )
+      } catch {
+        htmlPath = "" // 模板缺失等 → 仍保留 markdown 降级路径（fail-open）
+      }
       const output = {
         planName,
         type,
         round: current.round,
         status: current.status,
         dimensions,
+        stale,
+        // 服务端无法得知客户端是否真的渲染了 widget —— 如实标注 unknown，不谎报
+        ui: { resourceUri: HITL_APPROVAL_WIDGET_URI, rendered: "unknown" as const },
+        fallback: { markdownPath, htmlPath },
       }
+      const fallbackHint = markdownPath || htmlPath
+      const text =
+        stale.stale === true
+          ? `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。⚠️ 当前 server 进程早于产物更新（需重启）；widget 若未显示，降级入口：${fallbackHint}`
+          : `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。widget 若未显示，降级入口：${fallbackHint}`
       return {
-        content: [{ type: "text" as const, text: `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。请在 widget 中拍板。` }],
+        content: [{ type: "text" as const, text }],
         structuredContent: output,
+        /*
+         * 结果侧 `_meta`（Apps SDK 兼容补位，2026-09-14）：
+         * 宿主实际读的是**工具定义**的 `_meta.ui.resourceUri`（`tools/list` 时解析，
+         * 实测 `thread_items` 里已带 `mcpAppResourceUri`，而 `result._meta` 仍为 null 也照常绑定）；
+         * 这里补一份结果侧 `_meta` 不改变行为，只为兼容同时读结果位的客户端。
+         * 真正的渲染前提是：客户端 MCP Apps 能力开关（Codex: `/experimental` 的 enable_mcp_apps）
+         * + 资源 mimeType 为 `text/html;profile=mcp-app` + 资源存在 + dimensions 非空。
+         */
+        _meta: {
+          ui: { resourceUri: HITL_APPROVAL_WIDGET_URI },
+          "openai/outputTemplate": HITL_APPROVAL_WIDGET_URI,
+        },
       }
     } catch (e) {
       return errorResponse(`render_hitl_approval 失败: ${e instanceof Error ? e.message : String(e)}`)
@@ -208,9 +280,11 @@ export function registerHitlTools(server: ToolRegistrar) {
     description: "HITL 审批：创建提案。写入 HitlRecord（status=DRAFT，自动递增 round），并生成 hitl.md 提案文件供人工审核。\n" +
       "交互模式按安装环境自动裁决（caijuehub: hitl-interaction-rules.toml）：\n" +
       "- genui 模式环境（如 Qoder，客户端未声明 elicitation capability）：MUST 直接走 genui 流程——先用 genui show_widget 渲染逐项决策表单，用户拍板后以 _use_genui=true + 最终 dimensions 调用本工具。不带模式参数调用会返回 genui 引导而非弹框。\n" +
+      "- MCP Apps 模式环境（如 Codex）：MUST NOT 展开高维 inputRequired——创建阶段直接落 DRAFT，审批走 render_hitl_approval 打开的 core widget（其回调以 update_hitl(_use_widget=true) 落库）。不带模式参数时按环境自动走该路径；也可用 _mcp_apps=true 强制。\n" +
       "- 支持 elicitation 的客户端（2026-07-28+ 协议）：inputRequired 弹框，含逐项决策（LLM 传 dimensions）或简单弹框两种模式。\n" +
       "降级模式（_fallback=true）：genui 与弹框均不可用时兜底，跳过弹框直接以传入的 dimensions 创建，人工审核 hitl.md。\n" +
       "_use_genui=true：genui widget 回调后使用，跳过所有弹框，直接以传入的 dimensions 创建 DB+文件。\n" +
+      "_mcp_apps=true：强制 MCP Apps 流程（落 DRAFT 不弹框，审批走 core widget）。\n" +
       "planName 示例: add-coder-hitl-mcp-hook-plan-v1\n" +
       "type: PLAN=计划审批, PLAN_REVIEW=方案评审",
     inputSchema: z.object({
@@ -222,10 +296,11 @@ export function registerHitlTools(server: ToolRegistrar) {
       })).optional().describe("决策维度列表（LLM 根据对话生成）。不传则按模板默认 8 维度"),
       _fallback: z.boolean().optional().default(false).describe("降级模式：跳过 inputRequired，按原始代码行为直接创建 DB 记录+hitl.md"),
       _use_genui: z.boolean().optional().default(false).describe("genui 模式：genui widget 回调后使用，跳过所有弹框直接创建（dimensions 需传最终确认值）"),
+      _mcp_apps: z.boolean().optional().default(false).describe("Codex MCP Apps 强制模式：落 DRAFT 不弹 inputRequired，审批走 render_hitl_approval core widget（update_hitl(_use_widget=true)）"),
     }),
   }, async (args: Record<string, unknown>, ctx: Record<string, unknown>) => {
     try {
-      const { planName, type, dimensions, _fallback, _use_genui } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean }
+      const { planName, type, dimensions, _fallback, _use_genui, _mcp_apps } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean; _mcp_apps?: boolean }
 
       // ── planName 入口强校验（弱模型友好：不合规返回可照抄修正调用，而非让错误漂移） ──
       const _pnValid = /-(plan|collab-contract)-v\d+$/.test(planName)
@@ -243,13 +318,14 @@ export function registerHitlTools(server: ToolRegistrar) {
       // ── 最终维度内容（从弹框结果合并） ──
       let finalDims: { name: string; content: string }[] = []
 
-      // ── genui/降级模式：无弹框环节，直接采用传入的 dimensions（降级丢维度会退化成默认空模板） ──
-      if (_use_genui || _fallback) {
+      // ── genui/降级/mcpApps 模式：无弹框环节，直接采用传入的 dimensions（降级丢维度会退化成默认空模板） ──
+      const skipDialog = shouldSkipHitlCreateDialog(_interaction.mode, { fallback: _fallback, useGenui: _use_genui, mcpApps: _mcp_apps })
+      if (skipDialog) {
         finalDims = (dimensions || []).map(d => ({ name: d.name, content: d.content || "" }))
       }
 
       // ── 交互式确认（非降级模式且非 genui 模式） ──
-      if (!_fallback && !_use_genui) {
+      if (!skipDialog) {
         // 环境裁决：genui 模式下不发起注定失败的 elicitation，引导 LLM 走 widget 流程
         if (_interaction.mode === "genui") {
           const dimDesc = (dimensions || []).map((d, i) => `${i + 1}. ${d.name}: ${d.content || ""}`).join("\n")
@@ -266,7 +342,7 @@ export function registerHitlTools(server: ToolRegistrar) {
 
           if (!decResp) {
             // 首次调用 — 构建扁平逐项弹框
-            const props: Record<string, unknown> = {
+            const props: Record<string, ElicitFormProperty> = {
               globalAction: {
                 type: "string", enum: ["", "同意全部", "驳回全部"],
                 description: "同意全部=通过所有(含已调整行); 驳回全部=驳回提案; 留空=逐项"
@@ -290,7 +366,7 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `确认创建 HITL 提案\n\nplan: ${planName}\ntype: ${type}\n\n共 ${dimensions.length} 个决策维度：\n${dimDesc}`,
-                  requestedSchema: { type: "object", properties: props, required: requiredKeys } as any
+                  requestedSchema: elicitFormSchema(props, requiredKeys),
                 })
               }
             })
@@ -322,7 +398,10 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `确认创建 HITL 提案？\n\nplan: ${planName}\ntype: ${type}`,
-                  requestedSchema: { type: "object", properties: { action: { type: "string", enum: ["同意", "取消"], description: "同意=确认创建提案, 取消=取消操作" } }, required: ["action"] } as any
+                  requestedSchema: elicitFormSchema(
+                    { action: { type: "string", enum: ["同意", "取消"], description: "同意=确认创建提案, 取消=取消操作" } },
+                    ["action"],
+                  ),
                 })
               }
             })
@@ -361,34 +440,14 @@ export function registerHitlTools(server: ToolRegistrar) {
       // 生成 hitl.md
       const isoNow = now.toISOString()
 
-      // 动态生成维度表格行
-      const tableRows = finalDims.length > 0
-        ? finalDims.map((d, i) => `| ${i + 1} | ${d.name} | ${d.content} | 同意/驳回 |`).join("\n")
-        : [
-            "| 1 | 实施主体 | | 同意/驳回 |",
-            "| 2 | 数据模型 | | 同意/驳回 |",
-            "| 3 | MCP 工具 | | 同意/驳回 |",
-            "| 4 | 文件命名 | | 同意/驳回 |",
-            "| 5 | 模板 + schema | | 同意/驳回 |",
-            "| 6 | 新增依赖 | | 同意/驳回 |",
-            "| 7 | 预计文件数 | | 同意/驳回 |",
-            "| 8 | 预计轮次 | | 同意/驳回 |",
-          ].join("\n")
-
-      const tpl = [
-        `# ${planName} — HITL 提案 (round ${round})`,
-        "",
-        `> 创建: ${isoNow}  |  类型: ${type}  |  状态: DRAFT`,
-        "",
-        "## HITL 计划总览",
-        "",
-        "请填写以下决策维度，人工审核后点击 update_hitl 弹框选择「同意/驳回」完成审批：",
-        "",
-        "| # | 维度 | 方案内容 | 决策 |",
-        "|---|------|----------|:----:|",
-        tableRows,
-        "",
-      ].join("\n")
+      // 生成提案文档（真源 hitl-template.md：HITL 计划总览 + 审批结论 两章节齐备）
+      const tpl = buildHitlProposalMarkdown({
+        planName: String(planName),
+        round,
+        type: String(type),
+        createdAt: isoNow,
+        dimensions: finalDims,
+      })
       mkdirSync(plansDir, { recursive: true })
       writeFileSync(proposalPath, tpl, "utf-8")
 
@@ -406,6 +465,10 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (finalDims.length > 0) lines.push(`dimensions: ${finalDims.length} 项`)
       if (proposal.planProvisioned) lines.push(`PlanRecord: 自动预置（占位行，Plan 文件写出后 plan_track 回刷真实路径）`)
       if (_fallback) lines.push(`mode:     _fallback (跳过 dialog，原始代码降级)`)
+      if ((_interaction.mode === "mcpApps" || _mcp_apps) && !_fallback) {
+        lines.push(`mode:     mcpApps (Codex：不展开 inputRequired${_mcp_apps ? "，_mcp_apps 显式强制" : ""})`)
+        lines.push(``, `➡️ 下一步：调用 render_hitl_approval({ planName: "${planName}", type: "${type}" }) 打开审批 widget，由用户拍板。`)
+      }
       return textResponse(lines.join("\n"))
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
@@ -489,7 +552,7 @@ export function registerHitlTools(server: ToolRegistrar) {
           const decResp = _parseDecisions(ctx)
 
           if (!decResp) {
-            const props: Record<string, unknown> = {
+            const props: Record<string, ElicitFormProperty> = {
               globalAction: {
                 type: "string", enum: ["", "同意全部", "驳回全部"],
                 description: "同意全部=通过所有维度; 驳回全部=驳回提案; 留空=逐项"
@@ -512,7 +575,7 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `HITL 审批决策\n\nplan: ${planName}\ntype: ${type}\n\n逐项决策以下 ${dims.length} 个维度：\n${dimDesc}`,
-                  requestedSchema: { type: "object", properties: props, required: requiredKeys } as any
+                  requestedSchema: elicitFormSchema(props, requiredKeys),
                 })
               }
             })
@@ -536,7 +599,10 @@ export function registerHitlTools(server: ToolRegistrar) {
               inputRequests: {
                 confirm: inputRequired.elicit({
                   message: `HITL 审批决策\n\nplan: ${planName}\ntype: ${type}`,
-                  requestedSchema: { type: "object", properties: { action: { type: "string", enum: ["同意", "驳回", "取消"], description: "同意=通过审批, 驳回=驳回重做, 取消=暂不操作" } }, required: ["action"] } as any
+                  requestedSchema: elicitFormSchema(
+                    { action: { type: "string", enum: ["同意", "驳回", "取消"], description: "同意=通过审批, 驳回=驳回重做, 取消=暂不操作" } },
+                    ["action"],
+                  ),
                 })
               }
             })
@@ -585,7 +651,7 @@ export function registerHitlTools(server: ToolRegistrar) {
       // P3 #6：回写 .hitl.md 提案文件状态（DRAFT → TONGYI/BOHUI），保证双通道校验一致
       const proposalPath = findHitlFile(String(planName))
       if (proposalPath) {
-        updateHitlProposal(proposalPath, s, (_use_widget || _use_genui) ? dimensions : undefined)
+        updateHitlProposal(proposalPath, s, (_use_widget || _use_genui) ? dimensions : undefined, reason)
       }
       // 响应
       const lines = [