飛書智能查詢機器人搭建說明文檔
一、使用手冊
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）和大模型，基于命令獲取線上日志查詢結果并由大模型進行問題分析；
