飞书智能查询机器人设计与搭建一、使用手册1. 创建飞书机器人应用如果仅需对接已有机器人应用则可跳过该步骤建议各业务部门独立使用各自的机器人应用。在飞书开发者后台中创建企业自建应用添加机器人应用能力并申请对应的身份权限最终发布应用后即可在飞书中使用自定义机器人。注意新创建的机器人应用需要联系开发者进行后端自有服务对接否则无法使用命令查询和管理能力。步骤配置步骤配置解释配置说明1创建自建应用要为用户提供服务必须创建一个应用作为载体。登录飞书 开发者后台创建应用。在基础信息 凭证与基础信息页面可以查看应用的App ID和App Secret后续自有服务对接机器人的身份凭证。2添加应用能力机器人使应用可以接收消息、发送消息必须为应用开启机器人能力。在飞书开发者后台应用能力 添加应用能力页面添加机器人能力。3申请应用身份权限要通过应用调用接口、订阅事件以操作数据出于安全考虑必须为应用申请对应权限。要开通的具体权限可在要调用的接口和订阅的事件文档中查看。在飞书开发者后台开发配置 权限管理 API 权限页面开通应用身份权限。本项目机器人要申请的基本权限包括单聊和群聊4添加事件接收消息事件im.message.receive_v1要使应用及时收到用户在飞书发送的消息内容需要为应用订阅接收消息事件。在飞书开发者后台开发配置 事件与回调 事件配置页面编辑订阅方式。选择使用长连接接收事件并保存。提示在已添加事件区域点击添加事件并添加接收消息im.message.receive_v1事件。5发布应用当应用的基本信息、权限范围和应用功能等信息发生变更时都需要发布新的应用版本才能正式生效。在飞书开发者后台应用发布 版本管理与发布页面点击创建版本填写版本信息并发布并申请发布应用。若本次发布需要管理员审核建议创建一个新企业用于测试避免审核耗时。2. 配置机器人交互命令2.1 系统命令系统命令属于通用命令类型无法进行任何配置或修改统一由开发人员进行管理和维护若有想要新增的系统命令请联系开发者沟通。目前机器人系统支持的系统命令列表如下序号命令命令含义命令示例1/cmd展示当前机器人所有的可执行命令2/help {command}展示命令{command}的详细信息包括命令描述、命令参数等2.2 自定义命令自定义命令支持由用户配置和修改并由各业务系统自行维护。其配置过程如下序号步骤详细描述示例1选择业务域并新建命令配置选择业务域并新建命令配置目前仅支持电商机器人2填写命令配置各配置项参数的说明如下1.命令命令关键词命令触发的唯一标识必填2.描述命令的描述选填3.地址命令查询的目标地址从该地址获取返回数据必填4.请求类型地址的请求类型GET或POST必填5.模板ID飞书消息卡片的模板ID用于机器人呈现查询结果目前仅支持表格类型必填;6.附加信息命令请求目标地址时附加的请求头Header信息保存为JSON格式的key-value单层结构必填7.参数模版命令参数的配置模板该配置项实际会提取接收用户消息中的对应参数并在请求目标地址时作为查询参数传递必填8.提取模板查询结果的提取模板使用JsonPath表达式。该配置项实际会针对返回结果提取展示给用户消息中的字段数据列表必填3保存命令配置点击”保存“按钮保存命令配置2.2.1 附加信息填写规范附加信息是命令请求目标地址时附加的请求头Header信息在填写时需要保存为JSON格式的key-value单层结构其中key为请求头字段、value为字段值使用场景包括接口鉴权、更改请求方式POST请求Content-type默认为application/json、传递附加参数等。附加信息填写示例如下{Content-type:application/x-www-form-urlencoded,User-Agent:ffffffffffffffffffffffff0}2.2.2 参数模板填写规范参数模板是用户执行命令时需要同步传递的查询参数该模板配置项实际会识别并提取接收用户消息中对应参数的数据并在请求目标地址时作为查询参数传递。参数模板在填写时需要保存为JSON格式的key-value两层结构其中variable_params字段固定为变量集constant_params字段固定为常量集。参数模板填写示例如下{variable_params:{customerId:用户ID可选,orderId:订单ID可选,mobile:用户手机号可选,tradeId:交易号可选},constant_params:{current:1}}在variable_params变量集模板中key为参数名称、value为参数描述在constant_params常量集模板中key为参数名称、value为常量数值。注意这里常量参数不会在/help的系统命令中展示。2.2.3 提取模板填写规范提取模板是针对查询结果的提取结构该配置项实际会针对返回结果提取展示给用户消息中的字段数据列表提取模板在填写时需要保存为JSON格式的key-value单层结构其中key为结果提取字段、value为对应字段在返回结果中的JsonPath表达式。提取模板填写示例如下{customer_id:$.data[*].customer_id,order_id:$.data[*].order_id,parent_order_id:$.data[*].parent_order_id,goods_title:$.data[*].goods_title,resource_id:$.data[*].resource_id,status:$.data[*].status,strStartTime:$.data[*].strStartTime,strEndTime:$.data[*].strEndTime}需要注意的是结果提取字段key需要与飞书消息卡片模板ID中对应的变量名称相同否则机器人展示的查询消息将无法映射数据。3. 创建飞书消息卡片飞书自有的消息卡片具有良好的可读性、拓展性并且满足定制化需求与飞书机器人具有很强的联动性因此本系统选择飞书消息卡片来承载机器人返回的提取数据、格式化响应消息并作为结果展示看板。每条自定义命令都需要创建对应的消息卡片模板并在配置命令时填写对应的模板ID其地址为飞书卡片搭建工具需要注意的是目前机器人仅支持表格卡片且表格行变量名称需固定为result_array除此之外卡片在构建完成后必须发布并关联机器人应用才可以被调用。4. 添加并使用机器人机器人应用支持群聊需将机器人添加到群聊中和单聊命令的消息格式为{command} param_1valu_1 param_2value_2 ...其中param列表为参数模板中的变量集参数的子集无需全部使用机器人使用的示例如下二、系统设计机器人应用服务端通过EventDispatcher注册事件监听器建立长连接监听飞书客户端的机器人单聊或群聊消息识别并处理消息中的命令关键字和参数将最终查询结果通过WebSocket推送给客户端管理平台服务端通过独立的管理平台来管理和维护机器人相关命令的配置及参数三、未来演进数据总结对接大模型在数据查询后交由大模型对数据查询结果进行总结支持基于查询结果进行连续问答知识库助手对接知识库支持基于知识库和命令配置进行知识问答问题分析对接线上运维日志比如ClickHouse和大模型基于命令获取线上日志查询结果并由大模型进行问题分析