飞书文档 Markdown 互转与云空间文件管理

飞书云文档产品简介

云文档是飞书在线文档、电子表格、多维表格、知识库、云空间等产品的统称。

飞书云文档中，放置文档的容器有两种类型：云盘和知识库。

• 云盘：云盘内可创建文件夹，用于组织和管理文件。"云盘"是飞书 drive 的新名称（旧称"云空间"），本文档中两者同义，统一指代 cloud drive。
• 知识库：知识库(Wiki)是独立于云盘的文档容器，用户可拥有多个知识库。与云盘通过文件夹组织文件不同，知识库通过知识空间和节点构建层级体系（详见下文「飞书云文档的知识库简介」）。

用户新建云文档时，若未指定位置，文档默认存放在我的文档库中——这是系统默认的知识库。

飞书云文档的知识库简介

飞书知识库是一个面向组织的知识管理系统，通过结构化沉淀高价值信息，形成完整的知识体系，能够提升知识的流转和传播效率。

知识库和文件夹不是同一概念：

• 知识库的基础组成单位是知识空间，是企业根据需要搭建的不同类别的知识体系，由多个具有层级和所属关系的文档页面构成，每个知识空间有唯一的 space_id 作为标识。
• 知识空间中的内容以节点的形式组织，节点支持文档、表格等多种文件类型，节点之间可以形成层级的页面树结构。
• 而文件夹是云空间中用于管理文件和其它文件夹的容器，和知识库的组织逻辑、能力定位存在区别。

功能概述

提供飞书文档与 Markdown 互转、云盘文件/文件夹管理、跨体系移动（Wiki → 云盘）、文件元数据查询、云文档搜索等能力。具体能力、脚本与参考文档的对应关系见下方「触发映射与文档索引」。上传 Markdown 到飞书文档前，由 AI 在会话层预处理 Callout 格式（脚本仅校验不修正）。

环境说明

⚠️ $SKILL_DIR 仅为文档占位符，不是环境变量，执行命令时必须替换为实际绝对路径。在 bash 中直接写 $SKILL_DIR 而不加双引号时，若路径含空格会分词；若未替换则被解析为空字符串，导致 cd "$SKILL_DIR/scripts" 变成 cd "/scripts" 而报错"找不到路径"。

本 Skill 运行命令时采用 bash && 链式依赖执行（前一条成功才执行下一条），例子：cmd1 && cmd2

⚠️ 脚本已混淆，禁止读取源码

$SKILL_DIR/scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理，禁止读取或分析 .js 文件内容。混淆代码可读性极差，读取纯属浪费 token 和时间。

如需了解脚本功能和用法，请查阅下方「触发映射与文档索引」表。

全局前置条件

跨功能公共规则（必须遵守）

标准执行命令模板（端到端流程：读取凭证 → 读参考文档 → Write 写参数文件 → 执行 → 处理结果 → 清理）：

cd "$SKILL_DIR/scripts" && node <脚本名>.js --parameter-file-path <参数文件绝对路径>

成功：返回结果数据给用户；失败：根据错误码匹配解决方案并重试。

脚本日志输出机制

$SKILL_DIR/scripts/ 目录下的 JS 脚本的所有日志均通过 console.error 输出至标准错误流（stderr）

据此，脚本运行期间产生的所有输出（含进度日志与结构化结果数据 JSON）均经由 stderr 输出，标准输出流（stdout）为空。AI 在调用脚本、捕获输出时应知晓此特性。

触发映射与文档索引

下表合并了用户触发词、对应脚本、预计耗时与参考文档摘要。

身份与访问令牌

飞书企业自建应用和飞书用户在飞书中是两个完全独立的"用户"，各自拥有独立的云空间，互相不可见。本 Skill 默认以飞书企业自建应用身份（tenant_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：

1. 找到 "tenant_access_token" 字段（键名保持不变，不要修改键名）
2. 将该字段的值替换为用户提供的 user_access_token 值
3. 保存后，所有脚本调用自动以飞书用户身份操作用户个人空间的文档

{
  "appId": "cli_xxx",
  "appSecret": "xxx",
  "tenant_access_token": "eyxxxxxxxxxxxxxxxxxxxx",
  ...
}

💡 脚本内部统一通过该字段读取 token，并不关心其实际是 tenant 还是 user 类型 —— 飞书 API 服务端会根据 token 本身识别身份，因此只需替换值即可完成身份切换。

user_access_token 获取步骤

user_access_token 权限较高且需 OAuth 授权，本 Skill 不存储、不自动获取。需用户自行操作：

1. 打开飞书开放平台 API 调试台：获取文件元数据
2. 页面右侧 API 调试台请求头区域切换 Token 类型为 user_access_token
3. 登录授权后复制获取到的 user_access_token 值
4. 提供给 AI，AI 按上文「如何切换身份」写入 config.default.json 后执行脚本

⚠️ 安全提示：user_access_token 具有用户级别的完整权限，请妥善保管。本 Skill 仅临时使用，不做持久化存储，执行完毕后临时文件会自动清理。

协作者机制（应用访问用户单个文档的另一种路径）

若飞书企业自建应用只希望操作用户个人空间里的个别文档，也可在飞书客户端打开目标文档 → 右上角「分享」→ 添加协作者 → 搜索应用名并授予权限（查看/编辑/管理）。适合"只操作个别文档"的场景；若需批量操作用户空间多个文档，推荐改用上述 user_access_token 方式。

全局错误处理