@yarch/create-admin 0.1.0 → 0.2.1

package/templates/admin-semi/CLAUDE.md

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

package/templates/admin-semi/GEMINI.md

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

package/templates/base-semi/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md — {{packageName}}（微前端基座）工程守则
+
+> 本工程由 yarch 脚手架生成（`--micro base`），基于跨栈统一契约（yarch 仓 `contract/`）与微前端规约 `contract/web/micro-frontend.md`。
+> 任何 AI 编码代理改码前先读本文件；条文与直觉冲突时以本文件为准，红线改动直接拒绝——机检与 CR 均按此执行。
+
+## 基座五权（只归基座，条文 micro-frontend.md 一-1）
+
+登录态唯一持有（十-1）· 导航端口唯一注册（十-2）· 菜单与路由分发（三-4）· 主题下发（六-1）· 错误兜底（四-5）。子应用索要任何一项 = 架构违规。
+
+## 契约红线（违反 = 机检失败 / CR 必拒）
+
+| 红线 | 规则 | 出处 |
+|---|---|---|
+| manifest 装配 | 子应用接入/下线**只改 `src/app/micro-apps.config.ts` 登记表**（entry/version/routePrefix/menu）；禁在任何组件里硬编码子应用路由或菜单 | 十二-2 / 三-4 |
+| 登记先行 | 新子应用应用名须先在 yarch 仓 `contract/registry.md` 四节登记（两段式、首段=已登记服务名、全局不重名），再入本工程登记表 | registry.md 四 |
+| 共享运行时 | `src/micro/shared.ts` 注册 `__YARCH_REACT__ / __YARCH_CONTRACT__ / __YARCH_SUPPLY__` 后才能启动载器；新增共享成员须同步子应用供给层口径 | 八-1 / 八-2 |
+| 事件订阅宿主 | 子应用事件（`{应用名}:{动词-名词}`）的订阅挂**常驻布局壳**（`layouts/basic-layout.tsx`），不挂会随路由卸载的页面；订阅与退订成对 | 九-1 / 七-4 |
+| 统一信封 / 错误码 / traceId | 同单应用档：判错只看 `code`，错误码只用常量，报障必附 traceId | contract/api/* |
+| 底座升级 | `@yarch/contract`·`@yarch/react`·`@micro-zoe/micro-app` 一律 `pnpm update`；禁 patch / 内联拷贝 | — |
+
+## 验证（改完必跑）
+
+```bash
+pnpm build       # tsc --noEmit + vite build
+pnpm build:micro 同款子应用联调：入口 URL 经 VITE_SUB_*_URL 注入，禁改死代码
+```
+
+## 完成定义（DoD）
+
+tsc 零错 · build 通过 · 新子应用接入只动了登记表 · 基座在子应用全部下线后仍可独立运行（三-1）。

package/templates/base-semi/CLAUDE.md

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

package/templates/base-semi/GEMINI.md

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

package/templates/base-semi/README.md

@@ -0,0 +1,35 @@
+# {{appName}} · 微前端基座
+
+> {{description}}。规约依据：[contract/web/micro-frontend.md](https://github.com/ydonghao/yarch/blob/main/contract/web/micro-frontend.md) v1.0；
+> 载器 micro-app（contract/README.md 关键架构决策登记表默认档，观察哨：停更切 qiankun）。
+
+## 五权归基座（三-2/十-1/十-2）
+
+登录态与 token、菜单/路由分发、主题与 UI 档定义、全局错误兜底、布局外壳——全部在本工程；
+子应用经 `__YARCH_SUPPLY__`（props 下行，五-5）与共享 contract 单例（八-1）取用，禁子应用自建。
+
+## 开发
+
+```bash
+pnpm install && pnpm dev            # http://localhost:{{port}}
+```
+
+## 子应用接入三步（十二-2：入口变更只改 manifest）
+
+1. 生成子应用：`npm create @yarch/admin ysaas-billing -- --micro sub --registry <contract/registry.md>`
+2. 在 `src/app/micro-apps.config.ts` 登记入口/路由前缀/菜单元数据（跨环境入口用 `.env.local` 覆盖，十二-7）
+3. 子应用侧起 `pnpm dev:micro`（集成模式 dev server，本基座即可加载）
+
+## 双模式冒烟（十一-3，CI 口径）
+
+- 子应用独立：`pnpm build`（自足产物）
+- 子应用集成：`pnpm build:micro`（框架/contract 经 window 全局 shim，产物体积消失——八-1/八-2 机检对象）
+
+## 部署（十二-3/十二-4）
+
+构建产物内容寻址（hash 文件名）；nginx 一应用一 root + `try_files` 兜底——样例见 `conf/nginx.conf.example`。
+
+## 登记提醒
+
+应用名 `{{packageName}}`（首段服务名 `{{service}}`）须在 yarch 仓 `contract/registry.md` 四节前端应用名登记表登记（二-1/二-4）；
+storage key / 事件名 / 路由前缀均以应用名为前缀（二-2 一名三用）。

package/templates/base-semi/archetype.json

@@ -0,0 +1,13 @@
+{
+  "description": "yarch 微前端基座模板 · Semi 档：micro-app 载器（默认档）+ manifest 声明式装配 + 登录态/导航/主题/错误兜底五权归基座",
+  "variables": [
+    { "name": "packageName", "desc": "应用名（= npm 包名 = 路由前缀 = storage/事件前缀，micro-frontend.md 二-1/二-2）", "required": true, "default": "" },
+    { "name": "appName", "desc": "展示名（index.html 标题）", "required": false, "default": "= packageName" },
+    { "name": "service", "desc": "首段服务名（registry.md 已登记，二-1）", "required": false, "default": "" },
+    { "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": "" }
+  ]
+}

package/templates/base-semi/conf/nginx.conf.example

@@ -0,0 +1,19 @@
+# 静态托管样例（micro-frontend.md 十二-3/十二-4，对齐 contract/infra/nginx.md 一-2 配置纪律）：
+# 构建产物内容寻址（hash 文件名）且旧版本保留——回滚 = 基座 manifest 指针回拨，不重发构建；
+# 一应用一 root，try_files 兜底 history 路由 404。
+server {
+  listen 80;
+  server_name console.example.com;
+
+  # 基座（本工程产物）
+  location /ysaas-console/ {
+    alias /data/www/ysaas-console/;
+    try_files $uri $uri/ /ysaas-console/index.html;
+  }
+
+  # 子应用（独立发版、独立回滚，十二-1；入口 URL 登记在基座 micro-apps.config.ts）
+  location /ysaas-billing/ {
+    alias /data/www/ysaas-billing/;
+    try_files $uri $uri/ /ysaas-billing/index.html;
+  }
+}

package/templates/base-semi/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8"/>
+<title>{{appName}}</title>
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

package/templates/base-semi/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "{{description}}",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "react-router": "^7",
+    "react-router-dom": "^7",
+    "@yarch/contract": "{{yarchContractDep}}",
+    "@yarch/react": "{{yarchReactDep}}",
+    "@douyinfe/semi-ui": "^2",
+    "@micro-zoe/micro-app": "^1.0.0-rc.32"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4",
+    "typescript": "^5.6",
+    "vite": "^6"
+  }
+}

package/templates/base-semi/src/app/micro-apps.config.ts

@@ -0,0 +1,16 @@
+/**
+ * 子应用入口登记表（十二-2 manifest，git 声明式纳管）：应用名 → 入口/版本/路由前缀/菜单元数据。
+ * 子应用接入只改此表；跨环境入口 URL 由环境配置注入（十二-7，.env.local 覆盖），禁硬编码。
+ */
+import type { MicroAppsConfig } from "@yarch/contract";
+import { subAppRoutePrefix } from "@yarch/contract";
+
+export const microApps: MicroAppsConfig = [
+  {
+    name: "ysaas-billing",
+    entry: import.meta.env.VITE_SUB_BILLING_URL ?? "http://127.0.0.1:5174/ysaas-billing/",
+    version: "0.1.0",
+    routePrefix: subAppRoutePrefix("ysaas-billing"),
+    menu: [{ key: "ysaas-billing:invoices", path: "/invoices", title: "账单" }],
+  },
+];

package/templates/base-semi/src/app/router.tsx

@@ -0,0 +1,44 @@
+/**
+ * 基座路由：登录页 + 布局壳（基座自有页面 + 子应用前缀分发 + 404 兜底，四-5）。
+ * 子应用路由由 manifest 声明式装配（三-4：基座禁硬编码子应用内部路由）。
+ */
+import { Navigate, Routes, Route, useNavigate } from "react-router-dom";
+import { useEffect, type ReactNode } from "react";
+import { setupReactNavigator } from "@yarch/react";
+import BasicLayout from "../layouts/basic-layout";
+import Dashboard from "../pages/dashboard";
+import Login from "../pages/login";
+import NotFound from "../pages/not-found";
+import SubAppView from "../micro/sub-app";
+import { microApps } from "./micro-apps.config";
+import { authStore } from "../stores/auth";
+
+function NavigatorSetup() {
+  const navigate = useNavigate();
+  useEffect(() => { setupReactNavigator(navigate); }, [navigate]);
+  return null;
+}
+
+/** 登录门禁（十-1 登录态唯一归基座）：未持 token 一律回登录页 */
+function AuthGate({ children }: { children: ReactNode }) {
+  if (!authStore.token) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+
+export default function App() {
+  return (
+    <>
+      <NavigatorSetup />
+      <Routes>
+        <Route path="/login" element={<Login />} />
+        <Route path="/" element={<AuthGate><BasicLayout /></AuthGate>}>
+          <Route index element={<Dashboard />} />
+          {microApps.map((reg) => (
+            <Route key={reg.name} path={`${reg.routePrefix}/*`} element={<SubAppView appName={reg.name} />} />
+          ))}
+          <Route path="*" element={<NotFound />} />
+        </Route>
+      </Routes>
+    </>
+  );
+}

package/templates/base-semi/src/layouts/basic-layout.tsx

@@ -0,0 +1,51 @@
+/**
+ * 基座布局与外壳（三-2）：菜单/导航树 = 基座自有项 + manifest 声明式装配的子应用项（三-4）。
+ * 主题与 UI 档在此定义并下发（三-2/六-1/六-5）。
+ */
+import { useEffect } from "react";
+import { Layout, Nav, Toast } from "@douyinfe/semi-ui";
+import { Outlet, useLocation, useNavigate } from "react-router-dom";
+import { getAppEventBus } from "@yarch/contract";
+import { microApps } from "../app/micro-apps.config";
+
+export default function BasicLayout() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { Sider, Header, Content } = Layout;
+
+  // 事件上行订阅挂常驻布局壳（九-1/九-3）：路由切换不卸载，子应用事件随时可达（七-4 订阅与移除成对）
+  useEffect(() => {
+    const offList = microApps.map((reg) =>
+      getAppEventBus().on(`${reg.name}:export-done`, (payload) => {
+        Toast.success(`${reg.name} 事件上行：export-done ${JSON.stringify(payload)}`);
+      }),
+    );
+    return () => offList.forEach((off) => off());
+  }, []);
+
+  const items = [
+    { itemKey: "/", text: "首页" },
+    ...microApps.flatMap((reg) =>
+      reg.menu.map((m) => ({ itemKey: `${reg.routePrefix}${m.path}`, text: m.title })),
+    ),
+  ];
+
+  return (
+    <Layout style={{ minHeight: "100vh" }}>
+      <Sider>
+        <Nav
+          selectedKeys={[location.pathname]}
+          header={{ text: "{{appName}}" }}
+          items={items}
+          onSelect={(data) => navigate(String(data.itemKey))}
+        />
+      </Sider>
+      <Layout>
+        <Header style={{ background: "#fff", padding: "0 24px" }} />
+        <Content style={{ padding: 24 }}>
+          <Outlet />
+        </Content>
+      </Layout>
+    </Layout>
+  );
+}

package/templates/base-semi/src/main.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { createRoot } from "react-dom/client";
+import { semiGlobal } from "@douyinfe/semi-ui";
+// React 19 下 Semi 命令式渲染（Toast/Notification 等）须显式注入 createRoot，否则弹层静默不渲染
+semiGlobal.config.createRoot = createRoot;
+import { BrowserRouter } from "react-router-dom";
+import microApp from "@micro-zoe/micro-app";
+import App from "./app/router";
+import { registerSharedRuntimes } from "./micro/shared";
+
+// 基座先行注册共享运行时（八-1/八-2），再启动载器——子应用集成构建依赖 window 全局
+registerSharedRuntimes();
+microApp.start();
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </React.StrictMode>
+);

package/templates/base-semi/src/micro/shared.ts

@@ -0,0 +1,43 @@
+/**
+ * 共享运行时注册（八-1/八-2）：整个微前端体系只允许一份 @yarch/contract 与框架运行时，
+ * 由基座注册到 window 全局；子应用集成构建（--mode integrated）经同名 shim 取用，
+ * 产物中框架与 contract 体积消失（十三表八-1/八-2 机检的运行时基础）。
+ */
+import * as contract from "@yarch/contract";
+import * as react from "react";
+import * as reactDom from "react-dom";
+import * as reactDomClient from "react-dom/client";
+import * as reactJsxRuntime from "react/jsx-runtime";
+import * as reactJsxDevRuntime from "react/jsx-dev-runtime";
+import * as reactRouter from "react-router";
+import * as reactRouterDom from "react-router-dom";
+import type { SubAppUser } from "@yarch/contract";
+import { authStore } from "../stores/auth";
+import { themeToken } from "../ui/theme";
+
+export const SHARED_REACT_KEY = "__YARCH_REACT__";
+export const SUPPLY_KEY = "__YARCH_SUPPLY__";
+
+export function registerSharedRuntimes(): void {
+  const g = globalThis as Record<string, unknown>;
+  g[SHARED_REACT_KEY] = {
+    "react": react,
+    "react-dom": reactDom,
+    "react-dom/client": reactDomClient,
+    "react/jsx-runtime": reactJsxRuntime,
+    "react/jsx-dev-runtime": reactJsxDevRuntime,
+    "react-router": reactRouter,
+    "react-router-dom": reactRouterDom,
+  };
+  // 八-1：contract 单例标记（子应用 shim 与 e2e instanceof 断言的取用点）
+  contract.setSharedContract(contract);
+
+  // props 下行供给（五-5 最小集；getter 保证子应用每次取值都是最新登录态，十-1 token 只归基座）
+  g[SUPPLY_KEY] = {
+    getToken: (): string | null => authStore.token || null,
+    get user(): SubAppUser | null {
+      return authStore.token ? { id: "demo", name: "演示用户" } : null;
+    },
+    themeToken,
+  };
+}

package/templates/base-semi/src/micro/sub-app.tsx

@@ -0,0 +1,65 @@
+/**
+ * <micro-app> 基座侧封装：loading 骨架（五-2：mount 完成前 UI 态由基座持有）+
+ * 加载失败页含重试入口（四-5：禁白屏）。子应用路由前缀分发在 router.tsx 由 manifest 装配（三-4）。
+ */
+import { useEffect, useRef, useState } from "react";
+import { Button, Spin, Typography } from "@douyinfe/semi-ui";
+import { microApps } from "../app/micro-apps.config";
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "micro-app": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        name: string;
+        url: string;
+      };
+    }
+  }
+}
+
+export default function SubAppView({ appName }: { appName: string }) {
+  const reg = microApps.find((r) => r.name === appName);
+  const hostRef = useRef<HTMLElement | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [failed, setFailed] = useState(false);
+  const [retry, setRetry] = useState(0);
+
+  useEffect(() => {
+    const el = hostRef.current;
+    if (!el || !reg) return;
+    // 自定义元素事件经 addEventListener（成对移除，七-4）
+    const onMounted = () => { setLoading(false); setFailed(false); };
+    const onError = () => { setLoading(false); setFailed(true); };
+    el.addEventListener("mounted", onMounted);
+    el.addEventListener("error", onError);
+    return () => {
+      el.removeEventListener("mounted", onMounted);
+      el.removeEventListener("error", onError);
+    };
+  }, [reg, retry]);
+
+  if (!reg) {
+    return <Typography.Text type="danger">未登记的子应用：{appName}（见 micro-apps.config.ts，十二-2）</Typography.Text>;
+  }
+
+  return (
+    <div data-sub-app={reg.name}>
+      {loading && <Spin size="large" style={{ display: "flex", justifyContent: "center", padding: 48 }} />}
+      {failed && (
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 12, padding: 48 }}>
+          <Typography.Text type="danger">子应用 {reg.name} 加载失败（入口 {reg.entry}）</Typography.Text>
+          <Button theme="solid" type="warning" onClick={() => { setLoading(true); setRetry((n) => n + 1); }}>
+            重试
+          </Button>
+        </div>
+      )}
+      <micro-app
+        key={`${reg.name}-${retry}`}
+        ref={(el: HTMLElement | null) => { hostRef.current = el; }}
+        name={reg.name}
+        url={reg.entry}
+        style={{ display: failed ? "none" : "block" }}
+      />
+    </div>
+  );
+}

package/templates/base-semi/src/pages/dashboard.tsx

@@ -0,0 +1,16 @@
+/**
+ * 基座自有首页（三-1：去掉全部子应用后基座仍能运行——登录/菜单框架/404/错误页齐全）。
+ * 事件上行订阅挂常驻布局壳（layouts/basic-layout.tsx）——页面切换不丢订阅。
+ */
+import { Typography } from "@douyinfe/semi-ui";
+import { microApps } from "../app/micro-apps.config";
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h2>基座首页</h2>
+      <p>已登记子应用：{microApps.map((r) => r.name).join("、") || "（无）"}</p>
+      <Typography.Text type="tertiary">菜单由 micro-apps.config.ts 声明式装配（三-4）</Typography.Text>
+    </div>
+  );
+}

package/templates/base-semi/src/pages/login.tsx

@@ -0,0 +1,18 @@
+import { Button } from "@douyinfe/semi-ui";
+import { Navigate, useNavigate } from "react-router-dom";
+import { authStore } from "../stores/auth";
+
+export default function Login() {
+  const navigate = useNavigate();
+  // 已登录访问登录页一律回首页（十-1 登录态唯一归基座——覆盖会话恢复后直达 /login 的场景）
+  if (authStore.token) return <Navigate to="/" replace />;
+  return (
+    <div style={{ display: "flex", justifyContent: "center", alignItems: "center", height: "100vh" }}>
+      <form onSubmit={(e: React.FormEvent) => { e.preventDefault(); authStore.token = "demo"; navigate("/"); }}>
+        <h2>{{appName}} · 登录</h2>
+        <p>演示——真实认证走 yarch-auth JWT；登录态唯一归基座（十-1）</p>
+        <Button theme="solid" type="primary" htmlType="submit" block>登录</Button>
+      </form>
+    </div>
+  );
+}

package/templates/base-semi/src/pages/not-found.tsx

@@ -0,0 +1,13 @@
+import { Button, Typography } from "@douyinfe/semi-ui";
+import { useNavigate } from "react-router-dom";
+
+/** 四-5：未匹配路由兜底 404，禁白屏 */
+export default function NotFound() {
+  const navigate = useNavigate();
+  return (
+    <div style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 12, padding: 48 }}>
+      <Typography.Title heading={3}>404 · 页面不存在</Typography.Title>
+      <Button theme="solid" onClick={() => navigate("/")}>回首页</Button>
+    </div>
+  );
+}

package/templates/base-semi/src/stores/auth.ts

@@ -0,0 +1,13 @@
+/**
+ * 登录态持有与刷新（十-1：token 只由基座持有；二-2/七-3：storage key 带 {应用名}: 前缀）。
+ * 子应用经 __YARCH_SUPPLY__.getToken 取用（五-5 props 下行），禁自行持久化。
+ */
+import { createAppStorage } from "@yarch/contract";
+
+const storage = createAppStorage("{{appName}}");
+
+export const authStore = {
+  get token() { return storage.get<string>("token") ?? ""; },
+  set token(v: string) { storage.set("token", v); },
+  clear() { storage.remove("token"); },
+};

package/templates/base-semi/src/ui/theme.ts

@@ -0,0 +1,7 @@
+/**
+ * 主题 token（六-5：主题从基座下发，子应用禁自带第二套主题定义）——
+ * 经 __YARCH_SUPPLY__.themeToken 下发；semi 主题定制走 semi 官方 DSM 通道，此处登记业务 token。
+ */
+export const themeToken: Record<string, string> = {
+  "brand": "#165DFF",
+};

package/templates/base-semi/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/base-semi/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/base-semi/vite.config.ts

@@ -0,0 +1,17 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "127.0.0.1", // 钉死 IPv4 回环：与默认入口 URL/CI 同口径（vite 默认 localhost 在 macOS 为 ::1 only）
+    port: {{port}},
+    proxy: {
+      // 后端 API 反向代理（对接 yarch java/golang 栈的信封接口）
+      "/api/v1": {
+        target: "{{proxyTarget}}",
+        changeOrigin: true,
+      },
+    },
+  },
+});

package/templates/sub-semi/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — {{packageName}}（微前端子应用）工程守则
+
+> 本工程由 yarch 脚手架生成（`--micro sub`），独立·集成双运行形态（yarch 仓 `contract/web/micro-frontend.md` 十一）。
+> 任何 AI 编码代理改码前先读本文件；条文与直觉冲突时以本文件为准，红线改动直接拒绝——机检与 CR 均按此执行。
+
+## 双模式铁律（条文十一-2）
+
+一切运行期差异**只进 `src/supply/` 供给层**（standalone.ts / integrated.ts），业务代码零分支；`vite --mode integrated` 构建时 react 系与 `@yarch/contract` 由基座 window 全局提供（八-1/八-2），产物 `dist-micro/` 里框架体积必须消失。
+
+## 契约红线（违反 = 机检失败 / CR 必拒）
+
+| 红线 | 规则 | 出处 |
+|---|---|---|
+| 禁载器 | 子应用**禁 import `@micro-zoe/micro-app`**——载器只属基座（depcruise 规则 micro-loader-only-in-base） | 三-2 |
+| 导航注册 | `@yarch/react` 只允许在 `src/supply/` 出现（独立模式注册导航）；业务层禁 import（十-2） | 十-2 |
+| 禁连基座 | 禁 import 基座工程源码——共享只经基座 window 全局与挂载 props（五-5） | 十二-2 |
+| 事件名 | 自定义事件一律 `{应用名}:{动词-名词}`（如 `{{packageName}}:export-done`）；用 `defineAppEvents` 封装，禁裸事件名 | 九-3 |
+| storage key | 一律 `{应用名}:` 前缀（`createAppStorage` 已内置）；**禁裸 key 直写 localStorage**（跨应用覆写事故） | 二-2 / 七-3 |
+| 登录态 | token 只从 `__YARCH_SUPPLY__.getToken` / 供给层取；**禁自行持久化登录态**（唯一归基座） | 十-1 |
+| 路由 | 路由 base = 应用名前缀（供给层注入）；基座 manifest 里声明的每个 menu path 在本工程路由表必须有对应路由 | 四-1 / 四-2 |
+| 卸载清理 | unmount 彻底清理（root.unmount / 定时器 / 监听 / 动态 DOM）；重挂幂等，来回切换不崩不白屏 | 五-2 / 五-3 |
+| 弹层容器 | Modal/Toast 挂本应用容器（六-3）；React 19 下命令式弹层须注入 `semiGlobal.config.createRoot`（入口已预置，勿删） | 六-3 |
+
+## 验证（改完必跑）
+
+```bash
+pnpm build        # 独立模式：tsc --noEmit + vite build
+pnpm build:micro  # 集成模式：产物 dist-micro/（框架体积消失是八-2 的构建口径）
+```
+
+## 完成定义（DoD）
+
+双模式 build 全绿 · 双模式运行可进可出 · 新页面在基座集成档与独立直开档行为一致。

package/templates/sub-semi/CLAUDE.md

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

package/templates/sub-semi/GEMINI.md

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

package/templates/sub-semi/README.md

@@ -0,0 +1,28 @@
+# {{appName}} · 微前端子应用
+
+> {{description}}。规约依据：[contract/web/micro-frontend.md](https://github.com/ydonghao/yarch/blob/main/contract/web/micro-frontend.md) v1.0。
+
+## 双模式（十一）
+
+| 模式 | 命令 | 说明 |
+|---|---|---|
+| 独立运行 | `pnpm dev` / `pnpm build` | 全量自足，浏览器直开 http://localhost:{{port}}/ysaas-billing/…（URL 形态与集成一致，四-1） |
+| 集成运行 | `pnpm dev:micro` / `pnpm build:micro` | 供给层切 `__YARCH_SUPPLY__` 实现；react 系与 @yarch/contract 经 window shim 由基座提供（八-1/八-2）——集成产物 `dist-micro/` 中框架与 contract 体积消失 |
+
+双模式差异全部收敛在 `src/supply/`（十一-2 环境供给层）；业务代码出现 `if (isMicro)` 即设计缺陷。
+
+## 纪律速查（详见规约）
+
+- token 不落本应用（十-1）：`supply.getAccessToken()` 注入 createClient；401 只抛 `ApiError`，跳登录归基座（十-2）。
+- storage/事件一律前缀（二-2/九-3）：`createAppStorage` / `defineAppEvents`（见 `src/events.ts`），禁裸 key、裸事件名。
+- 弹层挂本应用容器（六-3）：`getPopupContainer`（见 `src/ui/popup.ts`）。
+- 全局监听成对移除（七-4/五-2）：卸载清理由供给层 `onUnmount` 统一挂接。
+- UI 档与基座一致（六-1）：semi（本模板档固化）；主题 token 由基座下发（六-5）。
+
+## 接入基座
+
+在基座仓 `src/app/micro-apps.config.ts` 登记本应用（十二-2）：`name: "{{packageName}}"`、入口 URL（跨环境 env 注入，十二-7）、菜单元数据。
+
+## 登记提醒
+
+应用名 `{{packageName}}`（首段服务名 `{{service}}`）须在 yarch 仓 `contract/registry.md` 四节前端应用名登记表登记（二-1/二-4）。

package/templates/sub-semi/archetype.json

@@ -0,0 +1,13 @@
+{
+  "description": "yarch 微前端子应用模板 · Semi 档：独立·集成双模式供给层 + micro-app 生命周期固化 + 前缀 storage/事件 + 框架 peerDeps 不打包",
+  "variables": [
+    { "name": "packageName", "desc": "应用名（= npm 包名 = 路由前缀 = storage/事件前缀，micro-frontend.md 二-1/二-2）", "required": true, "default": "" },
+    { "name": "appName", "desc": "展示名（index.html 标题）", "required": false, "default": "= packageName" },
+    { "name": "service", "desc": "首段服务名（registry.md 已登记，二-1）", "required": false, "default": "" },
+    { "name": "description", "desc": "工程描述（package.json）", "required": false, "default": "" },
+    { "name": "port", "desc": "vite dev 端口", "required": false, "default": "5174" },
+    { "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": "" }
+  ]
+}

package/templates/sub-semi/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8"/>
+<title>{{appName}}</title>
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/src/main.tsx"></script>
+</body>
+</html>