pi-remote-feishu 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# pi-remote-feishu
+
+Remote control Pi Agent via Feishu (飞书) chat. WebSocket bridge, interactive cards, attachments, and file sending for the Pi Agent.
+
+This is an independent Pi extension project. It does not modify `pi-main`.
+
+Current scope:
+
+- Feishu WebSocket message transport
+- Private chat and group chat session isolation
+- One Pi runtime per Feishu session key
+- Feishu card commands
+- Attachment processing
+- `send_file_to_chat` for returning local files to the current Feishu chat
+- Optional `lark-doc-cli` and `lark-im-readonly` skills when `lark-cli` is installed
+- Guardrails that block `lark-cli im` send/reply/receive commands
+
+## Quick Start
+
+Install and build:
+
+```powershell
+npm install --ignore-scripts
+npm run build
+```
+
+Create a config template:
+
+```powershell
+node .\dist\bin\pi-remote-feishu.js init --cwd D:\develop\pi-main
+```
+
+Edit:
+
+```text
+D:\develop\pi-main\.pi\feishu.json
+```
+
+Start the bridge:
+
+```powershell
+node .\dist\bin\pi-remote-feishu.js serve --cwd D:\develop\pi-main
+```
+
+You can also pass credentials through environment variables:
+
+```powershell
+$env:FEISHU_APP_ID="cli_xxx"
+$env:FEISHU_APP_SECRET="xxx"
+node .\dist\bin\pi-remote-feishu.js serve --cwd D:\develop\pi-main
+```
+
+## CLI Commands
+
+Check config and WebSocket connectivity:
+
+```powershell
+node .\dist\bin\pi-remote-feishu.js doctor --cwd D:\develop\pi-main
+```
+
+Send a test message when you know the chat id:
+
+```powershell
+node .\dist\bin\pi-remote-feishu.js send-test --chat-id <chatId> --text "hello"
+```
+
+Log incoming event summaries:
+
+```powershell
+node .\dist\bin\pi-remote-feishu.js serve --cwd D:\develop\pi-main --debug-events
+```
+
+or configure:
+
+```json
+{
+  "debug": {
+    "logIncomingEvents": true
+  }
+}
+```
+
+## Feishu Chat Commands
+
+- `/help`
+- `/sessions`
+- `/models`
+- `/new`
+- `/stop`
+- `/reset`
+- `/status`
+
+Group chats require mentioning the bot by default.
+
+## Skills And Message Output
+
+The extension exposes two skills to Pi only when `lark-cli` is installed and available on `PATH`:
+
+- `lark-doc-cli`: Feishu/Lark document workflows through `lark-cli`, including fetch, create, update, and media insertion.
+- `lark-im-readonly`: read-only IM inspection through `lark-cli`, including chat/member lookup, message search, and resource download.
+
+If `lark-cli` is not installed, these CLI skills are not loaded. The core Feishu transport, cards, attachments, and `send_file_to_chat` still work through the Feishu SDK.
+
+Loading a skill must not send Feishu messages by itself. In a Feishu-triggered run, the final chat reply is sent by the `pi-remote-feishu serve` transport. Generated local files should be returned through `send_file_to_chat`.
+
+The extension blocks these IM write or receive commands when the model tries to run them through bash:
+
+```bash
+lark-cli im +messages-send
+lark-cli im +messages-reply
+lark-cli im +messages-receive
+```
+
+## Docs
+
+- `ARCHITECTURE.md`
+- `ARCHITECTURE.zh-CN.md`
+- `docs/`

package/dist/attachments/mime.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 附件 MIME 类型推断工具。
+ */
+/** 根据文件名后缀推断 MIME 类型；未知扩展名返回通用二进制类型 */
+export declare function inferMimeType(fileName: string): string;
+/**
+ * 粗略判断一段 Buffer 是否像文本：
+ * 前 4KB 里只要出现字节 0（NUL），就认为不是文本。
+ * 用于决定小文件是内联内容还是落盘保存。
+ */
+export declare function isLikelyText(buffer: Buffer): boolean;

package/dist/attachments/mime.js

@@ -0,0 +1,27 @@
+/**
+ * 附件 MIME 类型推断工具。
+ */
+/** 常见图片扩展名 -> MIME 类型 */
+const MIME_BY_EXTENSION = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+};
+/** 根据文件名后缀推断 MIME 类型；未知扩展名返回通用二进制类型 */
+export function inferMimeType(fileName) {
+    const extension = fileName.split(".").pop()?.toLowerCase() ?? "";
+    return MIME_BY_EXTENSION[extension] ?? "application/octet-stream";
+}
+/**
+ * 粗略判断一段 Buffer 是否像文本：
+ * 前 4KB 里只要出现字节 0（NUL），就认为不是文本。
+ * 用于决定小文件是内联内容还是落盘保存。
+ */
+export function isLikelyText(buffer) {
+    return !buffer.subarray(0, 4096).includes(0);
+}
+//# sourceMappingURL=mime.js.map

package/dist/attachments/mime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../src/attachments/mime.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,yBAAyB;AACzB,MAAM,iBAAiB,GAA2B;IAChD,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;CACnB,CAAC;AAEF,uCAAuC;AACvC,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACjE,OAAO,iBAAiB,CAAC,SAAS,CAAC,IAAI,0BAA0B,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/attachments/processor.d.ts

@@ -0,0 +1,29 @@
+import type { FeishuChannel, FeishuConfig, FeishuMessage, ImageInput } from "../types.js";
+/**
+ * ============================================================
+ * 附件处理
+ * ------------------------------------------------------------
+ * 对消息携带的附件资源分类处理：
+ * 1. 表情包(sticker)：直接跳过
+ * 2. 图片 + 模型支持图片输入：转 base64 图片传给 Pi
+ * 3. 小型文本文件（非音视频、≤32KB、内容像文本）：内容内联到提示词
+ * 4. 其余文件：下载保存到临时目录，提示词里记录保存路径
+ * 5. 下载失败：提示词里记录失败原因
+ * ============================================================
+ */
+/** 附件处理结果：图片列表 + 文字说明列表 */
+export interface ProcessedAttachments {
+    images: ImageInput[];
+    notes: string[];
+}
+/**
+ * 处理一条消息的所有附件。
+ * 每个资源单独 try/catch：单个失败不影响其他资源。
+ */
+export declare function processAttachments(options: {
+    channel: Pick<FeishuChannel, "downloadResource">;
+    config: FeishuConfig;
+    message: FeishuMessage;
+    sessionKey: string;
+    supportsImages: boolean;
+}): Promise<ProcessedAttachments>;

package/dist/attachments/processor.js

@@ -0,0 +1,48 @@
+import { inferMimeType, isLikelyText } from "./mime.js";
+import { writeTempAttachment } from "./temp-files.js";
+/** 文本文件大小上限：超过则视为不可内联 */
+const TEXT_SIZE_LIMIT = 32 * 1024;
+/** 附件落盘文件名：优先用原始文件名，没有则用 fileKey.bin */
+function resourceFileName(fileKey, fileName) {
+    return fileName ?? `${fileKey}.bin`;
+}
+/**
+ * 处理一条消息的所有附件。
+ * 每个资源单独 try/catch：单个失败不影响其他资源。
+ */
+export async function processAttachments(options) {
+    const images = [];
+    const notes = [];
+    for (const resource of options.message.resources) {
+        if (resource.type === "sticker")
+            continue;
+        const fileName = resourceFileName(resource.fileKey, resource.fileName);
+        try {
+            const buffer = await options.channel.downloadResource(options.message.messageId, resource.fileKey, resource.type);
+            // 图片且模型支持：转 base64 作为图像输入
+            if (resource.type === "image" && options.supportsImages) {
+                images.push({
+                    type: "image",
+                    data: buffer.toString("base64"),
+                    mimeType: inferMimeType(fileName),
+                });
+                continue;
+            }
+            // 小型文本（非音视频）：内容直接内联进提示词
+            if (resource.type !== "audio" && resource.type !== "video" && buffer.length <= TEXT_SIZE_LIMIT && isLikelyText(buffer)) {
+                notes.push(`[Attachment text: ${fileName}]\n${buffer.toString("utf-8")}`);
+                continue;
+            }
+            // 其他文件：下载到临时目录，提示词记录路径（模型可用它读取）
+            const filePath = await writeTempAttachment(options.config.files.tempDir ?? ".", options.sessionKey, fileName, buffer);
+            notes.push(`[Attachment saved: ${fileName} -> ${filePath}]`);
+        }
+        catch (error) {
+            // 下载/处理失败：提示词里记录原因
+            const message = error instanceof Error ? error.message : String(error);
+            notes.push(`[Attachment failed: ${fileName}: ${message}]`);
+        }
+    }
+    return { images, notes };
+}
+//# sourceMappingURL=processor.js.map

package/dist/attachments/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["../../src/attachments/processor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAqBtD,yBAAyB;AACzB,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC;AAElC,wCAAwC;AACxC,SAAS,gBAAgB,CAAC,OAAe,EAAE,QAA4B;IACrE,OAAO,QAAQ,IAAI,GAAG,OAAO,MAAM,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAMxC;IACC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACjD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QAC1C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAEvE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;YAElH,0BAA0B;YAC1B,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;gBACxD,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,OAAO;oBACb,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;oBAC/B,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;iBAClC,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,wBAAwB;YACxB,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,eAAe,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvH,KAAK,CAAC,IAAI,CAAC,qBAAqB,QAAQ,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBAC1E,SAAS;YACX,CAAC;YAED,gCAAgC;YAChC,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,GAAG,EAAE,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YACtH,KAAK,CAAC,IAAI,CAAC,sBAAsB,QAAQ,OAAO,QAAQ,GAAG,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mBAAmB;YACnB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,KAAK,CAAC,IAAI,CAAC,uBAAuB,QAAQ,KAAK,OAAO,GAAG,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/attachments/temp-files.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 附件临时文件管理：
+ * 每个会话一个子目录（目录名由 sessionKey 清洗而来），
+ * 附件下载后写到这里，生成结束后整体清理。
+ */
+/**
+ * 把附件 Buffer 写入会话专属临时目录。
+ * 返回写入后的完整文件路径。
+ * 文件名会做安全清洗，去掉路径分隔符等危险字符。
+ */
+export declare function writeTempAttachment(tempDir: string, sessionKey: string, fileName: string, buffer: Buffer): Promise<string>;
+/**
+ * 清理某个会话的临时附件目录（生成结束/命令处理完后调用）。
+ * force: true 表示目录不存在也不报错。
+ */
+export declare function cleanupTempAttachments(tempDir: string, sessionKey: string): Promise<void>;

package/dist/attachments/temp-files.js

@@ -0,0 +1,32 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * 附件临时文件管理：
+ * 每个会话一个子目录（目录名由 sessionKey 清洗而来），
+ * 附件下载后写到这里，生成结束后整体清理。
+ */
+/**
+ * 把附件 Buffer 写入会话专属临时目录。
+ * 返回写入后的完整文件路径。
+ * 文件名会做安全清洗，去掉路径分隔符等危险字符。
+ */
+export async function writeTempAttachment(tempDir, sessionKey, fileName, buffer) {
+    // 清洗文件名：替换 Windows/Unix 路径分隔符与控制字符
+    const sanitizedName = fileName.replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_");
+    const safeName = sanitizedName.length > 0 && sanitizedName !== "." && sanitizedName !== ".." ? sanitizedName : "attachment.bin";
+    // 会话目录名：只保留安全字符
+    const dir = join(tempDir, sessionKey.replace(/[^a-zA-Z0-9_.-]/g, "_"));
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, safeName);
+    await writeFile(filePath, buffer);
+    return filePath;
+}
+/**
+ * 清理某个会话的临时附件目录（生成结束/命令处理完后调用）。
+ * force: true 表示目录不存在也不报错。
+ */
+export async function cleanupTempAttachments(tempDir, sessionKey) {
+    const dir = join(tempDir, sessionKey.replace(/[^a-zA-Z0-9_.-]/g, "_"));
+    await rm(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=temp-files.js.map

package/dist/attachments/temp-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-files.js","sourceRoot":"","sources":["../../src/attachments/temp-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe,EAAE,UAAkB,EAAE,QAAgB,EAAE,MAAc;IAC7G,mCAAmC;IACnC,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC;IAC1E,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,KAAK,GAAG,IAAI,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAChI,gBAAgB;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACrC,MAAM,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAAe,EAAE,UAAkB;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/dist/bin/pi-remote-feishu.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/pi-remote-feishu.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * ============================================================
+ * pi-remote-feishu 命令行入口（bin）
+ * ------------------------------------------------------------
+ * 支持子命令：
+ *   serve      启动 WebSocket 桥接，把飞书消息转发给 Pi 运行时（主命令）
+ *   init       生成一份 feishu.json 配置模板
+ *   doctor     检查配置与飞书 WebSocket 连通性
+ *   send-test  向指定聊天发送一条测试消息
+ *   help       打印帮助
+ *
+ * 参数来源优先级：环境变量 < 配置文件 < CLI 参数（见 config/load-config.ts）
+ * ============================================================
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { handleCardAction } from "../bridge/card-actions.js";
+import { handleFeishuMessage } from "../bridge/message-handler.js";
+import { SessionHostManager } from "../bridge/session-host-manager.js";
+import { loadConfig, resolveConfigFilePath } from "../config/load-config.js";
+import { createFeishuChannel } from "../feishu/channel.js";
+import { createWebhookNotImplementedError } from "../feishu/webhook.js";
+import { createStore } from "../store/store.js";
+/** 飞书 WebSocket 连接/断开的超时时间（毫秒） */
+const CONNECT_TIMEOUT_MS = 20_000;
+const DISCONNECT_TIMEOUT_MS = 5_000;
+/** 读取某个 flag 后面的参数值，缺失则报错 */
+function readFlag(args, index) {
+    const value = args[index + 1];
+    if (!value) {
+        throw new Error(`Missing value for ${args[index]}`);
+    }
+    return value;
+}
+/**
+ * 解析命令行参数。
+ * 第一个参数如果是 serve/init/doctor/send-test/help 则作为子命令，
+ * 否则默认为 serve（方便直接运行 `pi-remote-feishu --app-id ...`）。
+ */
+function parseArgs(args) {
+    const command = args[0] === "serve" || args[0] === "init" || args[0] === "doctor" || args[0] === "send-test"
+        ? args[0]
+        : args[0] === "help" || args[0] === "--help" || args[0] === "-h"
+            ? "help"
+            : "serve";
+    const config = {};
+    let logLevel;
+    let initPath;
+    let force = false;
+    let chatId;
+    let text;
+    for (let index = command === "serve" || command === "init" || command === "doctor" || command === "send-test" ? 1 : 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--app-id") {
+            config.appId = readFlag(args, index);
+            index += 1;
+        }
+        else if (arg === "--app-secret") {
+            config.appSecret = readFlag(args, index);
+            index += 1;
+        }
+        else if (arg === "--config") {
+            config.configPath = readFlag(args, index);
+            initPath = resolve(config.configPath);
+            index += 1;
+        }
+        else if (arg === "--cwd") {
+            config.cwd = resolve(readFlag(args, index));
+            index += 1;
+        }
+        else if (arg === "--log-level") {
+            logLevel = readFlag(args, index);
+            index += 1;
+        }
+        else if (arg === "--group-scope") {
+            // 群聊会话隔离范围：shared-chat（共享）/ per-user（按用户隔离）
+            const groupScope = readFlag(args, index);
+            if (groupScope !== "shared-chat" && groupScope !== "per-user") {
+                throw new Error("--group-scope must be shared-chat or per-user");
+            }
+            config.sessions = { ...config.sessions, groupScope };
+            index += 1;
+        }
+        else if (arg === "--debug-events") {
+            // 打印收到的消息/卡片事件摘要
+            config.debug = { ...config.debug, logIncomingEvents: true };
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--chat-id") {
+            chatId = readFlag(args, index);
+            index += 1;
+        }
+        else if (arg === "--text") {
+            text = readFlag(args, index);
+            index += 1;
+        }
+    }
+    return {
+        command,
+        config,
+        ...(logLevel ? { logLevel } : {}),
+        ...(initPath ? { initPath } : {}),
+        ...(force ? { force } : {}),
+        ...(chatId ? { chatId } : {}),
+        ...(text ? { text } : {}),
+    };
+}
+/** 打印命令行帮助 */
+function printHelp() {
+    console.log(`Usage:
+  pi-remote-feishu serve [options]
+  pi-remote-feishu init [--config <path>] [--force]
+  pi-remote-feishu doctor [options]
+  pi-remote-feishu send-test --chat-id <chatId> --text <text> [options]
+
+Options:
+  --app-id <id>          Feishu app id
+  --app-secret <secret>  Feishu app secret
+  --config <path>        Config file path
+  --cwd <path>           Default Pi working directory
+  --log-level <level>    fatal|error|warn|info|debug|trace
+  --group-scope <scope>  shared-chat|per-user
+  --debug-events         Log incoming message/card action summaries
+  --force                Overwrite config when used with init
+  --chat-id <id>         Target chat id for send-test
+  --text <text>          Text for send-test
+`);
+}
+/** 脱敏 App Secret：只保留头尾各 4 位，中间用 **** 代替 */
+function maskSecret(value) {
+    if (value.length <= 8)
+        return "****";
+    return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+/** 给 Promise 加超时：超时后 reject，并在结束时清理定时器 */
+async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/** 生成一份默认配置模板（pi-remote-feishu init 用），已存在且未带 --force 时拒绝覆盖 */
+function writeConfigTemplate(path, force) {
+    if (existsSync(path) && !force) {
+        throw new Error(`Config already exists: ${path}. Use --force to overwrite.`);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const template = {
+        appId: "cli_xxx",
+        appSecret: "replace-with-app-secret",
+        botName: "Pi Agent",
+        transport: "websocket",
+        policy: {
+            requireMention: true,
+            dmEnabled: true,
+            groupEnabled: true,
+            allowUsers: [],
+            allowChats: [],
+        },
+        sessions: {
+            groupScope: "shared-chat",
+            defaultCwd: process.cwd(),
+            store: "json",
+            idleTtlMs: 1_800_000,
+        },
+        rendering: {
+            mode: "stream-card",
+            showThinking: "quote",
+            showToolEvents: true,
+        },
+        files: {
+            allowedOutputDirs: [process.cwd()],
+            maxUploadBytes: 20_971_520,
+        },
+        debug: {
+            logIncomingEvents: false,
+        },
+    };
+    writeFileSync(path, `${JSON.stringify(template, null, 2)}\n`, "utf-8");
+}
+/** 生成收到的消息摘要（--debug-events 时打印到 stderr） */
+function incomingMessageSummary(message) {
+    return JSON.stringify({
+        event: "message",
+        messageId: message.messageId,
+        chatId: message.chatId,
+        chatType: message.chatType,
+        userOpenId: message.userOpenId,
+        senderName: message.senderName ?? "",
+        mentionedBot: message.mentionedBot,
+        textLength: message.text.length,
+        resources: message.resources.length,
+    });
+}
+/** 生成收到的卡片事件摘要（--debug-events 时打印到 stderr） */
+function incomingCardActionSummary(event) {
+    return JSON.stringify({
+        event: "cardAction",
+        messageId: event.messageId ?? "",
+        chatId: event.chatId,
+        userOpenId: event.userOpenId ?? "",
+        cmd: typeof event.actionValue.cmd === "string" ? event.actionValue.cmd : "",
+        hasToken: event.token !== undefined,
+    });
+}
+/** 根据配置创建飞书通道 */
+function createChannel(config, logLevel) {
+    return createFeishuChannel({
+        appId: config.appId,
+        appSecret: config.appSecret,
+        requireMention: config.policy.requireMention,
+        ...(logLevel ? { logLevel } : {}),
+    });
+}
+/** doctor 子命令：打印配置摘要，并实际连一次飞书 WebSocket 验证连通性 */
+async function runDoctor(cli) {
+    const cwd = resolve(cli.config.cwd ?? process.cwd());
+    const configPath = resolveConfigFilePath(cwd, cli.config.configPath);
+    const config = loadConfig(cli.config);
+    console.log("Pi Feishu Doctor");
+    console.log(`- cwd: ${cwd}`);
+    console.log(`- config: ${configPath ?? "env/cli only"}`);
+    console.log(`- appId: ${config.appId}`);
+    console.log(`- appSecret: ${maskSecret(config.appSecret)}`);
+    console.log(`- transport: ${config.transport}`);
+    console.log(`- dmEnabled: ${config.policy.dmEnabled}`);
+    console.log(`- groupEnabled: ${config.policy.groupEnabled}`);
+    console.log(`- requireMention: ${config.policy.requireMention}`);
+    console.log(`- groupScope: ${config.sessions.groupScope}`);
+    console.log(`- debug.logIncomingEvents: ${config.debug.logIncomingEvents}`);
+    if (config.transport === "webhook") {
+        console.log("- websocket: skipped, webhook transport is not implemented in v1");
+        return;
+    }
+    const channel = createChannel(config, cli.logLevel);
+    try {
+        await withTimeout(channel.connect(), CONNECT_TIMEOUT_MS, "Feishu websocket connect");
+        console.log(`- websocket: connected${channel.botName ? ` as ${channel.botName}` : ""}`);
+    }
+    finally {
+        await withTimeout(channel.disconnect(), DISCONNECT_TIMEOUT_MS, "Feishu websocket disconnect").catch(() => { });
+    }
+}
+/** send-test 子命令：连接飞书并发送一条测试文本 */
+async function runSendTest(cli) {
+    if (!cli.chatId) {
+        throw new Error("Missing --chat-id");
+    }
+    if (!cli.text) {
+        throw new Error("Missing --text");
+    }
+    const config = loadConfig(cli.config);
+    if (config.transport === "webhook") {
+        throw createWebhookNotImplementedError();
+    }
+    const channel = createChannel(config, cli.logLevel);
+    try {
+        await withTimeout(channel.connect(), CONNECT_TIMEOUT_MS, "Feishu websocket connect");
+        const result = await channel.sendText(cli.chatId, cli.text);
+        console.log(`Sent test message: ${result.messageId}`);
+    }
+    finally {
+        await withTimeout(channel.disconnect(), DISCONNECT_TIMEOUT_MS, "Feishu websocket disconnect").catch(() => { });
+    }
+}
+/**
+ * serve 主流程：
+ * 1. 加载配置、创建通道和存储
+ * 2. 创建 SessionHostManager（负责按 sessionKey 管理 Pi 运行时）
+ * 3. 注册消息/卡片/错误三个回调
+ * 4. 连接飞书，阻塞直到收到 SIGINT/SIGTERM
+ */
+async function main() {
+    const cli = parseArgs(process.argv.slice(2));
+    if (cli.command === "help") {
+        printHelp();
+        return;
+    }
+    if (cli.command === "init") {
+        const cwd = resolve(cli.config.cwd ?? process.cwd());
+        const configPath = cli.initPath ?? join(cwd, ".pi", "feishu.json");
+        writeConfigTemplate(configPath, cli.force ?? false);
+        console.log(`Created Feishu config: ${configPath}`);
+        return;
+    }
+    if (cli.command === "doctor") {
+        await runDoctor(cli);
+        process.exit(0);
+    }
+    if (cli.command === "send-test") {
+        await runSendTest(cli);
+        process.exit(0);
+    }
+    // ---- serve 子命令 ----
+    const config = loadConfig(cli.config);
+    if (config.transport === "webhook") {
+        throw createWebhookNotImplementedError();
+    }
+    const channel = createChannel(config, cli.logLevel);
+    const store = createStore(config);
+    const manager = new SessionHostManager({ config, store, channel });
+    // 收到飞书消息：可选的调试摘要 -> 交给 handleFeishuMessage 处理
+    channel.onMessage((message) => {
+        if (config.debug.logIncomingEvents) {
+            console.error(incomingMessageSummary(message));
+        }
+        handleFeishuMessage({ config, channel, store, manager, message }).catch((error) => {
+            console.error(error instanceof Error ? error.message : String(error));
+        });
+    });
+    // 收到卡片按钮事件：交给 handleCardAction 处理
+    channel.onCardAction((event) => {
+        if (config.debug.logIncomingEvents) {
+            console.error(incomingCardActionSummary(event));
+        }
+        handleCardAction({
+            config,
+            store,
+            manager,
+            event,
+            updateCardByToken: async (token, card) => {
+                await channel.updateCardByToken(token, card);
+            },
+        }).catch((error) => {
+            console.error(error instanceof Error ? error.message : String(error));
+        });
+    });
+    channel.onError((error) => {
+        console.error(error.message);
+    });
+    await channel.connect();
+    console.error(`Feishu bot connected${channel.botName ? ` as ${channel.botName}` : ""}.`);
+    // 阻塞等待退出信号，收到后断开飞书连接
+    await new Promise((resolvePromise) => {
+        const shutdown = () => {
+            channel.disconnect().finally(resolvePromise);
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=pi-remote-feishu.js.map