dsh-scrape 0.0.1 → 0.1.0

package/lib/errors.mjs

@@ -0,0 +1,137 @@
+/**
+ * 错误模型：抓取失败必须能被调用方分类处理，也必须能直接给人看。
+ *
+ * `code` 是稳定契约（不随文案变），`message` 是中文人话，`hint` 是「该去查什么」。
+ * **绝不吞异常**：所有失败路径都抛 ScrapeError，分类见 classifyFetchError。
+ */
+
+/** 网络 / HTTP / 输入类错误。code 稳定，文案可改。 */
+export class ScrapeError extends Error {
+  /**
+   * @param {string} code 稳定错误码
+   * @param {string} message 中文人话
+   * @param {{url?:string,cause?:unknown,details?:object,hint?:string}} [init] 附加信息
+   */
+  constructor(code, message, init = {}) {
+    super(message)
+    this.name = 'ScrapeError'
+    this.code = code
+    this.url = init.url
+    this.hint = init.hint
+    this.details = init.details ?? {}
+    if (init.cause !== undefined) this.cause = init.cause
+  }
+
+  /** 便于 JSON 序列化的纯数据视图（CLI --json 与工具错误都用它）。 */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+      url: this.url,
+      details: this.details,
+    }
+  }
+}
+
+/**
+ * 把底层 fetch / undici / socket 错误翻成我们的分类。
+ * @param {unknown} error 捕获到的异常
+ * @param {string} url 请求的 URL
+ * @returns {ScrapeError} 分类后的错误
+ */
+export function classifyFetchError(error, url) {
+  const name = error && typeof error === 'object' ? String(error.name) : ''
+  const causeCode = error && typeof error === 'object' && error.cause && typeof error.cause === 'object'
+    ? String(error.cause.code ?? '')
+    : ''
+  const message = error instanceof Error ? error.message : String(error)
+  const lower = message.toLowerCase()
+
+  if (name === 'TimeoutError' || lower.includes('timed out') || lower.includes('timeout')) {
+    return new ScrapeError('timeout', `请求超时：${url} 在限定时间内没有响应`, {
+      url, cause: error, hint: '站点可能很慢或在墙外；放宽 --timeout、换网络/代理，或先用浏览器确认它到底通不通',
+    })
+  }
+  if (name === 'AbortError') {
+    return new ScrapeError('aborted', `请求被取消：${url}`, {
+      url, cause: error, hint: '调用方主动取消（如工具超时），不是站点问题',
+    })
+  }
+  if (causeCode === 'ENOTFOUND' || causeCode === 'EAI_AGAIN' || lower.includes('getaddrinfo')) {
+    return new ScrapeError('dns', `域名解析失败：${url} 的主机名查不到`, {
+      url, cause: error, details: { code: causeCode }, hint: '检查域名是否拼错或已过期；国内网络访问境外站可能需要代理',
+    })
+  }
+  if (causeCode === 'ECONNREFUSED') {
+    return new ScrapeError('connection_refused', `连接被拒绝：${url} 没有在监听`, {
+      url, cause: error, details: { code: causeCode }, hint: '端口没开，或本地服务没起来',
+    })
+  }
+  if (causeCode === 'ECONNRESET' || causeCode === 'EPIPE' || causeCode === 'UND_ERR_SOCKET') {
+    return new ScrapeError('connection_reset', `连接被对端断开：${url}`, {
+      url, cause: error, details: { code: causeCode }, hint: '常见于代理中断或站点反爬；重试或换线路',
+    })
+  }
+  if (
+    causeCode.startsWith('CERT_') || causeCode === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' ||
+    causeCode === 'DEPTH_ZERO_SELF_SIGNED_CERT' || causeCode === 'ERR_TLS_CERT_ALTNAME_INVALID' ||
+    lower.includes('certificate')
+  ) {
+    return new ScrapeError('tls', `HTTPS 证书验证失败：${url}`, {
+      url, cause: error, details: { code: causeCode }, hint: '对方证书过期/自签/域名不匹配；不要为了抓取去关证书校验',
+    })
+  }
+  if (causeCode === 'UND_ERR_TOO_MANY_REDIRECTS' || lower.includes('redirect')) {
+    return new ScrapeError('too_many_redirects', `重定向过多：${url}`, {
+      url, cause: error, details: { code: causeCode }, hint: '大概是 http→https→http 死循环；先用浏览器确认最终地址',
+    })
+  }
+  if (causeCode === 'EHOSTUNREACH' || causeCode === 'ENETUNREACH') {
+    return new ScrapeError('network', `网络不可达：${url}`, {
+      url, cause: error, details: { code: causeCode }, hint: '本机没网或路由不通',
+    })
+  }
+  if (name === 'TypeError' && lower.includes('failed to parse url')) {
+    return new ScrapeError('invalid_url', `URL 不合法：${url}`, { url, cause: error, hint: '要带 http:// 或 https:// 前缀' })
+  }
+  return new ScrapeError('network', `请求失败：${url}（${message}）`, {
+    url, cause: error, details: { code: causeCode, name }, hint: '未知网络错误，看 details 里的原始 code',
+  })
+}
+
+/**
+ * HTTP 状态码 → 分类错误（4xx/5xx 都算失败，除非调用方声明可接受）。
+ * @param {string} url 请求 URL
+ * @param {number} status 状态码
+ * @param {string} statusText 状态说明
+ * @returns {ScrapeError} 分类后的错误
+ */
+export function httpStatusError(url, status, statusText) {
+  const suffix = statusText ? ` ${statusText}` : ''
+  const hint = status === 404
+    ? '地址不存在；确认路径，或这个站点确实没有这个文件'
+    : status === 403 || status === 401
+      ? '被站点或 WAF 拦了：可能需要登录、换 UA，或这个页面本来就不对匿名访问开放'
+      : status === 429
+        ? '被限速了：降低频率（--min-interval）后重试'
+        : status >= 500
+          ? '对方服务器出错，等一会儿再试'
+          : '按状态码查原因'
+  return new ScrapeError('http_status', `HTTP ${status}${suffix}：${url}`, {
+    url, details: { status, statusText }, hint,
+  })
+}
+
+/**
+ * 把任意异常收敛成 {code,message,hint}，供 CLI / 工具返回使用。
+ * @param {unknown} error 任意异常
+ * @returns {{code:string,message:string,hint?:string,status?:number}} 纯数据
+ */
+export function describeError(error) {
+  if (error instanceof ScrapeError) return error.toJSON()
+  if (error instanceof Error) {
+    return { code: 'internal', message: error.message }
+  }
+  return { code: 'internal', message: String(error) }
+}

package/lib/extract.mjs

@@ -0,0 +1,192 @@
+/**
+ * 正文抽取：「密度法」的最小实现 + 可解释的 confidence。
+ *
+ * 不做 Readability 那种打分模型的完整版，只做三件能被验证的事：
+ * 1) 有 `<main>` / `<article>` 且里面有足够文字 → 直接信它（这是站点自己声明的正文）；
+ * 2) 否则按「连续正文段」找最长的一段（允许中间夹 2 个短块，因为正文里常有图注、按钮行）；
+ * 3) 纯链接块、超短块、菜单词块判为样板内容（boilerplate）并丢掉。
+ *
+ * 每条结论都能说出理由（`reasons`），confidence 是这些理由的加权和，不是玄学分数。
+ */
+
+import { stripInline } from './html.mjs'
+
+/** 抽取器版本（报告里带上，便于对比不同版本的置信度口径）。 */
+export const EXTRACT_VERSION = 'density-v1'
+
+/** 正文块最短字数：低于这个数就认为「没抓到正文」。 */
+export const MIN_MAIN_CHARS = 200
+
+/** 纯样板块判定用的菜单词（整块只有这些词就丢）。 */
+const MENU_WORDS = /^(首页|主页|关于我们|关于|联系我们|产品|服务|登录|注册|订阅|搜索|菜单|更多|返回|上一篇|下一篇|home|menu|about|contact|products?|services?|login|sign in|sign up|register|subscribe|search|more|next|previous|back|share|follow)$/i
+
+/**
+ * 块的可读文本长度（去掉行内 Markdown 标记后计字）。
+ * @param {object} block 块
+ * @returns {number} 字数
+ */
+export function blockLength(block) {
+  if (!block) return 0
+  if (block.kind === 'table') {
+    const cells = [...(block.header ?? []), ...(block.rows ?? []).flat()]
+    return cells.reduce((sum, cell) => sum + stripInline(cell).length, 0)
+  }
+  return stripInline(block.text ?? '').length
+}
+
+/**
+ * 块里的链接文字占比（导航条的特征：整块几乎都是链接文字）。
+ * @param {object} block 块
+ * @returns {number} 0–1
+ */
+export function linkRatio(block) {
+  const text = String(block?.text ?? '')
+  const len = stripInline(text).length
+  if (len === 0) return 0
+  let linkChars = 0
+  for (const match of text.matchAll(/\[([^\]]*)\]\([^)]*\)/g)) linkChars += stripInline(match[1]).length
+  return linkChars / len
+}
+
+/**
+ * 判断一个块是不是界面样板（导航、页脚菜单、按钮行、版权行）。
+ * @param {object} block 块
+ * @returns {boolean} 是否样板
+ */
+export function isBoilerplate(block) {
+  const length = blockLength(block)
+  if (length === 0) return true
+  if (block.kind === 'rule') return true
+  const plain = stripInline(block.text ?? '')
+  if (MENU_WORDS.test(plain)) return true
+  // 短块不一定是样板：导航/页脚/分享条已经在 HTML 层按元素去掉了，
+  // 这里只丢「真的没有信息量」的碎片（图标残留、单个符号、空链接串）
+  if (block.kind === 'paragraph' && length < 8) return true
+  if (block.kind === 'listItem' && length < 6) return true
+  if (block.kind === 'listItem' && length < 60 && linkRatio(block) > 0.5) return true
+  if (block.kind === 'paragraph' && length < 120 && linkRatio(block) > 0.6) return true
+  if (/^(©|\(c\)|copyright|版权所有|all rights reserved)/i.test(plain)) return true
+  return false
+}
+
+/**
+ * 在一串块里找最长的一段正文（允许夹 2 个样板块）。
+ * @param {Array<object>} blocks 块
+ * @returns {{indexes:number[],chars:number}} 最佳连续段
+ */
+export function bestRun(blocks) {
+  let best = { indexes: [], chars: 0 }
+  let current = { indexes: [], chars: 0 }
+  let gap = 0
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i]
+    const length = blockLength(block)
+    if (isBoilerplate(block)) {
+      if (current.indexes.length === 0) continue
+      gap += 1
+      if (gap > 2) {
+        if (current.chars > best.chars) best = { ...current, indexes: [...current.indexes] }
+        current = { indexes: [], chars: 0 }
+        gap = 0
+      }
+      continue
+    }
+    gap = 0
+    current.indexes.push(i)
+    current.chars += length
+  }
+  if (current.chars > best.chars) best = { ...current, indexes: [...current.indexes] }
+  return best
+}
+
+/**
+ * 挑正文块并给出可解释的置信度。
+ * @param {Array<object>} blocks parseHtml 的块
+ * @param {{minChars?:number,spa?:boolean,maxChars?:number}} [options] 选项
+ * @returns {object} 抽取结果
+ */
+export function selectMain(blocks, options = {}) {
+  const minChars = options.minChars ?? MIN_MAIN_CHARS
+  const reasons = []
+  const all = Array.isArray(blocks) ? blocks : []
+  const totalChars = all.reduce((sum, block) => sum + blockLength(block), 0)
+
+  if (all.length === 0 || totalChars === 0) {
+    return {
+      blocks: [], method: 'empty', confidence: 0, reasons: ['页面没有任何可见文字'],
+      chars: { total: 0, kept: 0, dropped: 0, droppedBoilerplate: 0, droppedOffMain: 0 },
+      version: EXTRACT_VERSION,
+    }
+  }
+
+  const insideMain = all.filter((block) => block.inMain)
+  const insideMainChars = insideMain.reduce((sum, block) => sum + blockLength(block), 0)
+
+  let kept
+  let method
+  let base
+
+  // 站点自己声明的 <main>/<article> 是强信号：门槛放到 minChars 的一半（最低 80 字），
+  // 免得「短但完整」的文章被判成 fallback
+  if (insideMainChars >= Math.max(80, Math.round(minChars / 2))) {
+    kept = insideMain.filter((block) => !isBoilerplate(block) || block.kind === 'heading')
+    method = 'main-element'
+    base = 0.85
+    reasons.push(`页面用了 <main>/<article>，其中 ${insideMainChars} 字`)
+  } else {
+    const run = bestRun(all)
+    if (run.chars >= minChars) {
+      kept = all.filter((block, index) => run.indexes.includes(index))
+      method = 'density'
+      base = 0.55
+      reasons.push(`密度法选中 ${run.indexes.length} 个连续块，共 ${run.chars} 字（全页可见 ${totalChars} 字）`)
+    } else {
+      kept = all.filter((block) => !isBoilerplate(block))
+      if (kept.length === 0) kept = all.slice()
+      method = 'fallback'
+      base = 0.25
+      reasons.push(`没有可靠的正文段（最长连续段只有 ${run.chars} 字），退回「去掉样板后的全部文字」`)
+    }
+  }
+
+  // 只保留有文字的块，按原顺序
+  kept = kept.filter((block) => blockLength(block) > 0).sort((a, b) => a.seq - b.seq)
+
+  let confidence = base
+  const keptChars = kept.reduce((sum, block) => sum + blockLength(block), 0)
+  if (kept.length >= 3) { confidence += 0.10; reasons.push('保留块 ≥ 3 段（像正文而不是碎片）') }
+  if (keptChars >= 800) { confidence += 0.08; reasons.push(`正文 ${keptChars} 字（≥ 800）`) }
+  if (kept.some((block) => block.kind === 'heading')) { confidence += 0.05; reasons.push('正文里有标题层级') }
+  if (kept.some((block) => block.kind === 'table' || block.kind === 'code')) {
+    confidence += 0.05
+    reasons.push('正文里有表格或代码块（这类结构只在正文出现）')
+  }
+  if (keptChars < minChars) { confidence -= 0.15; reasons.push(`正文只有 ${keptChars} 字（< ${minChars}）`) }
+  if (keptChars < 50) { confidence -= 0.15; reasons.push('正文不足 50 字') }
+  if (options.spa) { confidence -= 0.10; reasons.push('页面疑似客户端渲染（不执行 JS 时内容天然不全）') }
+
+  confidence = Math.max(0.05, Math.min(0.95, Math.round(confidence * 100) / 100))
+
+  const droppedBoilerplate = all
+    .filter((block) => !kept.includes(block) && isBoilerplate(block))
+    .reduce((sum, block) => sum + blockLength(block), 0)
+  const keptSet = new Set(kept)
+  const droppedOffMain = all
+    .filter((block) => !keptSet.has(block) && !isBoilerplate(block))
+    .reduce((sum, block) => sum + blockLength(block), 0)
+
+  return {
+    blocks: kept,
+    method,
+    confidence,
+    reasons,
+    chars: {
+      total: totalChars,
+      kept: keptChars,
+      dropped: Math.max(0, totalChars - keptChars),
+      droppedBoilerplate,
+      droppedOffMain,
+    },
+    version: EXTRACT_VERSION,
+  }
+}

package/lib/format.mjs

@@ -0,0 +1,137 @@
+/**
+ * 渲染层：一份给人/给模型看的文本摘要，一份纯 JSON（Markdown 正文本身在 result.markdown）。
+ *
+ * 口径：**摘要不抢正文的位置**。CLI 文本模式先给 6 行事实（状态、字数、置信度、去噪统计、警告），
+ * 空一行，再接 Markdown 正文——这样 agent 读到的第一屏就是可引用的内容，而不是一堆元数据。
+ */
+
+/**
+ * 按显示宽度补空格（中文算 2 格），让中英混排对齐。
+ * @param {string} text 文本
+ * @param {number} width 目标宽度
+ * @returns {string} 补齐后的文本
+ */
+export function padDisplay(text, width) {
+  const displayWidth = (input) => [...String(input)].reduce((sum, ch) => sum + (ch.charCodeAt(0) > 0x2e7f ? 2 : 1), 0)
+  const current = displayWidth(text)
+  return current >= width ? String(text) : String(text) + ' '.repeat(width - current)
+}
+
+/**
+ * 字节数人话化。
+ * @param {number} bytes 字节
+ * @returns {string} 例如 42.1 KB
+ */
+export function humanBytes(bytes) {
+  const value = Number(bytes) || 0
+  if (value < 1024) return `${value} B`
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`
+  return `${(value / 1024 / 1024).toFixed(1)} MB`
+}
+
+/**
+ * 渲染去噪统计（只列非零项）。
+ * @param {object} removed removed 对象
+ * @returns {string} 一行说明
+ */
+export function renderRemoved(removed = {}) {
+  const parts = []
+  for (const key of ['script', 'style', 'nav', 'footer', 'aside', 'form', 'consent', 'share', 'comment', 'ad', 'noscript', 'svg', 'iframe', 'button', 'boilerplate']) {
+    const value = removed[key] ?? 0
+    if (value > 0) parts.push(`${key} ${value} 字`)
+  }
+  return parts.length > 0 ? `${parts.join(' · ')}（合计 ${removed.total ?? 0} 字）` : '没有可去噪的界面元素'
+}
+
+/**
+ * 渲染单页结果。
+ * @param {object} result scrape 结果
+ * @param {{detail?:'full'|'brief',maxWarnings?:number}} [options] 选项
+ * @returns {string} 文本
+ */
+export function renderText(result, options = {}) {
+  const detail = options.detail ?? 'full'
+  const maxWarnings = options.maxWarnings ?? (detail === 'brief' ? 2 : 6)
+  const lines = []
+
+  if (result.kind === 'multi') return renderMulti(result, options)
+
+  const provenance = result.provenance ?? {}
+  const content = result.content ?? {}
+  lines.push(`dsh-scrape ${result.version} · ${result.kind === 'html' ? '本地 HTML' : 'URL'} · ${provenance.finalUrl ?? provenance.requestedUrl ?? '(无地址)'}`)
+  const facts = (result.kind === 'html'
+    ? [humanBytes(provenance.bytes), provenance.charset ? `字符集 ${provenance.charset}` : null]
+    : [
+        provenance.httpStatus ? `HTTP ${provenance.httpStatus}` : '未取到响应',
+        humanBytes(provenance.bytes),
+        provenance.elapsedMs ? `${provenance.elapsedMs}ms` : null,
+        provenance.charset ? `字符集 ${provenance.charset}` : null,
+        provenance.redirects?.length ? `跟随 ${provenance.redirects.length} 次重定向` : null,
+        provenance.truncated ? '已截断' : null,
+      ]).filter(Boolean)
+  lines.push(`  ${facts.join(' · ')}`)
+  if (result.title) lines.push(`  标题：${result.title}`)
+  lines.push(`  正文 ${content.chars ?? 0} 字 · 置信度 ${content.confidence ?? 0}（${content.method ?? '-'}）· ${content.blocks ?? 0} 块 · ${content.headings ?? 0} 标题 · ${content.tables ?? 0} 表格`)
+  if (content.spaSuspected) lines.push('  ⚠️ 疑似 SPA：不执行 JS，正文可能不全')
+  lines.push(`  去噪：${renderRemoved(result.removed)}`)
+
+  if (result.blocked === 'robots') {
+    lines.push('')
+    lines.push('  ⛔ robots.txt 禁止抓取，已按规则跳过（没有发出页面请求）')
+  }
+
+  const warnings = result.warnings ?? []
+  if (warnings.length > 0) {
+    lines.push('  警告：')
+    for (const item of warnings.slice(0, maxWarnings)) lines.push(`    - [${item.code}] ${item.message}`)
+    if (warnings.length > maxWarnings) lines.push(`    - 还有 ${warnings.length - maxWarnings} 条（--json 看全量）`)
+  }
+  if (detail === 'full' && result.notes?.length > 0) {
+    lines.push('  说明：')
+    for (const note of result.notes.slice(0, 5)) lines.push(`    · ${note}`)
+  }
+
+  if (options.withMarkdown !== false) {
+    lines.push('')
+    lines.push('--- Markdown ---')
+    lines.push(result.markdown ?? '')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * 渲染多页结果（只给摘要，正文在 --json 里）。
+ * @param {object} result 多页结果
+ * @param {object} [options] 选项
+ * @returns {string} 文本
+ */
+function renderMulti(result, options = {}) {
+  const detail = options.detail ?? 'full'
+  const lines = []
+  lines.push(`dsh-scrape ${result.version} · 批量抓取 ${result.count}/${result.requested} 页`)
+  lines.push('')
+  lines.push(`  ${padDisplay('状态', 6)} ${padDisplay('字数', 8)} ${padDisplay('置信度', 7)} ${padDisplay('标题', 34)} URL`)
+  for (const page of result.pages ?? []) {
+    const status = page.blocked ? '⛔robots' : (page.provenance?.httpStatus ?? '-')
+    const title = (page.title ?? '').slice(0, 32)
+    lines.push(`  ${padDisplay(status, 6)} ${padDisplay(page.content?.chars ?? 0, 8)} ${padDisplay(page.content?.confidence ?? 0, 7)} ${padDisplay(title, 34)} ${page.provenance?.finalUrl ?? page.provenance?.requestedUrl ?? ''}`)
+  }
+  for (const failure of result.failures ?? []) {
+    lines.push(`  ✗ ${failure.url} —— [${failure.error.code}] ${failure.error.message}`)
+  }
+  if (detail === 'full') {
+    const warnCount = (result.pages ?? []).reduce((sum, page) => sum + (page.warnings?.length ?? 0), 0)
+    lines.push('')
+    lines.push(`  提示：${warnCount} 条页面警告；正文请用 --json 逐页取 markdown 字段`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * 渲染 JSON。
+ * @param {object} result 结果
+ * @returns {string} 格式化 JSON
+ */
+export function renderJson(result) {
+  return JSON.stringify(result, null, 2)
+}