openbird 1.0.0

package/.env.example

@@ -0,0 +1,2 @@
+OPENBIRD_COOKIE=""
+OPENBIRD_WEBHOOK_URL=""

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

package/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ztxtxwd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# OpenBird
+
+飞书（Lark）非官方基础设施服务，运行在本地，通过浏览器 cookie 连接飞书，提供两个核心能力：
+
+1. **Webhook 转发** — 连接飞书 WebSocket，将消息标准化后 POST 到你配置的 webhook 地址
+2. **MCP Server** — 通过 stdio 暴露 14 个飞书 API 工具，供 AI Agent 调用
+
+```
+飞书 WebSocket ──> OpenBird ──> Webhook URL（你的代码）
+                      │
+                   MCP stdio ──> AI Agent
+```
+
+## 快速开始
+
+```bash
+# 克隆并安装
+git clone https://github.com/nickthecook/openbird.git
+cd openbird
+pnpm install
+
+# 配置
+cp .env.example .env
+# 编辑 .env，粘贴你从浏览器 DevTools 复制的飞书 cookie
+```
+
+### 纯 MCP 模式
+
+```bash
+OPENBIRD_COOKIE="your_cookie_here" node bin/openbird.js
+```
+
+仅启动 MCP Server（stdio），不连接 WebSocket，不转发事件。
+
+### Webhook + MCP 模式
+
+```bash
+OPENBIRD_COOKIE="your_cookie_here" \
+OPENBIRD_WEBHOOK_URL="http://localhost:3000/webhook" \
+node bin/openbird.js
+```
+
+连接飞书 WebSocket 并将所有事件转发到你的 webhook 地址，同时提供 MCP 工具。
+
+### 运行示例
+
+```bash
+# 在一个进程里同时启动 webhook 接收端和 MCP 客户端
+node examples/basic-usage.mjs
+```
+
+## 配置
+
+| 环境变量 | 必填 | 说明 |
+|---|---|---|
+| `OPENBIRD_COOKIE` | 是 | 飞书浏览器 cookie 字符串 |
+| `OPENBIRD_WEBHOOK_URL` | 否 | 接收事件的 webhook 地址，不设置则为纯 MCP 模式 |
+| `OPENBIRD_DEBUG` | 否 | 设为 `true` 开启调试日志 |
+
+支持 `.env` 文件配置。
+
+## Webhook 事件
+
+OpenBird 将飞书 WebSocket 消息标准化为稳定的事件格式：
+
+```json
+{
+  "type": "im.message.receive_v1",
+  "event_id": "evt_7604769001905884091",
+  "timestamp": 1739347200000,
+  "data": {
+    "id": "7604769001905884091",
+    "conversation": {
+      "id": "7599271773103737795",
+      "type": "group"
+    },
+    "sender": {
+      "id": "7128839302827827201",
+      "type": "user"
+    },
+    "content": {
+      "type": "text",
+      "text": "hello"
+    },
+    "thread_id": null
+  }
+}
+```
+
+### 事件类型
+
+| 类型 | 说明 |
+|---|---|
+| `im.message.receive_v1` | 聊天消息（文本、富文本、图片、卡片等） |
+| `system.event.unknown` | 未识别的推送事件 |
+
+### 交付语义
+
+- 通过 HTTP POST 发送 JSON body
+- `event_id` 全局唯一，可用于幂等判断
+- 非 2xx 响应会指数退避重试，最多 5 次
+
+### 接收事件
+
+使用 [openbird-webhook-node](./webhooks/node/) 接收事件，无需手写 HTTP 服务：
+
+```js
+import { createServer } from 'openbird-webhook-node'
+
+createServer({
+  port: 3000,
+  onMessage(event) {
+    console.log(event.data.sender.id, event.data.content.text)
+  },
+})
+```
+
+## MCP 工具
+
+通过 [Model Context Protocol](https://modelcontextprotocol.io/) 提供 14 个工具（stdio 通信）。
+
+### 消息
+
+| 工具 | 说明 |
+|---|---|
+| `send_message` | 发送消息（支持 Markdown） |
+| `send_reply` | 回复指定消息（引用回复） |
+| `add_reaction` | 添加表情回应 |
+| `remove_reaction` | 移除表情回应 |
+
+### 会话
+
+| 工具 | 说明 |
+|---|---|
+| `get_chat_history` | 获取聊天历史消息 |
+| `get_chat_meta` | 获取会话元信息（最后消息位置、已读位置等） |
+| `create_chat` | 创建一对一会话 |
+| `search` | 搜索用户和群组 |
+
+### 用户
+
+| 工具 | 说明 |
+|---|---|
+| `get_user_info` | 根据用户 ID 获取信息 |
+| `get_user_profile_card` | 获取用户名片（头像、签名等） |
+| `set_user_signature` | 设置当前用户签名 |
+
+### 日历
+
+| 工具 | 说明 |
+|---|---|
+| `get_calendar_events` | 获取日历事件列表 |
+| `calendar_rsvp` | 回复日历邀请（接受/拒绝/待定） |
+
+### 媒体
+
+| 工具 | 说明 |
+|---|---|
+| `download_image` | 下载图片（支持解密） |
+
+### 使用 MCP Inspector 测试
+
+```bash
+npx @modelcontextprotocol/inspector node bin/openbird.js
+```
+
+## 项目结构
+
+```
+openbird/
+├── bin/openbird.js              # CLI 入口
+├── src/
+│   ├── index.js                 # 主入口
+│   ├── logger.js                # 日志（全部写 stderr，stdout 留给 MCP）
+│   ├── core/                    # 飞书协议实现
+│   │   ├── api.js               # HTTP API 客户端
+│   │   ├── auth.js              # Cookie 认证
+│   │   ├── websocket.js         # WebSocket 客户端
+│   │   ├── builders/            # Protobuf 请求/响应构建
+│   │   ├── proto/               # .proto 定义及生成代码
+│   │   └── utils/               # Cookie、加密、varint 工具
+│   ├── webhook/
+│   │   ├── normalizer.js        # WebSocket 消息 -> OpenBird 事件
+│   │   └── dispatcher.js        # HTTP POST 转发（含重试）
+│   └── mcp/
+│       └── server.js            # MCP Server（14 个工具）
+├── webhooks/
+│   └── node/                    # openbird-webhook-node（事件接收库）
+├── examples/
+│   └── basic-usage.mjs          # 完整示例
+└── docs/
+    └── plans/                   # 设计文档
+```
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 修改 proto.proto 后重新生成代码
+pnpm generate:proto
+
+# 启动
+node bin/openbird.js
+```
+
+## 工作原理
+
+OpenBird 逆向了飞书网页版的 WebSocket 协议和 HTTP API，使用你的浏览器 cookie 以你的用户身份认证——和浏览器使用的是同一个会话。
+
+**获取 cookie**：打开飞书网页版（feishu.cn），打开浏览器开发者工具，从任意 `*.feishu.cn` 请求中复制完整的 `Cookie` 请求头的值。
+
+**注意**：这是非官方工具。飞书可能随时修改协议，使用风险自负。
+
+## License
+
+MIT

package/bin/openbird.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+/**
+ * OpenBird CLI entry point
+ *
+ * Safety net: redirect console.log/warn/error to stderr
+ * so third-party libs don't pollute stdout (used by MCP JSON-RPC).
+ */
+
+const originalLog = console.log;
+const originalWarn = console.warn;
+const originalError = console.error;
+
+console.log = (...args) => process.stderr.write(args.join(' ') + '\n');
+console.warn = (...args) => process.stderr.write(args.join(' ') + '\n');
+console.error = (...args) => process.stderr.write(args.join(' ') + '\n');
+
+import { main } from '../src/index.js';
+
+main().catch((err) => {
+  process.stderr.write(`[openbird] Fatal: ${err.message}\n`);
+  if (err.stack) {
+    process.stderr.write(err.stack + '\n');
+  }
+  process.exit(1);
+});

package/docs/plans/2026-02-12-openbird-v1-design.md

@@ -0,0 +1,281 @@
+# OpenBird V1 Design
+
+## 1. 定位
+
+OpenBird 是一个独立运行的飞书非官方基础设施服务，通过 `npx openbird` 启动。
+
+它做两件事：
+
+1. **WebSocket -> Webhook**：连接飞书 WebSocket，将消息标准化后转发到用户配置的 webhook 地址
+2. **MCP Server**：暴露飞书 API 操作为 MCP tool，供 Agent 调用
+
+核心代码提取自 feishu-bot 项目的 `src/lib/`。
+
+## 2. 架构
+
+```
+用户浏览器 cookie
+        |
+        v
++-------------------------------------+
+|            OpenBird                  |
+|                                     |
+|  +-------------+  +--------------+  |
+|  |  WebSocket   |  |  MCP Server  |  |
+|  |  Listener    |  |  (stdio)     |  |
+|  +------+------+  +--------------+  |
+|         |                           |
+|  +------v------+                    |
+|  |   Event     |                    |
+|  | Normalizer  |                    |
+|  +------+------+                    |
+|         |                           |
+|  +------v------+                    |
+|  |  Webhook    |                    |
+|  |  Dispatcher |                    |
+|  +-------------+                    |
++-------------------------------------+
+```
+
+## 3. 配置与启动
+
+**启动**：
+
+```bash
+npx openbird
+```
+
+启动后 WebSocket 监听 + Webhook 转发 + MCP Server 同时工作。
+
+**配置**（环境变量或 `.env` 文件）：
+
+```
+OPENBIRD_COOKIE="session=xxx; swp_csrf_token=xxx; ..."
+OPENBIRD_WEBHOOK_URL="https://example.com/webhook"
+```
+
+## 4. Webhook 事件格式
+
+### 4.1 事件结构
+
+```json
+{
+  "version": "1.0",
+  "event_id": "evt_7604769001905884091",
+  "event_type": "im.message.created",
+  "timestamp": 1739347200,
+  "platform": "lark",
+  "data": {
+    "id": "7604769001905884091",
+    "conversation": {
+      "id": "7599271773103737795",
+      "type": "group"
+    },
+    "sender": {
+      "id": "7128839302827827201",
+      "type": "user"
+    },
+    "content": {
+      "type": "text",
+      "text": "hello"
+    },
+    "thread_id": null,
+    "created_at": 1739347200
+  },
+  "extensions": {
+    "lark": {
+      "chat_type": 2,
+      "from_type": 1,
+      "message_type": 4
+    }
+  },
+  "raw": {}
+}
+```
+
+### 4.2 event_type 规范
+
+三段式：`<domain>.<resource>.<action>`
+
+**domain 列表**（V1 重点支持 im 和 system）：
+
+| domain | 含义 |
+|---|---|
+| `im` | 即时通讯 |
+| `contact` | 通讯录 |
+| `calendar` | 日历 |
+| `approval` | 审批 |
+| `drive` | 云文档 |
+| `bot` | 机器人 |
+| `system` | 系统级 |
+
+**action 枚举**（固定集合，禁止自造）：
+
+- `created`
+- `updated`
+- `deleted`
+- `added`
+- `removed`
+- `unknown`（仅 system 使用）
+
+**V1 事件类型**：
+
+| event_type | 说明 |
+|---|---|
+| `im.message.created` | 新消息 |
+| `im.message.updated` | 消息编辑 |
+| `im.message.deleted` | 消息撤回 |
+| `im.reaction.added` | 添加表情回应 |
+| `im.reaction.removed` | 移除表情回应 |
+| `im.member.added` | 成员加入会话 |
+| `im.member.removed` | 成员离开会话 |
+| `im.conversation.created` | 会话创建 |
+| `im.conversation.updated` | 会话信息变更 |
+| `contact.user.updated` | 用户状态/信息变更 |
+| `calendar.event.created` | 日历事件 |
+| `system.event.unknown` | 未识别的推送事件 |
+
+### 4.3 data 字段规范
+
+- `id` 永远叫 `id`，不暴露平台 ID 命名
+- 所有嵌套对象都有 `id`
+- 类型字段用枚举，不用自由文本
+- `extensions` 放飞书特有字段，永远可选
+- `raw` 保留原始结构，不保证稳定
+
+### 4.4 Normalizer 映射规则
+
+```
+WebSocket decoded              ->  OpenBird event
+---------------------------------------------------
+command === 6                  ->  im.message.created
+command !== 6 (已知类型)        ->  对应的 event_type
+command !== 6 (未知类型)        ->  system.event.unknown
+
+messageId                      ->  event_id ("evt_" + messageId)
+                               ->  data.id
+chatId                         ->  data.conversation.id
+chatType (1/2/3)               ->  data.conversation.type (p2p/group/...)
+fromId                         ->  data.sender.id
+fromType (1/2)                 ->  data.sender.type (user/bot)
+type (消息类型 2/4/...)         ->  data.content.type (text/rich/image/...)
+content                        ->  data.content.text
+threadId                       ->  data.thread_id
+原始 decoded 对象               ->  raw
+```
+
+### 4.5 Webhook 交付语义
+
+- `event_id` 全局唯一
+- 允许重复投递，用户需自行幂等
+- 非 2xx 响应指数退避重试，最多 5 次
+
+## 5. MCP Server
+
+通过 stdio 通信（标准 MCP 协议）。所有 tool 共享启动时传入的 cookie 认证。
+
+### 5.1 消息操作
+
+| tool 名 | 对应方法 | 描述 |
+|---|---|---|
+| `send_message` | `sendMessage` | 发送消息（支持 Markdown） |
+| `send_reply` | `sendReply` | 回复指定消息（引用回复） |
+| `add_reaction` | `addEmojiReaction` | 给消息添加表情回应 |
+| `remove_reaction` | `removeEmojiReaction` | 移除表情回应 |
+
+### 5.2 会话操作
+
+| tool 名 | 对应方法 | 描述 |
+|---|---|---|
+| `get_chat_history` | `getChatHistory` | 获取聊天历史消息 |
+| `get_chat_meta` | `getChatMeta` | 获取会话元信息 |
+| `create_chat` | `createChat` | 创建一对一会话 |
+| `search` | `searchSome` | 搜索用户和群组 |
+
+### 5.3 用户操作
+
+| tool 名 | 对应方法 | 描述 |
+|---|---|---|
+| `get_user_info` | `getUserInfoById` | 获取用户/机器人信息 |
+| `get_user_profile_card` | `getUserProfileCard` | 获取用户名片（含签名） |
+| `set_user_signature` | `setUserSignature` | 设置当前用户签名 |
+
+### 5.4 日历操作
+
+| tool 名 | 对应方法 | 描述 |
+|---|---|---|
+| `get_calendar_events` | `getCalendarEvents` | 获取日历事件列表 |
+| `calendar_rsvp` | `calendarRsvp` | 回复日历邀请（接受/拒绝/待定） |
+
+### 5.5 媒体操作
+
+| tool 名 | 对应方法 | 描述 |
+|---|---|---|
+| `download_image` | `downloadImage` | 下载图片（支持解密） |
+
+共 15 个 tools。
+
+## 6. 目录结构
+
+```
+openbird/
+├── bin/
+│   └── openbird.js              # CLI 入口
+├── src/
+│   ├── core/                    # 从 feishu-bot/lib 提取的核心能力
+│   │   ├── api.js               # HTTP API 客户端
+│   │   ├── auth.js              # Cookie 认证
+│   │   ├── websocket.js         # WebSocket 客户端
+│   │   ├── builders/
+│   │   │   ├── header.js
+│   │   │   ├── params.js
+│   │   │   ├── proto.js
+│   │   │   └── richtext.js
+│   │   ├── proto/
+│   │   │   ├── proto.proto
+│   │   │   └── proto_pb.js
+│   │   ├── generated/
+│   │   │   ├── proto.js
+│   │   │   └── proto_pb.js
+│   │   └── utils/
+│   │       ├── cookie.js
+│   │       ├── encryption.js
+│   │       ├── time.js
+│   │       └── varint.js
+│   ├── webhook/
+│   │   ├── normalizer.js        # WebSocket 事件 -> OpenBird 标准格式
+│   │   └── dispatcher.js        # HTTP POST 转发到 webhook URL
+│   ├── mcp/
+│   │   └── server.js            # MCP Server (stdio), 15 个 tools
+│   └── index.js                 # 主入口：初始化 auth -> 启动 WS + MCP
+├── package.json
+├── .env.example
+└── README.md
+```
+
+### 6.1 从 feishu-bot 提取到 src/core/ 的文件
+
+直接迁移 `feishu-bot/src/lib/` 的以下文件：
+
+- `api.js`, `auth.js`, `websocket.js`
+- `builders/header.js`, `builders/params.js`, `builders/proto.js`, `builders/richtext.js`
+- `proto/proto.proto`, `proto/proto_pb.js`
+- `generated/proto.js`, `generated/proto_pb.js`
+- `utils/cookie.js`, `utils/encryption.js`, `utils/time.js`, `utils/varint.js`
+
+不迁移（agent 专用）：
+
+- `utils/timestamp-enhancer.js`
+- `utils/getAppKeyRemote.js`
+- `tools/time.js`（LangChain tool）
+
+## 7. V1 明确不做
+
+- 多 webhook 目标
+- 事件过滤/路由规则
+- Webhook 签名验证
+- 多平台适配
+- 事件持久化/回放
+- Agent Runtime
+- 多租户
+- UI