hm-doc-tool 0.3.0

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * CLI 入口
+ *
+ * 三个子命令：
+ * - download: 下载文档到本地 Markdown 文件
+ * - tree: 查看目录树结构（不下载）
+ * - wiki: 从JSON树文件生成Wiki页面
+ */
+const commander_1 = require("commander");
+const index_js_1 = require("./download/index.js");
+const index_js_2 = require("./tree/index.js");
+const index_js_3 = require("./wiki/index.js");
+const package_json_1 = __importDefault(require("../package.json"));
+const program = new commander_1.Command();
+program
+    .name(package_json_1.default.name)
+    .description(package_json_1.default.description)
+    .version(package_json_1.default.version);
+// =============================================================================
+// download 子命令
+// =============================================================================
+program
+    .command("download")
+    .description("Download HarmonyOS docs to local Markdown files")
+    .option("-c, --catalog <catalogName...>", "catalog name(s), can specify multiple")
+    .option("-n, --node-name <name>", "target node name")
+    .option("-i, --node-id <id>", "target node id")
+    .option("-u, --url <url>", "download from URL (auto-detect catalog and node)")
+    .option("-o, --output <dir>", "output directory", "./docs")
+    .option("--leaf-only", "only download leaf nodes", false)
+    .option("--no-cpp", "exclude C++ related docs")
+    .option("--concurrency <n>", "download concurrency", "5")
+    .option("--dry-run", "preview directory tree without downloading", false)
+    .option("-s, --summary", "generate summary JSON file after download", true)
+    .option("-l, --localize", "localize doc links to relative paths", false)
+    .action(index_js_1.handleDownload);
+// =============================================================================
+// tree 子命令
+// =============================================================================
+program
+    .command("tree")
+    .description("Display catalog tree structure")
+    .option("-c, --catalog <catalogName>", "catalog name (if not specified, show all catalogs from docs_catalog.json)")
+    .option("-n, --node-name <name>", "target node name")
+    .option("-i, --node-id <id>", "target node id")
+    .option("-d, --depth <n>", "display depth limit")
+    .option("-o, --output <dir>", "output directory for JSON", "./docs")
+    .option("--no-cpp", "exclude C++ related nodes")
+    .action(index_js_2.handleTree);
+// =============================================================================
+// wiki 子命令
+// =============================================================================
+program
+    .command("wiki")
+    .description("Generate Wiki pages from JSON tree files")
+    .option("-c, --config <path>", "config file path (default: built-in wiki_config.json)")
+    .option("-d, --docs <dir>", "docs directory path", "./docs")
+    .action(index_js_3.handleWiki);
+program.parse();

package/dist/tree/index.d.ts

@@ -0,0 +1,11 @@
+/** Tree 命令选项 */
+export interface TreeOptions {
+    catalog?: string;
+    nodeName?: string;
+    nodeId?: string;
+    depth?: string;
+    output: string;
+    cpp: boolean;
+}
+/** Tree 命令处理函数 */
+export declare function handleTree(opts: TreeOptions): Promise<void>;

package/dist/tree/index.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleTree = handleTree;
+/**
+ * Tree 命令入口
+ *
+ * 职责：
+ * 1. 处理 CLI 选项
+ * 2. 调用 common/ 模块执行目录树显示
+ */
+const tree_processor_js_1 = require("../common/tree-processor.js");
+const path_generator_js_1 = require("../common/path-generator.js");
+const tree_formatter_js_1 = require("../common/tree-formatter.js");
+const config_js_1 = require("../common/config.js");
+/** Tree 命令处理函数 */
+async function handleTree(opts) {
+    try {
+        const catalogName = opts.catalog;
+        const nodeName = opts.nodeName;
+        const nodeId = opts.nodeId;
+        const depth = opts.depth ? parseInt(opts.depth, 10) : undefined;
+        const noCpp = opts.cpp === false;
+        if (catalogName) {
+            // 单 catalog 模式
+            // 仅有 -c 参数时，额外输出 JSON 文件
+            const isJsonMode = !nodeName && !nodeId && !depth && !noCpp;
+            if (isJsonMode) {
+                const result = await (0, path_generator_js_1.saveCatalogJson)(catalogName, opts.output);
+                console.log(`已保存树结构 (${result.treeCount} 个顶层节点) -> ${result.treePath}`);
+                console.log(`已保存平铺节点列表 (${result.flatCount} 个节点) -> ${result.flatPath}`);
+            }
+            // 始终输出树形结构
+            console.log(`\n正在获取目录树: ${catalogName} ...`);
+            const flatNodes = await (0, tree_processor_js_1.fetchCatalogTree)(catalogName);
+            // 定位目标节点
+            let rootId;
+            if (nodeName || nodeId) {
+                const target = (0, tree_processor_js_1.findNode)(flatNodes, nodeId, nodeName);
+                if (!target) {
+                    console.error(`错误: 找不到节点: ${nodeId || nodeName}`);
+                    process.exit(1);
+                }
+                rootId = target.nodeId;
+            }
+            // buildTreeOutput 内部处理 C++ 过滤，skipIds 参数保留但不再使用
+            const output = (0, tree_formatter_js_1.buildTreeOutput)(flatNodes, rootId, catalogName, new Set(), false, depth, noCpp);
+            console.log(output);
+        }
+        else {
+            // 批量模式：使用 docs_catalog.json 配置文件
+            const catalogsWithTopLevel = (0, config_js_1.getAllCatalogsWithTopLevel)();
+            if (catalogsWithTopLevel.length === 0) {
+                console.error("错误: docs_catalog.json 中没有配置任何分类");
+                process.exit(1);
+            }
+            // 批量模式下，如果没有指定节点和过滤选项，生成 JSON 文件
+            const isJsonMode = !nodeName && !nodeId && !depth && !noCpp;
+            let currentTopLevel = "";
+            for (const { topLevel, catalog } of catalogsWithTopLevel) {
+                // 输出分隔提示
+                if (topLevel !== currentTopLevel) {
+                    currentTopLevel = topLevel;
+                    console.log(`\n=== ${topLevel} ===`);
+                }
+                // 生成 JSON 文件
+                if (isJsonMode) {
+                    const result = await (0, path_generator_js_1.saveCatalogJson)(catalog.id, opts.output);
+                    console.log(`已保存树结构 (${result.treeCount} 个顶层节点) -> ${result.treePath}`);
+                    console.log(`已保存平铺节点列表 (${result.flatCount} 个节点) -> ${result.flatPath}`);
+                }
+                console.log(`\n正在获取目录树: ${catalog.name} (${catalog.id}) ...`);
+                const flatNodes = await (0, tree_processor_js_1.fetchCatalogTree)(catalog.id);
+                // 定位目标节点
+                let rootId;
+                if (nodeName || nodeId) {
+                    const target = (0, tree_processor_js_1.findNode)(flatNodes, nodeId, nodeName);
+                    if (target) {
+                        rootId = target.nodeId;
+                    }
+                }
+                // buildTreeOutput 内部处理 C++ 过滤
+                const output = (0, tree_formatter_js_1.buildTreeOutput)(flatNodes, rootId, catalog.id, new Set(), false, depth, noCpp);
+                console.log(output);
+            }
+        }
+    }
+    catch (err) {
+        console.error("错误:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}

package/dist/wiki/index.d.ts

@@ -0,0 +1,7 @@
+/** Wiki 命令选项 */
+export interface WikiOptions {
+    config?: string;
+    docs: string;
+}
+/** Wiki 命令处理函数 */
+export declare function handleWiki(opts: WikiOptions): Promise<void>;

package/dist/wiki/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleWiki = handleWiki;
+/**
+ * Wiki 命令入口
+ *
+ * 职责：
+ * 1. 处理 CLI 选项
+ * 2. 调用 wiki-generator 执行 Wiki 生成
+ */
+const wiki_generator_js_1 = require("./wiki-generator.js");
+/** Wiki 命令处理函数 */
+async function handleWiki(opts) {
+    try {
+        const result = await (0, wiki_generator_js_1.generateWiki)(opts.config, opts.docs);
+        console.log(`\n生成完成: ${result.kitCount} kits + ${result.topicCount} topics, ${result.skippedCount} skipped`);
+    }
+    catch (err) {
+        console.error("错误:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}

package/dist/wiki/wiki-generator.d.ts

@@ -0,0 +1,3 @@
+import type { WikiGenerateResult } from "./wiki-types.js";
+/** 执行Wiki生成（按 topLevel 分开） */
+export declare function generateWiki(configPath: string | undefined, docsDir: string): Promise<WikiGenerateResult>;

package/dist/wiki/wiki-generator.js

@@ -0,0 +1,357 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWiki = generateWiki;
+/** Wiki生成器主逻辑 */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const wiki_utils_js_1 = require("./wiki-utils.js");
+/** 生成Kit概念页内容 */
+function buildWikiPage(kitNode, guideLeaves, apiLeaves, guideNodeMap, apiNodeMap, guideSummaryMap, apiSummaryMap, kitDesc, guidePrefix, apiPrefix) {
+    const kitName = kitNode.nodeName;
+    const kitZh = (0, wiki_utils_js_1.getKitZhName)(kitName);
+    const kitKey = (0, wiki_utils_js_1.getKitKey)(kitName);
+    const slug = kitKey ? kitKey.toLowerCase().replace(/_/g, "-") : kitZh;
+    const today = (0, wiki_utils_js_1.getToday)();
+    let content = `---
+title: "${kitZh} (${kitKey})"
+type: concept
+tags: ["harmonyos", "kit", "${kitZh}"]
+sources: []
+last_updated: ${today}
+---
+
+# ${kitZh} (${kitKey})
+
+${kitDesc}
+
+## 相关文档
+
+### 开发指南
+
+`;
+    for (const leaf of guideLeaves) {
+        const pathParts = (0, wiki_utils_js_1.buildPathParts)(leaf, guideNodeMap, true);
+        const relPath = pathParts.join("/") + ".md";
+        const link = `${guidePrefix}/${relPath}`;
+        const summary = guideSummaryMap.get(leaf.nodeId) || "";
+        const summaryPart = summary ? ` — ${summary}` : "";
+        content += `- [${leaf.nodeName}](<${link}>)${summaryPart}\n`;
+    }
+    if (apiLeaves.length > 0) {
+        content += "\n### API参考\n\n";
+        for (const leaf of apiLeaves) {
+            const pathParts = (0, wiki_utils_js_1.buildPathParts)(leaf, apiNodeMap, true);
+            const relPath = pathParts.join("/") + ".md";
+            const link = `${apiPrefix}/${relPath}`;
+            const summary = apiSummaryMap.get(leaf.nodeId) || "";
+            const summaryPart = summary ? ` — ${summary}` : "";
+            content += `- [${leaf.nodeName}](<${link}>)${summaryPart}\n`;
+        }
+    }
+    content += `
+## 连接
+
+- [[HarmonyOS应用开发]] — 总览
+`;
+    return [slug, content];
+}
+/** 生成Topic概念页内容 */
+function buildTopicPage(catKey, catInfo, guideLeaves, apiLeaves, guideNodeMap, apiNodeMap, guideSummaryMap, apiSummaryMap, guidePrefix, apiPrefix) {
+    const today = (0, wiki_utils_js_1.getToday)();
+    let content = `---
+title: "${catInfo.zh}"
+type: concept
+tags: ["harmonyos", "${catKey}"]
+sources: []
+last_updated: ${today}
+---
+
+# ${catInfo.zh}
+
+${catInfo.desc}
+
+## 相关文档
+
+### 开发指南
+
+`;
+    for (const leaf of guideLeaves) {
+        const pathParts = (0, wiki_utils_js_1.buildPathParts)(leaf, guideNodeMap, true);
+        const relPath = pathParts.join("/") + ".md";
+        const link = `${guidePrefix}/${relPath}`;
+        const summary = guideSummaryMap.get(leaf.nodeId) || "";
+        const summaryPart = summary ? ` — ${summary}` : "";
+        content += `- [${leaf.nodeName}](<${link}>)${summaryPart}\n`;
+    }
+    if (apiLeaves.length > 0) {
+        content += "\n### API参考\n\n";
+        for (const leaf of apiLeaves) {
+            const pathParts = (0, wiki_utils_js_1.buildPathParts)(leaf, apiNodeMap, true);
+            const relPath = pathParts.join("/") + ".md";
+            const link = `${apiPrefix}/${relPath}`;
+            const summary = apiSummaryMap.get(leaf.nodeId) || "";
+            const summaryPart = summary ? ` — ${summary}` : "";
+            content += `- [${leaf.nodeName}](<${link}>)${summaryPart}\n`;
+        }
+    }
+    content += `
+## 连接
+
+- [[HarmonyOS应用开发]] — 总览
+`;
+    return [catKey, content];
+}
+/** 生成index.md */
+function buildIndex(createdPages, guideSummarySet, apiSummarySet, guideClassifiedUnique, apiClassifiedUnique, outputDir, topLevel) {
+    const today = (0, wiki_utils_js_1.getToday)();
+    const guideTotal = guideSummarySet.size;
+    const apiTotal = apiSummarySet.size;
+    // 按类别分组
+    const byCategory = new Map();
+    for (const page of createdPages) {
+        const list = byCategory.get(page.category) || [];
+        list.push(page);
+        byCategory.set(page.category, list);
+    }
+    const lines = [
+        `# HarmonyOS ${topLevel} Wiki Index`,
+        "",
+        `> 自动生成于 ${today} | 共 ${guideTotal} 篇指南 + ${apiTotal} 篇API参考（仅统计有效文档） | ${guideClassifiedUnique} 篇指南 + ${apiClassifiedUnique} 篇API参考已归类至概念页`,
+        "",
+        "## Overview",
+        "- [Overview](overview.md) — 全局概览",
+        "",
+        "## 按Kit/服务分类",
+        "",
+    ];
+    const sortedCategories = [...byCategory.keys()].sort();
+    for (const cat of sortedCategories) {
+        const pages = byCategory.get(cat).sort((a, b) => a.zh.localeCompare(b.zh));
+        for (const page of pages) {
+            lines.push(`- [${page.zh} (${page.kitKey})](concepts/${page.slug}.md) — ${page.desc}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Sources");
+    lines.push("");
+    const indexContent = lines.join("\n");
+    const indexPath = (0, path_1.join)(outputDir, "index.md");
+    (0, fs_1.writeFileSync)(indexPath, indexContent, "utf-8");
+    console.log(`[INDEX] index.md (${createdPages.length} kits)`);
+}
+/** 为单个 topLevel 生成 Wiki */
+async function generateWikiForTopLevel(topLevel, catalogDataList, config, parentDir) {
+    const actualOutputDir = (0, path_1.join)(parentDir, `${topLevel}-wiki`);
+    console.log(`\n=== ${topLevel} ===`);
+    console.log(`输出目录: ${actualOutputDir}`);
+    // 按类型分离指南和API参考
+    let guideData;
+    let apiData;
+    for (const data of catalogDataList) {
+        if (data.catalogName === "指南") {
+            guideData = data;
+        }
+        else if (data.catalogName === "API参考") {
+            apiData = data;
+        }
+    }
+    if (!guideData && !apiData) {
+        console.log(`[SKIP] ${topLevel}: 未找到指南或API参考数据`);
+        return { kitCount: 0, topicCount: 0, skippedCount: 0, createdPages: [] };
+    }
+    // 构建查找表
+    const guideNodeMap = guideData ? (0, wiki_utils_js_1.buildNodeMap)(guideData.tree) : new Map();
+    const apiNodeMap = apiData ? (0, wiki_utils_js_1.buildNodeMap)(apiData.tree) : new Map();
+    const guideSummaryMap = guideData ? (0, wiki_utils_js_1.buildSummaryMap)(guideData.summary) : new Map();
+    const apiSummaryMap = apiData ? (0, wiki_utils_js_1.buildSummaryMap)(apiData.summary) : new Map();
+    const guideSummarySet = guideData ? (0, wiki_utils_js_1.buildSummarySet)(guideData.summary) : new Set();
+    const apiSummarySet = apiData ? (0, wiki_utils_js_1.buildSummarySet)(apiData.summary) : new Set();
+    // 查找所有Kit节点
+    const guideKits = guideData ? (0, wiki_utils_js_1.findKitNodes)(guideData.tree) : [];
+    const apiKits = apiData ? (0, wiki_utils_js_1.findKitNodes)(apiData.tree) : [];
+    const apiKitByName = new Map();
+    for (const kit of apiKits) {
+        apiKitByName.set(kit.nodeName, kit);
+    }
+    (0, fs_1.mkdirSync)((0, path_1.join)(actualOutputDir, "concepts"), { recursive: true });
+    let created = 0;
+    let skipped = 0;
+    const createdPages = [];
+    const allGuideNodeIds = new Set();
+    const allApiNodeIds = new Set();
+    const guidePrefix = guideData?.linkPrefix || "";
+    const apiPrefix = apiData?.linkPrefix || "";
+    // 第一步：生成Kit概念页
+    for (const kitNode of guideKits) {
+        const kitName = kitNode.nodeName;
+        const kitKey = (0, wiki_utils_js_1.getKitKey)(kitName);
+        const kitInfo = config.kitCategories[kitKey];
+        if (!kitInfo) {
+            console.log(`[SKIP] No kitCategories entry for: ${kitName} (key: ${kitKey})`);
+            skipped++;
+            continue;
+        }
+        const guideLeaves = (0, wiki_utils_js_1.collectLeafNodes)(kitNode, guideSummarySet);
+        for (const leaf of guideLeaves) {
+            allGuideNodeIds.add(leaf.nodeId);
+        }
+        const apiKit = apiKitByName.get(kitName);
+        const apiLeaves = apiKit ? (0, wiki_utils_js_1.collectLeafNodes)(apiKit, apiSummarySet) : [];
+        for (const leaf of apiLeaves) {
+            allApiNodeIds.add(leaf.nodeId);
+        }
+        const [slug, content] = buildWikiPage(kitNode, guideLeaves, apiLeaves, guideNodeMap, apiNodeMap, guideSummaryMap, apiSummaryMap, kitInfo.desc, guidePrefix, apiPrefix);
+        const filepath = (0, path_1.join)(actualOutputDir, "concepts", `${slug}.md`);
+        (0, fs_1.writeFileSync)(filepath, content, "utf-8");
+        created++;
+        createdPages.push({
+            slug,
+            kitKey,
+            zh: kitInfo.zh,
+            desc: kitInfo.desc,
+            category: kitInfo.zh,
+            guideCount: guideLeaves.length,
+            apiCount: apiLeaves.length,
+        });
+        console.log(`[OK] ${kitName} -> ${slug}.md (${guideLeaves.length} guides, ${apiLeaves.length} API)`);
+    }
+    // 第二步：处理仅在API树中存在的Kit
+    const guideKitNames = new Set(guideKits.map((n) => n.nodeName));
+    for (const kitNode of apiKits) {
+        if (guideKitNames.has(kitNode.nodeName)) {
+            continue;
+        }
+        const kitName = kitNode.nodeName;
+        const kitKey = (0, wiki_utils_js_1.getKitKey)(kitName);
+        const kitInfo = config.kitCategories[kitKey];
+        if (!kitInfo) {
+            continue;
+        }
+        const apiLeaves = (0, wiki_utils_js_1.collectLeafNodes)(kitNode, apiSummarySet);
+        for (const leaf of apiLeaves) {
+            allApiNodeIds.add(leaf.nodeId);
+        }
+        const [slug, content] = buildWikiPage(kitNode, [], apiLeaves, guideNodeMap, apiNodeMap, guideSummaryMap, apiSummaryMap, kitInfo.desc, guidePrefix, apiPrefix);
+        const filepath = (0, path_1.join)(actualOutputDir, "concepts", `${slug}.md`);
+        (0, fs_1.writeFileSync)(filepath, content, "utf-8");
+        created++;
+        createdPages.push({
+            slug,
+            kitKey,
+            zh: kitInfo.zh,
+            desc: kitInfo.desc,
+            category: kitInfo.zh,
+            guideCount: 0,
+            apiCount: apiLeaves.length,
+        });
+        console.log(`[OK] ${kitName} -> ${slug}.md (0 guides, ${apiLeaves.length} API)`);
+    }
+    // 第三步：生成Topic概念页
+    const topicGuideLeaves = new Map();
+    const guideSummary = guideData?.summary || [];
+    for (const node of guideSummary) {
+        const topics = (0, wiki_utils_js_1.matchTopic)(node.nodeName, config.topicCategories);
+        for (const t of topics) {
+            const list = topicGuideLeaves.get(t) || [];
+            list.push(node);
+            topicGuideLeaves.set(t, list);
+        }
+    }
+    const topicApiLeaves = new Map();
+    const apiSummary = apiData?.summary || [];
+    for (const node of apiSummary) {
+        const topics = (0, wiki_utils_js_1.matchTopic)(node.nodeName, config.topicCategories);
+        for (const t of topics) {
+            const list = topicApiLeaves.get(t) || [];
+            list.push(node);
+            topicApiLeaves.set(t, list);
+        }
+    }
+    // 去重：如果topic key和某个Kit key重叠，跳过该topic
+    const kitKeysLower = new Set();
+    for (const key of Object.keys(config.kitCategories)) {
+        kitKeysLower.add(key.replace("_Kit", "").toLowerCase());
+    }
+    let topicCreated = 0;
+    for (const [catKey, catInfo] of Object.entries(config.topicCategories)) {
+        if (kitKeysLower.has(catKey)) {
+            continue;
+        }
+        const gLeaves = topicGuideLeaves.get(catKey) || [];
+        const aLeaves = topicApiLeaves.get(catKey) || [];
+        if (gLeaves.length === 0 && aLeaves.length === 0) {
+            continue;
+        }
+        const [slug, content] = buildTopicPage(catKey, catInfo, gLeaves, aLeaves, guideNodeMap, apiNodeMap, guideSummaryMap, apiSummaryMap, guidePrefix, apiPrefix);
+        const filepath = (0, path_1.join)(actualOutputDir, "concepts", `${slug}.md`);
+        (0, fs_1.writeFileSync)(filepath, content, "utf-8");
+        topicCreated++;
+        createdPages.push({
+            slug,
+            kitKey: catKey,
+            zh: catInfo.zh,
+            desc: catInfo.desc,
+            category: catInfo.zh,
+            guideCount: gLeaves.length,
+            apiCount: aLeaves.length,
+        });
+        for (const leaf of gLeaves) {
+            allGuideNodeIds.add(leaf.nodeId);
+        }
+        for (const leaf of aLeaves) {
+            allApiNodeIds.add(leaf.nodeId);
+        }
+        console.log(`[TOPIC] ${catInfo.zh} -> ${slug}.md (${gLeaves.length} guides, ${aLeaves.length} API)`);
+    }
+    // 生成index.md
+    buildIndex(createdPages, guideSummarySet, apiSummarySet, allGuideNodeIds.size, allApiNodeIds.size, actualOutputDir, topLevel);
+    console.log(`\n${topLevel} 完成: ${created} kits + ${topicCreated} topics, ${skipped} skipped`);
+    return {
+        kitCount: created,
+        topicCount: topicCreated,
+        skippedCount: skipped,
+        createdPages,
+    };
+}
+/** 执行Wiki生成（按 topLevel 分开） */
+async function generateWiki(configPath, docsDir) {
+    // 加载配置，如果未指定则使用包内的默认配置
+    const actualConfigPath = configPath || (0, path_1.join)(__dirname, "..", "..", "wiki_config.json");
+    const config = (0, wiki_utils_js_1.loadWikiConfig)(actualConfigPath);
+    // docs目录
+    const actualInputDir = (0, path_1.resolve)(docsDir);
+    // wiki一定和docs平级
+    const parentDir = (0, path_1.resolve)(actualInputDir, "..");
+    console.log(`输入目录: ${actualInputDir}`);
+    // 加载所有catalog数据
+    const catalogDataList = (0, wiki_utils_js_1.loadAllCatalogData)(actualInputDir);
+    // 按 topLevel 分组
+    const byTopLevel = new Map();
+    for (const data of catalogDataList) {
+        const list = byTopLevel.get(data.topLevel) || [];
+        list.push(data);
+        byTopLevel.set(data.topLevel, list);
+    }
+    if (byTopLevel.size === 0) {
+        throw new Error("未找到任何 catalog 数据");
+    }
+    // 对每个 topLevel 生成 wiki
+    let totalKitCount = 0;
+    let totalTopicCount = 0;
+    let totalSkippedCount = 0;
+    const allCreatedPages = [];
+    for (const [topLevel, dataList] of byTopLevel) {
+        const result = await generateWikiForTopLevel(topLevel, dataList, config, parentDir);
+        totalKitCount += result.kitCount;
+        totalTopicCount += result.topicCount;
+        totalSkippedCount += result.skippedCount;
+        allCreatedPages.push(...result.createdPages);
+    }
+    console.log(`\n全部完成: ${totalKitCount} kits + ${totalTopicCount} topics, ${totalSkippedCount} skipped`);
+    return {
+        kitCount: totalKitCount,
+        topicCount: totalTopicCount,
+        skippedCount: totalSkippedCount,
+        createdPages: allCreatedPages,
+    };
+}

package/dist/wiki/wiki-types.d.ts

@@ -0,0 +1,61 @@
+/** Wiki生成器类型定义 */
+/** Kit分类信息 */
+export interface KitCategoryInfo {
+    zh: string;
+    desc: string;
+}
+/** Topic分类信息 */
+export interface TopicCategoryInfo {
+    zh: string;
+    desc: string;
+    patterns: string[];
+}
+/** Wiki配置 */
+export interface WikiConfig {
+    kitCategories: Record<string, KitCategoryInfo>;
+    topicCategories: Record<string, TopicCategoryInfo>;
+}
+/** 目录树节点 */
+export interface TreeNode {
+    nodeId: string;
+    nodeName: string;
+    isLeaf?: boolean;
+    parent?: string;
+    children?: TreeNode[];
+    relateDocument?: string;
+    [key: string]: unknown;
+}
+/** 摘要节点 */
+export interface SummaryNode {
+    nodeId: string;
+    nodeName: string;
+    summary?: string;
+    parent?: string;
+    [key: string]: unknown;
+}
+/** 生成的页面信息 */
+export interface CreatedPage {
+    slug: string;
+    kitKey: string;
+    zh: string;
+    desc: string;
+    category: string;
+    guideCount: number;
+    apiCount: number;
+}
+/** Wiki生成结果 */
+export interface WikiGenerateResult {
+    kitCount: number;
+    topicCount: number;
+    skippedCount: number;
+    createdPages: CreatedPage[];
+}
+/** Catalog数据（已加载的树和摘要） */
+export interface CatalogData {
+    topLevel: string;
+    catalogId: string;
+    catalogName: string;
+    tree: TreeNode[];
+    summary: SummaryNode[];
+    linkPrefix: string;
+}

package/dist/wiki/wiki-types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Wiki生成器类型定义 */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wiki/wiki-utils.d.ts

@@ -0,0 +1,33 @@
+import type { WikiConfig, TreeNode, SummaryNode, CatalogData } from "./wiki-types.js";
+/** 加载JSON文件 */
+export declare function loadJson<T>(filePath: string): T;
+/** 加载Wiki配置 */
+export declare function loadWikiConfig(configPath: string): WikiConfig;
+/** 加载所有Catalog数据 */
+export declare function loadAllCatalogData(inputDir: string): CatalogData[];
+/** 构建节点映射表 (nodeId -> node) */
+export declare function buildNodeMap(treeData: TreeNode[]): Map<string, TreeNode>;
+/** 构建摘要映射表 (nodeId -> summary) */
+export declare function buildSummaryMap(summaryData: SummaryNode[]): Map<string, string>;
+/** 构建摘要节点ID集合 */
+export declare function buildSummarySet(summaryData: SummaryNode[]): Set<string>;
+/** 判断是否为Kit节点 (匹配 "XXX Kit（YYY）" 格式) */
+export declare function isKitNode(node: TreeNode): boolean;
+/** 查找所有Kit节点 */
+export declare function findKitNodes(treeData: TreeNode[]): TreeNode[];
+/** 收集叶子节点 */
+export declare function collectLeafNodes(node: TreeNode, summarySet?: Set<string>): TreeNode[];
+/** 清理文件名中的非法字符 */
+export declare function sanitizeName(name: string): string;
+/** 构建从根节点到指定节点的路径 */
+export declare function buildPathParts(node: TreeNode, nodeMap: Map<string, TreeNode>, sanitize?: boolean): string[];
+/** 从Kit节点名提取中文描述 */
+export declare function getKitZhName(nodeName: string): string;
+/** 从Kit节点名获取Kit Key */
+export declare function getKitKey(nodeName: string): string;
+/** 匹配Topic分类 */
+export declare function matchTopic(nodeName: string, topicCategories: Record<string, {
+    patterns: string[];
+}>): string[];
+/** 获取当前日期字符串 */
+export declare function getToday(): string;