@evandu/super-pi 0.1.131 → 0.1.132

package/dist/server/feishu-cli.d.ts

@@ -0,0 +1,207 @@
+/**
+ * THE OFFICIAL FEISHU CLI, wrapped.
+ *
+ * WHY THE CLI AND NOT THE OPENAPI. Feishu ships `@larksuite/cli` (`lark-cli`), and it talks to a
+ * HIGHER-LEVEL API than the document one this file could otherwise call: the `docs_ai` service,
+ * which takes Markdown and returns Markdown, creates a document with content in ONE call, and
+ * carries the revision id on every write. Super Pi's own OpenAPI client had to create an empty
+ * document, convert Markdown into blocks, insert them as nested blocks under the page block, pack
+ * them into batches of a thousand, strip the read-only merge information off every table, and
+ * space its writes out because the block API allows three per second.
+ *
+ * So the honest answer to "why not just call the API" is: because Feishu already built the better
+ * caller, and it is the one that is maintained.
+ *
+ * WHY IT IS ALSO THE RIGHT AUTH PATH. The CLI stores its credentials in the OS keychain and
+ * authenticates with a device-code flow: `config init --new` creates an application through a
+ * browser confirmation (no developer-console work at all), and `auth login` grants a user token by
+ * the same kind of confirmation. A user token means the agent reaches the user's OWN documents -
+ * which removes the per-document "添加文档应用" step that the application-identity path needs, and
+ * it means Super Pi never holds a secret: the credential lives in the CLI's keychain, and this
+ * file only ever runs commands.
+ *
+ * THE ENVELOPE. Every command answers with JSON: `{"ok": true, "identity": "user", "data": {...}}`
+ * on stdout with exit code 0, and `{"ok": false, "error": {"type", "subtype", "code", "message",
+ * "hint"}}` on stderr with a non-zero exit code. The `hint` is Feishu's own "what to do about it",
+ * which is why this wrapper's errors can pass it through instead of inventing its own table.
+ */
+/** The tool that reads a Feishu document. */
+export declare const FEISHU_READ_TOOL_NAME = "feishu_doc_read";
+/** The tool that writes a Feishu document. */
+export declare const FEISHU_WRITE_TOOL_NAME = "feishu_doc_write";
+/** How the CLI is found. An explicit path wins, then the environment, then the PATH. */
+export declare const FEISHU_CLI_ENV = "SUPER_PI_FEISHU_CLI";
+/** The command name the CLI installs itself as. */
+export declare const FEISHU_CLI_COMMAND = "lark-cli";
+/** The success/failure envelope every CLI command answers with. */
+export type FeishuCliEnvelope = {
+    ok?: boolean;
+    identity?: string;
+    data?: Record<string, unknown>;
+    error?: {
+        type?: string;
+        subtype?: string;
+        code?: number;
+        message?: string;
+        hint?: string;
+    };
+    meta?: Record<string, unknown>;
+    /** Set when the answer was not JSON at all - a crash, a missing binary, a killed process. */
+    raw?: string;
+};
+/** The identity the CLI is acting as. */
+export type FeishuIdentity = "user" | "bot";
+/**
+ * What the CLI knows about itself: is it installed, is an application configured, is a person
+ * logged in.
+ */
+export type FeishuCliStatus = {
+    installed: boolean;
+    version?: string;
+    appId?: string;
+    userReady: boolean;
+    botReady: boolean;
+    identity?: FeishuIdentity;
+    /** Feishu's own "what to do about it", when the CLI had something to say. */
+    hint?: string;
+};
+/** The outcome of a CLI call, in the shape this product speaks in. */
+export declare class FeishuCliError extends Error {
+    readonly hint?: string | undefined;
+    readonly code?: number | undefined;
+    constructor(message: string, hint?: string | undefined, code?: number | undefined);
+}
+/** A spawn function, injected in tests so the suite never runs a real binary. */
+export type SpawnLike = (command: string, args: string[], options: {
+    shell: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    timeoutMs: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}>;
+/**
+ * A LONG-RUNNING command, whose output is watched while it runs.
+ *
+ * `config init --new` blocks until the person confirms the application in a browser, so its URL
+ * has to be read out of its output WHILE it is still running - which a promise of the finished
+ * output cannot do. Injected in tests for the same reason as the other spawn: the suite must
+ * never run the real binary, which would sit there waiting for a browser confirmation.
+ */
+export type BackgroundSpawnLike = (command: string, args: string[], options: {
+    shell: boolean;
+    env?: NodeJS.ProcessEnv;
+}) => {
+    onOutput: (listener: (chunk: string) => void) => void;
+    done: Promise<void>;
+};
+export type FeishuCliOptions = {
+    /** The command to run. Defaults to `lark-cli`, or `SUPER_PI_FEISHU_CLI` when it is set. */
+    command?: string;
+    /** Where the command runs. The CLI resolves `@file` paths against the working directory. */
+    cwd?: string;
+    /** Extra environment for the command. */
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests. */
+    spawn?: SpawnLike;
+    /** Injected in tests, for the one command that keeps running. */
+    backgroundSpawn?: BackgroundSpawnLike;
+    /** How long a command may take before it is killed. */
+    timeoutMs?: number;
+};
+export declare class FeishuCli {
+    private readonly options;
+    private readonly spawn;
+    private readonly backgroundSpawn;
+    private readonly timeoutMs;
+    constructor(options?: FeishuCliOptions);
+    /** The command to run. */
+    get command(): string;
+    /**
+     * RUNS ONE COMMAND AND PARSES ITS ENVELOPE.
+     *
+     * A command that is not found is an error the caller has to be able to tell apart from a
+     * command that ran and failed, so the missing-binary case is a distinct error code.
+     */
+    run(args: string[], options?: {
+        input?: string;
+        timeoutMs?: number;
+    }): Promise<FeishuCliEnvelope>;
+    /**
+     * THE CLI'S VERSION, or `undefined` when it is not installed.
+     *
+     * This is how the panel decides between "install it" and "connect it", so it must not throw.
+     */
+    version(): Promise<string | undefined>;
+    /**
+     * WHAT THE CLI KNOWS ABOUT ITSELF.
+     *
+     * `auth status` is the one command that answers without touching the network unless asked to
+     * verify, so it is what the panel polls.
+     */
+    status(): Promise<FeishuCliStatus>;
+    /**
+     * THE DEVICE-CODE LOGIN, in the two steps the CLI documents for agents: ask for a code without
+     * waiting, show the person the URL, and finish the exchange once they have authorized.
+     */
+    beginLogin(): Promise<{
+        deviceCode: string;
+        verificationUri?: string;
+    }>;
+    /** Finishes the device-code exchange once the person has authorized it. */
+    completeLogin(deviceCode: string): Promise<FeishuCliEnvelope>;
+    /**
+     * READS A DOCUMENT AS MARKDOWN.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched.
+     */
+    fetchDocument(reference: string): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        content: string;
+        title?: string;
+    }>;
+    /** CREATES A DOCUMENT FROM MARKDOWN. */
+    createDocument(title: string, markdown: string): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        url?: string;
+    }>;
+    /**
+     * UPDATES A DOCUMENT.
+     *
+     * `append` adds at the end; `overwrite` replaces the whole document and takes the revision the
+     * caller read, which is the optimistic lock the CLI's own API enforces.
+     */
+    updateDocument(reference: string, command: "append" | "overwrite", markdown: string, revisionId?: number): Promise<{
+        revisionId?: number;
+        updated?: number;
+    }>;
+    /**
+     * CREATES THE APPLICATION, the way the CLI does it: `config init --new` registers an application
+     * through a browser confirmation and prints the URL to confirm at.
+     *
+     * The command BLOCKS until the person finishes, so it runs in the background and the URL is
+     * taken from its output as soon as it appears. The promise resolves with that URL, or with
+     * `undefined` when the command printed none within the window - the command itself keeps
+     * running, because the person still has to confirm it in their browser.
+     */
+    startAppCreation(waitMs?: number): Promise<string | undefined>;
+}
+/**
+ * Parses an envelope out of a command's output.
+ *
+ * The CLI prints one JSON object per command, but it also prints human text in some paths, so the
+ * envelope is found by BRACE MATCHING rather than by taking everything between the first and the
+ * last brace - which would swallow two objects and fail to parse at all.
+ */
+export declare function parseEnvelope(output: string): FeishuCliEnvelope | undefined;
+/** The message a failed envelope carries. */
+export declare function errorMessage(envelope: FeishuCliEnvelope): string;
+/** The hint a failed envelope carries - Feishu's own "what to do about it". */
+export declare function errorHint(envelope: FeishuCliEnvelope): string | undefined;
+/** The code a failed envelope carries. */
+export declare function errorCode(envelope: FeishuCliEnvelope): number | undefined;

package/dist/server/feishu-cli.js

@@ -0,0 +1,419 @@
+import { spawn } from "node:child_process";
+/**
+ * THE OFFICIAL FEISHU CLI, wrapped.
+ *
+ * WHY THE CLI AND NOT THE OPENAPI. Feishu ships `@larksuite/cli` (`lark-cli`), and it talks to a
+ * HIGHER-LEVEL API than the document one this file could otherwise call: the `docs_ai` service,
+ * which takes Markdown and returns Markdown, creates a document with content in ONE call, and
+ * carries the revision id on every write. Super Pi's own OpenAPI client had to create an empty
+ * document, convert Markdown into blocks, insert them as nested blocks under the page block, pack
+ * them into batches of a thousand, strip the read-only merge information off every table, and
+ * space its writes out because the block API allows three per second.
+ *
+ * So the honest answer to "why not just call the API" is: because Feishu already built the better
+ * caller, and it is the one that is maintained.
+ *
+ * WHY IT IS ALSO THE RIGHT AUTH PATH. The CLI stores its credentials in the OS keychain and
+ * authenticates with a device-code flow: `config init --new` creates an application through a
+ * browser confirmation (no developer-console work at all), and `auth login` grants a user token by
+ * the same kind of confirmation. A user token means the agent reaches the user's OWN documents -
+ * which removes the per-document "添加文档应用" step that the application-identity path needs, and
+ * it means Super Pi never holds a secret: the credential lives in the CLI's keychain, and this
+ * file only ever runs commands.
+ *
+ * THE ENVELOPE. Every command answers with JSON: `{"ok": true, "identity": "user", "data": {...}}`
+ * on stdout with exit code 0, and `{"ok": false, "error": {"type", "subtype", "code", "message",
+ * "hint"}}` on stderr with a non-zero exit code. The `hint` is Feishu's own "what to do about it",
+ * which is why this wrapper's errors can pass it through instead of inventing its own table.
+ */
+/** The tool that reads a Feishu document. */
+export const FEISHU_READ_TOOL_NAME = "feishu_doc_read";
+/** The tool that writes a Feishu document. */
+export const FEISHU_WRITE_TOOL_NAME = "feishu_doc_write";
+/** How the CLI is found. An explicit path wins, then the environment, then the PATH. */
+export const FEISHU_CLI_ENV = "SUPER_PI_FEISHU_CLI";
+/** The command name the CLI installs itself as. */
+export const FEISHU_CLI_COMMAND = "lark-cli";
+/** The outcome of a CLI call, in the shape this product speaks in. */
+export class FeishuCliError extends Error {
+    hint;
+    code;
+    constructor(message, hint, code) {
+        super(message);
+        this.hint = hint;
+        this.code = code;
+        this.name = "FeishuCliError";
+    }
+}
+/**
+ * Runs the CLI and reads its envelope.
+ *
+ * THE SPAWN IS A SHELL ON WINDOWS, because npm installs the CLI as a `.cmd` shim and Node cannot
+ * execute one without a shell. The same rule the runtime's Pi spawn follows.
+ */
+const defaultSpawn = (command, args, options) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        shell: process.platform === "win32",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+    const timer = setTimeout(() => { child.kill(); }, options.timeoutMs);
+    child.once("error", (error) => {
+        clearTimeout(timer);
+        // A missing binary is the normal way this fails, and it has to be recognisable: the panel
+        // answers "install it" instead of "something went wrong".
+        reject(Object.assign(new Error(`could not run ${command}: ${error.message}`), { code: "ENOENT" }));
+    });
+    child.once("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stdout, stderr, code });
+    });
+    if (options.input !== undefined) {
+        child.stdin?.end(options.input);
+    }
+    else {
+        child.stdin?.end();
+    }
+});
+/**
+ * Runs a command that keeps going, and hands its output over as it arrives.
+ */
+const defaultBackgroundSpawn = (command, args, options) => {
+    const child = spawn(command, args, {
+        shell: options.shell,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: options.env ?? process.env,
+    });
+    return {
+        onOutput: (listener) => {
+            child.stdout?.on("data", (chunk) => listener(String(chunk)));
+            child.stderr?.on("data", (chunk) => listener(String(chunk)));
+        },
+        done: new Promise((resolve) => {
+            child.once("close", () => resolve());
+            child.once("error", () => resolve());
+        }),
+    };
+};
+/** Reads the first value that exists, so a renamed field does not take the feature down. */
+function pick(source, ...paths) {
+    if (!source || typeof source !== "object")
+        return undefined;
+    for (const path of paths) {
+        let current = source;
+        for (const part of path.split(".")) {
+            if (!current || typeof current !== "object") {
+                current = undefined;
+                break;
+            }
+            current = current[part];
+        }
+        if (current !== undefined && current !== null)
+            return current;
+    }
+    return undefined;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export class FeishuCli {
+    options;
+    spawn;
+    backgroundSpawn;
+    timeoutMs;
+    constructor(options = {}) {
+        this.options = options;
+        this.spawn = options.spawn ?? defaultSpawn;
+        this.backgroundSpawn = options.backgroundSpawn ?? defaultBackgroundSpawn;
+        this.timeoutMs = options.timeoutMs ?? 90_000;
+    }
+    /** The command to run. */
+    get command() {
+        return this.options.command ?? process.env[FEISHU_CLI_ENV] ?? FEISHU_CLI_COMMAND;
+    }
+    /**
+     * RUNS ONE COMMAND AND PARSES ITS ENVELOPE.
+     *
+     * A command that is not found is an error the caller has to be able to tell apart from a
+     * command that ran and failed, so the missing-binary case is a distinct error code.
+     */
+    async run(args, options = {}) {
+        let result;
+        try {
+            result = await this.spawn(this.command, args, {
+                shell: process.platform === "win32",
+                ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
+                ...(this.options.env ? { env: { ...process.env, ...this.options.env } } : {}),
+                ...(options.input !== undefined ? { input: options.input } : {}),
+                timeoutMs: options.timeoutMs ?? this.timeoutMs,
+            });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new FeishuCliError(`没有找到官方飞书 CLI（${this.command}）。请先运行 npm i -g @larksuite/cli 安装，再回到这里点「连接飞书账号」。`);
+            }
+            throw error;
+        }
+        // Success answers on stdout, failures on stderr; a crash answers with neither.
+        const parsed = parseEnvelope(result.stdout) ?? parseEnvelope(result.stderr);
+        if (parsed)
+            return parsed;
+        const text = (result.stderr || result.stdout || "").trim();
+        // A command that printed something that is not an envelope did not do what was asked, and
+        // treating that as success would hand the model an empty document.
+        throw new FeishuCliError(text
+            ? `飞书 CLI 没有返回可读的结果：${text.slice(0, 300)}`
+            : `飞书 CLI 执行失败（退出码 ${result.code}），而且没有说明原因。`);
+    }
+    /**
+     * THE CLI'S VERSION, or `undefined` when it is not installed.
+     *
+     * This is how the panel decides between "install it" and "connect it", so it must not throw.
+     */
+    async version() {
+        try {
+            const result = await this.spawn(this.command, ["--version"], {
+                shell: process.platform === "win32",
+                timeoutMs: 20_000,
+            });
+            // A command that failed is not a CLI that is installed. The version has to look like one,
+            // because the answer decides between "install it" and "connect it".
+            if (result.code !== 0)
+                return undefined;
+            const match = /\d+\.\d+\.\d+[\w.+-]*/.exec(`${result.stdout} ${result.stderr}`);
+            return match ? match[0] : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * WHAT THE CLI KNOWS ABOUT ITSELF.
+     *
+     * `auth status` is the one command that answers without touching the network unless asked to
+     * verify, so it is what the panel polls.
+     */
+    async status() {
+        const version = await this.version();
+        if (!version)
+            return { installed: false, userReady: false, botReady: false };
+        let envelope;
+        try {
+            envelope = await this.run(["auth", "status", "--json"], { timeoutMs: 30_000 });
+        }
+        catch (error) {
+            return {
+                installed: true,
+                version,
+                userReady: false,
+                botReady: false,
+                ...(error instanceof FeishuCliError ? { hint: error.message } : {}),
+            };
+        }
+        const identities = pick(envelope.data ?? envelope, "identities");
+        const user = identities?.user;
+        const bot = identities?.bot;
+        const identity = asString(envelope.identity) ?? pick(envelope.data ?? envelope, "identity");
+        return {
+            installed: true,
+            version,
+            ...(asString(pick(envelope.data ?? envelope, "appId", "app_id")) ? { appId: asString(pick(envelope.data ?? envelope, "appId", "app_id")) } : {}),
+            userReady: user?.available === true,
+            botReady: bot?.available === true,
+            ...(identity === "user" || identity === "bot" ? { identity } : {}),
+            ...(asString(user?.hint) ?? asString(bot?.hint) ? { hint: (asString(user?.hint) ?? asString(bot?.hint)) } : {}),
+        };
+    }
+    /**
+     * THE DEVICE-CODE LOGIN, in the two steps the CLI documents for agents: ask for a code without
+     * waiting, show the person the URL, and finish the exchange once they have authorized.
+     */
+    async beginLogin() {
+        const envelope = await this.run(["auth", "login", "--no-wait", "--json"], { timeoutMs: 60_000 });
+        if (envelope.ok === false)
+            throw new FeishuCliError(errorMessage(envelope), errorHint(envelope), errorCode(envelope));
+        const deviceCode = asString(pick(envelope.data ?? envelope, "device_code", "deviceCode"));
+        if (!deviceCode)
+            throw new FeishuCliError("飞书 CLI 没有返回设备码，无法发起登录。");
+        const verificationUri = asString(pick(envelope.data ?? envelope, "verification_uri_complete", "verificationUriComplete", "verification_uri", "verificationUri"));
+        return { deviceCode, ...(verificationUri ? { verificationUri } : {}) };
+    }
+    /** Finishes the device-code exchange once the person has authorized it. */
+    async completeLogin(deviceCode) {
+        return this.run(["auth", "login", "--device-code", deviceCode, "--json"], { timeoutMs: 120_000 });
+    }
+    /**
+     * READS A DOCUMENT AS MARKDOWN.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched.
+     */
+    async fetchDocument(reference) {
+        const envelope = await this.run(["docs", "+fetch", "--doc", reference, "--doc-format", "markdown", "--json"], { timeoutMs: 120_000 });
+        if (envelope.ok === false)
+            throw new FeishuCliError(errorMessage(envelope), errorHint(envelope), errorCode(envelope));
+        const document = pick(envelope.data ?? {}, "document");
+        const content = asString(pick(document ?? {}, "content")) ?? asString(pick(envelope.data ?? {}, "content")) ?? "";
+        return {
+            ...(asString(pick(document ?? {}, "document_id", "documentId")) ? { documentId: asString(pick(document ?? {}, "document_id", "documentId")) } : {}),
+            ...(asNumber(pick(document ?? {}, "revision_id", "revisionId")) !== undefined ? { revisionId: asNumber(pick(document ?? {}, "revision_id", "revisionId")) } : {}),
+            ...(asString(pick(document ?? {}, "title")) ? { title: asString(pick(document ?? {}, "title")) } : {}),
+            content,
+        };
+    }
+    /** CREATES A DOCUMENT FROM MARKDOWN. */
+    async createDocument(title, markdown) {
+        const envelope = await this.run(["docs", "+create", "--doc-format", "markdown", "--title", title, "--content", "-", "--json"], { input: markdown, timeoutMs: 180_000 });
+        if (envelope.ok === false)
+            throw new FeishuCliError(errorMessage(envelope), errorHint(envelope), errorCode(envelope));
+        const document = pick(envelope.data ?? {}, "document");
+        return {
+            ...(asString(pick(document ?? {}, "document_id", "documentId")) ? { documentId: asString(pick(document ?? {}, "document_id", "documentId")) } : {}),
+            ...(asNumber(pick(document ?? {}, "revision_id", "revisionId")) !== undefined ? { revisionId: asNumber(pick(document ?? {}, "revision_id", "revisionId")) } : {}),
+            ...(asString(pick(document ?? {}, "url")) ? { url: asString(pick(document ?? {}, "url")) } : {}),
+        };
+    }
+    /**
+     * UPDATES A DOCUMENT.
+     *
+     * `append` adds at the end; `overwrite` replaces the whole document and takes the revision the
+     * caller read, which is the optimistic lock the CLI's own API enforces.
+     */
+    async updateDocument(reference, command, markdown, revisionId) {
+        const args = ["docs", "+update", "--doc", reference, "--command", command, "--doc-format", "markdown", "--content", "-"];
+        if (revisionId !== undefined)
+            args.push("--revision-id", String(revisionId));
+        args.push("--json");
+        const envelope = await this.run(args, { input: markdown, timeoutMs: 180_000 });
+        if (envelope.ok === false)
+            throw new FeishuCliError(errorMessage(envelope), errorHint(envelope), errorCode(envelope));
+        const document = pick(envelope.data ?? {}, "document");
+        return {
+            ...(asNumber(pick(document ?? {}, "revision_id", "revisionId")) !== undefined ? { revisionId: asNumber(pick(document ?? {}, "revision_id", "revisionId")) } : {}),
+            ...(asNumber(pick(envelope.data ?? {}, "updated_blocks_count", "updatedBlocksCount")) !== undefined ? { updated: asNumber(pick(envelope.data ?? {}, "updated_blocks_count", "updatedBlocksCount")) } : {}),
+        };
+    }
+    /**
+     * CREATES THE APPLICATION, the way the CLI does it: `config init --new` registers an application
+     * through a browser confirmation and prints the URL to confirm at.
+     *
+     * The command BLOCKS until the person finishes, so it runs in the background and the URL is
+     * taken from its output as soon as it appears. The promise resolves with that URL, or with
+     * `undefined` when the command printed none within the window - the command itself keeps
+     * running, because the person still has to confirm it in their browser.
+     */
+    async startAppCreation(waitMs = 25_000) {
+        const handle = this.backgroundSpawn(this.command, ["config", "init", "--new"], {
+            shell: process.platform === "win32",
+            ...(this.options.env ? { env: { ...process.env, ...this.options.env } } : {}),
+        });
+        return new Promise((resolve) => {
+            let seen = "";
+            let settled = false;
+            const finish = (url) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(url);
+            };
+            const timer = setTimeout(() => finish(undefined), waitMs);
+            handle.onOutput((chunk) => {
+                seen += chunk;
+                const match = /https:\/\/[^\s"'<>)\]]+/.exec(seen);
+                if (match)
+                    finish(match[0]);
+            });
+            handle.done.then(() => finish(undefined));
+        });
+    }
+}
+/**
+ * Parses an envelope out of a command's output.
+ *
+ * The CLI prints one JSON object per command, but it also prints human text in some paths, so the
+ * envelope is found by BRACE MATCHING rather than by taking everything between the first and the
+ * last brace - which would swallow two objects and fail to parse at all.
+ */
+export function parseEnvelope(output) {
+    const text = output.trim();
+    if (!text)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        // fall through to the brace scan
+    }
+    for (let start = text.indexOf("{"); start !== -1; start = text.indexOf("{", start + 1)) {
+        const end = matchingBrace(text, start);
+        if (end === -1)
+            continue;
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch {
+            // not this one; keep looking
+        }
+    }
+    return undefined;
+}
+/**
+ * The index of the brace that closes the one at `start`, ignoring braces inside strings.
+ */
+function matchingBrace(text, start) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index += 1) {
+        const character = text[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (character === "{")
+            depth += 1;
+        else if (character === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+/** The message a failed envelope carries. */
+export function errorMessage(envelope) {
+    const message = asString(envelope.error?.message);
+    const code = envelope.error?.code;
+    if (message)
+        return code ? `飞书返回了错误（${code}）：${message}` : `飞书返回了错误：${message}`;
+    return "飞书返回了错误，但没有说明原因。";
+}
+/** The hint a failed envelope carries - Feishu's own "what to do about it". */
+export function errorHint(envelope) {
+    return asString(envelope.error?.hint);
+}
+/** The code a failed envelope carries. */
+export function errorCode(envelope) {
+    return asNumber(envelope.error?.code);
+}

package/dist/server/files.js

@@ -150,17 +150,17 @@ function rejectUnsafeShape(requested) {
     // UNC: `\\server\share\...` and its POSIX-spelled twin `//server/share`. Named explicitly because
     // `isAbsolute` is true for the first on Windows and false for the second on Linux.
     if (/^[\\/]{2}/.test(requested))
-        throw new FilesError(403, "拒绝 UNC 路径：路径必须在 workspace 内", "outside_workspace");
+        throw new FilesError(403, "拒绝 UNC 路径：请给出相对于工作区根目录的路径", "outside_workspace");
     // A drive letter in EITHER position: `C:\x` is absolute, `C:x` is drive-relative and resolves against
     // that drive's current directory, which is not a location the caller gets to choose. The colon is also
     // how NTFS alternate data streams are addressed (`notes.md:hidden`), which is a second file hiding
     // behind one path - handled by the segment check below.
     if (/^[A-Za-z]:/.test(requested))
-        throw new FilesError(403, "拒绝 Windows 盘符路径：路径必须在 workspace 内", "outside_workspace");
+        throw new FilesError(403, "拒绝 Windows 盘符路径：请给出相对于工作区根目录的路径", "outside_workspace");
     // Rooted, POSIX or Windows: `/etc/passwd` and `\Windows`. Both are absolute, and the leading-slash
     // forms are spelled out so the refusal does not depend on the host's own path parser agreeing.
     if (requested.startsWith("/") || requested.startsWith("\\"))
-        throw new FilesError(403, "拒绝绝对路径：路径必须在 workspace 内", "outside_workspace");
+        throw new FilesError(403, "拒绝绝对路径：请给出相对于工作区根目录的路径", "outside_workspace");
     return requested.replace(/\\/g, "/");
 }
 /**