@vibe-lark/larkpal 0.1.91-issue68.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

@@ -7009,6 +7009,175 @@ function clearChatInfoCache(accountId) {
 	}
 }
 //#endregion
+//#region src/core/lark-ws-event-normalizer.ts
+const REDACTED_HEADER_PATTERN = /authorization|token|secret|signature|encrypt|cookie|credential/i;
+function normalizeLarkWsEventFrame(frame) {
+	const rewrittenTypeFrame = readHeader(frame.headers, ["type"]) === "card" ? {
+		...frame,
+		headers: (frame.headers ?? []).map((header) => header.key === "type" ? {
+			...header,
+			value: "event"
+		} : header)
+	} : frame;
+	if (rewrittenTypeFrame.payload && rewrittenTypeFrame.payload.byteLength > 0) return rewrittenTypeFrame;
+	const eventType = readHeader(rewrittenTypeFrame.headers, [
+		"event_type",
+		"event-type",
+		"eventType",
+		"x-lark-event-type",
+		"x-lark-event_type"
+	]);
+	if (eventType !== "application.bot.menu_v6") return rewrittenTypeFrame;
+	const eventKey = readHeader(rewrittenTypeFrame.headers, [
+		"event_key",
+		"event-key",
+		"eventKey",
+		"menu_event_key",
+		"menu-event-key",
+		"menuEventKey"
+	]);
+	if (!eventKey) return rewrittenTypeFrame;
+	const payload = buildBotMenuPayload(rewrittenTypeFrame.headers, eventType, eventKey);
+	return {
+		...rewrittenTypeFrame,
+		headers: ensureDispatchHeaders(rewrittenTypeFrame.headers),
+		payload: new TextEncoder().encode(JSON.stringify(payload))
+	};
+}
+function getLarkWsFrameDiagnostics(frame) {
+	const diagnostics = {
+		msgType: readHeader(frame.headers, ["type"]),
+		eventType: readHeader(frame.headers, [
+			"event_type",
+			"event-type",
+			"eventType",
+			"x-lark-event-type",
+			"x-lark-event_type"
+		]),
+		eventKey: readHeader(frame.headers, [
+			"event_key",
+			"event-key",
+			"eventKey",
+			"menu_event_key",
+			"menu-event-key"
+		]),
+		headersCount: frame.headers?.length ?? 0,
+		hasData: frame.data != null,
+		hasPayload: !!frame.payload && frame.payload.byteLength > 0,
+		dataPreview: previewUnknown(frame.data),
+		payloadPreview: previewPayload(frame.payload)
+	};
+	if (!diagnostics.eventType || !diagnostics.hasPayload) diagnostics.headers = sanitizeHeaders(frame.headers);
+	return diagnostics;
+}
+function buildBotMenuPayload(headers, eventType, eventKey) {
+	const tenantKey = readHeader(headers, [
+		"tenant_key",
+		"tenant-key",
+		"tenantKey",
+		"x-tenant-key"
+	]);
+	const operatorOpenId = readHeader(headers, [
+		"operator_open_id",
+		"operator-open-id",
+		"operatorOpenId",
+		"open_id",
+		"open-id"
+	]);
+	const operatorUserId = readHeader(headers, [
+		"operator_user_id",
+		"operator-user-id",
+		"operatorUserId",
+		"user_id",
+		"user-id"
+	]);
+	const operatorUnionId = readHeader(headers, [
+		"operator_union_id",
+		"operator-union-id",
+		"operatorUnionId",
+		"union_id"
+	]);
+	const openChatId = readHeader(headers, [
+		"open_chat_id",
+		"open-chat-id",
+		"openChatId",
+		"chat_id",
+		"chat-id"
+	]);
+	return omitUndefined({
+		schema: "2.0",
+		header: omitUndefined({
+			event_type: eventType,
+			tenant_key: tenantKey
+		}),
+		event: omitUndefined({
+			event_key: eventKey,
+			operator: operatorOpenId || operatorUserId || operatorUnionId ? { operator_id: omitUndefined({
+				open_id: operatorOpenId,
+				user_id: operatorUserId,
+				union_id: operatorUnionId
+			}) } : void 0,
+			open_chat_id: openChatId
+		})
+	});
+}
+function readHeader(headers, names) {
+	const wanted = new Set(names.map(normalizeHeaderName));
+	for (const header of headers ?? []) {
+		const key = header.key;
+		const value = header.value;
+		if (!key || typeof value !== "string" || !value.trim()) continue;
+		if (wanted.has(normalizeHeaderName(key))) return value;
+	}
+}
+function normalizeHeaderName(name) {
+	return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function sanitizeHeaders(headers) {
+	return (headers ?? []).filter((header) => typeof header.key === "string").map((header) => ({
+		key: header.key,
+		value: REDACTED_HEADER_PATTERN.test(header.key) ? "[redacted]" : previewString(header.value)
+	}));
+}
+function ensureDispatchHeaders(headers) {
+	const nextHeaders = [...headers ?? []];
+	const ensureHeader = (key, value) => {
+		if (!readHeader(nextHeaders, [key])) nextHeaders.push({
+			key,
+			value
+		});
+	};
+	ensureHeader("message_id", `synthetic-${Date.now()}`);
+	ensureHeader("sum", "1");
+	ensureHeader("seq", "0");
+	ensureHeader("trace_id", "synthetic-bot-menu");
+	return nextHeaders;
+}
+function previewPayload(payload) {
+	if (!payload || payload.byteLength === 0) return void 0;
+	try {
+		return previewString(new TextDecoder().decode(payload));
+	} catch {
+		return `[binary:${payload.byteLength}]`;
+	}
+}
+function previewUnknown(value) {
+	if (value == null) return void 0;
+	if (typeof value === "string") return previewString(value);
+	try {
+		return previewString(JSON.stringify(value));
+	} catch {
+		return String(value).slice(0, 200);
+	}
+}
+function previewString(value) {
+	if (typeof value !== "string") return void 0;
+	return value.slice(0, 200);
+}
+function omitUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== void 0));
+}
+//#endregion
 //#region src/core/lark-client.ts
 /**
 * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
@@ -7331,24 +7500,13 @@ var LarkClient = class LarkClient {
 		const wsClientAny = this._wsClient;
 		const origHandleEventData = wsClientAny.handleEventData.bind(wsClientAny);
 		wsClientAny.handleEventData = (data) => {
-			const msgType = data.headers?.find?.((h) => h.key === "type")?.value;
-			const eventType = data.headers?.find?.((h) => h.key === "event_type")?.value;
+			const normalizedData = normalizeLarkWsEventFrame(data);
+			const diagnostics = getLarkWsFrameDiagnostics(normalizedData);
 			log$24.info("WS 收到原始事件", {
 				accountId: this.accountId,
-				msgType,
-				eventType,
-				headersCount: data.headers?.length,
-				hasData: !!data.data,
-				dataPreview: typeof data.data === "string" ? data.data.slice(0, 200) : JSON.stringify(data.data)?.slice(0, 200)
-			});
-			if (msgType === "card") return origHandleEventData({
-				...data,
-				headers: data.headers.map((h) => h.key === "type" ? {
-					...h,
-					value: "event"
-				} : h)
+				...diagnostics
 			});
-			return origHandleEventData(data);
+			return origHandleEventData(normalizedData);
 		};
 		await this.waitForAbort(dispatcher, abortSignal);
 	}
@@ -18179,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,
@@ -18229,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-issue68.0",
+  "version": "0.1.91-issue70.0",
   "description": "LarkPal - Lark/Feishu bot service",
   "type": "module",
   "main": "./dist/main.mjs",