@tbox.cn/app-template-agent 0.10.10 → 0.10.12

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 锚定匹配,闸外请求字节级不变) |
 
 ## 统一鉴权
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "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.0"
+    "@tbox.cn/app-sdk-server": "0.23.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.5
-      version: 0.1.5
+      specifier: 0.2.0
+      version: 0.2.0
     '@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.0
-      version: 0.22.0
+      specifier: 0.23.0
+      version: 0.23.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.0
+        version: 0.23.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.5(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.2.0(@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.5(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.2.0(@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.5':
-    resolution: {integrity: sha512-5M7CTzFpex+KQ+INTEaYGzA1aKEhAcnWbixk6hnXYk9y3CVpJWDo3MV1/ZiwsEmTsFYwryOglbLDS30m3RDl7w==}
+  '@tbox.cn/app-agent-sdk-server@0.2.0':
+    resolution: {integrity: sha512-5V+H4lDWd78RnRng3BtFc9TEKog/WN+SXl5oMJWvqR7oJvXGOgsToCra3dUXSHTZw4c9r7YEN1m+aXU0JdBe2g==}
     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.0':
-    resolution: {integrity: sha512-St5cP43/y/pH/s6ubXX44Rf0wmysL19tZRvTWSUV/0EmO7ouoRmtTzsWHe+XnqkcUnRgfSYm/evRse+K9ATNhg==}
+  '@tbox.cn/app-sdk-server@0.23.0':
+    resolution: {integrity: sha512-h+WtBjHF6ophOLj+amsiejZJ8TwoxLTmbnEmgfmUxDMgXHLzqJe/A/KAXN701ryku0IEDtIRXeWJ1szPLG9H5g==}
     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.5(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
+  '@tbox.cn/app-agent-sdk-server@0.2.0(@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.0
+      '@tbox.cn/app-sdk-server': 0.23.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.0':
+  '@tbox.cn/app-sdk-server@0.23.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.0
-  "@tbox.cn/app-agent-sdk-server": 0.1.5
-  "@tbox.cn/app-agent-sdk-client": 0.1.3
+  "@tbox.cn/app-sdk-server": 0.23.0
+  "@tbox.cn/app-agent-sdk-server": 0.2.0
+  "@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