220 lines
4.6 KiB
Markdown
Executable File
220 lines
4.6 KiB
Markdown
Executable File
---
|
|
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.
|