add-coder 0.3.34 → 0.3.37

package/templates/core/scripts/db-ensure.sh

@@ -123,14 +123,84 @@ build_target() {
     [ -n "$tables" ] && EXCLUDE_ARGS=(--exclude "$tables")
     echo ">>> Atlas 同步（共库模式: 仅 ADD 治理表，其余 $(echo "$tables" | tr ',' '\n' | wc -l) 张表排除）..."
   fi
+  # Atlas 自身的版本记录 schema 不属于期望态，必须排除，否则 diff 会生成 DROP SCHEMA ... CASCADE
+  EXCLUDE_ARGS+=(--exclude atlas_schema_revisions)
   TARGET_URL="${TARGET_URL}?sslmode=disable"
 }
 
-# ④ baseline 生成（同源：Prisma schema SQL，过滤 Prisma 7 ◇ 提示）
+# ③.5 raw 对象登记（schema 表达不了的对象：trgm 索引 / 向量层；单一事实源）
+#   期望态必须能表达这些对象，否则 diff 把「raw 对象」判成多余并生成 DROP（review 发现 #2）。
+#   约束：Atlas dev-url 必须是干净库且具备同名扩展（否则 gin_trgm_ops / vector 类型无法解析）；
+#   本项目的 dev 库是一次性沙箱 → 每次 diff 前从 template1 重建（见 prepare_atlas_dev_db）。
+RAW_OBJECTS_SQL="prisma/raw-objects.sql"
+RAW_OBJECTS_VECTOR_SQL="prisma/raw-objects-vector.sql"
+
+# template1 扩展引导（幂等）：新建库（含 Atlas dev 沙箱库）从 template1 继承扩展——
+#   缺扩展时期望态里的 gin_trgm_ops / vector 无法解析，diff 直接报错中止。
+#   镜像不含扩展时静默跳过（记忆检索按 fts-only 合法降级，不硬失败）。
+ensure_template1_extensions() {
+  local c="$1" u="$2"
+  podman exec "$c" true >/dev/null 2>&1 || return 0
+  podman exec "$c" psql -U "$u" -d template1 -tAc "CREATE EXTENSION IF NOT EXISTS pg_trgm;" >/dev/null 2>&1 || true
+  podman exec "$c" psql -U "$u" -d template1 -tAc "CREATE EXTENSION IF NOT EXISTS vector;" >/dev/null 2>&1 || true
+}
+
+# dev 沙箱库准备：DROP + CREATE TEMPLATE template1（template1 内已装 pg_trgm/vector）
+prepare_atlas_dev_db() {
+  # 容器 / 超级用户 / 库名探测：provisionDevUrl 实际建的是 `{project}-add-dev`（用户 postgres、库 dev），
+  # 历史环境可能是 `{project}-dev` / admin / `{project}-add-dev` 库——依次探测取第一个可用，
+  # 否则 DROP/CREATE DATABASE 与扩展引导会静默空转（沙箱库拿不到 pg_trgm / vector）。
+  local c="${PROJECT_NAME:-add-project}-add-dev" u="" d="${ATLAS_DEV_DB:-}"
+  podman exec "$c" true >/dev/null 2>&1 || c="${PROJECT_NAME:-add-project}-dev"
+  podman exec "$c" true >/dev/null 2>&1 || { echo ">>> [dev-url] 容器不可达，跳过重建（依赖现有 dev 库）"; return 0; }
+  for cand in "${ATLAS_DEV_USER:-postgres}" postgres "${DATABASE_USER:-admin}" admin; do
+    if [ -n "$cand" ] && podman exec "$c" psql -U "$cand" -d postgres -tAc "SELECT 1;" >/dev/null 2>&1; then
+      u="$cand"
+      break
+    fi
+  done
+  if [ -z "$u" ]; then
+    echo ">>> [dev-url] 未能确定 $c 的超级用户，跳过重建（沿用现有 dev 库）"
+    return 0
+  fi
+  if [ -z "$d" ]; then
+    # 库名优先取 ATLAS_DEV_URL 的路径段（dev），取不到再退回 add-project-dev
+    d="$(printf '%s' "${ATLAS_DEV_URL:-}" | sed -E 's/[?].*$//; s#.*/##')"
+    [ -n "$d" ] || d="add-project-dev"
+  fi
+  ensure_template1_extensions "$c" "$u"
+  if [ "${ADD_DB_KEEP_DEV:-}" = "yes" ]; then
+    echo ">>> [dev-url] ADD_DB_KEEP_DEV=yes：沿用现有 dev 库"
+    return 0
+  fi
+  podman exec "$c" psql -U "$u" -d postgres -tAc "DROP DATABASE IF EXISTS \"$d\";" >/dev/null 2>&1 || true
+  if podman exec "$c" psql -U "$u" -d postgres -tAc "CREATE DATABASE \"$d\" TEMPLATE template1;" >/dev/null 2>&1; then
+    echo ">>> [dev-url] 已从 template1 重建沙箱库 $d（干净 + 扩展齐备）"
+  else
+    echo ">>> [dev-url] 重建 $d 失败，沿用现有库（若解析报错请检查 template1 扩展）"
+  fi
+}
+
+# 目标库是否具备 pgvector（决定是否把向量段并入期望态）
+has_pgvector_in_target() {
+  local c="${PROJECT_NAME:-add-project}-postgres" u="${DATABASE_USER:-admin}" d="${PROJECT_NAME:-add-project}" has
+  has="$(podman exec "$c" psql -U "$u" -d "$d" -tAc "SELECT 1 FROM pg_available_extensions WHERE name='vector' LIMIT 1;" 2>/dev/null || true)"
+  [ "$has" = "1" ]
+}
+
+# ④ baseline 生成（同源：Prisma schema SQL + raw 对象登记段，过滤 Prisma 7 ◇ 提示）
 generate_baseline() {
   BASELINE_SQL="$(mktemp /tmp/atlas-target.XXXXXX.sql)"
   trap 'rm -f "$BASELINE_SQL"' EXIT
   npx prisma migrate diff --from-empty --to-schema "$SCHEMA_TARGET" --script 2>/dev/null | sed '/^◇/d' > "$BASELINE_SQL"
+  if [ -f "$RAW_OBJECTS_SQL" ]; then
+    printf '\n-- ===== raw objects registry =====\n' >> "$BASELINE_SQL"
+    cat "$RAW_OBJECTS_SQL" >> "$BASELINE_SQL"
+  fi
+  if has_pgvector_in_target && [ -f "$RAW_OBJECTS_VECTOR_SQL" ]; then
+    printf '\n-- ===== raw objects registry (vector) =====\n' >> "$BASELINE_SQL"
+    cat "$RAW_OBJECTS_VECTOR_SQL" >> "$BASELINE_SQL"
+  fi
 }
 
 # ⑤ diff 检测（SQL 语句特征判定：Atlas 无变更时输出 "Schemas are synced..." 非空，不算变更）
@@ -140,10 +210,28 @@ run_atlas_diff() {
   echo "$DIFF_SQL" | grep -qE "^(CREATE|ALTER|DROP|COMMENT|-- *(Create|Modify|Drop))"
 }
 
-# ⑥ apply（确认门槛：交互输出 SQL → 确认 → apply；拒绝则跳过）
+# ⑥ apply（双门槛：DROP 守卫 → 交互确认 → apply；任一不通过则跳过）
+#   DROP 守卫（Plan 轮 3 前置 / runtime review 发现 #2）：破坏性语句一律拒绝——
+#   raw SQL 对象（如 pg_trgm GIN 索引、pgvector 列/索引）无法被 Prisma schema 表达，
+#   diff 会误判为「多余对象」并生成 DROP；若放行，索引会被静默删除且不报错。
+#   显式放行需人工设 ADD_DB_ALLOW_DROP=yes，并在迁移评审中登记（禁止默认自动放行）。
 apply_atlas_diff() {
   echo "=== 待应用 diff SQL（前 60 行）==="
   echo "$DIFF_SQL" | head -60
+  local drops
+  drops="$(printf '%s\n' "$DIFF_SQL" | grep -nE '^DROP |DROP COLUMN|DROP CONSTRAINT|DROP INDEX|DROP TABLE|DROP TYPE|DROP SCHEMA' || true)"
+  if [ -n "$drops" ]; then
+    echo "!!! 检测到破坏性语句（DROP），已拒绝应用："
+    printf '%s\n' "$drops" | sed 's/^/    /'
+    echo "    处置建议："
+    echo "      ① 若是无法被 schema 表达的 raw SQL 对象（索引/扩展/向量列）→ 核对登记清单 prisma/raw-objects.sql、prisma/raw-objects-vector.sql；"
+    echo "      ② 确需删除时人工执行，并在迁移评审中登记（能力矩阵 §六 已登记同类缺口）。"
+    if [ "${ADD_DB_ALLOW_DROP:-}" != "yes" ]; then
+      echo "    （如需在评审后放行：ADD_DB_ALLOW_DROP=yes 重新执行）"
+      return 1
+    fi
+    echo "    ⚠️ ADD_DB_ALLOW_DROP=yes 已设置：放行破坏性变更（确认已完成迁移评审）"
+  fi
   read -rp "应用以上 schema 变更？[y/N] " ANS
   if [ "$ANS" = "y" ] || [ "$ANS" = "yes" ]; then
     atlas_cmd schema apply --url "$TARGET_URL" --to "file://$BASELINE_SQL" --dev-url "$ATLAS_DEV_URL" "${EXCLUDE_ARGS[@]}"
@@ -173,6 +261,8 @@ atlas_sync() {
     echo "!!! ATLAS_DEV_URL 未配置。请运行 add-coder init（分库引导自动创建 {project}-add-dev 常驻容器并登记）或手动配置"
     return 1
   fi
+  ensure_template1_extensions "${PROJECT_NAME:-add-project}-postgres" "${DATABASE_USER:-admin}"
+  prepare_atlas_dev_db
   build_target
   generate_baseline
   if run_atlas_diff; then

package/templates/core/scripts/mcp-server/shared/db-types.ts

@@ -138,6 +138,118 @@ export const CollabContractRowSchema = z.looseObject({
   updatedAt: z.date(),
 })
 
+// ===== Agent Memory 行 schema（对齐 prisma/add.prisma，Plan: add-coder-agent-memory-plan-v2） =====
+
+export const MemoryKindSchema = z.enum([
+  "DECISION", "CONSTRAINT", "PITFALL", "FAILURE", "LESSON",
+  "PATTERN", "CONVENTION", "FACT", "HANDOFF_DIGEST", "HYPOTHESIS",
+])
+export const MemoryStatusSchema = z.enum([
+  "CANDIDATE", "PENDING", "ACTIVE", "STALE", "SUPERSEDED", "REJECTED", "ARCHIVED",
+])
+export const MemoryScopeTypeSchema = z.enum([
+  "ORGANIZATION", "REPOSITORY", "BRANCH", "MODULE", "PATH", "SYMBOL", "PLAN", "SPEC",
+])
+export const MemorySourceTypeSchema = z.enum([
+  "PLAN", "SPEC", "DPS_GATE", "DEV_OPERATION", "RAHS_GATE", "HANDOFF", "MANUAL", "IMPORT",
+])
+export const EmbeddingStateSchema = z.enum(["DISABLED", "PENDING", "READY", "FAILED", "STALE"])
+export const RecallOutcomeSchema = z.enum([
+  "UNKNOWN", "USED", "USEFUL", "IRRELEVANT", "OUTDATED", "CONTRADICTED", "HARMFUL",
+])
+
+export const AddMemoryRowSchema = z.looseObject({
+  id: z.string(),
+  kind: MemoryKindSchema,
+  status: MemoryStatusSchema,
+  topic: z.string(),
+  content: z.string(),
+  summary: z.string().nullable(),
+  scopeType: MemoryScopeTypeSchema,
+  scopeValue: z.string(),
+  repositoryRef: z.string(),
+  importance: z.number(),
+  confidence: z.number(),
+  validFrom: z.date(),
+  validUntil: z.date().nullable(),
+  supersededById: z.string().nullable(),
+  contentHash: z.string(),
+  embeddingModel: z.string().nullable(),
+  embeddingDim: z.number().nullable(),
+  embeddingState: EmbeddingStateSchema,
+  createdBy: z.string().nullable(),
+  approvedBy: z.string().nullable(),
+  approvedAt: z.date().nullable(),
+  metadata: z.unknown().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const AddMemoryEvidenceRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  sourceType: MemorySourceTypeSchema,
+  sourceRef: z.string(),
+  planKeyword: z.string().nullable(),
+  excerpt: z.string(),
+  contentHash: z.string(),
+  occurredAt: z.date().nullable(),
+  metadata: z.unknown().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMemoryEvidenceLinkRowSchema = z.looseObject({
+  memoryId: z.string(),
+  evidenceId: z.string(),
+  relation: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMetricSnapshotRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  metricType: z.string(),
+  value: z.number(),
+  baseline: z.number().nullable(),
+  delta: z.number().nullable(),
+  unit: z.string().nullable(),
+  planKeyword: z.string().nullable(),
+  specRef: z.string().nullable(),
+  commitSha: z.string().nullable(),
+  sourceRef: z.string(),
+  metadata: z.unknown().nullable(),
+  measuredAt: z.date(),
+})
+
+export const AddMemoryRecallRowSchema = z.looseObject({
+  id: z.string(),
+  repositoryRef: z.string(),
+  query: z.string(),
+  stage: z.string(),
+  consumerRef: z.string().nullable(),
+  scopeContext: z.unknown(),
+  candidateIds: z.unknown(),
+  selectedIds: z.unknown(),
+  scoreBreakdown: z.unknown(),
+  exclusionReasons: z.unknown().nullable(),
+  rankingVersion: z.string(),
+  tokenBudget: z.number(),
+  injectedTokens: z.number(),
+  latencyMs: z.number().nullable(),
+  degradedMode: z.string().nullable(),
+  createdAt: z.date(),
+})
+
+export const AddMemoryRecallItemRowSchema = z.looseObject({
+  recallId: z.string(),
+  memoryId: z.string(),
+  selected: z.boolean(),
+  rank: z.number().nullable(),
+  outcome: RecallOutcomeSchema,
+  feedback: z.string().nullable(),
+  updatedAt: z.date(),
+})
+
 // ===== 类型派生（单一真源：schema → 类型） =====
 
 export type PlanRow = z.infer<typeof PlanRowSchema>
@@ -147,6 +259,12 @@ export type AuditLogRow = z.infer<typeof AuditLogRowSchema>
 export type DevOperationRow = z.infer<typeof DevOperationRowSchema>
 export type AddUserRow = z.infer<typeof AddUserRowSchema>
 export type CollabContractRow = z.infer<typeof CollabContractRowSchema>
+export type AddMemoryRow = z.infer<typeof AddMemoryRowSchema>
+export type AddMemoryEvidenceRow = z.infer<typeof AddMemoryEvidenceRowSchema>
+export type AddMemoryEvidenceLinkRow = z.infer<typeof AddMemoryEvidenceLinkRowSchema>
+export type AddMetricSnapshotRow = z.infer<typeof AddMetricSnapshotRowSchema>
+export type AddMemoryRecallRow = z.infer<typeof AddMemoryRecallRowSchema>
+export type AddMemoryRecallItemRow = z.infer<typeof AddMemoryRecallItemRowSchema>
 
 // ===== 查询参数（Prisma 最常用子集，结构化约束 + 运算符支持） =====
 
@@ -159,6 +277,7 @@ export interface QueryArgs<T> {
   orderBy?: { [K in keyof T]?: OrderDirection }
   take?: number
   skip?: number
+  cursor?: Record<string, unknown>
   include?: Record<string, unknown>
 }
 

package/templates/core/scripts/mcp-server/shared/hitl-create-policy.ts

@@ -0,0 +1,27 @@
+/*
+ * create_hitl 的交互裁决（手写模块；**不要放进 hitl-interaction.strategy.ts**——
+ * 那是 `hitl-interaction-rules.toml` 的生成产物，任何手写逻辑都会被 generate 覆盖）。
+ *
+ * 背景（2026-09-14 修复 Codex 空转）：
+ * 客户端按安装环境裁决交互方式：Qoder=genui、Codex=mcpApps、其余=inputRequired。
+ * `update_hitl` 早已有 `mcpApps` 分支（引导走 core widget），但 `create_hitl` **漏了这一支**，
+ * 于是 Codex 下走 elicitation 弹框 → 客户端不展示 → 一直"还在要输入" →
+ * 连续 8 轮后以 `inputRequired.maxRounds` 失败（实测报 `still required input after 8 rounds`）。
+ */
+
+/**
+ * create_hitl 是否需要跳过"创建确认弹框"：
+ * - `_fallback` / `_use_genui`：调用方显式声明的无弹框路径（既有语义）；
+ * - **`mcpApps`（Codex）**：审批交互在 core widget（`render_hitl_approval`）里完成，
+ *   此处直接产出 DRAFT 提案，再由 widget 供用户拍板。
+ */
+export function shouldSkipHitlCreateDialog(
+  mode: string, // 运行期取 toml 裁决值，收窄到 string 边界
+  flags: { fallback?: boolean; useGenui?: boolean; mcpApps?: boolean } = {},
+): boolean {
+  /*
+   * `_mcp_apps` 显式开关（2026-09-14 自 farm-agent 回灌）：环境裁决之外再给调用方一个强制入口——
+   * 适配其它客户端/build、或需要确定性地走 widget 流程时不必依赖 toml 探测结果。
+   */
+  return Boolean(flags.useGenui || flags.fallback || flags.mcpApps) || mode === "mcpApps"
+}

package/templates/core/scripts/mcp-server/shared/hitl-proposal-content.ts

@@ -0,0 +1,110 @@
+/*
+ * HITL 提案文档内容（生成 + 裁决回写）
+ *
+ * 为什么抽出来（2026-09-14 修复"生成器不满足自身 schema"）：
+ * `create_hitl` 原先把 markdown 直接内联在工具体里拼字符串，产物**缺 `## 审批结论`**，
+ * 而真源 `templates/core/templates/hitl-template.md` 与 `hitl-template.schema.json`
+ * 都把它列为必需章节；同时 `update_hitl` 只改状态行与维度列，**裁决结论不回写文档**——
+ * 结果 6/6 `*.hitl.md` 不满足自身 schema，"文件通道"残缺（结论只在 DB 与哨兵里）。
+ * 抽成纯函数后：生成物可用同一校验层直接断言（tests/hitl-proposal-content.test.ts）。
+ */
+
+/** 真源模板中的必需章节名（改这里必须同时改 hitl-template.md / .schema.json） */
+export const HITL_VERDICT_HEADING = "## 审批结论"
+
+export interface HitlDimension {
+  name: string
+  content?: string
+}
+
+export interface BuildHitlProposalInput {
+  planName: string
+  round: number
+  type: string
+  createdAt: string
+  dimensions?: HitlDimension[]
+}
+
+const escapeCell = (value: string) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>")
+
+/** 生成 HITL 提案 markdown（与 `hitl-template.md` 章节对齐） */
+export function buildHitlProposalMarkdown(input: BuildHitlProposalInput): string {
+  const dims = input.dimensions ?? []
+  const tableRows = dims.length > 0
+    ? dims.map((d, i) => `| ${i + 1} | ${d.name} | ${escapeCell(d.content ?? "")} | 同意/驳回 |`).join("\n")
+    : [
+        "| 1 | 实施主体 | | 同意/驳回 |",
+        "| 2 | 数据模型 | | 同意/驳回 |",
+        "| 3 | MCP 工具 | | 同意/驳回 |",
+        "| 4 | 文件命名 | | 同意/驳回 |",
+        "| 5 | 模板 + schema | | 同意/驳回 |",
+        "| 6 | 新增依赖 | | 同意/驳回 |",
+        "| 7 | 预计文件数 | | 同意/驳回 |",
+        "| 8 | 预计轮次 | | 同意/驳回 |",
+      ].join("\n")
+
+  return [
+    `# ${input.planName} — HITL 提案 (round ${input.round})`,
+    "",
+    `> 创建: ${input.createdAt}  |  类型: ${input.type}  |  状态: DRAFT`,
+    "",
+    "## HITL 计划总览",
+    "",
+    "请填写以下决策维度，人工审核后点击 update_hitl 弹框选择「同意/驳回」完成审批：",
+    "",
+    "| # | 维度 | 方案内容 | 决策 |",
+    "|---|------|----------|:----:|",
+    tableRows,
+    "",
+    HITL_VERDICT_HEADING,
+    "",
+    "> **tongyi**：方案通过。",
+    "> **bohui**：方案驳回，需修正后重新 create_hitl 发起下一轮。",
+    "",
+    "| 时间 | 决策 | 原因 |",
+    "|------|:----:|------|",
+    "| | | |",
+    "",
+  ].join("\n")
+}
+
+export interface HitlVerdict {
+  status: string
+  at: string
+  reason?: string
+}
+
+/** 结论表骨架（DRAFT 状态下为空白行；与 buildHitlProposalMarkdown 产出同形） */
+export const HITL_VERDICT_TABLE = [
+  "| 时间 | 决策 | 原因 |",
+  "|------|:----:|------|",
+] as const
+
+/** 保证「审批结论」章节存在（历史产物/旧生成器产物补骨架，不改动已有结论行） */
+export function ensureHitlVerdictSection(content: string): string {
+  if (content.includes(HITL_VERDICT_HEADING)) return content
+  return content.trimEnd() + "\n\n" + [HITL_VERDICT_HEADING, "", ...HITL_VERDICT_TABLE, "| | | |", ""].join("\n")
+}
+
+/**
+ * 把裁决回写进提案：刷新状态行 + 在「审批结论」表写入（或覆盖）一行。
+ * 幂等：同一提案重复调用只保留最后一行，不追加重复行。
+ */
+export function applyHitlDecisionToProposal(content: string, verdict: HitlVerdict): string {
+  const withStatus = ensureHitlVerdictSection(content).replace(/(状态:\s*)[A-Z_]+/, `$1${verdict.status}`)
+  const row = `| ${verdict.at} | ${verdict.status} | ${escapeCell(verdict.reason ?? "")} |`
+  const idx = withStatus.indexOf(HITL_VERDICT_HEADING)
+  const freshSection = [HITL_VERDICT_HEADING, "", "| 时间 | 决策 | 原因 |", "|------|:----:|------|", row, ""].join("\n")
+  if (idx < 0) {
+    // 历史产物（生成器修复前）没有该章节 → 补章节再写行，保证"文件通道"完整
+    return withStatus.trimEnd() + "\n\n" + freshSection
+  }
+  const lines = withStatus.slice(idx).split("\n")
+  const headerIdx = lines.findIndex((l) => l.startsWith("| 时间 |"))
+  if (headerIdx < 0) return withStatus.slice(0, idx) + freshSection
+  // 保留到分隔行，替换全部数据行；其后非表格内容（如追加说明）原样保留
+  const kept = lines.slice(headerIdx + 2).filter((l) => !l.trim().startsWith("|"))
+  while (kept.length > 0 && kept[0].trim() === "") kept.shift()
+  const head = withStatus.slice(0, idx) // 标题/元信息/维度表等「审批结论」之前的内容
+  return head + [...lines.slice(0, headerIdx + 2), row, ...(kept.length > 0 ? ["", ...kept] : [])].join("\n")
+}

package/templates/core/scripts/mcp-server/shared/hitl-widget-instance.ts

@@ -0,0 +1,85 @@
+/*
+ * HITL 审批实例 HTML（Plan hitl-widget-runtime-gap §WidgetInstance / §RenderFallback）
+ *
+ * 为什么需要：MCP Apps 类客户端（Codex）才渲染 widget；其余环境（Qoder/弹框/无 UI）下
+ * 审批必须仍有确定性入口。本模块把 core widget 模板 + 本次提案的维度数据落成一份**可直接打开**的
+ * 实例 HTML（文件面板/浏览器均可），并把路径回给调用方（render_hitl_approval 的 fallback）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+export const HITL_INSTANCE_DIR = "hitl"
+
+export interface HitlInstanceInput {
+  planName: string
+  type: string
+  round: number
+  status: string
+  dimensions: { name: string; content: string }[]
+  templateHtml: string
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}
+
+/** 生成实例 HTML：在模板 </body> 前注入 JSON 载荷 + 人类可读维度表（模板无占位符，故用注入而非替换） */
+export function buildHitlInstanceHtml(input: HitlInstanceInput): string {
+  const payload = {
+    planName: input.planName,
+    type: input.type,
+    round: input.round,
+    status: input.status,
+    dimensions: input.dimensions,
+  }
+  const rows = input.dimensions
+    .map(
+      (d, i) =>
+        `<tr><td>${i + 1}</td><td>${escapeHtml(d.name)}</td><td>${escapeHtml(d.content)}</td><td>同意 / 驳回</td></tr>`,
+    )
+    .join("")
+  const injected = [
+    `<script id="hitl-instance-payload" type="application/json">${JSON.stringify(payload).replace(/</g, "\\u003c")}</script>`,
+    `<section id="hitl-fallback-panel" data-plan="${escapeHtml(input.planName)}" data-round="${input.round}">`,
+    `<h2>HITL 审批（${escapeHtml(input.planName)} · ${escapeHtml(input.type)} round ${input.round}）</h2>`,
+    `<p>状态：${escapeHtml(input.status)} · 共 ${input.dimensions.length} 个维度。逐项确认后，把裁决结果告知 AI 即可落库（本页面为只读降级入口，不直接改库）。</p>`,
+    `<table><thead><tr><th>#</th><th>维度</th><th>方案内容</th><th>决策</th></tr></thead><tbody>${rows}</tbody></table>`,
+    `</section>`,
+  ].join("\n")
+
+  const bodyClose = input.templateHtml.match(/<\/body>/i)
+  if (bodyClose && bodyClose.index !== undefined) {
+    return (
+      input.templateHtml.slice(0, bodyClose.index) + injected + "\n" + input.templateHtml.slice(bodyClose.index)
+    )
+  }
+  return `${input.templateHtml}\n${injected}\n`
+}
+
+export interface WriteHitlInstanceResult {
+  htmlPath: string
+  created: boolean
+}
+
+/**
+ * 落盘实例 HTML（幂等：同 plan+round 覆盖写）。
+ * 模板缺失 → 抛明确错误（禁止静默返回空 HTML）。
+ */
+export function writeHitlInstanceHtml(
+  input: Omit<HitlInstanceInput, "templateHtml"> & { projectRoot: string; magicDir: string },
+): WriteHitlInstanceResult {
+  const templatePath = join(input.projectRoot, input.magicDir, "templates", "hitl-approval-widget.html")
+  if (!existsSync(templatePath)) {
+    throw new Error(`HITL widget 模板缺失: ${templatePath}（请执行 add-coder sync）`)
+  }
+  const dir = join(input.projectRoot, input.magicDir, HITL_INSTANCE_DIR)
+  mkdirSync(dir, { recursive: true })
+  const htmlPath = join(dir, `${input.planName}-round${input.round}.html`)
+  const html = buildHitlInstanceHtml({ ...input, templateHtml: readFileSync(templatePath, "utf-8") })
+  writeFileSync(htmlPath, html, "utf-8")
+  return { htmlPath, created: true }
+}