# online-api

**Repository Path**: zhaolandelong/online-api

## Basic Information

- **Project Name**: online-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# online-api

CLI 工具，将在线开发者手册和 API 文档下载为 Markdown 文件，方便本地检索和知识图谱构建。

## 功能

- **HTML → Markdown 转换** — 将网页内容转为结构清晰的 Markdown
- **SPA 渲染** — 通过 Playwright 渲染 JavaScript 重度页面（如飞书帮助中心）
- **图片处理三模式** — 默认替换为 `[image]` 占位符（最快），可选保留原图地址或下载到本地
- **表格支持** — 飞书表格（全 `<td>` 无 `<th>`）正确转为管道式 Markdown
- **代码块** — 自定义代码块结构转为标准 fence 代码块
- **Callout 支持** — 提示/警告/注意事项等 callout 元素转为 blockquote

## 环境要求

- Node.js 18+
- npm

## 安装

```bash
# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium
```

## 使用

### 快速调试（下载单页）

```bash
# 下载一个页面，输出到终端（默认不下载图片，替换为 [image]）
npx tsx debug/debug-md.ts <url>

# 下载到文件
npx tsx debug/debug-md.ts https://project.feishu.cn/b/helpcenter/1p8d7djs/nh4exbsn -o test.md

# 保留原始图片 URL
npx tsx debug/debug-md.ts <url> -o output.md --image-mode url

# 下载图片到本地
npx tsx debug/debug-md.ts <url> -o output.md --image-mode download

# 指定内容选择器
npx tsx debug/debug-md.ts <url> --selector ".doc-content"

# 不使用 Playwright（纯 HTTP 请求）
npx tsx debug/debug-md.ts <url> --no-playwright
```

### CLI 命令（批量下载）

```bash
# 查看可用文档源
npx tsx src/index.ts list

# 下载飞书项目开发者中心（默认输出到 test-docs/，确认后移入 docs/）
npx tsx src/index.ts download feishu-project

# 下载到指定目录
npx tsx src/index.ts download feishu-project -o ./docs

# 下载飞书项目产品手册
npx tsx src/index.ts download feishu-product-manual -o ./test-docs

# 预览页面发现结果（不下载）
npx tsx src/index.ts download feishu-product-manual --dry-run

# 下载图片到本地（默认不下载，加 --image-mode download 开启）
npx tsx src/index.ts download feishu-project --image-mode download

# 保留原始图片地址（不下载）
npx tsx src/index.ts download feishu-project --image-mode url
```

### CLI 命令（单页转换）

```bash
# 默认不下载图片，替换为 [image]
npx tsx src/index.ts convert <url>

# 保留原始图片 URL
npx tsx src/index.ts convert <url> --image-mode url

# 下载图片到本地
npx tsx src/index.ts convert <url> -o output.md --image-mode download

# 不使用 Playwright（纯 HTTP 请求）
npx tsx src/index.ts convert <url> --no-playwright
```

## 目录结构

```
.
├── src/
│   ├── index.ts               # CLI 入口
│   ├── types.ts               # 核心接口定义
│   ├── core/                  # 可复用引擎
│   │   ├── markdown.ts        # HTML → Markdown 转换管线
│   │   ├── browser.ts         # Playwright 生命周期管理
│   │   ├── fetcher.ts         # 混合抓取策略
│   │   ├── cache.ts           # 文件缓存
│   │   ├── writer.ts          # 文件输出
│   │   └── retry.ts           # 指数退避重试
│   └── sources/               # 文档源插件
│       ├── registry.ts        # 插件注册
│       ├── feishu-project/         # 飞书项目帮助中心（开发者手册）
|       └── feishu-product-manual/  # 飞书项目产品手册
├── debug/                     # 调试脚本
│   └── debug-md.ts            # 单页 Markdown 转换
├── tests/                     # 测试
├── test-docs/                 # 首次下载存放目录（审核后移入 docs/）
├── docs/                      # 已确认入库的文档（gitignored）
└── package.json
```

## 工作原理

1. **抓取**：通过 Playwright 渲染 SPA 页面（仅下载图片模式时滚动触发懒加载）
2. **预处理**：处理飞书自定义组件（标题 div、代码块、SVG 占位图、按钮等）
3. **转换**：Turndown + 自定义规则将 HTML 转为 Markdown
4. **后处理**：修复表格缩进、清理空白行
5. **图片处理**：根据 `--image-mode` 参数决定行为
   - `none`（默认）：替换图片为 `[image]` 占位符，最快
   - `url`：保留原始图片 URL 在 markdown 中
   - `download`：下载 CDN 图片到本地（遇到 403/404 自动保留原始 URL）

## 支持的文档源

- **飞书项目帮助中心** (`feishu-project`) — 开发者手册，支持 SPA 渲染、导航树提取、侧边栏目录
- **飞书项目产品手册** (`feishu-product-manual`) — 产品手册，与开发者手册共享同一套 SPA 解析引擎

## License

MIT