Solo-Doc CLI

Solo-Doc 是一个强大的 Node.js CLI 工具，旨在爬取复杂的文档站点并将其转换为单一的、保留层级结构的 Markdown 文件。

命名由来："Solo" 代表将多个文档页面整合为“单一”（solo）文件的能力，"Doc" 代表文档。

✨ 功能特性

• 🧠 智能探测:
  • 自动策略识别: 根据 URL 自动检测文档类型（Red Hat OpenShift 或 Alauda）。
  • 自动命名: 基于文档路径智能生成输出文件名（例如 acp-building_application.md），无需手动指定。
• 🏗 多策略支持: 针对不同文档框架的专用策略：
  • OCP (Red Hat OpenShift): 针对静态单页 HTML 文档进行了优化。
  • ACP (Alauda Container Platform): 针对使用 Puppeteer 的动态客户端渲染（基于 Rspress）文档进行了优化。
• 🌲 保持层级结构: 完整保留文档的原始目录结构（1, 1.1, 1.1.1...）。
• ✨ 纯净输出: 移除导航栏、侧边栏、页眉和页脚，仅保留核心内容。
• 📄 单文件输出: 将所有爬取的页面合并为一个完整的 Markdown 文件。

📦 安装

通过 NPM 安装（推荐）

你可以全局安装此工具：

npm install -g solo-doc

🚀 使用指南

全局安装后，你可以在任何终端窗口运行 solo-doc 命令。

基础用法（自动探测）

只需提供 URL。Solo-Doc 会自动识别站点类型并生成有意义的文件名。

# 爬取 Alauda 文档
# 输出文件: acp-building_application.md
solo-doc "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html"

# 爬取 Red Hat 文档
# 输出文件: ocp-building_applications.md
solo-doc "https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/building_applications/index"

🔗 多地址聚合 (Multi-URL Aggregation)

支持一次性爬取多个 URL 并将其合并为一个 Markdown 文件。多个地址之间使用逗号分隔。

# 爬取多个 URL 并合并
# 将依次爬取 url1 和 url2，合并输出到 combined.md
solo-doc "https://url1/...,https://url2/..." -o combined.md

📝 自定义输出文件名

使用 -o 参数指定自定义输出路径。

solo-doc "https://docs.alauda.io/..." -o my-manual.md

🔧 强制指定策略类型

如果 URL 无法被自动识别（例如私有 IP 或自定义域名），你可以使用 --type 强制指定策略。

# 针对私有部署强制使用 ACP 策略
solo-doc "http://10.1.2.3/docs/index.html" --type acp

⚙️ 选项参数

| 选项 | 描述 | 默认值 | |--------|-------------|---------| | <url> | 要爬取的文档 URL | (必填) | | -o, --output <path> | 输出文件路径。如果省略，将根据 URL 自动生成文件名。 | [type]-[path-segment].md | | -t, --type <type> | 强制指定策略类型 (ocp 或 acp)。 | 自动探测 | | --limit <number> | 限制爬取的页面数量 (用于测试/调试)。 | 无限制 | | --no-headless | 在可见模式下运行浏览器 (仅限 ACP，用于调试)。 | Headless (无头模式) |

🧪 实验性功能 (Beta)

🤖 文档对比 (AI VS 模式)

使用 AI 模型对比两个文档的内容差异和结构差异。此功能处于 Beta 阶段。

⚠️ 前置要求:

1. 需要在项目根目录或用户主目录下创建 .solodocrc.yml 配置文件。
2. 配置兼容 OpenAI 接口的 AI 服务（支持Azure OpenAI、DeepSeek 等）。

⚙️ AI 配置 (.solodocrc.yml)

在执行对比命令前，请创建 .solodocrc.yml 文件配置 AI 服务。

示例: 使用 Azure OpenAI

# 系统会自动识别 Azure 格式并处理 api-version
MODEL_BASE_URL: "https://your-resource.openai.azure.com/2024-12-01-preview"
MODEL_API_KEY: "your-azure-api-key"
MODEL_NAME: "gpt-4o-mini"

用法

solo-doc vs <baseline-url> <target-url> [options]

示例

# 对比 OpenShift 和 Alauda 的文档
# 将使用 .solodocrc.yml 中的默认模型
solo-doc vs \
  "https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/building_applications/index" \
  "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html"

# 临时覆盖使用的模型
solo-doc vs <url1> <url2>

📂 本地文件与多源聚合

VS 模式支持直接使用本地 Markdown 文件进行对比，无需重复爬取。同时也支持将多个源（URL 或本地文件）聚合后再进行对比。

# 1. 对比多个在线文档 (聚合对比)
# 场景：将 v1.0 的多个模块文档聚合，与 v2.0 的对应模块进行对比
solo-doc vs \
  "https://docs.site/v1/module-a,https://docs.site/v1/module-b" \
  "https://docs.site/v2/module-a,https://docs.site/v2/module-b"

# 2. 对比本地文件与在线文档
solo-doc vs ./local-draft.md "https://docs.prod.com/..."

# 3. 多文件聚合对比
# 将 part1.md 和 part2.md 合并作为基准，与 target.md 对比
solo-doc vs ./part1.md,./part2.md ./target.md

# 4. 混合使用 (URL + 本地文件)
solo-doc vs ./intro.md,"https://docs.site/chapter1" ./v2-draft.md

此命令将按顺序执行：

1. 数据准备:

   • 如果是 URL：自动爬取并保存为 Markdown。
   • 如果是本地文件：直接读取内容。
   • 如果是多个源：按顺序合并为一个聚合文件。

2. 提取目录: 提取两个文档的目录树结构。

3. AI 分析: 调用配置的 AI 模型，根据 solo-doc-prompt.md 定义的提示词进行两步分析：

   提示: solo-doc 会优先使用当前执行目录下的 solo-doc-prompt.md 文件。你可以复制默认模板到当前目录进行自定义修改。若当前目录不存在该文件，则使用内置默认模板。

   • 生成 vs-result.md: 详细的内容与结构差异分析。
   • 生成 vs-tree.md: 包含差异标注的合并目录树。

VS 模式选项

| 选项 | 描述 | 默认值 | |--------|-------------|---------| | -f, --force | 强制重新爬取文档，即使文件已存在。 | false |

✅ 环境要求

• Node.js >= 20
• Google Chrome (用于 ACP 爬取)

💻 开发

# 在开发模式下运行
npm run dev -- "https://docs.alauda.io/..."