@hwj123weijian/pi-feishu 0.11.1 → 0.11.3

package/README.md

@@ -163,6 +163,10 @@ pi -e D:\ai_study\pi-feishu
 
 已知限制：Pi 是单会话进程，群与群、群与私聊之间共享一个执行引擎，**跨聊天**的任务仍全局串行（排队提示会如实显示位数）。同一聊天内任务运行中继续发消息，会直接并入当前对话（steer），无需排队。远程命令作用于最近活跃的会话，`/model`、`/thinking`、`/compact` 建议在对应聊天的上一条消息之后紧接着发送。
 
+### 与本地使用共存
+
+Pi 同时是你本地的 TUI 工具：为避免飞书消息打断你正在终端里跑的任务，插件在驱动 Pi 前会检测本地是否繁忙——繁忙时飞书消息会等待（收到提示"本地 Pi 正在执行任务"），超过 15 分钟仍繁忙则取消处理并通知你重发。同理，群会话的目录锚定依赖会话文件落盘（Pi 在首条回复后才写盘），新会话的锚定从下一条消息开始生效。若在本地 Pi 手动切换过会话，远程路由的会话控制会过期一次：按提示在本地执行 `/feishu status` 刷新即可恢复。
+
 未知命令会返回提示，不会发给 Pi。`/model` 的候选来自本地 Pi 的 scoped models（未配置时为全部已授权模型）；`/model` 无参数时展示当前模型。注意：任何以 `/` 开头的消息都会先被当作命令解析，想发给 Pi 的提问请勿以 `/` 开头。
 
 ### 取消排队中的消息

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hwj123weijian/pi-feishu",
-	"version": "0.11.1",
+	"version": "0.11.3",
 	"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;
@@ -835,8 +866,50 @@ 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;
+		// Pi 是单会话进程：本地 TUI 正在跑的任务会被会话切换 abort 掉。
+		// 因此驱动 Pi 之前先等本地空闲，绝不打断用户手头的工作。
+		if (!(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

@@ -100,8 +100,13 @@ function getSharedState(): SharedFeishuState {
 		steer: (text) => {
 			// 仅当确有飞书轮次在跑时并入：发到当前活跃会话（轮次就在那里），绝不触发会话切换。
 			if (!state.activeBridge || !state.sendCurrentMessage) return false;
-			state.sendCurrentMessage(text, { deliverAs: "steer" });
-			return true;
+			try {
+				state.sendCurrentMessage(text, { deliverAs: "steer" });
+				return true;
+			} catch {
+				// pi 已失效等场景：并入失败，回落到正常排队。
+				return false;
+			}
 		},
 	};
 	const proxyRuntime: PiRuntime = {
@@ -122,6 +127,8 @@ function getSharedState(): SharedFeishuState {
 					},
 				});
 				return !result.cancelled;
+			} catch (error) {
+				rethrowStaleAsHint(state, error);
 			} finally {
 				state.switchingSession = false;
 			}
@@ -165,6 +172,24 @@ function tryGetSessionFile(context: ExtensionContext): string | undefined {
 	}
 }
 
+/** 缓存的命令上下文已失效（Pi 侧发生过会话替换）时的可操作提示。 */
+export const SESSION_CONTROL_HINT =
+	"本地 Pi 会话控制已过期（本地发生过会话切换）。请在本地 Pi 执行一次 /feishu status 刷新，然后重发这条消息。";
+
+function isStaleCtxError(error: unknown): boolean {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("extension ctx is stale") || message.includes("ctx is stale after session replacement");
+}
+
+/** 把 Pi 的英文 stale 内部错误转译成可操作指引，其余错误原样上抛。 */
+function rethrowStaleAsHint(state: SharedFeishuState, error: unknown): never {
+	if (isStaleCtxError(error)) {
+		state.latestCommandContext = undefined;
+		throw new Error(SESSION_CONTROL_HINT);
+	}
+	throw error instanceof Error ? error : new Error(String(error));
+}
+
 /**
  * p2p 私聊消息永远落在主会话：群消息处理会把 Pi 切进群的会话，
  * 这里负责在下一条私聊到来时切回去，避免把 Owner 的提问发进群会话。
@@ -182,7 +207,7 @@ async function sendToMainSession(state: SharedFeishuState, prompt: string): Prom
 	const context = state.latestCommandContext;
 	if (!context) {
 		// 主会话与当前会话不一致却没有命令上下文：直发会串进群会话，给出可操作的错误更安全。
-		throw new Error("Pi 会话控制尚未就绪，请先在本地执行一次 /feishu status。");
+		throw new Error(SESSION_CONTROL_HINT);
 	}
 	state.switchingSession = true;
 	try {
@@ -193,32 +218,47 @@ async function sendToMainSession(state: SharedFeishuState, prompt: string): Prom
 			},
 		});
 		if (result.cancelled) throw new Error("切回主 Pi 会话已取消。");
+	} catch (error) {
+		rethrowStaleAsHint(state, error);
 	} finally {
 		state.switchingSession = false;
 	}
 }
 
 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("Pi 会话控制尚未就绪，请先在本地执行一次 /feishu status。");
+	if (!context) throw new Error(SESSION_CONTROL_HINT);
 
 	const directory = state.controller.getChatDirectory(chatId);
 	state.switchingSession = true;
 	try {
-		const sessionFile = state.controller.getChatSessionFile(chatId);
 		if (sessionFile) {
 			// Pi 的 TUI switchSession 不透传 cwdOverride，改为把 cwd 写进会话头：
 			// SessionManager.open 切换时从 header 读取 cwd，runtime 随之在新目录重建。
-			if (directory && !(await anchorSessionHeaderCwd(sessionFile, directory))) {
-				throw new Error(`无法把群会话锚定到 ${directory}（会话文件不可写或格式未知）。`);
+			// 会话文件可能尚未落盘（Pi 要等首条 assistant 回复才写文件）——此时跳过
+			// 锚定正常处理，本轮回复落盘后下一轮自动生效，绝不因锚定失败终止消息。
+			let anchored = true;
+			if (directory) {
+				anchored = await anchorSessionHeaderCwd(sessionFile, directory);
 			}
 			const result = await context.switchSession(sessionFile, {
 				withSession: (nextContext) => {
-					if (directory) assertAnchoredCwd(nextContext, directory);
+					if (directory && anchored) checkAnchoredCwd(state, chatId, nextContext, directory);
 					return sendAndTrackGroupSession(state, chatId, sessionFile, nextContext, prompt);
 				},
 			});
 			if (result.cancelled) throw new Error("切换到飞书群绑定的 Pi 会话已取消。");
+			if (directory && !anchored) {
+				await state.controller
+					.notifyChat(chatId, "ℹ️ 本群的目录锚定将在下一条消息生效（当前会话文件尚未写入磁盘）。")
+					.catch(() => undefined);
+			}
 			return;
 		}
 
@@ -227,26 +267,19 @@ async function sendToChatSession(state: SharedFeishuState, chatId: string, promp
 				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;
+				if (directory) {
+					// 全新会话的文件还没落盘（Pi 等首条 assistant 回复才写）：本轮先在
+					// 继承的目录下处理，回复落盘后下一轮消息到来时锚定自动生效。
+					await state.controller
+						.notifyChat(chatId, `ℹ️ 本群已锚定到目录：${directory}，将从下一条消息开始在该目录下工作。`)
+						.catch(() => undefined);
 				}
 				await nextContext.sendUserMessage(prompt);
 			},
 		});
 		if (result.cancelled) throw new Error("创建飞书群专属 Pi 会话已取消。");
+	} catch (error) {
+		rethrowStaleAsHint(state, error);
 	} finally {
 		state.switchingSession = false;
 	}
@@ -286,12 +319,18 @@ export async function anchorSessionHeaderCwd(sessionFile: string, directory: str
 	return true;
 }
 
-function assertAnchoredCwd(context: ExtensionContext, directory: string): void {
+/** 锚定后校验 runtime cwd 是否真的切了过去；不符只提示，不终止消息。 */
+function checkAnchoredCwd(
+	state: SharedFeishuState,
+	chatId: string,
+	context: ExtensionContext,
+	directory: string,
+): void {
 	const effective = safeCwd(context);
 	if (effective && resolvePath(effective) !== resolvePath(directory)) {
-		throw new Error(
-			`群会话未能切换到绑定目录（当前：${effective}）。请重启本地 Pi 后重试，或在本地执行 /feishu status 刷新会话控制。`,
-		);
+		void state.controller
+			.notifyChat(chatId, `⚠️ 群会话未能切换到绑定目录（当前：${effective}，期望：${directory}）。`)
+			.catch(() => undefined);
 	}
 }