hm-doc-tool 0.3.0

package/dist/common/path-generator.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeFileName = safeFileName;
+exports.buildOutputPaths = buildOutputPaths;
+exports.collectDirectories = collectDirectories;
+exports.saveCatalogJson = saveCatalogJson;
+/**
+ * 路径和下载任务生成模块
+ *
+ * 职责：
+ * 1. 文件名安全化
+ * 2. 计算输出路径并生成下载任务列表
+ * 3. 收集输出所需的全部目录路径
+ * 4. 保存目录树 JSON 文件
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const api_client_js_1 = require("../api-client.js");
+const config_js_1 = require("./config.js");
+const tree_processor_js_1 = require("./tree-processor.js");
+// =============================================================================
+// 文件名安全化
+// =============================================================================
+/** 将文件/目录名中的非法字符及空格替换为下划线 */
+function safeFileName(name) {
+    return name.replace(/[<>:"/\\|?*\s]/g, "_");
+}
+// =============================================================================
+// 路径计算（公共逻辑）
+// =============================================================================
+/** 检查节点是否有关联文档（relateDocument 非空且非 "_"） */
+function hasValidRelateDocument(node) {
+    return !!node.relateDocument && node.relateDocument !== "_";
+}
+/**
+ * 计算根路径和所有节点的相对路径
+ *
+ * 路径计算使用全量 nodes 以保证父子关系完整；
+ * taskNodes 用于决定需要为哪些节点计算路径（可以是过滤后的子集）。
+ *
+ * @param nodes - 全量平铺节点（用于构建 nodeMap，保证父子关系完整）
+ * @param rootId - 指定子树根节点 ID，undefined 表示整个 catalog
+ * @param catalogName - catalog 名称
+ * @param outputBase - 输出根目录
+ * @param taskNodes - 需要计算路径的节点子集（如经过 --no-cpp 过滤后的）
+ * @returns 根路径和节点相对路径映射
+ */
+function buildPathMap(nodes, rootId, catalogName, outputBase, taskNodes) {
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    const nodesForPath = taskNodes || nodes;
+    // 确定输出根路径：指定了 rootId 则用节点名，否则用 catalog 显示名
+    const catalogNameResult = (0, config_js_1.findCatalogName)(catalogName);
+    const displayName = catalogNameResult || catalogName;
+    let rootPath;
+    if (rootId) {
+        const rootNode = nodeMap.get(rootId);
+        rootPath = rootNode
+            ? `${outputBase}/${safeFileName(rootNode.nodeName)}`
+            : `${outputBase}/${safeFileName(displayName)}`;
+    }
+    else {
+        rootPath = `${outputBase}/${safeFileName(displayName)}`;
+    }
+    // 递归计算每个节点相对于 rootPath 的路径
+    const pathMap = new Map();
+    function buildPath(nodeId) {
+        if (pathMap.has(nodeId))
+            return pathMap.get(nodeId);
+        const node = nodeMap.get(nodeId);
+        if (!node)
+            return "";
+        // rootId 节点自身：路径为空（rootPath 已包含其名称）
+        if (nodeId === rootId) {
+            pathMap.set(nodeId, "");
+            return "";
+        }
+        // 顶级节点（无 parent 或 parent 不在 nodeMap 中）：返回自身名称
+        if (!node.parent || !nodeMap.has(node.parent)) {
+            const relPath = safeFileName(node.nodeName);
+            pathMap.set(nodeId, relPath);
+            return relPath;
+        }
+        // 普通节点：递归拼接父路径
+        const parentPath = buildPath(node.parent);
+        const relPath = parentPath
+            ? `${parentPath}/${safeFileName(node.nodeName)}`
+            : safeFileName(node.nodeName);
+        pathMap.set(nodeId, relPath);
+        return relPath;
+    }
+    for (const node of nodesForPath)
+        buildPath(node.nodeId);
+    return { rootPath, pathMap };
+}
+/**
+ * 计算输出路径并生成下载任务列表
+ *
+ * @param nodes - 全量平铺节点（用于路径计算）
+ * @param rootId - 指定子树根节点 ID，undefined 表示整个 catalog
+ * @param catalogName - catalog 名称
+ * @param outputBase - 输出根目录
+ * @param taskNodes - 需要生成任务的节点子集（如经过 --no-cpp 过滤后的）
+ * @returns 下载任务列表
+ */
+function buildOutputPaths(nodes, rootId, catalogName, outputBase, taskNodes) {
+    const { rootPath, pathMap } = buildPathMap(nodes, rootId, catalogName, outputBase, taskNodes);
+    const nodesForTasks = taskNodes || nodes;
+    const tasks = [];
+    for (const node of nodesForTasks) {
+        const relPath = pathMap.get(node.nodeId) ?? "";
+        if (node.isLeaf || node.children.length === 0) {
+            // 叶子节点 → 直接在父目录下生成 .md
+            if (hasValidRelateDocument(node)) {
+                tasks.push({
+                    nodeId: node.nodeId,
+                    nodeName: node.nodeName,
+                    relateDocument: node.relateDocument,
+                    outputDir: rootPath + (relPath ? `/${relPath}` : "").replace(/\/[^/]+$/, ""),
+                    fileName: safeFileName(node.nodeName) + ".md",
+                    isLeaf: true,
+                });
+            }
+        }
+        else {
+            // 非叶子节点 → 创建同名文件夹，若有 relateDocument 则在文件夹内放自身 .md
+            if (hasValidRelateDocument(node)) {
+                tasks.push({
+                    nodeId: node.nodeId,
+                    nodeName: node.nodeName,
+                    relateDocument: node.relateDocument,
+                    outputDir: `${rootPath}/${relPath}`,
+                    fileName: safeFileName(node.nodeName) + ".md",
+                    isLeaf: false,
+                });
+            }
+        }
+    }
+    return tasks;
+}
+/**
+ * 收集输出所需的全部目录路径（去重、按深度排序）
+ *
+ * @param nodes - 全量平铺节点
+ * @param rootId - 指定子树根节点 ID
+ * @param catalogName - catalog 名称
+ * @param outputBase - 输出根目录
+ * @param taskNodes - 需要创建目录的节点子集
+ * @returns 目录路径数组，按深度从浅到深排序
+ */
+function collectDirectories(nodes, rootId, catalogName, outputBase, taskNodes) {
+    const { rootPath, pathMap } = buildPathMap(nodes, rootId, catalogName, outputBase, taskNodes);
+    const nodesForTasks = taskNodes || nodes;
+    const dirs = new Set();
+    dirs.add(rootPath);
+    for (const node of nodesForTasks) {
+        const relPath = pathMap.get(node.nodeId) ?? "";
+        if (!node.isLeaf && node.children.length > 0) {
+            // 非叶子节点 → 添加其文件夹路径
+            dirs.add(`${rootPath}/${relPath}`);
+        }
+        else {
+            // 叶子节点 → 添加其父目录路径
+            const lastSlash = relPath.lastIndexOf("/");
+            if (lastSlash > 0) {
+                dirs.add(`${rootPath}/${relPath.substring(0, lastSlash)}`);
+            }
+        }
+    }
+    return Array.from(dirs).sort((a, b) => a.split("/").length - b.split("/").length);
+}
+// =============================================================================
+// JSON 保存
+// =============================================================================
+/**
+ * 保存目录树 JSON 文件（参考 fetch_catalog.py）
+ * 输出两个文件：{catalog}_tree.json（原始树结构）和 {catalog}_nodes.json（平铺节点）
+ *
+ * @param catalogName - catalog 名称
+ * @param outputDir - 输出目录路径
+ * @returns 保存的文件路径
+ */
+async function saveCatalogJson(catalogName, outputDir) {
+    const tree = await (0, api_client_js_1.getCatalogTree)(catalogName);
+    const absDir = (0, node_path_1.resolve)(outputDir);
+    (0, node_fs_1.mkdirSync)(absDir, { recursive: true });
+    const treePath = (0, node_path_1.resolve)(absDir, `${catalogName}_tree.json`);
+    (0, node_fs_1.writeFileSync)(treePath, JSON.stringify(tree, null, 2), "utf-8");
+    const flat = (0, tree_processor_js_1.flattenNodes)(tree);
+    const flatPath = (0, node_path_1.resolve)(absDir, `${catalogName}_nodes.json`);
+    (0, node_fs_1.writeFileSync)(flatPath, JSON.stringify(flat, null, 2), "utf-8");
+    return { treePath, flatPath, treeCount: tree.length, flatCount: flat.length };
+}

package/dist/common/tree-formatter.d.ts

@@ -0,0 +1,19 @@
+import type { FlatNode } from "./types.js";
+/**
+ * 生成树形文本输出（使用 box-drawing 字符：├── └── │）
+ *
+ * 规则：
+ * - 指定了 rootId → 该节点作为根
+ * - 未指定 rootId → catalog 中文名作为根，其下挂所有顶层节点
+ * - 非叶子节点显示为 "节点名/"，若有关联文档则在子列表首行显示 "节点名.md"
+ * - 叶子节点显示为 "节点名.md"
+ *
+ * @param nodes - 全量平铺节点
+ * @param rootId - 指定子树根节点 ID
+ * @param catalogName - catalog 名称
+ * @param skipIds - 保留参数（未使用，过滤逻辑已内置）
+ * @param leafOnly - 是否只显示叶子节点
+ * @param maxDepth - 最大显示深度
+ * @param noCpp - 是否过滤 C++ 相关文档
+ */
+export declare function buildTreeOutput(nodes: FlatNode[], rootId: string | undefined, catalogName: string, _skipIds: Set<string>, leafOnly: boolean, maxDepth?: number, noCpp?: boolean): string;

package/dist/common/tree-formatter.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTreeOutput = buildTreeOutput;
+/**
+ * 树形文本格式化输出模块
+ *
+ * 职责：
+ * 1. 生成树形文本输出（box-drawing 字符：├── └── │）
+ */
+const config_js_1 = require("./config.js");
+const tree_processor_js_1 = require("./tree-processor.js");
+const tree_processor_js_2 = require("./tree-processor.js");
+/** 检查节点是否有关联文档（relateDocument 非空且非 "_"） */
+function hasValidRelateDocument(node) {
+    return !!node.relateDocument && node.relateDocument !== "_";
+}
+/**
+ * 生成树形文本输出（使用 box-drawing 字符：├── └── │）
+ *
+ * 规则：
+ * - 指定了 rootId → 该节点作为根
+ * - 未指定 rootId → catalog 中文名作为根，其下挂所有顶层节点
+ * - 非叶子节点显示为 "节点名/"，若有关联文档则在子列表首行显示 "节点名.md"
+ * - 叶子节点显示为 "节点名.md"
+ *
+ * @param nodes - 全量平铺节点
+ * @param rootId - 指定子树根节点 ID
+ * @param catalogName - catalog 名称
+ * @param skipIds - 保留参数（未使用，过滤逻辑已内置）
+ * @param leafOnly - 是否只显示叶子节点
+ * @param maxDepth - 最大显示深度
+ * @param noCpp - 是否过滤 C++ 相关文档
+ */
+function buildTreeOutput(nodes, rootId, catalogName, _skipIds, leafOnly, maxDepth, noCpp = false) {
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    // 收集子树或全量
+    let subtreeNodes;
+    if (rootId) {
+        subtreeNodes = (0, tree_processor_js_1.collectSubtree)(nodes, rootId);
+    }
+    else {
+        subtreeNodes = [...nodes];
+    }
+    // 过滤 C++（含后代）
+    if (noCpp) {
+        const skipSet = (0, tree_processor_js_2.buildCppSkipSet)(nodes, catalogName, noCpp);
+        subtreeNodes = subtreeNodes.filter((n) => !skipSet.has(n.nodeId));
+    }
+    // 过滤 leafOnly
+    if (leafOnly) {
+        subtreeNodes = subtreeNodes.filter((n) => n.isLeaf || n.children.length === 0);
+    }
+    const filteredIds = new Set(subtreeNodes.map((n) => n.nodeId));
+    // 找出根级节点（parent 不在过滤后集合中，或 parent 为空，或是 rootId 自身）
+    const rootNodes = subtreeNodes.filter((n) => !n.parent || !filteredIds.has(n.parent) || n.nodeId === rootId);
+    const lines = [];
+    /** 递归打印节点及其子节点 */
+    function printNode(node, prefix, isLast, depth) {
+        if (maxDepth !== undefined && depth > maxDepth)
+            return;
+        const connector = isLast ? "└── " : "├── ";
+        const isLeafNode = node.isLeaf || node.children.length === 0;
+        const hasDoc = hasValidRelateDocument(node);
+        const label = isLeafNode ? `${node.nodeName}.md` : `${node.nodeName}/`;
+        lines.push(`${prefix}${connector}${label}`);
+        if (!isLeafNode) {
+            const childPrefix = prefix + (isLast ? "    " : "│   ");
+            // 构建子项列表：先放自身 .md，再放子节点
+            const children = [];
+            if (hasDoc)
+                children.push({ node: null, isOwnMd: true });
+            const childNodes = node.children
+                .map((id) => nodeMap.get(id))
+                .filter((n) => !!n && filteredIds.has(n.nodeId));
+            for (const child of childNodes)
+                children.push({ node: child, isOwnMd: false });
+            for (let i = 0; i < children.length; i++) {
+                const isLastChild = i === children.length - 1;
+                const childConnector = isLastChild ? "└── " : "├── ";
+                if (children[i].isOwnMd) {
+                    lines.push(`${childPrefix}${childConnector}${node.nodeName}.md`);
+                }
+                else {
+                    printNode(children[i].node, childPrefix, isLastChild, depth + 1);
+                }
+            }
+        }
+    }
+    if (rootId) {
+        // 指定了节点 → 该节点作为根
+        const rootNode = nodeMap.get(rootId);
+        if (rootNode) {
+            const isLeafNode = rootNode.isLeaf || rootNode.children.length === 0;
+            const hasDoc = hasValidRelateDocument(rootNode);
+            lines.push(isLeafNode ? `${rootNode.nodeName}.md` : `${rootNode.nodeName}/`);
+            if (!isLeafNode) {
+                const children = [];
+                if (hasDoc)
+                    children.push({ node: null, isOwnMd: true });
+                const childNodes = rootNode.children
+                    .map((id) => nodeMap.get(id))
+                    .filter((n) => !!n && filteredIds.has(n.nodeId));
+                for (const child of childNodes)
+                    children.push({ node: child, isOwnMd: false });
+                for (let i = 0; i < children.length; i++) {
+                    const isLastChild = i === children.length - 1;
+                    const childConnector = isLastChild ? "└── " : "├── ";
+                    if (children[i].isOwnMd) {
+                        lines.push(`${childConnector}${rootNode.nodeName}.md`);
+                    }
+                    else {
+                        printNode(children[i].node, "", isLastChild, 1);
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // 未指定节点 → displayName 作为根，其下挂所有顶层节点
+        const catalogNameResult = (0, config_js_1.findCatalogName)(catalogName);
+        const displayName = catalogNameResult || catalogName;
+        lines.push(`${displayName}/`);
+        for (let i = 0; i < rootNodes.length; i++) {
+            const isLast = i === rootNodes.length - 1;
+            printNode(rootNodes[i], "", isLast, 1);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/common/tree-processor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 树结构处理模块
+ *
+ * 职责：
+ * 1. 将嵌套 CatalogNode[] 平铺为 FlatNode[]
+ * 2. 节点查找、子树收集
+ * 3. C++ 文档过滤（--no-cpp）
+ */
+import { type CatalogNode } from "../api-client.js";
+import type { FlatNode } from "./types.js";
+/** 将嵌套 CatalogNode[] 递归平铺为 FlatNode[] */
+export declare function flattenNodes(nodes: CatalogNode[]): FlatNode[];
+/** 在平铺列表中按 nodeId 或 nodeName 查找节点，优先 nodeId */
+export declare function findNode(nodes: FlatNode[], nodeId?: string, nodeName?: string): FlatNode | undefined;
+/** 收集 rootId 下的所有后代节点（含 rootId 自身） */
+export declare function collectSubtree(nodes: FlatNode[], rootId: string): FlatNode[];
+/** 收集多个根节点下所有后代 nodeId 集合（含根自身） */
+export declare function collectSubtreeIds(nodes: FlatNode[], rootIds: Set<string>): Set<string>;
+/**
+ * 获取目录树并平铺
+ * @param catalogName - catalog 名称
+ * @returns 平铺后的节点列表
+ */
+export declare function fetchCatalogTree(catalogName: string): Promise<FlatNode[]>;
+/**
+ * 构建 harmonyos-references 中 "C API" 子树的 nodeId 集合
+ * 仅对 harmonyos-references catalog 生效，其他 catalog 返回空集
+ */
+export declare function buildCppSkipIds(nodes: FlatNode[], catalogName: string): Set<string>;
+/**
+ * 构建完整的 C++ 过滤集合，包含：
+ * 1. harmonyos-references 中 "C API" 整棵子树
+ * 2. 所有 catalog 中 nodeName 含 "c++" 或 ".h" 的节点及其全部后代
+ */
+export declare function buildCppSkipSet(nodes: FlatNode[], catalogName: string, noCpp: boolean): Set<string>;

package/dist/common/tree-processor.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenNodes = flattenNodes;
+exports.findNode = findNode;
+exports.collectSubtree = collectSubtree;
+exports.collectSubtreeIds = collectSubtreeIds;
+exports.fetchCatalogTree = fetchCatalogTree;
+exports.buildCppSkipIds = buildCppSkipIds;
+exports.buildCppSkipSet = buildCppSkipSet;
+/**
+ * 树结构处理模块
+ *
+ * 职责：
+ * 1. 将嵌套 CatalogNode[] 平铺为 FlatNode[]
+ * 2. 节点查找、子树收集
+ * 3. C++ 文档过滤（--no-cpp）
+ */
+const api_client_js_1 = require("../api-client.js");
+// =============================================================================
+// 树结构操作
+// =============================================================================
+/** 将嵌套 CatalogNode[] 递归平铺为 FlatNode[] */
+function flattenNodes(nodes) {
+    const result = [];
+    function walk(list) {
+        for (const node of list) {
+            const childIds = node.children?.map((c) => c.nodeId) ?? [];
+            result.push({
+                nodeId: node.nodeId,
+                nodeName: node.nodeName,
+                relateDocument: node.relateDocument ?? null,
+                parent: node.parent ?? null,
+                children: childIds,
+                isLeaf: node.isLeaf ?? childIds.length === 0,
+            });
+            if (node.children?.length)
+                walk(node.children);
+        }
+    }
+    walk(nodes);
+    return result;
+}
+/** 在平铺列表中按 nodeId 或 nodeName 查找节点，优先 nodeId */
+function findNode(nodes, nodeId, nodeName) {
+    if (nodeId)
+        return nodes.find((n) => n.nodeId === nodeId);
+    if (nodeName)
+        return nodes.find((n) => n.nodeName === nodeName);
+    return undefined;
+}
+/** 收集 rootId 下的所有后代节点（含 rootId 自身） */
+function collectSubtree(nodes, rootId) {
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    const result = [];
+    function walk(id) {
+        const node = nodeMap.get(id);
+        if (!node)
+            return;
+        result.push(node);
+        for (const childId of node.children)
+            walk(childId);
+    }
+    walk(rootId);
+    return result;
+}
+/** 收集多个根节点下所有后代 nodeId 集合（含根自身） */
+function collectSubtreeIds(nodes, rootIds) {
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    const result = new Set();
+    function walk(id) {
+        if (result.has(id))
+            return;
+        result.add(id);
+        const node = nodeMap.get(id);
+        if (!node)
+            return;
+        for (const childId of node.children)
+            walk(childId);
+    }
+    for (const rootId of rootIds)
+        walk(rootId);
+    return result;
+}
+/**
+ * 获取目录树并平铺
+ * @param catalogName - catalog 名称
+ * @returns 平铺后的节点列表
+ */
+async function fetchCatalogTree(catalogName) {
+    const tree = await (0, api_client_js_1.getCatalogTree)(catalogName);
+    return flattenNodes(tree);
+}
+// =============================================================================
+// C++ 过滤
+// =============================================================================
+/**
+ * 构建 harmonyos-references 中 "C API" 子树的 nodeId 集合
+ * 仅对 harmonyos-references catalog 生效，其他 catalog 返回空集
+ */
+function buildCppSkipIds(nodes, catalogName) {
+    if (catalogName !== "harmonyos-references")
+        return new Set();
+    const cApiIds = nodes.filter((n) => n.nodeName === "C API").map((n) => n.nodeId);
+    if (cApiIds.length === 0)
+        return new Set();
+    return collectSubtreeIds(nodes, new Set(cApiIds));
+}
+/**
+ * 构建完整的 C++ 过滤集合，包含：
+ * 1. harmonyos-references 中 "C API" 整棵子树
+ * 2. 所有 catalog 中 nodeName 含 "c++" 或 ".h" 的节点及其全部后代
+ */
+function buildCppSkipSet(nodes, catalogName, noCpp) {
+    if (!noCpp)
+        return new Set();
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    const skipIds = buildCppSkipIds(nodes, catalogName);
+    // 找到所有 nodeName 包含 c++ 或 .h 的节点
+    const cppNodeIds = [];
+    for (const node of nodes) {
+        if (skipIds.has(node.nodeId))
+            continue;
+        const name = node.nodeName.toLowerCase();
+        if (name.includes("c++") || name.includes(".h")) {
+            cppNodeIds.push(node.nodeId);
+        }
+    }
+    // 收集这些节点及其全部后代
+    const result = new Set(skipIds);
+    for (const nodeId of cppNodeIds) {
+        collectDescendants(nodeMap, nodeId, result);
+    }
+    return result;
+}
+/** 递归收集 nodeId 及其所有后代加入 result 集合 */
+function collectDescendants(nodeMap, nodeId, result) {
+    if (result.has(nodeId))
+        return;
+    result.add(nodeId);
+    const node = nodeMap.get(nodeId);
+    if (!node)
+        return;
+    for (const childId of node.children)
+        collectDescendants(nodeMap, childId, result);
+}

package/dist/common/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 共享类型定义
+ */
+/** docs_catalog.json 中的 catalog 项 */
+export interface CatalogItem {
+    id: string;
+    name: string;
+}
+/** docs_catalog.json 中的顶层分类 */
+export interface TopLevelCatalog {
+    top_level: string;
+    catalogs: CatalogItem[];
+}
+/** 包含顶层分类信息的 catalog */
+export interface CatalogWithTopLevel {
+    topLevel: string;
+    catalog: CatalogItem;
+}
+/** 平铺后的节点，children 只存 nodeId 字符串 */
+export interface FlatNode {
+    nodeId: string;
+    nodeName: string;
+    relateDocument: string | null;
+    parent: string | null;
+    children: string[];
+    isLeaf: boolean;
+}
+/** 下载任务：一个节点对应一个待下载/写入的 .md 文件 */
+export interface OutputTask {
+    nodeId: string;
+    nodeName: string;
+    relateDocument: string | null;
+    /** 写入目录的绝对路径 */
+    outputDir: string;
+    /** .md 文件名（含扩展名） */
+    fileName: string;
+    isLeaf: boolean;
+}

package/dist/common/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * 共享类型定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/download/downloader.d.ts

@@ -0,0 +1,46 @@
+import type { FlatNode, OutputTask } from "../common/types.js";
+/**
+ * 通过 URL 下载单篇文档（不建目录，直接写入 outputDir）
+ *
+ * @param objectId - 文档 objectId
+ * @param catalogName - catalog 名称
+ * @param nodeName - 节点名称（用作文件名）
+ * @param outputDir - 输出目录
+ */
+export declare function downloadSingle(objectId: string, catalogName: string, nodeName: string, outputDir: string): Promise<void>;
+/** 下载选项 */
+export interface DownloadOptions {
+    outputDir: string;
+    concurrency: number;
+    leafOnly: boolean;
+    noCpp: boolean;
+    dryRun: boolean;
+    /** 顶层分类名称（如 "application"），用于构建输出路径 */
+    topLevel?: string;
+}
+/**
+ * 下载文档子树
+ *
+ * 完整流程：
+ * 1. 获取目录树 → 平铺为 FlatNode[]
+ * 2. 定位目标节点（按 nodeId 或 nodeName）
+ * 3. 收集子树节点
+ * 4. C++ 过滤（--no-cpp，含后代）
+ * 5. leafOnly 过滤
+ * 6. 计算输出路径（用全量 nodes 算路径，用过滤后 subtreeNodes 生成任务）
+ * 7. --dry-run 则打印树形结构后返回
+ * 8. 创建所有目录（先建目录避免并发竞态）
+ * 9. 并发下载文档并写入文件
+ * 10. 输出汇总（成功数、失败列表）
+ *
+ * @param catalogName - catalog 名称
+ * @param rootId - 子树根节点 ID，undefined 表示整个 catalog
+ * @param nodeName - 按名称定位节点（与 nodeId 二选一）
+ * @param nodeId - 按 ID 定位节点（优先于 nodeName）
+ * @param options - 下载选项
+ */
+export declare function downloadSubtree(catalogName: string, rootId: string | undefined, nodeName: string | undefined, nodeId: string | undefined, options: DownloadOptions): Promise<{
+    tasks: OutputTask[];
+    nodes: FlatNode[];
+    outputDir: string;
+} | undefined>;