> 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.

# 从 Query 开始

:::info 提示

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

<div hidden data-lark-callout-end></div>

:::

## 为什么要从 Query 开始

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

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

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

## 五个步骤

### 第 1 步：先整合一份 Query 清单

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

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

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

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

### 第 2 步：按意图聚成场景

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

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

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

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

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

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

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

<table><colgroup><col width="184"/><col width="184"/><col width="185"/><col width="185"/></colgroup><tbody><tr><td><strong>用户</strong></td><td><strong>chatbot</strong></td><td><strong>卡片样式</strong></td><td><strong>工具调用逻辑</strong></td></tr><tr><td>帮我点一杯生椰拿铁，冰的少糖，送到公司</td><td>没问题，帮你选好咖啡了，你可以直接支付或点击卡片修改信息。</td><td>提单卡（商品、规格、地址、价格明细、“立即支付”按钮）</td><td>并行搜菜品+取公司地址 → 创建预估订单 → 渲染卡片</td></tr></tbody></table>

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

<table><colgroup><col width="179"/><col width="531"/></colgroup><tbody><tr><td><strong>异常情况</strong></td><td><strong>chatbot 的应对</strong></td></tr><tr><td>菜品售罄</td><td>“生椰拿铁暂时售罄了，要试试厚乳拿铁吗？”</td></tr><tr><td>规格不支持</td><td>“这款不支持热饮哦，可以选冰/去冰/常温”</td></tr><tr><td>没拿到位置</td><td>追问“请问送到哪里？可以说‘家’或‘公司’”</td></tr></tbody></table>

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

### 第 4 步：倒推工具和卡片

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

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

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

## 两条贯穿始终的设计原则

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

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

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

### 原则二：结果图文混排，由模型决定何时推卡

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

## 小结

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