> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Feishu (Lark)

> 企業向けカスタムアプリで CowAgent を Feishu に接続

> 飛書（Feishu）の企業向けカスタムアプリを通じて CowAgent を接続。1 対 1 チャット、グループチャット（@メンション）に対応。WebSocket 長接続を使用するため公開 IP 不要、ストリーミングのタイプライター応答や音声メッセージにも対応します。

<Note>
  接続には管理者権限を持つ Feishu 企業ユーザーが必要です。
</Note>

## 1. 接続方法

### 方式 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" />

2. **アプリ機能の追加** で **Bot** 機能を追加:

<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800" />

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
```

<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800" />

4. **認証情報と基本情報** から `App ID` と `App Secret` を取得:

<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800" />

**ステップ 2: CowAgent に接続**

<Tabs>
  <Tab title="Web コンソール">
    Web コンソールから **チャネル** → **チャネルを追加** → **Feishu** → **手動入力** タブに切り替え、App ID と App Secret を入力して接続。
  </Tab>

  <Tab title="設定ファイル">
    `config.json` に以下を追加して起動:

    ```json theme={null}
    {
      "channel_type": "feishu",
      "feishu_app_id": "YOUR_APP_ID",
      "feishu_app_secret": "YOUR_APP_SECRET",
      "feishu_stream_reply": true
    }
    ```

    | パラメータ                  | 説明                                                      | デフォルト  |
    | ---------------------- | ------------------------------------------------------- | ------ |
    | `feishu_app_id`        | Feishu アプリの App ID                                      | -      |
    | `feishu_app_secret`    | Feishu アプリの App Secret                                  | -      |
    | `feishu_stream_reply`  | ストリーミングタイプライター応答を有効化                                    | `true` |
    | `feishu_detailed_card` | ストリーミング応答を詳細カード（ツール呼び出し、思考過程、経過時間）で表示。無効時は通常のタイプライターカード | `true` |
  </Tab>
</Tabs>

**ステップ 3: アプリの公開**

1. Cow 起動後、Feishu 開発者プラットフォームの **イベントとコールバック** で **ロングコネクション** モードを選択して保存:

<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600" />

2. **イベントを追加** で「メッセージ受信」を検索し、**メッセージ受信 v2.0** を選択。

3. （任意）**コールバック** で **カードアクショントリガー**（`card.action.trigger`）を追加すると `/tasks` のスケジューラー管理コマンドを使用できます。**メッセージ撤回**（`im.message.recalled_v1`）イベントを追加すると、メッセージの撤回でタスクをキャンセルできます。

4. **バージョン管理とリリース** で新バージョンを作成し **本番リリース** を申請、Feishu クライアントで承認:

<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600" />

## 2. 機能一覧

| 機能             | 対応状況                                                    |
| -------------- | ------------------------------------------------------- |
| 1 対 1 チャット     | ✅                                                       |
| グループチャット（@Bot） | ✅                                                       |
| テキストメッセージ      | ✅ 送受信                                                   |
| 画像メッセージ        | ✅ 送受信                                                   |
| 音声メッセージ        | ✅ 送受信                                                   |
| 引用返信           | ✅ 引用テキストとリッチテキストのコンテキスト                                 |
| ストリーミング応答      | ✅（Feishu cardkit ストリーミングカードベース）                         |
| Markdown カード   | ✅ 静的カードとストリーミング最終状態でリモート画像を Feishu にアップロード              |
| 詳細カード          | ✅ ツール呼び出し、思考過程、経過時間（`feishu_detailed_card` で制御、デフォルト有効） |
| スケジューラー操作      | ✅ `/tasks` で一覧、有効化、無効化、削除                               |

<Note>
  ストリーミング応答には `cardkit:card:write` 権限（ワンクリック作成では自動付与）と Feishu クライアント 7.20 以上が必要です。古いクライアントではアップグレード案内が表示され、権限/バージョン未充足時は通常テキスト応答に自動フォールバックします。
</Note>

## 3. 使い方

接続完了後、Feishu で Bot 名を検索してチャットを開始できます。

グループで使う場合は Bot をグループに追加し、@メンションでメッセージを送ってください。

個人チャットでは `/tasks`、グループでは Bot に @メンションして `/tasks` を送ると、そのチャットのタスクを管理できます。