@hwj123weijian/pi-feishu 0.2.0 → 0.5.0

package/README.md

@@ -8,14 +8,18 @@
 
 - 仅处理飞书私聊（`p2p`）文本消息
 - 首次启动生成一次性绑定码，只允许一个 Owner
+- 收到消息后立刻在原消息上添加“思考中”表情作为已读回执，回复送达后自动移除
+- 以 `/` 开头的消息走远程命令快速通道，不排队、不进入 LLM 上下文
 - 所有消息进入当前 Pi 会话，不创建额外 Agent 或会话
+- 消息需要排队时发送“排队中（第 N 位）”提示，轮到处理时自动撤回；队列变化时提示自动改写为新位数
+- Owner 在排队中的消息上点 ❌（`CrossMark`）表情即可取消该消息
 - Assistant 文本通过 Pi 的 `message_update` 增量渲染到同一张飞书卡片
 - 工具执行时仅显示安全的状态摘要，不展示参数、命令、文件内容或工具输出
 - SDK 以 500ms / 120 字符节流卡片更新；完成、失败、中止都会收尾卡片
 - 缺少更新权限或飞书卡片更新失败时，自动退化为原私聊的一次性文本回复
 - 串行处理消息，避免多条飞书消息同时驱动 Pi
 - 按飞书 `message_id` 去重
-- `/feishu stop`、`/feishu logout` 和 Pi 会话关闭时释放长连接
+- 长连接由跨会话的全局控制器保管：本地 `/new`、远程 `/new` 等会话切换不会断开；`/feishu stop`、`/feishu logout` 或 Pi 进程退出时释放
 - 凭据优先从环境变量读取，也可保存到本地凭据文件
 
 当前不支持群聊、图片、文件、卡片、语音、多用户、多会话、进程级沙箱或远程命令权限管理。这里的安全边界是“私聊 + 单 Owner”，Pi 本身仍拥有当前本地进程的权限。
@@ -35,11 +39,12 @@
    - `im:message.p2p_msg:readonly`：接收私聊消息
    - `im:message:send_as_bot`：以机器人身份回复
    - `im:message:update`：持续更新机器人发出的交互卡片
+   - 表情回复相关权限：在原消息上添加/移除“思考中”已读回执
 3. 在“事件与回调”中选择“使用长连接接收事件”。
 4. 添加事件 `im.message.receive_v1`。
 5. 创建并发布一个应用版本，使权限和事件订阅在企业内生效。
 
-这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。
+这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。若未授予表情回复权限，扩展同样可工作，只是原消息上不会出现已读表情。
 
 ## 安装
 
@@ -93,7 +98,7 @@ pi -e D:\ai_study\pi-feishu
 /bind 123456
 ```
 
-绑定成功后，直接私聊机器人即可驱动当前 Pi 会话。处理过程中会先显示“正在思考”，随后持续更新正文；Pi 调用工具时卡片会显示“正在执行工具”，最终状态会变为“已完成”。
+绑定成功后，直接私聊机器人即可驱动当前 Pi 会话。原消息会立刻出现“思考中”表情（已读回执），处理过程中先显示“正在思考”，随后持续更新正文；Pi 调用工具时卡片会显示“正在执行工具”，最终状态变为“已完成”，同时已读表情自动移除。
 
 也支持手动参数：
 
@@ -122,6 +127,28 @@ pi -e D:\ai_study\pi-feishu
 
 环境变量优先于凭据文件。如果环境变量中的 App ID 与已保存的 App ID 不同，旧 Owner 绑定不会被继承。
 
+### 飞书远程命令
+
+在飞书私聊里直接发送以下命令，会走高优先级快速通道：不进入消息队列排队，也不会作为提问发给 Pi。
+
+| 命令 | 作用 |
+| --- | --- |
+| `/help` | 显示远程命令帮助 |
+| `/new` | 新建 Pi 会话（丢弃当前对话上下文） |
+| `/stop` | 中止当前任务，并跳过队列中剩余消息 |
+| `/status` | 查看连接、队列、模型与上下文占用 |
+| `/compact` | 压缩当前会话上下文 |
+| `/thinking` | 查看思考档位，或切换：`/thinking off|minimal|low|medium|high|xhigh|max` |
+| `/model` | 查看当前模型，或模糊匹配切换：`/model <模型ID或名称>` |
+
+未知命令会返回提示，不会发给 Pi。`/model` 的候选来自本地 Pi 的 scoped models（未配置时为全部已授权模型）；`/model` 无参数时展示当前模型。注意：任何以 `/` 开头的消息都会先被当作命令解析，想发给 Pi 的提问请勿以 `/` 开头。
+
+### 取消排队中的消息
+
+消息排队期间，Owner 直接在**自己的这条消息**上点 ❌（`CrossMark`）表情即可取消：排队提示与已读表情立即清理，消息不会发给 Pi，后面消息的排队提示自动前移。仅 Owner 的取消表情生效，已开工的消息不能取消（用 `/stop` 中止）。
+
+飞书的“消息撤回”事件未被官方 Node SDK 的 channel 抽象透出（长连接也不允许挂第二条连接分流事件），因此这里以 ❌ 表情作为取消入口，效果等价于撤回后移出队列。
+
 ## 常见问题
 
 ### `setup` 或 `start` 连接失败
@@ -140,6 +167,14 @@ pi -e D:\ai_study\pi-feishu
 
 确认已申请并发布 `im:message:update`。卡片初始化或更新失败时，扩展会自动改为最终文本回复，避免用户没有任何反馈。
 
+### 没有已读表情
+
+确认已申请并发布表情回复相关权限。该权限缺失时扩展自动降级：消息照常收发，只是原消息上不会出现“思考中”表情。
+
+### 远程 `/new` 提示暂不可用
+
+远程会话切换依赖本地 Pi 提供的命令上下文。先在本地 Pi 执行任意 `/feishu` 子命令（例如 `/feishu status`），再从飞书发送 `/new`。切换完成后长连接自动延续，无需重新执行 `/feishu start`。
+
 ### Bot 提示“未授权”
 
 该 Bot 已绑定其他 Owner。若要重新绑定，先在本地 Pi 执行 `/feishu logout`，再重新 `setup`、`start` 和 `/bind`。
@@ -156,7 +191,7 @@ npm test
 npm run build
 ```
 
-测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、去重、Pi 增量文本、工具状态、流式卡片收尾、降级、错误脱敏和清理行为。
+测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、排队提示改位与撤回、❌ 取消、`/stop` 按条跳过、去重、已读表情回执、远程命令快速通道、思考档位与模型切换、Pi 增量文本、工具状态、流式卡片收尾、降级、错误脱敏和清理行为。
 
 ## 许可证
 

package/package.json

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

package/src/contracts.ts

@@ -21,6 +21,15 @@ export interface FeishuIncomingMessage {
 
 export type FeishuMessageHandler = (message: FeishuIncomingMessage) => Promise<void> | void;
 
+export interface FeishuReactionEvent {
+	messageId: string;
+	operatorOpenId: string;
+	emojiType: string;
+	action: "added" | "removed";
+}
+
+export type FeishuReactionHandler = (event: FeishuReactionEvent) => void;
+
 export interface FeishuReplySnapshot {
 	text: string;
 	status: "正在思考" | "正在生成回复" | "正在执行工具" | "已完成" | "处理失败" | "已取消";
@@ -36,8 +45,59 @@ export interface FeishuReply {
 export interface FeishuGateway {
 	connect(handler: FeishuMessageHandler): Promise<void>;
 	disconnect(): Promise<void>;
-	sendText(chatId: string, text: string, replyTo?: string): Promise<void>;
+	/** 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>;
+	/** Edits an already-sent text message in place. */
+	editText(messageId: string, text: string): Promise<void>;
+	/** Adds an emoji reaction to a message and returns the Feishu reaction id. */
+	addReaction(messageId: string, emojiType: string): Promise<string>;
+	removeReaction(messageId: string, reactionId: string): Promise<void>;
+	recallMessage(messageId: string): Promise<void>;
+	/** Subscribes to emoji reactions on messages visible to the bot. */
+	onReaction(handler: FeishuReactionHandler): () => void;
+}
+
+export interface FeishuStatus {
+	configured: boolean;
+	running: boolean;
+	ownerOpenId?: string;
+	appId?: string;
+	source?: "environment" | "file";
+	pendingMessages: number;
+}
+
+export interface PiRuntimeSnapshot {
+	streaming: boolean;
+	model?: string;
+	thinkingLevel?: string;
+	contextPercent?: number;
+}
+
+export interface PiModelInfo {
+	id: string;
+	name: string;
+	provider: string;
+}
+
+/**
+ * Exposes the Pi runtime capabilities needed by remote slash commands.
+ * Implementations must be defensive: the captured context goes stale after
+ * a session switch, so methods may become no-ops until the next event.
+ */
+export interface PiRuntime {
+	isIdle(): boolean;
+	abort(): void;
+	compact(): void;
+	/** Returns false when the runtime is unavailable or the switch was cancelled. */
+	newSession(): Promise<boolean>;
+	/** Returns false when the requested thinking level does not exist. */
+	setThinkingLevel(level: string): Promise<boolean>;
+	/** Models the user can currently switch to. */
+	listModels(): PiModelInfo[];
+	/** Switches by fuzzy id/name match; throws with a user-facing reason on failure. */
+	switchModel(query: string): Promise<PiModelInfo>;
+	snapshot(): PiRuntimeSnapshot;
 }
 
 export type AgentActivity = { kind: "thinking" } | { kind: "tool"; toolName: string };

package/src/controller.ts

@@ -7,18 +7,40 @@ import type {
 	FeishuGateway,
 	FeishuGatewayFactory,
 	FeishuIncomingMessage,
+	FeishuReactionEvent,
 	FeishuReply,
+	FeishuStatus,
+	PiRuntime,
 } from "./contracts.js";
 import { CredentialError, errorMessage, resolveCredentialInput, resolveRuntimeCredentials } from "./credentials.js";
 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";
+
+// 与 easycodeclient 的飞书集成一致：THINKING 表情兼作"已读 + 处理中"回执。
+const READ_REACTION_EMOJI = "THINKING";
+
+interface PendingTask {
+	messageId: string;
+	chatId: string;
+	reactionId: string;
+	tipText: string;
+	tipMessageId: string | undefined;
+	started: boolean;
+	cancelled: boolean;
+}
+
+function queueTipText(position: number): string {
+	return `⏳ 已收到，排队中（第 ${position} 位），将在当前任务完成后处理。`;
+}
 
 export interface FeishuControllerOptions {
 	store: CredentialStore;
 	gatewayFactory: FeishuGatewayFactory;
 	validateCredentials: CredentialValidator;
 	agent: AgentBridge;
+	runtime?: PiRuntime;
 	generateBindingCode?: () => string;
 }
 
@@ -27,26 +49,20 @@ export interface FeishuStartResult {
 	bindingCode?: string;
 }
 
-export interface FeishuStatus {
-	configured: boolean;
-	running: boolean;
-	ownerOpenId?: string;
-	appId?: string;
-	source?: "environment" | "file";
-	pendingMessages: number;
-}
-
 export class FeishuController {
 	private readonly store: CredentialStore;
 	private readonly gatewayFactory: FeishuGatewayFactory;
 	private readonly validateCredentials: CredentialValidator;
 	private readonly agent: AgentBridge;
+	private readonly runtime: PiRuntime | undefined;
 	private readonly generateBindingCode: (() => string) | undefined;
 	private readonly queue = new SerialMessageQueue();
 	private readonly deduplicator = new MessageDeduplicator();
 	private gateway: FeishuGateway | undefined;
 	private credentials: FeishuCredentials | undefined;
 	private binding: OwnerBinding | undefined;
+	private environment: Environment = {};
+	private readonly pendingTasks = new Map<string, PendingTask>();
 	private readonly activeReplies = new Set<FeishuReply>();
 
 	constructor(options: FeishuControllerOptions) {
@@ -54,6 +70,7 @@ export class FeishuController {
 		this.gatewayFactory = options.gatewayFactory;
 		this.validateCredentials = options.validateCredentials;
 		this.agent = options.agent;
+		this.runtime = options.runtime;
 		this.generateBindingCode = options.generateBindingCode;
 	}
 
@@ -91,6 +108,7 @@ export class FeishuController {
 		this.credentials = credentials;
 		this.binding = binding;
 		this.gateway = gateway;
+		this.environment = environment;
 		this.deduplicator.clear();
 
 		try {
@@ -101,6 +119,7 @@ export class FeishuController {
 			await gateway.disconnect().catch(() => undefined);
 			throw new CredentialError(`启动飞书长连接失败：${errorMessage(error, credentials)}`);
 		}
+		gateway.onReaction((event) => this.handleReaction(event));
 
 		const bindingCode = binding.getOrCreateCode();
 		return bindingCode ? { alreadyRunning: false, bindingCode } : { alreadyRunning: false };
@@ -109,6 +128,8 @@ export class FeishuController {
 	async stop(): Promise<boolean> {
 		const gateway = this.gateway;
 		if (!gateway) return false;
+		for (const entry of this.pendingTasks.values()) entry.cancelled = true;
+		this.pendingTasks.clear();
 		await Promise.all([...this.activeReplies].map((reply) => reply.cancel().catch(() => undefined)));
 		this.activeReplies.clear();
 		this.gateway = undefined;
@@ -149,60 +170,139 @@ export class FeishuController {
 		if (!gateway || !binding || message.chatType !== "p2p" || message.contentType !== "text") return;
 		if (!message.messageId || !this.deduplicator.accept(message.messageId)) return;
 
+		const reactionId = await this.ackRead(gateway, message.messageId);
 		const authorization = binding.authorize(message.senderOpenId, message.text);
 		switch (authorization.kind) {
 			case "binding-required":
-				await this.safeSend(gateway, message, "Bot 尚未绑定，请在本地 Pi 查看一次性绑定码。");
+				await this.acknowledge(gateway, message, reactionId, "Bot 尚未绑定，请在本地 Pi 查看一次性绑定码。");
 				return;
 			case "invalid-binding-code":
-				await this.safeSend(gateway, message, "绑定码无效，请检查本地 Pi 显示的一次性绑定码。");
+				await this.acknowledge(gateway, message, reactionId, "绑定码无效，请检查本地 Pi 显示的一次性绑定码。");
 				return;
 			case "unauthorized":
-				await this.safeSend(gateway, message, "未授权：此 Bot 仅响应已绑定的 Owner。");
+				await this.acknowledge(gateway, message, reactionId, "未授权：此 Bot 仅响应已绑定的 Owner。");
 				return;
 			case "bound":
 				await this.persistOwner(authorization.ownerOpenId);
-				await this.safeSend(gateway, message, "绑定成功，现在可以直接发送问题。");
+				await this.acknowledge(gateway, message, reactionId, "绑定成功，现在可以直接发送问题。");
 				return;
 			case "authorized":
-				void this.queue.enqueue(async () => {
-					if (this.gateway !== gateway) return;
-					const reply = await gateway.beginReply(message.chatId, message.messageId).catch(() => undefined);
-					if (reply) this.activeReplies.add(reply);
-					let latestText = "";
-					try {
-						const response = await this.agent.run(authorization.text, {
-							onText: (text) => {
-								latestText = text;
-								reply?.update({ text, status: "正在生成回复" });
-							},
-							onActivity: (activity) => {
-								reply?.update({
-									text: latestText,
-									status: activity.kind === "tool" ? "正在执行工具" : "正在思考",
-								});
-							},
-						});
-						if (this.gateway === gateway) {
-							if (reply) {
-								await reply.complete({ text: response, status: "已完成" });
-							} else {
-								await gateway.sendText(message.chatId, response, message.messageId);
-							}
-						}
-					} catch {
-						if (this.gateway === gateway) {
-							if (reply) {
-								await reply.fail();
-							} else {
-								await this.safeSend(gateway, message, "处理消息失败，请稍后再试。");
-							}
-						}
-					} finally {
-						if (reply) this.activeReplies.delete(reply);
+				if (parseRemoteCommand(authorization.text)) {
+					// 斜杠命令快速通道：不进入消息队列，也不进入 LLM 上下文。
+					await this.runRemoteCommand(gateway, message, reactionId, authorization.text);
+					return;
+				}
+				void this.enqueueAgentTask(gateway, message, authorization.text, reactionId);
+		}
+	}
+
+	private enqueueAgentTask(
+		gateway: FeishuGateway,
+		message: FeishuIncomingMessage,
+		text: string,
+		reactionId: string,
+	): void {
+		const entry: PendingTask = {
+			messageId: message.messageId,
+			chatId: message.chatId,
+			reactionId,
+			tipText: "",
+			tipMessageId: undefined,
+			started: false,
+			cancelled: false,
+		};
+		// Map 保持插入顺序：首位是正在处理的任务，其余按排队先后排列。
+		const position = this.pendingTasks.size + 1;
+		this.pendingTasks.set(message.messageId, entry);
+
+		if (position > 1) {
+			entry.tipText = queueTipText(position);
+			void gateway
+				.sendText(message.chatId, entry.tipText, message.messageId)
+				.then((tipId) => {
+					if (!tipId) return;
+					// 提示送达时任务已开工或已取消：提示已无意义，直接撤回。
+					if (entry.cancelled || entry.started) {
+						void gateway.recallMessage(tipId).catch(() => undefined);
+						return;
 					}
-				});
+					entry.tipMessageId = tipId;
+					this.refreshQueueTips(gateway);
+				})
+				.catch(() => undefined);
+		}
+
+		void this.queue.enqueue(async () => {
+			entry.started = true;
+			try {
+				this.recallTip(gateway, entry);
+				if (this.gateway !== gateway) return;
+				// 被取消的任务静默跳过：回执与提示已由取消方清理。
+				if (entry.cancelled) return;
+				await this.processWithAgent(gateway, message, text);
+			} finally {
+				this.pendingTasks.delete(message.messageId);
+				this.refreshQueueTips(gateway);
+				await this.clearRead(gateway, message.messageId, reactionId);
+			}
+		});
+	}
+
+	private recallTip(gateway: FeishuGateway, entry: PendingTask): void {
+		const tipId = entry.tipMessageId;
+		if (!tipId) return;
+		entry.tipMessageId = undefined;
+		void gateway.recallMessage(tipId).catch(() => undefined);
+	}
+
+	/** 排队提示动态改位：前方的任务完成或被移除后，剩余提示更新为新位数。 */
+	private refreshQueueTips(gateway: FeishuGateway): void {
+		let position = 0;
+		for (const entry of this.pendingTasks.values()) {
+			position += 1;
+			// 首位要么正在处理、要么即将开工（提示随即撤回），无需改写。
+			if (position === 1 || entry.started || !entry.tipMessageId) continue;
+			const text = queueTipText(position);
+			if (text === entry.tipText) continue;
+			entry.tipText = text;
+			void gateway.editText(entry.tipMessageId, text).catch(() => undefined);
+		}
+	}
+
+	/** 中止当前任务之后的所有排队消息，返回跳过数量。 */
+	private stopQueuedMessages(gateway: FeishuGateway): number {
+		let skipped = 0;
+		for (const entry of [...this.pendingTasks.values()]) {
+			if (entry.started) continue;
+			entry.cancelled = true;
+			skipped += 1;
+			this.recallTip(gateway, entry);
+			void this.clearRead(gateway, entry.messageId, entry.reactionId);
+			entry.reactionId = "";
+			// 立即移出登记表：后续提示改位不再把它算作在队。
+			this.pendingTasks.delete(entry.messageId);
 		}
+		return skipped;
+	}
+
+	/** Owner 在排队中的消息上点 ❌（或 NO）表情：取消该消息并清理提示与回执。 */
+	handleReaction(event: FeishuReactionEvent): void {
+		const gateway = this.gateway;
+		const binding = this.binding;
+		if (!gateway || !binding) return;
+		if (event.action !== "added") return;
+		const normalized = event.emojiType.toLowerCase();
+		if (normalized !== "crossmark" && normalized !== "no") return;
+		if (event.operatorOpenId !== binding.ownerOpenId) return;
+		const entry = this.pendingTasks.get(event.messageId);
+		if (!entry || entry.started || entry.cancelled) return;
+
+		entry.cancelled = true;
+		this.recallTip(gateway, entry);
+		void this.clearRead(gateway, entry.messageId, entry.reactionId);
+		entry.reactionId = "";
+		this.pendingTasks.delete(entry.messageId);
+		this.refreshQueueTips(gateway);
 	}
 
 	async waitForIdle(): Promise<void> {
@@ -221,6 +321,82 @@ export class FeishuController {
 		this.credentials = next;
 	}
 
+	private async processWithAgent(gateway: FeishuGateway, message: FeishuIncomingMessage, text: string): Promise<void> {
+		if (this.gateway !== gateway) return;
+		const reply = await gateway.beginReply(message.chatId, message.messageId).catch(() => undefined);
+		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" ? "正在执行工具" : "正在思考",
+					});
+				},
+			});
+			if (this.gateway === gateway) {
+				if (reply) {
+					await reply.complete({ text: response, status: "已完成" });
+				} else {
+					await gateway.sendText(message.chatId, response, message.messageId);
+				}
+			}
+		} catch {
+			if (this.gateway === gateway) {
+				if (reply) {
+					await reply.fail();
+				} else {
+					await this.safeSend(gateway, message, "处理消息失败，请稍后再试。");
+				}
+			}
+		} finally {
+			if (reply) this.activeReplies.delete(reply);
+		}
+	}
+
+	private async runRemoteCommand(
+		gateway: FeishuGateway,
+		message: FeishuIncomingMessage,
+		reactionId: string,
+		text: string,
+	): Promise<void> {
+		const replyText = await executeRemoteCommand(text, {
+			runtime: this.runtime,
+			status: () => this.status(this.environment),
+			stopQueue: () => this.stopQueuedMessages(gateway),
+		}).catch((error: unknown) => `执行命令出错：${this.sanitizeError(error)}`);
+		await this.acknowledge(gateway, message, reactionId, replyText);
+	}
+
+	private async ackRead(gateway: FeishuGateway, messageId: string): Promise<string> {
+		try {
+			return await gateway.addReaction(messageId, READ_REACTION_EMOJI);
+		} catch {
+			// 表情权限缺失时静默降级：不影响正常的收发消息流程。
+			return "";
+		}
+	}
+
+	private async clearRead(gateway: FeishuGateway, messageId: string, reactionId: string): Promise<void> {
+		if (!reactionId) return;
+		await gateway.removeReaction(messageId, reactionId).catch(() => undefined);
+	}
+
+	private async acknowledge(
+		gateway: FeishuGateway,
+		message: FeishuIncomingMessage,
+		reactionId: string,
+		text: string,
+	): Promise<void> {
+		await this.safeSend(gateway, message, text);
+		await this.clearRead(gateway, message.messageId, reactionId);
+	}
+
 	private async safeSend(gateway: FeishuGateway, message: FeishuIncomingMessage, text: string): Promise<void> {
 		try {
 			await gateway.sendText(message.chatId, text, message.messageId);

package/src/extension.ts

@@ -1,10 +1,70 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { FeishuController, type FeishuStatus } from "./controller.js";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentBridge, 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 { PiAgentBridge } from "./pi-agent-bridge.js";
+import { THINKING_LEVELS } from "./remote-commands.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;
+}
+
+const SHARED_STATE_KEY = "__piFeishuSharedState__";
+
+/**
+ * Pi 会在每次会话切换（含远程 /new）后重新执行扩展工厂并重新求值模块，
+ * 因此只有挂在 globalThis 上的状态能跨会话存活：长连接、凭据和队列都在
+ * 这里，工厂重跑时只替换当前会话的 bridge/runtime。
+ */
+function getSharedState(): SharedFeishuState {
+	const host = globalThis as typeof globalThis & { [SHARED_STATE_KEY]?: SharedFeishuState };
+	const existing = host[SHARED_STATE_KEY];
+	if (existing) return existing;
+
+	const state: SharedFeishuState = { current: 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);
+		},
+		cancel: (reason) => state.current?.bridge.cancel(reason),
+	};
+	const proxyRuntime: PiRuntime = {
+		isIdle: () => state.current?.runtime.isIdle() ?? true,
+		abort: () => state.current?.runtime.abort(),
+		compact: () => state.current?.runtime.compact(),
+		newSession: () => state.current?.runtime.newSession() ?? Promise.resolve(false),
+		setThinkingLevel: (level) => state.current?.runtime.setThinkingLevel(level) ?? Promise.resolve(false),
+		listModels: () => state.current?.runtime.listModels() ?? [],
+		switchModel: async (query) => {
+			const link = state.current;
+			if (!link) throw new Error("Pi 会话尚未就绪，请稍后再试。");
+			return link.runtime.switchModel(query);
+		},
+		snapshot: () => state.current?.runtime.snapshot() ?? { streaming: false },
+	};
+	state.controller = new FeishuController({
+		store: new FileCredentialStore(),
+		gatewayFactory: (credentials) => new SdkFeishuGateway(credentials),
+		validateCredentials: validateSdkCredentials,
+		agent: proxyAgent,
+		runtime: proxyRuntime,
+	});
+	host[SHARED_STATE_KEY] = state;
+	return state;
+}
 
 export interface ParsedFeishuCommand {
 	name: FeishuCommandName;
@@ -67,46 +127,151 @@ export function renderFeishuStatus(status: FeishuStatus): string {
 }
 
 export default function feishuExtension(pi: ExtensionAPI): void {
-	const agent = new PiAgentBridge((text) => pi.sendUserMessage(text));
-	const controller = new FeishuController({
-		store: new FileCredentialStore(),
-		gatewayFactory: (credentials) => new SdkFeishuGateway(credentials),
-		validateCredentials: validateSdkCredentials,
-		agent,
-	});
+	const state = getSharedState();
+	const bridge = new PiAgentBridge((text) => pi.sendUserMessage(text));
+	let latestContext: ExtensionContext | undefined;
+	let latestCommandContext: ExtensionCommandContext | undefined;
+
+	const runtime: PiRuntime = {
+		isIdle: () => withRuntimeContext(() => latestContext?.isIdle()) ?? true,
+		abort: () => withRuntimeContext(() => latestContext?.abort()),
+		compact: () => withRuntimeContext(() => latestContext?.compact()),
+		newSession: async () => {
+			const context = latestCommandContext;
+			if (!context) return false;
+			try {
+				const result = await context.newSession();
+				return !result.cancelled;
+			} catch {
+				return false;
+			}
+		},
+		setThinkingLevel: async (level) => {
+			if (!isThinkingLevel(level)) return false;
+			try {
+				pi.setThinkingLevel(level);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		listModels: () => {
+			return availableModels(latestContext).map(toModelInfo);
+		},
+		switchModel: async (query) => {
+			const model = resolveModel(query, latestContext);
+			try {
+				const applied = await pi.setModel(model);
+				if (!applied) throw new Error(`模型 ${model.name} 缺少可用的 API Key。`);
+			} catch (error) {
+				throw error instanceof Error ? error : new Error(String(error));
+			}
+			return toModelInfo(model);
+		},
+		snapshot: () => {
+			const model = latestContext?.model;
+			const usage = withRuntimeContext(() => latestContext?.getContextUsage());
+			const snapshot: PiRuntimeSnapshot = {
+				streaming: !(withRuntimeContext(() => latestContext?.isIdle()) ?? true),
+			};
+			if (model) snapshot.model = model.name || model.id;
+			if (latestContext?.thinkingLevel) snapshot.thinkingLevel = latestContext.thinkingLevel;
+			if (typeof usage?.percent === "number") snapshot.contextPercent = usage.percent;
+			return snapshot;
+		},
+	};
+	state.current = { bridge, runtime };
 
-	pi.on("message_end", (event) => {
-		agent.captureMessage(event.message);
+	// 每个事件都会带来新的 ExtensionContext；持续刷新，保证远程命令拿到的能力不失效。
+	const trackContext = (_event: unknown, context: ExtensionContext): void => {
+		latestContext = context;
+	};
+	pi.on("session_start", trackContext);
+	pi.on("agent_start", trackContext);
+	pi.on("message_end", (event, context) => {
+		trackContext(event, context);
+		bridge.captureMessage(event.message);
 	});
-	pi.on("message_update", (event) => {
-		agent.captureStreamingMessage(event.message);
+	pi.on("message_update", (event, context) => {
+		trackContext(event, context);
+		bridge.captureStreamingMessage(event.message);
 	});
-	pi.on("tool_execution_start", (event) => {
-		agent.captureToolStart(event.toolName);
+	pi.on("tool_execution_start", (event, context) => {
+		trackContext(event, context);
+		bridge.captureToolStart(event.toolName);
 	});
-	pi.on("tool_execution_end", () => {
-		agent.captureToolEnd();
+	pi.on("tool_execution_end", (event, context) => {
+		trackContext(event, context);
+		bridge.captureToolEnd();
 	});
-	pi.on("agent_settled", () => {
-		agent.settle();
+	pi.on("agent_settled", (event, context) => {
+		trackContext(event, context);
+		bridge.settle();
 	});
-	pi.on("session_shutdown", async () => {
-		await controller.stop();
-		agent.cancel("Pi 会话已关闭。");
+	pi.on("session_shutdown", () => {
+		// 只解绑本会话的桥：长连接归全局 controller 保管，本地 /new 切换会话后自动延续。
+		bridge.cancel("Pi 会话已关闭。");
 	});
 
 	pi.registerCommand("feishu", {
 		description: "配置和管理飞书私聊连接",
 		handler: async (args, context) => {
+			latestCommandContext = context;
 			try {
-				await handleFeishuCommand(parseFeishuCommand(args), controller, context);
+				await handleFeishuCommand(parseFeishuCommand(args), state.controller, context);
 			} catch (error) {
-				context.ui.notify(`飞书操作失败：${controller.sanitizeError(error)}`, "error");
+				context.ui.notify(`飞书操作失败：${state.controller.sanitizeError(error)}`, "error");
 			}
 		},
 	});
 }
 
+function availableModels(context: ExtensionContext | undefined): PiModel[] {
+	const scoped = context?.scopedModels ?? [];
+	if (scoped.length > 0) return scoped.map((entry) => entry.model);
+	return withRuntimeContext(() => context?.modelRegistry.getAvailable()) ?? [];
+}
+
+function resolveModel(query: string, context: ExtensionContext | undefined): PiModel {
+	const candidates = availableModels(context);
+	const needle = query.trim().toLowerCase();
+	if (!needle) throw new Error("请提供模型 ID 或名称，例如 /model sonnet。");
+	if (candidates.length === 0) throw new Error("当前没有可用模型，请先在本地 Pi 配置模型或 API Key。");
+
+	const exact = candidates.filter((model) => model.id.toLowerCase() === needle);
+	if (exact.length === 1 && exact[0]) return exact[0];
+	if (exact.length > 1) throw new Error(`“${query}”匹配到多个模型，请输入更完整的模型 ID。`);
+
+	const fuzzy = candidates.filter(
+		(model) => model.id.toLowerCase().includes(needle) || model.name.toLowerCase().includes(needle),
+	);
+	if (fuzzy.length === 1 && fuzzy[0]) return fuzzy[0];
+	if (fuzzy.length === 0) throw new Error(`未找到匹配“${query}”的模型。`);
+	throw new Error(
+		`“${query}”匹配到多个模型：${fuzzy
+			.slice(0, 3)
+			.map((model) => model.id)
+			.join("、")}…请输入更完整的模型 ID。`,
+	);
+}
+
+function toModelInfo(model: PiModel): PiModelInfo {
+	return { id: model.id, name: model.name || model.id, provider: String(model.provider) };
+}
+
+function isThinkingLevel(value: string): value is PiThinkingLevel {
+	return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+function withRuntimeContext<T>(action: () => T): T | undefined {
+	try {
+		return action();
+	} catch {
+		// 会话切换后捕获的 ctx 会失效，等下一个事件刷新即可。
+		return undefined;
+	}
+}
+
 async function handleFeishuCommand(
 	command: ParsedFeishuCommand,
 	controller: FeishuController,

package/src/gateway.ts

@@ -3,6 +3,7 @@ import type {
 	FeishuCredentials,
 	FeishuGateway,
 	FeishuMessageHandler,
+	FeishuReactionHandler,
 	FeishuReply,
 	FeishuReplySnapshot,
 } from "./contracts.js";
@@ -18,10 +19,16 @@ export interface NormalizedChannelMessage {
 
 export interface ChannelLike {
 	onMessage(handler: (message: NormalizedChannelMessage) => Promise<void> | void): () => void;
+	onReaction(handler: FeishuReactionHandler): () => void;
 	connect(): Promise<void>;
 	disconnect(): Promise<void>;
-	sendText(to: string, text: string, replyTo?: string): Promise<void>;
+	/** Sends text and resolves with the sent Feishu message id (for later recall). */
+	sendText(to: string, text: string, replyTo?: string): Promise<string | undefined>;
 	startCardStream(to: string, card: object, replyTo?: string): Promise<ChannelCardStream>;
+	editText(messageId: string, text: string): Promise<void>;
+	addReaction(messageId: string, emojiType: string): Promise<string>;
+	removeReaction(messageId: string, reactionId: string): Promise<void>;
+	recallMessage(messageId: string): Promise<void>;
 }
 
 export interface ChannelCardStream {
@@ -34,8 +41,10 @@ export type ChannelFactory = (credentials: FeishuCredentials) => ChannelLike;
 export class SdkFeishuGateway implements FeishuGateway {
 	private readonly credentials: FeishuCredentials;
 	private readonly channelFactory: ChannelFactory;
+	private readonly reactionHandlers = new Set<FeishuReactionHandler>();
 	private channel: ChannelLike | undefined;
 	private unsubscribe: (() => void) | undefined;
+	private reactionUnsubscribe: (() => void) | undefined;
 
 	constructor(credentials: FeishuCredentials, channelFactory: ChannelFactory = createOfficialChannel) {
 		this.credentials = credentials;
@@ -55,14 +64,20 @@ export class SdkFeishuGateway implements FeishuGateway {
 				text: message.content,
 			}),
 		);
+		const reactionUnsubscribe = channel.onReaction((event) => {
+			for (const reactionHandler of this.reactionHandlers) reactionHandler(event);
+		});
 		this.channel = channel;
 		this.unsubscribe = unsubscribe;
+		this.reactionUnsubscribe = reactionUnsubscribe;
 		try {
 			await channel.connect();
 		} catch (error) {
 			this.channel = undefined;
 			this.unsubscribe = undefined;
+			this.reactionUnsubscribe = undefined;
 			unsubscribe();
+			reactionUnsubscribe();
 			await channel.disconnect().catch(() => undefined);
 			throw error;
 		}
@@ -73,13 +88,44 @@ export class SdkFeishuGateway implements FeishuGateway {
 		this.channel = undefined;
 		this.unsubscribe?.();
 		this.unsubscribe = undefined;
+		this.reactionUnsubscribe?.();
+		this.reactionUnsubscribe = undefined;
 		if (channel) await channel.disconnect();
 	}
 
-	async sendText(chatId: string, text: string, replyTo?: string): Promise<void> {
+	onReaction(handler: FeishuReactionHandler): () => void {
+		this.reactionHandlers.add(handler);
+		return () => this.reactionHandlers.delete(handler);
+	}
+
+	async sendText(chatId: string, text: string, replyTo?: string): Promise<string | undefined> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		return channel.sendText(chatId, text, replyTo);
+	}
+
+	async addReaction(messageId: string, emojiType: string): Promise<string> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		return channel.addReaction(messageId, emojiType);
+	}
+
+	async removeReaction(messageId: string, reactionId: string): Promise<void> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		await channel.removeReaction(messageId, reactionId);
+	}
+
+	async recallMessage(messageId: string): Promise<void> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		await channel.recallMessage(messageId);
+	}
+
+	async editText(messageId: string, text: string): Promise<void> {
 		const channel = this.channel;
 		if (!channel) throw new Error("飞书长连接尚未启动。");
-		await channel.sendText(chatId, text, replyTo);
+		await channel.editText(messageId, text);
 	}
 
 	async beginReply(chatId: string, replyTo: string): Promise<FeishuReply> {
@@ -139,6 +185,17 @@ class OfficialChannelAdapter implements ChannelLike {
 		return this.channel.on("message", (message) => handler(toChannelMessage(message)));
 	}
 
+	onReaction(handler: FeishuReactionHandler): () => void {
+		return this.channel.on("reaction", (event) =>
+			handler({
+				messageId: event.messageId,
+				operatorOpenId: event.operator.openId,
+				emojiType: event.emojiType,
+				action: event.action,
+			}),
+		);
+	}
+
 	async connect(): Promise<void> {
 		await this.channel.connect();
 	}
@@ -147,8 +204,25 @@ class OfficialChannelAdapter implements ChannelLike {
 		await this.channel.disconnect();
 	}
 
-	async sendText(to: string, text: string, replyTo?: string): Promise<void> {
-		await this.channel.send(to, { text }, replyTo ? { replyTo } : undefined);
+	async sendText(to: string, text: string, replyTo?: string): Promise<string | undefined> {
+		const result = await this.channel.send(to, { text }, replyTo ? { replyTo } : undefined);
+		return result.messageId;
+	}
+
+	async editText(messageId: string, text: string): Promise<void> {
+		await this.channel.editMessage(messageId, text);
+	}
+
+	async addReaction(messageId: string, emojiType: string): Promise<string> {
+		return this.channel.addReaction(messageId, emojiType);
+	}
+
+	async removeReaction(messageId: string, reactionId: string): Promise<void> {
+		await this.channel.removeReaction(messageId, reactionId);
+	}
+
+	async recallMessage(messageId: string): Promise<void> {
+		await this.channel.recallMessage(messageId);
 	}
 
 	async startCardStream(to: string, card: object, replyTo?: string): Promise<ChannelCardStream> {

package/src/remote-commands.ts

@@ -0,0 +1,142 @@
+import type { FeishuStatus, PiRuntime, PiRuntimeSnapshot } from "./contracts.js";
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export const REMOTE_SLASH_COMMANDS: Record<string, string> = {
+	"/help": "显示远程命令帮助",
+	"/new": "新建 Pi 会话（丢弃当前对话上下文）",
+	"/stop": "中止当前任务，并跳过排队中的消息",
+	"/status": "查看飞书连接与 Pi 运行状态",
+	"/compact": "压缩当前会话上下文",
+	"/thinking": "查看或设置思考档位：/thinking [off|minimal|low|medium|high|xhigh|max]",
+	"/model": "查看当前模型，或切换：/model <模型ID或名称>",
+};
+
+export interface ParsedRemoteCommand {
+	name: string;
+	args: string;
+}
+
+export interface RemoteCommandContext {
+	runtime: PiRuntime | undefined;
+	status: () => Promise<FeishuStatus>;
+	/** Aborts queued messages after the current one; returns how many were skipped. */
+	stopQueue?: () => number;
+}
+
+export function parseRemoteCommand(input: string): ParsedRemoteCommand | undefined {
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("/")) return undefined;
+	const separator = trimmed.search(/\s/);
+	const name = separator === -1 ? trimmed : trimmed.slice(0, separator);
+	const args = separator === -1 ? "" : trimmed.slice(separator + 1).trim();
+	return { name: name.toLowerCase(), args };
+}
+
+export function renderRemoteHelp(): string {
+	const lines = Object.entries(REMOTE_SLASH_COMMANDS).map(([name, description]) => `  ${name} — ${description}`);
+	return ["飞书远程命令：", ...lines, "", "其余消息会直接发送给当前 Pi 会话处理。"].join("\n");
+}
+
+export function renderRemoteStatus(status: FeishuStatus, snapshot: PiRuntimeSnapshot | undefined): string {
+	const lines = ["飞书状态", `  连接：${status.running ? "已连接" : "未连接"}`, `  队列：${status.pendingMessages}`];
+	if (status.configured) {
+		lines.push(`  Owner：${status.ownerOpenId ? "已绑定" : "未绑定"}`);
+		lines.push("Pi 状态");
+		lines.push(`  模型：${snapshot?.model ?? "未知"}`);
+		lines.push(`  思考：${snapshot?.thinkingLevel ?? "未知"}`);
+		lines.push(`  上下文：${formatContextPercent(snapshot?.contextPercent)}`);
+		lines.push(`  运行：${snapshot?.streaming ? "运行中" : "空闲"}`);
+	}
+	return lines.join("\n");
+}
+
+export async function executeRemoteCommand(input: string, context: RemoteCommandContext): Promise<string> {
+	const command = parseRemoteCommand(input);
+	if (!command) return unknownCommandReply(input);
+	switch (command.name) {
+		case "/help":
+			return renderRemoteHelp();
+		case "/status": {
+			const status = await context.status();
+			return renderRemoteStatus(status, context.runtime?.snapshot());
+		}
+		case "/stop":
+			return executeStop(context);
+		case "/compact":
+			return executeCompact(context.runtime);
+		case "/new":
+			return executeNewSession(context.runtime);
+		case "/thinking":
+			return executeThinking(command.args, context.runtime);
+		case "/model":
+			return executeModel(command.args, context.runtime);
+		default:
+			return unknownCommandReply(command.name);
+	}
+}
+
+function executeStop(context: RemoteCommandContext): string {
+	const runtime = context.runtime;
+	const running = Boolean(runtime && !runtime.isIdle());
+	if (running) runtime?.abort();
+	const skipped = context.stopQueue?.() ?? 0;
+	if (!running && skipped === 0) return "当前没有正在运行的 Pi 任务。";
+	const suffix = skipped > 0 ? `，并跳过队列中的 ${skipped} 条消息` : "";
+	return `已发送中止信号${suffix}。`;
+}
+
+function executeCompact(runtime: PiRuntime | undefined): string {
+	if (!runtime) return "Pi 运行时尚未就绪，请稍后再试。";
+	runtime.compact();
+	return "已开始压缩上下文，完成后继续对话即可。";
+}
+
+async function executeNewSession(runtime: PiRuntime | undefined): Promise<string> {
+	if (!runtime) return "远程新建会话暂不可用：请先在本地 Pi 执行任意 /feishu 命令，再通过飞书发送 /new。";
+	const created = await runtime.newSession();
+	return created
+		? "已新建 Pi 会话，接下来是一个全新的对话。"
+		: "新建会话未完成（本地已取消或暂不可用）。请在本地 Pi 执行 /feishu 命令后重试。";
+}
+
+async function executeThinking(args: string, runtime: PiRuntime | undefined): Promise<string> {
+	const levels = THINKING_LEVELS.join(" / ");
+	if (!args) {
+		const current = runtime?.snapshot().thinkingLevel;
+		const line = current ? `当前思考档位：${current}` : "当前思考档位未知。";
+		return `${line}\n可用档位：${levels}\n示例：/thinking high`;
+	}
+	if (!runtime) return "Pi 运行时尚未就绪，请稍后再试。";
+	const level = args.toLowerCase();
+	const applied = await runtime.setThinkingLevel(level);
+	return applied ? `已切换思考档位：${level}。` : `无法设置思考档位“${args}”。\n可用档位：${levels}`;
+}
+
+async function executeModel(args: string, runtime: PiRuntime | undefined): Promise<string> {
+	if (!runtime) return "Pi 运行时尚未就绪，请稍后再试。";
+	if (!args) {
+		const current = runtime.snapshot().model;
+		const models = runtime.listModels();
+		const hint =
+			models.length > 0
+				? `共 ${models.length} 个可用模型，使用 /model <模型ID或名称> 切换。`
+				: "使用 /model <模型ID或名称> 切换。";
+		return current ? `当前模型：${current}\n${hint}` : `当前模型未知。\n${hint}`;
+	}
+	try {
+		const model = await runtime.switchModel(args);
+		return `已切换模型：${model.name}（${model.id}）。`;
+	} catch (error) {
+		return `切换模型失败：${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+
+function unknownCommandReply(input: string): string {
+	return `❓ 未知命令：${input.trim().split(/\s+/)[0]}\n\n输入 /help 查看可用命令。`;
+}
+
+function formatContextPercent(percent: number | undefined): string {
+	if (percent === undefined || percent === null || Number.isNaN(percent)) return "未知";
+	return `${Math.round(percent)}%`;
+}