dsh-paperforge

Readme

<div align="center">

<img src="docs/images/logo.png" width="480" alt="PaperForge：水彩风格的论文、对话气泡与钢笔">

<h3>在 DSH 里读论文：边读、边问、边记</h3>

<p>
<a href="#quick-start">快速开始</a> ·
<a href="#highlights">亮点</a> ·
<a href="#todo">TODO</a> ·
<a href="./AGENTS.md">开发手册</a> ·
<a href="./README.en.md">English</a>
</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-plugin-4f46e5)](https://github.com/topics/dsh-plugin) [![DSH](https://img.shields.io/badge/DSH-0.1.7%2B-6366f1)](https://github.com/deepseek-ai/deepseek-harness) [![Repo](https://img.shields.io/badge/github-PhysicalAI--0%2Fdsh--paperforge-181717?logo=github)](https://github.com/PhysicalAI-0/dsh-paperforge)

</div>

**读懂一篇论文，留下自己的思考。** 从论文库点开 PDF，原文、专属 AI 会话与 Markdown 笔记并排展开：选中难懂的段落，带着上下文向 AI 追问；划下重要的文字，框选值得留存的图表，高亮与截图自动收进本地笔记。下次打开，接着上次的思考往下读。

<a id="news"></a>

## <img src="docs/images/icons/news.png" width="48" height="32" alt=""> News

- **2026-09-29**
  - 原生多栏阅读布局：左边会话列表，中间本篇论文的 AI 会话，右边 PDF｜笔记。
  - 新增会话 Summary 与复制路径；笔记目录改为 `paperforge_notes`，不再引用的图片自动清理。
  - Markdown 块级编辑：所有 `.md` 都能原地编辑、自动保存。
  - 阅读链路重做：论文库、笔记实时预览、每篇论文一个专属 AI 会话。
- **2026-09-28** — 首个版本发布；改为 DSH 原生 `dsh plugin` 安装。

<a id="highlights"></a>

## <img src="docs/images/icons/highlights.png" width="48" height="32" alt=""> 亮点

![阅读布局：左边会话列表，中间本篇论文的 AI 会话，右边 PDF 与笔记](docs/images/zh/reading.png)

<table>
  <tr>
    <td width="33%" valign="top"><b>论文库</b><br>左侧栏「论文」列出工作区里的 PDF，点一篇进入阅读布局</td>
    <td width="33%" valign="top"><b>标注</b><br>划词高亮（六色）与框选截图自动写进笔记；选段也可复制为原文或 Markdown 引用</td>
    <td width="33%" valign="top"><b>Ask AI</b><br>划词「Ask AI」或页头「AI」：问题带上 <code>@论文</code>、页码与选段，发进本篇论文的会话</td>
  </tr>
  <tr>
    <td valign="top"><b>Markdown 编辑</b><br>所有 <code>.md</code> 都能原地编辑：点一块改源码，离开即渲染；自动保存，与插件、AI 的改动自动合并</td>
    <td valign="top"><b>Summary</b><br>论文库「会话」页签勾选会话，生成一份 Summary（Markdown）：每 3 个一批引用，最后综合</td>
    <td valign="top"><b>复制路径</b><br>任意文档页头的复制图标，一键复制文件路径</td>
  </tr>
</table>

<table>
  <tr>
    <td width="34%" align="center" valign="top"><img src="docs/images/zh/editor.png" alt="点一块即可编辑源码，其余保持渲染"><br><sub>笔记：点一块改源码，其余保持渲染</sub></td>
    <td width="66%" align="center" valign="top"><img src="docs/images/zh/summary.png" alt="Summary：AI 把多个会话的总结写进 Markdown"><br><sub>Summary：勾选的会话由 AI 汇总成一份 Markdown</sub></td>
  </tr>
</table>

<sub>截图中的论文页面来自 Vaswani et al., <i>Attention Is All You Need</i>（arXiv:1706.03762），按 Google 的授权注明出处、用于学术用途。Logo 与章节图标由 AI 图像模型生成。</sub>

<a id="quick-start"></a>

## <img src="docs/images/icons/quick-start.png" width="48" height="32" alt=""> 快速开始

前置条件：DSH `0.1.7+`，PATH 上有 `pnpm`。

```bash
dsh plugin --profile web add github:PhysicalAI-0/dsh-paperforge
# 或克隆后本地安装（改代码后重启 dsh web 即生效）：
git clone https://github.com/PhysicalAI-0/dsh-paperforge.git && cd dsh-paperforge
dsh plugin --profile web add .
```

在放论文的目录启动 `dsh web`（这个目录也要是 DSH 的工作区），左侧栏出现「论文」即安装成功。卸载：`dsh plugin --profile web remove dsh-paperforge`。

<a id="notes"></a>

## <img src="docs/images/icons/notes.png" width="48" height="32" alt=""> 笔记放在哪

```text
<论文目录>/paperforge_notes/
├─ <论文名>/<论文名>.md                     笔记（标准 Markdown，可直接编辑）
├─ <论文名>/assets/                         截图；不再被任何笔记引用的图片约 2 分钟后自动删除
├─ <论文名>/highlights.json、session.json   高亮位置、与论文会话的绑定
└─ Summary/                                 会话 Summary
```

<a id="config"></a>

## <img src="docs/images/icons/config.png" width="48" height="32" alt=""> 配置（可选）

在 `~/.dsh/profiles/web/cordis.patch.yml` 里按 id 覆盖：

```yaml
- id: paperforge
  config:
    workspaceRoot: <论文目录的绝对路径>   # 缺省 = 启动 dsh web 的目录
    notesDir: paperforge_notes          # 笔记根目录名（旧版默认是 notes）
    model:                              # 论文会话用的模型；不写则沿用当前模型
      provider: deepseek-official
      name: deepseek-flash
      reasoningEffort: high
```

不要写 `- insert:`（插件会被加载两次）。配置了 `model` 时，DSH 也会把它存为新会话的默认模型。

<a id="todo"></a>

## <img src="docs/images/icons/todo.png" width="48" height="32" alt=""> TODO

- [ ] Markdown 即时渲染（类似 Vditor）：图片点击放大、块拖拽排序
- [ ] 富渲染：mermaid 流程图 / 时序图 / 甘特图、echarts 图表、脑图
- [ ] 为同一篇论文开多个会话（页头「AI」按钮）
- [ ] 按页、按图读论文的工具与读图 skill，降低读图的 token 消耗
- [ ] 问答要点自动写回笔记
- [ ] 统一为 JavaScript：用 `mupdf` 替换 Python 边车；论文库扫描改为异步

<a id="limitations"></a>

## <img src="docs/images/icons/limitations.png" width="48" height="32" alt=""> 已知限制

- 右侧栏最多两栏（DSH 限制），更多窗口请拖成浮动。
- 论文会话在第一次提问前，左侧列表显示为「新会话」，DSH 的「新建会话」可能复用它。
- Markdown 按块编辑：撤销只在当前块内；跨块的引用式链接与脚注可能不生效；工作区外或超过 2 MB 的 `.md` 只能预览。
- Summary：DSH 每条消息最多引用 3 个会话，插件分批发送；内容由 AI 用写文件工具写入。
- 不同目录下的同名 PDF 共用一个笔记文件夹；笔记里的章节名固定为中文。

<a id="development"></a>

## <img src="docs/images/icons/development.png" width="48" height="32" alt=""> 开发

```bash
pixi run test     # 单元测试
pixi run verify   # 契约与冒烟测试
```

插件分两半：浏览器半 `lib/client.js`，宿主半 `lib/index.js` 等（注册 `/api/paper.*` 路由）。另有可选的 Python 边车 `py/`，只用于把高亮写进 PDF 文件本身。开发前先读 [`AGENTS.md`](./AGENTS.md)：DSH 插件的硬约束、关键 API、踩过的坑和路线图都在里面。

<a id="thanks"></a>

## <img src="docs/images/icons/thanks.png" width="48" height="32" alt=""> 缘起与致谢

作者是 [alphaXiv](https://www.alphaxiv.org/) 的重度用户，本插件「划词即问、就地记笔记」的交互正是受它启发。但它的问答额度有限，模型也不能替换，于是把「划词 → 追问 → 落笔记」搬回自己掌控的 DSH：不重复造阅读器，复用 DSH 原生的预览、会话与模型配置。

<sub>PaperForge 与 alphaXiv 及其团队无任何隶属、赞助或背书关系，也不包含其任何代码或素材。</sub>

<a id="license"></a>

## <img src="docs/images/icons/license.png" width="48" height="32" alt=""> License

[MIT](./LICENSE) © dsh-paperforge contributors