Gemini to Feishu (Lark) IM Bridge

English | 中文说明

---

English

A lightweight Node.js background service that connects your local gemini-cli agent to Feishu (Lark). This allows you to chat with and control your local Gemini agent directly through Feishu messages.

Features

• Utilizes Feishu's Open Platform Long Connection (WebSocket) to receive messages instantly without requiring a public IP or webhook URL.
• Transparently forwards text messages to the local gemini command line in headless JSON mode and returns the AI's response to your chat.
• Safe proxy management: Applies proxy settings strictly to the Gemini process to avoid breaking the Feishu WebSocket connection.

Prerequisites

1. Node.js: v18 or newer.
2. Gemini CLI: Ensure that the gemini CLI command is installed and authenticated.
3. Feishu Developer App: You must have a Custom App on the Feishu Open Platform with the Bot feature enabled, IM read/send permissions granted, and Event Subscription set to "Long Connection".

Installation

1. Copy or clone this repository to your local machine.
2. Install dependencies:

   npm install

3. Create a .env file in the root directory (see Configuration below).
4. Start the bridge:

   npm start

Configuration (.env)

Create a .env file in the project root with the following variables:

FEISHU_APP_ID=cli_aXXXXXXX
FEISHU_APP_SECRET=XXXXXXX

# --- Optional Gemini Proxy Settings ---
# If your network requires a proxy (e.g. Clash, V2ray) to access Google APIs, 
# provide the proxy URLs below. 
# 
# IMPORTANT: Use GEMINI_HTTP_PROXY and GEMINI_HTTPS_PROXY instead of standard HTTP_PROXY. 
# This prevents the Node.js application from proxying the Feishu WebSocket connection itself, 
# which would result in ECONNREFUSED errors.

GEMINI_HTTP_PROXY=http://127.0.0.1:7890
GEMINI_HTTPS_PROXY=http://127.0.0.1:7890

---

中文说明

这是一个轻量级的 Node.js 后台服务，可将您本地的 gemini-cli AI 代理连接到飞书 (Feishu/Lark)。通过此工具，您可以直接在飞书聊天框中发送消息，并调用和控制本地的 Gemini 终端。

功能特点

• 使用飞书开放平台的长连接 (WebSocket) 模式接收消息，无需配置公网 IP 或繁琐的 Webhook。
• 通过 Headless JSON 模式，透明地将文本转发给本地的 gemini 命令，并提取 AI 响应发送回飞书聊天框。
• 安全的代理管理：将代理设置严格隔离在 Gemini 子进程中，避免干扰飞书自身的 WebSocket 官方连接。

前提要求

1. Node.js：在您的机器上安装 v18 或更新版本。
2. Gemini CLI：确保本地已安装并配置好 gemini 命令行工具。
3. 飞书开发者应用：需要在飞书开放平台创建一个企业自建应用，启用“机器人”能力，开启收取/发送消息的权限。并在“事件订阅”中设置为长连接，通过订阅 im.message.receive_v1 事件获取最新消息。

安装与运行

1. 下载或克隆此项目到本地。
2. 安装依赖包：

   npm install

3. 在项目根目录中新建一个 .env 配置文件（参考下方的配置说明）。
4. 启动服务：

   npm start

配置文件说明 (.env)

在根目录新建 .env 文件，内容如下：

FEISHU_APP_ID=cli_aXXXXXXX
FEISHU_APP_SECRET=XXXXXXX

# --- 可选的 Gemini 代理设置 ---
# 如果您在国内使用，且需要代理 (如 Clash, V2ray) 才能访问 Google 的底层 API 服务器，
# 请在下方填入本地代理地址。
#
# 【重要提示】：请务必使用 GEMINI_HTTP_PROXY 和 GEMINI_HTTPS_PROXY，而不是直接写普通的 HTTP_PROXY。
# 这是因为普通的代理全局变量会导致 Node.js 在连接属于国内访问的飞书 WebSocket 时也走代理，从而引发 ECONNREFUSED （连接拒绝）报错。
# 这样命名后，代理地址仅透传拦截给执行 gemini 的子进程，不会影响全局网络。

GEMINI_HTTP_PROXY=http://127.0.0.1:7890
GEMINI_HTTPS_PROXY=http://127.0.0.1:7890