@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/dispatch-context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Dispatch context construction for the inbound agent dispatch pipeline.
+ *
+ * Derives all shared values needed by downstream dispatch helpers:
+ * logging, addressing, route resolution, thread session, and system
+ * event emission.
+ */
+import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import type { MessageContext } from '../types';
+import type { LarkAccount } from '../../core/types';
+import { LarkClient } from '../../core/lark-client';
+export interface DispatchContext {
+    ctx: MessageContext;
+    /** account 级别的 ClawdbotConfig（channels.feishu 已替换为 per-account 合并后的配置） */
+    accountScopedCfg: ClawdbotConfig;
+    account: LarkAccount;
+    runtime: RuntimeEnv;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    core: typeof LarkClient.runtime;
+    isGroup: boolean;
+    isThread: boolean;
+    feishuFrom: string;
+    feishuTo: string;
+    envelopeFrom: string;
+    envelopeOptions: ReturnType<typeof LarkClient.runtime.channel.reply.resolveEnvelopeFormatOptions>;
+    route: ReturnType<typeof LarkClient.runtime.channel.routing.resolveAgentRoute>;
+    threadSessionKey?: string;
+    commandAuthorized?: boolean;
+}
+/**
+ * Provide a safe RuntimeEnv fallback when the caller did not supply one.
+ * Replaces the previous unsafe `runtime as RuntimeEnv` casts.
+ */
+export declare function ensureRuntime(runtime: RuntimeEnv | undefined): RuntimeEnv;
+/**
+ * Derive all shared values needed by downstream helpers:
+ * logging, addressing, route resolution, and system event emission.
+ */
+export declare function buildDispatchContext(params: {
+    ctx: MessageContext;
+    account: LarkAccount;
+    accountScopedCfg: ClawdbotConfig;
+    runtime?: RuntimeEnv;
+    commandAuthorized?: boolean;
+}): DispatchContext;
+/**
+ * Resolve thread session key for thread-capable groups.
+ *
+ * Returns a thread-scoped session key when ALL conditions are met:
+ *   1. `threadSession` config is enabled on the account
+ *   2. The group is a topic group (chat_mode=topic) or uses thread
+ *      message mode (group_message_type=thread)
+ *
+ * The group info is fetched via `im.chat.get` with a 1-hour LRU cache
+ * to minimise OAPI calls.
+ */
+export declare function resolveThreadSessionKey(params: {
+    accountScopedCfg: ClawdbotConfig;
+    account: LarkAccount;
+    chatId: string;
+    threadId: string;
+    baseSessionKey: string;
+}): Promise<string | undefined>;

package/src/messaging/inbound/dispatch-context.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Dispatch context construction for the inbound agent dispatch pipeline.
+ *
+ * Derives all shared values needed by downstream dispatch helpers:
+ * logging, addressing, route resolution, thread session, and system
+ * event emission.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureRuntime = ensureRuntime;
+exports.buildDispatchContext = buildDispatchContext;
+exports.resolveThreadSessionKey = resolveThreadSessionKey;
+const routing_1 = require("openclaw/plugin-sdk/routing");
+const lark_client_1 = require("../../core/lark-client.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const chat_info_cache_1 = require("../../core/chat-info-cache.js");
+const comment_target_1 = require("../../core/comment-target.js");
+const log = (0, lark_logger_1.larkLogger)('inbound/dispatch-context');
+// ---------------------------------------------------------------------------
+// RuntimeEnv fallback
+// ---------------------------------------------------------------------------
+/**
+ * Provide a safe RuntimeEnv fallback when the caller did not supply one.
+ * Replaces the previous unsafe `runtime as RuntimeEnv` casts.
+ */
+function ensureRuntime(runtime) {
+    if (runtime)
+        return runtime;
+    return {
+        log: (...args) => log.info(args.map(String).join(' ')),
+        error: (...args) => log.error(args.map(String).join(' ')),
+        exit: (code) => process.exit(code),
+    };
+}
+// ---------------------------------------------------------------------------
+// Context construction
+// ---------------------------------------------------------------------------
+/**
+ * Derive all shared values needed by downstream helpers:
+ * logging, addressing, route resolution, and system event emission.
+ */
+function buildDispatchContext(params) {
+    const { ctx, account, accountScopedCfg } = params;
+    const runtime = ensureRuntime(params.runtime);
+    const log = runtime.log;
+    const error = runtime.error;
+    const isComment = (0, comment_target_1.isCommentTarget)(ctx.chatId);
+    const isGroup = !isComment && ctx.chatType === 'group';
+    const isThread = isGroup && Boolean(ctx.threadId);
+    const core = lark_client_1.LarkClient.runtime;
+    const feishuFrom = `feishu:${ctx.senderId}`;
+    // Comment targets use the comment target string directly as the "To"
+    // so the outbound routing layer can detect it and route through Drive API.
+    const feishuTo = isComment
+        ? ctx.chatId
+        : isGroup
+            ? `chat:${ctx.chatId}`
+            : `user:${ctx.senderId}`;
+    const envelopeFrom = isGroup ? `${ctx.chatId}:${ctx.senderId}` : ctx.senderId;
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(accountScopedCfg);
+    // ---- Route resolution ----
+    // Comment targets use the comment target as the peer ID so each
+    // comment thread gets its own session key.
+    const route = core.channel.routing.resolveAgentRoute({
+        cfg: accountScopedCfg,
+        channel: 'feishu',
+        accountId: account.accountId,
+        peer: isComment
+            ? { kind: 'direct', id: ctx.chatId }
+            : {
+                kind: isGroup ? 'group' : 'direct',
+                id: isGroup ? ctx.chatId : ctx.senderId,
+            },
+    });
+    // ---- System event ----
+    const sender = ctx.senderName ? `${ctx.senderName} (${ctx.senderId})` : ctx.senderId;
+    const location = isComment ? `comment ${ctx.chatId}` : isGroup ? `group ${ctx.chatId}` : 'DM';
+    const tags = [];
+    tags.push(`msg:${ctx.messageId}`);
+    if (ctx.parentId)
+        tags.push(`reply_to:${ctx.parentId}`);
+    if (ctx.contentType !== 'text')
+        tags.push(ctx.contentType);
+    if (ctx.mentions.some((m) => m.isBot))
+        tags.push('@bot');
+    if (ctx.threadId)
+        tags.push(`thread:${ctx.threadId}`);
+    if (ctx.resources.length > 0) {
+        tags.push(`${ctx.resources.length} attachment(s)`);
+    }
+    const tagStr = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+    core.system.enqueueSystemEvent(`Feishu[${account.accountId}] ${location} | ${sender}${tagStr}`, {
+        sessionKey: route.sessionKey,
+        contextKey: `feishu:message:${ctx.chatId}:${ctx.messageId}`,
+    });
+    return {
+        ctx,
+        accountScopedCfg,
+        account,
+        runtime,
+        log,
+        error,
+        core,
+        isGroup,
+        isThread,
+        feishuFrom,
+        feishuTo,
+        envelopeFrom,
+        envelopeOptions,
+        route,
+        threadSessionKey: undefined,
+        commandAuthorized: params.commandAuthorized,
+    };
+}
+// ---------------------------------------------------------------------------
+// Thread session resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve thread session key for thread-capable groups.
+ *
+ * Returns a thread-scoped session key when ALL conditions are met:
+ *   1. `threadSession` config is enabled on the account
+ *   2. The group is a topic group (chat_mode=topic) or uses thread
+ *      message mode (group_message_type=thread)
+ *
+ * The group info is fetched via `im.chat.get` with a 1-hour LRU cache
+ * to minimise OAPI calls.
+ */
+async function resolveThreadSessionKey(params) {
+    const { accountScopedCfg, account, chatId, threadId, baseSessionKey } = params;
+    if (account.config?.threadSession !== true)
+        return undefined;
+    const threadCapable = await (0, chat_info_cache_1.isThreadCapableGroup)({
+        cfg: accountScopedCfg,
+        chatId,
+        accountId: account.accountId,
+    });
+    if (!threadCapable) {
+        log.info(`thread session skipped: group ${chatId} is not topic/thread mode`);
+        return undefined;
+    }
+    // 使用 SDK 标准函数，保证分隔符格式与 resolveThreadParentSessionKey 兼容
+    const { sessionKey } = (0, routing_1.resolveThreadSessionKeys)({
+        baseSessionKey,
+        threadId,
+        parentSessionKey: baseSessionKey,
+        normalizeThreadId: (id) => id, // 飞书 thread ID (omt_xxx) 区分大小写，不做 lowercase
+    });
+    return sessionKey;
+}

package/src/messaging/inbound/dispatch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Agent dispatch for inbound Feishu messages.
+ *
+ * Builds the agent envelope, prepends chat history context, and
+ * dispatches through the appropriate reply path (system command
+ * vs. normal streaming/static flow).
+ *
+ * Implementation details are split across focused modules:
+ * - dispatch-context.ts  — DispatchContext type, route/session/event
+ * - dispatch-builders.ts — pure payload/body/envelope construction
+ * - dispatch-commands.ts — system command & permission notification
+ */
+import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { MessageContext } from '../types';
+import type { FeishuGroupConfig, LarkAccount } from '../../core/types';
+import type { PermissionError } from './permission';
+export declare function dispatchToAgent(params: {
+    ctx: MessageContext;
+    permissionError?: PermissionError;
+    mediaPayload: Record<string, unknown>;
+    /** Additional structured metadata for synthetic or event-driven inbound flows. */
+    extraInboundFields?: Record<string, unknown>;
+    quotedContent?: string;
+    account: LarkAccount;
+    /** account 级别的 ClawdbotConfig（channels.feishu 已替换为 per-account 合并后的配置） */
+    accountScopedCfg: ClawdbotConfig;
+    runtime?: RuntimeEnv;
+    chatHistories?: Map<string, HistoryEntry[]>;
+    historyLimit: number;
+    /** Override the message ID used for reply threading.  When set, the
+     *  reply-dispatcher uses this ID for typing indicators and card replies
+     *  instead of ctx.messageId (which may be a synthetic ID). */
+    replyToMessageId?: string;
+    /** When set, controls whether the sender is authorized to execute
+     *  control commands.  Computed by the handler via the SDK's access
+     *  group command gating system. */
+    commandAuthorized?: boolean;
+    /** Per-group configuration for skills, systemPrompt, etc. */
+    groupConfig?: FeishuGroupConfig;
+    /** Default group configuration from the "*" wildcard entry. */
+    defaultGroupConfig?: FeishuGroupConfig;
+    /** When true, the reply dispatcher skips typing indicators. */
+    skipTyping?: boolean;
+    /** The receiving bot's own open_id, used for self-identity injection. */
+    botOpenId?: string;
+}): Promise<void>;