123 lines
4.2 KiB
Markdown
123 lines
4.2 KiB
Markdown
# baoyu-fetch
|
||
|
||
[English](./README.md) | 简体中文 | [更新日志](./CHANGELOG.zh-CN.md) | [English Changelog](./CHANGELOG.md)
|
||
|
||
`baoyu-fetch` 是一个基于 Chrome CDP 的 Bun CLI。输入 URL，它会输出高质量
|
||
`markdown` 或 `json`；命中站点 adapter 时优先消费 API 返回或页面内结构化
|
||
数据，未命中时回退到通用 HTML 提取。
|
||
|
||
## 当前能力
|
||
|
||
- 通过 Chrome CDP 抓取渲染后的页面内容
|
||
- 监听网络请求与响应，按需拉取响应体
|
||
- adapter registry，支持按 URL 自动命中站点处理器
|
||
- 内置 `x`、`youtube`、`hn` adapters
|
||
- 通用 fallback：Defuddle 优先，Readability + HTML to Markdown 回退；`--format markdown` 时会再尝试 `defuddle.md` 兜底
|
||
- `stdout` 或 `--output` 输出 `markdown` / `json`
|
||
- 可选下载提取出的图片/视频并重写 Markdown 链接
|
||
- 提供登录/验证场景下的交互等待模式
|
||
- Chrome profile 默认对齐 `baoyu-skills/chrome-profile`
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
作为包使用时，推荐直接这样运行：
|
||
|
||
```bash
|
||
bunx baoyu-fetch https://example.com
|
||
```
|
||
|
||
也可以全局安装：
|
||
|
||
```bash
|
||
npm install -g baoyu-fetch
|
||
```
|
||
|
||
npm 包发布的是 TypeScript 源码入口，不包含预编译的 `dist`，所以运行时需要
|
||
Bun。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
bun run src/cli.ts https://example.com
|
||
bunx baoyu-fetch https://example.com
|
||
baoyu-fetch https://example.com
|
||
baoyu-fetch https://example.com --format markdown --output article.md
|
||
baoyu-fetch https://example.com --format markdown --output article.md --download-media
|
||
baoyu-fetch https://x.com/jack/status/20 --format json --output article.json
|
||
baoyu-fetch https://x.com/jack/status/20 --json
|
||
baoyu-fetch https://x.com/jack/status/20 --wait-for interaction
|
||
baoyu-fetch https://x.com/jack/status/20 --wait-for force
|
||
baoyu-fetch https://x.com/jack/status/20 --chrome-profile-dir ~/Library/Application\\ Support/baoyu-skills/chrome-profile
|
||
```
|
||
|
||
## 主要参数
|
||
|
||
```bash
|
||
baoyu-fetch <url> [options]
|
||
|
||
Options:
|
||
--output <file> 保存输出内容到文件
|
||
--format <type> 输出格式：markdown | json
|
||
--json `--format json` 的兼容别名
|
||
--adapter <name> 强制使用指定 adapter（如 x / hn / generic）
|
||
--download-media 下载 adapter 返回的媒体到 ./imgs 和 ./videos，并重写 markdown 链接
|
||
--media-dir <dir> 指定媒体下载根目录；默认使用输出文件所在目录
|
||
--debug-dir <dir> 导出调试信息（html、document.json、network.json）
|
||
--cdp-url <url> 连接现有 Chrome 调试地址
|
||
--browser-path <path> 指定 Chrome 可执行文件
|
||
--chrome-profile-dir <path>
|
||
指定 Chrome profile 目录。默认使用 BAOYU_CHROME_PROFILE_DIR，
|
||
否则回退到 baoyu-skills/chrome-profile
|
||
--headless 启动临时 headless Chrome（未连现有实例时）
|
||
--wait-for <mode> 等待模式：interaction | force
|
||
--wait-for-interaction
|
||
`--wait-for interaction` 的别名
|
||
--wait-for-login `--wait-for interaction` 的别名
|
||
--interaction-timeout <ms>
|
||
手动交互等待超时，默认 600000
|
||
--interaction-poll-interval <ms>
|
||
等待期间的轮询间隔，默认 1500
|
||
--login-timeout <ms> `--interaction-timeout` 的别名
|
||
--login-poll-interval <ms>
|
||
`--interaction-poll-interval` 的别名
|
||
--timeout <ms> 页面加载超时，默认 30000
|
||
--help 显示帮助
|
||
```
|
||
|
||
## 设计
|
||
|
||
核心链路：
|
||
|
||
1. CLI 解析 URL 和选项
|
||
2. 建立 CDP 会话并创建受控 tab
|
||
3. 启动 `NetworkJournal` 收集所有请求/响应
|
||
4. 由 adapter registry 匹配站点 adapter
|
||
5. adapter 返回结构化 `ExtractedDocument`
|
||
6. 没命中则走通用 HTML 提取
|
||
7. 按请求输出 Markdown，或输出包含 `document` 和 `markdown` 的 JSON
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
bun run check
|
||
bun run test
|
||
bun run build
|
||
```
|
||
|
||
## 发版
|
||
|
||
新增用户可见改动后，先添加一个 changeset：
|
||
|
||
```bash
|
||
bunx changeset
|
||
```
|
||
|
||
把生成的 `.changeset/*.md` 一起合并到 `main` 后，GitHub Actions 会自动创建或
|
||
更新 release PR；合并 release PR 之后，会自动发布到 npm。
|
||
|
||
发布流程不会编译 `dist`，而是直接把 `src/*.ts` 发布出去供 Bun 执行。
|