AgentTrace 智能体轨迹
可展开的智能体执行轨迹
用法
步骤轨迹
时间轴由宿主推进:追加 rows,跑完后把 working 设为 false。
Loading demo...
四种形态
variant 只改变行的形态,头部与折叠方式不变。
Loading demo...
最佳实践
- 时间轴留在宿主:追加
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(© 2026 Shane Levine,MIT)。
- 源码:
packages/tuffex/packages/components/src/agent-trace/。
查看源码
packages/tuffex/packages/components/src/agent-trace/index.ts
相关组件
- Chain of Thought:带 Markdown 正文的思考链。
- Reasoning Disclosure:单段推理。
- Sources:来源列表。