@zhin.js/adapter-lark 4.0.3 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @zhin.js/adapter-lark
 
+## 5.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 5.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 4.0.3
 
 ### Patch Changes

package/README.md

@@ -36,7 +36,7 @@ pnpm add @zhin.js/adapter-lark
 3. 启用机器人能力并配置事件订阅 URL：`https://your-domain/lark/webhook`
 4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-必填字段：`appId`、`appSecret`。
+必填字段（`endpoints[i]`）：`name`、`appId`、`appSecret`。
 
 ## 最小配置
 
@@ -44,14 +44,15 @@ pnpm add @zhin.js/adapter-lark
 # zhin.config.yml（Plugin Runtime）
 plugins:
   lark:
-    name: my-lark-bot
-    appId: ${LARK_APP_ID}
-    appSecret: ${LARK_APP_SECRET}
     webhookPath: /lark/webhook          # 可选，默认 /lark/webhook
-    encryptKey: ${LARK_ENCRYPT_KEY}     # 可选
-    verificationToken: ${LARK_VERIFY_TOKEN}  # 可选
     isFeishu: true                      # 可选，默认 true
     # apiBaseUrl: https://open.feishu.cn/open-apis
+    endpoints:
+      - name: my-lark-bot
+        appId: ${LARK_APP_ID}
+        appSecret: ${LARK_APP_SECRET}
+        # encryptKey: ${LARK_ENCRYPT_KEY}          # 可选
+        # verificationToken: ${LARK_VERIFY_TOKEN}  # 可选
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-lark`（`instanceKey: lark`）。

package/adapters/lark.ts

@@ -9,18 +9,31 @@ import {
   resolveLarkConfig,
   type LarkAdapterConfig,
 } from '../src/protocol.js';
+import { larkRuntimeStateToken } from '../src/lark-runtime-state.js';
 
 export { LarkEndpoint } from '../src/endpoint.js';
 export type { LarkEndpointOptions, LarkFetch } from '../src/endpoint.js';
 
 export default defineAdapter<LarkAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // image 段经 /im/v1/images 物化为 image_key（url 下载后上传）；
+  // 卡片交互未接入出站通道，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'text',
+  },
   create(context) {
+    const config = resolveLarkConfig(context.config);
+    // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
+    context.use(larkRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: 'webhook',
+    });
     return new LarkEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
       http: context.use(httpHostToken),
-      config: resolveLarkConfig(context.config),
+      config,
     });
   },
 });

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { larkEndpointCommands } from '../../../src/lark-endpoint-commands.js';
+
+export default larkEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { larkEndpointCommands } from '../../src/lark-endpoint-commands.js';
+
+export default larkEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { larkEndpointCommands } from '../../../src/lark-endpoint-commands.js';
+
+export default larkEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,12 +1,14 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { resolveMediaBinary } from './media-upload.js';
 import { type LarkMessage, type ResolvedLarkConfig } from './protocol.js';
 export type LarkFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
     readonly body?: string | FormData;
+    readonly signal?: AbortSignal;
 }) => Promise<{
     readonly ok: boolean;
     readonly status: number;
@@ -22,6 +24,14 @@ export interface LarkEndpointOptions {
 }
 export declare class LarkEndpoint implements EndpointInstance {
     #private;
+    /**
+     * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
+     * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
+     * - listGroupMembers：GET /im/v1/chats/:chat_id/members（open_id 分页，返回平台原生成员形状）
+     * 不接的项：listFriends（Lark 无好友概念，contact API 为组织通讯录而非社交关系）、
+     * listChannels（无频道/guild 概念）、写操作（审批/踢人/禁言等本轮不在范围内）。
+     */
+    readonly management: EndpointManagement;
     constructor(options: LarkEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
@@ -34,6 +44,8 @@ export declare class LarkEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
+    uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: LarkMessage): void;
     getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;

package/lib/endpoint.js

@@ -5,12 +5,39 @@ import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
+import { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 import { formatInboundContent, formatOutboundBody, generateMessageId, resolveChatType, resolveSender, resolveTarget, } from './protocol.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 const logger = getLogger('lark');
+/** 出站 HTTP 调用统一 30s 超时。 */
+const OUTBOUND_TIMEOUT_MS = 30_000;
 export class LarkEndpoint {
     #options;
     #fetch;
+    /**
+     * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
+     * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
+     * - listGroupMembers：GET /im/v1/chats/:chat_id/members（open_id 分页，返回平台原生成员形状）
+     * 不接的项：listFriends（Lark 无好友概念，contact API 为组织通讯录而非社交关系）、
+     * listChannels（无频道/guild 概念）、写操作（审批/踢人/禁言等本轮不在范围内）。
+     */
+    management = Object.freeze({
+        listGroups: async () => {
+            const items = await this.#listAllPages('/im/v1/chats');
+            const groups = [];
+            for (const item of items) {
+                const chatId = typeof item.chat_id === 'string' ? item.chat_id : '';
+                if (!chatId)
+                    continue;
+                groups.push({
+                    group_id: chatId,
+                    name: typeof item.name === 'string' && item.name ? item.name : chatId,
+                });
+            }
+            return groups;
+        },
+        listGroupMembers: (groupId) => this.#listAllPages(`/im/v1/chats/${encodeURIComponent(groupId)}/members`, { member_id_type: 'open_id' }),
+    });
     #routeReleases = [];
     #accessToken = { token: '', expires_in: 0, timestamp: 0 };
     #refreshPromise = null;
@@ -33,6 +60,15 @@ export class LarkEndpoint {
             return;
         this.#started = true;
         try {
+            if (!this.#options.config.encryptKey && !this.#options.config.verificationToken) {
+                // encryptKey / verificationToken 都未配置时 webhook 完全无鉴权，任何人可伪造事件
+                logger.warn(formatCompact({
+                    endpoint: this.#options.config.name,
+                    op: 'webhook',
+                    ok: false,
+                    error: 'neither encryptKey nor verificationToken configured; webhook is unauthenticated',
+                }));
+            }
             await this.#refreshAccessToken();
             this.#unregisterAgent = registerLarkAgentEndpoint(this.#options.config.name, this);
             this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
@@ -64,7 +100,8 @@ export class LarkEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const content = formatOutboundBody(payload);
+        const materialized = await this.#materializeOutboundMedia(payload);
+        const content = formatOutboundBody(materialized);
         const data = await this.#request('/im/v1/messages', {
             method: 'POST',
             params: { receive_id_type: 'chat_id' },
@@ -86,6 +123,55 @@ export class LarkEndpoint {
         }));
         return messageId;
     }
+    /**
+     * im/v1 消息 image 段只接受 image_key：canonical MediaRef（base64/本地路径/URL）
+     * 先经 /im/v1/images 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     */
+    async #materializeOutboundMedia(payload) {
+        if (!Array.isArray(payload))
+            return payload;
+        return Promise.all(payload.map(async (item) => {
+            if (typeof item === 'string' || !item || typeof item !== 'object')
+                return item;
+            const seg = item;
+            if (seg.type !== 'image')
+                return item;
+            const data = seg.data ?? {};
+            const media = readOutboundImageMedia(data);
+            if (!media)
+                return item;
+            const imageKey = await this.uploadImage(media);
+            if (!imageKey) {
+                const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+                return { type: 'text', data: { text: alt } };
+            }
+            return { type: 'image', data: { image_key: imageKey } };
+        }));
+    }
+    /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
+    async uploadImage(media) {
+        try {
+            await this.#ensureAccessToken();
+            const binary = await resolveMediaBinary(media);
+            const form = buildImageUploadForm(binary);
+            const url = `${this.#options.config.apiBaseUrl}/im/v1/images`;
+            const response = await this.#fetch(url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${this.#accessToken.token}` },
+                body: form,
+                signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
+            });
+            const data = await response.json();
+            if (data.code === 0) {
+                return data.data?.image_key || null;
+            }
+            throw new Error(`Image upload failed: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to upload image:', error);
+            return null;
+        }
+    }
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg) {
         if (!this.#open)
@@ -99,7 +185,7 @@ export class LarkEndpoint {
             id: generateMessageId(msg),
             metadata: Object.freeze({
                 messageType: msg.message_type,
-                chatType: resolveChatType(msg.chat_id),
+                chatType: resolveChatType(msg.chat_id, msg.chat_type),
                 endpoint: this.#options.config.name,
             }),
         }).catch((err) => {
@@ -275,6 +361,36 @@ export class LarkEndpoint {
             return false;
         }
     }
+    /** 拉取分页列表（items + has_more/page_token）；code!==0 时抛错交由 RPC 层透出。 */
+    async #listAllPages(path, params = {}) {
+        const items = [];
+        let pageToken = '';
+        do {
+            const data = await this.#request(path, {
+                method: 'GET',
+                params: {
+                    ...params,
+                    page_size: 100,
+                    ...(pageToken ? { page_token: pageToken } : {}),
+                },
+            });
+            if (data.code !== 0) {
+                throw new Error(`Lark API ${path} failed: ${data.msg ?? 'unknown'} (${data.code})`);
+            }
+            const page = data.data ?? {};
+            if (Array.isArray(page.items)) {
+                for (const item of page.items) {
+                    if (item !== null && typeof item === 'object') {
+                        items.push(item);
+                    }
+                }
+            }
+            pageToken = page.has_more === true && typeof page.page_token === 'string'
+                ? page.page_token
+                : '';
+        } while (pageToken);
+        return items;
+    }
     async #request(path, options = {}) {
         await this.#ensureAccessToken();
         const { method = 'GET', params = {}, body } = options;
@@ -288,6 +404,7 @@ export class LarkEndpoint {
                 Authorization: `Bearer ${this.#accessToken.token}`,
             },
             body: body && method !== 'GET' ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
         });
         if (!response.ok) {
             const text = await response.text().catch(() => '');

package/lib/index.d.ts

@@ -2,4 +2,5 @@ export { formatInboundContent, formatOutboundBody, generateMessageId, headerValu
 export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, type LarkAgentDeps, type LarkAgentEndpoint, } from './lark-agent-deps.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
 export { LarkEndpoint, type LarkEndpointOptions, type LarkFetch, } from './endpoint.js';
+export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, type LarkWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -2,4 +2,5 @@ export { formatInboundContent, formatOutboundBody, generateMessageId, headerValu
 export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, } from './lark-agent-deps.js';
 export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
 export { LarkEndpoint, } from './endpoint.js';
+export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';

package/lib/lark-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const larkEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/lark-endpoint-commands.js

@@ -0,0 +1,19 @@
+/**
+ * `lark endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { larkRuntimeStateToken } from './lark-runtime-state.js';
+export const larkEndpointCommands = createEndpointCommands({
+    adapterKey: 'lark',
+    adapterDisplayName: 'Lark',
+    fields: [
+        { key: 'appId', required: true, env: true, description: '飞书 App ID' },
+        { key: 'appSecret', required: true, env: true, description: '飞书 App Secret' },
+        { key: 'encryptKey', env: true, description: '事件加密 key' },
+        { key: 'verificationToken', env: true, description: '事件验证 token' },
+    ],
+    running: (use) => use(larkRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/lib/lark-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const larkRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/lark-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Lark 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `lark endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+export const larkRuntimeStateToken = defineEndpointRuntimeStateToken('lark');

package/lib/media-upload.d.ts

@@ -0,0 +1,15 @@
+import { type MediaRef } from '@zhin.js/core';
+export interface MediaBinary {
+    readonly data: Buffer;
+    readonly mimeType: string;
+    readonly fileName: string;
+}
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+/** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
+export declare function buildImageUploadForm(binary: MediaBinary): FormData;
+/**
+ * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -0,0 +1,62 @@
+/**
+ * Lark 图片上传（im/v1 消息 image 段需要 image_key）。
+ * 接口：POST {apiBaseUrl}/im/v1/images（multipart：image_type=message + image）
+ * 与 im/v1/messages 同属 IM 接口域（同一 tenant_access_token），不引入额外授权域。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+const MIME_EXT = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/bmp': 'bmp',
+};
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(media, download = defaultDownload) {
+    const mimeType = media.mime_type ?? 'image/png';
+    const ext = MIME_EXT[mimeType] ?? 'png';
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value;
+        return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+    }
+    if (media.kind === 'path') {
+        const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+        return { data: await readFile(path), mimeType, fileName: basename(path) };
+    }
+    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+async function defaultDownload(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw new Error(`download failed: HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+/** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
+export function buildImageUploadForm(binary) {
+    // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+    const bytes = new Uint8Array(binary.data.byteLength);
+    bytes.set(binary.data);
+    const form = new FormData();
+    form.append('image_type', 'message');
+    form.append('image', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+    return form;
+}
+/**
+ * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export function readOutboundImageMedia(data) {
+    if (typeof data.image_key === 'string' && data.image_key)
+        return undefined;
+    if (typeof data.file_key === 'string' && data.file_key)
+        return undefined;
+    if (typeof data.key === 'string' && data.key)
+        return undefined;
+    if (isMediaRef(data.media))
+        return data.media;
+    return mediaRefFromLegacyData(data);
+}

package/lib/protocol.d.ts

@@ -36,6 +36,8 @@ export interface LarkMessage {
     readonly create_time?: string;
     readonly update_time?: string;
     readonly chat_id?: string;
+    /** 事件携带的会话类型（'p2p' | 'group'）；p2p 的 chat_id 也是 oc_ 开头。 */
+    readonly chat_type?: string;
     readonly sender?: {
         readonly sender_id?: {
             readonly user_id?: string;
@@ -93,13 +95,17 @@ export interface LarkSendBody {
 }
 export declare function resolveLarkConfig(config?: LarkAdapterConfig): ResolvedLarkConfig;
 export declare function normalizeWebhookPath(path: string): string;
-export declare function resolveChatType(chatId?: string): 'group' | 'private';
+export declare function resolveChatType(chatId?: string, chatType?: string): 'group' | 'private';
 export declare function resolveTarget(msg: LarkMessage): string;
 export declare function resolveSender(msg: LarkMessage): string;
 export declare function generateMessageId(msg: LarkMessage): string;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: LarkMessage): string;
-export declare function verifySignature(encryptKey: string, timestamp: string, nonce: string, body: string, signature: string): boolean;
+/** 验签时间戳时效窗口（防重放）。 */
+export declare const LARK_SIGNATURE_MAX_AGE_MS: number;
+export declare function verifySignature(encryptKey: string, timestamp: string, nonce: string, body: string, signature: string, nowMs?: number): boolean;
+/** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
+export declare function verifyToken(token: string, expected: string): boolean;
 /**
  * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
  * Segment canonicalization is intentionally not done here.

package/lib/protocol.js

@@ -38,7 +38,12 @@ export function normalizeWebhookPath(path) {
     const trimmed = path.trim() || '/lark/webhook';
     return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
-export function resolveChatType(chatId) {
+export function resolveChatType(chatId, chatType) {
+    // 优先使用事件里的 chat_type：p2p 会话的 chat_id 同样以 oc_ 开头，不能靠前缀判断
+    if (chatType === 'group')
+        return 'group';
+    if (chatType === 'p2p')
+        return 'private';
     return chatId?.startsWith('oc_') ? 'group' : 'private';
 }
 export function resolveTarget(msg) {
@@ -86,8 +91,15 @@ export function formatInboundContent(msg) {
         return '[消息解析失败]';
     }
 }
-export function verifySignature(encryptKey, timestamp, nonce, body, signature) {
+/** 验签时间戳时效窗口（防重放）。 */
+export const LARK_SIGNATURE_MAX_AGE_MS = 5 * 60_000;
+export function verifySignature(encryptKey, timestamp, nonce, body, signature, nowMs = Date.now()) {
     try {
+        // 时效窗口 ±5min，超出直接拒绝（timestamp 为秒）
+        const ts = Number(timestamp);
+        if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > LARK_SIGNATURE_MAX_AGE_MS) {
+            return false;
+        }
         const stringToSign = `${timestamp}${nonce}${encryptKey}${body}`;
         const calculated = createHash('sha256').update(stringToSign).digest('hex');
         const a = Buffer.from(calculated);
@@ -100,6 +112,19 @@ export function verifySignature(encryptKey, timestamp, nonce, body, signature) {
         return false;
     }
 }
+/** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
+export function verifyToken(token, expected) {
+    try {
+        const a = Buffer.from(token);
+        const b = Buffer.from(expected);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
  * Segment canonicalization is intentionally not done here.
@@ -147,7 +172,8 @@ export function formatOutboundBody(payload) {
                     media = {
                         msg_type: 'image',
                         content: JSON.stringify({
-                            image_key: data.file_key ?? data.key ?? data.url,
+                            // image_key 由 endpoint 上传物化写入；file_key/key/url 为旧调用方兼容入口。
+                            image_key: data.image_key ?? data.file_key ?? data.key ?? data.url,
                         }),
                     };
                 }

package/lib/webhook.js

@@ -1,5 +1,5 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { headerValue, readTextBody, verifySignature, } from './protocol.js';
+import { headerValue, readTextBody, verifySignature, verifyToken, } from './protocol.js';
 const logger = getLogger('lark');
 export function registerLarkWebhookRoutes(http, handler) {
     const path = handler.config.webhookPath;
@@ -14,7 +14,7 @@ export async function handleLarkWebhookRequest(request, response, handler) {
         const rawBody = await readTextBody(request);
         if (handler.config.verificationToken) {
             const token = headerValue(request.headers, 'x-lark-request-token');
-            if (token !== handler.config.verificationToken) {
+            if (!verifyToken(token, handler.config.verificationToken)) {
                 logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid verification token' }));
                 response.writeHead(403, { 'Content-Type': 'text/plain' });
                 response.end('Forbidden');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "4.0.3",
+  "version": "5.0.1",
   "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,21 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,11 +66,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -95,6 +97,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerLarkPlatformPermitChecker } from './src/platform-permit.js';
+import { larkRuntimeStateToken } from './src/lark-runtime-state.js';
 
 export default definePlugin({
   name: 'lark',
   metadata: {
     displayName: 'Lark/Feishu (飞书) Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（lark endpoint list 的"运行中"数据源）
+    context.resources.provide(larkRuntimeStateToken, createEndpointRuntimeState());
     return registerLarkPlatformPermitChecker();
   },
 });

package/schema.json

@@ -3,23 +3,59 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "lark-bot"
-    },
-    "appId": { "type": "string" },
-    "appSecret": { "type": "string" },
-    "encryptKey": { "type": "string" },
-    "verificationToken": { "type": "string" },
     "webhookPath": {
       "type": "string",
       "default": "/lark/webhook"
     },
-    "apiBaseUrl": { "type": "string" },
+    "apiBaseUrl": {
+      "type": "string"
+    },
     "isFeishu": {
       "type": "boolean",
       "default": true
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Lark bot name"
+          },
+          "appId": {
+            "type": "string",
+            "description": "Lark app ID"
+          },
+          "appSecret": {
+            "type": "string",
+            "description": "Lark app secret"
+          },
+          "encryptKey": {
+            "type": "string",
+            "description": "Lark encrypt key"
+          },
+          "verificationToken": {
+            "type": "string",
+            "description": "Lark verification token"
+          }
+        },
+        "required": [
+          "name",
+          "appId",
+          "appSecret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["appId", "appSecret"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -3,12 +3,17 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointGroup, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
+import {
+  buildImageUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+} from './media-upload.js';
 import {
   formatInboundContent,
   formatOutboundBody,
@@ -25,12 +30,16 @@ import { registerLarkWebhookRoutes } from './webhook.js';
 
 const logger = getLogger('lark');
 
+/** 出站 HTTP 调用统一 30s 超时。 */
+const OUTBOUND_TIMEOUT_MS = 30_000;
+
 export type LarkFetch = (
   url: string,
   init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
     readonly body?: string | FormData;
+    readonly signal?: AbortSignal;
   },
 ) => Promise<{
   readonly ok: boolean;
@@ -50,6 +59,32 @@ export interface LarkEndpointOptions {
 export class LarkEndpoint implements EndpointInstance {
   readonly #options: LarkEndpointOptions;
   readonly #fetch: LarkFetch;
+  /**
+   * Console 社交面语义端口。Lark OpenAPI 仅接读取类列表能力：
+   * - listGroups：GET /im/v1/chats（bot 所在群列表，分页归一为 {group_id: chat_id, name}）
+   * - listGroupMembers：GET /im/v1/chats/:chat_id/members（open_id 分页，返回平台原生成员形状）
+   * 不接的项：listFriends（Lark 无好友概念，contact API 为组织通讯录而非社交关系）、
+   * listChannels（无频道/guild 概念）、写操作（审批/踢人/禁言等本轮不在范围内）。
+   */
+  readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
+    listGroups: async (): Promise<readonly EndpointGroup[]> => {
+      const items = await this.#listAllPages('/im/v1/chats');
+      const groups: EndpointGroup[] = [];
+      for (const item of items) {
+        const chatId = typeof item.chat_id === 'string' ? item.chat_id : '';
+        if (!chatId) continue;
+        groups.push({
+          group_id: chatId,
+          name: typeof item.name === 'string' && item.name ? item.name : chatId,
+        });
+      }
+      return groups;
+    },
+    listGroupMembers: (groupId) => this.#listAllPages(
+      `/im/v1/chats/${encodeURIComponent(groupId)}/members`,
+      { member_id_type: 'open_id' },
+    ),
+  });
   #routeReleases: HttpRouteRegistration[] = [];
   #accessToken: AccessToken = { token: '', expires_in: 0, timestamp: 0 };
   #refreshPromise: Promise<string> | null = null;
@@ -75,6 +110,15 @@ export class LarkEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
+      if (!this.#options.config.encryptKey && !this.#options.config.verificationToken) {
+        // encryptKey / verificationToken 都未配置时 webhook 完全无鉴权，任何人可伪造事件
+        logger.warn(formatCompact({
+          endpoint: this.#options.config.name,
+          op: 'webhook',
+          ok: false,
+          error: 'neither encryptKey nor verificationToken configured; webhook is unauthenticated',
+        }));
+      }
       await this.#refreshAccessToken();
       this.#unregisterAgent = registerLarkAgentEndpoint(this.#options.config.name, this);
       this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
@@ -108,7 +152,8 @@ export class LarkEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const content = formatOutboundBody(payload);
+    const materialized = await this.#materializeOutboundMedia(payload);
+    const content = formatOutboundBody(materialized);
     const data = await this.#request('/im/v1/messages', {
       method: 'POST',
       params: { receive_id_type: 'chat_id' },
@@ -131,6 +176,52 @@ export class LarkEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  /**
+   * im/v1 消息 image 段只接受 image_key：canonical MediaRef（base64/本地路径/URL）
+   * 先经 /im/v1/images 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   */
+  async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
+    if (!Array.isArray(payload)) return payload;
+    return Promise.all(payload.map(async (item) => {
+      if (typeof item === 'string' || !item || typeof item !== 'object') return item;
+      const seg = item as { type?: unknown; data?: Record<string, unknown> };
+      if (seg.type !== 'image') return item;
+      const data = seg.data ?? {};
+      const media = readOutboundImageMedia(data);
+      if (!media) return item;
+      const imageKey = await this.uploadImage(media);
+      if (!imageKey) {
+        const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+        return { type: 'text', data: { text: alt } };
+      }
+      return { type: 'image', data: { image_key: imageKey } };
+    }));
+  }
+
+  /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
+  async uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null> {
+    try {
+      await this.#ensureAccessToken();
+      const binary = await resolveMediaBinary(media);
+      const form = buildImageUploadForm(binary);
+      const url = `${this.#options.config.apiBaseUrl}/im/v1/images`;
+      const response = await this.#fetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${this.#accessToken.token}` },
+        body: form,
+        signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
+      });
+      const data = await response.json() as LarkApiResponse;
+      if (data.code === 0) {
+        return (data.data?.image_key as string) || null;
+      }
+      throw new Error(`Image upload failed: ${data.msg}`);
+    } catch (error) {
+      logger.error('Failed to upload image:', error);
+      return null;
+    }
+  }
+
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: LarkMessage): void {
     if (!this.#open) return;
@@ -143,7 +234,7 @@ export class LarkEndpoint implements EndpointInstance {
       id: generateMessageId(msg),
       metadata: Object.freeze({
         messageType: msg.message_type,
-        chatType: resolveChatType(msg.chat_id),
+        chatType: resolveChatType(msg.chat_id, msg.chat_type),
         endpoint: this.#options.config.name,
       }),
     }).catch((err) => {
@@ -325,6 +416,40 @@ export class LarkEndpoint implements EndpointInstance {
     }
   }
 
+  /** 拉取分页列表（items + has_more/page_token）；code!==0 时抛错交由 RPC 层透出。 */
+  async #listAllPages(
+    path: string,
+    params: Record<string, string | number> = {},
+  ): Promise<Record<string, unknown>[]> {
+    const items: Record<string, unknown>[] = [];
+    let pageToken = '';
+    do {
+      const data = await this.#request(path, {
+        method: 'GET',
+        params: {
+          ...params,
+          page_size: 100,
+          ...(pageToken ? { page_token: pageToken } : {}),
+        },
+      });
+      if (data.code !== 0) {
+        throw new Error(`Lark API ${path} failed: ${data.msg ?? 'unknown'} (${data.code})`);
+      }
+      const page = data.data ?? {};
+      if (Array.isArray(page.items)) {
+        for (const item of page.items) {
+          if (item !== null && typeof item === 'object') {
+            items.push(item as Record<string, unknown>);
+          }
+        }
+      }
+      pageToken = page.has_more === true && typeof page.page_token === 'string'
+        ? page.page_token
+        : '';
+    } while (pageToken);
+    return items;
+  }
+
   async #request(
     path: string,
     options: {
@@ -349,6 +474,7 @@ export class LarkEndpoint implements EndpointInstance {
         Authorization: `Bearer ${this.#accessToken.token}`,
       },
       body: body && method !== 'GET' ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
     });
     if (!response.ok) {
       const text = await response.text().catch(() => '');

package/src/index.ts

@@ -42,6 +42,13 @@ export {
   type LarkFetch,
 } from './endpoint.js';
 
+export {
+  buildImageUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type MediaBinary,
+} from './media-upload.js';
+
 export {
   registerLarkWebhookRoutes,
   handleLarkWebhookRequest,

package/src/lark-endpoint-commands.ts

@@ -0,0 +1,20 @@
+/**
+ * `lark endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { larkRuntimeStateToken } from './lark-runtime-state.js';
+
+export const larkEndpointCommands = createEndpointCommands({
+  adapterKey: 'lark',
+  adapterDisplayName: 'Lark',
+  fields: [
+    { key: 'appId', required: true, env: true, description: '飞书 App ID' },
+    { key: 'appSecret', required: true, env: true, description: '飞书 App Secret' },
+    { key: 'encryptKey', env: true, description: '事件加密 key' },
+    { key: 'verificationToken', env: true, description: '事件验证 token' },
+  ],
+  running: (use) => use(larkRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/src/lark-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * Lark 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `lark endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+
+export const larkRuntimeStateToken = defineEndpointRuntimeStateToken('lark');

package/src/media-upload.ts

@@ -0,0 +1,71 @@
+/**
+ * Lark 图片上传（im/v1 消息 image 段需要 image_key）。
+ * 接口：POST {apiBaseUrl}/im/v1/images（multipart：image_type=message + image）
+ * 与 im/v1/messages 同属 IM 接口域（同一 tenant_access_token），不引入额外授权域。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
+
+export interface MediaBinary {
+  readonly data: Buffer;
+  readonly mimeType: string;
+  readonly fileName: string;
+}
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/bmp': 'bmp',
+};
+
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(
+  media: MediaRef,
+  download: (url: string) => Promise<Buffer> = defaultDownload,
+): Promise<MediaBinary> {
+  const mimeType = media.mime_type ?? 'image/png';
+  const ext = MIME_EXT[mimeType] ?? 'png';
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('base64://')
+      ? media.value.slice('base64://'.length)
+      : media.value;
+    return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+  }
+  if (media.kind === 'path') {
+    const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+    return { data: await readFile(path), mimeType, fileName: basename(path) };
+  }
+  return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+
+async function defaultDownload(url: string): Promise<Buffer> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
+export function buildImageUploadForm(binary: MediaBinary): FormData {
+  // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+  const bytes = new Uint8Array(binary.data.byteLength);
+  bytes.set(binary.data);
+  const form = new FormData();
+  form.append('image_type', 'message');
+  form.append('image', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+  return form;
+}
+
+/**
+ * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
+  if (typeof data.image_key === 'string' && data.image_key) return undefined;
+  if (typeof data.file_key === 'string' && data.file_key) return undefined;
+  if (typeof data.key === 'string' && data.key) return undefined;
+  if (isMediaRef(data.media)) return data.media;
+  return mediaRefFromLegacyData(data);
+}

package/src/protocol.ts

@@ -41,6 +41,8 @@ export interface LarkMessage {
   readonly create_time?: string;
   readonly update_time?: string;
   readonly chat_id?: string;
+  /** 事件携带的会话类型（'p2p' | 'group'）；p2p 的 chat_id 也是 oc_ 开头。 */
+  readonly chat_type?: string;
   readonly sender?: {
     readonly sender_id?: {
       readonly user_id?: string;
@@ -145,7 +147,10 @@ export function normalizeWebhookPath(path: string): string {
   return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
 
-export function resolveChatType(chatId?: string): 'group' | 'private' {
+export function resolveChatType(chatId?: string, chatType?: string): 'group' | 'private' {
+  // 优先使用事件里的 chat_type：p2p 会话的 chat_id 同样以 oc_ 开头，不能靠前缀判断
+  if (chatType === 'group') return 'group';
+  if (chatType === 'p2p') return 'private';
   return chatId?.startsWith('oc_') ? 'group' : 'private';
 }
 
@@ -196,14 +201,23 @@ export function formatInboundContent(msg: LarkMessage): string {
   }
 }
 
+/** 验签时间戳时效窗口（防重放）。 */
+export const LARK_SIGNATURE_MAX_AGE_MS = 5 * 60_000;
+
 export function verifySignature(
   encryptKey: string,
   timestamp: string,
   nonce: string,
   body: string,
   signature: string,
+  nowMs: number = Date.now(),
 ): boolean {
   try {
+    // 时效窗口 ±5min，超出直接拒绝（timestamp 为秒）
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > LARK_SIGNATURE_MAX_AGE_MS) {
+      return false;
+    }
     const stringToSign = `${timestamp}${nonce}${encryptKey}${body}`;
     const calculated = createHash('sha256').update(stringToSign).digest('hex');
     const a = Buffer.from(calculated);
@@ -215,6 +229,18 @@ export function verifySignature(
   }
 }
 
+/** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
+export function verifyToken(token: string, expected: string): boolean {
+  try {
+    const a = Buffer.from(token);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
  * Segment canonicalization is intentionally not done here.
@@ -268,7 +294,8 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
           media = {
             msg_type: 'image',
             content: JSON.stringify({
-              image_key: data.file_key ?? data.key ?? data.url,
+              // image_key 由 endpoint 上传物化写入；file_key/key/url 为旧调用方兼容入口。
+              image_key: data.image_key ?? data.file_key ?? data.key ?? data.url,
             }),
           };
         }

package/src/webhook.ts

@@ -8,6 +8,7 @@ import {
   headerValue,
   readTextBody,
   verifySignature,
+  verifyToken,
   type LarkEventBody,
   type LarkMessage,
   type ResolvedLarkConfig,
@@ -43,7 +44,7 @@ export async function handleLarkWebhookRequest(
 
     if (handler.config.verificationToken) {
       const token = headerValue(request.headers, 'x-lark-request-token');
-      if (token !== handler.config.verificationToken) {
+      if (!verifyToken(token, handler.config.verificationToken)) {
         logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid verification token' }));
         response.writeHead(403, { 'Content-Type': 'text/plain' });
         response.end('Forbidden');