larkcc 0.4.0 → 0.6.0

package/dist/format/document.js

@@ -2,16 +2,18 @@
  * 飞书文档处理模块
  * 将 Markdown 转换为飞书文档块
  */
-import { buildTextBlock, buildHeadingBlock, buildCodeBlock, buildBulletBlock, buildOrderedBlock, buildQuoteBlock, buildTodoBlock, buildEquationBlock, buildCalloutBlock, buildDividerBlock, buildTableBlock, parseInlineText, } from "./builder.js";
-import { parseTable, parseTodo, parseBlockEquation, parseCallout, parseHeading, isCodeBlockStart, isCodeBlockEnd, isDivider, isBulletList, isOrderedList, } from "./parser.js";
+import { buildTextBlock, buildHeadingBlock, buildCodeBlock, buildBulletBlock, buildOrderedBlock, buildQuoteBlock, buildTodoBlock, buildEquationBlock, buildCalloutBlock, buildDividerBlock, buildImageBlock, buildTableBlock, parseInlineText, } from "./builder.js";
+import { parseTable, parseTodo, parseBlockEquation, parseCallout, parseHeading, isCodeBlockStart, isCodeBlockEnd, isDivider, isBulletList, isOrderedList, parseBulletList, parseOrderedList, } from "./parser.js";
 import { sanitizeContent } from "./sanitize.js";
 import { BlockType } from "./constants.js";
 // ── 主转换函数 ───────────────────────────────────────────────────
 /**
  * 将 Markdown 文本转换为飞书文档块
+ *
+ * 返回 DocumentBlockItem[] 保持原始顺序，区分简单块和需要 Descendants API 的复杂块
  */
 export function markdownToBlocks(markdown, originalMessage, meta) {
-    const blocks = [];
+    const items = [];
     // 1. 内容清理
     const { content: sanitizedMarkdown, warnings } = sanitizeContent(markdown);
     if (warnings.length > 0) {
@@ -27,7 +29,7 @@ export function markdownToBlocks(markdown, originalMessage, meta) {
         if (currentPara.length > 0) {
             const content = currentPara.join("\n").trim();
             if (content) {
-                blocks.push(buildTextBlock(content));
+                items.push({ type: "simple", block: buildTextBlock(content) });
             }
             currentPara = [];
         }
@@ -37,7 +39,7 @@ export function markdownToBlocks(markdown, originalMessage, meta) {
         // --- 代码块处理 ---
         if (inCodeBlock) {
             if (isCodeBlockEnd(line)) {
-                blocks.push(buildCodeBlock(codeContent.join("\n"), codeLang));
+                items.push({ type: "simple", block: buildCodeBlock(codeContent.join("\n"), codeLang) });
                 inCodeBlock = false;
                 codeContent = [];
                 codeLang = "";
@@ -59,24 +61,27 @@ export function markdownToBlocks(markdown, originalMessage, meta) {
         const equationResult = parseBlockEquation(lines, i);
         if (equationResult) {
             flushPara();
-            blocks.push(buildEquationBlock(equationResult.result.latex));
+            items.push({ type: "simple", block: buildEquationBlock(equationResult.result.latex) });
             i = equationResult.endIndex;
             continue;
         }
-        // --- 高亮块 ---
+        // --- 高亮块（需要 Descendants API） ---
         const calloutResult = parseCallout(lines, i);
         if (calloutResult) {
             flushPara();
             const { type, content } = calloutResult.result;
-            blocks.push(buildCalloutBlock(type, content.join("\n")));
+            items.push({ type: "callout", data: buildCalloutBlock(type, content.join("\n")) });
             i = calloutResult.endIndex;
             continue;
         }
-        // --- 表格 ---
+        // --- 表格（需要 Descendants API） ---
         const tableResult = parseTable(lines, i);
         if (tableResult) {
             flushPara();
-            blocks.push(buildTableBlock(tableResult.data));
+            const tableBlock = buildTableBlock(tableResult.data);
+            // 保留原始 Markdown，用于表格写入失败时的降级显示
+            tableBlock.rawMarkdown = lines.slice(i, tableResult.endIndex).join("\n");
+            items.push({ type: "table", data: tableBlock });
             i = tableResult.endIndex;
             continue;
         }
@@ -84,7 +89,7 @@ export function markdownToBlocks(markdown, originalMessage, meta) {
         const todoResult = parseTodo(line);
         if (todoResult) {
             flushPara();
-            blocks.push(buildTodoBlock(todoResult.content, todoResult.checked));
+            items.push({ type: "simple", block: buildTodoBlock(todoResult.content, todoResult.checked) });
             continue;
         }
         // --- 标题 ---
@@ -92,64 +97,78 @@ export function markdownToBlocks(markdown, originalMessage, meta) {
         if (headingLevel > 0) {
             flushPara();
             const content = line.slice(headingLevel + 1).trim();
-            blocks.push(buildHeadingBlock(headingLevel, content));
+            items.push({ type: "simple", block: buildHeadingBlock(headingLevel, content) });
             continue;
         }
         // --- 分割线 ---
         if (isDivider(line)) {
             flushPara();
-            blocks.push(buildDividerBlock());
+            items.push({ type: "simple", block: buildDividerBlock() });
             continue;
         }
         // --- 引用块 ---
         if (line.trim().startsWith("> ")) {
             flushPara();
             const quoteContent = line.trim().slice(2);
-            // 检查是否是高亮块语法（已在上面处理）
             if (!quoteContent.match(/^\[!\w+\]/)) {
-                blocks.push(buildQuoteBlock(quoteContent));
+                items.push({ type: "simple", block: buildQuoteBlock(quoteContent) });
             }
             continue;
         }
-        // --- 无序列表 ---
+        // --- 无序列表（支持嵌套层级） ---
         if (isBulletList(line)) {
             flushPara();
-            const match = line.match(/^(\s*)[-*]\s+(.+)$/);
-            if (match) {
-                blocks.push(buildBulletBlock(match[2]));
+            const parsed = parseBulletList(line);
+            if (parsed) {
+                items.push({ type: "simple", block: buildBulletBlock(parsed.content, parsed.level) });
             }
             continue;
         }
-        // --- 有序列表 ---
+        // --- 有序列表（支持嵌套层级） ---
         if (isOrderedList(line)) {
             flushPara();
-            const match = line.match(/^(\s*)(\d+)\.\s+(.+)$/);
-            if (match) {
-                blocks.push(buildOrderedBlock(match[3]));
+            const parsed = parseOrderedList(line);
+            if (parsed) {
+                items.push({ type: "simple", block: buildOrderedBlock(parsed.content, parsed.level) });
             }
             continue;
         }
+        // --- 图片（img_xxx 格式，已由 ImageResolver 处理） ---
+        const imgMatch = line.trim().match(/^!\[([^\]]*)\]\((img_[^)]+)\)$/i);
+        if (imgMatch) {
+            flushPara();
+            items.push({ type: "simple", block: buildImageBlock(imgMatch[2]) });
+            continue;
+        }
+        // --- 空行（段落分隔符） ---
+        if (line.trim() === "") {
+            flushPara();
+            continue;
+        }
         // --- 普通段落 ---
         currentPara.push(line);
     }
     // 处理剩余段落
     flushPara();
     // 3. 添加元数据头部
-    const headerBlocks = buildDocumentHeader(originalMessage, meta);
-    return { blocks: [...headerBlocks, ...blocks], warnings };
+    const headerItems = buildDocumentHeader(originalMessage, meta);
+    return { items: [...headerItems, ...items], warnings };
 }
 // ── 文档头部构建 ───────────────────────────────────────────────────
 function buildDocumentHeader(originalMessage, meta) {
-    const blocks = [];
+    const items = [];
     // 引用块显示用户原始消息
     if (originalMessage) {
-        blocks.push({
-            block_type: BlockType.QUOTE,
-            quote: { elements: parseInlineText(originalMessage) },
+        items.push({
+            type: "simple",
+            block: {
+                block_type: BlockType.QUOTE,
+                quote: { elements: parseInlineText(originalMessage) },
+            },
         });
     }
     // 分割线
-    blocks.push(buildDividerBlock());
+    items.push({ type: "simple", block: buildDividerBlock() });
     // 元数据（每行一个 text block，确保换行）
     const metaLines = [
         `📁 工作目录: ${meta.cwd}`,
@@ -158,13 +177,16 @@ function buildDocumentHeader(originalMessage, meta) {
         `📅 时间: ${meta.datetime}`,
     ];
     for (const line of metaLines) {
-        blocks.push({
-            block_type: BlockType.TEXT,
-            text: { elements: [{ text_run: { content: line } }] },
+        items.push({
+            type: "simple",
+            block: {
+                block_type: BlockType.TEXT,
+                text: { elements: [{ text_run: { content: line } }] },
+            },
         });
     }
     // 分割线
-    blocks.push(buildDividerBlock());
-    return blocks;
+    items.push({ type: "simple", block: buildDividerBlock() });
+    return items;
 }
 //# sourceMappingURL=document.js.map

package/dist/format/document.js.map

@@ -1 +1 @@
-{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/format/document.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/format/document.ts"],"names":[],"mappings":"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"}

package/dist/format/duration.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 时间格式化 & Thinking 卡片元素构建
+ *
+ * 统一 CardKit 和 Update 模式的 thinking 折叠面板，
+ * 对齐 openclaw-lark 的 collapsible_panel 方案。
+ */
+/** Thinking 内容截断阈值（字符数） */
+export declare const THINKING_OVERFLOW_TRUNCATE = 3000;
+/** 秒 → "3.2s" / "1m 23s" */
+export declare function formatDuration(seconds: number): string;
+/** 毫秒 → "3.2s" / "1m 23s" */
+export declare function formatReasoningDuration(ms: number): string;
+interface ThinkingPanelOptions {
+    thinking: string;
+    reasoningElapsedMs?: number;
+}
+/**
+ * 构建 thinking 折叠面板元素（collapsible_panel）
+ *
+ * 返回 [collapsible_panel, hr]，可直接展开到卡片 elements 数组。
+ * CardKit 和 Update 模式共用此函数，避免重复。
+ */
+export declare function buildThinkingPanel(options: ThinkingPanelOptions): any[];
+export {};

package/dist/format/duration.js

@@ -0,0 +1,72 @@
+/**
+ * 时间格式化 & Thinking 卡片元素构建
+ *
+ * 统一 CardKit 和 Update 模式的 thinking 折叠面板，
+ * 对齐 openclaw-lark 的 collapsible_panel 方案。
+ */
+// ── 常量 ──────────────────────────────────────────────────
+/** Thinking 内容截断阈值（字符数） */
+export const THINKING_OVERFLOW_TRUNCATE = 3000;
+// ── 时间格式化 ─────────────────────────────────────────────
+/** 秒 → "3.2s" / "1m 23s" */
+export function formatDuration(seconds) {
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainSec = Math.round(seconds % 60);
+    return `${minutes}m ${remainSec}s`;
+}
+/** 毫秒 → "3.2s" / "1m 23s" */
+export function formatReasoningDuration(ms) {
+    return formatDuration(ms / 1000);
+}
+/**
+ * 构建 thinking 折叠面板元素（collapsible_panel）
+ *
+ * 返回 [collapsible_panel, hr]，可直接展开到卡片 elements 数组。
+ * CardKit 和 Update 模式共用此函数，避免重复。
+ */
+export function buildThinkingPanel(options) {
+    const truncatedThinking = options.thinking.length > THINKING_OVERFLOW_TRUNCATE
+        ? options.thinking.slice(0, THINKING_OVERFLOW_TRUNCATE) + "\n..."
+        : options.thinking;
+    const durLabel = options.reasoningElapsedMs
+        ? ` ${formatReasoningDuration(options.reasoningElapsedMs)}`
+        : "";
+    return [
+        {
+            tag: "collapsible_panel",
+            expanded: false,
+            header: {
+                title: {
+                    tag: "markdown",
+                    content: `💭 Thought${durLabel}`,
+                    i18n_content: {
+                        zh_cn: `💭 思考${durLabel}`,
+                        en_us: `💭 Thought${durLabel}`,
+                    },
+                },
+                vertical_align: "center",
+                icon: {
+                    tag: "standard_icon",
+                    token: "down-small-ccm_outlined",
+                    size: "16px 16px",
+                },
+                icon_position: "follow_text",
+                icon_expanded_angle: -180,
+            },
+            border: { color: "grey", corner_radius: "5px" },
+            vertical_spacing: "8px",
+            padding: "8px 8px 8px 8px",
+            elements: [
+                {
+                    tag: "markdown",
+                    content: truncatedThinking,
+                    text_size: "notation",
+                },
+            ],
+        },
+        { tag: "hr" },
+    ];
+}
+//# sourceMappingURL=duration.js.map

package/dist/format/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/format/duration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2DAA2D;AAE3D,2BAA2B;AAC3B,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C,yDAAyD;AAEzD,4BAA4B;AAC5B,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IAC3C,OAAO,GAAG,OAAO,KAAK,SAAS,GAAG,CAAC;AACrC,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,uBAAuB,CAAC,EAAU;IAChD,OAAO,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AACnC,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAC9D,MAAM,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,0BAA0B;QAC5E,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,0BAA0B,CAAC,GAAG,OAAO;QACjE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAErB,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB;QACzC,CAAC,CAAC,IAAI,uBAAuB,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE;QAC3D,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL;YACE,GAAG,EAAE,mBAAmB;YACxB,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE;gBACN,KAAK,EAAE;oBACL,GAAG,EAAE,UAAU;oBACf,OAAO,EAAE,aAAa,QAAQ,EAAE;oBAChC,YAAY,EAAE;wBACZ,KAAK,EAAE,QAAQ,QAAQ,EAAE;wBACzB,KAAK,EAAE,aAAa,QAAQ,EAAE;qBAC/B;iBACF;gBACD,cAAc,EAAE,QAAQ;gBACxB,IAAI,EAAE;oBACJ,GAAG,EAAE,eAAe;oBACpB,KAAK,EAAE,yBAAyB;oBAChC,IAAI,EAAE,WAAW;iBAClB;gBACD,aAAa,EAAE,aAAa;gBAC5B,mBAAmB,EAAE,CAAC,GAAG;aAC1B;YACD,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE;YAC/C,gBAAgB,EAAE,KAAK;YACvB,OAAO,EAAE,iBAAiB;YAC1B,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,UAAU;oBACf,OAAO,EAAE,iBAAiB;oBAC1B,SAAS,EAAE,UAAU;iBACtB;aACF;SACF;QACD,EAAE,GAAG,EAAE,IAAI,EAAE;KACd,CAAC;AACJ,CAAC"}

package/dist/format/guide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 飞书格式指导模块
+ *
+ * 从文件加载格式指导内容，注入到 Claude 的 system prompt 中。
+ *
+ * 文件优先级：
+ * 1. ~/.larkcc/format-guide.md（用户自定义）
+ * 2. resources/format-guide.md（随项目发布的默认文件）
+ * 3. 内置默认内容（代码内 fallback）
+ *
+ * 注入方式：通过 query() 的 options.systemPrompt.append
+ * 注入时机：每次调用 query() 时传入，整个会话生效
+ */
+/**
+ * 获取格式指导内容（带缓存）
+ *
+ * 只在第一次调用时读取文件，后续返回缓存。
+ */
+export declare function getFormatGuideContent(): string;

package/dist/format/guide.js

@@ -0,0 +1,201 @@
+/**
+ * 飞书格式指导模块
+ *
+ * 从文件加载格式指导内容，注入到 Claude 的 system prompt 中。
+ *
+ * 文件优先级：
+ * 1. ~/.larkcc/format-guide.md（用户自定义）
+ * 2. resources/format-guide.md（随项目发布的默认文件）
+ * 3. 内置默认内容（代码内 fallback）
+ *
+ * 注入方式：通过 query() 的 options.systemPrompt.append
+ * 注入时机：每次调用 query() 时传入，整个会话生效
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+// ESM 兼容：__dirname 在 ESM 中不可用
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// ── 内置默认格式指导（fallback）────────────────────────────────
+const DEFAULT_FORMAT_GUIDE = `# 飞书格式规范
+
+你的回复会通过飞书展示。短内容显示为交互式卡片，长内容写入飞书云文档。
+两者对 Markdown 的支持不同，请严格遵守以下规范。
+
+## 一、通用规则（卡片和文档都适用）
+
+### 代码块
+- 必须标注语言：\`\`\`typescript、\`\`\`python、\`\`\`bash 等
+- 不要使用无语言标记的代码块（\`\`\`）
+- 不要在代码块外使用 | 开头的文字（会被误识别为表格）
+
+### 图片
+- 不要使用外部图片链接 ![alt](https://...)
+- 飞书只支持 img_xxx 格式的内部图片 key
+
+### 段落
+- 段落之间用空行分隔
+- 不要用 <br> 或 HTML 标签控制换行
+
+### 列表
+- 嵌套不要超过 2 级
+- 嵌套缩进统一用 2 个空格
+
+### 不要使用
+- HTML 标签（除了表格合并 <td colspan="2">，仅文档模式可用）
+- 脚注 [^1]
+- 折叠 <details>
+- 任务列表外的复选框语法
+
+## 二、卡片规则（短内容，显示为交互式卡片）
+
+飞书卡片 Markdown 只支持有限的格式子集：
+
+### 标题
+- 只用 #### (H4) 和 ##### (H5)
+- 不要使用 # ## ###（不会渲染为标题）
+
+### 表格
+- 列数不超过 5 列
+- 不要使用 colspan/rowspan 合并（卡片不支持 HTML）
+- 单元格内容尽量简短
+
+### 不支持（不要在卡片内容中使用）
+- > [!TYPE] Callout 语法
+- $$ 数学公式
+- 嵌套列表
+- 删除线 ~~text~~
+
+### 建议
+- 代码块标注语言
+- 使用 **粗体** 和 *斜体* 强调重点
+- 使用 > 引用块
+- 使用 --- 分割线
+
+## 三、文档规则（长内容，写入飞书云文档）
+
+飞书文档支持更丰富的格式：
+
+### Callout 高亮块
+使用 > [!TYPE] 语法，支持的类型和推荐 emoji：
+
+| 类型 | 推荐 emoji | 用途 |
+|------|-----------|------|
+| > [!NOTE] | 💡 | 提示信息 |
+| > [!TIP] | ✅ | 实用建议 |
+| > [!WARNING] | ⚠️ | 注意事项 |
+| > [!DANGER] | 🔴 | 危险操作 |
+| > [!CAUTION] | 🟡 | 谨慎操作 |
+| > [!INFO] | ℹ️ | 补充信息 |
+
+示例：
+> [!TIP] ✅
+> 使用 async/await 可以避免回调地狱。
+
+注意：
+- Callout 中不要嵌套列表或表格（渲染会失败）
+- 每条内容单独一行，用 > 开头
+
+### 表格
+- 列数建议不超过 6 列
+- 单元格内容不超过 200 个字符
+- 可以使用 <td colspan="N"> 合并列
+- 不要在同一表格中混用合并单元格和普通单元格
+- 表头和分隔符是必需的
+
+### 数学公式
+- 块级公式用 $$...$$
+- 行内公式用 $...$
+- 不要使用 \\\多行对齐（飞书不支持）
+- 不要使用 \\begin{}...\\end{} 环境
+
+### 代码块
+- 必须标注语言（飞书会根据语言做语法高亮）
+- 支持的语言：typescript, javascript, python, java, go, rust, bash, sql, json, yaml, xml, html, css, markdown, c, cpp, csharp, ruby, php, swift, kotlin, dart, r, matlab, scala, lua, perl, haskell, elixir, clojure, shell, powershell, dockerfile, makefile, toml, ini, diff, plaintext
+
+### 标题
+- 使用 H1-H6 完整层级
+- 文档会保留原始标题级别
+
+## 四、反面教材（这些会导致渲染失败或格式异常）
+
+❌ 代码块外使用 | 开头 → 被误识别为表格
+❌ Callout 中嵌套列表 → 渲染失败
+❌ 数学公式使用多行对齐 → 公式显示异常
+❌ 表格单元格内容超长 → 表格溢出文档宽度
+❌ 超过 3 级的列表嵌套 → 只显示为 2 级
+❌ 空的代码块（无语言标记且无内容）→ 创建失败
+❌ 在段落之间不空行 → 段落粘连显示为一坨文字`;
+// ── 文件路径 ───────────────────────────────────────────────────
+function getUserGuidePath() {
+    return path.join(os.homedir(), ".larkcc", "format-guide.md");
+}
+function getBundledGuidePaths() {
+    return [
+        // 编译后 dist/format/guide.js → dist/resources/format-guide.md
+        path.join(__dirname, "..", "resources", "format-guide.md"),
+        // 开发时 src/format/guide.ts → resources/format-guide.md
+        path.join(__dirname, "..", "..", "resources", "format-guide.md"),
+    ];
+}
+// ── 加载函数 ───────────────────────────────────────────────────
+/**
+ * 加载格式指导内容
+ *
+ * 优先级：
+ * 1. ~/.larkcc/format-guide.md（用户自定义）
+ * 2. resources/format-guide.md（随项目发布的默认文件）
+ * 3. 内置默认内容（代码内 fallback）
+ */
+function loadFormatGuideContent() {
+    // 1. 用户自定义文件
+    const userPath = getUserGuidePath();
+    try {
+        if (fs.existsSync(userPath)) {
+            const content = fs.readFileSync(userPath, "utf8").trim();
+            if (content) {
+                console.error(`[GUIDE] Loaded user format guide: ${userPath}`);
+                return content;
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[GUIDE] Failed to read user guide: ${error}`);
+    }
+    // 2. 随项目发布的默认文件（优先 dist/resources/，其次项目根 resources/）
+    const bundledPaths = getBundledGuidePaths();
+    for (const bundledPath of bundledPaths) {
+        try {
+            if (fs.existsSync(bundledPath)) {
+                const content = fs.readFileSync(bundledPath, "utf8").trim();
+                if (content) {
+                    console.error(`[GUIDE] Loaded bundled format guide: ${bundledPath}`);
+                    return content;
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[GUIDE] Failed to read bundled guide ${bundledPath}: ${error}`);
+        }
+    }
+    // 3. 内置默认
+    console.error("[GUIDE] Using built-in default format guide");
+    return DEFAULT_FORMAT_GUIDE;
+}
+// ── 缓存 ───────────────────────────────────────────────────────
+let cachedGuide = null;
+/**
+ * 获取格式指导内容（带缓存）
+ *
+ * 只在第一次调用时读取文件，后续返回缓存。
+ */
+export function getFormatGuideContent() {
+    if (cachedGuide !== null) {
+        return cachedGuide;
+    }
+    cachedGuide = loadFormatGuideContent();
+    return cachedGuide;
+}
+//# sourceMappingURL=guide.js.map

package/dist/format/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../../src/format/guide.ts"],"names":[],"mappings":"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"}

package/dist/format/image-resolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 图片解析模块
+ *
+ * 将 Markdown 中的外部图片 URL 下载并上传到飞书，
+ * 替换为飞书内部的 img_xxx 格式 key。
+ *
+ * 处理流程：
+ * 1. 提取代码块（保护代码内容）
+ * 2. 扫描 ![alt](https?://...) 模式
+ * 3. 串行下载 + 上传（避免触发速率限制）
+ * 4. 替换 URL → img_xxx
+ * 5. 恢复代码块
+ *
+ * 失败的图片保留原始 URL，由后续 sanitizeContent 降级为链接。
+ */
+export interface ImageResolveResult {
+    /** 替换后的 Markdown 内容 */
+    content: string;
+    /** 成功上传的图片数 */
+    uploaded: number;
+    /** 上传失败的图片数 */
+    failed: number;
+}
+/**
+ * 解析 Markdown 中的外部图片，下载并上传到飞书
+ *
+ * @param markdown 原始 Markdown 内容
+ * @param token tenant_access_token
+ * @returns 替换后的内容和统计信息
+ */
+export declare function resolveImages(markdown: string, token: string): Promise<ImageResolveResult>;