@hwj123weijian/pi-feishu 0.8.0 → 0.10.0

package/README.md

@@ -1,28 +1,30 @@
 # pi-feishu
 
-一个独立的 [Pi](https://github.com/earendil-works/pi-mono) 飞书扩展。它通过飞书官方 Node SDK 的 WebSocket 长连接，把飞书私聊文本转发到当前 Pi 会话，并以持续更新的交互卡片展示 Pi 的回复和执行状态。
+一个独立的 [Pi](https://github.com/earendil-works/pi-mono) 飞书扩展。它通过飞书官方 Node SDK 的 WebSocket 长连接，把飞书私聊和已绑定群聊的文本转发到对应的 Pi 会话，并以持续更新的交互卡片展示 Pi 的回复和执行状态。
 
 ## 设计边界
 
-当前版本只做一条可靠的最小链路：
+当前版本聚焦一条可靠的私聊 + 项目群链路：
 
-- 仅处理飞书私聊（`p2p`）文本消息
-- 首次启动生成一次性绑定码，只允许一个 Owner
+- 处理飞书私聊（`p2p`）文本消息，以及已绑定群聊中的文本消息
+- 首次启动生成一次性绑定码，只允许一个 Owner；绑定码只能在私聊中使用
+- Owner 可以把授权成员加入 allowlist（`/allow @成员`），授权成员在私聊和已绑定群里与 Owner 权限一致
 - 收到消息后立刻在原消息上添加“思考中”表情作为已读回执，回复送达后自动移除
 - 以 `/` 开头的消息走远程命令快速通道，不排队、不进入 LLM 上下文
-- 私聊消息进入当前 Pi 会话；扩展创建的每个群聊会在首次收到群消息时创建并绑定一个独立 Pi session，后续该群消息自动切回自己的 session，避免群之间和主对话串上下文
+- 私聊消息进入主 Pi 会话；每个绑定的群聊拥有独立 Pi session，群之间、群与主对话之间不共享上下文
+- 群消息会带上说话人上下文（如 `[飞书群聊] 张三：…`）再发给 Pi；bot 识别 @ 他人、@ 自己
 - 消息需要排队时发送“排队中（第 N 位）”提示，轮到处理时自动撤回；队列变化时提示自动改写为新位数
 - Owner 在排队中的消息上点 ❌（`CrossMark`）表情即可取消该消息
+- 未绑定的群里被 @ 时，bot 会回复绑定引导而不是沉默；非授权成员的普通群消息完全不会触发回复
+- Bot 被拉进新群时，会私聊 Owner 发送绑定引导和群聊权限体检结果；启动成功后也会私聊 Owner 发送欢迎语和权限体检
 - Assistant 文本通过 Pi 的 `message_update` 增量渲染到同一张飞书卡片
 - 工具执行时仅显示安全的状态摘要，不展示参数、命令、文件内容或工具输出
-- SDK 以 500ms / 120 字符节流卡片更新；完成、失败、中止都会收尾卡片
-- 缺少更新权限或飞书卡片更新失败时，自动退化为原私聊的一次性文本回复
-- 串行处理消息，避免多条飞书消息同时驱动 Pi
-- 按飞书 `message_id` 去重
+- SDK 以 500ms / 120 字符节流卡片更新；完成、失败、中止都会收尾卡片，失败原因（脱敏后）会写进回复
+- 消息串行处理（Pi 是单会话进程，跨群并行会互相打断），按飞书 `message_id` 去重且受理记录落盘（48 小时窗口），重启后飞书重推不会重复执行
 - 长连接由跨会话的全局控制器保管：本地 `/new`、远程 `/new` 等会话切换不会断开；`/feishu stop`、`/feishu logout` 或 Pi 进程退出时释放
 - 凭据优先从环境变量读取，也可保存到本地凭据文件
 
-支持 Owner 在飞书私聊中请求创建群聊；扩展会把 Owner 拉入新群、发送欢迎消息，并允许 Owner 在该扩展创建的群里 @机器人继续协作。建群后会私聊 Owner 做一次权限体检，提示缺失的基础 scope、事件订阅页和 `im:message.group_msg` 免 @ 权限申请链接。每个扩展创建的群聊会绑定自己的 Pi session，群聊之间、群聊与本地主对话之间不会共享上下文。其他群聊不会被处理。图片、文件、卡片、语音、多用户、进程级沙箱或远程命令权限管理仍不支持。Pi 本身仍拥有当前本地进程的权限。
+支持在飞书私聊中请求创建群聊；扩展会把 Owner 拉入新群、发送欢迎消息，并在绑定群与私聊中协同使用。图片、文件、卡片、语音、多用户并发执行、进程级沙箱仍不支持。Pi 本身仍拥有当前本地进程的权限。
 
 ## 环境要求
 
@@ -37,16 +39,17 @@
 1. 在“添加应用能力”中启用机器人。
 2. 在“权限管理”中申请：
    - `im:message.p2p_msg:readonly`：接收私聊消息
+   - `im:message.group_at_msg:readonly`：接收群内 @机器人 的消息（**群聊必需，缺了群里 @bot 会完全没有响应**）
    - `im:message:send_as_bot`：以机器人身份回复
-   - `im:chat`：创建群聊并邀请 Owner
+   - `im:chat`：创建群聊并邀请 Owner、读取群信息
    - `im:message:update`：持续更新机器人发出的交互卡片
    - `application:application:self_manage`：启动/建群后读取应用已授权 scope，用于自动提示缺失权限
    - 表情回复相关权限：在原消息上添加/移除“思考中”已读回执
 3. 在“事件与回调”中选择“使用长连接接收事件”。
-4. 添加事件 `im.message.receive_v1`。
+4. 添加事件 `im.message.receive_v1`；建议同时添加 `im.chat.member.bot.added_v1`（被拉进新群时私聊你发送绑定引导）。
 5. 创建并发布一个应用版本，使权限和事件订阅在企业内生效。
 
-这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。若未授予表情回复权限，扩展同样可工作，只是原消息上不会出现已读表情。若希望已创建项目群里无需 @ 机器人即可触发，需要额外申请敏感权限 `im:message.group_msg`；未开通时请在群里使用 `@机器人 你的问题`。
+这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。若未授予表情回复权限，扩展同样可工作，只是原消息上不会出现已读表情。若希望已绑定项目群里无需 @ 机器人即可触发，需要额外申请敏感权限 `im:message.group_msg`（需人工审核 1-3 天）；未开通时请在群里使用 `@机器人 你的问题`。
 
 ## 安装
 
@@ -131,19 +134,33 @@ pi -e D:\ai_study\pi-feishu
 
 ### 飞书远程命令
 
-在飞书私聊里直接发送以下命令，会走高优先级快速通道：不进入消息队列排队，也不会作为提问发给 Pi。
+在飞书私聊或已绑定的群里直接发送以下命令，会走高优先级快速通道：不进入消息队列排队，也不会作为提问发给 Pi。
 
 | 命令 | 作用 |
 | --- | --- |
 | `/help` | 显示远程命令帮助 |
-| `/new` | 新建 Pi 会话（丢弃当前对话上下文） |
+| `/new` | 新建 Pi 会话；在群里发送时重置该群绑定的会话，不影响主会话 |
 | `/stop` | 中止当前任务，并跳过队列中剩余消息 |
 | `/status` | 查看连接、队列、模型与上下文占用 |
 | `/compact` | 压缩当前会话上下文 |
 | `/thinking` | 查看思考档位，或切换：`/thinking off|minimal|low|medium|high|xhigh|max` |
 | `/model` | 查看当前模型，或模糊匹配切换：`/model <模型ID或名称>` |
+| `/bind` | （群聊）把当前群绑定到 Pi，创建独立会话；仅 Owner |
+| `/allow` | （仅 Owner）授权成员：`/allow @成员`；无参数时列出授权列表 |
+| `/deny` | （仅 Owner）移除授权：`/deny @成员` |
+| `/allowlist` | （仅 Owner）查看当前授权成员 |
 
-在飞书私聊中也可直接说“帮我拉个 XX 群”或“创建飞书群 XX”。机器人会创建群聊、邀请已绑定的 Owner 并发送欢迎消息；之后 Owner 在新群里 @机器人即可协作。该群首次收到消息时会创建一个独立 Pi session 并绑定到群，之后该群消息都会自动切回这个 session。已创建群聊的授权列表和 session 绑定会保存在本地凭据文件中，Pi 重启后仍可继续使用。
+在飞书私聊中也可直接说“帮我拉个 XX 群”或“创建飞书群 XX”。机器人会创建群聊、邀请已绑定的 Owner 并发送欢迎消息；建群后会私聊 Owner 做一次权限体检（含免 @ 权限申请链接）。已创建群聊和 session 绑定保存在本地凭据文件中，Pi 重启后仍可继续使用。
+
+### 群聊使用
+
+- **绑定已有群**：把机器人加进现有项目群后，Owner 在群里发送 `/bind` 即可绑定；之后该群获得独立 Pi session，与其他群和主对话互不串上下文。机器人被拉进新群时也会私聊 Owner 提醒绑定。
+- **触发方式**：默认在群里 `@机器人 你的问题`。飞书只向 bot 推送 @bot 的群消息；普通消息直接触发需要敏感权限 `im:message.group_msg`。
+- **授权成员**：默认只有 Owner 能使用。Owner 私聊发送 `/allow @张三` 后，张三即可在私聊和已绑定群里与机器人协作；`/deny @张三` 撤销。
+- **分寸感**：未绑定的群里被 @ 时回复绑定引导；非授权成员被 @ 时回复一次“未授权”；其余群内消息完全静默，不会刷屏。
+- **说话人上下文**：群消息发给 Pi 前会加上 `[飞书群聊] 说话人：` 前缀，@ 其他人会被改写成 `@名字`，模型知道在和谁对话。
+
+已知限制：Pi 是单会话进程，多个聊天的任务仍全局串行（排队提示会如实显示位数）；远程命令作用于最近活跃的会话，`/model`、`/thinking`、`/compact` 建议在对应聊天的上一条消息之后紧接着发送。
 
 未知命令会返回提示，不会发给 Pi。`/model` 的候选来自本地 Pi 的 scoped models（未配置时为全部已授权模型）；`/model` 无参数时展示当前模型。注意：任何以 `/` 开头的消息都会先被当作命令解析，想发给 Pi 的提问请勿以 `/` 开头。
 
@@ -175,9 +192,19 @@ pi -e D:\ai_study\pi-feishu
 
 确认已申请并发布表情回复相关权限。该权限缺失时扩展自动降级：消息照常收发，只是原消息上不会出现“思考中”表情。
 
+### 群里 @机器人 没反应
+
+按顺序排查：
+
+1. 群聊接收权限：确认已申请并发布 `im:message.group_at_msg:readonly`（缺了这个飞书不会推送任何群消息事件）。
+2. 应用版本：权限变更后需在权限管理页发布新版本才生效。
+3. 群是否绑定：只有扩展创建的群和 `/bind` 绑定过的群会处理消息。在被 @ 而无响应的群里，让 Owner 发送 `/bind`；如果连 @ 后的引导都没出现，通常是第 1、2 步的问题。
+4. 被 @ 的是否是机器人本身（@ 错了人不会触发）。
+5. 用 `/feishu status` 查看缺失 scope 的自检结果。
+
 ### 群里必须 @ 才有响应
 
-飞书默认只向 Bot 推送群内 @bot 消息。若希望扩展创建的项目群里普通消息也触发，需要额外申请并发布敏感权限 `im:message.group_msg`。本扩展已关闭 SDK 侧的强制 @ 过滤；权限生效后，已授权项目群内普通消息会直接进入 Pi。
+飞书默认只向 Bot 推送群内 @bot 消息。若希望绑定群内普通消息也触发，需要额外申请并发布敏感权限 `im:message.group_msg`。本扩展已关闭 SDK 侧的强制 @ 过滤；权限生效后，已绑定群内普通消息会直接进入 Pi。
 
 ### 远程 `/new` 提示暂不可用
 
@@ -189,7 +216,7 @@ pi -e D:\ai_study\pi-feishu
 
 ### 重复消息
 
-飞书事件可能重投。扩展在当前进程内缓存最近 1000 个 `message_id`，重复事件不会再次驱动 Pi。重启 Pi 后缓存会清空。
+飞书事件可能重投。扩展按 `message_id` 去重，并把受理记录落盘到 `~/.pi/agent/feishu/processed-messages.json`（48 小时滚动窗口、上限 5000 条），Pi 重启后飞书重推的旧消息也不会再次驱动 Pi。
 
 ## 开发
 
@@ -199,7 +226,7 @@ npm test
 npm run build
 ```
 
-测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、排队提示改位与撤回、❌ 取消、`/stop` 按条跳过、去重、已读表情回执、远程命令快速通道、思考档位与模型切换、Pi 增量文本、工具状态、流式卡片收尾、降级、错误脱敏和清理行为。
+测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、排队提示改位与撤回、❌ 取消、`/stop` 按条跳过、去重（含落盘恢复）、已读表情回执、远程命令快速通道、群绑定（`/bind`）与未托管群引导、allowlist 授权与撤销、群聊说话人上下文注入、mention 元数据透传、botAdded 引导、思考档位与模型切换、Pi 增量文本、工具状态、流式卡片收尾、降级、错误脱敏和清理行为。
 
 ## 许可证
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@hwj123weijian/pi-feishu",
-	"version": "0.8.0",
-	"description": "Minimal Feishu private-chat bridge for Pi",
+	"version": "0.10.0",
+	"description": "Feishu private-chat and managed-group bridge for Pi",
 	"type": "module",
 	"license": "MIT",
 	"publishConfig": {

package/src/contracts.ts

@@ -5,6 +5,10 @@ export interface FeishuCredentials {
 	managedGroupIds?: string[];
 	/** Per managed group Pi session file. Missing value is backfilled on the group's first message. */
 	groupSessions?: Record<string, string>;
+	/** Open IDs allowed to drive the bot besides the Owner, e.g. teammates in a managed group. */
+	allowlist?: string[];
+	/** Display names for allowlisted open IDs, captured from @mentions when authorizing. */
+	allowlistNames?: Record<string, string>;
 }
 
 export interface CredentialStore {
@@ -13,6 +17,13 @@ export interface CredentialStore {
 	clear(): Promise<void>;
 }
 
+export interface FeishuMentionInfo {
+	key: string;
+	openId?: string;
+	name?: string;
+	isBot?: boolean;
+}
+
 export interface FeishuIncomingMessage {
 	messageId: string;
 	chatId: string;
@@ -20,10 +31,21 @@ export interface FeishuIncomingMessage {
 	senderOpenId: string;
 	contentType: string;
 	text: string;
+	/** Sender display name when the platform provides one. */
+	senderName?: string;
+	/** True when the message @-mentions this bot (group messages only). */
+	mentionedBot?: boolean;
+	/** All @mentions carried by the message, bot included. */
+	mentions?: FeishuMentionInfo[];
 }
 
 export type FeishuMessageHandler = (message: FeishuIncomingMessage) => Promise<void> | void;
 
+export interface FeishuBotAddedEvent {
+	chatId: string;
+	operatorOpenId: string;
+}
+
 export interface FeishuReactionEvent {
 	messageId: string;
 	operatorOpenId: string;
@@ -41,7 +63,8 @@ export interface FeishuReplySnapshot {
 export interface FeishuReply {
 	update(snapshot: FeishuReplySnapshot): void;
 	complete(snapshot: FeishuReplySnapshot): Promise<void>;
-	fail(): Promise<void>;
+	/** Finalizes as failed; the sanitized reason is shown to the user when provided. */
+	fail(reason?: string): Promise<void>;
 	cancel(): Promise<void>;
 }
 
@@ -62,6 +85,10 @@ export interface FeishuGateway {
 	recallMessage(messageId: string): Promise<void>;
 	/** Subscribes to emoji reactions on messages visible to the bot. */
 	onReaction(handler: FeishuReactionHandler): () => void;
+	/** Subscribes to "bot added to chat" events. Optional: older gateways may not expose it. */
+	onBotAdded?(handler: (event: FeishuBotAddedEvent) => void): () => void;
+	/** Fetches basic chat metadata (e.g. group name) for guidance messages. Optional. */
+	getChatInfo?(chatId: string): Promise<{ name?: string } | undefined>;
 }
 
 export interface FeishuStatus {
@@ -97,6 +124,11 @@ export interface PiRuntime {
 	compact(): void;
 	/** Returns false when the runtime is unavailable or the switch was cancelled. */
 	newSession(): Promise<boolean>;
+	/**
+	 * Creates a new session for the chat-bound session of the given Feishu chat
+	 * and re-points the binding at it. Returns false when unavailable/cancelled.
+	 */
+	newChatSession?(chatId: string): Promise<boolean>;
 	/** Returns false when the requested thinking level does not exist. */
 	setThinkingLevel(level: string): Promise<boolean>;
 	/** Models the user can currently switch to. */