---

name: feishu-to-markdown-with-rustfs version: 1.0.0 description: Convert Feishu, Lark, or XFChat cloud docs to Markdown with optional RustFS or Care-Dev upload. Use when users provide a doc link. Triggers: 'feishu to markdown'. trigger: | TRIGGER when:

• User provides a Feishu, Lark, or XFChat /wiki/, /docx/, or /docs/ link
• User asks to convert a cloud document into Markdown
• User asks to preserve images and optionally upload them to RustFS or Care-Dev
• User asks for paste-ready Markdown for a knowledge base, column backend, or article editor

DO NOT TRIGGER when:

• The input is only local text or a local .docx file
• The task is general web scraping
• The user asks for PDF processing
• The user only wants Markdown editing or copywriting help references:
• references/feishu-openapi-flow.md
• references/care-dev-upload-flow.md allowed-tools:
• Read
• Edit
• Bash

---

飞书文档转 Markdown

将公司飞书、Lark 或 XFChat 文档链接转换为标准 Markdown。自动提取文字、标题、列表、表格、代码块、图片和部分嵌入式 sheet 内容；可将图片上传到 RustFS 或 Care-Dev，也可回退为本地 assets 目录。

使用方式

/feishu-to-markdown-with-rustfs

优先使用仓库内稳定入口：

• scripts/feishu_link_to_markdown.py

不要优先直接调用核心脚本，除非需要核对实现细节：

• scripts/feishu_docx_to_markdown.py

适用场景

当用户出现以下诉求时使用本 skill：

• “把这个飞书文档转成 Markdown”
• “把 wiki/docx/docs 链接转成可粘贴的 md”
• “保留图片并上传到 RustFS”
• “输出给知识库 / 专栏 / 文章后台”

Trigger / When to use

满足以下任一条件时触发：

• 用户提供 Feishu、Lark、XFChat 的 /wiki/、/docx/、/docs/ 链接
• 用户要求把飞书云文档转换为 Markdown
• 用户要求保留图片，并上传到 RustFS 或 Care-Dev
• 用户要求输出为适合知识库、专栏后台或文章系统粘贴的 Markdown

Do not use

仅适用于飞书、Lark、XFChat 云文档链接，不适用于：

• 本地 .docx 文件
• 普通网页抓取
• PDF 转换
• 没有云文档链接、只给出纯文本内容的场景

输入校验

执行前检查以下约束：

• 输入链接必须是 Feishu、Lark 或 XFChat 的文档链接
• 链接路径必须包含 /wiki/、/docx/ 或 /docs/
• 远程上传模式下必须提供上传目录
• Care-Dev 上传模式下必须提供后端地址和鉴权信息
• 若用户明确要求“不上传图片”，必须使用本地 assets 模式

权限与安全

• 不要在 SKILL.md 中写入真实 App Secret、Access Key、Secret Key 或 Token
• 优先从 ./.env.local 或环境变量读取敏感配置
• 命令示例中只使用环境变量占位，不写任何疑似真实密钥
• 仅在用户明确要求上传时，才使用远程上传能力
• 如果缺少凭据或权限不足，先说明缺失项，再回退到 --no-upload

操作指令

执行任务时遵循下面这些明确动作：

1. 先校验输入链接是否为 Feishu、Lark 或 XFChat 的 /wiki/、/docx/、/docs/ 链接。
2. 再确认输出路径、上传模式和上传目录。
3. 优先运行 scripts/feishu_link_to_markdown.py，不要默认直接调用核心脚本。
4. 若远程上传条件不完整，立即回退到 --no-upload 本地 assets 模式。
5. 转换完成后，必须检查 Markdown 输出路径、图片落点和 warning。
6. 若需要额外背景信息，再按需读取 references/，不要默认全部加载。

执行流程

Step 1：收集信息

先收集以下信息：

• 飞书文档链接，必填 支持格式：https://xxx.feishu.cn/docx/Xxx、/docs/Xxx、/wiki/Xxx
• 输出路径，选填 建议显式传 .md 路径，避免产物位置不明确
• 上传模式，选填 可选：
  • 上传到 RustFS
  • 上传到 Care-Dev
  • 不上传，仅保留本地图片
• 上传目录，远程上传时必填 常见值：
  • knowledge/column/{columnId}/article/{articleId}
  • knowledge/column/{columnId}/temp

如果用户没有提供输出路径，脚本默认写到当前工作目录，文件名默认为 <document-token>.md。

Step 2：检查环境

先确认 Python 可用，再确认依赖是否存在：

python --version 2>/dev/null || python3 --version
python3 -c "import requests" 2>/dev/null && echo "ok" || echo "missing"

如果 requests 缺失，提示：

pip install requests

如果用户要使用 --browser-cookies，再额外检查：

python3 -c "import browser_cookie3" 2>/dev/null && echo "ok" || echo "missing"

Step 3：准备凭据

先读取 skill 根目录下的：

• ./.env.local

不要假设仓库里一定存在 .env.example。只有它真实存在时才引用它。

飞书 OpenAPI 凭据

优先读取这些环境变量：

• CARE_FEISHU_APP_ID 或 FEISHU_APP_ID
• CARE_FEISHU_APP_SECRET 或 FEISHU_APP_SECRET
• CARE_FEISHU_BASE_URL 或 FEISHU_BASE_URL

默认 FEISHU_BASE_URL 为：

• https://open.feishu.cn

如果是 XFChat 私有网关，可使用：

• https://open.xfchat.iflytek.com

Care-Dev 上传参数

当用户要通过后端上传接口传图时，读取：

• CARE_DOCX_BASE_URL
• CARE_DOCX_TOKEN
• CARE_DOCX_DIRECTORY
• CARE_DOCX_TENANT_ID 可选
• CARE_DOCX_VISIT_TENANT_ID 可选

RustFS 直传参数

当用户要直接上传到 S3 兼容对象存储时，读取：

• CARE_DEV_FILE_S3_ENDPOINT
• CARE_DEV_FILE_S3_DOMAIN
• CARE_DEV_FILE_S3_BUCKET
• CARE_DEV_FILE_S3_ACCESS_KEY
• CARE_DEV_FILE_S3_ACCESS_SECRET
• CARE_DEV_FILE_S3_REGION 可选，默认 us-east-1
• CARE_DEV_FILE_S3_PATH_STYLE 可选

如果 RustFS 配置已存在，但未显式传 --directory，脚本会回退到：

• knowledge/column/temp

Step 4：执行转换

根据用户需求，选择下面一种方式执行。

方案 A：仅生成 Markdown，本地保存图片

python3 scripts/feishu_link_to_markdown.py \
  "https://www.xfchat.iflytek.com/wiki/xxxx" \
  --no-upload \
  --output /tmp/article.md \
  --assets-dir /tmp/article-assets

方案 B：通过 Care-Dev 接口上传图片

python3 scripts/feishu_link_to_markdown.py \
  "https://www.xfchat.iflytek.com/wiki/xxxx" \
  --base-url "$CARE_DOCX_BASE_URL" \
  --token "$CARE_DOCX_TOKEN" \
  --directory "knowledge/column/12/article/101" \
  --output /tmp/article.md

说明：

• --base-url 支持后端根地址
• --base-url 支持 admin-api 根地址
• --base-url 也支持完整上传接口地址
• --token 支持原始 token 或 Bearer ...

方案 C：直接上传到 RustFS

当 .env.local 已包含 RustFS 配置时执行：

python3 scripts/feishu_link_to_markdown.py \
  "https://www.xfchat.iflytek.com/wiki/xxxx" \
  --directory "knowledge/column/12/article/101" \
  --output /tmp/article.md

方案 D：读取本地浏览器 Cookie 抓取页面

仅在 OpenAPI 不方便使用、且本机已有登录态时使用：

python3 scripts/feishu_link_to_markdown.py \
  "https://www.feishu.cn/wiki/xxxx" \
  --browser-cookies \
  --browser chrome \
  --no-upload \
  --output /tmp/article.md

Step 5：验证输出

转换完成后，至少执行以下检查：

1. 确认 Markdown 文件已生成
2. 确认图片是远程 URL 或本地 assets 路径
3. 预览 Markdown 前几十行，确认标题和正文结构正常
4. 如果有表格、代码块、sheet，抽查转换效果

可执行：

ls -l /tmp/article.md

如果是本地图片模式，可执行：

ls -l /tmp/article-assets

如需快速预览 Markdown，可执行：

sed -n '1,40p' /tmp/article.md

Examples

示例 1：用户说“把这个飞书 wiki 链接转成 Markdown，图片不要上传，输出到 /tmp/article.md”。

执行方式：

python3 scripts/feishu_link_to_markdown.py \
  "https://www.feishu.cn/wiki/xxxx" \
  --no-upload \
  --output /tmp/article.md \
  --assets-dir /tmp/article-assets

示例 2：用户说“把这个文档转成可发专栏的 Markdown，图片上传到 knowledge/column/12/article/101”。

执行方式：

python3 scripts/feishu_link_to_markdown.py \
  "https://www.xfchat.iflytek.com/wiki/xxxx" \
  --directory "knowledge/column/12/article/101" \
  --output /tmp/article.md

示例 3：用户说“用 Care-Dev 接口上传图片，输出 Markdown 到固定路径”。

执行方式：

python3 scripts/feishu_link_to_markdown.py \
  "https://www.xfchat.iflytek.com/wiki/xxxx" \
  --base-url "$CARE_DOCX_BASE_URL" \
  --token "$CARE_DOCX_TOKEN" \
  --directory "$CARE_DOCX_DIRECTORY" \
  --output /tmp/article.md

错误处理

常见问题与建议：

| 错误关键词 | 常见原因 | 处理建议 | | --- | --- | --- | | This script only accepts a Feishu wiki/docx URL | 链接格式不支持 | 换成原始 /wiki/、/docx/、/docs/ 链接 | | tenant_access_token response was empty | 飞书凭据错误或网关不通 | 检查 FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_BASE_URL | | --base-url or CARE_DOCX_BASE_URL is required when upload is enabled | 开启上传但未提供后端地址 | 补充 --base-url 或环境变量 | | --token or CARE_DOCX_TOKEN is required when upload is enabled | 开启 Care-Dev 上传但未提供 token | 补充 --token 或环境变量 | | --directory or CARE_DOCX_DIRECTORY is required when upload is enabled | 上传目录缺失 | 提供文章目录或草稿目录 | | warning=sheet_fallback | 无法展开嵌入 sheet | 检查飞书应用的 Sheets 权限和文档授权 | | warning=mixed_content_risk | 图片还是 http:// 链接 | HTTPS 页面预览可能被浏览器拦截 | | 上传失败 | token、目录、接口地址或 RustFS 配置不正确 | 优先检查上传链路配置，必要时回退 --no-upload |

回退策略

除非用户明确要求“必须远程上传图片”，否则失败时按下面顺序回退：

1. 优先使用用户指定的上传方式
2. 若另一种远程上传方式已具备条件，可尝试切换
3. 最后回退到 --no-upload，将图片保存到本地 assets 目录

如果用户明确说“不要上传图片”，始终使用：

• --no-upload

输出规范

成功后至少向用户说明：

• Markdown 输出路径
• 图片是远程上传还是本地保存
• 如果是本地保存，assets 目录在哪里
• 是否出现影响发布或预览的 warning

典型输出形态：

<输出路径>/article.md
<输出路径>/article-assets/

如果启用远程上传，Markdown 中的图片应为远程 URL。
如果未启用上传，Markdown 中的图片应引用本地 assets 目录下的文件。

前置条件

• Python 3 可用
• 已安装 requests
• 若使用浏览器 Cookie 模式，已安装 browser_cookie3
• 飞书开放平台应用具备文档读取能力
• 若要上传图片，具备 Care-Dev 或 RustFS 对应配置
• 若要展开 sheet，应用还需要相应的表格读取权限

限制 / 不触发条件

• 不负责创建飞书应用或开通权限，只消费已有配置
• 不保证 100% 还原复杂排版、合并单元格或所有嵌入对象
• 没有可用凭据时，不应伪造上传成功结果
• 用户未提供云文档链接时，不应触发本 skill
• 若用户需求只是“解释一段 Markdown”或“润色文案”，不应触发本 skill

References / See also

只在需要时读取，不要默认全部加载：

• references/feishu-openapi-flow.md 当飞书鉴权、文档解析、sheet 拉取异常时查看
• references/care-dev-upload-flow.md 当 Care-Dev 上传链路、目录约定、接口路径不清楚时查看

写给 Agent 的规则

• 优先给出明确输出路径，避免生成后找不到文件
• 优先使用 scripts/feishu_link_to_markdown.py
• 指令要短、直给、可执行，不要写成长篇产品说明
• 不要承诺仓库中不存在的文件或能力
• 不要默认加载全部 references，按需读取