@m1heng-clawd/feishu 0.1.10 → 0.1.12

package/README.md

@@ -5,6 +5,12 @@ Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/o
 > **中文社区资料** - 配置教程、常见问题、使用技巧：[Wiki](https://github.com/m1heng/clawdbot-feishu/wiki)
 >
 > **Contributing / 贡献指南**: [CONTRIBUTING.md](./CONTRIBUTING.md)
+>
+> **Issue Reporting / 问题反馈**: Please check [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) first for common solutions, then open a structured Issue Form if needed.  
+> 问题反馈前请先查看 [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) 是否已有常见解答；如仍未解决，再提交结构化 Issue 模板。
+>
+> **Questions / 使用咨询**: Use `Question` issue for troubleshooting; use [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions) for open-ended Q&A.  
+> 排查型咨询请提交 `Question` Issue；开放式交流请使用 [Discussions](https://github.com/m1heng/clawdbot-feishu/discussions)。
 
 [English](#english) | [中文](#中文)
 
@@ -77,19 +83,57 @@ openclaw plugins update feishu
 | `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 |
+| `task:tasklist:read` | `feishu_tasklist_get`, `feishu_tasklist_list` | Get/list tasklists |
+| `task:comment:read` | `feishu_task_comment_list`, `feishu_task_comment_get` | List/get task comments |
+| `task:attachment:read` | `feishu_task_attachment_list`, `feishu_task_attachment_get` | List/get task attachments |
 
 **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/delete bitable records and manage fields |
-| `task:task:write` | `feishu_task_create`, `feishu_task_update`, `feishu_task_delete` | Create/update/delete tasks |
+| `task:task:write` | `feishu_task_create`, `feishu_task_subtask_create`, `feishu_task_update`, `feishu_task_delete` | Create/update/delete tasks |
+| `task:tasklist:write` | `feishu_tasklist_create`, `feishu_tasklist_update`, `feishu_tasklist_delete`, `feishu_tasklist_add_members`, `feishu_tasklist_remove_members`, `feishu_task_add_tasklist`, `feishu_task_remove_tasklist` | Create/update/delete tasklists and manage membership |
+| `task:comment:write` | `feishu_task_comment_create`, `feishu_task_comment_update`, `feishu_task_comment_delete` | Create/update/delete task comments |
+| `task:attachment:write` | `feishu_task_attachment_upload`, `feishu_task_attachment_delete` | Upload/delete task attachments |
+
+> Task scope names may vary slightly in Feishu console UI. If needed, search for Task / Tasklist / Comment / Attachment-related permissions and grant read/write accordingly.
+
+#### Task Comment Scopes ⚠️
+
+Task comments require dedicated scopes:
+1. Read comments: grant `task:comment:read`.
+2. Create/update/delete comments: grant `task:comment:write`.
+
+If these scopes are missing, comment APIs will return permission-denied errors.
+
+#### Task Attachment Upload ⚠️
+
+Task attachments support upload/get/list/delete. Upload sources:
+1. Local files on the OpenClaw/Node host (`file_path`)
+2. Remote links (`file_url`, public or presigned)
+
+For `file_url`, OpenClaw runtime media loader is used with safety checks and size limit (`mediaMaxMb`), then the downloaded file is uploaded via a temporary local file.
+
+#### Tasklist Ownership ⚠️
+
+> **Important:** Keep tasklist owner as the bot. Add users as members instead.
+
+Tasklist access is granted based on owner + member roles. If you change the owner to a user and the bot is not a member, the bot may lose permission to read/edit/manage that tasklist (and subsequent operations will fail).
+
+#### Task Visibility & Subtasks ⚠️
+
+> **Important:** A user can only view a task when they are included as an assignee.
+>
+> **Limitation:** The bot can currently only create subtasks for tasks created by itself.
 
-> Task scope names may vary slightly in Feishu console UI. If needed, search for Task-related permissions and grant read/write accordingly.
+To avoid “task created but not visible” issues:
+1. When creating a task, set the requesting user as an assignee.
+2. If you need more flexible subtask organization/visibility, consider using tasklists.
 
 #### Drive Access ⚠️
 
@@ -168,16 +212,112 @@ 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
     requireMention: true
+    # Group command mention bypass: "never" | "single_bot" | "always"
+    # Default "single_bot": allow authorized command-only messages without @
+    # only when the group has a single bot.
+    groupCommandMentionBypass: "single_bot"
     # Max media size in MB (default: 30)
     mediaMaxMb: 30
     # Render mode for bot replies: "auto" | "raw" | "card"
     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.
+
+#### Group Command Mention Bypass
+
+When `requireMention: true`, Feishu can still allow authorized control commands (such as `/new`) without `@bot`.
+
+| `groupCommandMentionBypass` | Behavior |
+|----------------------------|----------|
+| `never` | Never bypass `@` requirement for group commands. |
+| `single_bot` | Bypass only when the group contains at most one bot (default). |
+| `always` | Always allow authorized control commands to bypass mention gating. |
+
+Notes:
+- Bypass only applies to authorized control commands in group chats.
+- If any user is explicitly `@`-mentioned in the same message, bypass is disabled.
+- In DMs, this setting does not apply.
+
 #### Connection Mode
 
 Two connection modes are available for receiving events from Feishu:
@@ -276,7 +416,7 @@ 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**: Manage bitable (多维表格) fields and records (read/create/update/delete), supports both `/base/` and `/wiki/` URLs
@@ -394,19 +534,57 @@ openclaw plugins update feishu
 | `wiki:wiki:readonly` | `feishu_wiki` | 列出空间、列出节点、获取节点详情、搜索 |
 | `bitable:app:readonly` | `feishu_bitable` | 读取多维表格记录和字段 |
 | `task:task:read` | `feishu_task_get` | 获取任务详情 |
+| `task:tasklist:read` | `feishu_tasklist_get`, `feishu_tasklist_list` | 获取/列出任务清单（tasklists） |
+| `task:comment:read` | `feishu_task_comment_list`, `feishu_task_comment_get` | 列出/获取任务评论 |
+| `task:attachment:read` | `feishu_task_attachment_list`, `feishu_task_attachment_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` | 创建/更新/删除多维表格记录并管理字段 |
-| `task:task:write` | `feishu_task_create`, `feishu_task_update`, `feishu_task_delete` | 创建/更新/删除任务 |
+| `task:task:write` | `feishu_task_create`, `feishu_task_subtask_create`, `feishu_task_update`, `feishu_task_delete` | 创建/更新/删除任务 |
+| `task:tasklist:write` | `feishu_tasklist_create`, `feishu_tasklist_update`, `feishu_tasklist_delete`, `feishu_tasklist_add_members`, `feishu_tasklist_remove_members`, `feishu_task_add_tasklist`, `feishu_task_remove_tasklist` | 创建/更新/删除任务清单并管理成员/关联任务 |
+| `task:comment:write` | `feishu_task_comment_create`, `feishu_task_comment_update`, `feishu_task_comment_delete` | 创建/更新/删除任务评论 |
+| `task:attachment:write` | `feishu_task_attachment_upload`, `feishu_task_attachment_delete` | 上传/删除任务附件 |
+
+> 飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 `task` / `tasklist` / `comment` / `attachment` 搜索并授予对应读写权限。
+
+#### 任务评论权限 ⚠️
+
+任务评论需要单独授权：
+1. 读取评论：授予 `task:comment:read`。
+2. 创建/更新/删除评论：授予 `task:comment:write`。
+
+缺少上述权限时，评论相关接口会返回权限不足错误。
+
+#### 任务附件上传 ⚠️
+
+任务附件支持上传/获取/列表/删除。上传来源：
+1. OpenClaw/Node 所在机器的本地文件路径（`file_path`）
+2. 可直接下载的远程链接（`file_url`，公开/预签名 URL）
+
+`file_url` 上传路径会使用 OpenClaw 运行时的媒体下载安全校验与大小限制（`mediaMaxMb`），随后经临时本地文件上传到任务附件。
+
+#### 任务清单所有者限制 ⚠️
+
+> **重要：** 创建/修改任务清单时，请保持清单所有者为机器人本身，只把用户作为协作人添加。
+
+任务清单权限基于“所有者 + 协作成员角色”授予。如果把清单所有者改成用户、且机器人不在协作成员中，机器人可能会失去对该清单的读取/编辑/管理权限，导致后续对清单的操作失败。
+
+#### 任务限制 ⚠️
+
+> **重要：** 只有当任务责任人包含用户时，用户才能查看到该任务。
+>
+> **限制：** 机器人目前只能给自己创建出来的任务创建子任务。
 
-> 飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 `task` 搜索并授予对应读写权限。
+为避免“任务创建了但用户看不到”的问题：
+1. 创建任务时，请把发起用户设为任务负责人（`assignee`）。
+2. 如需更灵活的子任务创建/组织/可见性管理，建议使用任务清单（tasklists）。
 
 #### 云空间访问权限 ⚠️
 
@@ -485,16 +663,111 @@ channels:
     connectionMode: "websocket"
     # 私聊策略: "pairing" | "open" | "allowlist"
     dmPolicy: "pairing"
+    # 私聊白名单（open_id/user_id）；当 dmPolicy="open" 时请包含 "*"
+    allowFrom: []
     # 群聊策略: "open" | "allowlist" | "disabled"
     groupPolicy: "allowlist"
     # 群聊是否需要 @机器人
     requireMention: true
+    # 群聊命令绕过 @ 策略: "never" | "single_bot" | "always"
+    # 默认 "single_bot"：仅当群内机器人数量 <= 1 时，允许已授权命令免 @
+    groupCommandMentionBypass: "single_bot"
     # 媒体文件最大大小 (MB, 默认 30)
     mediaMaxMb: 30
     # 回复渲染模式: "auto" | "raw" | "card"
     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）把目标资源分享给机器人。
+
+#### 群聊命令免 @ 策略
+
+当 `requireMention: true` 时，Feishu 仍可让“已授权控制命令（如 `/new`）”在不 `@bot` 的情况下通过。
+
+| `groupCommandMentionBypass` | 行为 |
+|----------------------------|------|
+| `never` | 群聊命令永不绕过 `@` 校验。 |
+| `single_bot` | 仅当群内机器人数量不超过 1 个时才允许绕过（默认）。 |
+| `always` | 已授权控制命令始终可绕过 `@` 校验。 |
+
+说明：
+- 仅对群聊中的“已授权控制命令”生效。
+- 同一条消息里如果显式 `@` 了任意用户，则不会触发命令免 `@`。
+- 私聊场景不受该配置影响。
+
 #### 连接模式
 
 支持两种从飞书接收事件的连接模式：

package/index.ts

@@ -2,12 +2,12 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { feishuPlugin } from "./src/channel.js";
 import { setFeishuRuntime } from "./src/runtime.js";
-import { registerFeishuDocTools } from "./src/docx.js";
-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";
+import { registerFeishuDocTools } from "./src/doc-tools/index.js";
+import { registerFeishuWikiTools } from "./src/wiki-tools/index.js";
+import { registerFeishuDriveTools } from "./src/drive-tools/index.js";
+import { registerFeishuPermTools } from "./src/perm-tools/index.js";
+import { registerFeishuBitableTools } from "./src/bitable-tools/index.js";
+import { registerFeishuTaskTools } from "./src/task-tools/index.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
 export {

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
+  "scripts": {
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "ci:check": "npx tsc --noEmit && npm run test:coverage"
+  },
   "license": "MIT",
   "files": [
     "index.ts",
-    "src",
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
     "skills",
     "openclaw.plugin.json"
   ],
@@ -51,10 +59,12 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
     "@types/node": "^25.0.10",
     "openclaw": "2026.2.13",
     "tsx": "^4.21.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.8"
   },
   "peerDependencies": {
     "openclaw": ">=2026.2.13"

package/skills/feishu-doc/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: feishu-doc
 description: |
-  Feishu document read/write operations. Activate when user mentions Feishu docs, cloud docs, or docx links.
+  Feishu document read/write operations + comment management. Activate when user mentions Feishu docs, cloud docs, docx links, or document comments.
 ---
 
 # Feishu Document Tool
 
-Single tool `feishu_doc` with action parameter for all document operations.
+Single tool `feishu_doc` with action parameter for all document operations including comment management.
 
 ## Token Extraction
 
 From URL `https://xxx.feishu.cn/docx/ABC123def` → `doc_token` = `ABC123def`
+From URL `https://xxx.feishu.cn/docs/doccn123c` → `doc_token` = `doccn123c`
 
 ## Actions
 
@@ -32,6 +33,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 +74,8 @@ With folder:
 { "action": "create", "title": "New Document", "folder_token": "fldcnXXX" }
 ```
 
+Creates an empty document (title only).
+
 ### List Blocks
 
 ```json
@@ -77,6 +102,39 @@ Returns full block data including tables, images. Use this to read structured co
 { "action": "delete_block", "doc_token": "ABC123def", "block_id": "doxcnXXX" }
 ```
 
+### List Comments
+
+```json
+{ "action": "list_comments", "doc_token": "ABC123def", "page_size": 50 }
+```
+
+Returns all comments for the document. Use `page_token` for pagination. Comments include `is_whole` field to distinguish between whole-document comments (true) and block-level comments (false).
+
+### Get Single Comment
+
+```json
+{ "action": "get_comment", "doc_token": "ABC123def", "comment_id": "comment_xxx" }
+```
+
+### Create Comment
+
+```json
+{ "action": "create_comment", "doc_token": "ABC123def", "content": "Comment text" }
+```
+
+### List Comment Replies
+
+```json
+{ "action": "list_comment_replies", "doc_token": "ABC123def", "comment_id": "comment_xxx", "page_size": 50 }
+```
+
+`page_size` should be a positive integer. If omitted, tool defaults to `50`.
+
+### Comment Write Scope
+
+Current tool provides documented comment write action `create_comment` (global comment creation).
+For replies, use `list_comment_replies` for retrieval; the reply creation endpoint is not exposed in current SDK surface.
+
 ## Reading Workflow
 
 1. Start with `action: "read"` - get plain text + statistics
@@ -97,3 +155,7 @@ channels:
 ## Permissions
 
 Required: `docx:document`, `docx:document:readonly`, `docx:document.block:convert`, `drive:drive`
+
+For comment operations:
+- Read comments: `docx:document.comment:read`
+- Write comments: `docx:document.comment` (optional, for create_comment)