@vibe-lark/larkpal 0.1.91-issue69.0 → 0.1.91-issue70.0

package/README.md

@@ -93,9 +93,60 @@ lark-cli auth login
 | `LARKPAL_ENCRYPTION_KEY` | 用户凭证加密密钥（32字节 hex） | 未设置（明文，仅限开发） |
 | `LARKPAL_PLUGINS` | 声明式加载的插件列表 | 空 |
 | `LARKPAL_CHAT_JWT_SECRET` | Chat API JWT 签名密钥 | fallback 到 `LARKPAL_API_SECRET` |
+| `LARKPAL_BUSINESS_EVENT_CALLBACK_URL` | 飞书长连接业务事件回调地址，用于固定菜单和业务卡片 action | 空 |
 
 会话工作目录默认写入 `LARKPAL_WORKSPACE` 下的隐藏目录：飞书会话为 `.chats/`，通用 Agent 会话为 `.sessions/`，Chat API 历史为 `.chat-history/`。
 
+### Business Event Callback
+
+当配置 `LARKPAL_BUSINESS_EVENT_CALLBACK_URL` 时，LarkPal 会把内置处理器未消费的业务事件 POST 到该地址。典型来源包括飞书固定机器人菜单 `application.bot.menu_v6` 和业务自定义 `card.action.trigger`。回调响应可以让 LarkPal 在触发会话中发送可见反馈；业务系统拥有 workflow 语义和卡片内容，LarkPal 只负责 Feishu transport。
+
+**文本消息响应**
+
+```json
+{ "kind": "message", "text": "配方草稿已创建，请继续填写。" }
+```
+
+兼容格式：
+
+```json
+{ "message": { "text": "配方草稿已创建，请继续填写。" } }
+```
+
+**互动卡片响应**
+
+LarkPal 原样发送 `card` payload，不重写业务 action id。
+
+```json
+{
+  "kind": "card",
+  "card": {
+    "schema": "2.0",
+    "body": { "elements": [] }
+  }
+}
+```
+
+兼容格式：
+
+```json
+{ "card": { "schema": "2.0", "body": { "elements": [] } } }
+```
+
+**轻量提示响应**
+
+对于不支持直接 toast 的事件（如固定菜单），LarkPal 会降级发送一条可见文本消息，避免用户点击后无反馈。
+
+```json
+{ "kind": "toast", "toast": { "type": "warning", "content": "请先上传实验文档。" } }
+```
+
+兼容格式：
+
+```json
+{ "toast": { "type": "warning", "content": "请先上传实验文档。" } }
+```
+
 ### larkpal-agent Runtime 专用（LARKPAL_RUNTIME=larkpal-agent 时必填）
 
 | 变量名 | 用途 | 示例 |

package/dist/main.mjs

@@ -18337,7 +18337,15 @@ async function routeBusinessEvent(params) {
 		if (response.status === 204) return void 0;
 		if (!(response.headers.get("content-type") ?? "").includes("application/json")) return void 0;
 		const payload = await response.json();
-		return isObject(payload) ? payload : void 0;
+		if (!isObject(payload)) return void 0;
+		const normalizedResponse = normalizeBusinessCallbackResponse(payload);
+		await sendVisibleBusinessResponse({
+			cfg: params.cfg,
+			accountId: params.accountId,
+			envelope,
+			response: normalizedResponse
+		});
+		return normalizedResponse.raw;
 	} catch (err) {
 		log.warn("business event callback failed", {
 			accountId: params.accountId,
@@ -18387,6 +18395,105 @@ function extractBotMenuKey(rawEvent) {
 	const event = asRecord(raw.event);
 	return readString(raw.event_key, event.event_key, raw.menu_event_key, event.menu_event_key);
 }
+async function sendVisibleBusinessResponse(params) {
+	const target = params.envelope.conversationId;
+	if (!target) {
+		log.warn("business callback response has no Feishu send target", {
+			accountId: params.accountId,
+			eventType: params.envelope.eventType,
+			responseKind: params.response.kind,
+			trigger: params.envelope.trigger
+		});
+		return;
+	}
+	try {
+		if (params.response.kind === "card" && params.response.card) {
+			await sendCardFeishu({
+				cfg: params.cfg,
+				accountId: params.accountId,
+				to: target,
+				card: params.response.card
+			});
+			log.info("business callback card response sent", {
+				accountId: params.accountId,
+				eventType: params.envelope.eventType,
+				responseKind: params.response.kind,
+				target,
+				trigger: params.envelope.trigger
+			});
+			return;
+		}
+		const text = params.response.kind === "message" ? params.response.text : params.response.toast?.content;
+		if (text) {
+			await sendMessageFeishu({
+				cfg: params.cfg,
+				accountId: params.accountId,
+				to: target,
+				text
+			});
+			log.info("business callback message response sent", {
+				accountId: params.accountId,
+				eventType: params.envelope.eventType,
+				responseKind: params.response.kind,
+				target,
+				trigger: params.envelope.trigger
+			});
+		}
+	} catch (err) {
+		log.warn("business callback visible response send failed", {
+			accountId: params.accountId,
+			eventType: params.envelope.eventType,
+			responseKind: params.response.kind,
+			target,
+			trigger: params.envelope.trigger,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+function normalizeBusinessCallbackResponse(payload) {
+	const kind = typeof payload.kind === "string" ? payload.kind : void 0;
+	const message = asRecord(payload.message);
+	const toast = asRecord(payload.toast);
+	const card = normalizeCardPayload(payload);
+	const text = readString(payload.text, message.text, message.content);
+	if (kind === "card" && card) return {
+		kind: "card",
+		card,
+		raw: payload
+	};
+	if (card && !kind) return {
+		kind: "card",
+		card,
+		raw: payload
+	};
+	if (kind === "message" && text) return {
+		kind: "message",
+		text,
+		raw: payload
+	};
+	if (text && !kind) return {
+		kind: "message",
+		text,
+		raw: payload
+	};
+	if ((kind === "toast" || !kind) && isObject(toast)) return {
+		kind: "toast",
+		toast: {
+			type: readString(toast.type),
+			content: readString(toast.content)
+		},
+		raw: payload
+	};
+	return {
+		kind: "none",
+		raw: payload
+	};
+}
+function normalizeCardPayload(payload) {
+	if (isObject(payload.card)) return payload.card;
+	const card = asRecord(payload.card);
+	if (isObject(card.data)) return card.data;
+}
 function extractOperator(raw) {
 	const operator = asRecord(raw.operator);
 	const operatorId = asRecord(operator.operator_id);

package/package.json

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