---
name: feishu-docx-yashu
description: 本技能用于飞书文档(Docx)与Markdown互转，以及飞书云空间文件夹管理。激活条件：用户消息须包含以下关键词之一:`本地Markdown转飞书云文档`、`飞书云文档转本地Markdown`、`解析飞书云文档链接`、`获取飞书云文档的指定文件夹的token`、`飞书云文档新建文件夹`、`飞书云文档移动文件夹`、`飞书云文档获取指定文件夹的文件清单`、`获取飞书云文档的文件元数据`、`获取飞书云文档我的空间根文件夹元数据`、`飞书云文档搜索文档`、`飞书云文档移动知识库文档到云空间`、`飞书云文档移动Wiki到云盘`、`飞书云文档知识库文档移出`。
metadata:
  author: "AI Assistant"
  updated: "2026-08-07 00:00:00"
  version: "1.8.0"
title: feishu-docx-yashu
canonical_url: https://skilld.dev/gh/steelan9199/wechat-publisher/feishu-docx-yashu
last_updated: 2026-10-07T07:20:50.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 38 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-docx-yashu/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install steelan9199/wechat-publisher/feishu-docx-yashu`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/feishu-docx-yashu`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/steelan9199/wechat-publisher/feishu-docx-yashu) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/feishu-docx-yashu`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/feishu-docx-yashu --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/feishu-docx-yashu --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

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