tool-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tool UI

Use this skill to move from request to working Tool UI integration quickly.

Prefer assistant-ui when the project has no existing chat UI/runtime. Treat assistant-ui as optional when the app already has a working runtime.

使用本技能可快速将需求转化为可用的Tool UI集成方案。

如果项目尚无现成的聊天UI/运行时，优先使用assistant-ui；若应用已有可用的运行时，则assistant-ui为可选组件。

Workflow

工作流程

Run compatibility and doctor checks.
Find candidate components or bundles.
Install selected components.
Generate scaffolds and integrate runtime wiring.
Validate behavior and troubleshoot failures.

运行兼容性检查与诊断。
查找候选组件或组件包。
安装选定的组件。
生成脚手架并集成运行时连接。
验证行为并排查故障。

Step 1: Compatibility and Doctor

步骤1：兼容性检查与诊断

bash

python scripts/tool_ui_compat.py --project <repo-root>
python scripts/tool_ui_compat.py --project <repo-root> --doctor

Auto-fix missing

@tool-ui

registry entry:

bash

python scripts/tool_ui_compat.py --project <repo-root> --fix

Minimum requirements:

```
components.json
```
exists.

components.json.aliases.utils

exists (typically

@/lib/utils

components.json.registries["@tool-ui"]

equals

https://tool-ui.com/r/{name}.json

bash

python scripts/tool_ui_compat.py --project <repo-root>
python scripts/tool_ui_compat.py --project <repo-root> --doctor

自动修复缺失的

@tool-ui

注册表条目：

bash

python scripts/tool_ui_compat.py --project <repo-root> --fix

最低要求：

存在
```
components.json
```
文件。

存在

components.json.aliases.utils

（通常为

@/lib/utils

）。

components.json.registries["@tool-ui"]

的值等于

https://tool-ui.com/r/{name}.json

。

Step 2: Discover Components

步骤2：发现组件

Use intent-first discovery:

bash

python scripts/tool_ui_components.py list
python scripts/tool_ui_components.py find "<use case keywords>"
python scripts/tool_ui_components.py bundle
python scripts/tool_ui_components.py bundle planning-flow

References:

```
references/components-catalog.md
```
```
references/recipes.md
```

基于需求意图进行组件查找：

bash

python scripts/tool_ui_components.py list
python scripts/tool_ui_components.py find "<use case keywords>"
python scripts/tool_ui_components.py bundle
python scripts/tool_ui_components.py bundle planning-flow

参考文档：

```
references/components-catalog.md
```
```
references/recipes.md
```

Step 3: Install Components

步骤3：安装组件

Generate install command:

bash

python scripts/tool_ui_components.py install <component-id> [component-id...]

Default install pattern:

bash

npx shadcn@latest add https://tool-ui.com/r/<component-id>.json

生成安装命令：

bash

python scripts/tool_ui_components.py install <component-id> [component-id...]

默认安装方式：

bash

npx shadcn@latest add https://tool-ui.com/r/<component-id>.json

Step 4: Scaffold and Integrate

步骤4：生成脚手架与集成

Generate wiring snippet:

bash

python scripts/tool_ui_scaffold.py --mode assistant-backend --component plan
python scripts/tool_ui_scaffold.py --mode assistant-frontend --component option-list
python scripts/tool_ui_scaffold.py --mode manual --component stats-display

Use integration patterns for final adaptation:

```
references/integration-patterns.md
```

生成连接代码片段：

bash

python scripts/tool_ui_scaffold.py --mode assistant-backend --component plan
python scripts/tool_ui_scaffold.py --mode assistant-frontend --component option-list
python scripts/tool_ui_scaffold.py --mode manual --component stats-display

使用集成模式完成最终适配：

```
references/integration-patterns.md
```

Step 5: Validate and Troubleshoot

步骤5：验证与故障排查

After integration:

Run typecheck/lint.
Trigger a real tool call.
Confirm UI renders and interactions complete expected flow.

If broken, use:

```
references/troubleshooting.md
```

集成完成后：

运行类型检查/代码扫描。
触发一次真实的工具调用。
确认UI可正常渲染且交互能完成预期流程。

若出现问题，可参考：

```
references/troubleshooting.md
```

Action Model

动作模型

Tool UI uses two action surfaces, rendered as compound siblings outside the display component:

```
ToolUI.LocalActions
```
: non-consequential side effects (export, copy, open link). Handlers must not call
```
addResult(...)
```
.
```
ToolUI.DecisionActions
```
: consequential choices that produce a
```
DecisionResult
```
envelope via
```
createDecisionResult(...)
```
. The commit callback calls
```
addResult(...)
```
.

Compound wrapper pattern for display components with actions:

tsx

<ToolUI id={surfaceId}>
  <ToolUI.Surface><DataTable {...props} /></ToolUI.Surface>
  <ToolUI.Actions>
    <ToolUI.LocalActions
      actions={[{ id: "export-csv", label: "Export CSV" }]}
      onAction={(actionId) => { /* side effects only */ }}
    />
  </ToolUI.Actions>
</ToolUI>

Three components are action-centric exceptions — they keep embedded action props instead of sibling surfaces. All three share a unified interface:

```
actions
```
: action buttons rendered by the component.
```
onAction(actionId, state)
```
: runs after the action and receives post-action state.
```
onBeforeAction(actionId, state)
```
: guard evaluated before an action runs.

Component	State type passed to handlers
`OptionList`	`OptionListSelection`
`ParameterSlider`	`SliderValue[]`
`PreferencesPanel`	`PreferencesValue`

ESLint enforces this model:

no-embedded-response-actions

— bans legacy

responseActions

onResponseAction

props.

no-add-result-in-local-actions

— prevents

addResult()

inside LocalActions handlers.

decision-actions-require-envelope

— requires

createDecisionResult(...)

in DecisionActions handlers.

Tool UI使用两个动作层，作为复合兄弟元素渲染在展示组件外部：

```
ToolUI.LocalActions
```
：无影响的副作用操作（导出、复制、打开链接）。处理函数不得调用
```
addResult(...)
```
。
```
ToolUI.DecisionActions
```
：会产生实际影响的选择操作，需通过
```
createDecisionResult(...)
```
生成
```
DecisionResult
```
信封。提交回调需调用
```
addResult(...)
```
。

带动作的展示组件的复合包装模式：

tsx

<ToolUI id={surfaceId}>
  <ToolUI.Surface><DataTable {...props} /></ToolUI.Surface>
  <ToolUI.Actions>
    <ToolUI.LocalActions
      actions={[{ id: "export-csv", label: "Export CSV" }]}
      onAction={(actionId) => { /* side effects only */ }}
    />
  </ToolUI.Actions>
</ToolUI>

有三个组件是动作中心的例外情况——它们保留嵌入式动作属性而非兄弟层。这三个组件共享统一的接口：

```
actions
```
：组件渲染的动作按钮。
```
onAction(actionId, state)
```
：动作执行后运行，接收动作后的状态。
```
onBeforeAction(actionId, state)
```
：动作执行前的守卫检查。

组件	传递给处理函数的状态类型
`OptionList`	`OptionListSelection`
`ParameterSlider`	`SliderValue[]`
`PreferencesPanel`	`PreferencesValue`

ESLint强制遵循该模型：

no-embedded-response-actions

—— 禁止使用旧版

responseActions

onResponseAction

属性。

```
no-add-result-in-local-actions
```
—— 禁止在LocalActions处理函数中调用
```
addResult()
```
。

decision-actions-require-envelope

—— 要求在DecisionActions处理函数中使用

createDecisionResult(...)

。

Schema Boundary

Schema边界

Import from colocated entrypoints, not barrel

index.tsx

tsx

import { DataTable } from "@/components/tool-ui/data-table/data-table";
import { safeParseSerializableDataTable } from "@/components/tool-ui/data-table/schema";
import { ToolUI, createDecisionResult, type Action } from "@/components/tool-ui/shared";

从同目录的入口文件导入，而非从桶文件

index.tsx

导入：

tsx

import { DataTable } from "@/components/tool-ui/data-table/data-table";
import { safeParseSerializableDataTable } from "@/components/tool-ui/data-table/schema";
import { ToolUI, createDecisionResult, type Action } from "@/components/tool-ui/shared";

Operational Rules

操作规则

Install the smallest set of components that solves the request.
Validate one component first, then scale to multiple components.
Keep payload schemas serializable and explicit.

For decision flows, wire

DecisionActions

with

createDecisionResult(...)

and commit via

addResult(...)

For display components that need actions, use the compound
```
ToolUI
```
wrapper with
```
LocalActions
```
.

安装满足需求的最小组件集合。
先验证单个组件，再扩展到多个组件。
保持负载Schema可序列化且明确。
对于决策流程，需将
```
DecisionActions
```
与
```
createDecisionResult(...)
```
连接，并通过
```
addResult(...)
```
提交。
对于需要动作的展示组件，使用带
```
LocalActions
```
的复合
```
ToolUI
```
包装器。

Maintainer Notes

维护者说明

Keep component metadata synchronized with Tool UI source:

bash

python scripts/sync_components.py

Run script tests:

bash

python -m unittest discover -s tests -p "test_*.py"

保持组件元数据与Tool UI源同步：

bash

python scripts/sync_components.py

运行脚本测试：

bash

python -m unittest discover -s tests -p "test_*.py"