飞书桥接器 (Feishu Bridge)

🚀 轻量级飞书插件，桥接飞书与各种 AI 编程 IDE/CLI 工具

✨ 特性

• 🎯 零依赖: 无需 OpenClaw，独立运行
• 🔌 多 IDE 支持: VS Code, Cursor, Trae, OpenCode, Claude Code, Kiro, Antigravity
• 💬 全交互: 通过飞书完成所有操作，结果返回飞书
• 🔒 安全: Webhook 签名验证(HMAC-SHA256)，防重放攻击
• 📊 监控: 健康检查端点，Prometheus 指标
• 🔧 完整 CLI: 配置管理、守护进程、状态监控
• ⚡ 自动启动: Shell hook 自动检测 IDE 环境并启动服务
• 🔄 双模式: WebSocket 和 Webhook 双连接模式支持
• 💾 备用通信: 文件系统 IPC 机制确保可靠性

📦 安装

方式一: npm 全局安装（推荐）

npm install -g feishu-bridge

方式二: curl 一键安装

Linux/macOS:

curl -fsSL https://install.feishu-bridge.dev | bash

Windows (PowerShell):

iwr -useb https://install.feishu-bridge.dev/install.ps1 | iex

方式三: 手动安装

git clone https://github.com/your-org/feishu-bridge.git
cd feishu-bridge
npm install
npm run build
npm link

🔄 更新与卸载

更新到最新版本

# 查看当前版本
feishu-bridge --version

# 更新到最新版本
npm update -g feishu-bridge

# 或重新安装最新版本
npm install -g feishu-bridge@latest

完全卸载

# 1. 停止服务（如果正在运行）
feishu-bridge daemon stop

# 2. 卸载 npm 包
npm uninstall -g feishu-bridge

# 3. 清理配置文件（可选）
rm -rf ~/.config/feishu-bridge

# 4. 卸载 Shell Hook（如果已安装）
curl -fsSL https://install.feishu-bridge.dev/hook.sh | bash -s uninstall

🚀 快速开始

1. 配置飞书应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 获取 App ID 和 App Secret
4. 启用机器人功能
5. 选择连接模式（WebSocket 推荐）

2. 配置桥接器

# 设置 App ID
feishu-bridge config set feishu.appId cli_xxxxxxxxxxxx

# 设置 App Secret
feishu-bridge config set feishu.appSecret xxxxxxxxxxxxxxxxxxxxxxxx

# 设置连接模式（推荐 WebSocket，无需公网 IP）
feishu-bridge config set feishu.connectionMode websocket

# 验证配置
feishu-bridge config list

3. 启动服务

# 前台模式（调试用）
feishu-bridge start

# 或后台模式（生产用）
feishu-bridge daemon start

4. 在飞书使用

在配置了机器人的飞书群组中发送：

@vscode /generate a React button component

💬 使用指南

命令格式

@<目标> <命令>

支持的目标

| 目标 | 说明 | 示例 | |------|------|------| | @vscode | VS Code | @vscode /generate login form | | @cursor | Cursor | @cursor /run npm test | | @trae | Trae | @trae build project | | @opencode | OpenCode | @opencode fix bug | | @claude | Claude Code | @claude explain code | | @antigravity | Antigravity | @antigravity deploy | | @kiro | Kiro | @kiro generate API |

常用命令

代码生成：

@vscode /generate a React login form with TypeScript

运行命令：

@cursor /run npm install axios

打开文件：

@vscode open src/App.tsx

解释代码：

@claude explain the authentication flow

搜索代码：

@vscode /search "function handleSubmit"

构建项目：

@trae /build

⚙️ 配置详解

配置文件

位置：~/.config/feishu-bridge/config.json

{
  "feishu": {
    "appId": "cli_xxxxxxxxxxxx",
    "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "domain": "feishu",
    "connectionMode": "websocket",
    "encryptKey": "可选"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0"
  },
  "adapters": {
    "vscode": { "enabled": true },
    "cursor": { "enabled": true },
    "trae": { "enabled": true }
  },
  "behavior": {
    "autoStart": true,
    "maxOutputLength": 2000,
    "sessionTimeout": 30,
    "reverseChannelEnabled": true
  }
}

CLI 命令

# 服务管理
feishu-bridge start                 # 前台启动
feishu-bridge daemon start          # 后台启动
feishu-bridge daemon stop           # 停止服务
feishu-bridge daemon restart        # 重启服务
feishu-bridge status                # 查看状态

# 配置管理
feishu-bridge config set <key> <value>    # 设置配置
feishu-bridge config get <key>            # 获取配置
feishu-bridge config delete <key>         # 删除配置
feishu-bridge config list                 # 列出所有配置

# 其他
feishu-bridge --version             # 查看版本
feishu-bridge --help                # 显示帮助

🔌 连接模式

WebSocket 模式（推荐）

优点：

• 无需公网 IP
• 无需配置 Webhook URL
• 自动重连

配置：

feishu-bridge config set feishu.connectionMode websocket

飞书端配置：

1. 进入应用 → 事件订阅
2. 选择「长连接（WebSocket）」
3. 开启连接

Webhook 模式

适用场景：

• 有固定公网 IP
• 使用内网穿透工具（如 ngrok）

配置：

feishu-bridge config set feishu.connectionMode webhook
feishu-bridge config set server.webhookPath /webhook/feishu

飞书端配置：

1. 进入应用 → 事件订阅
2. 选择「HTTP 推送」
3. 配置 URL: http://你的IP:3000/webhook/feishu

🏗️ 架构

┌─────────────────┐    WebSocket/Webhook    ┌─────────────────────────┐
│   飞书用户       │  ───────────────────►   │      桥接器服务          │
│   (群组消息)     │                         │   (feishu-bridge)       │
└─────────────────┘                         └───────────┬─────────────┘
                                                        │
                             文件系统 IPC               │
                             /tmp/feishu-bridge/        ▼
                                                        │
                       ┌────────────────────────────────┴────────────────┐
                       │                                                    │
              ┌────────▼─────────┐  ┌──────────▼──────┐  ┌───────▼───────┐
              │   VS Code        │  │    Cursor       │  │    Trae       │
              │   扩展/脚本      │  │    脚本         │  │   脚本        │
              └──────────────────┘  └─────────────────┘  └───────────────┘

工作流程：

1. 用户在飞书发送 @vscode /generate button
2. 桥接器接收消息并解析
3. 写入指令文件到 /tmp/feishu-bridge/vscode/
4. IDE 扩展/脚本读取并执行
5. 结果写回文件系统
6. 桥接器发送回飞书

🛠️ 故障排除

服务无法启动

端口被占用：

# 更换端口
feishu-bridge config set server.port 3001
feishu-bridge start

无法接收消息

检查清单：

1. 服务是否运行：feishu-bridge status
2. 飞书应用是否已发布
3. 机器人是否在群组中
4. WebSocket 是否连接成功（查看日志）

查看日志：

# 前台模式直接查看
feishu-bridge start

# 后台模式查看日志
feishu-bridge daemon logs

IDE 无响应

检查指令文件：

# Windows
ls $env:TEMP\feishu-bridge\vscode\

# macOS/Linux
ls /tmp/feishu-bridge/vscode/

手动创建测试指令：

# 创建指令文件测试 IDE 响应
echo '{"type":"command","command":"/test","timestamp":'$(date +%s%3N)'}' > /tmp/feishu-bridge/vscode/cmd_test.json

WebSocket 连接失败

症状：

WebSocket connection failed: Authentication failed

解决：

1. 检查 App ID 和 App Secret
2. 确保应用已发布
3. 切换到 Webhook 模式：

   feishu-bridge config set feishu.connectionMode webhook
   feishu-bridge start

📊 监控

健康检查

curl http://localhost:3000/health

响应：

{
  "status": "healthy",
  "version": "1.0.3",
  "timestamp": "2026-02-08T12:00:00.000Z"
}

Prometheus 指标

curl http://localhost:3000/metrics

🧪 开发

# 克隆项目
git clone https://github.com/your-org/feishu-bridge.git
cd feishu-bridge

# 安装依赖
npm install

# 开发模式（热重载）
npm run dev

# 构建
npm run build

# 测试
npm test

# 运行
npm start

📄 许可证

MIT License

Happy Coding! 🚀