hm-doc-tool 0.3.0

package/README.md

@@ -0,0 +1,230 @@
+# HarmonyOS Documentation Downloader
+
+将华为 HarmonyOS 官方文档下载并转换为本地 Markdown 文件的 CLI 工具。
+
+## 功能特性
+
+- **目录结构同步** - 下载的文档目录层级与华为开发者官网完全一致
+- **链接本地化** - 将文档中的远程链接替换为本地相对路径，支持跨 catalog 和锚点保留
+- **元数据导出** - 支持导出目录树 JSON 和节点平铺列表
+- **文档概要生成** - 自动提取摘要，生成 summary JSON 索引
+- **Wiki 生成** - 从下载的文档生成 Wiki 文件
+- 多 catalog 支持（指南、API 参考、最佳实践、FAQ 等）
+- HTML 转 Markdown，保留代码块、表格、链接等格式
+- 并发下载，可配置并发数
+
+## 安装
+
+```bash
+# 克隆项目
+git clone <repository-url>
+cd hm-doc-new
+
+# 安装依赖
+npm install
+
+# 编译 TypeScript
+npm run build
+
+# 全局链接
+npm link
+```
+
+## 使用方法
+
+### 快速使用
+
+```bash
+# 批量查看所有文档结构，并输出树结构文件
+hm-doc tree
+
+# 批量下载所有文档，并输出概要文件
+hm-doc download
+
+# 使用默认配置生成 Wiki（必须先执行前两条命令）
+hm-doc wiki
+```
+
+### 下载文档
+
+```bash
+# 批量下载（从 docs_catalog.json 配置读取所有 catalog）
+hm-doc download
+
+# 下载指定 catalog
+hm-doc download -c harmonyos-guides
+
+# 下载多个 catalog
+hm-doc download -c harmonyos-guides -c harmonyos-references
+
+# 下载指定节点
+hm-doc download -c harmonyos-guides -n "快速入门"
+
+# 通过 URL 下载单篇文档
+hm-doc download -u "https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-overview"
+
+# 预览目录树（不下载）
+hm-doc download -c harmonyos-guides --dry-run
+
+# 排除 C++ 相关文档
+hm-doc download -c harmonyos-guides --no-cpp
+
+# 只下载叶子节点
+hm-doc download -c harmonyos-guides --leaf-only
+
+# 下载并生成 summary JSON
+hm-doc download -c harmonyos-guides -s
+
+# 下载并本地化链接（将远程链接替换为本地相对路径）
+hm-doc download -c harmonyos-guides -l
+
+# 批量下载 + summary + 链接本地化
+hm-doc download -s -l
+
+# 设置并发数
+hm-doc download -c harmonyos-guides --concurrency 10
+
+# 指定输出目录
+hm-doc download -o ./my-docs
+```
+
+### 查看目录树
+
+```bash
+# 批量查看所有 catalog（从 docs_catalog.json 配置读取）
+hm-doc tree
+
+# 查看指定 catalog
+hm-doc tree -c harmonyos-guides
+
+# 查看指定节点的子树
+hm-doc tree -c harmonyos-guides -n "快速入门"
+
+# 限制显示深度
+hm-doc tree -c harmonyos-guides -d 2
+
+# 导出 JSON 文件
+hm-doc tree -c harmonyos-guides -o ./raw
+```
+
+### 生成 Wiki
+
+```bash
+# 使用默认配置生成 Wiki
+hm-doc wiki
+
+# 指定配置文件
+hm-doc wiki -c ./my-wiki-config.json
+
+# 指定文档目录
+hm-doc wiki -d ./my-docs
+```
+
+## 命令参数
+
+### download 命令
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-c, --catalog <name...>` | catalog 名称，可指定多个 | 批量模式（所有 catalog） |
+| `-n, --node-name <name>` | 目标节点名称 | - |
+| `-i, --node-id <id>` | 目标节点 ID | - |
+| `-u, --url <url>` | 通过 URL 下载单篇文档 | - |
+| `-o, --output <dir>` | 输出目录 | `./docs` |
+| `--leaf-only` | 只下载叶子节点 | `false` |
+| `--no-cpp` | 排除 C++ 相关文档 | - |
+| `--concurrency <n>` | 下载并发数 | `5` |
+| `--dry-run` | 预览目录树，不下载 | `false` |
+| `-s, --summary` | 生成 summary JSON 文件 | `true`（可用 `--no-summary` 禁用） |
+| `-l, --localize` | 将文档中的远程链接替换为本地相对路径 | `false` |
+
+### tree 命令
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-c, --catalog <name>` | catalog 名称 | 批量模式（所有 catalog） |
+| `-n, --node-name <name>` | 目标节点名称 | - |
+| `-i, --node-id <id>` | 目标节点 ID | - |
+| `-d, --depth <n>` | 显示深度限制 | - |
+| `-o, --output <dir>` | JSON 输出目录 | `./docs` |
+| `--no-cpp` | 排除 C++ 相关节点 | - |
+
+### wiki 命令
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-c, --config <path>` | 配置文件路径 | 包内 `wiki_config.json` |
+| `-d, --docs <dir>` | 文档目录路径 | `./docs` |
+
+## 配置文件
+
+### wiki_config.json
+
+Wiki 生成配置，定义 Kit 分类和主题分类。位于项目根目录，打包时会包含在 npm 包内。
+
+```json
+{
+  "kitCategories": {
+    "Network_Kit": {
+      "zh": "网络服务",
+      "desc": "HTTP、WebSocket、Socket、网络管理等"
+    }
+  },
+  "topicCategories": {
+    "network": {
+      "zh": "网络与通信",
+      "desc": "HTTP、Socket、WebSocket、网络管理",
+      "patterns": ["网络", "HTTP", "Socket", "WebSocket"]
+    }
+  }
+}
+```
+
+- `kitCategories`: Kit 分类定义
+  - key: Kit 名称（如 `Network_Kit`）
+  - `zh`: 中文显示名
+  - `desc`: 描述
+- `topicCategories`: 主题分类定义
+  - key: 主题名称（如 `network`）
+  - `zh`: 中文显示名
+  - `desc`: 描述
+  - `patterns`: 匹配模式（用于自动分类文档）
+
+## 开发
+
+```bash
+npm run build    # 编译
+npm run start    # 运行
+```
+
+## 项目结构
+
+```
+src/
+├── index.ts                    # CLI 入口
+├── api-client.ts               # API 请求封装
+├── common/
+│   ├── types.ts                # 共享类型定义
+│   ├── config.ts               # 配置文件加载
+│   ├── tree-processor.ts       # 树结构处理
+│   ├── path-generator.ts       # 路径和任务生成
+│   └── tree-formatter.ts       # 树形文本格式化
+├── download/
+│   ├── index.ts                # Download 命令入口
+│   ├── downloader.ts           # 下载调度
+│   ├── summary-generator.ts    # Summary 生成
+│   ├── link-localizer.ts       # 链接本地化
+│   ├── markdown-converter.ts   # HTML 转 Markdown
+│   └── turndown-rules.ts       # Turndown 规则
+├── tree/
+│   └── index.ts                # Tree 命令入口
+└── wiki/
+    ├── index.ts                # Wiki 命令入口
+    ├── wiki-generator.ts       # Wiki 生成器
+    ├── wiki-types.ts           # Wiki 类型
+    └── wiki-utils.ts           # Wiki 工具函数
+```
+
+## License
+
+Private

package/dist/api-client.d.ts

@@ -0,0 +1,44 @@
+/** 文档内容数据结构 */
+export interface DocumentContent {
+    title: string;
+    html: string;
+    objectId: string;
+    catalogName: string;
+    displayUpdateTime: string;
+}
+/**
+ * 从 URL 中提取 objectId
+ * 策略依次为：查询参数 objectId/id → 路径末尾段 → 倒数第二段
+ * @returns objectId 或 null
+ */
+export declare function objectIdFromUrl(url: string): string | null;
+/**
+ * 从 URL 路径中提取 catalogName（匹配 /doc/<catalogName>/ 模式）
+ * @returns catalogName 或 null
+ */
+export declare function catalogNameFromUrl(url: string): string | null;
+/**
+ * 根据 objectId 获取文档 HTML 内容和元信息
+ * @param objectId - 文档唯一标识
+ * @param language - 语言代码，默认 "cn"
+ * @returns 文档内容（title, html, catalogName, displayUpdateTime）
+ */
+export declare function fetchDocument(objectId: string, language?: string): Promise<DocumentContent>;
+/** 目录树节点（嵌套结构） */
+export interface CatalogNode {
+    nodeId: string;
+    nodeName: string;
+    parent: string | null;
+    relateDocument: string | null;
+    children?: CatalogNode[];
+    isLeaf?: boolean;
+}
+/**
+ * 获取指定 catalog 的目录树（嵌套结构）
+ * @param catalogName - 目录分类名
+ * @param objectId - 可选，指定则返回该节点所在子树
+ * @returns 根节点数组
+ */
+export declare function getCatalogTree(catalogName: string, objectId?: string): Promise<CatalogNode[]>;
+/** 将 UTC 时间字符串转为北京时间 "YYYY-MM-DD HH:mm"，输入为空则返回空串 */
+export declare function formatUpdateTime(utcTimeStr: string): string;

package/dist/api-client.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.objectIdFromUrl = objectIdFromUrl;
+exports.catalogNameFromUrl = catalogNameFromUrl;
+exports.fetchDocument = fetchDocument;
+exports.getCatalogTree = getCatalogTree;
+exports.formatUpdateTime = formatUpdateTime;
+const BASE_URL = "https://svc-drcn.developer.huawei.com/community/servlet";
+const HEADERS = {
+    "Content-Type": "application/json",
+    Referer: "https://developer.huawei.com/consumer/cn/doc/",
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+};
+const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * 向华为文档 API 发送 POST 请求，自动处理超时和错误码校验
+ * @param path - API 路径（不含 BASE_URL）
+ * @param body - 请求体
+ * @returns 响应数据
+ * @throws HTTP 非 2xx 或 API 返回错误码时抛出
+ */
+async function post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await fetch(BASE_URL + path, {
+            method: "POST",
+            headers: HEADERS,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`API request failed: ${res.status} ${res.statusText} for ${path}`);
+        }
+        const data = (await res.json());
+        if (data.code && data.code !== 0 && data.code !== "0") {
+            throw new Error(`API error [${data.code}]: ${data.message} for ${path}`);
+        }
+        return data;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 从 URL 中提取 objectId
+ * 策略依次为：查询参数 objectId/id → 路径末尾段 → 倒数第二段
+ * @returns objectId 或 null
+ */
+function objectIdFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const pathname = parsed.pathname.replace(/\/$/, "");
+        const queryId = parsed.searchParams.get("objectId") || parsed.searchParams.get("id");
+        if (queryId)
+            return queryId;
+        const parts = pathname.split("/");
+        const lastSegment = parts[parts.length - 1];
+        if (lastSegment && lastSegment.length > 2)
+            return lastSegment;
+        if (parts.length >= 2) {
+            const secondLast = parts[parts.length - 2];
+            if (secondLast && secondLast.length > 2)
+                return secondLast;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从 URL 路径中提取 catalogName（匹配 /doc/<catalogName>/ 模式）
+ * @returns catalogName 或 null
+ */
+function catalogNameFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const match = parsed.pathname.match(/\/doc\/([^/]+)/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 根据 objectId 获取文档 HTML 内容和元信息
+ * @param objectId - 文档唯一标识
+ * @param language - 语言代码，默认 "cn"
+ * @returns 文档内容（title, html, catalogName, displayUpdateTime）
+ */
+async function fetchDocument(objectId, language = "cn") {
+    const data = await post("/consumer/cn/documentPortal/getDocumentById", {
+        language,
+        objectId,
+    });
+    const v = data.value;
+    if (!v) {
+        throw new Error(`Empty response for objectId: ${objectId}`);
+    }
+    return {
+        title: v.title ?? "",
+        html: v.content?.content ?? "",
+        objectId,
+        catalogName: v.catalogName ?? "",
+        displayUpdateTime: v.displayUpdateTime ?? "",
+    };
+}
+/**
+ * 获取指定 catalog 的目录树（嵌套结构）
+ * @param catalogName - 目录分类名
+ * @param objectId - 可选，指定则返回该节点所在子树
+ * @returns 根节点数组
+ */
+async function getCatalogTree(catalogName, objectId) {
+    const body = { language: "cn", catalogName };
+    if (objectId)
+        body.objectId = objectId;
+    const data = await post("/consumer/cn/documentPortal/getCatalogTree", body);
+    return data.value?.catalogTreeList ?? [];
+}
+// --- 时间格式化 ---
+/** 将 UTC 时间字符串转为北京时间 "YYYY-MM-DD HH:mm"，输入为空则返回空串 */
+function formatUpdateTime(utcTimeStr) {
+    if (!utcTimeStr)
+        return "";
+    const dt = new Date(utcTimeStr.replace(" ", "T") + "Z");
+    if (isNaN(dt.getTime()))
+        return utcTimeStr;
+    const bj = new Date(dt.getTime() + 8 * 60 * 60 * 1000);
+    const y = bj.getUTCFullYear();
+    const m = String(bj.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(bj.getUTCDate()).padStart(2, "0");
+    const h = String(bj.getUTCHours()).padStart(2, "0");
+    const min = String(bj.getUTCMinutes()).padStart(2, "0");
+    return `${y}-${m}-${d} ${h}:${min}`;
+}

package/dist/common/config.d.ts

@@ -0,0 +1,11 @@
+import type { TopLevelCatalog, CatalogWithTopLevel } from "./types.js";
+/** 加载 docs_catalog.json 配置文件 */
+export declare function loadDocsCatalogConfig(): TopLevelCatalog[];
+/** 根据 catalogName 查找对应的 top_level */
+export declare function findTopLevelForCatalog(catalogName: string): string | undefined;
+/** 根据 catalogName 查找对应的中文名称（name 字段） */
+export declare function findCatalogName(catalogName: string): string | undefined;
+/** 获取配置中所有 catalog 信息（包含 top_level） */
+export declare function getAllCatalogsWithTopLevel(): CatalogWithTopLevel[];
+/** 获取所有已知的 catalog ID 列表 */
+export declare function getAllCatalogIds(): string[];

package/dist/common/config.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDocsCatalogConfig = loadDocsCatalogConfig;
+exports.findTopLevelForCatalog = findTopLevelForCatalog;
+exports.findCatalogName = findCatalogName;
+exports.getAllCatalogsWithTopLevel = getAllCatalogsWithTopLevel;
+exports.getAllCatalogIds = getAllCatalogIds;
+/**
+ * 配置文件加载模块
+ *
+ * 职责：
+ * 1. 加载 docs_catalog.json 配置文件
+ * 2. 根据 catalogName 查找对应的 top_level
+ * 3. 获取所有 catalog 信息（包含 top_level）
+ * 4. 获取 catalog 的中文名称
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** 加载 docs_catalog.json 配置文件 */
+function loadDocsCatalogConfig() {
+    const configPath = (0, node_path_1.join)(__dirname, "..", "..", "docs_catalog.json");
+    const content = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+    return JSON.parse(content);
+}
+/** 根据 catalogName 查找对应的 top_level */
+function findTopLevelForCatalog(catalogName) {
+    const config = loadDocsCatalogConfig();
+    for (const topLevel of config) {
+        for (const catalog of topLevel.catalogs) {
+            if (catalog.id === catalogName) {
+                return topLevel.top_level;
+            }
+        }
+    }
+    return undefined;
+}
+/** 根据 catalogName 查找对应的中文名称（name 字段） */
+function findCatalogName(catalogName) {
+    const config = loadDocsCatalogConfig();
+    for (const topLevel of config) {
+        for (const catalog of topLevel.catalogs) {
+            if (catalog.id === catalogName) {
+                return catalog.name;
+            }
+        }
+    }
+    return undefined;
+}
+/** 获取配置中所有 catalog 信息（包含 top_level） */
+function getAllCatalogsWithTopLevel() {
+    const config = loadDocsCatalogConfig();
+    const result = [];
+    for (const topLevel of config) {
+        for (const catalog of topLevel.catalogs) {
+            result.push({ topLevel: topLevel.top_level, catalog });
+        }
+    }
+    return result;
+}
+/** 获取所有已知的 catalog ID 列表 */
+function getAllCatalogIds() {
+    const config = loadDocsCatalogConfig();
+    const result = [];
+    for (const topLevel of config) {
+        for (const catalog of topLevel.catalogs) {
+            result.push(catalog.id);
+        }
+    }
+    return result;
+}

package/dist/common/path-generator.d.ts

@@ -0,0 +1,39 @@
+import type { FlatNode, OutputTask } from "./types.js";
+/** 将文件/目录名中的非法字符及空格替换为下划线 */
+export declare function safeFileName(name: string): string;
+/**
+ * 计算输出路径并生成下载任务列表
+ *
+ * @param nodes - 全量平铺节点（用于路径计算）
+ * @param rootId - 指定子树根节点 ID，undefined 表示整个 catalog
+ * @param catalogName - catalog 名称
+ * @param outputBase - 输出根目录
+ * @param taskNodes - 需要生成任务的节点子集（如经过 --no-cpp 过滤后的）
+ * @returns 下载任务列表
+ */
+export declare function buildOutputPaths(nodes: FlatNode[], rootId: string | undefined, catalogName: string, outputBase: string, taskNodes?: FlatNode[]): OutputTask[];
+/**
+ * 收集输出所需的全部目录路径（去重、按深度排序）
+ *
+ * @param nodes - 全量平铺节点
+ * @param rootId - 指定子树根节点 ID
+ * @param catalogName - catalog 名称
+ * @param outputBase - 输出根目录
+ * @param taskNodes - 需要创建目录的节点子集
+ * @returns 目录路径数组，按深度从浅到深排序
+ */
+export declare function collectDirectories(nodes: FlatNode[], rootId: string | undefined, catalogName: string, outputBase: string, taskNodes?: FlatNode[]): string[];
+/**
+ * 保存目录树 JSON 文件（参考 fetch_catalog.py）
+ * 输出两个文件：{catalog}_tree.json（原始树结构）和 {catalog}_nodes.json（平铺节点）
+ *
+ * @param catalogName - catalog 名称
+ * @param outputDir - 输出目录路径
+ * @returns 保存的文件路径
+ */
+export declare function saveCatalogJson(catalogName: string, outputDir: string): Promise<{
+    treePath: string;
+    flatPath: string;
+    treeCount: number;
+    flatCount: number;
+}>;