@hwj123weijian/pi-feishu 0.1.0

package/.env.example

@@ -0,0 +1,2 @@
+FEISHU_APP_ID=cli_your_app_id
+FEISHU_APP_SECRET=your_app_secret

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-feishu contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# pi-feishu
+
+一个独立、极简的 [Pi](https://github.com/earendil-works/pi-mono) 飞书扩展。它通过飞书官方 Node SDK 的 WebSocket 长连接，把飞书私聊文本转发到当前 Pi 会话，并把最终回复发回原私聊。
+
+## 设计边界
+
+当前版本只做一条可靠的最小链路：
+
+- 仅处理飞书私聊（`p2p`）文本消息
+- 首次启动生成一次性绑定码，只允许一个 Owner
+- 所有消息进入当前 Pi 会话，不创建额外 Agent 或会话
+- 串行处理消息，避免多条飞书消息同时驱动 Pi
+- 按飞书 `message_id` 去重
+- `/feishu stop`、`/feishu logout` 和 Pi 会话关闭时释放长连接
+- 凭据优先从环境变量读取，也可保存到本地凭据文件
+
+当前不支持群聊、图片、文件、卡片、语音、多用户、多会话、进程级沙箱或远程命令权限管理。这里的安全边界是“私聊 + 单 Owner”，Pi 本身仍拥有当前本地进程的权限。
+
+## 环境要求
+
+- Node.js 22.19 或更高版本
+- Pi 0.83.0 或兼容版本
+- 一个启用了机器人能力的飞书企业自建应用
+
+## 飞书后台配置
+
+在[飞书开放平台](https://open.feishu.cn/app)创建企业自建应用，然后完成以下配置：
+
+1. 在“添加应用能力”中启用机器人。
+2. 在“权限管理”中申请：
+   - `im:message.p2p_msg:readonly`：接收私聊消息
+   - `im:message:send_as_bot`：以机器人身份回复
+3. 在“事件与回调”中选择“使用长连接接收事件”。
+4. 添加事件 `im.message.receive_v1`。
+5. 创建并发布一个应用版本，使权限和事件订阅在企业内生效。
+
+这个扩展不需要公网回调地址，也不需要加密密钥或 Verification Token。
+
+## 安装
+
+在项目目录安装依赖：
+
+```powershell
+cd D:\ai_study\pi-feishu
+npm install --ignore-scripts
+```
+
+开发时可以仅为本次启动加载：
+
+```powershell
+pi -e D:\ai_study\pi-feishu
+```
+
+也可以把本地包注册到 Pi：
+
+```powershell
+pi install D:\ai_study\pi-feishu
+pi
+```
+
+发布版本可直接从 npm 安装：
+
+```powershell
+pi install npm:@hwj123weijian/pi-feishu
+pi
+```
+
+## 配置与首次绑定
+
+推荐用环境变量提供敏感凭据：
+
+```powershell
+$env:FEISHU_APP_ID = "cli_xxxxxxxxxxxxx"
+$env:FEISHU_APP_SECRET = "xxxxxxxxxxxxxxxx"
+pi -e D:\ai_study\pi-feishu
+```
+
+进入 Pi 后依次执行：
+
+```text
+/feishu setup
+/feishu start
+```
+
+`start` 会在本地 Pi 中显示六位一次性绑定码。使用计划作为 Owner 的飞书账号私聊机器人：
+
+```text
+/bind 123456
+```
+
+绑定成功后，直接私聊机器人即可驱动当前 Pi 会话。
+
+也支持手动参数：
+
+```text
+/feishu setup cli_xxxxxxxxxxxxx xxxxxxxxxxxxxxxx
+```
+
+这种方式可能让 App Secret 出现在终端历史中，因此环境变量更合适。验证成功后，凭据默认保存到：
+
+```text
+~/.pi/agent/feishu/credentials.json
+```
+
+文件通过临时文件原子替换写入；在支持 POSIX 权限的平台上会限制为 `0600`。
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/feishu` | 显示帮助和当前状态 |
+| `/feishu setup [appId appSecret]` | 验证并保存飞书应用凭据 |
+| `/feishu start` | 建立 WebSocket 长连接并显示绑定码 |
+| `/feishu stop` | 停止长连接，保留凭据与 Owner |
+| `/feishu status` | 查看配置、连接、Owner 和队列状态 |
+| `/feishu logout` | 停止连接并清除本地凭据和 Owner |
+
+环境变量优先于凭据文件。如果环境变量中的 App ID 与已保存的 App ID 不同，旧 Owner 绑定不会被继承。
+
+## 常见问题
+
+### `setup` 或 `start` 连接失败
+
+检查 App ID 和 App Secret 是否来自同一个应用，并确认应用版本已经发布。`setup` 会实际建立一次临时 WebSocket 连接来验证凭据，而不只是检查字符串格式。
+
+### 机器人收不到私聊消息
+
+确认已启用机器人能力、订阅 `im.message.receive_v1`、接收方式为长连接，并已发布包含这些配置的应用版本。
+
+### 能收到消息但不能回复
+
+确认已申请并发布 `im:message:send_as_bot` 权限。
+
+### Bot 提示“未授权”
+
+该 Bot 已绑定其他 Owner。若要重新绑定，先在本地 Pi 执行 `/feishu logout`，再重新 `setup`、`start` 和 `/bind`。
+
+### 重复消息
+
+飞书事件可能重投。扩展在当前进程内缓存最近 1000 个 `message_id`，重复事件不会再次驱动 Pi。重启 Pi 后缓存会清空。
+
+## 开发
+
+```powershell
+npm run check
+npm test
+npm run build
+```
+
+测试使用 Fake Gateway 和 Fake Agent，不需要真实飞书凭据，覆盖凭据处理、Owner 绑定、私聊过滤、串行队列、去重、完整消息链路、错误脱敏和清理行为。
+
+## 许可证
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@hwj123weijian/pi-feishu",
+	"version": "0.1.0",
+	"description": "Minimal Feishu private-chat bridge for Pi",
+	"type": "module",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"keywords": [
+		"pi-package",
+		"feishu",
+		"coding-agent"
+	],
+	"pi": {
+		"extensions": [
+			"./src/extension.ts"
+		]
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE",
+		".env.example"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"check": "biome check . && tsc --noEmit",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@larksuiteoapi/node-sdk": "1.72.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "0.83.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.5",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@types/node": "24.12.4",
+		"typescript": "5.9.3",
+		"vitest": "4.1.9"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/src/contracts.ts

@@ -0,0 +1,37 @@
+export interface FeishuCredentials {
+	appId: string;
+	appSecret: string;
+	ownerOpenId?: string;
+}
+
+export interface CredentialStore {
+	load(): Promise<FeishuCredentials | null>;
+	save(credentials: FeishuCredentials): Promise<void>;
+	clear(): Promise<void>;
+}
+
+export interface FeishuIncomingMessage {
+	messageId: string;
+	chatId: string;
+	chatType: "p2p" | "group";
+	senderOpenId: string;
+	contentType: string;
+	text: string;
+}
+
+export type FeishuMessageHandler = (message: FeishuIncomingMessage) => Promise<void> | void;
+
+export interface FeishuGateway {
+	connect(handler: FeishuMessageHandler): Promise<void>;
+	disconnect(): Promise<void>;
+	sendText(chatId: string, text: string, replyTo?: string): Promise<void>;
+}
+
+export interface AgentBridge {
+	run(text: string): Promise<string>;
+	cancel(reason?: string): void;
+}
+
+export type FeishuGatewayFactory = (credentials: FeishuCredentials) => FeishuGateway;
+export type CredentialValidator = (credentials: FeishuCredentials) => Promise<void>;
+export type Environment = Readonly<Record<string, string | undefined>>;

package/src/controller.ts

@@ -0,0 +1,203 @@
+import type {
+	AgentBridge,
+	CredentialStore,
+	CredentialValidator,
+	Environment,
+	FeishuCredentials,
+	FeishuGateway,
+	FeishuGatewayFactory,
+	FeishuIncomingMessage,
+} 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";
+
+export interface FeishuControllerOptions {
+	store: CredentialStore;
+	gatewayFactory: FeishuGatewayFactory;
+	validateCredentials: CredentialValidator;
+	agent: AgentBridge;
+	generateBindingCode?: () => string;
+}
+
+export interface FeishuStartResult {
+	alreadyRunning: boolean;
+	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 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;
+
+	constructor(options: FeishuControllerOptions) {
+		this.store = options.store;
+		this.gatewayFactory = options.gatewayFactory;
+		this.validateCredentials = options.validateCredentials;
+		this.agent = options.agent;
+		this.generateBindingCode = options.generateBindingCode;
+	}
+
+	async setup(args: string, environment: Environment): Promise<FeishuCredentials> {
+		const input = resolveCredentialInput(args, environment);
+		const credentials: FeishuCredentials = { appId: input.appId, appSecret: input.appSecret };
+		try {
+			await this.validateCredentials(credentials);
+		} catch (error) {
+			throw new CredentialError(`飞书凭据验证失败：${errorMessage(error, credentials)}`);
+		}
+
+		const existing = await this.store.load();
+		const next =
+			existing?.appId === credentials.appId && existing.ownerOpenId
+				? { ...credentials, ownerOpenId: existing.ownerOpenId }
+				: credentials;
+		await this.store.save(next);
+		this.credentials = next;
+		this.binding = new OwnerBinding(next.ownerOpenId, this.generateBindingCode);
+		return next;
+	}
+
+	async start(environment: Environment): Promise<FeishuStartResult> {
+		if (this.gateway) return { alreadyRunning: true };
+
+		const stored = await this.store.load();
+		const credentials = resolveRuntimeCredentials(environment, stored);
+		if (!credentials) {
+			throw new CredentialError("尚未配置飞书凭据，请先执行 /feishu setup。");
+		}
+
+		const binding = new OwnerBinding(credentials.ownerOpenId, this.generateBindingCode);
+		const gateway = this.gatewayFactory(credentials);
+		this.credentials = credentials;
+		this.binding = binding;
+		this.gateway = gateway;
+		this.deduplicator.clear();
+
+		try {
+			await gateway.connect((message) => this.handleIncoming(message));
+		} catch (error) {
+			this.gateway = undefined;
+			this.binding = undefined;
+			await gateway.disconnect().catch(() => undefined);
+			throw new CredentialError(`启动飞书长连接失败：${errorMessage(error, credentials)}`);
+		}
+
+		const bindingCode = binding.getOrCreateCode();
+		return bindingCode ? { alreadyRunning: false, bindingCode } : { alreadyRunning: false };
+	}
+
+	async stop(): Promise<boolean> {
+		const gateway = this.gateway;
+		if (!gateway) return false;
+		this.gateway = undefined;
+		this.binding = undefined;
+		this.agent.cancel("飞书连接已停止。");
+		await gateway.disconnect();
+		return true;
+	}
+
+	async logout(): Promise<void> {
+		const stopped = await this.stop();
+		if (!stopped) this.agent.cancel("飞书已退出。");
+		this.credentials = undefined;
+		await this.store.clear();
+	}
+
+	async status(environment: Environment): Promise<FeishuStatus> {
+		const stored = await this.store.load();
+		const resolved = resolveRuntimeCredentials(environment, stored);
+		if (!resolved) {
+			return { configured: false, running: Boolean(this.gateway), pendingMessages: this.queue.pendingCount };
+		}
+		const source = environment.FEISHU_APP_ID?.trim() && environment.FEISHU_APP_SECRET?.trim() ? "environment" : "file";
+		const result: FeishuStatus = {
+			configured: true,
+			running: Boolean(this.gateway),
+			appId: resolved.appId,
+			source,
+			pendingMessages: this.queue.pendingCount,
+		};
+		if (resolved.ownerOpenId) result.ownerOpenId = resolved.ownerOpenId;
+		return result;
+	}
+
+	async handleIncoming(message: FeishuIncomingMessage): Promise<void> {
+		const gateway = this.gateway;
+		const binding = this.binding;
+		if (!gateway || !binding || message.chatType !== "p2p" || message.contentType !== "text") return;
+		if (!message.messageId || !this.deduplicator.accept(message.messageId)) return;
+
+		const authorization = binding.authorize(message.senderOpenId, message.text);
+		switch (authorization.kind) {
+			case "binding-required":
+				await this.safeSend(gateway, message, "Bot 尚未绑定，请在本地 Pi 查看一次性绑定码。");
+				return;
+			case "invalid-binding-code":
+				await this.safeSend(gateway, message, "绑定码无效，请检查本地 Pi 显示的一次性绑定码。");
+				return;
+			case "unauthorized":
+				await this.safeSend(gateway, message, "未授权：此 Bot 仅响应已绑定的 Owner。");
+				return;
+			case "bound":
+				await this.persistOwner(authorization.ownerOpenId);
+				await this.safeSend(gateway, message, "绑定成功，现在可以直接发送问题。");
+				return;
+			case "authorized":
+				void this.queue.enqueue(async () => {
+					if (this.gateway !== gateway) return;
+					try {
+						const response = await this.agent.run(authorization.text);
+						if (this.gateway === gateway) {
+							await gateway.sendText(message.chatId, response, message.messageId);
+						}
+					} catch {
+						if (this.gateway === gateway) {
+							await this.safeSend(gateway, message, "处理消息失败，请稍后再试。");
+						}
+					}
+				});
+		}
+	}
+
+	async waitForIdle(): Promise<void> {
+		await this.queue.waitForIdle();
+	}
+
+	sanitizeError(error: unknown): string {
+		return errorMessage(error, this.credentials);
+	}
+
+	private async persistOwner(ownerOpenId: string): Promise<void> {
+		const credentials = this.credentials;
+		if (!credentials) return;
+		const next = { ...credentials, ownerOpenId };
+		await this.store.save(next);
+		this.credentials = next;
+	}
+
+	private async safeSend(gateway: FeishuGateway, message: FeishuIncomingMessage, text: string): Promise<void> {
+		try {
+			await gateway.sendText(message.chatId, text, message.messageId);
+		} catch {
+			// The inbound event has already been acknowledged; outbound failures are non-fatal.
+		}
+	}
+}

package/src/credentials.ts

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { CredentialStore, Environment, FeishuCredentials } from "./contracts.js";
+
+const APP_ID_PATTERN = /^cli_[A-Za-z0-9_-]+$/;
+
+export class CredentialError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CredentialError";
+	}
+}
+
+export interface CredentialInput extends FeishuCredentials {
+	source: "arguments" | "environment";
+}
+
+export function parseSetupArguments(args: string): FeishuCredentials | null {
+	const trimmed = args.trim();
+	if (!trimmed) return null;
+
+	const parts = trimmed.split(/\s+/);
+	if (parts.length !== 2) {
+		throw new CredentialError("用法：/feishu setup <appId> <appSecret>，或设置 FEISHU_APP_ID/FEISHU_APP_SECRET。");
+	}
+
+	const appId = parts[0] ?? "";
+	const appSecret = parts[1] ?? "";
+	validateCredentialShape({ appId, appSecret });
+	return { appId, appSecret };
+}
+
+export function resolveCredentialInput(args: string, environment: Environment): CredentialInput {
+	const explicit = parseSetupArguments(args);
+	if (explicit) return { ...explicit, source: "arguments" };
+
+	const appId = environment.FEISHU_APP_ID?.trim() ?? "";
+	const appSecret = environment.FEISHU_APP_SECRET?.trim() ?? "";
+	if (!appId && !appSecret) {
+		throw new CredentialError(
+			"未提供飞书凭据。请设置 FEISHU_APP_ID、FEISHU_APP_SECRET，或使用 /feishu setup <appId> <appSecret>。",
+		);
+	}
+	if (!appId || !appSecret) {
+		throw new CredentialError("FEISHU_APP_ID 和 FEISHU_APP_SECRET 必须同时设置。");
+	}
+	validateCredentialShape({ appId, appSecret });
+	return { appId, appSecret, source: "environment" };
+}
+
+export function resolveRuntimeCredentials(
+	environment: Environment,
+	stored: FeishuCredentials | null,
+): FeishuCredentials | null {
+	const appId = environment.FEISHU_APP_ID?.trim() ?? "";
+	const appSecret = environment.FEISHU_APP_SECRET?.trim() ?? "";
+	if (appId || appSecret) {
+		if (!appId || !appSecret) {
+			throw new CredentialError("FEISHU_APP_ID 和 FEISHU_APP_SECRET 必须同时设置。");
+		}
+		validateCredentialShape({ appId, appSecret });
+		const ownerOpenId = stored?.appId === appId ? stored.ownerOpenId : undefined;
+		return ownerOpenId ? { appId, appSecret, ownerOpenId } : { appId, appSecret };
+	}
+	return stored;
+}
+
+export function validateCredentialShape(credentials: FeishuCredentials): void {
+	if (!APP_ID_PATTERN.test(credentials.appId)) {
+		throw new CredentialError("飞书 App ID 格式无效，通常应以 cli_ 开头。");
+	}
+	if (!credentials.appSecret.trim()) {
+		throw new CredentialError("飞书 App Secret 不能为空。");
+	}
+}
+
+export function redactSensitiveText(
+	text: string,
+	credentials?: Pick<FeishuCredentials, "appId" | "appSecret">,
+): string {
+	let redacted = text.replace(/(Bearer\s+)[A-Za-z0-9._~+/-]+/gi, "$1[REDACTED]");
+	if (credentials?.appSecret) {
+		redacted = redacted.split(credentials.appSecret).join("[REDACTED]");
+	}
+	return redacted;
+}
+
+export function errorMessage(error: unknown, credentials?: Pick<FeishuCredentials, "appId" | "appSecret">): string {
+	const message = error instanceof Error ? error.message : String(error);
+	return redactSensitiveText(message, credentials);
+}
+
+export function defaultCredentialsPath(): string {
+	return join(homedir(), ".pi", "agent", "feishu", "credentials.json");
+}
+
+export class FileCredentialStore implements CredentialStore {
+	private readonly path: string;
+
+	constructor(path = defaultCredentialsPath()) {
+		this.path = path;
+	}
+
+	async load(): Promise<FeishuCredentials | null> {
+		let raw: string;
+		try {
+			raw = await readFile(this.path, "utf8");
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return null;
+			throw new CredentialError(`读取飞书凭据失败：${errorMessage(error)}`);
+		}
+
+		let value: unknown;
+		try {
+			value = JSON.parse(raw);
+		} catch {
+			throw new CredentialError("飞书凭据文件不是有效 JSON，请执行 /feishu logout 后重新配置。");
+		}
+		if (!isCredentialRecord(value)) {
+			throw new CredentialError("飞书凭据文件格式无效，请执行 /feishu logout 后重新配置。");
+		}
+		validateCredentialShape(value);
+		return value.ownerOpenId
+			? { appId: value.appId, appSecret: value.appSecret, ownerOpenId: value.ownerOpenId }
+			: { appId: value.appId, appSecret: value.appSecret };
+	}
+
+	async save(credentials: FeishuCredentials): Promise<void> {
+		validateCredentialShape(credentials);
+		const directory = dirname(this.path);
+		await mkdir(directory, { recursive: true, mode: 0o700 });
+		const temporaryPath = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+		const payload = `${JSON.stringify(credentials, null, 2)}\n`;
+
+		try {
+			await writeFile(temporaryPath, payload, { encoding: "utf8", mode: 0o600, flag: "wx" });
+			await rename(temporaryPath, this.path);
+			await restrictFilePermissions(this.path);
+		} catch (error) {
+			await rm(temporaryPath, { force: true }).catch(() => undefined);
+			throw new CredentialError(`保存飞书凭据失败：${errorMessage(error, credentials)}`);
+		}
+	}
+
+	async clear(): Promise<void> {
+		try {
+			await rm(this.path, { force: true });
+		} catch (error) {
+			throw new CredentialError(`清除飞书凭据失败：${errorMessage(error)}`);
+		}
+	}
+}
+
+function isCredentialRecord(value: unknown): value is FeishuCredentials {
+	if (!value || typeof value !== "object") return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.appId === "string" &&
+		typeof record.appSecret === "string" &&
+		(record.ownerOpenId === undefined || typeof record.ownerOpenId === "string")
+	);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+async function restrictFilePermissions(path: string): Promise<void> {
+	try {
+		await chmod(path, 0o600);
+	} catch (error) {
+		if (process.platform !== "win32") throw error;
+	}
+}

package/src/extension.ts

@@ -0,0 +1,156 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { FeishuController, type FeishuStatus } from "./controller.js";
+import { CredentialError, FileCredentialStore } from "./credentials.js";
+import { SdkFeishuGateway, validateSdkCredentials } from "./gateway.js";
+import { PiAgentBridge } from "./pi-agent-bridge.js";
+
+type FeishuCommandName = "help" | "setup" | "start" | "stop" | "status" | "logout";
+
+export interface ParsedFeishuCommand {
+	name: FeishuCommandName;
+	args: string;
+}
+
+export function parseFeishuCommand(input: string): ParsedFeishuCommand {
+	const trimmed = input.trim();
+	if (!trimmed || trimmed === "help") return { name: "help", args: "" };
+
+	const separator = trimmed.search(/\s/);
+	const rawName = separator === -1 ? trimmed : trimmed.slice(0, separator);
+	let args = separator === -1 ? "" : trimmed.slice(separator).trim();
+	if (!isCommandName(rawName)) {
+		throw new CredentialError(`未知子命令：${rawName}。请执行 /feishu 查看帮助。`);
+	}
+	if (rawName !== "setup" && args) {
+		throw new CredentialError(`/feishu ${rawName} 不接受参数。`);
+	}
+	if (rawName === "setup" && args.startsWith("--manual")) {
+		args = args.slice("--manual".length).trim();
+	}
+	return { name: rawName, args };
+}
+
+export function renderFeishuHelp(): string {
+	return [
+		"Pi Feishu：通过飞书私聊使用当前 Pi 会话",
+		"",
+		"命令：",
+		"  /feishu",
+		"  /feishu setup [<appId> <appSecret>]",
+		"  /feishu start",
+		"  /feishu stop",
+		"  /feishu status",
+		"  /feishu logout",
+		"",
+		"推荐通过 FEISHU_APP_ID、FEISHU_APP_SECRET 提供凭据，然后执行 /feishu setup。",
+	].join("\n");
+}
+
+export function renderFeishuStatus(status: FeishuStatus): string {
+	if (!status.configured) {
+		return [
+			"飞书状态",
+			"  配置：未配置",
+			`  连接：${status.running ? "已连接" : "未连接"}`,
+			`  队列：${status.pendingMessages}`,
+		].join("\n");
+	}
+	return [
+		"飞书状态",
+		"  配置：已配置",
+		`  App ID：${status.appId ?? "未知"}`,
+		`  来源：${status.source === "environment" ? "环境变量" : "凭据文件"}`,
+		`  连接：${status.running ? "已连接" : "未连接"}`,
+		`  Owner：${status.ownerOpenId ?? "未绑定"}`,
+		`  队列：${status.pendingMessages}`,
+	].join("\n");
+}
+
+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,
+	});
+
+	pi.on("message_end", (event) => {
+		agent.captureMessage(event.message);
+	});
+	pi.on("agent_settled", () => {
+		agent.settle();
+	});
+	pi.on("session_shutdown", async () => {
+		await controller.stop();
+		agent.cancel("Pi 会话已关闭。");
+	});
+
+	pi.registerCommand("feishu", {
+		description: "配置和管理飞书私聊连接",
+		handler: async (args, context) => {
+			try {
+				await handleFeishuCommand(parseFeishuCommand(args), controller, context);
+			} catch (error) {
+				context.ui.notify(`飞书操作失败：${controller.sanitizeError(error)}`, "error");
+			}
+		},
+	});
+}
+
+async function handleFeishuCommand(
+	command: ParsedFeishuCommand,
+	controller: FeishuController,
+	context: ExtensionCommandContext,
+): Promise<void> {
+	switch (command.name) {
+		case "help": {
+			const status = await controller.status(process.env);
+			context.ui.notify(`${renderFeishuHelp()}\n\n${renderFeishuStatus(status)}`, "info");
+			return;
+		}
+		case "setup": {
+			const status = await controller.status(process.env);
+			if (status.running) {
+				throw new CredentialError("请先执行 /feishu stop，再修改飞书凭据。");
+			}
+			const credentials = await controller.setup(command.args, process.env);
+			context.ui.notify(`飞书凭据验证成功并已保存：${credentials.appId}`, "info");
+			return;
+		}
+		case "start": {
+			const result = await controller.start(process.env);
+			if (result.alreadyRunning) {
+				context.ui.notify("飞书长连接已经在运行。", "info");
+				return;
+			}
+			if (result.bindingCode) {
+				context.ui.notify(
+					`飞书长连接已启动。\n一次性绑定码：${result.bindingCode}\n请在飞书私聊 Bot 发送：/bind ${result.bindingCode}`,
+					"warning",
+				);
+			} else {
+				context.ui.notify("飞书长连接已启动，Owner 已绑定。", "info");
+			}
+			return;
+		}
+		case "stop":
+			context.ui.notify((await controller.stop()) ? "飞书长连接已停止。" : "飞书长连接未运行。", "info");
+			return;
+		case "status":
+			context.ui.notify(renderFeishuStatus(await controller.status(process.env)), "info");
+			return;
+		case "logout": {
+			if (context.hasUI) {
+				const confirmed = await context.ui.confirm("退出飞书", "停止连接并清除本地飞书凭据？");
+				if (!confirmed) return;
+			}
+			await controller.logout();
+			context.ui.notify("飞书连接已停止，本地凭据和 Owner 绑定已清除。", "info");
+		}
+	}
+}
+
+function isCommandName(value: string): value is FeishuCommandName {
+	return value === "setup" || value === "start" || value === "stop" || value === "status" || value === "logout";
+}

package/src/gateway.ts

@@ -0,0 +1,140 @@
+import { createLarkChannel, type LarkChannel, LoggerLevel, type NormalizedMessage } from "@larksuiteoapi/node-sdk";
+import type { FeishuCredentials, FeishuGateway, FeishuMessageHandler } from "./contracts.js";
+
+export interface NormalizedChannelMessage {
+	messageId: string;
+	chatId: string;
+	chatType: "p2p" | "group";
+	senderId: string;
+	content: string;
+	rawContentType: string;
+}
+
+export interface ChannelLike {
+	onMessage(handler: (message: NormalizedChannelMessage) => Promise<void> | void): () => void;
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	sendText(to: string, text: string, replyTo?: string): Promise<void>;
+}
+
+export type ChannelFactory = (credentials: FeishuCredentials) => ChannelLike;
+
+export class SdkFeishuGateway implements FeishuGateway {
+	private readonly credentials: FeishuCredentials;
+	private readonly channelFactory: ChannelFactory;
+	private channel: ChannelLike | undefined;
+	private unsubscribe: (() => void) | undefined;
+
+	constructor(credentials: FeishuCredentials, channelFactory: ChannelFactory = createOfficialChannel) {
+		this.credentials = credentials;
+		this.channelFactory = channelFactory;
+	}
+
+	async connect(handler: FeishuMessageHandler): Promise<void> {
+		if (this.channel) return;
+		const channel = this.channelFactory(this.credentials);
+		const unsubscribe = channel.onMessage((message) =>
+			handler({
+				messageId: message.messageId,
+				chatId: message.chatId,
+				chatType: message.chatType,
+				senderOpenId: message.senderId,
+				contentType: message.rawContentType,
+				text: message.content,
+			}),
+		);
+		this.channel = channel;
+		this.unsubscribe = unsubscribe;
+		try {
+			await channel.connect();
+		} catch (error) {
+			this.channel = undefined;
+			this.unsubscribe = undefined;
+			unsubscribe();
+			await channel.disconnect().catch(() => undefined);
+			throw error;
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		const channel = this.channel;
+		this.channel = undefined;
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		if (channel) await channel.disconnect();
+	}
+
+	async sendText(chatId: string, text: string, replyTo?: string): Promise<void> {
+		const channel = this.channel;
+		if (!channel) throw new Error("飞书长连接尚未启动。");
+		await channel.sendText(chatId, text, replyTo);
+	}
+}
+
+export async function validateSdkCredentials(
+	credentials: FeishuCredentials,
+	channelFactory: ChannelFactory = createOfficialChannel,
+): Promise<void> {
+	const channel = channelFactory(credentials);
+	try {
+		await channel.connect();
+	} finally {
+		await channel.disconnect().catch(() => undefined);
+	}
+}
+
+function createOfficialChannel(credentials: FeishuCredentials): ChannelLike {
+	return new OfficialChannelAdapter(
+		createLarkChannel({
+			appId: credentials.appId,
+			appSecret: credentials.appSecret,
+			transport: "websocket",
+			handshakeTimeoutMs: 10_000,
+			loggerLevel: LoggerLevel.error,
+			source: "pi-feishu",
+			policy: {
+				dmMode: "open",
+				groupAllowlist: [],
+				requireMention: true,
+			},
+			safety: {
+				chatQueue: { enabled: false },
+			},
+		}),
+	);
+}
+
+class OfficialChannelAdapter implements ChannelLike {
+	private readonly channel: LarkChannel;
+
+	constructor(channel: LarkChannel) {
+		this.channel = channel;
+	}
+
+	onMessage(handler: (message: NormalizedChannelMessage) => Promise<void> | void): () => void {
+		return this.channel.on("message", (message) => handler(toChannelMessage(message)));
+	}
+
+	async connect(): Promise<void> {
+		await this.channel.connect();
+	}
+
+	async disconnect(): Promise<void> {
+		await this.channel.disconnect();
+	}
+
+	async sendText(to: string, text: string, replyTo?: string): Promise<void> {
+		await this.channel.send(to, { text }, replyTo ? { replyTo } : undefined);
+	}
+}
+
+function toChannelMessage(message: NormalizedMessage): NormalizedChannelMessage {
+	return {
+		messageId: message.messageId,
+		chatId: message.chatId,
+		chatType: message.chatType,
+		senderId: message.senderId,
+		content: message.content,
+		rawContentType: message.rawContentType,
+	};
+}

package/src/message-deduplicator.ts

@@ -0,0 +1,26 @@
+export class MessageDeduplicator {
+	private readonly seen = new Set<string>();
+	private readonly order: string[] = [];
+	private readonly maxEntries: number;
+
+	constructor(maxEntries = 1000) {
+		this.maxEntries = maxEntries;
+	}
+
+	accept(messageId: string): boolean {
+		if (this.seen.has(messageId)) return false;
+		this.seen.add(messageId);
+		this.order.push(messageId);
+
+		while (this.order.length > this.maxEntries) {
+			const oldest = this.order.shift();
+			if (oldest) this.seen.delete(oldest);
+		}
+		return true;
+	}
+
+	clear(): void {
+		this.seen.clear();
+		this.order.length = 0;
+	}
+}

package/src/message-queue.ts

@@ -0,0 +1,26 @@
+export class SerialMessageQueue {
+	private tail: Promise<void> = Promise.resolve();
+	private pending = 0;
+
+	get pendingCount(): number {
+		return this.pending;
+	}
+
+	enqueue<T>(task: () => Promise<T>): Promise<T> {
+		this.pending += 1;
+		const execution = this.tail.then(task);
+		this.tail = execution
+			.then(
+				() => undefined,
+				() => undefined,
+			)
+			.finally(() => {
+				this.pending -= 1;
+			});
+		return execution;
+	}
+
+	async waitForIdle(): Promise<void> {
+		await this.tail;
+	}
+}

package/src/owner-binding.ts

@@ -0,0 +1,61 @@
+import { randomInt, timingSafeEqual } from "node:crypto";
+
+export type AuthorizationResult =
+	| { kind: "authorized"; text: string }
+	| { kind: "bound"; ownerOpenId: string }
+	| { kind: "binding-required" }
+	| { kind: "invalid-binding-code" }
+	| { kind: "unauthorized" };
+
+export class OwnerBinding {
+	private owner: string | undefined;
+	private code: string | undefined;
+	private readonly generateCode: () => string;
+
+	constructor(ownerOpenId: string | undefined, generateCode: () => string = defaultBindingCode) {
+		this.owner = ownerOpenId;
+		this.generateCode = generateCode;
+	}
+
+	get ownerOpenId(): string | undefined {
+		return this.owner;
+	}
+
+	getOrCreateCode(): string | undefined {
+		if (this.owner) return undefined;
+		if (!this.code) {
+			const generated = this.generateCode();
+			if (!/^\d{6}$/.test(generated)) {
+				throw new Error("绑定码生成器必须返回六位数字。");
+			}
+			this.code = generated;
+		}
+		return this.code;
+	}
+
+	authorize(senderOpenId: string, text: string): AuthorizationResult {
+		if (this.owner) {
+			return senderOpenId === this.owner ? { kind: "authorized", text } : { kind: "unauthorized" };
+		}
+
+		const match = text.trim().match(/^\/bind\s+(\d{6})$/);
+		if (!match) return { kind: "binding-required" };
+		const candidate = match[1] ?? "";
+		const expected = this.getOrCreateCode();
+		if (!expected || !safeEqual(candidate, expected)) return { kind: "invalid-binding-code" };
+
+		this.owner = senderOpenId;
+		this.code = undefined;
+		return { kind: "bound", ownerOpenId: senderOpenId };
+	}
+}
+
+function defaultBindingCode(): string {
+	return randomInt(100000, 1000000).toString();
+}
+
+function safeEqual(left: string, right: string): boolean {
+	const leftBuffer = Buffer.from(left);
+	const rightBuffer = Buffer.from(right);
+	return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/pi-agent-bridge.ts

@@ -0,0 +1,77 @@
+import type { AgentBridge } from "./contracts.js";
+
+interface PendingTurn {
+	resolve: (text: string) => void;
+	reject: (error: Error) => void;
+	lastAssistantText: string;
+}
+
+export class PiAgentBridge implements AgentBridge {
+	private readonly sendUserMessage: (text: string) => void;
+	private pending: PendingTurn | undefined;
+
+	constructor(sendUserMessage: (text: string) => void) {
+		this.sendUserMessage = sendUserMessage;
+	}
+
+	run(text: string): Promise<string> {
+		if (this.pending) {
+			return Promise.reject(new Error("已有飞书消息正在等待 Pi 回复。"));
+		}
+
+		return new Promise<string>((resolve, reject) => {
+			this.pending = { resolve, reject, lastAssistantText: "" };
+			try {
+				this.sendUserMessage(text);
+			} catch (error) {
+				this.pending = undefined;
+				reject(error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+	}
+
+	captureMessage(message: unknown): void {
+		if (!this.pending || !isAssistantMessage(message)) return;
+		const text = message.content
+			.filter(isTextContent)
+			.map((item) => item.text)
+			.join("");
+		if (text.trim()) this.pending.lastAssistantText = text.trim();
+	}
+
+	settle(): void {
+		const pending = this.pending;
+		if (!pending) return;
+		this.pending = undefined;
+		pending.resolve(pending.lastAssistantText || "Pi 已完成处理，但没有返回文本内容。");
+	}
+
+	cancel(reason = "Pi 会话已关闭。"): void {
+		const pending = this.pending;
+		if (!pending) return;
+		this.pending = undefined;
+		pending.reject(new Error(reason));
+	}
+}
+
+interface AssistantMessageLike {
+	role: "assistant";
+	content: unknown[];
+}
+
+interface TextContentLike {
+	type: "text";
+	text: string;
+}
+
+function isAssistantMessage(value: unknown): value is AssistantMessageLike {
+	if (!value || typeof value !== "object") return false;
+	const record = value as Record<string, unknown>;
+	return record.role === "assistant" && Array.isArray(record.content);
+}
+
+function isTextContent(value: unknown): value is TextContentLike {
+	if (!value || typeof value !== "object") return false;
+	const record = value as Record<string, unknown>;
+	return record.type === "text" && typeof record.text === "string";
+}