@khorsheed/dsh-reader 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,68 @@
 # @khorsheed/dsh-reader
 
-**灵感空间**：右侧栏一个**页面型 tab**，把 RSS/Atom 订阅和随手粘贴的文章链接收在同一面「灵感墙」上。点卡片在 dsh 里直接读正文（可划选引用），正文受宿主抓取上限截断时明说「内容未完整呈现」并给一个去原文的按钮。
+[English](README.en.md) | 中文
 
-> 包名、tab kind、Remote namespace 都还是 `reader` —— 它们是稳定标识（改了等于改部署的 loader 行和落盘目录），「灵感空间」是**用户看到的名字**。
+RSS 订阅和随手粘来的文章链接收在同一面墙上——点开就在 dsh 里读，划选就能引用进对话。
+
+刷到的论文和文章散落在浏览器标签页里，想喂给 agent 还得复制粘贴。这个插件在右侧栏加一个页面型 tab「灵感空间」：订阅源每天按点自动刷新，链接粘进来就存成卡片；正文在 dsh 里直接渲染成可读文本（能划选引用、能用浏览器自己的端上模型翻成中文），抓不全或站点拒抓都如实标明，绝不给一堵看起来正常、实则空心的墙。
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/reader-1.png" width="640" alt="灵感空间的墙:订阅与保存链接的卡片流,表头一行是筛选、排序、整墙翻译、刷新、设置与新增,搜索框独占一行">
+
+## 特性
+
+- **一面墙收齐订阅和链接**——RSS/Atom 订阅与粘贴的单篇文章同墙排列；文字搜索按相关性排（标题完全命中 → 标题包含 → 其它字段命中），筛选（未读 / 按来源 / 按类型 / 按标签）与搜索共用同一套本地谓词、不花请求；**转载去重默认开**（同条目 id / 归一化链接 / 折叠标题 + 同一发布日三层归并，任一命中即同组），幸存卡带「N 个重复来源」徽章；读者自建标签随打随用，在筛选弹层里也能删。
+- **点卡片就在 dsh 里读正文**——正文抽取为 DOM 文本（这正是划选引用能工作的原因）：去掉与标题重复的站头，还原懒加载图片（`data-src` / `srcset` / `<picture>` / `<noscript>`）与 base64 内联真图，公式以原生 MathML 渲染，arXiv 的 LaTeXML 矢量图保留；页面脚本画的图抓不到画面，但图注保留在正文里并另给一行说明。被宿主抓取上限截断时显示「受限篇幅，内容未完整呈现」+「阅读原文」。
+- **端上翻译，模型不出设备**——用浏览器自己的 Translator API（Chrome 138+ / Edge 148+ 桌面版），不花 token、不联网；翻译单元是**句子**，点一句只展开那一句的原文；三档视图（只看译文 / 双语对照 / 只看原文）。详情页与整面墙各有一个翻译开关，墙上逐字段判语言、绝不中译中。没有这个 API、语言对不可用、或正文本来就是中文时，地球按钮干脆不出现。
+- **译文落盘，重开零成本**——句子对写在宿主侧（全局句子记忆 + 按条目的段落映射，共享 64 MB 预算、按最近使用淘汰、无 TTL），刷新后点一下地球，整篇从磁盘重绘，模型一个请求都不发。
+- **抓取跑在宿主上**——卡片上的状态药丸（灰 = 未抓 / 蓝 = 抓取中 / 绿 = 已有全文 / 红 = 失败）点一下就开始，随后可以立刻离开页面：原始网页先落宿主磁盘，下次打开由浏览器半抽出正文。全文**自动补齐**（每次刷新最多 8 条、同时最多 2 个请求、失败 6 小时内不重试）；feed 自己发布全文的条目第一次打开零请求缓存。
+- **粘进来就知道是什么**——是 feed 就建订阅、是网页就存单篇；arxiv 的 abs/pdf 链接自动升级官方 HTML 版；DOI 链接先解析成 arXiv 版再落地；OpenReview 直接存「仅链接」并写明原因；抓不到的地址也一定存下来，原因分档写在卡片上（反爬 / 需要登录 / 不是网页 / 跨站跳转 / 连不上 / HTTP 错误）。
+- **引用进对话**——正文是应用级选区，`@khorsheed/dsh-quote` 的浮层菜单天然覆盖它；详情页另有「引用」（选区 + 来源标签经官方输入机合入当前会话草稿，读现有草稿合并、绝不覆盖、绝不发送）与「引用到侧边对话」（组合里真有 `sideChat` 服务时才显示）。
+- **订阅管理与最近阅读**——管理页里每个源一行：名称与订阅地址就地编辑、单独刷新、暂停/恢复、删除，缓存策略（正文保留时长、译文预算、清空译文缓存）与存储读数同页；「最近阅读」落盘 100 条、重启还在，滚出 feed 窗口的条目也能接着读。
+- **离开再回来接着读**——打开的文章、按内容锚定的阅读位置（第几个块、块内第几个字符）、墙上的筛选与译文，跨 dsh 会话由整个页面记住；位置另写 `sessionStorage`，页面重启后仍在原处。
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/reader-2.png" width="640" alt="详情页:正文以 DOM 文本渲染,地球开关点亮后按句对照翻译,点一句展开该句原文">
+
+## 安装
 
-抓取在**宿主半**完成（走 `ctx.web` 这条官方出网缝），浏览器半只做解析和渲染；订阅清单与最近一次抓回的原始 payload 落在 `$DSH_HOME/state/dsh-reader/state.json`（用 `node:fs` 原子写，**不走 `ctx.fs`** —— 那是按会话策略上锁的沙箱文件系统，见下方 Compatibility），每日按点自动刷新（插件自带 `setTimeout`，不是宿主服务）。
+```sh
+dsh plugin --profile web add @khorsheed/dsh-reader
+```
 
-## 三个面
+装完重启 web 实例后生效。卸载：
+
+```sh
+dsh plugin --profile web remove @khorsheed/dsh-reader
+```
+
+落盘只有一处目录：`$DSH_HOME/state/dsh-reader/`——`state.json`（订阅清单 + 最近 payload + 读者自己的标签与「最近阅读」记录）与 `bodies/`（超过 256 KiB 的正文各占一个文件；全局翻译记忆是其中的 `translation-memory.json`，超过阈值的条目译文映射也各占一个文件）。卸载后这个目录会留下——想彻底清干净就删掉整个 `dsh-reader/`。
+
+## Compatibility
+
+- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 可用，一处设计内降级——`sidebar.right.pane.tab` 座位、`ctx.web.fetch` 出网缝在 0.1.5-rc.1 上完整；应用内 Sidebar Browser 出口（脚本插图提示、反爬卡片的动作）需要 0.1.6-alpha.2+ 的 `browser` 右栏 tab 类型，0.1.5 宿主上退化为普通外部链接。minHost `0.1.5-rc.1`；本插件不做 preset 自隐（不需要 `pluginInventory`）。
+- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）。
+
+注意：宿主抓取缝默认把解码后的正文截到 100,000 字符且**静默截断**——这是部署配置可以抬升的上限（见「实现原理 · 抓取缝与存储」里的 patch 叠加层写法），不是插件的正文预算。
+
+## 已知限制
+
+- **只订阅、不爬全文**——新增订阅只抓 feed 本身，不会为每条目预抓正文（存储会爆，而且那是在当爬虫）；全文由自动补齐每次刷新补一片，或点开某条时就地抓一次。
+- **PDF 与其它非网页文件没有正文**——宿主的出网缝只认 `text/html`、`text/*`、`application/json`、`application/xml`，`application/pdf` 会被直接拒绝；而正文提取本来就是 DOM 的，PDF 没有 DOM。所以 PDF 链接只能存成「仅链接」的卡片 + 「阅读原文」，本插件不是 PDF 阅读器。
+- **跨站跳转不跟随**——宿主缝只报目标 origin、不报路径，所以换了主机的跳转（短链、ezproxy 之类的代理）一律如实报「跳到另一个站点」，不会跟过去猜。
+- **未读圆点不落盘**——未读标记是会话级状态，刷新或重启后全部回到未读。
+- **翻译只在 Chrome 138+ / Edge 148+ 桌面版可用**——Safari、Firefox、移动端没有 Translator API，这些浏览器里地球按钮不出现，其余功能不受影响（这是刻意的选择：一篇 5 万字符的长文走宿主 LLM 是几万 token + 十几秒 + 把文章再发给模型服务一次；端上翻译零成本、秒级、不出设备，质量是网页翻译级的 NMT）。
+- **超大文章抽不全**——宿主缝默认 100,000 字符上限（实测：Anthropic 研究页 ~266k、theverge.com ~899k、newyorker.com ~1.97M 字符），超限文章显示「受限篇幅」提示 +「阅读原文」；需要全文时由部署方抬升宿主缝上限，插件自己不会绕开宿主的出网策略。
+
+## 实现原理
+
+<details>
+<summary>各个面（灵感墙 / 详情 / 翻译 / 新增 / 订阅管理 / 最近阅读，点击展开）</summary>
+
+> 包名、tab kind、Remote namespace 都还是 `reader` —— 它们是稳定标识（改了等于改部署的 loader 行和落盘目录），「灵感空间」是**用户看到的名字**。
 
 | 面 | 内容 |
 | --- | --- |
 | 灵感墙 | **内容优先**：第一屏就是条目卡片流。**搜索框独占一行、铺满整行宽度**，筛选 / 排序 / 整墙翻译三个控件都移到**表头那一行**（和刷新、设置、加号在一起）——搜索框夹在三个按钮之间时，窄侧栏里连自己打了什么都看不全；每个弹层仍然挂在**打开它的那个按钮**下面，不会盖住另一个按钮。**文字搜索按相关性排**：标题完全命中 → 标题包含 → 其它字段命中，同一档里才用你选的排序（`#源id` / `@标签id` 这类选择器不参与排序），所以「搜一个标题却先出来别的」不再发生；搜索生效时底部还会写明**匹配了多少条**（`匹配「X」N 条`），列表有没有被筛过一眼可见。筛选是一个**两级弹层**，按「阅读状态」（未读）、「按来源」、「**按类型**」（订阅源 / 保存的链接）、「按标签」四种方式收窄墙：根页是阅读状态两行（只看未读、**隐藏重复**）、`按来源` 钻取行（那一行带着**当前值**，所以不存在「被藏起来的状态」）和类型三行。**隐藏重复默认开**：同一篇文章被多个源转载时折成一张卡（三层归并，任一命中即同组：同条目 id——共享 guid 按设计共享抓取/已读/译文；链接归一化——剥协议/www/utm 类追踪参数；折叠标题 + 同一发布日；绝不模糊匹配），幸存卡带「N 个重复来源」徽章（悬停列出其它来源），读过一个副本整组即已读，底部注明隐藏了几条，自动补抓也不为被隐藏的副本花请求，点进去是来源页——独占弹层高度、自己滚动、来源超过 6 个时出现自己的搜索框；**所以订阅再多，弹层第一页也恒定是几行**。筛选用的是和搜索同一套本地谓词（D14），所以不花请求，值就写在搜索框里（`#源id` / `#rss` / `#link` / `@标签id`）、看得见也能清掉——**搜索框里有内容时框内右侧出现一个 ×**，点它一次清空（筛选值和手输的关键词一起清）。**墙上也能整墙翻译**：工具条最右的地球（和详情页那个各自独立，共享同一份翻译记忆）。开启后**逐字段判语言**——中文标题/摘要原样保留、混合卡片只翻英文那一半，绝不中译中；只翻**进入过视口**的卡片（IntersectionObserver 喂队列、每批 6 张、按语言分组、沿用正文那套哨兵批量+校验+逐条兜底），滚回去不重复请求，进详情也不再翻一次标题。下拉两档：只看译文（**鼠标悬停在被翻译的文字上**时只把**那个字段**换回原文——标题换标题、摘要换摘要，卡片空白处/瓷贴/箭头一律不动，便于核对又不神经质）/ 双语对照（每个字段的原文常驻在译文下方，且**沿用该字段自身的排版**——标题原文就是标题字号与行高，靠墨色和字重与译文区分，不缩成小注）。**卡片文字盒是固定的**：标题与摘要各按两行预留高度并双向 clamp，所以译文/原文互换（hover 或对照）都不会改变卡片高度、网格不跳动；只有「双语对照」是显式切换、会让网格整体变高一次。条目卡片是**有底、有描边、12px 圆角的卡**：悬停只提亮不位移，键盘聚焦有环；未读条目标题上墨、瓷砖角上一个**圆点**（7px，会话级、不落盘），已读条目留在原位、只是安静一档；feed 自己的分类与读者自建标签共用同一套药丸尺寸（自建标签带描边、可折行），打标签按卡片上的「＋」打开面板——里面勾选已存在的标签，或**输入名字回车新建**（原生 datalist 已换成可样式化的行）；**标签在筛选弹层的「按标签」区可以删除**（每行右侧一个安静的 ×，删掉即从词表和所有条目上移除，正在用它筛选时收窄也一并清掉）。**保存的链接如果读不到正文，卡片上有一个「仅链接」小徽章**（虚线、安静），悬停与详情会说明原因（见下方「只能存链接的链接」）。**链接卡片的标题在正文解析出来后升级成文章自己的**（正文第一个 h1，否则文档标题；另带第一段实质文字当摘要），随正文写进宿主标注——正文被预算淘汰后卡片仍读这份记忆，一墙论文不用一篇篇点开。没有 `publishedAt` 的保存链接按**它的源加入时间**参与时间排序，所以刚加的那条在最上面，不会沉底。底部一行**新鲜度**：「刷出于 3 小时前 · 每日 10:00」，让你决定要不要按刷新 |
-| 详情 | 点卡片进来。正文以 DOM 文本渲染——**这正是划选引用能工作的原因**，也是这个面不放 iframe 的原因。正文**没有阅读量度**：侧栏给多宽就铺多宽，段落和列表共用同一条右缘。工具条：返回、**翻译（地球 + 视图下拉）**、复制链接、在浏览器打开原文，**单条保存的链接另有一个删除按钮**（订阅源的条目没有：下次刷新它还会回来，给「删除」是假承诺）；标题下的**标签行里还有「重新抓取」**（和卡片药丸同一个宿主动作，用它换一份新副本时会清掉这篇的译文记录——正文要换成新的 DOM）。正文下面列"同一来源"的其他条目。**页面用脚本画的插图抓不到**：这类 `<figure>` 在服务器 HTML 里只有一个空 div 和一句图注（实测 transformer-circuits.pub 这篇有 84 张），抓取不执行脚本，所以**图注保留在正文里**（它是页面发布的文字，写明了画的是什么），正文上方另给一行「这一页有 N 张插图由页面自己的脚本绘制，抓取时拿不到画面（图注保留在正文里）—— 阅读原文」（宿主有 Sidebar Browser 时这个出口开在应用内；未来 capture 包在场时这里还会出现「渲染抓取」——探测不到就不渲染）。**capture 渲染回来的图能进正文**：页面脚本绘制的图以「内联 SVG + 内联样式」到达，归一化按安全子集保留（形状/文字/defs/渐变/裁剪/symbol 复用；`script`/`foreignObject`/SMIL/事件/外部引用永不放行，`url(` 只许本文档片段）——而不是只剩图注。**组合图的结构同样保**：capture 渲染的组合图（图 + 样式盒搭的属性卡）在 figure 里保留 div/span 容器与白名单样式（布局/绘制属性；`position:fixed`、`z-index` 超限、外部 `url()`、脚本把戏全剥），而且任何被解包的块级容器都留下词边界——相邻文字绝不粘连。**但静态标记里就有 URL 的图会回收**：懒加载站点把真 URL 放在 `data-src` 等属性、`srcset`、`<picture>` 的 `<source>` 或 `<noscript>` 的 no-JS 兜底里（`src` 里只是 1px 占位图），抽取按这个顺序解析候选、取 srcset 里最大的一张；**反过来，把真图直接内联成 base64 data URI 的页面（transformer-circuits 一类）也保**——占位图与真图按载荷大小分道（阈值 512 字符，1px gif 约 70、真图表数千起），小的照旧当占位、穿透到懒加载属性，大的原样保留；正文输出的每个 `<img>` 都带 `referrerpolicy="no-referrer"`（防盗链的 CDN 否则直接 403）。**LaTeXML 的矢量图也保**：arxiv HTML 把图嵌成 `<object type="image/svg+xml" data="…">`，归一化把它改写成带原始宽高的 `<img>`；非图片的 object（PDF、视频）照旧整棵丢弃。**公式是原生渲染的 MathML**：arxiv HTML 版的 `<math alttext="…">` 按安全子集放行（`annotation-xml` 与任何脚本永不放行——前者是 HTML 注射通道），块级公式横向滚动而不是顶破排版 |
+| 详情 | 点卡片进来。正文以 DOM 文本渲染——**这正是划选引用能工作的原因**，也是这个面不放 iframe 的原因。正文**没有阅读量度**：侧栏给多宽就铺多宽，段落和列表共用同一条右缘。工具条：返回、**翻译（地球 + 视图下拉）**、复制链接、在浏览器打开原文，**单条保存的链接另有一个删除按钮**（订阅源的条目没有：下次刷新它还会回来，给「删除」是假承诺）；标题下的**标签行里还有「重新抓取」**（和卡片药丸同一个宿主动作，用它换一份新副本时会清掉这篇的译文记录——正文要换成新的 DOM）。正文下面列"同一来源"的其他条目。**页面用脚本画的插图抓不到**：这类 `<figure>` 在服务器 HTML 里只有一个空 div 和一句图注（实测 transformer-circuits.pub 这篇有 84 张），抓取不执行脚本，所以**图注保留在正文里**（它是页面发布的文字，写明了画的是什么），正文上方另给一行「这一页有 N 张插图由页面自己的脚本绘制，抓取时拿不到画面（图注保留在正文里）—— 阅读原文」（宿主有 Sidebar Browser 时这个出口开在应用内；未来 capture 包在场时这里还会出现「渲染抓取」——探测不到就不渲染）。**capture 渲染回来的图能进正文**：页面脚本绘制的图以「内联 SVG + 内联样式」到达，归一化按安全子集保留（形状/文字/defs/渐变/裁剪/symbol 复用；`script`/`foreignObject`/SMIL/事件/外部引用永不放行，`url(` 只许本文档片段）——而不是只剩图注。**组合图的结构同样保**：capture 渲染的组合图（图 + 样式盒搭的属性卡）在 figure 里保留 div/span 容器与白名单样式（布局/绘制属性；`position:fixed`、`z-index` 超限、外部 `url()`、脚本把戏全剥），而且任何被解包的块级容器都留下词边界——相邻文字绝不粘连。**但静态标记里就有 URL 的图会回收**：懒加载站点把真 URL 放在 `data-src` 等属性、`srcset`、`<picture>` 的 `<source>` 或 `<noscript>` 的 no-JS 兜底里（`src` 里只是 1px 占位图），抽取按这个顺序解析候选、取 srcset 里最大的一张；**反过来，把真图直接内联成 base64 data URI 的页面（transformer-circuits 一类）也保**——占位图与真图按载荷大小分道（阈值 512 字符，1px gif 约 70、真图表数千起），小的照旧当占位、穿透到懒加载属性，大的原样保留；正文输出的每个 `<img>` 都带 `referrerpolicy="no-referrer"`（防盗链的 CDN 否则直接 403）。**还有 403 之外的一种拦法**：源站回 `Cross-Origin-Resource-Policy: same-origin`（实测 claude.dev 的全部 `/media` 插图）时，浏览器跨源拿不到像素——直接抓明明 200，页面上却只有裂图加整句 alt。这种图改由宿主侧代抓（公共地址校验、连接钉死在已校验地址、每跳重验、8 MiB 上限、`image/*` 类型闸——宿主自己的 `ctx.web` 缝只给文本体，给不了二进制）：正文里加载失败的 `<img>` 会被改指到宿主取回的字节（data: URI），加载正常的图永不走这条代理，宿主也取不回来的保持裂图原样（「阅读原文」仍是出口）。**LaTeXML 的矢量图也保**：arxiv HTML 把图嵌成 `<object type="image/svg+xml" data="…">`，归一化把它改写成带原始宽高的 `<img>`；非图片的 object（PDF、视频）照旧整棵丢弃。**公式是原生渲染的 MathML**：arxiv HTML 版的 `<math alttext="…">` 按安全子集放行（`annotation-xml` 与任何脚本永不放行——前者是 HTML 注射通道），块级公式横向滚动而不是顶破排版 |
 | 翻译（浏览器本地） | 工具条上的**地球**是开关：点亮 = 正文显示译文。它右边的下拉三档：**只看译文**（默认，正文上方一条一次性提示说明「点任意一句可看原文，再点收起」）、**双语对照**（每段下方常驻原文小字，可整段折起）、**只看原文**。翻译单元是**句子**：点一句只展开那**一句**的原文（段落下、左侧细线 + 高亮），再点收起，可同时展开多句；**即使这句话中间夹着链接、被切成几段文本，展开的仍是完整的那一句**（不会显示成碎片），**原文那一行不是控件**（它是给选中引用用的文本，点它不收起；点句子才收起，而且**正在选区里的点击会被忽略**，所以拖选原文或译文都不会把展开的原文收掉）。英文原文按**正文级**排版（13.5px、secondary 墨色、行距 1.62、行间 3px）；它**按容器位置分别排边距**（段落旁：贴住所属段落，上 4px / 下 14px；列表项、引用、表格单元格里则在译文下方 5px，**不会被负边距拽上去贴住译文**），**已展开的那一句保留一条很细的下划线**（只有下划线，没有常驻底色/竖条——那是「这句绑定了下面那行原文」的安静标记）；配对高亮**只在 hover 时**出现：鼠标移到某句中文上，这一句（含被链接切开的各段）和它对应那一行原文一起高亮；移到原文行上同理反向。**默认不画任何底色或竖条** —— 试过的常驻标记会把整篇点成花的。**全程在浏览器里跑**（Chrome 138+/Edge 148+ 桌面版的 `Translator` API），模型不出设备、不花 token；**译文的句子对会落盘**（见下），地球开关与翻译会话不落——没有这个 API、语言对不可用、或正文本来就是中文时，地球**不出现**。**译文两层落盘**（`$DSH_HOME/state/dsh-reader`，与缓存正文同一目录、同一敏感级、同一个卸载故事）：全局**句子记忆**（按 `<源>→<目标>:<句子哈希>` 存原文+译文，5 万句上限）+ **按条目的段落映射**（哈希→译文，键在正文哈希上，正文小幅重抓后逐句复用仍在）；合计预算默认 64 MB（订阅管理页的缓存策略同一个动词可调），按「最近使用」跨两层淘汰，**没有 TTL**（重建一份译文要一次手势加逐句模型，不该按小时过期）。效果是：刷新后地球照样等那一下手势，手势之后整篇从磁盘重绘、模型不沾；句子在两份 schema 版本失配时读作 miss、惰性淘汰（浏览器模型升级后不会把旧译文当成新模型的产出） |
 | 新增（弹窗） | 表头加号、空态卡片、墙上尾部虚线卡片三处都能打开同一个**弹窗**（成员 tab 的邀请弹窗同款做法：透明遮罩 + 居中卡片，Esc / 点遮罩关闭），因为「新增」是个瞬时动作，墙没必要被它替换掉。粘进去的地址**存成什么由抓回来的内容决定**（D15）：是 feed 就建订阅，是网页就只存这一篇。**arxiv 的 abs/pdf 链接自动升级到官方 HTML 版**（`arxiv.org/html/<id>`，LaTeXML 生成的语义标记：真表格、真公式），HTML 版不存在（404）时回退到粘进来的地址照常走。**DOI 链接先解析成 arXiv 版再落地**（Crossref 取标题与作者 → arXiv 标题搜索 → 标题相似度 + 作者姓重合的双因子闸；配不上就回普通路径，绝不猜），命中时卡片标注来源 DOI；**OpenReview 链接不抓、直接存仅链接**（实测服务器端读不到：API 在 Cloudflare 挑战后、论坛是 JS SPA），原因和建议写在卡片上（有 arxiv 版就粘 arxiv 链接）。**抓不到也一定存下来**：判定从「成功 / 失败」改成「已保存 + 能不能预览」，原因分档写在弹窗里（反爬 / 需要登录 / 不是网页 / 跨站跳转 / 连不上 / HTTP 错误），对应的卡片标成「仅链接」——把读者粘的 URL 丢掉，比留一张只能打开原文的卡更坏 |
 | 订阅管理（页面） | 表头齿轮进入**订阅管理页**：顶部是一行**压缩设置**（每日刷新时间 + 正文保留并排，长说明收进悬停提示）与一行**存储区**（原文缓存读数「N 篇 · 体量」、译文缓存读数「M 篇映射 + S 句 · 体量」、**译文预算**输入（MB，blur/回车提交）、两步的**清空译文缓存**——读数是宿主聚合的，表本身不过线）与两排带小标题的**筛选片**（`按类型`：全部 / 订阅源 / 保存的链接，各带条数；`排序`：按添加时间 / 按名称 / 按抓取时间，默认添加时间倒序），下面每个源一行，**名称与订阅地址都可以就地编辑**（改地址 = 换一份文档，保存后立刻重抓，名称留空则回退成 feed 自己的标题）、类型、条目数、上次抓取时间、失败原因（按分类说人话，不是宿主缝原话）、单独刷新、暂停/恢复、删除，以及**每日刷新时间的配置**。这些问题是关于「源」而不是关于「内容」的，所以它们不在墙上 |
@@ -23,38 +74,37 @@
 
 **点击语义（定案方案 B）**：点卡片 = 进详情页。大多数阅读在 dsh 里完成；正文太长或想直接看原文时，详情页自己的按钮会跳浏览器。卡片尾部的箭头是"这里能进"的提示，不是控件。
 
-## 引用
-
-正文是应用级选区，所以 `@khorsheed/dsh-quote` 的浮层菜单**本来就覆盖它**——本插件不自己造选区菜单。详情页底部另有：
+**引用**：正文是应用级选区，所以 `@khorsheed/dsh-quote` 的浮层菜单**本来就覆盖它**——本插件不自己造选区菜单。详情页底部另有：
 
 - **引用**：选区（没选区就是整条）+ 来源标签，经官方输入机合成进当前会话草稿（读现有草稿合并，绝不覆盖、绝不发送）；
 - **引用到侧边对话**：只有组合里真有 `sideChat` 服务时才显示（能力握手说了算），否则这一项隐藏。
 
-`reader` 自带一个薄 typert Remote（namespace `reader`），verb：`capabilities` / `listSources` / `addSource` / `updateSource` / `removeSource` / `refresh` / `getBodies` / `quoteToSideChat`。宿主半**不解析** feed——解析在浏览器半，`getBodies` 只把原始 payload 交过去。
+</details>
 
-## 安装
+<details>
+<summary>内部机制（架构、抓取缝、翻译、存储，点击展开）</summary>
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-reader
-# 卸载：
-dsh plugin --profile web remove @khorsheed/dsh-reader
-```
+**架构。** 抓取在**宿主半**完成（走 `ctx.web` 这条官方出网缝），浏览器半只做解析和渲染：宿主半提供 `reader` 服务核心（`ctx.provide('reader')`）并挂出薄 Typert Remote 面（namespace `reader`），订阅清单与最近一次抓回的原始 payload 落在 `$DSH_HOME/state/dsh-reader/state.json`（用 `node:fs` 原子写，不走 `ctx.fs`，见下），每日按点自动刷新由插件自带的 `setTimeout` 驱动（宿主没有调度服务可骑）。浏览器半两段式注册右侧栏：先把自己铸造的 tab 类型 `reader`（实现 id `@khorsheed/dsh-reader`，带 guide 卡片）注册进 `sidebarRightTabs` 注册表，再经 `slots.inject('sidebar.right.pane.tab', …)` 把面板本体挂到 keyed 座位；中英文字典随插件注册；Remote 经 `ctx.remote.$mount` 自行挂载。feed 解析必然在浏览器半——宿主侧没有 XML/DOM 解析器（`globalThis.DOMParser === false`），`getBodies` 只把原始 payload 交过去。没有 `static inject`：每个可选能力（`fs`、`web`、`sideChat`、`browser` tab 类型、capture Remote）都在使用时探测，缺席即降级，绝不抛错。
 
-装完重启宿主。落盘只有一处目录：`$DSH_HOME/state/dsh-reader/`——`state.json`（订阅清单 + 最近 payload + 读者自己的标签与「最近阅读」记录）与 `bodies/`（超过 256 KiB 的正文各占一个文件；全局翻译记忆是其中的 `translation-memory.json`，超过阈值的条目译文映射也各占一个文件）。卸载后这个目录会留下——想彻底清干净就删掉整个 `dsh-reader/`。
+**状态为什么不走 `ctx.fs`**：`ctx.fs` 是**沙箱**文件系统，每一次写都由**调用会话**的文件策略把关；workspace-write 会话写 `$DSH_HOME/state` 会被拒（`FS_SANDBOX_DENIED`，验收实例上真实发生过）。这道栅栏本身是对的、要留着；错的是把「属于部署」的状态交给一个「属于会话」的能力。所以本包按仓库里其它宿主态包的写法（`packages/lab/src/state.ts`）用 `node:fs` 原子写（临时文件 + rename），目录不可写时降级为仅内存。
 
-## Compatibility
+**Remote 面。** namespace `reader`，verb 分组：源管理 `capabilities` / `listSources` / `addSource` / `updateSource` / `removeSource` / `refresh`；正文 `getBodies` / `getEntryBody` / `fetchEntryBody` / `storeEntryBody` / `getRawBody` / `entryFetchStates` / `listBackfillCandidates`；译文 `getEntryTranslation` / `getSentenceTranslations` / `rememberSentences` / `clearTranslations`；标签 `entryTags` / `listTags` / `createTag` / `tagEntry` / `renameTag` / `deleteTag` / `pruneTags`；阅读记录 `recordRead` / `listRecent` / `clearRecent`；缓存策略与读数 `getCachePolicy` / `setCachePolicy` / `getStorageStats`；以及 `quoteToSideChat`。宿主半**不解析** feed——解析在浏览器半。
+
+**来源名用 feed 自己声明的标题**：宿主半不解析 feed（它没有 XML 解析器），所以新建时只能给一个从 URL 推出来的名字（就是你看到的那串 `raw.githubusercontent.com/...`）。浏览器半解析出 `<channel><title>` 后会用真实标题替换显示名，所以卡片上会出现「Anthropic Research」这样的名字，失败时回退成 URL。列表里报错时显示「{count} 天前」这种占位符也是同一类问题的另一面（参数没被插值），已修。
 
-- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 完整——`sidebar.right.pane.tab` 座位、`ctx.web.fetch` 出网缝、`ctx.fs` 版本守卫写、`pluginInventory` 都不需要（本插件不做 preset 自隐）。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）
-- **状态为什么不用 `ctx.fs`**：`ctx.fs` 是本仓库的**沙箱**文件系统，每一次写都由**调用会话**的文件策略把关；workspace-write 会话写 `$DSH_HOME/state` 会被拒（`FS_SANDBOX_DENIED`，验收实例上真实发生过）。这道栅栏本身是对的、要留着；错的是把「属于部署」的状态交给一个「属于会话」的能力。所以本包按仓库里其它宿主态包的写法（`packages/lab/src/state.ts`）用 `node:fs` 原子写（临时文件 + rename），目录不可写时降级为仅内存。
-- **来源名用 feed 自己声明的标题**：宿主半不解析 feed（它没有 XML 解析器），所以新建时只能给一个从 URL 推出来的名字（就是你看到的那串 `raw.githubusercontent.com/...`）。浏览器半解析出 `<channel><title>` 后会用真实标题替换显示名，所以卡片上会出现「Anthropic Research」这样的名字，失败时回退成 URL。列表里报错时显示「{count} 天前」这种占位符也是同一类问题的另一面（参数没被插值），已修。
-- **翻译用的是浏览器自己的端上模型，不是宿主的模型**：`self.Translator`（Chrome 138+/Edge 148+，仅桌面版）在本机进程内翻译，所以**模型不出设备、不花任何 token、不联网**（首次按语言对下一次小语言包，`Translator.create()` 需要用户手势——点地球那一下正好是）。**译文的派生句子对会写到宿主侧**（`$DSH_HOME/state/dsh-reader` 下的全局句子记忆 + 按条目映射，默认 64 MB 预算按最近使用淘汰，无 TTL；敏感级与旁边缓存的正文相同，隐私论据从来是关于网络而不是磁盘）。代价是**只在 Chrome/Edge 桌面存在**：Safari、Firefox、移动端没有这个 API，插件就把地球藏起来，其余功能不受影响。这是刻意的选择：一篇 5 万字符的长文如果走宿主 LLM，是几万 token + 十几秒 + 把文章再发给模型服务一次；端上翻译是零成本、秒级、不出设备（质量是网页翻译级的 NMT，不是 LLM 级）。
-- **翻译单元是句子，不是段落，也不是文本节点**：先按句切好再发出去，配对是**构造出来的真**，不是事后猜的——段落级翻译拿回来是一整段，模型会合句拆句，再对齐就可能给你看错原文。批量发送时句子之间插哨兵，返回的段数对不上就把那一批退回「一句一请求」，**代价是粒度，永远不是正确性**。跨行内元素的句子（例如句中有链接）会变成两个单元，链接本身不动；`<pre>`/`<code>` 里的内容从不翻译。
-- **翻译器建不起来时不会假装**：`Translator.availability()` 只是**提示**，不是承诺 —— Chrome 上确实出现过「availability 说能用、`create()` 却抛 `NotSupportedError`（"Unable to create translator for the given source and target language"）」的情况（macOS 构建有同类记录）。所以插件会：① 源语言先问浏览器的 `LanguageDetector`（猜错源语言正会让某些语言对建不起来，而那条报错**不说是哪个语言对**）；② 目标语言按 `zh` → `zh-Hans` 两种写法依次真建一次；③ 全都以 `NotSupportedError` 拒绝时，**地球自行消失**并明说「这个浏览器无法翻译 en → zh / en → zh-Hans」，同时指向 `chrome://on-device-internals` 的 Broker State 自查；网络/配额这类**非永久**失败则保留地球以便重试，并报出尝试过的语言对与原因（浏览器原文里两个语言都不出现）。
-- **正文还原是逐字节的**：翻译只改文本节点（原文在内存里留着），「只看原文」和取消都能把正文还原成宿主发来的那份 HTML 原样。这也是为什么译文不会丢掉链接、图片、表格——它们根本没被碰过。
-- **有些站点拒绝自动抓取，界面会诚实地告诉你**：实测 `openai.com` 对**任何非浏览器请求都返回 403**（带代理、不带代理、换浏览器 UA 都一样，返回的是一个反机器人挑战页）。这不是抽取失败，也不是能靠重试解决的问题，所以详情页对 401/403 显示「这个站点拒绝自动抓取（原文地址对人以外的请求返回验证页）」而不是「无法提取正文」。**状态码不是唯一线索**：实测 `openreview.net` 的 PDF 链接是 `302 → /challenge?redirect=…` 然后 **200** 的挑战页——只看状态码会把挑战页当成文章存下来（这正是「加进去了但点开没内容」的根因）。所以判定是组合的：最终 URL 与请求 URL 是否变了、可见文本是否少到不像一页、以及反爬/登录页的痕迹词；命中任一条就不再存正文，改存「仅链接」。同类站点（newsletter 平台、付费墙）会有同样表现。这也是为什么浏览器渲染抓取不在本插件范围内：那条路需要 browser-pane，而它目前仍是 planned。
-- **有的 feed 只对部分文章给全文，其余只给摘要**：实测 OpenAI alignment feed 的 27 条正文从 **155 字符**（一句摘要）到 **62,044 字符**（全文）不等——这不是截断，是发布方就这么发的。**摘要不再被当成全文**：以前 feed 的 `<description>` 会被塞进 `contentHtml`，于是条目看起来「已经有正文」——自动补齐跳过它、点开也不再抓，详情页就把那 167 字的摘要当成整篇文章显示。现在解析器给这种条目打上 `summaryOnly`，**打开时照样就地抓一次真文章**（抓取期间正文上方写明「这条订阅源只发布了摘要 —— 全文在原文页面上」，抓到之后这句自动消失），自动补齐也把它列进待补清单。**重抓只在这篇还没有缓存正文时发生**：`summaryOnly` 是 feed 条目的属性、一旦为真就永远为真，所以以前这里会让已经抓过的文章**每次打开都重抓一次**（用同一份正文把 DOM 换掉，译文也就跟着没了）；现在只有屏上那段文字是 feed 自己给的（`fromFeed`）才触发抓取。
-- **宿主一次只交接 100,000 字符，所以超大 feed 只能读到一部分**：这是宿主出网缝的默认上限（`web-fetch-http` 的 `maxBodyChars`），**不是插件的正文预算**（插件自己的预算是单源 256 KB / 总量 2 MiB）。你那条 feed 有 646,905 字符，宿主只给前 100,000，所以 21 条里只有落在前面那部分的两条能读到。插件**无法**绕过它：`ctx.web.fetch` 只接受 `{ url }`，没有 Range、没有自定义请求头、没有分页，插件也不会为了绕过它去 vendor `fetch`（那等于绕开宿主的出网策略）。要让 646 KB 的 feed 完整可读，**不需要改宿主代码**：用官方的 patch 叠加层给那一行加 config 即可（`--patch <file>` 或机器级的 `$DSH_HOME/cordis.patch.yml`，后者对所有 profile 生效）：
+**翻译用的是浏览器自己的端上模型，不是宿主的模型**：`self.Translator`（Chrome 138+/Edge 148+，仅桌面版）在本机进程内翻译，所以**模型不出设备、不花任何 token、不联网**（首次按语言对下一次小语言包，`Translator.create()` 需要用户手势——点地球那一下正好是）。**译文的派生句子对会写到宿主侧**（`$DSH_HOME/state/dsh-reader` 下的全局句子记忆 + 按条目映射，默认 64 MB 预算按最近使用淘汰，无 TTL；敏感级与旁边缓存的正文相同，隐私论据从来是关于网络而不是磁盘）。
+
+**翻译单元是句子，不是段落，也不是文本节点**：先按句切好再发出去，配对是**构造出来的真**，不是事后猜的——段落级翻译拿回来是一整段，模型会合句拆句，再对齐就可能给你看错原文。批量发送时句子之间插哨兵，返回的段数对不上就把那一批退回「一句一请求」，**代价是粒度，永远不是正确性**。跨行内元素的句子（例如句中有链接）会变成两个单元，链接本身不动；`<pre>`/`<code>` 里的内容从不翻译。
+
+**翻译器建不起来时不会假装**：`Translator.availability()` 只是**提示**，不是承诺 —— Chrome 上确实出现过「availability 说能用、`create()` 却抛 `NotSupportedError`（"Unable to create translator for the given source and target language"）」的情况（macOS 构建有同类记录）。所以插件会：① 源语言先问浏览器的 `LanguageDetector`（猜错源语言正会让某些语言对建不起来，而那条报错**不说是哪个语言对**）；② 目标语言按 `zh` → `zh-Hans` 两种写法依次真建一次；③ 全都以 `NotSupportedError` 拒绝时，**地球自行消失**并明说「这个浏览器无法翻译 en → zh / en → zh-Hans」，同时指向 `chrome://on-device-internals` 的 Broker State 自查；网络/配额这类**非永久**失败则保留地球以便重试，并报出尝试过的语言对与原因（浏览器原文里两个语言都不出现）。
+
+**正文还原是逐字节的**：翻译只改文本节点（原文在内存里留着），「只看原文」和取消都能把正文还原成宿主发来的那份 HTML 原样。这也是为什么译文不会丢掉链接、图片、表格——它们根本没被碰过。
+
+**有些站点拒绝自动抓取，界面会诚实地告诉你**：实测 `openai.com` 对**任何非浏览器请求都返回 403**（带代理、不带代理、换浏览器 UA 都一样，返回的是一个反机器人挑战页）。这不是抽取失败，也不是能靠重试解决的问题，所以详情页对 401/403 显示「这个站点拒绝自动抓取（原文地址对人以外的请求返回验证页）」而不是「无法提取正文」。**状态码不是唯一线索**：实测 `openreview.net` 的 PDF 链接是 `302 → /challenge?redirect=…` 然后 **200** 的挑战页——只看状态码会把挑战页当成文章存下来（这正是「加进去了但点开没内容」的根因）。所以判定是组合的：最终 URL 与请求 URL 是否变了、可见文本是否少到不像一页、以及反爬/登录页的痕迹词；命中任一条就不再存正文，改存「仅链接」。同类站点（newsletter 平台、付费墙）会有同样表现。
+
+**有的 feed 只对部分文章给全文，其余只给摘要**：实测 OpenAI alignment feed 的 27 条正文从 **155 字符**（一句摘要）到 **62,044 字符**（全文）不等——这不是截断，是发布方就这么发的。**摘要不再被当成全文**：以前 feed 的 `<description>` 会被塞进 `contentHtml`，于是条目看起来「已经有正文」——自动补齐跳过它、点开也不再抓，详情页就把那 167 字的摘要当成整篇文章显示。现在解析器给这种条目打上 `summaryOnly`，**打开时照样就地抓一次真文章**（抓取期间正文上方写明「这条订阅源只发布了摘要 —— 全文在原文页面上」，抓到之后这句自动消失），自动补齐也把它列进待补清单。**重抓只在这篇还没有缓存正文时发生**：`summaryOnly` 是 feed 条目的属性、一旦为真就永远为真，所以以前这里会让已经抓过的文章**每次打开都重抓一次**（用同一份正文把 DOM 换掉，译文也就跟着没了）；现在只有屏上那段文字是 feed 自己给的（`fromFeed`）才触发抓取。
+
+**宿主一次只交接 100,000 字符，所以超大 feed 只能读到一部分**：这是宿主出网缝的默认上限（`web-fetch-http` 的 `maxBodyChars`），**不是插件的正文预算**（插件自己的预算是单源 2 MiB / 总量 12 MiB，见 `MAX_BODY_CHARS_PER_SOURCE`）。你那条 feed 有 646,905 字符，宿主只给前 100,000，所以 21 条里只有落在前面那部分的两条能读到。插件**无法**绕过它：`ctx.web.fetch` 只接受 `{ url }`，没有 Range、没有自定义请求头、没有分页，插件也不会为了绕过它去 vendor `fetch`（那等于绕开宿主的出网策略）。要让 646 KB 的 feed 完整可读，**不需要改宿主代码**：用官方的 patch 叠加层给那一行加 config 即可（`--patch <file>` 或机器级的 `$DSH_HOME/cordis.patch.yml`，后者对所有 profile 生效）：
 
 ```yaml
 - id: web-fetch-http
@@ -62,29 +112,33 @@ dsh plugin --profile web remove @khorsheed/dsh-reader
     maxBodyChars: 2000000   # 默认 100000
 ```
 
-已用 `dsh --profile web --patch <file> --dump-config` 实测确认合成结果里带着这个值；3080 上已按此加上覆盖并实测：同一条 feed 由「100,000 字符 / 截断 / 2 条」变成「**646,905 字符 / 未截断 / 21 条完整**」。**2026-09-19 又抬了一档**：研究类文章本身就很大——实测 `transformer-circuits.pub` 的 emotions 那篇 HTML 有 **41.8 MB**（60 张插图是内联 base64），而宿主缝的**字节上限** `maxResponseBytes` 默认只有 5 MB，整次抓取会直接失败（`response exceeds the maximum of 5000000 bytes`），`maxBodyChars` 也挡在前面。现在 3080 的部署配置把**两个上限一起抬到 64 MB**，并把**抓取超时从默认 30 秒抬到 180 秒**（同一篇实测直连 19.5 秒，机器一忙以前就会以 `web fetch timed out` 失败；见 `$DSH_HOME/profiles/web/cordis.patch.yml`）。代价是**全机**每次抓取的峰值内存与传输量都随之上升。注意**插件自己的单源预算必须 ≥ 宿主上限**，否则落盘时会再切一刀——本包的预算是 2 MiB/源、12 MiB/总量（见 `MAX_BODY_CHARS_PER_SOURCE`）。注意边界：插件的 patch 只能挂**自己那一行**（仓库禁止插件去挂/改别人的行），所以这条覆盖属于**部署配置**，由部署方决定；而且它抬高的是**全机所有网页抓取**的上限。
-- **全文是自动补齐的，不需要你点**：每次加载后，宿主给出"还缺全文"的条目清单（一次最多 8 条，失败的条目 6 小时内不再重试），浏览器半条一条抓取+抽取并写入缓存（24 小时，管理页可改），**同时最多 2 个请求**。补齐中的条目仍在墙上显示 feed 自己给的内容，底部一行进度「正在补齐全文 3/8…」；抓到的卡片标一个「已抓全文」（徽章的含义是：卡片上仍是 feed 自己的摘要，全文已经缓存好了，点开就能读）。**不确定要不要等？直接点开那一条**：打开时若本地还没有正文，它会就地抓一次并显示「正在抓取正文…」，不必等补齐轮到它。
-  - 为什么不是"全部一次抓完"：那等于把每个订阅源的所有文章都爬一遍。这里是**每次刷新补一片**，滚动前进。
-  - **抓不到就展示已有的**：站点拒绝（401/403）、连不上、抽取失败，三种情况分开说明，正文位置永远显示 feed 自己发布的内容 + 「阅读原文」，绝不空白。
-- **被宿主截断的 feed 会抢救，而不是整份丢掉**：宿主缝按字符数截断，截在标签中间会让整份 XML 不合法——而"整份不合法"曾经等于**一条都没有**。现在解析器会：完整闭合的 `<item>`/`<entry>` 全部保留（用文档根上的命名空间声明重新包装，否则带 `content:encoded` 前缀的片段自己也是坏 XML）；被截断的那条尽最大努力修复并标成**部分**，正文照常显示已经拿到的部分；墙上给一行「未完整」说明 + 阅读原文。配一个提交在仓库里的 fixture（`tests/fixtures/feed-truncated.xml`）锁住这个形状。
-  实测：验收实例那条 646 KB 的 feed（宿主只给 100,000 字符）现在能出 **2 张卡**——一张完整的 42 KB 正文，一张部分正文——而在这次修复前是 **0 张**。
-- **默认过滤是「全部」而不是「今日」**：RSS 源的最新条目经常不是今天的（验收实例那条 feed 最新一篇是 8 天前），默认「今日」会让刚订阅完的墙看起来像空的 —— 也就是「订阅成功了但什么都没有」。现在**没有「今日」这个过滤**：收窄墙的四种方式（未读 / 按来源 / 按类型 / 按标签）都在筛选弹层里，按钮自己的按下态、以及它写进搜索框的 `#源id` / `#rss` / `#link` / `@标签id`，让「被隐藏了什么」始终看得见。
-- **正文超过 256 KiB 会存成单独文件**：`state.json` 只留元数据（文件名 + 字符数），正文本体落在 `$DSH_HOME/state/dsh-reader/bodies/<hash>.html`。【正文保留】设置的 12/24/168 小时 / 永久对**两种正文一视同仁**，淘汰（超出「保留条数」上限或 TTL 到期后重抓）时会连文件一起删掉。这样做是因为 `state.json` 是一份整体读写的 JSON：一篇插图内联成 base64 的论文抽出来几十 MB，直接塞进去会让之后每一次读者操作都付出几 MB 的往返。
-- **正文顶部的重复标题会被去掉**：详情页已经渲染了条目标题，而文章自己的 HTML 里常常再来一两遍（实测那篇有**两个** `<h1>`，前面还跟着站名和 logo 链接）。抽取时会去掉与文档标题重复的一二级标题、开头的站头chaff 与空行，正文从「Authors」这类真实内容开始。
-- **正文没有阅读量度**：段落和列表都铺满侧栏给的宽度，没有 `max-width`（早先只给段落限宽，右侧留出一条参差的空白带，看起来像布局坏了）。想要更短的行，把侧栏收窄即可。
-- **宿主抓取上限是已知限制**：`ctx.web.fetch` 把解码后的正文截到 100,000 字符且**静默截断**。超限的文章抽不全（实测：Anthropic 研究页 ~266k、theverge.com ~899k、newyorker.com ~1.97M 字符）；摘要页里的文章标题、作者、摘要仍然在。详情页会因此显示「受限篇幅，内容未完整呈现」+「阅读原文」。RSS 源基本安全（实测：HN 11KB、BBC 25KB、阮一峰 69KB、Simon Willison 83KB——83KB 已经贴着上限）。
-- **降级矩阵**：无 `fs` → 状态只在内存里、重启即丢（握手会 `hasFs: false`，不假装有持久化）；无 `web` → 新增的链接照样存下来并标成「仅链接（连不上）」+「阅读原文」，不抛异常、更不丢 URL；无 `sideChat` → 侧边对话那一项隐藏；无 `quote` → 选区浮层缺席，但条目级「引用」按钮照常工作。宿主低于 0.1.6-alpha.2（没有 `browser` 这个右栏 tab 类型）→ 需要真浏览器的地方（脚本插图提示、反爬卡片的动作）给的是普通外部链接，不报错。
-- **跨源重定向只跟随能还原的那一跳**：宿主缝会拒跨源跳转（`WEB_REDIRECT_BLOCKED`），而且**只报目标 origin、不报路径**。所以插件只在**同一个主机换 scheme/端口**时重新进缝（`http://host/feed` → `https://host/feed`，路径与查询原样保留）；**换了主机就如实说「这个地址会跳到另一个站点」，不再跟过去**——跟着 origin 根路径抓回来的是另一个页面，然后还会被当成读者粘的那个地址存下来。这条以前写的是「最多跟 3 跳」，但那段判定读的是错误**消息文本**里根本没有的 `WEB_REDIRECT_BLOCKED`（宿主把它放在 `error.code` 上），所以跟随从来没生效过、每次都是把宿主缝的原话甩给用户；现在按 `code` 判定，并补了回归测试。
-- **站点拒绝 / 登录墙 / PDF 都只会变成「仅链接」**：抓回来的页面如果**几乎没有可读文本**（`< 200` 字符可见文本，去掉 script/style 后计）并且带着反爬或登录页的痕迹，就不当作文章存下来——**挑战页本身绝不落成卡片正文**。`application/pdf` 之类更是宿主的出网缝直接拒绝的类型（`WEB_UNSUPPORTED_CONTENT_TYPE`，只认 html/text/json/xml）。这些卡片照常出现在墙上、能打标签、能复制链接、能删除，点开只有原因 + 「阅读原文」。
-- **不可重试的原因不会被自动重试**：反爬、登录墙、PDF、HTTP 错误、空页面都记录成不可重试（`isRetryablePreviewFailure` 只放行 `unreachable`），自动补齐不会再敲它们；订阅管理页那一行的「刷新」仍可手动重试，成功后清掉记录。这样插件不会对一个永远拒绝它的站点每 6 小时敲一次。
-- **不做条件请求**：宿主缝没有自定义请求头入口，所以没有 ETag/If-None-Match，每次刷新都是完整抓取。
-- **订阅登录墙后面的内容：不做**。没有凭证注入面。
-
-## Known Limitations
-
-- **只订阅、不抓文**：新增订阅时只抓 feed 本身，不会为每条目预抓正文（存储会爆，而且那是在当爬虫）。想看某条正文时点开它，付一次抓取。
-- **PDF 与其它非网页文件没有正文**：宿主的出网缝只认 `text/html`、`text/*`、`application/json`、`application/xml`，`application/pdf` 会被直接拒绝；而正文提取本来就是 DOM 的，PDF 没有 DOM。所以 PDF 链接只能存成「仅链接」的卡片 + 「阅读原文」，插件不是 PDF 阅读器。
-- **跨站跳转不跟随**：宿主缝只报目标 origin，路径无法还原，所以换了主机的跳转（短链、ezproxy 之类的代理）一律如实报「跳到另一个站点」，不会跟过去猜。
-- **未读与正文不落盘**：会话级状态。持久化逐条已读游标需要第二份写密集文档，而"自上次看过以来有什么新的"本身就是这个插件的价值所在。
-- **XML 解析在浏览器**：宿主侧没有 XML/DOM 解析器（`globalThis.DOMParser === false`），所以 feed 解析必然在客户端。
-- **不依赖 browser-pane**：`proposals/active/2026-09-13-browser-pane.md` 还是 planned，而且 canvas 的 CDP 帧里承载不了划选引用。
+已用 `dsh --profile web --patch <file> --dump-config` 实测确认合成结果里带着这个值；验收实例上已按此加上覆盖并实测：同一条 feed 由「100,000 字符 / 截断 / 2 条」变成「**646,905 字符 / 未截断 / 21 条完整**」。**2026-09-19 又抬了一档**：研究类文章本身就很大——实测 `transformer-circuits.pub` 的 emotions 那篇 HTML 有 **41.8 MB**（60 张插图是内联 base64），而宿主缝的**字节上限** `maxResponseBytes` 默认只有 5 MB，整次抓取会直接失败（`response exceeds the maximum of 5000000 bytes`），`maxBodyChars` 也挡在前面。现在验收实例的部署配置把**两个上限一起抬到 64 MB**，并把**抓取超时从默认 30 秒抬到 180 秒**（同一篇实测直连 19.5 秒，机器一忙以前就会以 `web fetch timed out` 失败）。代价是**全机**每次抓取的峰值内存与传输量都随之上升。注意边界：插件的 patch 只能挂**自己那一行**（仓库禁止插件去挂/改别人的行），所以这条覆盖属于**部署配置**，由部署方决定；而且它抬高的是**全机所有网页抓取**的上限。
+
+**全文是自动补齐的，不需要你点**：每次加载后，宿主给出"还缺全文"的条目清单（一次最多 8 条，失败的条目 6 小时内不再重试），浏览器半一条一条抓取+抽取并写入缓存（24 小时，管理页可改），**同时最多 2 个请求**。补齐中的条目仍在墙上显示 feed 自己给的内容，底部一行进度「正在补齐全文 3/8…」；抓到的卡片标一个「已抓全文」（徽章的含义是：卡片上仍是 feed 自己的摘要，全文已经缓存好了，点开就能读）。**不确定要不要等？直接点开那一条**：打开时若本地还没有正文，它会就地抓一次并显示「正在抓取正文…」，不必等补齐轮到它。
+
+- 为什么不是"全部一次抓完"：那等于把每个订阅源的所有文章都爬一遍。这里是**每次刷新补一片**，滚动前进。
+- **抓不到就展示已有的**：站点拒绝（401/403）、连不上、抽取失败，三种情况分开说明，正文位置永远显示 feed 自己发布的内容 + 「阅读原文」，绝不空白。
+
+**被宿主截断的 feed 会抢救，而不是整份丢掉**：宿主缝按字符数截断，截在标签中间会让整份 XML 不合法——而"整份不合法"曾经等于**一条都没有**。现在解析器会：完整闭合的 `<item>`/`<entry>` 全部保留（用文档根上的命名空间声明重新包装，否则带 `content:encoded` 前缀的片段自己也是坏 XML）；被截断的那条尽最大努力修复并标成**部分**，正文照常显示已经拿到的部分；墙上给一行「未完整」说明 + 阅读原文。配一个提交在仓库里的 fixture（`tests/fixtures/feed-truncated.xml`）锁住这个形状。实测：验收实例那条 646 KB 的 feed（宿主只给 100,000 字符）现在能出 **2 张卡**——一张完整的 42 KB 正文，一张部分正文——而在这次修复前是 **0 张**。
+
+**站点拒绝 / 登录墙 / PDF 都只会变成「仅链接」**：抓回来的页面如果**几乎没有可读文本**（`< 200` 字符可见文本，去掉 script/style 后计）并且带着反爬或登录页的痕迹，就不当作文章存下来——**挑战页本身绝不落成卡片正文**。`application/pdf` 之类更是宿主的出网缝直接拒绝的类型（`WEB_UNSUPPORTED_CONTENT_TYPE`，只认 html/text/json/xml）。这些卡片照常出现在墙上、能打标签、能复制链接、能删除，点开只有原因 + 「阅读原文」。
+
+**不可重试的原因不会被自动重试**：反爬、登录墙、PDF、HTTP 错误、空页面都记录成不可重试（`isRetryablePreviewFailure` 只放行 `unreachable`），自动补齐不会再敲它们；订阅管理页那一行的「刷新」仍可手动重试，成功后清掉记录。这样插件不会对一个永远拒绝它的站点每 6 小时敲一次。
+
+**跨源重定向只跟随能还原的那一跳**：宿主缝会拒跨源跳转（`WEB_REDIRECT_BLOCKED`），而且**只报目标 origin、不报路径**。所以插件只在**同一个主机换 scheme/端口**时重新进缝（`http://host/feed` → `https://host/feed`，路径与查询原样保留）；**换了主机就如实说「这个地址会跳到另一个站点」，不再跟过去**——跟着 origin 根路径抓回来的是另一个页面，然后还会被当成读者粘的那个地址存下来。判定按 `error.code` 而不是错误消息文本（宿主把 `WEB_REDIRECT_BLOCKED` 放在 `error.code` 上），有回归测试。
+
+**不做条件请求**：宿主缝没有自定义请求头入口，所以没有 ETag/If-None-Match，每次刷新都是完整抓取。**订阅登录墙后面的内容：不做**——没有凭证注入面。
+
+**正文超过 256 KiB 会存成单独文件**：`state.json` 只留元数据（文件名 + 字符数），正文本体落在 `$DSH_HOME/state/dsh-reader/bodies/<hash>.html`。【正文保留】设置的 12/24/168 小时 / 永久对**两种正文一视同仁**，淘汰（超出「保留条数」上限或 TTL 到期后重抓）时会连文件一起删掉。这样做是因为 `state.json` 是一份整体读写的 JSON：一篇插图内联成 base64 的论文抽出来几十 MB，直接塞进去会让之后每一次读者操作都付出几 MB 的往返。
+
+**正文顶部的重复标题会被去掉**：详情页已经渲染了条目标题，而文章自己的 HTML 里常常再来一两遍（实测那篇有**两个** `<h1>`，前面还跟着站名和 logo 链接）。抽取时会去掉与文档标题重复的一二级标题、开头的站头 chaff 与空行，正文从「Authors」这类真实内容开始。
+
+**默认过滤是「全部」而不是「今日」**：RSS 源的最新条目经常不是今天的（验收实例那条 feed 最新一篇是 8 天前），默认「今日」会让刚订阅完的墙看起来像空的 —— 也就是「订阅成功了但什么都没有」。现在**没有「今日」这个过滤**：收窄墙的四种方式（未读 / 按来源 / 按类型 / 按标签）都在筛选弹层里，按钮自己的按下态、以及它写进搜索框的 `#源id` / `#rss` / `#link` / `@标签id`，让「被隐藏了什么」始终看得见。
+
+**降级矩阵**：无 `fs` → 状态只在内存里、重启即丢（握手会 `hasFs: false`，不假装有持久化）；无 `web` → 新增的链接照样存下来并标成「仅链接（连不上）」+「阅读原文」，不抛异常、更不丢 URL；无 `sideChat` → 侧边对话那一项隐藏；无 `quote` → 选区浮层缺席，但条目级「引用」按钮照常工作；无 capture 包 → 脚本插图提示处不出现「渲染抓取」；宿主低于 0.1.6-alpha.2（没有 `browser` 这个右栏 tab 类型）→ 需要真浏览器的地方（脚本插图提示、反爬卡片的动作）给的是普通外部链接，不报错。
+
+</details>
+
+## 开发
+
+隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/dsh-reader`）。问题与贡献请移步该仓库。