# dsh-read-url 🌐 [English](README.md) | **中文** ![dsh-read-url](docs/banner.svg) [![npm](https://img.shields.io/npm/v/dsh-read-url)](https://www.npmjs.com/package/dsh-read-url) [![License](https://img.shields.io/github/license/2672243194/dsh-read-url)](https://github.com/2672243194/dsh-read-url/blob/main/LICENSE) DeepSeek Harness 的 URL 阅读插件：抓取任意 URL——**网页（HTML）、JSON 接口、RSS/Atom 订阅源**——**自动识别编码（UTF-16 BOM / GBK/GB2312 / UTF-8 / Big5 / Shift-JIS）**，提取干净正文（**分页长文自动拼接**），输出**省 token 的紧凑文本或结构化 Markdown**。 核心零运行时依赖（Node 20+ 内置能力完成抓取/转码/提取），免 API key，免服务端，装完即用。 ## 内容支持 - HTML 技术文档、论坛、嵌套文章与自定义元素；保留可见代码示例和元数据。 - 纯文本、Markdown、CSV、JSON 与厂商 `+json` 接口。 - RSS 1.0/2.0、Atom（含命名空间、相对文章链接和 `xml:base`）。 - 无 Content-Type 的 UTF-16 BOM 文本。 续读位置使用 `charsStart + charsReturned`；跳过段间空行后，返回的 `charsStart` 可能大于请求 offset。Markdown 表格最多转换前 25 行，保留省略行数提示。 ## 为什么做它 DSH 的 Agent 能搜索（返回链接和片段），但缺"把 URL 读成干净正文"这一步。官方 `tool-web` 的 `web_fetch` 是**整页 turndown 转换**（导航/广告/侧栏全保留），默认上限 20 万字符——token 黑洞。本插件只返回模型真正需要的：**净化后的正文 + 必要元数据**，并默认截断。 ### 同类插件对比（2026-08-15 实测源码/文档） | 能力 | 官方 `tool-web` web_fetch | dsh-webfetch | dsh-scrape-webpage | **dsh-read-url** | |---|---|---|---|---| | 正文净化（容器级提取） | ❌ 整页渲染 | ⚠️ 标签级去噪，nav/footer 仍混入 | ⚠️ 自研，含噪音 | ✅ article/main 容器 + 噪音剥离 | | 默认输出上限 | 200000 字符 | 50000 字符 | 30000 字符 | **6000 字符 + 段落级截断** | | 中文 GBK/GB2312 | 视 provider | ⚠️ 未归一化，GB2312 易乱码 | ❌ 未处理 | ✅ 归一化 + 乱码回退 + UTF-16 BOM + Shift-JIS | | JSON / RSS / Atom URL | ❌ 仅 HTML | ❌ | ❌ | ✅ 原生紧凑渲染 | | 分页长文 | ❌ 需逐页手动调用 | ❌ | ❌ | ✅ 自动拼接（默认 3 页） | | 会话级缓存 | ❌ | ❌ | ❌ | ✅ 5 分钟 TTL | | 走 `ctx.web` seam | ✅ 官方本体 | ❌ 全局 fetch | ❌ | ✅ 优先 seam，缺失回退 | | `ctx.effect` 卸载清理 | ✅ | ❌ | ❌ | ✅ | | 协作式超时（不暴露给模型） | ✅ | ⚠️ 自管 | ⚠️ 自管 | ✅ `timeoutMs` + `exec.signal` | | 模型视角输出 | 整页 Markdown | 紧凑文本 | 15 字段 JSON | **紧凑文本（无需解析 JSON）** | | 依赖 | 官方 | TS 需构建 | 零依赖 | 核心零运行时依赖（JS ESM 即装即用） | | 反爬/降级响应（UA 与 TLS 指纹） | ⚠️ Node 默认 UA，实测 https 被中间设备按 TLS 指纹拦截、百度返回无热搜的降级版 | ❓ 未披露 | ❓ 未披露 | ✅ 完整浏览器 UA，实测获取完整版页面（百度热搜正常） | > 2026-08-16 实测（本机环境）：停用本插件后用官方 `web_fetch` 读 `https://www.baidu.com`——TLS 握手被中间设备按程序指纹拦截（退回 http 才成功），且百度对 Node UA 返回**服务端降级版**（热搜词条改由 JS 异步加载，静态 HTML 不含）；换回 `dsh-read-url` 后 https 正常、热搜完整可读。差异根因：请求的 UA 与 TLS 特征决定网站/中间设备是否按 bot 处理。 ## 遵循 DSH 架构理念 按官方文档实现（`docs/capability-seams.md`、`docs/cordis-primer.md`、`docs/tool-execution-pipeline.md`）： 1. **网络访问走 `ctx.web` 能力缝**——读取、跳转与爬取使用 `ctx.web.fetch({ url }, signal)` 及解码后的 `body.kind/content`；服务或提供方不可用时回退直连。提供方 HTTP 错误与策略拒绝保留为错误。可选的 profile 配置 `directFetchOrigins` 为可信来源选择显式直连； 2. **可逆副作用**——会话缓存注册在 `ctx.effect` 下，插件卸载即自动清理（时间可组合性）； 3. **协作式工具调用超时**——`ToolDefinition.timeoutMs` 声明预算，`execute(args, exec)` 把 `exec.signal` 转发给 fetch，超时策略由管线强制执行，不把超时暴露给模型； 4. **模型视角精简**——render 输出紧凑文本（`title:` 头部 + 正文），模型直接消费，无需解析 JSON；默认参数最省 token，结构化能力按需开启； 5. **并行工具调用**——4 个工具全部声明 `isConcurrencySafe`（v1.1.0 起）：共享状态（会话缓存 / 解码器缓存 / SPA 浏览器 page 隔离）均满足交换性安全，agent loop 可把多个 read_url 调用归入并行池——多源阅读任务的墙钟时间按最慢一站计，而非各站之和。 ## 安装 ```bash # 从 GitHub（推荐，便于更新） npx @deepseek-ai/dsh plugin --profile web add github:2672243194/dsh-read-url # 本地开发 npx @deepseek-ai/dsh plugin --profile web add ./dsh-read-url ``` 重启 DSH（Web/TUI）后，设置 → 插件列表应看到 `dsh-read-url` 已启用。 ## 使用 直接对话： ``` 帮我读一下 https://example.com/article 并总结要点 用 markdown 格式读 https://docs.example.org/guide 同时读一下这几个网址，对比它们的观点： ``` ### 真实案例（实测数据） **1. 省 token——只返回模型真正需要的内容** 门户页 `read_url` 返回按 `maxChars`（默认 6000）截断的干净正文——不是带导航/广告/页脚的原始页面。重复读取命中 5 分钟会话缓存（`(cached)`），模型不会重复抓取： ``` title: 新闻中心首页_新浪网 charset utf-8 (chars 800/12398 — 截断，offset 续读) ``` **2. 海外站——直连 + 代理并发竞速** 检测到代理时，直连与代理 `curl` 同时发起、先完成者胜。原本被墙的海外站（直连超时 + 回退约 11s）现在 1 秒内读到： ``` BBC 中文: OK (633ms) — 4000+ 字符干净头条新闻 ``` **3. 长文续读（`offset`）** 1.2 万字符的文章分片读取，`offset` 从缓存续读且不重复前文——模型上下文只保留需要的部分： ``` chars 800+800/12398 · cached ``` **4. 跨页批量研究** `read_url_batch` 并行读最多 10 页（并发 4），逐页净化、失败隔离： ``` 读取 2/4 页成功，2 页失败 --- 阮一峰的网络日志 (491 字符) --- --- Example Domain (127 字符) --- [失败] https://zh.wikipedia.org/... — Fetch failed: HTTP 403 ... ``` ### 工具 **`read_url(url, maxChars?, offset?, mode?, includeLinks?)`** — 抓取并提取干净正文。支持 HTML 网页、JSON 接口（紧凑重排渲染）、RSS/Atom 订阅源（条目列表 + `feedCount`）；分页长文（小说/新闻/论坛）自动拼接至 `paginateMax` 页；页面元数据（`published`、`author`）自动提取——**meta → JSON-LD → 正文署名行 三级兜底**（v1.3.0 起解析 schema.org JSON-LD，新闻站发布时间/作者显著补全）；`` 壳页（链接跳板 / 反盗链中转 / 无 JS 的 SPA 入口）自动跟随到真实页（最多 3 跳、防循环、失败保留原页不报错，v1.3.0）；声明 `` 的框架/老论坛页，页面内相对链接按 base 解析（v1.3.0） | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | `url` | string | 必填 | http(s) URL | | `maxChars` | number | 6000 | 返回正文最大字符数（500–20000） | | `offset` | number | 0 | 从该字符偏移续读（长文续段，命中缓存不重复前文） | | `mode` | string | `text` | `text` = 纯文本（最省 token）；`markdown` = 结构化 | | `includeLinks` | boolean | `false` | 额外返回页面内最多 20 条链接（标题+URL） | **`read_url_batch(urls, maxChars?, mode?, includeLinks?)`** — 批量读多个 URL（1–10 个），并行、逐页净化，合并成一个紧凑报告 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | `urls` | string[] | 必填 | http(s) URL 列表（1–10 个） | | `maxChars` | number | 3000 | 每页返回正文最大字符数（500–20000） | | `mode` | string | `text` | `text` = 纯文本；`markdown` = 结构化 | | `includeLinks` | boolean | `false` | 每页额外返回链接（标题+URL） | - 并发 4 限制（防目标站限流），单页失败**不影响其他页**（结果里标注 `[失败]` + 原因）； - 复用 `read_url` 的全部能力与缓存：编码识别、正文净化、SPA 渲染、5 分钟缓存（重复批量读直接命中）。 **`read_url_site(url, maxPages?, maxDepth?, includeContent?, maxCharsPerPage?)`** — 整站递归爬取：从入口 URL 出发，BFS 发现同域名页面，返回紧凑站点地图 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | `url` | string | 必填 | http(s) 入口 URL | | `maxPages` | number | 15 | 最多尝试的页面数（2–50，含失败页面；小数向下取整） | | `maxDepth` | number | 2 | 最大链接深度（1–5） | | `includeContent` | boolean | `false` | 每页附短正文摘要（默认关——结构优先，省 token） | | `maxCharsPerPage` | number | 500 | includeContent 时每页摘要长度（200–2000） | - **只爬同域名**；登录/API/静态资源路径自动跳过；URL 去重（去 fragment）； - 并发 2 对目标站友好；单页失败记录 `[失败]` 不影响整体； - 输出为缩进树：`[深度] 标题 (字符数) URL`； - **不做 SPA 渲染**（整站是轻量批量抓取，渲染每页 1s+ 太慢）——SPA 页请用 `read_url` 单读。 **`read_url_links(url, limit?)`** — 只列出页面链接清单，不返回正文（更轻，适合找来源/摸站点结构） | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | `url` | string | 必填 | http(s) URL | | `limit` | number | 20 | 最多返回链接数（1–50） | ### 配置（可选） 通过 profile 的 `cordis.patch.yml` 覆盖（默认值见插件自带 `cordis.patch.yml`）： ```yaml - id: dsh-read-url config: timeoutMs: 15000 # 单请求超时（500-120000，自动钳制） maxBytes: 3145728 # 响应体上限（字节） maxChars: 6000 # 默认正文截断 maxLinks: 20 # read_url_links 默认条数 spaRender: true # SPA 渲染增强（需 playwright 已安装，未装自动降级提示） paginate: true # 分页长文自动拼接 paginateMax: 3 # 每篇最多拼接页数，含首页（1-10，自动钳制） userAgent: '...' # 请求 UA cacheTtlMs: 300000 # 成功缓存 TTL cacheMax: 32 # 缓存条目上限 ``` 配置在加载时统一强转数字并钳制到合理范围——YAML 里加引号的数字也能用，非法值回退默认。 #### 显式直连来源（v1.9.0） `directFetchOrigins` 默认为 `[]`。对于可信的本地反向代理（例如通过 hosts 文件映射 GitHub 域名），在插件的 **profile 配置**中显式列出来源，再重载插件/profile： ```yaml - id: dsh-read-url config: directFetchOrigins: - https://github.com - https://api.github.com - https://raw.githubusercontent.com ``` 命中的来源立即直连，跳过宿主 web provider **及其 SSRF 检查**。仅添加你信任的来源；其 DNS/hosts 映射到本机或私有地址也会被允许。此选项不开放为工具参数。未列出的初始 URL 保留既有 provider 选择与回退行为；provider 拒绝不会自动启用此例外。 按 URL 规范化后的协议、域名、端口精确匹配，子域名需单独配置。最多 32 项，每项不超过 2,048 字符。仅接受 HTTP(S) origin，可带一个结尾 `/`；凭据、路径、查询、片段、通配符和歧义写法都会触发配置错误。此选项与数字选项不同，非法项不会静默回退默认值。 请求选用显式直连后，后续 HTTP 重定向、meta-refresh、分页及爬取子页面均限制在列表内；provider 内部处理的跳转仍属于 provider 路径。直连每次尝试最多跟随 5 次 HTTP 重定向，遇循环提前停止。越界目标在发请求前停止；被此策略阻止的刷新跳转或分页保留可读的静态结果并附提示。显式直连不使用插件的 curl 代理竞速或 SPA 渲染，防止它们扩大例外范围；启用 `spaRender` 且 `read_url` 或 `read_url_links` 原本需要渲染脚本空壳时，会提示仅能静态读取。取消、正文大小限制及一次有界 Retry-After 重试继续生效。四个工具统一遵守此策略；成功与失败缓存按完整规范化列表隔离，修改或清空列表后不会误用旧策略的结果。 受控 HTTP 服务与 provider 桩覆盖默认拒绝、显式直连、重定向、分页、四工具、缓存隔离、取消、超时及正文上限。 ### 输出结构（紧凑） ```json { "url": "...", "title": "...", "siteName": "...", "lang": "zh-CN", "charset": "gbk", "mode": "text", "truncated": true, "charsTotal": 12990, "charsReturned": 6000, "charsStart": 0, "text": "……", "rendered": true, // 仅 SPA 渲染后提取时出现 "paginated": 3, // 自动拼接的页数（仅 > 1 时出现） "feedCount": 20, // RSS/Atom 条目数（仅订阅源） "published": "2026-08-01", // 页面声明了发布时间时（含署名行兜底） "author": "……", // 页面声明了作者时（含署名行兜底） "links": [] // 仅 includeLinks=true 时 } ``` ### PTC 模式 输出是纯 JSON、可组合，PTC 模式下一次编排多 URL 并行读取： ```ts const results = await Promise.all([ read_url({ url: 'https://a.example.com', maxChars: 4000 }), read_url({ url: 'https://b.example.com', maxChars: 4000 }), ]) ``` ## 省 token 设计（核心） 1. **默认只给正文**——不返回 headings/keywords/images/字数统计等冗余字段，需要时按参数取； 2. **段落级智能截断 + offset 续读**——默认 6000 字符（约 3000 token），在段落边界截断保证语义完整（text 模式段落以 `\n\n` 分隔，切口落在真实段落边界而非句中），输出行仅一行 `(chars 6000/12990 — 截断，offset 续读)` 引导；续读从指定偏移开始、命中缓存切片，**不重复返回已读前文**（实测 0+500 → 500+500，无重复）；offset 越界返回空而非重复开头； 3. **URL 片段定位阅读（v1.4.0）**——`url#section-anchor` 直接定位长文档目标小节：容器锚点精确切块（深度计数平衡提取）、标题锚点从该处起读；cache key 保留 fragment 保证 `#a`/`#b` 互不串页，offset 相对小节起点。实测 python-docs `#str.startswith`：**235,393 → 111,587 字符（-52.6%）**，默认 6000 字符窗口直接落在目标方法而非文档头； 4. **隐藏元素与同意弹窗剥离**——有界属性解析识别 `hidden`、`aria-hidden="true"`、`display:none`、`visibility:hidden` 和 `visibility:collapse`，按标签深度完整移除嵌套容器；class 按词段匹配，保留论坛、下载说明与高亮代码；属性支持单双引号、无引号值和等号两侧空格； 5. **元数据三路兜底（v1.5.0）**——发布时间合并链 `article:`/`og:` meta → JSON-LD → `