md-lark-converter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown ↔ Feishu Converter

Markdown ↔ 飞书转换器

Two CLI commands handle the conversion:

md2fs
— Markdown → Feishu clipboard format (paste directly into Feishu docs)
fs2md
— Feishu → Markdown (fetch via URL, with automatic image download)

Both are provided by

@md-lark-converter/cli

两个CLI命令负责处理转换：

md2fs
—— Markdown → 飞书剪贴板格式（可直接粘贴到飞书文档）
fs2md
—— 飞书 → Markdown（通过URL获取，支持自动下载图片）

以上命令均由

@md-lark-converter/cli

提供。

First: Check CLI Availability

第一步：检查CLI是否可用

Before running any command, verify the CLI is installed:

bash

which md2fs 2>/dev/null || echo "NOT_INSTALLED"

If not installed, install it:

bash

npm install -g @md-lark-converter/cli

运行任何命令前，请先验证CLI是否已安装：

bash

which md2fs 2>/dev/null || echo "NOT_INSTALLED"

如果未安装，请执行以下命令安装：

bash

npm install -g @md-lark-converter/cli

Markdown → Feishu (md2fs)

Markdown → 飞书（md2fs）

The most common use case — the user has Markdown content and wants it in Feishu.

bash

undefined

最常见的使用场景——用户拥有Markdown内容并希望导入到飞书。

bash

undefined

Convert and copy to clipboard — user pastes directly into Feishu

转换并复制到剪贴板——用户可直接粘贴到飞书

md2fs <file.md> --copy

Pipe content from stdin

从标准输入管道传入内容

echo "# Hello World" | md2fs --stdin --copy

Save raw Lark JSON (for debugging or programmatic use)

保存原始Lark JSON（用于调试或程序化调用）

md2fs <file.md> -o output.json


After `md2fs --copy` succeeds, tell the user: "Content copied to clipboard — paste into your Feishu document with Cmd+V / Ctrl+V."

If clipboard copy fails (common on headless/remote environments), `md2fs` falls back to printing HTML to stdout. In that case, suggest saving to a JSON file with `-o` instead.

md2fs <file.md> -o output.json


`md2fs --copy`执行成功后，请告知用户：“内容已复制到剪贴板——使用Cmd+V / Ctrl+V粘贴到你的飞书文档中即可。”

如果剪贴板复制失败（在无头/远程环境中常见），`md2fs`会自动回退到将HTML输出到标准输出。这种情况下，建议用户使用`-o`参数将内容保存为JSON文件。

Feishu → Markdown (fs2md)

飞书 → Markdown（fs2md）

Fetches a Feishu document by URL and converts to Markdown. Requires authentication — see Cookie Setup below.

bash

undefined

通过URL获取飞书文档并转换为Markdown格式。此功能需要身份验证——请参阅下方的Cookie设置部分。

bash

undefined

Save to file (images auto-downloaded to ./images/ next to the output)

保存到文件（图片会自动下载到输出文件旁的./images/目录）

fs2md <feishu-url> -o output.md

Copy Markdown to clipboard instead of saving

将Markdown复制到剪贴板而非保存到文件

fs2md <feishu-url>

Skip image downloading

跳过图片下载

fs2md <feishu-url> -o output.md --no-images

undefined

fs2md <feishu-url> -o output.md --no-images

undefined

Supported URL formats

支持的URL格式

Both document types are supported — wiki URLs are auto-resolved to the underlying docx:

```
https://xxx.feishu.cn/docx/TOKEN
```
```
https://xxx.feishu.cn/wiki/TOKEN
```

两种文档类型均支持——wiki URL会自动解析为对应的docx文档：

```
https://xxx.feishu.cn/docx/TOKEN
```
```
https://xxx.feishu.cn/wiki/TOKEN
```

Image handling

图片处理

By default, all images in the document are downloaded to an

images/

directory alongside the output file, and Markdown references are rewritten to

./images/filename.png

. Use

--no-images

if you only need the text.

默认情况下，文档中的所有图片都会下载到输出文件旁的

images/

目录，并且Markdown中的图片引用会重写为

./images/filename.png

。如果仅需要文本内容，请使用

--no-images

参数。

Cookie Setup (Required for fs2md)

Cookie设置（fs2md必需）

fs2md

needs a Feishu session cookie to access documents. The cookie is resolved in this order:

```
--cookie
```
CLI flag (one-off use)
```
FEISHU_COOKIE
```
environment variable
```
~/.md-lark-converter.json
```
config file (recommended for persistent use)

fs2md

需要飞书会话Cookie才能访问文档。Cookie的读取优先级如下：

```
--cookie
```
CLI参数（一次性使用）
```
FEISHU_COOKIE
```
环境变量
```
~/.md-lark-converter.json
```
配置文件（推荐用于持久化使用）

Check if cookie is already configured

检查Cookie是否已配置

bash

cat ~/.md-lark-converter.json 2>/dev/null

If the config file exists and contains a cookie, try using it directly. Only proceed with cookie setup if it's missing or expired (authentication errors).

bash

cat ~/.md-lark-converter.json 2>/dev/null

如果配置文件存在且包含Cookie，可直接尝试使用。仅当Cookie缺失或过期（出现身份验证错误）时，才需要进行Cookie设置。

Obtaining the cookie

获取Cookie

When a cookie is needed (missing or expired), proactively ask the user:

"I need a Feishu session cookie to fetch documents. Would you like me to automatically open a browser and extract it after you log in? Or would you prefer to copy it manually from DevTools?"

当需要Cookie时（缺失或过期），请主动询问用户：

“我需要一个飞书会话Cookie来获取文档。你希望我自动打开浏览器并在你登录后提取Cookie？还是更愿意从开发者工具中手动复制？”

Option A: Automatic extraction via MCP browser tool

选项A：通过MCP浏览器工具自动提取

IMPORTANT: Do NOT write a Playwright/Puppeteer script file to implement this. Use an MCP browser tool.

If the user chooses automatic extraction:

Check if an MCP browser tool (e.g. Playwright MCP) is available in the current session
If not available, tell the user they need to configure one first, and suggest adding this to
```
.mcp.json
```
in the project root or
```
~/.claude/mcp.json
```
globally:
json
```
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}
```
Then ask the user to restart the session after adding the config.
If available, use the MCP browser tool to:
1. Launch a headed browser and navigate to
```
https://www.feishu.cn
```
2. Tell the user to log in within the browser window
3. Poll the browser cookies every 2 seconds, checking for
```
session_list_v5
```
  or
```
_csrf_token
```
  cookie names — their presence indicates a successful login
4. Once detected, collect all cookies whose domain includes
```
feishu.cn
```
  or
```
lark
```
  , format them as
```
name=value; name=value; ...
```
5. Save to
```
~/.md-lark-converter.json
```
  :
  json
```
{ "cookie": "<collected-cookie-string>" }
```
6. Close the browser and confirm to the user that the cookie has been saved

Key details:

Use
```
headless: false
```
— the user needs to interact with the login page
Set a generous timeout (5 minutes) for the polling loop — login may involve 2FA or SSO
Do NOT rely on URL pattern matching after login; Feishu may redirect to various paths

重要提示：请勿编写Playwright/Puppeteer脚本文件来实现此功能，请使用MCP浏览器工具。

如果用户选择自动提取：

检查当前会话中是否有可用的MCP浏览器工具（如Playwright MCP）

如果不可用，告知用户需要先配置该工具，并建议在项目根目录的

.mcp.json

或全局的

~/.claude/mcp.json

中添加以下配置：

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}

然后请用户添加配置后重启会话。

如果可用，使用MCP浏览器工具执行以下步骤：
1. 启动带界面的浏览器并导航到
```
https://www.feishu.cn
```
2. 告知用户在浏览器窗口中完成登录
3. 每2秒轮询一次浏览器Cookie，检查是否存在
```
session_list_v5
```
  或
```
_csrf_token
```
  Cookie——这些Cookie的存在表示登录成功
4. 检测到Cookie后，收集所有域包含
```
feishu.cn
```
  或
```
lark
```
  的Cookie，格式化为
```
name=value; name=value; ...
```
5. 保存到
```
~/.md-lark-converter.json
```
  ：
  json
```
{ "cookie": "<收集到的Cookie字符串>" }
```
6. 关闭浏览器并向用户确认Cookie已保存

关键细节：

使用
```
headless: false
```
——用户需要与登录页面交互
为轮询循环设置足够长的超时时间（5分钟）——登录可能涉及双因素认证或单点登录
不要依赖登录后的URL模式匹配——飞书可能会重定向到不同路径

Option B: Manual extraction from DevTools (default)

选项B：从开发者工具手动提取（默认方式）

Guide the user through manual extraction:

Open a Feishu document in the browser (e.g.
```
https://xxx.feishu.cn/docx/...
```
)
Open DevTools —
```
F12
```
(Windows/Linux) or
```
Cmd+Option+I
```
(macOS)
Switch to the Network tab, refresh the page
Click any request to
```
feishu.cn
```
In the request headers, copy the entire Cookie header value (it's long — that's expected)
Save to config file:

bash

cat > ~/.md-lark-converter.json << 'EOF'
{
  "cookie": "YOUR_COOKIE_HERE"
}
EOF

引导用户手动提取Cookie：

在浏览器中打开一个飞书文档（如
```
https://xxx.feishu.cn/docx/...
```
）
打开开发者工具——Windows/Linux按
```
F12
```
，macOS按
```
Cmd+Option+I
```
切换到网络标签页，刷新页面
点击任何发送到
```
feishu.cn
```
的请求
在请求头中，复制整个Cookie头的值（内容很长，这是正常的）
保存到配置文件：

bash

cat > ~/.md-lark-converter.json << 'EOF'
{
  "cookie": "YOUR_COOKIE_HERE"
}
EOF

Cookie expiration

Cookie过期

The cookie expires periodically (typically after a few days). If

fs2md

returns authentication errors or empty results, the cookie needs to be refreshed. Ask the user again whether they'd like automatic or manual extraction.

Cookie会定期过期（通常几天后）。如果

fs2md

返回身份验证错误或空结果，说明Cookie需要刷新。请再次询问用户希望选择自动浏览器提取还是手动从开发者工具复制。

Decision Flow

决策流程

When the user's request involves Feishu:

User has Markdown, wants it in Feishu →

Identify the Markdown file path or content
Run
```
md2fs <path> --copy
```
Confirm clipboard is ready for pasting

User wants Feishu content as Markdown →

Get the Feishu document URL

Check cookie:

cat ~/.md-lark-converter.json 2>/dev/null

If no cookie exists, ask the user whether to auto-extract via browser automation or manually copy from DevTools
Run
```
fs2md <url> -o <output-path>
```
Report the saved file path and image count

User shares a feishu.cn link without explicit instructions → Ask whether they want to export it as Markdown. If yes, follow the Feishu → Markdown flow.

User mentions Feishu cookie / authentication issues → Check the existing config, then offer automatic browser extraction first, with manual DevTools as fallback.

当用户的请求涉及飞书时：

用户拥有Markdown内容，希望导入到飞书 →

确定Markdown文件路径或内容
运行
```
md2fs <path> --copy
```
确认剪贴板已准备好粘贴

用户希望将飞书内容转换为Markdown →

获取飞书文档URL

检查Cookie：

cat ~/.md-lark-converter.json 2>/dev/null

如果没有Cookie，询问用户是否通过浏览器自动化自动提取，还是从开发者工具手动复制
运行
```
fs2md <url> -o <output-path>
```
报告保存的文件路径和图片数量

用户分享feishu.cn链接但未给出明确指令 → 询问用户是否要将其导出为Markdown。如果是，按照飞书→Markdown的流程操作。

用户提到飞书Cookie/身份验证问题 → 检查现有配置，然后优先提供自动浏览器提取选项，同时将手动开发者工具提取作为备选。