For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/design-principles/from-query.md.

从 Query 开始

提示

做应用插件方案时,很多人第一反应是“我有哪些工具/接口,能拼出什么功能”。但在豆包里,用户不是来点按钮的,而是用一句话表达需求。所以正确的顺序应该反过来:先看清用户会怎么说,再决定豆包该怎么答,最后倒推出需要哪些工具和卡片。这一章就讲这套“从 Query 开始”的设计方法。

为什么要从 Query 开始

传统的功能设计是从供给出发:先罗列系统能力,再设计入口和页面,让用户按既定路径操作。但在豆包这样的对话式产品里,用户的入口只有一句话,而且怎么说、说得多详细完全不受你控制。同一个“想喝咖啡”的需求,有人会说“xx 品牌有什么新品”,有人直接说“帮我点杯生椰拿铁送到公司”,还有人说“昨天那杯再来一杯”。

如果只盯着工具去设计,很容易出现两种问题:一是真实高频的说法没被覆盖,用户一开口就答非所问;二是为了追求功能完整,设计了大量用户其实很少用到的路径,浪费开发资源。

从 Query 开始,本质上是让真实需求来决定投入的优先级——先搞清楚用户会怎么问、问得最多的是什么,再据此设计回答体验,最后才反推需要哪些工具能力和卡片样式。

五个步骤

第 1 步:先整合一份 Query 清单

过去的用户访谈和调研记录、客服和售后工单、自家 App 里的搜索词和反馈、你对自家用户的了解,都是很好的 Query 来源。把这些渠道里和你业务相关的用户表达都收集起来,再补上你能想到的典型说法。核心是站在用户视角,写下他们真实会说的话,而不是纯粹的功能描述。

写清单时,建议每个场景都覆盖三种说法,这样后续调优才有的放矢:

  • 直接说法:明确点了你的品牌、商品或动作,比如“帮我点一杯 XX 生椰拿铁”。
  • 间接说法:只说了目标没说清方案,比如“想喝点提神的”“下午有点困”,这类最能检验模型的理解力。
  • 反例说法:那些不该触发你服务的话,比如闲聊、和你业务无关的需求。留几条用来验证不会误触发。

这份清单不用一次做全,先覆盖你判断最高频的几个场景即可,后面可以边用边补。

第 2 步:按意图聚成场景

把大量零散的 Query 按“用户到底想干什么”归类,每一类就是一个场景。判断依据是意图,不是字面。比如下面这些说法字面差别很大,但意图都是“我已经想好了要什么,直接帮我下单”:

  • 帮我点一杯生椰拿铁,冰的少糖,送到公司
  • 点一杯生椰拿铁
  • 来杯瑞幸咖啡

它们会被归到同一个场景“一句话下单”。而“瑞幸最近有什么新品”“想喝点咖啡有什么推荐”这类,用户其实还没想好要买什么,需要豆包给建议,就属于另一个场景“模糊推荐”。

常见的场景类型可以参考:

  • 模糊推荐:用户有需求但没有明确方案,需要豆包基于场景和偏好推荐
  • 条件筛选:用户给了明确条件(品类、价格、时间、位置等),需要精准搜索
  • 一句话直达:用户一句话说清了目标,豆包端到端完成
  • 基于记忆复用:用户基于历史订单或偏好快速复购,比如“昨天那杯再来一杯”
  • 过程中修改:用户在下单流程里改地址、改规格、改数量
  • 查询与追踪:查订单状态、查配送进度
  • 取消:下单后反悔

第 3 步:为每个场景写理想态

理想态就是“这个场景下,一段完美的人机对话应该长什么样”。它不是抽象描述,而是把对话一轮一轮写出来:用户说了什么,我们的应用插件应该怎么回复,配什么卡片,背后调了哪些工具。推荐用一张四列表来表达:

用户chatbot卡片样式工具调用逻辑
帮我点一杯生椰拿铁,冰的少糖,送到公司没问题,帮你选好咖啡了,你可以直接支付或点击卡片修改信息。提单卡(商品、规格、地址、价格明细、“立即支付”按钮)并行搜菜品+取公司地址 → 创建预估订单 → 渲染卡片

描述理想态时,除了正常流程,还要把常见的异常情况和豆包的应对一并想清楚,这往往比正常流程更能体现体验的好坏:

异常情况chatbot 的应对
菜品售罄“生椰拿铁暂时售罄了,要试试厚乳拿铁吗?”
规格不支持“这款不支持热饮哦,可以选冰/去冰/常温”
没拿到位置追问“请问送到哪里?可以说‘家’或‘公司’”

不同场景的理想态各有侧重。比如“模糊推荐”的重点是豆包给的建议是否合口味、是否好选;“基于记忆复用”的重点是能否准确找回上一单并一键复刻;“过程中修改”的重点是只改用户提到的部分、其余信息保持不变。把每个核心场景的理想态都写扎实,方案的骨架就立起来了。

第 4 步:倒推工具和卡片

理想态写完,需要哪些工具、哪些卡片就自然浮现了。把所有场景的对话过一遍,提取出反复出现的能力,就是你要提供的工具清单。比如外卖场景反复用到的能力可以收敛成这样一组工具:

工具作用
搜索门店按位置/关键词/品类找店
搜索菜品跨门店或店内搜菜品
获取/新增地址下单前置,避免地址缺失
创建预估订单含试算、优惠,返回提单信息
查询订单实时进度 + 历史记录
取消订单下单后取消

卡片同理:理想态里出现过的每种展示形态——商品列表卡、单项卡、提单卡、失效卡等——就是你需要使用的卡片模板。这样倒推出来的工具和卡片,每一个都对应真实需求,不会多也不会漏。

两条贯穿始终的设计原则

在写理想态和设计工具时,有两条原则值得反复对照:

原则一:工具按“先搜索、再执行”组织,把推理交给模型

不要把复杂的业务判断塞进工具里,而是把工具拆成“查”和“做”两类:先用搜索类工具拿到候选(门店、菜品、车型、航班等),再用执行类工具完成动作(下单、修改、取消)。中间“用哪个、怎么搭配”的推理交给模型。工具只需把信息给全、把动作做对,模型负责根据用户的话灵活组合。

原则二:结果图文混排,由模型决定何时推卡

豆包的回答是文字和卡片混在一起的。什么时候用文字讲清楚、什么时候推一张卡让用户直接操作,交给模型根据对话节奏判断。你要做的是把卡片模板准备好、把槽位定义清楚,而不是规定死“第几轮必须出什么卡”。这样对话才自然,不会变成生硬的表单填写。

小结

从 Query 开始的设计方法,可以浓缩成一句话:先听用户怎么说,再想豆包怎么答,最后倒推要做什么。具体就是五步——自己动手攒 Query 清单、按意图聚成场景、排出优先级、为核心场景写理想态、倒推工具和卡片。把这套流程走一遍,你的方案就会牢牢扎根在真实需求上,而不是停留在功能的堆砌。