@hwj123weijian/pi-feishu 0.6.0 → 0.8.0

package/README.md

@@ -10,7 +10,7 @@
 - 首次启动生成一次性绑定码，只允许一个 Owner
 - 收到消息后立刻在原消息上添加“思考中”表情作为已读回执，回复送达后自动移除
 - 以 `/` 开头的消息走远程命令快速通道，不排队、不进入 LLM 上下文
-- 所有消息进入当前 Pi 会话，不创建额外 Agent 或会话
+- 私聊消息进入当前 Pi 会话；扩展创建的每个群聊会在首次收到群消息时创建并绑定一个独立 Pi session，后续该群消息自动切回自己的 session，避免群之间和主对话串上下文
 - 消息需要排队时发送“排队中（第 N 位）”提示，轮到处理时自动撤回；队列变化时提示自动改写为新位数
 - Owner 在排队中的消息上点 ❌（`CrossMark`）表情即可取消该消息
 - Assistant 文本通过 Pi 的 `message_update` 增量渲染到同一张飞书卡片
@@ -22,7 +22,7 @@
 - 长连接由跨会话的全局控制器保管：本地 `/new`、远程 `/new` 等会话切换不会断开；`/feishu stop`、`/feishu logout` 或 Pi 进程退出时释放
 - 凭据优先从环境变量读取，也可保存到本地凭据文件
 
-支持 Owner 在飞书私聊中请求创建群聊；扩展会把 Owner 拉入新群、发送欢迎消息，并允许 Owner 在该扩展创建的群里 @机器人继续协作。其他群聊不会被处理。图片、文件、卡片、语音、多用户、多会话、进程级沙箱或远程命令权限管理仍不支持。Pi 本身仍拥有当前本地进程的权限。
+支持 Owner 在飞书私聊中请求创建群聊；扩展会把 Owner 拉入新群、发送欢迎消息，并允许 Owner 在该扩展创建的群里 @机器人继续协作。建群后会私聊 Owner 做一次权限体检，提示缺失的基础 scope、事件订阅页和 `im:message.group_msg` 免 @ 权限申请链接。每个扩展创建的群聊会绑定自己的 Pi session，群聊之间、群聊与本地主对话之间不会共享上下文。其他群聊不会被处理。图片、文件、卡片、语音、多用户、进程级沙箱或远程命令权限管理仍不支持。Pi 本身仍拥有当前本地进程的权限。
 
 ## 环境要求
 
@@ -40,12 +40,13 @@
    - `im:message:send_as_bot`：以机器人身份回复
    - `im:chat`：创建群聊并邀请 Owner
    - `im:message:update`：持续更新机器人发出的交互卡片
+   - `application:application:self_manage`：启动/建群后读取应用已授权 scope，用于自动提示缺失权限
    - 表情回复相关权限：在原消息上添加/移除“思考中”已读回执
 3. 在“事件与回调”中选择“使用长连接接收事件”。
 4. 添加事件 `im.message.receive_v1`。
 5. 创建并发布一个应用版本，使权限和事件订阅在企业内生效。
 
-这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。若未授予表情回复权限，扩展同样可工作，只是原消息上不会出现已读表情。
+这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。若未授予表情回复权限，扩展同样可工作，只是原消息上不会出现已读表情。若希望已创建项目群里无需 @ 机器人即可触发，需要额外申请敏感权限 `im:message.group_msg`；未开通时请在群里使用 `@机器人 你的问题`。
 
 ## 安装
 
@@ -93,7 +94,7 @@ pi -e D:\ai_study\pi-feishu
 /feishu start
 ```
 
-`start` 会在本地 Pi 中显示六位一次性绑定码。使用计划作为 Owner 的飞书账号私聊机器人：
+`start` 会在本地 Pi 中显示六位一次性绑定码。若已配置凭据但启动 Pi 后尚未连接，扩展会在会话开始时提示执行 `/feishu start`；如需 Pi 启动后自动连接，可设置 `PI_FEISHU_AUTO_START=1`（或 `FEISHU_AUTO_START=1`）。使用计划作为 Owner 的飞书账号私聊机器人：
 
 ```text
 /bind 123456
@@ -142,7 +143,7 @@ pi -e D:\ai_study\pi-feishu
 | `/thinking` | 查看思考档位，或切换：`/thinking off|minimal|low|medium|high|xhigh|max` |
 | `/model` | 查看当前模型，或模糊匹配切换：`/model <模型ID或名称>` |
 
-在飞书私聊中也可直接说“帮我拉个 XX 群”或“创建飞书群 XX”。机器人会创建群聊、邀请已绑定的 Owner 并发送欢迎消息；之后 Owner 在新群里 @机器人即可继续使用当前 Pi 会话。已创建群聊的授权列表会保存在本地凭据文件中，Pi 重启后仍可继续使用。
+在飞书私聊中也可直接说“帮我拉个 XX 群”或“创建飞书群 XX”。机器人会创建群聊、邀请已绑定的 Owner 并发送欢迎消息；之后 Owner 在新群里 @机器人即可协作。该群首次收到消息时会创建一个独立 Pi session 并绑定到群，之后该群消息都会自动切回这个 session。已创建群聊的授权列表和 session 绑定会保存在本地凭据文件中，Pi 重启后仍可继续使用。
 
 未知命令会返回提示，不会发给 Pi。`/model` 的候选来自本地 Pi 的 scoped models（未配置时为全部已授权模型）；`/model` 无参数时展示当前模型。注意：任何以 `/` 开头的消息都会先被当作命令解析，想发给 Pi 的提问请勿以 `/` 开头。
 
@@ -174,6 +175,10 @@ pi -e D:\ai_study\pi-feishu
 
 确认已申请并发布表情回复相关权限。该权限缺失时扩展自动降级：消息照常收发，只是原消息上不会出现“思考中”表情。
 
+### 群里必须 @ 才有响应
+
+飞书默认只向 Bot 推送群内 @bot 消息。若希望扩展创建的项目群里普通消息也触发，需要额外申请并发布敏感权限 `im:message.group_msg`。本扩展已关闭 SDK 侧的强制 @ 过滤；权限生效后，已授权项目群内普通消息会直接进入 Pi。
+
 ### 远程 `/new` 提示暂不可用
 
 远程会话切换依赖本地 Pi 提供的命令上下文。先在本地 Pi 执行任意 `/feishu` 子命令（例如 `/feishu status`），再从飞书发送 `/new`。切换完成后长连接自动延续，无需重新执行 `/feishu start`。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hwj123weijian/pi-feishu",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "Minimal Feishu private-chat bridge for Pi",
 	"type": "module",
 	"license": "MIT",

package/src/contracts.ts

@@ -3,6 +3,8 @@ export interface FeishuCredentials {
 	appSecret: string;
 	ownerOpenId?: string;
 	managedGroupIds?: string[];
+	/** Per managed group Pi session file. Missing value is backfilled on the group's first message. */
+	groupSessions?: Record<string, string>;
 }
 
 export interface CredentialStore {
@@ -47,6 +49,8 @@ export interface FeishuGateway {
 	connect(handler: FeishuMessageHandler): Promise<void>;
 	disconnect(): Promise<void>;
 	createGroupChat(name: string, ownerOpenId: string): Promise<string>;
+	/** Best-effort application scope audit. Undefined grantedScopes means the app cannot read its scope list yet. */
+	probeGrantedScopes?(): Promise<{ grantedScopes?: string[] }>;
 	/** Sends text and resolves with the sent Feishu message id (for later recall). */
 	sendText(chatId: string, text: string, replyTo?: string): Promise<string | undefined>;
 	beginReply(chatId: string, replyTo: string): Promise<FeishuReply>;
@@ -109,8 +113,13 @@ export interface AgentProgressObserver {
 	onActivity?: (activity: AgentActivity) => void;
 }
 
+export interface AgentRunOptions {
+	/** Route this turn through the Pi session bound to the Feishu chat. */
+	chatId?: string;
+}
+
 export interface AgentBridge {
-	run(text: string, observer?: AgentProgressObserver): Promise<string>;
+	run(text: string, observer?: AgentProgressObserver, options?: AgentRunOptions): Promise<string>;
 	cancel(reason?: string): void;
 }
 

package/src/controller.ts

@@ -17,6 +17,7 @@ import { MessageDeduplicator } from "./message-deduplicator.js";
 import { SerialMessageQueue } from "./message-queue.js";
 import { OwnerBinding } from "./owner-binding.js";
 import { executeRemoteCommand, parseRemoteCommand } from "./remote-commands.js";
+import { buildGroupPermissionReminder } from "./scopes.js";
 
 // 与 easycodeclient 的飞书集成一致：THINKING 表情兼作"已读 + 处理中"回执。
 const READ_REACTION_EMOJI = "THINKING";
@@ -91,6 +92,7 @@ export class FeishuController {
 						...credentials,
 						...(existing.ownerOpenId ? { ownerOpenId: existing.ownerOpenId } : {}),
 						...(existing.managedGroupIds ? { managedGroupIds: existing.managedGroupIds } : {}),
+						...(existing.groupSessions ? { groupSessions: existing.groupSessions } : {}),
 					}
 				: credentials;
 		await this.store.save(next);
@@ -147,11 +149,49 @@ export class FeishuController {
 		}
 		await gateway.sendText(
 			chatId,
-			`👋 群聊「${name}」已创建，当前绑定的 Pi 飞书机器人已就绪。直接在群内 @机器人即可开始协作。`,
+			`👋 群聊「${name}」已创建，当前绑定的 Pi 飞书机器人已就绪。直接在群内 @机器人即可开始协作。若群内普通消息没有响应，请先 @ 机器人；开通免 @ 权限后可直接发消息。`,
 		);
+		await this.sendGroupPermissionReminder(gateway, ownerOpenId, name);
 		return chatId;
 	}
 
+	getChatSessionFile(chatId: string): string | undefined {
+		return this.credentials?.groupSessions?.[chatId];
+	}
+
+	async setChatSessionFile(chatId: string, sessionFile: string): Promise<void> {
+		const credentials = this.credentials;
+		if (!credentials) return;
+		const updated = {
+			...credentials,
+			groupSessions: { ...(credentials.groupSessions ?? {}), [chatId]: sessionFile },
+		};
+		await this.store.save(updated);
+		this.credentials = updated;
+	}
+
+	private async sendGroupPermissionReminder(
+		gateway: FeishuGateway,
+		ownerOpenId: string,
+		groupName: string,
+	): Promise<void> {
+		const credentials = this.credentials;
+		if (!credentials) return;
+		let grantedScopes: string[] | undefined;
+		try {
+			grantedScopes = (await gateway.probeGrantedScopes?.())?.grantedScopes;
+		} catch {
+			grantedScopes = undefined;
+		}
+		const reminder = buildGroupPermissionReminder({
+			appId: credentials.appId,
+			groupName,
+			...(grantedScopes ? { grantedScopes } : {}),
+		});
+		if (!reminder) return;
+		await gateway.sendText(ownerOpenId, reminder).catch(() => undefined);
+	}
+
 	async stop(): Promise<boolean> {
 		const gateway = this.gateway;
 		if (!gateway) return false;
@@ -173,6 +213,19 @@ export class FeishuController {
 		await this.store.clear();
 	}
 
+	/** 读取应用已开通 scope 列表（用于权限健康度检查）。未连接或 probe 失败时返回空对象。 */
+	async probeScopes(): Promise<{ grantedScopes?: string[] }> {
+		try {
+			return (await this.gateway?.probeGrantedScopes?.()) ?? {};
+		} catch {
+			return {};
+		}
+	}
+
+	get appId(): string | undefined {
+		return this.credentials?.appId;
+	}
+
 	async status(environment: Environment): Promise<FeishuStatus> {
 		const stored = await this.store.load();
 		const resolved = resolveRuntimeCredentials(environment, stored);
@@ -355,18 +408,22 @@ export class FeishuController {
 		if (reply) this.activeReplies.add(reply);
 		let latestText = "";
 		try {
-			const response = await this.agent.run(text, {
-				onText: (latest) => {
-					latestText = latest;
-					reply?.update({ text: latest, status: "正在生成回复" });
-				},
-				onActivity: (activity) => {
-					reply?.update({
-						text: latestText,
-						status: activity.kind === "tool" ? "正在执行工具" : "正在思考",
-					});
+			const response = await this.agent.run(
+				text,
+				{
+					onText: (latest) => {
+						latestText = latest;
+						reply?.update({ text: latest, status: "正在生成回复" });
+					},
+					onActivity: (activity) => {
+						reply?.update({
+							text: latestText,
+							status: activity.kind === "tool" ? "正在执行工具" : "正在思考",
+						});
+					},
 				},
-			});
+				message.chatType === "group" ? { chatId: message.chatId } : undefined,
+			);
 			if (this.gateway === gateway) {
 				if (reply) {
 					await reply.complete({ text: response, status: "已完成" });

package/src/credentials.ts

@@ -67,6 +67,7 @@ export function resolveRuntimeCredentials(
 			appSecret,
 			...(matching?.ownerOpenId ? { ownerOpenId: matching.ownerOpenId } : {}),
 			...(matching?.managedGroupIds ? { managedGroupIds: matching.managedGroupIds } : {}),
+			...(matching?.groupSessions ? { groupSessions: matching.groupSessions } : {}),
 		};
 	}
 	return stored;
@@ -134,6 +135,7 @@ export class FileCredentialStore implements CredentialStore {
 			...(Array.isArray(value.managedGroupIds)
 				? { managedGroupIds: value.managedGroupIds.filter((id): id is string => typeof id === "string") }
 				: {}),
+			...(isStringRecord(value.groupSessions) ? { groupSessions: value.groupSessions } : {}),
 		};
 	}
 
@@ -170,10 +172,16 @@ function isCredentialRecord(value: unknown): value is FeishuCredentials {
 		typeof record.appId === "string" &&
 		typeof record.appSecret === "string" &&
 		(record.ownerOpenId === undefined || typeof record.ownerOpenId === "string") &&
-		(record.managedGroupIds === undefined || Array.isArray(record.managedGroupIds))
+		(record.managedGroupIds === undefined || Array.isArray(record.managedGroupIds)) &&
+		(record.groupSessions === undefined || isStringRecord(record.groupSessions))
 	);
 }
 
+function isStringRecord(value: unknown): value is Record<string, string> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	return Object.values(value).every((entry) => typeof entry === "string");
+}
+
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
 	return error instanceof Error && "code" in error;
 }

package/src/extension.ts

@@ -6,19 +6,30 @@ import { CredentialError, FileCredentialStore } from "./credentials.js";
 import { SdkFeishuGateway, validateSdkCredentials } from "./gateway.js";
 import { PiAgentBridge } from "./pi-agent-bridge.js";
 import { THINKING_LEVELS } from "./remote-commands.js";
+import {
+	buildEventSubUrl,
+	buildPermissionPageUrl,
+	buildScopeApplyUrl,
+	hasScope,
+	missingScopes,
+	REQUIRED_APP_SCOPES,
+	SENSITIVE_GROUP_MSG_SCOPE,
+} from "./scopes.js";
 
 type FeishuCommandName = "help" | "setup" | "start" | "stop" | "status" | "logout";
 type PiModel = NonNullable<ExtensionContext["model"]>;
 type PiThinkingLevel = NonNullable<ExtensionContext["thinkingLevel"]>;
 
 interface SessionLink {
-	bridge: PiAgentBridge;
 	runtime: PiRuntime;
 }
 
 interface SharedFeishuState {
 	controller: FeishuController;
 	current: SessionLink | undefined;
+	activeBridge: PiAgentBridge | undefined;
+	latestCommandContext: ExtensionCommandContext | undefined;
+	sendCurrentMessage: ((text: string) => void) | undefined;
 }
 
 const SHARED_STATE_KEY = "__piFeishuSharedState__";
@@ -33,14 +44,30 @@ function getSharedState(): SharedFeishuState {
 	const existing = host[SHARED_STATE_KEY];
 	if (existing) return existing;
 
-	const state: SharedFeishuState = { current: undefined, controller: undefined as unknown as FeishuController };
+	const state: SharedFeishuState = {
+		current: undefined,
+		activeBridge: undefined,
+		latestCommandContext: undefined,
+		sendCurrentMessage: undefined,
+		controller: undefined as unknown as FeishuController,
+	};
 	const proxyAgent: AgentBridge = {
-		run: (text, observer) => {
-			const link = state.current;
-			if (!link) return Promise.reject(new Error("Pi 会话尚未就绪，请稍后再试。"));
-			return link.bridge.run(text, observer);
+		run: (text, observer, options) => {
+			const bridge = new PiAgentBridge(async (prompt) => {
+				if (options?.chatId) {
+					await sendToChatSession(state, options.chatId, prompt);
+					return;
+				}
+				if (!state.current) throw new Error("Pi 会话尚未就绪，请稍后再试。");
+				if (!state.sendCurrentMessage) throw new Error("Pi 会话尚未就绪，请稍后再试。");
+				state.sendCurrentMessage(prompt);
+			});
+			state.activeBridge = bridge;
+			return bridge.run(text, observer).finally(() => {
+				if (state.activeBridge === bridge) state.activeBridge = undefined;
+			});
 		},
-		cancel: (reason) => state.current?.bridge.cancel(reason),
+		cancel: (reason) => state.activeBridge?.cancel(reason),
 	};
 	const proxyRuntime: PiRuntime = {
 		isIdle: () => state.current?.runtime.isIdle() ?? true,
@@ -67,6 +94,35 @@ function getSharedState(): SharedFeishuState {
 	return state;
 }
 
+async function sendToChatSession(state: SharedFeishuState, chatId: string, prompt: string): Promise<void> {
+	const context = state.latestCommandContext;
+	if (!context) throw new Error("Pi 会话控制尚未就绪，请先在本地执行一次 /feishu status。");
+
+	const sessionFile = state.controller.getChatSessionFile(chatId);
+	if (sessionFile) {
+		const result = await context.switchSession(sessionFile, {
+			withSession: async (nextContext) => {
+				state.latestCommandContext = nextContext;
+				const currentFile = nextContext.sessionManager.getSessionFile();
+				if (currentFile && currentFile !== sessionFile) await state.controller.setChatSessionFile(chatId, currentFile);
+				await nextContext.sendUserMessage(prompt);
+			},
+		});
+		if (result.cancelled) throw new Error("切换到飞书群绑定的 Pi 会话已取消。");
+		return;
+	}
+
+	const result = await context.newSession({
+		withSession: async (nextContext) => {
+			state.latestCommandContext = nextContext;
+			const currentFile = nextContext.sessionManager.getSessionFile();
+			if (currentFile) await state.controller.setChatSessionFile(chatId, currentFile);
+			await nextContext.sendUserMessage(prompt);
+		},
+	});
+	if (result.cancelled) throw new Error("创建飞书群专属 Pi 会话已取消。");
+}
+
 export interface ParsedFeishuCommand {
 	name: FeishuCommandName;
 	args: string;
@@ -107,29 +163,158 @@ export function renderFeishuHelp(): string {
 	].join("\n");
 }
 
-export function renderFeishuStatus(status: FeishuStatus): string {
+/** 对齐 easycodeclient：start 成功后的仪表盘式提示。 */
+export function renderStartSuccess(status: FeishuStatus, bindingCode?: string): string {
+	const lines: string[] = ["🚀 飞书 Bot 已就绪！"];
+	if (status.appId) lines.push(`  App ID：${status.appId}`);
+	lines.push("  连接：WebSocket 长连接已建立");
+	if (bindingCode) {
+		lines.push(`  Owner：未绑定，一次性绑定码 ${bindingCode}`);
+		lines.push(`  请在飞书私聊 Bot 发送：/bind ${bindingCode}`);
+	} else if (status.ownerOpenId) {
+		lines.push(`  Owner：${status.ownerOpenId}`);
+	}
+	lines.push("", "  现在去飞书给 Bot 发消息试试 👋", "  输入 /feishu stop 停止");
+	return lines.join("\n");
+}
+
+/** 对齐 easycodeclient：缺少凭据时给出可操作的配置指引。 */
+export function renderMissingCredentials(): string {
+	return [
+		"⚠️ 未找到飞书凭证，请先配置：",
+		"  /feishu setup <appId> <appSecret>    # 验证并保存凭据",
+		"  或设置环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET 后执行 /feishu setup",
+	].join("\n");
+}
+
+/**
+ * 对齐 easycodeclient 的 appendPostSetupGuidance：setup 成功后的分步配置引导。
+ * grantedScopes 为 undefined 表示无法读取已开通列表（首次配置很常见），按全部缺失处理。
+ */
+export function renderPostSetupGuidance(appId: string, grantedScopes?: string[]): string {
+	const missing = grantedScopes ? missingScopes(grantedScopes, REQUIRED_APP_SCOPES) : [...REQUIRED_APP_SCOPES];
+	const lines: string[] = [
+		"",
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"🔧 一键完成下一步配置（强烈建议）",
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+	];
+
+	if (grantedScopes && missing.length === 0) {
+		lines.push("  ✅ 应用已开通全部必需 scope，无需额外申请。");
+	} else {
+		lines.push(
+			grantedScopes
+				? `  📋 第 1 步：一键申请缺失的 ${missing.length} 项权限（自动预选 scope）`
+				: "  📋 第 1 步：一键申请应用所需权限（自动预选 scope）",
+			`     👉 ${buildScopeApplyUrl({ appId, scopes: missing })}`,
+		);
+		if (missing.length > 0 && missing.length <= 12) {
+			lines.push("     需申请的 scope：");
+			for (const scope of missing) lines.push(`       - ${scope}`);
+		}
+	}
+
+	lines.push(
+		"",
+		"  📡 第 2 步：在事件订阅页勾选必要事件",
+		`     👉 ${buildEventSubUrl(appId)}`,
+		"     需订阅事件：",
+		"       - im.message.receive_v1（接收消息）",
+		"       - im.message.recalled_v1（用户撤回消息 → 排队消息同步撤回）",
+		"       - im.chat.member.bot.added_v1（被拉入群通知）",
+		"       - card.action.trigger（卡片按钮回调）",
+		"",
+		"  🔄 第 3 步：申请发布版本",
+		"     在权限管理页申请版本发布，让 scope 生效：",
+		`     👉 ${buildPermissionPageUrl(appId)}`,
+		"",
+	);
+
+	// 🔔 免 @ 敏感权限提示
+	if (!grantedScopes || !hasScope(grantedScopes, SENSITIVE_GROUP_MSG_SCOPE)) {
+		lines.push(
+			"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+			"💬 想让 Bot 在群里「免 @ 直接响应所有消息」？",
+			"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+			"  默认：群里只有 @bot 时才会收到事件（飞书平台层硬规则）。",
+			"  要免 @ 直接响应，必须额外申请「敏感权限」：",
+			`     👉 ${buildScopeApplyUrl({ appId, scopes: [SENSITIVE_GROUP_MSG_SCOPE] })}`,
+			`     权限：\`${SENSITIVE_GROUP_MSG_SCOPE}\` —— 「读取关联群聊内所有消息」`,
+			"  ⚠️ 这是飞书的敏感权限，需要人工审核（一般 1-3 天）。",
+			"  申请页「使用场景说明」可参考：用于 AI 编程助手在专属项目协作群中",
+			"  无需 @ 即可响应团队成员的编程请求和问题，提升协作效率。",
+			"",
+		);
+	}
+	lines.push("  💡 步骤 1-3 完成后，回到 Pi 执行 /feishu start 即可使用！");
+	return lines.join("\n");
+}
+
+/**
+ * 对齐 easycodeclient 的 start 后权限健康检查：probe 权限并追加修复指引。
+ * probe 失败不阻塞主流程，返回原文案。
+ */
+export async function appendScopeHealthHint(
+	appId: string,
+	dashboard: string,
+	grantedScopes?: string[],
+): Promise<string> {
+	if (!grantedScopes) return dashboard;
+	const missing = missingScopes(grantedScopes, REQUIRED_APP_SCOPES);
+	const hasGroupMsg = hasScope(grantedScopes, SENSITIVE_GROUP_MSG_SCOPE);
+	if (missing.length === 0 && hasGroupMsg) {
+		return `${dashboard}\n\n✅ 应用权限配置完整，所有功能均可正常使用。`;
+	}
+	const lines = ["", "⚠️ 以下应用权限尚未开通，对应功能会受限："];
+	if (missing.length > 0) {
+		lines.push(`📋 缺失 ${missing.length} 项基础权限，点击一键申请：`);
+		lines.push(`👉 ${buildScopeApplyUrl({ appId, scopes: missing })}`);
+	}
+	if (!hasGroupMsg) {
+		lines.push("💬 「免 @ 响应」权限未开：群内需 @机器人 才能触发，点击开通：");
+		lines.push(`👉 ${buildScopeApplyUrl({ appId, scopes: [SENSITIVE_GROUP_MSG_SCOPE] })}`);
+	}
+	lines.push("🔄 权限生效（需发布应用版本）：");
+	lines.push(`👉 ${buildPermissionPageUrl(appId)}`);
+	return `${dashboard}\n${lines.join("\n")}`;
+}
+
+export function renderFeishuStatus(status: FeishuStatus, scopeHealth?: string[]): string {
 	if (!status.configured) {
 		return [
-			"飞书状态",
-			"  配置：未配置",
-			`  连接：${status.running ? "已连接" : "未连接"}`,
+			"📊 飞书状态:",
+			"  配置：未配置，请运行 /feishu setup",
+			`  连接：${status.running ? "🟢 运行中" : "🔴 已停止"}`,
 			`  队列：${status.pendingMessages}`,
 		].join("\n");
 	}
-	return [
-		"飞书状态",
-		"  配置：已配置",
+	const lines = [
+		"📊 飞书状态:",
+		"  配置：✅ 已配置",
 		`  App ID：${status.appId ?? "未知"}`,
 		`  来源：${status.source === "environment" ? "环境变量" : "凭据文件"}`,
-		`  连接：${status.running ? "已连接" : "未连接"}`,
+		`  连接：${status.running ? "🟢 运行中" : "🔴 已停止"}`,
 		`  Owner：${status.ownerOpenId ?? "未绑定"}`,
 		`  队列：${status.pendingMessages}`,
-	].join("\n");
+	];
+	// ✨ Mini-doctor：scope 健康度自检（对齐 easycodeclient 的 /feishu status）。
+	if (scopeHealth) {
+		lines.push("");
+		if (scopeHealth.length === 0) {
+			lines.push("  ✅ 应用权限：已开通全部必需 scope");
+		} else {
+			lines.push(`  ⚠️ 应用权限：缺失 ${scopeHealth.length} 项必需 scope`);
+			for (const scope of scopeHealth) lines.push(`       - ${scope}`);
+		}
+	}
+	if (!status.running) lines.push("  运行 /feishu start 启动 Bot");
+	return lines.join("\n");
 }
 
 export default function feishuExtension(pi: ExtensionAPI): void {
 	const state = getSharedState();
-	const bridge = new PiAgentBridge((text) => pi.sendUserMessage(text));
+	state.sendCurrentMessage = (text) => pi.sendUserMessage(text);
 	let latestContext: ExtensionContext | undefined;
 	let latestCommandContext: ExtensionCommandContext | undefined;
 
@@ -138,7 +323,7 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 		abort: () => withRuntimeContext(() => latestContext?.abort()),
 		compact: () => withRuntimeContext(() => latestContext?.compact()),
 		newSession: async () => {
-			const context = latestCommandContext;
+			const context = latestCommandContext ?? state.latestCommandContext;
 			if (!context) return false;
 			try {
 				const result = await context.newSession();
@@ -181,37 +366,63 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 			return snapshot;
 		},
 	};
-	state.current = { bridge, runtime };
+	state.current = { runtime };
+
+	let startupNoticeShown = false;
+	const maybeNotifyFeishuStartup = async (context: ExtensionContext): Promise<void> => {
+		if (startupNoticeShown) return;
+		startupNoticeShown = true;
+		const status = await state.controller.status(process.env);
+		if (!status.configured || status.running) return;
+		if (shouldAutoStartFeishu(process.env)) {
+			const result = await state.controller.start(process.env);
+			const dashboard = renderStartSuccess(await state.controller.status(process.env), result.bindingCode);
+			context.ui.notify(
+				dashboard.replace("🚀 飞书 Bot 已就绪！", "🚀 飞书插件已自动启动，Bot 已就绪！"),
+				result.bindingCode ? "warning" : "info",
+			);
+			return;
+		}
+		context.ui.notify(
+			"飞书插件已加载，但长连接未启动。请执行 /feishu start；如需 Pi 启动后自动连接，可设置 PI_FEISHU_AUTO_START=1。",
+			"warning",
+		);
+	};
 
 	// 每个事件都会带来新的 ExtensionContext；持续刷新，保证远程命令拿到的能力不失效。
 	const trackContext = (_event: unknown, context: ExtensionContext): void => {
 		latestContext = context;
 	};
-	pi.on("session_start", trackContext);
+	pi.on("session_start", (event, context) => {
+		trackContext(event, context);
+		void maybeNotifyFeishuStartup(context).catch((error) => {
+			context.ui.notify(`飞书启动检查失败：${state.controller.sanitizeError(error)}`, "error");
+		});
+	});
 	pi.on("agent_start", trackContext);
 	pi.on("message_end", (event, context) => {
 		trackContext(event, context);
-		bridge.captureMessage(event.message);
+		state.activeBridge?.captureMessage(event.message);
 	});
 	pi.on("message_update", (event, context) => {
 		trackContext(event, context);
-		bridge.captureStreamingMessage(event.message);
+		state.activeBridge?.captureStreamingMessage(event.message);
 	});
 	pi.on("tool_execution_start", (event, context) => {
 		trackContext(event, context);
-		bridge.captureToolStart(event.toolName);
+		state.activeBridge?.captureToolStart(event.toolName);
 	});
 	pi.on("tool_execution_end", (event, context) => {
 		trackContext(event, context);
-		bridge.captureToolEnd();
+		state.activeBridge?.captureToolEnd();
 	});
 	pi.on("agent_settled", (event, context) => {
 		trackContext(event, context);
-		bridge.settle();
+		state.activeBridge?.settle();
 	});
 	pi.on("session_shutdown", () => {
-		// 只解绑本会话的桥：长连接归全局 controller 保管，本地 /new 切换会话后自动延续。
-		bridge.cancel("Pi 会话已关闭。");
+		// 长连接归全局 controller 保管，本地 /new 切换会话后自动延续。
+		state.activeBridge?.cancel("Pi 会话已关闭。");
 	});
 
 	pi.registerTool({
@@ -247,6 +458,7 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 		description: "配置和管理飞书私聊连接",
 		handler: async (args, context) => {
 			latestCommandContext = context;
+			state.latestCommandContext = context;
 			try {
 				await handleFeishuCommand(parseFeishuCommand(args), state.controller, context);
 			} catch (error) {
@@ -289,6 +501,11 @@ function toModelInfo(model: PiModel): PiModelInfo {
 	return { id: model.id, name: model.name || model.id, provider: String(model.provider) };
 }
 
+function shouldAutoStartFeishu(environment: NodeJS.ProcessEnv): boolean {
+	const value = environment.PI_FEISHU_AUTO_START ?? environment.FEISHU_AUTO_START;
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+
 function isThinkingLevel(value: string): value is PiThinkingLevel {
 	return (THINKING_LEVELS as readonly string[]).includes(value);
 }
@@ -319,31 +536,53 @@ async function handleFeishuCommand(
 				throw new CredentialError("请先执行 /feishu stop，再修改飞书凭据。");
 			}
 			const credentials = await controller.setup(command.args, process.env);
-			context.ui.notify(`飞书凭据验证成功并已保存：${credentials.appId}`, "info");
+			context.ui.notify(`✅ 飞书凭据验证成功并已保存：${credentials.appId}`, "info");
+			// 对齐 easycodeclient：setup 成功后输出分步配置引导（一键申请权限/事件订阅/发布版本）。
+			context.ui.notify(renderPostSetupGuidance(credentials.appId), "info");
+			// 并自动拉起长连接，省去手动 /feishu start。
+			await handleFeishuCommand({ name: "start", args: "" }, controller, context);
 			return;
 		}
 		case "start": {
+			// 对齐 easycodeclient：未配置凭据时给出可操作的配置指引，而非报错。
+			const precheck = await controller.status(process.env);
+			if (!precheck.configured) {
+				context.ui.notify(renderMissingCredentials(), "warning");
+				return;
+			}
 			const result = await controller.start(process.env);
 			if (result.alreadyRunning) {
-				context.ui.notify("飞书长连接已经在运行。", "info");
+				context.ui.notify("⚠️ 飞书 Bot 已在运行中。输入 /feishu stop 停止后再启动。", "info");
 				return;
 			}
-			if (result.bindingCode) {
-				context.ui.notify(
-					`飞书长连接已启动。\n一次性绑定码：${result.bindingCode}\n请在飞书私聊 Bot 发送：/bind ${result.bindingCode}`,
-					"warning",
-				);
-			} else {
-				context.ui.notify("飞书长连接已启动，Owner 已绑定。", "info");
+			const postStart = await controller.status(process.env);
+			let dashboard = renderStartSuccess(postStart, result.bindingCode);
+			// 对齐 easycodeclient：start 后 probe 权限健康度，缺失时追加一键申请链接。
+			const appId = controller.appId;
+			if (appId) {
+				const probe = await controller.probeScopes();
+				dashboard = await appendScopeHealthHint(appId, dashboard, probe.grantedScopes);
 			}
+			context.ui.notify(dashboard, result.bindingCode ? "warning" : "info");
 			return;
 		}
 		case "stop":
-			context.ui.notify((await controller.stop()) ? "飞书长连接已停止。" : "飞书长连接未运行。", "info");
+			context.ui.notify((await controller.stop()) ? "✅ 飞书长连接已停止。" : "⚠️ 飞书 Bot 未运行。", "info");
 			return;
-		case "status":
-			context.ui.notify(renderFeishuStatus(await controller.status(process.env)), "info");
+		case "status": {
+			const status = await controller.status(process.env);
+			// ✨ Mini-doctor：probe scope 健康度（失败不影响 status 输出）。
+			let scopeHealth: string[] | undefined;
+			const appId = controller.appId;
+			if (status.configured && appId) {
+				const probe = await controller.probeScopes();
+				if (probe.grantedScopes) {
+					scopeHealth = missingScopes(probe.grantedScopes, REQUIRED_APP_SCOPES);
+				}
+			}
+			context.ui.notify(renderFeishuStatus(status, scopeHealth), "info");
 			return;
+		}
 		case "logout": {
 			if (context.hasUI) {
 				const confirmed = await context.ui.confirm("退出飞书", "停止连接并清除本地飞书凭据？");

package/src/gateway.ts

@@ -7,6 +7,7 @@ import type {
 	FeishuReply,
 	FeishuReplySnapshot,
 } from "./contracts.js";
+import { probeGrantedScopes } from "./scopes.js";
 
 export interface NormalizedChannelMessage {
 	messageId: string;
@@ -123,6 +124,10 @@ export class SdkFeishuGateway implements FeishuGateway {
 		return result.data.chat_id;
 	}
 
+	async probeGrantedScopes(): Promise<{ grantedScopes?: string[] }> {
+		return probeGrantedScopes(this.credentials);
+	}
+
 	async sendText(chatId: string, text: string, replyTo?: string): Promise<string | undefined> {
 		const channel = this.channel;
 		if (!channel) throw new Error("飞书长连接尚未启动。");
@@ -190,8 +195,11 @@ function createOfficialChannel(credentials: FeishuCredentials): ChannelLike {
 			policy: {
 				dmMode: "open",
 				// Controller enforces owner identity and only accepts groups it created.
+				// Keep SDK-side mention filtering off so apps with im:message.group_msg
+				// can receive normal managed-group messages without @. Without that
+				// sensitive scope, Feishu only pushes @bot group events anyway.
 				groupAllowlist: [],
-				requireMention: true,
+				requireMention: false,
 			},
 			safety: {
 				chatQueue: { enabled: false },

package/src/pi-agent-bridge.ts

@@ -8,10 +8,10 @@ interface PendingTurn {
 }
 
 export class PiAgentBridge implements AgentBridge {
-	private readonly sendUserMessage: (text: string) => void;
+	private readonly sendUserMessage: (text: string) => void | Promise<void>;
 	private pending: PendingTurn | undefined;
 
-	constructor(sendUserMessage: (text: string) => void) {
+	constructor(sendUserMessage: (text: string) => void | Promise<void>) {
 		this.sendUserMessage = sendUserMessage;
 	}
 
@@ -23,12 +23,10 @@ export class PiAgentBridge implements AgentBridge {
 		return new Promise<string>((resolve, reject) => {
 			this.pending = { resolve, reject, lastAssistantText: "", observer };
 			observer?.onActivity?.({ kind: "thinking" });
-			try {
-				this.sendUserMessage(text);
-			} catch (error) {
+			Promise.resolve(this.sendUserMessage(text)).catch((error: unknown) => {
 				this.pending = undefined;
 				reject(error instanceof Error ? error : new Error(String(error)));
-			}
+			});
 		});
 	}
 

package/src/scopes.ts

@@ -0,0 +1,119 @@
+import type { FeishuCredentials } from "./contracts.js";
+
+export const REQUIRED_APP_SCOPES = [
+	"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",
+	"im:chat:read",
+	"application:application:self_manage",
+] as const;
+
+export const SENSITIVE_GROUP_MSG_SCOPE = "im:message.group_msg";
+
+export interface ScopeProbeResult {
+	grantedScopes?: string[];
+}
+
+export function missingScopes(granted: readonly string[] | undefined, required: readonly string[]): string[] {
+	if (!granted) return [...required];
+	const set = new Set(granted);
+	return required.filter((scope) => !set.has(scope));
+}
+
+export function hasScope(granted: readonly string[] | undefined, scope: string): boolean {
+	return Boolean(granted?.includes(scope));
+}
+
+export function buildScopeApplyUrl(params: { appId: string; scopes: readonly string[] }): string {
+	const url = new URL(`https://open.feishu.cn/app/${params.appId}/auth`);
+	if (params.scopes.length > 0 && params.scopes.length < 20) url.searchParams.set("q", params.scopes.join(","));
+	url.searchParams.set("op_from", "pi-feishu");
+	url.searchParams.set("token_type", "tenant");
+	return url.toString();
+}
+
+export function buildPermissionPageUrl(appId: string): string {
+	return `https://open.feishu.cn/app/${appId}/permission`;
+}
+
+export function buildEventSubUrl(appId: string): string {
+	return `https://open.feishu.cn/app/${appId}/event-sub`;
+}
+
+export async function probeGrantedScopes(credentials: FeishuCredentials): Promise<ScopeProbeResult> {
+	const tokenResponse = await fetch("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ app_id: credentials.appId, app_secret: credentials.appSecret }),
+	});
+	const tokenResult = (await tokenResponse.json()) as { code?: number; msg?: string; tenant_access_token?: string };
+	if (!tokenResponse.ok || tokenResult.code !== 0 || !tokenResult.tenant_access_token) {
+		throw new Error(`获取飞书 tenant token 失败：${tokenResult.msg ?? tokenResponse.statusText}`);
+	}
+
+	const scopeResponse = await fetch("https://open.feishu.cn/open-apis/application/v6/applications/me?lang=zh_cn", {
+		headers: { Authorization: `Bearer ${tokenResult.tenant_access_token}` },
+	});
+	const scopeResult = (await scopeResponse.json()) as {
+		code?: number;
+		app?: ScopeApp;
+		data?: ScopeApp & { app?: ScopeApp };
+	};
+	if (!scopeResponse.ok || scopeResult.code !== 0) return {};
+	const app = scopeResult.data?.app ?? scopeResult.app ?? scopeResult.data ?? {};
+	const rawScopes = app.scopes ?? app.online_version?.scopes ?? [];
+	return {
+		grantedScopes: rawScopes.map((entry) => entry.scope).filter((scope): scope is string => Boolean(scope)),
+	};
+}
+
+interface ScopeApp {
+	scopes?: Array<{ scope?: string }>;
+	online_version?: { scopes?: Array<{ scope?: string }> };
+}
+
+export function buildGroupPermissionReminder(params: {
+	appId: string;
+	groupName: string;
+	grantedScopes?: readonly string[];
+}): string | null {
+	const missingRequired = missingScopes(params.grantedScopes, REQUIRED_APP_SCOPES);
+	const missingGroupMsg = !hasScope(params.grantedScopes, SENSITIVE_GROUP_MSG_SCOPE);
+	const unknown = !params.grantedScopes;
+	if (!unknown && missingRequired.length === 0 && !missingGroupMsg) return null;
+
+	const requiredForLink = unknown ? REQUIRED_APP_SCOPES : missingRequired;
+	const lines = ["💬 **【重要体验提示 — 飞书项目群权限】**", "", `您刚才成功创建了项目群「${params.groupName}」。`, ""];
+	if (unknown) {
+		lines.push(
+			"ℹ️ 当前应用还不能读取自身已开通 scope 列表（通常缺少 `application:application:self_manage`），无法自动确认权限完整性。",
+			"",
+		);
+	}
+	if (missingRequired.length > 0 || unknown) {
+		lines.push(
+			"⚠️ **基础权限可能未完整开通**，缺失时会影响私聊/群聊接收、回复、更新卡片和已读表情。",
+			`👉 一键申请基础权限：${buildScopeApplyUrl({ appId: params.appId, scopes: requiredForLink })}`,
+			"",
+		);
+	}
+	if (missingGroupMsg || unknown) {
+		lines.push(
+			`⚠️ **免 @ 权限未确认**：如果不开通 \`${SENSITIVE_GROUP_MSG_SCOPE}\`，群里普通消息可能不会触发机器人；请在群里 @ 机器人，或申请免 @ 权限。`,
+			`👉 一键申请免 @ 权限：${buildScopeApplyUrl({ appId: params.appId, scopes: [SENSITIVE_GROUP_MSG_SCOPE] })}`,
+			"",
+		);
+	}
+	lines.push(
+		"还需要确认事件订阅与发布：",
+		`1️⃣ 事件订阅页确认订阅 \`im.message.receive_v1\`：${buildEventSubUrl(params.appId)}`,
+		`2️⃣ 权限管理页申请发布版本使权限生效：${buildPermissionPageUrl(params.appId)}`,
+		"",
+		"权限生效前，群里请先使用 `@机器人 你的问题`。",
+	);
+	return lines.join("\n");
+}