@vibe-lark/larkpal 0.1.91-issue71.0 → 0.1.91-issue83.0

package/README.md

@@ -88,6 +88,7 @@ lark-cli auth login
 | `LARKPAL_EXTERNAL_URL` | 外部可访问的网关 URL | - |
 | `LARKPAL_PUBLIC_URL` | OAuth 回调公开 URL | `http://localhost:3000` |
 | `LARKPAL_API_SECRET` | Agent Completion API 鉴权密钥 | `dev-internal-secret` |
+| `LARKPAL_BUSINESS_EVENT_CALLBACK_URL` | 飞书固定菜单和业务卡片回调转发地址 | 未配置 |
 | `LARKPAL_COMPLETION_CWD` | Agent Completion 工作目录 | `/tmp/larkpal-completion` |
 | `LARKPAL_CC_IDLE_TIMEOUT` | CC 进程空闲超时（秒） | `0`（永不超时） |
 | `LARKPAL_ENCRYPTION_KEY` | 用户凭证加密密钥（32字节 hex） | 未设置（明文，仅限开发） |
@@ -112,6 +113,48 @@ lark-cli auth login
 
 ---
 
+## Business Event Callback
+
+设置 `LARKPAL_BUSINESS_EVENT_CALLBACK_URL` 后，LarkPal 会把未被内置处理器消费的飞书固定菜单事件和业务卡片交互事件 POST 到该地址。
+
+`card.action.trigger` 的请求体包含稳定的 `action` 字段：
+
+```json
+{
+  "eventType": "card.action.trigger",
+  "trigger": {
+    "kind": "card_action",
+    "key": "card.action.update_draft",
+    "value": {
+      "action": "card.action.update_draft",
+      "eventId": "rd_assistant_create_formula",
+      "draftId": "...",
+      "status": "drafting"
+    }
+  },
+  "action": {
+    "value": {
+      "action": "card.action.update_draft",
+      "eventId": "rd_assistant_create_formula",
+      "draftId": "...",
+      "status": "drafting"
+    },
+    "inputValue": {
+      "project_id": "selected-project-id"
+    },
+    "formValue": {
+      "project_id": "selected-project-id"
+    }
+  }
+}
+```
+
+`action.value` 原样保留卡片组件配置里的 callback metadata。`select_static` 等带 `name` 的输入组件会把选中值规范化到 `action.inputValue[name]`；`action.formValue` 同步提供同一组表单值，方便业务侧按字段名读取。
+
+业务回调返回 `{"kind":"card_update","card":{...}}` 时，LarkPal 会用返回的 `card` patch 原始飞书卡片；返回 `toast` 时会继续作为卡片交互响应返回。
+
+---
+
 ## Agent Completion API
 
 外部业务方作为 AI 能力消费方，调用 LarkPal 的通用 AI 补全接口。

package/dist/main.mjs

@@ -18349,6 +18349,9 @@ function buildBusinessEventEnvelope(params) {
 	const openMessageId = readString(raw.open_message_id, context.open_message_id, event.open_message_id);
 	const cardId = readString(raw.card_id, raw.cardId, context.card_id, event.card_id);
 	const action = asRecord(raw.action);
+	const actionName = readString(action.name);
+	const inputValue = normalizeActionInputValue(action);
+	const formValue = normalizeActionFormValue(action, inputValue);
 	const sessionId = readString(actionValue.sessionId, actionValue.session_id, raw.session_id, event.session_id);
 	const conversationId = readString(openChatId, chatId);
 	return {
@@ -18368,8 +18371,11 @@ function buildBusinessEventEnvelope(params) {
 		card: { cardId },
 		action: {
 			value: action.value,
-			formValue: action.form_value,
-			inputValue: action.input_value
+			formValue,
+			inputValue,
+			name: actionName,
+			option: action.option,
+			options: action.options
 		},
 		conversationId,
 		sessionId,
@@ -18399,6 +18405,38 @@ function asRecord(value) {
 function isObject(value) {
 	return value != null && typeof value === "object" && !Array.isArray(value);
 }
+function normalizeActionInputValue(action) {
+	const inputValue = readFirstDefined(action.input_value, action.inputValue);
+	if (inputValue !== void 0) return inputValue;
+	const name = readString(action.name);
+	if (!name) return void 0;
+	const selected = extractSelectedActionValue(action);
+	if (selected === void 0) return void 0;
+	return { [name]: selected };
+}
+function normalizeActionFormValue(action, inputValue) {
+	const formValue = readFirstDefined(action.form_value, action.formValue);
+	if (formValue !== void 0) return formValue;
+	return isObject(inputValue) ? inputValue : void 0;
+}
+function extractSelectedActionValue(action) {
+	const directValue = readFirstDefined(action.selected_value, action.selectedValue);
+	if (directValue !== void 0) return directValue;
+	const optionValue = extractOptionValue(action.option);
+	if (optionValue !== void 0) return optionValue;
+	const options = Array.isArray(action.options) ? action.options : void 0;
+	if (options?.length) {
+		const values = options.map(extractOptionValue).filter((value) => value !== void 0);
+		if (values.length) return values;
+	}
+}
+function extractOptionValue(option) {
+	if (!isObject(option)) return void 0;
+	return readFirstDefined(option.value, option.id, option.key);
+}
+function readFirstDefined(...values) {
+	for (const value of values) if (value != null) return value;
+}
 function readString(...values) {
 	for (const value of values) if (typeof value === "string" && value.trim()) return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-lark/larkpal",
-  "version": "0.1.91-issue71.0",
+  "version": "0.1.91-issue83.0",
   "description": "LarkPal - Lark/Feishu bot service",
   "type": "module",
   "main": "./dist/main.mjs",