openbird 2.4.0 → 3.0.0

package/README.md

@@ -1,15 +1,9 @@
 # OpenBird
 
-飞书（Lark）非官方基础设施服务，运行在本地，通过浏览器 cookie 连接飞书，提供两个核心能力：
+飞书（Lark）非官方基础设施服务，运行在本地，通过浏览器 cookie 连接飞书，提供两个显式运行模式：
 
-1. **Webhook 转发** — 连接飞书 WebSocket，将消息标准化后 POST 到你配置的 webhook 地址
-2. **MCP Server** — 通过 stdio 暴露多个飞书 API 工具，供 AI Agent 调用
-
-```
-飞书 WebSocket ──> OpenBird ──> Webhook URL（你的代码）
-                      │
-                   MCP stdio ──> AI Agent
-```
+1. **Relay 模式** — 连接飞书 WebSocket，将消息标准化后 POST 到你提供的 webhook 地址
+2. **MCP 模式** — 通过 stdio 暴露多个飞书 API 工具，供 AI Agent 调用
 
 ## 快速开始
 
@@ -24,41 +18,50 @@ cp .env.example .env
 # 编辑 .env，粘贴你从浏览器 DevTools 复制的飞书 cookie
 ```
 
-### 纯 MCP 模式
+### MCP 模式
 
 ```bash
-OPENBIRD_COOKIE="your_cookie_here" node bin/openbird.js
+OPENBIRD_COOKIE="your_cookie_here" node bin/openbird.js mcp
 ```
 
 仅启动 MCP Server（stdio），不连接 WebSocket，不转发事件。
 
-### Webhook + MCP 模式
+### Relay 模式
 
 ```bash
 OPENBIRD_COOKIE="your_cookie_here" \
-OPENBIRD_WEBHOOK_URL="http://localhost:3000/webhook" \
-node bin/openbird.js
+node bin/openbird.js relay http://localhost:3000/webhook
 ```
 
-连接飞书 WebSocket 并将所有事件转发到你的 webhook 地址，同时提供 MCP 工具。
+连接飞书 WebSocket 并将所有事件转发到你提供的 webhook 地址。
 
 ### 运行示例
 
 ```bash
-# 在一个进程里同时启动 webhook 接收端和 MCP 客户端
 node examples/basic-usage.mjs
 ```
 
+该示例以 MCP 模式启动 OpenBird，并演示如何通过 stdio 连接 MCP 客户端。
+
 ## 配置
 
 | 环境变量 | 必填 | 说明 |
 |---|---|---|
 | `OPENBIRD_COOKIE` | 是 | 飞书浏览器 cookie 字符串 |
-| `OPENBIRD_WEBHOOK_URL` | 否 | 接收事件的 webhook 地址，不设置则为纯 MCP 模式 |
 | `OPENBIRD_DEBUG` | 否 | 设为 `true` 开启调试日志 |
+| `OPENBIRD_ENRICH` | 否 | Relay 模式下设为 `false` 可关闭事件富化 |
 
 支持 `.env` 文件配置。
 
+### 迁移说明
+
+旧版本通过 `OPENBIRD_WEBHOOK_URL` 是否存在来隐式决定是否同时启动 webhook 转发。现在改为显式命令：
+
+- `node bin/openbird.js mcp`
+- `node bin/openbird.js relay <webhook-url>`
+
+Relay 模式不再自动启动 MCP server。
+
 ## Webhook 事件
 
 OpenBird 将飞书 WebSocket 消息标准化为稳定的事件格式：
@@ -87,6 +90,34 @@ OpenBird 将飞书 WebSocket 消息标准化为稳定的事件格式：
 }
 ```
 
+`im.thread.reply_count_v1` 示例：
+
+```json
+{
+  "type": "im.thread.reply_count_v1",
+  "event_id": "evt_123",
+  "timestamp": 1712023530000,
+  "semantic": {
+    "entity": "thread",
+    "action": "activity_detected",
+    "kind": "state_signal",
+    "consumable": false,
+    "requires_hydration": "fetch_thread_messages",
+    "dedupe_key": "thread:thread_1:reply_count:12",
+    "dedupe_strategy": "drop_exact_match",
+    "routing_hints": ["thread", "activity"]
+  },
+  "data": {
+    "chatId": "chat_1",
+    "threadId": "thread_1",
+    "replyCount": 12,
+    "updateTime": 1712023530000
+  }
+}
+```
+
+当前仅 `im.thread.reply_count_v1` 会携带 `semantic` 字段。其他 webhook 事件仍保持现有结构。
+
 ### 事件类型
 
 | 类型 | 说明 |
@@ -154,6 +185,13 @@ createServer({
 })
 ```
 
+然后用 Relay 模式启动 OpenBird：
+
+```bash
+OPENBIRD_COOKIE="your_cookie_here" \
+node bin/openbird.js relay http://localhost:3000/webhook
+```
+
 ## MCP 工具
 
 通过 [Model Context Protocol](https://modelcontextprotocol.io/) 提供多个工具（stdio 通信）。
@@ -252,7 +290,7 @@ createServer({
 ### 使用 MCP Inspector 测试
 
 ```bash
-npx @modelcontextprotocol/inspector node bin/openbird.js
+npx @modelcontextprotocol/inspector node bin/openbird.js mcp
 ```
 
 ## 项目结构
@@ -261,7 +299,7 @@ npx @modelcontextprotocol/inspector node bin/openbird.js
 openbird/
 ├── bin/openbird.js              # CLI 入口
 ├── src/
-│   ├── index.js                 # 主入口
+│   ├── index.js                 # 模式分发与共享启动逻辑
 │   ├── logger.js                # 日志（全部写 stderr，stdout 留给 MCP）
 │   ├── core/                    # 飞书协议实现
 │   │   ├── api.js               # HTTP API 客户端（34 个方法）
@@ -276,7 +314,7 @@ openbird/
 │   └── mcp/
 │       └── server.js            # MCP Server（多个工具）
 ├── examples/
-│   └── basic-usage.mjs          # 完整示例
+│   └── basic-usage.mjs          # MCP 示例
 └── docs/
     └── plans/                   # 设计文档
 ```
@@ -296,8 +334,11 @@ pnpm test:coverage
 # 修改 proto.proto 后重新生成代码
 pnpm generate:proto
 
-# 启动
-node bin/openbird.js
+# 启动 MCP 模式
+node bin/openbird.js mcp
+
+# 启动 Relay 模式
+node bin/openbird.js relay http://localhost:3000/webhook
 ```
 
 ### 测试

package/dist/bin/openbird.js

@@ -3,4 +3,4 @@ console.log=(...a)=>process.stderr.write(a.join(" ")+"\n");
 console.warn=(...a)=>process.stderr.write(a.join(" ")+"\n");
 console.error=(...a)=>process.stderr.write(a.join(" ")+"\n");
 import{main}from"../index.js";
-main().catch(e=>{process.stderr.write("[openbird] Fatal: "+e.message+"\n");e.stack&&process.stderr.write(e.stack+"\n");process.exit(1)});
+main(process.argv.slice(2)).then(c=>{if(c&&c!==0)process.exit(c)}).catch(e=>{process.stderr.write("[openbird] Fatal: "+e.message+"\n");e.stack&&process.stderr.write(e.stack+"\n");process.exit(1)});