整站文字抓取 API

从一个网址开始，沿站内链接抓取多个页面的正文文字（后台任务）；遵守 robots.txt 与 Crawl-delay，单站串行、至少间隔 500ms，只抓 HTML

数据来源：目标网站

返回统一的 JSON 格式 { code, message, cached, stale, updatedAt, data }，支持跨域，免注册每天可免费调用 100 次，注册后每天 10000 次。

创建整站文字抓取任务，返回 taskId

POST /api/crawl

请求参数

• url（必填）：起始网址（http / https），只允许公网地址，示例 https://example.com
• max_pages：最多抓取的页面数：未登录 1~20，登录后 1~50（管理员可在系统设置里调低上限），示例 10
• max_depth：链接深度 0~10：0 只抓起始页，1 再抓起始页上的链接，以此类推，示例 2
• scope：site 同一站点（同域名，www 与否视为同一站点）；path 只抓起始网址所在目录下的页面，示例 path
• mode：main 尽量只保留正文；all 提取全部可见文字，示例 all

返回字段

• taskId（string）：任务 ID（随机 UUID，不可猜测），用于 /api/crawl/result 查询
• status（string）：任务状态：running 抓取中 / done 已完成 / failed 失败
• startUrl（string）：起始网址（规范化后）
• options（object）：本次任务实际使用的参数
• options.maxPages（number）：最多抓取的页面数（含抓取失败的页面，不含跳过的）
• options.maxDepth（number）：最大链接深度（0 只抓起始页）
• options.scope（string）：抓取范围：site 同一站点 / path 起始网址所在目录
• options.mode（string）：文字提取模式：main 只保留正文 / all 全部可见文字
• createdAt（string）：创建时间（ISO 8601）
• expiresAt（string）：结果过期时间（ISO 8601）：任务结束后保留 30 分钟，运行中为创建后 30 分钟（结束时顺延）

查询抓取任务的进度与分页结果（不计调用次数）

GET /api/crawl/result

请求参数

• task_id（必填）：/api/crawl 返回的 taskId，示例 3f2b8c1e-6a7d-4e59-9b1a-0c2d4e6f8a9b
• offset：从第几个页面开始返回（0 起），示例 0
• limit：本次最多返回的页面数，1~50，示例 10
• include_text：是否返回每个页面的文字：true / false（只看进度时设为 false），示例 false

返回字段

• taskId（string）：任务 ID（随机 UUID，不可猜测），用于 /api/crawl/result 查询
• status（string）：任务状态：running 抓取中 / done 已完成 / failed 失败
• startUrl（string）：起始网址（规范化后）
• options（object）：本次任务实际使用的参数
• options.maxPages（number）：最多抓取的页面数（含抓取失败的页面，不含跳过的）
• options.maxDepth（number）：最大链接深度（0 只抓起始页）
• options.scope（string）：抓取范围：site 同一站点 / path 起始网址所在目录
• options.mode（string）：文字提取模式：main 只保留正文 / all 全部可见文字
• createdAt（string）：创建时间（ISO 8601）
• expiresAt（string）：结果过期时间（ISO 8601）：任务结束后保留 30 分钟，运行中为创建后 30 分钟（结束时顺延）
• finishedAt（string|null）：结束时间（ISO 8601）；运行中为 null
• error（string|null）：任务失败的原因（如起始网址指向内网、robots.txt 无法读取）；未失败时为 null
• note（string|null）：补充说明（如起始页被 robots.txt 禁止、超过总文字量提前结束）；没有时为 null
• progress（object）：进度
• progress.crawled（number）：已抓取的页面数（= success + failed）
• progress.success（number）：成功提取文字的页面数
• progress.failed（number）：抓取失败的页面数（4xx / 5xx / 连接失败 / 超时）
• progress.skipped（number）：跳过的链接数（robots.txt 禁止、非 HTML、跳转到站外、指向内网、图片 / PDF 等文件）
• progress.queued（number）：队列中尚未处理的链接数
• progress.maxPages（number）：页面数上限
• truncated（boolean）：是否因文字总量超过 500 万字符而提前结束
• totalChars（number）：已保存的文字总字符数
• total（number）：已抓取的页面总数（分页用）
• offset（number）：本次返回的起始位置
• limit（number）：本次最多返回的页面数
• pages（array）：页面列表，按抓取顺序（广度优先）
• pages[].url（string）：页面网址（跟随站内跳转后的地址）
• pages[].depth（number）：链接深度（起始页为 0）
• pages[].status（number|null）：HTTP 状态码；连接失败、超时时为 null
• pages[].title（string|null）：页面标题；失败或没有标题时为 null