@m1heng-clawd/feishu 0.1.7 → 0.1.8

package/README.md

@@ -2,6 +2,8 @@
 
 Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
 
+> **中文社区资料** - 配置教程、常见问题、使用技巧：[Wiki](https://github.com/m1heng/clawdbot-feishu/wiki)
+
 [English](#english) | [中文](#中文)
 
 ---
@@ -113,7 +115,9 @@ The `feishu_bitable` tools support both URL formats:
 
 In the Feishu Open Platform console, go to **Events & Callbacks**:
 
-1. **Event configuration**: Select **Long connection** (recommended)
+1. **Event configuration**: Select the subscription mode matching your `connectionMode`:
+   - **Long connection** — for `connectionMode: "websocket"` (recommended, no public URL needed)
+   - **Request URL** — for `connectionMode: "webhook"` (requires a publicly accessible URL)
 2. **Add event subscriptions**:
 
 | Event | Description |
@@ -139,8 +143,8 @@ channels:
     enabled: true
     appId: "cli_xxxxx"
     appSecret: "secret"
-    # Domain: "feishu" (China) or "lark" (International)
-    domain: "feishu"
+    # Domain: "feishu" (China), "lark" (International), or custom URL
+    domain: "feishu"  # or "https://open.xxx.cn" for private deployment
     # Connection mode: "websocket" (recommended) or "webhook"
     connectionMode: "websocket"
     # DM policy: "pairing" | "open" | "allowlist"
@@ -155,6 +159,45 @@ channels:
     renderMode: "auto"
 ```
 
+#### Connection Mode
+
+Two connection modes are available for receiving events from Feishu:
+
+| Mode | Description |
+|------|-------------|
+| `websocket` | (Default, recommended) Long-polling WebSocket connection. No public URL required, works behind NAT/firewall. Best for local development and most deployments. |
+| `webhook` | HTTP server that receives event callbacks. Requires a publicly accessible URL. Suitable for server deployments behind a reverse proxy (e.g. Nginx). |
+
+**WebSocket mode** (default, no extra config needed):
+
+```yaml
+channels:
+  feishu:
+    connectionMode: "websocket"  # or just omit this line
+```
+
+In Feishu console: Events & Callbacks → select **Long connection**.
+
+**Webhook mode**:
+
+```yaml
+channels:
+  feishu:
+    connectionMode: "webhook"
+    webhookPort: 3000               # HTTP server port (default: 3000)
+    webhookPath: "/feishu/events"   # Event callback path (default: "/feishu/events")
+    encryptKey: "your_encrypt_key"           # From Feishu console → Events & Callbacks → Encrypt Key
+    verificationToken: "your_verify_token"   # From Feishu console → Events & Callbacks → Verification Token
+```
+
+In Feishu console: Events & Callbacks → select **Request URL** → set the URL to:
+
+```
+https://your-domain.com/feishu/events
+```
+
+> **Note:** The Request URL must be HTTPS and publicly accessible. For local development, you can use tools like [ngrok](https://ngrok.com) to create a tunnel: `ngrok http 3000`, then use the generated URL.
+
 #### Render Mode
 
 | Mode | Description |
@@ -163,6 +206,46 @@ channels:
 | `raw` | Always send replies as plain text. Markdown tables are converted to ASCII. |
 | `card` | Always send replies as interactive cards with full markdown rendering (syntax highlighting, tables, clickable links). |
 
+#### Dynamic Agent Creation (Multi-User Workspace Isolation)
+
+When enabled, each DM user automatically gets their own isolated agent instance with a dedicated workspace. This provides complete isolation including separate conversation history, memory (MEMORY.md), and workspace files.
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "open"
+    allowFrom: ["*"]
+    dynamicAgentCreation:
+      enabled: true
+      # Template for workspace directory ({userId} = OpenID, {agentId} = generated agent ID)
+      workspaceTemplate: "~/workspaces/feishu-{agentId}"
+      # Template for agent config directory
+      agentDirTemplate: "~/.openclaw/agents/{agentId}/agent"
+      # Optional: limit total number of dynamic agents
+      maxAgents: 100
+
+session:
+  # Also set dmScope for session isolation (conversation history)
+  dmScope: "per-peer"
+```
+
+| Option | Description |
+|--------|-------------|
+| `enabled` | Enable dynamic agent creation for DM users |
+| `workspaceTemplate` | Template for workspace path. Supports `{userId}` (OpenID) and `{agentId}` (= `feishu-{openId}`) |
+| `agentDirTemplate` | Template for agent directory path |
+| `maxAgents` | Optional limit on number of dynamic agents |
+
+**How it works:**
+1. When a new user sends a DM, the system creates a new agent entry in `openclaw.json`
+2. A binding is created to route that user's DM to their dedicated agent
+3. Workspace and agent directories are created automatically
+4. Subsequent messages from that user go to their isolated agent
+
+**Difference from `dmScope: "per-peer"`:**
+- `dmScope: "per-peer"` only isolates conversation history
+- `dynamicAgentCreation` provides full isolation (workspace, memory, identity, tools)
+
 ### Features
 
 - WebSocket and Webhook connection modes
@@ -180,6 +263,7 @@ channels:
 - **Bitable tools**: Read/write bitable (多维表格) records, supports both `/base/` and `/wiki/` URLs
 - **@mention forwarding**: When you @mention someone in your message, the bot's reply will automatically @mention them too
 - **Permission error notification**: When the bot encounters a Feishu API permission error, it automatically notifies the user with the permission grant URL
+- **Dynamic agent creation**: Each DM user can have their own isolated agent instance with dedicated workspace (optional)
 
 #### @Mention Forwarding
 
@@ -196,9 +280,12 @@ The bot automatically detects @mentions in your message and includes them in its
 
 Check the following:
 1. Have you configured **event subscriptions**? (See Event Subscriptions section)
-2. Is the event configuration set to **long connection**?
+2. Does the event subscription mode match your `connectionMode`?
+   - `websocket` → **Long connection** in Feishu console
+   - `webhook` → **Request URL** in Feishu console (URL must be reachable)
 3. Did you add the `im.message.receive_v1` event?
 4. Are the permissions approved?
+5. For webhook mode: is your server running and the URL publicly accessible?
 
 #### 403 error when sending messages
 
@@ -339,7 +426,9 @@ openclaw plugins update feishu
 
 在飞书开放平台的应用后台，进入 **事件与回调** 页面：
 
-1. **事件配置方式**：选择 **使用长连接接收事件**（推荐）
+1. **事件配置方式**：根据你的 `connectionMode` 选择对应的订阅方式：
+   - **使用长连接接收事件** — 对应 `connectionMode: "websocket"`（推荐，无需公网地址）
+   - **使用请求地址接收事件** — 对应 `connectionMode: "webhook"`（需要公网可访问的 URL）
 2. **添加事件订阅**，勾选以下事件：
 
 | 事件 | 说明 |
@@ -365,8 +454,8 @@ channels:
     enabled: true
     appId: "cli_xxxxx"
     appSecret: "secret"
-    # 域名: "feishu" (国内) 或 "lark" (国际)
-    domain: "feishu"
+    # 域名: "feishu" (国内)、"lark" (国际) 或自定义 URL
+    domain: "feishu"  # 私有化部署可用 "https://open.xxx.cn"
     # 连接模式: "websocket" (推荐) 或 "webhook"
     connectionMode: "websocket"
     # 私聊策略: "pairing" | "open" | "allowlist"
@@ -381,6 +470,45 @@ channels:
     renderMode: "auto"
 ```
 
+#### 连接模式
+
+支持两种从飞书接收事件的连接模式：
+
+| 模式 | 说明 |
+|------|------|
+| `websocket` | （默认，推荐）长连接 WebSocket 模式。无需公网地址，可在 NAT/防火墙后使用。适合本地开发和大部分部署场景。 |
+| `webhook` | HTTP 服务器接收事件回调。需要公网可访问的 URL。适合通过反向代理（如 Nginx）部署的服务器环境。 |
+
+**WebSocket 模式**（默认，无需额外配置）：
+
+```yaml
+channels:
+  feishu:
+    connectionMode: "websocket"  # 或直接省略此行
+```
+
+飞书控制台：事件与回调 → 选择 **使用长连接接收事件**。
+
+**Webhook 模式**：
+
+```yaml
+channels:
+  feishu:
+    connectionMode: "webhook"
+    webhookPort: 3000               # HTTP 服务端口（默认: 3000）
+    webhookPath: "/feishu/events"   # 事件回调路径（默认: "/feishu/events"）
+    encryptKey: "your_encrypt_key"           # 飞书控制台 → 事件与回调 → Encrypt Key
+    verificationToken: "your_verify_token"   # 飞书控制台 → 事件与回调 → Verification Token
+```
+
+飞书控制台：事件与回调 → 选择 **使用请求地址接收事件** → 填入请求地址：
+
+```
+https://your-domain.com/feishu/events
+```
+
+> **提示：** 请求地址必须是 HTTPS 且公网可访问。本地开发时，可使用 [ngrok](https://ngrok.com) 等工具创建隧道：`ngrok http 3000`，然后使用生成的地址。
+
 #### 渲染模式
 
 | 模式 | 说明 |
@@ -389,6 +517,46 @@ channels:
 | `raw` | 始终纯文本，表格转为 ASCII |
 | `card` | 始终使用卡片，支持语法高亮、表格、链接等 |
 
+#### 动态 Agent 创建（多用户 Workspace 隔离）
+
+启用后，每个私聊用户会自动获得独立的 agent 实例和专属 workspace。这提供完整的隔离，包括独立的对话历史、记忆（MEMORY.md）和工作区文件。
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "open"
+    allowFrom: ["*"]
+    dynamicAgentCreation:
+      enabled: true
+      # workspace 目录模板 ({userId} = OpenID, {agentId} = 生成的 agent ID)
+      workspaceTemplate: "~/workspaces/feishu-{agentId}"
+      # agent 配置目录模板
+      agentDirTemplate: "~/.openclaw/agents/{agentId}/agent"
+      # 可选：限制动态 agent 总数
+      maxAgents: 100
+
+session:
+  # 同时设置 dmScope 以隔离对话历史
+  dmScope: "per-peer"
+```
+
+| 选项 | 说明 |
+|------|------|
+| `enabled` | 是否为私聊用户启用动态 agent 创建 |
+| `workspaceTemplate` | workspace 路径模板，支持 `{userId}`（OpenID）和 `{agentId}`（= `feishu-{openId}`）|
+| `agentDirTemplate` | agent 目录路径模板 |
+| `maxAgents` | 可选，限制动态 agent 的最大数量 |
+
+**工作原理：**
+1. 当新用户发送私聊时，系统在 `openclaw.json` 中创建新的 agent 条目
+2. 创建 binding 将该用户的私聊路由到专属 agent
+3. 自动创建 workspace 和 agent 目录
+4. 该用户后续的消息都会路由到其隔离的 agent
+
+**与 `dmScope: "per-peer"` 的区别：**
+- `dmScope: "per-peer"` 仅隔离对话历史
+- `dynamicAgentCreation` 提供完整隔离（workspace、记忆、身份、工具）
+
 ### 功能
 
 - WebSocket 和 Webhook 连接模式
@@ -406,6 +574,7 @@ channels:
 - **多维表格工具**：读写多维表格记录，支持 `/base/` 和 `/wiki/` 两种链接格式
 - **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
 - **权限错误提示**：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
+- **动态 Agent 创建**：每个私聊用户可拥有独立的 agent 实例和专属 workspace（可选）
 
 #### @ 转发功能
 
@@ -422,9 +591,12 @@ channels:
 
 检查以下配置：
 1. 是否配置了 **事件订阅**？（见上方事件订阅章节）
-2. 事件配置方式是否选择了 **长连接**？
+2. 事件订阅方式是否与 `connectionMode` 匹配？
+   - `websocket` → 飞书控制台选择 **使用长连接接收事件**
+   - `webhook` → 飞书控制台选择 **使用请求地址接收事件**（URL 必须可访问）
 3. 是否添加了 `im.message.receive_v1` 事件？
 4. 相关权限是否已申请并审核通过？
+5. 如果使用 webhook 模式：服务是否正在运行？URL 是否公网可访问？
 
 #### 返回消息时 403 错误
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",
@@ -46,7 +46,7 @@
     }
   },
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.30.0",
+    "@larksuiteoapi/node-sdk": "^1.56.1",
     "@sinclair/typebox": "^0.34.48",
     "zod": "^4.3.6"
   },

package/src/accounts.ts

@@ -1,7 +1,79 @@
 import type { ClawdbotConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
-import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+import type { FeishuConfig, FeishuAccountConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
 
+/**
+ * List all configured account IDs from the accounts field.
+ */
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = (cfg.channels?.feishu as FeishuConfig)?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return [];
+  }
+  return Object.keys(accounts).filter(Boolean);
+}
+
+/**
+ * List all Feishu account IDs.
+ * If no accounts are configured, returns [DEFAULT_ACCOUNT_ID] for backward compatibility.
+ */
+export function listFeishuAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) {
+    // Backward compatibility: no accounts configured, use default
+    return [DEFAULT_ACCOUNT_ID];
+  }
+  return [...ids].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Resolve the default account ID.
+ */
+export function resolveDefaultFeishuAccountId(cfg: ClawdbotConfig): string {
+  const ids = listFeishuAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * Get the raw account-specific config.
+ */
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): FeishuAccountConfig | undefined {
+  const accounts = (cfg.channels?.feishu as FeishuConfig)?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return undefined;
+  }
+  return accounts[accountId];
+}
+
+/**
+ * Merge top-level config with account-specific config.
+ * Account-specific fields override top-level fields.
+ */
+function mergeFeishuAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): FeishuConfig {
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+
+  // Extract base config (exclude accounts field to avoid recursion)
+  const { accounts: _ignored, ...base } = feishuCfg ?? {};
+
+  // Get account-specific overrides
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+
+  // Merge: account config overrides base config
+  return { ...base, ...account } as FeishuConfig;
+}
+
+/**
+ * Resolve Feishu credentials from a config.
+ */
 export function resolveFeishuCredentials(cfg?: FeishuConfig): {
   appId: string;
   appSecret: string;
@@ -21,31 +93,46 @@ export function resolveFeishuCredentials(cfg?: FeishuConfig): {
   };
 }
 
+/**
+ * Resolve a complete Feishu account with merged config.
+ */
 export function resolveFeishuAccount(params: {
   cfg: ClawdbotConfig;
   accountId?: string | null;
 }): ResolvedFeishuAccount {
+  const accountId = normalizeAccountId(params.accountId);
   const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
-  const enabled = feishuCfg?.enabled !== false;
-  const creds = resolveFeishuCredentials(feishuCfg);
+
+  // Base enabled state (top-level)
+  const baseEnabled = feishuCfg?.enabled !== false;
+
+  // Merge configs
+  const merged = mergeFeishuAccountConfig(params.cfg, accountId);
+
+  // Account-level enabled state
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+
+  // Resolve credentials from merged config
+  const creds = resolveFeishuCredentials(merged);
 
   return {
-    accountId: params.accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    accountId,
     enabled,
     configured: Boolean(creds),
+    name: (merged as FeishuAccountConfig).name?.trim() || undefined,
     appId: creds?.appId,
+    appSecret: creds?.appSecret,
+    encryptKey: creds?.encryptKey,
+    verificationToken: creds?.verificationToken,
     domain: creds?.domain ?? "feishu",
+    config: merged,
   };
 }
 
-export function listFeishuAccountIds(_cfg: ClawdbotConfig): string[] {
-  return [DEFAULT_ACCOUNT_ID];
-}
-
-export function resolveDefaultFeishuAccountId(_cfg: ClawdbotConfig): string {
-  return DEFAULT_ACCOUNT_ID;
-}
-
+/**
+ * List all enabled and configured accounts.
+ */
 export function listEnabledFeishuAccounts(cfg: ClawdbotConfig): ResolvedFeishuAccount[] {
   return listFeishuAccountIds(cfg)
     .map((accountId) => resolveFeishuAccount({ cfg, accountId }))