GetMyBot 知识库

公式

计算金额或折扣,并根据条件选择回复;了解文本表达式与计算动作的区别。

本页内容

公式可让机器人计算和选择值。例如价格 500、数量 3 时,{{= price * qty}} 会显示 1500。请先把 price 和 qty 保存为客户参数或当前反应的临时数据。

简单计算可直接写在消息中。处理列表、日期或俄语函数名时,请使用计算动作。GetMyBot 有两种不同的公式语言:

  • 表达式:用于简单算术、比较和字符串。可在正文的 {{= 表达式}}、计算动作的公式(expr)模式,以及决策表的条件中使用。
  • 高级公式:接近电子表格公式,支持列表、JSON、日期、哈希、LAMBDA 和俄语函数名。用于计算动作的高级公式(formula)模式、按公式验证回答及公式测试器。

公式可用的位置

位置使用的语言
消息正文中的 {{= 表达式}}表达式
计算动作的公式模式(expr)表达式
计算动作的决策表模式(rules)“如果”的条件为表达式;“那么”和默认值为可使用 {{...}} 的普通文字
计算动作的高级公式模式(formula)高级公式
符合公式的回答验证高级公式
公式测试器(test_formula)高级公式

计算动作

一个动作只能选择以下一种模式:

  • 公式(expr):单个表达式。
  • 决策表(rules + default):按顺序检查“如果 → 那么”,返回首个满足条件的值;否则返回默认值。
  • 高级公式(formula):完整公式语言。

结果可以保存到当前反应的 ctx(保存到 ctx,save_to_ctx),或客户资料中的参数(保存到参数,save_to_param),也可以同时保存两处,但至少要选一处。例如保存到 ctx 的 discount 可用 {{ctx.discount}} 插入。

表达式、条件和规则结果各不超过 4096 字节;高级公式不超过 16384 字节;决策表最多 64 条规则。限制按字节计算,俄语西里尔字母通常占 2 字节。

{"type":"compute","params":{"formula":"IF({total} > 1000; \"批发\"; \"零售\")","save_to_ctx":"segment"}}

表达式

语法

  • 运算符:算术 + - * / %,比较 == != < > <= >=,逻辑 && || !,三元选择 条件 ? 是 : 否,括号 ( )。
  • 常量:数字 42、3.14,带引号的文字 "你好" 或 '你好',布尔值 true、false。
  • 数据:不用花括号;名称从客户参数和 ctx 中查找,例如 price * qty、ctx.total、param.total。未知名称返回空文字。
  • 函数:名称(参数1, 参数2),参数用逗号分隔。

函数

仅支持以下小写名称:len、upper、lower、trim、concat、round、floor、ceil、abs、min、max。min、max 必须各有两个参数;concat 可接受任意数量。len 与高级公式的 LEN 按读者看到的字符计数:带重音的字母、国旗或由多个码位构成的家庭表情 👨‍👩‍👧‍👦 都算一个字符。

表达式没有中文或俄语函数别名。在 {{= }} 中调用未知函数时,整段替换内容会原样留在消息中。

高级公式

语法

  • 参数用分号分隔,例如 IF({total} > 1000; "批发"; "零售")。
  • 运算符:算术 + - * /,文字拼接 &,比较 = != <> < > <= >=(相等仅用一个 =);逻辑运算使用 AND、OR、NOT 函数。
  • 文字可用单引号或双引号。字符串里的 "" 不代表一个引号;需要给 HTML 属性加引号时可交替使用两种引号,例如 "<a href='tg://user?id=" & r.user_id & "'>资料</a>"。
  • 数据用单层花括号:{键名} 读取 ctx({text} 或 {answer} 可读入站消息);{user:键名} 读取订阅者参数;{global:键名} 读取机器人全局参数。
  • LAMBDA(r; 表达式) 定义列表各项的处理方式,用于 FILTER、FOREACH、ARRAYFIND、REDUCE。JSON 对象字段用点访问,例如 r.user_id。
  • 结果会转为文字。需保存列表时用 TOJSON,下一个公式再用 FROMJSON 读取。
  • 函数名不区分大小写,支持下方列出的俄语别名;文档中的中文解释不是可调用的函数名。

高级公式函数

以下以实际可调用的英文名称列出,括号中是可调用的俄语别名。

数学

SUM(СУММ)、AVERAGE(СРЗНАЧ)、MAX(МАКС)、MIN(МИН)、MOD(ОСТАТ)、POW(СТЕПЕНЬ)、SQRT(КОРЕНЬ)、PI(ПИ)、ROUND(ОКРУГЛ)、CEIL(ОКРВВЕРХ)、FLOOR(ОКРВНИЗ)、TRUNC(ОТБР)、ABS、RANDBETWEEN(СЛУЧМЕЖДУ)。

文本

LEN(ДЛСТР)、LEFT(ЛЕВСИМВ)、RIGHT(ПРАВСИМВ)、MID(ПСТР)、LOWER(СТРОЧН)、UPPER(ПРОПИСН)、UPPERFIRST(ПРОПИСНПЕРВ)、REPEAT(ПОВТОР)、CONCAT(СЦЕПИТЬ)、SUBSTITUTE(ПОДСТАВИТЬ)、FIND(НАЙТИ)、SEARCH(ПОИСК)、FIELD(ПОЛЕ)、TRIM、LTRIM、RTRIM、PADLEFT、PADRIGHT、SPLIT、JOIN、STARTSWITH、ENDSWITH、CONTAINS、NL。

逻辑

IF(ЕСЛИ)、AND(И)、OR(ИЛИ)、NOT(НЕ)、EMPTY、ISNUMBER(ЕЧИСЛО)、COALESCE。

列表

SORT、RSORT、UNIQUE、FILTER、FOREACH、REDUCE、INDEX、SLICE、COUNTA(СЧЁТЗ)、COUNTUNIQUE、ARRAYADD、ARRAYREMOVE、ARRAYREPLACE、ARRAYFIND、PAIRUP(СОСТАВИТЬПАРЫ)。

PAIRUP(items; idField; seed [; tagsField]) 用于“随机咖啡”配对。人数为奇数时有一组 3 人;可尽量避免把带有共同标签(如 "|a|b|" 或标签数组)的成员放在一起。同样的输入与 seed 会得到同样的分组。上限为 10,000 人、每人 64 个标签;共同标签很多时可能无法避免全部重合,但不会遗漏参与者。查找记录动作一次最多读 10,000 行,高级公式结果不超过 4 MB。

日期与时间

TODAY(СЕГОДНЯ)、NOW(ТДАТА)、DATEADD、DATESUB、DATEDIF(РАЗНДАТ)、DATEFORMAT、DATEVALUE、WEEKDAY(ДЕНЬНЕД)。

JSON

TOJSON、FROMJSON、JSONPATH、JP、JSONOBJECT、JSONARRAY、KEYS、VALUES。

加密与编码

HASH(ХЭШ)、TOBASE64、FROMBASE64、FROMJWT、FROMJWK。

参数

PARAMID、PARAMREPLACE、PARAMREMOVE。

示例

正文中的表达式:

  • 订单总额:{{= price * qty}}。
  • 四舍五入后的三分之一:{{= round(total / 3)}}。
  • 条件选择:{{= param.total > 1000 ? "批发" : "零售"}}。
  • 拼接文字:{{= concat("订单号", ctx.order_id)}}。

计算动作中的高级公式:

  • 九折金额:ОКРУГЛ({user:total} * 0.9)。
  • ctx 列表的元素数:СЧЁТЗ(FROMJSON({items}))。
  • 从 ctx.rows 生成稳定的伪随机顺序,只要盐值不变,排序就不变:
{"type":"compute","params":{"formula":"TOJSON(SORT(FOREACH(FROMJSON({rows}); LAMBDA(r; HASH(\"sha256\"; r.user_id & \"-salt\") & \"|\" & r.user_id))))","save_to_ctx":"order"}}

符合公式的回答验证应在成功时返回空文字,失败时返回错误文字,例如 IF(ISNUMBER({answer}); ""; "请输入数字")。

测试公式

测试器只计算高级公式,返回结果或语法错误,不保存数据:

  • 在回答验证的符合公式设置中填写示例回答,点击检查。
  • API:POST /api/bots/{botID}/reactions/test-formula,请求体 {"formula":"…","sample_text":"…"}。
  • MCP:test_formula,传 bot_id、formula、sample。

响应含 ok(已成功求值)、result、error 和 matches(结果为空时为 true,表示该回答会通过验证)。测试运行在空上下文:ctx、客户参数和全局参数均为空,{键名} 和 {user:键名} 得到空文字。只有示例文字可作为 {text}、{answer} 或 {received_message} 读取。测试器不检查 {{= }}、公式模式或决策表中的表达式。

接下来