扣子提示词变量设置教程：动态传参解析

在扣子（Coze）平台配置Bot时，变量操作是构建动态提示词的核心环节。本质是将用户输入、对话上下文或插件返回的数据作为可变内容注入提示词，从而实现个性化回复与逻辑分流。硬性规则是变量名必须严格遵循平台定义的语法格式，否则提示词将原样输出，无法被解析。先掌握这几个要点，后续逐步拆解。

进入Bot编辑页，点击「提示词」标签页，再点击编辑框顶部的「插入变量」按钮，侧边栏会列出所有可用变量。变量分为三大类：【用户信息】，例如user_id、user_name；【对话上下文】，例如last_message、chat_history；以及【插件/工作流输出】——需先添加插件，手动勾选“导出为变量”，变量名可自定义，如weather_result、db_query_list。

关键限制：只有侧边栏中出现的字段名才被平台识别。若在提示词里手动输入{{user_phone}}，但平台并未提供该字段，最终发送给LLM的仍是字面量{{user_phone}}，完全无效。

变量占位符的正确写法

所有变量必须用双大括号包裹，且内部绝对不允许出现空格。例如：{{user_name}}✅，{{ user_name }}❌。这个细节常被忽略，却是最频繁的出错点。

变量名区分大小写。{{UserName}}与{{user_name}}视为不同变量。若平台仅提供小写下划线格式，自行改用驼峰式会导致解析失败。

当变量值可能为空或为列表时，直接嵌入提示词容易引发异常。以实际场景为例：查询天气插件导出的变量名为weather_info，但用户未授权定位，该值为null。此时提示词写“今天{{weather_info}}，建议出门带伞”，输出变成“今天，建议出门带伞”，语义断裂。

列表类变量的安全展开处理

针对列表类变量，推荐以下三种处理方式，按使用频率排序：

方法一：使用内置的list_join函数（推荐）
在变量名后追加|list_join:“、”，例如{{db_query_list|list_join:“、”}}，可将["北京","上海","深圳"]渲染为“北京、上海、深圳”。语法简洁，应用最广。

方法二：配合if条件判断避免空渲染
用{{#if db_query_list}}有结果：{{db_query_list|list_join:“，”}}{{/if}}包裹，变量为空或null时不输出任何内容，避免语句断裂。

方法三：手动遍历（适合简单场景）
写法：{{#each db_query_list}}{{this}}{{/each}}。需要逐项添加前缀或后缀时尤其方便，如生成编号列表：{{#each db_query_list}}● {{this}}{{/each}}。

插件调用的参数映射规则

在Bot的「插件」模块中，点击目标插件右侧的「配置」，进入「参数映射」区域。操作分三步：

第一步：左侧选中插件要求的参数名，例如city、date_range。
第二步：右侧点击「+ 添加变量」，从弹窗中选择已声明的变量，例如user_location或fixed_date。
第三步：确认映射关系后保存。下次插件触发时，会将对应变量值作为实际参数传入。

注意：插件参数名是开发者定义的固定字符串，不可随意修改。若填入的变量名不存在或类型不匹配——比如插件要求数字却传入字符串——插件调用会失败，报错信息为“Parameter validation failed”。

调试变量是否生效

一个实用的调试技巧：在提示词末尾临时追加一行【DEBUG】变量快照：user={{user_name}}, history_len={{chat_history.length}}, weather={{weather_info}}。发布Bot后，用测试账号发一条消息，查看Bot返回的完整响应体——若看到类似“【DEBUG】变量快照：user=张三, history_len=5, weather=多云”的内容，说明所有变量已成功解析。

若某个变量仍显示为{{xxx}}原样，则平台未识别该变量。此时需回到「插入变量」侧边栏核对名称，或检查插件是否已启用并完成导出设置。