HHY 扩展 · 当前版本 v1.7.1
HTML 扩展与抓取框架
用官方 HTML 扩展和安全 Frontier 完成 URL 规范化、链接发现、递归去重及有界静态抓取。
HTML 扩展是什么
官方 html 0.2.0 是一个无网络、无文件副作用的进程扩展。它用 Lexbor 解析不可信 HTML、执行 CSS Selector，并通过 extract_report 返回批量记录和明确的截断元数据。
构建与安装 HTML 扩展
brew install jansson lexbor
make -C extensions/html
./build/hhy install ./extensions/html
./build/hhy list| 完整签名 | 用途 |
|---|---|
| html.text(String html, String selector, Map?) -> String? | 读取首个节点的规范化文本 |
| html.text_all(String html, String selector, Map?) -> List<String> | 读取全部匹配节点的文本 |
| html.attr(String html, String selector, String name, Map?) -> String? | 读取首个节点的属性 |
| html.attr_all(String html, String selector, String name, Map?) -> List<String> | 读取全部匹配节点的属性 |
| html.exists(String html, String selector) -> Bool | 判断 Selector 是否命中 |
| html.extract(String html, String selector, Map schema, Map?) -> List<Map> | 一次解析文档，并按 schema 投影重复记录 |
| 选项 | 适用方法 | 行为 |
|---|---|---|
| trim: Bool | text、text_all、attr、attr_all | 是否清理首尾空白，默认开启 |
| max_results: Int | text_all、attr_all、extract | 默认 1000，硬上限 10000 |
扩展把输入限制在 768 KiB，以便协议消息始终有界。extract 的 schema 字段使用 { selector, value: "text" } 或 { selector, value: "attr", name }；空 selector 表示读取当前 root。它不返回 DOM handle：Protocol 1 只运输 JSON 可表达的值，因此 html.extract 在扩展内一次完成解析和字段投影。
从 HTML 扩展到安全爬虫框架
静态 Spider 把多个职责组合成闭环：Runtime 的 url_resolve 规范化并解析相对 URL；HTML 扩展发现链接；按深度推进的 Frontier 在入队前检查域名、路径、页面数、队列大小和请求指纹；HTTP 网络层在实际连接地址上阻止 SSRF。
| 能力 | 当前实现程度 |
|---|---|
| url_resolve(url, base?) | 返回 url、scheme、host、port、path、query 与稳定 fingerprint |
| 链接发现 | follow_selector 提取 href，逐层加入 Frontier |
| Frontier 与去重 | 按深度、有界并发；规范 URL 指纹在入队前去重 |
| 边界限制 | allowed_domains、path prefixes、max_depth/pages/frontier/links |
| SSRF 防护 | 在每次实际 socket 连接时阻止 loopback、私网及 link-local，覆盖重定向 |
适用范围与明确边界
当前支持内存或原子 checkpoint Frontier、严格配置匹配的断点恢复，以及 send_to 流式响应文件。可选 Playwright Renderer 能执行 JavaScript；它与无副作用的 Lexbor HTML 扩展隔离，并对主文档、重定向和子资源执行域名与 DNS 私网检查。