steelan9199 飞书文档 Markdown 互转与云空间文件管理
飞书云文档产品简介
云文档是飞书在线文档、电子表格、多维表格、知识库、云空间等产品的统称。
飞书云文档中，放置文档的容器有两种类型：云盘和知识库。
- 云盘：云盘内可创建文件夹，用于组织和管理文件。"云盘"是飞书 drive 的新名称（旧称"云空间"），本文档中两者同义，统一指代 cloud drive。
- 知识库：知识库(Wiki)是独立于云盘的文档容器，用户可拥有多个知识库。与云盘通过文件夹组织文件不同，知识库通过知识空间和节点构建层级体系（详见下文「飞书云文档的知识库简介」）。
用户新建云文档时，若未指定位置，文档默认存放在我的文档库中——这是系统默认的知识库。
飞书云文档的知识库简介
飞书知识库是一个面向组织的知识管理系统，通过结构化沉淀高价值信息，形成完整的知识体系，能够提升知识的流转和传播效率。
知识库和文件夹不是同一概念：
- 知识库的基础组成单位是知识空间，是企业根据需要搭建的不同类别的知识体系，由多个具有层级和所属关系的文档页面构成，每个知识空间有唯一的 space_id 作为标识。
- 知识空间中的内容以节点的形式组织，节点支持文档、表格等多种文件类型，节点之间可以形成层级的页面树结构。
- 而文件夹是云空间中用于管理文件和其它文件夹的容器，和知识库的组织逻辑、能力定位存在区别。
功能概述
提供飞书文档与 Markdown 互转、云盘文件/文件夹管理、跨体系移动（Wiki → 云盘）、文件元数据查询、云文档搜索等能力。具体能力、脚本与参考文档的对应关系见下方「触发映射与文档索引」。上传 Markdown 到飞书文档前，由 AI 在会话层预处理 Callout 格式（脚本仅校验不修正）。
环境说明
| 项目 | 说明 |
|---|---|
$SKILL_DIR |
当前 Skill 所在的绝对目录，即 SKILL.md 文件所在的文件夹 |
| Shell 类型 | bash |
| 脚本目录 | $SKILL_DIR/scripts |
| 临时文件目录 | $SKILL_DIR/temp |
| Node.js 版本 | >=18.20.8 |
| 依赖安装 | 运行 cd "$SKILL_DIR/scripts" && npm install 安装依赖 |
⚠️
$SKILL_DIR仅为文档占位符，不是环境变量，执行命令时必须替换为实际绝对路径。在 bash 中直接写$SKILL_DIR而不加双引号时，若路径含空格会分词；若未替换则被解析为空字符串，导致cd "$SKILL_DIR/scripts"变成cd "/scripts"而报错"找不到路径"。
本 Skill 运行命令时采用 bash && 链式依赖执行（前一条成功才执行下一条），例子：cmd1 && cmd2
⚠️ 脚本已混淆，禁止读取源码
$SKILL_DIR/scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理，禁止读取或分析 .js 文件内容。混淆代码可读性极差，读取纯属浪费 token 和时间。
如需了解脚本功能和用法，请查阅下方「触发映射与文档索引」表。
全局前置条件
| 前置条件 | 说明 |
|---|---|
| 🔑 凭证文件 | 默认从 $SKILL_DIR/config.default.json 读取凭证，直接使用，禁止向用户索要（避免工作暂停）。仅当用户主动提供新凭证时，使用用户提供的凭证。tenant_access_token 优先复用配置文件中已有值，仅当业务脚本返回 token 失效描述时才刷新（详见「身份与访问令牌」章节） |
| 🧑💻 身份选择 | 默认以飞书企业自建应用身份操作；若需操作用户个人云文档，详见下方「身份与访问令牌」章节 |
跨功能公共规则（必须遵守）
| 规则 | 说明 |
|---|---|
| 📁 执行目录 | 执行任何脚本前必须先 cd 到脚本目录（见「环境说明」表），再运行命令 |
| 📄 参数传递 | 所有需要配置参数的脚本必须通过 --parameter-file-path 传递配置，禁止命令行直接传参 |
| 📄 参数文件路径 | --parameter-file-path 的值必须使用绝对路径和正斜杠 / |
| 🗑️ 临时文件存放 | 临时参数文件统一存放到临时文件目录（见「环境说明」表），不得与脚本文件混杂存放 |
| 🧹 临时文件清理 | 任务完成后必须清理 $SKILL_DIR/temp 目录，运行 cd "$SKILL_DIR/scripts" && node clear_temp.js 完成清理。 |
| 📖 脚本文档强制读取 | 执行任何脚本前必须先读取对应的参考文档，严格按照文档中的参数格式操作，禁止凭记忆或直觉编写参数 |
| ✍️ 参数文件写入 | 创建参数文件写入 $SKILL_DIR/temp/ 目录， 文件编码必须为 UTF-8 ，禁止添加 BOM。 |
标准执行命令模板（端到端流程：读取凭证 → 读参考文档 → Write 写参数文件 → 执行 → 处理结果 → 清理）：
cd "$SKILL_DIR/scripts" && node <脚本名>.js --parameter-file-path <参数文件绝对路径>
成功：返回结果数据给用户；失败：根据错误码匹配解决方案并重试。
脚本日志输出机制
$SKILL_DIR/scripts/ 目录下的 JS 脚本的所有日志均通过 console.error 输出至标准错误流（stderr）
据此，脚本运行期间产生的所有输出（含进度日志与结构化结果数据 JSON）均经由 stderr 输出，标准输出流（stdout）为空。AI 在调用脚本、捕获输出时应知晓此特性。
触发映射与文档索引
下表合并了用户触发词、对应脚本、预计耗时与参考文档摘要。
| 用户输入触发词 | 脚本 | 预计耗时 | 参考文档（先读再用） | 文档内容摘要 |
|---|---|---|---|---|
| "Markdown上传到飞书文档"/"上传Markdown到飞书"/"本地Markdown转飞书文档" | markdown-to-feishu.js |
约 5-10 秒 | Markdown转飞书指南 | Markdown 上传到飞书的详细步骤、参数说明、Callout 格式检查与自动修正规则 |
| "飞书文档下载为Markdown"/"下载飞书文档为Markdown"/"飞书文档转Markdown" | feishu-to-markdown.js |
约 5-10 秒 | 飞书转Markdown指南 | 飞书文档下载为 Markdown 的详细流程 |
| "解析飞书文档链接"/"获取document_id"/"从链接提取文档ID" | url-to-document-id.js |
约 2 秒 | 链接解析指南 | 飞书云文档链接解析为 document_id（文件 token）的详细流程 |
| "搜索文件夹"/"搜索云文档"/"搜索文档"/"查找云文档" | search-document.js |
约 2 秒 | 搜索云文档指南 | 根据关键词搜索当前用户可见云文档、文件夹、知识库及知识库内文档（支持 tenant_access_token 与 user_access_token，支持分页与 doc_filter/wiki_filter 过滤） |
| "从链接提取文件夹token" | 不需要脚本 | 约 2 秒 | 获取文件夹token指南 | 从链接提取文件夹token |
| "获取文件夹元数据"/"获取folder_meta"/"查看文件夹信息" | get-folder-meta.js |
约 2 秒 | 获取文件夹元数据指南 | 获取文件夹元数据（ID、名称、创建者等） |
| "获取我的空间"/"获取根文件夹"/"获取root_folder_meta" | get-root-folder-meta.js |
约 2 秒 | 获取我的空间元数据指南 | 获取我的空间（根文件夹）元数据（token、ID、所有者 ID） |
| "获取文件元数据"/"获取file_meta"/"查看文件信息"/"批量获取文件元数据" | get-file-meta.js |
约 2 秒 | 获取文件元数据指南 | 根据文件 token 批量获取任意类型文件元数据（标题、所有者、密级、URL 等），含 doc_type 推断规则 |
| "获取文件夹文件清单"/"获取文件列表"/"列出文件夹中的文件" | get-files.js |
约 2 秒 | 获取文件清单指南 | 获取文件夹中的文件清单（名称、类型、token、URL 等）。默认排除文件夹：除非用户明确提及"文件夹"或"包括文件夹"，否则参数文件中必须添加 "filter_type": "file" |
| "新建文件夹"/"创建文件夹"/"在云空间创建文件夹" | create-folder.js |
约 2 秒 | 新建文件夹指南 | 新建文件夹的详细流程和参数说明 |
| "移动文件"/"移动文件夹"/"把文件移动到" | move-file.js |
约 2 秒 | 移动文件指南 | 移动文件或文件夹（含异步任务自动轮询和权限配置说明） |
| "移动知识库文档到云空间"/"移动Wiki到云盘"/"知识库文档移出" | move-wiki-to-docs.js |
约 2-15 秒 | 移动知识库文档至云空间指南 | 将知识空间（Wiki）节点移动至云空间文件夹（跨体系移动，含异步任务自动轮询和权限配置说明） |
| "删除文件"/"删除文件夹"/"移除文件到回收站" | delete-file.js |
约 2 秒 | 删除文件指南 | 删除文件或文件夹（含异步任务自动轮询） |
| "批量删除文件"/"批量删除"/"一次删除多个文件" | batch-delete-file.js |
视数量而定 | 批量删除文件指南 | 批量删除文件（输入 token 列表，内置频率控制，仅文件不含文件夹） |
| "查询异步任务"/"查询任务状态"/"查看任务进度" | task-check.js |
约 2 秒 | 查询异步任务指南 | 查询异步任务状态（删除/移动文件夹任务） |
| "获取tenant_access_token"/"刷新令牌" | get-tenant-access-token.js |
约 2 秒 | 访问令牌获取指南 | 访问令牌获取、刷新流程和凭证管理规则 |
| 脚本调用后自动执行（清理临时文件） | clear_temp.js |
约 1 秒 | — | 清理 $SKILL_DIR/temp 目录下的临时文件 |
| — | — | — | 错误码说明 | 所有错误码说明和解决方案 |
身份与访问令牌
飞书企业自建应用和飞书用户在飞书中是两个完全独立的"用户"，各自拥有独立的云空间，互相不可见。本 Skill 默认以飞书企业自建应用身份（tenant_access_token）操作应用自身空间的文档。
| Token 类型 | 归属身份 | 操作范围 | 有效期 | 获取方式 | 自动获取 |
|---|---|---|---|---|---|
tenant_access_token |
飞书企业自建应用 | 应用自身云空间的文档 | 约 2 小时 | 本 Skill 调用 get-tenant-access-token.js，凭 appId+appSecret 自动向飞书换取 |
✅ |
user_access_token |
飞书用户（个人） | 用户个人云空间的可见文档 | 约 2 小时 | 用户自行打开飞书开放平台 API 调试台网页，登录授权后复制 token 值（步骤见下文「user_access_token 获取步骤」） | ❌ |
⚠️ 令牌使用策略（重要）：本 Skill 优先复用
config.default.json中的tenant_access_token，默认不主动刷新，以避免不必要的换取请求。仅当其他业务脚本返回信息中出现"token 不合法"、"token 已过期"、"token 失效"等类似描述时，才运行cd "$SKILL_DIR/scripts" && node get-tenant-access-token.js --parameter-file-path <参数文件绝对路径>刷新令牌（脚本会自动将新令牌回写到配置文件，无需手动处理）。详细获取/刷新流程见 访问令牌获取指南。
如何切换身份：以飞书用户身份操作用户空间文档
若需操作用户个人空间的文档，所有脚本无需修改，只需修改凭证文件 $SKILL_DIR/config.default.json：
- 找到
"tenant_access_token"字段（键名保持不变，不要修改键名） - 将该字段的值替换为用户提供的
user_access_token值 - 保存后，所有脚本调用自动以飞书用户身份操作用户个人空间的文档
{
"appId": "cli_xxx",
"appSecret": "xxx",
"tenant_access_token": "eyxxxxxxxxxxxxxxxxxxxx",
...
}
💡 脚本内部统一通过该字段读取 token，并不关心其实际是 tenant 还是 user 类型 —— 飞书 API 服务端会根据 token 本身识别身份，因此只需替换值即可完成身份切换。
user_access_token 获取步骤
user_access_token 权限较高且需 OAuth 授权，本 Skill 不存储、不自动获取。需用户自行操作：
- 打开飞书开放平台 API 调试台：获取文件元数据
- 页面右侧 API 调试台请求头区域切换 Token 类型为
user_access_token - 登录授权后复制获取到的
user_access_token值 - 提供给 AI，AI 按上文「如何切换身份」写入
config.default.json后执行脚本
⚠️ 安全提示：
user_access_token具有用户级别的完整权限，请妥善保管。本 Skill 仅临时使用，不做持久化存储，执行完毕后临时文件会自动清理。
协作者机制（应用访问用户单个文档的另一种路径）
若飞书企业自建应用只希望操作用户个人空间里的个别文档，也可在飞书客户端打开目标文档 → 右上角「分享」→ 添加协作者 → 搜索应用名并授予权限（查看/编辑/管理）。适合"只操作个别文档"的场景；若需批量操作用户空间多个文档，推荐改用上述 user_access_token 方式。
全局错误处理
| 错误场景 | 处理方式 |
|---|---|
依赖缺失（Cannot find package 'probe-image-size'） |
重新安装依赖（命令见「环境说明」表） |
| 令牌失效（业务脚本返回"token 不合法/已过期/失效"等描述） | 自动刷新令牌（流程见「身份与访问令牌」章节），更新参数文件后重试 |
| 其他错误码 | 查阅 错误码说明 匹配解决方案 |