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

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

@@ -0,0 +1,99 @@
+// @vitest-environment happy-dom
+/**
+ * QuickCommands 快捷胶囊（W2-1 自 mall 随迁）：断言原样——harness 改 kit context 注入形式
+ * （原 mock 应用 store → 现最小测试 store + KitChatProvider；本地图文合并经 config store 快照注入）。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import type { ReactNode } from 'react';
+import { create } from 'zustand';
+import type { CoreChatStore } from '@tbox.cn/app-sdk/client';
+import { configureChatConfigDefaults, useChatConfigStore } from '../../chat-config';
+import { KitChatProvider } from '../../store-context';
+import { QuickCommands } from './index';
+
+/** 最小测试 store（仅 helloAck 消费面）；注入形式经 KitChatProvider。 */
+const testStore = create<{ helloAck: unknown }>(() => ({ helloAck: null })) as unknown as CoreChatStore;
+
+/** 构建期快照（对齐 mall config/chat.json 三条——本地图标合并真源） */
+const STATIC_COMMANDS = [
+  {
+    label: '今日优惠',
+    query: '现在有什么优惠？',
+    icon: 'https://mdn.alipayobjects.com/agt_content/afts/img/yirAQ7obEFcAAAAAAAAAAAAAehe3AQBr/original',
+  },
+  {
+    label: '品牌导览',
+    query: '品牌导览',
+    icon: 'https://mdn.alipayobjects.com/agt_content/afts/img/6-OCR5kWFaAAAAAAAAAAAAAAehe3AQBr/original',
+  },
+  {
+    label: '活动中心',
+    query: '活动中心',
+    icon: 'https://mdn.alipayobjects.com/agt_content/afts/img/yirAQ7obEFcAAAAAAAAAAAAAehe3AQBr/original',
+  },
+];
+
+function renderWithKit(container: HTMLElement, node: ReactNode): void {
+  flushSync(() =>
+    createRoot(container).render(
+      <KitChatProvider store={testStore} cards={{}} rawCards={{}}>
+        {node}
+      </KitChatProvider>,
+    ),
+  );
+}
+
+beforeEach(() => {
+  configureChatConfigDefaults({ quickCommands: STATIC_COMMANDS });
+});
+
+afterEach(() => {
+  testStore.setState({ helloAck: null } as never);
+  useChatConfigStore.setState({ quickCommands: [] });
+  document.body.innerHTML = '';
+});
+
+describe('QuickCommands 快捷胶囊', () => {
+  it('按服务端顺序渲染三项、合并本地图标并发送服务端 prompt', () => {
+    testStore.setState({
+      helloAck: {
+        chatConfig: {
+          quickCommands: [
+            { label: '今日优惠', prompt: '服务端优惠查询' },
+            { label: '品牌导览', prompt: '服务端品牌导览' },
+            { label: '活动中心', prompt: '服务端活动查询' },
+          ],
+        },
+      },
+    } as never);
+    const onCommand = vi.fn();
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    renderWithKit(container, <QuickCommands onCommand={onCommand} />);
+
+    const buttons = [...container.querySelectorAll<HTMLButtonElement>('.quick-commands__item')];
+    expect(buttons.map((button) => button.textContent)).toEqual(['今日优惠', '品牌导览', '活动中心']);
+    expect(container.textContent).not.toContain('找门店');
+    expect(buttons[1]?.querySelector('img')?.src).toContain('6-OCR5kWFa');
+    flushSync(() => buttons[1]!.click());
+    expect(onCommand).toHaveBeenCalledWith('服务端品牌导览');
+  });
+
+  it('隐藏时保留胶囊容器，但禁止交互', () => {
+    const onCommand = vi.fn();
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    renderWithKit(container, <QuickCommands hidden onCommand={onCommand} />);
+
+    const commands = container.querySelector('.quick-commands');
+    const button = container.querySelector<HTMLButtonElement>('.quick-commands__item');
+    expect(commands).not.toBeNull();
+    expect(commands?.classList.contains('quick-commands--hidden')).toBe(true);
+    expect(commands?.getAttribute('aria-hidden')).toBe('true');
+    expect(button?.disabled).toBe(true);
+    flushSync(() => button?.click());
+    expect(onCommand).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,52 @@
+// 输入框上方的快捷指令；文案由 chatConfig 驱动，服务端下发不含 icon 时按 label 合并本地配置。
+// 011 I2：服务端 HelloAck.chatConfig.quickCommands 优先（单一真源），本地 chat.json 为 fallback。
+// label 只写纯文字；前面的星标由本组件渲染（icon 字段或默认 ✦），不要把 ✦/emoji 写进 label。
+import { useChatConfigStore } from '../../chat-config';
+import { useChatStore } from '../../store-context';
+import starIcon from '../../../assets/quick-command-star.svg';
+import './index.less';
+
+export function QuickCommands({
+  onCommand,
+  hidden = false,
+}: {
+  onCommand: (query: string) => void;
+  hidden?: boolean;
+}) {
+  const staticCommands = useChatConfigStore((s) => s.quickCommands);
+  const serverCommands = useChatStore((s) => s.helloAck?.chatConfig.quickCommands);
+  // 服务端下发优先；未收到 HELLO_ACK（非 mall 部署）回落本地静态
+  const staticByLabel = new Map(staticCommands.map((command) => [command.label, command]));
+  const commands = serverCommands && serverCommands.length > 0
+    ? serverCommands.map((command) => ({
+        label: command.label,
+        query: command.prompt,
+        icon: staticByLabel.get(command.label)?.icon,
+      }))
+    : staticCommands;
+  if (!commands.length) return null;
+
+  return (
+    <div
+      className={`quick-commands${hidden ? ' quick-commands--hidden' : ''}`}
+      aria-hidden={hidden || undefined}
+    >
+      {commands.map((cmd) => (
+        <button
+          key={cmd.label}
+          className="quick-commands__item"
+          disabled={hidden}
+          onClick={() => onCommand(cmd.query)}
+        >
+          <img
+            className="quick-commands__icon"
+            src={cmd.icon ?? starIcon}
+            alt=""
+            onError={(event) => { event.currentTarget.src = starIcon; }}
+          />
+          <span className="quick-commands__label">{cmd.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}

package/{apps/client → packages/agent-ui-kit}/src/components/ScrollToBottomButton/index.less

@@ -13,7 +13,7 @@
   z-index: 10;
   opacity: 0;
   transform: scale(0.8);
-  transition: opacity 0.2s ease, transform 0.2s ease;
+  transition: opacity var(--tbox-motion-duration-fast) ease, transform var(--tbox-motion-duration-fast) ease;
   pointer-events: none;
 
   &--visible {

package/packages/agent-ui-kit/src/components/ToolCallBlock/detail.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildMemoryToolCallPayload,
+  buildPreToolArgsPayload,
+  buildPreToolResultPayload,
+  buildPreToolToolCallPayload,
+  buildSkillToolCallPayload,
+  MEMORY_TOOL_CALL_NAME,
+  PRE_TOOL_CALL_NAME,
+  SKILL_TOOL_CALL_NAME,
+} from '@tbox.cn/app-contracts';
+import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import {
+  buildSummaryText,
+  deriveSummary,
+  deriveToolCallItem,
+  prettyDetailText,
+} from './detail';
+import type { ToolCallViewItem } from './detail';
+
+/** 载荷一律经契约 builder 构造——与线上实时/历史路径字节级同构 */
+const mkTc = (over: Partial<ToolCallInfo>): ToolCallInfo => ({
+  id: 't0',
+  name: 'plain_tool',
+  status: 'done',
+  ...over,
+});
+
+describe('deriveToolCallItem（三分支视图模型）', () => {
+  it('skill 带 description：前置技能徽标 + detail（input=描述 / output=已加载）', () => {
+    const payload = buildSkillToolCallPayload({ name: 'member-guide', description: '会员导购技能' });
+    const item = deriveToolCallItem(
+      mkTc({ id: 's1', name: SKILL_TOOL_CALL_NAME, args: payload.args, result: payload.result }),
+    );
+    expect(item.kind).toBe('skill');
+    expect(item.label).toBe('会员导购技能');
+    expect(item.badge).toBe('前置技能');
+    expect(item.status).toBe('done');
+    expect(item.detail).toEqual({ inputText: '会员导购技能', outputText: '已加载', isError: false });
+  });
+
+  it('skill 无中文 description → 中文通用标题；args 非法 JSON 不泄漏技术名；calling 态无详情入口', () => {
+    const payload = buildSkillToolCallPayload({ name: 'minimal-skill' });
+    const noDesc = deriveToolCallItem(
+      mkTc({ id: 's2', name: SKILL_TOOL_CALL_NAME, args: payload.args, result: payload.result }),
+    );
+    expect(noDesc.label).toBe('加载技能');
+    expect(noDesc.detail).toBeUndefined();
+    const badArgs = deriveToolCallItem(
+      mkTc({ id: 's3', name: SKILL_TOOL_CALL_NAME, args: 'not-json' }),
+    );
+    expect(badArgs.label).toBe('加载技能');
+    expect(badArgs.detail).toBeUndefined();
+    // 实时路径 START→ARGS→RESULT 逐帧，RESULT 前存在 calling 瞬态——详情入口必须屏蔽
+    const withDesc = buildSkillToolCallPayload({ name: 's', description: 'd' });
+    const calling = deriveToolCallItem(
+      mkTc({ id: 's4', name: SKILL_TOOL_CALL_NAME, status: 'calling', args: withDesc.args }),
+    );
+    expect(calling.status).toBe('calling');
+    expect(calling.label).toBe('加载技能');
+    expect(calling.detail).toBeUndefined();
+  });
+
+  it('preTool done：前置工具徽标 + input=toolArgs 紧凑串 + output=pretty(result)', () => {
+    const { args, result } = buildPreToolToolCallPayload({
+      toolName: 'member-balance',
+      description: '会员卡余额查询',
+      args: { cardNo: 'C001' },
+      result: { balance: 1200 },
+    });
+    const item = deriveToolCallItem(
+      mkTc({ id: 'p1', name: PRE_TOOL_CALL_NAME, args, result }),
+    );
+    expect(item.kind).toBe('preTool');
+    expect(item.label).toBe('会员卡余额查询');
+    expect(item.badge).toBe('前置工具');
+    expect(item.status).toBe('done');
+    expect(item.detail?.inputText).toBe('{"cardNo":"C001"}');
+    expect(item.detail?.outputText).toBe(JSON.stringify({ balance: 1200 }, null, 2));
+    expect(item.detail?.isError).toBe(false);
+  });
+
+  it('preTool error（payload status，tc.status 恒 done）：error 态 + output=错误文案', () => {
+    const item = deriveToolCallItem(
+      mkTc({
+        id: 'p2',
+        name: PRE_TOOL_CALL_NAME,
+        args: buildPreToolArgsPayload({ toolName: 'parking-fee', description: '停车费查询', toolArgs: { plate: '沪A12345' } }),
+        result: buildPreToolResultPayload({ toolName: 'parking-fee', status: 'error', error: '接口超时' }),
+      }),
+    );
+    expect(item.status).toBe('error');
+    expect(item.detail?.isError).toBe(true);
+    expect(item.detail?.outputText).toBe('接口超时');
+  });
+
+  it('preTool calling（只有 args 无 result）：无详情入口', () => {
+    const item = deriveToolCallItem(
+      mkTc({
+        id: 'p3',
+        name: PRE_TOOL_CALL_NAME,
+        status: 'calling',
+        args: buildPreToolArgsPayload({ toolName: 'member-balance', toolArgs: {} }),
+      }),
+    );
+    expect(item.status).toBe('calling');
+    expect(item.label).toBe('查询会员余额');
+    expect(item.detail).toBeUndefined();
+  });
+
+  it('normal done：中文标题 + 无徽标 + input=args / output=result 原文', () => {
+    const item = deriveToolCallItem(
+      mkTc({ id: 'n1', name: 'search_stores', args: '{"keyword":"咖啡"}', result: '{"total":3}' }),
+    );
+    expect(item.label).toBe('搜索商场门店');
+    expect(item.badge).toBeUndefined();
+    expect(item.detail).toEqual({ inputText: '{"keyword":"咖啡"}', outputText: '{"total":3}', isError: false });
+  });
+
+  it('normal error 与中断（error=请求中断）：isError + output=错误文本', () => {
+    const failed = deriveToolCallItem(
+      mkTc({ id: 'n2', name: 'pay_order', status: 'error', args: '{}', error: '支付网关拒绝' }),
+    );
+    expect(failed.status).toBe('error');
+    expect(failed.detail?.isError).toBe(true);
+    expect(failed.detail?.outputText).toBe('支付网关拒绝');
+    const interrupted = deriveToolCallItem(
+      mkTc({ id: 'n3', name: 'search_stores', args: '{"k":"v"}', status: 'error', error: '请求中断' }),
+    );
+    expect(interrupted.detail?.outputText).toBe('请求中断');
+    expect(interrupted.detail?.isError).toBe(true);
+  });
+
+  it('normal 全空（CANCEL_RUN 后无 result）→ 无详情入口', () => {
+    const item = deriveToolCallItem(mkTc({ id: 'n4', name: 'search_stores', status: 'done' }));
+    expect(item.detail).toBeUndefined();
+  });
+
+  it('未知英文 normal 工具使用中文通用标题，不直接暴露技术名', () => {
+    const item = deriveToolCallItem(mkTc({ id: 'n5', name: 'future_vendor_lookup_v2', status: 'calling' }));
+    expect(item.label).toBe('处理工具任务');
+    expect(item.label).not.toContain('future_vendor_lookup_v2');
+  });
+});
+
+describe('prettyDetailText（归一 + 幂等 + 不截断）', () => {
+  it('合法紧凑 JSON → pretty；pretty 再入不变；纯文本原文；长文本不截断', () => {
+    const compact = '{"a":1,"b":[2,3]}';
+    const pretty = prettyDetailText(compact);
+    expect(pretty).toBe(JSON.stringify({ a: 1, b: [2, 3] }, null, 2));
+    expect(prettyDetailText(pretty)).toBe(pretty);
+    expect(prettyDetailText('plain text')).toBe('plain text');
+    const long = 'x'.repeat(600);
+    expect(prettyDetailText(long)).toHaveLength(600);
+    expect(prettyDetailText('')).toBe('');
+  });
+});
+
+describe('deriveToolCallItem memory 分支（018 tool-debug）', () => {
+  const memoryTc = (status: 'hit' | 'miss' | 'degraded' | 'skipped', over?: { error?: string; reason?: string }) => {
+    const payload = buildMemoryToolCallPayload({
+      query: '推荐适合父母的餐厅',
+      status,
+      ...(status === 'hit'
+        ? {
+            records: [
+              { id: 'm1', kind: 'preference', content: '用户偏好安静的家庭聚餐环境' },
+              { id: 'm2', kind: 'fact', content: '用户是黄金会员' },
+            ],
+          }
+        : {}),
+      ...(over?.error ? { error: over.error } : {}),
+      ...(over?.reason ? { reason: over.reason } : {}),
+    });
+    return mkTc({ id: 'mem-1', name: MEMORY_TOOL_CALL_NAME, args: payload.args, result: payload.result });
+  };
+
+  it('hit：记忆召回徽标 + label 命中数 + 详情（input=query / output=records 预览）', () => {
+    const item = deriveToolCallItem(memoryTc('hit'));
+    expect(item.kind).toBe('memory');
+    expect(item.badge).toBe('记忆召回');
+    expect(item.label).toBe('记忆召回 · 2 条命中');
+    expect(item.status).toBe('done');
+    expect(item.techName).toBe(MEMORY_TOOL_CALL_NAME);
+    expect(item.detail?.inputText).toBe('推荐适合父母的餐厅');
+    expect(item.detail?.outputText).toContain('[preference] 用户偏好安静的家庭聚餐环境');
+    expect(item.detail?.isError).toBe(false);
+  });
+
+  it('degraded：error 视觉态 + 详情=错误信息', () => {
+    const item = deriveToolCallItem(memoryTc('degraded', { error: '记忆召回超时' }));
+    expect(item.status).toBe('error');
+    expect(item.label).toBe('记忆召回降级');
+    expect(item.detail?.isError).toBe(true);
+    expect(item.detail?.outputText).toBe('记忆召回超时');
+  });
+
+  it('skipped（intent）：done 态 + label 跳过原因 + 无详情', () => {
+    const item = deriveToolCallItem(memoryTc('skipped', { reason: 'intent' }));
+    expect(item.status).toBe('done');
+    expect(item.label).toBe('记忆召回 · 跳过（意图命中）');
+    expect(item.detail).toBeUndefined();
+  });
+
+  it('miss：done 态 + 无详情', () => {
+    const item = deriveToolCallItem(memoryTc('miss'));
+    expect(item.status).toBe('done');
+    expect(item.label).toBe('记忆召回');
+    expect(item.detail).toBeUndefined();
+  });
+});
+
+describe('techName（018 dev 视图技术标识）', () => {
+  it('normal=协议名 / preTool=被预执行工具 id / skill=skillName / memory=伪工具名', () => {
+    const normal = deriveToolCallItem(mkTc({ id: 'n1', name: 'search_stores', args: '{}', result: '{}' }));
+    expect(normal.techName).toBe('search_stores');
+    const { args: preArgs, result: preResult } = buildPreToolToolCallPayload({
+      toolName: 'member-balance',
+      args: { cardNo: 'C001' },
+      result: { balance: 1 },
+    });
+    const pre = deriveToolCallItem(mkTc({ id: 'p1', name: PRE_TOOL_CALL_NAME, args: preArgs, result: preResult }));
+    expect(pre.techName).toBe('member-balance');
+    const skill = buildSkillToolCallPayload({ name: 'member-guide' });
+    const sk = deriveToolCallItem(mkTc({ id: 's1', name: SKILL_TOOL_CALL_NAME, args: skill.args, result: skill.result }));
+    expect(sk.techName).toBe('member-guide');
+    const mem = deriveToolCallItem(mkTc({ id: 'm1', name: MEMORY_TOOL_CALL_NAME, args: '{}', result: '{}' }));
+    expect(mem.techName).toBe(MEMORY_TOOL_CALL_NAME);
+  });
+});
+
+describe('deriveSummary + buildSummaryText（L1 聚合）', () => {
+  const mkItem = (over: Partial<ToolCallViewItem>): ToolCallViewItem => ({
+    id: 'i0',
+    kind: 'normal',
+    label: 'x',
+    status: 'done',
+    ...over,
+  });
+
+  it('混合条目：技能/工具计数 + 最近执行标题 + calling + 失败数', () => {
+    const s = deriveSummary([
+      mkItem({ id: '1', kind: 'skill' }),
+      mkItem({ id: '2', kind: 'skill', status: 'error' }),
+      mkItem({ id: '3', kind: 'preTool' }),
+      mkItem({ id: '4', kind: 'preTool', label: '查询停车费用', status: 'calling' }),
+      mkItem({ id: '5', status: 'error' }),
+    ]);
+    expect(s).toEqual({
+      skillCount: 2,
+      toolCount: 3,
+      totalCount: 5,
+      callingCount: 1,
+      activeTitle: '查询停车费用',
+      calling: true,
+      failedCount: 2,
+    });
+  });
+
+  it('多个 calling 条目使用最后开始的任务作为收起态主标题', () => {
+    const s = deriveSummary([
+      mkItem({ id: '1', label: '查询会员信息', status: 'calling' }),
+      mkItem({ id: '2', label: '搜索商场门店', status: 'calling' }),
+    ]);
+    expect(s.callingCount).toBe(2);
+    expect(s.activeTitle).toBe('搜索商场门店');
+    expect(buildSummaryText(s)).toEqual(['正在搜索商场门店 · 另有 1 项']);
+  });
+
+  it('buildSummaryText：执行中标题优先、数量降级；稳定态按技能/工具有序汇总', () => {
+    expect(buildSummaryText({
+      skillCount: 0,
+      toolCount: 3,
+      totalCount: 3,
+      callingCount: 0,
+      calling: false,
+      failedCount: 0,
+    })).toEqual([
+      '已调用工具 3 个',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 2,
+      toolCount: 0,
+      totalCount: 2,
+      callingCount: 0,
+      calling: false,
+      failedCount: 0,
+    })).toEqual([
+      '已加载技能 2 个',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 2,
+      toolCount: 3,
+      totalCount: 5,
+      callingCount: 0,
+      calling: false,
+      failedCount: 0,
+    })).toEqual([
+      '已加载技能 2 个',
+      '已调用工具 3 个',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 1,
+      toolCount: 2,
+      totalCount: 3,
+      callingCount: 2,
+      activeTitle: '搜索商场门店',
+      calling: true,
+      failedCount: 0,
+    })).toEqual([
+      '正在搜索商场门店 · 另有 1 项',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 0,
+      toolCount: 1,
+      totalCount: 1,
+      callingCount: 1,
+      activeTitle: '查询停车费用',
+      calling: true,
+      failedCount: 0,
+    })).toEqual([
+      '正在查询停车费用',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 0,
+      toolCount: 1,
+      totalCount: 1,
+      callingCount: 1,
+      activeTitle: '正在同步停车信息',
+      calling: true,
+      failedCount: 0,
+    })).toEqual([
+      '正在同步停车信息',
+    ]);
+    expect(buildSummaryText({
+      skillCount: 0,
+      toolCount: 0,
+      totalCount: 0,
+      callingCount: 0,
+      calling: false,
+      failedCount: 0,
+    })).toEqual([
+      '暂无工具活动',
+    ]);
+  });
+});