@tbox.cn/app-template-agent 0.10.21 → 0.10.23

package/pnpm-lock.template.yaml

@@ -16,20 +16,20 @@ catalogs:
       specifier: 0.2.0
       version: 0.2.0
     '@tbox.cn/app-agent-sdk-server':
-      specifier: 0.3.1
-      version: 0.3.1
+      specifier: 0.3.2
+      version: 0.3.2
     '@tbox.cn/app-contracts':
-      specifier: 0.13.2
-      version: 0.13.2
+      specifier: 0.13.3
+      version: 0.13.3
     '@tbox.cn/app-sdk-client':
       specifier: 0.21.3
       version: 0.21.3
     '@tbox.cn/app-sdk-server':
-      specifier: 0.26.0
-      version: 0.26.0
+      specifier: 0.26.1
+      version: 0.26.1
     '@tbox.cn/app-theme-tbox':
-      specifier: 0.1.4
-      version: 0.1.4
+      specifier: 0.1.5
+      version: 0.1.5
     '@types/express':
       specifier: 4.17.25
       version: 4.17.25
@@ -103,7 +103,7 @@ importers:
     devDependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.26.0
+        version: 0.26.1
       eslint:
         specifier: 'catalog:'
         version: 9.39.5
@@ -136,10 +136,10 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
       '@tbox.cn/app-theme-tbox':
         specifier: 'catalog:'
-        version: 0.1.4
+        version: 0.1.5
       react:
         specifier: 'catalog:'
         version: 18.3.1
@@ -150,6 +150,9 @@ importers:
         specifier: 'catalog:'
         version: 4.5.7(@types/react@18.3.31)(react@18.3.1)
     devDependencies:
+      '@tbox.cn/app-agent-sdk-server':
+        specifier: 'catalog:'
+        version: 0.3.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@types/node':
         specifier: 'catalog:'
         version: 24.13.3
@@ -191,7 +194,7 @@ importers:
         version: 0.21.3
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.26.0
+        version: 0.26.1
       typescript:
         specifier: 'catalog:'
         version: 5.9.3
@@ -218,10 +221,10 @@ importers:
         version: 0.1.0(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(@tbox-dev-js/sdk@0.1.18)(zod@3.25.76)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
       express:
         specifier: 'catalog:'
         version: 4.22.2
@@ -261,7 +264,7 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
       antd-mobile:
         specifier: 5.42.3
         version: 5.42.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -310,7 +313,7 @@ importers:
     dependencies:
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
       zod:
         specifier: 3.25.76
         version: 3.25.76
@@ -341,10 +344,10 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
       react:
         specifier: 18.3.1
         version: 18.3.1
@@ -384,11 +387,14 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.2
+        version: 0.13.3
     devDependencies:
+      '@app/contracts-mall':
+        specifier: workspace:*
+        version: link:../contracts-mall
       '@types/node':
         specifier: 24.13.3
         version: 24.13.3
@@ -1415,8 +1421,8 @@ packages:
     resolution: {integrity: sha512-yxK5vLuERzlebTwiw8WxU6e9rm7F1L9tVW4aSUGsIxeU0y8VtRcrh7y8xKbrlXR4WL4XrmYZ6ZoDyOuro9sn5A==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-agent-sdk-server@0.3.1':
-    resolution: {integrity: sha512-VWAlG+Efjyo6Wwj4QPKO9N4DPjhG20z3t9cGjzjW8ZvUFU7hQ7NngbFh7Z7IXtYrXJCGpjJSGtMLJ9AgBk67iQ==}
+  '@tbox.cn/app-agent-sdk-server@0.3.2':
+    resolution: {integrity: sha512-NrKZNjc6xJgkF2EXnGApOnVS52HMllDmtNnd8GjQh9qfiJfkvzKSsceCUu2Ek75tTjY5axBGJP5sel1+N2N07g==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-contracts@0.13.0':
@@ -1431,6 +1437,10 @@ packages:
     resolution: {integrity: sha512-0lY9g29ice7xYbmV5XDnEiMmM70jvSzeK2cciUZVpzHgGykWqZiPRlqXIGkIRY7uObDQ1cICHC4mS67HuNQ8Jg==}
     engines: {node: '>=20.0.0'}
 
+  '@tbox.cn/app-contracts@0.13.3':
+    resolution: {integrity: sha512-P16LFd+ZzIASrujs6fyaOEwRnsLg7Lh5k1qOVDNblmohrvUbVIOK5ntn+7mupJxnjK7SY43RUT4mtWtfM85/rQ==}
+    engines: {node: '>=20.0.0'}
+
   '@tbox.cn/app-sdk-client@0.21.3':
     resolution: {integrity: sha512-64y22k5gzCc9eEQ0IJA1izxPaosNEmoCJ4YrsfHOoHYq2UPJCCmP7RIu3Rn4stPZ4tcmRdMdAi2y5499KObYHw==}
     engines: {node: '>=20.0.0'}
@@ -1443,16 +1453,16 @@ packages:
     resolution: {integrity: sha512-HLLRg1y2jB32uJPL3/a387eABdNZUxrmkGoJwIv44XV9B94DXmTgb9vxYzbyBa0FazxXG0WudyzFnmH5eeqqrw==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-server@0.26.0':
-    resolution: {integrity: sha512-VpV3sf4K/2MEsnkuK5EqZUyf9KoSVHeJUm4Al0M6R4Wumg6183apnxB2f38S5wuP30JSJShN/ww63EzRniTrjw==}
+  '@tbox.cn/app-sdk-server@0.26.1':
+    resolution: {integrity: sha512-spg0aF6nmt9Nbxz8ofRYyojOpeOWcYI3mfTevzVJrhfzKmQ3WufpmP/lwLHuQkF2WEVI33dhVQQum7TFCck3+Q==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@tbox.cn/app-theme-tbox@0.1.4':
-    resolution: {integrity: sha512-VF2fjTBFKJ6x/wvM6/T0qi7dmoiN1stNIT2xDerYbBBLCggr7f+H0v6VtuFMSed6tirlcpAlqtBDOctxudHJlQ==}
+  '@tbox.cn/app-theme-tbox@0.1.5':
+    resolution: {integrity: sha512-NL3xmPQOuXBf7vWutU3dWLhvhCvQSA6cHGH76qcqBkPSAgUlKacE1G67jOFyWlC9rg5oMWVOdrkniXvhi5v/4w==}
 
-  '@tbox.cn/app-toolkit@0.8.0':
-    resolution: {integrity: sha512-urefCf5DCWbH9wM8dSGavA9MNdY4gx7LY16+s9jIlwhahq83mfrCP2h9ombn44ljMrv04G7mnb3vMtNeWs5/Ug==}
+  '@tbox.cn/app-toolkit@0.8.3':
+    resolution: {integrity: sha512-i+rz8tUwndygwCw/T5dp/59p2JKW+Xpfy2UznKOY8vuKbqbe2ANCUTDUuNf8IDuyfvy158Iw/+5H/hLVNAD/3w==}
     engines: {node: '>=20.0.0'}
 
   '@types/babel__core@7.20.5':
@@ -4175,7 +4185,7 @@ snapshots:
       - '@types/react'
       - immer
 
-  '@tbox.cn/app-agent-sdk-server@0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
+  '@tbox.cn/app-agent-sdk-server@0.3.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
     dependencies:
       '@ag-ui/core': 0.0.47
       '@ai-sdk/openai-compatible': 2.0.68(zod@3.25.76)
@@ -4183,9 +4193,9 @@ snapshots:
       '@mastra/core': 1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76)
       '@mastra/observability': 1.16.5(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(zod@3.25.76)
       '@tbox.cn/agent-plugin': 0.1.0(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(@tbox-dev-js/sdk@0.1.18)(zod@3.25.76)
-      '@tbox.cn/app-contracts': 0.13.2
+      '@tbox.cn/app-contracts': 0.13.3
       '@tbox.cn/app-sdk-core': 0.20.5
-      '@tbox.cn/app-sdk-server': 0.26.0
+      '@tbox.cn/app-sdk-server': 0.26.1
       ai: 6.0.246(zod@3.25.76)
       express: 4.22.2
       gray-matter: 4.0.3
@@ -4221,6 +4231,12 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
+  '@tbox.cn/app-contracts@0.13.3':
+    dependencies:
+      '@ag-ui/core': 0.0.47
+      react: 18.3.1
+      zod: 3.25.76
+
   '@tbox.cn/app-sdk-client@0.21.3':
     dependencies:
       '@tbox.cn/app-contracts': 0.13.0
@@ -4236,21 +4252,21 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.13.2
 
-  '@tbox.cn/app-sdk-server@0.26.0':
+  '@tbox.cn/app-sdk-server@0.26.1':
     dependencies:
       '@ag-ui/core': 0.0.47
-      '@tbox.cn/app-contracts': 0.13.1
-      '@tbox.cn/app-sdk-core': 0.20.4
-      '@tbox.cn/app-toolkit': 0.8.0
+      '@tbox.cn/app-contracts': 0.13.3
+      '@tbox.cn/app-sdk-core': 0.20.5
+      '@tbox.cn/app-toolkit': 0.8.3
       express: 4.22.2
       jose: 6.2.8
       zod: 3.25.76
     transitivePeerDependencies:
       - supports-color
 
-  '@tbox.cn/app-theme-tbox@0.1.4': {}
+  '@tbox.cn/app-theme-tbox@0.1.5': {}
 
-  '@tbox.cn/app-toolkit@0.8.0':
+  '@tbox.cn/app-toolkit@0.8.3':
     dependencies:
       ajv: 8.20.0
       zod: 3.25.76

package/pnpm-workspace.template.yaml

@@ -40,12 +40,12 @@ catalog:
   "@tbox.cn/agent-plugin": 0.1.0
   "@tbox.cn/app-sdk-core": 0.20.5
   "@tbox.cn/app-sdk-client": 0.21.3
-  "@tbox.cn/app-sdk-server": 0.26.0
-  "@tbox.cn/app-agent-sdk-server": 0.3.1
+  "@tbox.cn/app-sdk-server": 0.26.1
+  "@tbox.cn/app-agent-sdk-server": 0.3.2
   "@tbox.cn/app-agent-sdk-client": 0.2.0
-  "@tbox.cn/app-contracts": 0.13.2
-  "@tbox.cn/app-contracts-mall": 0.13.1
-  "@tbox.cn/app-theme-tbox": 0.1.4
+  "@tbox.cn/app-contracts": 0.13.3
+  "@tbox.cn/app-contracts-mall": 0.13.2
+  "@tbox.cn/app-theme-tbox": 0.1.5
   zustand: 4.5.7
   eslint: 9.39.5
   typescript-eslint: 8.67.0

package/scripts/check-workspace.mjs

@@ -30,6 +30,30 @@ const nestedLockfiles = new Set([
 ]);
 const viteConfigPattern = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
 
+/**
+ * CLI 裸简写防线：应用文档里不得出现 `tbox-app <cmd>`（agent 照抄后 PATH 无 bin → 命令失败）。
+ * 唯一合法形态 = `npx --yes @tbox.cn/app-cli <cmd>`；`tbox-app-dev`（私有 CLI）不匹配。
+ */
+const bareCliPattern = /\btbox-app\s+(?:module|provider|theme|starter|new|create|schema|skills|doctor|miniapp-container)\b/g;
+const cliDocFiles = [
+  'AGENTS.md',
+  'README.md',
+  'ENV.md',
+  'TEMPLATE.md',
+  'apps/client/src/business/README.md',
+];
+
+async function checkCliShorthand(findings) {
+  for (const rel of cliDocFiles) {
+    const file = path.join(projectDir, rel);
+    if (!existsSync(file)) continue;
+    const text = await readFile(file, 'utf8');
+    for (const match of text.matchAll(bareCliPattern)) {
+      findings.bareCliShorthands.push(`${rel}: ${match[0]}`);
+    }
+  }
+}
+
 function relativeDir(filePath) {
   const relative = path.relative(projectDir, path.dirname(filePath));
   return relative === '' ? '.' : relative.split(path.sep).join('/');
@@ -95,6 +119,10 @@ function printFailure(findings) {
     console.error('\npackages/* 缺少 tbox.module.json（contracts / app-sdk / shared 除外）：');
     for (const file of findings.missingModuleDescriptors) console.error(`  - ${file}`);
   }
+  if (findings.bareCliShorthands.length > 0) {
+    console.error('\n检测到 CLI 裸简写（须写全 npx --yes @tbox.cn/app-cli <cmd>）：');
+    for (const item of findings.bareCliShorthands) console.error(`  - ${item}`);
+  }
 
   console.error('');
   process.exitCode = 1;
@@ -147,10 +175,12 @@ async function main() {
     nestedLockfiles: [],
     detachedViteConfigs: [],
     missingModuleDescriptors: [],
+    bareCliShorthands: [],
   };
 
   await walk(projectDir, findings);
   await checkModuleDescriptors(projectDir, findings);
+  await checkCliShorthand(findings);
 
   if (Object.values(findings).some((items) => items.length > 0)) {
     printFailure(findings);

package/scripts/smoke.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * smoke.mjs — 一次性运行时冒烟（三级回路第二级）。
+ *
+ * 四验：boot（/api/health 200 + status:ok）→ browser 登录 → /api/auth/me → 进程组清理。
+ * 设计约束（与平台沙箱共存）：
+ * - 静态入口 src/index.ts（不走 dev.ts——dev 面引入 vite/token 分面，非本脚本职责）；
+ * - NODE_ENV=development（SDK 安全姿态）；端口由 OS 分配（仅覆盖 PORT——apps/server 唯一消费该键）；
+ * - detached 进程组 + SIGTERM→SIGKILL，零残留；
+ * - 路径锚定脚本位置（任意 cwd 可执行）；
+ * - 登录 403 AUTH_BROWSER_LOGIN_DISABLED = 合法配置（SKIP，不判失败）；
+ * - fail-soft 配置降级不阻断 boot：stderr/stdout 尾部固定 dump，提示人工判读 WARN/ERROR。
+ *
+ * 用法：pnpm smoke / node scripts/smoke.mjs [--self-test]
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SERVER_DIR = path.join(APP_ROOT, 'apps', 'server');
+const KNOWN_WARNINGS = ['client/dist 缺失'];
+const BOOT_TIMEOUT_MS = 30_000;
+const TOTAL_TIMEOUT_MS = 60_000;
+const LOG_LIMIT = 200_000;
+
+/** OS 分配空闲端口（listen 0 → 取 port → close）。 */
+export function pickPort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address !== null ? address.port : NaN;
+      server.close(() => (Number.isInteger(port) && port > 0 ? resolve(port) : reject(new Error('无法分配端口'))));
+    });
+  });
+}
+
+/** 端口合法性（禁固定 dev/stage 端口——互踩防线；非法直接 throw）。 */
+export function assertValidPort(port) {
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new Error(`非法端口: ${port}`);
+  if (port === 8000 || port === 8001) throw new Error(`冒烟端口不可复用固定端口 ${port}（OS 分配）`);
+}
+
+/** 日志尾部（末 maxLines 行；超长截断）。 */
+export function tailLines(text, maxLines = 100) {
+  if (!text) return '';
+  const lines = text.split(/\r?\n/);
+  if (lines.length <= maxLines) return text;
+  return lines.slice(-maxLines).join('\n');
+}
+
+function appendLog(state, chunk) {
+  state.log += chunk;
+  if (state.log.length > LOG_LIMIT) state.log = state.log.slice(-LOG_LIMIT);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function requestJson(url, init = {}) {
+  const response = await fetch(url, { ...init, signal: AbortSignal.timeout(5_000) });
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  return { status: response.status, body };
+}
+
+/** 进程组终止（detached spawn 的反向操作；ESRCH 容忍）。 */
+function killGroup(pid, signal) {
+  if (!pid) return;
+  try {
+    process.kill(process.platform === 'win32' ? pid : -pid, signal);
+  } catch (error) {
+    if (error.code !== 'ESRCH') throw error;
+  }
+}
+
+async function waitForHealth(port, child, state, spawnErrorOf = () => undefined) {
+  const deadline = Date.now() + BOOT_TIMEOUT_MS;
+  const url = `http://127.0.0.1:${port}/api/health`;
+  while (Date.now() < deadline) {
+    const spawnError = spawnErrorOf();
+    if (spawnError) throw new Error(`server 启动失败：${spawnError.message}`);
+    if (child.exitCode !== null) {
+      throw new Error(`server 在健康检查前退出（code=${child.exitCode}）\n${tailLines(state.log)}`);
+    }
+    try {
+      const { status, body } = await requestJson(url);
+      if (status === 200 && body?.status === 'ok') return;
+      throw new Error(`/api/health 非预期响应: ${status} ${JSON.stringify(body)}`);
+    } catch (error) {
+      if (String(error.message).includes('/api/health 非预期响应')) throw error;
+      await sleep(250);
+    }
+  }
+  throw new Error(`/api/health 超时（${BOOT_TIMEOUT_MS}ms）\n${tailLines(state.log)}`);
+}
+
+async function loginMatrix(port) {
+  const login = await requestJson(`http://127.0.0.1:${port}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ method: 'browser' }),
+  });
+  if (login.status === 200 && typeof login.body?.token === 'string') {
+    const me = await requestJson(`http://127.0.0.1:${port}/api/auth/me`, {
+      headers: { authorization: `Bearer ${login.body.token}` },
+    });
+    if (me.status !== 200 || !me.body?.identity) {
+      throw new Error(`/api/auth/me 校验失败: ${me.status} ${JSON.stringify(me.body)}`);
+    }
+    return 'PASS';
+  }
+  if (login.status === 403 && login.body?.code === 'AUTH_BROWSER_LOGIN_DISABLED') {
+    return 'SKIP（browser 登录关闭——合法配置）';
+  }
+  throw new Error(`browser 登录失败: ${login.status} ${JSON.stringify(login.body)}`);
+}
+
+export async function runSmoke(opts = {}) {
+  const totalTimeoutMs = opts.timeoutMs ?? TOTAL_TIMEOUT_MS;
+  if (opts.probe) {
+    const port = await pickPort();
+    assertValidPort(port);
+    return { ok: true, reason: `probe ok（port=${port}）` };
+  }
+  if (!existsSync(path.join(SERVER_DIR, 'node_modules', 'tsx'))) {
+    return { ok: false, reason: 'apps/server/node_modules 下的 tsx 缺席——先执行 pnpm install' };
+  }
+  let port;
+  try {
+    port = await pickPort();
+    assertValidPort(port);
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+
+  const state = { log: '' };
+  let child = null;
+  let watchdog;
+  const cleanup = async () => {
+    if (!child || child.exitCode !== null) return;
+    killGroup(child.pid, 'SIGTERM');
+    const deadline = Date.now() + 2_000;
+    while (child.exitCode === null && Date.now() < deadline) await sleep(50);
+    if (child.exitCode === null) killGroup(child.pid, 'SIGKILL');
+  };
+  const onSignal = () => {
+    void cleanup().finally(() => process.exit(130));
+  };
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  const MAX_ATTEMPTS = 3;
+  let lastError = null;
+  try {
+    if (totalTimeoutMs > 0) {
+      watchdog = setTimeout(() => {
+        console.error(`⏱️ 冒烟总超时 ${totalTimeoutMs}ms——强制终止 server 进程组`);
+        void cleanup().finally(() => process.exit(1));
+      }, totalTimeoutMs);
+      watchdog.unref();
+    }
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+      state.log = '';
+      const startedAt = Date.now();
+      child = spawn(process.execPath, ['--import', 'tsx', 'src/index.ts'], {
+        cwd: SERVER_DIR,
+        env: { ...process.env, PORT: String(port), NODE_ENV: 'development' },
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let spawnError;
+      child.stdout.on('data', (chunk) => appendLog(state, chunk.toString()));
+      child.stderr.on('data', (chunk) => appendLog(state, chunk.toString()));
+      child.once('error', (error) => {
+        spawnError = error;
+        appendLog(state, `spawn error: ${error.message}\n`);
+      });
+
+      console.log(`[smoke] 启动 server（port=${port}, entry=src/index.ts${attempt > 1 ? `，第 ${attempt} 次尝试` : ''}）…`);
+      try {
+        await waitForHealth(port, child, state, () => spawnError);
+        console.log(`[smoke] ✓ health（${Date.now() - startedAt}ms）`);
+
+        const login = await loginMatrix(port);
+        console.log(`[smoke] ✓ login/me：${login}`);
+
+        const warningLines = state.log.split(/\r?\n/).filter((line) => /\b(WARN|ERROR)\b/.test(line));
+        const knownWarnings = warningLines.filter((line) => KNOWN_WARNINGS.some((known) => line.includes(known)));
+        const warnings = warningLines.filter((line) => !KNOWN_WARNINGS.some((known) => line.includes(known)));
+        if (knownWarnings.length > 0) {
+          console.log('[smoke] 已知告警（[known]，不判失败）：');
+          for (const line of knownWarnings.slice(0, 5)) console.log(`  [known] ${line}`);
+        }
+        if (warnings.length > 0) {
+          console.log('[smoke] 运行期 WARN/ERROR（前 20 行）：');
+          for (const line of warnings.slice(0, 20)) console.log(`  ${line}`);
+        }
+        return { ok: true, reason: 'health + login + me 全通过' };
+      } catch (error) {
+        lastError = error;
+        const portBusy = /EADDRINUSE|already in use/i.test(state.log);
+        await cleanup();
+        child = null;
+        if (portBusy && attempt < MAX_ATTEMPTS) {
+          try {
+            port = await pickPort();
+            assertValidPort(port);
+          } catch (portError) {
+            return { ok: false, reason: `端口重分配失败：${portError.message}` };
+          }
+          console.log(`[smoke] 端口被占用——改用 ${port} 重试（${attempt}/${MAX_ATTEMPTS}）`);
+          continue;
+        }
+        break;
+      }
+    }
+    return {
+      ok: false,
+      reason: `${lastError?.message ?? '未知失败'}\n\n--- server 日志尾部 ---\n${tailLines(state.log)}`,
+    };
+  } finally {
+    if (watchdog) clearTimeout(watchdog);
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+    await cleanup();
+  }
+}
+
+function selfTest() {
+  const failures = [];
+  const eq = (label, actual, expected) => {
+    if (actual !== expected) failures.push(`${label}: ${JSON.stringify(actual)} !== ${JSON.stringify(expected)}`);
+  };
+  eq('tailLines short', tailLines('a\nb'), 'a\nb');
+  eq('tailLines trim', tailLines('1\n2\n3', 2), '2\n3');
+  eq('tailLines empty', tailLines(''), '');
+  for (const bad of [0, -1, 8000, 8001, 70000, 1.5, NaN]) {
+    let threw = false;
+    try {
+      assertValidPort(bad);
+    } catch {
+      threw = true;
+    }
+    if (!threw) failures.push(`assertValidPort(${bad}) 应 throw`);
+  }
+  assertValidPort(8123);
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`[smoke:self-test] ${failure}`);
+    return false;
+  }
+  console.log('[smoke:self-test] ok');
+  return true;
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  if (process.argv.includes('--self-test')) {
+    if (!selfTest()) process.exit(1);
+    const probe = await runSmoke({ probe: true });
+    if (!probe.ok) {
+      console.error(`[smoke:self-test] ${probe.reason}`);
+      process.exit(1);
+    }
+    console.log(`[smoke:self-test] ${probe.reason}`);
+    process.exit(0);
+  }
+  const result = await runSmoke();
+  if (result.ok) {
+    console.log(`✅ smoke 通过：${result.reason}`);
+    console.log('[smoke] 提示：检查运行期 WARN/ERROR（fail-soft 配置降级在此可见）');
+  } else {
+    console.error(`❌ smoke 失败：${result.reason}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/verify-generated.mjs

@@ -4,7 +4,7 @@
  *   ① 装配文件与模块声明一致（漂移 = 0，服务端 modules.ts）
  *   ② 2 装配文件双锚点完整（imports + register 标记齐全）
  *   ③ 装配文件无裸露 import（全部 import 行在锚区内；import type 豁免）
- * 自包含实现（模板独立于 CLI 包），全量校验以 `tbox-app module doctor` / `tbox-app module diff` 为准。
+ * 自包含实现（模板独立于 CLI 包），全量校验以 CLI `module doctor` / `module diff` 为准。
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
@@ -101,7 +101,7 @@ async function main() {
 
   // ① 漂移 = 0：声明（manifest + 本地模块）vs 服务端 modules.ts 实际装配
   // 契约包（无 tbox.module.json / 无 serverModule）不参与 modules.ts 装配，不计入声明
-  // （客户端 modules.ts 装配漂移由 tbox-app module doctor 全量校验兜底）
+  // （客户端 modules.ts 装配漂移由 CLI module doctor 全量校验兜底）
   const npmModules = readManifestModules();
   const declared = new Set([
     ...npmModules