dsh-paper-reader

不定时更新。

一个给 DSHA（DeepSeek Harness）用的论文阅读插件。点输入框旁边的「论文」，聊天区会换成三栏：左边是工作区里的文稿目录，中间是正文，右边是这篇论文的子代理。

怎么工作

论文对话用平台的子代理，没有自己实现一套。在右栏第一次提问时，会在你当前这个会话下面开一个可续聊的子代理，把论文文件交给它，让它自己用工具读；之后每一条都通过人类通道（ctx.subagents.prompt）发给同一个子代理，所以右栏可以直接聊。子代理处于休眠状态时，这条通道会顺手把它唤醒。子会话在持久化里的 parentSession 就是你当前会话，记录留在你原来的对话里，原生那边能看到它也能点开接着聊。

子代理的工具和系统提示继承父会话的 Agent 预设，插件不做组装；审批策略由平台固定为不询问，面板里不会弹确认。

右栏显示的是只读镜像：活着的时候转发它的流式输出，跑完被平台回收之后改读持久化日志（sessionQuery.readSession()），不会为了显示把它叫醒。想让它在原生界面里跑，点「原生打开」，桌面端会同时把论文停靠到右边。

版面

• 电脑：三块边到边平铺（目录较窄、论文占中间、对话在右），列宽可以直接拖。进门时会顺手把左侧会话栏收起来，离开时还回去。
• 手机：宽度不够，才退化成「目录 / 论文 / 对话」三个页签。
• 停靠：三栏里点「停靠」，论文挂到右侧栏，中间的原生聊天不受影响；点「三栏阅读」切回来。

阅读器内部没有第二个「论文」入口，输入框那个按钮在阅读器打开时会变成不可点的「阅读中」，不会叠出一层。进入阅读器时三栏有淡入动画，系统开启减少动态效果时自动关闭。

右栏是聊天样式，黑底白字，消息流加输入框，Enter 发送、Shift+Enter 换行。运行中也点得动发送，它会排队；旁边多一个「停止」。

子代理调用的工具会以小标签贴在对应的那条回答上，流式过程中就能看到。

首轮的交接提示词不进聊天：镜像里只保留你真正问的那句话，纯点击开始（比如「精读总结」）时那条提示词整条不显示。

安装

dsha-plugin import /tmp/dsh-paper-reader.zip

插件行是 patchReload: startup，装完要在 App 里重启一次 DSHA Web 才会加载。

打包用的脚本：

python3 - <<'PY'
import zipfile, os
root, out = '/root/dsh-paper-reader', '/tmp/dsh-paper-reader.zip'
with zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as z:
    for base, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in ('node_modules', '.git')]
        for f in files:
            full = os.path.join(base, f)
            z.write(full, os.path.relpath(full, '/root'))
PY

卸载用 dsha-plugin delete dsh-paper-reader，同样要重启。

使用

1. 打开任意会话，点输入框右侧的「论文」。
2. 左栏选一篇文稿（第一次进去会自动打开第一篇 Markdown），中栏阅读。
3. 在右栏直接问。第一条会把这篇论文交给子代理（提示词是中文，PDF 直接把文件路径给它，让它自己调工具读；环境里没有 PDF 解析工具时，提示词里还给了插件抽取好的纯文本缓存路径兜底）。
4. 之后每条都发给同一个子代理，可以一直追问。跑的时候右栏会流式显示，也可以点「停止」。
5. 想用原生界面，点「原生打开」。按 Esc 或点「返回对话」回到原来的聊天。

PDF

中栏用 pdf.js 渲染，支持缩放、反色和下载。文字抽取在宿主侧做，所以 PDF 也能总结和追问。扫描版 PDF 没有文字层，抽不出正文，只能当图片看。

配置

环境变量	说明
DSHA_PAPER_ROOTS	追加可读根目录，用 : 分隔。默认只有 dsh 进程的工作目录，本机是 /root。例如要读手机存储：DSHA_PAPER_ROOTS=/sdcard/Download:/sdcard/Documents
DSHA_PAPER_PDFJS_DIR	pdf.js 所在目录，默认是插件内的 node_modules/pdfjs-dist

接口

都挂在 /api/paper-reader 下面，用和上游 /api 一样的浏览器鉴权，没登录返回 401，非信任域返回 403。

方法	路径	说明
GET	/health	状态、可读根目录、子代理是否可用
GET	/tree?root=&all=1	工作区文稿目录树
GET	/file?path=	单篇文件，返回类型、正文和下载地址
GET	/raw?path=&download=1	原始字节，给 PDF、图片和下载用
GET	/text?path=	pdf.js 抽取出来的文字，带缓存
GET	/pdfjs/*	转发 pdfjs-dist 的静态资源
GET	/chat?path=&sessionId=	子代理状态和只读镜像
POST	/chat	没有子代理就起一个，已经有就把 message 发给它。参数 path、sessionId，可选 message、delivery
GET	/chat/stream?path=&sessionId=	镜像的流式输出，NDJSON
POST	/chat/interrupt	打断子代理
POST	/chat/reset	忘掉这篇论文的子代理映射，下次重新起
POST	/summary	早期的一次性总结接口，走 ctx.llm，保留备用

文件接口只读，不写不改不删。路径会先 realpath 再校验是否落在允许的根目录内，防 .. 和前缀逃逸，不跟随软链接。

限制

• 面板是只读镜像加一个输入框，更完整的操作（队列、审批、模型切换）在原生子会话里。
• 子代理一轮结束后会被回收，镜像还能看，继续追问会把它唤醒。
• LaTeX 公式按源码显示，DOCX 之类的格式只能下载。
• 手机存储默认不在可读范围，要用 DSHA_PAPER_ROOTS 打开。
• 安装、更新、卸载后都需要重启 DSHA Web。

开发

pnpm install --ignore-scripts
pnpm test

pdfjs-dist 是运行时依赖，react、react-dom、jsdom 只在测试时用。

测试分三个文件。test/test-host.mjs 覆盖文件接口、越界防护、鉴权和 pdf.js 资源；test/test-chat.mjs 用假的 agents、subagents、sessionQuery 服务配真实 http，覆盖子代理的启动参数、复用和换父会话、状态与镜像（包括冷会话读持久化日志）、流式转发、打断和错误分支；test/test-client.mjs 用 jsdom 挂载真实组件，覆盖三栏、目录树、Markdown、右栏控制台、两种版面互切和 PDF 回退。

目录

文件	作用
lib/index.js	路由和路径校验
lib/chat.js	子代理：映射存储、启动、活/冷镜像、打断
lib/pdf-text.js	pdf.js 的文字抽取和资源定位
lib/client.js	按钮、三栏面板、子代理控制台、停靠标签、样式

MIT