@m1heng-clawd/feishu 0.1.9 → 0.1.11

package/README.md

@@ -3,6 +3,8 @@
 Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
 
 > **中文社区资料** - 配置教程、常见问题、使用技巧：[Wiki](https://github.com/m1heng/clawdbot-feishu/wiki)
+>
+> **Contributing / 贡献指南**: [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 [English](#english) | [中文](#中文)
 
@@ -16,6 +18,19 @@ Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/o
 openclaw plugins install @m1heng-clawd/feishu
 ```
 
+> [!IMPORTANT]
+> **Windows Troubleshooting (`spawn npm ENOENT`)**
+>
+> If `openclaw plugins install` fails, install manually:
+>
+> ```bash
+> # 1. Download the package
+> curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
+>
+> # 2. Install from local file
+> openclaw plugins install ./feishu-0.1.3.tgz
+> ```
+
 ### Upgrade
 
 ```bash
@@ -61,16 +76,20 @@ openclaw plugins update feishu
 | `drive:drive:readonly` | `feishu_drive` | List folders, get file info |
 | `wiki:wiki:readonly` | `feishu_wiki` | List spaces, list nodes, get node info, search |
 | `bitable:app:readonly` | `feishu_bitable` | Read bitable records and fields |
+| `task:task:read` | `feishu_task_get` | Get task details |
 
 **Read-write** (optional, for create/edit/delete operations):
 
 | Permission | Tool | Description |
 |------------|------|-------------|
 | `docx:document` | `feishu_doc` | Create/edit documents |
-| `docx:document.block:convert` | `feishu_doc` | Markdown to blocks conversion (required for write/append) |
+| `docx:document.block:convert` | `feishu_doc` | Markdown to blocks conversion (required for write/append/create_and_write; also used by `feishu_drive.import_document`) |
 | `drive:drive` | `feishu_doc`, `feishu_drive` | Upload images to documents, create folders, move/delete files |
 | `wiki:wiki` | `feishu_wiki` | Create/move/rename wiki nodes |
-| `bitable:app` | `feishu_bitable` | Create/update bitable records |
+| `bitable:app` | `feishu_bitable` | Create/update/delete bitable records and manage fields |
+| `task:task:write` | `feishu_task_create`, `feishu_task_update`, `feishu_task_delete` | Create/update/delete tasks |
+
+> Task scope names may vary slightly in Feishu console UI. If needed, search for Task-related permissions and grant read/write accordingly.
 
 #### Drive Access ⚠️
 
@@ -149,6 +168,8 @@ channels:
     connectionMode: "websocket"
     # DM policy: "pairing" | "open" | "allowlist"
     dmPolicy: "pairing"
+    # DM allowlist (open_id/user_id). Include "*" when dmPolicy="open"
+    allowFrom: []
     # Group policy: "open" | "allowlist" | "disabled"
     groupPolicy: "allowlist"
     # Require @mention in groups
@@ -159,6 +180,81 @@ channels:
     renderMode: "auto"
 ```
 
+#### DM Policy & Access Control
+
+`dmPolicy` controls who can interact with the bot in direct messages (DM).  
+In multi-account mode, this is resolved per account (`channels.feishu.accounts.<accountId>`).
+
+| `dmPolicy` | Who can send DM | How to grant access to a user |
+|------------|------------------|--------------------------------|
+| `pairing` | Users in `allowFrom`, or users approved through pairing | User sends a DM and gets a pairing code; bot owner runs `openclaw pairing approve feishu <code>`. |
+| `open` | Everyone | Set `allowFrom: ["*"]` so all users are treated as allowed. |
+| `allowlist` | Only users in `allowFrom` | Add the user's `open_id`/`user_id` to `allowFrom`, then reload config. |
+
+Notes:
+- `allowFrom` accepts Feishu user IDs (`open_id` recommended, `user_id` also supported).
+- If `dmPolicy: "open"`, use `allowFrom: ["*"]`. This is required by top-level schema validation and keeps access behavior explicit.
+- `pairing` and `allowlist` can both pre-authorize users with `allowFrom`.
+
+Pairing flow (owner approval):
+1. User sends any DM to the bot.
+2. Bot replies with a pairing code (for example `H9ZEHY8R`).
+3. Bot owner approves:
+
+```bash
+openclaw pairing approve feishu H9ZEHY8R
+```
+
+4. The user is added to the allow store and can chat immediately.
+
+Example: open to everyone
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "open"
+    allowFrom: ["*"]
+```
+
+Example: controlled rollout (pairing + pre-approved users)
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "pairing"
+    allowFrom:
+      - "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+Example: strict allowlist
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "allowlist"
+    allowFrom:
+      - "ou_alice"
+      - "ou_bob"
+```
+
+Example: account-level isolation
+
+```yaml
+channels:
+  feishu:
+    accounts:
+      lobster-1:
+        dmPolicy: "open"
+        allowFrom: ["*"]
+      lobster-5:
+        dmPolicy: "pairing"
+```
+
+Top-level `channels.feishu.dmPolicy` / `channels.feishu.allowFrom` are fallback defaults for accounts that do not override them.
+
+> `dmPolicy` only controls who can trigger the bot.  
+> To actually read/write docs or files, you still need: (1) correct Feishu app scopes, and (2) sharing the target resources (Drive/Wiki/Bitable) with the bot.
+
 #### Connection Mode
 
 Two connection modes are available for receiving events from Feishu:
@@ -257,10 +353,11 @@ session:
 - Pairing flow for DM approval
 - User and group directory lookup
 - **Card render mode**: Optional markdown rendering with syntax highlighting
-- **Document tools**: Read, create, and write Feishu documents with markdown (tables not supported due to API limitations)
+- **Document tools**: Read, create, and write Feishu documents with markdown, including atomic `create_and_write` / `import_document` flows for reliable create+content write
 - **Wiki tools**: Navigate knowledge bases, list spaces, get node details, search, create/move/rename nodes
 - **Drive tools**: List folders, get file info, create folders, move/delete files
-- **Bitable tools**: Read/write bitable (多维表格) records, supports both `/base/` and `/wiki/` URLs
+- **Bitable tools**: Manage bitable (多维表格) fields and records (read/create/update/delete), supports both `/base/` and `/wiki/` URLs
+- **Task tools**: Create, get details, update, and delete tasks via Feishu Task v2 API
 - **@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)
@@ -299,18 +396,6 @@ Send `/new` command in the chat.
 
 Feishu API has rate limits. Streaming updates can easily trigger throttling. We use complete-then-send approach for stability.
 
-#### Windows install error `spawn npm ENOENT`
-
-If `openclaw plugins install` fails, install manually:
-
-```bash
-# 1. Download the package
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
-
-# 2. Install from local file
-openclaw plugins install ./feishu-0.1.3.tgz
-```
-
 #### Cannot find the bot in Feishu
 
 1. Ensure the app is published (at least to test version)
@@ -327,6 +412,19 @@ openclaw plugins install ./feishu-0.1.3.tgz
 openclaw plugins install @m1heng-clawd/feishu
 ```
 
+> [!IMPORTANT]
+> **Windows 排错（`spawn npm ENOENT`）**
+>
+> 如果 `openclaw plugins install` 失败，可以手动安装：
+>
+> ```bash
+> # 1. 下载插件包
+> curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
+>
+> # 2. 从本地安装
+> openclaw plugins install ./feishu-0.1.3.tgz
+> ```
+
 ### 升级
 
 ```bash
@@ -372,16 +470,20 @@ openclaw plugins update feishu
 | `drive:drive:readonly` | `feishu_drive` | 列出文件夹、获取文件信息 |
 | `wiki:wiki:readonly` | `feishu_wiki` | 列出空间、列出节点、获取节点详情、搜索 |
 | `bitable:app:readonly` | `feishu_bitable` | 读取多维表格记录和字段 |
+| `task:task:read` | `feishu_task_get` | 获取任务详情 |
 
 **读写权限**（可选，用于创建/编辑/删除操作）：
 
 | 权限 | 工具 | 说明 |
 |------|------|------|
 | `docx:document` | `feishu_doc` | 创建/编辑文档 |
-| `docx:document.block:convert` | `feishu_doc` | Markdown 转 blocks（write/append 必需） |
+| `docx:document.block:convert` | `feishu_doc` | Markdown 转 blocks（write/append/create_and_write 必需，`feishu_drive.import_document` 也会用到） |
 | `drive:drive` | `feishu_doc`, `feishu_drive` | 上传图片到文档、创建文件夹、移动/删除文件 |
 | `wiki:wiki` | `feishu_wiki` | 创建/移动/重命名知识库节点 |
-| `bitable:app` | `feishu_bitable` | 创建/更新多维表格记录 |
+| `bitable:app` | `feishu_bitable` | 创建/更新/删除多维表格记录并管理字段 |
+| `task:task:write` | `feishu_task_create`, `feishu_task_update`, `feishu_task_delete` | 创建/更新/删除任务 |
+
+> 飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 `task` 搜索并授予对应读写权限。
 
 #### 云空间访问权限 ⚠️
 
@@ -460,6 +562,8 @@ channels:
     connectionMode: "websocket"
     # 私聊策略: "pairing" | "open" | "allowlist"
     dmPolicy: "pairing"
+    # 私聊白名单（open_id/user_id）；当 dmPolicy="open" 时请包含 "*"
+    allowFrom: []
     # 群聊策略: "open" | "allowlist" | "disabled"
     groupPolicy: "allowlist"
     # 群聊是否需要 @机器人
@@ -470,6 +574,81 @@ channels:
     renderMode: "auto"
 ```
 
+#### 私聊策略（dmPolicy）与访问授权
+
+`dmPolicy` 控制的是“谁可以在私聊里触发机器人”。  
+在多账号模式下，它按账号生效（`channels.feishu.accounts.<accountId>`）。
+
+| `dmPolicy` | 谁能私聊触发机器人 | 如何给用户开通 |
+|------------|------------------|----------------|
+| `pairing` | `allowFrom` 中的用户，或已通过配对审批的用户 | 用户先私聊机器人拿到配对码；管理员执行 `openclaw pairing approve feishu <code>`。 |
+| `open` | 所有人 | 配置 `allowFrom: ["*"]`，表示全部放开。 |
+| `allowlist` | 仅 `allowFrom` 中的用户 | 将用户 `open_id`/`user_id` 加入 `allowFrom`，然后重载配置。 |
+
+说明：
+- `allowFrom` 支持飞书用户 ID（推荐 `open_id`，也支持 `user_id`）。
+- 当 `dmPolicy: "open"` 时，建议固定写 `allowFrom: ["*"]`，语义最清晰，也满足顶层配置校验要求。
+- `pairing` 和 `allowlist` 都可以先通过 `allowFrom` 预授权部分用户。
+
+配对审批流程（pairing）：
+1. 用户先给机器人发一条私聊消息。
+2. 机器人返回配对码（例如 `H9ZEHY8R`）。
+3. 管理员执行审批命令：
+
+```bash
+openclaw pairing approve feishu H9ZEHY8R
+```
+
+4. 审批后该用户立即可用。
+
+示例：全部放开
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "open"
+    allowFrom: ["*"]
+```
+
+示例：灰度放开（pairing + 预授权）
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "pairing"
+    allowFrom:
+      - "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+示例：严格白名单
+
+```yaml
+channels:
+  feishu:
+    dmPolicy: "allowlist"
+    allowFrom:
+      - "ou_alice"
+      - "ou_bob"
+```
+
+示例：按账号隔离配置
+
+```yaml
+channels:
+  feishu:
+    accounts:
+      lobster-1:
+        dmPolicy: "open"
+        allowFrom: ["*"]
+      lobster-5:
+        dmPolicy: "pairing"
+```
+
+`channels.feishu.dmPolicy` / `channels.feishu.allowFrom` 是“默认值”；账号下未覆盖时才会继承。
+
+> `dmPolicy` 只控制“是否允许触发机器人”。  
+> 真正执行文档/云盘/知识库/多维表格操作，还需要两层权限：1）应用 API 权限（scopes）；2）把目标资源分享给机器人。
+
 #### 连接模式
 
 支持两种从飞书接收事件的连接模式：
@@ -571,7 +750,8 @@ session:
 - **文档工具**：读取、创建、用 Markdown 写入飞书文档（表格因 API 限制不支持）
 - **知识库工具**：浏览知识库、列出空间、获取节点详情、搜索、创建/移动/重命名节点
 - **云空间工具**：列出文件夹、获取文件信息、创建文件夹、移动/删除文件
-- **多维表格工具**：读写多维表格记录，支持 `/base/` 和 `/wiki/` 两种链接格式
+- **多维表格工具**：支持多维表格字段与记录的读取/创建/更新/删除，支持 `/base/` 和 `/wiki/` 两种链接格式
+- **任务工具**：基于 Task v2 API 支持任务创建、获取详情、更新和删除
 - **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
 - **权限错误提示**：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
 - **动态 Agent 创建**：每个私聊用户可拥有独立的 agent 实例和专属 workspace（可选）
@@ -610,18 +790,6 @@ session:
 
 飞书 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。
 
-#### Windows 安装报错 `spawn npm ENOENT`
-
-如果 `openclaw plugins install` 失败，可以手动安装：
-
-```bash
-# 1. 下载插件包
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
-
-# 2. 从本地安装
-openclaw plugins install ./feishu-0.1.3.tgz
-```
-
 #### 在飞书里找不到机器人
 
 1. 确保应用已发布（至少发布到测试版本）

package/index.ts

@@ -7,6 +7,7 @@ import { registerFeishuWikiTools } from "./src/wiki.js";
 import { registerFeishuDriveTools } from "./src/drive.js";
 import { registerFeishuPermTools } from "./src/perm.js";
 import { registerFeishuBitableTools } from "./src/bitable.js";
+import { registerFeishuTaskTools } from "./src/task.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
 export {
@@ -23,7 +24,7 @@ export {
   sendFileFeishu,
   sendMediaFeishu,
 } from "./src/media.js";
-export { probeFeishu } from "./src/probe.js";
+export { probeFeishu, clearProbeCache } from "./src/probe.js";
 export {
   addReactionFeishu,
   removeReactionFeishu,
@@ -57,6 +58,7 @@ const plugin = {
     registerFeishuDriveTools(api);
     registerFeishuPermTools(api);
     registerFeishuBitableTools(api);
+    registerFeishuTaskTools(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",
@@ -46,17 +46,17 @@
     }
   },
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.58.0",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
     "@sinclair/typebox": "0.34.48",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
-    "openclaw": "2026.1.29",
+    "openclaw": "2026.2.13",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.29"
+    "openclaw": ">=2026.2.13"
   }
 }

package/skills/feishu-doc/SKILL.md

@@ -32,6 +32,28 @@ Replaces entire document with markdown content. Supports: headings, lists, code
 
 **Limitation:** Markdown tables are NOT supported.
 
+### Create + Write (Atomic, Recommended)
+
+```json
+{
+  "action": "create_and_write",
+  "title": "New Document",
+  "content": "# Title\n\nMarkdown content..."
+}
+```
+
+With folder:
+```json
+{
+  "action": "create_and_write",
+  "title": "New Document",
+  "content": "# Title\n\nMarkdown content...",
+  "folder_token": "fldcnXXX"
+}
+```
+
+Creates the document and writes content in one call. Prefer this over separate `create` + `write`.
+
 ### Append Content
 
 ```json
@@ -51,6 +73,8 @@ With folder:
 { "action": "create", "title": "New Document", "folder_token": "fldcnXXX" }
 ```
 
+Creates an empty document (title only).
+
 ### List Blocks
 
 ```json

package/src/bitable-tools/actions.ts

@@ -0,0 +1,199 @@
+import type {
+  BitableClient,
+  BitableFieldCreateData,
+  BitableFieldUpdateData,
+} from "./common.js";
+import { formatField, runBitableApiCall } from "./common.js";
+
+// -------- Field operations --------
+
+export async function listFields(client: BitableClient, appToken: string, tableId: string) {
+  const res = await runBitableApiCall("bitable.appTableField.list", () =>
+    client.bitable.appTableField.list({
+      path: { app_token: appToken, table_id: tableId },
+    }),
+  );
+
+  const fields = res.data?.items ?? [];
+  return {
+    fields: fields.map((f) => formatField(f)),
+    total: fields.length,
+  };
+}
+
+export async function createField(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  field: BitableFieldCreateData,
+) {
+  const res = await runBitableApiCall("bitable.appTableField.create", () =>
+    client.bitable.appTableField.create({
+      path: { app_token: appToken, table_id: tableId },
+      data: field,
+    }),
+  );
+
+  return {
+    field: res.data?.field ? formatField(res.data.field) : undefined,
+  };
+}
+
+export async function updateField(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  fieldId: string,
+  field: BitableFieldUpdateData,
+) {
+  const res = await runBitableApiCall("bitable.appTableField.update", () =>
+    client.bitable.appTableField.update({
+      path: { app_token: appToken, table_id: tableId, field_id: fieldId },
+      data: field,
+    }),
+  );
+
+  return {
+    field: res.data?.field ? formatField(res.data.field) : undefined,
+  };
+}
+
+export async function deleteField(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  fieldId: string,
+) {
+  const res = await runBitableApiCall("bitable.appTableField.delete", () =>
+    client.bitable.appTableField.delete({
+      path: { app_token: appToken, table_id: tableId, field_id: fieldId },
+    }),
+  );
+
+  return {
+    success: res.data?.deleted ?? true,
+    field_id: res.data?.field_id ?? fieldId,
+    deleted: res.data?.deleted ?? true,
+  };
+}
+
+// -------- Record operations --------
+
+export async function listRecords(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  pageSize?: number,
+  pageToken?: string,
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.list", () =>
+    client.bitable.appTableRecord.list({
+      path: { app_token: appToken, table_id: tableId },
+      params: {
+        page_size: pageSize ?? 100,
+        ...(pageToken && { page_token: pageToken }),
+      },
+    }),
+  );
+
+  return {
+    records: res.data?.items ?? [],
+    has_more: res.data?.has_more ?? false,
+    page_token: res.data?.page_token,
+    total: res.data?.total,
+  };
+}
+
+export async function getRecord(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  recordId: string,
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.get", () =>
+    client.bitable.appTableRecord.get({
+      path: { app_token: appToken, table_id: tableId, record_id: recordId },
+    }),
+  );
+
+  return {
+    record: res.data?.record,
+  };
+}
+
+export async function createRecord(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  fields: Record<string, unknown>,
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.create", () =>
+    client.bitable.appTableRecord.create({
+      path: { app_token: appToken, table_id: tableId },
+      data: { fields },
+    }),
+  );
+
+  return {
+    record: res.data?.record,
+  };
+}
+
+export async function updateRecord(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  recordId: string,
+  fields: Record<string, unknown>,
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.update", () =>
+    client.bitable.appTableRecord.update({
+      path: { app_token: appToken, table_id: tableId, record_id: recordId },
+      data: { fields },
+    }),
+  );
+
+  return {
+    record: res.data?.record,
+  };
+}
+
+export async function deleteRecord(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  recordId: string,
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.delete", () =>
+    client.bitable.appTableRecord.delete({
+      path: { app_token: appToken, table_id: tableId, record_id: recordId },
+    }),
+  );
+
+  return {
+    success: res.data?.deleted ?? true,
+    record_id: res.data?.record_id ?? recordId,
+    deleted: res.data?.deleted ?? true,
+  };
+}
+
+export async function batchDeleteRecords(
+  client: BitableClient,
+  appToken: string,
+  tableId: string,
+  recordIds: string[],
+) {
+  const res = await runBitableApiCall("bitable.appTableRecord.batchDelete", () =>
+    client.bitable.appTableRecord.batchDelete({
+      path: { app_token: appToken, table_id: tableId },
+      data: { records: recordIds },
+    }),
+  );
+
+  const results = res.data?.records ?? [];
+  return {
+    results,
+    requested: recordIds.length,
+    deleted: results.filter((r) => r.deleted).length,
+  };
+}