@yarch/create-admin 0.1.0 → 0.2.1

package/README.md

@@ -1,42 +1,110 @@
-# @yarch/create-admin · yarch web 工程生成器
+# @yarch/create-admin
 
-> W6-W9（2026-09-03 拍板）：npm 分发 + 交互问答 + maven-archetype 式全量渲染 + 模板资产化。
-> golang 栈 `cmd/yarch-init` 的 web 对偶——模板是**声明式资产**（`{{var}}` 占位 + `archetype.json` 变量声明，不要求自身可安装），工程正确性由 CI「生成后冒烟」保证。
+> 一条命令生成**生成即合规**的中后台工程——契约底座、命名标准、结构纪律全部预置，三档 UI 任选。
+> npm：[@yarch/create-admin](https://www.npmjs.com/package/@yarch/create-admin)（v0.1.0+）
 
-## 创建工程（一行命令，零 clone）
+## 优势：比裸脚手架（create-vite）多给什么
+
+| 维度 | 裸脚手架 | 本生成器 |
+|---|---|---|
+| 接口层 | 空壳，信封/错误码自己搭 | `@yarch/contract` 预接线：RestResponse 信封解包 · 13 码错误码表 · traceId 透传 · 401 自动跳登录 |
+| 工程名 | 随手起 | 强制 registry 标准（小写短横线 + 禁裸通用词）；工程名 = npm 包名 = 服务名，生成即登记提醒 |
+| UI 库 | 自己选、自己集成 | **三档一键选**：Semi / antd / Arco——契约底座与结构不变，只换 UI 壳 |
+| 升级 | 模板拷走即断亲 | 底座是 npm 版本依赖：`pnpm update @yarch/contract @yarch/react` 一行跟进平台修复 |
+| 结构 | 分层靠自觉 | feature-first 分层 + depcruise 同款机检口径（pages 薄入口、禁反向依赖） |
+| 跨栈 | — | 与 java / golang 栈同一套契约：一个 traceId 前后端拉通，错误码语义唯一 |
+
+## 创建：三档 UI，各一条命令
 
 ```bash
-# 标准路径：从 npm registry 拉取脚手架（三包已发版后即可用）——
-npm create @yarch/admin@latest ysaas-console          # 交互问答：工程名 → UI 档 → 描述 → 端口 → 代理 → GitLab 分组
+# Semi 档（默认 · 抖音系）
+npm create @yarch/admin@latest ysaas-console
+
+# antd 档（蚂蚁系）
 npm create @yarch/admin@latest ysaas-console -- --ui antd
 
-# 发版前/开发中（本地，等价 golang `go run ./cmd/yarch-init`）：
-node stacks/web/packages/create/bin/create-admin.mjs ysaas-console --deps file
+# Arco 档（字节系）
+npm create @yarch/admin@latest ysaas-console -- --ui arco
+```
+
+不传 `--ui` 则交互三选一（回车落默认 Semi）；交互同时问描述 / 端口 / API 代理目标 / GitLab 分组，全部有默认值。三档底座与目录结构完全一致，切换档位 = 换个名字重新生成。
+
+## 起跑（两分钟）
+
+```bash
+cd ysaas-console
+pnpm install
+pnpm dev        # http://localhost:5173
+pnpm build      # tsc --noEmit + vite build
 ```
 
-工程名即一切标识（W7 标准化）：npm 包名 = registry.md 服务名，生成器强制 `^[a-z][a-z0-9-]{1,31}$` + 禁裸通用词（一-1/一-2，与 golang 侧同款校验）。
+- **接后端**：`vite.config.ts` 已预配 `/api/v1` 反向代理，改 target 即指向你的服务；
+- **升级底座**：`pnpm update @yarch/contract @yarch/react`；
+- **登记**：按生成后的控制台提醒，去 yarch 仓 `contract/registry.md` 登记服务名（PR 即登记）。
 
-## 问答变量（archetype.json 声明，渲染进目录/文件/内容）
+## 微前端：一条命令生成基座 / 子应用
 
-| 变量 | 问题 | 默认 |
+```bash
+# 基座（布局/菜单/登录态/路由分发/错误兜底，全局唯一）
+npm create @yarch/admin@latest ysaas-console -- --micro base
+
+# 子应用（独立·集成双运行形态，只做域内页面）
+npm create @yarch/admin@latest ysaas-billing -- --micro sub --port 5174
+```
+
+与单应用档的差异（规约：[micro-frontend.md](../../../contract/web/micro-frontend.md)）：
+
+- **应用名双重校验**：在服务名规则之上加「服务名-用途」两段式 + `contract/registry.md` 登记表核对（重名/未登记当场拒绝；登记表离线时可用包内快照）；
+- **基座**：`micro-apps.config.ts` 登记表声明式装配菜单与路由分发（禁硬编码子应用路由）、登录态唯一持有、共享运行时注册（`src/micro/shared.ts`）、加载失败重试页；
+- **子应用**：`src/supply/` 供给层实现独立·集成双运行（十一-2）——独立模式全量自足可单独 `pnpm dev`，集成构建（`pnpm build:micro` → `dist-micro/`）react 系与 contract 由基座 window 全局提供，产物体积里框架消失；
+- **UI 档**：本批仅 Semi（`--ui` 其余档触发式扩展）。
+
+仓内活案例：[examples/ysaas-console](../examples/ysaas-console)（基座）+ [examples/ysaas-billing](../examples/ysaas-billing)（子应用），事件上行/双模式/e2e 全链路。
+
+<details>
+<summary><b>附录：交互问答明细 · flags 全表 · 命名规则 · 原理 · 发布（点开）</b></summary>
+
+### 交互问答（单应用 6 项；微前端形态在最前多一项「工程形态」）
+
+| # | 问题 | 默认 |
 |---|---|---|
-| `packageName` | 工程名（= npm 包名 = registry 服务名） | 必填 |
-| `appName` | 展示名（index.html 标题） | = packageName |
-| `description` | 工程描述 | `<名>：基于 yarch web 脚手架生成的中后台工程` |
-| `port` | vite dev 端口 | 5173 |
-| `proxyTarget` | `/api/v1` 反向代理目标 | `http://localhost:8080` |
-| `yarchContractDep` / `yarchReactDep` | @yarch 底座依赖形态 | `--deps version`（默认，`^0.1.0`，标准形态）· `--deps file`（发版前本地过渡 = golang replace 行对偶） |
+| 0 | 工程形态：1) 单应用（默认）2) 微前端基座 3) 微前端子应用 | 单应用 |
+| 1 | 工程名（= npm 包名 = registry 服务名，须过校验） | 必填 |
+| 2 | UI 档：1) Semi（默认）2) antd 3) Arco | semi |
+| 3 | 工程描述 | `<工程名>：基于 yarch web 脚手架生成的中后台工程` |
+| 4 | dev 端口 | 5173 |
+| 5 | API 代理目标 | `http://localhost:8080` |
+| 6 | GitLab 分组（登记提示用） | 空 |
 
-CI 非交互：`--yes` + 全量 flags；渲染后扫描残留 `{{var}}`，有即报错（防模板与变量集漂移）。
+### 命名规则（contract/registry.md 一-1/一-2，与 golang 生成器同款）
+
+- 格式 `^[a-z][a-z0-9-]{1,31}$`：小写字母/数字/短横线，字母开头，2~32 字符——大写、下划线、中文一律当场拒绝；
+- 禁裸通用词：`api app service server backend web admin main common system demo user gateway` 不得单独成名（加前缀消歧，如 `ysaas-admin`）。
+
+### 非交互 flags（脚本 / CI）
+
+`npm create @yarch/admin@latest <名> -- --ui antd --yes`（npm 传 flag 须 `--` 分隔；pnpm 直接跟）。
+维护者本地直跑：`node stacks/web/packages/create/bin/create-admin.mjs <名> --ui antd --yes --deps file`。
+
+| flag | 取值 | 说明 |
+|---|---|---|
+| `--name` | 工程名 | 也可用第一个位置参数 |
+| `--ui` | `semi` \| `antd` \| `arco` | 非法值报错 |
+| `--micro` | `base` \| `sub` | 微前端模板档；缺省=单应用 admin（不受微前端规约约束） |
+| `--registry` | 路径 | 微前端应用名核对用的 registry.md（缺省用包内快照） |
+| `--desc` | 文本 | 不得含双引号/反斜杠 |
+| `--port` | 1024~65535 | |
+| `--proxy` | `http(s)://…` | API 代理目标 |
+| `--group` | 文本 | GitLab 分组 |
+| `--deps` | `version`（默认）\| `file` | `file` = 指向 yarch 本仓源码（发版前联调） |
+| `--src` / `--out` | 目录 | 模板根 / 输出目录（默认 `./<工程名>`，须空） |
+| `--yes` | | 非交互，缺省全走默认 |
 
-## 三档模板（templates/，W1 决策）
+### 原理（一段话）
 
-| 档 | UI 库 |
-|---|---|
-| `admin-semi`（默认） | Semi Design（抖音系） |
-| `admin-antd` | antd（蚂蚁系） |
-| `admin-arco` | Arco Design（字节系） |
+maven-archetype / cookiecutter 模式：三档模板是声明式资产（`{{var}}` 占位 + `archetype.json` 变量声明），生成器做问答 → 变量集 → 目录/文件/内容全量替换 + 残留占位符扫描；模板自身不要求可安装，工程正确性由 CI「生成后冒烟」（生成 → install → tsc → build）保证。
 
-## 发布（W6）
+### 发布（维护者）
 
-推 tag `stacks/web/vX.Y.Z` 触发 [web-publish.yml](../../../.github/workflows/web-publish.yml)：发版前跑契约断言 + 依赖机检，随后按 contract → react → create 顺序发布三包（幂等：registry 已有同版本则跳过；需仓库 Secret `NPM_TOKEN`）——**golang「tag → module proxy」的 npm 对偶**。发布前自检：`pnpm --filter <包名> pack --dry-run`。
+推 tag `stacks/web/vX.Y.Z` → [web-publish.yml](../../../.github/workflows/web-publish.yml)：断言 + 机检 → contract → react → create 顺序发布（幂等）。
+</details>

package/bin/create-admin.mjs

@@ -18,6 +18,7 @@ import { readFileSync, writeFileSync, readdirSync, mkdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import readline from "node:readline/promises";
+import { parseRegistryMd } from "./registry.mjs";
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const UI_TIERS = {
@@ -25,6 +26,14 @@ const UI_TIERS = {
   antd: "antd（蚂蚁系）",
   arco: "Arco Design（字节系）",
 };
+// 微前端模板档（W10）：载器 micro-app（contract/README 登记表默认档），UI 档本批固定 semi，其余档触发式。
+const MICRO_KINDS = {
+  base: "微前端基座（micro-frontend.md 一-1：全局唯一，承载布局/菜单/登录态/路由分发/错误兜底）",
+  sub: "微前端子应用（micro-frontend.md 一-3：独立·集成双运行形态，只做域内页面）",
+};
+// @yarch 底座版本依赖（--deps version 形态）；与本仓发版版本同步 bump。
+const YARCH_VERSION = "^0.3.0";
+const YARCH_PRO_REACT_VERSION = "^0.1.0";
 
 const servicePattern = /^[a-z][a-z0-9-]{1,31}$/;
 // 禁裸通用词（registry.md 一-1/一-2 口径摘录，与 golang yarch-init 同款；完整表以 contract/registry.md 为准）。
@@ -40,11 +49,13 @@ const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9]*)\s*\}\}/g;
 
 function usage() {
   return [
-    "用法：create-admin <工程名|输出目录> [--name <名>] [--ui semi|antd|arco] [--desc <描述>]",
-    "              [--port <端口>] [--proxy <目标>] [--group <GitLab分组>] [--deps file|version]",
-    "              [--src <模板根>] [--out <目录>] [--yes]",
+    "用法：create-admin <工程名|输出目录> [--name <名>] [--ui semi|antd|arco] [--micro base|sub]",
+    "              [--registry <registry.md 路径>] [--desc <描述>] [--port <端口>] [--proxy <目标>]",
+    "              [--group <GitLab分组>] [--deps file|version] [--src <模板根>] [--out <目录>] [--yes]",
+    "  --micro   微前端模板档（W10）：base=基座 / sub=子应用；缺省=单应用 admin（不受微前端规约约束）",
+    "  --registry  微前端名称核对用的 contract/registry.md 路径（默认用包内快照 bin/registry-snapshot.json）",
     "  --yes     非交互：缺省项全走默认值（CI 用）",
-    "  --deps    @yarch 底座依赖形态：version（默认，^0.1.0，需 @yarch 已发 npm）| file（发版前本地过渡）",
+    "  --deps    @yarch 底座依赖形态：version（默认，^0.2.0，需 @yarch 已发 npm）| file（发版前本地过渡）",
   ].join("\n");
 }
 
@@ -77,6 +88,43 @@ function validateName(name) {
   return null;
 }
 
+// —— 微前端应用名校验（micro-frontend.md 二-1/二-4，十三表「创建期」机检）——
+
+// 快照来源：--registry 指向的 registry.md（CI/内网用最新表）优先，否则用随包分发的快照。
+function loadRegistry(registryArg) {
+  if (registryArg) {
+    return parseRegistryMd(readFileSync(resolve(registryArg), "utf8"));
+  }
+  try {
+    const snapshot = JSON.parse(readFileSync(join(PKG_ROOT, "bin", "registry-snapshot.json"), "utf8"));
+    return {
+      serviceNames: new Set(snapshot.serviceNames),
+      appNames: new Set(snapshot.appNames),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function validateMicroName(name, registry) {
+  const baseErr = validateName(name);
+  if (baseErr) return baseErr;
+  if (!registry) {
+    return "无法核对 registry.md（缺 bin/registry-snapshot.json 且未传 --registry <path>）——微前端应用名必须核对登记表（二-1）";
+  }
+  if (!name.includes("-")) {
+    return "微前端应用名须由「服务名-用途/域」两段及以上构成（micro-frontend.md 二-1，正例 ysaas-billing）";
+  }
+  const service = name.split("-")[0];
+  if (!registry.serviceNames.has(service)) {
+    return `首段 ${service} 不在 registry.md 二节已登记服务名表（二-1）；若快照过期，用 --registry 指向最新 contract/registry.md`;
+  }
+  if (registry.appNames.has(name)) {
+    return `应用名 ${name} 已在 registry.md 四节登记（二-4：跨项目不得重名）`;
+  }
+  return null;
+}
+
 async function askText(rl, question, { fallback = "", validate = null, optional = false } = {}) {
   for (;;) {
     const hint = fallback ? `（默认 ${fallback}）` : optional ? "（可空）" : "";
@@ -144,12 +192,23 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const nameArg = args.name || (args._.length > 0 && !args._[0].startsWith("/") ? args._[0] : null);
 
+  let micro = args.micro;
+  if (micro !== undefined && !(micro in MICRO_KINDS)) {
+    fatal(`--micro 须为 ${Object.keys(MICRO_KINDS).join("|")}，当前：${micro}`);
+  }
   const ui = args.ui ?? "semi";
   if (!(ui in UI_TIERS)) fatal(`--ui 须为 ${Object.keys(UI_TIERS).join("|")}，当前：${ui}`);
+  if (micro && ui !== "semi") {
+    fatal("微前端模板档本批仅 semi（W1 默认档）；其余 UI 档触发式扩展（PLAN.md W10）");
+  }
 
   const interactive = !args.yes && process.stdin.isTTY;
   if (!nameArg && !interactive) fatal(`工程名必填（或用 --yes 走交互外模式）：\n${usage()}`);
 
+  // 微前端形态才需要登记表核对（二-1 首段=已登记服务名；单应用仍走一-1/一-2 正则+禁裸词）。
+  const needsRegistry = micro !== undefined || interactive; // 交互形态问答后可能选 micro
+  const registry = needsRegistry ? loadRegistry(args.registry) : null;
+
   const rl = interactive ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
   try {
     let name = nameArg;
@@ -160,17 +219,34 @@ async function main() {
 
     if (interactive) {
       console.log("yarch web 工程生成器（@yarch/create-admin）\n");
-      if (!name) name = await askText(rl, "工程名（= npm 包名 = registry 服务名）", { validate: validateName });
-      else if (validateName(name)) fatal(validateName(name));
+      if (micro === undefined) {
+        const kindIdx = await askSelect(
+          rl,
+          "工程形态（micro-frontend.md 一：单应用不受微前端规约约束；基座全局唯一、子应用双运行形态）",
+          [
+            "单应用 admin（默认，npm create @yarch/admin 常规形态）",
+            "微前端基座 base（--micro base）",
+            "微前端子应用 sub（--micro sub）",
+          ],
+          0,
+        );
+        micro = kindIdx === 0 ? undefined : kindIdx === 1 ? "base" : "sub";
+      }
+      const validator = micro ? (v) => validateMicroName(v, registry) : validateName;
+      const nameLabel = micro
+        ? "应用名（= 路由前缀 = storage/事件前缀，二-2 一名三用；首段=已登记服务名）"
+        : "工程名（= npm 包名 = registry 服务名）";
+      if (!name) name = await askText(rl, nameLabel, { validate: validator });
+      else if (validator(name)) fatal(validator(name));
       if (!description) {
         description = await askText(rl, "工程描述", {
-          fallback: `${name}：基于 yarch web 脚手架生成的中后台工程`,
+          fallback: `${name}：基于 yarch web 脚手架生成的${micro ? (micro === "base" ? "微前端基座" : "微前端子应用") : "中后台"}工程`,
           validate: (v) => (v.includes('"') || v.includes("\\") ? "不得包含双引号与反斜杠（要写进 package.json）" : null),
         });
       }
       if (!port) {
         port = await askText(rl, "dev 端口", {
-          fallback: "5173",
+          fallback: micro === "sub" ? "5174" : "5173",
           validate: (v) => (/^\d{4,5}$/.test(v) && Number(v) >= 1024 && Number(v) <= 65535 ? null : "1024~65535 的数字端口号"),
         });
       }
@@ -184,10 +260,10 @@ async function main() {
     }
 
     if (!name) fatal(`工程名缺失。\n${usage()}`);
-    const nameErr = validateName(name);
+    const nameErr = micro ? validateMicroName(name, registry) : validateName(name);
     if (nameErr) fatal(`工程名 ${JSON.stringify(name)} ${nameErr}`);
-    description ??= `${name}：基于 yarch web 脚手架生成的中后台工程`;
-    port ??= "5173";
+    description ??= `${name}：基于 yarch web 脚手架生成的${micro ? (micro === "base" ? "微前端基座" : "微前端子应用") : "中后台"}工程`;
+    port ??= micro === "sub" ? "5174" : "5173";
     proxyTarget ??= "http://localhost:8080";
     group ??= "";
     if (!/^\d{4,5}$/.test(port) || Number(port) < 1024 || Number(port) > 65535) {
@@ -197,14 +273,24 @@ async function main() {
       fatal(`代理目标 ${proxyTarget} 无效：须为 http(s):// 开头`);
     }
 
-    // @yarch 底座依赖形态（W8）：version = ^0.1.0（标准形态，@yarch/contract、@yarch/react 已发 npm）；
+    // @yarch 底座依赖形态（W8）：version = 版本依赖（标准形态，@yarch/contract、@yarch/react 已发 npm）；
     // file: 绝对路径 = golang replace 行对偶（发版前本地过渡，yarch 源码变更后重跑 pnpm install 刷新）。
     const depsMode = args.deps === "file" ? "file" : "version";
-    const yarchContractDep =
-      depsMode === "version" ? "^0.1.0" : `file:${resolve(PKG_ROOT, "../contract")}`;
-    const yarchReactDep = depsMode === "version" ? "^0.1.0" : `file:${resolve(PKG_ROOT, "../react")}`;
+    const yarchContractDep = depsMode === "version" ? YARCH_VERSION : `file:${resolve(PKG_ROOT, "../contract")}`;
+    const yarchReactDep = depsMode === "version" ? YARCH_VERSION : `file:${resolve(PKG_ROOT, "../react")}`;
+    const yarchProReactDep = depsMode === "version" ? YARCH_PRO_REACT_VERSION : `file:${resolve(PKG_ROOT, "../pro-react")}`;
 
-    const vars = { packageName: name, appName: name, description, port, proxyTarget, yarchContractDep, yarchReactDep };
+    const vars = {
+      packageName: name,
+      appName: name,
+      service: name.split("-")[0],
+      description,
+      port,
+      proxyTarget,
+      yarchContractDep,
+      yarchReactDep,
+      yarchProReactDep,
+    };
 
     const outDir = resolve(args.out || (args._.length > 0 ? args._[args._.length - 1] : name));
     let existing;
@@ -215,7 +301,9 @@ async function main() {
     }
     if (existing && existing.length > 0) fatal(`输出目录 ${outDir} 非空`);
 
-    const templateDir = resolve(args.src || join(PKG_ROOT, "templates", `admin-${ui}`));
+    const templateDir = resolve(
+      args.src || join(PKG_ROOT, "templates", micro ? `${micro}-semi` : `admin-${ui}`),
+    );
     try {
       readFileSync(join(templateDir, "archetype.json"));
     } catch {
@@ -230,12 +318,19 @@ async function main() {
 
     const tierDesc = JSON.parse(readFileSync(join(templateDir, "archetype.json"), "utf8")).description;
     const groupHint = group ? `（属主建议：${group}/${name}）` : "";
-    console.log(`✅ 已生成 ${outDir}（${n} 个文件，admin-${ui} 档）—— ${tierDesc}
+    const tierLabel = micro ? `${micro}-semi 档` : `admin-${ui} 档`;
+    const registryHint = micro
+      ? `2. 应用名已置为 ${JSON.stringify(name)}——去 yarch 仓 contract/registry.md 四节前端应用名登记表登记${groupHint}
+  3. ${micro === "base"
+        ? "基座：micro-apps.config.ts 是子应用入口登记表（十二-2，git 纳管）；子应用接入只改此表"
+        : "子应用：在基座仓 micro-apps.config.ts 登记入口（十二-2）；pnpm dev 独立运行 / pnpm dev:micro 被基座加载（十一）"}`
+      : `2. 服务名已置为 ${JSON.stringify(name)}——去 yarch 仓 contract/registry.md 登记表登记${groupHint}`;
+    console.log(`✅ 已生成 ${outDir}（${n} 个文件，${tierLabel}）—— ${tierDesc}
 
 下一步：
   1. cd ${outDir} && pnpm install && pnpm dev        # http://localhost:${port}
-  2. 服务名已置为 ${JSON.stringify(name)}——去 yarch 仓 contract/registry.md 登记表登记${groupHint}
-  3. @yarch 底座为 ${depsMode === "version" ? "^0.1.0 版本依赖（升级 = pnpm update @yarch/contract @yarch/react）" : "file: 本地依赖（发版前过渡；正式发版后改用默认 version 形态重新生成或手动替换）"}
+${registryHint}
+  ${micro ? "4" : "3"}. @yarch 底座为 ${depsMode === "version" ? `${YARCH_VERSION} 版本依赖（升级 = pnpm update @yarch/contract @yarch/react）` : "file: 本地依赖（发版前过渡；正式发版后改用默认 version 形态重新生成或手动替换）"}
 `);
   } finally {
     if (rl) rl.close();

package/bin/gen-registry-snapshot.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// 从 contract/registry.md 生成包内快照 bin/registry-snapshot.json（发版前跑；npm 消费方无仓可读，
+// 快照是 --registry 未传时的核对来源）。CI/内网可随时用 --registry 指最新 registry.md 覆盖快照。
+//
+// 用法：node bin/gen-registry-snapshot.mjs [yarch 仓根目录]（默认向上定位 ../../../../）
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { parseRegistryMd } from "./registry.mjs";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(process.argv[2] ?? join(PKG_ROOT, "../../../.."));
+const mdPath = join(repoRoot, "contract", "registry.md");
+
+let md;
+try {
+  md = readFileSync(mdPath, "utf8");
+} catch {
+  console.error(`gen-registry-snapshot: 读不到 ${mdPath}（传 yarch 仓根目录作为参数）`);
+  process.exit(1);
+}
+
+const { serviceNames, appNames } = parseRegistryMd(md);
+const snapshot = {
+  source: "contract/registry.md",
+  generatedAt: new Date().toISOString(),
+  serviceNames: [...serviceNames].sort(),
+  appNames: [...appNames].sort(),
+};
+const out = join(PKG_ROOT, "bin", "registry-snapshot.json");
+writeFileSync(out, `${JSON.stringify(snapshot, null, 2)}\n`);
+console.log(`✅ ${out}：服务名 ${snapshot.serviceNames.length} 个，应用名 ${snapshot.appNames.length} 个`);

package/bin/registry-snapshot.json

@@ -0,0 +1,15 @@
+{
+  "source": "contract/registry.md",
+  "generatedAt": "2026-09-18T06:28:35.369Z",
+  "serviceNames": [
+    "yagent",
+    "ybookreading",
+    "ycomp",
+    "ysaas"
+  ],
+  "appNames": [
+    "ycomp-console",
+    "ysaas-billing",
+    "ysaas-console"
+  ]
+}

package/bin/registry.mjs

@@ -0,0 +1,19 @@
+// registry.md 解析（共享模块：create-admin 校验 与 gen-registry-snapshot 快照生成 同源，防漂移）。
+// 解析 contract/registry.md：二节服务名登记表 + 四节前端应用名登记表（首列反引号包裹的行）。
+export function parseRegistryMd(md) {
+  const serviceNames = new Set();
+  const appNames = new Set();
+  let section = "";
+  for (const line of md.split("\n")) {
+    const heading = line.match(/^##\s+(一|二|三|四|五|六|七|八|九|十)、/);
+    if (heading) {
+      section = heading[1];
+      continue;
+    }
+    const cell = line.match(/^\|\s*`([a-z][a-z0-9-]{1,31})`\s*\|/);
+    if (!cell) continue;
+    if (section === "二") serviceNames.add(cell[1]);
+    else if (section === "四") appNames.add(cell[1]);
+  }
+  return { serviceNames, appNames };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarch/create-admin",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "yarch web 工程生成器：交互问答 + archetype 全量渲染（maven-archetype/cookiecutter 模式，golang cmd/yarch-init 的 web 对偶）",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "README.md"
   ],
   "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/yuandonghao/yarch.git", "directory": "stacks/web/packages/create" },
+  "repository": { "type": "git", "url": "git+https://github.com/ydonghao/yarch.git", "directory": "stacks/web/packages/create" },
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20"

package/templates/admin-antd/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — {{packageName}} 工程守则
+
+> 本工程由 yarch 脚手架生成，基于跨栈统一契约（yarch 仓 `contract/`，全部 v1.0 定稿）。
+> 任何 AI 编码代理改码前先读本文件；条文与直觉冲突时以本文件为准，红线改动直接拒绝——机检与 CR 均按此执行。
+
+## 契约红线（违反 = 机检失败 / CR 必拒）
+
+| 红线 | 规则 | 出处 |
+|---|---|---|
+| 统一信封 | 响应一律 `{code, message, data, traceId}` 四字段，`code === 0` 即成功；判错只看 `code`，HTTP 状态码不承载业务语义 | contract/api/rest-response.md |
+| 错误码 | 只用 `@yarch/contract` 的 `errorCodes` 常量（1xxx 通用 / 2xxx 认证）；新业务码在业务仓登记 3xxx+ 段位；**禁裸数字错误码** | contract/api/error-codes.md |
+| HTTP 封装 | 业务请求只经 `createClient` 产出的客户端（信封解包 / traceId 透传 / 401 跳登录已内置）；**禁裸 fetch/axios 直连业务接口** | 参考 `src/features/*/api.ts` 现状 |
+| 分层方向 | `pages/` 只组合 `features/`（禁直调 `features/*/api.ts`，取数经 hooks）；`ui/`·`components/` 禁反向依赖 `features/`·`pages/` | yarch depcruise 同款规则 |
+| traceId | 排查链路键即 `traceId`（W3C traceparent）；响应头/信封里的 traceId 禁丢弃，报障必附 | contract/api/logging-trace.md |
+| 命名 | 文件/目录 kebab-case；工程名即服务名（小写短横线，禁裸通用词），改名 = registry 变更评审 | contract/registry.md 一 |
+| 底座升级 | `@yarch/contract`·`@yarch/react` 一律 `pnpm update` 跟进版本；**禁 patch / 改 node_modules / 拷贝源码内联** | — |
+
+## 验证（改完必跑，全绿才算完成）
+
+```bash
+pnpm build       # tsc --noEmit + vite build——生成工程的机检底线
+```
+
+平台侧还有契约断言测试与依赖方向机检（depcruise）；本工程若引入 CI，建议把两者加进来后再放开依赖方向的约束。
+
+## 登记与升级
+
+- 服务名 / 错误码段位 / 前端应用名登记：yarch 仓 `contract/registry.md`（PR 即登记）；
+- 底座新版本：`pnpm update @yarch/contract @yarch/react`，只改 version 一行。
+
+## 完成定义（DoD）
+
+tsc 零错 · build 通过 · 新增接口全走统一信封与错误码常量 · 新增取数落在 features 层。

package/templates/admin-antd/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/admin-antd/GEMINI.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/admin-antd/archetype.json

@@ -1,12 +1,53 @@
 {
   "description": "yarch 中后台工程模板 · antd 档（蚂蚁系）：Vite + React 19 + react-router 7 + @yarch 契约底座",
   "variables": [
-    { "name": "packageName", "desc": "工程名（= npm 包名 = registry.md 服务名，一-1 校验）", "required": true, "default": "" },
-    { "name": "appName", "desc": "展示名（index.html 标题）", "required": false, "default": "= packageName" },
-    { "name": "description", "desc": "工程描述（package.json）", "required": false, "default": "" },
-    { "name": "port", "desc": "vite dev 端口", "required": false, "default": "5173" },
-    { "name": "proxyTarget", "desc": "/api/v1 反向代理目标", "required": false, "default": "http://localhost:8080" },
-    { "name": "yarchContractDep", "desc": "@yarch/contract 依赖（发版前 file: 本地路径，发版后 ^x.y.z）", "required": false, "default": "" },
-    { "name": "yarchReactDep", "desc": "@yarch/react 依赖（同上）", "required": false, "default": "" }
+    {
+      "name": "packageName",
+      "desc": "工程名（= npm 包名 = registry.md 服务名，一-1 校验）",
+      "required": true,
+      "default": ""
+    },
+    {
+      "name": "appName",
+      "desc": "展示名（index.html 标题）",
+      "required": false,
+      "default": "= packageName"
+    },
+    {
+      "name": "description",
+      "desc": "工程描述（package.json）",
+      "required": false,
+      "default": ""
+    },
+    {
+      "name": "port",
+      "desc": "vite dev 端口",
+      "required": false,
+      "default": "5173"
+    },
+    {
+      "name": "proxyTarget",
+      "desc": "/api/v1 反向代理目标",
+      "required": false,
+      "default": "http://localhost:8080"
+    },
+    {
+      "name": "yarchContractDep",
+      "desc": "@yarch/contract 依赖（发版前 file: 本地路径，发版后 ^x.y.z）",
+      "required": false,
+      "default": ""
+    },
+    {
+      "name": "yarchReactDep",
+      "desc": "@yarch/react 依赖（同上）",
+      "required": false,
+      "default": ""
+    },
+    {
+      "name": "yarchProReactDep",
+      "desc": "@yarch/pro-react 依赖（CL5 antd 档预装；发版前 file: 本地路径）",
+      "required": false,
+      "default": ""
+    }
   ]
 }

package/templates/admin-antd/package.json

@@ -14,6 +14,7 @@
     "react-router-dom": "^7",
     "@yarch/contract": "{{yarchContractDep}}",
     "@yarch/react": "{{yarchReactDep}}",
+    "@yarch/pro-react": "{{yarchProReactDep}}",
     "antd": "^5"
   },
   "devDependencies": {

package/templates/admin-arco/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — {{packageName}} 工程守则
+
+> 本工程由 yarch 脚手架生成，基于跨栈统一契约（yarch 仓 `contract/`，全部 v1.0 定稿）。
+> 任何 AI 编码代理改码前先读本文件；条文与直觉冲突时以本文件为准，红线改动直接拒绝——机检与 CR 均按此执行。
+
+## 契约红线（违反 = 机检失败 / CR 必拒）
+
+| 红线 | 规则 | 出处 |
+|---|---|---|
+| 统一信封 | 响应一律 `{code, message, data, traceId}` 四字段，`code === 0` 即成功；判错只看 `code`，HTTP 状态码不承载业务语义 | contract/api/rest-response.md |
+| 错误码 | 只用 `@yarch/contract` 的 `errorCodes` 常量（1xxx 通用 / 2xxx 认证）；新业务码在业务仓登记 3xxx+ 段位；**禁裸数字错误码** | contract/api/error-codes.md |
+| HTTP 封装 | 业务请求只经 `createClient` 产出的客户端（信封解包 / traceId 透传 / 401 跳登录已内置）；**禁裸 fetch/axios 直连业务接口** | 参考 `src/features/*/api.ts` 现状 |
+| 分层方向 | `pages/` 只组合 `features/`（禁直调 `features/*/api.ts`，取数经 hooks）；`ui/`·`components/` 禁反向依赖 `features/`·`pages/` | yarch depcruise 同款规则 |
+| traceId | 排查链路键即 `traceId`（W3C traceparent）；响应头/信封里的 traceId 禁丢弃，报障必附 | contract/api/logging-trace.md |
+| 命名 | 文件/目录 kebab-case；工程名即服务名（小写短横线，禁裸通用词），改名 = registry 变更评审 | contract/registry.md 一 |
+| 底座升级 | `@yarch/contract`·`@yarch/react` 一律 `pnpm update` 跟进版本；**禁 patch / 改 node_modules / 拷贝源码内联** | — |
+
+## 验证（改完必跑，全绿才算完成）
+
+```bash
+pnpm build       # tsc --noEmit + vite build——生成工程的机检底线
+```
+
+平台侧还有契约断言测试与依赖方向机检（depcruise）；本工程若引入 CI，建议把两者加进来后再放开依赖方向的约束。
+
+## 登记与升级
+
+- 服务名 / 错误码段位 / 前端应用名登记：yarch 仓 `contract/registry.md`（PR 即登记）；
+- 底座新版本：`pnpm update @yarch/contract @yarch/react`，只改 version 一行。
+
+## 完成定义（DoD）
+
+tsc 零错 · build 通过 · 新增接口全走统一信封与错误码常量 · 新增取数落在 features 层。

package/templates/admin-arco/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/admin-arco/GEMINI.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/admin-semi/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — {{packageName}} 工程守则
+
+> 本工程由 yarch 脚手架生成，基于跨栈统一契约（yarch 仓 `contract/`，全部 v1.0 定稿）。
+> 任何 AI 编码代理改码前先读本文件；条文与直觉冲突时以本文件为准，红线改动直接拒绝——机检与 CR 均按此执行。
+
+## 契约红线（违反 = 机检失败 / CR 必拒）
+
+| 红线 | 规则 | 出处 |
+|---|---|---|
+| 统一信封 | 响应一律 `{code, message, data, traceId}` 四字段，`code === 0` 即成功；判错只看 `code`，HTTP 状态码不承载业务语义 | contract/api/rest-response.md |
+| 错误码 | 只用 `@yarch/contract` 的 `errorCodes` 常量（1xxx 通用 / 2xxx 认证）；新业务码在业务仓登记 3xxx+ 段位；**禁裸数字错误码** | contract/api/error-codes.md |
+| HTTP 封装 | 业务请求只经 `createClient` 产出的客户端（信封解包 / traceId 透传 / 401 跳登录已内置）；**禁裸 fetch/axios 直连业务接口** | 参考 `src/features/*/api.ts` 现状 |
+| 分层方向 | `pages/` 只组合 `features/`（禁直调 `features/*/api.ts`，取数经 hooks）；`ui/`·`components/` 禁反向依赖 `features/`·`pages/` | yarch depcruise 同款规则 |
+| traceId | 排查链路键即 `traceId`（W3C traceparent）；响应头/信封里的 traceId 禁丢弃，报障必附 | contract/api/logging-trace.md |
+| 命名 | 文件/目录 kebab-case；工程名即服务名（小写短横线，禁裸通用词），改名 = registry 变更评审 | contract/registry.md 一 |
+| 底座升级 | `@yarch/contract`·`@yarch/react` 一律 `pnpm update` 跟进版本；**禁 patch / 改 node_modules / 拷贝源码内联** | — |
+
+## 验证（改完必跑，全绿才算完成）
+
+```bash
+pnpm build       # tsc --noEmit + vite build——生成工程的机检底线
+```
+
+平台侧还有契约断言测试与依赖方向机检（depcruise）；本工程若引入 CI，建议把两者加进来后再放开依赖方向的约束。
+
+## 登记与升级
+
+- 服务名 / 错误码段位 / 前端应用名登记：yarch 仓 `contract/registry.md`（PR 即登记）；
+- 底座新版本：`pnpm update @yarch/contract @yarch/react`，只改 version 一行。
+
+## 完成定义（DoD）
+
+tsc 零错 · build 通过 · 新增接口全走统一信封与错误码常量 · 新增取数落在 features 层。