feishu-bridge 1.0.3 → 1.0.4

package/README.md

@@ -1,22 +1,30 @@
-# Feishu Bridge
+# 飞书桥接器 (Feishu Bridge)
 
-🚀 轻量级飞书插件，桥接飞书与各种AI编程IDE/CLI工具
+🚀 轻量级飞书插件，桥接飞书与各种 AI 编程 IDE/CLI 工具
 
 ## ✨ 特性
 
-- **🎯 零依赖**: 无需OpenClaw，独立运行
-- **🔌 多IDE支持**: VS Code, Cursor, Trae, OpenCode, Claude Code, Kiro, Antigravity
+- **🎯 零依赖**: 无需 OpenClaw，独立运行
+- **🔌 多 IDE 支持**: VS Code, Cursor, Trae, OpenCode, Claude Code, Kiro, Antigravity
 - **💬 全交互**: 通过飞书完成所有操作，结果返回飞书
-- **🔒 安全**: Webhook签名验证(HMAC-SHA256)，防重放攻击
-- **📊 监控**: 健康检查端点，Prometheus指标
-- **🔧 完整CLI**: 配置管理、守护进程、状态监控
-- **⚡ 自动启动**: Shell hook自动检测IDE环境并启动服务
-- **🔄 双模式**: WebSocket和Webhook双连接模式支持
-- **💾 备用通信**: 文件系统IPC机制确保可靠性
+- **🔒 安全**: Webhook 签名验证(HMAC-SHA256)，防重放攻击
+- **📊 监控**: 健康检查端点，Prometheus 指标
+- **🔧 完整 CLI**: 配置管理、守护进程、状态监控
+- **⚡ 自动启动**: Shell hook 自动检测 IDE 环境并启动服务
+- **🔄 双模式**: WebSocket 和 Webhook 双连接模式支持
+- **💾 备用通信**: 文件系统 IPC 机制确保可靠性
+
+---
 
 ## 📦 安装
 
-### 方式一: curl一键安装 (推荐)
+### 方式一: npm 全局安装（推荐）
+
+```bash
+npm install -g feishu-bridge
+```
+
+### 方式二: curl 一键安装
 
 **Linux/macOS:**
 ```bash
@@ -28,12 +36,6 @@ curl -fsSL https://install.feishu-bridge.dev | bash
 iwr -useb https://install.feishu-bridge.dev/install.ps1 | iex
 ```
 
-### 方式二: npm全局安装
-
-```bash
-npm install -g feishu-bridge
-```
-
 ### 方式三: 手动安装
 
 ```bash
@@ -44,195 +46,348 @@ npm run build
 npm link
 ```
 
-## Architecture
+---
 
-```
-┌─────────────────┐    WebSocket/Webhook    ┌─────────────────────────┐
-│   Feishu        │ ◄──────────────────────► │     Feishu Bot          │
-│  (手机/PC/Web)  │                         │   (自建应用机器人)        │
-└─────────────────┘                         └─────────────────────────┘
-                                                        │
-                                                        ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Feishu Bridge Core                          │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
-│  │  Message    │  │   Session   │  │   Tool      │  │  Response  │ │
-│  │  Handler    │  │   Manager   │  │   Router    │  │  Formatter │ │
-│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
-└─────────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                      IDE/CLI Adapters Layer                         │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
-│  │ VS Code  │ │  Cursor  │ │  Trae    │ │ OpenCode │ │ Claude   │  │
-│  │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │  │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## Installation
-
-### npm Global Install
+## 🚀 快速开始
+
+### 1. 配置飞书应用
+
+1. 访问 [飞书开放平台](https://open.feishu.cn/)
+2. 创建企业自建应用
+3. 获取 **App ID** 和 **App Secret**
+4. 启用机器人功能
+5. 选择连接模式（WebSocket 推荐）
+
+### 2. 配置桥接器
 
 ```bash
-# Install globally
-npm install -g feishu-bridge
+# 设置 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
+```
 
-# Configure your Feishu app credentials
-feishu-bridge config set appId YOUR_APP_ID
-feishu-bridge config set appSecret YOUR_APP_SECRET
+### 3. 启动服务
 
-# Start the server
+```bash
+# 前台模式（调试用）
 feishu-bridge start
+
+# 或后台模式（生产用）
+feishu-bridge daemon start
 ```
 
-### Manual Install
+### 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`
+
+```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 命令
 
 ```bash
-# Clone the repository
-git clone https://github.com/your-org/feishu-bridge.git
-cd feishu-bridge
+# 服务管理
+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                # 显示帮助
+```
 
-# Install dependencies
-npm install
+---
 
-# Build the project
-npm run build
+## 🔌 连接模式
 
-# Start the server
-npm start
+### WebSocket 模式（推荐）
+
+**优点：**
+- 无需公网 IP
+- 无需配置 Webhook URL
+- 自动重连
+
+**配置：**
+```bash
+feishu-bridge config set feishu.connectionMode websocket
+```
+
+**飞书端配置：**
+1. 进入应用 → 事件订阅
+2. 选择「长连接（WebSocket）」
+3. 开启连接
+
+### Webhook 模式
+
+**适用场景：**
+- 有固定公网 IP
+- 使用内网穿透工具（如 ngrok）
+
+**配置：**
+```bash
+feishu-bridge config set feishu.connectionMode webhook
+feishu-bridge config set server.webhookPath /webhook/feishu
 ```
 
-## Configuration
+**飞书端配置：**
+1. 进入应用 → 事件订阅
+2. 选择「HTTP 推送」
+3. 配置 URL: `http://你的IP:3000/webhook/feishu`
+
+---
 
-Create a `.env` file in your project root:
+## 🏗️ 架构
 
-```env
-FEISHU_APP_ID=your_app_id
-FEISHU_APP_SECRET=your_app_secret
-FEISHU_ENCRYPT_KEY=your_encrypt_key (optional)
-FEISHU_VERIFICATION_TOKEN=your_verification_token (optional)
-SERVER_PORT=3000
-SERVER_HOST=0.0.0.0
 ```
+┌─────────────────┐    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. 桥接器发送回飞书
 
-## Usage
+---
 
-### CLI Commands
+## 🛠️ 故障排除
 
+### 服务无法启动
+
+**端口被占用：**
 ```bash
-# Configuration
-feishu-bridge config set appId <value>
-feishu-bridge config set appSecret <value>
-feishu-bridge config list
+# 更换端口
+feishu-bridge config set server.port 3001
+feishu-bridge start
+```
+
+### 无法接收消息
 
-# Service management
-feishu-bridge start                    # Start service
-feishu-bridge start --daemon          # Start in daemon mode
-feishu-bridge daemon start            # Start daemon
-feishu-bridge daemon stop             # Stop daemon
-feishu-bridge status                  # Check service status
+**检查清单：**
+1. 服务是否运行：`feishu-bridge status`
+2. 飞书应用是否已发布
+3. 机器人是否在群组中
+4. WebSocket 是否连接成功（查看日志）
 
-# Auto-start hook (install once)
-curl -fsSL https://install.feishu-bridge.dev/hook.sh | bash
+**查看日志：**
+```bash
+# 前台模式直接查看
+feishu-bridge start
+
+# 后台模式查看日志
+feishu-bridge daemon logs
+```
+
+### IDE 无响应
+
+**检查指令文件：**
+```bash
+# Windows
+ls $env:TEMP\feishu-bridge\vscode\
+
+# macOS/Linux
+ls /tmp/feishu-bridge/vscode/
 ```
 
-### Feishu Commands
+**手动创建测试指令：**
+```bash
+# 创建指令文件测试 IDE 响应
+echo '{"type":"command","command":"/test","timestamp":'$(date +%s%3N)'}' > /tmp/feishu-bridge/vscode/cmd_test.json
+```
 
-Once the server is running, interact with your IDEs/CLIs directly from Feishu:
+### WebSocket 连接失败
 
+**症状：**
 ```
-@vscode /generate Create a React component for a todo list
-@cursor /run npm start
-@opencode /ask How do I implement authentication in Express.js?
-@claude-code /explain this function
+WebSocket connection failed: Authentication failed
 ```
 
-## Supported Commands
+**解决：**
+1. 检查 App ID 和 App Secret
+2. 确保应用已发布
+3. 切换到 Webhook 模式：
+   ```bash
+   feishu-bridge config set feishu.connectionMode webhook
+   feishu-bridge start
+   ```
+
+---
+
+## 📊 监控
+
+### 健康检查
+
+```bash
+curl http://localhost:3000/health
+```
 
-- `@vscode`: Interact with VS Code and GitHub Copilot
-- `@cursor`: Interact with Cursor IDE
-- `@opencode`: Interact with OpenCode
-- `@claude`: Interact with Claude Code
-- `@trae`: Interact with Trae
-- `@antigravity`: Interact with Antigravity
-- `@kiro`: Interact with Kiro
+响应：
+```json
+{
+  "status": "healthy",
+  "version": "1.0.3",
+  "timestamp": "2026-02-08T12:00:00.000Z"
+}
+```
 
-## Development
+### Prometheus 指标
 
-### Prerequisites
+```bash
+curl http://localhost:3000/metrics
+```
 
-- Node.js 18+
-- npm or yarn
+---
 
-### Setup
+## 🧪 开发
 
 ```bash
-# Clone the repository
+# 克隆项目
 git clone https://github.com/your-org/feishu-bridge.git
 cd feishu-bridge
 
-# Install dependencies
+# 安装依赖
 npm install
 
-# Build the project
+# 开发模式（热重载）
+npm run dev
+
+# 构建
 npm run build
 
-# Start in development mode
-npm run dev
+# 测试
+npm test
+
+# 运行
+npm start
 ```
 
-### Project Structure
-
-```
-src/
-├── core/                      # Core modules
-│   ├── bridge.ts              # Main bridge coordinator
-│   ├── config.ts              # Configuration management
-│   ├── logger.ts              # Logging system
-│   ├── health.ts              # Health monitoring & metrics
-│   └── daemon.ts              # Process daemon & auto-restart
-├── feishu/                    # Feishu integration
-│   ├── client.ts              # Feishu API client
-│   ├── webhook.ts             # Webhook handler with signature verification
-│   ├── websocket.ts           # WebSocket connection handler
-│   └── types.ts               # Feishu type definitions
-├── adapters/                  # IDE/CLI adapters (7 implementations)
-│   ├── base.ts                # Adapter base class
-│   ├── vscode.ts              # VS Code adapter
-│   ├── cursor.ts              # Cursor adapter
-│   ├── opencode.ts            # OpenCode adapter (Socket)
-│   └── ...
-├── cli/                       # CLI implementation
-│   ├── index.ts               # CLI entry & commands
-│   └── config.ts              # Config management
-├── commands/                  # Command processing
-│   ├── executor.ts            # Command executor
-│   └── parser.ts              # Command parser
-├── session/                   # Session management
-│   └── manager.ts             # Session manager
-└── utils/                     # Utility functions
-    └── http.ts                # HTTP utilities
-
-scripts/                       # Installation scripts
-├── install.sh                 # Linux/macOS installer
-├── install.ps1                # Windows installer
-└── install-hook.sh            # Auto-start hook installer
-
-tests/                         # Test suite (54 tests)
-├── unit/                      # Unit tests
-└── integration/               # Integration tests
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
-
-MIT License
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**Happy Coding!** 🚀