企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• MCP Clients
• 本地部署

本篇技术指南以当前仓库中飞书/OpenClaw 插件技能包内的 feishu-fetch-doc SKILL 文档 为核心，完整讲解如何让 AI Agent 读取飞书云文档的 Markdown 内容、如何识别并下载文档内的图片/文件/画板，以及知识库（Wiki）链接的类型判别与工具路由策略。读完本文，你将掌握feishu_fetch_doc、feishu_doc_media、feishu_wiki_space_node三件工具的正确调用姿势，并能结合插件源码理解其底层实现与配置前提。

feishu-fetch-doc 是什么

feishu-fetch-doc是飞书/OpenClaw 官方插件（feishu-openclaw-plugin）技能包中用于获取飞书云文档内容的 SKILL。其定位非常聚焦：调用底层 MCP 工具feishu_fetch_doc，把一篇飞书云文档（docx）转换为Markdown 格式文本（Lark-flavored）返回给 Agent，供后续阅读、摘要、改写、存档等场景使用。

在插件结构中，SKILL 通过 openclaw.plugin.json 中的"skills": ["./skills"]字段声明并挂载，属于插件交付的"能力说明书"层；真正执行调用的则是src/tools/mcp/doc/fetch.js中注册的 MCP 工具。从源码看，该工具通过飞书官方 MCP 网关（默认https://mcp.feishu.cn/mcp）以 JSON-RPCtools/call方式完成调用，并携带用户级访问令牌（UAT）与X-Lark-MCP-Allowed-Tools请求头做权限约束，见 fetch.js 与 shared.js。

doc_id 参数的三种传法

SKILL 中feishu_fetch_doc只有一个必填参数doc_id，且设计得非常宽容，支持三种写法：

这一设计在源码中得到印证：fetch.js 中FetchDocSchema的doc_id字段描述即为"文档 ID 或 URL（支持自动解析）"。更进一步的实现证据可见 doc-media.js 中的extractDocumentId函数：它通过正则/\/docx\/([A-Za-z0-9]+)/从 URL 中提取document_id，匹配失败时直接返回输入字符串本身——这就是"传 URL 自动提取、传 token 原样使用"的底层逻辑。

此外，feishu_fetch_doc的 schema 还暴露了两个可选分页参数：

• offset（整数，最小 0，默认 0）：字符偏移量，用于大文档分页获取；
• limit（整数，最小 1）：返回的最大字符数，仅在用户明确要求分页时使用。

也就是说，面对超长文档，Agent 不必一次性拉取全部内容，可以配合offset/limit按段读取，避免截断与超时。

重要：文档内的图片、文件、画板需单独下载

SKILL 文档用醒目篇幅强调：feishu_fetch_doc只返回文本化的 Markdown 内容，文档中的图片、文件、画板不会内嵌字节流，而是以 HTML 标签形式出现在返回文本中，必须通过feishu_doc_media（action:download）工具单独获取。

识别三种媒体标签格式

返回的 Markdown 中，媒体资源按以下三种 HTML 标签形态出现：

• 图片：

  <image token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" width="1833" height="2491" align="center"/>

• 文件：

  <view type="1"> <file token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" name="skills.zip"/> </view>

• 画板：

  <whiteboard token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc"/>

Agent 的正确动作是：从标签中提取token属性值，然后调用feishu_doc_media下载。

下载步骤

1. 从 HTML 标签中提取token属性值；
2. 调用feishu_doc_media（action:download）：

   { "action": "download", "resource_token": "提取的token", "resource_type": "media", "output_path": "/path/to/save/file" }

底层实现细节

doc-media.js 对downloadaction 的实现补充了 SKILL 未展开的关键细节，值得 Agent 开发者留意：

• resource_type只有两种取值：media（文档素材：图片、视频、文件等，走drive.v1.media.download接口）和whiteboard（画板，走board.v1.whiteboard.downloadAsImage接口，返回缩略图）。下载画板时应传resource_type: "whiteboard"。
• output_path的扩展名智能补全：如果output_path不带扩展名，工具会根据响应头Content-Type自动追加扩展名（内置MIME_TO_EXT映射表覆盖 png/jpg/gif/webp/mp4/pdf/doc/xls/ppt/zip/txt/json 等常见类型）；画板类型无 MIME 时默认补.png。例如output_path: "/tmp/avatar"可能实际保存为/tmp/avatar.png，返回结果中的saved_path字段会给出最终路径。
• 下载完成后返回size_bytes、content_type、saved_path等字段，便于 Agent 校验与引用。
• 对应地，该工具还支持insertaction（在文档末尾插入本地图片/文件，单文件最大 20MB），与下载形成闭环，但 SKILL 本次仅涉及download。

Wiki URL 处理策略：先判型，再路由

知识库链接（/wiki/TOKEN）背后可能指向云文档、电子表格、多维表格等不同类型的对象。SKILL 明确告诫：当不确定类型时，不能直接假设是云文档（docx），必须先查询实际类型——否则用文档工具去读电子表格或多维表格会失败或产生错误语义。

三步处理流程

1. 先调用feishu_wiki_space_node（action:get）解析 wiki token：

   { "action": "get", "token": "wiki_token_here" }

2. 从返回的node中获取obj_type（实际文档类型）和obj_token（实际文档 token）；
3. 根据obj_type调用对应工具：

完整示例

用户：帮我看下这个文档 https://xxx.feishu.cn/wiki/ABC123

1. 调用feishu_wiki_space_node（action: get, token: ABC123）；
2. 返回obj_type: "docx",obj_token: "doxcnXYZ789"；
3. 调用feishu_mcp_fetch_doc（doc_id: doxcnXYZ789）。

源码侧的依据与边界

space-node.js 中，feishu_wiki_space_node的getaction 会调用飞书 Wiki API 的get_node接口（obj_type默认按wiki解析），并返回node对象——SKILL 中的obj_type/obj_token正是取自该返回结构。同时该工具的描述字段也明确写道："node_token 是节点的唯一标识符，obj_token 是实际文档的 token。可通过 get 操作将 wiki 类型的 node_token 转换为实际文档的 obj_token"，与 SKILL 的策略完全一致。

需要说明的边界：getaction 的 schema 允许显式传入obj_type（可取值包括doc、sheet、mindnote、bitable、file、docx、slides、wiki），用于在已知类型时加速解析；而 SKILL 路由表只覆盖docx、sheet、bitable三种主流类型，其余类型（如mindnote思维笔记、slides幻灯片、file文件）在 SKILL 层面按"告知用户暂不支持"处理——Agent 编排时应把这种兜底路径也写进自己的判断逻辑。

工具组合一览

围绕"读取飞书云文档"这一需求，SKILL 给出了配套工具矩阵：

从插件注册逻辑看，这些工具并非无条件启用：doc/index.js 会先检查配置中tools.doc开关（关闭则整个 MCP doc 工具集不注册），drive/index.js 对应检查tools.drive开关（决定feishu_doc_media等是否可用）。因此实战中若 Agent 提示找不到工具，应优先确认 OpenClaw 配置中对应工具分类是否被启用。

权限与运行前提

根据插件 README 的说明，读取飞书云文档需要应用具备docx:document:readonly权限，发送消息等操作还需要im:message:send_as_bot等权限；应用创建后应在开放平台"权限管理"中批量导入完整权限列表并完成发布审批。MCP 调用链路还依赖飞书 MCP 网关地址，其解析优先级为：运行时 override >openclaw.json中的channels.feishu.mcpEndpoint（兼容旧字段mcp_url）> 环境变量FEISHU_MCP_ENDPOINT> 默认值https://mcp.feishu.cn/mcp，详见 shared.js；如需服务端鉴权，可通过环境变量FEISHU_MCP_BEARER_TOKEN或FEISHU_MCP_TOKEN注入。

实战要点小结

1. 区分文本与媒体：feishu_fetch_doc只负责 Markdown 文本；图片/文件/画板一律以<image>、<file>、<whiteboard>标签暴露 token，需要二次调用feishu_doc_media下载。
2. Wiki 链接必须判型：对/wiki/链接先走feishu_wiki_space_node的get，拿到obj_type/obj_token再按表路由到 docx/sheet/bitable 工具，切勿假设 wiki 即云文档。
3. 善用分页与扩展名补全：大文档用offset/limit分段读取；feishu_doc_media下载时输出路径可不写扩展名，由工具按 Content-Type 自动补全。
4. 检查工具开关与权限：tools.doc、tools.drive开关决定工具是否注册，docx:document:readonly等权限决定调用是否成功。

本文涉及的全部源码、SKILL 与配置示例均位于当前仓库 资料/feishu-openclaw-plugin/package 目录下，读者可按 SKILL.md、fetch.js、doc-media.js、space-node.js 的路径顺序深入研读。

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• MCP Clients
• 本地部署