dsh-read-url

dsh plugin --profile web add dsh-read-url

dsh-read-url

🌐 [English](README.md) | 中文



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 行，保留省略行数提示。

为什么做它

本插件控制 URL 阅读的输出量：从 HTML 提取净化后的正文 + 必要元数据，提供段落截断、续读和会话缓存；也保留 DSH 配置的提供方返回的纯文本或 Markdown。DSH 0.2.1-rc.2 已包含 DeepSeek Fetch API 提供方，可获得的原文和元数据取决于所选提供方。

同类插件对比（2026-08-15 实测源码/文档）

以下是历史快照，不代表新版 DeepSeek Fetch API 提供方的行为。

能力 · 官方 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 调用归入并行池——多源阅读任务的墙钟时间按最慢一站计，而非各站之和。

安装

DSH 桌面版

打开 插件 → 添加插件，输入 dsh-read-url（npm 包名）、GitHub 仓库地址或本地项目目录后安装。在插件详情检查版本，以及组件是否显示 运行中。

桌面版使用独立的 desktop profile 和内置 DSH 运行时。CLI 各 profile 的安装及全局 CLI 升级与桌面版分别管理。手动配置本插件时，应使用桌面 profile 的 cordis.patch.yml。本地目录安装会链接源目录，修改代码后应重启桌面版，以加载新的模块。

CLI / 本地开发

# 从 GitHub 安装到 web profile
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
同时读一下这几个网址，对比它们的观点：<url1> <url2> <url3>

真实案例（实测数据）

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，新闻站发布时间/作者显著补全）；<meta http-equiv="refresh"> 壳页（链接跳板 / 反盗链中转 / 无 JS 的 SPA 入口）自动跟随到真实页（最多 3 跳、防循环、失败保留原页不报错，v1.3.0）；声明 <base href> 的框架/老论坛页，页面内相对链接按 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–200

…(truncated)