@hwj123weijian/pi-feishu 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-feishu
 
-一个独立、极简的 [Pi](https://github.com/earendil-works/pi-mono) 飞书扩展。它通过飞书官方 Node SDK 的 WebSocket 长连接，把飞书私聊文本转发到当前 Pi 会话，并把最终回复发回原私聊。
+一个独立的 [Pi](https://github.com/earendil-works/pi-mono) 飞书扩展。它通过飞书官方 Node SDK 的 WebSocket 长连接，把飞书私聊文本转发到当前 Pi 会话，并以持续更新的交互卡片展示 Pi 的回复和执行状态。
 
 ## 设计边界
 
@@ -9,6 +9,10 @@
 - 仅处理飞书私聊（`p2p`）文本消息
 - 首次启动生成一次性绑定码，只允许一个 Owner
 - 所有消息进入当前 Pi 会话，不创建额外 Agent 或会话
+- Assistant 文本通过 Pi 的 `message_update` 增量渲染到同一张飞书卡片
+- 工具执行时仅显示安全的状态摘要，不展示参数、命令、文件内容或工具输出
+- SDK 以 500ms / 120 字符节流卡片更新；完成、失败、中止都会收尾卡片
+- 缺少更新权限或飞书卡片更新失败时，自动退化为原私聊的一次性文本回复
 - 串行处理消息，避免多条飞书消息同时驱动 Pi
 - 按飞书 `message_id` 去重
 - `/feishu stop`、`/feishu logout` 和 Pi 会话关闭时释放长连接
@@ -30,11 +34,12 @@
 2. 在“权限管理”中申请：
    - `im:message.p2p_msg:readonly`：接收私聊消息
    - `im:message:send_as_bot`：以机器人身份回复
+   - `im:message:update`：持续更新机器人发出的交互卡片
 3. 在“事件与回调”中选择“使用长连接接收事件”。
 4. 添加事件 `im.message.receive_v1`。
 5. 创建并发布一个应用版本，使权限和事件订阅在企业内生效。
 
-这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。
+这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。若未授予 `im:message:update`，扩展仍可工作，但会降级为最终文本一次性回复。
 
 ## 安装
 
@@ -88,7 +93,7 @@ pi -e D:\ai_study\pi-feishu
 /bind 123456
 ```
 
-绑定成功后，直接私聊机器人即可驱动当前 Pi 会话。
+绑定成功后，直接私聊机器人即可驱动当前 Pi 会话。处理过程中会先显示“正在思考”，随后持续更新正文；Pi 调用工具时卡片会显示“正在执行工具”，最终状态会变为“已完成”。
 
 也支持手动参数：
 
@@ -131,6 +136,10 @@ pi -e D:\ai_study\pi-feishu
 
 确认已申请并发布 `im:message:send_as_bot` 权限。
 
+### 只能收到最终文本，没有流式卡片
+
+确认已申请并发布 `im:message:update`。卡片初始化或更新失败时，扩展会自动改为最终文本回复，避免用户没有任何反馈。
+
 ### Bot 提示“未授权”
 
 该 Bot 已绑定其他 Owner。若要重新绑定，先在本地 Pi 执行 `/feishu logout`，再重新 `setup`、`start` 和 `/bind`。
@@ -147,7 +156,7 @@ npm test
 npm run build
 ```
 
-测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、去重、完整消息链路、错误脱敏和清理行为。
+测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、去重、Pi 增量文本、工具状态、流式卡片收尾、降级、错误脱敏和清理行为。
 
 ## 许可证
 

package/package.json

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

package/src/contracts.ts

@@ -21,14 +21,34 @@ export interface FeishuIncomingMessage {
 
 export type FeishuMessageHandler = (message: FeishuIncomingMessage) => Promise<void> | void;
 
+export interface FeishuReplySnapshot {
+	text: string;
+	status: "正在思考" | "正在生成回复" | "正在执行工具" | "已完成" | "处理失败" | "已取消";
+}
+
+export interface FeishuReply {
+	update(snapshot: FeishuReplySnapshot): void;
+	complete(snapshot: FeishuReplySnapshot): Promise<void>;
+	fail(): Promise<void>;
+	cancel(): Promise<void>;
+}
+
 export interface FeishuGateway {
 	connect(handler: FeishuMessageHandler): Promise<void>;
 	disconnect(): Promise<void>;
 	sendText(chatId: string, text: string, replyTo?: string): Promise<void>;
+	beginReply(chatId: string, replyTo: string): Promise<FeishuReply>;
+}
+
+export type AgentActivity = { kind: "thinking" } | { kind: "tool"; toolName: string };
+
+export interface AgentProgressObserver {
+	onText?: (text: string) => void;
+	onActivity?: (activity: AgentActivity) => void;
 }
 
 export interface AgentBridge {
-	run(text: string): Promise<string>;
+	run(text: string, observer?: AgentProgressObserver): Promise<string>;
 	cancel(reason?: string): void;
 }
 

package/src/controller.ts

@@ -7,6 +7,7 @@ import type {
 	FeishuGateway,
 	FeishuGatewayFactory,
 	FeishuIncomingMessage,
+	FeishuReply,
 } from "./contracts.js";
 import { CredentialError, errorMessage, resolveCredentialInput, resolveRuntimeCredentials } from "./credentials.js";
 import { MessageDeduplicator } from "./message-deduplicator.js";
@@ -46,6 +47,7 @@ export class FeishuController {
 	private gateway: FeishuGateway | undefined;
 	private credentials: FeishuCredentials | undefined;
 	private binding: OwnerBinding | undefined;
+	private readonly activeReplies = new Set<FeishuReply>();
 
 	constructor(options: FeishuControllerOptions) {
 		this.store = options.store;
@@ -107,6 +109,8 @@ export class FeishuController {
 	async stop(): Promise<boolean> {
 		const gateway = this.gateway;
 		if (!gateway) return false;
+		await Promise.all([...this.activeReplies].map((reply) => reply.cancel().catch(() => undefined)));
+		this.activeReplies.clear();
 		this.gateway = undefined;
 		this.binding = undefined;
 		this.agent.cancel("飞书连接已停止。");
@@ -163,15 +167,39 @@ export class FeishuController {
 			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);
+						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) {
-							await gateway.sendText(message.chatId, response, message.messageId);
+							if (reply) {
+								await reply.complete({ text: response, status: "已完成" });
+							} else {
+								await gateway.sendText(message.chatId, response, message.messageId);
+							}
 						}
 					} catch {
 						if (this.gateway === gateway) {
-							await this.safeSend(gateway, message, "处理消息失败，请稍后再试。");
+							if (reply) {
+								await reply.fail();
+							} else {
+								await this.safeSend(gateway, message, "处理消息失败，请稍后再试。");
+							}
 						}
+					} finally {
+						if (reply) this.activeReplies.delete(reply);
 					}
 				});
 		}

package/src/extension.ts

@@ -78,6 +78,15 @@ export default function feishuExtension(pi: ExtensionAPI): void {
 	pi.on("message_end", (event) => {
 		agent.captureMessage(event.message);
 	});
+	pi.on("message_update", (event) => {
+		agent.captureStreamingMessage(event.message);
+	});
+	pi.on("tool_execution_start", (event) => {
+		agent.captureToolStart(event.toolName);
+	});
+	pi.on("tool_execution_end", () => {
+		agent.captureToolEnd();
+	});
 	pi.on("agent_settled", () => {
 		agent.settle();
 	});

package/src/gateway.ts

@@ -1,5 +1,11 @@
 import { createLarkChannel, type LarkChannel, LoggerLevel, type NormalizedMessage } from "@larksuiteoapi/node-sdk";
-import type { FeishuCredentials, FeishuGateway, FeishuMessageHandler } from "./contracts.js";
+import type {
+	FeishuCredentials,
+	FeishuGateway,
+	FeishuMessageHandler,
+	FeishuReply,
+	FeishuReplySnapshot,
+} from "./contracts.js";
 
 export interface NormalizedChannelMessage {
 	messageId: string;
@@ -15,6 +21,12 @@ export interface ChannelLike {
 	connect(): Promise<void>;
 	disconnect(): Promise<void>;
 	sendText(to: string, text: string, replyTo?: string): Promise<void>;
+	startCardStream(to: string, card: object, replyTo?: string): Promise<ChannelCardStream>;
+}
+
+export interface ChannelCardStream {
+	update(card: object): Promise<void>;
+	finish(): Promise<void>;
 }
 
 export type ChannelFactory = (credentials: FeishuCredentials) => ChannelLike;
@@ -69,6 +81,14 @@ export class SdkFeishuGateway implements FeishuGateway {
 		if (!channel) throw new Error("飞书长连接尚未启动。");
 		await channel.sendText(chatId, text, replyTo);
 	}
+
+	async beginReply(chatId: string, replyTo: string): Promise<FeishuReply> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		const initial = { text: "", status: "正在思考" } satisfies FeishuReplySnapshot;
+		const stream = await channel.startCardStream(chatId, buildReplyCard(initial), replyTo);
+		return new SdkFeishuReply(stream, channel, chatId, replyTo, initial);
+	}
 }
 
 export async function validateSdkCredentials(
@@ -92,6 +112,10 @@ function createOfficialChannel(credentials: FeishuCredentials): ChannelLike {
 			handshakeTimeoutMs: 10_000,
 			loggerLevel: LoggerLevel.error,
 			source: "pi-feishu",
+			outbound: {
+				streamThrottleMs: 500,
+				streamThrottleChars: 120,
+			},
 			policy: {
 				dmMode: "open",
 				groupAllowlist: [],
@@ -126,6 +150,150 @@ class OfficialChannelAdapter implements ChannelLike {
 	async sendText(to: string, text: string, replyTo?: string): Promise<void> {
 		await this.channel.send(to, { text }, replyTo ? { replyTo } : undefined);
 	}
+
+	async startCardStream(to: string, card: object, replyTo?: string): Promise<ChannelCardStream> {
+		const stream = new OfficialChannelCardStream(this.channel, to, card, replyTo);
+		await stream.start();
+		return stream;
+	}
+}
+
+interface CardStreamControllerLike {
+	update(card: object): Promise<void>;
+}
+
+class OfficialChannelCardStream implements ChannelCardStream {
+	private controller: CardStreamControllerLike | undefined;
+	private resolveOpened: (() => void) | undefined;
+	private resolveProducer: (() => void) | undefined;
+	private readonly opened: Promise<void>;
+	private readonly producerCompleted: Promise<void>;
+	private readonly stream: Promise<void>;
+
+	constructor(channel: LarkChannel, to: string, card: object, replyTo?: string) {
+		this.opened = new Promise<void>((resolve) => {
+			this.resolveOpened = resolve;
+		});
+		this.producerCompleted = new Promise<void>((resolve) => {
+			this.resolveProducer = resolve;
+		});
+		this.stream = channel
+			.stream(
+				to,
+				{
+					card: {
+						initial: card,
+						producer: async (controller) => {
+							this.controller = controller;
+							this.resolveOpened?.();
+							await this.producerCompleted;
+						},
+					},
+				},
+				replyTo ? { replyTo } : undefined,
+			)
+			.then(() => undefined);
+	}
+
+	async start(): Promise<void> {
+		await Promise.race([this.opened, this.stream]);
+	}
+
+	async update(card: object): Promise<void> {
+		const controller = this.controller;
+		if (!controller) throw new Error("飞书流式回复尚未准备完成。");
+		await controller.update(card);
+	}
+
+	async finish(): Promise<void> {
+		this.resolveProducer?.();
+		await this.stream;
+	}
+}
+
+class SdkFeishuReply implements FeishuReply {
+	private snapshot: FeishuReplySnapshot;
+	private terminal = false;
+	private updateFailed = false;
+
+	constructor(
+		private readonly stream: ChannelCardStream,
+		private readonly channel: ChannelLike,
+		private readonly chatId: string,
+		private readonly replyTo: string,
+		initial: FeishuReplySnapshot,
+	) {
+		this.snapshot = initial;
+	}
+
+	update(snapshot: FeishuReplySnapshot): void {
+		if (this.terminal) return;
+		this.snapshot = snapshot;
+		void this.stream.update(buildReplyCard(snapshot)).catch(() => {
+			this.updateFailed = true;
+		});
+	}
+
+	async complete(snapshot: FeishuReplySnapshot): Promise<void> {
+		await this.finish(snapshot, snapshot.text || "Pi 已完成处理，但没有返回文本内容。");
+	}
+
+	async fail(): Promise<void> {
+		await this.finish(
+			{ text: this.snapshot.text || "处理消息失败，请稍后再试。", status: "处理失败" },
+			"处理消息失败，请稍后再试。",
+		);
+	}
+
+	async cancel(): Promise<void> {
+		await this.finish({ text: this.snapshot.text || "任务已取消。", status: "已取消" }, "任务已取消。");
+	}
+
+	private async finish(snapshot: FeishuReplySnapshot, fallbackText: string): Promise<void> {
+		if (this.terminal) return;
+		this.terminal = true;
+		this.snapshot = snapshot;
+		try {
+			if (!this.updateFailed) await this.stream.update(buildReplyCard(snapshot));
+			await this.stream.finish();
+		} catch {
+			await this.channel.sendText(this.chatId, fallbackText, this.replyTo).catch(() => undefined);
+		}
+	}
+}
+
+export function buildReplyCard(snapshot: FeishuReplySnapshot): object {
+	const content = snapshot.text.trim() || statusPlaceholder(snapshot.status);
+	return {
+		config: { wide_screen_mode: true },
+		header: {
+			title: { tag: "plain_text", content: "Pi" },
+			template: headerTemplate(snapshot.status),
+		},
+		elements: [
+			{ tag: "markdown", content },
+			{
+				tag: "note",
+				elements: [{ tag: "plain_text", content: snapshot.status }],
+			},
+		],
+	};
+}
+
+function statusPlaceholder(status: FeishuReplySnapshot["status"]): string {
+	if (status === "正在执行工具") return "正在执行工具…";
+	if (status === "正在生成回复") return "正在生成回复…";
+	if (status === "已取消") return "任务已取消。";
+	if (status === "处理失败") return "处理消息失败，请稍后再试。";
+	if (status === "已完成") return "Pi 已完成处理，但没有返回文本内容。";
+	return "正在思考…";
+}
+
+function headerTemplate(status: FeishuReplySnapshot["status"]): "blue" | "green" | "red" | "grey" {
+	if (status === "已完成") return "green";
+	if (status === "处理失败") return "red";
+	if (status === "已取消") return "grey";
+	return "blue";
 }
 
 function toChannelMessage(message: NormalizedMessage): NormalizedChannelMessage {

package/src/pi-agent-bridge.ts

@@ -1,9 +1,10 @@
-import type { AgentBridge } from "./contracts.js";
+import type { AgentBridge, AgentProgressObserver } from "./contracts.js";
 
 interface PendingTurn {
 	resolve: (text: string) => void;
 	reject: (error: Error) => void;
 	lastAssistantText: string;
+	observer: AgentProgressObserver | undefined;
 }
 
 export class PiAgentBridge implements AgentBridge {
@@ -14,13 +15,14 @@ export class PiAgentBridge implements AgentBridge {
 		this.sendUserMessage = sendUserMessage;
 	}
 
-	run(text: string): Promise<string> {
+	run(text: string, observer?: AgentProgressObserver): Promise<string> {
 		if (this.pending) {
 			return Promise.reject(new Error("已有飞书消息正在等待 Pi 回复。"));
 		}
 
 		return new Promise<string>((resolve, reject) => {
-			this.pending = { resolve, reject, lastAssistantText: "" };
+			this.pending = { resolve, reject, lastAssistantText: "", observer };
+			observer?.onActivity?.({ kind: "thinking" });
 			try {
 				this.sendUserMessage(text);
 			} catch (error) {
@@ -31,12 +33,32 @@ export class PiAgentBridge implements AgentBridge {
 	}
 
 	captureMessage(message: unknown): void {
-		if (!this.pending || !isAssistantMessage(message)) return;
+		this.captureAssistantText(message);
+	}
+
+	captureStreamingMessage(message: unknown): void {
+		this.captureAssistantText(message);
+	}
+
+	captureToolStart(toolName: string): void {
+		this.pending?.observer?.onActivity?.({ kind: "tool", toolName });
+	}
+
+	captureToolEnd(): void {
+		this.pending?.observer?.onActivity?.({ kind: "thinking" });
+	}
+
+	private captureAssistantText(message: unknown): void {
+		const pending = this.pending;
+		if (!pending || !isAssistantMessage(message)) return;
 		const text = message.content
 			.filter(isTextContent)
 			.map((item) => item.text)
 			.join("");
-		if (text.trim()) this.pending.lastAssistantText = text.trim();
+		const normalized = text.trim();
+		if (!normalized || normalized === pending.lastAssistantText) return;
+		pending.lastAssistantText = normalized;
+		pending.observer?.onText?.(normalized);
 	}
 
 	settle(): void {