Pi-Feishu

通过飞书官方 Bot API（WebSocket 长连接），将飞书作为聊天渠道远程控制 Pi Agent。

在飞书中给 Bot 发消息，Pi 自动接收并处理，响应实时回传到飞书。

功能

• 使用飞书官方 Node.js SDK（@larksuiteoapi/node-sdk）WebSocket 长连接，稳定可靠
• 工具执行进度实时推送：每次工具调用在飞书中显示可编辑的进度卡片
• 中间文本推送：assistant 思考过程中的每一步文本都推送到飞书，不只是最终回复
• Reaction 输入指示：处理中显示 Typing 表情，完成后自动移除
• 媒体收发：图片、文件自动下载/上传，支持双向传递
• Pi LLM 可主动发送文本、图片、文件到飞书（通过注册的工具）
• 消息去重（12h TTL FIFO）+ 过期消息过滤（30min）
• 支持多用户同时与 Bot 对话
• 支持飞书（国内）和 Lark（海外）两种域名

安装

pi install npm:pi-feishu

配置

获取凭证

在飞书开放平台创建应用，获取 App ID 和 App Secret。确保应用已开启机器人能力。

配置方式

支持三种配置方式，优先级从高到低：

1. CLI 标志

pi --feishu-app-id=cli_xxx --feishu-app-secret=xxx

2. 环境变量

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

3. Pi settings.json（推荐）

在 .pi/settings.json（项目级）或 ~/.pi/agent/settings.json（全局）中添加：

{
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "domain": "feishu",
    "encryptKey": "",
    "verificationToken": ""
  }
}

字段名支持 camelCase（appId）和 snake_case（app_id）两种写法。项目级配置覆盖全局配置。

配置项说明

字段	环境变量	CLI 标志	必需
App ID	FEISHU_APP_ID	--feishu-app-id	是
App Secret	FEISHU_APP_SECRET	--feishu-app-secret	是
域名	FEISHU_DOMAIN	--feishu-domain	否，默认 feishu
加密密钥	FEISHU_ENCRYPT_KEY	--feishu-encrypt-key	否
验证令牌	FEISHU_VERIFICATION_TOKEN	--feishu-verification-token	否

domain 可选 feishu（国内）或 lark（海外），默认 feishu。

启动

pi

Pi 启动时会自动加载 pi-feishu 扩展并通过 WebSocket 连接飞书。在飞书中给 Bot 发消息即可开始使用。

管理命令

在 Pi 中使用 /feishu 命令管理连接：

命令	说明
/feishu start	启动飞书 Bot 连接
/feishu stop	断开连接
/feishu status	查看连接状态
/feishu config	查看当前配置
/feishu help	显示帮助

消息流程

一次典型的工具调用对话，飞书端看到的消息如下：

用户: 帮我查看当前目录的文件

Bot:                                    [进度卡片，原地更新]
  执行中 (1)
  Shell ...

Bot:                                    [进度卡片更新]
  工具调用
  Shell

Bot:                                    [最终回复]
  当前目录下有以下文件：
  - src/index.ts
  - src/feishu-client.ts
  ...

事件映射

Pi 事件	飞书动作
入站消息	添加 Typing Reaction + 转发给 Pi
tool_execution_start	创建/更新进度卡片
tool_execution_end	更新进度卡片（标记完成/失败）
turn_end（含工具调用）	发送中间文本（回复模式）
turn_end（纯文本）	发送最终回复（新消息）
agent_end	移除 Typing Reaction

注册的 Pi 工具

Pi LLM 可以主动调用以下工具向飞书发送内容：

工具名	说明
send_to_feishu	发送文本消息到飞书
send_image_to_feishu	上传并发送图片到飞书
send_file_to_feishu	上传并发送文件到飞书

消息类型支持

入站类型	说明	资源下载
text	纯文本	--
post	富文本（Markdown）	--
image	图片	自动下载到本地
file	文件	自动下载到本地
audio	语音	自动下载到本地
video	视频	自动下载到本地
sticker	表情	--
interactive	卡片消息	--

出站类型	说明
post	富文本（Markdown，支持分块）
interactive	进度卡片（可编辑更新）
image	图片消息（通过 image_key）
file	文件消息（通过 file_key）

架构

+---------------------+   WebSocket (SDK)   +--------------------+
|   飞书 Bot 网关      | <-----------------> |  Pi Extension      |
|   open.feishu.cn    |   EventDispatcher   |  (feishu-client)   |
+---------------------+                     +---------+----------+
                                                      |
                                                      | sendUserMessage()
                                                      | on("turn_end")
                                                      | on("tool_execution_*")
                                                      v
                                             +--------------------+
                                             |  Pi Agent Core     |
                                             |  (LLM + Tools)     |
                                             +--------------------+

项目结构

pi-feishu/
+-- src/
|   +-- index.ts           # Pi 扩展主入口，事件处理，工具注册
|   +-- feishu-client.ts   # 飞书 WebSocket 客户端封装
|   +-- types.ts           # 类型定义
+-- package.json
+-- README.md

开发

npm install
npm run typecheck
pi -e ./src/index.ts --feishu-app-id=YOUR_ID --feishu-app-secret=YOUR_SECRET

注意事项

1. App Secret 请妥善保管，不要提交到版本控制
2. 应用需要在飞书开放平台开启「机器人」能力
3. 单条消息最大 4000 字符（飞书限制），长消息自动分块
4. 进度卡片内容限制约 3500 字符，超出部分自动截断
5. 媒体文件下载到系统临时目录（/tmp/feishu-media/）

License

MIT