Skill: kari-code/ka (version 1.0.0)

--- 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, including table creation for Docx. ## 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", "owner_open_id": "ou_xxx" } ``` With folder: ```json { "action": "create", "title": "New Document", "folder_token": "fldcnXXX", "owner_open_id": "ou_xxx" } ``` **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. ### 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" } ``` ### 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 ``` **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`

path: references/block-types.md
content: # 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.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)