@hwj123weijian/pi-feishu 0.10.0 → 0.10.2

package/package.json

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

package/src/extension.ts

@@ -35,8 +35,13 @@ interface SharedFeishuState {
 	mainSessionFile: string | undefined;
 	/** Pi 进程当前所在的会话文件，随每个事件刷新。 */
 	currentSessionFile: string | undefined;
-	/** 群绑定相关 switch/newSession 进行中的标记：期间出现的会话文件不得记为主会话。 */
-	bindingGroupChat: boolean;
+	/**
+	 * 本扩展发起的 switch/newSession 进行中的标记：
+	 * - 期间出现的会话文件不得记为主会话；
+	 * - Pi 对旧会话发出的 session_shutdown 是我们自己引起的，
+	 *   不能据此取消正在等待的飞书轮次（否则群消息必然失败）。
+	 */
+	switchingSession: boolean;
 }
 
 const SHARED_STATE_KEY = "__piFeishuSharedState__";
@@ -58,7 +63,7 @@ function getSharedState(): SharedFeishuState {
 		sendCurrentMessage: undefined,
 		mainSessionFile: undefined,
 		currentSessionFile: undefined,
-		bindingGroupChat: false,
+		switchingSession: false,
 		controller: undefined as unknown as FeishuController,
 	};
 	const proxyAgent: AgentBridge = {
@@ -85,7 +90,7 @@ function getSharedState(): SharedFeishuState {
 		newChatSession: async (chatId) => {
 			const context = state.latestCommandContext;
 			if (!context) return false;
-			state.bindingGroupChat = true;
+			state.switchingSession = true;
 			try {
 				const result = await context.newSession({
 					withSession: async (nextContext) => {
@@ -96,7 +101,7 @@ function getSharedState(): SharedFeishuState {
 				});
 				return !result.cancelled;
 			} finally {
-				state.bindingGroupChat = false;
+				state.switchingSession = false;
 			}
 		},
 		setThinkingLevel: (level) => state.current?.runtime.setThinkingLevel(level) ?? Promise.resolve(false),
@@ -124,7 +129,7 @@ function observeSessionFile(state: SharedFeishuState, context: ExtensionContext)
 	const file = tryGetSessionFile(context);
 	if (!file) return;
 	state.currentSessionFile = file;
-	if (state.bindingGroupChat) return;
+	if (state.switchingSession) return;
 	if (state.controller.isGroupSessionFile(file)) return;
 	state.mainSessionFile = file;
 }
@@ -157,20 +162,25 @@ async function sendToMainSession(state: SharedFeishuState, prompt: string): Prom
 		// 主会话与当前会话不一致却没有命令上下文：直发会串进群会话，给出可操作的错误更安全。
 		throw new Error("Pi 会话控制尚未就绪，请先在本地执行一次 /feishu status。");
 	}
-	const result = await context.switchSession(main, {
-		withSession: async (nextContext) => {
-			state.latestCommandContext = nextContext;
-			await nextContext.sendUserMessage(prompt);
-		},
-	});
-	if (result.cancelled) throw new Error("切回主 Pi 会话已取消。");
+	state.switchingSession = true;
+	try {
+		const result = await context.switchSession(main, {
+			withSession: async (nextContext) => {
+				state.latestCommandContext = nextContext;
+				await nextContext.sendUserMessage(prompt);
+			},
+		});
+		if (result.cancelled) throw new Error("切回主 Pi 会话已取消。");
+	} finally {
+		state.switchingSession = false;
+	}
 }
 
 async function sendToChatSession(state: SharedFeishuState, chatId: string, prompt: string): Promise<void> {
 	const context = state.latestCommandContext;
 	if (!context) throw new Error("Pi 会话控制尚未就绪，请先在本地执行一次 /feishu status。");
 
-	state.bindingGroupChat = true;
+	state.switchingSession = true;
 	try {
 		const sessionFile = state.controller.getChatSessionFile(chatId);
 		if (sessionFile) {
@@ -197,7 +207,7 @@ async function sendToChatSession(state: SharedFeishuState, chatId: string, promp
 		});
 		if (result.cancelled) throw new Error("创建飞书群专属 Pi 会话已取消。");
 	} finally {
-		state.bindingGroupChat = false;
+		state.switchingSession = false;
 	}
 }
 
@@ -489,6 +499,9 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 	});
 	pi.on("session_shutdown", () => {
 		// 长连接归全局 controller 保管，本地 /new 切换会话后自动延续。
+		// 本扩展为群/私聊路由发起的 switch/newSession 会让 Pi 对旧会话发 shutdown；
+		// 那不是真正的会话关闭，此刻轮次刚要开始，绝不能取消，否则回复永远传不回飞书。
+		if (state.switchingSession) return;
 		state.activeBridge?.cancel("Pi 会话已关闭。");
 	});
 

package/src/scopes.ts

@@ -165,21 +165,50 @@ export function buildBotAddedGuidance(params: {
 	return lines.join("\n");
 }
 
+/** 每个 scope 的用途说明，用于欢迎语中的权限清单。 */
+export const SCOPE_DESCRIPTIONS: Record<string, string> = {
+	"im:message.p2p_msg:readonly": "接收私聊消息",
+	"im:message.group_at_msg:readonly": "接收群内 @机器人 的消息",
+	"im:message:send_as_bot": "以机器人身份发送/回复消息",
+	"im:message:update": "持续更新交互卡片（流式回复）",
+	"im:message.reactions:read": "读取表情回复（❌ 取消排队消息）",
+	"im:message.reactions:write_only": "添加表情回复（思考中已读回执）",
+	"im:chat": "创建群聊并邀请 Owner",
+	"im:chat:read": "读取群信息（群名等）",
+	"application:application:self_manage": "读取应用已开通权限，自动完成权限体检",
+	[SENSITIVE_GROUP_MSG_SCOPE]: "群内免 @ 直接响应所有消息（敏感权限，需人工审核）",
+};
+
+function renderScopeInventory(): string[] {
+	return [...REQUIRED_APP_SCOPES, SENSITIVE_GROUP_MSG_SCOPE].map((scope) => {
+		const description = SCOPE_DESCRIPTIONS[scope];
+		return description ? `- \`${scope}\`（${description}）` : `- \`${scope}\``;
+	});
+}
+
 /**
  * 权限体检段落：grantedScopes 未知时返回 null（不猜）；
- * 全部就绪时返回 ✅ 段落，否则返回缺失清单 + 一键申请链接。
+ * 全部就绪时返回 ✅ 段落 + 完整依赖清单（便于逐项核对），
+ * 否则返回缺失清单 + 一键申请链接。
  */
 export function buildScopeHealthSection(appId: string, grantedScopes?: readonly string[]): string | null {
 	if (!grantedScopes) return null;
 	const missing = missingScopes(grantedScopes, REQUIRED_APP_SCOPES);
 	const hasGroupMsg = hasScope(grantedScopes, SENSITIVE_GROUP_MSG_SCOPE);
 	if (missing.length === 0 && hasGroupMsg) {
-		return "✅ 应用权限配置完整，所有功能均可正常使用。";
+		return ["✅ 应用权限配置完整，所有功能均可正常使用。", "", "本 Bot 依赖以下权限（均已开通）：", ...renderScopeInventory()].join(
+			"\n",
+		);
 	}
 	const lines = ["⚠️ 以下应用权限尚未开通，对应功能会受限："];
 	if (missing.length > 0) {
 		lines.push(`📋 缺失 ${missing.length} 项基础权限，点击一键申请：`);
 		lines.push(`👉 ${buildScopeApplyUrl({ appId, scopes: missing })}`);
+		lines.push("   缺失明细：");
+		for (const scope of missing) {
+			const description = SCOPE_DESCRIPTIONS[scope];
+			lines.push(`   - \`${scope}\`${description ? `（${description}）` : ""}`);
+		}
 	}
 	if (!hasGroupMsg) {
 		lines.push("💬 「免 @ 响应」权限未开：群内需 @机器人 才能触发，点击开通：");