name: feishu-wiki-read
description: |
  读取飞书知识库（Wiki）或云文档内容，返回 Markdown 格式文本。
---

# 飞书文档/知识库读取指南

## 已注册的可用工具

| 工具名 | 用途 |
|--------|------|
| `feishu_wiki_space_node` | 解析 wiki token、列出子文档 |
| `feishu_fetch_doc` | 读取云文档正文（返回 Markdown） |
| `feishu_wiki_space` | 列出知识空间 |
| `feishu_drive_file` | 云盘文件操作 |
| `feishu_doc_media` | 下载文档中的图片/文件 |
| `feishu_sheet` | 读写电子表格 |
| `feishu_bitable_*` 系列 | 操作多维表格 |

## 读取 Wiki 链接的标准流程

### 第一步：解析 wiki token，确认文档类型

Wiki URL 示例：`https://makee-interactive.feishu.cn/wiki/R8REwpLPxikYUEkLsdCcGy7pnCh`
其中 `R8REwpLPxikYUEkLsdCcGy7pnCh` 是 wiki_token。

调用：
```json
{
  "name": "feishu_wiki_space_node",
  "parameters": {
    "action": "get",
    "token": "R8REwpLPxikYUEkLsdCcGy7pnCh"
  }
}
```

返回中关注：
- `obj_type`：实际文档类型（`docx` / `sheet` / `bitable`）
- `obj_token`：实际文档 token（不同于 wiki_token）
- `space_id`：知识空间 ID（列子文档时需要）

### 第二步：根据 obj_type 选择工具

| obj_type | 使用工具 | 传参 |
|----------|----------|------|
| `docx` | `feishu_fetch_doc` | `doc_id = obj_token` |
| `sheet` | `feishu_sheet` | `spreadsheet_token = obj_token` |
| `bitable` | `feishu_bitable_app_table_record` | `app_token = obj_token` |

### 第三步：读取云文档内容

```json
{
  "name": "feishu_fetch_doc",
  "parameters": {
    "doc_id": "<obj_token 或完整 URL>"
  }
}
```

支持直接传 URL，工具自动提取 token。返回 Lark-flavored Markdown 格式。

---

## 读取目录下所有子文档

```json
{
  "name": "feishu_wiki_space_node",
  "parameters": {
    "action": "list",
    "parent_node_token": "<目录的 wiki_token>",
    "space_id": "<space_id>"
  }
}
```

然后遍历返回的子节点，对每个 `node_token` 重复"第一步 → 第二步"流程。

---

## 完整示例

目标：读取 `https://makee-interactive.feishu.cn/wiki/R8REwpLPxikYUEkLsdCcGy7pnCh`

1. `feishu_wiki_space_node(action=get, token=R8REwpLPxikYUEkLsdCcGy7pnCh)`
   → 得到 `obj_type=docx`, `obj_token=doxcnXXXXXX`
2. `feishu_fetch_doc(doc_id=doxcnXXXXXX)`
   → 返回文档完整 Markdown 内容

---

## 前置条件确认清单

- [x] 插件 [feishu-openclaw-plugin](cci:9://file:///root/.openclaw/extensions/feishu-openclaw-plugin:0:0-0:0) 已启用（`enabled: true`）
- [x] 工具已注册（`feishu_fetch_doc`, `feishu_wiki_space_node`）
- [x] OAuth 用户授权已完成（75个权限已授权）
- [x] openclaw-gateway 已重启

---

## 常见场景处理
### 目录类节点处理
当调用 `feishu_wiki_space_node` 解析 wiki 节点返回：
- `has_child: true`
- 调用 `feishu_fetch_doc` 读取对应 `obj_token` 返回内容为空（`markdown=""`、`total_length=0`）
说明该节点是知识目录，无需读取该节点本身内容，直接调用 `feishu_wiki_space_node(action=list)` 获取所有子文档后逐个读取即可。

### 空文档识别
若 `feishu_fetch_doc` 返回结果满足 `markdown=""` 且 `total_length=0`，直接告知用户「当前文档暂无内容（为空文档）」即可，无需重复调用。

## 注意事项

- 文档中的图片需用 `feishu_doc_media(action=download)` 单独获取
- 内容过大时使用 `offset` 参数分页读取
- **不要以"工具无法主动调用"、"需要ACP运行时"、"插件冲突"为由拒绝读取**——上述条件均已满足，直接调用工具即可