1. 从手动搬运到一键直达这套方案到底解决了什么问题每次写完一篇长文最烦的从来不是写本身而是写完之后的搬运工作。本地 Markdown 文件躺在编辑器里要发到飞书文档上给团队看得先打开飞书、新建文档、复制粘贴、重新调格式、图片还得一张张传。一篇三千字的稿子光搬运就能耗掉十几分钟格式还经常乱掉——标题层级没了、表格变成一堆竖线、代码块全糊在一起。我前前后后试过不少办法。手动复制是最笨的但也是最多人还在用的。后来用飞书自带的导入功能支持 Markdown 文件上传但每次都要手动点好几步而且图片路径处理经常出问题。再后来想用 API 自动化结果卡在权限配置上飞书的企业自建应用权限申请流程对个人开发者不算友好折腾半天没跑通。直到我把 AI Agent 和 MCP 协议这套组合拳打顺了才真正实现了“写完即上传”的体验。现在我的工作流是这样的在本地用 Markdown 写完稿子跟 AI 助手说一句“帮我把这篇传到飞书”几十秒后飞书文档链接就回来了格式完整、图片正常、表格清晰。整个过程不需要我打开飞书客户端不需要手动操作任何界面。这套方案的核心价值在于三点。第一是省时间把重复性的搬运工作完全交给 AI 和自动化流程一篇文档从写完到上线飞书从十几分钟压缩到不到一分钟。第二是保格式Markdown 的标题、列表、表格、代码块、图片在转换过程中能最大程度保留原始结构不会出现手动复制那种格式崩坏的情况。第三是可复用一旦流程跑通以后每篇文档都可以走同样的管道形成稳定的内容发布流水线。适合谁来参考这套方案如果你经常需要把本地 Markdown 文档同步到飞书不管是技术文档、项目周报、会议纪要还是知识库条目这套流程都能帮你省下大量机械操作的时间。如果你对 AI Agent 和 MCP 协议感兴趣想找一个实际可落地的场景来练手这个项目也是很好的切入点——它涉及 API 调用、协议理解、文件处理和错误排查麻雀虽小五脏俱全。接下来我会把这套方案的完整实现过程拆开讲清楚包括整体设计思路、MCP 协议的核心机制、飞书 API 的对接细节、实操步骤、参数配置以及我踩过的那些坑。2. 整体方案设计与技术选型拆解2.1 为什么选 MCP Agent 这套组合先说清楚 MCP 是什么。MCP 全称 Model Context Protocol翻译过来叫“模型上下文协议”本质上是一套让 AI 模型和外部工具、数据源之间标准化通信的协议。你可以把它理解成 AI 世界的 USB 接口——以前每个 AI 工具要对接外部服务都得自己写一套适配代码有了 MCP 之后只要外部服务实现了 MCP Server任何支持 MCP 的 AI 客户端都能直接调用。我选这套方案而不是直接写脚本调飞书 API核心理由有三个。第一个理由是交互自然。写个 Python 脚本调 API 当然也能实现上传但每次都要打开终端、敲命令、传参数。用 MCP Agent 的方式我只需要用自然语言跟 AI 说“把这篇文档传到飞书”Agent 会自动理解意图、调用对应的 MCP 工具、处理返回结果。这种交互方式对非技术用户友好得多也更符合“AI 替我干活”的直觉。第二个理由是扩展性强。MCP 协议是标准化的今天我用它对接飞书明天想对接其他文档平台只要那个平台有 MCP ServerAgent 端几乎不用改代码。这种可插拔的架构比写死一个脚本要灵活得多。第三个理由是错误处理更智能。直接调 API 的话遇到 token 过期、权限不足、网络超时这些问题脚本往往直接报错退出。而 Agent 可以在 MCP 工具返回错误后根据错误信息自动尝试修复——比如重新获取 token、换一种上传方式、或者提示我手动处理。这种“智能重试”的能力在实际使用中非常省心。2.2 飞书文档 API 的能力边界飞书开放平台提供了丰富的文档相关 API我实际用到的主要是这几个。创建文档接口用于在指定文件夹下新建一个飞书文档返回文档的 token 和 URL。导入文件接口支持把 Markdown、Word、Excel 等格式的文件导入为飞书云文档这个接口对 Markdown 的支持相当不错标题、列表、表格、代码块都能正确转换。上传素材接口用于上传图片等媒体文件返回一个 file_token可以在文档中引用。获取文件夹列表接口用来找到目标文件夹的 token方便把文档创建在正确的位置。这里有个关键点需要说明飞书 API 的权限模型是基于应用App的。你需要先在飞书开放平台创建一个企业自建应用申请对应的文档权限如docx:document、drive:drive等然后获取 App ID 和 App Secret用它们换取 tenant_access_token 或 user_access_token。tenant_access_token 是以应用身份操作user_access_token 是以用户身份操作。对于个人使用场景我建议用 user_access_token因为这样创建的文档归属你自己权限管理也更简单。2.3 整体架构长什么样整个方案的架构可以分成四层。最上层是用户交互层也就是你跟 AI 助手对话的界面。可以是支持 MCP 的桌面客户端也可以是命令行工具甚至可以是聊天窗口。你在这里用自然语言发出指令。第二层是Agent 调度层AI 模型在这里理解你的意图决定调用哪个 MCP 工具传入什么参数以及如何处理返回结果。这一层是“大脑”。第三层是MCP Server 层这是实际执行操作的模块。它封装了飞书 API 的调用逻辑对外暴露标准化的 MCP 工具接口比如upload_markdown_to_feishu、create_feishu_doc等。Agent 通过 MCP 协议跟它通信。最底层是飞书开放平台提供实际的文档创建、文件导入、素材上传等 API 能力。数据流向是这样的你在交互层说“把这篇文档传到飞书”Agent 解析出意图和文件路径通过 MCP 协议调用 MCP Server 的upload_markdown_to_feishu工具MCP Server 读取本地 Markdown 文件、处理图片、调用飞书 API 完成上传然后把飞书文档链接返回给 AgentAgent 再展示给你。2.4 关键选型对比几种上传方式的优劣在确定最终方案之前我对比了几种常见的 Markdown 转飞书文档的方式列个表方便你参考。方案实现难度格式保留自动化程度适用场景手动复制粘贴极低差无偶尔发一两篇飞书客户端导入低较好半自动不频繁的文档同步Python 脚本调 API中好全自动有编程基础、固定流程MCP Agent中高好全自动智能追求自然交互、多平台扩展手动复制粘贴的问题很明显格式丢失严重尤其是表格和代码块粘过去基本要重新排版。飞书客户端导入比手动好一些但每次都要打开客户端、找到导入入口、选择文件步骤还是太多。Python 脚本能实现全自动但交互方式不自然每次都要敲命令。MCP Agent 的方案在自动化程度和交互体验上都是最优的代价是前期配置稍微复杂一点但一次配置长期受益。我最终选 MCP Agent还有一个很实际的原因我日常已经在用 AI 助手处理各种任务把上传飞书这个能力集成进去之后不需要切换工具在一个对话窗口里就能完成“写稿-改稿-上传”的全流程。这种工作流的连贯性比省下的那几分钟操作时间更有价值。3. 核心细节解析与实操要点3.1 MCP Server 的工具设计MCP Server 是整个方案的核心执行单元它的工具设计直接决定了 Agent 能做什么、怎么做。我设计了三个核心工具覆盖从创建文档到上传内容的完整流程。工具一create_feishu_doc。这个工具负责在飞书指定文件夹下创建一个空文档返回文档的 document_id 和 URL。参数包括title文档标题和folder_token目标文件夹的 token可选不传则创建在根目录。这个工具看起来简单但它是后续所有操作的基础——你得先有个文档才能往里写内容。工具二upload_markdown_to_feishu。这是最核心的工具负责把本地 Markdown 文件的内容写入飞书文档。参数包括document_id目标文档 ID、markdown_contentMarkdown 文本内容、image_base_path图片基础路径用于解析相对路径的图片。这个工具内部会做几件事解析 Markdown 中的图片引用、上传图片到飞书素材库、把图片链接替换为飞书可识别的格式、调用飞书文档 API 写入内容。工具三import_markdown_file。这个工具走的是飞书“导入文件”接口直接把整个 Markdown 文件导入为飞书文档。参数包括file_path本地文件路径和folder_token目标文件夹。这个工具的好处是格式转换由飞书官方处理兼容性最好缺点是导入后的文档结构可能跟预期有细微差异比如某些嵌套列表的层级可能变化。提示三个工具可以组合使用。最简单的流程是直接用import_markdown_file一步到位如果需要更精细的控制比如先创建文档再分段写入就用create_feishu_docupload_markdown_to_feishu的组合。3.2 飞书 API 鉴权token 获取与刷新飞书 API 的鉴权是整个流程中最容易出问题的环节。我详细说一下。首先你需要在飞书开放平台创建企业自建应用拿到 App ID 和 App Secret。然后调用鉴权接口获取 token。飞书支持两种 tokentenant_access_token和user_access_token。前者以应用身份操作有效期 2 小时后者以用户身份操作有效期也是 2 小时但需要额外的 OAuth 流程。对于个人使用场景我推荐用tenant_access_token因为获取方式简单不需要跳转授权页面。获取方式如下curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d { app_id: your_app_id, app_secret: your_app_secret }返回结果里会有tenant_access_token和expire过期时间秒。你需要在每次调用 API 前检查 token 是否过期过期了就重新获取。我的做法是在 MCP Server 里维护一个 token 缓存记录获取时间和过期时间每次调用前判断是否需要刷新。这里有个坑要注意飞书的 token 有效期是 2 小时但如果你在 token 即将过期时发起请求可能会遇到“token 已过期”的错误。我的经验是提前 5 分钟刷新也就是缓存有效期设为 1 小时 55 分钟避免边界情况。3.3 Markdown 解析与图片处理Markdown 里的图片处理是另一个容易翻车的点。本地 Markdown 文件里的图片通常是相对路径比如但飞书文档需要的是可访问的 URL 或者上传后的 file_token。我的处理流程是这样的先用正则表达式扫描 Markdown 内容找出所有图片引用提取出图片路径。然后判断路径类型——如果是网络 URL以 http/https 开头直接保留如果是本地相对路径就拼接基础路径得到绝对路径读取文件内容调用飞书素材上传接口上传拿到 file_token再把 Markdown 里的图片引用替换成飞书可识别的格式。飞书文档 API 写入图片的方式比较特殊需要在内容块中使用image类型的 block并传入 file_token。具体格式如下{ block_type: 27, image: { token: 上传后获得的file_token } }这里有个细节飞书素材上传接口需要指定父节点类型和 token。对于文档图片父节点类型是docx_image父节点 token 是文档的 document_id。上传成功后会返回 file_token这个 token 在文档内可以直接使用。注意飞书素材上传有大小限制单张图片不能超过 20MB。如果你有大量高清图片建议先压缩再上传否则会报错。3.4 Markdown 语法到飞书文档块的映射飞书文档 API 使用的是“块”Block的概念每个段落、标题、列表、表格都是一个独立的块。Markdown 语法需要转换成对应的块类型。我整理了一个映射表Markdown 语法飞书块类型block_type 值# 标题一级标题3## 标题二级标题4### 标题三级标题5普通段落文本2- 列表项无序列表121. 列表项有序列表13 引用引用15代码块代码14表格表格31图片图片27转换过程中有几个容易出问题的地方。第一是嵌套列表飞书的列表块支持嵌套但需要通过children字段来组织层级关系处理起来比较绕。第二是表格飞书表格块的结构比较复杂需要先创建表格块再填充单元格内容而且表格的行列数在创建时就确定了不能动态增减。第三是代码块需要指定语言类型飞书支持的语言列表跟 Markdown 的常见语言标识不完全一致需要做映射。我的建议是如果文档结构比较简单标题段落少量列表用upload_markdown_to_feishu逐块写入完全没问题。如果文档里有大量复杂表格和嵌套列表直接用import_markdown_file走飞书官方导入接口更省心格式兼容性更好。4. 完整实操流程从零跑通一键上传4.1 环境准备与依赖安装先把基础环境搭好。你需要准备的东西包括一个飞书账号企业版或个人版都行、一台能跑 Python 的电脑、一个支持 MCP 的 AI 客户端。飞书这边先去开放平台创建企业自建应用。进入开发者后台点击“创建应用”选择“企业自建应用”填个名字和描述。创建完成后在“凭证与基础信息”页面拿到 App ID 和 App Secret。然后在“权限管理”页面申请以下权限docx:document文档读写、drive:drive云空间读写、drive:file文件上传。申请后需要管理员审批个人版账号一般秒过。Python 环境这边我用的 Python 3.10需要安装几个依赖库pip install requests markdown-it-py mcprequests用于调飞书 APImarkdown-it-py用于解析 Markdown 语法mcp是 MCP 协议的 Python SDK。如果你打算用 Node.js 写 MCP Server对应的包是modelcontextprotocol/sdk安装方式类似。AI 客户端这边我用的是支持 MCP 的桌面客户端。配置方式是在客户端的配置文件里添加 MCP Server 的启动命令。以 JSON 配置为例{ mcpServers: { feishu-uploader: { command: python, args: [/path/to/feishu_mcp_server.py], env: { FEISHU_APP_ID: your_app_id, FEISHU_APP_SECRET: your_app_secret } } } }配置完成后重启客户端Agent 就能识别到飞书上传工具了。4.2 MCP Server 核心代码实现下面是我写的 MCP Server 核心代码用 Python 实现。代码分三个部分鉴权模块、Markdown 处理模块、MCP 工具定义。鉴权模块负责获取和缓存 tokenimport time import requests class FeishuAuth: def __init__(self, app_id, app_secret): self.app_id app_id self.app_secret app_secret self._token None self._expire_at 0 def get_token(self): if self._token and time.time() self._expire_at: return self._token resp requests.post( https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal, json{app_id: self.app_id, app_secret: self.app_secret} ) data resp.json() if data.get(code) ! 0: raise Exception(f获取token失败: {data}) self._token data[tenant_access_token] # 提前5分钟刷新 self._expire_at time.time() data[expire] - 300 return self._tokenMarkdown 处理模块负责解析图片和转换格式import re import os def extract_images(markdown_text, base_path): 提取Markdown中的图片引用返回图片列表和替换后的文本 pattern r!\[([^\]]*)\]\(([^)])\) images [] def replace(match): alt, src match.group(1), match.group(2) if src.startswith((http://, https://)): return match.group(0) # 网络图片保留原样 abs_path os.path.join(base_path, src) images.append({alt: alt, path: abs_path, original: match.group(0)}) return f-1}}}}}) new_text re.sub(pattern, replace, markdown_text) return new_text, imagesMCP 工具定义部分用mcpSDK 注册工具from mcp.server import Server from mcp.types import Tool, TextContent server Server(feishu-uploader) auth FeishuAuth(os.environ[FEISHU_APP_ID], os.environ[FEISHU_APP_SECRET]) server.tool() async def import_markdown_file(file_path: str, folder_token: str ) - str: 将本地Markdown文件导入为飞书文档 token auth.get_token() # 读取文件 with open(file_path, r, encodingutf-8) as f: content f.read() # 调用飞书导入接口 # ... 具体实现见下文 return f文档已创建: {doc_url}4.3 飞书文档导入接口的调用细节飞书的“导入文件”接口是异步的调用后会返回一个 ticket你需要轮询查询导入结果。完整流程分三步。第一步上传文件到飞书云空间。调用POST /open-apis/drive/v1/files/upload_all传入文件名、父文件夹 token、文件内容。返回 file_token。第二步创建导入任务。调用POST /open-apis/drive/v1/import_tasks传入 file_token、文件类型md表示 Markdown、目标文件夹 token、目标文件名。返回 ticket。第三步轮询查询任务结果。调用GET /open-apis/drive/v1/import_tasks/{ticket}直到返回job_status为success此时会返回导入后的文档 token 和 URL。轮询间隔我设的是 1 秒最多轮询 30 次。实测下来一篇三千字的 Markdown 文档导入通常 3-5 秒完成。如果超过 30 秒还没成功大概率是文件有问题或者权限不足需要检查。注意导入接口对 Markdown 文件的大小有限制不能超过 20MB。另外导入后的文档格式跟原始 Markdown 可能有细微差异比如某些特殊符号的转义、表格对齐方式等这是正常现象。4.4 图片上传与替换的完整流程如果走upload_markdown_to_feishu这条路逐块写入图片处理流程如下。先扫描 Markdown 内容提取所有本地图片路径。然后逐个上传到飞书素材库def upload_image(auth, doc_id, image_path): token auth.get_token() with open(image_path, rb) as f: files {file: (os.path.basename(image_path), f, image/png)} data { parent_type: docx_image, parent_node: doc_id, size: os.path.getsize(image_path) } resp requests.post( https://open.feishu.cn/open-apis/drive/v1/medias/upload_all, headers{Authorization: fBearer {token}}, filesfiles, datadata ) result resp.json() if result.get(code) ! 0: raise Exception(f图片上传失败: {result}) return result[data][file_token]拿到 file_token 后在构建文档块时使用image类型块传入 token。飞书文档 API 会自动把图片渲染到文档中。这里有个实操心得图片上传是串行的一张一张传。如果文档里有十几张图整个上传过程可能要十几秒。我试过改成并发上传但飞书接口对并发有限制容易触发限流。所以还是老老实实串行稳一点。4.5 在 Agent 端配置与调用MCP Server 跑起来之后Agent 端需要做两件事一是配置 MCP Server 的连接信息二是确保 Agent 能正确识别和调用工具。配置方式前面已经说了在客户端的 MCP 配置里加上 Server 的启动命令和环境变量。配置完成后你可以在对话里问 Agent“你有哪些飞书相关的工具”如果配置正确Agent 会列出import_markdown_file、create_feishu_doc、upload_markdown_to_feishu这三个工具。调用的时候直接用自然语言描述需求就行。比如“把/Users/me/docs/report.md这个文件传到飞书”“帮我在飞书创建一个叫‘项目周报’的文档内容用我本地这个 Markdown 文件”“把这篇 Markdown 上传到飞书放到‘技术文档’文件夹里”Agent 会自动解析出文件路径、目标文件夹等信息调用对应的 MCP 工具。如果信息不全比如你没说文件夹Agent 会追问或者使用默认值。我实测下来从发出指令到拿到飞书文档链接一篇普通长度的文档大概 20-40 秒。其中大部分时间花在图片上传和飞书服务端处理上Agent 本身的调度几乎不耗时。5. 常见问题与排查技巧实录5.1 权限报错从 99991672 到 99991663飞书 API 的权限报错是最常见的。我遇到过的主要有这几个错误码。99991672通常是应用没有申请对应的权限。解决方法是去开放平台权限管理页面检查是否申请了docx:document、drive:drive、drive:file这三个权限申请后需要重新发布应用版本等审批通过后生效。99991663token 无效或已过期。检查 token 是否正确获取、是否在有效期内。如果用的是tenant_access_token确认应用是否已发布且审批通过。未发布的应用获取的 token 权限受限。99991661请求参数错误。常见原因是 folder_token 传错了或者文件类型不支持。检查文件夹 token 是否正确文件扩展名是否为.md。实操心得飞书的错误信息有时候比较模糊光看错误码很难定位问题。我的做法是在 MCP Server 里把完整的请求参数和响应内容都打日志出问题的时候看日志比看错误码快得多。5.2 图片上传失败路径、格式与大小图片上传失败的原因主要有三类。第一类是路径问题。Markdown 里的图片路径是相对路径但 MCP Server 的工作目录可能跟 Markdown 文件不在同一个目录。我的处理方式是在调用工具时显式传入image_base_path参数指定图片的基础路径。如果不传默认用 Markdown 文件所在目录。第二类是格式问题。飞书素材上传接口支持 PNG、JPG、JPEG、GIF、BMP、WEBP 等常见格式。如果你有 SVG 图片需要先转成 PNG 再上传。我遇到过 SVG 上传后无法显示的问题后来统一转成 PNG 解决了。第三类是大小问题。单张图片不能超过 20MB。超过的话需要先压缩。我用 Pillow 库写了个简单的压缩函数把图片质量降到 85%尺寸限制在 2000px 以内基本能压到 5MB 以下画质损失肉眼几乎看不出来。5.3 格式错乱表格、代码块与嵌套列表格式错乱是 Markdown 转飞书文档时最让人头疼的问题。我踩过的坑包括表格变成纯文本、代码块丢失语言标识、嵌套列表层级混乱。表格问题的根源在于飞书表格块的结构比较复杂。如果用逐块写入的方式需要先创建表格块再逐行逐列填充单元格。我的建议是如果文档里有表格优先用import_markdown_file走官方导入接口格式兼容性最好。如果必须逐块写入那就把表格转成飞书支持的格式或者干脆用图片代替表格。代码块问题主要是语言标识的映射。Markdown 里写python飞书代码块需要的是python这个语言标识大部分情况下是一致的但有些语言标识飞书不支持比如text、plain需要映射成plain_text。嵌套列表的问题在于飞书的列表块需要通过children字段组织层级。我的处理方式是递归解析 Markdown 的列表结构构建对应的块树。这部分代码稍微复杂一点但逻辑是清晰的遇到缩进就增加层级遇到同级就平铺。5.4 常见问题速查表问题现象可能原因排查方法解决方案报错 99991672权限未申请检查开放平台权限列表申请权限并重新发布报错 99991663token 过期检查 token 获取时间重新获取 token图片不显示路径错误检查 image_base_path传入正确的图片基础路径图片上传失败格式不支持检查图片扩展名转成 PNG/JPG表格格式乱块类型不匹配检查表格块结构改用 import 接口代码块无高亮语言标识错误检查语言映射映射为飞书支持的语言导入超时文件过大检查文件大小压缩文件或拆分上传文档创建在根目录folder_token 未传检查参数传入正确的文件夹 token5.5 几个让我少走弯路的实操技巧第一个技巧先用小文件测试。不要一上来就拿几千字带几十张图的文档测试先用一个简单的 Markdown 文件跑通流程确认鉴权、上传、格式转换都没问题再逐步增加复杂度。第二个技巧日志要打全。MCP Server 里每个 API 调用的请求参数和响应内容都打日志出问题的时候直接看日志定位比猜快得多。我用的是 Python 的logging模块日志级别设成 DEBUG输出到文件。第三个技巧token 缓存要持久化。如果你的 MCP Server 是每次调用都重启的有些客户端是这样的token 缓存放在内存里就没意义了。可以把 token 和过期时间写到本地文件下次启动时先读文件没过期就直接用。第四个技巧图片先压缩再上传。尤其是截图原始尺寸往往很大压缩到 2000px 宽、质量 85%肉眼几乎看不出差别但上传速度快很多也不容易触发大小限制。第五个技巧文件夹 token 提前准备好。飞书的文件夹 token 不是一眼能看到的需要调 API 获取。我的做法是提前调一次GET /open-apis/drive/v1/files列出根目录下的文件夹找到目标文件夹的 token 记下来配置到 MCP Server 的环境变量里省得每次都要查。6. 进阶玩法让这套流程更顺手6.1 批量上传与目录同步单篇上传跑通之后很自然会想到批量处理。我现在的做法是把要上传的 Markdown 文件放在一个目录里跟 Agent 说“把这个目录下所有 Markdown 文件都传到飞书”Agent 会遍历目录、逐个上传最后返回一个文档链接列表。批量上传有几个要注意的点。第一是限流飞书 API 对调用频率有限制批量上传时要在每次请求之间加个短延迟我设的是 500ms实测下来不会触发限流。第二是错误隔离某个文件上传失败不应该影响其他文件每个文件独立处理失败的记录下来最后统一报告。第三是目录结构映射如果本地目录有子文件夹可以考虑在飞书里创建对应的文件夹结构保持组织方式一致。6.2 与写作流程的深度集成我现在的工作流已经跟这套上传方案深度绑定了。写稿的时候在本地用 Markdown 编辑器写写完之后直接跟 AI 助手说“传到飞书”几十秒后链接就回来了。整个过程不需要打开飞书客户端不需要手动操作任何界面。更进一步我还在 Agent 端配置了一些快捷指令。比如“发周报”会自动找到本周的周报文件并上传到指定的飞书文件夹“发技术文档”会把docs/目录下的最新文档同步到飞书知识库。这些快捷指令本质上就是预设了文件路径和目标文件夹的模板用起来非常顺手。6.3 扩展到其他文档平台MCP 协议的好处在于标准化。今天我用它对接飞书明天如果想对接其他文档平台只要那个平台有 MCP ServerAgent 端几乎不用改代码。我目前正在尝试把同样的流程扩展到其他支持 MCP 的文档平台思路是一样的写一个 MCP Server 封装平台的 APIAgent 端配置一下就能用。这种可插拔的架构意味着你在这套方案上投入的学习成本是可以复用的。理解了 MCP 协议的工作原理、掌握了 Agent 调用工具的方式、踩过了 API 鉴权和格式转换的坑换一个平台无非是换一套 API 调用逻辑整体框架不用动。6.4 安全与权限的边界控制最后说一下安全方面的考虑。飞书应用的 App Secret 是敏感信息不要硬编码在代码里也不要在对话里明文传输。我的做法是放在环境变量里MCP Server 启动时从环境变量读取。另外申请权限时遵循最小必要原则只申请真正需要的权限不要图省事申请一堆用不到的权限。对于团队使用场景建议用tenant_access_token而不是user_access_token这样文档归属应用而不是个人人员变动时不会影响文档的归属和权限。个人使用场景用哪种都行看个人偏好。我在实际使用中还有一个体会这套方案最大的价值不在于省了多少操作时间而在于它把“上传文档”这个动作从我的注意力里彻底移除了。以前每次写完稿子脑子里还要惦记着“待会儿要传到飞书”现在完全不用想一句话的事。这种认知负担的释放比省下的几分钟操作时间重要得多。
1. 从手动搬运到一键直达这套方案到底解决了什么问题每次写完一篇长文最烦的从来不是写本身而是写完之后的搬运工作。本地 Markdown 文件躺在编辑器里要发到飞书文档上给团队看得先打开飞书、新建文档、复制粘贴、重新调格式、图片还得一张张传。一篇三千字的稿子光搬运就能耗掉十几分钟格式还经常乱掉——标题层级没了、表格变成一堆竖线、代码块全糊在一起。我前前后后试过不少办法。手动复制是最笨的但也是最多人还在用的。后来用飞书自带的导入功能支持 Markdown 文件上传但每次都要手动点好几步而且图片路径处理经常出问题。再后来想用 API 自动化结果卡在权限配置上飞书的企业自建应用权限申请流程对个人开发者不算友好折腾半天没跑通。直到我把 AI Agent 和 MCP 协议这套组合拳打顺了才真正实现了“写完即上传”的体验。现在我的工作流是这样的在本地用 Markdown 写完稿子跟 AI 助手说一句“帮我把这篇传到飞书”几十秒后飞书文档链接就回来了格式完整、图片正常、表格清晰。整个过程不需要我打开飞书客户端不需要手动操作任何界面。这套方案的核心价值在于三点。第一是省时间把重复性的搬运工作完全交给 AI 和自动化流程一篇文档从写完到上线飞书从十几分钟压缩到不到一分钟。第二是保格式Markdown 的标题、列表、表格、代码块、图片在转换过程中能最大程度保留原始结构不会出现手动复制那种格式崩坏的情况。第三是可复用一旦流程跑通以后每篇文档都可以走同样的管道形成稳定的内容发布流水线。适合谁来参考这套方案如果你经常需要把本地 Markdown 文档同步到飞书不管是技术文档、项目周报、会议纪要还是知识库条目这套流程都能帮你省下大量机械操作的时间。如果你对 AI Agent 和 MCP 协议感兴趣想找一个实际可落地的场景来练手这个项目也是很好的切入点——它涉及 API 调用、协议理解、文件处理和错误排查麻雀虽小五脏俱全。接下来我会把这套方案的完整实现过程拆开讲清楚包括整体设计思路、MCP 协议的核心机制、飞书 API 的对接细节、实操步骤、参数配置以及我踩过的那些坑。2. 整体方案设计与技术选型拆解2.1 为什么选 MCP Agent 这套组合先说清楚 MCP 是什么。MCP 全称 Model Context Protocol翻译过来叫“模型上下文协议”本质上是一套让 AI 模型和外部工具、数据源之间标准化通信的协议。你可以把它理解成 AI 世界的 USB 接口——以前每个 AI 工具要对接外部服务都得自己写一套适配代码有了 MCP 之后只要外部服务实现了 MCP Server任何支持 MCP 的 AI 客户端都能直接调用。我选这套方案而不是直接写脚本调飞书 API核心理由有三个。第一个理由是交互自然。写个 Python 脚本调 API 当然也能实现上传但每次都要打开终端、敲命令、传参数。用 MCP Agent 的方式我只需要用自然语言跟 AI 说“把这篇文档传到飞书”Agent 会自动理解意图、调用对应的 MCP 工具、处理返回结果。这种交互方式对非技术用户友好得多也更符合“AI 替我干活”的直觉。第二个理由是扩展性强。MCP 协议是标准化的今天我用它对接飞书明天想对接其他文档平台只要那个平台有 MCP ServerAgent 端几乎不用改代码。这种可插拔的架构比写死一个脚本要灵活得多。第三个理由是错误处理更智能。直接调 API 的话遇到 token 过期、权限不足、网络超时这些问题脚本往往直接报错退出。而 Agent 可以在 MCP 工具返回错误后根据错误信息自动尝试修复——比如重新获取 token、换一种上传方式、或者提示我手动处理。这种“智能重试”的能力在实际使用中非常省心。2.2 飞书文档 API 的能力边界飞书开放平台提供了丰富的文档相关 API我实际用到的主要是这几个。创建文档接口用于在指定文件夹下新建一个飞书文档返回文档的 token 和 URL。导入文件接口支持把 Markdown、Word、Excel 等格式的文件导入为飞书云文档这个接口对 Markdown 的支持相当不错标题、列表、表格、代码块都能正确转换。上传素材接口用于上传图片等媒体文件返回一个 file_token可以在文档中引用。获取文件夹列表接口用来找到目标文件夹的 token方便把文档创建在正确的位置。这里有个关键点需要说明飞书 API 的权限模型是基于应用App的。你需要先在飞书开放平台创建一个企业自建应用申请对应的文档权限如docx:document、drive:drive等然后获取 App ID 和 App Secret用它们换取 tenant_access_token 或 user_access_token。tenant_access_token 是以应用身份操作user_access_token 是以用户身份操作。对于个人使用场景我建议用 user_access_token因为这样创建的文档归属你自己权限管理也更简单。2.3 整体架构长什么样整个方案的架构可以分成四层。最上层是用户交互层也就是你跟 AI 助手对话的界面。可以是支持 MCP 的桌面客户端也可以是命令行工具甚至可以是聊天窗口。你在这里用自然语言发出指令。第二层是Agent 调度层AI 模型在这里理解你的意图决定调用哪个 MCP 工具传入什么参数以及如何处理返回结果。这一层是“大脑”。第三层是MCP Server 层这是实际执行操作的模块。它封装了飞书 API 的调用逻辑对外暴露标准化的 MCP 工具接口比如upload_markdown_to_feishu、create_feishu_doc等。Agent 通过 MCP 协议跟它通信。最底层是飞书开放平台提供实际的文档创建、文件导入、素材上传等 API 能力。数据流向是这样的你在交互层说“把这篇文档传到飞书”Agent 解析出意图和文件路径通过 MCP 协议调用 MCP Server 的upload_markdown_to_feishu工具MCP Server 读取本地 Markdown 文件、处理图片、调用飞书 API 完成上传然后把飞书文档链接返回给 AgentAgent 再展示给你。2.4 关键选型对比几种上传方式的优劣在确定最终方案之前我对比了几种常见的 Markdown 转飞书文档的方式列个表方便你参考。方案实现难度格式保留自动化程度适用场景手动复制粘贴极低差无偶尔发一两篇飞书客户端导入低较好半自动不频繁的文档同步Python 脚本调 API中好全自动有编程基础、固定流程MCP Agent中高好全自动智能追求自然交互、多平台扩展手动复制粘贴的问题很明显格式丢失严重尤其是表格和代码块粘过去基本要重新排版。飞书客户端导入比手动好一些但每次都要打开客户端、找到导入入口、选择文件步骤还是太多。Python 脚本能实现全自动但交互方式不自然每次都要敲命令。MCP Agent 的方案在自动化程度和交互体验上都是最优的代价是前期配置稍微复杂一点但一次配置长期受益。我最终选 MCP Agent还有一个很实际的原因我日常已经在用 AI 助手处理各种任务把上传飞书这个能力集成进去之后不需要切换工具在一个对话窗口里就能完成“写稿-改稿-上传”的全流程。这种工作流的连贯性比省下的那几分钟操作时间更有价值。3. 核心细节解析与实操要点3.1 MCP Server 的工具设计MCP Server 是整个方案的核心执行单元它的工具设计直接决定了 Agent 能做什么、怎么做。我设计了三个核心工具覆盖从创建文档到上传内容的完整流程。工具一create_feishu_doc。这个工具负责在飞书指定文件夹下创建一个空文档返回文档的 document_id 和 URL。参数包括title文档标题和folder_token目标文件夹的 token可选不传则创建在根目录。这个工具看起来简单但它是后续所有操作的基础——你得先有个文档才能往里写内容。工具二upload_markdown_to_feishu。这是最核心的工具负责把本地 Markdown 文件的内容写入飞书文档。参数包括document_id目标文档 ID、markdown_contentMarkdown 文本内容、image_base_path图片基础路径用于解析相对路径的图片。这个工具内部会做几件事解析 Markdown 中的图片引用、上传图片到飞书素材库、把图片链接替换为飞书可识别的格式、调用飞书文档 API 写入内容。工具三import_markdown_file。这个工具走的是飞书“导入文件”接口直接把整个 Markdown 文件导入为飞书文档。参数包括file_path本地文件路径和folder_token目标文件夹。这个工具的好处是格式转换由飞书官方处理兼容性最好缺点是导入后的文档结构可能跟预期有细微差异比如某些嵌套列表的层级可能变化。提示三个工具可以组合使用。最简单的流程是直接用import_markdown_file一步到位如果需要更精细的控制比如先创建文档再分段写入就用create_feishu_docupload_markdown_to_feishu的组合。3.2 飞书 API 鉴权token 获取与刷新飞书 API 的鉴权是整个流程中最容易出问题的环节。我详细说一下。首先你需要在飞书开放平台创建企业自建应用拿到 App ID 和 App Secret。然后调用鉴权接口获取 token。飞书支持两种 tokentenant_access_token和user_access_token。前者以应用身份操作有效期 2 小时后者以用户身份操作有效期也是 2 小时但需要额外的 OAuth 流程。对于个人使用场景我推荐用tenant_access_token因为获取方式简单不需要跳转授权页面。获取方式如下curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d { app_id: your_app_id, app_secret: your_app_secret }返回结果里会有tenant_access_token和expire过期时间秒。你需要在每次调用 API 前检查 token 是否过期过期了就重新获取。我的做法是在 MCP Server 里维护一个 token 缓存记录获取时间和过期时间每次调用前判断是否需要刷新。这里有个坑要注意飞书的 token 有效期是 2 小时但如果你在 token 即将过期时发起请求可能会遇到“token 已过期”的错误。我的经验是提前 5 分钟刷新也就是缓存有效期设为 1 小时 55 分钟避免边界情况。3.3 Markdown 解析与图片处理Markdown 里的图片处理是另一个容易翻车的点。本地 Markdown 文件里的图片通常是相对路径比如但飞书文档需要的是可访问的 URL 或者上传后的 file_token。我的处理流程是这样的先用正则表达式扫描 Markdown 内容找出所有图片引用提取出图片路径。然后判断路径类型——如果是网络 URL以 http/https 开头直接保留如果是本地相对路径就拼接基础路径得到绝对路径读取文件内容调用飞书素材上传接口上传拿到 file_token再把 Markdown 里的图片引用替换成飞书可识别的格式。飞书文档 API 写入图片的方式比较特殊需要在内容块中使用image类型的 block并传入 file_token。具体格式如下{ block_type: 27, image: { token: 上传后获得的file_token } }这里有个细节飞书素材上传接口需要指定父节点类型和 token。对于文档图片父节点类型是docx_image父节点 token 是文档的 document_id。上传成功后会返回 file_token这个 token 在文档内可以直接使用。注意飞书素材上传有大小限制单张图片不能超过 20MB。如果你有大量高清图片建议先压缩再上传否则会报错。3.4 Markdown 语法到飞书文档块的映射飞书文档 API 使用的是“块”Block的概念每个段落、标题、列表、表格都是一个独立的块。Markdown 语法需要转换成对应的块类型。我整理了一个映射表Markdown 语法飞书块类型block_type 值# 标题一级标题3## 标题二级标题4### 标题三级标题5普通段落文本2- 列表项无序列表121. 列表项有序列表13 引用引用15代码块代码14表格表格31图片图片27转换过程中有几个容易出问题的地方。第一是嵌套列表飞书的列表块支持嵌套但需要通过children字段来组织层级关系处理起来比较绕。第二是表格飞书表格块的结构比较复杂需要先创建表格块再填充单元格内容而且表格的行列数在创建时就确定了不能动态增减。第三是代码块需要指定语言类型飞书支持的语言列表跟 Markdown 的常见语言标识不完全一致需要做映射。我的建议是如果文档结构比较简单标题段落少量列表用upload_markdown_to_feishu逐块写入完全没问题。如果文档里有大量复杂表格和嵌套列表直接用import_markdown_file走飞书官方导入接口更省心格式兼容性更好。4. 完整实操流程从零跑通一键上传4.1 环境准备与依赖安装先把基础环境搭好。你需要准备的东西包括一个飞书账号企业版或个人版都行、一台能跑 Python 的电脑、一个支持 MCP 的 AI 客户端。飞书这边先去开放平台创建企业自建应用。进入开发者后台点击“创建应用”选择“企业自建应用”填个名字和描述。创建完成后在“凭证与基础信息”页面拿到 App ID 和 App Secret。然后在“权限管理”页面申请以下权限docx:document文档读写、drive:drive云空间读写、drive:file文件上传。申请后需要管理员审批个人版账号一般秒过。Python 环境这边我用的 Python 3.10需要安装几个依赖库pip install requests markdown-it-py mcprequests用于调飞书 APImarkdown-it-py用于解析 Markdown 语法mcp是 MCP 协议的 Python SDK。如果你打算用 Node.js 写 MCP Server对应的包是modelcontextprotocol/sdk安装方式类似。AI 客户端这边我用的是支持 MCP 的桌面客户端。配置方式是在客户端的配置文件里添加 MCP Server 的启动命令。以 JSON 配置为例{ mcpServers: { feishu-uploader: { command: python, args: [/path/to/feishu_mcp_server.py], env: { FEISHU_APP_ID: your_app_id, FEISHU_APP_SECRET: your_app_secret } } } }配置完成后重启客户端Agent 就能识别到飞书上传工具了。4.2 MCP Server 核心代码实现下面是我写的 MCP Server 核心代码用 Python 实现。代码分三个部分鉴权模块、Markdown 处理模块、MCP 工具定义。鉴权模块负责获取和缓存 tokenimport time import requests class FeishuAuth: def __init__(self, app_id, app_secret): self.app_id app_id self.app_secret app_secret self._token None self._expire_at 0 def get_token(self): if self._token and time.time() self._expire_at: return self._token resp requests.post( https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal, json{app_id: self.app_id, app_secret: self.app_secret} ) data resp.json() if data.get(code) ! 0: raise Exception(f获取token失败: {data}) self._token data[tenant_access_token] # 提前5分钟刷新 self._expire_at time.time() data[expire] - 300 return self._tokenMarkdown 处理模块负责解析图片和转换格式import re import os def extract_images(markdown_text, base_path): 提取Markdown中的图片引用返回图片列表和替换后的文本 pattern r!\[([^\]]*)\]\(([^)])\) images [] def replace(match): alt, src match.group(1), match.group(2) if src.startswith((http://, https://)): return match.group(0) # 网络图片保留原样 abs_path os.path.join(base_path, src) images.append({alt: alt, path: abs_path, original: match.group(0)}) return f-1}}}}}) new_text re.sub(pattern, replace, markdown_text) return new_text, imagesMCP 工具定义部分用mcpSDK 注册工具from mcp.server import Server from mcp.types import Tool, TextContent server Server(feishu-uploader) auth FeishuAuth(os.environ[FEISHU_APP_ID], os.environ[FEISHU_APP_SECRET]) server.tool() async def import_markdown_file(file_path: str, folder_token: str ) - str: 将本地Markdown文件导入为飞书文档 token auth.get_token() # 读取文件 with open(file_path, r, encodingutf-8) as f: content f.read() # 调用飞书导入接口 # ... 具体实现见下文 return f文档已创建: {doc_url}4.3 飞书文档导入接口的调用细节飞书的“导入文件”接口是异步的调用后会返回一个 ticket你需要轮询查询导入结果。完整流程分三步。第一步上传文件到飞书云空间。调用POST /open-apis/drive/v1/files/upload_all传入文件名、父文件夹 token、文件内容。返回 file_token。第二步创建导入任务。调用POST /open-apis/drive/v1/import_tasks传入 file_token、文件类型md表示 Markdown、目标文件夹 token、目标文件名。返回 ticket。第三步轮询查询任务结果。调用GET /open-apis/drive/v1/import_tasks/{ticket}直到返回job_status为success此时会返回导入后的文档 token 和 URL。轮询间隔我设的是 1 秒最多轮询 30 次。实测下来一篇三千字的 Markdown 文档导入通常 3-5 秒完成。如果超过 30 秒还没成功大概率是文件有问题或者权限不足需要检查。注意导入接口对 Markdown 文件的大小有限制不能超过 20MB。另外导入后的文档格式跟原始 Markdown 可能有细微差异比如某些特殊符号的转义、表格对齐方式等这是正常现象。4.4 图片上传与替换的完整流程如果走upload_markdown_to_feishu这条路逐块写入图片处理流程如下。先扫描 Markdown 内容提取所有本地图片路径。然后逐个上传到飞书素材库def upload_image(auth, doc_id, image_path): token auth.get_token() with open(image_path, rb) as f: files {file: (os.path.basename(image_path), f, image/png)} data { parent_type: docx_image, parent_node: doc_id, size: os.path.getsize(image_path) } resp requests.post( https://open.feishu.cn/open-apis/drive/v1/medias/upload_all, headers{Authorization: fBearer {token}}, filesfiles, datadata ) result resp.json() if result.get(code) ! 0: raise Exception(f图片上传失败: {result}) return result[data][file_token]拿到 file_token 后在构建文档块时使用image类型块传入 token。飞书文档 API 会自动把图片渲染到文档中。这里有个实操心得图片上传是串行的一张一张传。如果文档里有十几张图整个上传过程可能要十几秒。我试过改成并发上传但飞书接口对并发有限制容易触发限流。所以还是老老实实串行稳一点。4.5 在 Agent 端配置与调用MCP Server 跑起来之后Agent 端需要做两件事一是配置 MCP Server 的连接信息二是确保 Agent 能正确识别和调用工具。配置方式前面已经说了在客户端的 MCP 配置里加上 Server 的启动命令和环境变量。配置完成后你可以在对话里问 Agent“你有哪些飞书相关的工具”如果配置正确Agent 会列出import_markdown_file、create_feishu_doc、upload_markdown_to_feishu这三个工具。调用的时候直接用自然语言描述需求就行。比如“把/Users/me/docs/report.md这个文件传到飞书”“帮我在飞书创建一个叫‘项目周报’的文档内容用我本地这个 Markdown 文件”“把这篇 Markdown 上传到飞书放到‘技术文档’文件夹里”Agent 会自动解析出文件路径、目标文件夹等信息调用对应的 MCP 工具。如果信息不全比如你没说文件夹Agent 会追问或者使用默认值。我实测下来从发出指令到拿到飞书文档链接一篇普通长度的文档大概 20-40 秒。其中大部分时间花在图片上传和飞书服务端处理上Agent 本身的调度几乎不耗时。5. 常见问题与排查技巧实录5.1 权限报错从 99991672 到 99991663飞书 API 的权限报错是最常见的。我遇到过的主要有这几个错误码。99991672通常是应用没有申请对应的权限。解决方法是去开放平台权限管理页面检查是否申请了docx:document、drive:drive、drive:file这三个权限申请后需要重新发布应用版本等审批通过后生效。99991663token 无效或已过期。检查 token 是否正确获取、是否在有效期内。如果用的是tenant_access_token确认应用是否已发布且审批通过。未发布的应用获取的 token 权限受限。99991661请求参数错误。常见原因是 folder_token 传错了或者文件类型不支持。检查文件夹 token 是否正确文件扩展名是否为.md。实操心得飞书的错误信息有时候比较模糊光看错误码很难定位问题。我的做法是在 MCP Server 里把完整的请求参数和响应内容都打日志出问题的时候看日志比看错误码快得多。5.2 图片上传失败路径、格式与大小图片上传失败的原因主要有三类。第一类是路径问题。Markdown 里的图片路径是相对路径但 MCP Server 的工作目录可能跟 Markdown 文件不在同一个目录。我的处理方式是在调用工具时显式传入image_base_path参数指定图片的基础路径。如果不传默认用 Markdown 文件所在目录。第二类是格式问题。飞书素材上传接口支持 PNG、JPG、JPEG、GIF、BMP、WEBP 等常见格式。如果你有 SVG 图片需要先转成 PNG 再上传。我遇到过 SVG 上传后无法显示的问题后来统一转成 PNG 解决了。第三类是大小问题。单张图片不能超过 20MB。超过的话需要先压缩。我用 Pillow 库写了个简单的压缩函数把图片质量降到 85%尺寸限制在 2000px 以内基本能压到 5MB 以下画质损失肉眼几乎看不出来。5.3 格式错乱表格、代码块与嵌套列表格式错乱是 Markdown 转飞书文档时最让人头疼的问题。我踩过的坑包括表格变成纯文本、代码块丢失语言标识、嵌套列表层级混乱。表格问题的根源在于飞书表格块的结构比较复杂。如果用逐块写入的方式需要先创建表格块再逐行逐列填充单元格。我的建议是如果文档里有表格优先用import_markdown_file走官方导入接口格式兼容性最好。如果必须逐块写入那就把表格转成飞书支持的格式或者干脆用图片代替表格。代码块问题主要是语言标识的映射。Markdown 里写python飞书代码块需要的是python这个语言标识大部分情况下是一致的但有些语言标识飞书不支持比如text、plain需要映射成plain_text。嵌套列表的问题在于飞书的列表块需要通过children字段组织层级。我的处理方式是递归解析 Markdown 的列表结构构建对应的块树。这部分代码稍微复杂一点但逻辑是清晰的遇到缩进就增加层级遇到同级就平铺。5.4 常见问题速查表问题现象可能原因排查方法解决方案报错 99991672权限未申请检查开放平台权限列表申请权限并重新发布报错 99991663token 过期检查 token 获取时间重新获取 token图片不显示路径错误检查 image_base_path传入正确的图片基础路径图片上传失败格式不支持检查图片扩展名转成 PNG/JPG表格格式乱块类型不匹配检查表格块结构改用 import 接口代码块无高亮语言标识错误检查语言映射映射为飞书支持的语言导入超时文件过大检查文件大小压缩文件或拆分上传文档创建在根目录folder_token 未传检查参数传入正确的文件夹 token5.5 几个让我少走弯路的实操技巧第一个技巧先用小文件测试。不要一上来就拿几千字带几十张图的文档测试先用一个简单的 Markdown 文件跑通流程确认鉴权、上传、格式转换都没问题再逐步增加复杂度。第二个技巧日志要打全。MCP Server 里每个 API 调用的请求参数和响应内容都打日志出问题的时候直接看日志定位比猜快得多。我用的是 Python 的logging模块日志级别设成 DEBUG输出到文件。第三个技巧token 缓存要持久化。如果你的 MCP Server 是每次调用都重启的有些客户端是这样的token 缓存放在内存里就没意义了。可以把 token 和过期时间写到本地文件下次启动时先读文件没过期就直接用。第四个技巧图片先压缩再上传。尤其是截图原始尺寸往往很大压缩到 2000px 宽、质量 85%肉眼几乎看不出差别但上传速度快很多也不容易触发大小限制。第五个技巧文件夹 token 提前准备好。飞书的文件夹 token 不是一眼能看到的需要调 API 获取。我的做法是提前调一次GET /open-apis/drive/v1/files列出根目录下的文件夹找到目标文件夹的 token 记下来配置到 MCP Server 的环境变量里省得每次都要查。6. 进阶玩法让这套流程更顺手6.1 批量上传与目录同步单篇上传跑通之后很自然会想到批量处理。我现在的做法是把要上传的 Markdown 文件放在一个目录里跟 Agent 说“把这个目录下所有 Markdown 文件都传到飞书”Agent 会遍历目录、逐个上传最后返回一个文档链接列表。批量上传有几个要注意的点。第一是限流飞书 API 对调用频率有限制批量上传时要在每次请求之间加个短延迟我设的是 500ms实测下来不会触发限流。第二是错误隔离某个文件上传失败不应该影响其他文件每个文件独立处理失败的记录下来最后统一报告。第三是目录结构映射如果本地目录有子文件夹可以考虑在飞书里创建对应的文件夹结构保持组织方式一致。6.2 与写作流程的深度集成我现在的工作流已经跟这套上传方案深度绑定了。写稿的时候在本地用 Markdown 编辑器写写完之后直接跟 AI 助手说“传到飞书”几十秒后链接就回来了。整个过程不需要打开飞书客户端不需要手动操作任何界面。更进一步我还在 Agent 端配置了一些快捷指令。比如“发周报”会自动找到本周的周报文件并上传到指定的飞书文件夹“发技术文档”会把docs/目录下的最新文档同步到飞书知识库。这些快捷指令本质上就是预设了文件路径和目标文件夹的模板用起来非常顺手。6.3 扩展到其他文档平台MCP 协议的好处在于标准化。今天我用它对接飞书明天如果想对接其他文档平台只要那个平台有 MCP ServerAgent 端几乎不用改代码。我目前正在尝试把同样的流程扩展到其他支持 MCP 的文档平台思路是一样的写一个 MCP Server 封装平台的 APIAgent 端配置一下就能用。这种可插拔的架构意味着你在这套方案上投入的学习成本是可以复用的。理解了 MCP 协议的工作原理、掌握了 Agent 调用工具的方式、踩过了 API 鉴权和格式转换的坑换一个平台无非是换一套 API 调用逻辑整体框架不用动。6.4 安全与权限的边界控制最后说一下安全方面的考虑。飞书应用的 App Secret 是敏感信息不要硬编码在代码里也不要在对话里明文传输。我的做法是放在环境变量里MCP Server 启动时从环境变量读取。另外申请权限时遵循最小必要原则只申请真正需要的权限不要图省事申请一堆用不到的权限。对于团队使用场景建议用tenant_access_token而不是user_access_token这样文档归属应用而不是个人人员变动时不会影响文档的归属和权限。个人使用场景用哪种都行看个人偏好。我在实际使用中还有一个体会这套方案最大的价值不在于省了多少操作时间而在于它把“上传文档”这个动作从我的注意力里彻底移除了。以前每次写完稿子脑子里还要惦记着“待会儿要传到飞书”现在完全不用想一句话的事。这种认知负担的释放比省下的几分钟操作时间重要得多。
