lark-docx2md 0.5.1 → 0.5.3-beta.0

package/README.md

@@ -45,6 +45,7 @@ npx -y lark-docx2md@latest download <url>
 | `--agent [mode]`         | Agent 模式：日志 ERROR。不传值（或 `=true`）为在线模式，Markdown 输出到 stdout；传 `local` 则落盘后输出引导 AI 读取的提示词 | `LARK_DOCX2MD_AGENT=true\|local`    | `false`               |
 | `--image-mode <mode>`    | 图片处理模式：`local`（下载到本地）或 `online`（24h 临时链接） | `LARK_DOCX2MD_IMAGE_MODE`    | `local`               |
 | `--filter-title <title>` | 按标题过滤：仅转换匹配标题及其下级内容（匹配到同级或更高级标题时截止） | —                            | —                     |
+| `--filter-title-block-id <id>` | 按 heading 块 id 精确过滤（无同名歧义），通常配合 `get-titles` 子命令获取；与 `--filter-title` 互斥 | —                            | —                     |
 | `--wb-format <format>`   | 画板输出格式：`base64`、`inline-svg`、`svg`、`yaml` | `LARK_DOCX2MD_WB_FORMAT`     | `svg`（agent 下默认 `yaml`） |
 | `--wb-bg <style>`        | 画板 SVG 背景：`none`、`dot` 或颜色值如 `#fff`       | `LARK_DOCX2MD_WB_BG`         | `none`                |
 | `--wb-image-mode <mode>` | 画板图片模式：`online`、`base64` 或 `local`        | `LARK_DOCX2MD_WB_IMAGE_MODE` | `local`               |
@@ -54,7 +55,25 @@ npx -y lark-docx2md@latest download <url>
 > - `--agent`（在线）：强制 `--image-mode=online`、`--wb-image-mode=online`；`--wb-format` 默认 `yaml`，仅允许 `inline-svg` / `yaml`；转换完成后 Markdown 直接通过 stdout 输出。
 > - `--agent local`：强制 `--image-mode=local`、`--wb-image-mode=local`（Markdown、图片、画板中的图片均落盘）；`--wb-format` 默认 `yaml`，仅允许 `inline-svg` / `yaml`；stdout 输出引导 AI 读取文件的提示词（包含绝对路径）。
 > - 非 agent 模式下 `--wb-format yaml` 时：`--wb-image-mode` 强制为 `online`。
-> - `--filter-title`：按标题文本精确匹配（忽略前后空格），收集该标题及其所有子级块，遇到同级或更高级标题时停止。未匹配到则报错提示。
+> - `--filter-title`：按标题文本精确匹配（忽略前后空格），收集该标题及其所有子级块，遇到同级或更高级标题时停止。同名标题取首个；未匹配时错误信息附全文标题 yaml 清单。
+> - `--filter-title-block-id`：按 heading 块 id 严格相等匹配，适用于同名标题或脚本化场景；通常先用 `get-titles` 查出目标 `blockId` 再传入。与 `--filter-title` 互斥。
+
+## 子命令：`get-titles`
+
+列出 docx/wiki 文档全部标题（不支持 sheets），配合 `--filter-title-block-id` 使用可避开同名歧义。
+
+```bash
+npx -y lark-docx2md@latest get-titles --agent <url>
+```
+
+| 参数                    | 说明                                                                                       | 默认值    |
+|-----------------------|------------------------------------------------------------------------------------------|--------|
+| `<url>`               | 飞书 wiki/docx URL                                                                       | —      |
+| `--max-level <n>`     | 仅输出 `level <= n` 的标题（1~9）                                                     | `9`    |
+| `--format <format>`   | 输出格式：`yaml`（扁平） \| `yaml-tree`（嵌套） \| `json` \| `tree`（json 嵌套） \| `text`（缩进的 markdown 标题） | `yaml` |
+| `--agent [mode]`      | 同 `dl`，降低日志级别                                                                 | —      |
+
+输出包含 `blockId` / `index` / `level` / `text` / `path`，可被 AI 直接消费用于选择目标章节。
 
 ## 功能
 

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { r as setLogLevel, t as convert } from "./converter-Bqb4bqxh.js";
+import { i as getTitles, n as convert, o as setLogLevel, r as formatTitlesAsText, s as serializeYaml, t as buildTitleTree } from "./converter-D1nCzDJF.js";
 import { Command } from "commander";
 import { LoggerLevel } from "@larksuiteoapi/node-sdk";
 //#region src/cli.ts
 const program = new Command();
 program.name("larkDocx2md").description("Download Lark/Feishu documents to markdown");
-program.command("download").alias("dl").description("Download a wiki document to markdown").option("--app-id <id>", "Feishu app ID (or read from LARK_DOCX2MD_APP_ID)").option("--app-secret <secret>", "Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)").option("-o, --output <dir>", "Output directory (or LARK_DOCX2MD_OUTPUT)").option("--agent [mode]", "Enable agent mode: ERROR log level, and AI-oriented stdout. Pass \"local\" to save markdown/images/whiteboards to disk and print a read-file prompt (or LARK_DOCX2MD_AGENT=true|local)").option("--wb-format <format>", "Whiteboard output format: \"base64\", \"inline-svg\", \"svg\", or \"yaml\" (or LARK_DOCX2MD_WB_FORMAT)").option("--wb-bg <style>", "Whiteboard SVG background: \"none\", \"dot\", or a color like \"#fff\" (or LARK_DOCX2MD_WB_BG)").option("--wb-image-mode <mode>", "Whiteboard image mode: \"online\", \"base64\", or \"local\" (or LARK_DOCX2MD_WB_IMAGE_MODE)").option("--image-mode <mode>", "Image handling mode: \"local\" or \"online\" (or LARK_DOCX2MD_IMAGE_MODE)").option("--filter-title <title>", "Only convert the section matching this heading title").argument("<url>", "Feishu wiki document URL: https://*.feishu.cn/wiki/*").action(async (url, opts) => {
+program.command("download").alias("dl").description("Download a wiki document to markdown").option("--app-id <id>", "Feishu app ID (or read from LARK_DOCX2MD_APP_ID)").option("--app-secret <secret>", "Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)").option("-o, --output <dir>", "Output directory (or LARK_DOCX2MD_OUTPUT)").option("--agent [mode]", "Enable agent mode: ERROR log level, and AI-oriented stdout. Pass \"local\" to save markdown/images/whiteboards to disk and print a read-file prompt (or LARK_DOCX2MD_AGENT=true|local)").option("--wb-format <format>", "Whiteboard output format: \"base64\", \"inline-svg\", \"svg\", or \"yaml\" (or LARK_DOCX2MD_WB_FORMAT)").option("--wb-bg <style>", "Whiteboard SVG background: \"none\", \"dot\", or a color like \"#fff\" (or LARK_DOCX2MD_WB_BG)").option("--wb-image-mode <mode>", "Whiteboard image mode: \"online\", \"base64\", or \"local\" (or LARK_DOCX2MD_WB_IMAGE_MODE)").option("--image-mode <mode>", "Image handling mode: \"local\" or \"online\" (or LARK_DOCX2MD_IMAGE_MODE)").option("--filter-title <title>", "Only convert the section matching this heading title (single title, first match wins on duplicates)").option("--filter-title-block-id <id>", "Only convert the section whose heading block id matches (most precise; obtain from get-titles)").argument("<url>", "Feishu wiki document URL: https://*.feishu.cn/wiki/*").action(async (url, opts) => {
 	opts.appId = opts.appId ?? process.env.LARK_DOCX2MD_APP_ID;
 	opts.appSecret = opts.appSecret ?? process.env.LARK_DOCX2MD_APP_SECRET;
 	opts.output = opts.output ?? process.env.LARK_DOCX2MD_OUTPUT ?? "./larkDocx2mdOutput";
@@ -45,6 +45,7 @@ program.command("download").alias("dl").description("Download a wiki document to
 		"base64",
 		"local"
 	].includes(opts.wbImageMode)) program.error(`Invalid --wb-image-mode "${opts.wbImageMode}", must be "online", "base64", or "local"`);
+	if (opts.filterTitle && opts.filterTitleBlockId) program.error("--filter-title and --filter-title-block-id are mutually exclusive; choose one");
 	const appId = opts.appId;
 	const appSecret = opts.appSecret;
 	if (!appId || !appSecret) program.error("Missing credentials: pass --app-id/--app-secret or set LARK_DOCX2MD_APP_ID/LARK_DOCX2MD_APP_SECRET");
@@ -58,11 +59,68 @@ program.command("download").alias("dl").description("Download a wiki document to
 		wbBg: opts.wbBg,
 		wbFormat: opts.wbFormat,
 		agent: agentLocal ? "local" : opts.agent === true,
-		filterTitle: opts.filterTitle?.trim()
+		filterTitle: opts.filterTitle?.trim(),
+		filterTitleBlockId: opts.filterTitleBlockId?.trim()
 	});
 	if (agentLocal) process.stdout.write(`**The Feishu document has been downloaded to the following absolute path:**\n\n\`${result.filePath}\`\n\n**Read this file to access the full markdown content.**\n`);
 	else if (opts.agent === true) process.stdout.write(result.markdown);
 });
+program.command("get-titles").description("Print all headings (level 1~9) of a wiki/docx document. Useful before --filter-title-block-id.").option("--app-id <id>", "Feishu app ID (or read from LARK_DOCX2MD_APP_ID)").option("--app-secret <secret>", "Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)").option("--max-level <n>", "Only output headings whose level <= n (1~9)", "9").option("--format <format>", "Output format: \"yaml\" (flat, default) | \"yaml-tree\" (nested) | \"json\" (flat) | \"tree\" (json nested) | \"text\" (indented markdown headings)", "yaml").option("--agent [mode]", "Enable agent mode: ERROR log level, AI-oriented stdout (or LARK_DOCX2MD_AGENT=true|local)").argument("<url>", "Feishu wiki/docx URL: https://*.feishu.cn/{wiki,docx,docs}/*").action(async (url, opts) => {
+	opts.appId = opts.appId ?? process.env.LARK_DOCX2MD_APP_ID;
+	opts.appSecret = opts.appSecret ?? process.env.LARK_DOCX2MD_APP_SECRET;
+	if (opts.agent === void 0) {
+		const envAgent = process.env.LARK_DOCX2MD_AGENT;
+		if (envAgent === "true") opts.agent = true;
+		else if (envAgent === "local") opts.agent = "local";
+		else opts.agent = false;
+	} else if (typeof opts.agent === "string" && opts.agent !== "local") program.error(`Invalid --agent value "${opts.agent}", only "local" is supported (or omit the value)`);
+	if (opts.agent === true || opts.agent === "local") setLogLevel(LoggerLevel.error);
+	const maxLevel = parseInt(opts.maxLevel ?? "9", 10);
+	if (!Number.isInteger(maxLevel) || maxLevel < 1 || maxLevel > 9) program.error(`Invalid --max-level "${opts.maxLevel}", must be an integer in [1, 9]`);
+	const format = opts.format ?? "yaml";
+	if (![
+		"yaml",
+		"yaml-tree",
+		"json",
+		"tree",
+		"text"
+	].includes(format)) program.error(`Invalid --format "${format}", must be "yaml" | "yaml-tree" | "json" | "tree" | "text"`);
+	const appId = opts.appId;
+	const appSecret = opts.appSecret;
+	if (!appId || !appSecret) program.error("Missing credentials: pass --app-id/--app-secret or set LARK_DOCX2MD_APP_ID/LARK_DOCX2MD_APP_SECRET");
+	const result = await getTitles({
+		appId,
+		appSecret,
+		url,
+		agent: opts.agent === "local" ? "local" : opts.agent === true
+	});
+	const filtered = result.titles.filter((t) => t.level <= maxLevel);
+	if (format === "yaml") process.stdout.write(serializeYaml({
+		url: result.url,
+		docToken: result.docToken,
+		titles: filtered
+	}));
+	else if (format === "yaml-tree") {
+		const tree = buildTitleTree(filtered);
+		process.stdout.write(serializeYaml({
+			url: result.url,
+			docToken: result.docToken,
+			titles: tree
+		}));
+	} else if (format === "json") process.stdout.write(JSON.stringify({
+		url: result.url,
+		docToken: result.docToken,
+		titles: filtered
+	}, null, 2) + "\n");
+	else if (format === "tree") {
+		const tree = buildTitleTree(filtered);
+		process.stdout.write(JSON.stringify({
+			url: result.url,
+			docToken: result.docToken,
+			titles: tree
+		}, null, 2) + "\n");
+	} else process.stdout.write(formatTitlesAsText(filtered) + "\n");
+});
 program.parse();
 //#endregion
 export {};

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Command } from 'commander';\nimport { LoggerLevel } from '@larksuiteoapi/node-sdk';\nimport { convert } from './converter.js';\nimport { setLogLevel } from './logger.js';\nimport type { SvgBackground, WbFormat, WbImageMode } from './types.js';\n\nconst program = new Command();\nprogram.name('larkDocx2md').description('Download Lark/Feishu documents to markdown');\n\nprogram\n  .command('download')\n  .alias('dl')\n  .description('Download a wiki document to markdown')\n  .option('--app-id <id>', 'Feishu app ID (or read from LARK_DOCX2MD_APP_ID)')\n  .option('--app-secret <secret>', 'Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)')\n  .option('-o, --output <dir>', 'Output directory (or LARK_DOCX2MD_OUTPUT)')\n  .option('--agent [mode]', 'Enable agent mode: ERROR log level, and AI-oriented stdout. Pass \"local\" to save markdown/images/whiteboards to disk and print a read-file prompt (or LARK_DOCX2MD_AGENT=true|local)')\n  .option('--wb-format <format>', 'Whiteboard output format: \"base64\", \"inline-svg\", \"svg\", or \"yaml\" (or LARK_DOCX2MD_WB_FORMAT)')\n  .option('--wb-bg <style>', 'Whiteboard SVG background: \"none\", \"dot\", or a color like \"#fff\" (or LARK_DOCX2MD_WB_BG)')\n  .option('--wb-image-mode <mode>', 'Whiteboard image mode: \"online\", \"base64\", or \"local\" (or LARK_DOCX2MD_WB_IMAGE_MODE)')\n  .option('--image-mode <mode>', 'Image handling mode: \"local\" or \"online\" (or LARK_DOCX2MD_IMAGE_MODE)')\n  .option('--filter-title <title>', 'Only convert the section matching this heading title')\n  .argument('<url>', 'Feishu wiki document URL: https://*.feishu.cn/wiki/*')\n  .action(async (url: string, opts: { appId?: string; appSecret?: string; output?: string; agent?: boolean | string; imageMode?: string; wbImageMode?: string; wbBg?: SvgBackground; wbFormat?: string; filterTitle?: string }) => {\n    // ─── 环境变量默认值（直接指定 > 环境变量 > 内置默认值）────────────────\n    opts.appId = opts.appId ?? process.env.LARK_DOCX2MD_APP_ID;\n    opts.appSecret = opts.appSecret ?? process.env.LARK_DOCX2MD_APP_SECRET;\n    opts.output = opts.output ?? process.env.LARK_DOCX2MD_OUTPUT ?? './larkDocx2mdOutput';\n    // 解析 --agent：可能为 undefined | true | 'local' | 其他字符串\n    if (opts.agent === undefined) {\n      const envAgent = process.env.LARK_DOCX2MD_AGENT;\n      if (envAgent === 'true') opts.agent = true;\n      else if (envAgent === 'local') opts.agent = 'local';\n      else opts.agent = false;\n    } else if (typeof opts.agent === 'string' && opts.agent !== 'local') {\n      program.error(`Invalid --agent value \"${opts.agent}\", only \"local\" is supported (or omit the value)`);\n    }\n    const agentEnabled = opts.agent === true || opts.agent === 'local';\n    const agentLocal = opts.agent === 'local';\n\n    opts.imageMode = opts.imageMode ?? process.env.LARK_DOCX2MD_IMAGE_MODE ?? 'local';\n    opts.wbFormat = opts.wbFormat ?? process.env.LARK_DOCX2MD_WB_FORMAT;\n    opts.wbBg = opts.wbBg ?? process.env.LARK_DOCX2MD_WB_BG ?? 'none';\n    opts.wbImageMode = opts.wbImageMode ?? process.env.LARK_DOCX2MD_WB_IMAGE_MODE ?? 'local';\n\n    // 设置 wb-format 默认值：--agent local 默认 inline-svg（兼容本地画板图片），--agent（在线）默认 yaml，其余 svg\n    if (!opts.wbFormat) {\n      opts.wbFormat = agentEnabled ? 'yaml' : 'svg';\n    }\n\n    if (agentEnabled) {\n      setLogLevel(LoggerLevel.error);\n      if (agentLocal) {\n        // --agent local：图片/画板图片均落盘\n        opts.imageMode = 'local';\n        opts.wbImageMode = 'local';\n      } else {\n        // --agent（在线）：一律在线，且画板仅支持内嵌形式\n        opts.imageMode = 'online';\n        opts.wbImageMode = 'online';\n      }\n      if (!['inline-svg', 'yaml'].includes(opts.wbFormat)) {\n        program.error(`Agent mode only supports \"inline-svg\" or \"yaml\" for --wb-format`);\n      }\n    } else {\n      // yaml 格式图片仅支持 online\n      if (opts.wbFormat === 'yaml') {\n        opts.wbImageMode = 'online';\n      }\n    }\n\n    if (opts.imageMode && !['local', 'online'].includes(opts.imageMode)) {\n      program.error(`Invalid --image-mode \"${opts.imageMode}\", must be \"local\" or \"online\"`);\n    }\n    if (!['base64', 'inline-svg', 'svg', 'yaml'].includes(opts.wbFormat)) {\n      program.error(`Invalid --wb-format \"${opts.wbFormat}\", must be \"base64\", \"inline-svg\", \"svg\", or \"yaml\"`);\n    }\n    if (!['online', 'base64', 'local'].includes(opts.wbImageMode)) {\n      program.error(`Invalid --wb-image-mode \"${opts.wbImageMode}\", must be \"online\", \"base64\", or \"local\"`);\n    }\n\n    const appId = opts.appId!;\n    const appSecret = opts.appSecret!;\n    if (!appId || !appSecret) {\n      program.error('Missing credentials: pass --app-id/--app-secret or set LARK_DOCX2MD_APP_ID/LARK_DOCX2MD_APP_SECRET');\n    }\n\n    const result = await convert({\n      appId,\n      appSecret,\n      url,\n      output: opts.output,\n      imageMode: opts.imageMode as 'local' | 'online',\n      wbImageMode: opts.wbImageMode as WbImageMode,\n      wbBg: opts.wbBg,\n      wbFormat: opts.wbFormat as WbFormat,\n      agent: agentLocal ? 'local' : (opts.agent === true),\n      filterTitle: opts.filterTitle?.trim(),\n    });\n\n    if (agentLocal) {\n      // 本地模式：输出引导 AI 读取文件的提示词（绝对路径）\n      process.stdout.write(\n        `**The Feishu document has been downloaded to the following absolute path:**\\n\\n` +\n        `\\`${result.filePath}\\`\\n\\n` +\n        `**Read this file to access the full markdown content.**\\n`,\n      );\n    } else if (opts.agent === true) {\n      process.stdout.write(result.markdown);\n    }\n  });\n\nprogram.parse();\n"],"mappings":";;;;;AAOA,MAAM,UAAU,IAAI,SAAS;AAC7B,QAAQ,KAAK,cAAc,CAAC,YAAY,6CAA6C;AAErF,QACG,QAAQ,WAAW,CACnB,MAAM,KAAK,CACX,YAAY,uCAAuC,CACnD,OAAO,iBAAiB,mDAAmD,CAC3E,OAAO,yBAAyB,2DAA2D,CAC3F,OAAO,sBAAsB,4CAA4C,CACzE,OAAO,kBAAkB,yLAAuL,CAChN,OAAO,wBAAwB,yGAAiG,CAChI,OAAO,mBAAmB,iGAA2F,CACrH,OAAO,0BAA0B,8FAAwF,CACzH,OAAO,uBAAuB,4EAAwE,CACtG,OAAO,0BAA0B,uDAAuD,CACxF,SAAS,SAAS,uDAAuD,CACzE,OAAO,OAAO,KAAa,SAAqM;AAE/N,MAAK,QAAQ,KAAK,SAAS,QAAQ,IAAI;AACvC,MAAK,YAAY,KAAK,aAAa,QAAQ,IAAI;AAC/C,MAAK,SAAS,KAAK,UAAU,QAAQ,IAAI,uBAAuB;AAEhE,KAAI,KAAK,UAAU,KAAA,GAAW;EAC5B,MAAM,WAAW,QAAQ,IAAI;AAC7B,MAAI,aAAa,OAAQ,MAAK,QAAQ;WAC7B,aAAa,QAAS,MAAK,QAAQ;MACvC,MAAK,QAAQ;YACT,OAAO,KAAK,UAAU,YAAY,KAAK,UAAU,QAC1D,SAAQ,MAAM,0BAA0B,KAAK,MAAM,kDAAkD;CAEvG,MAAM,eAAe,KAAK,UAAU,QAAQ,KAAK,UAAU;CAC3D,MAAM,aAAa,KAAK,UAAU;AAElC,MAAK,YAAY,KAAK,aAAa,QAAQ,IAAI,2BAA2B;AAC1E,MAAK,WAAW,KAAK,YAAY,QAAQ,IAAI;AAC7C,MAAK,OAAO,KAAK,QAAQ,QAAQ,IAAI,sBAAsB;AAC3D,MAAK,cAAc,KAAK,eAAe,QAAQ,IAAI,8BAA8B;AAGjF,KAAI,CAAC,KAAK,SACR,MAAK,WAAW,eAAe,SAAS;AAG1C,KAAI,cAAc;AAChB,cAAY,YAAY,MAAM;AAC9B,MAAI,YAAY;AAEd,QAAK,YAAY;AACjB,QAAK,cAAc;SACd;AAEL,QAAK,YAAY;AACjB,QAAK,cAAc;;AAErB,MAAI,CAAC,CAAC,cAAc,OAAO,CAAC,SAAS,KAAK,SAAS,CACjD,SAAQ,MAAM,kEAAkE;YAI9E,KAAK,aAAa,OACpB,MAAK,cAAc;AAIvB,KAAI,KAAK,aAAa,CAAC,CAAC,SAAS,SAAS,CAAC,SAAS,KAAK,UAAU,CACjE,SAAQ,MAAM,yBAAyB,KAAK,UAAU,gCAAgC;AAExF,KAAI,CAAC;EAAC;EAAU;EAAc;EAAO;EAAO,CAAC,SAAS,KAAK,SAAS,CAClE,SAAQ,MAAM,wBAAwB,KAAK,SAAS,qDAAqD;AAE3G,KAAI,CAAC;EAAC;EAAU;EAAU;EAAQ,CAAC,SAAS,KAAK,YAAY,CAC3D,SAAQ,MAAM,4BAA4B,KAAK,YAAY,2CAA2C;CAGxG,MAAM,QAAQ,KAAK;CACnB,MAAM,YAAY,KAAK;AACvB,KAAI,CAAC,SAAS,CAAC,UACb,SAAQ,MAAM,qGAAqG;CAGrH,MAAM,SAAS,MAAM,QAAQ;EAC3B;EACA;EACA;EACA,QAAQ,KAAK;EACb,WAAW,KAAK;EAChB,aAAa,KAAK;EAClB,MAAM,KAAK;EACX,UAAU,KAAK;EACf,OAAO,aAAa,UAAW,KAAK,UAAU;EAC9C,aAAa,KAAK,aAAa,MAAM;EACtC,CAAC;AAEF,KAAI,WAEF,SAAQ,OAAO,MACb,oFACK,OAAO,SAAS,iEAEtB;UACQ,KAAK,UAAU,KACxB,SAAQ,OAAO,MAAM,OAAO,SAAS;EAEvC;AAEJ,QAAQ,OAAO"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Command } from 'commander';\nimport { LoggerLevel } from '@larksuiteoapi/node-sdk';\nimport { buildTitleTree, convert, formatTitlesAsText, getTitles } from './converter.js';\nimport { setLogLevel } from './logger.js';\nimport { serializeYaml } from './whiteboard/yaml/serialize.js';\nimport type { SvgBackground, WbFormat, WbImageMode } from './types.js';\n\nconst program = new Command();\nprogram.name('larkDocx2md').description('Download Lark/Feishu documents to markdown');\n\nprogram\n  .command('download')\n  .alias('dl')\n  .description('Download a wiki document to markdown')\n  .option('--app-id <id>', 'Feishu app ID (or read from LARK_DOCX2MD_APP_ID)')\n  .option('--app-secret <secret>', 'Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)')\n  .option('-o, --output <dir>', 'Output directory (or LARK_DOCX2MD_OUTPUT)')\n  .option('--agent [mode]', 'Enable agent mode: ERROR log level, and AI-oriented stdout. Pass \"local\" to save markdown/images/whiteboards to disk and print a read-file prompt (or LARK_DOCX2MD_AGENT=true|local)')\n  .option('--wb-format <format>', 'Whiteboard output format: \"base64\", \"inline-svg\", \"svg\", or \"yaml\" (or LARK_DOCX2MD_WB_FORMAT)')\n  .option('--wb-bg <style>', 'Whiteboard SVG background: \"none\", \"dot\", or a color like \"#fff\" (or LARK_DOCX2MD_WB_BG)')\n  .option('--wb-image-mode <mode>', 'Whiteboard image mode: \"online\", \"base64\", or \"local\" (or LARK_DOCX2MD_WB_IMAGE_MODE)')\n  .option('--image-mode <mode>', 'Image handling mode: \"local\" or \"online\" (or LARK_DOCX2MD_IMAGE_MODE)')\n  .option('--filter-title <title>', 'Only convert the section matching this heading title (single title, first match wins on duplicates)')\n  .option('--filter-title-block-id <id>', 'Only convert the section whose heading block id matches (most precise; obtain from get-titles)')\n  .argument('<url>', 'Feishu wiki document URL: https://*.feishu.cn/wiki/*')\n  .action(async (url: string, opts: { appId?: string; appSecret?: string; output?: string; agent?: boolean | string; imageMode?: string; wbImageMode?: string; wbBg?: SvgBackground; wbFormat?: string; filterTitle?: string; filterTitleBlockId?: string }) => {\n    // ─── 环境变量默认值（直接指定 > 环境变量 > 内置默认值）────────────────\n    opts.appId = opts.appId ?? process.env.LARK_DOCX2MD_APP_ID;\n    opts.appSecret = opts.appSecret ?? process.env.LARK_DOCX2MD_APP_SECRET;\n    opts.output = opts.output ?? process.env.LARK_DOCX2MD_OUTPUT ?? './larkDocx2mdOutput';\n    // 解析 --agent：可能为 undefined | true | 'local' | 其他字符串\n    if (opts.agent === undefined) {\n      const envAgent = process.env.LARK_DOCX2MD_AGENT;\n      if (envAgent === 'true') opts.agent = true;\n      else if (envAgent === 'local') opts.agent = 'local';\n      else opts.agent = false;\n    } else if (typeof opts.agent === 'string' && opts.agent !== 'local') {\n      program.error(`Invalid --agent value \"${opts.agent}\", only \"local\" is supported (or omit the value)`);\n    }\n    const agentEnabled = opts.agent === true || opts.agent === 'local';\n    const agentLocal = opts.agent === 'local';\n\n    opts.imageMode = opts.imageMode ?? process.env.LARK_DOCX2MD_IMAGE_MODE ?? 'local';\n    opts.wbFormat = opts.wbFormat ?? process.env.LARK_DOCX2MD_WB_FORMAT;\n    opts.wbBg = opts.wbBg ?? process.env.LARK_DOCX2MD_WB_BG ?? 'none';\n    opts.wbImageMode = opts.wbImageMode ?? process.env.LARK_DOCX2MD_WB_IMAGE_MODE ?? 'local';\n\n    // 设置 wb-format 默认值：--agent local 默认 inline-svg（兼容本地画板图片），--agent（在线）默认 yaml，其余 svg\n    if (!opts.wbFormat) {\n      opts.wbFormat = agentEnabled ? 'yaml' : 'svg';\n    }\n\n    if (agentEnabled) {\n      setLogLevel(LoggerLevel.error);\n      if (agentLocal) {\n        // --agent local：图片/画板图片均落盘\n        opts.imageMode = 'local';\n        opts.wbImageMode = 'local';\n      } else {\n        // --agent（在线）：一律在线，且画板仅支持内嵌形式\n        opts.imageMode = 'online';\n        opts.wbImageMode = 'online';\n      }\n      if (!['inline-svg', 'yaml'].includes(opts.wbFormat)) {\n        program.error(`Agent mode only supports \"inline-svg\" or \"yaml\" for --wb-format`);\n      }\n    } else {\n      // yaml 格式图片仅支持 online\n      if (opts.wbFormat === 'yaml') {\n        opts.wbImageMode = 'online';\n      }\n    }\n\n    if (opts.imageMode && !['local', 'online'].includes(opts.imageMode)) {\n      program.error(`Invalid --image-mode \"${opts.imageMode}\", must be \"local\" or \"online\"`);\n    }\n    if (!['base64', 'inline-svg', 'svg', 'yaml'].includes(opts.wbFormat)) {\n      program.error(`Invalid --wb-format \"${opts.wbFormat}\", must be \"base64\", \"inline-svg\", \"svg\", or \"yaml\"`);\n    }\n    if (!['online', 'base64', 'local'].includes(opts.wbImageMode)) {\n      program.error(`Invalid --wb-image-mode \"${opts.wbImageMode}\", must be \"online\", \"base64\", or \"local\"`);\n    }\n    if (opts.filterTitle && opts.filterTitleBlockId) {\n      program.error('--filter-title and --filter-title-block-id are mutually exclusive; choose one');\n    }\n\n    const appId = opts.appId!;\n    const appSecret = opts.appSecret!;\n    if (!appId || !appSecret) {\n      program.error('Missing credentials: pass --app-id/--app-secret or set LARK_DOCX2MD_APP_ID/LARK_DOCX2MD_APP_SECRET');\n    }\n\n    const result = await convert({\n      appId,\n      appSecret,\n      url,\n      output: opts.output,\n      imageMode: opts.imageMode as 'local' | 'online',\n      wbImageMode: opts.wbImageMode as WbImageMode,\n      wbBg: opts.wbBg,\n      wbFormat: opts.wbFormat as WbFormat,\n      agent: agentLocal ? 'local' : (opts.agent === true),\n      filterTitle: opts.filterTitle?.trim(),\n      filterTitleBlockId: opts.filterTitleBlockId?.trim(),\n    });\n\n    if (agentLocal) {\n      // 本地模式：输出引导 AI 读取文件的提示词（绝对路径）\n      process.stdout.write(\n        `**The Feishu document has been downloaded to the following absolute path:**\\n\\n` +\n        `\\`${result.filePath}\\`\\n\\n` +\n        `**Read this file to access the full markdown content.**\\n`,\n      );\n    } else if (opts.agent === true) {\n      process.stdout.write(result.markdown);\n    }\n  });\n\nprogram\n  .command('get-titles')\n  .description('Print all headings (level 1~9) of a wiki/docx document. Useful before --filter-title-block-id.')\n  .option('--app-id <id>', 'Feishu app ID (or read from LARK_DOCX2MD_APP_ID)')\n  .option('--app-secret <secret>', 'Feishu app secret (or read from LARK_DOCX2MD_APP_SECRET)')\n  .option('--max-level <n>', 'Only output headings whose level <= n (1~9)', '9')\n  .option('--format <format>', 'Output format: \"yaml\" (flat, default) | \"yaml-tree\" (nested) | \"json\" (flat) | \"tree\" (json nested) | \"text\" (indented markdown headings)', 'yaml')\n  .option('--agent [mode]', 'Enable agent mode: ERROR log level, AI-oriented stdout (or LARK_DOCX2MD_AGENT=true|local)')\n  .argument('<url>', 'Feishu wiki/docx URL: https://*.feishu.cn/{wiki,docx,docs}/*')\n  .action(async (url: string, opts: { appId?: string; appSecret?: string; maxLevel?: string; format?: string; agent?: boolean | string }) => {\n    opts.appId = opts.appId ?? process.env.LARK_DOCX2MD_APP_ID;\n    opts.appSecret = opts.appSecret ?? process.env.LARK_DOCX2MD_APP_SECRET;\n    if (opts.agent === undefined) {\n      const envAgent = process.env.LARK_DOCX2MD_AGENT;\n      if (envAgent === 'true') opts.agent = true;\n      else if (envAgent === 'local') opts.agent = 'local';\n      else opts.agent = false;\n    } else if (typeof opts.agent === 'string' && opts.agent !== 'local') {\n      program.error(`Invalid --agent value \"${opts.agent}\", only \"local\" is supported (or omit the value)`);\n    }\n    const agentEnabled = opts.agent === true || opts.agent === 'local';\n    if (agentEnabled) setLogLevel(LoggerLevel.error);\n\n    const maxLevel = parseInt(opts.maxLevel ?? '9', 10);\n    if (!Number.isInteger(maxLevel) || maxLevel < 1 || maxLevel > 9) {\n      program.error(`Invalid --max-level \"${opts.maxLevel}\", must be an integer in [1, 9]`);\n    }\n    const format = opts.format ?? 'yaml';\n    if (!['yaml', 'yaml-tree', 'json', 'tree', 'text'].includes(format)) {\n      program.error(`Invalid --format \"${format}\", must be \"yaml\" | \"yaml-tree\" | \"json\" | \"tree\" | \"text\"`);\n    }\n\n    const appId = opts.appId!;\n    const appSecret = opts.appSecret!;\n    if (!appId || !appSecret) {\n      program.error('Missing credentials: pass --app-id/--app-secret or set LARK_DOCX2MD_APP_ID/LARK_DOCX2MD_APP_SECRET');\n    }\n\n    const result = await getTitles({\n      appId,\n      appSecret,\n      url,\n      agent: opts.agent === 'local' ? 'local' : (opts.agent === true),\n    });\n    const filtered = result.titles.filter(t => t.level <= maxLevel);\n\n    if (format === 'yaml') {\n      process.stdout.write(serializeYaml({ url: result.url, docToken: result.docToken, titles: filtered }));\n    } else if (format === 'yaml-tree') {\n      const tree = buildTitleTree(filtered);\n      process.stdout.write(serializeYaml({ url: result.url, docToken: result.docToken, titles: tree }));\n    } else if (format === 'json') {\n      process.stdout.write(JSON.stringify({ url: result.url, docToken: result.docToken, titles: filtered }, null, 2) + '\\n');\n    } else if (format === 'tree') {\n      const tree = buildTitleTree(filtered);\n      process.stdout.write(JSON.stringify({ url: result.url, docToken: result.docToken, titles: tree }, null, 2) + '\\n');\n    } else {\n      process.stdout.write(formatTitlesAsText(filtered) + '\\n');\n    }\n  });\n\nprogram.parse();\n"],"mappings":"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"}

package/dist/{converter-nwp8DCnk.d.ts → converter-Cb2tYM7d.d.ts}

@@ -17,6 +17,7 @@ interface ConvertOptions {
   wbFormat: WbFormat;
   agent?: boolean | 'local';
   filterTitle?: string;
+  filterTitleBlockId?: string;
 }
 interface ConvertResult {
   markdown: string;
@@ -25,6 +26,15 @@ interface ConvertResult {
 }
 //# sourceMappingURL=types.d.ts.map
 //#endregion
+//#region src/title-filter.d.ts
+interface HeadingInfo {
+  blockId: string;
+  index: number;
+  level: number;
+  text: string;
+  path: string[];
+}
+//#endregion
 //#region src/converter.d.ts
 declare function parseWikiUrl(url: string): {
   docType: string;
@@ -32,8 +42,25 @@ declare function parseWikiUrl(url: string): {
   sheetId?: string;
 };
 declare function convert(opts: ConvertOptions): Promise<ConvertResult>;
+interface GetTitlesOptions {
+  appId: string;
+  appSecret: string;
+  url: string;
+  agent?: boolean | 'local';
+}
+interface GetTitlesResult {
+  url: string;
+  docToken: string;
+  titles: HeadingInfo[];
+}
+declare function getTitles(opts: GetTitlesOptions): Promise<GetTitlesResult>;
+interface TitleTreeNode extends HeadingInfo {
+  children?: TitleTreeNode[];
+}
+declare function buildTitleTree(titles: HeadingInfo[]): TitleTreeNode[];
+declare function formatTitlesAsText(titles: HeadingInfo[]): string;
 //# sourceMappingURL=converter.d.ts.map
 
 //#endregion
-export { convert, parseWikiUrl };
-//# sourceMappingURL=converter-nwp8DCnk.d.ts.map
+export { GetTitlesOptions, GetTitlesResult, TitleTreeNode, buildTitleTree, convert, formatTitlesAsText, getTitles, parseWikiUrl };
+//# sourceMappingURL=converter-Cb2tYM7d.d.ts.map

package/dist/converter-Cb2tYM7d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter-Cb2tYM7d.d.ts","names":[],"sources":["../src/types.ts","../src/title-filter.ts","../src/converter.ts"],"mappings":";;;;AAsCa,KAhBD,SAAA,GAgBC,OAAA,GAAA,QAAA;AACE,KAdH,WAAA,GAcG,QAAA,GAAA,QAAA,GAAA,OAAA;AACP,KAZI,QAAA,GAYJ,QAAA,GAAA,YAAA,GAAA,KAAA,GAAA,MAAA;AACI,KAVA,aAAA,GAUA,MAAA,GAAA,KAAA,GAAA,CAAA,MAAA,GAAA,CAAA,CAAA,CAAA;AAAQ,UARH,cAAA,CAQG;EAaH,KAAA,EAAA,MAAA;;;;EC/BA,SAAA,EDeJ,SCfe;eDgBb;QACP;YACI;EElBI,KAAA,CAAA,EAAA,OAAY,GAAA,OAAA;EAUN,WAAO,CAAA,EAAA,MAAA;EAAA,kBAAA,CAAA,EAAA,MAAA;;AAAiC,UFqB7C,aAAA,CErB6C;UAAR,EAAA,MAAA;EAAO,QAAA,EAAA,MAAA;EAsG5C,QAAA,CAAA,EAAA,MAAA;AAQjB;AAOA;;;AFhHa,UCfI,WAAA,CDeJ;SACE,EAAA,MAAA;OACP,EAAA,MAAA;OACI,EAAA,MAAA;EAAQ,IAAA,EAAA,MAAA;EAaH,IAAA,EAAA,MAAA,EAAA;;;;iBE/BD,YAAA;EFDJ,OAAA,EAAA,MAAS;EAGT,QAAA,EAAA,MAAW;EAGX,OAAA,CAAA,EAAA,MAAQ;AAGpB,CAAA;AAEiB,iBEAK,OAAA,CFAS,IAAA,EEAM,cFAN,CAAA,EEAuB,OFAvB,CEA+B,aFA/B,CAAA;AAAA,UEsGd,gBAAA,CFtGc;OAKlB,EAAA,MAAA;WACE,EAAA,MAAA;KACP,EAAA,MAAA;OACI,CAAA,EAAA,OAAA,GAAA,OAAA;;AAaK,UEyFA,eAAA,CFzFa;;;UE4FpB;AD3HV;iBC+HsB,SAAA,OAAiB,mBAAmB,QAAQ;UAwBjD,aAAA,SAAsB;aAC1B;AAxJb;AAUsB,iBAkJN,cAAA,CAlJa,MAAA,EAkJW,WAlJX,EAAA,CAAA,EAkJ2B,aAlJ3B,EAAA;AAAA,iBAoKb,kBAAA,CApKa,MAAA,EAoKe,WApKf,EAAA,CAAA,EAAA,MAAA"}

package/dist/{converter-Bqb4bqxh.js → converter-D1nCzDJF.js}

@@ -53,7 +53,7 @@ function createClient(appId, appSecret, loggerLevel = LoggerLevel.warn) {
 		const allBlocks = [];
 		let pageToken;
 		for (let i = 0;; i++) {
-			if (i > 0) await sleep$1(100);
+			if (i > 0) await sleep$1(50);
 			const data = await call("getDocxBlocks", () => client.docx.v1.documentBlock.list({
 				path: { document_id: docToken },
 				params: {
@@ -93,11 +93,8 @@ function createClient(appId, appSecret, loggerLevel = LoggerLevel.warn) {
 			await resp.writeFile(filename);
 			return filename;
 		} catch (error) {
-			if ([
-				400,
-				401,
-				403
-			].includes(error.status)) throw new Error(`下载图片[${imgToken}]异常, 检查是否有接口 https://open.feishu.cn/document/server-docs/docs/drive-v1/media/download 的权限。`);
+			if (error.status === 401) throw new Error(`下载图片[${imgToken}]异常, 检查是否有接口 https://open.feishu.cn/document/server-docs/docs/drive-v1/media/download 的权限`);
+			if (error.status === 403) throw new Error(`下载图片[${imgToken}]异常, 应用的文档权限大于等于文档本身“谁可以创建副本、打印和下载”的权限`);
 			throw error;
 		}
 	}
@@ -564,8 +561,10 @@ const tableParser = {
 			const row = Math.floor(i / cols);
 			const col = i % cols;
 			if (rows[row]?.cells[col]) {
-				rows[row].cells[col].rowSpan = m.row_span > 1 ? m.row_span : void 0;
-				rows[row].cells[col].colSpan = m.col_span > 1 ? m.col_span : void 0;
+				const rowSpan = m.row_span ?? 1;
+				const colSpan = m.col_span ?? 1;
+				rows[row].cells[col].rowSpan = rowSpan > 1 ? rowSpan : void 0;
+				rows[row].cells[col].colSpan = colSpan > 1 ? colSpan : void 0;
 			}
 		}
 		const skipSet = /* @__PURE__ */ new Set();
@@ -2885,7 +2884,7 @@ var MdTransformer = class {
 							error: `读取失败：${e.message}`
 						});
 					} finally {
-						await sleep(600);
+						await sleep(300);
 					}
 				}
 				map.set(raw, {
@@ -2997,6 +2996,33 @@ function extractHeadingText(block) {
 	return body.elements.map((e) => e.text_run?.content ?? "").join("").trim();
 }
 /**
+* 内部工具：维护标题祖先栈与 1-based 序号，将一个 heading block 转为 HeadingInfo。
+* 传入非 heading block 返回 null，不改变内部状态。
+*/
+function createHeadingTracker() {
+	const stack = [];
+	let counter = 0;
+	function push(block) {
+		const level = getHeadingLevel(block);
+		if (level === null) return null;
+		const text = extractHeadingText(block) ?? "";
+		while (stack.length > 0 && stack[stack.length - 1].level >= level) stack.pop();
+		stack.push({
+			level,
+			text
+		});
+		counter += 1;
+		return {
+			blockId: block.block_id ?? "",
+			index: counter,
+			level,
+			text,
+			path: stack.map((s) => s.text)
+		};
+	}
+	return { push };
+}
+/**
 * 创建标题过滤器，返回一个 pageHandler 兼容的回调和结果获取器。
 * 纯函数工厂，无副作用，易于测试。
 */
@@ -3006,6 +3032,7 @@ function createTitleFilter(options) {
 	let matchedLevel = 0;
 	const collected = [];
 	const seenHeadings = [];
+	const tracker = createHeadingTracker();
 	function pageHandler(blocks) {
 		for (const block of blocks) {
 			if (block.block_type === 1) {
@@ -3014,16 +3041,12 @@ function createTitleFilter(options) {
 			}
 			switch (state) {
 				case "scanning": {
-					const level = getHeadingLevel(block);
-					if (level !== null) {
-						const text = extractHeadingText(block) ?? "";
-						seenHeadings.push({
-							level,
-							text
-						});
-						if (text === targetTitle) {
+					const info = tracker.push(block);
+					if (info) {
+						seenHeadings.push(info);
+						if (info.text === targetTitle) {
 							state = "collecting";
-							matchedLevel = level;
+							matchedLevel = info.level;
 							collected.push(block);
 						}
 					}
@@ -3055,6 +3078,81 @@ function createTitleFilter(options) {
 		getResult
 	};
 }
+/**
+* 按 heading 块 id 过滤（最精确，不会受同名标题干扰）。
+* 仅匹配 block_type 为 heading（1~9）且 block_id 严格相等的块。
+*/
+function createTitleBlockIdFilter(options) {
+	const target = options.blockId.trim();
+	let state = "scanning";
+	let matchedLevel = 0;
+	const collected = [];
+	const seen = [];
+	const tracker = createHeadingTracker();
+	function pageHandler(blocks) {
+		for (const block of blocks) {
+			if (block.block_type === 1) {
+				collected.push(block);
+				continue;
+			}
+			switch (state) {
+				case "scanning": {
+					const info = tracker.push(block);
+					if (info) {
+						seen.push(info);
+						if (block.block_id === target) {
+							state = "collecting";
+							matchedLevel = info.level;
+							collected.push(block);
+						}
+					}
+					break;
+				}
+				case "collecting": {
+					const level = getHeadingLevel(block);
+					if (level !== null && level <= matchedLevel) {
+						state = "done";
+						return false;
+					}
+					collected.push(block);
+					break;
+				}
+				case "done": return false;
+			}
+		}
+		return state !== "done";
+	}
+	function getResult() {
+		return {
+			blocks: [...collected],
+			matched: state === "collecting" || state === "done",
+			availableHeadings: [...seen]
+		};
+	}
+	return {
+		pageHandler,
+		getResult
+	};
+}
+/**
+* 流式收集文档中所有标题，用于 get-titles 命令。
+* 返回的 pageHandler 始终返回 true，以遵循分页拉取全量文档。
+*/
+function createHeadingCollector() {
+	const headings = [];
+	const tracker = createHeadingTracker();
+	function pageHandler(blocks) {
+		for (const block of blocks) {
+			const info = tracker.push(block);
+			if (info) headings.push(info);
+		}
+		return true;
+	}
+	return {
+		pageHandler,
+		getHeadings: () => [...headings]
+	};
+}
 //#endregion
 //#region src/converter.ts
 const logger = createLogger("converter");
@@ -3099,18 +3197,11 @@ async function convert(opts) {
 	} else {
 		const doc = await client.getDocxDocument(docToken);
 		let blocks;
-		if (opts.filterTitle) {
-			const filter = createTitleFilter({ title: opts.filterTitle });
+		const filter = createDocxFilter(opts);
+		if (filter) {
 			await client.getDocxBlocks(docToken, filter.pageHandler);
 			const result = filter.getResult();
-			if (!result.matched) {
-				let msg = `No heading matched "${opts.filterTitle}". Please verify the heading text.`;
-				if (result.availableHeadings.length > 0) {
-					const list = result.availableHeadings.map((h) => `${"#".repeat(h.level)} ${h.text}`).join("\n");
-					msg += `\n\nAvailable headings in the document:\n\n${list}`;
-				}
-				throw new Error(msg);
-			}
+			if (!result.matched) throw new Error(buildFilterErrorMessage(opts, result, opts.url, docToken));
 			blocks = result.blocks;
 		} else blocks = await client.getDocxBlocks(docToken);
 		logger.info(`Fetched ${blocks.length} blocks`);
@@ -3135,7 +3226,70 @@ async function convert(opts) {
 		filePath
 	};
 }
+/** 优先级：filterTitleBlockId > filterTitle。返回 null 表示不过滤。 */
+function createDocxFilter(opts) {
+	if (opts.filterTitleBlockId) return createTitleBlockIdFilter({ blockId: opts.filterTitleBlockId });
+	if (opts.filterTitle) return createTitleFilter({ title: opts.filterTitle });
+	return null;
+}
+function buildFilterErrorMessage(opts, result, url, docToken) {
+	let target;
+	if (opts.filterTitleBlockId) target = `block id "${opts.filterTitleBlockId}"`;
+	else target = `"${opts.filterTitle}"`;
+	let msg = `No heading matched ${target}. Please verify the heading text/id.`;
+	if (result.availableHeadings.length > 0) {
+		const yaml = serializeYaml({
+			url,
+			docToken,
+			titles: result.availableHeadings
+		});
+		msg += `\n\nFull title list of the document (yaml, same shape as \`get-titles\`):\n\n${yaml}`;
+	}
+	return msg;
+}
+/** 拉取 docx/wiki 文档中所有标题信息（扁平列表，不下载图片）。 */
+async function getTitles(opts) {
+	const { docType, docToken: rawToken } = parseWikiUrl(opts.url);
+	if (docType === "sheets") throw new Error("get-titles only supports docx/wiki documents, not spreadsheets");
+	const sdkLoggerLevel = opts.agent ? LoggerLevel.error : LoggerLevel.warn;
+	const client = createClient(opts.appId, opts.appSecret, sdkLoggerLevel);
+	let docToken = rawToken;
+	if (docType === "wiki") {
+		const node = await client.getWikiNodeInfo(docToken);
+		docToken = node.obj_token;
+		logger.info("Resolved wiki node:", node.obj_type, docToken);
+	}
+	const collector = createHeadingCollector();
+	await client.getDocxBlocks(docToken, collector.pageHandler);
+	const titles = collector.getHeadings();
+	logger.info(`Collected ${titles.length} headings`);
+	return {
+		url: opts.url,
+		docToken,
+		titles
+	};
+}
+/** 按 level 栈式回溯将扁平标题列表转为树（容忍跳级标题）。 */
+function buildTitleTree(titles) {
+	const roots = [];
+	const stack = [];
+	for (const t of titles) {
+		const node = { ...t };
+		while (stack.length > 0 && stack[stack.length - 1].level >= node.level) stack.pop();
+		if (stack.length === 0) roots.push(node);
+		else {
+			const parent = stack[stack.length - 1];
+			(parent.children ??= []).push(node);
+		}
+		stack.push(node);
+	}
+	return roots;
+}
+/** 按级别以 markdown heading 风格输出人读文本（包含缩进）。 */
+function formatTitlesAsText(titles) {
+	return titles.map((t) => `${"  ".repeat(Math.max(0, t.level - 1))}${"#".repeat(t.level)} ${t.text}`).join("\n");
+}
 //#endregion
-export { parseWikiUrl as n, setLogLevel as r, convert as t };
+export { parseWikiUrl as a, getTitles as i, convert as n, setLogLevel as o, formatTitlesAsText as r, serializeYaml as s, buildTitleTree as t };
 
-//# sourceMappingURL=converter-Bqb4bqxh.js.map
+//# sourceMappingURL=converter-D1nCzDJF.js.map