@m1heng-clawd/feishu 0.1.11 → 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,6 +83,9 @@ 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):
 
@@ -87,9 +96,44 @@ openclaw plugins update feishu
 | `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 ⚠️
 
-> Task scope names may vary slightly in Feishu console UI. If needed, search for Task-related permissions and grant read/write accordingly.
+> **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.
+
+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 ⚠️
 
@@ -174,6 +218,10 @@ channels:
     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"
@@ -255,6 +303,21 @@ Top-level `channels.feishu.dmPolicy` / `channels.feishu.allowFrom` are fallback
 > `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:
@@ -471,6 +534,9 @@ 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` | 列出/获取任务附件 |
 
 **读写权限**（可选，用于创建/编辑/删除操作）：
 
@@ -481,9 +547,44 @@ openclaw plugins update feishu
 | `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）。
 
 #### 云空间访问权限 ⚠️
 
@@ -568,6 +669,9 @@ channels:
     groupPolicy: "allowlist"
     # 群聊是否需要 @机器人
     requireMention: true
+    # 群聊命令绕过 @ 策略: "never" | "single_bot" | "always"
+    # 默认 "single_bot"：仅当群内机器人数量 <= 1 时，允许已授权命令免 @
+    groupCommandMentionBypass: "single_bot"
     # 媒体文件最大大小 (MB, 默认 30)
     mediaMaxMb: 30
     # 回复渲染模式: "auto" | "raw" | "card"
@@ -649,6 +753,21 @@ channels:
 > `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.11",
+  "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
 
@@ -101,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
@@ -121,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)

package/skills/feishu-task/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: feishu-task
+description: |
+  Feishu Task, tasklist, subtask, comment, and attachment management. Activate when user mentions tasks, tasklists, subtasks, task comments, task attachments, or task links.
+---
+
+# Feishu Task Tools
+
+Tools:
+- `feishu_task_create`
+- `feishu_task_subtask_create`
+- `feishu_task_get`
+- `feishu_task_update`
+- `feishu_task_delete`
+- `feishu_task_comment_create`
+- `feishu_task_comment_list`
+- `feishu_task_comment_get`
+- `feishu_task_comment_update`
+- `feishu_task_comment_delete`
+- `feishu_task_attachment_upload`
+- `feishu_task_attachment_list`
+- `feishu_task_attachment_get`
+- `feishu_task_attachment_delete`
+- `feishu_task_add_tasklist`
+- `feishu_task_remove_tasklist`
+- `feishu_tasklist_create`
+- `feishu_tasklist_get`
+- `feishu_tasklist_list`
+- `feishu_tasklist_update`
+- `feishu_tasklist_delete`
+- `feishu_tasklist_add_members`
+- `feishu_tasklist_remove_members`
+
+## Notes
+
+- `task_guid` can be taken from a task URL (guid query param) or from `feishu_task_get` output.
+- `comment_id` can be obtained from `feishu_task_comment_list` output.
+- `attachment_guid` can be obtained from `feishu_task_attachment_list` output.
+- `user_id_type` controls returned/accepted user identity type (`open_id`, `user_id`, `union_id`).
+- If no assignee is specified, set the assignee to the requesting user. Avoid creating unassigned tasks because the user may not be able to view them.
+- Task visibility: users can only view tasks when they are included as assignee.
+- Current limitation: the bot can only create subtasks for tasks created by itself.
+- Attachment upload supports local `file_path` and remote `file_url`. Remote URLs are fetched with runtime media safety checks and size limit (`mediaMaxMb`).
+- Keep tasklist owner as the bot. Add users as members to avoid losing bot access.
+- Use tasklist tools for tasklist membership changes; do not use `feishu_task_update` to move tasks between tasklists.
+
+## Create Task
+
+```json
+{
+  "summary": "Quarterly review",
+  "description": "Prepare review notes",
+  "due": { "timestamp": "1735689600000", "is_all_day": true },
+  "members": [
+    { "id": "ou_xxx", "role": "assignee", "type": "user" }
+  ],
+  "user_id_type": "open_id"
+}
+```
+
+## Create Subtask
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "summary": "Draft report outline",
+  "description": "Collect key metrics",
+  "due": { "timestamp": "1735689600000", "is_all_day": true },
+  "members": [
+    { "id": "ou_xxx", "role": "assignee", "type": "user" }
+  ],
+  "user_id_type": "open_id"
+}
+```
+
+## Create Comment
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "content": "Looks good to me",
+  "user_id_type": "open_id"
+}
+```
+
+## Upload Attachment (file_path)
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "file_path": "/path/to/report.pdf",
+  "user_id_type": "open_id"
+}
+```
+
+## Upload Attachment (file_url)
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "file_url": "https://oss-example.com/bucket/report.pdf",
+  "filename": "report.pdf",
+  "user_id_type": "open_id"
+}
+```
+
+## Tasklist Membership For Tasks
+
+### Add Task to Tasklist
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "section_guid": "6d0f9f48-2e06-4e3d-8a0f-acde196e8c61",
+  "user_id_type": "open_id"
+}
+```
+
+### Remove Task from Tasklist
+
+```json
+{
+  "task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "user_id_type": "open_id"
+}
+```
+
+## Tasklists
+
+Tasklists support three roles: owner (read/edit/manage), editor (read/edit), viewer (read).
+
+### Create Tasklist
+
+```json
+{
+  "name": "Project Alpha Tasklist",
+  "members": [
+    { "id": "ou_xxx", "type": "user", "role": "editor" }
+  ],
+  "user_id_type": "open_id"
+}
+```
+
+### Get Tasklist
+
+```json
+{
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "user_id_type": "open_id"
+}
+```
+
+### List Tasklists
+
+```json
+{
+  "page_size": 50,
+  "page_token": "aWQ9NzEwMjMzMjMxMDE=",
+  "user_id_type": "open_id"
+}
+```
+
+### Update Tasklist
+
+```json
+{
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "tasklist": {
+    "name": "Renamed Tasklist",
+    "owner": { "id": "ou_xxx", "type": "user", "role": "owner" }
+  },
+  "update_fields": ["name", "owner"],
+  "origin_owner_to_role": "editor",
+  "user_id_type": "open_id"
+}
+```
+
+### Delete Tasklist
+
+```json
+{
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004"
+}
+```
+
+### Add Tasklist Members
+
+```json
+{
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "members": [
+    { "id": "ou_xxx", "type": "user", "role": "editor" }
+  ],
+  "user_id_type": "open_id"
+}
+```
+
+### Remove Tasklist Members
+
+```json
+{
+  "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
+  "members": [
+    { "id": "ou_xxx", "type": "user", "role": "viewer" }
+  ],
+  "user_id_type": "open_id"
+}
+```

package/src/bitable-tools/index.ts

@@ -0,0 +1 @@
+export { registerFeishuBitableTools } from "./register.js";