lark-docx2md 0.5.2 → 0.5.3-beta.1

package/README.md

@@ -42,9 +42,10 @@ npx -y lark-docx2md@latest download <url>
 | `--app-id <id>`          | 飞书应用 App ID                               | `LARK_DOCX2MD_APP_ID`        | —                     |
 | `--app-secret <secret>`  | 飞书应用 App Secret                           | `LARK_DOCX2MD_APP_SECRET`    | —                     |
 | `-o, --output <dir>`     | 输出目录                                      | `LARK_DOCX2MD_OUTPUT`        | `./larkDocx2mdOutput` |
-| `--agent [mode]`         | Agent 模式：日志 ERROR。不传值（或 `=true`）为在线模式，Markdown 输出到 stdout；传 `local` 则落盘后输出引导 AI 读取的提示词 | `LARK_DOCX2MD_AGENT=true\|local`    | `false`               |
+| `--agent [mode]`         | Agent 模式：日志 ERROR。不传值（或 `=stdout`）为在线模式，Markdown 输出到 stdout；传 `local` 则落盘后输出引导 AI 读取的提示词 | `LARK_DOCX2MD_AGENT=stdout\|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` / `level` / `text`，可被 AI 直接消费用于选择目标章节（嵌套关系由 `yaml-tree` / `tree` 格式天然表达）。
 
 ## 功能
 

package/dist/cli.js

@@ -1,27 +1,56 @@
 #!/usr/bin/env node
-import { r as setLogLevel, t as convert } from "./converter-vuRwWoA4.js";
+import { a as setLogLevel, n as buildTitleTree, o as serializeYaml, r as getTitles, t as convert } from "./converter-DLMAssSI.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
 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) => {
+/**
+* 把 commander 解析出的 --agent 原值（undefined | true | string）与
+* LARK_DOCX2MD_AGENT 环境变量统一收敛为精确的 AgentMode | false。
+*
+* 优先级：显式 --agent > 环境变量 > 默认 false。
+* 非法取值返回错误信息字符串，由调用方决定如何上报。
+*/
+function resolveAgentMode(raw) {
+	if (raw === void 0) {
+		const env = process.env.LARK_DOCX2MD_AGENT;
+		if (env === "stdout" || env === "local") return { value: env };
+		if (env !== void 0 && env !== "") return {
+			value: false,
+			error: `Invalid LARK_DOCX2MD_AGENT="${env}", must be "stdout" or "local"`
+		};
+		return { value: false };
+	}
+	if (raw === true) return { value: "stdout" };
+	if (raw === "stdout" || raw === "local") return { value: raw };
+	return {
+		value: false,
+		error: `Invalid --agent value "${raw}", must be "stdout" or "local"`
+	};
+}
+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. Modes: \"stdout\" (default, print markdown to stdout) or \"local\" (save markdown/images/whiteboards to disk and print a read-file prompt). Or LARK_DOCX2MD_AGENT=stdout|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";
-	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)`);
-	const agentEnabled = opts.agent === true || opts.agent === "local";
+	const agentResolved = resolveAgentMode(opts.agent);
+	if (agentResolved.error) {
+		program.error(agentResolved.error);
+		return;
+	}
+	opts.agent = agentResolved.value;
+	const agentEnabled = opts.agent === "stdout" || opts.agent === "local";
 	const agentLocal = opts.agent === "local";
+	const agentStdout = opts.agent === "stdout";
 	opts.imageMode = opts.imageMode ?? process.env.LARK_DOCX2MD_IMAGE_MODE ?? "local";
 	opts.wbFormat = opts.wbFormat ?? process.env.LARK_DOCX2MD_WB_FORMAT;
 	opts.wbBg = opts.wbBg ?? process.env.LARK_DOCX2MD_WB_BG ?? "none";
 	opts.wbImageMode = opts.wbImageMode ?? process.env.LARK_DOCX2MD_WB_IMAGE_MODE ?? "local";
-	if (!opts.wbFormat) opts.wbFormat = agentEnabled ? "yaml" : "svg";
+	if (!opts.wbFormat) if (agentLocal) opts.wbFormat = "inline-svg";
+	else if (agentStdout) opts.wbFormat = "yaml";
+	else opts.wbFormat = "svg";
 	if (agentEnabled) {
 		setLogLevel(LoggerLevel.error);
 		if (agentLocal) {
@@ -45,6 +74,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");
@@ -57,11 +87,49 @@ program.command("download").alias("dl").description("Download a wiki document to
 		wbImageMode: opts.wbImageMode,
 		wbBg: opts.wbBg,
 		wbFormat: opts.wbFormat,
-		agent: agentLocal ? "local" : opts.agent === true,
-		filterTitle: opts.filterTitle?.trim()
+		agent: opts.agent,
+		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);
+	else if (agentStdout) process.stdout.write(result.markdown);
+});
+program.command("get-titles").description("Print all headings (level 1~9) of a wiki/docx document as a nested yaml tree. 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("-o, --output <dir>", "Output directory used by --agent local (or LARK_DOCX2MD_OUTPUT)").option("--max-level <n>", "Only output headings whose level <= n (1~9)", "9").option("--agent [mode]", "Enable agent mode: ERROR log level, AI-oriented stdout. Modes: \"stdout\" (default, print titles to stdout) or \"local\" (save titles to disk and print a read-file prompt). Or LARK_DOCX2MD_AGENT=stdout|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;
+	opts.output = opts.output ?? process.env.LARK_DOCX2MD_OUTPUT ?? "./larkDocx2mdOutput";
+	const agentResolved = resolveAgentMode(opts.agent);
+	if (agentResolved.error) {
+		program.error(agentResolved.error);
+		return;
+	}
+	opts.agent = agentResolved.value;
+	const agentEnabled = opts.agent === "stdout" || opts.agent === "local";
+	const agentLocal = opts.agent === "local";
+	if (agentEnabled) 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 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
+	});
+	const tree = buildTitleTree(result.titles.filter((t) => t.level <= maxLevel));
+	const content = serializeYaml({
+		url: result.url,
+		docToken: result.docToken,
+		titles: tree
+	});
+	if (agentLocal) {
+		fs.mkdirSync(opts.output, { recursive: true });
+		const filePath = path.resolve(opts.output, `${result.docToken}.titles.yaml`);
+		fs.writeFileSync(filePath, content);
+		process.stdout.write(`**The Feishu document titles have been downloaded to the following absolute path:**\n\n\`${filePath}\`\n\n**Read this file to access the full titles list.**\n`);
+	} else process.stdout.write(content);
 });
 program.parse();
 //#endregion

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 * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { Command } from 'commander';\nimport { LoggerLevel } from '@larksuiteoapi/node-sdk';\nimport { convert } from './converter.js';\nimport { buildTitleTree, getTitles } from './get-titles.js';\nimport { setLogLevel } from './logger.js';\nimport { serializeYaml } from './whiteboard/yaml/serialize.js';\nimport type { SvgBackground, WbFormat, WbImageMode, AgentMode } from './types.js';\n\nconst program = new Command();\nprogram.name('larkDocx2md').description('Download Lark/Feishu documents to markdown');\n\n/**\n * 把 commander 解析出的 --agent 原值（undefined | true | string）与\n * LARK_DOCX2MD_AGENT 环境变量统一收敛为精确的 AgentMode | false。\n *\n * 优先级：显式 --agent > 环境变量 > 默认 false。\n * 非法取值返回错误信息字符串，由调用方决定如何上报。\n */\nfunction resolveAgentMode (raw: boolean | string | undefined): { value: AgentMode | false; error?: string } {\n  if (raw === undefined) {\n    const env = process.env.LARK_DOCX2MD_AGENT;\n    if (env === 'stdout' || env === 'local') return { value: env };\n    if (env !== undefined && env !== '') {\n      return { value: false, error: `Invalid LARK_DOCX2MD_AGENT=\"${env}\", must be \"stdout\" or \"local\"` };\n    }\n    return { value: false };\n  }\n  // --agent 不带值：默认 stdout\n  if (raw === true) return { value: 'stdout' };\n  if (raw === 'stdout' || raw === 'local') return { value: raw };\n  return { value: false, error: `Invalid --agent value \"${raw}\", must be \"stdout\" or \"local\"` };\n}\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. Modes: \"stdout\" (default, print markdown to stdout) or \"local\" (save markdown/images/whiteboards to disk and print a read-file prompt). Or LARK_DOCX2MD_AGENT=stdout|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 | 'stdout' | 'local' | 其他字符串\n    const agentResolved = resolveAgentMode(opts.agent);\n    if (agentResolved.error) {\n      program.error(agentResolved.error);\n      return;\n    }\n    opts.agent = agentResolved.value;\n    const agentEnabled = opts.agent === 'stdout' || opts.agent === 'local';\n    const agentLocal = opts.agent === 'local';\n    const agentStdout = opts.agent === 'stdout';\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 stdout 默认 yaml，其余 svg\n    if (!opts.wbFormat) {\n      if (agentLocal) opts.wbFormat = 'inline-svg';\n      else if (agentStdout) opts.wbFormat = 'yaml';\n      else opts.wbFormat = '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 stdout：一律在线，且画板仅支持内嵌形式\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: opts.agent as AgentMode | false,\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 (agentStdout) {\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 as a nested yaml tree. 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('-o, --output <dir>', 'Output directory used by --agent local (or LARK_DOCX2MD_OUTPUT)')\n  .option('--max-level <n>', 'Only output headings whose level <= n (1~9)', '9')\n  .option('--agent [mode]', 'Enable agent mode: ERROR log level, AI-oriented stdout. Modes: \"stdout\" (default, print titles to stdout) or \"local\" (save titles to disk and print a read-file prompt). Or LARK_DOCX2MD_AGENT=stdout|local')\n  .argument('<url>', 'Feishu wiki/docx URL: https://*.feishu.cn/{wiki,docx,docs}/*')\n  .action(async (url: string, opts: { appId?: string; appSecret?: string; output?: string; maxLevel?: 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    opts.output = opts.output ?? process.env.LARK_DOCX2MD_OUTPUT ?? './larkDocx2mdOutput';\n    const agentResolved = resolveAgentMode(opts.agent);\n    if (agentResolved.error) {\n      program.error(agentResolved.error);\n      return;\n    }\n    opts.agent = agentResolved.value;\n    const agentEnabled = opts.agent === 'stdout' || opts.agent === 'local';\n    const agentLocal = 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\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 as AgentMode | false,\n    });\n    const filtered = result.titles.filter(t => t.level <= maxLevel);\n    const tree = buildTitleTree(filtered);\n    const content = serializeYaml({ url: result.url, docToken: result.docToken, titles: tree });\n\n    if (agentLocal) {\n      // 本地模式：落盘 + 输出引导 AI 读取文件的提示词（绝对路径）\n      fs.mkdirSync(opts.output, { recursive: true });\n      const filePath = path.resolve(opts.output, `${result.docToken}.titles.yaml`);\n      fs.writeFileSync(filePath, content);\n      process.stdout.write(\n        `**The Feishu document titles have been downloaded to the following absolute path:**\\n\\n` +\n        `\\`${filePath}\\`\\n\\n` +\n        `**Read this file to access the full titles list.**\\n`,\n      );\n    } else {\n      process.stdout.write(content);\n    }\n  });\n\nprogram.parse();\n"],"mappings":"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"}

package/dist/{converter-vuRwWoA4.js → converter-DLMAssSI.js}

@@ -1,7 +1,7 @@
-import * as lark from "@larksuiteoapi/node-sdk";
-import { LoggerLevel } from "@larksuiteoapi/node-sdk";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as lark from "@larksuiteoapi/node-sdk";
+import { LoggerLevel } from "@larksuiteoapi/node-sdk";
 //#region src/client.ts
 const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const RATE_LIMIT_MAX_RETRIES = 3;
@@ -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: {
@@ -561,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();
@@ -2685,7 +2687,7 @@ function createLogger(module) {
 }
 //#endregion
 //#region src/md-ast/transformer.ts
-const logger$1 = createLogger("transformer");
+const logger$2 = createLogger("transformer");
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var MdTransformer = class {
 	constructor(client, opts, sourceType = "docx") {
@@ -2701,14 +2703,14 @@ var MdTransformer = class {
 		const map = /* @__PURE__ */ new Map();
 		const uniqueTokens = [...new Set(tokens)];
 		if (uniqueTokens.length === 0) return map;
-		if (this.opts.imageMode === "online" || this.opts.agent === true) for (let i = 0; i < uniqueTokens.length; i += 5) {
+		if (this.opts.imageMode === "online" || this.opts.agent === "stdout") for (let i = 0; i < uniqueTokens.length; i += 5) {
 			const batch = uniqueTokens.slice(i, i + 5);
 			const urlMap = await this.client.batchGetTmpDownloadUrl(batch);
 			for (const token of batch) {
 				const url = urlMap[token];
 				if (url) {
 					map.set(token, url);
-					logger$1.info("Resolved image URL:", token);
+					logger$2.info("Resolved image URL:", token);
 				}
 			}
 		}
@@ -2718,7 +2720,7 @@ var MdTransformer = class {
 				let localPath = await this.client.downloadImage(token, imgDir);
 				localPath = path.relative(this.opts.output, localPath);
 				map.set(token, localPath);
-				logger$1.info("Downloaded image:", localPath);
+				logger$2.info("Downloaded image:", localPath);
 			}
 		}
 		return map;
@@ -2726,15 +2728,15 @@ var MdTransformer = class {
 	async resolveWhiteboards(tokens) {
 		const map = /* @__PURE__ */ new Map();
 		for (const token of tokens) try {
-			logger$1.info("Fetching whiteboard nodes:", token);
+			logger$2.info("Fetching whiteboard nodes:", token);
 			const wbNodes = await this.client.getWhiteboardNodes(token);
-			logger$1.info(`Whiteboard ${token}: ${wbNodes.length} nodes`);
+			logger$2.info(`Whiteboard ${token}: ${wbNodes.length} nodes`);
 			let node;
 			if (this.opts.wbFormat === "yaml") node = await this.processWhiteboardYaml(token, wbNodes);
 			else node = await this.processWhiteboardSvg(token, wbNodes);
 			map.set(token, node);
 		} catch (e) {
-			logger$1.warn(`Failed to render whiteboard ${token}:`, e.message);
+			logger$2.warn(`Failed to render whiteboard ${token}:`, e.message);
 		}
 		return map;
 	}
@@ -2754,7 +2756,7 @@ var MdTransformer = class {
 			const svgPath = path.join(svgDir, `${token}.svg`);
 			fs.writeFileSync(svgPath, svgContent);
 			const relPath = path.relative(this.opts.output, svgPath);
-			logger$1.info("Generated whiteboard SVG:", relPath);
+			logger$2.info("Generated whiteboard SVG:", relPath);
 			return {
 				type: "image",
 				alt: `画板-${token}`,
@@ -2770,7 +2772,7 @@ var MdTransformer = class {
 		let resolvedYaml = yamlContent;
 		let effectiveMode = this.opts.wbImageMode;
 		if (effectiveMode === "base64") {
-			logger$1.warn("YAML mode does not support base64 image embedding, falling back to online mode");
+			logger$2.warn("YAML mode does not support base64 image embedding, falling back to online mode");
 			effectiveMode = "online";
 		}
 		if (imageTokens.length > 0) resolvedYaml = await this.resolveYamlImages(resolvedYaml, imageTokens, effectiveMode);
@@ -2789,7 +2791,7 @@ var MdTransformer = class {
 				const onlineUrl = urlMap[token];
 				if (onlineUrl) {
 					svgContent = svgContent.split(`href="${token}"`).join(`href="${onlineUrl}"`);
-					logger$1.info("Replaced whiteboard image with online URL:", token);
+					logger$2.info("Replaced whiteboard image with online URL:", token);
 				}
 			}
 		}
@@ -2801,11 +2803,11 @@ var MdTransformer = class {
 					const buf = fs.readFileSync(localPath);
 					const dataUri = `data:${path.extname(localPath).slice(1) === "png" ? "image/png" : "image/jpeg"};base64,${buf.toString("base64")}`;
 					svgContent = svgContent.split(`href="${token}"`).join(`href="${dataUri}"`);
-					logger$1.info("Embedded whiteboard image as base64:", token);
+					logger$2.info("Embedded whiteboard image as base64:", token);
 				} else {
 					const relPath = path.basename(localPath);
 					svgContent = svgContent.split(`href="${token}"`).join(`href="${relPath}"`);
-					logger$1.info("Replaced whiteboard image with local path:", relPath);
+					logger$2.info("Replaced whiteboard image with local path:", relPath);
 				}
 			}
 		}
@@ -2819,7 +2821,7 @@ var MdTransformer = class {
 				const onlineUrl = urlMap[token];
 				if (onlineUrl) {
 					yamlContent = yamlContent.split(token).join(onlineUrl);
-					logger$1.info("Replaced YAML image token with online URL:", token);
+					logger$2.info("Replaced YAML image token with online URL:", token);
 				}
 			}
 		}
@@ -2829,7 +2831,7 @@ var MdTransformer = class {
 				const localPath = await this.client.downloadImage(token, imgDir);
 				const relPath = path.relative(this.opts.output, localPath);
 				yamlContent = yamlContent.split(token).join(relPath);
-				logger$1.info("Replaced YAML image token with local path:", relPath);
+				logger$2.info("Replaced YAML image token with local path:", relPath);
 			}
 		}
 		return yamlContent;
@@ -2882,7 +2884,7 @@ var MdTransformer = class {
 							error: `读取失败：${e.message}`
 						});
 					} finally {
-						await sleep(600);
+						await sleep(300);
 					}
 				}
 				map.set(raw, {
@@ -2891,7 +2893,7 @@ var MdTransformer = class {
 					sheets: resolved
 				});
 			} catch (e) {
-				logger$1.warn(`Failed to resolve sheet ${raw}:`, e.message);
+				logger$2.warn(`Failed to resolve sheet ${raw}:`, e.message);
 				map.set(raw, {
 					type: "sheetResolved",
 					title: "",
@@ -2994,15 +2996,31 @@ function extractHeadingText(block) {
 	return body.elements.map((e) => e.text_run?.content ?? "").join("").trim();
 }
 /**
-* 创建标题过滤器，返回一个 pageHandler 兼容的回调和结果获取器。
-* 纯函数工厂，无副作用，易于测试。
+* 将 heading block 转为 HeadingInfo；非 heading 返回 null。纯函数，无状态。
 */
-function createTitleFilter(options) {
-	const targetTitle = options.title.trim();
+function toHeadingInfo(block) {
+	const level = getHeadingLevel(block);
+	if (level === null) return null;
+	return {
+		blockId: block.block_id ?? "",
+		level,
+		text: extractHeadingText(block) ?? ""
+	};
+}
+/**
+* 通用 heading 过滤器骨架：扫描 → 命中 → 收集 → 终止 状态机。
+* 调用方仅需提供 `match(block, info)` 谓词决定何时进入 collecting。
+*
+* 复用要点：
+* - page 节点（block_type=1）始终保留
+* - scanning 阶段把所有 heading 推入 availableHeadings
+* - collecting 阶段遇到同级或更高级标题终止
+*/
+function createHeadingMatchFilter(match) {
 	let state = "scanning";
 	let matchedLevel = 0;
 	const collected = [];
-	const seenHeadings = [];
+	const seen = [];
 	function pageHandler(blocks) {
 		for (const block of blocks) {
 			if (block.block_type === 1) {
@@ -3011,16 +3029,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 = toHeadingInfo(block);
+					if (info) {
+						seen.push(info);
+						if (match(block, info)) {
 							state = "collecting";
-							matchedLevel = level;
+							matchedLevel = info.level;
 							collected.push(block);
 						}
 					}
@@ -3043,8 +3057,8 @@ function createTitleFilter(options) {
 	function getResult() {
 		return {
 			blocks: [...collected],
-			matched: state === "collecting" || state === "done",
-			availableHeadings: [...seenHeadings]
+			matched: state !== "scanning",
+			availableHeadings: [...seen]
 		};
 	}
 	return {
@@ -3052,9 +3066,41 @@ function createTitleFilter(options) {
 		getResult
 	};
 }
+/**
+* 按标题文本过滤（首个匹配生效；若有同名标题，请改用 createTitleBlockIdFilter）。
+*/
+function createTitleFilter(options) {
+	const target = options.title.trim();
+	return createHeadingMatchFilter((_block, info) => info.text === target);
+}
+/**
+* 按 heading 块 id 过滤（最精确，不会受同名标题干扰）。
+* 仅匹配 block_type 为 heading（1~9）且 block_id 严格相等的块。
+*/
+function createTitleBlockIdFilter(options) {
+	const target = options.blockId.trim();
+	return createHeadingMatchFilter((block) => block.block_id === target);
+}
+/**
+* 流式收集文档中所有标题，用于 get-titles 命令。
+* 返回的 pageHandler 始终返回 true，以遵循分页拉取全量文档。
+*/
+function createHeadingCollector() {
+	const headings = [];
+	function pageHandler(blocks) {
+		for (const block of blocks) {
+			const info = toHeadingInfo(block);
+			if (info) headings.push(info);
+		}
+		return true;
+	}
+	return {
+		pageHandler,
+		getHeadings: () => [...headings]
+	};
+}
 //#endregion
-//#region src/converter.ts
-const logger = createLogger("converter");
+//#region src/url.ts
 function parseWikiUrl(url) {
 	const m = url.match(/^https:\/\/[\w.-]+\/(docs|docx|wiki|sheets)\/([a-zA-Z0-9]+)/);
 	if (!m) throw new Error("Invalid feishu document URL");
@@ -3065,6 +3111,51 @@ function parseWikiUrl(url) {
 		sheetId
 	};
 }
+//#endregion
+//#region src/get-titles.ts
+const logger$1 = createLogger("get-titles");
+/** 拉取 docx/wiki 文档中所有标题信息（扁平列表，不下载图片）。不支持电子表格。 */
+async function getTitles(opts) {
+	const { docType, docToken: rawToken } = parseWikiUrl(opts.url);
+	if (docType === "sheets") throw new Error("get-titles does not support spreadsheets, only docx/wiki documents are supported");
+	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$1.info("Resolved wiki node:", node.obj_type, docToken);
+		if (node.obj_type === "sheet") throw new Error("get-titles does not support spreadsheets (wiki node points to a spreadsheet), only docx/wiki documents are supported");
+	}
+	const collector = createHeadingCollector();
+	await client.getDocxBlocks(docToken, collector.pageHandler);
+	const titles = collector.getHeadings();
+	logger$1.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;
+}
+//#endregion
+//#region src/converter.ts
+const logger = createLogger("converter");
 async function convert(opts) {
 	const { docType, docToken: rawToken, sheetId } = parseWikiUrl(opts.url);
 	logger.info("Captured document token:", rawToken, sheetId ? `sheetId: ${sheetId}` : "");
@@ -3096,18 +3187,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`);
@@ -3132,7 +3216,28 @@ 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: buildTitleTree(result.availableHeadings)
+		});
+		msg += `\n\nFull title list of the document:\n\n${yaml}`;
+	}
+	return msg;
+}
 //#endregion
-export { parseWikiUrl as n, setLogLevel as r, convert as t };
+export { setLogLevel as a, parseWikiUrl as i, buildTitleTree as n, serializeYaml as o, getTitles as r, convert as t };
 
-//# sourceMappingURL=converter-vuRwWoA4.js.map
+//# sourceMappingURL=converter-DLMAssSI.js.map