@evandu/super-pi 0.1.130 → 0.1.132

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-D_c-CYAr.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CXB6U5mz.css">
+    <script type="module" crossorigin src="/assets/index-ChyemF2I.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-D3MEG8uH.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/application/document-service.d.ts

@@ -0,0 +1,68 @@
+import type { Store } from "../store.js";
+import type { DocumentFormat } from "../documents.js";
+/**
+ * The largest request the document endpoint accepts.
+ *
+ * A document's extracted text rides in the request, so the cap is the document cap - a request past
+ * it is refused outright rather than truncated into a document that silently lost its tail.
+ */
+export declare const MAX_DOCUMENT_REQUEST_BYTES: number;
+/**
+ * THE DOCUMENT SERVICE: what an agent can do with the files in a workspace.
+ *
+ * It is the agent-facing half of the parsing layer. The knowledge base uses the same parsing code
+ * (see `knowledge.ts`), so a PDF reads the same way whether it was imported into the knowledge base
+ * or read straight out of the workspace - which is the point of having one parsing layer.
+ *
+ * WHY THE SERVICE OWNS THE PATH GUARD AND NOT THE EXTENSION. The extension runs in Pi's process and
+ * could ask for any path it liked. The service resolves every path against the workspace root with
+ * the same `resolveInsideRoot` guard the file panel uses, so a `..` or a symlink pointing outside
+ * the workspace is refused by construction rather than by a check somebody has to remember.
+ */
+export declare class DocumentService {
+    private readonly store;
+    constructor(store: Store);
+    /**
+     * The workspace a conversation works in, taken from the store.
+     *
+     * The conversation is the caller's identity, and the workspace is derived from it. A request that
+     * named its own workspace would be a request that could read another workspace.
+     */
+    private workspacePath;
+    /**
+     * Reads a file's contents.
+     *
+     * A text file is returned as it is; a document is parsed. The distinction matters because the two
+     * fail differently: a text file that does not exist is a missing file, while a document that
+     * cannot be parsed is a document with a reason.
+     */
+    read(conversationId: string, path: string): Promise<{
+        text: string;
+        format: string;
+        warnings: string[];
+        etag: string;
+    }>;
+    /**
+     * Writes a document into the workspace.
+     *
+     * The content is Markdown for a Word or PDF document and CSV for a spreadsheet, and the format is
+     * taken from the file's extension - so the caller says "write this report to REPORT.docx" and the
+     * right writer is chosen. An extension that names no document format is refused, because writing
+     * a `.txt` file is what Pi's own `write` tool is for, and a second way to do it is a second way to
+     * be wrong about it.
+     *
+     * OVERWRITING AN EXISTING FILE NEEDS THE VERSION THE CALLER READ, the same rule the file panel's
+     * write enforces (docs/DOCUMENTS.md: 覆盖已有文件前要确认，etag 语义和文件面板一致). A document is a
+     * file a person edits; an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit
+     * made an hour ago with no refusal, no diff, no warning. A missing etag over an existing file and a
+     * stale one are both refused, and the refusal carries the CURRENT etag - which is what makes an
+     * informed overwrite possible, the same way the panel's 409 does: re-sending the current etag is
+     * the deliberate "仍然覆盖", not a skipped check. A file that does not exist yet is the ordinary
+     * create case and needs no confirmation.
+     */
+    write(conversationId: string, path: string, content: string, title?: string, baseEtag?: string): Promise<{
+        path: string;
+        bytes: number;
+        format: DocumentFormat;
+    }>;
+}

package/dist/server/application/document-service.js

@@ -0,0 +1,120 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, extname } from "node:path";
+import { buildDocument, documentFormatOf, DocumentError, extractText } from "../documents.js";
+import { fileEtag, resolveInsideRoot } from "../files.js";
+/**
+ * The largest request the document endpoint accepts.
+ *
+ * A document's extracted text rides in the request, so the cap is the document cap - a request past
+ * it is refused outright rather than truncated into a document that silently lost its tail.
+ */
+export const MAX_DOCUMENT_REQUEST_BYTES = 8 * 1024 * 1024;
+/**
+ * THE DOCUMENT SERVICE: what an agent can do with the files in a workspace.
+ *
+ * It is the agent-facing half of the parsing layer. The knowledge base uses the same parsing code
+ * (see `knowledge.ts`), so a PDF reads the same way whether it was imported into the knowledge base
+ * or read straight out of the workspace - which is the point of having one parsing layer.
+ *
+ * WHY THE SERVICE OWNS THE PATH GUARD AND NOT THE EXTENSION. The extension runs in Pi's process and
+ * could ask for any path it liked. The service resolves every path against the workspace root with
+ * the same `resolveInsideRoot` guard the file panel uses, so a `..` or a symlink pointing outside
+ * the workspace is refused by construction rather than by a check somebody has to remember.
+ */
+export class DocumentService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * The workspace a conversation works in, taken from the store.
+     *
+     * The conversation is the caller's identity, and the workspace is derived from it. A request that
+     * named its own workspace would be a request that could read another workspace.
+     */
+    workspacePath(conversationId) {
+        const conversation = this.store.snapshot().conversations.find(item => item.id === conversationId);
+        if (!conversation)
+            throw new Error("会话不存在");
+        const workspace = this.store.snapshot().workspaces.find(item => item.id === conversation.workspaceId);
+        if (!workspace)
+            throw new Error("工作区不存在");
+        return workspace.path;
+    }
+    /**
+     * Reads a file's contents.
+     *
+     * A text file is returned as it is; a document is parsed. The distinction matters because the two
+     * fail differently: a text file that does not exist is a missing file, while a document that
+     * cannot be parsed is a document with a reason.
+     */
+    async read(conversationId, path) {
+        const root = this.workspacePath(conversationId);
+        const absolute = await resolveInsideRoot(root, path);
+        const info = await stat(absolute).catch(() => null);
+        if (!info || !info.isFile())
+            throw new Error(`找不到文件：${path}`);
+        const extension = extname(absolute).toLocaleLowerCase();
+        const format = documentFormatOf(extension);
+        if (format) {
+            try {
+                const extracted = await extractText(absolute, format);
+                return { text: extracted.text, format, warnings: extracted.warnings, etag: await fileEtag(absolute) };
+            }
+            catch (error) {
+                // The parser's reasons are already written for a person - a scan with no text layer, an
+                // encrypted file, a missing package - and they are passed through unchanged. A model that
+                // is told "读取失败" cannot help the person; a model that is told "这份 PDF 是扫描件" can.
+                if (error instanceof DocumentError)
+                    throw new Error(error.message);
+                throw error;
+            }
+        }
+        const { readFile } = await import("node:fs/promises");
+        const buffer = await readFile(absolute);
+        // The etag rides along so a follow-up `document_write` over this file can present the version it
+        // read - the same confirm-before-overwrite the file panel's editor lives by (see `write`).
+        return { text: buffer.toString("utf8"), format: extension || "text", warnings: [], etag: await fileEtag(absolute) };
+    }
+    /**
+     * Writes a document into the workspace.
+     *
+     * The content is Markdown for a Word or PDF document and CSV for a spreadsheet, and the format is
+     * taken from the file's extension - so the caller says "write this report to REPORT.docx" and the
+     * right writer is chosen. An extension that names no document format is refused, because writing
+     * a `.txt` file is what Pi's own `write` tool is for, and a second way to do it is a second way to
+     * be wrong about it.
+     *
+     * OVERWRITING AN EXISTING FILE NEEDS THE VERSION THE CALLER READ, the same rule the file panel's
+     * write enforces (docs/DOCUMENTS.md: 覆盖已有文件前要确认，etag 语义和文件面板一致). A document is a
+     * file a person edits; an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit
+     * made an hour ago with no refusal, no diff, no warning. A missing etag over an existing file and a
+     * stale one are both refused, and the refusal carries the CURRENT etag - which is what makes an
+     * informed overwrite possible, the same way the panel's 409 does: re-sending the current etag is
+     * the deliberate "仍然覆盖", not a skipped check. A file that does not exist yet is the ordinary
+     * create case and needs no confirmation.
+     */
+    async write(conversationId, path, content, title, baseEtag) {
+        const root = this.workspacePath(conversationId);
+        const absolute = await resolveInsideRoot(root, path);
+        const extension = extname(absolute).toLocaleLowerCase();
+        const format = documentFormatOf(extension);
+        if (!format) {
+            throw new Error(`只能写 PDF、Word（.docx）和 Excel（.xlsx）文件；${extension || "这个文件"} 请用 write 工具直接写文本。`);
+        }
+        const existing = await stat(absolute).catch(() => null);
+        if (existing?.isFile()) {
+            const current = await fileEtag(absolute);
+            if (!baseEtag) {
+                throw new Error(`文件已存在：${path}。覆盖它必须先确认版本——先用 document_read 读取该文件，把它返回的 etag 作为 baseEtag 传入；当前 etag：${current}。`);
+            }
+            if (baseEtag !== current) {
+                throw new Error(`文件在磁盘上已被其他程序修改，未写入：${path}（当前 etag：${current}，你提供的是 ${baseEtag}）。如确认覆盖，请带着当前 etag 重试。`);
+            }
+        }
+        const { bytes } = await buildDocument({ format, content, title });
+        await mkdir(dirname(absolute), { recursive: true });
+        await writeFile(absolute, bytes);
+        return { path, bytes: bytes.length, format };
+    }
+}

package/dist/server/application/feishu-service.d.ts

@@ -0,0 +1,132 @@
+import { FeishuCli } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export declare const MAX_FEISHU_REQUEST_BYTES: number;
+/**
+ * WHAT THE PANEL NEEDS TO SHOW, in words a person can act on.
+ */
+export type FeishuStatus = {
+    /** Whether the official CLI is on this machine at all. */
+    installed: boolean;
+    version?: string;
+    /** The application the CLI is configured with, when it has one. */
+    appId?: string;
+    /** Whether a person has authorized the CLI to act as them. */
+    userReady: boolean;
+    /** Whether the CLI can act as the application itself. */
+    botReady: boolean;
+    /** The identity the CLI will use by default. */
+    identity?: "user" | "bot";
+    /** Whether the agent can read and write documents right now. */
+    connected: boolean;
+    /** What to do next, in one sentence. */
+    message: string;
+};
+/** The outcome of starting the connect flow. */
+export type FeishuConnectResult = {
+    ok: boolean;
+    /** Which step the person is on: creating an application, or authorizing their account. */
+    step?: "app" | "login";
+    /** The URL to open in a browser. */
+    verificationUri?: string;
+    /** The device code, kept server-side until the person says they are done. */
+    deviceCode?: string;
+    message: string;
+    /** Feishu's own "what to do about it", when there was one. */
+    hint?: string;
+};
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export declare class FeishuService {
+    private readonly cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    private pendingDeviceCode?;
+    constructor(cli?: FeishuCli);
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The three states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The CLI has an application but no person logged in: the agent can still act as the
+     *   application, but it cannot reach that person's own documents until they authorize it.
+     */
+    status(): Promise<FeishuStatus>;
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application: `config init --new` registers one through a browser confirmation. It BLOCKS
+     *   until the person confirms, so it runs in the background and the URL is taken from its output.
+     * - An application but no person: `auth login --no-wait --json` asks for a device code and hands
+     *   back the URL to open. The code is kept here until the person says they are done.
+     */
+    connect(): Promise<FeishuConnectResult>;
+    /**
+     * FINISHES THE LOGIN, once the person says they authorized it.
+     *
+     * The device code is handed back to the CLI, which completes the exchange and stores the token
+     * in the keychain. Super Pi never sees the token itself.
+     */
+    completeConnect(): Promise<FeishuConnectResult>;
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    read(input: {
+        url: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        title?: string;
+        url: string;
+        format: "markdown";
+        content: string;
+    }>;
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    write(input: {
+        url?: string;
+        content: string;
+        mode?: "create" | "append" | "replace";
+        title?: string;
+        baseRevisionId?: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        url?: string;
+        mode: "create" | "append" | "replace";
+    }>;
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    tool(body: unknown): Promise<unknown>;
+}

package/dist/server/application/feishu-service.js

@@ -0,0 +1,264 @@
+import { FeishuCli, FeishuCliError, errorHint, errorMessage } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export const MAX_FEISHU_REQUEST_BYTES = 4 * 1024 * 1024;
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export class FeishuService {
+    cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    pendingDeviceCode;
+    constructor(cli = new FeishuCli()) {
+        this.cli = cli;
+    }
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The three states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The CLI has an application but no person logged in: the agent can still act as the
+     *   application, but it cannot reach that person's own documents until they authorize it.
+     */
+    async status() {
+        const status = await this.cli.status();
+        if (!status.installed) {
+            return {
+                installed: false,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                message: "没有检测到官方飞书 CLI（lark-cli）。请先在终端运行 npm i -g @larksuite/cli 装上它，再回到这里点「连接飞书账号」。如果已经装了但 Super Pi 找不到（两边的 PATH 不一样），用环境变量 SUPER_PI_FEISHU_CLI 指向它的完整路径再重启 Super Pi。",
+            };
+        }
+        if (!status.appId) {
+            return {
+                installed: true,
+                ...(status.version ? { version: status.version } : {}),
+                userReady: false,
+                botReady: false,
+                connected: false,
+                message: "飞书 CLI 已就绪，但还没有应用。点「连接飞书账号」，它会给你一个浏览器链接，确认之后应用就建好了——不用去开发者后台注册。",
+            };
+        }
+        if (!status.userReady) {
+            return {
+                installed: true,
+                ...(status.version ? { version: status.version } : {}),
+                appId: status.appId,
+                userReady: false,
+                botReady: status.botReady,
+                connected: false,
+                ...(status.identity ? { identity: status.identity } : {}),
+                message: "应用已配置，但还没有登录你的账号。点「连接飞书账号」用浏览器授权，授权之后 Agent 就能以你的身份读写你自己的文档，不用逐篇加协作者。",
+            };
+        }
+        return {
+            installed: true,
+            ...(status.version ? { version: status.version } : {}),
+            appId: status.appId,
+            userReady: true,
+            botReady: status.botReady,
+            connected: true,
+            identity: status.identity ?? "user",
+            message: "已连接：Agent 会以你的身份读写飞书云文档。",
+        };
+    }
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application: `config init --new` registers one through a browser confirmation. It BLOCKS
+     *   until the person confirms, so it runs in the background and the URL is taken from its output.
+     * - An application but no person: `auth login --no-wait --json` asks for a device code and hands
+     *   back the URL to open. The code is kept here until the person says they are done.
+     */
+    async connect() {
+        const status = await this.status();
+        if (!status.installed) {
+            return { ok: false, message: status.message };
+        }
+        if (!status.appId) {
+            const verificationUri = await this.cli.startAppCreation();
+            return {
+                ok: true,
+                step: "app",
+                ...(verificationUri ? { verificationUri } : {}),
+                message: verificationUri
+                    ? "在浏览器里打开这个链接确认一下，应用就建好了（CLI 会把应用和凭据存进系统钥匙串）。确认完点「我已完成」。"
+                    : "CLI 没有打印出链接。请在终端里运行 lark-cli config init --new，按提示扫码确认，然后回到这里点「连接飞书账号」。",
+            };
+        }
+        try {
+            const login = await this.cli.beginLogin();
+            this.pendingDeviceCode = login.deviceCode;
+            return {
+                ok: true,
+                step: "login",
+                ...(login.verificationUri ? { verificationUri: login.verificationUri } : {}),
+                deviceCode: login.deviceCode,
+                message: login.verificationUri
+                    ? "在浏览器里打开这个链接，用你的飞书账号确认授权，然后点「我已完成」。"
+                    : "CLI 已经发起设备码授权。请在浏览器里确认，然后点「我已完成」。",
+            };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * FINISHES THE LOGIN, once the person says they authorized it.
+     *
+     * The device code is handed back to the CLI, which completes the exchange and stores the token
+     * in the keychain. Super Pi never sees the token itself.
+     */
+    async completeConnect() {
+        if (!this.pendingDeviceCode) {
+            return { ok: false, message: "没有待完成的登录。点「连接飞书账号」重新开始。" };
+        }
+        const deviceCode = this.pendingDeviceCode;
+        this.pendingDeviceCode = undefined;
+        try {
+            const envelope = await this.cli.completeLogin(deviceCode);
+            if (envelope.ok === false) {
+                return { ok: false, message: errorMessage(envelope), ...(errorHint(envelope) ? { hint: errorHint(envelope) } : {}) };
+            }
+            return { ok: true, message: "已连接。现在 Agent 能以你的身份读写飞书云文档了。" };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    async read(input) {
+        const document = await this.cli.fetchDocument(input.url);
+        return {
+            ...(document.documentId ? { documentId: document.documentId } : {}),
+            ...(document.revisionId !== undefined ? { revisionId: document.revisionId } : {}),
+            ...(document.title ? { title: document.title } : {}),
+            url: input.url,
+            format: "markdown",
+            content: document.content,
+        };
+    }
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    async write(input) {
+        const mode = input.mode ?? (input.url ? "append" : "create");
+        const content = String(input.content ?? "");
+        if (!content.trim())
+            throw new Error("要写入的内容是空的。");
+        if (mode === "create") {
+            const title = input.title?.trim() || titleFromMarkdown(content);
+            const created = await this.cli.createDocument(title, content);
+            return {
+                ...(created.documentId ? { documentId: created.documentId } : {}),
+                ...(created.revisionId !== undefined ? { revisionId: created.revisionId } : {}),
+                ...(created.url ? { url: created.url } : {}),
+                mode,
+            };
+        }
+        if (!input.url)
+            throw new Error("追加或覆盖需要给出文档链接或 token。");
+        if (mode === "replace") {
+            if (!input.baseRevisionId) {
+                throw new Error("覆盖前需要确认文档版本：先用 feishu_doc_read 读一次这篇文档，把它返回的 revisionId 作为 baseRevisionId 传入。覆盖会清空整篇文档，必须先看过。");
+            }
+            const revision = Number(input.baseRevisionId);
+            if (!Number.isFinite(revision)) {
+                throw new Error(`baseRevisionId 不是有效的版本号：${input.baseRevisionId}`);
+            }
+            const updated = await this.cli.updateDocument(input.url, "overwrite", content, revision);
+            return {
+                ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+                url: input.url,
+                mode,
+            };
+        }
+        const updated = await this.cli.updateDocument(input.url, "append", content);
+        return {
+            ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+            url: input.url,
+            mode,
+        };
+    }
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    async tool(body) {
+        const request = (body ?? {});
+        const action = String(request.action ?? "read");
+        if (action === "read") {
+            return this.read({ url: String(request.url ?? "") });
+        }
+        if (action === "write") {
+            const mode = request.mode === "create" || request.mode === "append" || request.mode === "replace" ? request.mode : undefined;
+            return this.write({
+                ...(request.url ? { url: String(request.url) } : {}),
+                content: String(request.content ?? ""),
+                ...(mode ? { mode } : {}),
+                ...(request.title ? { title: String(request.title) } : {}),
+                ...(request.baseRevisionId ? { baseRevisionId: String(request.baseRevisionId) } : {}),
+            });
+        }
+        throw new Error(`未知的飞书工具操作：${action}`);
+    }
+}
+/** The message of a failure, whatever shape the failure has. */
+function messageOf(error) {
+    if (error instanceof FeishuCliError)
+        return error.message;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** The hint of a failure, when it carries one. */
+function hintOf(error) {
+    return error instanceof FeishuCliError ? error.hint : undefined;
+}
+/**
+ * A TITLE FROM THE CONTENT, for a document created without one.
+ *
+ * The first heading is what a person would have called it, and a generated title is better than
+ * "未命名文档" only when there is something to take.
+ */
+function titleFromMarkdown(content) {
+    for (const line of content.split("\n")) {
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line.trim());
+        if (heading?.[1])
+            return heading[1].slice(0, 800);
+    }
+    const firstLine = content.split("\n").map((line) => line.trim()).find((line) => line.length > 0);
+    return (firstLine ? firstLine.slice(0, 800) : "未命名文档");
+}