@m1heng-clawd/feishu 0.1.4 → 0.1.6

package/README.md

@@ -49,17 +49,48 @@ npm install @m1heng-clawd/feishu
 | `im:message:recall` | Recall | Recall sent messages |
 | `im:message.reactions:read` | Reactions | View message reactions |
 
-#### Document Tools Permissions
+#### Tool Permissions
 
-Required if using Feishu document tools (`feishu_doc_*`):
+**Read-only** (minimum required):
 
-| Permission | Description |
-|------------|-------------|
-| `docx:document` | Create/edit documents |
-| `docx:document:readonly` | Read documents |
-| `docx:document.block:convert` | Markdown to blocks conversion (required for write/append) |
-| `drive:drive` | Upload images to documents |
-| `drive:drive:readonly` | List folders |
+| Permission | Tool | Description |
+|------------|------|-------------|
+| `docx:document:readonly` | `feishu_doc` | Read documents |
+| `drive:drive:readonly` | `feishu_drive` | List folders, get file info |
+| `wiki:wiki:readonly` | `feishu_wiki` | List spaces, list nodes, get node info, search |
+
+**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) |
+| `drive:drive` | `feishu_doc`, `feishu_drive` | Upload images to documents, create folders, move/delete files |
+| `wiki:wiki` | `feishu_wiki` | Create/move/rename wiki nodes |
+
+#### Drive Access ⚠️
+
+> **Important:** Bots don't have their own "My Space" (root folder). Bots can only access files/folders that have been **shared with them**.
+
+To let the bot manage files:
+1. Create a folder in your Feishu Drive
+2. Right-click the folder → **Share** → search for your bot name
+3. Grant appropriate permission (view/edit)
+
+Without this step, `feishu_drive` operations like `create_folder` will fail because the bot has no root folder to create in.
+
+#### Wiki Space Access ⚠️
+
+> **Important:** API permissions alone are not enough for wiki access. You must also add the bot to each wiki space.
+
+1. Open the wiki space you want the bot to access
+2. Click **Settings** (gear icon) → **Members**
+3. Click **Add Member** → search for your bot name
+4. Select appropriate permission level (view/edit)
+
+Without this step, `feishu_wiki` will return empty results even with correct API permissions.
+
+Reference: [Wiki FAQ - How to add app to wiki](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca)
 
 #### Event Subscriptions ⚠️
 
@@ -129,7 +160,10 @@ channels:
 - 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)
+- **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
 - **@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
 
 #### @Mention Forwarding
 
@@ -225,17 +259,48 @@ npm install @m1heng-clawd/feishu
 | `im:message:recall` | 撤回 | 撤回已发送消息 |
 | `im:message.reactions:read` | 表情 | 查看消息表情回复 |
 
-#### 文档工具权限
+#### 工具权限
 
-使用飞书文档工具（`feishu_doc_*`）需要以下权限：
+**只读权限**（最低要求）：
 
-| 权限 | 说明 |
-|------|------|
-| `docx:document` | 创建/编辑文档 |
-| `docx:document:readonly` | 读取文档 |
-| `docx:document.block:convert` | Markdown 转 blocks（write/append 必需） |
-| `drive:drive` | 上传图片到文档 |
-| `drive:drive:readonly` | 列出文件夹 |
+| 权限 | 工具 | 说明 |
+|------|------|------|
+| `docx:document:readonly` | `feishu_doc` | 读取文档 |
+| `drive:drive:readonly` | `feishu_drive` | 列出文件夹、获取文件信息 |
+| `wiki:wiki:readonly` | `feishu_wiki` | 列出空间、列出节点、获取节点详情、搜索 |
+
+**读写权限**（可选，用于创建/编辑/删除操作）：
+
+| 权限 | 工具 | 说明 |
+|------|------|------|
+| `docx:document` | `feishu_doc` | 创建/编辑文档 |
+| `docx:document.block:convert` | `feishu_doc` | Markdown 转 blocks（write/append 必需） |
+| `drive:drive` | `feishu_doc`, `feishu_drive` | 上传图片到文档、创建文件夹、移动/删除文件 |
+| `wiki:wiki` | `feishu_wiki` | 创建/移动/重命名知识库节点 |
+
+#### 云空间访问权限 ⚠️
+
+> **重要：** 机器人没有自己的"我的空间"（根目录）。机器人只能访问**被分享给它的文件/文件夹**。
+
+要让机器人管理文件：
+1. 在你的飞书云空间创建一个文件夹
+2. 右键文件夹 → **分享** → 搜索机器人名称
+3. 授予相应权限（查看/编辑）
+
+如果不做这一步，`feishu_drive` 的 `create_folder` 等操作会失败，因为机器人没有根目录可以创建文件夹。
+
+#### 知识库空间权限 ⚠️
+
+> **重要：** 仅有 API 权限不够，还需要将机器人添加到知识库空间。
+
+1. 打开需要机器人访问的知识库空间
+2. 点击 **设置**（齿轮图标）→ **成员管理**
+3. 点击 **添加成员** → 搜索机器人名称
+4. 选择权限级别（查看/编辑）
+
+如果不做这一步，即使 API 权限正确，`feishu_wiki` 也会返回空结果。
+
+参考文档：[知识库常见问题 - 如何将应用添加为知识库成员](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca)
 
 #### 事件订阅 ⚠️
 
@@ -305,7 +370,10 @@ channels:
 - 用户和群组目录查询
 - **卡片渲染模式**：支持语法高亮的 Markdown 渲染
 - **文档工具**：读取、创建、用 Markdown 写入飞书文档（表格因 API 限制不支持）
+- **知识库工具**：浏览知识库、列出空间、获取节点详情、搜索、创建/移动/重命名节点
+- **云空间工具**：列出文件夹、获取文件信息、创建文件夹、移动/删除文件
 - **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
+- **权限错误提示**：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
 
 #### @ 转发功能
 

package/index.ts

@@ -3,6 +3,9 @@ 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";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
 export {
@@ -49,6 +52,9 @@ const plugin = {
     setFeishuRuntime(api.runtime);
     api.registerChannel({ plugin: feishuPlugin });
     registerFeishuDocTools(api);
+    registerFeishuWikiTools(api);
+    registerFeishuDriveTools(api);
+    registerFeishuPermTools(api);
   },
 };
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",
   "files": [
     "index.ts",
     "src",
+    "skills",
     "openclaw.plugin.json"
   ],
   "repository": {

package/skills/feishu-doc/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: feishu-doc
+description: |
+  Feishu document read/write operations. Activate when user mentions Feishu docs, cloud docs, or docx links.
+---
+
+# Feishu Document Tool
+
+Single tool `feishu_doc` with action parameter for all document operations.
+
+## Token Extraction
+
+From URL `https://xxx.feishu.cn/docx/ABC123def` → `doc_token` = `ABC123def`
+
+## Actions
+
+### Read Document
+
+```json
+{ "action": "read", "doc_token": "ABC123def" }
+```
+
+Returns: title, plain text content, block statistics. Check `hint` field - if present, structured content (tables, images) exists that requires `list_blocks`.
+
+### Write Document (Replace All)
+
+```json
+{ "action": "write", "doc_token": "ABC123def", "content": "# Title\n\nMarkdown content..." }
+```
+
+Replaces entire document with markdown content. Supports: headings, lists, code blocks, quotes, links, images (`![](url)` auto-uploaded), bold/italic/strikethrough.
+
+**Limitation:** Markdown tables are NOT supported.
+
+### Append Content
+
+```json
+{ "action": "append", "doc_token": "ABC123def", "content": "Additional content" }
+```
+
+Appends markdown to end of document.
+
+### Create Document
+
+```json
+{ "action": "create", "title": "New Document" }
+```
+
+With folder:
+```json
+{ "action": "create", "title": "New Document", "folder_token": "fldcnXXX" }
+```
+
+### List Blocks
+
+```json
+{ "action": "list_blocks", "doc_token": "ABC123def" }
+```
+
+Returns full block data including tables, images. Use this to read structured content.
+
+### Get Single Block
+
+```json
+{ "action": "get_block", "doc_token": "ABC123def", "block_id": "doxcnXXX" }
+```
+
+### Update Block Text
+
+```json
+{ "action": "update_block", "doc_token": "ABC123def", "block_id": "doxcnXXX", "content": "New text" }
+```
+
+### Delete Block
+
+```json
+{ "action": "delete_block", "doc_token": "ABC123def", "block_id": "doxcnXXX" }
+```
+
+## Reading Workflow
+
+1. Start with `action: "read"` - get plain text + statistics
+2. Check `block_types` in response for Table, Image, Code, etc.
+3. If structured content exists, use `action: "list_blocks"` for full data
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      doc: true  # default: true
+```
+
+**Note:** `feishu_wiki` depends on this tool - wiki page content is read/written via `feishu_doc`.
+
+## Permissions
+
+Required: `docx:document`, `docx:document:readonly`, `docx:document.block:convert`, `drive:drive`

package/skills/feishu-doc/references/block-types.md

@@ -0,0 +1,102 @@
+# Feishu Block Types Reference
+
+Complete reference for Feishu document block types. Use with `feishu_doc_list_blocks`, `feishu_doc_update_block`, and `feishu_doc_delete_block`.
+
+## Block Type Table
+
+| block_type | Name | Description | Editable |
+|------------|------|-------------|----------|
+| 1 | Page | Document root (contains title) | No |
+| 2 | Text | Plain text paragraph | Yes |
+| 3 | Heading1 | H1 heading | Yes |
+| 4 | Heading2 | H2 heading | Yes |
+| 5 | Heading3 | H3 heading | Yes |
+| 6 | Heading4 | H4 heading | Yes |
+| 7 | Heading5 | H5 heading | Yes |
+| 8 | Heading6 | H6 heading | Yes |
+| 9 | Heading7 | H7 heading | Yes |
+| 10 | Heading8 | H8 heading | Yes |
+| 11 | Heading9 | H9 heading | Yes |
+| 12 | Bullet | Unordered list item | Yes |
+| 13 | Ordered | Ordered list item | Yes |
+| 14 | Code | Code block | Yes |
+| 15 | Quote | Blockquote | Yes |
+| 16 | Equation | LaTeX equation | Partial |
+| 17 | Todo | Checkbox / task item | Yes |
+| 18 | Bitable | Multi-dimensional table | No |
+| 19 | Callout | Highlight block | Yes |
+| 20 | ChatCard | Chat card embed | No |
+| 21 | Diagram | Diagram embed | No |
+| 22 | Divider | Horizontal rule | No |
+| 23 | File | File attachment | No |
+| 24 | Grid | Grid layout container | No |
+| 25 | GridColumn | Grid column | No |
+| 26 | Iframe | Embedded iframe | No |
+| 27 | Image | Image | Partial |
+| 28 | ISV | Third-party widget | No |
+| 29 | MindnoteBlock | Mindmap embed | No |
+| 30 | Sheet | Spreadsheet embed | No |
+| 31 | Table | Table | Partial |
+| 32 | TableCell | Table cell | Yes |
+| 33 | View | View embed | No |
+| 34 | Undefined | Unknown type | No |
+| 35 | QuoteContainer | Quote container | No |
+| 36 | Task | Lark Tasks integration | No |
+| 37 | OKR | OKR integration | No |
+| 38 | OKRObjective | OKR objective | No |
+| 39 | OKRKeyResult | OKR key result | No |
+| 40 | OKRProgress | OKR progress | No |
+| 41 | AddOns | Add-ons block | No |
+| 42 | JiraIssue | Jira issue embed | No |
+| 43 | WikiCatalog | Wiki catalog | No |
+| 44 | Board | Board embed | No |
+| 45 | Agenda | Agenda block | No |
+| 46 | AgendaItem | Agenda item | No |
+| 47 | AgendaItemTitle | Agenda item title | No |
+| 48 | SyncedBlock | Synced block reference | No |
+
+## Editing Guidelines
+
+### Text-based blocks (2-17, 19)
+
+Update text content using `feishu_doc_update_block`:
+
+```json
+{
+  "doc_token": "ABC123",
+  "block_id": "block_xxx",
+  "content": "New text content"
+}
+```
+
+### Image blocks (27)
+
+Images cannot be updated directly via `update_block`. Use `feishu_doc_write` or `feishu_doc_append` with markdown to add new images.
+
+### Table blocks (31)
+
+**Important:** Table blocks CANNOT be created via the `documentBlockChildren.create` API (error 1770029). This affects `feishu_doc_write` and `feishu_doc_append` - markdown tables will be skipped with a warning.
+
+Tables can only be read (via `list_blocks`) and individual cells (type 32) can be updated, but new tables cannot be inserted programmatically via markdown.
+
+### Container blocks (24, 25, 35)
+
+Grid and QuoteContainer are layout containers. Edit their child blocks instead.
+
+## Common Patterns
+
+### Replace specific paragraph
+
+1. `feishu_doc_list_blocks` - find the block_id
+2. `feishu_doc_update_block` - update its content
+
+### Insert content at specific location
+
+Currently, the API only supports appending to document end. For insertion at specific positions, consider:
+1. Read existing content
+2. Delete affected blocks
+3. Rewrite with new content in desired order
+
+### Delete multiple blocks
+
+Blocks must be deleted one at a time. Delete child blocks before parent containers.

package/skills/feishu-drive/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: feishu-drive
+description: |
+  Feishu cloud storage file management. Activate when user mentions cloud space, folders, drive.
+---
+
+# Feishu Drive Tool
+
+Single tool `feishu_drive` for cloud storage operations.
+
+## Token Extraction
+
+From URL `https://xxx.feishu.cn/drive/folder/ABC123` → `folder_token` = `ABC123`
+
+## Actions
+
+### List Folder Contents
+
+```json
+{ "action": "list" }
+```
+
+Root directory (no folder_token).
+
+```json
+{ "action": "list", "folder_token": "fldcnXXX" }
+```
+
+Returns: files with token, name, type, url, timestamps.
+
+### Get File Info
+
+```json
+{ "action": "info", "file_token": "ABC123", "type": "docx" }
+```
+
+Searches for the file in the root directory. Note: file must be in root or use `list` to browse folders first.
+
+`type`: `doc`, `docx`, `sheet`, `bitable`, `folder`, `file`, `mindnote`, `shortcut`
+
+### Create Folder
+
+```json
+{ "action": "create_folder", "name": "New Folder" }
+```
+
+In parent folder:
+```json
+{ "action": "create_folder", "name": "New Folder", "folder_token": "fldcnXXX" }
+```
+
+### Move File
+
+```json
+{ "action": "move", "file_token": "ABC123", "type": "docx", "folder_token": "fldcnXXX" }
+```
+
+### Delete File
+
+```json
+{ "action": "delete", "file_token": "ABC123", "type": "docx" }
+```
+
+## File Types
+
+| Type | Description |
+|------|-------------|
+| `doc` | Old format document |
+| `docx` | New format document |
+| `sheet` | Spreadsheet |
+| `bitable` | Multi-dimensional table |
+| `folder` | Folder |
+| `file` | Uploaded file |
+| `mindnote` | Mind map |
+| `shortcut` | Shortcut |
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      drive: true  # default: true
+```
+
+## Permissions
+
+- `drive:drive` - Full access (create, move, delete)
+- `drive:drive:readonly` - Read only (list, info)
+
+## Known Limitations
+
+- **Bots have no root folder**: Feishu bots use `tenant_access_token` and don't have their own "My Space". The root folder concept only exists for user accounts. This means:
+  - `create_folder` without `folder_token` will fail (400 error)
+  - Bot can only access files/folders that have been **shared with it**
+  - **Workaround**: User must first create a folder manually and share it with the bot, then bot can create subfolders inside it

package/skills/feishu-perm/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: feishu-perm
+description: |
+  Feishu permission management for documents and files. Activate when user mentions sharing, permissions, collaborators.
+---
+
+# Feishu Permission Tool
+
+Single tool `feishu_perm` for managing file/document permissions.
+
+## Actions
+
+### List Collaborators
+
+```json
+{ "action": "list", "token": "ABC123", "type": "docx" }
+```
+
+Returns: members with member_type, member_id, perm, name.
+
+### Add Collaborator
+
+```json
+{ "action": "add", "token": "ABC123", "type": "docx", "member_type": "email", "member_id": "user@example.com", "perm": "edit" }
+```
+
+### Remove Collaborator
+
+```json
+{ "action": "remove", "token": "ABC123", "type": "docx", "member_type": "email", "member_id": "user@example.com" }
+```
+
+## Token Types
+
+| Type | Description |
+|------|-------------|
+| `doc` | Old format document |
+| `docx` | New format document |
+| `sheet` | Spreadsheet |
+| `bitable` | Multi-dimensional table |
+| `folder` | Folder |
+| `file` | Uploaded file |
+| `wiki` | Wiki node |
+| `mindnote` | Mind map |
+
+## Member Types
+
+| Type | Description |
+|------|-------------|
+| `email` | Email address |
+| `openid` | User open_id |
+| `userid` | User user_id |
+| `unionid` | User union_id |
+| `openchat` | Group chat open_id |
+| `opendepartmentid` | Department open_id |
+
+## Permission Levels
+
+| Perm | Description |
+|------|-------------|
+| `view` | View only |
+| `edit` | Can edit |
+| `full_access` | Full access (can manage permissions) |
+
+## Examples
+
+Share document with email:
+```json
+{ "action": "add", "token": "doxcnXXX", "type": "docx", "member_type": "email", "member_id": "alice@company.com", "perm": "edit" }
+```
+
+Share folder with group:
+```json
+{ "action": "add", "token": "fldcnXXX", "type": "folder", "member_type": "openchat", "member_id": "oc_xxx", "perm": "view" }
+```
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      perm: true  # default: false (disabled)
+```
+
+**Note:** This tool is disabled by default because permission management is a sensitive operation. Enable explicitly if needed.
+
+## Permissions
+
+Required: `drive:permission`

package/skills/feishu-wiki/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: feishu-wiki
+description: |
+  Feishu knowledge base navigation. Activate when user mentions knowledge base, wiki, or wiki links.
+---
+
+# Feishu Wiki Tool
+
+Single tool `feishu_wiki` for knowledge base operations.
+
+## Token Extraction
+
+From URL `https://xxx.feishu.cn/wiki/ABC123def` → `token` = `ABC123def`
+
+## Actions
+
+### List Knowledge Spaces
+
+```json
+{ "action": "spaces" }
+```
+
+Returns all accessible wiki spaces.
+
+### List Nodes
+
+```json
+{ "action": "nodes", "space_id": "7xxx" }
+```
+
+With parent:
+```json
+{ "action": "nodes", "space_id": "7xxx", "parent_node_token": "wikcnXXX" }
+```
+
+### Get Node Details
+
+```json
+{ "action": "get", "token": "ABC123def" }
+```
+
+Returns: `node_token`, `obj_token`, `obj_type`, etc. Use `obj_token` with `feishu_doc` to read/write the document.
+
+### Create Node
+
+```json
+{ "action": "create", "space_id": "7xxx", "title": "New Page" }
+```
+
+With type and parent:
+```json
+{ "action": "create", "space_id": "7xxx", "title": "Sheet", "obj_type": "sheet", "parent_node_token": "wikcnXXX" }
+```
+
+`obj_type`: `docx` (default), `sheet`, `bitable`, `mindnote`, `file`, `doc`, `slides`
+
+### Move Node
+
+```json
+{ "action": "move", "space_id": "7xxx", "node_token": "wikcnXXX" }
+```
+
+To different location:
+```json
+{ "action": "move", "space_id": "7xxx", "node_token": "wikcnXXX", "target_space_id": "7yyy", "target_parent_token": "wikcnYYY" }
+```
+
+### Rename Node
+
+```json
+{ "action": "rename", "space_id": "7xxx", "node_token": "wikcnXXX", "title": "New Title" }
+```
+
+## Wiki-Doc Workflow
+
+To edit a wiki page:
+
+1. Get node: `{ "action": "get", "token": "wiki_token" }` → returns `obj_token`
+2. Read doc: `feishu_doc { "action": "read", "doc_token": "obj_token" }`
+3. Write doc: `feishu_doc { "action": "write", "doc_token": "obj_token", "content": "..." }`
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      wiki: true  # default: true
+      doc: true   # required - wiki content uses feishu_doc
+```
+
+**Dependency:** This tool requires `feishu_doc` to be enabled. Wiki pages are documents - use `feishu_wiki` to navigate, then `feishu_doc` to read/edit content.
+
+## Permissions
+
+Required: `wiki:wiki` or `wiki:wiki:readonly`