飞书智能查询机器人搭建说明文档
一、使用手册
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_1=valu_1 param_2=value_2 ...，其中param列表为参数模板中的变量集参数的子集（无需全部使用），机器人使用的示例如下：
二、系统设计
- 机器人应用服务端： 通过
EventDispatcher注册事件监听器，建立长连接监听飞书客户端的机器人单聊或群聊消息，识别并处理消息中的命令关键字和参数，将最终查询结果通过WebSocket推送给客户端； - 管理平台服务端： 通过独立的管理平台来管理和维护机器人相关命令的配置及参数；
三、未来演进
- 数据总结：对接大模型，在数据查询后交由大模型对数据查询结果进行总结，支持基于查询结果进行连续问答；
- 知识库助手：对接知识库，支持基于知识库和命令配置进行知识问答；
- 问题分析：对接线上运维日志（比如ClickHouse）和大模型，基于命令获取线上日志查询结果并由大模型进行问题分析；
