@tbox.cn/app-template-h5 0.1.0

package/.gitignore

@@ -0,0 +1,19 @@
+node_modules
+dist
+dist-ssr
+.vite
+*.tsbuildinfo
+*.local
+.DS_Store
+*.log
+.pnpm-store
+
+# IDE
+.idea
+.vscode
+*.iml
+
+# 环境变量（含密钥，勿提交；用 .env.example 提供模板）
+.env
+.env.*
+!.env.example

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.tbox/app.json

@@ -0,0 +1,4 @@
+{
+  "templateVersion": "0.1.0",
+  "npmModules": []
+}

package/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+template-h5 是面向 AI 生成移动 H5 应用的单 workspace 模板：`apps/client`（React/Vite）+ `apps/server`（Express）。
+
+> **工作区上下文**：仓库内本目录是根 workspace 成员子树，平台引用走 `catalog:`（in-repo 经根 overrides 源码直连 SDK）；`tbox-app create` 从模板源（目录或 pack tgz）展开生成应用，`pnpm-workspace.yaml` 由 `pnpm-workspace.template.yaml` 改名生成。
+
+## 工程结构
+
+| 包 | 职责 |
+|---|---|
+| `apps/client` | React/Vite H5 页面与业务入口（@app/client） |
+| `apps/server` | Express API：健康检查、静态托管、inspector（@app/server） |
+| `scripts/` | 平台生命周期脚本（prepare/dev/start/stop/build 固定名契约）与工程守卫 |
+
+## 常用命令
+
+```sh
+pnpm install
+pnpm dev              # 单进程 localhost:8000（API + 页面 + HMR）
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm verify           # typecheck + test + lint + build + check:inspector
+pnpm check:inspector  # inspector 接线守卫（随 @tbox.cn/app-sdk 分发）
+```
+
+会话开始时，若 `node_modules` 缺失，先跑 `pnpm install`。
+
+## SDK 复用点（优先复用，勿手写）
+
+- `@tbox.cn/app-sdk/client`：`configureRuntime`（API base 注入，勿硬编码 host）、`httpGet/httpPost/createService`（HTTP 客户端）、`ErrorBoundary`、`createLogger`、`installGlobalErrorReporting`
+- `@tbox.cn/app-sdk/server`：`createLogger`
+- `@tbox.cn/app-sdk/platform`：`installInspector` + vite `code-inspect` 插件（页面微调基线，受 `check:inspector` 守卫）
+- 不直接 import `@tbox-dev-js/sdk`——平台能力一律经 `@tbox.cn/app-sdk` 公开入口。
+
+## 关键入口
+
+```text
+apps/client/src/main.tsx                 # 客户端根入口（configureRuntime + ErrorBoundary + render）
+apps/client/src/business/App.tsx         # 业务应用唯一入口（新应用从这里开始）
+apps/server/src/index.ts                 # 静态入口（唯一 tsup entry：static + SPA + /api JSON 404）
+apps/server/src/app.ts                   # 装配主体（express + /api/health + start()）
+apps/server/src/dev.ts                   # vite dev 入口（仅 tsx 运行；禁入 tsup bundle）
+```
+
+## 平台基础设施（守卫保护，勿删改）
+
+- 单端口 8000（dev 与生产统一；端口经 `process.env.PORT || 8000`，lint 禁止硬编码）
+- `installInspector` 接线 + `apps/client/index.html` 的 `/__vs_inspector__.js` 标签（页面微调契约）
+- `GET /api/health` 恒返回 `{ "status": "ok" }`；未知 `/api/*` 恒 JSON 404
+- 服务端凭证/环境变量不进 client bundle（客户端环境值仅 `import.meta.env.VITE_*` 且经 `configureRuntime` 注入）
+
+## web-view 样式约定（嵌入支付宝小程序 web-view 壳时遵守）
+
+1. **长度单位 PX 大写**——小写 `px` 被壳内字体缩放改写，大写跳过改写保持视觉尺寸。
+2. **flex 子项设 `flex-shrink: 0`**——防壳内宽度不定导致元素被压缩。
+3. **滚动容器隐藏滚动条**（`::-webkit-scrollbar { display: none }`）。
+4. **颜色用 `rgba()` 传统语法**——避免 `color-mix`/`oklch` 在低版本内核不渲染。
+
+## 边界
+
+- 不创建嵌套 Vite 项目、第二个 `package.json` 或额外 lockfile（check:workspace 校验）。
+- 无模块装配面：`tbox-app module add` 不适用于本模板（模块展开后仅告警、不装配）。
+- 结构、路由、命令、依赖或环境变量变化时同步 README 与本文件。

package/LEGAL.md

@@ -0,0 +1,7 @@
+Legal Disclaimer
+
+Within this source code, the comments in Chinese shall be the original, governing version. Any comment in other languages are for reference only. In the event of any conflict between the Chinese language version comments and other language version comments, the Chinese language version shall prevail.
+
+法律免责声明
+
+关于代码注释部分，中文注释为官方版本，其它语言注释仅做参考。中文注释可能与其它语言注释存在不一致，当中文注释与其它语言注释存在不一致时，请以中文注释为准。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# template-h5
+
+tbox 移动 H5 全栈模板（包名 `@tbox.cn/app-template-h5`），单 workspace：`apps/client`（React/Vite）+ `apps/server`（Express）。运行时与页面微调经 `@tbox.cn/app-sdk`。
+
+## 快速开始
+
+```sh
+pnpm install
+pnpm dev
+```
+
+开发期浏览器访问 `http://localhost:8000`（单端口：API + 页面 + HMR）。`server` 负责 API、健康检查与生产静态托管，`client` 负责 H5 页面与业务入口。
+
+## 生成新应用
+
+```sh
+# 本地模板目录
+tbox-app create . --name my-h5-app --source <tbox-app 仓>/templates/template-h5
+# 或 registry（公开发布后）
+tbox-app create . --name my-h5-app --source @tbox.cn/app-template-h5
+pnpm install
+```
+
+## 目录边界
+
+- `apps/client/src/business/`：业务应用唯一入口
+- `apps/server/src/index.ts`：静态入口（唯一 tsup entry）
+- `apps/server/src/dev.ts`：vite dev 入口（仅本地开发）
+- `scripts/`：平台生命周期脚本（prepare/dev/start/stop/build 固定名）
+
+## 环境变量
+
+| 变量 | 侧 | 说明 |
+|---|---|---|
+| `PORT` | server | 服务端口（默认 8000） |
+| `HOST` | server | 监听地址（默认 0.0.0.0） |
+| `VITE_API_URL` | client | API base（空串/未设 = 同源相对路径）；经 `configureRuntime` 注入 |
+
+## 验收
+
+```sh
+pnpm verify    # typecheck + test + lint + build + check:inspector
+```
+
+更多工程约束见 [AGENTS.md](AGENTS.md)。

package/apps/client/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <!-- 移动端视口；缩放锁定，配合 postcss-pxtorem 的 750→rem 换算 -->
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
+    />
+    <meta name="theme-color" content="#0f172a" />
+    <!-- rem 弹性根字号（threshold 450 / designWidth 750）：移动端随屏宽缩放、PC 固定 50px 居中。
+         在 CSS 前同步执行，避免首屏字号闪动。 -->
+    <script>
+      (function () {
+        var THRESHOLD = 450,
+          DESIGN = 750;
+        function setRootFontSize() {
+          var w = document.documentElement.clientWidth;
+          document.documentElement.style.fontSize =
+            (w > THRESHOLD ? 50 : (100 / DESIGN) * w) + 'px';
+        }
+        setRootFontSize();
+        window.addEventListener('resize', setRootFontSize);
+        window.addEventListener('orientationchange', setRootFontSize);
+      })();
+    </script>
+    <title>H5 应用</title>
+    <!-- 平台微调(inspector) runtime：由 server 提供 GET /__vs_inspector__.js；dev 下经 Vite 代理到 server。 -->
+    <script src="/__vs_inspector__.js" defer></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/client/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@app/client",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tbox.cn/app-sdk": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "happy-dom": "catalog:",
+    "postcss-pxtorem": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  }
+}

package/apps/client/src/business/App.test.tsx

@@ -0,0 +1,18 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import { createElement } from 'react';
+import BusinessApp from './App';
+
+describe('BusinessApp', () => {
+  it('渲染中性入口标题', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    flushSync(() => {
+      createRoot(container).render(createElement(BusinessApp));
+    });
+    expect(container.querySelector('h1')?.textContent).toBe('你的移动应用，从这里开始');
+    container.remove();
+  });
+});

package/apps/client/src/business/App.tsx

@@ -0,0 +1,15 @@
+/**
+ * 业务应用唯一入口：中性单页起点，无占位标记。
+ * 新应用替换本组件；后端调用走 @tbox.cn/app-sdk/client 的 httpGet/httpPost（同源 /api/*）。
+ */
+export default function BusinessApp() {
+  return (
+    <main className="app-shell">
+      <section className="app-hero" aria-labelledby="app-title">
+        <p className="app-kicker">H5 应用</p>
+        <h1 id="app-title">你的移动应用，从这里开始</h1>
+        <p>品牌、页面与数据能力从这里构建——前后端同仓，SDK 提供运行时与页面微调基线。</p>
+      </section>
+    </main>
+  );
+}

package/apps/client/src/main.tsx

@@ -0,0 +1,36 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import {
+  configureRuntime,
+  ErrorBoundary,
+  installGlobalErrorReporting,
+} from '@tbox.cn/app-sdk/client';
+import BusinessApp from './business/App';
+import './styles/base.css';
+
+// H1：环境值注入点（SDK 零 Vite 依赖）——VITE_API_URL 空串/未设 = 同源相对路径
+configureRuntime({ apiBaseUrl: import.meta.env.VITE_API_URL as string | undefined });
+
+// 全局错误兜底：未捕获异常/rejection → 统一日志行（上报扩展点见 SDK client logger）
+installGlobalErrorReporting();
+
+const el = document.getElementById('root');
+
+if (el) {
+  createRoot(el).render(
+    <StrictMode>
+      <ErrorBoundary
+        fallback={
+          <main className="app-error">
+            <h1>页面暂时不可用</h1>
+            <button type="button" onClick={() => window.location.reload()}>
+              重新加载
+            </button>
+          </main>
+        }
+      >
+        <BusinessApp />
+      </ErrorBoundary>
+    </StrictMode>,
+  );
+}

package/apps/client/src/shims/node-stub.ts

@@ -0,0 +1,14 @@
+/**
+ * 浏览器端 fs / path 桩。
+ *
+ * @tbox-dev-js/sdk 的 ESM 顶层静态 import 了 Node 的 fs/path（用于 Node 环境的代码路径，
+ * 浏览器不会执行到），但静态 import 会让 vite 生产构建因"命名导出不存在"而失败。
+ * 用本桩 alias 掉 fs/path，提供同名空实现即可（浏览器永不调用这些路径）。
+ */
+export const existsSync = (): boolean => false;
+export const readFileSync = (): string => '';
+export const resolve = (...p: string[]): string => p.join('/');
+export const join = (...p: string[]): string => p.join('/');
+export const dirname = (p = ''): string => p.split('/').slice(0, -1).join('/');
+
+export default { existsSync, readFileSync, resolve, join, dirname };

package/apps/client/src/styles/base.css

@@ -0,0 +1,61 @@
+/* 基础样式三合一：tokens 变量 + 移动端基础 + motion。
+   变量值保持中性（slate 系），主题覆写由各应用自行扩展。 */
+
+/* ===== tokens（变量） ===== */
+:root {
+  --font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --color-background: #f8fafc;
+  --color-surface: #ffffff;
+  --color-text: #0f172a;
+  --color-muted: #64748b;
+  --color-primary: #0f766e;
+  --color-primary-strong: #115e59;
+  --color-accent: #f59e0b;
+  --color-border: #dbe4ea;
+  --color-focus: #f59e0b;
+  --content-width: 480px;
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.25rem;
+  --space-6: 1.5rem;
+  --space-8: 2rem;
+  --radius-sm: 0.5rem;
+  --radius-md: 0.75rem;
+  --shadow-soft: 0 20px 50px rgba(15, 23, 42, 0.08);
+}
+
+/* ===== 基础（reset + 移动端基线） ===== */
+:root { font-family: var(--font-family); color: var(--color-text); background: var(--color-background); font-synthesis: none; text-rendering: optimizeLegibility; }
+*, *::before, *::after { box-sizing: border-box; }
+html { min-width: 320px; min-height: 100%; background: var(--color-background); }
+body { margin: 0; min-width: 320px; min-height: 100%; overflow-x: hidden; background: var(--color-background); }
+body, button, input, textarea, select { font: inherit; }
+button, a, input, textarea, select { -webkit-tap-highlight-color: transparent; }
+button, a { touch-action: manipulation; }
+button { min-height: 44px; cursor: pointer; }
+button:disabled { cursor: wait; opacity: 0.65; }
+img, video, canvas { display: block; max-width: 100%; }
+img { height: auto; }
+#root { min-height: 100dvh; }
+@supports not (height: 100dvh) { #root { min-height: 100vh; } }
+@media (min-width: 700px) {
+  body { display: flex; justify-content: center; background: #e2e8f0; }
+  #root { width: min(100%, 480px); min-height: 100dvh; background: var(--color-background); box-shadow: 0 0 0 1px rgba(15, 23, 42, 0.08); overflow-x: hidden; }
+}
+:focus-visible { outline: 3px solid var(--color-focus); outline-offset: 3px; }
+
+/* ===== 入口类（中性起点，随应用改写） ===== */
+.app-shell { min-height: 100dvh; padding: max(2rem, env(safe-area-inset-top)) var(--space-5) max(2rem, env(safe-area-inset-bottom)); }
+.app-hero { padding: clamp(2.5rem, 12vh, 6rem) 0 var(--space-8); }
+.app-kicker { display: inline-flex; align-items: center; gap: var(--space-2); color: var(--color-primary); font-size: 0.78rem; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase; }
+.app-hero h1 { max-width: 12ch; margin: var(--space-4) 0; font-size: 2.75rem; line-height: 1.02; }
+.app-hero p { max-width: 34rem; margin: 0 0 var(--space-6); color: var(--color-muted); font-size: 1.05rem; line-height: 1.7; }
+.app-error { display: grid; min-height: 100dvh; place-content: center; gap: var(--space-4); padding: var(--space-6); text-align: center; }
+@media (max-width: 380px) { .app-hero h1 { font-size: 2.4rem; } }
+
+/* ===== motion ===== */
+.loading-dot { width: 0.65rem; height: 0.65rem; border-radius: 50%; background: currentColor; animation: pulse 1.2s ease-in-out infinite; }
+@keyframes pulse { 0%, 100% { opacity: 0.35; transform: scale(0.8); } 50% { opacity: 1; transform: scale(1); } }
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; scroll-behavior: auto !important; transition-duration: 0.01ms !important; } }

package/apps/client/src/vite-env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+
+declare module 'postcss-pxtorem';

package/apps/client/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "react-jsx",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/apps/client/vite.config.ts

@@ -0,0 +1,39 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import pxToRem from 'postcss-pxtorem';
+import { resolve } from 'node:path';
+// 平台微调配套 babel plugin（随 @tbox.cn/app-sdk 分发）：dev 期给每个 JSX 注入源码位置属性，
+// 供 inspector runtime(/__vs_inspector__.js) 点选元素→定位源码（check:inspector 断言点）。
+import codeInspectPlugin from '@tbox.cn/app-sdk/platform/code-inspect';
+
+const pxToRemPlugin = pxToRem({
+  rootValue: 100,
+  unitPrecision: 5,
+  propList: ['*'],
+  selectorBlackList: ['.no-rem'],
+  minPixelValue: 1,
+  mediaQuery: false,
+  // 排除 node_modules 内三方样式，但放行 pnpm 布局下的 @tbox.cn 模块 CSS（agent 同参）
+  exclude: /node_modules\/(?!\.pnpm|@tbox\.cn)/,
+});
+
+// dev 期页面由 apps/server dev.ts 的 vite middleware 托管（本文件被其加载）；
+// build 恒走静态产物。无 .tbox-dev.local 探针段（h5 无 dev 装配面，native launch）。
+export default defineConfig(({ command }) => ({
+  plugins: [react({ babel: { plugins: command === 'serve' ? [codeInspectPlugin] : [] } })],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+      // @tbox-dev-js/sdk 顶层静态 import fs/path（浏览器不执行）——生产构建以桩 alias（agent 同构）
+      fs: resolve(__dirname, 'src/shims/node-stub.ts'),
+      path: resolve(__dirname, 'src/shims/node-stub.ts'),
+    },
+  },
+  css: {
+    postcss: { plugins: [pxToRemPlugin] },
+  },
+  build: {
+    rollupOptions: { input: { index: resolve(__dirname, 'index.html') } },
+  },
+}));

package/apps/server/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@app/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch --exclude ../../apps/client src/dev.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tbox.cn/app-sdk": "catalog:",
+    "express": "catalog:"
+  },
+  "devDependencies": {
+    "@types/express": "catalog:",
+    "@types/node": "catalog:",
+    "@types/supertest": "catalog:",
+    "supertest": "catalog:",
+    "tsx": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  }
+}

package/apps/server/src/app.ts

@@ -0,0 +1,35 @@
+/**
+ * 装配主体（模块级单例）：express 链 + /api/health + start()。客户端供给由入口决定——
+ * 静态产物见 index.ts（唯一 tsup entry），vite dev 见 dev.ts（仅 tsx）。
+ * 平台微调（inspector）在入口级接线（index.ts / dev.ts），保持本模块测试纯净。
+ */
+import { createServer } from 'http';
+import express from 'express';
+import { createLogger } from '@tbox.cn/app-sdk/server';
+
+export const app = express();
+const logger = createLogger('server');
+
+app.use(express.json());
+
+// 健康检查契约（平台探活）：GET /api/health → {"status":"ok"}
+app.get('/api/health', (_req, res) => {
+  res.json({ status: 'ok' });
+});
+
+// 未知 /api/* 恒 JSON 404（不落 SPA 兜底）
+app.use('/api', (_req, res) => {
+  res.status(404).json({ error: 'Not Found' });
+});
+
+export function start() {
+  const port = Number(process.env.PORT ?? 8000);
+  const host = process.env.HOST ?? '0.0.0.0';
+  const server = createServer(app);
+  server.on('error', (err) => {
+    logger.error('server error:', err);
+    process.exit(1);
+  });
+  server.listen(port, host, () => logger.info(`listening on http://${host}:${port}`));
+  return server;
+}

package/apps/server/src/dev.ts

@@ -0,0 +1,71 @@
+/**
+ * vite dev 入口（仅 tsx 运行：pnpm dev；物理不进 tsup bundle——forbid-vite 插件拦截）。
+ * middlewareMode + 单端口 8000：HTTP 与 HMR WS 全走应用端口。
+ * 部署形态一律走 dist/index.js（静态产物，零 HMR WS）。
+ */
+import { createServer } from 'http';
+import path from 'path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'url';
+import { createServer as createViteServer } from 'vite';
+import { injectScript, installInspector, isReady } from '@tbox.cn/app-sdk/platform';
+import { app, start } from './app.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const clientRoot = path.resolve(__dirname, '../../client');
+
+// HMR WS 独立路径与协议常量（scripts/smoke-dev-hmr.sh 断言消费，不得改名）：
+// dev 基础设施命名空间（双下划线），与业务命名空间解耦。
+const HMR_WS_PATH = '/__vite_hmr';
+
+// HMR WS hub：永不 listen 的纯事件载体。hmr.server 在场 → vite 不自建独立端口，
+// 客户端按页面同源端口连接。vite 对 hub 仅 on/off('upgrade')。
+const hmrHub = createServer();
+
+const vite = await createViteServer({
+  root: clientRoot,
+  server: {
+    middlewareMode: true,
+    allowedHosts: true, // 沙箱域名 Host 透传放行（dev-only；dist 物理不含 vite）
+    fs: { deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**'] },
+    hmr: { server: hmrHub, path: HMR_WS_PATH },
+  },
+  appType: 'custom', // 不加 Vite 自己的 SPA fallback，由下方 app.use('*') 统一处理
+});
+
+// 平台微调（inspector）：入口级接线（与 index.ts 对称），须先于 vite middlewares
+installInspector(app);
+
+const viteHmrPath = path.posix.join(vite.config.base, HMR_WS_PATH);
+
+app.use(vite.middlewares);
+
+// HTML 路由兜底：非 /api 一律返回 index.html（经 Vite 转换 + inspector 注入）
+app.use('*', async (req, res, next) => {
+  if (req.originalUrl.startsWith('/api')) {
+    return next();
+  }
+  try {
+    const rawHtml = await readFile(path.join(clientRoot, 'index.html'), 'utf-8');
+    const template = await vite.transformIndexHtml(req.originalUrl, rawHtml);
+    const html = isReady() ? injectScript(template) : template;
+    res.status(200).set({ 'Content-Type': 'text/html' }).end(html);
+  } catch (e) {
+    next(e);
+  }
+});
+
+const server = start();
+
+// 升级处理：vite-hmr 协议 + 认领路径 → hub；其余一律销毁（本模板无业务 WS）
+server.on('upgrade', (request, socket, head) => {
+  const protocol = request.headers['sec-websocket-protocol'];
+  if (typeof protocol === 'string' && (protocol === 'vite-hmr' || protocol === 'vite-ping')) {
+    const { pathname } = new URL(request.url || '/', 'http://localhost');
+    if (pathname === viteHmrPath) {
+      hmrHub.emit('upgrade', request, socket, head);
+      return;
+    }
+  }
+  socket.destroy();
+});

package/apps/server/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * 静态入口（唯一 tsup entry → dist/index.js）：express.static 供给 client/dist。
+ * dist 形态恒静态——vite dev 仅存在于 src/dev.ts（tsx 运行，禁入 tsup entry，
+ * tsup.config.ts forbid-vite 插件拦截）。
+ */
+import path from 'path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'url';
+import express from 'express';
+import { createLogger } from '@tbox.cn/app-sdk/server';
+import { installInspector } from '@tbox.cn/app-sdk/platform';
+import { app, start } from './app.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const logger = createLogger('server');
+
+// 平台微调（inspector）：点选元素→定位源码（接线契约由 pnpm check:inspector 守卫）。
+// 入口级调用（index.ts / dev.ts 对称），app.ts 保持测试纯净。
+installInspector(app);
+
+const clientDistPath = path.join(__dirname, '../../client/dist');
+if (!existsSync(path.join(clientDistPath, 'index.html'))) {
+  logger.warn(`client/dist 缺失（${clientDistPath}）——页面将不可用；请先执行 pnpm build:client`);
+}
+
+app.use(express.static(clientDistPath));
+app.get('*', (req, res) => {
+  if (!req.path.startsWith('/api')) {
+    res.sendFile(path.join(clientDistPath, 'index.html'));
+  } else {
+    res.status(404).json({ error: 'Not Found' });
+  }
+});
+
+start();

package/apps/server/tests/app.test.ts

@@ -0,0 +1,17 @@
+import request from 'supertest';
+import { describe, expect, it } from 'vitest';
+import { app } from '../src/app.js';
+
+describe('HTTP API', () => {
+  it('GET /api/health → {"status":"ok"}（平台探活契约）', async () => {
+    const res = await request(app).get('/api/health');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ status: 'ok' });
+  });
+
+  it('未知 /api/* → JSON 404（不落 SPA 兜底）', async () => {
+    const res = await request(app).get('/api/nope');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ error: 'Not Found' });
+  });
+});

package/apps/server/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src", "tests"]
+}