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

package/apps/server/src/app.ts

@@ -0,0 +1,452 @@
+/**
+ * 装配主体（模块级单例）：express 链、/api 路由、createEngine、WS、start()/listen、进程防线。
+ * 客户端供给由入口决定——静态产物见 index.ts（唯一 tsup entry），vite dev 见 dev.ts（仅 tsx）。
+ * import 本模块即完成装配（与旧单文件入口时序等价：listen 仍在 start() 内最后发生）。
+ */
+import express from 'express';
+import cors from 'cors';
+import { createServer, type IncomingMessage } from 'http';
+import type { Duplex } from 'node:stream';
+import path from 'path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'url';
+import { registerAll } from './modules.js';
+
+// ===== 模板日志（@tbox.cn/app-sdk/server createLogger：本地时间 + LEVEL + [tag] + req/conv 尾缀） =====
+import { createLogger } from '@tbox.cn/app-sdk/server';
+const serverLogger = createLogger('server');
+const authLogger = createLogger('AUTH');
+const skillLogger = createLogger('SKILL');
+const preToolLogger = createLogger('PRETOOL');
+const actionLogger = createLogger('ACTION');
+const upgradeLogger = createLogger('upgrade');
+import {
+  createWsServer,
+  createServerContext,
+  createEngineFromContext,
+  loadProviderCatalog,
+  tboxTraceExporter,
+  extractImageUrls,
+  TBOX_FILE_URL_PREFIX,
+  createAuthRuntime,
+  createPlatformApiRouter,
+  createTtsProxy,
+  createModelProvider,
+  createPluginIntegration,
+  ConversationService,
+  loadLocalSkills,
+  resolveSkillMode,
+  resolvePreToolTimeout,
+  resolveToolDebug,
+  resolveEarlyToolExecution,
+  resolveMemoryStoreGuarded,
+  withRecallCache,
+  buildMessageInputs,
+  loadChatConfig,
+  loadAgentPromptConfig,
+  toWsChatConfig,
+  installTboxDev,
+} from '@tbox.cn/app-sdk/server';
+import { installInspector } 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 { deploymentFromIntegrations, buildDefaultMallContext } from './config/deployment.js';
+import { loadIntegrations } from './config/integration.js';
+// 011 S2/S3：mall 装配原语（条件装配——未配置部署文件时零引用）
+import {
+  createScopeSessionRegistry,
+  createActionGrantService,
+  createModuleActionDispatcher,
+  createEffectRuntime,
+  createIntegrationsRegistry,
+  createAuthStrategyRegistry,
+  createEnvironmentSecretProvider,
+  attachCardActionTokens,
+} from '@tbox.cn/app-sdk/server';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// chat.json 配置目录（credentials 同款锚定三元式）：dev 态 TBOX_CONFIG_DIR 指档位目录，
+// 否则应用根 config/。src|dist → server → apps → 应用根（与 mall entry 锚点同构）。
+const CONFIG_DIR = process.env.TBOX_CONFIG_DIR
+  ? path.resolve(process.env.TBOX_CONFIG_DIR)
+  : path.resolve(__dirname, '../../../config');
+const PORT = Number(process.env.PORT) || 8000;
+const HOST = process.env.HOST || '0.0.0.0';
+const isProduction = process.env.NODE_ENV === 'production';
+// 018 tool-debug：模块级单次解析双喂（engine 发射门控 + ws-server HELLO_ACK 旗标同值同源；
+// 非法值只 warn 一次——对齐 skillMode/preToolTimeout 解析先例）
+const toolDebug = resolveToolDebug(process.env.TBOX_TOOL_DEBUG, process.env.NODE_ENV);
+// PR-2 尽早工具执行（缺省 off）：多工具轮参数流完即预执行白名单查询工具，
+// 收益依赖 config/llm_provider.json parallelToolCalls 开启；单工具轮行为等价现状
+const earlyToolExecution = resolveEarlyToolExecution(process.env.TBOX_EARLY_TOOL_EXECUTION);
+
+/** 应用根探测（apps/server cwd → 逐层向上找 .tbox/app.json；dev/bundle 双态收敛） */
+function appRoot(): string {
+  let dir = path.resolve(process.cwd());
+  for (let i = 0; i < 4; i++) {
+    if (existsSync(path.join(dir, '.tbox', 'app.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(process.cwd());
+}
+
+const AI_MODEL_NAME = process.env.APP_AI_MODEL_NAME || '';
+
+// agent 提示词（config/agent.jsonc；未配置 = SDK 默认兜底；读取一次，改文件需重启生效）
+const AGENT_PROMPT = loadAgentPromptConfig(CONFIG_DIR);
+
+// 平台能力装配（003/006 平台轴，已下沉 @tbox.cn/app-sdk/server）。
+// 011 L1 + F2/F3：装配序 integrations → deployment 派生 → auth（v4：部署拓扑并入
+// integrations.json 单文件真源——integrations 先装，deployment 由其投影派生；auth 构造期
+// 直引 validateContext）。上下文统一化 Stage 2：auth 的 validateContext 域校验注入（HTTP
+// body.context 伪冒防线：mallId 形状校验 → 403）与 scopeDefaults 同源。
+const integrationsConfig = loadIntegrations();
+const deployment = integrationsConfig ? deploymentFromIntegrations(integrationsConfig) : undefined;
+const auth = createAuthRuntime(undefined, {
+  // validateContext 只在全局面生效（login/dev-login 的 body.context 走 login-routes 独立归一化）
+  ...(deployment ? { validateContext: deployment.assembly.validateScope } : {}),
+});
+const { getModel } = createModelProvider();
+const pluginTools = createPluginIntegration();
+
+// 017：长期记忆（默认 inmemory 开启；TBOX_MEMORY_STORE=off 逃生舱 / knowledge 需 KB_ID+DOC_ID+API_KEY）。
+// 单实例双消费：engine（recall + 三工具）与 /api/memory 管理面共享同一存储。
+// 017 M4：KB 校验三态（TBOX_MEMORY_KB_VALIDATE：1=异步降级不阻塞启动 / strict=同步 fail-fast /
+// 未设置不校验）——gated store 统一收口，装配面恒定（INV-D），降级只发生在调用执行时。
+const memoryBase = await resolveMemoryStoreGuarded({
+  store: process.env.TBOX_MEMORY_STORE,
+  kbId: process.env.TBOX_MEMORY_KB_ID,
+  kbDocId: process.env.TBOX_MEMORY_KB_DOC_ID,
+  kbBaseUrl: process.env.TBOX_MEMORY_KB_BASE_URL,
+  kbCookie: process.env.TBOX_MEMORY_KB_COOKIE,
+  validate: process.env.TBOX_MEMORY_KB_VALIDATE,
+  validateTimeoutMs: process.env.TBOX_MEMORY_KB_VALIDATE_TIMEOUT_MS,
+});
+// B4：recall 缓存装饰器（list 60s TTL + 空结果负缓存短路——零记忆用户 recall <10ms）。
+// 组合序：withRecallCache 包 gated 外层（gate 失败穿透不污染缓存）；单实例双消费
+// （engine recall + 三工具 + /api/memory 管理面）共享 wrapped 实例——save 写失效钩子生效。
+const memory = {
+  ...memoryBase,
+  ...(memoryBase.store ? { store: withRecallCache(memoryBase.store) } : {}),
+};
+
+/** 懒初始化单例 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) => {
+  serverLogger.error('unhandledRejection:', reason);
+});
+process.on('uncaughtException', (err) => {
+  serverLogger.error('uncaughtException:', err);
+});
+
+export const app = express();
+app.use(cors());
+app.use(express.json());
+
+// 🔒 平台基础设施 — 禁止 AI 删除或修改（@infrastructure-locked）
+installInspector(app);
+
+// 非 prod 默认开启 dev-login：对暴露公网的实例给出可见警示（生产必须 NODE_ENV=production）
+if (auth.config.devLoginEnabled) {
+  authLogger.warn(
+    'dev-login 已开启（非 production 默认）。若本实例暴露公网，请设 NODE_ENV=production 或 AUTH_DEV_LOGIN_DISABLED=true。',
+  );
+}
+
+// 自注册闭环：模块路由挂载到 /api/m/<moduleId>/（在 apiRouter 之前，避免被 /api 兜底 404 截获）
+// ctx 为模块级单例：registerAll 在 start() 内执行，ApiRouteRegistry 共享 root 保证延迟注册即时生效
+// 011 L1 + F2/F3：控制面纯两键（malls + defaultMallId）——旧 ProviderRegistry 链已拆除，
+// provider 绑定唯一真源 = config/integrations.json（槽位轴；与 mall 模板同构）；
+// F2：scopeDefaults 中立注入 + authExchanges 同引用（provider 包 register 期自注册换码器）
+const providerCatalog = loadProviderCatalog(appRoot());
+const scopeDefaults = deployment?.controlPlane.defaultMallId
+  ? { defaultMallId: deployment.controlPlane.defaultMallId }
+  : undefined;
+// 011 B2：可变认证策略注册表——模块 register 期注册（厂商签名策略），transportFactory 同引用
+const authStrategies = createAuthStrategyRegistry();
+
+// provider 拆包 F2/F3：integrations 槽位解析轴（config/integrations.json 存在即生效；
+// 缺席 → undefined，模块槽解析与换码链 fail-fast 显性暴露）
+// instanceIdOf 注入 mall 语义（SDK 零领域铁律——mallId 派生归模板层）
+// root config.miniAppId（016 默认商圈兜底拼装用；与 mall 模板同构——env 注入形态无参考表可查）
+const rootMiniAppId =
+  typeof integrationsConfig?.config.config?.miniAppId === 'string' && integrationsConfig.config.config.miniAppId
+    ? integrationsConfig.config.config.miniAppId
+    : undefined;
+const integrations = integrationsConfig
+  ? createIntegrationsRegistry({
+      integrations: integrationsConfig.config,
+      // catalog 真源 = 应用根 .tbox/app.json（上方无条件装载）
+      catalog: providerCatalog,
+      authStrategies,
+      secretProvider: createEnvironmentSecretProvider({
+        source: process.env as Record<string, string | undefined>,
+        // 文件通道（v2）：config/credentials/ 凭据文件优先（ref = 文件名 stem 直引），env 兜底。
+        // dev 态 TBOX_CONFIG_DIR 指档位目录 → files 指档位凭据目录；PR-2 前目录缺席零行为。
+        ...(process.env.TBOX_CONFIG_DIR
+          ? { files: path.resolve(process.env.TBOX_CONFIG_DIR, 'credentials') }
+          : { files: path.resolve(__dirname, '../../../config/credentials') }),
+        allowedHeaderNames: ['content-type', 'sign', 'timestamp', 'publickey', 'x-api-key'],
+        production: isProduction,
+      }),
+      instanceIdOf: (scope) => scope.mallId ?? '',
+      // F5 观测轴：provider factory 收到的 transport 统一包外部调用日志（→/← path durMs）
+      logger: createLogger('provider'),
+    })
+  : undefined;
+
+const ctx = createServerContext({
+  authStrategies,
+  authExchanges: auth.exchanges,
+  ...(memory.store ? { memory: memory.store } : {}),
+  ...(integrations ? { integrations } : {}),
+  ...(scopeDefaults ? { scopeDefaults } : {}),
+});
+
+// 全局 /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 [+memory] + 404 兜底；卡片恢复内部化）
+// 017：装配记忆时挂载 /api/memory 管理面（与引擎同源 store）
+app.use('/api', createPlatformApiRouter({ ctx, auth, ...(memory.store ? { memory: memory.store } : {}) }));
+
+// tbox dev 工具族（/_tbox：卡片预览 API + 页面族；dev-only 自门控——NODE_ENV=production
+// 零挂载；import 期注册先于 dev.ts 运行期 vite middleware，路由序恒胜）
+installTboxDev(app, { 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_PROMPT.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,
+    // 018 tool-debug：工具调试视图（memory/silent preTool 前端表达；缺省关）
+    toolDebug,
+    // PR-2 尽早工具执行（缺省 off；env TBOX_EARLY_TOOL_EXECUTION=1 开启）
+    earlyToolExecution,
+    // 017：长期记忆（默认 inmemory；off 时 enabled=false 不装配）
+    ...(memory.enabled && memory.store ? { memory: { store: memory.store } } : {}),
+    // 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 内容）
+  skillLogger.info(
+    `mode=${skillMode} skills=${engine.listSkills().map((s) => s.name).join(',') || '(none)'}`,
+  );
+  // 010：前置工具诊断（仅 toolId/描述/路由形态，不含 decide 逻辑）
+  preToolLogger.info(
+    `timeoutMs=${preToolTimeoutMs} preTools=${engine.listPreTools().map((d) => d.toolId).join(',') || '(none)'}`,
+  );
+  // 017：记忆诊断（装配形态 + 能力面 + 校验模式；recall 配置行由 SDK [MEMORY] 构造期日志输出）
+  const memoryLogger = createLogger('MEMORY');
+  memoryLogger.info(
+    `store=${memory.mode}${memory.store?.capabilities ? ` caps=${Object.entries(memory.store.capabilities).filter(([, v]) => v).map(([k]) => k).join(',') || 'none'}` : ''} validate=${memory.validateMode ?? 'off'}`,
+  );
+  return engine;
+}
+
+const httpServer = createServer(app);
+
+/** dev 态升级扩展点（dev.ts 注册）：返回 true = 已认领，app 路由跳过。生产 bundle 恒空。 */
+export type UpgradeDelegate = (request: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+let upgradeDelegate: UpgradeDelegate | undefined;
+export function registerUpgradeDelegate(delegate: UpgradeDelegate): void {
+  upgradeDelegate = delegate;
+}
+
+export async function start() {
+  // 011 S6：mall 装配 + 生产环境缺动作授权密钥 → 启动期提示（签发路径运行时兜底报错）
+  if (deployment && isProduction && !process.env.ACTION_TOKEN_SECRET && !process.env.AUTH_TOKEN_SECRET) {
+    actionLogger.warn('生产环境未配置 ACTION_TOKEN_SECRET/AUTH_TOKEN_SECRET——卡片动作授权装配将 fail-fast 拒绝启动');
+  }
+
+  // 注册业务模块（自注册闭环）
+  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 moduleActions: ReturnType<typeof createModuleActionDispatcher> | undefined;
+  if (deployment && scopeSessions && grants) {
+    moduleActions = createModuleActionDispatcher({
+      grants,
+      sessions: scopeSessions,
+      state: ctx.state,
+      actions: ctx.cardActions,
+      cardRegistry: ctx.cards.getAll(),
+      // 015 P3：effect 运行时纯投影（payment/authorization 回调补签在 dispatcher step7，
+      // 客户端执行在 SDK host-effect-runner——模板零装配效果链）
+      effects: createEffectRuntime(),
+      extractScopeKey: deployment.assembly.extractScopeKey,
+    });
+    for (const action of ctx.cardActions.getAll().values()) {
+      moduleActions.register(action);
+    }
+  }
+
+  // chat.json 真读（原 scope 分支内 demo 硬编码移除，快捷指令迁入 config/chat.json——与 mall 同构：
+  // 配置单一真源 + settings 运行时下发；chatConfig 无条件传递，非 scope 部署亦发 ack）
+  const loadedChatConfig = loadChatConfig(CONFIG_DIR);
+  const chatWss = createWsServer(engine, {
+    auth: auth.wsAuth,
+    // 018 tool-debug：HELLO_ACK 旗标（仅开启时携带；与 engine.toolDebug 同值同源）
+    toolDebug,
+    ...(scopeSessions
+      ? {
+          scopeSessions,
+          ...(moduleActions ? { moduleActions } : {}),
+          // 016：默认商圈兜底——无 URL 参数访问时服务端补 HELLO context（显式参数优先）；
+          // root config.miniAppId 优先（读源统一，回落 malls[].miniAppId；与 mall 模板同构）
+          ...(deployment
+            ? { defaultContext: buildDefaultMallContext(deployment.controlPlane, rootMiniAppId) }
+            : {}),
+        }
+      : {}),
+    chatConfig: toWsChatConfig(loadedChatConfig),
+  });
+  const ttsWss = createTtsProxy();
+
+  httpServer.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      serverLogger.error(`Port ${PORT} is already in use.`);
+    } else if (err.code === 'EACCES') {
+      serverLogger.error(`Permission denied while binding ${HOST}:${PORT}.`);
+    } else {
+      serverLogger.error('Failed to start HTTP server:', err);
+    }
+    process.exit(1);
+  });
+
+  httpServer.on('upgrade', (request, socket, head) => {
+    socket.on('error', (e) => upgradeLogger.warn('socket error:', e.message));
+    if (upgradeDelegate?.(request, socket, head)) return;
+    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') {
+      // 通道门与 UI 同值同源（chat.json enableTTS 单源）：关态硬拒 upgrade，
+      // 防服务端开着 TTS 代理但 UI 已隐藏按钮的僵尸路径；destroy 于 handleUpgrade 之前
+      if (!loadedChatConfig.enableTTS) {
+        upgradeLogger.warn('TTS disabled (chat.json enableTTS:false) — /ws/tts upgrade rejected');
+        socket.destroy();
+        return;
+      }
+      ttsWss.handleUpgrade(request, socket, head, (ws) => {
+        ttsWss.emit('connection', ws, request);
+      });
+    } else {
+      socket.destroy();
+    }
+  });
+
+  httpServer.listen(PORT, HOST, () => {
+    serverLogger.info(`🚀 Server running at http://${HOST}:${PORT}`);
+    serverLogger.info(`📡 WebSocket endpoint: ws://${HOST}:${PORT}/ws`);
+    serverLogger.info(`🔊 TTS endpoint: ws://${HOST}:${PORT}/ws/tts`);
+  });
+}

package/apps/server/src/cli/collect-registry.ts

@@ -1,15 +1,17 @@
-import { createServerContext, buildToolCardBindings } from '@tbox.cn/app-sdk/server';
+import { createServerContext } from '@tbox.cn/app-sdk/server';
+import type { ToolCardBinding } from '@tbox.cn/agent-plugin/cards';
 import { registerAll } from '../modules.js';
 import { registerAppTools } from '../app-tools.js';
 
 export interface RegistryState {
   staticToolIds: string[];
   cardTypes: string[];
-  bindings: ReturnType<typeof buildToolCardBindings>;
+  /** v2 出卡协议：tool→card 静态绑定退场（出卡由工具出参 cards 运行期声明），恒空数组 */
+  bindings: ToolCardBinding[];
 }
 
 /**
- * 从自注册闭环收集当前注册状态（静态工具 id / cardType / tool→card 绑定）。
+ * 从自注册闭环收集当前注册状态（静态工具 id / cardType）。
  * 供 plugin-doctor / plugin-inspect 复用——替代已删除的手写 tools/registry.ts + cards/registry.ts。
  * 与运行时（apps/server/src/index.ts start()）保持一致的注册面：registerAll + registerAppTools
  * （010：apps 级演示工具统一注册面，双处同调防失同步）。
@@ -18,10 +20,9 @@ export async function collectRegistryState(): Promise<RegistryState> {
   const ctx = createServerContext();
   await registerAll(ctx);
   registerAppTools(ctx); // 与运行时一致（translate + clock 为 apps 级演示工具）
-  const cards = ctx.cards.getAll();
   return {
     staticToolIds: Object.keys(ctx.tools.getAll()),
-    cardTypes: Object.keys(cards),
-    bindings: buildToolCardBindings(cards),
+    cardTypes: Object.keys(ctx.cards.getAll()),
+    bindings: [],
   };
 }

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

@@ -1,81 +1,47 @@
 /**
- * 部署控制平面 loader（011 L2：模板装配点专用）。
- * - DEPLOYMENT_CONTROL_PLANE_PATH 存在 → 读取 + zod 校验 + 无内联密钥断言；
- * - 未配置 → 返回 undefined（模板退化为通用助手形态，非 mall 部署）。
+ * mall 装配派生层（integrations v4：部署拓扑并入 integrations.json——单文件真源；
+ * 与 mall 模板同构，base 无 mallName 包装链）。
+ * - 旧 `config/deployments/development.json` 已退役：stale 防线在 integration.ts 装载链
+ *   （在场且含 malls 键 → error 迁移指引；support 独立体系不受影响）；
+ * - controlPlane 来源 = integration.ts 的 mallControlPlaneOf 投影（attributes 赋义 zod
+ *   单源上收 contracts-mall——本文件不再内嵌 schema）；
  * - mall 语义集中在 contracts-mall（TIER1）；apps 只做装配组合（011 L6 checklist）。
  */
-import { readFileSync } from 'node:fs';
-import { z } from 'zod';
-import {
-  createMallRuntimeAssembly,
-  type MallDeploymentControlPlane,
-  type MallRuntimeAssembly,
-} from '@tbox.cn/app-contracts-mall';
+import { createLogger } from '@tbox.cn/app-sdk/server';
+import { createMallRuntimeAssembly, type MallDeploymentControlPlane, type MallRuntimeAssembly } from '@app/contracts-mall';
+import type { LoadedIntegrations } from './integration.js';
 
-const providerInstanceSchema = z.object({
-  providerInstanceId: z.string().min(1),
-  providerTemplateId: z.string().min(1),
-  scope: z.record(z.string(), z.string()).optional(),
-  config: z.record(z.string(), z.unknown()).optional(),
-  credentialRef: z.string().optional(),
-  credentialVersion: z.string().optional(),
-  enabled: z.boolean(),
-});
-
-const controlPlaneSchema = z.object({
-  deployment: z.object({
-    miniAppId: z.string().min(1),
-    agentId: z.string().min(1),
-    components: z.array(
-      z.object({
-        componentId: z.string().min(1),
-        enabledFeatures: z.array(z.string()).optional(),
-        optional: z.boolean().optional(),
-      }),
-    ),
-  }),
-  malls: z.array(z.object({ mallId: z.string().min(1), name: z.string().min(1) })),
-  providerTemplates: z
-    .array(
-      z.object({
-        providerTemplateId: z.string().min(1),
-        credentialType: z.string().min(1),
-      }),
-    )
-    .optional(),
-  providerInstances: z.array(providerInstanceSchema),
-});
-
-/** 无内联密钥断言（011 L2）：命中敏感键名即拒（部署配置只放引用不放机密） */
-const SECRET_KEY_PATTERN = /api[-_]?key|private[-_]?key|secret|password|token|credential/i;
-
-function assertNoInlineSecrets(config: unknown, path = '$'): void {
-  if (Array.isArray(config)) {
-    config.forEach((item, i) => assertNoInlineSecrets(item, `${path}[${i}]`));
-    return;
-  }
-  if (config && typeof config === 'object') {
-    for (const [k, v] of Object.entries(config as Record<string, unknown>)) {
-      if (SECRET_KEY_PATTERN.test(k)) {
-        throw new Error(`部署配置含疑似内联密钥字段：${path}.${k}（机密只允许经 credentialRef 引用环境变量）`);
-      }
-      assertNoInlineSecrets(v, `${path}.${k}`);
-    }
-  }
-}
+const deploymentLogger = createLogger('DEPLOYMENT');
 
 export interface LoadedDeployment {
   controlPlane: MallDeploymentControlPlane;
   assembly: MallRuntimeAssembly;
 }
 
-/** 读取并校验部署控制平面（路径未配置 → undefined = 非 mall 部署） */
-export function loadDeploymentControlPlane(envPath?: string): LoadedDeployment | undefined {
-  const p = envPath ?? process.env.DEPLOYMENT_CONTROL_PLANE_PATH;
-  if (!p) return undefined;
-  const raw = JSON.parse(readFileSync(p, 'utf8'));
-  assertNoInlineSecrets(raw);
-  const parsed = controlPlaneSchema.parse(raw);
-  const controlPlane = parsed as MallDeploymentControlPlane;
-  return { controlPlane, assembly: createMallRuntimeAssembly(controlPlane) };
+/** integrations 装载产物 → mall 装配（恒投影——无参考表 = 空平面，装配零拓扑分支） */
+export function deploymentFromIntegrations(loaded: LoadedIntegrations): LoadedDeployment {
+  const assembly = createMallRuntimeAssembly(loaded.controlPlane);
+  return { controlPlane: loaded.controlPlane, assembly };
+}
+
+/**
+ * 016：默认商圈 HELLO context（无 URL 参数访问时的服务端兜底；与 mall 模板同构）。
+ * v4 mallId-only 注入（D8/D9）：miniAppId 是尽力回填的展示值，非会话边界——
+ * 读源统一 root config.miniAppId 优先、回落参考表 attributes.miniAppId；双缺不再
+ * 阻断注入（此前 warn-refuse 会造成默认商圈静默失效），按 mallId-only 注入。
+ * 缺省 defaultMallId → undefined（不兜底）。
+ */
+export function buildDefaultMallContext(
+  controlPlane: MallDeploymentControlPlane,
+  rootMiniAppId?: string,
+): Record<string, unknown> | undefined {
+  if (!controlPlane.defaultMallId) return undefined;
+  const mall = controlPlane.malls.find((m) => m.mallId === controlPlane.defaultMallId);
+  const miniAppId = rootMiniAppId ?? mall?.miniAppId;
+  if (!miniAppId) {
+    deploymentLogger.warn(
+      `defaultMallId=${controlPlane.defaultMallId} 无 miniAppId 真源（root config 与参考表双缺）——按 mallId-only 注入默认商圈`,
+    );
+  }
+  return { mall: { mallId: controlPlane.defaultMallId, ...(miniAppId ? { miniAppId } : {}) } };
 }