---
title: Chain of Thought
description: 多步推理与工具调用的时间线
category: AiReasoning
status: beta
since: 0.3.9
tags: [ai, reasoning, timeline]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="ChainOfThoughtChainOfThoughtDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const steps = [
    { id: '1', kind: 'thinking', title: '拆解需求', body: '先确认输入边界。', status: 'done' },
    { id: '2', kind: 'tool', title: 'read_file(src/main.ts)', status: 'done' },
    { id: '3', kind: 'thinking', title: '正在推导实现', body: '排序是瓶颈…', status: 'active' },
  ]
  </script>

  <template>
    <TxChainOfThought :steps="steps" streaming />
  </template>
---
::::

### 最佳实践

- `id` 用稳定标识，不用数组下标。
- 同一时刻最多一个 `active` 步骤；正文跟随只作用于其中一个。
- 思考正文可以整段一次性送入：组件自己按节奏逐步放出，不需要宿主把一段文字拆成字再喂。
- 步骤结束时把 `status` 改为 `done` 或 `error`，否则旋转指示会一直留着。
- 工具步骤的 `title` 写成调用签名（`read_file(src/main.ts)`），不只写工具名。
- 需要自定义步骤渲染时，组合 `TxReasoningDisclosure` 与 `TxToolCallCard`。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `steps` | `AiChainStep[]` | — | 步骤列表，必填。`AiChainStep` 为 `{ id, kind: 'thinking' \| 'tool', title, body?, status: 'active' \| 'done' \| 'error', durationMs? }`。 |
| `streaming` | `boolean` | `false` | 仍在输出；有 `active` 步骤时头部显示思考球。 |
| `defaultOpen` | `boolean` | `true` | 不在流式时的展开状态。 |
| `label` | `string` | `'Chain of thought'` | 头部文案；非英文界面需覆盖。 |
| `userOpen` | `boolean` | — | 宿主持有的展开状态，优先级最高；回写 `toggle` 可跨重新挂载保留。 |
| `collapseDelayMs` | `number` | `2000` | 流式时，最后一个活跃步骤结束后保持展开的毫秒数，之后收起；`0` 表示立即收起。 |
| `bullets` | `boolean` | `steps.length > 1` | 是否显示步骤圆点状态指示器。单步思考默认省略。 |
### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `toggle` | `(open: boolean)` | 点击头部时触发，参数为切换后的状态。 |

## 概述

- 展开状态：`userOpen` 优先，其次是用户点击；流式时有 `active` 步骤就展开；最后一个活跃步骤结束后，保持展开 `collapseDelayMs`（默认 2000 毫秒）再收起；不在流式时取 `defaultOpen`。
- 思考步骤的 `body` 在 `streaming` 且该步骤为 `active` 时按节奏逐步显示（与流式文本同一时钟：节奏稳定，积压会在约 0.6 秒内追平）；已结束的步骤和减弱动效偏好下立即全量显示。显示出来的永远是已收到文本的前缀，不会被改写；未写完的 Markdown 标记（如 `**加粗`）先临时闭合，不会露出星号。
- 思考正文放出时会跟随到底部；读者向上滚动查看后停止跟随，回到底部附近后恢复。工具步骤的 `body` 变长时，活跃步骤的正文滚到底部。
- `done` 步骤带 `durationMs` 时，标题后显示耗时（`· 3.2s`，10 秒及以上取整秒）。
- 头部计数为 `steps.length`，只有一步时不显示。
- 头部是原生 `<button>`，带 `aria-expanded` 与 `aria-controls`；步骤列表是 `<ol>`。

## 技术实现

- 思考正文经 `use-paced-text.ts` 包装 `useStreamPacer`，与 `TxStreamText` 同一时钟放出；已结束的步骤与减弱动效时直接全量显示。
- 展开宽限由 `watch` 驱动的计时器实现，卸载时清理。
- 源码：`packages/tuffex/packages/components/src/chain-of-thought/`。

<TuffDocSourceLink />
