@openilink/app-lark

# 直接构建并启动
docker compose up -d

# 或单独构建镜像
docker build -t openilink-app-lark .
docker run -d \
  -p 8081:8081 \
  -e HUB_URL="https://your-hub.example.com" \
  -e BASE_URL="https://your-app.example.com" \
  -e LARK_APP_ID="cli_xxx" \
  -e LARK_APP_SECRET="xxx" \
  -e LARK_CHAT_ID="oc_xxx" \
  -v app-data:/data \
  openilink-app-lark

git clone https://github.com/openilink/openilink-app-lark.git && cd openilink-app-lark
npm install
cp .env.example .env
# 编辑 .env 填入你的配置

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

# 生产模式
npm run build
npm start

第一步：创建应用

1. 前往 飞书开发者后台
2. 点击「创建企业自建应用」
3. 填写应用名称（如"OpeniLink Bridge"）和描述
4. 记录 App ID 和 App Secret

第二步：配置机器人能力

1. 在应用管理页面，进入「添加应用能力」
2. 开启「机器人」能力

第三步：配置事件订阅

1. 进入「事件订阅」配置页面
2. 连接方式选择 「使用长连接接收事件」（WebSocket 模式，无需公网 IP）
3. 添加以下事件：
   • im.message.receive_v1 -- 接收消息事件

第四步：添加权限

在「权限管理」页面，根据需要使用的功能添加对应权限：

基础权限（必选）：

日历权限：

通讯录权限：

云文档 / 云空间权限：

其他权限：

第五步：发布应用

1. 在应用管理页面点击「创建版本」
2. 填写版本信息后提交审核
3. 管理员在飞书管理后台审批通过即可使用

第六步：获取群聊 ID

如需将微信消息自动转发到指定飞书群，需要获取群聊 Chat ID：

1. 将机器人添加到目标群聊
2. 在群聊中 @机器人 发送任意消息，从 WebSocket 事件日志中获取 chat_id
3. 将其配置为 LARK_CHAT_ID 环境变量

架构图

graph LR
    subgraph 用户侧
        WX[微信用户]
    end

    subgraph OpeniLink Hub
        HUB[Hub 网关]
        AI[Hub AI 引擎]
    end

    subgraph app-lark
        HTTP[HTTP Server :8081]
        BRIDGE[Bridge 桥接层]
        ROUTER[Router 路由器]
        TOOLS[34 Tools]
    end

    subgraph 飞书
        LARK_API[飞书 Open API]
        LARK_WS[飞书 WebSocket]
        LARK_CHAT[飞书群聊]
    end

    WX -- 发消息 --> HUB
    HUB -- webhook --> HTTP
    HTTP -- 消息事件 --> BRIDGE
    BRIDGE -- 转发 --> LARK_API --> LARK_CHAT
    LARK_WS -- 飞书回复 --> HTTP
    HTTP -- 回传 --> HUB --> WX

    HUB -- 自然语言 --> AI
    AI -- 调用 tool --> HTTP
    HTTP --> ROUTER --> TOOLS
    TOOLS -- SDK 调用 --> LARK_API
    TOOLS -- 结果 --> ROUTER --> HTTP --> HUB --> WX

模式一：自动桥接

微信与飞书之间的消息自动双向转发，无需人工干预。

微信用户发消息
  → Hub 推送 webhook（message.* 事件）
    → app-lark 接收并通过 WxToLark 桥接模块处理
      → 调用飞书 IM API 发送到指定群聊（LARK_CHAT_ID）

飞书群内回复
  → 飞书 WebSocket 长连接推送事件
    → app-lark 接收并回传给 Hub
      → Hub 将消息投递回微信用户

模式二：自然语言调用

用户以自然语言描述需求，Hub AI 自动识别意图并调用对应的飞书 Tool。

用户: "帮我查一下本周的日程安排"
  → Hub AI 理解语义
    → 调用 list_calendar_events 工具
      → 飞书日历 API 返回日程数据
        → 格式化后返回给用户

用户: "给张三发条飞书消息，告诉他明天开会"
  → Hub AI 理解语义
    → 先调用 search_contact 找到张三的 open_id
    → 再调用 send_lark_message 发送消息
      → 返回发送结果

模式三：命令调用

Hub 发送 command 事件，直接路由到对应 Tool 的 handler 执行。

Hub 推送 command 事件（如 send_lark_message）
  → Router 根据命令名匹配 handler
    → handler 解析参数并调用飞书 SDK
      → 将执行结果通过 HubClient 回复给用户

常用命令

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

# 编译 TypeScript
npm run build

# 生产环境运行
npm start

# 运行测试
npm test

# 监听模式运行测试
npm run test:watch

项目结构

src/
├── index.ts              # 主入口 - HTTP 服务器 & 飞书事件订阅
├── config.ts             # 环境变量配置加载
├── store.ts              # SQLite 数据持久化
├── router.ts             # 命令路由器
├── bridge/
│   ├── wx-to-lark.ts     # 微信 → 飞书 消息桥接
│   └── lark-to-wx.ts     # 飞书 → 微信 消息桥接
├── hub/
│   ├── client.ts         # Hub API 客户端
│   ├── manifest.ts       # App Manifest 生成
│   ├── oauth.ts          # OAuth 安装流程
│   ├── webhook.ts        # Hub Webhook 处理
│   └── types.ts          # Hub 类型定义
├── lark/
│   ├── client.ts         # 飞书 SDK 客户端封装
│   └── event.ts          # 飞书 WebSocket 事件订阅
├── tools/
│   ├── index.ts          # Tool 注册中心
│   ├── im.ts             # 即时通讯（7 tools）
│   ├── calendar.ts       # 日历（3 tools）
│   ├── doc.ts            # 云文档（3 tools）
│   ├── task.ts           # 任务（3 tools）
│   ├── contact.ts        # 通讯录（2 tools）
│   ├── drive.ts          # 云空间（3 tools）
│   ├── base.ts           # 多维表格（3 tools）
│   ├── sheets.ts         # 电子表格（3 tools）
│   ├── mail.ts           # 邮箱（3 tools）
│   ├── wiki.ts           # 知识库（2 tools）
│   └── vc.ts             # 视频会议（2 tools）
└── utils/
    └── crypto.ts         # 加密工具

HTTP 端点