feishu-sync

name	feishu-sync
description	使用Playwright自动同步文档到飞书。Use for tasks like syncing markdown to Feishu, automating Feishu document updates, browser automation for Feishu. Keywords: 飞书同步, feishu sync, playwright, 文档同步, 自动化

feishu-sync

使用Playwright自动化同步Markdown文档到飞书Wiki/文档

Use this skill for 飞书文档自动同步、Markdown到飞书的自动化、浏览器自动化操作飞书。

---

快速使用

前置条件

# 确保使用anaconda python（已安装playwright）
/opt/anaconda3/bin/python3 -c "from playwright.sync_api import sync_playwright; print('OK')"

# 如未安装，执行：
pip install playwright pyperclip
playwright install chromium

运行同步

/opt/anaconda3/bin/python3 scripts/sync_to_feishu.py

---

核心脚本

位置: scripts/sync_to_feishu.py

关键配置

# 目标飞书文档URL
FEISHU_URL = "https://xxx.feishu.cn/wiki/xxxxxxx"

# 源文件路径
REPORT_PATH = Path("docs/research/your-report.md")

执行流程

1. 读取本地Markdown文件
2. 复制内容到系统剪贴板
3. 启动Chrome浏览器（非无头模式）
4. 导航到飞书文档
5. 检测登录状态，等待用户登录（5分钟超时）
6. 登录后自动点击编辑区域
7. 移动到文档末尾，添加分隔线
8. 自动粘贴内容（Cmd+V）
9. 等待用户确认后关闭浏览器

---

最佳实践

1. 使用系统Chrome而非下载Chromium

# 推荐：使用系统安装的Chrome，避免下载超时
browser = await p.chromium.launch(
    headless=False,
    channel="chrome"  # 关键参数
)

原因: Chromium下载经常超时（30s），使用系统Chrome可跳过下载步骤。

2. 禁用输出缓冲

# 在脚本开头添加，确保实时输出
sys.stdout.reconfigure(line_buffering=True)
sys.stderr.reconfigure(line_buffering=True)

原因: 后台运行时输出会被缓冲，无法实时监控进度。

3. 设置足够的登录超时

await page.wait_for_url(
    lambda url: "wiki" in url and "accounts" not in url,
    timeout=300000  # 5分钟，给用户足够时间扫码登录
)

原因: 扫码登录需要时间，2分钟可能不够。

4. 多种编辑区域选择器

editor_selectors = [
    '[data-testid="doc-editor"]',
    '.doc-content',
    '.suite-markdown-container',
    '[contenteditable="true"]',  # 最通用
    '.editor-container',
    '.wiki-content',
    '.lark-editor',
]

原因: 飞书不同版本/页面的编辑器选择器可能不同。

5. 使用pyperclip处理剪贴板

import pyperclip
pyperclip.copy(report_content)

# 然后用键盘快捷键粘贴
await page.keyboard.press('Meta+v')

原因: 直接用Playwright的fill()方法对富文本编辑器兼容性差。

---

常见问题

Q1: Chromium下载超时

Error: Request to https://cdn.playwright.dev/... timed out after 30000ms

解决: 使用 channel="chrome" 参数使用系统Chrome。

Q2: 登录超时

❌ 登录超时或失败: Timeout 120000ms exceeded

解决:

1. 增加timeout到300000ms（5分钟）
2. 确保浏览器窗口可见，及时完成登录

Q3: 找不到编辑区域

⚠️ 未找到编辑区域，尝试点击页面中心...

解决:

1. 检查飞书文档是否有编辑权限
2. 尝试手动点击编辑区域后再运行脚本

Q4: 粘贴失败

解决:

1. 确保pyperclip已安装
2. macOS需要授予终端剪贴板访问权限
3. 手动按Cmd+V作为备选

Q5: 输出为空/无法监控进度

解决: 添加 sys.stdout.reconfigure(line_buffering=True)

---

扩展场景

同步到多个文档

FEISHU_URLS = [
    "https://xxx.feishu.cn/wiki/doc1",
    "https://xxx.feishu.cn/wiki/doc2",
]

for url in FEISHU_URLS:
    await sync_to_document(page, url, content)

定时同步

# crontab -e
0 9 * * * /opt/anaconda3/bin/python3 /path/to/sync_to_feishu.py >> /var/log/feishu-sync.log 2>&1

替换而非追加

# 全选后粘贴，替换全部内容
await page.keyboard.press('Meta+a')
await page.keyboard.press('Meta+v')

---

完整脚本模板

#!/opt/anaconda3/bin/python3
"""飞书文档自动同步"""

import asyncio
import sys
from pathlib import Path

sys.stdout.reconfigure(line_buffering=True)
sys.stderr.reconfigure(line_buffering=True)

from playwright.async_api import async_playwright
import pyperclip

FEISHU_URL = "https://xxx.feishu.cn/wiki/xxx"
SOURCE_FILE = Path("docs/your-file.md")

async def sync():
    content = SOURCE_FILE.read_text(encoding="utf-8")
    pyperclip.copy(content)

    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False, channel="chrome")
        page = await (await browser.new_context()).new_page()

        await page.goto(FEISHU_URL)
        await page.wait_for_timeout(3000)

        # 等待登录
        if "accounts" in page.url:
            print("请登录飞书...")
            await page.wait_for_url(
                lambda u: "wiki" in u and "accounts" not in u,
                timeout=300000
            )

        # 点击编辑区域
        await page.wait_for_timeout(3000)
        await page.click('[contenteditable="true"]', timeout=5000)

        # 粘贴
        await page.keyboard.press('Meta+End')
        await page.keyboard.press('Enter')
        await page.keyboard.press('Meta+v')

        print("✅ 同步完成")
        await page.wait_for_event('close', timeout=300000)
        await browser.close()

if __name__ == "__main__":
    asyncio.run(sync())

---

相关资源

• Playwright Python文档: https://playwright.dev/python/
• 飞书开放平台: https://open.feishu.cn/
• pyperclip: https://pypi.org/project/pyperclip/