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

package/packages/agent-ui-kit/src/utils/pull-down-machine.ts

@@ -0,0 +1,157 @@
+/**
+ * 下拉加载历史手势状态机（纯逻辑，零 React 依赖，node 可测）。
+ * 核心修正：touchStart 不再锁定 isAtTop（旧实现在未滚动容器上初始 false → 全新手势死区），
+ * 门控移到 touchMove 实时判定——未到顶时每次重锚，到顶后从最近锚点测距；
+ * wheel 为桌面回退（顶部向上滚累积，越阈即发，发后归零）。
+ * 阈值三分：PULL_DOWN_THRESHOLD 只管指示器视觉，PULL_TRIGGER_OFFSET 管触摸触发，
+ * WHEEL_TRIGGER_ACCUM 管滚轮触发——共用一个常量会让「看得见」等同于「要加载」。
+ * wrapper（use-pull-down-history）职责：状态镜像 / 定时器 / disabled 短路；
+ * 业务防抖权威在 store（isLoadingHistory），机器内 isLoading 忽略为双保险。
+ */
+
+/** 指示器完全露出所需的阻尼后位移——纯视觉基准（PullDownIndicator 的 marginTop 同源）。 */
+export const PULL_DOWN_THRESHOLD = 60;
+/**
+ * 触发加载所需的**内容位移**，对齐平台惯例：iOS UIRefreshControl 实际在 60~80pt 触发
+ * （控件自身高约 60pt），Android SwipeRefreshLayout 默认 64dp（DEFAULT_CIRCLE_TARGET）。
+ * 取 64 落在两者交集；阻尼 0.5 下对应手指行程 128px。
+ * 注意这些惯例量的是内容位移而非手指行程——按手指行程设阈值会得到四五倍的错值。
+ */
+export const PULL_TRIGGER_OFFSET = 64;
+/**
+ * 桌面滚轮累积触发阈值（单独于触摸）：一次滚轮事件 deltaY 常见 100+，
+ * 与触摸共用 60 会「一滚即加载」；这里要求连续向上滚约三次。
+ */
+export const WHEEL_TRIGGER_ACCUM = 128;
+/** wheel 累积 → 拖拽尺度的换算比，使两条路径的位移与文案切换点重合。 */
+export const WHEEL_DISTANCE_SCALE = PULL_TRIGGER_OFFSET / WHEEL_TRIGGER_ACCUM;
+/** wheel 停止多久后复位视觉（ms）——触控板惯性滚动的间隔通常远小于此。 */
+export const WHEEL_IDLE_RESET_MS = 220;
+/**
+ * 拖拽阻尼：原生下拉在小位移区间接近 1:1 跟手，0.4 会显得「沉」（手指 100px 内容才动 40px）。
+ * 0.5 兼顾跟手感与「越拉越沉」的物理暗示。
+ */
+export const DAMPING = 0.5;
+/** noMore 展示保持时长（wrapper 定时后 reset；机器内部无定时器保 node 可测） */
+export const NO_MORE_HOLD_MS = 1500;
+
+export type PullStatus = 'idle' | 'pulling' | 'ready' | 'loading' | 'noMore';
+
+export interface PullDownState {
+  status: PullStatus;
+  distance: number;
+}
+
+export function createPullDownMachine() {
+  let status: PullStatus = 'idle';
+  let distance = 0;
+  let startY = 0;
+  let wheelAccum = 0;
+
+  /** 同步置 loading（touchEnd 越阈触发；离开由 wrapper 在 onLoad 完成后 reset()） */
+  const enterLoading = () => {
+    status = 'loading';
+    distance = PULL_DOWN_THRESHOLD;
+  };
+
+  const resetDistance = () => {
+    if (status !== 'idle' && status !== 'noMore') {
+      status = 'idle';
+    }
+    if (status !== 'noMore') distance = 0;
+  };
+
+  return {
+    getState(): PullDownState {
+      return { status, distance };
+    },
+
+    touchStart(clientY: number): void {
+      startY = clientY;
+    },
+
+    touchMove(i: { clientY: number; isAtTop: boolean; hasMore: boolean; isLoading: boolean }): { preventDefault: boolean } {
+      if (i.isLoading) return { preventDefault: false };
+      // 未到顶：重锚（原生滚动照常），状态回 idle（noMore 保留——顶部已无更多的展示态）
+      if (!i.isAtTop) {
+        startY = i.clientY;
+        resetDistance();
+        return { preventDefault: false };
+      }
+      const deltaY = i.clientY - startY;
+      if (deltaY <= 0) {
+        resetDistance();
+        return { preventDefault: false };
+      }
+      if (!i.hasMore) {
+        status = 'noMore';
+        distance = Math.min(deltaY * DAMPING, PULL_DOWN_THRESHOLD);
+        return { preventDefault: true };
+      }
+      distance = deltaY * DAMPING;
+      status = distance > PULL_TRIGGER_OFFSET ? 'ready' : 'pulling';
+      return { preventDefault: true };
+    },
+
+    touchEnd(i: { hasMore: boolean }): { shouldLoad: boolean; holdNoMore: boolean } {
+      if (status === 'ready' && i.hasMore) {
+        enterLoading();
+        return { shouldLoad: true, holdNoMore: false };
+      }
+      if (status === 'noMore') {
+        return { shouldLoad: false, holdNoMore: true }; // wrapper 定时后 reset
+      }
+      status = 'idle';
+      distance = 0;
+      return { shouldLoad: false, holdNoMore: false };
+    },
+
+    /**
+     * 触控板双指滑动 / 滚轮。与拖拽的差别是没有「松手」这一刻，故越阈即发、不经 ready 等释放。
+     * 但累积过程同样驱动 status/distance——否则双指滑动全程无反馈、加载突然发生，
+     * 与拖拽的观感对不上。distance 按触发线之比换算到与拖拽同一尺度，胶囊位移与文案才同步。
+     */
+    wheel(i: { deltaY: number; isAtTop: boolean; hasMore: boolean; isLoading?: boolean }): { shouldLoad: boolean } {
+      // 加载中全忽略：触控板惯性会在加载期间继续送 wheel，若放行会把 status 从 loading
+      // 改回 pulling、distance 反复增减——表现为动画弹来弹去（touchMove 同守卫）。
+      if (i.isLoading || status === 'loading') return { shouldLoad: false };
+      // 离顶 / 向下滚：累积与视觉一并复位
+      if (!i.isAtTop || i.deltaY >= 0) {
+        wheelAccum = 0;
+        resetDistance();
+        return { shouldLoad: false };
+      }
+      wheelAccum -= i.deltaY;
+      if (!i.hasMore) {
+        status = 'noMore';
+        distance = Math.min(wheelAccum * WHEEL_DISTANCE_SCALE, PULL_DOWN_THRESHOLD);
+        return { shouldLoad: false };
+      }
+      if (wheelAccum > WHEEL_TRIGGER_ACCUM) {
+        wheelAccum = 0;
+        enterLoading();
+        return { shouldLoad: true };
+      }
+      distance = wheelAccum * WHEEL_DISTANCE_SCALE;
+      status = 'pulling';
+      return { shouldLoad: false };
+    },
+
+    /**
+     * wheel 停止后由 wrapper 定时调用：清掉累积与视觉，避免文案卡在拉动态。
+     * loading 期间只清累积不动视觉——此刻的 loading 由加载完成时的 reset 收尾，
+     * 在这里复位会把「加载中」文案打回「历史记录」。
+     */
+    wheelIdle(): void {
+      wheelAccum = 0;
+      if (status !== 'loading') resetDistance();
+    },
+
+    reset(): void {
+      status = 'idle';
+      distance = 0;
+      startY = 0;
+      wheelAccum = 0;
+    },
+  };
+}

package/packages/agent-ui-kit/src/utils/tool-call-display.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from 'vitest';
+import { describeToolCall, formatCompactToolIo } from './tool-call-display';
+import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import { buildPreToolArgsPayload, buildPreToolResultPayload } from '@tbox.cn/app-contracts';
+import {
+  buildMemoryToolCallPayload,
+  buildSkillToolCallPayload,
+  MEMORY_TOOL_CALL_NAME,
+} from '@tbox.cn/app-contracts';
+
+const normal = (over: Partial<ToolCallInfo> = {}): ToolCallInfo => ({
+  id: 't1',
+  name: 'getWeather',
+  status: 'done',
+  result: JSON.stringify({ temp: 22 }),
+  ...over,
+});
+
+describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
+  it('skill：label 取 skillName，无详情', () => {
+    const { args } = buildSkillToolCallPayload({ name: 'weather-guide', description: '天气' });
+    const d = describeToolCall({
+      id: 's1',
+      name: '__tbox_skill',
+      args,
+      result: '{}',
+      status: 'done',
+    });
+    expect(d).toEqual({ kind: 'skill', label: 'weather-guide', hasDetail: false });
+  });
+
+  it('preTool done：label 取 description、详情 = 结果文本', () => {
+    const args = buildPreToolArgsPayload({
+      toolName: 'getWeather',
+      description: '天气查询',
+      toolArgs: { city: '杭州' },
+    });
+    const result = buildPreToolResultPayload({
+      toolName: 'getWeather',
+      status: 'done',
+      result: { temp: 22 },
+    });
+    const d = describeToolCall({
+      id: 'p1',
+      name: '__tbox_pretool',
+      args,
+      result,
+      status: 'done',
+    });
+    expect(d.kind).toBe('preTool');
+    if (d.kind === 'preTool') {
+      expect(d.label).toBe('天气查询');
+      expect(d.status).toBe('done');
+      expect(d.hasDetail).toBe(true);
+      expect(d.resultText).toContain('"temp": 22');
+    }
+  });
+
+  it('preTool calling：label 可用（ARGS 先行）、无详情', () => {
+    const args = buildPreToolArgsPayload({ toolName: 'getWeather', description: '天气查询' });
+    const d = describeToolCall({
+      id: 'p2',
+      name: '__tbox_pretool',
+      args,
+      status: 'calling',
+    });
+    expect(d.kind).toBe('preTool');
+    if (d.kind === 'preTool') {
+      expect(d.status).toBe('calling');
+      expect(d.hasDetail).toBe(false);
+      expect(d.label).toBe('天气查询');
+    }
+  });
+
+  it('preTool error：经 result payload status 判定（ToolCallInfo.status 恒 done，R 语义）', () => {
+    const args = buildPreToolArgsPayload({ toolName: 'getWeather', description: '天气查询' });
+    const result = buildPreToolResultPayload({
+      toolName: 'getWeather',
+      status: 'error',
+      error: '超时',
+    });
+    const d = describeToolCall({
+      id: 'p3',
+      name: '__tbox_pretool',
+      args,
+      result,
+      status: 'done',
+    });
+    expect(d.kind).toBe('preTool');
+    if (d.kind === 'preTool') {
+      expect(d.status).toBe('error');
+      expect(d.errorText).toBe('超时');
+    }
+  });
+
+  it('preTool 容错：ARGS 非法 → label 降级空串、状态不崩', () => {
+    const d = describeToolCall({
+      id: 'p4',
+      name: '__tbox_pretool',
+      args: 'not-json',
+      result: 'not-json',
+      status: 'done',
+    });
+    expect(d.kind).toBe('preTool');
+    if (d.kind === 'preTool') {
+      expect(d.label).toBe('');
+      expect(d.status).toBe('done');
+    }
+  });
+
+  it('normal：label = 工具名，详情 = 有 result/error', () => {
+    expect(describeToolCall(normal())).toEqual({
+      kind: 'normal',
+      label: 'getWeather',
+      hasDetail: true,
+    });
+    expect(describeToolCall(normal({ status: 'calling', result: undefined }))).toEqual({
+      kind: 'normal',
+      label: 'getWeather',
+      hasDetail: false,
+    });
+  });
+});
+
+describe('describeToolCall memory 分支（018 tool-debug）', () => {
+  const memoryTc = (over: Partial<ToolCallInfo> = {}): ToolCallInfo => {
+    const payload = buildMemoryToolCallPayload({
+      query: '推荐美食',
+      status: 'hit',
+      records: [
+        { id: 'm1', kind: 'preference', content: '用户爱吃辣' },
+        { id: 'm2', kind: 'fact', content: '用户是会员' },
+      ],
+      durMs: 120,
+    });
+    return {
+      id: 'mem1',
+      name: MEMORY_TOOL_CALL_NAME,
+      args: payload.args,
+      result: payload.result,
+      status: 'done',
+      ...over,
+    };
+  };
+
+  it('hit：label 带命中数，详情 = records 预览', () => {
+    const d = describeToolCall(memoryTc());
+    expect(d.kind).toBe('memory');
+    if (d.kind === 'memory') {
+      expect(d.status).toBe('hit');
+      expect(d.hits).toBe(2);
+      expect(d.label).toBe('记忆召回 · 2 条命中');
+      expect(d.hasDetail).toBe(true);
+      expect(d.detailText).toContain('[preference] 用户爱吃辣');
+      expect(d.detailText).toContain('[fact] 用户是会员');
+    }
+  });
+
+  it('miss：无详情（I3/S1——miss 仅 label 表达）', () => {
+    const payload = buildMemoryToolCallPayload({ query: 'x', status: 'miss' });
+    const d = describeToolCall(
+      memoryTc({ args: payload.args, result: payload.result }),
+    );
+    expect(d.kind).toBe('memory');
+    if (d.kind === 'memory') {
+      expect(d.status).toBe('miss');
+      expect(d.hits).toBe(0);
+      expect(d.hasDetail).toBe(false);
+      expect(d.label).toBe('记忆召回');
+    }
+  });
+
+  it('degraded：详情 = 错误信息（调试载荷即错误本身）', () => {
+    const payload = buildMemoryToolCallPayload({
+      query: 'x',
+      status: 'degraded',
+      error: '记忆召回超时（600ms deadline）',
+    });
+    const d = describeToolCall(
+      memoryTc({ args: payload.args, result: payload.result }),
+    );
+    expect(d.kind).toBe('memory');
+    if (d.kind === 'memory') {
+      expect(d.status).toBe('degraded');
+      expect(d.hasDetail).toBe(true);
+      expect(d.detailText).toBe('记忆召回超时（600ms deadline）');
+    }
+  });
+
+  it('skipped：reason 意图命中进 label、无详情', () => {
+    const payload = buildMemoryToolCallPayload({ query: 'x', status: 'skipped', reason: 'intent' });
+    const d = describeToolCall(
+      memoryTc({ args: payload.args, result: payload.result }),
+    );
+    expect(d.kind).toBe('memory');
+    if (d.kind === 'memory') {
+      expect(d.status).toBe('skipped');
+      expect(d.label).toBe('记忆召回 · 跳过（意图命中）');
+      expect(d.hasDetail).toBe(false);
+    }
+  });
+
+  it('容错：result 非法 JSON → miss 降级不崩', () => {
+    const d = describeToolCall(memoryTc({ result: 'not-json' }));
+    expect(d.kind).toBe('memory');
+    if (d.kind === 'memory') {
+      expect(d.status).toBe('miss');
+      expect(d.hasDetail).toBe(false);
+    }
+  });
+});
+
+describe('formatCompactToolIo（018 dev 紧凑格式）', () => {
+  it('合法 JSON → 单行化', () => {
+    expect(formatCompactToolIo('{"a": 1, "b": [2, 3]}')).toBe('{"a":1,"b":[2,3]}');
+  });
+
+  it('短文本原样返回', () => {
+    expect(formatCompactToolIo('plain text')).toBe('plain text');
+    expect(formatCompactToolIo('')).toBe('');
+  });
+
+  it('超长 → 头尾保留 + 中段省略标记（tail 300 保尾部 cards/错误）', () => {
+    const head = 'h'.repeat(900);
+    const middle = 'm'.repeat(500);
+    const tail = 't'.repeat(300);
+    const out = formatCompactToolIo(head + middle + tail);
+    expect(out).toContain(head.slice(0, 100));
+    expect(out).toContain(tail.slice(-100));
+    expect(out).toContain('已省略 500 字符');
+    expect(out).not.toContain(middle.slice(0, 50));
+  });
+
+  it('自定义截断参数', () => {
+    const out = formatCompactToolIo('a'.repeat(100), { head: 20, tail: 10 });
+    expect(out).toContain('已省略 70 字符');
+    expect(out.startsWith('a'.repeat(20))).toBe(true);
+    expect(out.endsWith('a'.repeat(10))).toBe(true);
+  });
+});

package/packages/agent-ui-kit/src/utils/tool-call-display.ts

@@ -0,0 +1,146 @@
+/**
+ * 工具展示语义判定（010 下沉 S5）：「什么伪工具怎么显示」是框架语义，不该散在 UI 组件。
+ * - describeToolCall：ToolCallInfo → ToolCallDisplay 四分支（skill / preTool / normal / memory）；
+ * - 纯函数零 UI 语义：徽标/颜色/展开交互留装配层（模板 ToolCallBlock 纯渲染）；
+ * - preTool error 态经 result payload 的 status 判定（preTool 通道的 RESULT 恒置 done——
+ *   isError 仅模型路径工具失败终态，R''8）——新增伪工具类型只需在此加 case；
+ * - memory（018 tool-debug）：状态从 result envelope 派生（合成路径 RESULT 恒 done，
+ *   ToolCallInfo.status 不承载语义，preTool 同款 R''8）。
+ */
+import {
+  MEMORY_TOOL_CALL_NAME,
+  PRE_TOOL_CALL_NAME,
+  SKILL_TOOL_CALL_NAME,
+  parseMemoryToolCallResult,
+  parsePreToolToolCallArgs,
+  parsePreToolToolCallResult,
+  parseSkillToolCallArgs,
+} from '@tbox.cn/app-contracts';
+import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+
+export type ToolCallDisplay =
+  | { kind: 'skill'; label: string; hasDetail: false }
+  | {
+      kind: 'preTool';
+      label: string;
+      status: 'calling' | 'done' | 'error';
+      hasDetail: boolean;
+      resultText?: string;
+      errorText?: string;
+    }
+  | { kind: 'normal'; label: string; hasDetail: boolean }
+  | {
+      kind: 'memory';
+      label: string;
+      /** 召回结果语义（result envelope 派生） */
+      status: 'hit' | 'miss' | 'degraded' | 'skipped';
+      /** 命中条数（hit ≥1，其余 0） */
+      hits: number;
+      hasDetail: boolean;
+      /** 详情文本（hit: records 预览；degraded: 错误信息）；miss/skipped 缺省 */
+      detailText?: string;
+    };
+
+function prettyJson(value: unknown): string {
+  try {
+    return JSON.stringify(JSON.parse(JSON.stringify(value)), null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+/** skipped reason 机器值 → 展示文案（未知值降级省略） */
+const MEMORY_SKIP_REASON_TEXT: Record<string, string> = { intent: '意图命中' };
+
+export function describeToolCall(tc: ToolCallInfo): ToolCallDisplay {
+  if (tc.name === SKILL_TOOL_CALL_NAME) {
+    const args = parseSkillToolCallArgs(tc.args);
+    return { kind: 'skill', label: args?.skillName ?? '', hasDetail: false };
+  }
+
+  if (tc.name === PRE_TOOL_CALL_NAME) {
+    const args = parsePreToolToolCallArgs(tc.args);
+    const result = parsePreToolToolCallResult(tc.result);
+    const status: 'calling' | 'done' | 'error' =
+      tc.status === 'calling' ? 'calling' : result?.status === 'error' ? 'error' : 'done';
+    return {
+      kind: 'preTool',
+      label: args?.description ?? args?.toolName ?? '',
+      status,
+      // 详情：done → 结果（有用户价值）；error → 错误文案；calling → 无
+      hasDetail: status !== 'calling' && !!tc.result,
+      ...(status === 'done' && result?.result !== undefined
+        ? { resultText: prettyJson(result.result) }
+        : {}),
+      ...(status === 'error' ? { errorText: result?.error ?? '预执行失败' } : {}),
+    };
+  }
+
+  if (tc.name === MEMORY_TOOL_CALL_NAME) {
+    const result = parseMemoryToolCallResult(tc.result);
+    const status = result?.status ?? 'miss';
+    const hits = status === 'hit' ? (result?.hits ?? 0) : 0;
+    const skipText =
+      status === 'skipped' && result?.reason
+        ? MEMORY_SKIP_REASON_TEXT[result.reason]
+        : undefined;
+    const label =
+      status === 'hit'
+        ? `记忆召回 · ${hits} 条命中`
+        : status === 'degraded'
+          ? '记忆召回降级'
+          : status === 'skipped'
+            ? `记忆召回 · 跳过${skipText ? `（${skipText}）` : ''}`
+            : '记忆召回';
+    const detailText =
+      status === 'degraded'
+        ? (result?.error ?? '记忆召回超时或存储异常')
+        : status === 'hit' && result?.records && result.records.length > 0
+          ? result.records.map((r) => `[${r.kind}] ${r.text}`).join('\n')
+          : undefined;
+    return {
+      kind: 'memory',
+      label,
+      status,
+      hits,
+      hasDetail: !!detailText,
+      ...(detailText !== undefined ? { detailText } : {}),
+    };
+  }
+
+  return {
+    kind: 'normal',
+    label: tc.name,
+    hasDetail: !!(tc.result || tc.error),
+  };
+}
+
+// ===== 紧凑 IO 格式化（018 dev 视图；纯函数单源——双模板共用） =====
+
+const COMPACT_IO_HEAD = 900;
+const COMPACT_IO_TAIL = 300;
+
+/**
+ * 工具出入参紧凑格式化（018 dev 视图）：
+ * - 合法 JSON → 单行化（无缩进 stringify）；超长 → 头尾保留 + 中段省略标记
+ *   （head > tail 刻意为之：cards 字段与错误信息恒在尾部——修正 500 头截断截掉要害的缺陷）；
+ * - 非法 JSON 原文同策略截断；
+ * - 仅服务屏显紧凑；复制场景请用原文/美化全文，不经本函数。
+ */
+export function formatCompactToolIo(
+  raw: string,
+  opts?: { head?: number; tail?: number },
+): string {
+  if (!raw) return '';
+  const head = opts?.head ?? COMPACT_IO_HEAD;
+  const tail = opts?.tail ?? COMPACT_IO_TAIL;
+  let text = raw;
+  try {
+    text = JSON.stringify(JSON.parse(raw));
+  } catch {
+    // 非 JSON：原文截断
+  }
+  if (text.length <= head + tail) return text;
+  const omitted = text.length - head - tail;
+  return `${text.slice(0, head)}\n…[已省略 ${omitted} 字符]…\n${text.slice(-tail)}`;
+}

package/packages/agent-ui-kit/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/packages/agent-ui-kit/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src"]
+}

package/packages/agent-ui-kit/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    setupFiles: ['src/test/setup.ts'],
+  },
+});