AB
AiBoss站
教程

扣子

教程

用扣子卡片把 Bot 输出做成图文列表

扣子的消息卡片能把 Bot 返回的纯文本改写成带图片、标题、摘要的图文卡片。本文从卡片的结构讲起,逐步完成变量定义、组件绑定、模板发布,并把卡片挂到 Bot 上,做出一个以卡片形式输出每日新闻的最小示例。

扣子(Coze)里的 Bot 默认用纯文本回复,信息一多就显得拥挤。消息卡片的作用,是让你自定义 Bot 输出内容的呈现格式,把结果以一张排版好的小卡片发出去,读者一眼就能看到图片、标题和摘要。它适合已经能跑通 Bot 与工作流、希望进一步改善输出观感的人,尤其是做资讯推送、商品展示、活动通知这类「列表型」内容的场景。本文围绕卡片本身展开:卡片由什么组成、在哪些地方生效、怎么建变量、怎么绑定组件、怎么发布并挂到 Bot 上。想先了解扣子的整体能力,可以从 扣子 的工具页看起。

准备工作

卡片不是孤立存在的,它需要挂在一个已经能正常对话的 Bot 上,并且数据来源要提前打通。动手之前,请确认下面几件事已经就绪。

  • 一个可用的扣子账号与个人空间。卡片功能位于个人空间内,登录后能在空间里看到「卡片」入口。
  • 一个已经调试通过的 Bot。本文示例是「每日新闻小助手」,它需要能正常接收用户提问并给出回复。
  • 提供数据的插件或工作流。卡片本身不产生数据,它只负责把数据排成好看的版式。示例中的新闻列表来自插件返回的结果,因此插件要先配置好、能返回结构化的数组。
  • 明确卡片要在哪个客户端查看。这一点直接决定你做出来的卡片能不能被看到,详见下文的使用范围说明。

如果上述任何一项还缺,建议先把 Bot 的对话链路跑通,再回到卡片这一步。卡片是展示层的改造,底层数据不通,卡片做出来也是空的。

操作步骤

第一步:理解卡片由哪三部分组成

进入卡片创建页后,界面大致分为三个环节:模板、组件、结构。理解这三者的关系,后面的操作会顺很多。

  • 模板:卡片的整体骨架。你可以选用自己此前搭建并保存的模板,也可以直接使用官方提供的模板作为起点。
  • 组件:填充骨架的零件,分为布局组件与基础组件两类。布局组件负责划分区域,基础组件负责承载具体内容。
  • 结构:组件在画布上的嵌套与排列关系。你把布局组件拖进画布,再把基础组件放进布局的格子里,就形成了最终的结构。

布局组件的作用是「分区」。例如选择一个九宫格布局,Bot 输出时就会按九宫格的形式呈现内容;选择多列布局,则可以做出左图右文这类常见排版。基础组件则是真正显示内容的部分,文本、图片都属于基础组件。选中画布上的任意一个组件后,右侧会出现配置面板,通常分为基础配置与高级配置两组,可以调整内容、颜色、字体等属性。布局里的每一个小格子都能单独调整,所以同一张卡片里不同区域可以有不同的样式。

第二步:确认卡片的使用范围

在投入时间做设计之前,先确认你的使用场景是否被支持。消息卡片目前有两条明确的限制:

  • 客户端限制:消息卡片仅在豆包客户端、飞书客户端内生效。在其他渠道里,卡片可能不会按设计的样子呈现。
  • 功能限制:仅工作流和插件功能支持添加消息卡片。也就是说,卡片要挂在由工作流或插件产出结果的位置上。

如果你的 Bot 主要面向其他渠道,那么卡片带来的收益有限,应优先考虑纯文本或富文本方案。这两条限制会随产品迭代变化,实际可用范围请以官网当前信息为准。

第三步:搭建卡片骨架

下面以「每日新闻小助手」为例,做一个左图右文的新闻列表卡片。

  1. 在个人空间进入卡片创建页,新建一张卡片。
  2. 从布局组件中选择多列布局 1:2,把它拖入画布。这个布局把一行分成左右两栏,左栏窄、右栏宽,正好适合放缩略图和文字。
  3. 从基础组件中依次把图片、标题、正文拖入中间布局框中。图片放在左侧窄栏,标题和正文放在右侧宽栏,形成上下排列。
  4. 选中每个组件,在右侧配置面板里调整基础配置与高级配置,例如文字颜色、字号、图片的圆角与填充方式。这一步决定卡片的观感,可以反复预览调整。

此时卡片只是静态的样板,里面的文字和图片还是占位内容。要让它在 Bot 回复时显示真实数据,需要引入变量。

第四步:新建数组变量

新闻是一组条目,不是单条,所以变量类型要选数组。操作如下:

  1. 在卡片编辑界面新建变量。
  2. 变量类型选择 Array,因为我们要通过变量接收一个返回值列表。
  3. 填写变量的默认值。默认值是一段 JSON 数组,每个元素包含标题、摘要、图片地址、链接四个字段。示例结构如下:
[
  {
    "title": "这是一个新闻标题",
    "summary": "新闻摘要的作用很重要,它可以决定读者是否阅读一篇新闻,并对读者的观点和态度产生影响。",
    "image": "",
    "url": "https://www.coze.cn"
  },
  {
    "title": "这是一个新闻标题",
    "summary": "新闻摘要的作用很重要,它可以决定读者是否阅读一篇新闻,并对读者的观点和态度产生影响。",
    "image": "",
    "url": "https://www.coze.cn"
  },
  {
    "title": "这是一个新闻标题",
    "summary": "新闻摘要的作用很重要,它可以决定读者是否阅读一篇新闻,并对读者的观点和态度产生影响。",
    "image": "",
    "url": "https://www.coze.cn"
  }
]

默认值的作用是让卡片在编辑状态下有内容可显示,方便你调版式。真正上线后,这个数组会被工作流或插件返回的真实数据替换。字段名要与后续数据源保持一致,否则绑定后取不到值。

第五步:把变量绑定到组件

变量建好之后,还要告诉卡片「哪个字段显示在哪个位置」。依次把图片、标题、摘要三个组件与变量中的对应字段绑定:

  • 图片组件绑定 image 字段;
  • 标题组件绑定 title 字段;
  • 正文组件绑定 summary 字段。

绑定完成后,卡片会按数组中的元素数量重复渲染,每一条新闻生成一张卡片。如果绑定后预览仍是占位文字,先检查字段名是否拼写一致、变量类型是否为数组。

第六步:保存模板并发布

版式和绑定都确认无误后,保存这张卡片为模板,然后执行发布。发布这一步不能省,未发布的卡片无法在 Bot 中被引用。发布后如果后续又修改了设计,需要重新发布才会生效。

第七步:把卡片挂到 Bot 上

最后一步是让 Bot 用上这张卡片。进入 Bot 的配置界面,把设置好的卡片绑定进去,按照界面提示把卡片与对应的输出位置一一对应,然后点击确认。绑定关系要与你设计时的意图一致:卡片接收的是哪一路数据,就要挂在产出该数据的工作流或插件节点上。

完成绑定后,在豆包客户端或飞书客户端里与 Bot 对话,即可看到卡片形式的输出结果。

一个完整示例

把上面的步骤串起来,一个最小可用的「每日新闻卡片」流程是这样的:

  1. 数据层:配置一个能返回新闻列表的插件,返回结构为包含 title、summary、image、url 四个字段的数组。
  2. Bot 层:创建一个「每日新闻小助手」Bot,接入上述插件,确认对话时能拿到新闻数据。
  3. 卡片层:新建卡片,选择多列布局 1:2,左栏放图片组件,右栏放标题与正文组件。
  4. 变量层:新建 Array 类型变量,填入三条示例数据作为默认值。
  5. 绑定层:图片绑 image,标题绑 title,正文绑 summary。
  6. 发布层:保存模板并发布。
  7. 接入层:回到 Bot,绑定该卡片,确认对应关系后保存。
  8. 验证层:在豆包或飞书客户端中向 Bot 提问,检查返回的卡片是否按左图右文排列、条数是否与数据一致。

这个示例刻意保持最小:只有一种布局、三个基础组件、一个数组变量。跑通之后再考虑增加字段,例如在卡片里加入发布时间、来源标签,或者把单列改成两列网格以容纳更多条目。

注意事项

  • 客户端不匹配会导致卡片看不到。消息卡片仅在豆包客户端、飞书客户端内生效,在其他渠道测试时不要误以为是配置出错。
  • 只有工作流和插件支持添加消息卡片。如果你的输出链路不经过这两者,卡片无法挂载。
  • 变量类型必须是数组。新闻、商品、通知这类列表型内容都要用 Array,用单值类型只能渲染一条。
  • 字段名要与数据源严格一致。绑定靠字段名匹配,大小写或拼写不同都会取不到值,卡片会显示默认值或空白。
  • 修改后要重新发布。卡片模板发布之后才会被 Bot 引用,改完设计不重新发布,看到的仍是旧版。
  • 默认值只是占位。默认数组用于编辑期预览,上线后会被真实数据覆盖,不要把正式内容写死在默认值里。
  • 布局组件决定输出形态。选了九宫格就按九宫格输出,选了 1:2 多列就按左右分栏输出,改版式本质上是在换布局组件。
  • 功能与可用范围可能变化。卡片的支持渠道、组件种类、配额等属于易变信息,动手前请以官网当前信息为准。