dsh-scrape 0.0.1 → 0.1.0

package/lib/index.mjs

@@ -0,0 +1,15 @@
+/**
+ * 公开 API：插件、CLI 和别的程序都从这里（或直接 import 对应子模块）取能力。
+ * 拆成小文件是为了「想只用一段就只 import 一段」，不是为了好看。
+ */
+
+export { scrape, scrapeHtml, scrapeMany, detectSpa, resolveRobots, warning, VERSION, TOOL_NAME, DEFAULTS, LIMITATIONS } from './scrape.mjs'
+export { parseHtml, tokenizeHtml, parseAttrs, renderInline, detectSpaSignals, collapseWhitespace, stripInline, noiseKindOf, resolveUrl } from './html.mjs'
+export { selectMain, blockLength, linkRatio, isBoilerplate, bestRun, EXTRACT_VERSION, MIN_MAIN_CHARS } from './extract.mjs'
+export { renderMarkdown, textLinesToMarkdown, blockToMarkdown, lineRef, summaryLine } from './markdown.mjs'
+export { parseRobots, checkAllowance, matchingGroups, pathMatches, describeAllowance, pathOf, originOf, BOT_TOKEN } from './robots.mjs'
+export { fetchPage, fetchOptional, decodeBuffer, sniffCharset, charsetFromContentType, assertFetchableUrl, DEFAULT_USER_AGENT } from './net.mjs'
+export { createThrottle, hostKey, DEFAULT_MIN_INTERVAL_MS } from './limit.mjs'
+export { decodeEntities, hasEntities, NAMED_ENTITIES } from './entities.mjs'
+export { ScrapeError, classifyFetchError, httpStatusError, describeError } from './errors.mjs'
+export { renderText, renderJson, renderRemoved, humanBytes, padDisplay } from './format.mjs'

package/lib/limit.mjs

@@ -0,0 +1,120 @@
+/**
+ * 抓取限速：同一个域名「不并发、不猛打」。
+ *
+ * 规则只有两条，但都是硬规则：
+ * 1) **同域串行**——上一个请求的响应体读完之前，不发下一个（不并发）；
+ * 2) **同域最小间隔**——两次请求的发出时间至少隔 `minIntervalMs`（默认 500ms）；
+ *    如果 robots.txt 声明了 `Crawl-delay`，取两者更大者。
+ *
+ * 不同域名互不影响（各走各的队列），所以批量抓多个站点不会被串成一条长队。
+ * 这是「礼貌抓取」的工程底线：并发猛打是被封的最快方式，也会烧掉用户的 IP 招牌。
+ */
+
+/** 默认同域最小间隔（毫秒）。 */
+export const DEFAULT_MIN_INTERVAL_MS = 500
+
+/**
+ * 睡一会儿。
+ * @param {number} ms 毫秒
+ * @returns {Promise<void>} 完成后解析
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 取 URL 的主机键（同主机不同端口视为同一站点，因为限速关心的是对方服务器）。
+ * @param {string} url 任意 URL
+ * @returns {string} 主机名（小写）
+ */
+export function hostKey(url) {
+  try {
+    return new URL(url).hostname.toLowerCase()
+  } catch {
+    return String(url)
+  }
+}
+
+/**
+ * 造一个与实例绑定的限速器。
+ * @param {{minIntervalMs?:number,maxPerHost?:number}} [options] 选项
+ * @returns {{acquire:(url:string)=>Promise<{release:()=>void}>,stats:()=>object,minIntervalMs:number,setHostInterval:(host:string,ms:number)=>void}} 限速器
+ */
+export function createThrottle(options = {}) {
+  const defaultInterval = Math.max(0, options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS)
+  /** @type {Map<string,{tail:Promise<void>,lastStart:number,requests:number,waitedMs:number,interval:number}>} */
+  const hosts = new Map()
+
+  /**
+   * 取（或建）某主机的队列状态。
+   * @param {string} host 主机键
+   * @returns {object} 队列状态
+   */
+  const stateOf = (host) => {
+    let state = hosts.get(host)
+    if (!state) {
+      state = { tail: Promise.resolve(), lastStart: 0, requests: 0, waitedMs: 0, interval: defaultInterval }
+      hosts.set(host, state)
+    }
+    return state
+  }
+
+  return {
+    minIntervalMs: defaultInterval,
+
+    /**
+     * 为 robots.txt 的 Crawl-delay 抬高某主机的间隔（只升不降）。
+     * @param {string} host 主机键
+     * @param {number} ms 间隔毫秒
+     * @returns {void}
+     */
+    setHostInterval(host, ms) {
+      if (!Number.isFinite(ms) || ms <= 0) return
+      const state = stateOf(host)
+      state.interval = Math.max(state.interval, Math.round(ms))
+    },
+
+    /**
+     * 排队拿到一次请求许可。用完后必须 `release()`（放在 finally 里）。
+     * @param {string} url 目标 URL
+     * @returns {Promise<{release:()=>void}>} 许可凭据
+     */
+    async acquire(url) {
+      const host = hostKey(url)
+      const state = stateOf(host)
+      const previous = state.tail
+      let finish
+      state.tail = new Promise((resolve) => { finish = resolve })
+
+      await previous
+      const wait = state.lastStart + state.interval - Date.now()
+      if (wait > 0) {
+        state.waitedMs += wait
+        await sleep(wait)
+      }
+      state.lastStart = Date.now()
+      state.requests += 1
+
+      let released = false
+      return {
+        release() {
+          if (released) return
+          released = true
+          finish()
+        },
+      }
+    },
+
+    /**
+     * 每个主机抓了几次、一共等了多久（用于报告与自测）。
+     * @returns {object} 统计
+     */
+    stats() {
+      const out = {}
+      for (const [host, state] of hosts) {
+        out[host] = { requests: state.requests, waitedMs: state.waitedMs, intervalMs: state.interval }
+      }
+      return out
+    },
+  }
+}

package/lib/markdown.mjs

@@ -0,0 +1,161 @@
+/**
+ * 把结构化块渲染成 Markdown，并让每一块都能回指源行号。
+ *
+ * 行号标注用 HTML 注释（`<!-- L42 -->`）：渲染出来看不见，但被下游模型读到、
+ * 被 grep 到，于是「这句话来自原页第 42 行」是可验证的，而不是凭记忆说的。
+ * 想要一份没有注释的干净 Markdown，把 `lineRefs` 关掉即可。
+ */
+
+import { stripInline } from './html.mjs'
+
+/**
+ * 生成一条行号标注。
+ * @param {number} start 起始行（1 基）
+ * @param {number} end 结束行（1 基，等于起始行时省略）
+ * @returns {string} 注释行
+ */
+export function lineRef(start, end) {
+  const from = Math.max(1, Number(start) || 1)
+  const to = Math.max(from, Number(end) || from)
+  return to > from ? `<!-- L${from}-${to} -->` : `<!-- L${from} -->`
+}
+
+/**
+ * 转义表格单元格里的竖线（否则会把表格结构冲掉）。
+ * @param {string} text 单元格文本
+ * @returns {string} 转义后的文本
+ */
+function escapeCell(text) {
+  return String(text ?? '').replace(/\|/g, '\\|').replace(/\n+/g, ' ').trim()
+}
+
+/**
+ * 单块 → Markdown 行数组。
+ * @param {object} block 块
+ * @returns {string[]} Markdown 行
+ */
+export function blockToMarkdown(block) {
+  switch (block.kind) {
+    case 'heading':
+      return [`${'#'.repeat(Math.max(1, Math.min(6, block.level ?? 2)))} ${block.text.trim()}`]
+    case 'paragraph':
+      return [block.text.trim()]
+    case 'listItem': {
+      const indent = '  '.repeat(Math.max(0, (block.depth ?? 1) - 1))
+      const marker = block.ordered ? `${block.index ?? 1}. ` : '- '
+      return [`${indent}${marker}${block.text.trim()}`]
+    }
+    case 'quote':
+      return block.text.trim().split('\n').map((line) => `> ${line.trim()}`)
+    case 'code': {
+      const fence = block.text.includes('```') ? '````' : '```'
+      const lang = block.lang ?? ''
+      return [`${fence}${lang}`, block.text, fence]
+    }
+    case 'rule':
+      return ['---']
+    case 'table': {
+      const header = block.header ?? []
+      const rows = block.rows ?? []
+      if (header.length === 0) return []
+      if (rows.length === 0) {
+        // 只有表头没有数据行：Markdown 表格装不下，退化成一行文字，信息不丢
+        return [`${header.map(escapeCell).filter(Boolean).join(' · ')}`]
+      }
+      const width = Math.max(header.length, ...rows.map((row) => row.length))
+      const pad = (cells) => {
+        const out = cells.map(escapeCell)
+        while (out.length < width) out.push('')
+        return `| ${out.join(' | ')} |`
+      }
+      const lines = [pad(header), `| ${new Array(width).fill('---').join(' | ')} |`]
+      for (const row of rows) lines.push(pad(row))
+      return lines
+    }
+    default:
+      return block.text ? [block.text.trim()] : []
+  }
+}
+
+/**
+ * 块列表 → Markdown 文档。
+ * @param {Array<object>} blocks 块（按文档顺序）
+ * @param {{lineRefs?:boolean,maxChars?:number}} [options] 选项
+ * @returns {{markdown:string,truncated:boolean,chars:number,blockCount:number,lines:Array<{line:number,endLine:number,kind:string}>}} 渲染结果
+ */
+export function renderMarkdown(blocks, options = {}) {
+  const lineRefs = options.lineRefs !== false
+  const maxChars = options.maxChars ?? 0
+  const lines = []
+  const map = []
+
+  for (const block of blocks) {
+    // 空白块直接跳过，别在正文里制造连续空行
+    const needsText = block.kind !== 'table' && block.kind !== 'code' && block.kind !== 'rule'
+    if (needsText && !String(block.text ?? '').trim()) continue
+    const rendered = blockToMarkdown(block)
+    if (rendered.length === 0 || rendered.every((line) => line.trim() === '')) continue
+    if (lines.length > 0) lines.push('')
+    if (lineRefs) lines.push(lineRef(block.line, block.endLine))
+    lines.push(...rendered)
+    map.push({ line: block.line, endLine: block.endLine, kind: block.kind })
+  }
+
+  let markdown = lines.join('\n').trim()
+  let truncated = false
+  if (maxChars > 0 && markdown.length > maxChars) {
+    markdown = `${markdown.slice(0, maxChars).trimEnd()}\n\n<!-- 已截断：只保留前 ${maxChars} 字，完整内容请提高 maxChars -->`
+    truncated = true
+  }
+
+  return { markdown, truncated, chars: markdown.length, blockCount: map.length, lines: map }
+}
+
+/**
+ * 没有可用块时（例如纯文本响应、或极碎的页面）用行号对齐的可见文本兜底。
+ * @param {string[]} textLines 行号对齐的可见文本
+ * @param {{lineRefs?:boolean,from?:number,to?:number}} [options] 选项
+ * @returns {{markdown:string,chars:number,blockCount:number,lines:Array<object>}} 渲染结果
+ */
+export function textLinesToMarkdown(textLines, options = {}) {
+  const lineRefs = options.lineRefs !== false
+  const from = options.from ?? 0
+  const to = options.to ?? textLines.length
+  const out = []
+  const map = []
+  let paragraph = []
+
+  const flush = () => {
+    if (paragraph.length === 0) return
+    const text = paragraph.map((item) => item.text).join(' ').trim()
+    const start = paragraph[0].line
+    const end = paragraph[paragraph.length - 1].line
+    paragraph = []
+    if (!text) return
+    if (lineRefs) out.push(lineRef(start, end))
+    out.push(text)
+    out.push('')
+    map.push({ line: start, endLine: end, kind: 'text' })
+  }
+
+  for (let i = from; i < Math.min(to, textLines.length); i++) {
+    const text = String(textLines[i] ?? '').trim()
+    if (!text) { flush(); continue }
+    paragraph.push({ line: i + 1, text })
+  }
+  flush()
+
+  const markdown = out.join('\n').trim()
+  return { markdown, chars: markdown.length, blockCount: map.length, lines: map }
+}
+
+/**
+ * 一行摘要（给工具卡片与 CLI 首行）。
+ * @param {object} result scrape 结果
+ * @returns {string} 摘要
+ */
+export function summaryLine(result) {
+  const title = result.title ? stripInline(result.title).slice(0, 60) : '(无标题)'
+  const chars = result.content?.chars ?? 0
+  return `${title} · ${chars} 字 · 置信度 ${result.content?.confidence ?? 0} · ${result.provenance?.httpStatus ?? '-'} ${result.provenance?.finalUrl ?? ''}`.trim()
+}

package/lib/net.mjs

@@ -0,0 +1,283 @@
+/**
+ * 网络层：抓一个 URL 的原始字节，并把「重定向链、字符集、截断」这些抓取事实记下来。
+ *
+ * 三条设计取舍：
+ * 1) **手动跟随重定向**（`redirect: 'manual'`）——这样才能把每一跳记进 provenance，
+ *    也才能自己控制跳数与跨站跳转；undici 的自动跟随只留最终 URL，证据会丢。
+ * 2) **自己解码字符集**——`response.text()` 永远按 UTF-8 解，中文老站（GBK/GB18030/Big5）
+ *    会变成乱码。这里读字节、从响应头或 `<meta charset>` 认字符集，再交给 `TextDecoder`。
+ * 3) **按字节上限截断**——边读边数，超过 maxBytes 就掐掉并标记 `truncated`，
+ *    避免一个 200MB 的页面把 agent 的上下文炸掉。
+ */
+
+import { classifyFetchError, httpStatusError, ScrapeError } from './errors.mjs'
+
+/** 默认 UA：说明自己是谁、能做什么，站点管理员看得懂。 */
+export const DEFAULT_USER_AGENT =
+  'dsh-scrape/0.1.0 (+https://github.com/dongsheng123132/dsh-scrape; robots-aware AI fetcher)'
+
+/** 判为重定向的状态码。 */
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308])
+
+/** 不响应字符集检测的二进制类型：抓到也当字节，不猜编码。 */
+const TEXT_HINT = /^(text\/|application\/(json|xml|xhtml\+xml|javascript|rss\+xml|atom\+xml|ld\+json))/i
+
+/**
+ * 校验 URL 能抓（http/https 且能解析）。
+ * @param {string} url 原始 URL
+ * @returns {URL} 解析后的 URL
+ */
+export function assertFetchableUrl(url) {
+  let target
+  try {
+    target = new URL(String(url))
+  } catch (error) {
+    throw new ScrapeError('invalid_url', `URL 不合法：${url}`, {
+      url: String(url), cause: error, hint: '要写全，例如 https://example.com/page',
+    })
+  }
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+    throw new ScrapeError('invalid_url', `只支持 http/https：${target.protocol}//${target.host}`, {
+      url: String(url), hint: '不做 file:// ftp://；本地文件请用 --file 或 html 输入',
+    })
+  }
+  return target
+}
+
+/**
+ * 从 Content-Type 里取字符集。
+ * @param {string} contentType 响应头 Content-Type
+ * @returns {string} 小写字符集名，取不到返回空串
+ */
+export function charsetFromContentType(contentType) {
+  const match = /charset\s*=\s*"?([\w.:-]+)"?/i.exec(String(contentType ?? ''))
+  return match ? match[1].toLowerCase() : ''
+}
+
+/**
+ * 从 HTML 头部字节里嗅 `<meta charset>` / `<meta http-equiv>`。
+ * 只看前 2048 字节（规范建议），够覆盖绝大多数页面。
+ * @param {Buffer} buffer 原始字节
+ * @returns {string} 小写字符集名，嗅不到返回空串
+ */
+export function sniffCharset(buffer) {
+  const head = buffer.subarray(0, 2048).toString('latin1')
+  const direct = /<meta[^>]+charset\s*=\s*["']?\s*([\w.:-]+)/i.exec(head)
+  if (direct) return direct[1].toLowerCase()
+  const httpEquiv = /<meta[^>]+http-equiv\s*=\s*["']?content-type["']?[^>]*content\s*=\s*["'][^"']*charset=([\w.:-]+)/i.exec(head)
+  return httpEquiv ? httpEquiv[1].toLowerCase() : ''
+}
+
+/**
+ * 用指定字符集解码字节；字符集不认识就退回 UTF-8，并把这件事说出来。
+ * @param {Buffer} buffer 原始字节
+ * @param {string} label 字符集名
+ * @returns {{text:string,charset:string,fallback:boolean,error?:string}} 解码结果
+ */
+export function decodeBuffer(buffer, label) {
+  const wanted = String(label ?? '').trim().toLowerCase()
+  const candidates = wanted ? [wanted] : []
+  candidates.push('utf-8')
+  let lastError = ''
+  for (const candidate of candidates) {
+    try {
+      const decoder = new TextDecoder(candidate, { fatal: false })
+      return { text: decoder.decode(buffer), charset: candidate, fallback: candidate !== wanted && wanted !== '', ...(lastError ? { error: lastError } : {}) }
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error)
+    }
+  }
+  // 兜底：Node 里 TextDecoder('utf-8') 一定存在，走不到这里
+  return { text: buffer.toString('utf8'), charset: 'utf-8', fallback: true, error: lastError }
+}
+
+/**
+ * 边读边截断，拿到不超过 maxBytes 的字节。
+ * @param {ReadableStream<Uint8Array>|null} body 响应体流
+ * @param {number} maxBytes 字节上限
+ * @returns {Promise<{buffer:Buffer,truncated:boolean}>} 字节与截断标记
+ */
+async function readCapped(body, maxBytes) {
+  if (!body || typeof body.getReader !== 'function') {
+    return { buffer: Buffer.alloc(0), truncated: false }
+  }
+  const reader = body.getReader()
+  const chunks = []
+  let total = 0
+  let truncated = false
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    if (!value || value.length === 0) continue
+    const remaining = maxBytes - total
+    if (value.length > remaining) {
+      chunks.push(Buffer.from(value.subarray(0, remaining)))
+      total += remaining
+      truncated = true
+      try { await reader.cancel() } catch { /* 取消失败不影响已读字节 */ }
+      break
+    }
+    chunks.push(Buffer.from(value))
+    total += value.length
+    if (total >= maxBytes) {
+      // 刚好读满上限：再探一次才知道后面还有没有，别把「正好 maxBytes」误报成截断
+      const next = await reader.read()
+      if (next.done) break
+      truncated = true
+      try { await reader.cancel() } catch { /* 忽略 */ }
+      break
+    }
+  }
+  return { buffer: Buffer.concat(chunks, total), truncated }
+}
+
+/**
+ * 抓一个 URL（含手动跟随重定向、字符集解码、按字节截断）。
+ *
+ * @param {string} url 目标 URL
+ * @param {object} [options] 选项
+ * @param {number} [options.timeoutMs=15000] 单跳超时（毫秒，整个请求含读体）
+ * @param {number} [options.maxBytes=2000000] 响应体字节上限
+ * @param {number} [options.maxRedirects=5] 最多跟几跳
+ * @param {number[]} [options.acceptStatus] 额外接受的状态码（默认 2xx）
+ * @param {string} [options.userAgent] UA
+ * @param {AbortSignal} [options.signal] 外部取消信号
+ * @param {{acquire:(url:string)=>Promise<void>}} [options.throttle] 同域限速器
+ * @returns {Promise<object>} 抓取结果（含 redirects / charset / buffer / text / truncated）
+ */
+export async function fetchPage(url, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 15000
+  const maxBytes = Math.max(64, options.maxBytes ?? 2_000_000)
+  const maxRedirects = Math.max(0, options.maxRedirects ?? 5)
+  const acceptStatus = options.acceptStatus ?? []
+  const userAgent = options.userAgent ?? DEFAULT_USER_AGENT
+  const startedAt = Date.now()
+
+  let current = assertFetchableUrl(url)
+  const requestedUrl = current.toString()
+  const redirects = []
+
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    // 同域限速：拿到许可才发请求，读完响应体才放行下一个。
+    // try/finally 保证任何异常路径都会放行，否则这个域名的队列会被永久堵死。
+    const lease = options.throttle ? await options.throttle.acquire(current.toString()) : null
+    let released = false
+    const release = () => {
+      if (released) return
+      released = true
+      lease?.release()
+    }
+
+    try {
+      const timeoutSignal = AbortSignal.timeout(timeoutMs)
+      const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal
+
+      let response
+      try {
+        response = await fetch(current, {
+          redirect: 'manual',
+          signal,
+          headers: {
+            'user-agent': userAgent,
+            accept: 'text/html,application/xhtml+xml,text/plain;q=0.9,application/json;q=0.8,*/*;q=0.5',
+            'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8',
+          },
+        })
+      } catch (error) {
+        throw classifyFetchError(error, current.toString())
+      }
+
+      if (REDIRECT_STATUS.has(response.status)) {
+        const location = response.headers.get('location')
+        try { await response.body?.cancel() } catch { /* 忽略：只为放掉连接 */ }
+        if (!location) {
+          // 3xx 但没有 Location：按最终响应处理，不要假装跟过去了
+          return await finish(response, current.toString(), { requestedUrl, redirects, startedAt, maxBytes })
+        }
+        let next
+        try {
+          next = new URL(location, current).toString()
+        } catch (error) {
+          throw new ScrapeError('bad_redirect', `重定向的 Location 不合法：${location}`, {
+            url: current.toString(), cause: error, details: { location },
+            hint: '站点给了相对/畸形地址；先用浏览器确认最终落点',
+          })
+        }
+        redirects.push({ from: current.toString(), to: next, status: response.status })
+        if (hop === maxRedirects) {
+          throw new ScrapeError('too_many_redirects', `重定向超过 ${maxRedirects} 跳：${requestedUrl}`, {
+            url: requestedUrl, details: { redirects }, hint: '可能是死循环；先确认最终地址再抓',
+          })
+        }
+        current = assertFetchableUrl(next)
+        continue
+      }
+
+      if (!response.ok && !acceptStatus.includes(response.status)) {
+        try { await response.body?.cancel() } catch { /* 忽略 */ }
+        throw httpStatusError(current.toString(), response.status, response.statusText)
+      }
+
+      return await finish(response, current.toString(), { requestedUrl, redirects, startedAt, maxBytes })
+    } catch (error) {
+      // 已经分类过的（ScrapeError）直接抛；读响应体失败这种底层错误在这里补分类
+      if (error instanceof ScrapeError) throw error
+      throw classifyFetchError(error, current.toString())
+    } finally {
+      release()
+    }
+  }
+
+  throw new ScrapeError('too_many_redirects', `重定向过多：${requestedUrl}`, {
+    url: requestedUrl, details: { redirects }, hint: '可能是死循环；先确认最终地址再抓',
+  })
+}
+
+/**
+ * 收尾：读体、解码、组装 provenance。
+ * @param {Response} response fetch 响应
+ * @param {string} finalUrl 最终 URL
+ * @param {object} meta 上下文（requestedUrl/redirects/startedAt/maxBytes）
+ * @returns {Promise<object>} 抓取结果
+ */
+async function finish(response, finalUrl, meta) {
+  const contentType = response.headers.get('content-type') ?? ''
+  const { buffer, truncated } = await readCapped(response.body, meta.maxBytes)
+  const headerCharset = charsetFromContentType(contentType)
+  const sniffed = headerCharset || sniffCharset(buffer)
+  const decoded = decodeBuffer(buffer, sniffed)
+
+  return {
+    requestedUrl: meta.requestedUrl,
+    finalUrl: response.url && response.url !== finalUrl ? response.url : finalUrl,
+    redirects: meta.redirects,
+    status: response.status,
+    statusText: response.statusText ?? '',
+    ok: response.ok,
+    contentType,
+    charset: decoded.charset,
+    charsetDeclared: sniffed || '',
+    charsetFallback: decoded.fallback,
+    buffer,
+    text: decoded.text,
+    bytes: buffer.length,
+    truncated,
+    isText: TEXT_HINT.test(contentType) || contentType === '',
+    elapsedMs: Date.now() - meta.startedAt,
+  }
+}
+
+/**
+ * 抓一个「补充文件」并允许 404（robots.txt 用）。
+ * 失败不抛错，返回 null 由调用方决定怎么说明。
+ * @param {string} url 文件 URL
+ * @param {object} [options] 同 fetchPage
+ * @returns {Promise<object|null>} 抓取结果；网络/状态失败返回 null
+ */
+export async function fetchOptional(url, options = {}) {
+  try {
+    return await fetchPage(url, { maxBytes: 256 * 1024, ...options, acceptStatus: [200, 204, 400, 401, 403, 404, 410, 429, 500, 502, 503] })
+  } catch {
+    return null
+  }
+}