Metadata-Version: 2.4
Name: open-feishu
Version: 0.4.1
Summary: Python SDK for Feishu / Lark
Author-email: Zhiyuan Chen <this@zyc.ai>
Maintainer-email: Zhiyuan Chen <this@zyc.ai>
License-Expression: AGPL-3.0-or-later
Project-URL: documentation, https://feishu.danling.org
Project-URL: homepage, https://feishu.danling.org
Project-URL: repository, https://github.com/ZhiyuanChen/open-feishu
Keywords: async,bot,feishu,lark,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chanfig>=0.0.102
Requires-Dist: httpx
Requires-Dist: pycryptodome
Requires-Dist: starlette
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == "anthropic"
Provides-Extra: attachments
Requires-Dist: openpyxl; extra == "attachments"
Requires-Dist: pillow; extra == "attachments"
Requires-Dist: pymupdf; extra == "attachments"
Requires-Dist: python-docx; extra == "attachments"
Requires-Dist: python-pptx; extra == "attachments"
Provides-Extra: gateway
Requires-Dist: uvicorn; extra == "gateway"
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Requires-Dist: pymupdf; extra == "mcp"
Provides-Extra: openai
Requires-Dist: openai; extra == "openai"
Provides-Extra: ws
Requires-Dist: websockets; extra == "ws"
Dynamic: license-file

# OpenFeishu

OpenFeishu 是一个飞书开放平台的 Python SDK，提供了飞书开放平台的接口封装，方便开发者使用飞书开放平台的接口。

## 使用

### 快速开始

`FeishuClient` 是一个异步客户端，统一管理应用凭证、令牌的自动获取与缓存，以及带自动重试的 HTTP 传输。推荐通过 `async with` 使用，以便自动释放底层连接。消息接口以接收者为第一个参数（其 ID 类型会自动推断），消息内容为第二个参数；`client.im.send` 还会根据内容的形态自动推断消息类型（`msg_type`）。

```python
import asyncio

from feishu import FeishuClient


async def main():
    async with FeishuClient("cli_xxx", "app_secret") as client:
        await client.im.send("oc_xxx", "hello, world!")


asyncio.run(main())
```

应用凭证也可以通过环境变量 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 提供，此时可省略构造参数：`async with FeishuClient() as client: ...`。

### 命名空间

各业务能力按资源划分到不同命名空间下，每个命名空间提供「裸动词」式的 CRUD 方法（如 `create` / `get` / `update` / `delete` / `list`）。常用入口：

| 命名空间 | 说明 |
| --- | --- |
| `client.im` | 即时消息：发送、回复、编辑、撤回、转发消息 |
| `client.contact.users` / `client.contact.departments` | 通讯录：用户与部门 |
| `client.bitable.tables` | 多维表格：数据表、字段与记录 |
| `client.calendar.events` | 日历：日程与参与人 |
| `client.approval.instances` | 审批：审批实例与任务 |
| `client.drive.files` | 云空间：文件的上传、下载、复制与删除 |

此外还有 `client.docx`（新版文档）、`client.sheets`（电子表格）、`client.wiki`（知识库）、`client.board.whiteboards`（画板）、`client.vc`（视频会议）、`client.task`（任务）、`client.oauth`（用户身份 OAuth）、`client.cards`（卡片构建器）等命名空间。

```python
async with FeishuClient("cli_xxx", "app_secret") as client:
    user = await client.contact.users.get("ou_xxx", user_id_type="open_id")
    records = await client.bitable.records.list("app_token", "tbl_xxx")
```

### 接收事件

要接收飞书推送的事件（如「接收消息」），先用 `EventDispatcher` 按事件类型注册异步处理函数，Webhook 接收器与长连接两种接入方式共用同一套处理函数。

```python
from feishu.events import EventDispatcher

dispatcher = EventDispatcher()


@dispatcher.on("im.message.receive_v1")
async def on_message(event):
    print(event.event_id)
```

**方式一：长连接（WebSocket）。** 本地开发、内网部署或轻量机器人可用 `feishu.ws.WsClient` 主动与飞书建立一条持久 WebSocket 连接（对标 Slack 的 Socket Mode），事件经该连接推送：

```python
import asyncio

from feishu.ws import WsClient

ws = WsClient("cli_xxx", "app_secret", dispatcher)
asyncio.run(ws.start())
```

长连接依赖可选的 `websockets` 包，可通过 `pip install open-feishu[ws]` 安装。

**方式二：HTTP Webhook。** 公网 Webhook 场景可用 `create_event_app` 生成一个可独立运行的 Starlette 应用，默认带签名新鲜度（防重放）与去重保护，以任意 ASGI 服务器（如 `uvicorn`）运行即可：

```python
from feishu.events import create_event_app

app = create_event_app(dispatcher, encrypt_key="ek_secret")
# uvicorn module:app
```

### Agent

`feishu.agent.Agent` 是面向机器人产品的开箱即用入口：它把飞书客户端、LLM 后端、工具注册表、会话存储、审批卡片、OAuth 授权恢复、附件处理和事件接入装配在一起。最小可部署模板在仓库的 `examples/agent` 目录，完整说明见 https://feishu.danling.org/guides/agent/。

```bash
pip install "open-feishu[openai,ws,gateway]"
```

```python
from feishu.agent import Agent, ToolRegistry

registry = ToolRegistry()


@registry.register(
    input_schema={"type": "object", "properties": {}, "additionalProperties": False},
    description="返回当前服务状态。",
)
def service_status():
    return "ok"


config = {
    "feishu": {"app_id": "cli_xxx", "app_secret": "app_secret"},
    "model": {
        "model": "gpt-4o-mini",
        "api_key": "sk_xxx",
        "base_url": "https://api.openai.com/v1",
    },
    "storage": {"path": ".agent/agent.db"},
    "toolkits": [],
    "system": "你是一个简洁的飞书助手。",
}

Agent(config, registry=registry).run(backend="ws")
```

`backend="ws"` 通过飞书长连接收事件，适合本地、内网和容器常驻部署；`backend="http"` 暴露 `/feishu/event`、`/health` 和 OAuth 回调路由，适合公网 Webhook、用户授权工具和统一健康检查。`Agent(config)` 接收已加载的 mapping；YAML、TOML、`.env` 或密钥服务由应用层读取后组装进配置。

## 安装

从 PyPI 安装最新的稳定版本：

```shell
pip install open-feishu
```

如果需要使用 `feishu-mcp` 命令，请安装 MCP 可选依赖：

```shell
pip install "open-feishu[mcp]"
```

从源代码安装最新版本：

```shell
pip install git+https://github.com/ZhiyuanChen/open-feishu.git
```

## 许可证

`SPDX-License-Identifier: AGPL-3.0-or-later`
