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

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

@@ -0,0 +1,261 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRoot, type Root } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import {
+  buildMemoryToolCallPayload,
+  buildPreToolArgsPayload,
+  buildPreToolResultPayload,
+  buildSkillToolCallPayload,
+  MEMORY_TOOL_CALL_NAME,
+  PRE_TOOL_CALL_NAME,
+  SKILL_TOOL_CALL_NAME,
+} from '@tbox.cn/app-contracts';
+import type { ToolCallInfo } from '../../types';
+import ToolCallBlock from './index';
+
+const mocks = vi.hoisted(() => ({
+  copyText: vi.fn(async () => true),
+  toast: vi.fn(async () => {}),
+}));
+
+vi.mock('../../utils/copyText', () => ({ copyText: mocks.copyText }));
+vi.mock('../../utils/toast', () => ({ toast: mocks.toast }));
+
+/** 夹具：1 preTool(done) + 1 skill(带 description) + 1 normal(calling)，载荷经契约 builder 同构 */
+function makeCalls(): ToolCallInfo[] {
+  const skill = buildSkillToolCallPayload({ name: 'member-guide', description: '会员导购技能' });
+  return [
+    {
+      id: 'pre-1',
+      name: PRE_TOOL_CALL_NAME,
+      args: buildPreToolArgsPayload({
+        toolName: 'member-balance',
+        description: '会员卡余额查询',
+        toolArgs: { cardNo: 'C001' },
+      }),
+      result: buildPreToolResultPayload({
+        toolName: 'member-balance',
+        status: 'done',
+        result: { balance: 1200 },
+      }),
+      status: 'done',
+    },
+    {
+      id: 'skill-1',
+      name: SKILL_TOOL_CALL_NAME,
+      args: skill.args,
+      result: skill.result,
+      status: 'done',
+    },
+    { id: 'tool-1', name: 'search_stores', status: 'calling' },
+  ];
+}
+
+/** 018：memory 伪工具夹具（hit + degraded），载荷经契约 builder 同构 */
+function makeMemoryCalls(): ToolCallInfo[] {
+  const hit = buildMemoryToolCallPayload({
+    query: '推荐美食',
+    status: 'hit',
+    records: [{ id: 'm1', kind: 'preference', content: '用户爱吃辣' }],
+  });
+  const degraded = buildMemoryToolCallPayload({
+    query: '今天活动',
+    status: 'degraded',
+    error: '记忆召回超时',
+  });
+  return [
+    { id: 'mem-hit', name: MEMORY_TOOL_CALL_NAME, args: hit.args, result: hit.result, status: 'done' },
+    { id: 'mem-deg', name: MEMORY_TOOL_CALL_NAME, args: degraded.args, result: degraded.result, status: 'done' },
+  ];
+}
+
+function renderBlock(
+  calls: ToolCallInfo[],
+  opts: { debug?: boolean } = {},
+): {
+  container: HTMLElement;
+  rerender: (next: ToolCallInfo[]) => void;
+  unmount: () => void;
+} {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root: Root = createRoot(container);
+  flushSync(() => root.render(<ToolCallBlock toolCalls={calls} debug={opts.debug} />));
+  return {
+    container,
+    rerender: (next) => flushSync(() => root.render(<ToolCallBlock toolCalls={next} debug={opts.debug} />)),
+    unmount: () => flushSync(() => root.unmount()),
+  };
+}
+
+function expandSummary(container: HTMLElement): void {
+  flushSync(() => container.querySelector<HTMLButtonElement>('.tool-calls__summary')?.click());
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('ToolCallBlock prod 态（018 I4：友好聚合、无出入参展开）', () => {
+  it('默认收起为语义按钮，主文案显示当前执行中的中文任务标题', () => {
+    const { container, unmount } = renderBlock(makeCalls());
+    const summary = container.querySelector<HTMLButtonElement>('.tool-calls__summary');
+    expect(summary?.tagName).toBe('BUTTON');
+    expect(summary?.type).toBe('button');
+    expect(summary?.getAttribute('aria-expanded')).toBe('false');
+    expect(summary?.textContent).toContain('正在搜索商场门店');
+    expect(summary?.textContent).not.toContain('search_stores');
+    expect(container.querySelector('.tool-calls__list')).toBeNull();
+    unmount();
+  });
+
+  it('展开后活动行仅状态/中文名/徽标——零详情触发按钮、零技术名（I4）', () => {
+    const { container, unmount } = renderBlock(makeCalls());
+    expandSummary(container);
+
+    expect(container.querySelectorAll('.tool-calls__item')).toHaveLength(3);
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('前置工具');
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('会员卡余额查询');
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('搜索商场门店');
+    // I4：无任何出入参展开入口（触发按钮/chevron/复制全部不渲染）
+    expect(container.querySelectorAll('button.tool-calls__item-trigger')).toHaveLength(0);
+    expect(container.querySelector('.tool-calls__item-chevron')).toBeNull();
+    expect(container.querySelector('.tool-calls__detail')).toBeNull();
+    expect(container.querySelector('.tool-calls__copy')).toBeNull();
+    expect(container.querySelector('.tool-calls__item-tech')).toBeNull();
+    unmount();
+  });
+
+  it('preTool payload 失败保持失败聚合与失败活动行', () => {
+    const failedPreTool: ToolCallInfo = {
+      id: 'pre-error',
+      name: PRE_TOOL_CALL_NAME,
+      args: buildPreToolArgsPayload({ toolName: 'parking-fee', description: '停车费查询' }),
+      result: buildPreToolResultPayload({ toolName: 'parking-fee', status: 'error', error: '接口超时' }),
+      status: 'done',
+    };
+    const { container, unmount } = renderBlock([failedPreTool]);
+    expect(container.querySelector('.tool-calls__summary')?.textContent).toContain('已调用工具 1 个');
+    expect(container.querySelector('.tool-calls__failed')?.textContent).toContain('1 个失败');
+
+    expandSummary(container);
+    expect(container.querySelector('.tool-calls__item--error')).not.toBeNull();
+    unmount();
+  });
+
+  it('聚合按钮可由浏览器原生键盘激活', () => {
+    const { container, unmount } = renderBlock(makeCalls());
+    const summary = container.querySelector<HTMLButtonElement>('.tool-calls__summary');
+    summary?.focus();
+    expect(document.activeElement).toBe(summary);
+    flushSync(() => summary?.click());
+    expect(container.querySelector('.tool-calls__list')).not.toBeNull();
+    unmount();
+  });
+});
+
+describe('ToolCallBlock dev 态（018 tool-debug：紧凑详情 + 技术后缀）', () => {
+  it('展开后行标题附技术名后缀（协议技术名 dev 可见）', () => {
+    const { container, unmount } = renderBlock(makeCalls(), { debug: true });
+    expandSummary(container);
+
+    const tech = container.querySelector('.tool-calls__item-tech');
+    expect(tech?.textContent).toBe(' · member-balance');
+    expect(container.querySelectorAll('button.tool-calls__item-trigger')).toHaveLength(2);
+    unmount();
+  });
+
+  it('详情在消息流内展开：屏显走紧凑单行格式（formatCompactToolIo），双栏输入输出', () => {
+    const { container, unmount } = renderBlock(makeCalls(), { debug: true });
+    expandSummary(container);
+    flushSync(() => container.querySelector<HTMLButtonElement>('.tool-calls__item-trigger')?.click());
+
+    const detail = container.querySelector('.tool-calls__detail');
+    expect(detail).not.toBeNull();
+    const bodies = detail?.querySelectorAll('.tool-calls__detail-body');
+    // 紧凑单行（无 pretty 缩进空格）
+    expect(bodies?.[0].textContent).toContain('{"cardNo":"C001"}');
+    expect(bodies?.[1].textContent).toContain('{"balance":1200}');
+    expect(bodies?.[0].textContent).not.toContain('"cardNo": "C001"');
+    // 输入/输出双栏标签
+    expect(detail?.textContent).toContain('输入');
+    expect(detail?.textContent).toContain('输出');
+    unmount();
+  });
+
+  it('输出复制仍为美化全文（屏显紧凑、粘贴友好分工）', async () => {
+    const { container, unmount } = renderBlock(makeCalls(), { debug: true });
+    expandSummary(container);
+    flushSync(() => container.querySelector<HTMLButtonElement>('.tool-calls__item-trigger')?.click());
+    // 第二个复制按钮 = 输出（第一个是输入）
+    container.querySelectorAll<HTMLButtonElement>('.tool-calls__copy')[1]?.click();
+
+    await vi.waitFor(() => expect(mocks.copyText).toHaveBeenCalledTimes(1));
+    expect(mocks.copyText).toHaveBeenCalledWith(expect.stringContaining('"balance": 1200'));
+    expect(mocks.toast).toHaveBeenCalledWith('输出已复制', 'success');
+    unmount();
+  });
+
+  it('聚合与行详情展开状态在流式 rerender 后保持稳定', () => {
+    const calls = makeCalls();
+    const { container, rerender, unmount } = renderBlock(calls, { debug: true });
+    expandSummary(container);
+    flushSync(() => container.querySelector<HTMLButtonElement>('.tool-calls__item-trigger')?.click());
+    expect(container.querySelector('.tool-calls__detail')).not.toBeNull();
+
+    rerender(calls.map((item) => item.id === 'tool-1'
+      ? { ...item, status: 'done' as const, args: '{"keyword":"咖啡"}', result: '{"total":3}' }
+      : item));
+
+    expect(container.querySelector('.tool-calls__summary')?.getAttribute('aria-expanded')).toBe('true');
+    expect(container.querySelector('.tool-calls__list')).not.toBeNull();
+    expect(container.querySelector('.tool-calls__detail')).not.toBeNull();
+    expect(container.querySelector('.tool-calls__summary')?.textContent).toContain('已调用工具 2 个');
+    unmount();
+  });
+
+  it('详情按钮可由浏览器原生键盘激活', () => {
+    const { container, unmount } = renderBlock(makeCalls(), { debug: true });
+    expandSummary(container);
+    const detailTrigger = container.querySelector<HTMLButtonElement>('.tool-calls__item-trigger');
+    detailTrigger?.focus();
+    expect(document.activeElement).toBe(detailTrigger);
+    expect(detailTrigger?.getAttribute('aria-expanded')).toBe('false');
+    flushSync(() => detailTrigger?.click());
+    expect(detailTrigger?.getAttribute('aria-expanded')).toBe('true');
+    unmount();
+  });
+});
+
+describe('ToolCallBlock memory 伪工具（018）', () => {
+  it('hit/degraded 活动行：记忆召回徽标、降级为失败态、dev 详情含记录预览', () => {
+    const { container, unmount } = renderBlock(makeMemoryCalls(), { debug: true });
+    expandSummary(container);
+
+    const items = container.querySelectorAll('.tool-calls__item');
+    expect(items).toHaveLength(2);
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('记忆召回 · 1 条命中');
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('记忆召回降级');
+    expect(container.querySelector('.tool-calls__item--error')).not.toBeNull();
+    expect(container.querySelector('.tool-calls__list')?.textContent).toContain('记忆召回');
+
+    flushSync(() => container.querySelector<HTMLButtonElement>('.tool-calls__item-trigger')?.click());
+    const bodies = container.querySelectorAll('.tool-calls__detail-body');
+    expect(bodies[0].textContent).toBe('推荐美食');
+    expect(bodies[1].textContent).toContain('[preference] 用户爱吃辣');
+    unmount();
+  });
+
+  it('prod 态 memory 行无展开入口（与其它工具一致）', () => {
+    const { container, unmount } = renderBlock(makeMemoryCalls());
+    expandSummary(container);
+    expect(container.querySelectorAll('button.tool-calls__item-trigger')).toHaveLength(0);
+    expect(container.querySelector('.tool-calls__detail')).toBeNull();
+    unmount();
+  });
+});

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

@@ -0,0 +1,212 @@
+import { useId, useMemo, useState } from 'react';
+import { CaretDown, Check, Copy, X } from '@phosphor-icons/react';
+import type { ToolCallInfo } from '../../types';
+import { formatCompactToolIo } from '../../utils/tool-call-display';
+import { buildSummaryText, deriveSummary, deriveToolCallItem, prettyDetailText } from './detail';
+import type { ToolCallViewItem } from './detail';
+import { copyText } from '../../utils/copyText';
+import { toast } from '../../utils/toast';
+import './index.less';
+
+const EMPTY_TEXT = '（无）';
+
+const STATUS_TEXT: Record<ToolCallViewItem['status'], string> = {
+  done: '成功',
+  error: '失败',
+  calling: '执行中',
+};
+
+/**
+ * Codex 风格工具活动日志：紧凑聚合行 / 流内活动列表 / 行内完整 IO。
+ * 语义判定仍在 SDK describeToolCall + detail.ts 视图模型，本组件只管理展示状态；
+ * debug 门控在渲染层（018 tool-debug）：prod 恒无出入参展开入口（I4），
+ * dev 行标题附技术名、详情走紧凑单行格式（复制仍为美化全文）；
+ * 图标颜色不传 color prop（phosphor 落 SVG fill 属性，var() 低版本 web-view 不可靠），
+ * 统一走 currentColor + less token 类。
+ */
+export default function ToolCallBlock({
+  toolCalls,
+  debug = false,
+}: {
+  toolCalls: ToolCallInfo[];
+  /** 018 tool-debug：dev 视图（出入参展开 + 技术名 + 紧凑格式）；prod 缺省 false */
+  debug?: boolean;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const [expandedDetailIds, setExpandedDetailIds] = useState<Set<string>>(() => new Set());
+  const listId = useId();
+  const items = useMemo(() => toolCalls.map(deriveToolCallItem), [toolCalls]);
+  const summary = useMemo(() => deriveSummary(items), [items]);
+
+  const toggleDetail = (id: string) => {
+    setExpandedDetailIds((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  };
+
+  return (
+    <div className="tool-calls">
+      <button
+        type="button"
+        className={`tool-calls__summary${summary.calling ? ' tool-calls__summary--calling' : ''}`}
+        aria-expanded={expanded}
+        aria-controls={listId}
+        onClick={() => setExpanded((current) => !current)}
+      >
+        <span className="tool-calls__left">
+          {summary.calling ? (
+            <span className="tool-calls__spinner" aria-hidden="true" />
+          ) : summary.failedCount > 0 ? (
+            <X className="tool-calls__icon tool-calls__icon--error" size={16} strokeWidth={2.5} />
+          ) : (
+            <Check className="tool-calls__icon tool-calls__icon--success" size={16} strokeWidth={2.5} />
+          )}
+          <span className="tool-calls__summary-text">
+            {buildSummaryText(summary).join(' · ')}
+            {summary.failedCount > 0 && (
+              <span className="tool-calls__failed"> · {summary.failedCount} 个失败</span>
+            )}
+          </span>
+        </span>
+        <CaretDown
+          size={14}
+          className={`tool-calls__chevron${expanded ? ' tool-calls__chevron--up' : ''}`}
+        />
+      </button>
+
+      {expanded && (
+        <div id={listId} className="tool-calls__list">
+          {items.map((item) => {
+            // 018 I4：prod（debug=false）恒无出入参展开入口；dev 才有详情交互
+            const hasDetail = debug && !!item.detail;
+            const detailExpanded = hasDetail && expandedDetailIds.has(item.id);
+            const detailId = `${listId}-${item.id}`;
+            const itemContent = (
+              <>
+                <span className="tool-calls__item-left">
+                  {item.status === 'calling' && (
+                    <span className="tool-calls__spinner tool-calls__spinner--sm" />
+                  )}
+                  {item.status === 'done' && (
+                    <Check className="tool-calls__icon tool-calls__icon--success" size={14} strokeWidth={2.5} />
+                  )}
+                  {item.status === 'error' && (
+                    <X className="tool-calls__icon tool-calls__icon--error" size={14} strokeWidth={2.5} />
+                  )}
+                  <span className="tool-calls__item-name">
+                    {item.label}
+                    {debug && item.techName && (
+                      <span className="tool-calls__item-tech"> · {item.techName}</span>
+                    )}
+                  </span>
+                  {item.badge && (
+                    <span className="tool-calls__badge">· {item.badge}</span>
+                  )}
+                </span>
+                {hasDetail && (
+                  <CaretDown
+                    size={12}
+                    className={`tool-calls__item-chevron${detailExpanded ? ' tool-calls__item-chevron--up' : ''}`}
+                  />
+                )}
+              </>
+            );
+
+            return (
+              <div key={item.id} className={`tool-calls__item tool-calls__item--${item.status}`}>
+                {hasDetail ? (
+                  <button
+                    type="button"
+                    className="tool-calls__item-trigger"
+                    aria-expanded={detailExpanded}
+                    aria-controls={detailId}
+                    aria-label={`${item.label}，${STATUS_TEXT[item.status]}，${detailExpanded ? '收起详情' : '查看详情'}`}
+                    onClick={() => toggleDetail(item.id)}
+                  >
+                    {itemContent}
+                  </button>
+                ) : (
+                  <div
+                    className="tool-calls__item-trigger tool-calls__item-trigger--static"
+                    role="status"
+                    aria-label={`${item.label}，${STATUS_TEXT[item.status]}`}
+                  >
+                    {itemContent}
+                  </div>
+                )}
+                {detailExpanded && item.detail && (
+                  <ToolCallInlineDetail id={detailId} item={item} />
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * 018 dev 详情区：屏显走 formatCompactToolIo（单行紧凑 + 头尾保留）；
+ * 复制走 prettyDetailText（美化全文）——屏显紧凑、粘贴友好分工。
+ */
+function ToolCallInlineDetail({ id, item }: { id: string; item: ToolCallViewItem }) {
+  const formatted = useMemo(
+    () => ({
+      input: formatCompactToolIo(item.detail?.inputText ?? ''),
+      output: formatCompactToolIo(item.detail?.outputText ?? ''),
+      inputPretty: prettyDetailText(item.detail?.inputText ?? ''),
+      outputPretty: prettyDetailText(item.detail?.outputText ?? ''),
+    }),
+    [item],
+  );
+
+  const copyIo = async (text: string, label: string) => {
+    const copied = await copyText(text);
+    void toast(copied ? `${label}已复制` : '复制失败，请重试', copied ? 'success' : 'error');
+  };
+
+  return (
+    <div id={id} className="tool-calls__detail">
+      <div className="tool-calls__detail-section">
+        <div className="tool-calls__detail-heading">
+          <span className="tool-calls__detail-label">输入</span>
+          <button
+            type="button"
+            className="tool-calls__copy"
+            aria-label={`复制${item.label}的输入`}
+            disabled={!formatted.inputPretty}
+            onClick={() => void copyIo(formatted.inputPretty, '输入')}
+          >
+            <Copy size={13} />
+            <span>复制</span>
+          </button>
+        </div>
+        <pre className="tool-calls__detail-body">{formatted.input || EMPTY_TEXT}</pre>
+      </div>
+      <div className="tool-calls__detail-section">
+        <div className="tool-calls__detail-heading">
+          <span className="tool-calls__detail-label">输出</span>
+          <button
+            type="button"
+            className="tool-calls__copy"
+            aria-label={`复制${item.label}的输出`}
+            disabled={!formatted.outputPretty}
+            onClick={() => void copyIo(formatted.outputPretty, '输出')}
+          >
+            <Copy size={13} />
+            <span>复制</span>
+          </button>
+        </div>
+        <pre
+          className={`tool-calls__detail-body${item.detail?.isError ? ' tool-calls__detail-body--error' : ''}`}
+        >
+          {formatted.output || EMPTY_TEXT}
+        </pre>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Mall 工具活动标题：只改变展示，不改协议中的技术 name。
+ * 当前模块工具使用精确中文标题；未知英文工具使用中文通用兜底，避免把技术标识泄漏到用户标题面。
+ */
+const TOOL_TITLE_BY_NAME: Readonly<Record<string, string>> = {
+  // 会员
+  queryPoints: '查询会员积分',
+  queryMemberInfo: '查询会员信息',
+  queryMemberCard: '查询会员卡',
+  queryEnrollmentForm: '查询入会状态',
+  queryEnrollmentCta: '准备入会指引',
+  queryLoginCta: '准备登录指引',
+
+  // 商场导购
+  recommend: '推荐商品',
+  'search-products': '搜索商品',
+  'product-facets': '查询商品筛选项',
+  'get-product': '查询商品详情',
+  'compare-products': '对比商品',
+  'search-shops': '搜索商场门店',
+  'get-shop': '查询门店详情',
+  'mall-directory': '查询商场楼层',
+  'get-location': '查询门店位置',
+  'list-human-guides': '查询人工导购',
+  'list-browsing-history': '查询浏览记录',
+  'list-nearby-malls': '查询附近商场',
+  'list-categories': '查询商场业态',
+  'search-knowledge': '检索商场知识',
+  'customer-service-faq': '查询客服问题',
+  'mall-context': '加载商场信息',
+  'mall-info': '查询商场信息',
+
+  // 停车
+  queryParkingFee: '查询停车费用',
+  listVehicles: '查询已绑车辆',
+  listPaymentRecords: '查询停车缴费记录',
+  queryParkingInfo: '查询停车场信息',
+  queryApplicableBenefits: '查询停车权益',
+  locateVehicle: '查找车辆位置',
+  listInvoiceableOrders: '查询可开票订单',
+  queryParkingPaymentStatus: '查询停车支付状态',
+  queryParkingPaymentDetail: '查询停车订单详情',
+
+  // 优惠活动
+  listActivityCategories: '查询活动分类',
+  listActivities: '查询商场活动',
+  getActivityDetail: '查询活动详情',
+  listActivitySessions: '查询活动场次',
+  getActivityGuide: '查询活动参与指南',
+  searchOffers: '搜索优惠',
+  getOfferDetail: '查询优惠详情',
+  listEntitlements: '查询我的优惠',
+  listPromotions: '查询促销活动',
+  getPromotionDetail: '查询促销详情',
+  getParticipationGuide: '查询参与步骤',
+  listCoupons: '查询优惠券',
+  getPackageDetail: '查询礼包详情',
+  recommendOffers: '推荐可用优惠',
+  calculateBestDeal: '测算最佳优惠',
+
+  // 碰出惊喜与平台前置工具
+  getBumpInActivity: '查询碰出惊喜活动',
+  getBumpInActivityBanner: '加载碰出惊喜活动',
+  getCurrentTime: '获取当前时间',
+
+  // 历史命名与确定性 Gallery 别名
+  'member-balance': '查询会员余额',
+  'parking-fee': '查询停车费用',
+  'parking-fee-context': '加载停车费用信息',
+  search_stores: '搜索商场门店',
+  search_mall_services: '搜索商场服务',
+  get_member_points: '查询会员积分',
+  load_parking_order: '查询停车订单',
+  search_nearby_stores: '搜索附近门店',
+  read_store_opening_hours: '查询门店营业时间',
+  search_shops_with_member_benefits_and_parking_validation_rules_for_current_mall: '搜索会员权益门店',
+  pay_order: '提交支付订单',
+};
+
+const HAN_TEXT = /[\u3400-\u9fff]/u;
+const MAX_TITLE_LENGTH = 28;
+
+function compactChineseTitle(value: string | undefined): string | undefined {
+  if (!value || !HAN_TEXT.test(value)) return undefined;
+  const firstClause = value.trim().split(/[\n。；;]/u, 1)[0]?.trim();
+  if (!firstClause) return undefined;
+  return firstClause.length > MAX_TITLE_LENGTH
+    ? `${firstClause.slice(0, MAX_TITLE_LENGTH - 1)}…`
+    : firstClause;
+}
+
+/** 中文描述 > 已登记中文标题 > 原始中文名 > 中文通用兜底。 */
+export function resolveToolTitle(
+  technicalName: string,
+  preferredText?: string,
+  fallback = '处理工具任务',
+): string {
+  return compactChineseTitle(preferredText)
+    ?? TOOL_TITLE_BY_NAME[technicalName]
+    ?? compactChineseTitle(technicalName)
+    ?? fallback;
+}

package/packages/agent-ui-kit/src/hooks/use-drag-gesture.test.ts

@@ -0,0 +1,66 @@
+// @vitest-environment happy-dom
+/**
+ * 手势通道用例。核心契约：触摸/笔参与拖拽，鼠标不参与——桌面的下拉意图由触控板双指滑动
+ * 经 wheel 表达，按住鼠标拖页面在桌面上是选中文本的惯例，不该触发下拉。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import { createElement } from 'react';
+import { useDragGesture } from './use-drag-gesture';
+
+function pointer(type: string, clientY: number, name: string) {
+  const e = new Event(name, { bubbles: true, cancelable: true }) as PointerEvent;
+  Object.defineProperties(e, {
+    pointerType: { value: type },
+    clientY: { value: clientY },
+  });
+  return e;
+}
+
+/** 极简 hook 宿主：仓库内既有写法（createRoot + flushSync），不引入额外测试依赖。 */
+function setup() {
+  const el = document.createElement('div');
+  document.body.appendChild(el);
+  const handlers = { onStart: vi.fn(), onMove: vi.fn(() => true), onEnd: vi.fn() };
+  const Host = () => {
+    useDragGesture({ scrollRef: { current: el }, ...handlers });
+    return null;
+  };
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  flushSync(() => createRoot(host).render(createElement(Host)));
+  return { el, handlers };
+}
+
+describe('useDragGesture', () => {
+  it('D1 触摸指针参与拖拽', () => {
+    const { el, handlers } = setup();
+    el.dispatchEvent(pointer('touch', 100, 'pointerdown'));
+    el.dispatchEvent(pointer('touch', 160, 'pointermove'));
+    expect(handlers.onStart).toHaveBeenCalledWith({ clientY: 100 });
+    expect(handlers.onMove).toHaveBeenCalledWith({ clientY: 160 });
+  });
+
+  it('D2 鼠标拖拽被忽略（桌面单指拖拽不响应，交给 wheel 通道）', () => {
+    const { el, handlers } = setup();
+    el.dispatchEvent(pointer('mouse', 100, 'pointerdown'));
+    el.dispatchEvent(pointer('mouse', 160, 'pointermove'));
+    expect(handlers.onStart).not.toHaveBeenCalled();
+    expect(handlers.onMove).not.toHaveBeenCalled();
+  });
+
+  it('D3 笔同触摸（手写笔在触屏设备上是等价输入）', () => {
+    const { el, handlers } = setup();
+    el.dispatchEvent(pointer('pen', 50, 'pointerdown'));
+    el.dispatchEvent(pointer('pen', 90, 'pointermove'));
+    expect(handlers.onStart).toHaveBeenCalledTimes(1);
+    expect(handlers.onMove).toHaveBeenCalledTimes(1);
+  });
+
+  it('D4 未按下时的移动不算拖拽', () => {
+    const { el, handlers } = setup();
+    el.dispatchEvent(pointer('touch', 160, 'pointermove'));
+    expect(handlers.onMove).not.toHaveBeenCalled();
+  });
+});