@tbox.cn/app-template-agent 0.2.0 → 0.7.4

package/apps/server/src/config/integration.ts

@@ -0,0 +1,81 @@
+/**
+ * Integrations 配置面 loader（integrations v4：绑定组整组继承 + catalog 派生 + 部署实例注册表）。
+ * - `config/integrations.json` 存在即生效（模板缺省 = 全槽 mock，裸跑即完整演示）；
+ *   `TBOX_INTEGRATIONS_FILE` 仅覆盖路径（显式指定真实部署素材）。
+ * - 单文件真源（v4）：部署拓扑（instances 注册表 + defaultInstanceId）与 provider 绑定同文件——
+ *   旧 `config/deployments/development.json` 已退役，stale 防线在装载链 fail-fast
+ *   （mall 家族形态判定：含 malls 键；support 独立体系不受影响）。
+ * - zod 单源 = SDK parseIntegrationsConfig（断言 → strict 校验；拼错键启动即报）；
+ *   控制平面投影 = contracts-mall mallControlPlaneOf（恒返回——无表 = 空平面）。
+ * - 本壳只保留 I/O：占位展开（real-env 统一配置链——缺变量 fail-fast，错误含文件与
+ *   缺失清单）+ DEFAULT_PATH 双态锚点探测（打包形态私有知识，不入 SDK）。
+ * - 与 base 模板同构（双生无同步机制——公共能力先行落位，漂移由生成应用 verify 守护）。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandEnvVars, parseIntegrationsConfig } from '@tbox.cn/app-sdk/server';
+import type { IntegrationsConfig } from '@tbox.cn/app-contracts';
+import { mallControlPlaneOf } from '@app/contracts-mall/server';
+import type { MallDeploymentControlPlane } from '@app/contracts-mall';
+
+// 默认路径 = 应用根 config/integrations.json。双态锚点探测（bundle 打平后 import.meta.url 层级漂移）：
+// dev 态本文件在 src/config/（四层到根）；tsup bundle 态打平进 dist/（三层到根）。
+// 与 CONFIG_DIR（index.ts __dirname 三层，src|dist 同层）不同——本文件 dev 态深一层，逐层向上探测
+// 首个含 config/integrations.json 的应用根（上限四层，两态收敛）。
+const DEFAULT_PATH = (() => {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 4; i++) {
+    const candidate = path.join(dir, 'config', 'integrations.json');
+    if (existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  // 未探测到 → 四层基准路径（loadIntegrations existsSync 判缺席）
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../config/integrations.json');
+})();
+
+export interface LoadedIntegrations {
+  config: IntegrationsConfig;
+  source: string;
+  /** mall 控制平面投影（恒在场——无参考表 = 空平面；装配链零拓扑分支） */
+  controlPlane: MallDeploymentControlPlane;
+}
+
+/**
+ * v4 stale 防线（G1 限 mall 家族）：旧部署控制面文件在场且含 malls 键 → fail-fast
+ * （零消费方——残留即静默丢拓扑，必须显式迁移）；不含 malls 键（非 mall 形态）不阻断。
+ * baseDir 缺省 = 模块位置锚点（双态收敛同 DEFAULT_PATH）；测试注入临时根。
+ */
+export function assertNoStaleDeploymentControlPlane(baseDir?: string): void {
+  let dir = baseDir ?? path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 4; i++) {
+    const candidate = path.join(dir, 'config', 'deployments', 'development.json');
+    if (existsSync(candidate)) {
+      try {
+        const stale = JSON.parse(readFileSync(candidate, 'utf8')) as { malls?: unknown };
+        if (stale && typeof stale === 'object' && 'malls' in stale) {
+          throw new Error(
+            '部署控制面已并入 config/integrations.json（instances 注册表 + defaultInstanceId）——' +
+              '请迁移后删除 config/deployments/development.json（malls → instances[].id/attributes，defaultMallId → defaultInstanceId）',
+          );
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.includes('已并入')) throw e;
+        // 旧文件非法 JSON 不在本防线职责（旧体系已退役）——不阻断启动
+      }
+      return;
+    }
+    dir = path.dirname(dir);
+  }
+}
+
+/** 读取并校验 integrations 配置（文件缺席 → undefined = 槽位解析不启用，模块走探测链） */
+export function loadIntegrations(envPath?: string): LoadedIntegrations | undefined {
+  assertNoStaleDeploymentControlPlane();
+  const p = envPath ?? process.env.TBOX_INTEGRATIONS_FILE ?? DEFAULT_PATH;
+  if (!p || !existsSync(p)) return undefined;
+  // 顺序固定：展开（占位符）→ 断言 → zod（后两步在 parseIntegrationsConfig 内，防线单点）
+  const raw = JSON.parse(expandEnvVars(readFileSync(p, 'utf8'), process.env, p));
+  const config = parseIntegrationsConfig(raw);
+  return { config, source: p, controlPlane: mallControlPlaneOf(config) };
+}

package/apps/server/src/dev.ts

@@ -0,0 +1,81 @@
+/**
+ * vite dev 入口（仅 tsx 运行：pnpm dev；物理不进 tsup bundle——forbid-vite 插件拦截）。
+ * middlewareMode + 单端口：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, isReady } from '@tbox.cn/app-sdk/platform';
+import { createLogger } from '@tbox.cn/app-sdk/server';
+import { app, registerUpgradeDelegate, start } from './app.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverLogger = createLogger('server');
+const clientRoot = path.resolve(__dirname, '../../client');
+
+// HMR WS 独立路径：dev 基础设施命名空间（双下划线呼应 /@vite/*），与业务命名空间（/ws*）
+// 解耦——delegate 只认领此路径，根路径归还业务路由。
+const HMR_WS_PATH = '/__vite_hmr';
+
+// HMR WS hub：永不 listen 的纯事件载体。hmr.server 在场 → vite 不自建 24678 独立端口，
+// 客户端 __HMR_PORT__=null → 按页面同源端口连接（公网端口映射无关）。vite 对 hub 仅
+// on/off('upgrade')（6.4.3 源码实证）；协议常量（vite-hmr/vite-ping）与认领路径
+// posix.join(base, hmr.path) 是 vite 契约面，由 scripts/smoke-dev-hmr.sh 守护。
+const hmrHub = createServer();
+
+const vite = await createViteServer({
+  root: clientRoot,
+  server: {
+    middlewareMode: true,
+    // 沙箱域名 Host 透传放行（dev-only；dist 物理不含 vite）。安全边界四条
+    // （cors() 既存全开 / 代理收敛公网入口 / token 轴不变 / /@fs 另有 deny）见 Agent Note 2026-09-09。
+    allowedHosts: true,
+    // /@fs 加固：默认 deny 不含服务端凭证目录（client 永不需要经 /@fs 读它）
+    fs: { deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**', '**/config/credentials/**'] },
+    hmr: { server: hmrHub, path: HMR_WS_PATH },
+  },
+  // custom：不加 Vite 自己的 SPA fallback，由下方 app.use('*') 统一处理 HTML 路由
+  appType: 'custom',
+  optimizeDeps: { entries: [] },
+});
+
+// 升级委托：与 vite hmrServerWsListener 同条件（协议整串匹配 + pathname === 认领路径）。
+// viteHmrPath 与 vite 同一 resolved config、同式 posix.join 派生——恒等无漂移（字面比较
+// 在未来设 base 时有悬挂方向：delegate 认领转发而 vite 不接，socket 无人销毁）。协议轴
+// 必须保留：hub 是纯事件载体无 destroy，仅匹配 path 的非 vite 协议升级会转发后无人认领。
+// 未认领的升级回落 app 路由（业务 /ws、根路径归还业务、fail-fast 语义不变）。
+const viteHmrPath = path.posix.join(vite.config.base, HMR_WS_PATH);
+registerUpgradeDelegate((request, socket, head) => {
+  const protocol = request.headers['sec-websocket-protocol'];
+  if (protocol !== 'vite-hmr' && protocol !== 'vite-ping') return false;
+  const { pathname } = new URL(request.url || '/', 'http://localhost');
+  if (pathname !== viteHmrPath) return false;
+  hmrHub.emit('upgrade', request, socket, head);
+  return true;
+});
+
+// Vite 中间件：静态资源、模块转换、HMR（装配已在 ./app.js import 期完成）
+app.use(vite.middlewares);
+
+// HTML 路由兜底：非 /api、/ws 一律返回 index.html（经 Vite 转换 + inspector 注入）
+app.use('*', async (req, res, next) => {
+  if (req.originalUrl.startsWith('/api') || req.originalUrl.startsWith('/ws')) {
+    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);
+  }
+});
+
+start().catch((err) => {
+  serverLogger.error('Failed to start:', err);
+  process.exit(1);
+});

package/apps/server/src/index.ts

@@ -1,388 +1,35 @@
-import express from 'express';
-import cors from 'cors';
-import { createServer } from 'http';
+/**
+ * 静态入口（唯一 tsup entry → dist/index.js）：express.static 供给 client/dist。
+ * dist 形态恒静态——vite dev 仅存在于 src/dev.ts（tsx 运行，禁入 tsup entry，
+ * tsup.config.ts forbid-vite 插件拦截）。NODE_ENV 只影响 SDK 安全姿态（dev-login/密钥链）。
+ */
 import path from 'path';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'url';
-import { registerAll } from './modules.js';
-import {
-  createWsServer,
-  createServerContext,
-  createEngineFromContext,
-  tboxTraceExporter,
-  extractImageUrls,
-  TBOX_FILE_URL_PREFIX,
-  createAuthRuntime,
-  createPlatformApiRouter,
-  createTtsProxy,
-  createModelProvider,
-  createPluginIntegration,
-  ConversationService,
-  loadLocalSkills,
-  resolveSkillMode,
-  resolvePreToolTimeout,
-  buildMessageInputs,
-} from '@tbox.cn/app-sdk/server';
-import { installInspector, injectScript, isReady } from '@tbox.cn/app-sdk/platform';
-import { registerAppTools } from './app-tools.js';
-import { APP_PRE_TOOLS } from './pre-tools.js';
-import { INTENT_ROUTES, createAppIntentDispatcher } from './intent-routes.js';
-import { loadDeploymentControlPlane } from './config/deployment.js';
-import { createFeatureGate } from './config/feature-gate.js';
-// 011 S2/S3：mall 装配原语（条件装配——未配置部署文件时零引用）
-import {
-  createScopeSessionRegistry,
-  createActionGrantService,
-  createComponentActionDispatcher,
-  createEffectRuntime,
-  createProviderRegistry,
-  createAuthenticatedTransportFactory,
-  createAuthStrategyRegistry,
-  createEnvironmentSecretProvider,
-  createInMemoryStateStore,
-  attachCardActionTokens,
-} from '@tbox.cn/app-sdk/server';
+import express from 'express';
+import { createLogger } from '@tbox.cn/app-sdk/server';
+import { app, start } from './app.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PORT = Number(process.env.PORT) || 8000;
-const HOST = process.env.HOST || '0.0.0.0';
-const isProduction = process.env.NODE_ENV === 'production';
-
-const AI_MODEL_NAME = process.env.APP_AI_MODEL_NAME || '';
-
-const AGENT_CONFIG = {
-  instructions: [
-    '你是一个通用 AI 助手。可以回答用户问题，也可以调用工具获取信息。用简洁、清晰的语言回复。',
-    '调用业务工具时正常按其 schema 传参，拿到结果后用自然语言回复用户；',
-    '是否向用户呈现卡片由系统自动决定，你不需要也不应该主动渲染 UI。',
-  ].join('\n'),
-};
-
-// 平台能力装配（003/006 平台轴，已下沉 @tbox.cn/app-sdk/server）
-const auth = createAuthRuntime();
-const { getModel } = createModelProvider();
-const pluginTools = createPluginIntegration();
-
-/** 懒初始化单例 ConversationService */
-let _conversationService: ConversationService | null = null;
-function getConversationService(): ConversationService | null {
-  if (!_conversationService) {
-    const apiKey = process.env.TBOX_API_KEY;
-    if (!apiKey) return null;
-    _conversationService = new ConversationService(apiKey);
-  }
-  return _conversationService;
-}
-
-// 进程级最后防线
-process.on('unhandledRejection', (reason) => {
-  console.error('[server] unhandledRejection:', reason);
-});
-process.on('uncaughtException', (err) => {
-  console.error('[server] uncaughtException:', err);
-});
-
-const app = express();
-app.use(cors());
-app.use(express.json());
+const serverLogger = createLogger('server');
 
-// 🔒 平台基础设施 — 禁止 AI 删除或修改（@infrastructure-locked）
-installInspector(app);
-
-// 非 prod 默认开启 dev-login：对暴露公网的实例给出可见警示（生产必须 NODE_ENV=production）
-if (auth.config.devLoginEnabled) {
-  console.warn(
-    '[AUTH] dev-login 已开启（非 production 默认）。若本实例暴露公网，请设 NODE_ENV=production 或 AUTH_DEV_LOGIN_DISABLED=true。',
+const clientDistPath = path.join(__dirname, '../../client/dist');
+if (!existsSync(path.join(clientDistPath, 'index.html'))) {
+  serverLogger.warn(
+    `client/dist 缺失（${clientDistPath}）——页面将不可用（API/WS 不受影响）；请先执行 pnpm build:client`,
   );
 }
 
-// 自注册闭环：模块路由挂载到 /api/m/<moduleId>/（在 apiRouter 之前，避免被 /api 兜底 404 截获）
-// ctx 为模块级单例：registerAll 在 start() 内执行，ApiRouteRegistry 共享 root 保证延迟注册即时生效
-// 011 L1：条件 mall 装配——DEPLOYMENT_CONTROL_PLANE_PATH 存在时注入 runtime/providers/state
-const deployment = loadDeploymentControlPlane();
-// 011 B2：可变认证策略注册表——模块 register 期注册（joycity 签名策略），transportFactory 同引用
-const authStrategies = createAuthStrategyRegistry();
-
-const ctx = createServerContext({
-  ...(deployment
-    ? {
-        state: createInMemoryStateStore(),
-        runtime: {
-          // 011 D10/S5/评审 M2：门控 = 执行期护栏——组件未声明 enabledFeatures = 全启用
-          // （与 MallDeploymentComponent 语义一致；声明了 → 白名单包含才放行）
-          isFeatureEnabled: createFeatureGate(deployment.controlPlane.deployment.components),
-          config: deployment.controlPlane as unknown as Record<string, unknown>,
-        },
-        providers: createProviderRegistry({
-          instances: deployment.controlPlane.providerInstances,
-          // 011 评审 7.1：credentialType 真源参数化——providerTemplates 声明优先，
-          // 缺省回退从实例派生 + joycity-c-signed-v1（向后兼容既有部署配置）
-          templates:
-            deployment.controlPlane.providerTemplates ??
-            deployment.controlPlane.providerInstances.map((i: { providerTemplateId: string }) => ({
-              providerTemplateId: i.providerTemplateId,
-              credentialType: 'joycity-c-signed-v1',
-            })),
-          transportFactory: createAuthenticatedTransportFactory({
-            strategies: authStrategies,
-            secretProvider: createEnvironmentSecretProvider({
-              source: process.env as Record<string, string | undefined>,
-              allowedHeaderNames: ['content-type', 'sign', 'timestamp', 'publickey', 'x-api-key'],
-              production: isProduction,
-            }),
-          }),
-        }),
-      }
-    : {}),
-  authStrategies,
-});
-
-// 全局 /api 鉴权（H2 挂载顺序契约）：除 public（login/dev-login/health）外一律要求 Bearer token；
-// optional 模式缺失 token → 匿名身份（写通道仍被 action gateway 拒绝）
-// ⚠️ 必须先于 /api/m、/api/action、createPlatformApiRouter 挂载，保证全 API 面受鉴权约束
-app.use('/api', auth.middleware);
-
-app.use('/api/m', ctx.routes.mount());
-
-// 业务动作网关（004 D3/C2）：POST /api/action — SDK 黑盒唯一写入口（幂等/防重放/签名槽位；
-// 006 D11：匿名写拒绝，不随 AUTH_MODE 变）
-app.use('/api/action', ctx.actions.middleware());
-
-// API 路由（平台路由面：auth/health/tbox/conversation + 404 兜底；卡片恢复内部化）
-app.use('/api', createPlatformApiRouter({ ctx, auth }));
-
-// 从 ServerContext 构造 ChatEngine（自注册闭环组装端）
-async function createEngine(
-  extra?: { cardActionAttacher: (payload: import('@tbox.cn/app-contracts').TboxCardPayload, sessionId: string) => Promise<import('@tbox.cn/app-contracts').TboxCardPayload> },
-) {
-  // 009：应用级本地 skills（SKILL.md 目录格式，dev/dist 路径恒等 = src/dist 平级 + __dirname 绝对解析）
-  const appSkills = await loadLocalSkills(path.resolve(__dirname, '../skills'));
-  const skillMode = resolveSkillMode(process.env.TBOX_SKILL_MODE);
-  // 010：单次解析（引擎选项与启动日志同源，非法值只 warn 一次）
-  const preToolTimeoutMs = resolvePreToolTimeout(process.env.TBOX_PRE_TOOL_TIMEOUT_MS);
-
-  const engine = await createEngineFromContext(ctx, {
-    instructions: AGENT_CONFIG.instructions,
-    model: getModel(AI_MODEL_NAME),
-    traceExporter: tboxTraceExporter,
-    modelName: AI_MODEL_NAME,
-    fileUrlPrefix: TBOX_FILE_URL_PREFIX,
-    // 009：双模式全局配置（accelerated 默认：本地路由命中 → reminder 注入当前轮，零额外 LLM 轮次；
-    // progressive：全量注册 InlineSkill，模型渐进 skill_read）
-    skillMode,
-    skills: appSkills,
-    // 010：前置工具加速（应用级声明 + 单工具预算；TBOX_PRE_TOOL_TIMEOUT_MS=0 整体禁用）
-    preTools: APP_PRE_TOOLS,
-    preToolTimeoutMs,
-    // 011 B3：卡片动作 token 签发器（mall 装配时注入）
-    cardActionAttacher: extra?.cardActionAttacher,
-    // B21：意图路由接线（业务意图表 + handlerDispatch）
-    intentRoutes: INTENT_ROUTES,
-    handlerDispatch: createAppIntentDispatcher(ctx),
-    loadPlugins: async () => {
-      const loaded = await pluginTools.loadTools({
-        reservedToolIds: Object.keys(ctx.tools.getAll()),
-      });
-      return { tools: loaded.tools, references: loaded.references };
-    },
-    saveMessage: async ({ conversationId, query, answer, mediaItems, outerBusinessId, cards, skills, preTools }) => {
-      const agentId = process.env.TBOX_APP_ID;
-      const service = getConversationService();
-      if (!service || !agentId) return undefined;
-      const imageUrls = extractImageUrls(mediaItems, TBOX_FILE_URL_PREFIX);
-      // P3 W1：卡片快照随消息持久化（MessageEmbedded，004 D1）。
-      // 009 D10：skill 加载记录随消息持久化（inputs.skills，前端历史表达重建）。
-      // 010：前置工具记录随消息持久化（inputs.preTools，前端历史表达重建）。
-      // inputs「非空才加」组装规则已下沉 SDK buildMessageInputs（010 S3）。
-      // 若平台拒绝 inputs（V1 验证失败），此处切换为 extraParams 字符串或 FileCardPersistenceBackend 落盘。
-      const inputs = buildMessageInputs({ cards, skills, preTools });
-      return await service.saveMessage({
-        conversationId,
-        agentId,
-        query,
-        answer,
-        ...(outerBusinessId && { outerBusinessId }),
-        ...(imageUrls.length > 0 && {
-          multiModalInputs: { imageUrls },
-        }),
-        ...(inputs && { inputs }),
-      });
-    },
-  });
-
-  // 009：启动日志诊断（仅名称/描述/路由词，不含 SOP 内容）
-  console.log(
-    `[SKILL] mode=${skillMode} skills=${engine.listSkills().map((s) => s.name).join(',') || '(none)'}`,
-  );
-  // 010：前置工具诊断（仅 toolId/描述/路由形态，不含 decide 逻辑）
-  console.log(
-    `[PRETOOL] timeoutMs=${preToolTimeoutMs} preTools=${engine.listPreTools().map((d) => d.toolId).join(',') || '(none)'}`,
-  );
-  return engine;
-}
-
-if (isProduction) {
-  const clientDistPath = path.join(__dirname, '../../client/dist');
-  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' });
-    }
-  });
-} else {
-  // 开发环境：Vite middlewareMode 单进程
-  const { createServer: createViteServer } = await import('vite');
-  const { readFile } = await import('fs/promises');
-  const clientRoot = path.resolve(__dirname, '../../client');
-  const vite = await createViteServer({
-    root: clientRoot,
-    server: { middlewareMode: true },
-    // custom：不添加 Vite 自己的 SPA fallback / 404 处理器，
-    // 由下方 app.use('*') 统一处理 HTML 路由，避免 Vite 的 404 先返回。
-    appType: 'custom',
-    optimizeDeps: { entries: [] },
-  });
-
-  // Vite 中间件：处理静态资源、模块转换、HMR
-  app.use(vite.middlewares);
-
-  // HTML 路由兜底：非 /api、/ws 的请求一律返回 index.html（经 Vite 转换 + inspector 注入）
-  app.use('*', async (req, res, next) => {
-    if (req.originalUrl.startsWith('/api') || req.originalUrl.startsWith('/ws')) {
-      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 httpServer = createServer(app);
-
-async function start() {
-  // 011 S6：mall 装配 + 生产环境缺动作授权密钥 → 启动期提示（签发路径运行时兜底报错）
-  if (deployment && isProduction && !process.env.ACTION_TOKEN_SECRET && !process.env.AUTH_TOKEN_SECRET) {
-    console.warn('[ACTION] 生产环境未配置 ACTION_TOKEN_SECRET/AUTH_TOKEN_SECRET——卡片写动作 token 签发将失败');
-  }
-
-  // 注册业务模块（自注册闭环）
-  await registerAll(ctx);
-
-  // 模板演示工具（apps 级工具，P3 建议迁入模块）：不参与模块体系，经统一注册面注册
-  // （010：start() 与 cli/collect-registry.ts 双处同调，防注册面失同步）
-  registerAppTools(ctx);
-
-  // 011 F2/E2：mall 装配（条件）——scope 会话 + 动作授权先行（engine attacher 依赖）
-  const scopeSessions: ReturnType<typeof createScopeSessionRegistry> | undefined = deployment
-    ? createScopeSessionRegistry({
-        extractScopeKey: deployment.assembly.extractScopeKey,
-        validateScope: deployment.assembly.validateScope,
-        buildScope: deployment.assembly.buildScope,
-      })
-    : undefined;
-  const grants = scopeSessions ? createActionGrantService({ store: ctx.state }) : undefined;
-
-  // 011 B3：卡片动作 token 签发（build → attach → send；sessionId 引擎登记、scope 经 sessions 查）
-  const cardActionAttacher = grants && scopeSessions
-    ? async (
-        payload: import('@tbox.cn/app-contracts').TboxCardPayload,
-        sessionId: string,
-      ): Promise<import('@tbox.cn/app-contracts').TboxCardPayload> => {
-        const session = scopeSessions.get(sessionId);
-        if (!session) return payload;
-        return attachCardActionTokens({
-          payload,
-          actions: ctx.cardActions,
-          grants: grants,
-          sessionId: session.sessionId,
-          scope: session.scopeFlat,
-        });
-      }
-    : undefined;
-  const engine = await createEngine(cardActionAttacher ? { cardActionAttacher } : undefined);
-
-  // 011 F2/E2：组件动作分发（依赖 scopeSessions/grants）
-  let componentActions: ReturnType<typeof createComponentActionDispatcher> | undefined;
-  if (deployment && scopeSessions && grants) {
-    componentActions = createComponentActionDispatcher({
-      grants,
-      sessions: scopeSessions,
-      state: ctx.state,
-      actions: ctx.cardActions,
-      cardRegistry: ctx.cards.getAll(),
-      // 011 E5/J7：alipay 授权宿主处理器——二期占位（authCode 回传通道未实现）
-      effects: createEffectRuntime({
-        handleAlipayAuthorization: async () => {
-          console.warn('[ALIPAY] 授权回调通道二期（authCode 回传 + resultActionId 补签未实现），授权效果未执行');
-        },
-      }),
-      extractScopeKey: deployment.assembly.extractScopeKey,
-    });
-    for (const action of ctx.cardActions.getAll().values()) {
-      componentActions.register(action);
-    }
+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' });
   }
-
-  const chatWss = createWsServer(engine, {
-    auth: auth.wsAuth,
-    ...(scopeSessions
-      ? {
-          scopeSessions,
-          ...(componentActions ? { componentActions } : {}),
-          chatConfig: {
-            quickCommands: [
-              { label: '找美食', prompt: '帮我找商场里的美食' },
-              { label: '会员积分', prompt: '我的会员积分是多少' },
-            ],
-            enableImageUpload: true,
-          },
-        }
-      : {}),
-  });
-  const ttsWss = createTtsProxy();
-
-  httpServer.on('error', (err: NodeJS.ErrnoException) => {
-    if (err.code === 'EADDRINUSE') {
-      console.error(`[server] Port ${PORT} is already in use.`);
-    } else if (err.code === 'EACCES') {
-      console.error(`[server] Permission denied while binding ${HOST}:${PORT}.`);
-    } else {
-      console.error('[server] Failed to start HTTP server:', err);
-    }
-    process.exit(1);
-  });
-
-  httpServer.on('upgrade', (request, socket, head) => {
-    socket.on('error', (e) => console.warn('[upgrade] socket error:', e.message));
-    const { pathname } = new URL(request.url || '/', 'http://localhost');
-
-    if (pathname === '/ws') {
-      chatWss.handleUpgrade(request, socket, head, (ws) => {
-        chatWss.emit('connection', ws, request);
-      });
-    } else if (pathname === '/ws/tts') {
-      ttsWss.handleUpgrade(request, socket, head, (ws) => {
-        ttsWss.emit('connection', ws, request);
-      });
-    } else {
-      socket.destroy();
-    }
-  });
-
-  httpServer.listen(PORT, HOST, () => {
-    console.log(`🚀 Server running at http://${HOST}:${PORT}`);
-    console.log(`📡 WebSocket endpoint: ws://${HOST}:${PORT}/ws`);
-    console.log(`🔊 TTS endpoint: ws://${HOST}:${PORT}/ws/tts`);
-  });
-}
+});
 
 start().catch((err) => {
-  console.error('[server] Failed to start:', err);
+  serverLogger.error('Failed to start:', err);
   process.exit(1);
-});
+});

package/apps/server/src/intent-routes.ts

@@ -2,9 +2,10 @@ import type { IntentRoute, HandlerResult, ServerContext } from '@tbox.cn/app-sdk
 
 /**
  * 业务意图表（B21：intent-framework hybrid 接线——SDK 框架 + 源码意图表，003 §3.3）。
- * chat() 先 matchIntent（最长关键词命中）；命中则经 handlerDispatch 出卡/文字，不走 LLM。
+ * chat() 先 matchIntent（统一检索层 BM25 竞争：长词 OR ≥2 token 规则，score 降序 + id 字典序）；
+ * handler 缺省直接出卡/文字，也可用 continueWith 续接完整 Agent。
  *
- * 示例（商圈应用启用积分抵扣停车意图）：
+ * 示例（商圈应用启用积分抵扣停车意图，handlerId 对应已装模块的 handler id）：
  *   { id: 'points-parking', keywords: ['积分抵扣停车', '停车抵扣'], handlerId: 'points-parking', action: 'run' }
  * 本模板默认空表（保持 LLM + tool calling 主路径）；业务方在此声明意图路由。
  */
@@ -17,7 +18,13 @@ export const INTENT_ROUTES: IntentRoute[] = [];
  * P2-3：用户原始输入以 payload.content 传入，handler 侧可经 payload.content 取用。
  */
 export function createAppIntentDispatcher(ctx: ServerContext) {
-  return async (route: IntentRoute, content: string): Promise<HandlerResult | undefined> => {
-    return ctx.handlers.dispatch(route.handlerId, route.action, { content }, ctx);
+  // 上下文统一化：第三参 reqCtx（引擎意图分发注入的运行上下文）透传 handlers.dispatch
+  // 第五参——意图 handler 经 handle 第四参消费；断链 = 意图路径恒「缺少运行上下文」。
+  return async (
+    route: IntentRoute,
+    content: string,
+    reqCtx?: import('@tbox.cn/app-contracts').RequestContext,
+  ): Promise<HandlerResult | undefined> => {
+    return ctx.handlers.dispatch(route.handlerId, route.action, { content }, ctx, reqCtx);
   };
 }

package/apps/server/src/modules.ts

@@ -11,11 +11,14 @@ import type { ServerContext, InferModuleCards } from '@tbox.cn/app-sdk/server';
 // SDK 装配框架（非模块行，CLI 增量维护保留非标行）
 import { registerServerModules } from '@tbox.cn/app-sdk/server';
 import { serverModule as moduleWeather } from '@app/module-weather/server';
+import { serverModule as providerCustom } from '@app/provider-custom/server';
 // @tbox:imports-end
 
 // @tbox:register-begin
+// base 模板出厂预装 provider-custom（自定义 API 落点）+ weather 演示模块
 const modules = [
   moduleWeather,
+  providerCustom,
 ];
 // @tbox:register-end