@tbox.cn/app-template-agent 0.10.20 → 0.10.22

package/pnpm-lock.template.yaml

@@ -16,11 +16,11 @@ catalogs:
       specifier: 0.2.0
       version: 0.2.0
     '@tbox.cn/app-agent-sdk-server':
-      specifier: 0.3.0
-      version: 0.3.0
+      specifier: 0.3.1
+      version: 0.3.1
     '@tbox.cn/app-contracts':
-      specifier: 0.13.1
-      version: 0.13.1
+      specifier: 0.13.3
+      version: 0.13.3
     '@tbox.cn/app-sdk-client':
       specifier: 0.21.3
       version: 0.21.3
@@ -28,8 +28,8 @@ catalogs:
       specifier: 0.26.0
       version: 0.26.0
     '@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
@@ -136,10 +136,10 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        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
@@ -218,10 +218,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.0(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        version: 0.13.3
       express:
         specifier: 'catalog:'
         version: 4.22.2
@@ -261,7 +261,7 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        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 +310,7 @@ importers:
     dependencies:
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        version: 0.13.3
       zod:
         specifier: 3.25.76
         version: 3.25.76
@@ -341,10 +341,10 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.3.0(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        version: 0.13.3
       react:
         specifier: 18.3.1
         version: 18.3.1
@@ -384,11 +384,14 @@ importers:
         version: 0.2.0(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.3.0(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.3.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.13.1
+        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 +1418,8 @@ packages:
     resolution: {integrity: sha512-yxK5vLuERzlebTwiw8WxU6e9rm7F1L9tVW4aSUGsIxeU0y8VtRcrh7y8xKbrlXR4WL4XrmYZ6ZoDyOuro9sn5A==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-agent-sdk-server@0.3.0':
-    resolution: {integrity: sha512-thnnPwA0Tkb3yf+HxmeIEDyji6myIJVKvyhzn0WWuVJN7mg9I6+juTimxwRNhqnpZBjue3kExMw75+MvTineYA==}
+  '@tbox.cn/app-agent-sdk-server@0.3.1':
+    resolution: {integrity: sha512-VWAlG+Efjyo6Wwj4QPKO9N4DPjhG20z3t9cGjzjW8ZvUFU7hQ7NngbFh7Z7IXtYrXJCGpjJSGtMLJ9AgBk67iQ==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-contracts@0.13.0':
@@ -1427,6 +1430,14 @@ packages:
     resolution: {integrity: sha512-Cty4qoknyihli6ZMlxOqqTgRqwg0NOh0WOMfIWdB4rHua0QzZkP1jUoeffq5imnpIh7vXdfLhDpv/JwTrHd1XQ==}
     engines: {node: '>=20.0.0'}
 
+  '@tbox.cn/app-contracts@0.13.2':
+    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'}
@@ -1435,13 +1446,17 @@ packages:
     resolution: {integrity: sha512-4kcoxnZnPgsO0RwAsjsodOXRhZNQcr9r3INN3Z03/JR2e3E+izkW2YHsgGcdbVSVX81s8gZrkaBbE+xco3wSqg==}
     engines: {node: '>=20.0.0'}
 
+  '@tbox.cn/app-sdk-core@0.20.5':
+    resolution: {integrity: sha512-HLLRg1y2jB32uJPL3/a387eABdNZUxrmkGoJwIv44XV9B94DXmTgb9vxYzbyBa0FazxXG0WudyzFnmH5eeqqrw==}
+    engines: {node: '>=20.0.0'}
+
   '@tbox.cn/app-sdk-server@0.26.0':
     resolution: {integrity: sha512-VpV3sf4K/2MEsnkuK5EqZUyf9KoSVHeJUm4Al0M6R4Wumg6183apnxB2f38S5wuP30JSJShN/ww63EzRniTrjw==}
     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==}
@@ -4167,7 +4182,7 @@ snapshots:
       - '@types/react'
       - immer
 
-  '@tbox.cn/app-agent-sdk-server@0.3.0(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
+  '@tbox.cn/app-agent-sdk-server@0.3.1(@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)
@@ -4175,8 +4190,8 @@ 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.1
-      '@tbox.cn/app-sdk-core': 0.20.4
+      '@tbox.cn/app-contracts': 0.13.2
+      '@tbox.cn/app-sdk-core': 0.20.5
       '@tbox.cn/app-sdk-server': 0.26.0
       ai: 6.0.246(zod@3.25.76)
       express: 4.22.2
@@ -4207,6 +4222,18 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
+  '@tbox.cn/app-contracts@0.13.2':
+    dependencies:
+      '@ag-ui/core': 0.0.47
+      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
@@ -4218,6 +4245,10 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.13.0
 
+  '@tbox.cn/app-sdk-core@0.20.5':
+    dependencies:
+      '@tbox.cn/app-contracts': 0.13.2
+
   '@tbox.cn/app-sdk-server@0.26.0':
     dependencies:
       '@ag-ui/core': 0.0.47
@@ -4230,7 +4261,7 @@ snapshots:
     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':
     dependencies:

package/pnpm-workspace.template.yaml

@@ -38,14 +38,14 @@ catalog:
   ws: 8.21.3
   "@types/ws": 8.18.1
   "@tbox.cn/agent-plugin": 0.1.0
-  "@tbox.cn/app-sdk-core": 0.20.4
+  "@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.0
+  "@tbox.cn/app-agent-sdk-server": 0.3.1
   "@tbox.cn/app-agent-sdk-client": 0.2.0
-  "@tbox.cn/app-contracts": 0.13.1
-  "@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

package/INTEGRATION.md

@@ -1,95 +0,0 @@
-# INTEGRATION —— 自定义服务集成指引（真源）
-
-本文件是应用「自定义服务集成」指引的唯一真源；发现入口 = 根 `AGENTS.md`
-「自定义服务集成（provider-custom）」节（该节为指针，勿在其下扩展内容）。
-
-**自定义 API** = 服务的真实后端由你自己对接：声明住在 `config/integrations.json`，adapter
-代码住在 `packages/provider-custom/`。服务后端三选一：Mock（演示数据，装 provider-mock
-即用）/ 自定义 API（你自己的后端接口——本文件流程）/ 服务商集成（官方 provider 包，
-`module add` + `provider bind`）。
-
-## 任务路由
-
-| 你的任务 | 按此读取 |
-|---|---|
-| 为一个服务接入 | `packages/contracts-mall/src/services/<域>.ts`（Port 定义）+ `packages/provider-custom/INTEGRATION.md` |
-| 为某模块全部服务接入 | `packages/<module>/INTEGRATION.md` + `packages/<module>/tbox.module.json` + 该域 Port 文件 + `packages/provider-custom/INTEGRATION.md` |
-| 应用全部服务接入 | `tbox-app module list` 后逐模块按上行 |
-| 实施与排障 | `packages/provider-custom/INTEGRATION.md`（声明/骨架/注册/凭据/完成判据全链） |
-
-## 四步流程
-
-收到「为某服务/模块/应用接入自定义 API」（或「对接我的 API」「先要接口清单」等同义
-说法）的请求时按四步走：
-
-1. **说明并产出接入材料清单**（规范见下节）。目标不在已装模块服务槽词汇内 → 说明未装
-   该模块，引导 `module add` 或 `new module`，不进入后续步骤。用户已给出的信息不重复问。
-   未实施前调用报 `PROVIDER_NOT_IMPLEMENTED` 属预期中间态。
-2. **落声明**：目标槽已有内联声明则跳过；否则直接编辑 `config/integrations.json`
-   （CLI provider 命令仅支持字符串厂商）按「声明落点」表写入。
-3. **实施 adapter**：按 `packages/provider-custom/INTEGRATION.md` 实施。
-4. **验收**：`pnpm typecheck && pnpm build` 通过 + `npx --yes @tbox.cn/app-cli module
-   doctor`；平台重启后该服务的调用不再报 `PROVIDER_NOT_IMPLEMENTED`（resolveService
-   惰性——调用时观测；doctor 对通配槽凭据不设防，运行时判据为最终裁判）。
-
-### 第 1 步：接入材料清单规范
-
-清单回答**「你的后端需要提供什么」**——从用户需要准备的材料出发；不解释槽/Port/registry/
-级联等平台内部机制（用户追问除外）。
-
-**信息源（按序读，勿凭空编造）**：
-
-- 槽位清单与必选性 → `packages/<module>/tbox.module.json`（`declare.consumes` 消费需求、
-  `declare.owns` 服务归属）；
-- 接口签名细节 → 消费模块 `src/server/ports.ts` 或 `packages/contracts-mall/src/services/<域>.ts`
-  （每个 Port 方法 = 后端需提供的一个接口）；
-- 该模块接入语义（顺序/依赖/可选降级）→ `packages/<module>/INTEGRATION.md`。
-
-**清单交付项**（每服务一份，模块/应用维度 = 逐服务罗列）：
-
-- 服务槽：展示名 + 一句业务说明；
-- 每个接口（Port 方法）：接口语义（查询什么/写入什么）；入参中来自平台的定位键
-  （如 userId / plateNo——平台传入，你的后端按它定位用户/车辆）；返回**必选**字段与
-  **可选**字段；可选方法（`?` 结尾）缺席时的产品降级行为；
-- 连接材料：API 地址（baseUrl）、认证方式（静态请求头 → `static-headers-v1`；Bearer/
-  自定义签名 → 自定义认证策略）、其他可选连接参数（超时等）；
-- 依赖与顺序：接入该服务前需要先接入的其他服务/模块；`*.snapshot` 聚合槽由底层服务
-  派生——落声明时跳过；
-- 材料收集后仍缺的信息（baseUrl / 认证 / 密钥放置方式）明确列出请用户补充。
-
-**纯询问即停**：用户仅询问「需要提供哪些接口/材料」（未给连接信息）→ 产出清单即停，
-等用户补充材料后再落声明与实施。密钥等敏感值不写进 prompt/代码/明文——经平台凭据
-（`credentialRef`）配置，见 `packages/provider-custom/INTEGRATION.md`「认证与凭据」。
-
-**中文名称寻址**：用户用中文展示名指代（如「会员积分」模块）→ 经 `packages/*/tbox.module.json`
-的 `name`/`id` 或 `tbox-app module list` 解析到模块；解析歧义时向用户确认。
-
-## 声明落点
-
-| 维度 | 绑定（单点） | 激活 | 共享连接参数落点 |
-|---|---|---|---|
-| 指定服务 | `services.<slot>.provider = "provider-custom"` | 节点本身 | 槽/实例级 `config` |
-| 指定模块 | `modules[<install id>].provider = "provider-custom"`（**单点作用于全部 ownedServices**） | owned 槽补 `{}` 通配节点 | `modules[<install id>].config` |
-| 应用 | root `provider = "provider-custom"` | 同左逐槽 | root `config` |
-
-推荐 CLI（等价路径）：`tbox-app provider use provider-custom --module <install id>`（模块）/
-`provider use provider-custom`（应用）/ `provider bind <slot> provider-custom`（服务）。
-
-关键形态约束：
-
-- **绑定与激活正交**：provider 选择单点落绑定层；激活 = `services[<slot>]` 节点在场
-  （`{}` 空槽 = 通配激活，实例差异化再补 instances 键）。只写绑定不写激活 → 服务保持
-  `service-not-configured`（诚实暴露，非错误）。
-- **内联 provider 声明（对象形态）已弃用（v8）**：存量兼容读；迁移 =
-  `tbox-app provider migrate --write`（内联 → provider-custom 统一落点，迁移后 ⚠ 待接入，
-  按 provider-custom/INTEGRATION.md 实施转 ok）。
-- 完整字段语义（各层级联、instances 激活等）单源 = `@tbox.cn/app-contracts` 的
-  integrations-config（zod 校验，与运行时同一解析面）。
-- **provider 名三处一致**（声明/注册/凭据）规则与失败信号见
-  `packages/provider-custom/INTEGRATION.md`「provider 名三处一致」。
-
-## 验收
-
-- `pnpm typecheck && pnpm build` 通过 + `npx --yes @tbox.cn/app-cli module doctor`；
-- 平台重启后该服务的调用不再报 `PROVIDER_NOT_IMPLEMENTED`（resolveService 惰性——
-  调用时观测；doctor 对通配槽凭据不设防，运行时判据为最终裁判）。