feishu-tools

飞书/Lark 工具库 - 让任何 Agent 都能便捷调用飞书能力

---

设计理念

任何 Agent 阅读代码后，无需额外指导，即可正确调用。

• 完整的类型提示，IDE/Agent 可自动补全
• 每个函数都有详细的 docstring
• 清晰的错误信息，包含解决方案提示
• 统一的 API 设计模式

---

功能特性

模块	功能	状态
认证 (Auth)	OAuth 2.0 授权、Token 持久化、自动刷新	✅
文档 (Doc)	文档获取、创建、更新、删除、移动、复制、图片上传、协作者管理	✅
云空间 (Drive)	文件列表、文件夹创建、全局搜索	✅
多维表格 (Bitable)	应用/表/记录/字段管理	✅
即时消息 (IM)	消息获取、搜索、发送、资源下载	✅
日历 (Calendar)	日程管理、参会人管理、忙闲查询	✅
任务 (Task)	任务管理、清单管理	✅
知识库 (Wiki)	知识空间列表、详情、创建	✅

---

安装

从源码安装

git clone https://github.com/ZZFFLL/openclaw-lark-python.git
cd openclaw-lark-python
pip install -e ".[dev]"

依赖要求

• Python >= 3.10
• lark-oapi >= 1.0.0
• httpx >= 0.25.0
• pydantic >= 2.0.0

---

快速开始

1. 初始化客户端

from feishu_tools import FeishuClient

# 应用身份（适合后台任务）
client = FeishuClient(
    app_id="cli_xxx",
    app_secret="xxx",
)

# 用户身份（需要先通过 OAuth 获取）
client = FeishuClient.with_user_token(
    user_access_token="u-xxx",
    app_id="cli_xxx",
    app_secret="xxx",
)

# 国际版 Lark
client = FeishuClient(
    app_id="cli_xxx",
    app_secret="xxx",
    brand="lark",
)

2. 认证授权

from feishu_tools.auth import AuthService

auth = AuthService(
    app_id="cli_xxx",
    app_secret="xxx",
    storage_path="./tokens.json",
)

# 生成授权链接
url = auth.get_authorize_url(
    redirect_uri="https://example.com/callback",
    scope="drive:drive docx:document offline_access",
)

# 用户授权后，用授权码换取 token
result = auth.authorize_user(code="authorization_code")

# 创建客户端
client = FeishuClient.with_user_token(
    user_access_token=result.token.access_token,
    app_id="cli_xxx",
    app_secret="xxx",
)

3. 文档操作

# 获取文档内容
doc = client.doc.fetch(doc_id="doxcnxxx")
print(doc["content"])

# 创建文档
result = client.doc.create(
    title="项目文档",
    markdown="# 概述\n\n这是文档内容...",
)

# 追加内容
client.doc.update(
    doc_id="doxcnxxx",
    mode="append",
    markdown="## 新章节\n\n追加的内容...",
)

# 移动文档
client.doc.move(doc_id="doxcnxxx", folder_token="fldcnxxx")

# 上传图片
result = client.doc.upload_image(
    doc_id="doxcnxxx",
    file_path="/path/to/image.png",
)

# 在指定位置插入图片
client.doc.service.insert_image_at(
    doc_id="doxcnxxx",
    file_path="/path/to/image.png",
    position="after:## 架构图",
)

4. 云空间操作

# 列出文件
files = client.drive.list_files(folder_token="fldcnxxx")
for f in files["files"]:
    print(f"[{f['type']}] {f['name']}")

# 全局搜索
result = client.drive.service.search_docs(query="项目计划")
for f in result["files"]:
    print(f"{f['title']}: {f['url']}")

# 创建文件夹
result = client.drive.create_folder(name="新文件夹")

5. 协作者管理

# 查看协作者
result = client.doc.service.list_collaborators(doc_id="doxcnxxx")

# 添加协作者
client.doc.service.add_collaborator(
    doc_id="doxcnxxx",
    member_id="ou_xxx",
    perm="edit",
)

---

命令行工具

# 设置环境变量
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

# 登录授权
python -m feishu_tools.cli auth login

# 获取文档内容
python -m feishu_tools.cli doc fetch doxcnxxx -o output.md

# 创建文档
python -m feishu_tools.cli doc create --title "报告" --file report.md

# 列出文件
python -m feishu_tools.cli drive list

# 搜索文档
python -m feishu_tools.cli drive search "项目计划"

详细使用方法请参考 CLI 文档。

---

项目结构

openclaw-lark-python/
├── src/
│   └── feishu_tools/       # Python 包源码
│       ├── __init__.py     # 公开 API 导出
│       ├── client.py       # 同步客户端
│       ├── async_client.py # 异步客户端
│       ├── cli.py          # 命令行工具
│       ├── auth/           # 认证模块
│       ├── doc/            # 文档模块
│       ├── drive/          # 云空间模块
│       ├── im/             # 即时消息模块
│       ├── bitable/        # 多维表格模块
│       ├── calendar/       # 日历模块
│       ├── task/           # 任务模块
│       ├── wiki/           # 知识库模块
│       └── common/         # 公共模块
├── tests/                  # 测试文件
├── skills/                 # Agent 技能文档
├── docs/                   # 项目文档
├── scripts/                # 工具脚本
└── pyproject.toml          # 项目配置

---

Agent 技能文档

skills/ 目录包含 Agent 使用指南，描述如何使用飞书功能：

技能	用途
feishu-agent-guide	Agent 使用指南（必读）
feishu-auth	认证授权
feishu-create-doc	创建文档
feishu-fetch-doc	获取文档
feishu-update-doc	更新文档
feishu-doc-organize	文档整理（移动/删除/复制）
feishu-docx-powerwrite	高质量写入（含图片）
feishu-document-enhanced	协作者管理、媒体上传
feishu-drive	云空间操作
feishu-folder-summary	文件夹批量读取

---

开发指南

运行测试

pytest tests/
pytest tests/test_auth_service.py -v

类型检查

mypy src/feishu_tools

代码检查

ruff check src/
ruff check --fix src/

---

错误处理

from feishu_tools.common.errors import FeishuAPIError

try:
    client.doc.fetch(doc_id="xxx")
except FeishuAPIError as e:
    print(f"错误: {e.message}")
    print(f"错误码: {e.code}")

---

许可证

MIT License - 详见 LICENSE

---

相关链接

• 飞书开放平台
• Lark 开发者文档
• lark-oapi SDK