feat: add SDK session implementation with approval flow and audit logging

- Implement SDK session with secretary model for tool approval flow - Add audit logging for tool usage and permission decisions - Support Feishu card interactions for approval requests - Add new commands for task interruption and progress checking - Remove old test files and update documentation
2026-04-01 12:51:00 +08:00
parent ba1b5b76c6
commit eac90941ef
34 changed files with 2375 additions and 965 deletions
@@ -0,0 +1,72 @@
+# 回调概述
+
+回调适用于需要对用户行为进行同步响应的业务场景，即当用户在飞书中触发某些操作时，前端加载等待服务端返回响应数据。待服务端返回响应结果时，前端加载完成，并向用户展示返回的响应结果。
+
+在飞书业务中，回调功能的典型使用场景如下：
+
+- **卡片交互场景**：用户点击卡片上的交互组件（比如审批卡片上的同意/拒绝按钮），开发者的服务端将收到按钮的点击回调，并且需要立即响应更新后的卡片内容，给予用户操作反馈（比如把审批状态流转为已审批）。
+
+- **链接预览场景**：用户在聊天中查看某个应用链接，该链接支持返回应用配置的[预览数据](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/development-link-preview/link-preview-development-guide)，此时该应用的服务端会收到[拉取链接预览数据](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/development-link-preview/pull-link-preview-data-callback-structure)的回调，并且需要立即响应返回链接预览内容，从而使终端用户看到链接预览效果。
+
+## 回调与事件的区别
+
+![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/88c9a80327f80bc5ddce17babe63f64d_bWeBkMFagD.png?height=440&lazyload=true&maxWidth=600&width=1600)
+
+回调与[事件](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)相似但又有不同：
+- **相似点：**
+    - 都是飞书服务器主动向开发者服务器推送数据。
+    - 回调与事件有相似的数据结构，可以复用同一套加密解密策略，开发者在解析飞书返回的内容时，可以采取同一套策略。
+- **差异点：**
+    - 订阅回调后，开发者服务器需要**立即返回**响应内容，以反馈用户操作，而事件则不要求返回。
+    - 回调是同步操作，不提供补推机制，超时未响应即认为这次回调失败，前端会展示报错等平台提供的兜底响应策略。
+    - 事件是异步操作，开发者只需简单响应飞书服务器是否收到事件即可，如开发者未响应，则平台会补推送事件。
+
+## 订阅流程
+
+步骤 | 说明
+---|---
+1. 选择回调订阅方式 | 回调订阅方式分为 **使用长连接接收回调** 和 **将回调发送至开发者服务器** 两种，你可以根据需要自行选择任一订阅方式。<br>**注意事项**：-   **使用长连接接收回调** 方式是飞书 SDK 内提供的能力，你可以通过集成飞书 SDK 与开放平台建立一条 WebSocket 全双工通道（你的服务器需要能够访问公网）。后续当应用订阅的回调发生时，开放平台会通过该通道向你的服务器发送消息。详细配置说明参见[使用长连接接收回调](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/configure-callback-request-address)。<br>- **将回调发送至开发者服务器** 方式是传统的 Webhook 模式，该方式需要你提供用于接收回调消息的服务器公网地址。后续当应用订阅的回调发生时，开放平台会向服务器的公网地址发送 HTTP POST 请求，请求内包含回调数据。详细配置说明参见[将回调发送至开发者服务器](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/step-1-choose-a-subscription-mode/send-callbacks-to-developers-server)。
+2. 添加所需回调 | 完成回调订阅方式配置后，即可为应用添加所需订阅的回调，并发布应用使配置生效。具体操作参见[添加回调](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/add-callback)。
+3. 接收回调 | 根据不同的回调订阅方式接收回调：<br>- **使用长连接接收回调** 方式已经封装了鉴权逻辑，无需进行数据解密与验签操作，直接接收来自开放平台的回调请求即可。<br>- **将回调发送至开发者服务器** 方式需要你根据应用的加密策略进行安全校验，如果是加密回调，需要先解密回调，再解析回调详情。具体操作参见[接收回调](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/receive-and-handle-callbacks)。
+
+## 回调结构
+
+回调返回的数据结构与事件类似。以“拉取链接预览数据”(`url.preview.get`)为例，回调的结构示意如下：
+
+```json
+{
+  "schema": "2.0", //表示回调的版本，2.0表示这个回调结构与事件的2.0版本在形式上一致
+  "header": { //回调的通用参数
+    "token": "vi57noNQoGbhxxxxxWmmWdlsSn3FTzk1", //对应 Verification Token
+    "create_time": "170134xxxxx18480", //回调发送的时间戳，近似于回调触发的时间
+    "event_type": "url.preview.get", //回调类型
+    "tenant_key": "736xxxxx260f175d", //回调所属应用的租户id
+    "app_id": "cli_a40xxxxxe57e100c" //回调所属应用的应用id
+  },
+  "event": { //记录不同回调类型返回的详细的上下文信息
+    "operator": { 
+      "tenant_key": "736588cxxxx175d",
+      "user_id": "c3xxxxd1",
+      "open_id": "ou_xxxxx54182ea7b8319f4d39823b79d2"
+    },
+    "host": "im_message", //链接所在的宿主场景。枚举包括1.im_message 聊天消息 2.im_top_notice 群置顶
+    "context": { //这个场景下具体的上下文参数
+      "url": "https://feishu-url.bytedance.net/smartcard/test/111", //匹配URL规则的原链接
+      "preview_token": "e28r7df2-xxxx-477d-a8d0-2e1eb99796c2", //用于标识链接预览的凭证，在返回链接预览数据时要用
+      "open_message_id": "om_191d914xxxxx81c97a609c663452dfdf", //触发链接预览的消息ID
+      "open_chat_id": "oc_20443194b65f9c8cf2935818dae39999" //触发链接预览的群ID
+    }
+  }
+}
+```
+
+## 回调列表
+
+目前支持的回调列表如下：
+
+功能模块 | 回调名称 | 描述
+---|---|---
+卡片 | [卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication) | 用户点击卡片上配置回传交互的组件时，触发此回调。<br>可通过返回 toast、更新后的卡片内容等反馈用户的交互。
+链接预览 | [拉取链接预览数据](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/development-link-preview/pull-link-preview-data-callback-structure) | 用户在聊天中查看匹配应用注册的URL规则的链接时，触发此回调。<br>可通过返回文字链、卡片等链接预览内容，为裸链扩展链接预览效果。
+卡片 | [消息卡片回传交互（旧）](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure) | 当用户点击卡片上添加了回传交互的组件时，开发者注册的服务端回调地址将收到此回调。<br>开发者可声明通过弹出 toast、更新卡片、保持原内容不变等方式来响应用户交互。<br><md-alert type="tip" icon="none">该回调使用旧版的协议，兼容历史的机器人[回调配置](https://open.feishu.cn/document/ukTMukTMukTM/uYzMxEjL2MTMx4iNzETM)。
+q
@@ -0,0 +1,253 @@
+# 卡片回传交互回调
+
+**卡片回传交互**作用于飞书卡片的 **请求回调** 交互组件。当终端用户点击飞书卡片上的回传交互组件后，你在开发者后台应用内注册的回调请求地址将会收到 **卡片回传交互** 回调。该回调包含了用户与卡片之间的交互信息。
+
+你的业务服务器接收到回调请求后，需要在 3 秒内响应回调请求，声明通过弹出 Toast 提示、更新卡片、保持原内容不变等方式响应用户交互。了解详细的操作步骤，参考[处理卡片回调](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/handle-card-callbacks)。
+
+卡片回调和服务端响应回调的结构体参考下文。
+**注意事项**：- 本文档提供新版本的卡片回调结构和响应示例。开放平台 SDK 已全量支持新版卡片回调。
+- 了解旧版回调的 SDK 调用，参考[消息卡片回传交互（旧）](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure)。
+
+## 回调
+
+基本信息 | &nbsp;
+---|---
+回调类型 | card.action.trigger
+支持的应用类型 | Custom App、Store App
+权限要求<br>**订阅该事件所需的权限，开启其中任意一项权限即可订阅**<br>开启任一权限即可 | 暂无
+字段权限要求 | **注意事项**：事件结构体中存在 `user_id` 敏感字段，仅当应用开启“获取用户 user ID”权限后才会返回。<br>获取用户 user ID(contact:user.employee_id:readonly)
+推送方式 | [Webhook](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)
+
+## 回调结构体
+
+字段 | 数据类型 | 描述
+---|---|---
+schema | string | 回调的版本。固定取值为 `2.0`，为最新版本回调。了解旧版本回调，参考[消息卡片回传交互（旧）](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure)。
+header | object | 回调基本信息。
+event_id | string | 回调的唯一标识。
+token | string | 应用的 Verification Token。
+create_time | string | 回调发送的时间，接近回调发生的时间。微秒级时间戳。
+event_type | string | 回调类型。卡片交互场景中，固定为 `"card.action.trigger"`。
+tenant_key | string | 应用归属的 tenant key，即租户唯一标识。
+app_id | string | 应用的 App ID。
+event | object | 回调的详细信息。
+operator | object | 回调触发者信息。
+tenant_key | string | 回调触发者的 tenant key，即租户唯一标识。
+user_id | string | 回调触发者的 user_id。了解不同的用户 ID，参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。
+union_id | string | 回调触发者的 union_id。
+open_id | string | 回调触发者的 open_id。
+token | string | [更新卡片](https://open.feishu.cn/document/ukTMukTMukTM/uMDO1YjLzgTN24yM4UjN)用的凭证，有效期为 30 分钟，最多可更新 2 次。
+action | object | 交互信息。
+value | object/ string | 交互组件绑定的开发者自定义回传数据，对应组件中的 value 属性。类型为 string 或 object，可由开发者指定。
+tag | string | 交互组件的标签。
+timezone | string | 用户当前所在地区的时区。当用户操作日期选择器、时间选择器、或日期时间选择器时返回。
+name | string | 组件的自定义唯一标识，用于识别内嵌在表单容器中的某个组件。
+form_value | object | 表单容器内用户提交的数据。示例值：<br>```JSON<br>{<br>"field name 1": [ // 表单容器内某多选组件的 name 和 value<br>"selectDemo1",<br>"selectDemo2"<br>], <br>"field name 2": "value 2", // 表单容器内某交互组件的 name 和 value<br>"field name 3": "value 3", // 表单容器内某交互组件的 name 和 value<br>}<br>```
+input_value | string | 当输入框组件未内嵌在表单容器中时，用户在输入框中提交的数据。
+option | string | 当折叠按钮组、下拉选择-单选、人员选择-单选、日期选择器、时间选择器、日期时间选择器组件未内嵌在表单容器中时，用户选择该类组件某个选项时，组件返回的选项回调值。
+options | string[] | 当下拉选择-多选组件和人员选择-多选组件未内嵌在表单容器中时，用户选择该类组件某个选项时，组件返回的选项回调值。
+checked | bool | 当勾选器组件未内嵌在表单容器中时，勾选器组件的回调数据。
+host | string | 卡片展示场景。
+delivery_type | string | 卡片分发类型，固定取值为 `url_preview`，表示链接预览卡片。仅链接预览卡片有此字段。
+context | object | 展示场景上下文。
+url | string | 链接地址（适用于链接预览场景）。
+preview_token | string | 链接预览的 token（适用于链接预览场景）。
+open_message_id | string | 消息 ID。
+open_chat_id | string | 会话 ID。
+
+## 回调结构体示例
+
+```json
+{
+    "schema": "2.0", // 回调的版本
+    "header": { // 回调基本信息
+        "event_id": "f7984f25108f8137722bb63c*****", // 回调的唯一标识
+        "token": "066zT6pS4QCbgj5Do145GfDbbag*****", // 应用的 Verification Token
+        "create_time": "1603977298000000",  // 回调发送的时间，接近回调发生的时间。微秒级时间戳
+        "event_type": "card.action.trigger", // 回调类型卡片交互场景中，固定为 "card.action.trigger"
+        "tenant_key": "2df73991750*****", // 应用归属的 tenant key，即租户唯一标识
+        "app_id": "cli_a5fb0ae6a4******" // 应用的 App ID
+    },
+    "event": { // 回调的详细信息
+        "operator": {   // 回调触发者信息
+            "tenant_key": "2df73991750*****", // 回调触发者的 tenant key，即租户唯一标识
+            "user_id": "867*****", // 回调触发者的 user ID。当应用开启“获取用户 user ID”权限后，该参数返回
+            "open_id": "ou_3c14f3a59eaf2825dbe25359f15*****", // 回调触发者的 Open ID
+            "union_id": "on_cad4860e7af114fb4ff6c5d496d*****" // 回调触发者的 Union ID
+        },
+        "token": "c-295ee57216a5dc9de90fefd0aadb4b1d7d******", // 更新卡片用的凭证，有效期为 30 分钟，最多可更新 2 次
+        "action": { // 用户操作交互组件回传的数据
+            "value": { // 交互组件绑定的开发者自定义回传数据，对应组件中的 value 属性。类型为 string 或 object，可由开发者指定。
+                "key": "value"
+            },
+            "tag": "button", // 交互组件的标签
+            "timezone": "Asia/Shanghai", // 用户当前所在地区的时区。当用户操作日期选择器、时间选择器、或日期时间选择器时返回
+            "form_value": { // 表单容器内用户提交的数据
+                "field name1": [ // 表单容器内某多选组件的 name 和 value
+                    "selectDemo1",
+                    "selectDemo2"
+                ],
+                "field name2": "value2", // 表单容器内某交互组件的 name 和 value
+                "DatePicker_bpqdq5puvn4": "2024-04-01 +0800", // 表单容器内日期选择器组件的 name 和 value
+                "DateTimePicker_ihz2d7a74i": "2024-04-29 07:07 +0800", // 表单容器内日期时间选择器组件的 name 和 value
+                "Input_lf4fmxwfrd9": "1234", // 表单容器内输入框组件的 name 和 value
+                "PersonSelect_2ejys7ype7m": "ou_3c14f3a59eaf2825dbe25359f15*****", // 表单容器内人员选择-单选组件的 name 和 value
+                "Select_a2d5b7l3zd": "1", // 表单容器内下拉选择-单选组件的 name 和 value
+                "TimePicker_7ecsf6xkqsq": "00:00 +0800" // 表单容器内时间选择器组件的 name 和 value
+            },
+            "name": "Button_lvkepfu3" // 用户操作交互组件的名称，由开发者自定义
+        },
+        "host": "im_message", // 卡片展示场景
+        "delivery_type": "url_preview", // 卡片分发类型，固定取值为 url_preview，表示链接预览卡片仅链接预览卡片有此字段
+        "context": { //  卡片展示场景相关信息
+            "url": "xxx", // 链接地址（适用于链接预览场景）
+            "preview_token": "xxx", // 链接预览的 token（适用于链接预览场景）
+            "open_message_id": "om_574d639e4a44e4dd646eaf628e2*****", // 卡片所在的消息 ID
+            "open_chat_id": "oc_e4d2605ca917e695f54f11aaf56*****" // 卡片所在的会话 ID
+        }
+    }
+}
+```
+
+## 响应回调的结构体
+
+你的业务服务器接收到回调请求后，需要在 3 秒内响应回调请求，声明通过弹出 Toast 提示、更新卡片、保持原内容不变等方式响应用户交互。以下为使用卡片 JSON 代码和卡片模板响应的字段说明。要了解响应方式，参考[处理卡片回调](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/handle-card-callbacks)。warning
+业务服务端不可使用重定向状态码（`HTTP 3xx`）来响应卡片的回调请求，否则用户端将会出现交互请求错误。
+
+### 使用卡片 JSON 代码响应
+
+字段 | 数据类型 | 是否必填 | 描述
+---|---|---|---
+toast | object | 否 | 客户端的 Toast 弹窗提示。
+type | string | 否 | 弹窗提示的类型。可选值有：info、success、error、和 warning。<br>不同的值的展示效果如下图所示：<br>![img_v3_02ao_9fdce3f7-5ba1-4f86-941f-2e5e7f6fd4eg.jpg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e62145dca9a372b1b51f0ea2e2629160_y1gPzFePcx.jpg?height=844&lazyload=true&width=1280)
+content | string | 否 | 单语言提示文案。要配置多语言提示文案，请使用 `i18n` 字段。
+i18n | Map | 否 | 多语言提示文案。示例配置：<br>```json<br>{<br>"i18n": {<br>"zh_cn": "更新成功！",<br>"en_us": "Successful update"<br>}<br>}<br>```
+key | string | 否 | 语言。可选值：<br>- `zh_cn`: 简体中文<br>- `en_us`: 英文<br>- `zh_hk`: 繁体中文（香港）<br>- `zh_tw`: 繁体中文（台湾）<br>- `ja_jp`: 日语<br>- `id_id`: 印尼语<br>- `vi_vn`: 越南语<br>- `th_th`: 泰语<br>- `pt_br`: 葡萄牙语<br>- `es_es`: 西班牙语<br>- `ko_kr`: 韩语<br>- `de_de`: 德语<br>- `fr_fr`: 法语<br>- `it_it`: 意大利语<br>- `ru_ru`: 俄语<br>- `ms_my`: 马来语
+value | string | 否 | 语言对应的文案。
+card | object | 否 | 卡片数据。
+type | string | 是 | 卡片类型。可选值：<br>- `template`：搭建工具构建的卡片，可视为一个卡片模板<br>- `raw`：由 JSON 构建的卡片<br>要使用卡片 JSON 代码响应，请选择 `raw`。
+data | object | 是 | 卡片的 JSON 数据。 <br>- 若发送卡片时，卡片 JSON 结构为 1.0 版本，那么你需传入卡片 JSON 1.0 数据。详情参考[卡片 JSON 1.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-structure)<br>- 若发送卡片时，卡片 JSON 结构为 2.0 版本，那么你需传入卡片 JSON 2.0 数据。详情参考[卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)
+
+响应回调的结构体示例（以 JSON 2.0 结构为例）
+
+```json
+{
+    "toast": {
+        "type": "info",
+        "content": "卡片交互成功",
+        "i18n": {
+            "zh_cn": "卡片交互成功",
+            "en_us": "card action success"
+        }
+    },
+    "card": {
+        "type": "raw",
+        "data": {
+            "schema": "2.0",
+            "config": {
+                "update_multi": true,
+                "style": {
+                    "text_size": {
+                        "normal_v2": {
+                            "default": "normal",
+                            "pc": "normal",
+                            "mobile": "heading"
+                        }
+                    }
+                }
+            },
+            "body": {
+                "direction": "vertical",
+                "padding": "12px 12px 12px 12px",
+                "elements": [
+                    {
+                        "tag": "div",
+                        "text": {
+                            "tag": "plain_text",
+                            "content": "示例文本",
+                            "text_size": "normal_v2",
+                            "text_align": "left",
+                            "text_color": "default"
+                        },
+                        "margin": "0px 0px 0px 0px"
+                    }
+                ]
+            },
+            "header": {
+                "title": {
+                    "tag": "plain_text",
+                    "content": "示例标题"
+                },
+                "subtitle": {
+                    "tag": "plain_text",
+                    "content": "示例文本"
+                },
+                "template": "blue",
+                "padding": "12px 12px 12px 12px"
+            }
+        }
+    }
+}
+```
+
+### 使用卡片模板响应
+
+字段 | 数据类型 | 是否必填 | 描述
+---|---|---|---
+toast | object | 否 | 客户端的 Toast 弹窗提示。
+type | string | 否 | 弹窗提示的类型。可选值有：info、success、error、和 warning。<br>不同的值的展示效果如下图所示：<br>![img_v3_02ao_9fdce3f7-5ba1-4f86-941f-2e5e7f6fd4eg.jpg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e62145dca9a372b1b51f0ea2e2629160_y1gPzFePcx.jpg?height=844&lazyload=true&width=1280)
+content | string | 否 | 单语言提示文案。要配置多语言提示文案，请使用 `i18n` 字段。
+i18n | Map | 否 | 多语言提示文案。示例配置：<br>```json<br>{<br>"i18n": {<br>"zh_cn": "更新成功！",<br>"en_us": "Successful update"<br>}<br>}<br>```
+key | string | 否 | 语言。可选值：<br>- `zh_cn`: 简体中文<br>- `en_us`: 英文<br>- `zh_hk`: 繁体中文（香港）<br>- `zh_tw`: 繁体中文（台湾）<br>- `ja_jp`: 日语<br>- `id_id`: 印尼语<br>- `vi_vn`: 越南语<br>- `th_th`: 泰语<br>- `pt_br`: 葡萄牙语<br>- `es_es`: 西班牙语<br>- `ko_kr`: 韩语<br>- `de_de`: 德语<br>- `fr_fr`: 法语<br>- `it_it`: 意大利语<br>- `ru_ru`: 俄语<br>- `ms_my`: 马来语
+value | string | 否 | 语言对应的文案。
+card | object | 否 | 卡片数据。
+type | string | 是 | 卡片类型。可选值：<br>- `template`：搭建工具构建的卡片，可视为一个卡片模板<br>- `raw`：由 JSON 构建的卡片<br>要使用卡片模板响应，请选择 `template`。
+data | object | 是 | 卡片模板的数据。
+template_id | string | 是 | 搭建工具中创建的卡片（也称卡片模板）的 ID，如 AAqigYkzabcef。可在搭建工具中通过复制卡片模板 ID 获取。<br>![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8bf97ff2bceed633b28f5ce2d2ec0270_zPTWqjljT8.png?height=329&lazyload=true&maxWidth=500&width=1574)
+template_variable | object | 否 | 若卡片绑定了变量，你需在该字段中传入实际变量数据的值。示例：如果变量名称在搭建工具中被定义为 open_id，则此处需要对 open_id 变量传入值。以“ou_d506829e8b6a17607e56bcd6b1aabcef”为示例：<br>```json<br>{<br>"open_id": "ou_d506829e8b6a17607e56bcd6b1aabcef"<br>}<br>```
+template_version_name | string | 否 | 搭建工具中创建的卡片的版本号，如 1.0.0。卡片发布后，将生成版本号。可在搭建工具 **版本管理** 处获取。<br>![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b3e96c8ca7c5c029bdbce6c0ca1ba413_aoV0ao7VUo.png?height=384&lazyload=true&maxWidth=500&width=1459)
+
+响应回调的结构体示例
+
+```json
+{
+    "toast": {
+        "type": "info",
+        "content": "卡片交互成功",
+        "i18n": {
+            "zh_cn": "卡片交互成功",
+            "en_us": "card action success"
+        }
+    },
+    "card": {
+        "type": "template",
+        "data": {
+            "template_id": "AAqi6xJ8rabcd",
+            "template_version_name": "1.0.0",
+            "template_variable": {
+                "open_id": "ou_d506829e8b6a17607e56bcd6b1aabcef"
+            }
+        }
+    }
+}
+```
+## 错误码
+
+在飞书客户端进行卡片交互时，若交互出错，将返回如下图对应的错误码。错误码说明及解决方案如下表所示。
+
+![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/29558d328f22a099dc8ce5c66bf4e5ba_DD7lIR8Lxk.png?height=64&lazyload=true&width=285)
+错误码仅支持飞书客户端 7.28 及以上版本。若未返回错误码，请升级飞书客户端后重试。
+
+错误码 | 描述 | 解决方案
+---|---|---
+200340 | 应用未配置飞书卡片回调地址或配置的请求地址无效。<br>若应用已配置，请确保你已创建并发布了最新的应用版本使修改生效。 | 1. 前往[开发者后台](https://open.feishu.cn/app)，点击目标应用，选择 **开发配置** > **事件与回调**。<br>2. 在 **事件与回调** 页面 **回调配置** 页签下，填写正确有效的请求地址并保存。<br>3. 在 **已订阅的回调** 项中，确保已添加卡片回传交互回调。<br>**提示**：你也可以选择使用长连接接收回调。了解更多，参考[配置回调订阅方式](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/configure-callback-request-address)。
+200341 | 所请求的卡片回调服务未在规定时间内响应飞书卡片服务端。 | 请确保配置的回调地址能够在 3 秒内响应卡片回调请求。
+200342 | 飞书卡片服务端无法与该卡片回调地址建立 TCP 连接。 | 请检查并确保配置的回调地址可以正常访问。
+200343 | 飞书卡片服务端解析该卡片回调地址的 DNS 失败。 | 请检查并确保配置的回调地址的域名正确。
+200530 | 在表单容器中的交互组件的 name （表单项标识）属性为空。 | `name` 是表单容器内组件的唯一标识，用于识别用户提交的数据属于哪个组件，在单张卡片内不可为空、不可重复。<br>- 如果你使用卡片 JSON 搭建卡片，请确保所有的 name 属性的值不为空。`name` 数据类型为字符串。<br>- 如果你使用卡片搭建工具搭建卡片：<br>1. 在卡片编辑页面，选中表单内的交互组件，在右侧属性页签下，确保 **表单项标识** 已填写。<br>![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/93894aaf05f60f3576e64cb5a0f22569_62E0goGKeA.png?height=482&lazyload=true&width=1547)<br>2. 点击右上角的 **保存**，然后点击 **发布**，确保修改生效。<br>![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b704b7552c24d7956b402092c7c38775_c3K900pZqf.png?height=557&lazyload=true&width=1557)
+200080 | 飞书卡片服务端请求该卡片回调地址时发生错误。 | 请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)进行处理。
+200671 | 请求的卡片回调服务返回了非 `HTTP 200` 的状态码，导致无法进行正常的卡片交互。 | 请检查并确保接口代码逻辑正常，确保不会返回异常状态码。
+200672 | 请求的卡片回调服务返回了错误的响应体格式。 | - 如果你添加的是新版卡片回传交互(`card.action.trigger`)回调，请参考[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication#65787609)检查响应回调的结构体的格式是否有误。<br>- 如果你添加的是旧版卡片回传交互(`card.action.trigger_v1`)回调，请参考[消息卡片回传交互（旧）](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure)检查响应回调的结构体的格式是否有误。<br>- 如果你同时添加了新版和旧版卡片回传交互回调，响应其中任一回调即为成功响应。建议你删除多余的请求方式。
+200673 | 请求的卡片回调服务返回了错误的卡片。 | - 如果你添加的是新版卡片回传交互(`card.action.trigger`)回调，请参考[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication#65787609)检查响应回调的结构体中 `card` 部分是否有误。<br>- 如果你添加的是旧版卡片回传交互(`card.action.trigger_v1`)回调，请参考[消息卡片回传交互（旧）](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure)检查响应回调的结构体中除 `toast` 外的其它部分是否有误。
+200830 | JSON 2.0 结构的卡片无法更新为 JSON 1.0 结构卡片。 | 如果交互前卡片的结构为[卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)，交互后的卡片结构仍必须为 2.0 结构。
+300000 | 服务内部错误。 | 请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。