@hwj123weijian/pi-feishu 0.6.0 → 0.7.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`；未开通时请在群里使用 `@机器人 你的问题`。
 
 ## 安装
 
@@ -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 的提问请勿以 `/` 开头。
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hwj123weijian/pi-feishu",
-	"version": "0.6.0",
+	"version": "0.7.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;
@@ -355,18 +395,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

@@ -12,13 +12,15 @@ 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 +35,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 +85,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;
@@ -129,7 +176,7 @@ export function renderFeishuStatus(status: FeishuStatus): string {
 
 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 +185,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,7 +228,7 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 			return snapshot;
 		},
 	};
-	state.current = { bridge, runtime };
+	state.current = { runtime };
 
 	// 每个事件都会带来新的 ExtensionContext；持续刷新，保证远程命令拿到的能力不失效。
 	const trackContext = (_event: unknown, context: ExtensionContext): void => {
@@ -191,27 +238,27 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 	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 +294,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) {

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("飞书长连接尚未启动。");

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");
+}