@zhin.js/adapter-lark 1.0.97 → 1.1.0

package/README.md

@@ -1,15 +1,15 @@
 # @zhin.js/adapter-lark
 
-Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管理。
+Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
-## 功能特性
+## 功能
 
-- 支持飞书和 Lark 国际版
-- Webhook 事件接收（HTTP 回调）
-- Bearer Token 自动刷新
-- 消息加密和签名验证（可选）
-- URL 验证自动处理
-- 群管理 AI 工具（通过包内 `skills/lark/SKILL.md` 与 `addTool` 暴露给 AI）
+- Webhook 事件接收（`httpHostToken` POST + 可选 verificationToken / encryptKey 签名）
+- URL 验证挑战（`url_verification`）
+- Tenant Access Token 自动刷新
+- 支持飞书与 Lark 国际版 API 基址
+- canonical `markdown` 段编码为 `interactive` 卡片中的 `lark_md`
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -17,99 +17,86 @@ Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管
 pnpm add @zhin.js/adapter-lark
 ```
 
-## 依赖
+## Plugin Runtime
 
-- `@zhin.js/host-router` — HTTP 服务（提供 Webhook 路由）
+- `@zhin.js/adapter` — 约定式 `adapters/lark.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-## 配置
+入站：`gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → `im/v1/messages`
 
-```yaml
-# zhin.config.yml
-bots:
-  - context: lark
-    name: my-lark-bot
-    appId: cli_xxxxxxxxxxxx
-    appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
-    webhookPath: /lark/webhook
-    # 可选配置
-    # encryptKey: your-encrypt-key
-    # verificationToken: your-token
-    # isFeishu: true          # 使用飞书 API（默认）
-    # apiBaseUrl: https://open.feishu.cn/open-apis   # 自定义 API 地址
-
-plugins:
-  - "@zhin.js/adapter-lark"
-  - "@zhin.js/host-router"
-```
-
-或使用 TypeScript 配置：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  bots: [
-    {
-      context: 'lark',
-      name: 'my-lark-bot',
-      appId: process.env.LARK_APP_ID!,
-      appSecret: process.env.LARK_APP_SECRET!,
-      webhookPath: '/lark/webhook',
-    }
-  ],
-  plugins: ['@zhin.js/adapter-lark', '@zhin.js/host-router']
-})
-```
+入站 `metadata.mentioned`：**未接线**。消息事件的 `mentions[]` 元素含 `id.open_id`，但本适配器拿不到 bot 自身的 open_id——配置（`appId` / `appSecret` / `name` 等）不含 bot open_id，代码也未调用 `bot/v3/info` 获取应用信息，故无可靠判据比对 mentions。
 
-## 使用示例
+## 前置条件
 
-### 注册命令
+1. 在 [飞书开放平台](https://open.feishu.cn/)（或 Lark）创建企业自建应用
+2. 获取 **App ID**、**App Secret**
+3. 启用机器人能力并配置事件订阅 URL：`https://your-domain/lark/webhook`
+4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+必填字段（`endpoints[i]`）：`name`、`appId`、`appSecret`。
 
-const { addCommand } = usePlugin()
+## 最小配置
 
-addCommand(
-  new MessageCommand('hello')
-    .desc('飞书问候')
-    .action((message) => {
-      return `你好，${message.$sender.name}！`
-    })
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  lark:
+    webhookPath: /lark/webhook          # 可选，默认 /lark/webhook
+    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`）。
 
-```typescript
-import { usePlugin } from 'zhin.js'
+## 环境变量
 
-const { addMiddleware } = usePlugin()
+| 变量 | 说明 |
+|------|------|
+| `LARK_APP_ID` | 应用 App ID |
+| `LARK_APP_SECRET` | 应用 App Secret |
+| `LARK_BOT_NAME` | 默认 endpoint 名称（可选） |
 
-addMiddleware(async (message, next) => {
-  if (message.$adapter === 'lark') {
-    console.log('收到飞书消息:', message.$content)
-  }
-  await next()
-})
-```
+## 消息类型映射
 
-## AI 工具（Skill）
+| 飞书类型 | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | text |
+| markdown | 原文 | interactive（`lark_md`） |
+| image | `[image]` | image（需 `file_key`） |
+| file | `[file: name]` | file |
+| audio / video / sticker | `[audio]` / `[video]` / `[sticker]` | — |
+| card | — | interactive |
 
-适配器内置群管理 Skill，自动注册以下工具供 AI 调用：
+## Agent 工具
 
-- 群聊管理（成员管理、群信息修改等）
+`agent/` 目录保留（get_user、群聊、管理员、上传文件等）。工具声明 `adapter: 'lark'` 后，通过惰性的 `context.$client` 自动取得当前操作的 `LarkClient`；无需把 Endpoint id 暴露给模型。
 
-> 工具使用飞书的 `open_id` 和 `chat_id` 格式标识用户和群聊。
+## 平台权限（platform permit）
 
-## 飞书开发者配置
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
 
-1. 登录 [飞书开放平台](https://open.feishu.cn/)
-2. 创建应用并获取 `App ID` 和 `App Secret`
-3. 配置事件回调 URL：`http://your-server:8086/api/lark/webhook`
-4. 订阅 `im.message.receive_v1` 事件
-5. 发布应用
+## 测试
+
+```bash
+pnpm --filter @zhin.js/adapter-lark build
+pnpm --filter @zhin.js/adapter-lark test
+```
 
-## 许可证
+## 故障排查
 
-MIT License
+| 现象 | 排查 |
+| --- | --- |
+| URL 验证失败 | 检查公网 HTTPS、`webhookPath`、verification token 与 encrypt key |
+| Tenant Token 获取失败 | 检查 `appId`、`appSecret` 与应用版本是否已发布 |
+| 群里 @机器人不触发 AI | 当前无法可靠判定 bot open_id；使用显式 AI 前缀 |
+| 能收不能发 | 检查机器人消息权限、可见范围与应用是否已加入群聊 |

package/adapters/lark.js

@@ -0,0 +1,36 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/lark.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LarkEndpoint } from "../lib/endpoint.js";
+import { resolveLarkConfig, } from "../lib/protocol.js";
+import { larkRuntimeStateToken } from "../lib/lark-runtime-state.js";
+export { LarkEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+    // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+    // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
+    // 卡片交互未接入出站通道，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'upload'],
+        interactive: 'text',
+        markdown: 'native',
+    },
+    create(context) {
+        const config = resolveLarkConfig(context.config);
+        // 注册到插件运行时状态（lark.endpoint list 的"运行中"数据源）
+        context.use(larkRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: 'webhook',
+        });
+        return new LarkEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/lark.ts

@@ -0,0 +1,41 @@
+/**
+ * Convention entry: discover `adapters/lark.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LarkEndpoint } from '../src/endpoint.js';
+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'],
+  operations: ['recall'],
+  // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+  // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+  // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
+  // 卡片交互未接入出站通道，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'text',
+    markdown: 'native',
+  },
+  create(context) {
+    const config = resolveLarkConfig(context.config);
+    // 注册到插件运行时状态（lark.endpoint list 的"运行中"数据源）
+    context.use(larkRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new LarkEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/agent/PERMITS.md

@@ -0,0 +1,22 @@
+# 飞书 Lark Platform Permits
+
+## 入站字段
+
+群聊消息经 `getChatInfo`（TTL 60s）比对 `owner_id` / `user_manager_id_list`：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `owner` · `admin` · `member` |
+| `$sender.permissions` | `chat_owner` · `chat_admin` · `manage_managers` |
+
+## Permit 词汇表
+
+| `platform(lark,…)` | 含义 |
+|--------------------|------|
+| `chat_owner` | 群主 |
+| `chat_admin` | 群管理员 |
+| `manage_managers` | 可设/撤管理员 |
+
+## 工厂映射
+
+`scene_admin` → `chat_admin` · `scene_owner` → `chat_owner`

package/agent/tools/add_members.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '添加飞书群成员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermit('chat_admin')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.addChatMembers(chat_id, user_ids.split(','));
+    return { success, message: success ? '成员添加成功' : '添加失败' };
+  },
+});
+

package/agent/tools/create_chat.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ name: string; members: string; owner?: string }>({
+  description: '创建飞书群聊',
+  inputSchema: z.object({
+    name: z.string().describe('群名'),
+    members: z.string().describe('成员 open_id 列表，逗号分隔'),
+    owner: z.string().optional().describe('群主 open_id（可选）'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ name, members, owner   }: { name: string; members: string; owner?: string }, context) {
+    const endpoint = context.$client;
+    const chatId = await endpoint.createChat(name, members.split(','), owner);
+    return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
+  },
+});
+

package/agent/tools/dissolve_chat.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ chat_id: string }>({
+  description: '解散飞书群聊（需要群主权限）',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ chat_id   }: { chat_id: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.dissolveChat(chat_id);
+    return { success, message: success ? '群聊已解散' : '解散失败' };
+  },
+});
+

package/agent/tools/get_user.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ user_id: string }>({
+  description: '获取飞书用户信息',
+  inputSchema: z.object({
+    user_id: z.string().describe('用户 ID (open_id)'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ user_id   }: { user_id: string }, context) {
+    const endpoint = context.$client;
+    return await endpoint.getUserInfo(user_id);
+  },
+});
+

package/agent/tools/remove_managers.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '移除飞书群管理员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermit('manage_managers')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.removeChatManagers(chat_id, user_ids.split(','));
+    return { success, message: success ? '管理员移除成功' : '移除失败' };
+  },
+});
+

package/agent/tools/set_managers.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '设置飞书群管理员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermit('manage_managers')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.setChatManagers(chat_id, user_ids.split(','));
+    return { success, message: success ? '管理员设置成功' : '设置失败' };
+  },
+});
+

package/agent/tools/update_chat.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ chat_id: string; name?: string; description?: string }>({
+  description: '更新飞书群聊信息（群名、描述）',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    name: z.string().optional().describe('新群名（可选）'),
+    description: z.string().optional().describe('新描述（可选）'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermit('chat_admin')],
+  async execute({ chat_id, name, description   }: { chat_id: string; name?: string; description?: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.updateChatInfo(chat_id, { name, description });
+    return { success, message: success ? '群信息更新成功' : '更新失败' };
+  },
+});
+

package/agent/tools/upload_file.ts

@@ -0,0 +1,23 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{
+  file_path: string;
+  file_type: 'image' | 'file' | 'video' | 'audio';
+}>({
+  description: '上传文件到飞书（image/file/video/audio）',
+  inputSchema: z.object({
+    file_path: z.string().describe('本地文件路径'),
+    file_type: z.enum(['image', 'file', 'video', 'audio']).default('file').describe('飞书文件类型'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ file_path, file_type }: {
+    file_path: string;
+    file_type: 'image' | 'file' | 'video' | 'audio';
+  }, context) {
+    const endpoint = context.$client;
+    const result = await endpoint.uploadFile(file_path, file_type);
+    return { success: true, file_key: result, message: `文件已上传，file_key: ${result}` };
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { larkEndpointCommands } from "../../../lib/lark-endpoint-commands.js";
+export default larkEndpointCommands.add;

package/commands/endpoint/add/[id].ts

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

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { larkEndpointCommands } from "../../lib/lark-endpoint-commands.js";
+export default larkEndpointCommands.list;

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/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { larkEndpointCommands } from "../../../lib/lark-endpoint-commands.js";
+export default larkEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

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

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { LarkClient } from './endpoint.js';
+import type { LarkEventBody } from './protocol.js';
+export type LarkClientEventMap = Record<string, LarkEventBody>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly lark: {
+            readonly client: LarkClient;
+            readonly events: LarkClientEventMap;
+        };
+    }
+}
+export declare const larkClient: import("@zhin.js/adapter").EndpointClientToken<LarkClient, LarkClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const larkClient = defineEndpointClient('lark');

package/lib/endpoint.d.ts

@@ -0,0 +1,100 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+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;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface LarkEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedLarkConfig;
+    readonly fetch?: LarkFetch;
+}
+export interface LarkClientApi {
+    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+    updateChatInfo(chatId: string, options: {
+        name?: string;
+        description?: string;
+    }): Promise<boolean>;
+    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    getChatMembers(chatId: string): Promise<unknown[]>;
+    dissolveChat(chatId: string): Promise<boolean>;
+    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}
+/** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
+export declare class LarkClient implements LarkClientApi {
+    readonly api: LarkClientApi;
+    constructor(api: LarkClientApi);
+    getUserInfo: (id: string, type?: "open_id" | "user_id" | "union_id") => Promise<unknown>;
+    getChatInfo: (id: string) => Promise<unknown>;
+    uploadFile: (path: string, type?: "image" | "file" | "video" | "audio") => Promise<string | null>;
+    createChat: (name: string, users: string[], owner?: string) => Promise<string | null>;
+    updateChatInfo: (id: string, options: {
+        name?: string;
+        description?: string;
+    }) => Promise<boolean>;
+    addChatMembers: (id: string, users: string[]) => Promise<boolean>;
+    removeChatMembers: (id: string, users: string[]) => Promise<boolean>;
+    getChatMembers: (id: string) => Promise<unknown[]>;
+    dissolveChat: (id: string) => Promise<boolean>;
+    setChatManagers: (id: string, users: string[]) => Promise<boolean>;
+    removeChatManagers: (id: string, users: string[]) => Promise<boolean>;
+}
+export declare class LarkEndpoint extends Endpoint<LarkClient> {
+    #private;
+    readonly client: LarkClient;
+    /**
+     * 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;
+    readonly control: EndpointControl;
+    constructor(options: LarkEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedLarkConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+    /** 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;
+    admitPlatform(name: string, event: unknown): void;
+    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+    updateChatInfo(chatId: string, options: {
+        name?: string;
+        description?: string;
+    }): Promise<boolean>;
+    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    getChatMembers(chatId: string): Promise<unknown[]>;
+    dissolveChat(chatId: string): Promise<boolean>;
+    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}