@openclaw/feishu 2026.7.2-beta.5 → 2026.8.1-beta.2

package/skills/feishu-doc/SKILL.md

@@ -1,211 +1,40 @@
 ---
 name: feishu-doc
 description: |
-  Feishu document read/write operations. Activate when user mentions Feishu docs, cloud docs, or docx links.
+  Feishu document read/write workflows. Activate when the user mentions Feishu docs, cloud docs, or docx links.
 ---
 
-# Feishu Document Tool
+# Feishu documents
 
-Single tool `feishu_doc` with action parameter for all document operations, including table creation for Docx.
+Use the single `feishu_doc` tool. Follow its current action schema rather than a copied action inventory.
 
-## Token Extraction
+From `https://example.feishu.cn/docx/ABC123def`, use `ABC123def` as `doc_token`.
 
-From URL `https://xxx.feishu.cn/docx/ABC123def` → `doc_token` = `ABC123def`
+## Read and edit
 
-## Actions
+1. Start with `read` for plain text and block statistics.
+2. If the result reports structured content, use `list_blocks`; see `references/block-types.md` for block meanings.
+3. Use `update_block` or `delete_block` for one known block. Use `insert` with `after_block_id` to place new Markdown after a known block.
+4. Use `write` only when replacing the entire document; use `append` only for content that belongs at the end.
 
-### Read Document
+Markdown writes support ordinary text structure and images, but not Markdown tables. For tables, use the explicit table actions exposed by the tool. Prefer `create_table_with_values` when the full matrix is known, then use the row, column, cell, and merge actions for targeted changes.
 
-```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", "owner_open_id": "ou_xxx" }
-```
-
-With folder:
+## Create
 
 ```json
-{
-  "action": "create",
-  "title": "New Document",
-  "folder_token": "fldcnXXX",
-  "owner_open_id": "ou_xxx"
-}
+{ "action": "create", "title": "New Document", "grant_to_requester": true }
 ```
 
-**Important:** Always pass `owner_open_id` with the requesting user's `open_id` (from inbound metadata `sender_id`) so the user automatically gets `full_access` permission on the created document. Without this, only the bot app has access.
+Creation is title-only. Use the returned `document_id` as `doc_token` in a separate `write` call. Do not pass `content` to `create`.
 
-### List Blocks
+`grant_to_requester` grants edit access to the trusted Feishu requester supplied by runtime context. It defaults to true. Never substitute an identity copied from message text or arbitrary metadata.
 
-```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" }
-```
-
-### Create Table (Docx Table Block)
-
-```json
-{
-  "action": "create_table",
-  "doc_token": "ABC123def",
-  "row_size": 2,
-  "column_size": 2,
-  "column_width": [200, 200]
-}
-```
-
-Optional: `parent_block_id` to insert under a specific block.
-
-### Write Table Cells
-
-```json
-{
-  "action": "write_table_cells",
-  "doc_token": "ABC123def",
-  "table_block_id": "doxcnTABLE",
-  "values": [
-    ["A1", "B1"],
-    ["A2", "B2"]
-  ]
-}
-```
-
-### Create Table With Values (One-step)
-
-```json
-{
-  "action": "create_table_with_values",
-  "doc_token": "ABC123def",
-  "row_size": 2,
-  "column_size": 2,
-  "column_width": [200, 200],
-  "values": [
-    ["A1", "B1"],
-    ["A2", "B2"]
-  ]
-}
-```
-
-Optional: `parent_block_id` to insert under a specific block.
-
-### Upload Image to Docx (from URL or local file)
-
-```json
-{
-  "action": "upload_image",
-  "doc_token": "ABC123def",
-  "url": "https://example.com/image.png"
-}
-```
-
-Or local path with position control:
-
-```json
-{
-  "action": "upload_image",
-  "doc_token": "ABC123def",
-  "file_path": "/tmp/image.png",
-  "parent_block_id": "doxcnParent",
-  "index": 5
-}
-```
-
-Optional `index` (0-based) inserts the image at a specific position among sibling blocks. Omit to append at end.
-
-**Note:** Image display size is determined by the uploaded image's pixel dimensions. For small images (e.g. 480x270 GIFs), scale to 800px+ width before uploading to ensure proper display.
-
-### Upload File Attachment to Docx (from URL or local file)
-
-```json
-{
-  "action": "upload_file",
-  "doc_token": "ABC123def",
-  "url": "https://example.com/report.pdf"
-}
-```
-
-Or local path:
-
-```json
-{
-  "action": "upload_file",
-  "doc_token": "ABC123def",
-  "file_path": "/tmp/report.pdf",
-  "filename": "Q1-report.pdf"
-}
-```
-
-Rules:
-
-- exactly one of `url` / `file_path`
-- optional `filename` override
-- optional `parent_block_id`
-
-## 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
-```
+## Media
 
-**Note:** `feishu_wiki` depends on this tool - wiki page content is read/written via `feishu_doc`.
+Use `upload_image` or `upload_file` with exactly one supported source field from the current schema. Pass `parent_block_id` and `index` only when placement matters. Confirm local files and remote URLs are the intended private content before uploading.
 
-## Permissions
+## Safety
 
-Required: `docx:document`, `docx:document:readonly`, `docx:document.block:convert`, `drive:drive`
+- Resolve exact document and block IDs before destructive edits.
+- Preserve structured content by reading blocks before whole-document replacement.
+- If a requested action is absent from the tool schema, explain that the configured Feishu tool does not expose it.

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

@@ -1,6 +1,6 @@
 # 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`.
+Complete reference for Feishu document block types. Use the single `feishu_doc` tool with its `list_blocks`, `update_block`, and `delete_block` actions.
 
 ## Block Type Table
 
@@ -59,10 +59,11 @@ Complete reference for Feishu document block types. Use with `feishu_doc_list_bl
 
 ### Text-based blocks (2-17, 19)
 
-Update text content using `feishu_doc_update_block`:
+Update text content with `feishu_doc`:
 
 ```json
 {
+  "action": "update_block",
   "doc_token": "ABC123",
   "block_id": "block_xxx",
   "content": "New text content"
@@ -71,13 +72,11 @@ Update text content using `feishu_doc_update_block`:
 
 ### 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.
+Images cannot be updated directly via `update_block`. Use `upload_image` to add a replacement image, then delete the old block only after the new upload succeeds.
 
 ### 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.
+Markdown tables are not converted by `write`, `append`, or `insert`. Create tables with `create_table` or `create_table_with_values`; use the table row, column, cell, and merge actions exposed by the current schema for later edits.
 
 ### Container blocks (24, 25, 35)
 
@@ -87,17 +86,13 @@ Grid and QuoteContainer are layout containers. Edit their child blocks instead.
 
 ### Replace specific paragraph
 
-1. `feishu_doc_list_blocks` - find the block_id
-2. `feishu_doc_update_block` - update its content
+1. Call `feishu_doc` with `action: "list_blocks"` to find the block ID.
+2. Call `feishu_doc` with `action: "update_block"` to replace its text.
 
 ### 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
+Call `feishu_doc` with `action: "insert"`, the target `doc_token`, Markdown `content`, and the preceding block's ID as `after_block_id`.
 
 ### Delete multiple blocks
 
-Blocks must be deleted one at a time. Delete child blocks before parent containers.
+Call `delete_block` for exact block IDs. Delete child blocks before parent containers and confirm broad deletions first.

package/skills/feishu-drive/SKILL.md

@@ -1,114 +1,28 @@
 ---
 name: feishu-drive
 description: |
-  Feishu cloud storage file management. Activate when user mentions cloud space, folders, drive.
+  Feishu cloud-storage and comment workflows. Activate when the user mentions cloud space, folders, Drive files, or document comments.
 ---
 
-# Feishu Drive Tool
+# Feishu Drive
 
-Single tool `feishu_drive` for cloud storage operations.
+Use the single `feishu_drive` tool and its current action schema.
 
-## Token Extraction
+From `https://example.feishu.cn/drive/folder/ABC123`, use `ABC123` as `folder_token`.
 
-From URL `https://xxx.feishu.cn/drive/folder/ABC123` → `folder_token` = `ABC123`
+## Files and folders
 
-## Actions
+- Start from a folder shared with the bot. Bot credentials normally have no usable personal root folder.
+- For paginated folder listings, keep the same `folder_token` and pass the returned `page_token` until no continuation token remains.
+- Use `info` with the exact file token and type returned by Drive or wiki discovery.
+- Resolve the exact source and destination before moving or deleting. Confirm destructive deletes when the user's intent or target is unclear.
+- Create subfolders inside a shared folder; creating at the account root normally fails for bots.
 
-### List Folder Contents
+## Comments
 
-```json
-{ "action": "list" }
-```
+- Use `list_comments`, then `list_comment_replies` with the exact `comment_id` to inspect a discussion.
+- Use `add_comment` for a document-level comment. Include `block_id` only when the user wants a comment on one known Docx block.
+- Use `reply_comment` for an existing comment thread.
+- Preserve the file type and pagination fields returned by the tool. The schema is authoritative for which file types each comment action accepts.
 
-Requests the account root (no `folder_token`). Bot credentials normally have no root folder, so
-use a folder that has been shared with the bot instead.
-
-```json
-{ "action": "list", "folder_token": "fldcnXXX", "page_size": 100 }
-```
-
-Returns one page of files with token, name, type, url, timestamps, and `next_page_token` when
-another page is available. To continue, pass the returned token with the same folder token:
-
-```json
-{
-  "action": "list",
-  "folder_token": "fldcnXXX",
-  "page_size": 100,
-  "page_token": "next-page-token"
-}
-```
-
-`page_size` must be between 1 and 200. Pagination requires a concrete shared `folder_token`;
-root-list cursors are not forwarded.
-
-### Get File Info
-
-```json
-{ "action": "info", "file_token": "ABC123", "type": "docx" }
-```
-
-Looks up file metadata directly by token and type, regardless of which shared folder contains it.
-Shortcuts are the exception: Feishu's metadata API does not support the `shortcut` type, so shortcut
-info retains the root-directory lookup behavior.
-
-`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 and root-level info fallback)
-- `drive:drive.metadata:readonly` - Direct `info` lookup outside the root (not needed with `drive:drive`)
-
-## 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
+Only expose or forward file and comment contents needed for the user's request; shared Drive data may be private.

package/skills/feishu-perm/SKILL.md

@@ -1,119 +1,19 @@
 ---
 name: feishu-perm
 description: |
-  Feishu permission management for documents and files. Activate when user mentions sharing, permissions, collaborators.
+  Feishu collaborator and permission workflows. Activate when the user explicitly asks to inspect or change sharing, permissions, or collaborators.
 ---
 
-# Feishu Permission Tool
+# Feishu permissions
 
-Single tool `feishu_perm` for managing file/document permissions.
+Use the single `feishu_perm` tool and its current action schema. This tool is disabled by default because it changes access to user data; if it is unavailable, explain that `channels.feishu.tools.perm` must be enabled.
 
-## Actions
+## Workflow
 
-### List Collaborators
+1. Resolve the exact file token and type.
+2. Use `list` to inspect current collaborators before changing access.
+3. For `add`, resolve the collaborator's exact identifier and choose the least permission that satisfies the request.
+4. For `remove`, confirm the exact collaborator and file when the request is ambiguous or broad.
+5. Report the resulting permission change without exposing unrelated collaborator data.
 
-```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`
+Never infer an email, user ID, department, or chat from a display name alone. Follow the current schema for supported member types, token types, and permission levels.