iBBot 内置 PopLang 语言引擎使用技能文档

文档概述

本文档介绍 iBBot 系统内置的 PopLang 语言引擎的使用方法。PopLang 是一种面向操作码（OPCode Oriented Programming）的脚本语言，支持变量操作、条件判断、循环控制、函数定义等编程特性。通过 iBBot 提供的三个 API 接口，用户可以执行 PopLang 代码、评估表达式以及运行脚本文件。

---

一、API 接口说明

1.1 执行 PopLang 代码

接口路径： /ibbot/poplang/run

请求方法： POST / GET / ALL

功能描述： 执行完整的 PopLang 代码字符串，支持多行代码

请求参数：

参数名	类型	必填	描述
user_id	string	是	用户ID
code	string	是	PopLang 代码字符串，支持多行
is_wait	boolean	否	是否等待异步执行完成，默认 true
s_id	string	否	会话ID

请求示例：

{
    "user_id": "user123",
    "code": "set sum 0\nset one 1\nset n 1\nset max 100\nset flag true\n\npop.func.define addTo100\n+ sum n sum\n+ n one n\n!= n 100 flag\npop.func.end\n\npop.do.while flag addTo100",
    "is_wait": true
}

响应示例：

{
    "ret": true,
    "data": {
        "result": {
            "ret": true,
            "msg": "success",
            "results": [...]
        },
        "context": {
            "sum": 5050,
            "n": 100,
            "flag": false
        },
        "executed_at": "2026-01-15T10:30:00.000Z"
    }
}

---

1.2 评估 PopLang 表达式

接口路径： /ibbot/poplang/eval

请求方法： POST / GET / ALL

功能描述： 执行单行 PopLang 表达式，快速评估

请求参数：

参数名	类型	必填	描述
user_id	string	是	用户ID
expression	string	是	单行 PopLang 表达式
s_id	string	否	会话ID

请求示例：

{
    "user_id": "user123",
    "expression": "+ a b sum",
    "s_id": "session_001"
}

响应示例：

{
    "ret": true,
    "data": {
        "result": {
            "ret": true,
            "msg": "success",
            "results": [30]
        },
        "context": {},
        "expression": "+ a b sum",
        "executed_at": "2026-01-15T10:30:00.000Z"
    }
}

---

1.3 执行 PopLang 脚本文件

接口路径： /ibbot/poplang/script

请求方法： POST / GET / ALL

功能描述： 执行存储在服务器上的 PopLang 脚本文件

请求参数：

参数名	类型	必填	描述
user_id	string	是	用户ID
script_path	string	是	脚本文件的绝对路径
s_id	string	否	会话ID

请求示例：

{
    "user_id": "user123",
    "script_path": "/path/to/skills/bubble_sort.pop",
    "s_id": "session_001"
}

响应示例：

{
    "ret": true,
    "data": {
        "result": {
            "ret": true,
            "msg": "success",
            "results": [...]
        },
        "context": {
            "sorted_array": [1, 2, 3, 5, 8]
        },
        "script_name": "bubble_sort.pop",
        "executed_at": "2026-01-15T10:30:00.000Z"
    }
}

---

二、PopLang 语法规范

2.1 基本语法规则

PopLang 采用面向操作码的设计，每行代码格式为：

opcode [参数1] [参数2] [参数3] ...

• opcode：操作码或函数名
• 参数：0-N 个参数，均为变量名（除 set 语句外）

2.2 变量赋值

2.2.1 使用 set 初始化变量

# 数值常量
set count 100
set score 95

# 字符串常量（使用 ** 标记）
set name **张三
set message **Hello World

# JSON 对象
set user **{"name": "李四", "age": 25}

# 数组
set numbers **[1, 2, 3, 4, 5]

# 布尔值
set flag true
set is_active false

重要规则： set 只能用于初始化常量，不能使用变量作为值

# 错误用法
set a b  # b 是变量，不允许

# 正确用法
= a b   # 使用 = 操作符进行变量间赋值

2.2.2 变量间赋值

# 基本赋值
= dest source

# 示例
set x 10
set y 20
= x y     # 将 y 的值赋给 x

2.3 算术运算

# 加法
+ a b result    # result = a + b

# 减法
- a b result    # result = a - b

# 乘法
* a b result    # result = a * b

# 除法
/ a b result    # result = a / b

# 取模
% a b result    # result = a % b

注意： 所有运算操作码只能使用变量，不能使用常量

# 错误用法
+ i 1 i        # 不能直接使用常量 1

# 正确用法
set one 1
+ i one i

2.4 比较运算

# 大于
> a b result    # result = (a > b)

# 大于等于
>= a b result   # result = (a >= b)

# 小于
< a b result    # result = (a < b)

# 小于等于
<= a b result   # result = (a <= b)

# 等于
== a b result   # result = (a == b)

# 不等于
!= a b result   # result = (a != b)

2.5 逻辑运算

# 逻辑与
&& a b result   # result = (a && b)

# 逻辑或
|| a b result   # result = (a || b)

# 逻辑非
! a result      # result = !a

2.6 位运算

# 按位或
| a b result    # result = a | b

# 按位与
& a b result    # result = a & b

# 按位异或
^ a b result    # result = a ^ b

# 左移
<< a b result   # result = a << b

# 右移
>> a b result   # result = a >> b

# 按位取反
~ a result      # result = ~a

2.7 条件运算（三目运算符）

# 条件赋值
?= condition true_value false_value result

示例：

set score 85
set pass_threshold 60
>= score pass_threshold is_pass
?= is_pass **及格 **不及格 result

2.8 对象操作

2.8.1 读取对象属性

object.get object.property.subproperty result

示例：

set user **{"name": "张三", "address": {"city": "北京", "district": "朝阳"}}
object.get user.name user_name
object.get user.address.city city_name

2.8.2 设置对象属性

object.set object.property value

示例：

set user **{}
set name **李四
object.set user.name name
set age 30
object.set user.age age

2.8.3 对象合并

object.assign target source result

2.9 数组操作

2.9.1 创建数组

# 方法一：使用 new
new array
= my_array $ret

# 方法二：使用 set
set my_array **[1, 2, 3, 4, 5]

2.9.2 读取数组元素

array.get array index result

示例：

set numbers **[10, 20, 30, 40, 50]
set i 2
array.get numbers i value   # value = 30

2.9.3 设置数组元素

array.set array index value

示例：

set numbers **[10, 20, 30, 40, 50]
set i 2
set new_value 35
array.set numbers i new_value   # numbers[2] = 35

2.10 函数定义与调用

2.10.1 定义函数

pop.func.define function_name
    # 函数体：多行 PopLang 代码
    opcode1 ...
    opcode2 ...
    ...
pop.func.end

示例：计算两个数的和

pop.func.define add
    + a b sum
pop.func.end

2.10.2 定义带参数的函数

pop.func.define add_numbers num1 num2
    + num1 num2 sum
    = result sum
pop.func.end

调用带参数的函数：

set x 10
set y 20
add_numbers x y result   # result = 30

2.10.3 函数返回值

return value1 value2 ...

示例：

pop.func.define calculate a b
    + a b sum
    * a b product
    return sum product
pop.func.end

set x 10
set y 20
calculate x y sum_val product_val

2.10.4 调用函数

# 无参数调用
function_name

# 有参数调用
function_name param1 param2 ...

2.11 流程控制

2.11.1 条件判断

pop.ifelse condition true_function false_function

示例：判断分数是否及格

set score 85
set pass_threshold 60
>= score pass_threshold is_pass

pop.func.define handle_pass
    set result **及格
pop.func.end

pop.func.define handle_fail
    set result **不及格
pop.func.end

pop.ifelse is_pass handle_pass handle_fail

2.11.2 循环控制

do-while 循环：

pop.do.while condition loop_function

示例：1 到 100 求和

set sum 0
set i 1
set max 100
set one 1
set continue true

pop.func.define add_loop
    + sum i sum
    + i one i
    < i max continue
pop.func.end

pop.do.while continue add_loop

while 循环：

pop.while condition loop_function

示例：

set i 0
set max 10
set continue true

pop.func.define while_loop
    # 循环体代码
    + i one i
    < i max continue
pop.func.end

pop.while continue while_loop

2.12 其他操作码

2.12.1 类型判断

typeof variable result

2.12.2 创建对象

# 创建普通对象
new object
= my_obj $ret

# 创建数组
new array
= my_array $ret

# 创建字符串
new string
= my_str $ret

# 创建 Map
new map
= my_map $ret

# 创建日期对象
new date
= current_time $ret

2.12.3 删除属性

del variable1 variable2 ...

2.12.4 清空上下文

clear

2.12.5 延迟执行

pop.sleep milliseconds

示例：

set delay_time 1000
pop.sleep delay_time   # 延迟 1 秒

2.12.6 退出执行

pop.exit

2.13 注释

# 这是一行注释
# 多行注释需要每行都使用 #

---

三、内置 iBBot 函数

3.1 用户偏好管理

# 获取用户偏好
ibbot.getUserPreferences preferences

# 保存用户偏好
ibbot.saveUserPreference **测试偏好 category **这是详细信息

3.2 任务管理

# 获取用户任务列表
ibbot.getUserTasks task_list

# 创建任务
ibbot.createTask **帮我搜索信息 ["skill.md"] task_info

# 取消任务
ibbot.cancelTask task_id result

3.3 系统状态

# 获取系统状态
ibbot.getSystemStatus status

3.5 日志输出

# 输出日志
ibbot.log info **这是一条信息
ibbot.log error **这是一条错误

---

四、完整示例

4.1 冒泡排序

# 初始化数组
set arr **[5, 3, 8, 1, 2, 7, 4, 6]
set n 8
set swapped true
set i 0
set temp 0
set one 1
set limit 0

# 定义：比较并交换相邻元素
pop.func.define compare_swap
    set next_i i
    + next_i one next_i
    array.get arr i current
    array.get arr next_i next_val
    > current next_val need_swap
    pop.ifelse need_swap do_swap no_swap
pop.func.end

# 定义：执行交换
pop.func.define do_swap
    = temp current
    array.set arr i next_val
    array.set arr next_i temp
    set swapped true
pop.func.end

# 定义：不交换
pop.func.define no_swap
pop.func.end

# 定义：单次冒泡扫描
pop.func.define bubble_scan
    set swapped false
    set i 0
    - n one limit
    set scan_continue true
    < i limit scan_continue
pop.func.end

# 定义：扫描循环控制
pop.func.define scan_loop
    < i limit do_scan
    pop.ifelse do_scan continue_scan end_scan
pop.func.end

# 定义：执行扫描比较
pop.func.define do_scan
    compare_swap
    + i one i
    set scan_continue true
pop.func.end

# 定义：继续扫描
pop.func.define continue_scan
    set scan_continue true
pop.func.end

# 定义：结束扫描
pop.func.define end_scan
    set scan_continue false
pop.func.end

# 定义：检查是否需要继续排序
pop.func.define check_sort_continue
    bubble_scan
    pop.do.while scan_continue scan_loop
    ?= swapped keep_sorting stop_sorting sort_continue
pop.func.end

# 定义：继续排序
pop.func.define keep_sorting
    set sort_continue true
pop.func.end

# 定义：停止排序
pop.func.define stop_sorting
    set sort_continue false
pop.func.end

# 执行冒泡排序
set sort_continue true
pop.do.while sort_continue check_sort_continue

# 输出排序结果
set sorted_array arr

4.2 查找数组元素

# 初始化数组和目标值
set numbers **[19320153333, 13789051335, 15689901356, 13490377131, 13390001233]
set target 18216815719
set length 5
set i 0
set found false
set one 1
set continue true

# 定义查找函数
pop.func.define check_loop
    array.get numbers i current
    == current target is_match
    pop.ifelse is_match handle_found handle_not_found
pop.func.end

# 找到的处理函数
pop.func.define handle_found
    set found true
    set continue false
pop.func.end

# 未找到的处理函数
pop.func.define handle_not_found
    + i one i
    < i length continue
pop.func.end

# 执行查找
pop.do.while continue check_loop

# 输出结果
?= found **找到 **未找到 result

4.3 计算 1 到 N 的和

# 计算 1+2+...+100
set sum 0
set i 1
set max 100
set one 1
set continue true

pop.func.define accumulate
    + sum i sum
    + i one i
    < i max continue
pop.func.end

pop.do.while continue accumulate

# sum = 5050

4.4 调用 iBBot API 端点

# 调用用户输入处理接口
set input_data **{"user_id": "test_user", "input": "帮我搜索Python教程", "s_id": "session_123"}
/ibbot/process input_data result

# 获取用户任务列表
/tasks:GET {"user_id": "test_user"} tasks

# 获取用户偏好
/preferences:GET {"user_id": "test_user"} prefs

# 获取系统状态
/status:GET {} status

---

五、错误处理

5.1 常见错误及解决方法

错误类型	原因	解决方法
语法错误	操作码使用不当	检查操作码拼写和参数数量
变量未定义	使用未初始化的变量	使用 set 先初始化变量
常量误用	在非 set 语句中使用常量	使用变量替代常量
函数未定义	调用未声明的函数	确保函数在使用前已定义
类型错误	操作码参数类型不匹配	检查变量类型是否正确

5.2 调试技巧

# 使用日志输出变量值
ibbot.log info **当前变量值
ibbot.log info sum

# 使用返回值查看结果
= debug_value variable_name

---

六、最佳实践

6.1 代码组织

1. 变量初始化放在开头：使用 set 初始化所有变量
2. 函数定义集中放置：将所有函数定义放在主逻辑之前
3. 使用有意义的变量名：提高代码可读性
4. 添加注释：使用 # 注释关键逻辑

6.2 性能优化

1. 减少循环嵌套：避免过深的循环嵌套
2. 合理使用缓存：将重复计算的结果保存到变量
3. 避免不必要的函数调用：简单操作直接使用操作码

6.3 安全性

1. 输入验证：对外部输入进行验证
2. 避免递归过深：PopLang 有递归深度限制
3. 使用 safeFlag：确保在安全模式下执行

---

七、版本信息

• API 版本: v1.0.0
• PopLang 版本: 2.0
• 最后更新: 2026-01-15
• 兼容性: 与 iBBot 系统完全集成

---

附录

---

PopLang 调用 iBBot 端点请求示例

一、基本调用语法

PopLang 支持两种方式调用 iBBot 的 API 端点：

1.1 使用 / 开头的端点路径

# 语法：/端点路径 参数量 结果变量
/ibbot/process input_data result

1.2 使用完整 URL（http:// 或 https://）

# 语法：http://域名:端口/端点路径 参数量 结果变量
http://localhost:3000/ibbot/process input_data result

1.3 指定 HTTP 方法

# 语法：/端点路径:方法名 参数量 结果变量
/ibbot/tasks:GET params task_list
/ibbot/preferences/update:POST update_data update_result

---

二、完整示例

2.1 调用用户输入处理接口

# 准备输入数据
set input_data **{"user_id": "user123", "input": "帮我搜索Python教程", "s_id": "session_001"}

# 调用 /ibbot/process 接口（POST 方法）
/ibbot/process input_data process_result

# 输出结果
ibbot.log info **处理结果
= result_info process_result

2.2 获取用户任务列表（GET 请求）

# 准备查询参数
set query_params **{"user_id": "user123", "status": "running", "limit": 10, "offset": 0}

# 调用 /ibbot/tasks 接口（GET 方法）
/tasks:GET query_params tasks_list

# 遍历任务列表
set task_count 0
set i 0
array.get tasks_list.tasks task_count
set has_more true
< i task_count has_more

pop.func.define process_tasks
    array.get tasks_list.tasks i current_task
    object.get current_task.task_id task_id
    object.get current_task.status task_status
    ibbot.log info **任务ID: task_id, 状态: task_status
    + i one i
    < i task_count has_more
pop.func.end

pop.do.while has_more process_tasks

2.3 获取任务详情

# 准备任务ID
set task_id **rtagent_123456

# 调用 /ibbot/task 接口
set task_params **{"task_id": task_id, "user_id": "user123"}
/task:GET task_params task_detail

# 输出任务详情
object.get task_detail.task_type task_type
object.get task_detail.status task_status
ibbot.log info **任务类型: task_type, 状态: task_status

2.4 取消任务（POST 请求）

# 准备取消参数
set cancel_data **{"task_id": "rtagent_123456"}

# 调用 /ibbot/task/cancel 接口
/task/cancel:POST cancel_data cancel_result

# 检查取消结果
object.get cancel_result.ret is_success
pop.ifelse is_success cancel_ok cancel_fail

pop.func.define cancel_ok
    ibbot.log info **任务取消成功
pop.func.end

pop.func.define cancel_fail
    object.get cancel_result.msg error_msg
    ibbot.log error **取消失败: error_msg
pop.func.end

2.5 获取用户偏好

# 准备参数
set pref_params **{"user_id": "user123"}

# 调用 /ibbot/preferences 接口
/preferences:GET pref_params user_prefs

# 读取用户信息
object.get user_prefs.data.email user_email
object.get user_prefs.data.address user_address

# 输出用户信息
ibbot.log info **用户邮箱: user_email
ibbot.log info **用户地址: user_address

2.6 更新用户偏好

# 准备更新数据
set update_data **{"user_id": "user123", "email": "newemail@example.com", "address": "北京市朝阳区"}

# 调用 /ibbot/preferences/update 接口
/preferences/update:POST update_data update_result

# 检查更新结果
object.get update_result.ret update_success
pop.ifelse update_success update_ok update_error

pop.func.define update_ok
    ibbot.log info **用户偏好更新成功
pop.func.end

pop.func.define update_error
    object.get update_result.msg error_msg
    ibbot.log error **更新失败: error_msg
pop.func.end

2.7 获取系统状态

# 调用 /ibbot/status 接口（GET 请求）
/status:GET {} system_status

# 读取系统信息
object.get system_status.data.system system_name
object.get system_status.data.version version
object.get system_status.data.uptime_formatted uptime

# 输出系统状态
ibbot.log info **系统: system_name
ibbot.log info **版本: version
ibbot.log info **运行时间: uptime

# 读取任务统计
object.get system_status.data.rtagent_task_stats task_stats
object.get task_stats.total total_tasks
object.get task_stats.processing processing_tasks
object.get task_stats.completed completed_tasks

ibbot.log info **总任务数: total_tasks
ibbot.log info **处理中: processing_tasks
ibbot.log info **已完成: completed_tasks

---

三、结合 iBBot 内置函数的示例

3.1 综合示例：自动处理用户输入并创建任务

# 步骤1: 获取用户偏好
set pref_params **{"user_id": "user123"}
/preferences:GET pref_params user_prefs

# 步骤2: 提取用户邮箱
object.get user_prefs.data.email user_email

# 步骤3: 判断是否有邮箱
set has_email true
== user_email null no_email
pop.ifelse no_email ask_email continue_process

pop.func.define ask_email
    ibbot.log info **用户无邮箱，请先设置邮箱
    set process_result **{"ret": false, "msg": "请先设置邮箱"}
pop.func.end

pop.func.define continue_process
    # 步骤4: 处理用户输入
    set input_data **{"user_id": "user123", "input": "帮我搜索Python教程并发送到邮箱", "s_id": "session_001"}
    /ibbot/process input_data process_result
    
    # 步骤5: 检查处理结果
    object.get process_result.ret is_success
    pop.ifelse is_success get_task_info show_error
pop.func.end

pop.func.define get_task_info
    object.get process_result.data.ibbot_task_id task_id
    ibbot.log info **任务已创建，ID: task_id
    
    # 步骤6: 获取任务详情
    set task_params **{"task_id": task_id, "user_id": "user123"}
    /ibbot/task:GET task_params task_detail
    
    object.get task_detail.status task_status
    ibbot.log info **任务状态: task_status
pop.func.end

pop.func.define show_error
    object.get process_result.msg error_msg
    ibbot.log error **处理失败: error_msg
pop.func.end

3.2 批量任务管理示例

# 定义任务列表
set task_list **[["搜索Python教程", ["skill.md"]], ["发送邮件报告", ["mail-skill.md"]], ["生成网站", ["aiweb-skill.md"]]]
set results **[]
set i 0
set one 1
set task_count 3
set has_more true

# 定义创建任务函数
pop.func.define create_batch_tasks
    array.get task_list i current_task
    array.get current_task 0 instruction
    array.get current_task 1 skills
    
    # 准备创建任务的数据
    set task_data **{"user_id": "user123", "instruction": instruction, "skill_names": skills, "s_id": "batch_001"}
    
    # 调用创建任务接口
    /ibbot/process task_data task_result
    
    # 保存结果
    array.set results i task_result
    
    # 增加计数器
    + i one i
    < i task_count has_more
pop.func.end

# 执行批量创建
pop.do.while has_more create_batch_tasks

# 输出所有任务结果
= all_results results
ibbot.log info **批量任务创建完成

3.3 监控任务状态示例

# 设置要监控的任务ID
set monitor_task_id **rtagent_123456
set check_interval 2000
set max_checks 30
set check_count 0
set one 1
set continue_monitor true

# 定义检查任务状态函数
pop.func.define check_task_status
    set task_params **{"task_id": monitor_task_id, "user_id": "user123"}
    /ibbot/task:GET task_params task_info
    
    object.get task_info.status current_status
    ibbot.log info **任务状态: current_status
    
    # 判断是否完成
    == current_status **completed is_completed
    == current_status **failed is_failed
    == current_status **cancelled is_cancelled
    
    || is_completed is_finished
    || is_failed is_finished
    || is_cancelled is_finished
    
    pop.ifelse is_finished stop_monitor continue_check
pop.func.end

pop.func.define stop_monitor
    set continue_monitor false
    ibbot.log info **任务已完成，停止监控
pop.func.end

pop.func.define continue_check
    + check_count one check_count
    >= check_count max_checks timeout_check
    
    pop.ifelse timeout_check timeout_monitor wait_next
pop.func.end

pop.func.define timeout_monitor
    set continue_monitor false
    ibbot.log warn **监控超时
pop.func.end

pop.func.define wait_next
    pop.sleep check_interval
pop.func.end

# 开始监控
pop.do.while continue_monitor check_task_status

---

四、错误处理示例

4.1 带重试机制的调用

# 定义带重试的API调用函数
set max_retries 3
set retry_count 0
set one 1
set call_success false
set api_result **{}

pop.func.define call_with_retry
    set call_params **{"user_id": "user123", "input": "测试输入"}
    /ibbot/process call_params api_result
    
    object.get api_result.ret is_success
    pop.ifelse is_success call_ok call_retry
pop.func.end

pop.func.define call_ok
    set call_success true
    ibbot.log info **API调用成功
pop.func.end

pop.func.define call_retry
    + retry_count one retry_count
    < retry_count max_retries should_retry
    
    pop.ifelse should_retry do_retry give_up
pop.func.end

pop.func.define do_retry
    set wait_time 1000
    pop.sleep wait_time
    call_with_retry
pop.func.end

pop.func.define give_up
    ibbot.log error **API调用失败，已达最大重试次数
pop.func.end

# 执行带重试的调用
call_with_retry

---

五、注意事项

1. 参数传递：参数必须是一个对象变量，不能直接传递 JSON 字符串
2. 方法指定：默认使用 GET 方法，如需 POST 请在路径后加 :POST
3. 结果存储：调用结果会存储到指定的结果变量中
4. 错误处理：建议始终检查返回结果中的 ret 字段判断是否成功
5. 异步执行：API 调用是异步的，需要使用 pop.do.while 等待结果

这些示例展示了如何在 PopLang 中完整地调用 iBBot 的各种 API 端点，实现用户输入处理、任务管理、偏好管理等功能的自动化编排。