pi-feishu-connector

安静、可靠的 Pi × 飞书/Lark 连接器。群聊默认只响应明确的机器人 @提及。

English · 更新记录 · 安全说明 · 来源与许可证

特性

• 群聊默认静默：普通消息、@其他人、回复机器人都不触发；机器人身份未知时拒绝群消息。私聊正常工作。
• 请求绑定输出：只转发当前请求所属会话的回复；忽略空闲会话自主输出、旧会话迟到事件。
• 系统通知不进群：健康、配额等 owner 通知只投私聊；连接断开/恢复报告默认关闭。
• 持久 Outbox：按会话串行投递、幂等键、重试和崩溃恢复；容量与重试上限可配置。
• 连接自愈：心跳探测、退避重连、配额熔断、断连消息补收；补收仍须通过群触发策略。
• 会话管理：按私聊用户、群或话题隔离，FIFO 队列，空闲回收；替换会话后恢复订阅。
• 原生 Pi 能力：模型切换、思考等级、压缩、历史会话、技能与插件命令转发。
• 媒体与常驻：图片输入、文件提取、文件发送、可选流式卡片；独立 daemon 关闭终端后继续运行。
• 更新保留数据：替换或移除扩展会停止旧连接，但不删除凭据、历史和待投递消息。

安装

需要 Node.js 22.18+、Pi、macOS 或 Linux。daemon 使用 Bash/POSIX 进程管理。

pi install git:github.com/huaiwen/[email protected]
pi

在 Pi 中执行：

/feishu setup
/feishu start

setup 通过二维码创建和配置飞书应用。使用已有应用时，需要启用机器人、发布应用并订阅 im.message.receive_v1 长连接事件；按功能配置消息、资源和表情权限。

私聊机器人，或在群里 @机器人 + 问题。群策略在表情、命令路由和模型调用之前检查。

从 pi-feishu-link 迁移

1. 在旧扩展仍注册时执行 /feishu stop，然后关闭旧 Pi 会话。 旧版的自动清理逻辑可能删除配置；先备份状态目录。

2. 在终端移除旧包，再安装新包：

   pi remove npm:pi-feishu-link
   pi install git:github.com/huaiwen/[email protected]

3. 重启 Pi。新包沿用 ~/.pi/agent/feishu-link/，保留凭据、路由、会话映射和 Outbox。

4. 旧配置显式写入的值会保留。要采用严格群策略，在 Pi 中执行：

   /feishu config groupPolicy=mention
   /feishu config groupAlsoOnReply=false
   /feishu config connection.downReportEnabled=false

   同时确认配置与 runtime-overrides.json 中的 groupKeywords 都为空数组。

不要同时启用两个飞书桥接扩展。兼容期保留 PI_FEISHU_LINK_HOME、PI_FEISHU_LINK_CHILD、PI_FEISHU_LINK_DAEMON 环境名和旧的会话哈希格式。

开发版与更新

本地维护补丁时使用路径安装，避免 Pi 管理的 Git/npm 缓存被更新覆盖：

git clone https://github.com/huaiwen/pi-feishu-connector.git
cd pi-feishu-connector
npm ci
pi install "$PWD"

发布版安装固定 tag；升级时显式安装新的 tag。停止 daemon 后再替换正在使用的源码，完成后 /feishu start。

命令

| 场景 | 命令 | | --- | --- | | Pi 终端 | /feishu setup、start、stop、restart、takeover、status、doctor | | 热改配置 | /feishu config key=value | | 飞书会话 | /status、/workspace、/stop、/doctor、/help | | Pi 原生命令 | /model、/thinking、/compact、/new、/resume、/name、/session、/copy | | 插件和技能 | /skill:name 及其他扩展命令转交 Pi |

群里的命令也需要 @机器人。可选的 @ineersa/my-pi-scheduler 只为已创建并绑定路由的任务投递结果；没有引入固定群广播 Webhook。

默认配置与权限

{
  "groupPolicy": "mention",
  "groupKeywords": [],
  "groupAlsoOnReply": false,
  "connection": { "downReportEnabled": false }
}

这些是新配置默认值；显式配置和运行时覆盖优先。需要开放群聊的管理员仍可自行配置 open 策略。

@提及不是身份授权。 接入共享群前设置 allowUsers、allowChats 和 admins。继承的工具权限默认是 relaxed：大部分工具直接执行，命中破坏性黑名单时请求审批。需要更严格控制时执行：

/feishu config permissions.policy=strict

凭据应通过本地配置或 Pi 认证流程管理，不要在群中发送 API key。此版本保留进程内 Pi SDK 会话，不提供操作系统级沙箱或参考项目的独立 RPC 进程隔离。

数据与卸载

状态目录默认是 ~/.pi/agent/feishu-link/，可通过 PI_FEISHU_LINK_HOME 更改。配置和会话映射按私有文件权限保存；聊天历史由 Pi SessionManager 持久化。日志和 Outbox 可能包含聊天内容，请勿提交到 Git。

卸载前执行 /feishu stop。pi remove 只移除包注册；连接器检测到移除后停止，不自动删除用户数据。确认不再需要后自行清理状态目录及相应 Pi 会话文件。

开发与验证

npm ci
npm test
npm run check
npm pack --dry-run

测试覆盖群触发、通知路由、请求生命周期、空闲回收、安装源识别、连接恢复、媒体、持久投递和真实 Pi 扩展加载。CI 在 Linux/macOS 上运行。

来源

• 基于 amlyczz/pi-feishu-link v0.2.3，保留上游历史与 MIT 许可。
• 吸收 Tieboyh/pi-feishu-bot 的请求绑定事件、会话生命周期与持久数据保护思路，按现有架构重新实现。
• 保留原项目对 AX1202/pi-feishu-lark、yangtuooc/pi-feishu-lark、my-pi-scheduler、pi-agent-qqbot 的致谢。

本次没有移植参考项目的完整 RPC 后端、群历史预取或固定群通知。详见 THIRD_PARTY_NOTICES.md。

English

A quiet-by-default Feishu/Lark connector for Pi, based on pi-feishu-link with selected lifecycle safety patterns from pi-feishu-bot.

Install with pi install git:github.com/huaiwen/[email protected], then run /feishu setup and /feishu start in Pi. Requires Node.js 22.18+ and macOS/Linux.

Groups require an explicit bot mention by default. Unknown bot identity fails closed; reply-to-bot and keyword exceptions are disabled in new configurations. Assistant events are forwarded only for an active request on the current session handle. Owner notifications never fall back to groups, and connection reports default to off.

The connector keeps the persistent outbox, per-conversation FIFO sessions, native Pi commands and self-healing daemon. Updates/uninstalls preserve state. Existing configurations are not silently overwritten; review their group policy when migrating. Stop the old daemon and close old Pi sessions before removing pi-feishu-link. Both packages share the legacy state directory for compatibility and should not run together.

Pi tools execute with your local account privileges. Configure user/chat allowlists and strict tool approvals before exposing the bot to others. Run npm test and npm run check for validation.

License

MIT. Original copyright notices and reference attribution are retained.