@tbox.cn/app-template-agent 0.10.11 → 0.10.13

package/ENV.md

@@ -115,6 +115,8 @@ dev/src 与 prod/dist bundle 形态恒等）：
 | `TBOX_LLM_AFFINITY` | 会话亲和大容量旋钮(缺省 on;`=off` 关闭——fetch 头 `X-Affinity-Session` 与 body `prompt_cache_key` 双通道均不注入。best-effort 语义:网关负载可覆盖亲和;排障时若网关对未知 body 字段报错可关) |
 | `TBOX_LLM_CONN_BIND` | per-session 连接绑定旋钮(缺省 on;`=off` 关闭——LLM fetch 回退全局连接池。连接=网关缓存池路由单位:per-session 单连接(120s keep-alive)钉死集群分配,保活跨 run 提升前缀缓存命中;排障时可关) |
 | `TBOX_LLM_COOKIE_AFFINITY` | 网关 cookie 亲和旋钮(缺省 on;`=off` 关闭——不回传网关 set-cookie。回传激活 LB 粘性:连接重建后恢复原集群的通道;best-effort) |
+| `TBOX_SOFA_TRACE` | SOFA 链路标识注入旋钮(缺省 on;`=off` 关注入——出站 `*.tbox.cn` 请求不带 sofa-traceid/traceid 双格式头;作用域进入照常。平台 tracelog 串联排障用,独立回滚) |
+| `TBOX_SOFA_TRACE_HOSTS` | SOFA 注入 host 闸门扩展(逗号分隔 host 后缀,**追加**于缺省 `tbox.cn`;如预发 `agtgw-pre.alipay.com`。dot 锚定匹配,闸外请求字节级不变) |
 
 ## 统一鉴权
 
@@ -171,7 +173,7 @@ dev/src 与 prod/dist bundle 形态恒等）：
 | `MALL_HOME_DEV_SERVICES` | 首页「常用服务」开发测试入口展示开关:`true`/`1` 展示,`false`/`0`/缺席隐藏(fail-closed,正式用户零透出;生产部署不配置即隐藏态)。server 启动期解析,经 `GET /api/m/mall-core/config` 下发前端(响应 `{ showDevServices: boolean }`);env 变更需重启进程。注入走外层 source(档位 env 文件/启动器 scripts/app-dev.mjs),`tbox-app dev` 不注入 env 值 |
 | `HOST` | 服务监听地址(默认 `0.0.0.0`) |
 | `PORT` | 服务监听端口(默认 `8000`) |
-| `TBOX_DEV_TOKEN` | 沙箱 dev server 鉴权 token(方案 W;平台运行时注入,**本地无需设置**):形状 `^[A-Za-z0-9_-]{20,128}$`。在场 → protected 双面裁决——dev 面(凭据 + 浏览器导航/同源信号)完整 vite 能力,static 面(无凭据/跨源子资源)纯 dist + SSE 刷新,零源码泄漏;缺席 → classic(与历史行为字节级等价)。在场但形状不合规 → fail-closed 全 static。配套:`GET /__tbox_dev_hot_reload`(static 面刷新 SSE,凭据无关);HMR WS 凭据走 query(`tbox_dev_token`,页面 bootstrap 自动补参);protected 面 vite `fs.allow` 收窄(client 源 + 工作区依赖真源)+ `fs.deny` 保留 |
+| `TBOX_DEV_TOKEN` | 沙箱 dev server 鉴权 token(方案 W;平台运行时注入,**本地无需设置**):形状 `^[A-Za-z0-9_-]{20,128}$`。在场 → protected 双面裁决——dev 面(凭据 + 浏览器导航/同源信号)完整 vite 能力,static 面(无凭据/跨源子资源)dist 静态 + SPA fallback catch-all(GET/HEAD 未命中恒回入口页,对齐生产)+ SSE 刷新,零源码泄漏;缺席 → classic(与历史行为字节级等价)。在场但形状不合规 → fail-closed 全 static。配套:`GET /__tbox_dev_hot_reload`(static 面刷新 SSE,凭据无关);HMR WS 凭据走 query(`tbox_dev_token`,页面 bootstrap 自动补参);protected 面 vite `fs.allow` 收窄(client 源 + 工作区依赖真源)+ `fs.deny` 保留 |
 | `TBOX_DEV_SSE_KEEPALIVE_MS` | protected 面 SSE 心跳间隔 ms(缺省 15000;smoke-dev-protected.sh 经此覆盖加速断言。非法/缺席回退缺省) |
 
 ## 本地 export 命令块(必需项,可复制)
@@ -208,3 +210,4 @@ export MALL_HOME_DEV_SERVICES=true
 | 页面反复刷新循环 | `dev_build_end` 高频 | touch 型工具循环改文件——排查写入源 |
 | 302 后 requestId 变化对不上 | 前后两条 `dev_face_decision` requestId 不同 | 302 盖戳是独立一跳（box 侧 `dev_token_redirect`），两跳 requestId 各自独立——按 URL 与时序关联 |
 | 本地 protected 直跑模块 403 | `dev_face_decision` reason 正常但 `/@fs` 403 | 构建区（.tbox-dev.local）缺席时 fs.allow 为收窄半径；workspace 真源目录在 allow 内（`packages/`），应用自有文件按收窄语义拒绝 |
+| curl/脚本 GET 任意路径 → 200 入口页（非业务 JSON） | —（无异常日志） | 正常 static 面语义（2026-10-09 起 catch-all 对齐生产）；GET 404 才异常 = dist 缺失（watch 首建窗口/构建失败） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.10.11",
+  "version": "0.10.13",
   "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server。唯一模板（W4 单一模板统一化：缺省空装配 chat 形态；mall 能力经 profiles/mall 加装），能力经 tbox-app module add 模块扩展（shopping-guide/member 等）。",
   "engines": {
     "node": ">=24.0.0 <25.0.0"
@@ -36,7 +36,7 @@
     "typescript-eslint": "8.67.0",
     "eslint-plugin-react-hooks": "5.2.0",
     "vite": "6.4.3",
-    "@tbox.cn/app-sdk-server": "0.22.1"
+    "@tbox.cn/app-sdk-server": "0.24.0"
   },
   "license": "MIT",
   "publishConfig": {

package/packages/agent-ui-kit/src/components/ActionBar/DebugButton.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment happy-dom
+/**
+ * DebugButton postMessage 载荷契约锁（P0 对齐 trace-exporter 行格式锁定先例）：
+ * 载荷形状是 H5 → 平台父窗口的跨系统契约——键名漂移 = 平台侧静默断裂。
+ * conversationId 语义：会话 β 后由服务端经 run 事件 threadId / 历史行下发，
+ * 与 requestId 同点位落位至 message；D2 锁定「缺席 = 键值 undefined 仍发送」
+ * 现状降级形态（平台侧 no-conv 回退依赖此形态）。
+ */
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@tbox.cn/app-agent-sdk-client', () => ({
+  createLogger: () => ({ warn: vi.fn() }),
+}));
+
+import { DebugButton } from './DebugButton';
+
+describe('DebugButton 平台契约（tbox:debug-trace 载荷锁定）', () => {
+  let host: HTMLDivElement;
+  let root: ReturnType<typeof createRoot>;
+  let postSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    // happy-dom 下 window.parent === window：同一函数引用
+    postSpy = vi.fn();
+    window.parent.postMessage = postSpy as unknown as typeof window.postMessage;
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    host.remove();
+  });
+
+  const clickDebug = () => {
+    act(() => {
+      host.querySelector('.tbox-debug-btn')!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+  };
+
+  it('D1 点击 → 载荷全键精确（type/requestId/conversationId/messageId/messageCreatedAt）', () => {
+    act(() => {
+      root.render(<DebugButton requestId="req_1" conversationId="conv_1" messageId="m1" messageCreatedAt={123} />);
+    });
+    clickDebug();
+    expect(postSpy).toHaveBeenCalledTimes(1);
+    expect(postSpy.mock.calls[0]![0]).toEqual({
+      type: 'tbox:debug-trace',
+      requestId: 'req_1',
+      conversationId: 'conv_1',
+      messageId: 'm1',
+      messageCreatedAt: 123,
+    });
+    expect(postSpy.mock.calls[0]![1]).toBe('*');
+  });
+
+  it('D2 conversationId 缺席 → 载荷键恒在场、值为 undefined（现状降级形态锁定）', () => {
+    act(() => {
+      root.render(<DebugButton requestId="req_1" messageId="m2" messageCreatedAt={456} />);
+    });
+    clickDebug();
+    const payload = postSpy.mock.calls[0]![0] as Record<string, unknown>;
+    // 键恒在场（严格区分键存在性——toEqual 对 undefined 键与缺失等价，故断言键集）
+    expect(Object.keys(payload).sort()).toEqual([
+      'conversationId',
+      'messageCreatedAt',
+      'messageId',
+      'requestId',
+      'type',
+    ]);
+    expect(payload.conversationId).toBeUndefined();
+    expect(payload.requestId).toBe('req_1');
+  });
+
+  it('D3 requestId 缺席 → 不渲染（渲染守卫不变）', () => {
+    act(() => {
+      root.render(<DebugButton messageId="m3" />);
+    });
+    expect(host.querySelector('.tbox-debug-btn')).toBeNull();
+  });
+});

package/packages/agent-ui-kit/src/components/ActionBar/index.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment happy-dom
+/**
+ * ActionBar → DebugButton prop 接线守卫（病因学守卫）：
+ * 会话 β（31de86f3）删除 conversationId prop 行零红灯复发——本测试锁定
+ * message.requestId/conversationId 恒透传至 DebugButton（删除任一 prop 行 → 红）。
+ * 捕获式 mock（MessageBubble 测试同款模式）。
+ */
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ChatMessage } from '../../types';
+
+const { debugPropsRef } = vi.hoisted(() => ({
+  debugPropsRef: {} as { current?: Record<string, unknown> },
+}));
+
+vi.mock('./DebugButton', () => ({
+  DebugButton: (props: Record<string, unknown>) => {
+    debugPropsRef.current = props;
+    return null;
+  },
+}));
+vi.mock('../../store-context', () => ({
+  useChatStore: (selector: (s: Record<string, unknown>) => unknown) =>
+    selector({ submitFeedback: vi.fn() }),
+}));
+vi.mock('../../chat-config', () => ({
+  useChatConfigStore: (selector: (s: Record<string, unknown>) => unknown) => selector({ enableTTS: false }),
+}));
+vi.mock('@tbox.cn/app-agent-sdk-client', () => ({
+  createLogger: () => ({ warn: vi.fn() }),
+  useFeedbackAdapter: () => undefined,
+  useRefreshSession: () => undefined,
+  useTTSAdapter: () => undefined,
+}));
+vi.mock('../../utils/copyText', () => ({ copyText: vi.fn(async () => true) }));
+vi.mock('../../utils/toast', () => ({ toast: vi.fn() }));
+
+import { ActionBar } from './index';
+
+const doneMessage = (over: Partial<ChatMessage> = {}): ChatMessage => ({
+  id: 'm1',
+  role: 'assistant',
+  content: '答案',
+  status: 'done',
+  createdAt: 1,
+  ...over,
+});
+
+describe('ActionBar → DebugButton 接线（病因学守卫）', () => {
+  let host: HTMLDivElement;
+  let root: ReturnType<typeof createRoot>;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    debugPropsRef.current = undefined;
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    host.remove();
+  });
+
+  it('A1 done 消息：requestId + conversationId 均透传（删除任一 prop 行 → 红）', () => {
+    act(() => {
+      root.render(<ActionBar message={doneMessage({ requestId: 'req_1', conversationId: 'conv_1' })} />);
+    });
+    expect(debugPropsRef.current).toMatchObject({
+      requestId: 'req_1',
+      conversationId: 'conv_1',
+      messageId: 'm1',
+    });
+  });
+
+  it('A2 字段缺席：prop 透传 undefined（不抛错、按钮层自守卫）', () => {
+    act(() => {
+      root.render(<ActionBar message={doneMessage({ requestId: 'req_1' })} />);
+    });
+    expect(debugPropsRef.current).toMatchObject({ requestId: 'req_1', conversationId: undefined });
+  });
+});

package/packages/agent-ui-kit/src/components/ActionBar/index.tsx

@@ -150,6 +150,7 @@ export function ActionBar({ message }: { message: ChatMessage }) {
 
       <DebugButton
         requestId={message.requestId}
+        conversationId={message.conversationId}
         messageId={message.id}
         messageCreatedAt={new Date(message.createdAt).getTime()}
       />

package/packages/agent-ui-kit/src/components/MessageBubble/index.test.tsx

@@ -7,8 +7,8 @@ import type { TboxCardPayload } from '@tbox.cn/app-contracts';
 const mocks = vi.hoisted(() => ({
   state: {
     cardsByMessageId: {} as Record<string, TboxCardPayload[]>,
-    conversationId: null,
   },
+  debugProps: null as Record<string, unknown> | null,
 }));
 
 vi.mock('../../store-context', () => ({
@@ -29,7 +29,12 @@ vi.mock('../../components/ActionBar', () => ({
   CopyButton: () => null,
   getMessageCopyText: () => '',
 }));
-vi.mock('../../components/ActionBar/DebugButton', () => ({ DebugButton: () => null }));
+vi.mock('../../components/ActionBar/DebugButton', () => ({
+  DebugButton: (props: Record<string, unknown>) => {
+    mocks.debugProps = props;
+    return null;
+  },
+}));
 
 import { MessageBubble } from './index';
 
@@ -109,4 +114,21 @@ describe('MessageBubble member gate card partition', () => {
     // 纵向铺开：不再有轮播圆点指示器
     expect(host.querySelector('[aria-label^="第 "]')).toBeNull();
   });
+
+  it('error 消息接线：DebugButton 透传 requestId + conversationId（error 分支守卫——不经 ActionBar 的独立渲染路径）', () => {
+    mocks.state.cardsByMessageId = {}; // 用例间隔离：清除前序用例的卡片桶残留
+    mocks.debugProps = null;
+    act(() => {
+      root.render(
+        <MessageBubble
+          message={{ ...emptyAssistantMessage, status: 'error' as const, error: '失败', requestId: 'req_e', conversationId: 'conv_e' }}
+        />,
+      );
+    });
+    expect(mocks.debugProps).toMatchObject({
+      requestId: 'req_e',
+      conversationId: 'conv_e',
+      messageId: 'assistant-1',
+    });
+  });
 });

package/packages/agent-ui-kit/src/components/MessageBubble/index.tsx

@@ -163,6 +163,7 @@ export function MessageBubble({ message }: { message: ChatMessage }) {
               {message.requestId && (
                 <DebugButton
                   requestId={message.requestId}
+                  conversationId={message.conversationId}
                   messageId={message.id}
                   messageCreatedAt={new Date(message.createdAt).getTime()}
                 />

package/pnpm-lock.template.yaml

@@ -16,11 +16,11 @@ catalogs:
       specifier: 0.1.0
       version: 0.1.0
     '@tbox.cn/app-agent-sdk-client':
-      specifier: 0.1.3
-      version: 0.1.3
+      specifier: 0.1.4
+      version: 0.1.4
     '@tbox.cn/app-agent-sdk-server':
-      specifier: 0.1.6
-      version: 0.1.6
+      specifier: 0.2.1
+      version: 0.2.1
     '@tbox.cn/app-contracts':
       specifier: 0.12.3
       version: 0.12.3
@@ -28,8 +28,8 @@ catalogs:
       specifier: 0.12.4
       version: 0.12.4
     '@tbox.cn/app-sdk-server':
-      specifier: 0.22.1
-      version: 0.22.1
+      specifier: 0.24.0
+      version: 0.24.0
     '@tbox.cn/app-theme-tbox':
       specifier: 0.1.3
       version: 0.1.3
@@ -115,7 +115,7 @@ importers:
     devDependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.22.1
+        version: 0.24.0
       eslint:
         specifier: 'catalog:'
         version: 9.39.5
@@ -142,7 +142,7 @@ importers:
         version: link:../../packages/provider-custom
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.3(@types/react@18.3.31)
+        version: 0.1.4(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
         version: 0.12.3
@@ -206,7 +206,7 @@ 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.1.6(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.2.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
         version: 0.12.3
@@ -246,7 +246,7 @@ importers:
         version: 2.1.10(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.3(@types/react@18.3.31)
+        version: 0.1.4(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
         version: 0.12.3
@@ -314,10 +314,10 @@ importers:
     dependencies:
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.3(@types/react@18.3.31)
+        version: 0.1.4(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.1.6(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.2.1(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
         version: 0.12.3
@@ -1335,12 +1335,12 @@ packages:
       '@tbox-dev-js/sdk': '>=0.1.18 <0.2.0'
       zod: '>=3.24.0 <4.0.0'
 
-  '@tbox.cn/app-agent-sdk-client@0.1.3':
-    resolution: {integrity: sha512-oyHvufpJ1bWfoEAm82Kkh07d0NbuK9NQkZGEvprB3UBKEQRgyydKps58K1IHHjVZ/eDMBeGA8DgAxqAbC8rQCw==}
+  '@tbox.cn/app-agent-sdk-client@0.1.4':
+    resolution: {integrity: sha512-5Mlqcsvj7q0/5DyTNbczCEttodfhJf5m2XBhgepF04pye3TlOuHJazR5mkInRyPjZAzbYiC0uN6AaK86Dmt1aQ==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-agent-sdk-server@0.1.6':
-    resolution: {integrity: sha512-manek451WQdIWDS41Gd+HJDgELjZc5Kq7GMzSMRBg5IuWrxHTJUgbw+SGHPAPxd+bjn83ck9hKleXi4pwNpntg==}
+  '@tbox.cn/app-agent-sdk-server@0.2.1':
+    resolution: {integrity: sha512-LzyTVgVk6xYVJZ1ah5zJUjz8mV49w0z/cWAO098DVedUXRzYGI6w9sAK/XQRJVzs0ZVJGxVw8pqlGx2yvJD4ug==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-contracts-mall@0.12.4':
@@ -1367,8 +1367,8 @@ packages:
     resolution: {integrity: sha512-KDcFdIrIEOlwDvIqBu29CzR5vDjt0BCADMBrgrd5WlRqjrPM1/jM/RcaRO6gRuElmQCp5LfsoAkVeYTZE/6rpw==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-server@0.22.1':
-    resolution: {integrity: sha512-IYeOOvUogleijkibS1glG/N7Myv2LlaSCbwxAf8FrLqgkgHpzzGK75xMGFCrak3FwzjWDfj3zMCM7ywbcpY+zQ==}
+  '@tbox.cn/app-sdk-server@0.24.0':
+    resolution: {integrity: sha512-BzE40pZokr5DyXc5YuzJ7+PM/fA3rN9814/xxyFA5fToIz+YFIpamE4s9VgsJODYsgvfY0NsZeQ3bisv3yh6fw==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
@@ -4077,7 +4077,7 @@ snapshots:
       '@tbox-dev-js/sdk': 0.1.18
       zod: 3.25.76
 
-  '@tbox.cn/app-agent-sdk-client@0.1.3(@types/react@18.3.31)':
+  '@tbox.cn/app-agent-sdk-client@0.1.4(@types/react@18.3.31)':
     dependencies:
       '@tbox.cn/app-contracts': 0.12.3
       '@tbox.cn/app-sdk-client': 0.21.1
@@ -4089,7 +4089,7 @@ snapshots:
       - '@types/react'
       - immer
 
-  '@tbox.cn/app-agent-sdk-server@0.1.6(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
+  '@tbox.cn/app-agent-sdk-server@0.2.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)
@@ -4099,7 +4099,7 @@ snapshots:
       '@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.12.3
       '@tbox.cn/app-sdk-core': 0.20.2
-      '@tbox.cn/app-sdk-server': 0.22.1
+      '@tbox.cn/app-sdk-server': 0.24.0
       ai: 6.0.246(zod@3.25.76)
       express: 4.22.2
       gray-matter: 4.0.3
@@ -4149,7 +4149,7 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.12.3
 
-  '@tbox.cn/app-sdk-server@0.22.1':
+  '@tbox.cn/app-sdk-server@0.24.0':
     dependencies:
       '@ag-ui/core': 0.0.47
       '@tbox.cn/app-contracts': 0.12.3

package/pnpm-workspace.template.yaml

@@ -40,9 +40,9 @@ catalog:
   "@tbox.cn/agent-plugin": 0.1.0
   "@tbox.cn/app-sdk-core": 0.20.2
   "@tbox.cn/app-sdk-client": 0.21.1
-  "@tbox.cn/app-sdk-server": 0.22.1
-  "@tbox.cn/app-agent-sdk-server": 0.1.6
-  "@tbox.cn/app-agent-sdk-client": 0.1.3
+  "@tbox.cn/app-sdk-server": 0.24.0
+  "@tbox.cn/app-agent-sdk-server": 0.2.1
+  "@tbox.cn/app-agent-sdk-client": 0.1.4
   "@tbox.cn/app-contracts": 0.12.3
   "@tbox.cn/app-contracts-mall": 0.12.4
   "@tbox.cn/app-theme-tbox": 0.1.3