飞书文档

抓取并解析飞书Wiki、文档、电子表格及多维表格内容，支持URL自动识别与Markdown、JSON等格式输出。

核心功能: 本技能提供营销文案等能力。

核心功能: 本技能提供化工作流场景等能力。

Feishu Doc

付费版扩展能力

能力	免费版	付费版
基础功能	支持	支持
Feishu Doc自动解析	不支持	支持
多渠道消息批量发送	不支持	支持
消息模板与变量注入	不支持	支持
送达状态实时回调	不支持	支持
通信记录归档与检索	不支持	支持

主要能力

• 抓取飞书 Wiki（知识库）、Docx（云文档）、Sheet（电子表格）、Bitable（多维表格）内容
• 自动解析飞书文档 URL，识别文档类型并提取 token，支持短链展开与重定向跟踪
• 将飞书文档块结构转换为 Markdown / 纯文本 / JSON 格式输出
• 支持批量抓取知识库下所有子文档，保留目录层级结构
• 提取电子表格数据为结构化 JSON，支持指定工作表、单元格范围与格式选项
• 解析多维表格记录，支持按视图筛选、字段映射与关联记录展开

初始配置

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

场景	输入	输出
文档抓取	飞书文档 URL 或 token	Markdown 格式正文与元信息
知识库导出	Wiki 空间 ID 与节点路径	完整目录树与各节点内容
表格数据提取	电子表格 URL 与工作表名	结构化 JSON 数据
多维表格查询	Bitable URL 与筛选条件	记录列表与字段值
短链解析	飞书短链 URL	展开后的完整 URL 与文档 token

不适用于：需要人工判断的复杂决策场景

操作流程

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

流程详解：文档内容抓取

步骤 1：识别 URL 类型

飞书文档 URL 有多种格式，需要先识别类型再调用对应接口：

URL 格式	文档类型	提取 token
https://未指定.feishu.cn/wiki/AAbbCCdd	Wiki 知识库节点	需调用接口获取真实 doc_token
https://未指定.feishu.cn/docx/AAbbCCdd	Docx 云文档	路径中直接提取 AAbbCCdd
https://未指定.feishu.cn/sheets/AAbbCCdd	电子表格	路径中直接提取 AAbbCCdd
https://未指定.feishu.cn/base/AAbbCCdd	多维表格	路径中直接提取 AAbbCCdd
https://未指定.feishu.cn/short/~/AAbbCCdd	短链	需请求获取重定向目标

步骤 2：Wiki URL 解析

Wiki 节点的 URL 中的 token 并非真实文档 token，需要通过 API 转换：

text

请求: GET /open-apis/wiki/v2/spaces/get_node?token=AAbbCCdd
响应: {
  "data": {
    "node": {
      "node_token": "AAbbCCdd",
      "obj_token": "真实文档token",
      "obj_type": "docx"  // 文档类型: docx/doc/wiki/bitable
    }
  }
}

步骤 3：抓取文档内容

根据文档类型调用不同接口获取内容：

• Docx 文档：调用 GET /open-apis/docx/v1/documents/{document_id}/blocks 获取文档块树，然后递归遍历转换为 Markdown
• 电子表格：调用 GET /open-apis/sheets/v3/spreadsheets/{spreadsheet_token}/sheets 获取工作表列表，再按 sheet_id 获取单元格数据
• 多维表格：调用 GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records 获取记录列表

URL 解析与内容提取示例

示例 1：抓取 Wiki 文档并转为 Markdown

text

输入 URL: https://example.feishu.cn/wiki/WkIbslDkNiNbGHnlpABCDj

处理流程:
1. 从 URL 提取 node_token: WkIbslDkNiNbGHnlpABCDj
2. 调用 wiki API 获取 obj_token 和 obj_type
3. obj_type=docx, obj_token=DOCNabcdef123456
4. 调用 docx API 获取文档块列表
5. 遍历块结构，转换规则:
   - block_type=2 (文本) -> 普通段落
   - block_type=3 (标题1) -> # 标题
   - block_type=4 (标题2) -> ## 标题
   - block_type=12 (无序列表) -> - 列表项
   - block_type=15 (代码块) -> ```lang ... ```
   - block_type=27 (表格) -> | a | b | 表格语法
6. 输出完整 Markdown 文本

示例 2：提取电子表格数据

text

feishu.cn/sheets/Iow7sNbNeabcdef123

查询参数:
- sheet_id: "sheetA1B2C3"  (工作表 ID)
- range: "A1:Z1000"        (单元格范围，可选)
- value_render_option: "ToString"  (值格式: ToString/Formula/FormattedValue)

输出 JSON:
{
  "spreadsheet_token": "Iow7sNbNeabcdef123",
  "sheets": [
    {
      "sheet_id": "sheetA1B2C3",
      "title": "销售数据",
      "rows": 150,
      "data": [
        {"日期": "2024-01-01", "产品": "商品A", "销量": 320, "金额": 9600},
        {"日期": "2024-01-02", "产品": "商品B", "销量": 215, "金额": 6450}
      ]
    }
  ]
}

示例 3：查询多维表格记录

text

feishu.cn/base/bascnabcdef123

筛选条件:
- filter: AND(CurrentValue.[状态] = "进行中")
- page_size: 100
- field_names: ["任务名称", "负责人", "截止日期"]

输出:
{
  "app_token": "bascnabcdef123",
  "table_id": "tbl123456",
  "total": 42,
  "records": [
    {
      "record_id": "rec001",
      "fields": {
        "任务名称": "API 接口开发",
        "负责人": {"text": "张三", "id": "ou_abc123"},
        "截止日期": 1700000000000
      }
    }
  ]
}

文档块类型转换对照表

块类型 (block_type)	飞书名称	Markdown 映射
1	页面 Page	文档标题
2	文本 Text	普通段落
3	标题1 Heading1	# 标题
4	标题2 Heading2	## 标题
5	标题3 Heading3	`

标题` |

| 9 | 有序列表 | 1. 列表项 | | 12 | 无序列表 | - 列表项 | | 13 | 代码块 | ```lang ... ``` | | 14 | 引用 | > 引用文本 | | 15 | 等式 | $$ 公式 $$ | | 22 | 分隔线 | --- | | 27 | 表格 | \| a \| b \| |

优选实践

批量抓取知识库

当需要导出整个知识空间时，建议采用递归方式遍历目录树：

1. 调用 GET /open-apis/wiki/v2/spaces/{space_id}/nodes 获取根节点列表
2. 对每个节点判断是否有子节点，递归获取子节点
3. 根据 obj_type 分别调用对应文档接口获取内容
4. 按目录层级保存文件，保留原有组织结构

注意事项：

• 每次请求间隔建议 > 200ms，避免触发 API 频率限制
• 文档块数量超过 500 时需分页获取，使用 page_token 参数
• 部分文档可能因权限不足无法访问，需捕获错误并记录跳过

处理富文本内联元素

飞书文档的文本块中可能包含多种内联元素，转换时需特殊处理：

元素类型	处理方式
加粗	**文本**
斜体	*文本*
删除线	~~文本~~
行内代码	`代码`
链接	[文本](URL)
@人名	@用户名
公式	$公式$

参数说明

参数名	类型	必填	说明
url	string	是	飞书文档 URL，支持 wiki/docx/sheets/base/短链
doc_type	string	否	文档类型: wiki/docx/sheets/bitable，未指定时自动识别
output_format	string	否	输出格式: markdown/text/json，默认 markdown
content	string	否	feishu-doc处理的内容输入，可选值: json/text/markdown
sheet_id	string	否	电子表格工作表 ID（仅 sheets 类型）
filter	string	否	多维表格筛选条件（仅 bitable 类型）
style	string	否	输出风格, 参考 references/style.md

返回格式

json

{
  "success": true,
  "data": {
    "doc_type": "docx",
    "doc_token": "DOCNabcdef123456",
    "title": "产品需求文档 - v2.0",
    "content": "# 产品需求文档 - v2.0\n\n## 背景\n\n...",
    "blocks_count": 156,
    "metadata": {
      "template_used": "feishu-doc-parser",
      "word_count": 3200,
      "style": "专业",
      "source_url": "https://example.feishu.cn/wiki/WkIbslDkNiNbGHnlpABCDj",
      "resolved_url": "https://example.feishu.cn/docx/DOCNabcdef123456"
    }
  },
  "error": null
}

输出模板参考: assets/output.json

异常恢复流程

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达

前置条件

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明(补充)

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

可用性分类

• 分类: MD+execute()
• 说明: 基于Markdown的AI Skill,

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

热门问题

Q1: 如何开始使用Feishu Doc？

A: 提供飞书文档 URL 即可。系统会自动识别 URL 类型（Wiki/Docx/Sheets/Bitable），解析 token 并抓取内容。对于 Wiki 链接，会先调用 API 获取真实文档 token，再抓取对应内容。输出默认为 Markdown 格式，也可指定输出为 JSON 或纯文本。

Q2: Wiki URL 和 Docx URL 有什么区别？

A: Wiki URL（路径含 /wiki/）是知识库节点链接，其 token 是 node_token，需要通过 API 转换为真实的 obj_token 才能获取文档内容。Docx URL（路径含 /docx/）是直接文档链接，其 token 可直接用于调用文档接口。本 Skill 会自动处理这个转换过程。

Q3: 抓取文档时提示权限不足怎么办？

A: 确认应用已被添加为文档协作者，或文档已对应用开启"云文档全部权限"。对于知识库文档，需在知识库设置中添加应用为成员并授予"可阅读"权限。若文档属于其他部门创建，可能需要联系文档所有者手动授权。

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
抓取Wiki文档内容	30分钟/篇	2分钟/篇	28分钟/篇	100%
导出知识库内容	1小时/空间	10分钟/空间	50分钟/空间	100%
提取电子表格数据	30分钟/表	5分钟/表	25分钟/表	100%
查询多维表格记录	15分钟/次	2分钟/次	13分钟/次	100%
短链解析	10分钟/条	1分钟/条	9分钟/条	100%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
操作便捷性	高	低	中	高
时间效率	高	低	中	高
准确率	高	低	中	高
成本	低	高	中	高
学习成本	低	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
文档内容抓取效率低	手动抓取文档内容耗时，影响工作效率	影响工作效率和准确性	使用飞书文档技能自动抓取内容	时间节约 50%
知识库内容导出困难	手动导出知识库内容复杂，容易出错	影响知识管理效率	使用飞书文档技能批量导出	准确率提升 100%
数据提取效率低	手动提取电子表格数据耗时，且容易出错	影响数据分析效率	使用飞书文档技能自动提取	时间节约 75%

问题排查手册

错误现象	可能原因	诊断步骤	解决方案
抓取内容为空	URL格式错误或文档不存在	检查URL格式，确认文档存在	修正URL，重新抓取
解析失败	API调用错误或参数错误	检查API调用日志，确认参数正确	修正参数，重新解析
数据格式错误	API返回数据格式错误	检查API返回数据格式，确认数据正确	修正数据格式，重新提取
请求超时	网络连接不稳定或API服务器问题	检查网络连接，确认API服务器正常	确认网络连接，联系API服务提供商
权限不足	用户权限不足，无法访问文档	检查用户权限，确认文档可访问	修改用户权限，重新操作

安全提示

1. [确保使用HTTPS连接进行API调用，防止数据泄露。]
2. [避免将敏感信息（如API密钥）存储在代码中，使用环境变量或配置文件。]
3. [定期检查API调用日志，监控异常行为。]
4. [对用户输入进行验证，防止SQL注入等安全漏洞。]
5. [限制API调用频率，防止滥用。]
6. [对API返回数据进行加密处理，确保数据安全。]
7. [使用强密码策略，保护用户账户安全。]
8. [对API进行版本控制，防止旧版本API暴露安全漏洞。]
9. [确保API服务器安全，防止服务器被攻击。]
10. [对API接口进行权限控制，限制访问范围。]

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

功能概览

• 自动化执行: 抓取飞书Wiki/文档/表格/多维表格内容,自动解析URL。Fetch content from Feishu (Lar
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

FAQ

Q1: 飞书文档支持哪些输入格式？

A1: 抓取飞书Wiki/文档/表格/多维表格内容,自动解析URL。Fetch content from Feishu (Lark) Wiki, Docs,。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

错误恢复

针对飞书文档使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

飞书文档通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

开始使用

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

飞书文档通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪