---
name: feishu-doc
description: Read, create, append, replace, and structurally edit Feishu Docx documents with the feishu_doc tool. Use when Codex needs to work with Feishu docs, cloud docs, docx links, document blocks, tables, images, or file attachments in Feishu/Lark documents.
---

# Feishu Doc

Use the `feishu_doc` tool for Feishu Docx operations.

If the current environment does not expose `feishu_doc`, tell the user that the required tool is unavailable and stop instead of inventing a workaround.

## Extract the doc token

Extract `doc_token` from the document URL.

Example:

- `https://xxx.feishu.cn/docx/ABC123def` -> `ABC123def`

## Start with the right workflow

Choose the lightest workflow that fits the request.

### Read a document

1. Call `{"action":"read","doc_token":"..."}` first.
2. Inspect `hint`, `block_types`, and summary fields in the response.
3. If the document contains structured content such as tables or images, call `{"action":"list_blocks","doc_token":"..."}`.
4. Use `get_block` only when a single block needs closer inspection.

### Replace or append text content

Use markdown-oriented actions for plain document content:

- `write`: replace the entire document
- `append`: append content to the end

Use markdown for headings, lists, code blocks, quotes, links, and images.

Do not rely on markdown tables. Use table actions instead.

### Perform block-level edits

Use these actions when the user wants targeted updates instead of full-document replacement:

- `list_blocks`
- `get_block`
- `update_block`
- `delete_block`

Prefer block-level edits when preserving surrounding content matters.

## Core actions

### Read

```json
{ "action": "read", "doc_token": "ABC123def" }
```

### Write the whole document

```json
{ "action": "write", "doc_token": "ABC123def", "content": "# Title\n\nMarkdown content..." }
```

### Append content

```json
{ "action": "append", "doc_token": "ABC123def", "content": "Additional content" }
```

### Create a document

Always pass the requesting user's `open_id` as `owner_open_id` when available so the user automatically gets access to the new document.

```json
{ "action": "create", "title": "New Document", "owner_open_id": "ou_xxx" }
```

With a folder:

```json
{
  "action": "create",
  "title": "New Document",
  "folder_token": "fldcnXXX",
  "owner_open_id": "ou_xxx"
}
```

### Inspect or edit blocks

```json
{ "action": "list_blocks", "doc_token": "ABC123def" }
```

```json
{ "action": "get_block", "doc_token": "ABC123def", "block_id": "doxcnXXX" }
```

```json
{
  "action": "update_block",
  "doc_token": "ABC123def",
  "block_id": "doxcnXXX",
  "content": "New text"
}
```

```json
{ "action": "delete_block", "doc_token": "ABC123def", "block_id": "doxcnXXX" }
```

## Tables

Use table actions for real Docx tables.

### Create an empty table

```json
{
  "action": "create_table",
  "doc_token": "ABC123def",
  "row_size": 2,
  "column_size": 2,
  "column_width": [200, 200]
}
```

Optional: include `parent_block_id` to insert under a specific block.

### Fill table cells

```json
{
  "action": "write_table_cells",
  "doc_token": "ABC123def",
  "table_block_id": "doxcnTABLE",
  "values": [
    ["A1", "B1"],
    ["A2", "B2"]
  ]
}
```

### Create and fill a table in 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"]
  ]
}
```

## Images and file attachments

### Upload an image

Use exactly one of `url` or `file_path`.

```json
{
  "action": "upload_image",
  "doc_token": "ABC123def",
  "url": "https://example.com/image.png"
}
```

```json
{
  "action": "upload_image",
  "doc_token": "ABC123def",
  "file_path": "/tmp/image.png",
  "parent_block_id": "doxcnParent",
  "index": 5
}
```

For small images, scale the asset before uploading so it displays at a useful size in the document.

### Upload a file attachment

Use exactly one of `url` or `file_path`.

```json
{
  "action": "upload_file",
  "doc_token": "ABC123def",
  "url": "https://example.com/report.pdf"
}
```

```json
{
  "action": "upload_file",
  "doc_token": "ABC123def",
  "file_path": "/tmp/report.pdf",
  "filename": "Q1-report.pdf"
}
```

Optional: include `parent_block_id`.

## Operating rules

- Start with `read` for unfamiliar documents.
- Escalate to `list_blocks` when `read` indicates structured content.
- Use `write` only when replacing the full document is intended.
- Prefer block-level edits when the user asks for localized changes.
- Use table actions instead of markdown tables.
- Preserve the user's access by passing `owner_open_id` on document creation when that identity is available.