# feishu-sync

**Repository Path**: SKINGAP/feishu-sync

## Basic Information

- **Project Name**: feishu-sync
- **Description**: 获取飞书内容
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# feishu-sync

把飞书知识库、飞书文档和飞书电子表格同步到本地 Markdown、图片、CSV 与 JSON。

## 环境要求

- Python 3.10 或更高版本
- 飞书企业自建应用

推荐使用虚拟环境：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```

如果只使用工具、不运行测试：

```powershell
python -m pip install -e .
```

## 飞书应用配置

复制配置模板：

```powershell
Copy-Item .env.example .env
```

填写应用凭证：

```dotenv
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
```

工具使用自建应用的 `tenant_access_token`，不需要用户 OAuth 登录。token 缓存在
`.cache/tenant_token.json`，过期前会自动刷新；缓存中不会保存 App Secret。

在飞书开放平台为应用开通与实际资源对应的权限，至少包括：

- 查看、评论和下载云空间中的文件
- 查看电子表格
- 查看知识库
- 导出云文档

仅开通 API 权限还不够。读取用户拥有的文档时，需要在文档的“添加文档应用”中加入该应用；读取知识库时，需要由知识库管理员向应用授权。Drive 导出接口只支持企业自建应用。

## 使用方法

在项目目录直接运行：

```powershell
python main.py pull "https://example.feishu.cn/wiki/wikxxxx?sheet=sheet_id"
python main.py pull "https://example.feishu.cn/docx/doxxxxx"
python main.py pull "https://example.feishu.cn/sheets/shtxxxx"
```

安装为命令后也可以运行：

```powershell
feishu-sync pull "https://example.feishu.cn/wiki/wikxxxx"
```

指定输出根目录：

```powershell
feishu-sync pull "https://example.feishu.cn/docx/doxxxxx" --output-dir D:\feishu-data
```

支持的 URL：

- `/wiki/{node_token}`
- `/docx/{docx_token}`
- `/sheets/{spreadsheet_token}`

表格 URL 带 `?sheet={sheet_id}` 时只导出指定工作表；不带参数时导出所有非空工作表。

## 输出结构

默认输出到项目目录下的 `data/`。目录名称始终使用输入链接中的 token：

```text
data/{input_token}/
├── metadata.json
├── content.md
├── sheet_{sheet_id}.csv
└── assets/
    └── image_001.png
```

- 文档生成 `content.md`。
- DOCX 内嵌图片保存到 `assets/`，Markdown 使用相对路径；纯外链图片保留原链接。
- 表格按工作表生成 UTF-8 BOM 编码的 CSV，中文可直接用 Excel 打开。
- `metadata.json` 记录源链接、输入 token、wiki 解引用后的资源 token/type、标题、同步时间、工作表状态和输出文件。
- 导出 DOCX 只是临时文件，转换完成后自动删除。

## 错误与退出码

- `0`：成功
- `2`：命令参数、URL 或 `.env` 配置错误
- `3`：token 或资源权限错误
- `4`：网络、飞书 API、空表格、导出或转换错误

常见问题：

- **HTTP 403 / 没有文档权限**：确认应用已开通 API 权限，并已被添加到目标文档；知识库还需要管理员授权。
- **空表格**：指定工作表为空时命令失败；导出全部时跳过个别空表，所有工作表都为空时失败。
- **导出超时**：导出任务等待上限为 120 秒，请稍后重试，并检查应用是否拥有“导出云文档”权限。
- **token 失效**：工具会自动刷新并重试一次；仍失败时检查 App ID、App Secret 和应用状态。

错误消息会带上飞书错误码和 request ID（如果响应提供），但不会打印 App Secret 或 access token。

## 开发与测试

```powershell
python -m pytest -q
python -m compileall -q .
python main.py --help
python main.py pull --help
```