openbird 3.2.4 → 3.2.6

package/README.md

@@ -1,27 +1,18 @@
 # OpenBird
 
-飞书（Lark）非官方基础设施服务，运行在本地，通过浏览器 cookie 连接飞书，提供两个显式运行模式：
+**为 AI Agent 准备的飞书（Lark）工具箱。** 本地运行，通过浏览器 cookie 以你本人的身份接入飞书，把飞书能力打包成可直接调用的工具，提供两个显式运行模式：
 
-1. **Relay 模式** — 连接飞书 WebSocket，将消息标准化后 POST 到你提供的 webhook 地址
-2. **MCP 模式** — 通过 stdio 暴露多个飞书 API 工具，供 AI Agent 调用
+1. **MCP 模式** — 通过 stdio 暴露 77 个飞书工具，供 AI Agent（Claude Desktop、Cursor 等）调用
+2. **Relay 模式** — 连接飞书 WebSocket，将消息标准化后 POST 到你提供的 webhook 地址
 
 ## 快速开始
 
-```bash
-# 克隆并安装
-git clone https://github.com/ztxtxwd/openbird.git
-cd openbird
-pnpm install
-
-# 配置
-cp .env.example .env
-# 编辑 .env，粘贴你从浏览器 DevTools 复制的飞书 cookie
-```
+无需 clone 源码，直接通过 `npx` 运行即可。唯一的前置条件是准备好飞书 cookie：打开飞书网页版（feishu.cn），浏览器 DevTools 从任意 `*.feishu.cn` 请求的请求头中复制完整的 `Cookie` 值。
 
 ### MCP 模式
 
 ```bash
-OPENBIRD_COOKIE="your_cookie_here" node bin/openbird.js mcp
+OPENBIRD_COOKIE="your_cookie_here" npx openbird mcp
 ```
 
 仅启动 MCP Server（stdio），不连接 WebSocket，不转发事件。
@@ -30,18 +21,28 @@ OPENBIRD_COOKIE="your_cookie_here" node bin/openbird.js mcp
 
 ```bash
 OPENBIRD_COOKIE="your_cookie_here" \
-node bin/openbird.js relay http://localhost:3000/webhook
+  npx openbird relay http://localhost:3000/webhook
 ```
 
 连接飞书 WebSocket 并将所有事件转发到你提供的 webhook 地址。
 
-### 运行示例
+### 在 MCP 客户端中配置
 
-```bash
-node examples/basic-usage.mjs
-```
+以 Claude Desktop / Cursor 为例，在 MCP server 配置里填：
 
-该示例以 MCP 模式启动 OpenBird，并演示如何通过 stdio 连接 MCP 客户端。
+```json
+{
+  "mcpServers": {
+    "openbird": {
+      "command": "npx",
+      "args": ["-y", "openbird", "mcp"],
+      "env": {
+        "OPENBIRD_COOKIE": "your_cookie_here"
+      }
+    }
+  }
+}
+```
 
 ## 配置
 
@@ -57,8 +58,8 @@ node examples/basic-usage.mjs
 
 旧版本通过 `OPENBIRD_WEBHOOK_URL` 是否存在来隐式决定是否同时启动 webhook 转发。现在改为显式命令：
 
-- `node bin/openbird.js mcp`
-- `node bin/openbird.js relay <webhook-url>`
+- `npx openbird mcp`
+- `npx openbird relay <webhook-url>`
 
 Relay 模式不再自动启动 MCP server。
 
@@ -189,12 +190,12 @@ createServer({
 
 ```bash
 OPENBIRD_COOKIE="your_cookie_here" \
-node bin/openbird.js relay http://localhost:3000/webhook
+  npx openbird relay http://localhost:3000/webhook
 ```
 
 ## MCP 工具
 
-通过 [Model Context Protocol](https://modelcontextprotocol.io/) 提供多个工具（stdio 通信）。
+通过 [Model Context Protocol](https://modelcontextprotocol.io/) 提供 **77 个工具**（stdio 通信），覆盖消息、会话、话题、用户、通讯录、机器人、日历、加急、百科、云文档等 14 个类别。
 
 ### 消息
 
@@ -207,6 +208,17 @@ node bin/openbird.js relay http://localhost:3000/webhook
 | `get_message_link_permission` | 查询消息链接预览权限 |
 | `add_reaction` | 添加表情回应 |
 | `remove_reaction` | 移除表情回应 |
+| `pin_message` | 在会话中置顶消息 |
+| `list_chat_pins` | 列出会话中置顶的消息 |
+| `unpin_message` | 取消置顶消息 |
+
+### 定时消息
+
+| 工具 | 说明 |
+|---|---|
+| `put_schedule_message` | 创建定时消息（未来时间发送） |
+| `patch_schedule_message` | 更新 / 暂停 / 删除 / 立即发送定时消息 |
+| `pull_schedule_message_by_ids` | 按 ID 批量查询定时消息 |
 
 ### 会话
 
@@ -215,6 +227,8 @@ node bin/openbird.js relay http://localhost:3000/webhook
 | `get_chat_history` | 获取聊天历史消息 |
 | `get_chat_meta` | 获取会话元信息（最后消息位置、已读位置等） |
 | `create_chat` | 创建一对一会话 |
+| `create_group` | 创建群聊 |
+| `patch_group_chat` | 更新群聊信息（名称、描述、图标） |
 | `search` | 搜索用户和群组 |
 | `search_in_chat` | 在指定会话中搜索消息 |
 | `mark_chat_read` | 标记会话已读 |
@@ -223,22 +237,37 @@ node bin/openbird.js relay http://localhost:3000/webhook
 | `mark_session` | 标记会话为重要 |
 | `unmark_session` | 取消标记会话 |
 
+### 话题
+
+| 工具 | 说明 |
+|---|---|
+| `create_thread` | 从消息创建话题 |
+| `get_thread_messages` | 获取话题内的消息列表 |
+
 ### 用户
 
 | 工具 | 说明 |
 |---|---|
-| `get_user_info` | 根据用户 ID 获取信息 |
+| `get_user_info` | 根据用户 ID 获取信息（同时支持用户和机器人） |
+| `get_user_by_id` | 获取用户资料（包含 alias 和备注） |
 | `get_user_profile_card` | 获取用户名片（头像、签名等） |
 | `set_user_signature` | 设置当前用户签名 |
 | `get_user_relation` | 查询与目标用户的关系 |
 | `get_user_presence` | 获取用户在线状态 |
 
-### 机器人
+### 通讯录
+
+| 工具 | 说明 |
+|---|---|
+| `save_contact_alias` | 保存联系人备注名和备忘 |
+| `sync_contact_info` | 同步联系人信息 |
+
+### Webhook 机器人
 
 | 工具 | 说明 |
 |---|---|
 | `create_webhook_bot` | 在指定会话中创建 webhook 机器人 |
-| `get_webhook_bot_info` | 获取 webhook 机器人的 webhook 地址和配置信息 |
+| `get_webhook_bot_info` | 获取 webhook 机器人的 webhook 地址和签名配置 |
 | `send_webhook_bot_text` | 通过 webhook URL 发送文本消息 |
 | `send_webhook_bot_post` | 通过 webhook URL 发送富文本 post 消息 |
 | `send_webhook_bot_image` | 通过 webhook URL 使用已有 `image_key` 发送图片消息 |
@@ -246,25 +275,33 @@ node bin/openbird.js relay http://localhost:3000/webhook
 | `send_webhook_bot_card` | 通过 webhook URL 发送交互式卡片消息 |
 | `send_webhook_bot_message` | 通过 webhook URL 发送原始 webhook payload |
 
-### 通讯录
-
-| 工具 | 说明 |
-|---|---|
-| `save_contact_alias` | 保存联系人备注名和备忘 |
-| `sync_contact_info` | 同步联系人信息 |
-
 ### 日历
 
 | 工具 | 说明 |
 |---|---|
-| `get_calendar_events` | 获取日历事件列表 |
+| `get_calendar_events` | 获取用户日历事件列表 |
+| `web_list_calendar_events` | 按时间范围列出日历事件 |
+| `mget_events_with_ids` | 按 event key 批量查询事件详情 |
+| `create_calendar_event` | 创建日历事件（标题、时间、地点、提醒、与会者） |
+| `update_calendar_event` | 更新已有日历事件 |
+| `delete_calendar_event` | 删除日历事件 |
 | `calendar_rsvp` | 回复日历邀请（接受/拒绝/待定） |
+| `reply_calendar_event_invitation` | 带 RSVP 评论回复邀请 |
+| `transfer_calendar_event` | 转让事件所有权给其他用户 |
+| `web_share_calendar_event` | 把日历事件分享到一个或多个会话 |
+| `upgrade_to_meeting` | 把日程升级为视频会议（创建会议群） |
+| `create_meeting_minute` | 为日程创建会议纪要文档（返回飞书文档 URL） |
+| `get_place_tips` | 事件地点自动补全 |
 
-### 话题
+### 会议室与组织
 
 | 工具 | 说明 |
 |---|---|
-| `create_thread` | 从消息创建话题 |
+| `search_guests` | 搜索可加为与会者的用户和群组 |
+| `search_meeting_rooms` | 在指定时间窗口内搜索可用会议室 |
+| `pull_buildings` | 列出包含会议室的楼宇 |
+| `pull_meeting_rooms_in_building` | 按楼宇列出会议室 |
+| `pull_tenants_by_ids` | 按租户 ID 批量查询组织信息 |
 
 ### 加急
 
@@ -273,6 +310,26 @@ node bin/openbird.js relay http://localhost:3000/webhook
 | `send_urgent` | 发送加急通知 |
 | `get_urgent_ack_status` | 查询加急确认状态 |
 
+### 百科
+
+| 工具 | 说明 |
+|---|---|
+| `get_baike_card` | 获取飞书词典词条卡片（定义、全称、贡献者、详情链接） |
+| `get_baike_recommend_docs` | 获取词条的推荐文档 |
+
+### 云文档
+
+| 工具 | 说明 |
+|---|---|
+| `docx_open_document` | 打开飞书文档进行编辑，返回 block tree 并缓存供后续操作使用 |
+| `get_docx_block_tree` | 获取文档 block tree（支持 wiki 或 docx） |
+| `docx_insert_block` | 插入新 block |
+| `docx_edit_text` | 编辑 block 的文本内容 |
+| `docx_change_block_type` | 修改 block 类型（如文本→标题、列表项→待办） |
+| `docx_set_block_properties` | 设置 block 属性（done / folded / align / language / emoji / 缩进 等） |
+| `docx_delete_blocks` | 删除一个或多个 block |
+| `docx_move_block` | 移动 block 到新的父节点或位置 |
+
 ### 配置
 
 | 工具 | 说明 |
@@ -284,13 +341,14 @@ node bin/openbird.js relay http://localhost:3000/webhook
 
 | 工具 | 说明 |
 |---|---|
-| `download_image` | 下载图片 |
+| `download_image` | 下载图片（返回 base64 编码数据） |
 | `download_file` | 下载消息附件到本地临时文件并返回路径 |
 
 ### 使用 MCP Inspector 测试
 
 ```bash
-npx @modelcontextprotocol/inspector node bin/openbird.js mcp
+OPENBIRD_COOKIE="your_cookie_here" \
+  npx @modelcontextprotocol/inspector npx -y openbird mcp
 ```
 
 ## 项目结构
@@ -312,7 +370,7 @@ openbird/
 │   │   ├── normalizer.js        # WebSocket 消息 -> OpenBird 事件
 │   │   └── dispatcher.js        # HTTP POST 转发（含重试）
 │   └── mcp/
-│       └── server.js            # MCP Server（多个工具）
+│       └── server.js            # MCP Server（77 个工具）
 ├── examples/
 │   └── basic-usage.mjs          # MCP 示例
 └── docs/