• 简体中文

      • Tool 卡片

      聊天窗口会用内置的通用 Tool 卡片呈现模型发起的 Tool 调用。通用卡片可以显示输入、执行状态、错误和结果；业务应用还可以按 Tool 注册名注册专用 Renderer，把结构化结果呈现为选择器、图表、报告或工作流确认界面。通用卡片是聊天窗口的内部组件，没有从 Registry 的入口导出，应用通过 Renderer 扩展它，而不是直接引用它。

      Tool 卡片组件示例

      Tool 调用状态

      状态界面含义
      input-streaming模型还在生成 Tool 参数
      input-available参数完整，等待执行或用户审批
      output-availableTool 已返回结果
      output-errorTool 执行失败，展示可理解的错误

      ASK Tool 在 input-available 时显示允许、拒绝或修改参数操作。Renderer 只负责交互和展示，审批决定通过传入的回调交给 AIChatProvider 和 Transport 处理，Renderer 不要自己修改已保存的 Tool 状态。

      注册专用 Renderer

      编辑应用安装的 AI Root Provider，把 Renderer 映射传给 NocoBaseAIRootProvider.toolRenderers。键必须是 Tool 注册名：

      <NocoBaseAIRootProvider
  toolRenderers={{
    'find-customer': CustomerToolCard,
  }}
>
  {children}
</NocoBaseAIRootProvider>

      内置 Renderer 已经覆盖 suggestions、chartGenerator、businessReportGenerator、子员工委派和工作流输出，传入的映射会和它们合并。使用相同的键会替换内置 Renderer，只有确实要换掉内置界面时才这样做。

      Renderer 组件接收 AIToolRendererProps：part 是这次 Tool 调用的内容和状态，disabled 表示当前不可操作，onApprove、onReject、onEdit 和 onRevise 用来提交用户的审批决定。映射的值可以直接是组件，也可以是 { component, handlesApproval?, standalone? }：handlesApproval 表示 Renderer 自己提供审批操作，standalone 表示它脱离通用卡片的布局单独渲染。

      Renderer 必须能够显示历史消息中已经完成的 Tool part。不要只处理实时执行回调，否则刷新会话后卡片会变为空白。输入和输出都应先做运行时校验，再渲染可信字段。

      什么时候使用专用卡片

      • 结果需要用户从有限选项中继续选择
      • 输出是图表、报告或结构化业务摘要
      • Tool 委派给另一个员工，需要显示任务进度
      • 工作流结果需要业务确认

      简单文本或 JSON 结果继续使用通用卡片即可，不需要为每个 Tool 创建组件。

      处理错误和审批

      错误文案应描述可行动的原因，例如当前角色没有发布权限，而不是直接输出堆栈。带副作用的 Tool 默认使用 ASK；卡片可以改善确认体验，但不能把服务端的 ACL 和业务校验移到浏览器。

      相关链接