Paper Highlight Agent —— 用户指南（v0.4）
🗺️ 路线图
- v0.4（当前版本）：已完成核心功能，适用于论文高亮场景下的个性化学习闭环。
- v1.0（计划 2026.09）：将提升稳定性与易用性，完善细节，正式发布稳定版本。
- v2.0（计划 2026.10）：探索与 Zotero 文献管理工具联动，进一步提升学术工作流效率。
- v3.0 (计划 2027+)：探索个性化画像的更多应用，实现可迁移可分享的画像系统。
欢迎 Star ⭐ 关注项目，或 Watch 以获取最新进展！
面向使用者。开发者请参阅
packages/paper-highlight/README.md；设计细节见docs/paper-highlight-agent-design.md；历史进展见docs/paper-highlight-progress-v0.*.md。
这是什么？
Paper Highlight Agent 是一个跑在 DeepSeek Harness（dsh）里的「论文多色高亮助手」：
- 你丢给它一篇论文 PDF；
- 它把论文解析成网页，并逐节提出语义高亮（五色标注）；
- 你在浏览器里审查 / 修改每一处高亮；
- 它从你的修改里学习你的偏好（颜色语义、密度、粒度），越用越准；
- 审查完的论文可以一键导出成带高亮的 HTML 或 Markdown，拿去分享 / 放进笔记软件。
一句话：给 PDF 论文做「带注释的高亮读书笔记」，并且 Agent 会越读越懂你的口味。
快速开始
前提：已安装 @deepseek-ai/dsh，且已创建 paper profile（含 MinerU API key 配置，见设计文档 / 部署文档）。
启动（在任意目录）：
dsh --profile paper --port 3081 --no-open然后浏览器打开 http://127.0.0.1:3081，进入「论文」标签页。
⚠️ 端口纪律：
3081是你在用的这个 Web 会话。不要自己 kill / 重启它；需要重启（例如更新了宿主代码）时由你来操作，重启后刷新页面即可。
完整工作流（一次论文审查）
| 步骤 | 谁来做 | 说明 |
|---|---|---|
| 1. 提供论文 | 你 | 把 PDF 文件交给 Agent（或放到 D:\aa\data\ 对应目录），Agent 调用 parse_pdf 解析成结构化文本 |
| 2. 全局通读 | Agent | 通读全文，产出「论文地图」+ 每节高亮计划（预期颜色 / 密度 / 跳过节），先给你看计划 |
| 3. 逐节 propose | Agent | 一次只做一节：按计划 + 你的画像 + 领域背景，提出候选高亮（颜色 + 理由） |
| 4. 审查 | 你 | 在 GUI 里接受 / 删除 / 改色 / 改范围 / 手动新增 / 写备注（见下方快捷键） |
| 5. 标记节完毕 | 你 | 每节审查完点「标记本节审查完毕」→ Agent 做章节反思，产出画像更新提案 |
| 6. 确认画像提案 | 你 | 在「提案」面板或直接对 Agent 说「确认提案」→ 偏好并入画像（可审计、可回退） |
| 7. 论文完毕 + 导出 | 你 / Agent | 全部节审查完（或说「论文完毕」）→ Agent 产出论文级反思（paper-reflection.md）→ 你点「导出」下载 HTML / Markdown |
GUI 操作指南
主视图（「论文」标签页）
- 顶部工具栏：选论文下拉、刷新、「导出」按钮。
- 审查进度条（图例上方）：
已审 X/Y 节+ 进度条 + 「下一个」未审查节提示 —— 刷新页面不丢进度。 - 图例：五色语义（颜色可在画像面板自定义）。
- 正文：已接受的高亮以
<mark>色块显示，悬停可看理由；点任意色块弹出操作条。 - 节列表：各节状态（已审 / 未审），可「标记本节审查完毕」。
操作条（点中一处高亮后出现）
| 按钮 | 作用 |
|---|---|
| 接受 | 采纳这处候选高亮 |
| 删除 | 移除这处高亮 |
| 5 个色块 | 改色（换成其他语义色） |
| 改范围 | 进入「重新选文」模式，用鼠标重选覆盖范围 |
| 备注输入 | 给这处高亮写一句注释 |
快捷键（论文视图、非输入框内有效）
| 按键 | 作用 |
|---|---|
1–5 |
把当前选中的高亮改为第 1–5 个颜色 |
A |
接受当前高亮 |
D |
删除当前高亮 |
R |
改范围（进入选文模式） |
Esc |
取消（关操作条 / 关导出框 / 退出选文） |
Ctrl+Enter |
标记当前节审查完毕 |
E |
打开 / 关闭导出对话框 |
「新增高亮」没有快捷键 —— 它依赖鼠标选中正文文字（选中即出现「新增高亮」入口）。
导出
- 点工具栏「导出」→ 弹窗里选 HTML 或 Markdown，可选「包含未决（proposed）高亮」（默认只导出已接受 + 手动新增的）。
- 点「下载」→ 浏览器下载一个自包含文件：
- HTML：内联样式、无外部依赖，任何浏览器 / 笔记软件直接打开即见高亮 + 图例；
- Markdown：带
<mark>高亮标记 + 顶部图例，适合 Markdown 编辑器 / 笔记软件。
- 导出文件同时落在
data/<paper_id>/export/目录，可随时取用。
五色语义与你的画像
默认五色语义（可在「画像」面板改颜色 / 改文字）：
| 颜色 | 语义 |
|---|---|
| 🔴 红 | 核心洞见 / 贡献 |
| 🟡 黄 | 关键定义 / 方法 |
| 🔵 蓝 | 局限 / 风险 |
| 🟢 绿 | 可借鉴 / 启发 |
| 🟣 紫 | 待深挖 / 存疑 |
- 画像（
highlight-profile/）由四层构成：颜色语义、规则（密度 / 粒度等）、示例库、统计。你每次「接受 / 删除 / 改色 / 改范围」都是学习信号。 - 你的确认是唯一的落库通道：Agent 只产出「提案」，你确认后偏好才并入画像（低置信规则以「禁用候选」形式入库，可在画像面板手动启用）。
- 领域背景：Agent 参考工作区内的
field-map.md（领域发展线）判断语句分量 —— 范式转移节点的句子会优先高亮。
数据都在哪？
| 路径 | 内容 |
|---|---|
D:\aa\data\<paper_id>\ |
每篇论文：paper.md（文本）、anchors.json（锚点）、paper.highlights.json（高亮 + 计划）、reflections.json（反思提案）、paper-reflection.md（论文级反思） |
D:\aa\data\<paper_id>\export\ |
导出产物（<paper_id>.html / <paper_id>.md） |
D:\aa\highlight-profile\ |
你的画像：colors.yml / rules.json / exemplars.json / stats.json / reflection-notes.md |
D:\aa\field-map.md |
领域发展线（Agent 建议、你也可手工编辑，追加式） |
数据根目录解析顺序：profile 配置
root（已钉D:\aa）→ 环境变量PAPER_HL_ROOT→ 当前目录（兜底）。
常见问题（FAQ）
- 刷新 / 重开会话后进度还在吗？ 在。审查状态写入
paper.highlights.json，刷新即恢复（进度条按节状态显示）。 - Agent 提的高亮不合适？ 直接删 / 改色 / 改范围即可；你的操作会进入学习信号，越用越贴合。
- 为什么这次高亮更「克制」了？ 画像在收敛 —— 你删得多的地方 Agent 会降低密度；反之会适度放开。
- 导出 HTML 打不开 / 样式怪？ 它是自包含的，直接双击打开即可；若在笔记软件里预览异常，用浏览器打开或换 Markdown 格式导出。
- 想从零重新学？ 在画像面板编辑 / 清空对应层即可（文件也可手工改）。
- 提案面板有未确认的项？ 那是一次「画像更新提案」，确认后才生效；不确认则保持现状，可随时再来。
版本状态
- v0.1 管线打通 ✅ · v0.2 审查闭环 ✅ · v0.3 画像收敛 ✅（三篇论文修改率 50%→33%→0%）· v0.4 打磨导出 ✅（归档 v0.4.0）：HTML/MD 导出、领域地图、论文级反思、快捷键 / 进度条 / 导出对话框。