feat(feishu): one-click QR-scan app creation

This commit is contained in:
zhayujie
2026-05-05 18:32:58 +08:00
parent 8730f7fd27
commit a9c8a59f58
8 changed files with 867 additions and 145 deletions

View File

@@ -3,25 +3,43 @@ title: 飞书
description: 将 CowAgent 接入飞书应用
---
通过自建应用 CowAgent 接入飞书,需要是飞书企业用户且具有企业管理权限
> 通过飞书自建应用接入 CowAgent,支持单聊与群聊(@机器人),使用 WebSocket 长连接模式,无需公网 IP支持流式打字机回复、语音消息收发
## 一、创建企业自建应用
<Note>
接入需要是飞书企业用户且具有企业管理权限。
</Note>
### 1. 创建应用
## 一、接入方式
进入 [飞书开发平台](https://open.feishu.cn/app/),点击 **创建企业自建应用**,填写必要信息后点击 **创建**
### 方式一:扫码一键接入(推荐)
启动 Cow 项目后在终端中即可完成扫码创建。或打开 Web 控制台本地链接http://127.0.0.1:9899 ),选择 **通道** 菜单,点击 **接入通道**,选择 **飞书**,点击 **一键创建飞书应用**,使用 **飞书 App** 扫描二维码即可自动完成应用创建并接入:
<img src="https://cdn.link-ai.tech/doc/20260505181126.png" width="800"/>
<Note>
1. `lark-oapi` 依赖版本需要 >=1.5.5
2. 扫码创建出的应用会自动预置全部所需权限(消息收发、卡片读写、群聊事件等)和事件订阅,无需到开发者后台手动配置。
</Note>
### 方式二:手动创建接入
需要先在飞书开放平台创建自建应用并配置权限,再通过 Web 控制台或配置文件接入。
**步骤一:创建应用**
1. 进入 [飞书开发平台](https://open.feishu.cn/app/),点击 **创建企业自建应用**
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg" width="500"/>
### 2. 添加机器人能力
在 **添加应用能力** 菜单中,为应用添加 **机器人** 能力:
2. 在 **添加应用能力** 中,为应用添加 **机器人** 能力
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800"/>
### 3. 配置应用权限
点击 **权限管理**,复制以下权限配置,粘贴到 **权限配置** 下方的输入框内,全选筛选出来的权限,点击 **批量开通** 并确认:
3. 在 **权限管理** 中,将以下权限粘贴到输入框,全选并 **批量开通**
```
im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p2p_msg,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,cardkit:card:write
@@ -29,43 +47,65 @@ im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p
<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800"/>
## 二、项目配置
1. 在 **凭证与基础信息** 中获取 `App ID` 和 `App Secret`
4. 在 **凭证与基础信息** 中获取 `App ID` 和 `App Secret`
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800"/>
2. 将以下配置加入项目根目录的 `config.json` 文件:
**步骤二:接入 CowAgent**
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
<Tabs>
<Tab title="Web 控制台">
打开 Web 控制台,选择 **通道** 菜单,点击 **接入通道**,选择 **飞书**切换到「手动填写」Tab输入 App ID 和 App Secret点击接入即可。
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动程序:
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `feishu_app_id` | 飞书机器人应用 App ID | - |
| `feishu_app_secret` | 飞书机器人 App Secret | - |
| `feishu_stream_reply` | 是否开启流式打字机回复,关闭则一次性返回完整文本 | `true` |
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
> **流式回复要求**:需要为机器人开通 `cardkit:card:write` 权限,且接收方飞书客户端版本 ≥ 7.20。低版本客户端会显示 "请升级客户端" 占位提示;权限未开通时会自动降级为普通文本回复。
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `feishu_app_id` | 飞书应用 App ID | - |
| `feishu_app_secret` | 飞书应用 App Secret | - |
| `feishu_stream_reply` | 是否开启流式打字机回复 | `true` |
</Tab>
</Tabs>
配置完成后启动项目。
**步骤三:发布应用**
## 三、配置事件订阅
1. 成功运行项目后,在飞书开放平台点击 **事件与回调**,选择 **长连接** 方式,点击保存:
1. 启动 Cow 项目后,在飞书开放平台点击 **事件与回调**,选择 **长连接** 模式并保存:
<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600"/>
2. 点击下方的 **添加事件**,搜索 "接收消息",选择 "**接收消息v2.0**",确认添加
2. 点击 **添加事件**,搜索 "接收消息",选择 **接收消息 v2.0** 并确认
3. 点击 **版本管理与发布**,创建版本并申请 **线上发布**,在飞书客户端查看审批消息并审核通过:
3. 点击 **版本管理与发布**,创建版本并申请 **线上发布**,在飞书客户端审核通过:
<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600"/>
完成后在飞书中搜索机器人名称,即可开始对话。
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 单聊 | ✅ |
| 群聊(@机器人) | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 语音消息 | ✅ 收发 |
| 流式回复 | ✅(通过 `feishu_stream_reply` 配置控制,默认开启) |
<Note>
流式回复需要机器人具备 `cardkit:card:write` 权限(一键创建已默认开通),且接收方飞书客户端版本 ≥ 7.20。低版本客户端会显示升级提示,权限或版本不满足时自动降级为普通文本回复。
</Note>
## 三、使用
完成接入后,在飞书中搜索机器人名称即可开始单聊对话。
如需在群聊中使用,将机器人添加到群中,@机器人发送消息即可。

View File

@@ -1,73 +1,107 @@
---
title: Feishu (Lark)
description: Integrate CowAgent into Feishu application
description: Integrate CowAgent into Feishu via a custom enterprise app
---
Integrate CowAgent into Feishu by creating a custom enterprise app. You need to be a Feishu enterprise user with admin privileges.
> Integrate CowAgent into Feishu via a custom enterprise app. Supports p2p chat and group chat (@bot), uses WebSocket long connection (no public IP needed), supports streaming typewriter replies and voice messages.
## 1. Create Enterprise Custom App
<Note>
You need to be a Feishu enterprise user with admin privileges.
</Note>
### 1.1 Create App
## 1. Setup
Go to [Feishu Developer Platform](https://open.feishu.cn/app/), click **Create Enterprise Custom App**, fill in the required information and click **Create**:
### Option 1: One-click Scan to Create (Recommended)
No need to manually create an app on the Feishu Developer Platform. Start the Cow project, open the web console (default `http://127.0.0.1:9899/`), go to **Channels**, click **Add Channel**, choose **Feishu**, then under the **Scan QR** tab click **One-click Create Feishu App** and scan with the **Feishu App** to complete app creation and connection automatically.
<Note>
The created app comes with all required permissions (messaging, card read/write, group events, etc.) and event subscriptions pre-configured. Currently only the Feishu mainland version is supported (Lark international not yet supported).
</Note>
When starting from CLI without `feishu_app_id` configured, the QR code is also printed to the terminal.
### Option 2: Manual Setup
Manually create a custom app on the Feishu Developer Platform, then connect via Web Console or config file.
**Step 1: Create the App**
1. Go to [Feishu Developer Platform](https://open.feishu.cn/app/), click **Create Enterprise Custom App**:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg" width="500"/>
### 1.2 Add Bot Capability
In **Add App Capabilities**, add **Bot** capability to the app:
2. In **Add App Capabilities**, add the **Bot** capability:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800"/>
### 1.3 Configure App Permissions
Click **Permission Management**, paste the following permission string into the input box below **Permission Configuration**, select all filtered permissions, click **Batch Enable** and confirm:
3. In **Permission Management**, paste the following permissions and **Batch Enable** all:
```
im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p2p_msg,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,cardkit:card:write
```
`cardkit:card:write` is used for streaming typewriter replies (creating and updating streaming cards). You can skip it if streaming is not needed.
<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800"/>
## 2. Project Configuration
1. Get `App ID` and `App Secret` from **Credentials & Basic Info**:
4. Get `App ID` and `App Secret` from **Credentials & Basic Info**:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800"/>
2. Add the following configuration to `config.json` in the project root:
**Step 2: Connect to CowAgent**
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
<Tabs>
<Tab title="Web Console">
Open the web console, go to **Channels**, click **Add Channel**, choose **Feishu**, switch to the **Manual** tab, enter App ID and App Secret, then click connect.
</Tab>
<Tab title="Config File">
Add the following to `config.json` and start the program:
| Parameter | Description | Default |
| --- | --- | --- |
| `feishu_app_id` | Feishu bot App ID | - |
| `feishu_app_secret` | Feishu bot App Secret | - |
| `feishu_stream_reply` | Enable streaming typewriter reply (powered by Feishu cardkit streaming card API). Disable to return the full text at once. | `true` |
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
> **Streaming requirements**: requires `cardkit:card:write` permission on the bot, and recipient Feishu client version ≥ 7.20. Older clients will see a "please upgrade" placeholder; if the permission is missing, replies automatically fall back to plain text.
| Parameter | Description | Default |
| --- | --- | --- |
| `feishu_app_id` | Feishu app App ID | - |
| `feishu_app_secret` | Feishu app App Secret | - |
| `feishu_stream_reply` | Enable streaming typewriter reply | `true` |
</Tab>
</Tabs>
Start the project after configuration is complete.
**Step 3: Publish the App**
## 3. Configure Event Subscription
1. After the project is running successfully, go to the Feishu Developer Platform, click **Events & Callbacks**, select **Long Connection** mode, and click save:
1. After Cow is running, go to **Events & Callbacks** in the Feishu Developer Platform, choose **Long Connection** mode and save:
<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600"/>
2. Click **Add Event** below, search for "Receive Message", select "**Receive Message v2.0**", and confirm.
2. Click **Add Event**, search for "Receive Message" and choose **Receive Message v2.0**.
3. Click **Version Management & Release**, create a new version and apply for **Production Release**. Check the approval message in the Feishu client and approve:
3. Click **Version Management & Release**, create a version and apply for **Production Release**. Approve the request in the Feishu client:
<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600"/>
Once completed, search for the bot name in Feishu to start chatting.
## 2. Features
| Feature | Status |
| --- | --- |
| P2P chat | ✅ |
| Group chat (@bot) | ✅ |
| Text messages | ✅ send/receive |
| Image messages | ✅ send/receive |
| Voice messages | ✅ send/receive |
| Streaming reply | ✅ (powered by Feishu cardkit streaming card) |
<Note>
Streaming reply requires the `cardkit:card:write` permission (already enabled by one-click creation) and Feishu client version ≥ 7.20. Older clients see an upgrade prompt; if the permission or version is not satisfied, replies fall back to plain text automatically.
</Note>
## 3. Usage
After connection, search for the bot name in Feishu to start a chat.
To use in groups, add the bot to a group and @-mention it.

View File

@@ -1,73 +1,107 @@
---
title: Feishu (Lark)
description: CowAgent を Feishu アプリケーションに統合する
description: 企業向けカスタムアプリで CowAgent を Feishu に接続
---
企業向けカスタムアプリを作成して、CowAgent を Feishu に統合します。管理者権限を持つ Feishu 企業ユーザーである必要があります。
> 飛書Feishu企業向けカスタムアプリを通じて CowAgent を接続。1 対 1 チャット、グループチャット(@メンションに対応。WebSocket 長接続を使用するため公開 IP 不要、ストリーミングのタイプライター応答や音声メッセージにも対応します。
## 1. 企業カスタムアプリの作成
<Note>
接続には管理者権限を持つ Feishu 企業ユーザーが必要です。
</Note>
### 1.1 アプリの作成
## 1. 接続方法
[Feishu 開発者プラットフォーム](https://open.feishu.cn/app/)にアクセスし、**企業カスタムアプリを作成**をクリックして、必要な情報を入力し**作成**をクリックします:
### 方式 1: ワンクリック作成(推奨)
事前に Feishu 開発者プラットフォームでアプリを作成する必要はありません。Cow を起動後、Web コンソール(既定 `http://127.0.0.1:9899/`)を開き、**チャネル** メニュー → **チャネルを追加** → **Feishu** を選択し、**QR スキャン** タブで **ワンクリックで Feishu アプリを作成** をクリック。**Feishu アプリ** で QR コードをスキャンするとアプリ作成と接続が自動完了します。
<Note>
作成されたアプリには必要な権限(メッセージ送受信、カード読み書き、グループイベントなど)とイベント購読がすべて事前設定されています。現在は Feishu 中国版のみ対応で、Lark 国際版は未対応です。
</Note>
CLI から `feishu_app_id` 未設定で起動した場合は、ターミナルにも QR コードが表示されます。
### 方式 2: 手動作成
Feishu 開発者プラットフォームで自分でアプリを作成し、Web コンソールまたは設定ファイルから接続します。
**ステップ 1: アプリ作成**
1. [Feishu 開発者プラットフォーム](https://open.feishu.cn/app/) にアクセスし、**企業カスタムアプリを作成** をクリック:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg" width="500"/>
### 1.2 Bot 機能追加
**アプリ機能の追加**で、アプリに **Bot** 機能を追加します:
2. **アプリ機能の追加** で **Bot** 機能追加:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800"/>
### 1.3 アプリ権限の設定
**権限管理**をクリックし、**権限設定**の下の入力欄に以下の権限文字列を貼り付け、フィルタされたすべての権限を選択し、**一括有効化**をクリックして確認します:
3. **権限管理** で以下の権限を貼り付け、全選択して **一括有効化**:
```
im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p2p_msg,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,cardkit:card:write
```
`cardkit:card:write` はストリーミングタイプライター応答(ストリーミングカードの作成と更新)に使用されます。ストリーミングが不要な場合は省略できます。
<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800"/>
## 2. プロジェクト設定
1. **認証情報と基本情報**から `App ID` と `App Secret` を取得します:
4. **認証情報と基本情報** から `App ID` と `App Secret` を取得:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800"/>
2. プロジェクトルートの `config.json` に以下の設定を追加します:
**ステップ 2: CowAgent に接続**
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
<Tabs>
<Tab title="Web コンソール">
Web コンソールから **チャネル** → **チャネルを追加** → **Feishu** → **手動入力** タブに切り替え、App ID と App Secret を入力して接続。
</Tab>
<Tab title="設定ファイル">
`config.json` に以下を追加して起動:
| パラメータ | 説明 | デフォルト値 |
| --- | --- | --- |
| `feishu_app_id` | Feishu Bot の App ID | - |
| `feishu_app_secret` | Feishu Bot の App Secret | - |
| `feishu_stream_reply` | ストリーミングタイプライター応答を有効にするかFeishu 公式 cardkit ストリーミングカード API を使用)。無効化するとテキストを一括で返します。 | `true` |
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
> **ストリーミングの要件**: Bot に `cardkit:card:write` 権限を付与する必要があり、受信者の Feishu クライアントバージョンが 7.20 以上である必要があります。古いバージョンのクライアントでは「クライアントをアップグレードしてください」というプレースホルダーが表示されます。権限が付与されていない場合は、自動的に通常のテキスト応答にフォールバックします。
| パラメータ | 説明 | デフォルト |
| --- | --- | --- |
| `feishu_app_id` | Feishu アプリの App ID | - |
| `feishu_app_secret` | Feishu アプリの App Secret | - |
| `feishu_stream_reply` | ストリーミングタイプライター応答を有効化 | `true` |
</Tab>
</Tabs>
設定完了後、プロジェクトを起動します。
**ステップ 3: アプリの公開**
## 3. イベントサブスクリプションの設定
1. プロジェクトが正常に動作した後、Feishu 開発者プラットフォームに移動し、**イベントとコールバック**をクリックし、**ロングコネクション**モードを選択して保存をクリックします:
1. Cow 起動後、Feishu 開発者プラットフォームの **イベントとコールバック** で **ロングコネクション** モードを選択して保存:
<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600"/>
2. 下の**イベントを追加**をクリックし、「メッセージ受信」を検索して「**メッセージ受信 v2.0**を選択し、確認します
2. **イベントを追加**「メッセージ受信」を検索し**メッセージ受信 v2.0** を選択。
3. **バージョン管理とリリース**をクリックし、新しいバージョンを作成し**本番リリース**を申請します。Feishu クライアントで承認メッセージを確認し、承認します:
3. **バージョン管理とリリース** で新バージョンを作成し **本番リリース** を申請Feishu クライアントで承認:
<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600"/>
完了後、Feishu で Bot 名を検索してチャットを開始できます。
## 2. 機能一覧
| 機能 | 対応状況 |
| --- | --- |
| 1 対 1 チャット | ✅ |
| グループチャット(@Bot | ✅ |
| テキストメッセージ | ✅ 送受信 |
| 画像メッセージ | ✅ 送受信 |
| 音声メッセージ | ✅ 送受信 |
| ストリーミング応答 | ✅Feishu cardkit ストリーミングカードベース) |
<Note>
ストリーミング応答には `cardkit:card:write` 権限(ワンクリック作成では自動付与)と Feishu クライアント 7.20 以上が必要です。古いクライアントではアップグレード案内が表示され、権限/バージョン未充足時は通常テキスト応答に自動フォールバックします。
</Note>
## 3. 使い方
接続完了後、Feishu で Bot 名を検索してチャットを開始できます。
グループで使う場合は Bot をグループに追加し、@メンションでメッセージを送ってください。