---
title: "AgentTrace 智能体轨迹"
description: "可展开的智能体执行轨迹"
category: AiAgent
status: beta
since: 0.3.9
tags: [ai, agent, trace, disclosure]
syncStatus: reviewed
verified: true
---

## 用法

### 步骤轨迹
时间轴由宿主推进：追加 `rows`，跑完后把 `working` 设为 `false`。
:::TuffDemoWrapper{demo="AgentTraceStepsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAgentTrace
      :rows="rows"
      :working="working"
      :default-open="open"
      done-label="思考了 4 秒"
    />
  </template>
---
:::

### 四种形态
`variant` 只改变行的形态，头部与折叠方式不变。
:::TuffDemoWrapper{demo="AgentTraceVariantsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAgentTrace
      :key="variant"
      :variant="variant"
      :rows="datasets[variant]"
      :query="variant === 'search' ? '最好的华夫蛋筒供应商' : undefined"
      :more-label="variant === 'search' ? '还有 7 条' : undefined"
      default-open
      @open="openInBrowser"
    />
  </template>
---
:::

### 最佳实践

- 时间轴留在宿主：追加 `rows`、翻转 `working`，不要把播放脚本放进组件。
- `search` 形态必须处理 `open`，否则点击没有任何效果。
- 长轨迹用 `moreLabel` 收尾，不要铺开几十行。
- 成段散文用 `reasoning`（换行、不截断），单行标签用 `steps`。
- 流式界面把 `toggle` 存到宿主再传回 `userOpen`，实例重建后仍保留读者的选择。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `rows` | `AgentTraceRow[]` | — | 轨迹行，必填。 |
| `variant` | `'steps' \| 'reasoning' \| 'search' \| 'coding'` | `'steps'` | 行的形态与排版。 |
| `query` | `string` | — | `search` 形态在结果上方回显的查询。 |
| `working` | `boolean` | `false` | 是否仍在运行，驱动微光与转圈。 |
| `activeLabel` | `string` | 按形态 | 运行中的头部文案。 |
| `doneLabel` | `string` | 按形态 | 结束后的头部文案。 |
| `moreLabel` | `string` | — | 末尾的溢出说明，例如 `还有 7 条`。 |
| `defaultOpen` | `boolean` | — | 交互前的展开状态；缺省时取 `working`。 |
| `userOpen` | `boolean` | — | 宿主持有的展开状态，优先级最高，实例重建后仍有效。 |
| `selectedId` | `string` | — | `coding` 形态选中的行 id；绑定后选中态由宿主接管。 |

各形态的默认头部文案如下；「思考了 4 秒」这类带计数的文案只有宿主知道，需自行传 `doneLabel`。

| 形态 | `activeLabel` | `doneLabel` |
|------|------|------|
| `steps` / `reasoning` | `Thinking` | `Thought` |
| `search` | `Searching the web` | `Searched the web` |
| `coding` | `Running tools` | `Ran tools` |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `toggle` | `(open: boolean)` | 点击头部时触发，参数为切换后的状态。 |
| `open` | `(row: AgentTraceRow)` | `search` 形态点击带链接的行时触发；组件不会自行跳转。 |
| `select` | `(id: string \| null)` | `coding` 形态选中或取消选中时触发，取消时为 `null`。 |

### 插槽

| 插槽名 | 作用域参数 | 说明 |
|------|------|------|
| `icon` | `{ working }` | 替换头部的星芒图标。 |
| `label` | `{ working }` | 替换头部文案。 |
| `row` | `{ row, index }` | 替换行内容，保留行容器与入场动画。 |

### 类型

#### AgentTraceRow

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `string` | 行的稳定 key。 |
| `primary` | `string` | 步骤名、推理句、网站标题或工具名。 |
| `secondary` | `string` | 右侧详情：计数、域名、文件路径或命令。 |
| `mono` | `boolean` | `secondary` 改用等宽字体。 |
| `added` / `removed` | `number` | 差分计数，显示为 `+N −M`，减号是 U+2212。 |
| `href` | `string` | `search` 形态下行渲染为链接，点击派发 `open`。 |
| `status` | `'pending' \| 'active' \| 'done' \| 'error'` | `steps` 形态的图标：`active` 转圈，`error` 画叉，其余打勾。 |

## 概述

- 展开状态依次取 `userOpen`、用户点击、`defaultOpen`、`working`；用户点击只保存在实例内。
- 头部是 `button`，带 `aria-expanded` 与 `aria-controls`；收起时折叠区设 `inert`，行移出 Tab 序列。
- `search` 行保留真实 `href`（可复制、可中键打开），点击时 `preventDefault` 并派发 `open`，由宿主决定打开方式。
- 不传 `status` 时，`working` 期间只有最后一行转圈。
- `coding` 行是带 `aria-pressed` 的 `button`。
- 减少动态效果时只停动画，开合与状态照常。

## 技术实现

- 移植自 [Beautiful UI](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）。
- 源码：`packages/tuffex/packages/components/src/agent-trace/`。

<TuffDocSourceLink />

## 相关组件

- [Chain of Thought](./chain-of-thought.zh.mdc)：带 Markdown 正文的思考链。
- [Reasoning Disclosure](./reasoning-disclosure.zh.mdc)：单段推理。
- [Sources](./sources.zh.mdc)：来源列表。
