导师在 PDF 上画线,PaperDesk 把修改位置交给论文 Agent

如果导师在 PDF 上圈出一句话，写下“这里补一篇对照文献”，负责修改的人还得回到 .tex 文件里找对应位置。把批注交给编码 Agent，也通常要先告诉它文件名、段落和原句。PaperDesk 试图省掉这段人工转述。

这个开源本地审阅工具让人在浏览器中查看论文 PDF 并留下批注；LaTeX 文档借助 SyncTeX 定位到源文件和行号，Word 文档则按文本匹配定位到段落。终端里的编辑者可以通过 desk.py 读取批注和位置。项目还提供 watch 命令输出新批注事件，但 watch 进程需要事先接入能唤醒 Agent 的机制；单独开一个终端运行它，不等于 Agent 会自动改稿。

以下按项目仓库说明梳理使用方法和边界。文中的批注、事件和命令输出为示意，不涉及性能测试结果。

01

CHAPTER 01

一、PDF 批注怎么对应到源码

论文在 PDF 里按页阅读，修改却发生在 LaTeX 文件或 Word 文档里。PaperDesk 在批注时保存选区、原句和位置，再尝试给出对应的源文件行号或段落号。这样编辑者拿到批注后，至少有一个可以核对的起点。

对 LaTeX，定位依赖编译时生成的 SyncTeX 映射；对 Word，依赖 PDF 文本与 .docx 段落的匹配。定位失败时，项目仍保存批注并标明原因，不能把每条批注都当作已准确锚定。

从批注到修改的基本路径是：

●●●Terminal

[ 人类审阅者 ] (看 PDF 划选文字 / 手机端语音批注)
      │
      ▼ (HTTP / WebSockets / SyncTeX 坐标解析)
[ PaperDesk 服务端 (serve.py) ]
      │
      ▼ (追加写入结构化评论流 comments.jsonl)
[ 终端监听进程 (desk.py watch) ]
      │
      ▼ (终端事件，需接入 Agent 的唤醒机制)
[ 本地 Coding Agent（已接入 watch 时）/ 人工编辑者 ]
      │
      ▼ (核对定位结果，修改后按配置重建)
[ 论文源码 (.tex / .docx) ] ──> [ 新 PDF ]

批注里有源文件位置和附近上下文，编辑者不必只靠一句模糊描述全局搜索；碰到未能解析的批注或复杂宏，仍要自行确认修改位置。

02

CHAPTER 02

二、LaTeX 靠 SyncTeX，Word 靠文本匹配

这两种文档的定位方法不同，使用前要先确认论文的源文件类型。

1. LaTeX：把 PDF 坐标交给 SyncTeX

LaTeX 编译时启用 SyncTeX，才会生成供反向查询的 .synctex.gz 文件。

在 LaTeX 模式下，当审阅者在 Web 界面选中一段文字或点击一张图片时，前端会将该选区的物理坐标 (page, x_pt, y_pt) 发送至本地服务器 serve.py。服务端直接调用底层的 synctex edit 命令：

●●●Terminal

# PaperDesk 底层调用 SyncTeX 的核心逻辑抽象
out = subprocess.run(
    ["synctex", "edit", "-o", f"{int(page)}:{float(x_pt):.2f}:{float(y_pt):.2f}:{PDF}"],
    capture_output=True, text=True, timeout=20, cwd=PAPER
).stdout

编译产生的 .synctex.gz 记录排版位置与源文件行号的对应关系。PaperDesk 读取 synctex edit 的返回值，给批注附上文件名和行号；项目还会补充所在章节、图表或标签等上下文。下面是说明这些字段如何配合的示意记录，不是本次运行的输出：

●●●Terminal

{
  "id": 14,
  "status": "open",
  "anchor": {
    "file": "sections/methodology.tex",
    "line": 142,
    "section": "Methodology > Feature Extraction",
    "float": "figure",
    "label": "fig:pipeline"
  },
  "quote": "The extracted representations are then normalized...",
  "text": "此处需要说明特征归一化采用的是 L2 范数还是 LayerNorm。"
}

2. Word：从 PDF 文字回找文档段落

Word 文档没有 SyncTeX。项目说明中的做法是先用 LibreOffice 把 .docx 转成 PDF，再用 Poppler 读取 PDF 的文本框；另一边从 word/document.xml 读取原文段落。选中一段文字时，工具会在这些段落中寻找连续匹配的词，并结合页面上的顺序处理重复段落，最终给出形如 report.docx:¶12 的位置。它是段落级锚定，遇到换行、字体或复杂排版，仍要对照原文确认。

03

CHAPTER 03

三、让批注进入终端

批注保存在 comments.jsonl。有人在浏览器里留言，终端里的 Agent 并不会自己知道；需要先启动 desk.py watch，并把它的输出接到宿主的唤醒或监控机制。

1. watch 提供事件和在线状态

项目 README 特别提醒：监听命令要在 Agent 的唤醒链路中持续运行。如果监控到期，还得重新挂上；否则新批注仍会保存，只是不会主动送到 Agent 当前会话。

PaperDesk 在 desk.py 中引入了专属的 watch 命令：

●●●Terminal

python desk.py watch

运行时，新批注、回复或转录完成的语音留言会在终端输出事件。下面是事件的示意格式：

●●●Terminal

+ #14 open sections/methodology.tex:142 Methodology > Feature Extraction [figure fig:pipeline]
  quote: "The extracted representations are then normalized..."
  此处需要说明特征归一化采用的是 L2 范数还是 LayerNorm。

desk.py watch 定期读取评论文件并更新心跳。页面在无人监听时提示 unwatched，这只能反映监听进程的状态，不能证明 Agent 已在线处理批注。

2. 编辑者接到批注后做什么

desk.py 提供几条简单命令，人工编辑者或已接入的 Agent 可以按需调用：

当 Agent 宿主已接入 watch，并且事先授予它修改论文源码的权限时，可以按下面的假设流程处理一条批注。PaperDesk 本身不替 Agent 判断修改内容：

●●●Terminal

[人类在 Web 端批注] 
       │
       ▼
[desk.py watch 吐出事件]
       │
       ▼
[Agent 捕获事件 -> 读取 methodology.tex 第 142 行]
       │
       ▼
[Agent 执行修改 -> 调用 xelatex/latexmk 重新编译]
       │
       ▼ (编译成功)
[Agent 执行 python desk.py reply 14 "已补充 LayerNorm 说明与参考文献"]
       │
       ▼
[Agent 执行 python desk.py resolve 14]
       │
       ▼
[Web 端实时变更为已解决状态，刷新查看新排版]

04

CHAPTER 04

四、按照仓库说明搭建本地审阅环境

准备好论文源文件和编译工具后，可以按项目文档配置服务。下面是操作顺序，配置字段应以仓库当前版本为准。

1. 前置环境准备

• Python：建议 3.11 及以上版本（若使用 Python 3.10，需安装 pip install tomli）。
• TeX 编译链（LaTeX 模式）：本地已安装 TeX Live、MacTeX 或 MiKTeX，确保系统环境变量中包含 synctex 命令行工具。
• Word 转换支持（可选，Docx 模式）：
• macOS: brew install poppler libreoffice
• Linux (Ubuntu/Debian): sudo apt-get install poppler-utils libreoffice
• 语音转录模型（可选）：如果审阅者习惯直接在手机或平板端口述审阅意见，可安装 pip install faster-whisper。

2. 项目配置与初始化

在论文仓库所在的上级或独立工作目录中克隆工具，并创建论文配置文件 paperdesk.toml：

●●●Terminal

git clone https://github.com/dmrai-lab/paperdesk.git
cd paperdesk
cp paperdesk.example.toml paperdesk.toml

编辑 paperdesk.toml，指定待审阅的论文项目路径及编译方式：

●●●Terminal

[paper]
dir = "../my-icml-paper"  # 论文源文件目录
main = "main.tex"          # 主文件
build = "latexmk -pdf -synctex=1 -interaction=nonstopmode -halt-on-error main.tex"
[people]
reviewer = "Prof. Zhang"
editor = "Agent"            # 也可以写人工编辑者的名字
[server]
host = "127.0.0.1"
port = 8765
[voice]
model = "small"             # 只有安装 faster-whisper 时才用于本地转录
glossary = "diffusion MRI, q-space, b-value"

检查点：编译需要启用 -synctex=1（或在 TeX 源文件中设置 \synctex=1）。如果没有生成 .synctex.gz，批注仍可保存，但无法获得源文件行号。

3. 启动本地服务与多端协同

在终端执行：

●●●Terminal

python serve.py

默认将在本地 http://127.0.0.1:8765 启动服务。浏览器打开该地址，即可看到通过内嵌 pdf.js 渲染的完整论文视图。

• 远程审阅（可选）：仓库的 tunnel.sh 使用 Cloudflare quick tunnel，运行前要检查脚本预期的 cloudflared 安装路径。它会生成临时公网地址；若允许从外网访问，应先配置并验证 auth.json 的账号密码保护。这个页面能提交批注，不能把临时地址当作“只读分享”。

4. 验证与排错自检清单

在实际投入 Agent 协同前，建议按以下检查清单进行联调：

1. SyncTeX 定位有效性验证：在 Web 页面随机选中正文一个单词，观察右侧弹出的锚定标签是否显示形如 paper.tex:84。若显示 page X (unresolved)，请检查源文件编译时是否生成了 .synctex.gz，或路径是否包含特殊字符。
2. 状态流转验证：在 Web 提交一条测试批注 #1，在另一个终端执行 python desk.py list，确认能够正常列出该批注。随后执行 python desk.py resolve 1，确认 Web 端批注卡片立即标记为解决。
3. 语音转录验证：录制一段包含专业术语的 5 秒语音，执行 python desk.py transcribe，检查是否能借助配置的 glossary 准确转出文本。

05

CHAPTER 05

五、试用前还要留意什么

1. 行号要复核：宏定义、动态引入文件等复杂 LaTeX 写法可能让 SyncTeX 定位到不符合预期的行。修改前先读锚点附近的源码。
2. Word 只定位到段落：字体和 LibreOffice 转换结果可能影响文字匹配。拿到 ¶n 后，仍要打开原段落确认。
3. 适用范围是论文文档：仓库没有提供 Excel 工作簿或 PowerPoint 幻灯片的定位支持。
4. 先留退路：让 Agent 改源文件前，保存当前工作并检查 Git 差异。未提交的修改尤其要备份；每处理一条批注就重建 PDF、看实际改到了哪里。

PaperDesk 值得试的地方是把 PDF 批注连同源码位置带进终端。先拿一条真实批注验证定位，再决定要不要接入 Agent 的监听与改稿权限；定位、修改和编译这三步都应能单独检查。

R

REFERENCE

参考来源

• PaperDesk 官方 GitHub 代码仓库：https://github.com/dmrai-lab/paperdesk
• PaperDesk Agent 协同规范文档 (AGENTS.md)：https://github.com/dmrai-lab/paperdesk/blob/master/AGENTS.md
• SyncTeX 技术手册与规范标准 (TeX Live Manual)：https://tug.org/texlive/Contents/live/texmf-dist/doc/man/man1/synctex.man1.pdf
• dmrai-lab 组织主页与开源项目集：https://github.com/dmrai-lab

→

READ NEXT

延伸阅读

• Codex怎么调用OriginPro：用Python自动画图、保存工程和导出插图
• 科研人用 ChatGPT 的痛苦在于：聊得越深入，越难验证