add-coder 0.3.23 → 0.3.25-0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.3.23",
+  "version": "0.3.25-0",
   "private": false,
   "description": "[codein2027](https://github.com/xiaomingming92/codein2027) - A complete scaffolding for building the ADD programming paradigm, the implementation layer for AI code governance. Core principle: Audit as Infrastructure. Breaks the black-box programming process and cross-session amnesia, evolving programming paradigms into an auditable, traceable, and convergent new era. npx-ready.\n\n[codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架——AI 代码治理的落地方案。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。npx 即用，人人可体验。",
   "repository": {
@@ -40,6 +40,7 @@
   "email": "wujixmm@gmail.com",
   "license": "AGPL-3.0-only",
   "dependencies": {
+    "@ariga/atlas": "^1.3.0",
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/server": "2.0.0",
     "commander": "^13.1.0",

package/templates/.add-coder-src-hash.json

@@ -1,5 +1,5 @@
 {
-  "_version": "0.3.23",
+  "_version": "0.3.25-0",
   "adapters/claude/hooks/doc-format-guard.sh": "ec59ad3f",
   "adapters/claude/hooks/lib/common.sh": "4f3e64ad",
   "adapters/claude/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -26,6 +26,7 @@
   "adapters/claude/hooks/subagent-stop.sh": "0f89e28c",
   "adapters/claude/mcp.json": "4ddc5120",
   "adapters/claude/settings.json": "067ccc45",
+  "adapters/codex/config.toml.example": "de1634aa",
   "adapters/codex/hooks/doc-format-guard.sh": "8e134e78",
   "adapters/codex/hooks/lib/common.sh": "4f3e64ad",
   "adapters/codex/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -180,7 +181,7 @@
   "core/rules/profiles/webapp-profile.md": "e493ae7b",
   "core/rules/project_rules.md": "82b25e08",
   "core/rules/theory-practice-map.toml": "b1db99fd",
-  "core/scripts/db-ensure.sh": "faeb6b92",
+  "core/scripts/db-ensure.sh": "94a5ff92",
   "core/scripts/gen-plan-index.sh": "bfc6ad3e",
   "core/scripts/mcp-server/elicitation/confirm.ts": "924857b8",
   "core/scripts/mcp-server/elicitation/index.ts": "44c5dc3f",
@@ -202,7 +203,8 @@
   "core/scripts/mcp-server/shared/package.json": "e3d5a4a2",
   "core/scripts/mcp-server/shared/prisma.ts": "a9618f99",
   "core/scripts/mcp-server/shared/project-root-strategy.ts": "1a5bdc57",
-  "core/scripts/mcp-server/shared/response.ts": "f7806b67",
+  "core/scripts/mcp-server/shared/redact.ts": "22e008aa",
+  "core/scripts/mcp-server/shared/response.ts": "0d1539a8",
   "core/scripts/mcp-server/shared/run-command.ts": "42caf972",
   "core/scripts/mcp-server/tasks/index.ts": "c040eb75",
   "core/scripts/mcp-server/tasks/runner.ts": "d84bd35d",
@@ -214,20 +216,20 @@
   "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "b58e76ee",
   "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "23fbbb6b",
   "core/scripts/mcp-server/tools/gateway/check_dps.ts": "4d599b38",
-  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "4078b0f1",
-  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "486df441",
+  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "3ce99c7c",
+  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "8d6efd83",
   "core/scripts/mcp-server/tools/gateway/helpers.ts": "f8794a92",
   "core/scripts/mcp-server/tools/gateway/index.ts": "559acb75",
   "core/scripts/mcp-server/tools/gateway.backup": "65eae393",
   "core/scripts/mcp-server/tools/hitl.ts": "f447345f",
   "core/scripts/mcp-server/tools/hook-event-report.ts": "3f21836e",
-  "core/scripts/mcp-server/tools/index.ts": "884172ba",
+  "core/scripts/mcp-server/tools/index.ts": "3e6b6135",
   "core/scripts/mcp-server/tools/plan.ts": "477fd80d",
   "core/scripts/mcp-server/tools/quality.ts": "c4634453",
   "core/scripts/mcp-server/tools/registrar.ts": "efd81b3a",
   "core/scripts/mcp-server/tools/review.ts": "370f84f2",
   "core/scripts/mcp-server/types.ts": "6c5e60bc",
-  "core/scripts/mcp-server.ts": "99cc6833",
+  "core/scripts/mcp-server.ts": "48b1fd69",
   "core/skills/add-paradigm/SKILL.md": "5d4fa389",
   "core/skills/session-init/SKILL.md": "bb1205b0",
   "core/specs/add-coder-npm-package/checklist.md": "ed92032c",
@@ -252,6 +254,7 @@
   "core/templates/hitl-template.md": "44989804",
   "core/templates/hitl-template.schema.json": "e7ecc53e",
   "core/templates/index.md": "0fb42ea5",
+  "core/templates/ports.example.md": "f5a7e436",
   "core/templates/prd-incremental-template.md": "4a996ad5",
   "core/templates/prd-incremental-template.schema.json": "bb44f022",
   "core/templates/prd-standard-template.md": "abf639c2",

package/templates/adapters/codex/config.toml.example

@@ -0,0 +1,20 @@
+# Codex MCP 配置模板（真源）
+# 渲染后分发到 .codex/ 与各 magic dirs templates/，供 --print-mcp-config 输出
+# 使用方式:
+#   npx add-coder init --adapter=codex --print-mcp-config   # stdout 输出片段
+#   npx add-coder init --adapter=codex --write-user-config  # 显式确认后写入 ~/.codex/config.toml
+#
+# Windows 分支（renderer 按平台注入，无需手动修改）:
+#   win32: command = "cmd /c"  args = ["npx.cmd", "tsx", "..."]   # .cmd 分支
+#   posix: command = "npx"     args = ["tsx", "..."]
+#
+# 安全约定:
+#   - env 只引用环境变量（{{projectRoot}} 由渲染时注入，密码/连接串禁止写入模板）
+#   - DATABASE_URL 请通过消费方 .env 或 IDE 环境传入，模板不包含任何连接串
+
+[mcp_servers.add_coder]
+command = "{{codexCommand}}"
+args = ["tsx", "{{magicDir}}/scripts/mcp-server.ts"]
+env = {
+  PROJECT_ROOT = "{{projectRoot}}",
+}

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

@@ -82,3 +82,106 @@ fi
 if [ "$DO_MIGRATE" = "true" ]; then
   backup_add_tables
 fi
+
+# ════ Atlas 声明式同步模块（函数式；消费方日常变更同步入口，与 v2 引擎同源逻辑）════
+# 触发：--migrate（init 流程）或宿主手动 `bash db-ensure.sh <engine> <container> --migrate`
+# 依赖环境变量：DB_URL / ADD_DATABASE_URL(可选) / ATLAS_DEV_URL / PROJECT_NAME / DATABASE_USER
+
+# ① atlas 可执行解析（三路径：add-coder 包内 → 顶层 .bin → PATH；无则走 npx --no-install）
+resolve_atlas_bin() {
+  local b
+  for b in \
+    "$PROJECT_DIR/node_modules/add-coder/node_modules/.bin/atlas" \
+    "$PROJECT_DIR/node_modules/.bin/atlas" \
+    "$(command -v atlas 2>/dev/null || true)"; do
+    [ -n "$b" ] && [ -x "$b" ] && { echo "$b"; return 0; }
+  done
+  return 1
+}
+
+# ② atlas 命令执行器（本地 bin 或 npx --no-install）
+atlas_cmd() {
+  local bin; bin="$(resolve_atlas_bin || true)"
+  if [ -n "$bin" ]; then "$bin" "$@"; else npx --no-install @ariga/atlas "$@"; fi
+}
+
+# ③ 目标构造（模式判定：分库=ADD 模型 / 共库=宿主 + 动态 exclude 非 ADD 表）
+# 输出全局：TARGET_URL / SCHEMA_TARGET / EXCLUDE_ARGS
+build_target() {
+  TARGET_URL=""
+  SCHEMA_TARGET="prisma/"
+  EXCLUDE_ARGS=()
+  local tables
+  if [ -n "${ADD_DATABASE_URL:-}" ]; then
+    TARGET_URL="${ADD_DATABASE_URL//?schema=public/}"
+    SCHEMA_TARGET="prisma/add.prisma"
+    echo ">>> Atlas 同步（分库模式: ADD 治理模型）..."
+  else
+    TARGET_URL="${DB_URL//?schema=public/}"
+    # 动态 exclude：库中除 ADD 7 表外的全部表（业务表/checkpoint/_prisma_migrations）——Atlas glob 不生效，需 public. 前缀精确名
+    tables="$(podman exec "${PROJECT_NAME:-add-project}-postgres" psql -U "${DATABASE_USER:-admin}" -d "${PROJECT_NAME:-add-project}" -tAc "SELECT string_agg('public.' || table_name, ',') FROM information_schema.tables WHERE table_schema='public' AND table_name NOT IN ('AddUser','DevOperation','AuditLog','HitlRecord','PlanRecord','ReviewRecord','CollabContract');" 2>/dev/null || true)"
+    [ -n "$tables" ] && EXCLUDE_ARGS=(--exclude "$tables")
+    echo ">>> Atlas 同步（共库模式: 仅 ADD 治理表，其余 $(echo "$tables" | tr ',' '\n' | wc -l) 张表排除）..."
+  fi
+  TARGET_URL="${TARGET_URL}?sslmode=disable"
+}
+
+# ④ baseline 生成（同源：Prisma schema SQL，过滤 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"
+}
+
+# ⑤ diff 检测（SQL 语句特征判定：Atlas 无变更时输出 "Schemas are synced..." 非空，不算变更）
+# 输出全局 DIFF_SQL；返回 0=有变更 / 1=无变更
+run_atlas_diff() {
+  DIFF_SQL="$(atlas_cmd schema diff --from "$TARGET_URL" --to "file://$BASELINE_SQL" --dev-url "$ATLAS_DEV_URL" "${EXCLUDE_ARGS[@]}" 2>/dev/null)"
+  echo "$DIFF_SQL" | grep -qE "^(CREATE|ALTER|DROP|COMMENT|-- *(Create|Modify|Drop))"
+}
+
+# ⑥ apply（确认门槛：交互输出 SQL → 确认 → apply；拒绝则跳过）
+apply_atlas_diff() {
+  echo "=== 待应用 diff SQL（前 60 行）==="
+  echo "$DIFF_SQL" | head -60
+  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[@]}"
+    echo ">>> Atlas 同步完成"
+  else
+    echo ">>> 已取消，未应用"
+  fi
+}
+
+# ⑦ Atlas 同步主流程（探测 → dev-url → 目标 → baseline → diff → apply）
+atlas_sync() {
+  [ "$ENGINE" = "sqlite" ] && return 0
+  # 迁移锁（进程层契约 v2 §6）：多 IDE 并发 init 时仅一个进程执行迁移
+  # 非阻塞拿锁（pg_try_advisory_lock），会话级锁——脚本退出连接断开自动释放
+  LOCK_KEY="0xADD001"
+  LOCKED="$(podman exec "${PROJECT_NAME:-add-project}-postgres" psql -U "${DATABASE_USER:-admin}" -d "${PROJECT_NAME:-add-project}" -tAc "SELECT pg_try_advisory_lock(${LOCK_KEY});" 2>/dev/null || true)"
+  if [ "$LOCKED" != "t" ]; then
+    echo "!!! 另一个进程正在迁移，请稍后重试"
+    return 1
+  fi
+  if ! atlas_cmd version > /dev/null 2>&1; then
+    echo "!!! Atlas 不可用。add-coder sync --patch 可自动安装 @ariga/atlas；或手动: pnpm add -D @ariga/atlas"
+    echo "    降级路径: prisma-diff（免 shadow）→ db-push + 强制备份；文档: README「Atlas 数据库同步能力」"
+    return 1
+  fi
+  if [ -z "${ATLAS_DEV_URL:-}" ]; then
+    echo "!!! ATLAS_DEV_URL 未配置。请运行 add-coder init（分库引导自动创建 {project}-add-dev 常驻容器并登记）或手动配置"
+    return 1
+  fi
+  build_target
+  generate_baseline
+  if run_atlas_diff; then
+    apply_atlas_diff
+  else
+    echo ">>> schema 一致（幂等出口）"
+  fi
+}
+
+if [ "$DO_MIGRATE" = "true" ]; then
+  atlas_sync
+fi

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

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

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

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

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

@@ -9,7 +9,7 @@
 import * as z from "zod/v4";
 import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
-import { join } from "path";
+import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
 import {
   readFileSafe,
@@ -42,7 +42,9 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         const pm = apf.find(
           (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
+            f.toLowerCase().includes(pp.toLowerCase()) &&
+            f.includes("-plan-v") &&
+            !f.includes(".hitl"),
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
@@ -80,6 +82,71 @@ export function registerCheckRahs(server: ToolRegistrar) {
           })) as Array<{ id: string }>;
           auditScore = Math.min(100, logs.length * 10);
         } catch {}
+        // ── 范围保真度 / Spec 合规 / 阶段对称性：从静态基线改为动态计算（修复：
+        //    三个维度原为固定 80，任何 Plan 的 RAHS 上限 88 永远无法通过）──
+        try {
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const checks = arContent.match(/^- \[[ x]\]/gm) || [];
+            const done = checks.filter((c) => c.includes("[x]")).length;
+            // 阶段对称性：add-route Step 产出项勾选率（Handoff/Report Closure 等
+            //    条件项未勾选时按比例折算，不阻塞）
+            symScore = checks.length > 0
+              ? Math.max(70, Math.round((done / checks.length) * 100))
+              : 70;
+          }
+        } catch {}
+        try {
+          // Spec 合规：checklist [T] 项勾选率（[R] 运行时项不计入）
+          const specDir = join(PROJECT_ROOT, MAGIC_DIR, "specs");
+          const sn = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
+          const clPath = join(specDir, sn, "checklist.md");
+          if (existsSync(clPath)) {
+            const cl = (await readFileSafe(clPath)) || "";
+            const tItems = cl.match(/^- \[[ x]\] \[T\]/gm) || [];
+            const tDone = tItems.filter((c) => c.includes("[x]")).length;
+            specScore = tItems.length > 0
+              ? Math.max(70, Math.round((tDone / tItems.length) * 100))
+              : 70;
+          }
+        } catch {}
+        try {
+          // 范围保真度：git diff 变更文件与 add-route 附录清单匹配率
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const appendix = (
+              arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) ||
+              []
+            ).map((f: string) => f.replace(/`/g, "").toLowerCase());
+            const diff = runCommand("git", ["diff", "--name-only"], {
+              cwd: PROJECT_ROOT,
+              timeout: 5000,
+            });
+            const diffFiles = diff.stdout
+              .trim()
+              .split("\n")
+              .filter(Boolean)
+              .map((f: string) => f.toLowerCase());
+            if (appendix.length > 0 && diffFiles.length > 0) {
+              const matched = diffFiles.filter((f) =>
+                appendix.some((a) => f === a || f.endsWith(`/${a}`)),
+              ).length;
+              scopeScore = Math.max(70, Math.round((matched / diffFiles.length) * 100));
+            }
+          }
+        } catch {}
         const parts = [
           "=== RAHS：Runtime Architecture Health Score ===",
           `Plan 关键词: "${pp}"`,

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

@@ -69,7 +69,7 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
           // 提取 add-route 附录文件清单
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json)`/g) || [])
+          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/index.ts

@@ -12,6 +12,61 @@ import { registerReviewTools } from "./review.js"
 import { PROJECT_ID } from "../shared/env.js"
 import type { ToolRegistrar } from "./registrar.js"
 
+// ── 读写分级信号量节流（进程层并发契约 v2 §7：Codex Parallel MCP 真并行兑底） ──
+// 读工具共享 8 并发；写工具共享 4 并发；超限请求排队（MCP 协议允许延迟响应，排队即天然反压）
+const READ_MAX = 8
+const WRITE_MAX = 4
+
+const READ_TOOLS = new Set([
+  "get_project_context", "find_related_docs", "get_db_schema", "query_audit_logs",
+  "plan_status", "review_status", "status_hitl", "contract_status",
+  "check_dps", "check_rahs", "check_add_route_status", "check_spec_sync",
+  "check_add_route_completeness", "check_phase_symmetry", "check_failure_path",
+  "check_add_compliance", "get_hook_events",
+])
+
+function createSemaphore(limit: number) {
+  let active = 0
+  const queue: (() => void)[] = []
+  const acquire = () =>
+    new Promise<void>((resolve) => {
+      if (active < limit) {
+        active++
+        resolve()
+      } else {
+        queue.push(resolve)
+      }
+    })
+  const release = () => {
+    active--
+    const next = queue.shift()
+    if (next) {
+      active++
+      next()
+    }
+  }
+  return { acquire, release }
+}
+
+// 429 指数退避重试（3 次，250ms 起步，倍率 2x）：上游限流不直接透传
+async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let lastErr: unknown
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      return await fn()
+    } catch (e) {
+      lastErr = e
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/429|rate.?limit|限流/i.test(msg)) throw e
+      await new Promise((r) => setTimeout(r, 250 * 2 ** (attempt - 1)))
+    }
+  }
+  throw lastErr
+}
+
+const readSem = createSemaphore(READ_MAX)
+const writeSem = createSemaphore(WRITE_MAX)
+
 export function registerAllTools(server: McpServer) {
   // D9 多 MCP 路由安全：派生装饰版 registrar，为所有工具 description 注入项目身份前缀
   const origRegister = server.registerTool.bind(server)
@@ -20,10 +75,20 @@ export function registerAllTools(server: McpServer) {
   type ToolCb = Parameters<RegisterTool>[2]
   const registerTool = ((name: string, config: ToolConfig, cb: ToolCb) => {
     const c = config as { description?: string }
+    // 读写分级节流 + 429 退避（进程层契约 v2：Codex 并行调用兜底）
+    const sem = READ_TOOLS.has(name) ? readSem : writeSem
+    const throttledCb = (async (...args: unknown[]) => {
+      await sem.acquire()
+      try {
+        return await withRetry(async () => cb(...(args as Parameters<ToolCb>)))
+      } finally {
+        sem.release()
+      }
+    }) as ToolCb
     return origRegister(
       name,
       { ...config, description: `[项目: ${PROJECT_ID}] ${c.description ?? ""}` },
-      cb,
+      throttledCb,
     )
   }) as RegisterTool
   const registrar: ToolRegistrar = { registerTool }

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

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/server"
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"
 import { registerAll } from "./mcp-server/index.js"
+import { redact } from "./mcp-server/shared/redact.js"
 
 async function main() {
   const server = new McpServer(
@@ -14,6 +15,6 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error("[ADD-MCP] Fatal error:", error)
+  console.error("[ADD-MCP] Fatal error:", redact(error instanceof Error ? error.message : String(error)))
   process.exit(1)
 })

package/templates/core/templates/ports.example.md

@@ -0,0 +1,49 @@
+# 端口契约登记表（{{projectName}}）
+
+> **定位**：本项目开发环境端口统一登记表，是项目本地端口分配的唯一事实源。
+> **维护**：新增容器/服务端口前必须先查本表；改端口后必须同步更新 `.env.development` 变量、`DATABASE_URL`/`SHADOW_DATABASE_URL`/`ATLAS_DEV_URL` 与本表三处。
+> **最后更新**: （登记日期，按实际填写）
+> ⚠️ 跨项目共享端口（如本机 5433/5434/5437 等）以跨项目事实源 `docs/ports.md`（如 farm-agent）为准，本项目表只登记本项目端口。
+
+---
+
+## 1. 端口分配总表
+
+> **init 自动登记**：`add-coder init`（分库引导）与 Atlas 同步会自动为「主库 / ADD 库 / Atlas dev 库」三类容器分配端口并登记本表——分配规则见 §4 约定规则。以下为示例行。
+
+| 端口 | 服务 | 用途 | 状态 | 配置位置 |
+|:---:|------|------|:---:|---------|
+| 5432 | PostgreSQL 宿主库 | 宿主业务库（PG 标准端口，示例） | 🟡 示例 | 宿主自有配置 |
+| 5433 | PostgreSQL ADD 配套库 | add-coder 配套容器第一顺位：`{{projectName}}-add-postgres`（宿主 5432 之后从 5433 起，示例） | 🟡 示例 | `.env.development` `ADD_DATABASE_URL` |
+| 5434 | PostgreSQL Atlas dev 库 | Atlas 常驻 dev 空库 `{{projectName}}-add-dev`（可随时重置，示例） | 🟡 示例 | `.env.development` `ATLAS_DEV_URL` |
+| 3000 | Web dev server | 前端/服务开发端口（示例） | 🟡 示例 | `.env.development` `PORT` |
+
+> 表头为固定规范；行数据为**示例**，按项目实际情况增删改。
+
+## 2. 已知冲突与处置
+
+| # | 端口 | 冲突方 A | 冲突方 B | 处置 |
+|:---:|:---:|---------|---------|------|
+| 1 | 5433 | 本项目默认值 | 其他项目同默认值 | 🟡 示例：已改用空闲端口并登记 |
+
+## 3. 容器快照
+
+### 运行中
+
+| 容器 | 端口 | 归属 |
+|------|------|------|
+| `{{projectName}}-add-postgres` | 5433 | 本项目 ADD 治理库（分库引导，示例） |
+| `{{projectName}}-add-dev` | 5434 | 本项目 Atlas dev 空库（可随时重置，示例） |
+
+### Created / Exited（历史容器，端口已释放）
+
+`—`（示例：按 `podman ps -a` 实际登记）
+
+## 4. 约定规则
+
+1. **改端口 = 三处同步**：`.env.development` 变量 + `DATABASE_URL`/`ADD_DATABASE_URL`/`SHADOW_DATABASE_URL`/`ATLAS_DEV_URL` + compose 引用，改完更新本表
+2. **新增服务**：先查本表 + 跨项目事实源取空闲端口；**PG 配套从 5433 起**（宿主标准 5432 之后第一顺位），按服务类型分段（PG=5433+ / Web=3xxx / MCP=30xx），避免默认值撞车
+3. **init 全局登记（统一分配器）**：`add-coder init` 通过统一端口分配器为「主库 / ADD 库 / Atlas dev 库」一次性分配并登记本表——分配前先读本表已有登记（已登记端口复用不重复分配）与跨项目事实源，再**从 5433 起扫描真实空闲**（podman ps + `portInUse` 探测），分配后写入本表；**禁止各模块自行分散扫描端口**（建议起点可在端口规则 `ports-rules.toml` 调整）
+4. **Atlas dev 库同表登记**：dev-url 常驻空库与主库同表登记，状态列标注「dev 库」；dev 库**可随时重置，不是数据真源**，重置后无需迁移备份
+5. **删除容器前**：确认数据卷是否需要保留（容器删了卷还在）
+6. **端口检测**：`podman ps --format '{{.Names}} {{.Ports}}'` 为准，`ss -tlnp` 为辅