@hwj123weijian/pi-feishu 0.11.2 → 0.12.0

package/README.md

@@ -155,13 +155,21 @@ pi -e D:\ai_study\pi-feishu
 ### 群聊使用
 
 - **绑定已有群**：把机器人加进现有项目群后，Owner 在群里发送 `/bind` 即可绑定；之后该群获得独立 Pi session，与其他群和主对话互不串上下文。机器人被拉进新群时也会私聊 Owner 提醒绑定。
-- **绑定项目目录**（推荐）：发送 `/bind /path/to/project` 把群锚定到项目目录——群会话的工作目录会切换到该目录，bot 直接读写这个项目；Owner 显式绑定的目录会自动加入 Pi 的项目信任。私聊里说“帮我拉个群 /path/to/project”也可以在建群时一并锚定。
+- **独立群引擎**：群消息由独立的 `pi -p` 子进程处理（不再复用你本地 TUI 的 Pi 会话）——每个群有独立的会话历史（`~/.pi/agent/feishu/group-sessions/<chatId>.jsonl`），互不串上下文，不同群可以同时对话，也不会打断或依赖你本地终端里正在跑的任务。
+- **绑定项目目录**（推荐）：发送 `/bind /path/to/project` 把群锚定到项目目录——群子进程直接在该目录下启动，bot 的读写、bash 都在这个项目里执行；Owner 显式绑定的目录会自动加入 Pi 的项目信任。私聊里说“帮我拉个群 /path/to/project”也可以在建群时一并锚定。
 - **触发方式**：默认在群里 `@机器人 你的问题`。飞书只向 bot 推送 @bot 的群消息；普通消息直接触发需要敏感权限 `im:message.group_msg`。
 - **授权成员**：默认只有 Owner 能使用。Owner 私聊发送 `/allow @张三` 后，张三即可在私聊和已绑定群里与机器人协作；`/deny @张三` 撤销。
 - **分寸感**：未绑定的群里被 @ 时回复绑定引导；非授权成员被 @ 时回复一次“未授权”；其余群内消息完全静默，不会刷屏。
 - **说话人上下文**：群消息发给 Pi 前会加上 `[飞书群聊] 说话人：` 前缀，@ 其他人会被改写成 `@名字`，模型知道在和谁对话。
+- **群内 /new**：删除该群的会话文件，下一条群消息以全新历史开始。
 
-已知限制：Pi 是单会话进程，群与群、群与私聊之间共享一个执行引擎，**跨聊天**的任务仍全局串行（排队提示会如实显示位数）。同一聊天内任务运行中继续发消息，会直接并入当前对话（steer），无需排队。远程命令作用于最近活跃的会话，`/model`、`/thinking`、`/compact` 建议在对应聊天的上一条消息之后紧接着发送。
+已知限制：私聊仍驱动本地 TUI 所在的 Pi 进程（与本地终端共享引擎，排队提示如实显示位数；本地繁忙时私聊消息会等待，不会打断你）。同一群里任务运行中继续发消息会排队（群子进程按会话文件串行，保证对话顺序）。远程命令 `/model`、`/thinking`、`/compact` 作用于本地 Pi 进程，对群子进程不生效；群内 `/new` 用于重置群会话。
+
+### 与本地使用共存
+
+群聊走独立子进程后与本地使用完全解耦：你在终端 TUI 里跑任何任务都不会被飞书消息打断，也不需要先跑完才能处理群消息。私聊仍在本地 Pi 进程内驱动——本地繁忙时私聊消息会等待（收到提示“本地 Pi 正在执行任务”），超过 15 分钟则取消处理并通知你重发；若在本地 Pi 手动切换过会话，私聊路由的会话控制会过期一次：按提示在本地执行 `/feishu status` 刷新即可恢复。
+
+群子进程从 PATH 中查找 `pi` 可执行文件；如不在 PATH 中，可设置 `PI_BIN` 环境变量指向 pi 的完整路径。
 
 未知命令会返回提示，不会发给 Pi。`/model` 的候选来自本地 Pi 的 scoped models（未配置时为全部已授权模型）；`/model` 无参数时展示当前模型。注意：任何以 `/` 开头的消息都会先被当作命令解析，想发给 Pi 的提问请勿以 `/` 开头。
 

package/package.json

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

package/src/controller.ts

@@ -90,6 +90,20 @@ export interface FeishuControllerOptions {
 	generateBindingCode?: () => string;
 	/** 落盘去重记录的路径；默认与凭据同目录，测试注入临时路径。 */
 	deduplicationPath?: string;
+	/** 本地忙闲轮询间隔（测试可调小）。 */
+	idlePollMs?: number;
+	/** 本地 Pi 持续繁忙多久后放弃处理（默认 15 分钟）。 */
+	localBusyTimeoutMs?: number;
+	/** 繁忙持续多久后给聊天发等待提示（默认 3 秒）。 */
+	busyNotifyAfterMs?: number;
+}
+
+const DEFAULT_IDLE_POLL_MS = 2000;
+const DEFAULT_LOCAL_BUSY_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_BUSY_NOTIFY_AFTER_MS = 3000;
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 export interface FeishuStartResult {
@@ -106,6 +120,11 @@ export class FeishuController {
 	private readonly generateBindingCode: (() => string) | undefined;
 	private readonly queue = new SerialMessageQueue();
 	private readonly deduplicator: MessageDeduplicator;
+	private readonly idlePollMs: number;
+	private readonly localBusyTimeoutMs: number;
+	private readonly busyNotifyAfterMs: number;
+	/** stop() 置位：让本地忙闲等待循环立即退出。 */
+	private stopped = false;
 	private gateway: FeishuGateway | undefined;
 	private credentials: FeishuCredentials | undefined;
 	private binding: OwnerBinding | undefined;
@@ -122,6 +141,9 @@ export class FeishuController {
 		this.agent = options.agent;
 		this.runtime = options.runtime;
 		this.generateBindingCode = options.generateBindingCode;
+		this.idlePollMs = options.idlePollMs ?? DEFAULT_IDLE_POLL_MS;
+		this.localBusyTimeoutMs = options.localBusyTimeoutMs ?? DEFAULT_LOCAL_BUSY_TIMEOUT_MS;
+		this.busyNotifyAfterMs = options.busyNotifyAfterMs ?? DEFAULT_BUSY_NOTIFY_AFTER_MS;
 		// 对齐 easycodeclient：受理即落盘的去重记录，进程重启后飞书重推也不会重复执行。
 		this.deduplicator = new MessageDeduplicator(5000, options.deduplicationPath ?? defaultProcessedMessagesPath());
 	}
@@ -170,6 +192,7 @@ export class FeishuController {
 		this.binding = binding;
 		this.gateway = gateway;
 		this.environment = environment;
+		this.stopped = false;
 		// 恢复落盘的受理记录：重启后飞书重推的事件仍会被去重，而不是重复驱动 Pi。
 		await this.deduplicator.hydrate();
 
@@ -250,6 +273,13 @@ export class FeishuController {
 		return Object.values(sessions).includes(sessionFile);
 	}
 
+	/** 向指定聊天发一条提示文字（fire-and-forget，失败静默）。 */
+	async notifyChat(chatId: string, text: string): Promise<void> {
+		const gateway = this.gateway;
+		if (!gateway) return;
+		await gateway.sendText(chatId, text).catch(() => undefined);
+	}
+
 	async setChatSessionFile(chatId: string, sessionFile: string): Promise<void> {
 		const credentials = this.credentials;
 		if (!credentials) return;
@@ -286,6 +316,7 @@ export class FeishuController {
 	async stop(): Promise<boolean> {
 		const gateway = this.gateway;
 		if (!gateway) return false;
+		this.stopped = true;
 		this.botAddedUnsubscribe?.();
 		this.botAddedUnsubscribe = undefined;
 		for (const entry of this.pendingTasks.values()) entry.cancelled = true;
@@ -525,7 +556,11 @@ export class FeishuController {
 		}
 		if (!isDirectory) {
 			await gateway
-				.sendText(message.chatId, `❌ 目录不存在或不是文件夹：${resolved}\n用法：/bind /path/to/project`, message.messageId)
+				.sendText(
+					message.chatId,
+					`❌ 目录不存在或不是文件夹：${resolved}\n用法：/bind /path/to/project`,
+					message.messageId,
+				)
 				.catch(() => undefined);
 			return;
 		}
@@ -835,8 +870,51 @@ export class FeishuController {
 		this.credentials = next;
 	}
 
+	/**
+	 * 等待本地 Pi 空闲。超过 localBusyTimeoutMs 仍繁忙则放弃（返回 false），
+	 * 等待超过 3 秒时先给聊天发一条提示，让用户知道消息没有丢。
+	 */
+	private async waitForLocalIdle(gateway: FeishuGateway, message: FeishuIncomingMessage): Promise<boolean> {
+		const runtime = this.runtime;
+		if (!runtime) return true;
+		const start = Date.now();
+		let notified = false;
+		for (;;) {
+			if (this.stopped || this.gateway !== gateway) return false;
+			let idle: boolean;
+			try {
+				idle = runtime.isIdle();
+			} catch {
+				idle = true; // 忙闲未知（ctx 失效等）时不得阻塞消息处理。
+			}
+			if (idle) return true;
+			const waitedMs = Date.now() - start;
+			if (waitedMs > this.localBusyTimeoutMs) return false;
+			if (!notified && waitedMs > this.busyNotifyAfterMs) {
+				notified = true;
+				await gateway
+					.sendText(
+						message.chatId,
+						"⏳ 本地 Pi 正在执行任务，本条消息将在其完成后处理（不会打断本地任务）。",
+						message.messageId,
+					)
+					.catch(() => undefined);
+			}
+			await sleep(this.idlePollMs);
+		}
+	}
+
 	private async processWithAgent(gateway: FeishuGateway, message: FeishuIncomingMessage, text: string): Promise<void> {
 		if (this.gateway !== gateway) return;
+		// p2p 私聊在本地 Pi 进程内驱动：本地 TUI 正在跑的任务会被会话切换 abort 掉，
+		// 因此先等本地空闲，绝不打断用户手头的工作。
+		// 群消息由独立 pi 子进程承载，与本地会话互不影响，无需等待。
+		if (message.chatType !== "group" && !(await this.waitForLocalIdle(gateway, message))) {
+			await gateway
+				.sendText(message.chatId, "⏳ 本地 Pi 长时间繁忙，本条消息已取消处理，请稍后重发。", message.messageId)
+				.catch(() => undefined);
+			return;
+		}
 		const reply = await gateway.beginReply(message.chatId, message.messageId).catch(() => undefined);
 		if (reply) this.activeReplies.add(reply);
 		let latestText = "";

package/src/extension.ts

@@ -1,5 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve as resolvePath } from "node:path";
+import { rm } from "node:fs/promises";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -7,19 +6,18 @@ import type {
 	ProjectTrustHandler,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { AgentBridge, FeishuStatus, PiModelInfo, PiRuntime, PiRuntimeSnapshot } from "./contracts.js";
-
-/** switchSession/withSession 回调里的新会话上下文；Pi 未从包根导出该类型名，从签名提取。 */
-type SwitchCallback = NonNullable<
-	Parameters<ExtensionCommandContext["switchSession"]>[1] extends infer O | undefined
-		? O extends { withSession?: (ctx: infer C) => unknown }
-			? C
-			: never
-		: never
->;
+import type {
+	AgentBridge,
+	AgentProgressObserver,
+	FeishuStatus,
+	PiModelInfo,
+	PiRuntime,
+	PiRuntimeSnapshot,
+} from "./contracts.js";
 import { FeishuController } from "./controller.js";
 import { CredentialError, FileCredentialStore } from "./credentials.js";
 import { SdkFeishuGateway, validateSdkCredentials } from "./gateway.js";
+import { defaultGroupSessionFile, GroupAgentRunner } from "./group-agent.js";
 import { PiAgentBridge } from "./pi-agent-bridge.js";
 import { THINKING_LEVELS } from "./remote-commands.js";
 import {
@@ -58,6 +56,8 @@ interface SharedFeishuState {
 	 *   不能据此取消正在等待的飞书轮次（否则群消息必然失败）。
 	 */
 	switchingSession: boolean;
+	/** 群消息子进程运行器（每群独立 pi -p 进程，不碰本地会话）。 */
+	groupRunner: GroupAgentRunner;
 }
 
 const SHARED_STATE_KEY = "__piFeishuSharedState__";
@@ -80,15 +80,16 @@ function getSharedState(): SharedFeishuState {
 		mainSessionFile: undefined,
 		currentSessionFile: undefined,
 		switchingSession: false,
+		groupRunner: new GroupAgentRunner(),
 		controller: undefined as unknown as FeishuController,
 	};
 	const proxyAgent: AgentBridge = {
 		run: (text, observer, options) => {
+			if (options?.chatId) {
+				// 群消息走独立 pi 子进程：不切本地会话、不碰 TUI、目录天然锚定。
+				return runGroupAgent(state, options.chatId, text, observer);
+			}
 			const bridge = new PiAgentBridge(async (prompt) => {
-				if (options?.chatId) {
-					await sendToChatSession(state, options.chatId, prompt);
-					return;
-				}
 				await sendToMainSession(state, prompt);
 			});
 			state.activeBridge = bridge;
@@ -96,9 +97,14 @@ function getSharedState(): SharedFeishuState {
 				if (state.activeBridge === bridge) state.activeBridge = undefined;
 			});
 		},
-		cancel: (reason) => state.activeBridge?.cancel(reason),
+		cancel: (reason) => {
+			state.activeBridge?.cancel(reason);
+			// 群消息由独立子进程承载：一并终止它们。
+			state.groupRunner.stop();
+		},
 		steer: (text) => {
 			// 仅当确有飞书轮次在跑时并入：发到当前活跃会话（轮次就在那里），绝不触发会话切换。
+			// 群消息走独立子进程，不经过这里。
 			if (!state.activeBridge || !state.sendCurrentMessage) return false;
 			try {
 				state.sendCurrentMessage(text, { deliverAs: "steer" });
@@ -115,22 +121,13 @@ function getSharedState(): SharedFeishuState {
 		compact: () => state.current?.runtime.compact(),
 		newSession: () => state.current?.runtime.newSession() ?? Promise.resolve(false),
 		newChatSession: async (chatId) => {
-			const context = state.latestCommandContext;
-			if (!context) return false;
-			state.switchingSession = true;
+			// 群会话由独立子进程承载：/new 等价于删除该群的 session 文件，
+			// 下一条群消息的子进程会以全新历史启动。
 			try {
-				const result = await context.newSession({
-					withSession: async (nextContext) => {
-						state.latestCommandContext = nextContext;
-						const sessionFile = nextContext.sessionManager.getSessionFile();
-						if (sessionFile) await state.controller.setChatSessionFile(chatId, sessionFile);
-					},
-				});
-				return !result.cancelled;
-			} catch (error) {
-				rethrowStaleAsHint(state, error);
-			} finally {
-				state.switchingSession = false;
+				await rm(defaultGroupSessionFile(chatId), { force: true });
+				return true;
+			} catch {
+				return false;
 			}
 		},
 		setThinkingLevel: (level) => state.current?.runtime.setThinkingLevel(level) ?? Promise.resolve(false),
@@ -225,131 +222,26 @@ async function sendToMainSession(state: SharedFeishuState, prompt: string): Prom
 	}
 }
 
-async function sendToChatSession(state: SharedFeishuState, chatId: string, prompt: string): Promise<void> {
-	const sessionFile = state.controller.getChatSessionFile(chatId);
-	// Pi 侧切换后当前会话可能恰好就是目标群会话：此时无需命令上下文，直接投递。
-	if (sessionFile && sessionFile === state.currentSessionFile && state.sendCurrentMessage) {
-		state.sendCurrentMessage(prompt);
-		return;
-	}
-	const context = state.latestCommandContext;
-	if (!context) throw new Error(SESSION_CONTROL_HINT);
-
+/** 群消息：spawn 独立 pi 子进程（cwd=绑定目录，session 文件按群隔离）。 */
+async function runGroupAgent(
+	state: SharedFeishuState,
+	chatId: string,
+	prompt: string,
+	observer: AgentProgressObserver | undefined,
+): Promise<string> {
 	const directory = state.controller.getChatDirectory(chatId);
-	state.switchingSession = true;
+	const sessionFile = defaultGroupSessionFile(chatId);
 	try {
-		if (sessionFile) {
-			// Pi 的 TUI switchSession 不透传 cwdOverride，改为把 cwd 写进会话头：
-			// SessionManager.open 切换时从 header 读取 cwd，runtime 随之在新目录重建。
-			if (directory && !(await anchorSessionHeaderCwd(sessionFile, directory))) {
-				throw new Error(`无法把群会话锚定到 ${directory}（会话文件不可写或格式未知）。`);
-			}
-			const result = await context.switchSession(sessionFile, {
-				withSession: (nextContext) => {
-					if (directory) assertAnchoredCwd(nextContext, directory);
-					return sendAndTrackGroupSession(state, chatId, sessionFile, nextContext, 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);
-				if (currentFile && directory) {
-					// 新会话默认继承当前 cwd：把会话头 cwd 改写为绑定目录后重新切换一次，
-					// runtime 会以新 cwd 重建，然后才投递消息。
-					if (!(await anchorSessionHeaderCwd(currentFile, directory))) {
-						throw new Error(`无法把群会话锚定到 ${directory}（会话文件不可写或格式未知）。`);
-					}
-					const anchored = await nextContext.switchSession(currentFile, {
-						withSession: (finalContext) => {
-							state.latestCommandContext = finalContext;
-							assertAnchoredCwd(finalContext, directory);
-							return finalContext.sendUserMessage(prompt);
-						},
-					});
-					if (anchored.cancelled) throw new Error("锚定群会话工作目录已取消。");
-					return;
-				}
-				await nextContext.sendUserMessage(prompt);
-			},
-		});
-		if (result.cancelled) throw new Error("创建飞书群专属 Pi 会话已取消。");
+		const result = await state.groupRunner.run(sessionFile, directory, prompt, observer);
+		return result.text || "Pi 已完成处理，但没有返回文本内容。";
 	} catch (error) {
-		rethrowStaleAsHint(state, error);
-	} finally {
-		state.switchingSession = false;
-	}
-}
-
-/**
- * 把会话文件头（JSONL 首行的 session header）里的 cwd 改写为绑定目录。
- * 群会话空闲时文件不被任何 runtime 持有，重写首行是安全的；下次
- * SessionManager.open 会以新 cwd 重建 runtime（工具、bash 都在新目录执行）。
- * 返回 false 表示文件不可读/格式未知，调用方给出可操作错误。
- */
-export async function anchorSessionHeaderCwd(sessionFile: string, directory: string): Promise<boolean> {
-	let raw: string;
-	try {
-		raw = await readFile(sessionFile, "utf8");
-	} catch {
-		return false;
-	}
-	const newlineIndex = raw.indexOf("\n");
-	const firstLine = newlineIndex === -1 ? raw : raw.slice(0, newlineIndex);
-	let header: Record<string, unknown>;
-	try {
-		header = JSON.parse(firstLine) as Record<string, unknown>;
-	} catch {
-		return false;
-	}
-	if (header.type !== "session" || typeof header.cwd !== "string") return false;
-	if (resolvePath(header.cwd) === resolvePath(directory)) return true;
-	header.cwd = directory;
-	const updatedFirstLine = JSON.stringify(header);
-	const updated = newlineIndex === -1 ? updatedFirstLine : updatedFirstLine + raw.slice(newlineIndex);
-	try {
-		await writeFile(sessionFile, updated, "utf8");
-	} catch {
-		return false;
-	}
-	return true;
-}
-
-function assertAnchoredCwd(context: ExtensionContext, directory: string): void {
-	const effective = safeCwd(context);
-	if (effective && resolvePath(effective) !== resolvePath(directory)) {
+		const reason = state.controller.sanitizeError(error);
 		throw new Error(
-			`群会话未能切换到绑定目录（当前：${effective}）。请重启本地 Pi 后重试，或在本地执行 /feishu status 刷新会话控制。`,
+			`${reason}（群聊由独立 pi 进程处理${directory ? `，工作目录：${directory}` : ""}；若 pi 不在 PATH 中，可设置 PI_BIN 环境变量）`,
 		);
 	}
 }
 
-function safeCwd(context: ExtensionContext): string | undefined {
-	try {
-		return context.cwd;
-	} catch {
-		return undefined;
-	}
-}
-
-async function sendAndTrackGroupSession(
-	state: SharedFeishuState,
-	chatId: string,
-	sessionFile: string,
-	nextContext: SwitchCallback,
-	prompt: string,
-): Promise<void> {
-	state.latestCommandContext = nextContext;
-	const currentFile = nextContext.sessionManager.getSessionFile();
-	if (currentFile && currentFile !== sessionFile) await state.controller.setChatSessionFile(chatId, currentFile);
-	await nextContext.sendUserMessage(prompt);
-}
-
 export interface ParsedFeishuCommand {
 	name: FeishuCommandName;
 	args: string;

package/src/group-agent.ts

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { AgentProgressObserver } from "./contracts.js";
+
+export interface GroupAgentRunResult {
+	text: string;
+	exitCode: number | null;
+}
+
+export interface GroupAgentRunOptions {
+	/** 硬超时：超时后 SIGTERM 子进程。 */
+	timeoutMs?: number;
+	/** pi 可执行文件；默认从 PATH 找 pi，可用 PI_BIN 覆盖。 */
+	bin?: string;
+	/** 测试注入：替换 spawn。 */
+	spawnImpl?: typeof spawn;
+}
+
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+
+interface PrintEvent {
+	type?: string;
+	message?: { role?: string; content?: unknown };
+	toolName?: string;
+}
+
+/**
+ * 群聊代理运行器：为每条群消息 spawn 一个独立的 `pi -p --mode json` 子进程。
+ *
+ * 与 easycodeclient「每群独立引擎」对齐的架构：
+ * - cwd 直接设为群的绑定目录 → 目录锚定天然成立；
+ * - 每个群固定一个 session 文件 → 历史隔离且跨重启续接；
+ * - 完全不触碰用户本地 TUI 的会话（不会被 abort、没有 stale ctx）；
+ * - 不同群的子进程彼此独立 → 群间真实并行。
+ */
+export class GroupAgentRunner {
+	private readonly timeoutMs: number;
+	private readonly bin: string;
+	private readonly spawnImpl: typeof spawn;
+	private readonly children = new Set<ReturnType<typeof spawn>>();
+
+	constructor(options: GroupAgentRunOptions = {}) {
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.bin = options.bin ?? process.env.PI_BIN ?? "pi";
+		this.spawnImpl = options.spawnImpl ?? spawn;
+	}
+
+	/** 当前在跑的子进程数（用于测试与状态展示）。 */
+	get runningCount(): number {
+		return this.children.size;
+	}
+
+	/** 中止所有在跑的群子进程（远程 /stop）；返回数量。 */
+	stop(): number {
+		let killed = 0;
+		for (const child of this.children) {
+			child.kill("SIGTERM");
+			killed += 1;
+		}
+		return killed;
+	}
+
+	async run(
+		sessionFile: string,
+		directory: string | undefined,
+		prompt: string,
+		observer?: AgentProgressObserver,
+	): Promise<GroupAgentRunResult> {
+		await mkdir(dirname(sessionFile), { recursive: true, mode: 0o700 });
+		const child = this.spawnImpl(this.bin, ["-p", "--mode", "json", "--session", sessionFile, prompt], {
+			cwd: directory ?? process.cwd(),
+			env: process.env,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		this.children.add(child);
+
+		return new Promise<GroupAgentRunResult>((resolve, reject) => {
+			let stdoutBuffer = "";
+			let stderrBuffer = "";
+			let latestAssistantText = "";
+			let settled = false;
+			const timer = setTimeout(() => {
+				child.kill("SIGTERM");
+			}, this.timeoutMs);
+
+			const finish = (error?: Error) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				this.children.delete(child);
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve({ text: latestAssistantText, exitCode: child.exitCode });
+			};
+
+			child.stdout?.on("data", (chunk: Buffer) => {
+				stdoutBuffer += chunk.toString("utf8");
+				let newlineIndex = stdoutBuffer.indexOf("\n");
+				while (newlineIndex !== -1) {
+					const line = stdoutBuffer.slice(0, newlineIndex).trim();
+					stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+					this.handleJsonLine(line, observer, (text) => {
+						latestAssistantText = text;
+					});
+					newlineIndex = stdoutBuffer.indexOf("\n");
+				}
+			});
+			child.stderr?.on("data", (chunk: Buffer) => {
+				stderrBuffer += chunk.toString("utf8");
+			});
+			child.on("error", (error) => {
+				finish(new Error(`启动 pi 子进程失败（cwd: ${directory ?? process.cwd()}）：${error.message}`));
+			});
+			child.on("close", (code) => {
+				if (code === 0) {
+					observer?.onText?.(latestAssistantText);
+					finish();
+					return;
+				}
+				const stderr = stderrBuffer.trim();
+				finish(new Error(stderr ? `pi 子进程退出码 ${code}：${stderr}` : `pi 子进程退出码 ${code}`));
+			});
+		});
+	}
+
+	private handleJsonLine(
+		line: string,
+		observer: AgentProgressObserver | undefined,
+		setLatest: (text: string) => void,
+	): void {
+		if (!line) return;
+		let event: PrintEvent;
+		try {
+			event = JSON.parse(line) as PrintEvent;
+		} catch {
+			return;
+		}
+		if (event.type === "tool_execution_start") {
+			const toolName = event.toolName ?? "tool";
+			observer?.onActivity?.({ kind: "tool", toolName });
+			return;
+		}
+		if (event.type !== "message_update" || event.message?.role !== "assistant") return;
+		const text = extractText(event.message.content);
+		if (text) {
+			setLatest(text);
+			observer?.onText?.(text);
+		}
+	}
+}
+
+function extractText(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const item of content) {
+		if (item && typeof item === "object" && (item as { type?: string }).type === "text") {
+			const text = (item as { text?: unknown }).text;
+			if (typeof text === "string") parts.push(text);
+		}
+	}
+	return parts.join("").trimEnd();
+}
+
+/** 群专属 session 文件：~/.pi/agent/feishu/group-sessions/<chatId>.jsonl，由 pi CLI 自管。 */
+export function defaultGroupSessionFile(chatId: string): string {
+	const safe = chatId.replace(/[^A-Za-z0-9_-]/g, "_");
+	return join(homedir(), ".pi", "agent", "feishu", "group-sessions", `${safe}.jsonl`);
+}

package/src/scopes.ts

@@ -196,9 +196,12 @@ export function buildScopeHealthSection(appId: string, grantedScopes?: readonly
 	const missing = missingScopes(grantedScopes, REQUIRED_APP_SCOPES);
 	const hasGroupMsg = hasScope(grantedScopes, SENSITIVE_GROUP_MSG_SCOPE);
 	if (missing.length === 0 && hasGroupMsg) {
-		return ["✅ 应用权限配置完整，所有功能均可正常使用。", "", "本 Bot 依赖以下权限（均已开通）：", ...renderScopeInventory()].join(
-			"\n",
-		);
+		return [
+			"✅ 应用权限配置完整，所有功能均可正常使用。",
+			"",
+			"本 Bot 依赖以下权限（均已开通）：",
+			...renderScopeInventory(),
+		].join("\n");
 	}
 	const lines = ["⚠️ 以下应用权限尚未开通，对应功能会受限："];
 	if (missing.length > 0) {