Thunderbit Open API home page
支持API 控制台
开始使用

Skills + CLI

在终端中运行 Thunderbit —— 把网页蒸馏成 Markdown、提取结构化数据、推荐字段，以及批量处理最多 100 个 URL。CLI 既可独立使用，也可作为 AI 编码 Agent 能发现的 skills 工具集。

直接从终端进行蒸馏、提取、字段推荐和批量任务。

安装

CLI 在 npm 上发布为 @thunderbit/thunderbit-cli，并在你的 PATH 中暴露 thunderbit 二进制。

# Install globally
npm install -g @thunderbit/thunderbit-cli

# Or run one-shot via npx
npx -y @thunderbit/thunderbit-cli --help

同款命令面的 Python 版本（pip install thunderbit）已在路线图上。

认证

使用 CLI 之前，你需要用 Thunderbit API key 完成认证。在 app.thunderbit.com/console 获取 key。格式：tb_ 后跟 32 位十六进制字符。

通过环境变量设置

export THUNDERBIT_API_KEY=tb_YOUR_API_KEY

单次命令传入

thunderbit --api-key tb_YOUR_API_KEY distill https://example.com

自托管 / 本地开发

对自托管的 Thunderbit 网关，请覆盖 base URL：

# Per call
thunderbit --base-url https://api.your-domain.com distill https://example.com

# Or set via environment variable
export THUNDERBIT_API_BASE_URL=https://api.your-domain.com
thunderbit distill https://example.com

查看版本

thunderbit --version
# or
thunderbit -V

全局选项

以下 flag 适用于所有命令：

选项说明
--api-key <key>, -kAPI key（或设置 THUNDERBIT_API_KEY）
--base-url <url>API base URL（或设置 THUNDERBIT_API_BASE_URL）
--format <format>, -f输出格式：json、table 或 markdown（默认 json）
--version, -V打印 CLI 版本
--help, -h显示命令帮助

命令

Distill

把单个 URL 蒸馏成干净、对 LLM 友好的 Markdown。

# Basic usage
thunderbit distill https://example.com/article

# Stream Markdown to stdout
thunderbit distill https://example.com --format markdown

# Save to file
thunderbit distill https://example.com --format markdown > article.md

Distill 选项

# Use the basic JS renderer (covers most modern sites)
thunderbit distill https://example.com --render-mode basic

# Use the full headless browser (slowest, highest fidelity)
thunderbit distill https://example.com --render-mode full

# Geo-target for region-aware sites
thunderbit distill https://example.com --country-code DE

# Bump per-page timeout
thunderbit distill https://example.com --timeout 60000

# Use sync /distill instead of the default async submit + poll
thunderbit distill https://example.com --sync

可用选项：

选项默认值说明
--render-mode <mode>nonenone、basic 或 full
--timeout <ms>30000每页请求超时（毫秒）
--country-code <CC>USISO 两位国家码，大写
--syncfalse使用同步模式而非默认的异步提交 + 轮询

Extract

从网页提取结构化数据。schema 是 字段名 → 自然语言指令 的扁平映射 —— 每个值都是 AI 在页面上定位该字段的提示。

说明：上游 OpenAPI 规范示例展示的是 JSON Schema ({type:"object",properties:…})。撰写本文时线上服务器期望下面所示的扁平指令映射，我们正在对齐规范。

# 内联 schema —— 字段 → 指令的扁平映射
thunderbit extract https://example.com/product \
  --schema '{"name":"product name","price":"the listed price as a number","currency":"3-letter currency code"}'

# 从文件读取 schema
thunderbit extract https://example.com/product --schema ./schema.json

# 保存提取的 JSON
thunderbit extract https://example.com/product --schema ./schema.json --format json -o data.json

响应始终把 data.data 作为数组返回，与 schema 匹配的每个页面区域对应一个元素：

{
  "success": true,
  "data": {
    "url": "https://example.com/product",
    "data": [
      { "name": "iPhone 15 Pro", "price": 999, "currency": "USD" }
    ]
  }
}

交互模式

# AI proposes fields, you toggle/edit, then extraction runs with the curated schema
thunderbit extract https://example.com/product --interactive

# Steer the suggestion with a prompt
thunderbit extract https://example.com/product -i --prompt "focus on pricing and availability"

# Persist the schema for reuse
thunderbit extract https://example.com/product -i --save-schema ./product-schema.json

Extract 选项

# Bump page-render time for SPAs
thunderbit extract https://example.com --schema ./schema.json --render-mode full

# Sync mode
thunderbit extract https://example.com --schema ./schema.json --sync

# Longer timeout for complex pages
thunderbit extract https://example.com --schema ./schema.json --timeout 120000

可用选项：

选项默认值说明
--schema <json-or-file>—内联 JSON 或 schema 文件路径
--interactive, -ifalse一气呵成完成 推荐 → 整理 → 提取
--prompt <text>—用于 AI 推荐的引导提示（配合 -i）
--render-mode <mode>nonenone、basic 或 full
--timeout <ms>60000每页请求超时（毫秒）
--syncfalse同步模式
--save-schema <file>—保存最终 schema 以便复用

Suggest Fields

在你写 schema 之前，先让 AI 推荐可提取字段。

# Basic
thunderbit suggest-fields https://example.com/product

# Steer with a prompt
thunderbit suggest-fields https://example.com/listings --prompt "extract job postings only"

# Region-aware
thunderbit suggest-fields https://example.com --country-code DE

交互式编辑器允许你按编号切换字段（1 3 5）、add、rm 2、edit 4，然后输入 done 确认。suggest-fields 返回 [{name, type, instruction}, …]；当你把它喂给 extract 时，先转成扁平映射：

thunderbit suggest-fields "$URL" --format json \
  | jq 'map({(.name): .instruction}) | add' > schema.json

thunderbit extract "$URL" --schema ./schema.json

可用选项：

选项默认值说明
--prompt <text>—引导提示
--country-code <CC>USISO 两位国家码

Batch Distill

在一次批量任务中提交最多 100 个 URL。默认会提交并轮询，直到 COMPLETED / FAILED / CANCELLED。

# URLs as positional args
thunderbit batch distill https://a.com https://b.com https://c.com

# Or read URLs from a file (one per line)
thunderbit batch distill --file urls.txt

# Submit only — print the job ID and exit (use webhook or poll later)
thunderbit batch distill --file urls.txt --no-poll

Batch Distill 选项

# Bump per-page timeout
thunderbit batch distill --file urls.txt --timeout 60000

# Pipe results into another tool
thunderbit batch distill --file urls.txt --format json \
  | jq -r '.data.results[] | select(.success == true) | .markdown' \
  > distilled.md

可用选项：

选项默认值说明
--file <path>—从文件读取 URL（每行一个）
--timeout <ms>30000每页请求超时（毫秒）
--no-pollfalse仅提交，打印 job ID 并退出

取消正在运行的批量 distill 任务

thunderbit batch cancel-distill <jobId>

已完成的页面会保留结果。待处理的页面会被丢弃，对应部分不再计费。服务端确认后，状态会变为 CANCELLED。

Batch Extract

提交最多 100 个 URL，使用一份共享 schema。

# URLs as positional args + inline schema
thunderbit batch extract https://a.com https://b.com \
  --schema ./schema.json

# Read URLs from a file
thunderbit batch extract --file urls.txt --schema ./schema.json

# Submit only
thunderbit batch extract --file urls.txt --schema ./schema.json --no-poll

可用选项：

选项默认值说明
--file <path>—从文件读取 URL（每行一个）
--schema <json-or-file>—内联 JSON 或 schema 文件（必填）
--timeout <ms>60000每页请求超时（毫秒）
--no-pollfalse仅提交，打印 job ID 并退出

取消正在运行的批量 extract 任务

thunderbit batch cancel-extract <jobId>

语义与 cancel-distill 相同——已完成的行会被保留，待处理的行会被丢弃，剩余部分不再计费。

输出处理

CLI 默认输出到 stdout，方便你用管道或重定向。

# Pipe Markdown into another tool
thunderbit distill https://example.com --format markdown | head -50

# Redirect to a file
thunderbit distill https://example.com --format markdown > output.md

# Save extraction JSON
thunderbit extract https://example.com --schema ./schema.json --format json > data.json

格式行为

  • --format json（默认）：完整 API 响应作为紧凑 JSON 输出，包括 success、data、creditsUsed 等。可以接 jq。
  • --format markdown：distill 输出原始 Markdown 正文；其他命令输出完整 JSON。
  • --format table：表格化结果（extract、suggest-fields）以 ASCII 表格输出。
# Markdown body straight to disk
thunderbit distill https://example.com --format markdown

# Full structured response
thunderbit distill https://example.com --format json

示例

快速 Distill

# Distill an article
thunderbit distill https://docs.thunderbit.com/introduction --format markdown

# Save HTML-converted Markdown to disk
thunderbit distill https://example.com --format markdown -o page.md

批量 RAG 数据导入

# Distill a docs site listed in urls.txt and write each page to disk
thunderbit batch distill --file urls.txt --format json \
  | jq -r '.data.results[] | select(.success == true) | "\(.url)\t\(.markdown)"' \
  > corpus.tsv

先发现再提取

# Step 1: AI proposes fields, you curate, schema saved to disk
thunderbit extract https://example.com/product -i --save-schema ./schema.json

# Step 2: re-use across the catalog
thunderbit batch extract --file urls.txt --schema ./schema.json --format json > products.json

CI 检查门 —— 提取结果为空就失败

thunderbit extract "$URL" --schema ./schema.json --format json \
  | jq -e '.data | length > 0'

与其他工具组合

# Extract URLs from a search-result JSON
thunderbit distill https://example.com --format json \
  | jq -r '.data.metadata.canonicalUrl'

# Pipe distilled content into a model for summarisation
thunderbit distill "$URL" --format markdown \
  | claude -p "summarise the article in 5 bullets"

# Count successful pages in a batch
thunderbit batch distill --file urls.txt --format json \
  | jq '[.data.results[] | select(.success == true)] | length'

退出码

码含义
0成功。结果按 --format 选择的格式打印到 stdout。
1任意失败 —— API key 缺失、认证错误、HTTP 4xx/5xx、网络错误、schema 文件缺失、必需参数缺失。

所有错误文本都写入 stderr。失败时 stdout 保持为空（即使带 --format json 也是如此）。这意味着 jq 管道永远不会拿到半成品的 envelope —— 解析前请先检查退出码（或用 set -e）。

轮询进度（例如 async submit + poll 输出的 Processing... (3)）也写入 stderr。用 2>/dev/null 静音它。单页同步调用（--sync）不会输出进度。

故障排查

Error: API key is required。 请 export THUNDERBIT_API_KEY 或传入 --api-key。

企业代理后的网络错误。 设置 HTTPS_PROXY 和 HTTP_PROXY —— Node 与 Python 客户端都会读取它们。

批量轮询很慢。 把 --timeout 调高，控制每页预算。轮询节奏本身固定为几秒一次，目前 CLI 不能配置。

开源

Thunderbit CLI 采用 MIT 协议开源，仓库在 GitHub：thunderbit-open/thunderbit-mcp-server（同一仓库还包含 MCP server 与 Claude Code 插件）。npm 包：@thunderbit/thunderbit-cli。

相关链接

  • MCP Server —— 同样的能力，以 MCP 工具形式暴露
  • SDKs —— 在你自己的代码中调用
  • API Reference —— 原生 HTTP

目录

安装认证通过环境变量设置单次命令传入自托管 / 本地开发查看版本全局选项命令DistillDistill 选项Extract交互模式Extract 选项Suggest FieldsBatch DistillBatch Distill 选项取消正在运行的批量 distill 任务Batch Extract取消正在运行的批量 extract 任务输出处理格式行为示例快速 Distill批量 RAG 数据导入先发现再提取CI 检查门 —— 提取结果为空就失败与其他工具组合退出码故障排查开源相关链接