---
title: "ToolChips 工具调用流"
description: "一次智能体运行的紧凑工具调用流"
category: AiAgent
status: beta
since: 0.3.9
tags: [ai, tool, diff, disclosure]
syncStatus: reviewed
verified: true
---

## 用法

### 运行流
`rows` 随数据到达增长，`diffs` 汇总本次改动的文件。
:::TuffDemoWrapper{demo="ToolChipsRunFlowDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const rows = [
    {
      id: 'think',
      label: '思考',
      chip: '正在规划搅拌排期…',
      icon: 'think',
      detail: [{ text: '周末需求集中在开心果，先churn它。' }],
    },
    {
      id: 'write',
      label: '写入 204 行',
      chip: 'ChurnSchedule.tsx',
      icon: 'write',
      mono: true,
      detailMono: true,
      detail: [{ text: '+ const windows = slots.filter(Boolean)', tone: 'add' }],
    },
  ]

  const diffs = [
    { file: 'flavors.css', add: 13, del: 0 },
    { file: 'ChurnSchedule.tsx', add: 74, del: 41 },
  ]
  </script>

  <template>
    <TxToolChips :rows="rows" :diffs="diffs" :more-count="2" />
  </template>
---
:::

### 单独使用差分区
`TxDiffChips` 单独导出，不需要外层的工具调用流。

```vue
<script setup lang="ts">
import { TxDiffChips } from '@talex-touch/tuffex/tool-chips'

const diffs = [
  { file: 'flavors.css', add: 13, del: 0 },
  { file: 'menu.ts', add: 8, del: 2 },
]
</script>

<template>
  <TxDiffChips :diffs="diffs" :more-count="2" @select="openFile" />
</template>
```

### 最佳实践

- `label` 写做了什么（「写入 204 行」），`chip` 写对什么做的（文件名、命令）：折叠时只有这两段可扫读。
- 路径与命令开 `mono`，散文不开。
- 详情控制在两三行，长日志改用 `TxToolCallCard`。
- 差分只列前几项，其余交给 `moreCount`。
- 流式界面由宿主持有 `expandedRows`，组件重建后读者的展开选择不会丢。

## API 参考

### TxToolChips

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `rows` | `ToolChipRow[]` | — | 行数据，必填。 |
| `diffs` | `ToolChipDiff[]` | `[]` | 差分数据；为空时差分区连同分隔线不渲染。 |
| `summary` | `string` | — | 折叠头文案；不传时由 `summaryFormatter` 生成。 |
| `summaryFormatter` | `(rowCount: number) => string` | `` n => `${n} tool call${n === 1 ? '' : 's'}` `` | 折叠头的默认文案，按数量处理单复数。 |
| `open` | `boolean` | — | 整组展开状态，配合 `v-model:open`；不传则组件自持。 |
| `defaultOpen` | `boolean` | `true` | 非受控时的初始展开状态。 |
| `expandedRows` | `string[]` | — | 已展开行的 id，配合 `v-model:expandedRows`。 |
| `defaultExpandedRows` | `string[]` | `[]` | 非受控时初始展开的行。 |
| `moreCount` | `number` | `0` | 差分区未列出的数量。 |
| `moreLabelFormatter` | `(count: number) => string` | `` n => `+${n} more` `` | 溢出控件的文案。 |

#### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:open` | `(open: boolean)` | 整组展开或收起时触发。 |
| `update:expandedRows` | `(ids: string[])` | 展开的行变化时触发。 |
| `toggle` | `(id: string, expanded: boolean)` | 某行切换时触发，参数为切换后的状态。 |
| `rowClick` | `(row: ToolChipRow)` | 点击行时触发，与 `toggle` 同时派发。 |
| `diffClick` | `(diff: ToolChipDiff)` | 点击差分 chip 时触发。 |
| `more` | `()` | 点击差分区的溢出控件时触发。 |

#### 插槽

| 插槽名 | 作用域参数 | 说明 |
|------|------|------|
| `row-icon` | `{ row }` | 替换行图标；`icon` 不是内置值时必须提供。 |
| `chip` | `{ row }` | 替换行尾 chip 的内容。 |
| `detail` | `{ row }` | 替换展开后的详情。 |
| `diffs` | `{ diffs }` | 替换差分区内容，分隔线保留。 |

#### 暴露方法

| 方法 | 说明 |
|------|------|
| `expand(id)` / `collapse(id)` | 展开或收起指定行；已是该状态时不执行。 |
| `expandAll()` / `collapseAll()` | 展开或收起全部行。 |

### TxDiffChips

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `diffs` | `ToolChipDiff[]` | — | 差分列表，必填。 |
| `moreCount` | `number` | `0` | 未列出的数量；大于 0 时渲染 `+N more`。 |
| `moreLabelFormatter` | `(count: number) => string` | `` n => `+${n} more` `` | 溢出控件的文案。 |
| `staggerStep` | `number` | `80` | chip 入场的错峰间隔（ms）。 |

#### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `select` | `(diff: ToolChipDiff)` | 点击差分 chip 时触发。 |
| `more` | `()` | 点击溢出控件时触发。 |

#### 插槽

| 插槽名 | 作用域参数 | 说明 |
|------|------|------|
| `chip` | `{ diff }` | 替换单个 chip 的内容。 |

### 类型

#### ToolChipRow

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `string` | 行的稳定 key，展开状态按它索引。 |
| `label` | `string` | 做了什么。 |
| `chip` | `string` | 行尾 chip：参数、路径或命令；占满剩余宽度，过长截断。 |
| `icon` | `'think' \| 'write' \| 'run' \| 'read' \| string` | 内置四种图标；其他值需配 `row-icon` 插槽。 |
| `mono` | `boolean` | chip 使用等宽字体。 |
| `detailMono` | `boolean` | 详情行使用等宽字体。 |
| `detail` | `{ text, tone? }[]` | 展开后的详情；`tone` 为 `add`（成功色）或 `del`（危险色）。 |

#### ToolChipDiff

| 字段 | 类型 | 说明 |
|------|------|------|
| `file` | `string` | 文件名。 |
| `add` | `number` | 新增行数，显示为 `+N`。 |
| `del` | `number` | 删除行数，显示为 `−N`（U+2212 减号）；为 0 时不显示。 |

## 概述

- 展开状态按 `row.id` 索引，标签相同的两行互不影响。
- `open` 与 `expandedRows` 传入时以 prop 为准，否则由组件自持；两种模式都派发事件。
- 悬停时工具图标淡出、chevron 淡入；已展开的行与触屏（`hover: none`）下 chevron 常显。
- 所有数字为 `tabular-nums`，流式更新时宽度不跳。
- 组件不自行播放：宿主随数据到达向 `rows` 追加行，每行自带入场动画。
- `TxToolChips` 内部渲染 `TxDiffChips`，透传 `diffs`、`moreCount`、`moreLabelFormatter`，并把 `select`、`more` 转发为 `diffClick`、`more`。

## 技术实现

- chip 文字色可用 `--tx-bui-tool-chips-chip-color` 覆写。
- 移植自 [Beautiful UI](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）。
- 源码：`packages/tuffex/packages/components/src/tool-chips/`。

<TuffDocSourceLink />

## 相关组件

- [ToolCallCard](./tool-call-card.zh.mdc)：单次调用的完整卡片，带状态、日志与重试。
- [Chain of Thought](./chain-of-thought.zh.mdc)：带 Markdown 正文的思考链。
