Paper Highlight Agent —— 用户指南与技术概览 (README)

🗺️ 路线图

• v0.7（当前版本）：已完成核心功能，适用于论文高亮场景下的个性化学习闭环。
• v1.0（计划 2026.09）：将提升稳定性与易用性，完善细节，正式发布稳定版本。

欢迎 Star ⭐ 关注项目，或 Watch 以获取最新进展！

---

Paper Highlight Agent 是一款运行于本地 DeepSeek Harness (DSH) 平台的 Human-in-the-loop（人机协作）论文多色高亮智能体。

系统通过 MinerU 解析学术 PDF，借助大模型自主通读并分节提议高亮，用户在 Web GUI 中进行极简审查。Agent 则基于“提案防污染机制”，从用户的微调决策中提炼个性化画像，实现越用越贴合个人阅读偏好的持续演进。

• 交互端点：http://127.0.0.1:3081（DSH Web GUI）
• 本地工作区：D:\aa（语料库 data/ + 画像库 highlight-profile/）

---

架构简述：本项目如何运作？（技术摘要）

详细架构设计请参阅报告文档：

• 插件架构与工具调用规范 ➔ docs/paper-highlight-report-01-dsh.md
• 状态机流转与自适应画像机制 ➔ docs/paper-highlight-report-02-agent.md

1. DSH 插件化生态嵌入（Report 01 摘要）：
   • 单一真理源数据驱动：Agent（通过 12 个原子工具）与前端 GUI（通过 HTTP API）读写完全相同的结构化文件 data/<paper_id>/paper.highlights.json，彻底规避主从同步冲突。
   • 微内核挂载：通过 Cordis 运行时补丁注册路由、向会话动态注入 3 个工作流技能、注入前端 KaTeX 渲染引擎。
2. 人机协同与节级状态机（Report 02 摘要）：
   • 节级增量推进：Agent 全文规划后，坚持一次只处理一节，写入候选标注后立即挂起等待，避免一次性生成导致的高昂返工成本。
   • 用户终审合入：用户在 GUI 上的操作实时沉淀为 Append-only 决策日志；反思模块仅产出提案，由用户审批后由 Host 进程合入画像，杜绝大模型幻觉污染。

---

一、核心剖析：自适应四层画像系统（Highlight Profile）

画像系统（位于 highlight-profile/）是 Agent 具备“记忆”与“个性化对齐”的灵魂。它并非一个笼统的 Prompt 文本，而是解耦为 由抽象到具象、由硬约束到软信号 的四层递进式架构：

┌────────────────────────────────────────────────────────────────────────┐
│ L1 颜色语义层 (colors.yml) ── 【认知基底】                               │
│ 明确定义：每种颜色代表何种学术概念价值（不可模糊）                       │
├────────────────────────────────────────────────────────────────────────┤
│ L2 偏好规则层 (rules.json) ── 【硬性基准】                               │
│ 明确约束：单节高亮密度、长短切词粒度；含「置信度隔离」安全锁              │
├────────────────────────────────────────────────────────────────────────┤
│ L3 典型示例库 (exemplars.json) ── 【直觉参考】                           │
│ 动态范例：提供少样本 (Few-shot) 参照，记录用户的微调模式                │
├────────────────────────────────────────────────────────────────────────┤
│ L4 置信度统计 (stats.json) ── 【决策温控】                               │
│ 量化指标：记录历史认可率，动态调节提议时的「激进 / 保守」风格             │
└────────────────────────────────────────────────────────────────────────┘

---

L1 · 颜色语义层 (colors.yml) —— 建立概念认知体系

定义系统允许使用的颜色色值及其对应的学术核心语义。Agent 不会随意给句子上色，必须严格对齐 L1 的分类法。

• 系统内置 5 色基准：
  • red（核心贡献 / 创新洞见）：解决什么痛点、核心主张、突破性结论。
  • yellow（关键定义 / 核心方法）：模型架构名词、数学符号定义、关键算法流程。
  • blue（局限性 / 潜在风险）：作者自我审视的缺点、边界条件、未解决的缺陷。
  • green（启发借鉴 / 可复用机制）：对后续工程实践或迁移研究有启发的技巧。
  • purple（存疑点 / 需深挖逻辑）：论证略微跳跃、实验支撑单薄、需要二次查阅的地方。
• 支持自定义：用户可在面板中修改定义（如将绿色重新定义为“数据集说明”），修改后优先以用户定义的语义覆盖系统基准。

---

L2 · 偏好规则层 (rules.json) —— 行为密度与粒度约束

约束 Agent 提议时的宏观尺度与排版边界，主要管理密度与文本切分粒度。

• 包含的核心规则维度：
  • 密度基线（Density Baseline）：定义正文单节容纳的最佳标注条数（默认建议 3～5 处/节）。
  • 粒度倾向（Granularity Bias）：定义用户习惯标注“完整长句（Sentence-level）”还是“核心动宾短语（Phrase-level）”。
  • 结构感知（Section Bias）：定义特殊章节（如 Abstract、Related Work）的特殊缩减规则。
• 低置信度隔离锁（enabled: false）：
  • 当 Agent 在单次反思中提炼出一条新规则（例如“用户似乎喜欢把含数学公式的句子都标黄”）时，由于单次样本置信度不足，系统会将其标记为 enabled: false（禁用候选）入库。
  • 只有当该行为在后续多篇论文中被重复确认、积累了充足置信度后，系统才会在提案中建议将其激活（enabled: true），成为全局硬规则。

---

L3 · 典型示例库 (exemplars.json) —— 少样本经验外推

存储具体语境下的真实范例，作为 Prompt 的 Few-shot（少样本提示）信号。它不干预硬规则，而是为大模型提供“阅读直觉”。

• 数据组织方式：成对记录 原始文本 + 候选主张 (suggested) + 用户最终修正 (final decision) + 修正理由。
• 软信号特性：当 Agent 处理新章节，发现当前句式与示例库某条“被用户拒绝将模型背景标红”的案例相似时，Agent 会下调标红倾向。这种软信号不会僵化系统，保证了泛化弹性。

---

L4 · 置信度统计 (stats.json) —— 动态决策温控器

记录用户长期与 Agent 交互的接受率量化指标（如“累计审查 3 篇 · 样本总数 86 处 · 采纳率 72%”）。

• 如何驱动决策：
  • 高认可率（>75%）：表明画像已高度收敛，Agent 进入高自信状态，会主动参考 L3 示例库进行深度、细粒度的个性化标注。
  • 低认可率（<60% 或冷启动期）：表明用户偏好尚处于摸索期或 Agent 理解存在偏差。Agent 自动切换至保守防御状态，大幅收缩标注数量，仅严格按 L2 的最低密度提议核心事实，极大降低用户审查时的删除心智负担。

---

四层画像的协同推理过程（运行时实例）

当 Agent 读到某节中的句子：

"Unlike previous models, our method uses a dual-encoder to eliminate recurrence bottleneck..."

Agent 的大脑按如下顺序完成决策判断：

1. L4 评估自信度：当前认可率 78%，允许基于模式主动联想。
2. L1 匹配色彩：对比属于“核心创新机制”，初选 red（创新）或 yellow（方法）。
3. L2 检查规则限制：检查当前节是否已超 4 处高亮（已激活规则：单节最多 4 处），若未超标，采纳为“短语级”（enabled: true：偏好短语粒度），剔除修饰词，仅划定核心动宾短语。
4. L3 案例校准：检索到一条相似案例“用户曾把 eliminate bottleneck 改为贡献色”，最终确定赋予 red。

---

二、3 分钟快速上手

1. 检查运行环境

启动 DSH 服务，在浏览器打开：http://127.0.0.1:3081，进入 Paper Highlight 控制面板。

2. 认识内置基准论文

工作区 data/ 目录下已预置 3 篇经典论文，可直接用于体验：

• sutskever2014 (Sequence to Sequence Learning)：功能展示最全，已完成最新锚点重构与排版适配，推荐首选体验。
• bahdanau2014 (Neural Machine Translation by Jointly Learning to Align and Translate)：保留部分进行中的审查状态。
• mikolov2013 (Distributed Representations of Words and Phrases)：已完成基础解析语料沉淀。

3. 发起首次协同

在 DSH 聊天窗口中向 Agent 发送指令：

为 sutskever2014 提出高亮

Agent 将自动加载全局阅读计划技能（paper-hl-global-read），生成策略后开始为第 1 节生成候选高亮，完成后自动在 GUI 中呈现并挂起等待审阅。

---

三、端到端协作标准工作流（SOP）

任务遵循严格的“粗规划 ➔ 节级细交互 ➔ 终态收尾”循环：

【阶段 1：全局规划】 ➔ 【阶段 2：节级循环协作 (核心)】                 ➔ 【阶段 3：收尾归档】
通读全文 ──> 产出 Plan    提出候选 ──> 人工审查 ──> 差异反思 ──> 确认画像     论文复盘与知识沉淀
(global-read)            (propose)    (GUI 介入)   (reflect)    (confirm)      (reflect_paper)

1. 全局通读与策略对齐 (global-read)
   • Agent 通读全篇结构，制定章节策略（预估重点色系、密度基线、跳过引言/附录等）。
   • 用户在 GUI 看到计划生成，前置校准预期。
2. 节级增量提出 (propose)
   • Agent 调取最新画像，读取单节正文生成候选（status: proposed），立即挂起停顿。
3. 专家介入审查（GUI 界面操作）
   • 用户在 Web 端快速判定（接受、改色、微调范围、剔除）。
4. 差异反思与画像提案 (reflect)
   • 单节审阅完毕后，Agent 比对初选与终审差异，生成 reflections.json 偏好提案。
   • 用户在 GUI 提案面板审阅，勾选合理项后点击「确认合并」（防污染合入）。
5. 轮转进入下一节
   • 用户点击 GUI 中的「重新提出高亮」或在对话框中发送“继续下一节”。全文结束后执行 reflect_paper 收尾。

---

四、Web GUI 交互操作手册

1. 单个高亮交互操作条（点击高亮文本触发）

操作指令	对应行为	典型适用场景
Accept (接受)	点击绿色对勾或确认动作	赞同 Agent 给出的颜色与划选范围。
Reject (否决)	点击红色叉号删除标记	内容属于冗余背景或非重点说明。
Recolor (改色)	呼出 L1 调色盘快速切换颜色	认可选中文本，但语义归类不当（如将方法错划为背景）。
Rescope (改范围)	点击后光标重新在原文拉选	Agent 选区过长（整句冗长）或过短（缺少关键限定主干）。
Note (加备注)	为该处标注附加快捷批注	记录阅读灵感、推导疑问或跨论文引用线索。

2. 批量与效率快捷键

• 章节批量审批：点击章节标题右侧的**节芯片（✓）**直接整节批量通过；Shift + 点击可执行整节反选。
• 一键回环指令：审查完成后，点击界面上的「重新提出高亮」，系统后台写入状态标记并自动将下一轮唤醒指令复制到剪贴板，直接 Ctrl + V 贴入聊天框即可唤醒 Agent。
• 导出生成物：支持一键导出包含高亮图例与独立样式的自包含 HTML，或保留结构化标注的 Markdown 文档。
• 系统格式化（⚠️ 高危）：点击「一键格式化」将抹去该论文的全部历史高亮与画像配置，强制回归初始冷启动状态。

---

五、排版渲染引擎与内容治理规则

系统内置专用富文本排版渲染引擎（兼容 v0.6.x 规范），在浏览器端提供媲美出版级论文的阅读体验：

1. 渲染呈现能力

• 行内数学公式：本地离线 KaTeX 极速渲染 $s_{i-1}$、$h_j$ 等片段，无网络延迟与排版方块错误。
• 独立复杂公式块：全面支持矩阵 \begin{array}、多重积分/连乘 \prod 以及公式自动编号标签 \tag{}。
• 原生 HTML 表格：自动识别结构化表格并支持边框对齐与溢出横向平滑滚动。
• 高清图表资产：架构图与实验图表通过专属 Host 静态文件代理（.phl-figure）无损显示。

2. 展示性内容治理红线

• 硬性隔离规则：图片内部、图表数据区、复杂行间公式主体属于纯展示性内容，系统底层强制禁止打高亮。
• 可标注区域：仅限正文段落与图表标题说明文本（*_caption）。底层 Schema 校验器会自动拦截任何跨入展示性块体的高亮提议。

💡 排错提示：静态图片展示依赖 Host 路由扩展。若首次部署遇到图片裂开，只需彻底重启一次 DSH Web 服务即可永久生效。

---

六、工作区目录与数据安全原则

D:\aa (DSH Workspace 根目录)
  ├── data/
  │    └── <paper_id>/
  │         ├── paper.md                # 规范化论文纯文本（带语义锚点）
  │         ├── anchors.json            # 句子级/段落级坐标锚点底座
  │         └── paper.highlights.json   # 标注真理源（含规划、高亮条目、决策全量日志）
  │
  └── highlight-profile/                # 自适应四层画像资产库
       ├── colors.yml                   # [L1] 颜色语义分类法配置
       ├── rules.json                   # [L2] 显式行为准则（含隔离中的候选规则）
       ├── exemplars.json               # [L3] 典型微调案例对照库
       ├── stats.json                   # [L4] 认可率统计与置信度度量
       └── reflection-notes.md          # 历史反思心得记录

• 数据零污染防线：日常浏览、反思分析及渲染引擎对数据只有读取权限。唯一能产生数据修改的行为，是用户在前端确认提案或点击保存。
• 版本追踪提醒：工作区已纳入本地 Git 仓库监管。在完成批次精读后，请手动执行 git commit 与 git push 保存进度（Agent 绝不会私自推送远端）。

---

七、工程文档全景索引

文档路径	核心定位与内容
docs/paper-highlight-report-01-dsh.md	生态集成报告：详细阐述 Host、Client、Tools、Skills 四大挂载点底层机制及 12 个原子工具的职责划分。
docs/paper-highlight-report-02-agent.md	系统主流程与画像架构：深入剖析三轮协同链路、分节挂起状态机、四层画像演进理论与防污染闭环。
docs/paper-highlight-progress-v0.6.md	渲染引擎研发历程：记录 KaTeX 数学公式支持、表格自适应滚动、图片静态代理的演进实录与经验沉淀。
packages/paper-highlight/README.md	代码级实现说明：提供开发架构分解、单测运行指令及构建分发说明。