# Feishu DOCX Yashu

> 本技能用于飞书文档(Docx)与Markdown互转，以及飞书云空间文件夹管理。激活条件：用户消息须包含以下关键词之一:`本地Markdown转飞书云文档`、`飞书云文档转本地Markdown`、`解析飞书云文档链接`、`获取飞书云文档的指定文件夹的token`、`飞书云文档新建文件夹`、`飞书云文档移动文件夹`、`飞书云文档获取指定文件夹的文件清单`、`获取飞书云文档的文件元数据`、`获取飞书云文档我的空间根文件夹元数据`、`飞书云文档搜索文档`、`飞书云文档移动知识库文档到云空间`、`飞书云文档移动Wiki到云盘`、`飞书云文档知识库文档移出`。

- Skill: `steelan9199/feishu-docx-yashu` (Agent Skill, multi-file: 39 files)
- Install (CLI): `npx skillmds add steelan9199/feishu-docx-yashu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/feishu-docx-yashu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: steelan9199 (https://skillmd.com/u/steelan9199)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/steelan9199/feishu-docx-yashu

---


# 飞书文档 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转飞书指南]($SKILL_DIR/references/markdown-to-feishu.md)        | Markdown 上传到飞书的详细步骤、参数说明、Callout 格式检查与自动修正规则                                                                                         |
| "飞书文档下载为Markdown"/"下载飞书文档为Markdown"/"飞书文档转Markdown" | `feishu-to-markdown.js`                | 约 5-10 秒 | [飞书转Markdown指南]($SKILL_DIR/references/feishu-to-markdown.md)        | 飞书文档下载为 Markdown 的详细流程                                                                                                                              |
| "解析飞书文档链接"/"获取document_id"/"从链接提取文档ID"                | `url-to-document-id.js`                | 约 2 秒    | [链接解析指南]($SKILL_DIR/references/url-to-document-id.md)              | 飞书云文档链接解析为 document_id（文件 token）的详细流程                                                                                                        |
| "搜索文件夹"/"搜索云文档"/"搜索文档"/"查找云文档"                      | `search-document.js`                   | 约 2 秒    | [搜索云文档指南]($SKILL_DIR/references/search-document.md)               | 根据关键词搜索当前用户可见云文档、文件夹、知识库及知识库内文档（支持 tenant_access_token 与 user_access_token，支持分页与 doc_filter/wiki_filter 过滤）         |
| "从链接提取文件夹token"                                              | 不需要脚本                             | 约 2 秒    | [获取文件夹token指南]($SKILL_DIR/references/get-folder-token.md)         | 从链接提取文件夹token |
| "获取文件夹元数据"/"获取folder_meta"/"查看文件夹信息"                  | `get-folder-meta.js`                   | 约 2 秒    | [获取文件夹元数据指南]($SKILL_DIR/references/get-folder-meta.md)         | 获取文件夹元数据（ID、名称、创建者等）                                                                                                                          |
| "获取我的空间"/"获取根文件夹"/"获取root_folder_meta"                   | `get-root-folder-meta.js`              | 约 2 秒    | [获取我的空间元数据指南]($SKILL_DIR/references/get-root-folder-meta.md)  | 获取我的空间（根文件夹）元数据（token、ID、所有者 ID）                                                                                                          |
| "获取文件元数据"/"获取file_meta"/"查看文件信息"/"批量获取文件元数据"   | `get-file-meta.js`                     | 约 2 秒    | [获取文件元数据指南]($SKILL_DIR/references/get-file-meta.md)             | 根据文件 token 批量获取任意类型文件元数据（标题、所有者、密级、URL 等），含 doc_type 推断规则                                                                   |
| "获取文件夹文件清单"/"获取文件列表"/"列出文件夹中的文件"               | `get-files.js`                         | 约 2 秒    | [获取文件清单指南]($SKILL_DIR/references/get-files.md)                   | 获取文件夹中的文件清单（名称、类型、token、URL 等）。**默认排除文件夹**：除非用户明确提及"文件夹"或"包括文件夹"，否则参数文件中必须添加 `"filter_type": "file"` |
| "新建文件夹"/"创建文件夹"/"在云空间创建文件夹"                         | `create-folder.js`                     | 约 2 秒    | [新建文件夹指南]($SKILL_DIR/references/create-folder.md)                 | 新建文件夹的详细流程和参数说明                                                                                                                                  |
| "移动文件"/"移动文件夹"/"把文件移动到"                                 | `move-file.js`                         | 约 2 秒    | [移动文件指南]($SKILL_DIR/references/move-file.md)                       | 移动文件或文件夹（含异步任务自动轮询和权限配置说明）                                                                                                            |
| "移动知识库文档到云空间"/"移动Wiki到云盘"/"知识库文档移出"             | `move-wiki-to-docs.js`                 | 约 2-15 秒 | [移动知识库文档至云空间指南]($SKILL_DIR/references/move-wiki-to-docs.md) | 将知识空间（Wiki）节点移动至云空间文件夹（跨体系移动，含异步任务自动轮询和权限配置说明）                                                                        |
| "删除文件"/"删除文件夹"/"移除文件到回收站"                             | `delete-file.js`                       | 约 2 秒    | [删除文件指南]($SKILL_DIR/references/delete-file.md)                     | 删除文件或文件夹（含异步任务自动轮询）                                                                                                                          |
| "批量删除文件"/"批量删除"/"一次删除多个文件"                           | `batch-delete-file.js`                 | 视数量而定 | [批量删除文件指南]($SKILL_DIR/references/batch-delete-file.md)           | 批量删除文件（输入 token 列表，内置频率控制，仅文件不含文件夹）                                                                                                 |
| "查询异步任务"/"查询任务状态"/"查看任务进度"                           | `task-check.js`                        | 约 2 秒    | [查询异步任务指南]($SKILL_DIR/references/task-check.md)                  | 查询异步任务状态（删除/移动文件夹任务）                                                                                                                         |
| "获取tenant_access_token"/"刷新令牌"                                   | `get-tenant-access-token.js`           | 约 2 秒    | [访问令牌获取指南]($SKILL_DIR/references/get-tenant-access-token.md)     | 访问令牌获取、刷新流程和凭证管理规则                                                                                                                            |
| 脚本调用后自动执行（清理临时文件）                                     | `clear_temp.js`                        | 约 1 秒    | —                                                                        | 清理 `$SKILL_DIR/temp` 目录下的临时文件                                                                                                                         |
| —                                                                      | —                                      | —          | [错误码说明]($SKILL_DIR/references/error-code.md)                        | 所有错误码说明和解决方案                                                                                                                                        |

## 身份与访问令牌

**飞书企业自建应用**和**飞书用户**在飞书中是两个完全独立的"用户"，各自拥有独立的云空间，互相不可见。本 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/references/get-tenant-access-token.md)。

### 如何切换身份：以飞书用户身份操作用户空间文档

若需操作**用户个人空间**的文档，**所有脚本无需修改**，只需修改凭证文件 `$SKILL_DIR/config.default.json`：

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

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

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

### user_access_token 获取步骤

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

1. 打开飞书开放平台 API 调试台：[获取文件元数据](https://open.feishu.cn/document/server-docs/docs/drive-v1/file/batch_query)
2. 页面右侧 API 调试台请求头区域切换 Token 类型为 `user_access_token`
3. 登录授权后复制获取到的 `user_access_token` 值
4. 提供给 AI，AI 按上文「如何切换身份」写入 `config.default.json` 后执行脚本

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

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

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

## 全局错误处理

| 错误场景                                                 | 处理方式                                                            |
| -------------------------------------------------------- | ------------------------------------------------------------------- |
| 依赖缺失（`Cannot find package 'probe-image-size'`）     | 重新安装依赖（命令见「环境说明」表）                                |
| 令牌失效（业务脚本返回"token 不合法/已过期/失效"等描述） | 自动刷新令牌（流程见「身份与访问令牌」章节），更新参数文件后重试    |
| 其他错误码                                               | 查阅 [错误码说明]($SKILL_DIR/references/error-code.md) 匹配解决方案 |