HarmonyOS Documentation Downloader

将华为 HarmonyOS 官方文档下载并转换为本地 Markdown 文件的 CLI 工具。

功能特性

• 目录结构同步 - 下载的文档目录层级与华为开发者官网完全一致
• 链接本地化 - 将文档中的远程链接替换为本地相对路径，支持跨 catalog 和锚点保留
• 元数据导出 - 支持导出目录树 JSON 和节点平铺列表
• 文档概要生成 - 自动提取摘要，生成 summary JSON 索引
• Wiki 生成 - 从下载的文档生成 Wiki 文件
• 多 catalog 支持（指南、API 参考、最佳实践、FAQ 等）
• HTML 转 Markdown，保留代码块、表格、链接等格式
• 并发下载，可配置并发数

安装

# 克隆项目
git clone <repository-url>
cd hm-doc-new

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 全局链接
npm link

使用方法

快速使用

# 批量查看所有文档结构，并输出树结构文件
hm-doc tree

# 批量下载所有文档，并输出概要文件
hm-doc download

# 使用默认配置生成 Wiki（必须先执行前两条命令）
hm-doc wiki

下载文档

# 批量下载（从 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

查看目录树

# 批量查看所有 catalog（从 docs_catalog.json 配置读取）
hm-doc tree

# 查看指定 catalog
hm-doc tree -c harmonyos-guides

# 查看多个 catalog
hm-doc tree -c harmonyos-guides -c atomic-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

# 使用默认配置生成 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 包内。

{
  "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: 匹配模式（用于自动分类文档）

开发

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