ChatPDF Pro 把 PDF、结构化阅读和带引用的问答放在同一个工作区。上传前先选定 MinerU 或本地解析；解析完成后，速览、全文总结、大纲、翻译和 RAG 问答都读取同一份块级索引。回答里的引用可以直接跳回 PDF 原页。
文档、聊天、笔记和高亮默认保存在本机。使用 MinerU 时，PDF 会发送到你配置的 MinerU 服务；使用云端对话、嵌入或视觉模型时，相应内容会发送给模型提供商；联网搜索只在开启后发送查询。通过 DOI、arXiv、标题或论文网页导入时，标识或标题会发送给学术元数据服务，确认候选后才下载 PDF。需要尽量减少外部传输时，请选择本地上传、本地解析、本地模型并关闭联网搜索。
全文导读、关键图表解读与 PDF 原文对照
右侧「速览」会通读全文，生成概述、术语、方法与实验、关键图表和结论。它不是当前页摘要。
| 速览深度 | 适合场景 | 内容范围 |
|---|---|---|
| 简略 | 先判断论文是否值得细读 | 3 个术语，最多 2 张关键图表 |
| 标准 | 日常阅读，默认档位 | 5 个术语，最多 3 张关键图表 |
| 详细 | 精读方法、实验和图表 | 8 个术语，最多 5 张关键图表；会读取更多上下文并消耗更多 token |
完整结果会按文档版本、解析路线、模型和深度缓存。切换视图或重新打开文档不会重复生成；需要更新时再点「重新生成」。
按章节总结全文，并标出对应页码
左侧「总结」按章节整理全文，页码标签可以直接跳回原文。顶部会显示正文和附录的覆盖情况；右侧速览可以保持打开，方便同时核对总体结论和图表解读。
多级章节结构与 PDF 跳转
MinerU 路线直接使用解析结果中的章节层级、编号和页码。点击标题即可定位原文，逐页阅读和连续阅读都支持跳转。
页面翻译、悬浮译文和自由笔记
「阅读」视图把页面翻译和笔记放在同一个工作区。两张组件卡可以拖动换位、调整分栏宽度、收起，或移动为底部通栏。译文按块缓存，支持全文预翻译、原文 / 译文切换和失败块补译；笔记既可以从 PDF 划词创建，也可以直接在当前页新建。
文档问答、思考过程和可跳转引用
回答中的 [1] [2] 只关联本轮实际读取的证据，点击即可回到 PDF。思考过程默认折叠，公式、Markdown 和 Mermaid 可以直接渲染。点名 Figure、表格或架构图时，回答下方会尽量附上从 PDF 裁出的原图；输入框旁还可以框选页面区域，把截图和问题一起发给视觉模型。
上传前先选择路线。文档开始解析后，系统不会在后台悄悄换用另一条路线。
| 路线 | 适合文档 | 说明 |
|---|---|---|
| MinerU（默认） | 扫描件、公式、表格和复杂版面 | PDF 会上传到已配置的 MinerU 服务；正文、章节结构、图表和问答索引全程使用 MinerU 结果 |
| 本地解析 | 原生文本 PDF，或希望尽量在本机处理 | 使用 PyMuPDF、pdfplumber、OpenDataLoader 和 DocLayout-YOLO；首次选择时会提示安装本地组件 |
两条路线都会发布统一的块级索引。速览、总结、大纲、翻译和问答只读取当前文档已发布的路线与版本，旧缓存不会混入新结果。OCR 和 YOLO 是本地路线内部的补充能力，不是额外的解析路线。
- PDF.js 原文渲染，支持逐页 / 连续阅读、缩放、页码跳转、划词和高亮。
- 全文总结、大纲、速览、翻译与笔记可以同时使用，不需要反复切换页面。
- 翻译和笔记组件支持拖动换位、左右分栏、底部通栏、折叠和高度调整；布局会保存在本机。
- 译文按块增量保存。长文档预翻译中断后，已完成部分仍会保留，只补失败或缺失的块。
- MinerU 上传、解析、结果下载和索引构建都有进度；后台任务可以取消或重试。
- 可以在当前页直接写自由笔记，也可以先划选 PDF 原文，再创建带摘录的引用笔记。
- 引用笔记会保留页码和选区坐标。点击「定位原文」即可返回对应页面，并重新标出当时的文字范围。
- 编辑器采用就地 Markdown 预览：光标所在行保留原始标记，其余内容直接按标题、列表、粗体、引用等样式排版，不需要在编辑和预览之间切换。
- 支持标题、列表、任务清单、粗体、斜体、删除线、引用、链接、代码块、GFM 表格和 LaTeX 公式；保存后会渲染代码高亮与 KaTeX 公式。
- 面板只显示当前页的笔记，翻页时随页面切换。笔记、高亮和会话会写入本机后端的用户资产目录，浏览器
localStorage只保留迁移源与离线缓存；写入带 revision，多个窗口不会静默覆盖。 - 支持
[[note:笔记ID]]、[[paper:论文ID]]、[[doc:文档ID#section:章节ID]]双向链接。代码块中的相同文本不会被误识别，缺失、歧义和无效章节是明确状态；笔记卡会显示反链数量。
- BM25、分块向量和语义意群向量通过 RRF 合并，兼顾精确词、语义近义和章节上下文。
- Agent 可以搜索文档、读取完整章节、补读命中块前后文，并在证据不再增加时提前停止。
- 表格查询会保留表头、目标行和对照行；公式在检索前做 LaTeX / OCR 归一化。
- 最终引用只能来自本轮工具实际返回的证据。未知或失配的证据编号会被过滤。
- Trace 面板显示检索步骤、工具调用和停止原因；回答风险检查单独给出提示。
- 上传并完成解析后，系统只从论文正文、页面文本和块索引中识别论文自己出现的公开仓库地址，不会凭预训练知识猜仓库，也不会把联网搜索结果当成论文代码仓库。
- 当问题涉及“怎么实现”“训练脚本在哪里”“损失函数对应哪段代码”等内容时，Agent 会按
list_paper_repos → search_paper_repo → read_paper_repo的顺序工作：先登记仓库，再按路径关键词找源码，最后读取实际文件正文。 - 首次登记可自动读取 README、目录树和一个高相关实现入口；目录命中后还会自动读取最多两个源码文件，必要时可继续按路径或游标读取。代码内容会进入独立的
PAPER_REPO_EVIDENCE证据通道。 - 当前只有公开 GitHub 仓库支持匿名目录和文件读取；GitLab、Hugging Face 只登记和展示地址，不读取文件。仓库必须由论文正文明确提供，不能手写任意
repoId或 URL。 - 访问是只读的，不克隆、不写入、不执行仓库代码或 README 命令。路径会做相对路径校验，二进制、权重、压缩包和过大的文件会被跳过；每轮有目录搜索、文件读取和字符数预算。
- 回答中的论文事实继续使用文档
[n]引用；代码事实使用“文件路径 + 符号名”标注。Trace 面板会显示仓库识别、路径检索和文件读取过程。
- MinerU 解析出的图片、表格和公式会发布为带页码、坐标和文档版本的视觉资产。
- 速览、文档问答和视觉搜索共用这些资产，不会分别裁剪同一张图。
- 问到具体图号或架构图时，回答会从这份资产索引裁出原图挂在正文下方，并可以定位回 PDF；图不是模型画出来的。
- 当前对话模型具备视觉能力时，可以用区域截图把页面局部和问题一起发送。
- 主解析缺少图表区域时，本地路线可以用 DocLayout-YOLO 补充定位；视觉模型只处理需要解读或核验的区域。
- 数值表格支持可选的视觉核验，核验结果只标记为确认、冲突或无法判断，不会覆盖原始文本。
- 支持 OpenAI、Anthropic、Gemini、Grok、DeepSeek、Kimi、Qwen、GLM、MiniMax、Ollama，以及 OpenAI 兼容接口。
- 对话、嵌入、重排和视觉模型分别配置。没有视觉能力的模型不会被当作视觉模型使用。
- 思考档位按模型能力显示，例如
off、minimal、low、medium、high、xhigh、max或ultra；不支持的档位不会发送给服务商。 - 联网搜索有关闭、自动和强制三种模式。自动模式由 Agent 根据问题决定是否搜索以及搜索什么，不会简单把整段提问原样提交。
- 网页证据与文档证据分开标记。公开网页、GitHub 内容和 YouTube 公开字幕可在授权后继续读取。
- 文档结果绑定解析路线、解析代次和源文件哈希。重新解析或换路线后，旧的速览、总结、翻译和 RAG 索引会失效。
- 桌面后端只绑定
127.0.0.1，并使用会话令牌保护 API。 - 外部网页正文和模型输出都按不可信内容处理，不能反向修改系统指令或伪造文档引用。
- 文档、PDF 版本、解析代次、会话、请求运行和消息分别使用独立 ID；流式事件带单调序号，迟到事件不会写进另一个会话。
- 解析设置中的「当前文档健康检查」会核对原 PDF、解析身份、阅读结构、FAISS 对、语义组、视觉资产、用户资产和下游任务。自动修复只处理可重建派生产物，并在失败时回滚。
- 上传区「从 Zotero 导入」或左侧栏「Zotero 导入 / 导出」可连接本机 Zotero Desktop，按标题、作者和分类查找论文，再选择 PDF 附件导入。
- 请先启动 Zotero，并在其「设置 → 高级」中允许本机应用通信。PDF 需已下载到本机；关联附件会经过归属与 PDF 内容校验。
- 导入沿用当前解析路线和 Embedding 配置，同一 PDF 重复导入时打开已有文档，无须重复解析。
- 打开论文后，切到「导出到 Zotero」，先在 Zotero 中选好分类，返回 ChatPDF 确认目标并导出题录。标题、作者、年份、期刊、DOI、URL 和摘要会写入 Zotero；PDF、聊天和笔记不随题录导出。
- Zotero 未启动时仍可下载 RIS，再在 Zotero 中导入。导出结果不明时先检查目标库，避免产生重复条目。
- 当前支持同机运行的 ChatPDF 与 Zotero 个人库，不支持远程服务器桥接、群组库或双向自动同步。Zotero 导入后的 MinerU / 云模型数据传输规则与普通上传相同。
- 首页上传卡的
DOI / arXiv入口支持 DOI、arXiv、论文网页、直接 PDF 链接和完整标题。 - 标题检索最多显示 5 个带强标识候选；候选超过一个时必须手动选择，不会默认导入第一条。
- 确认后才获取 PDF。每次 HTTPS 重定向都会重新校验公网 IP，连接建立后还会核对实际 peer；文件有大小限制并必须通过 PDF magic 校验。
- 元数据、PDF 获取、MinerU 解析和问答索引分别显示状态。没有开放 PDF 时保留元数据任务，可改用本地上传；DOI/arXiv 或文件哈希重复时直接打开已有文档。
- 「设置中心 → 全局设置 → 论文订阅库」的发现结果也提供「导入」入口，走同一候选确认与解析状态机。
这些入口都在阅读区和对话输入栏附近，不需要另外打开独立页面。
对话输入卡顶部会显示本轮实际使用的上下文：当前文档、PDF 选区、页面截图、关联文档，以及手动添加的章节、图表、笔记或段落。
- 点击
@按钮，或在输入框的词边界直接键入@，可以搜索当前解析代际中的章节、图表、笔记、当前页段落和已上传文档。 - 选择结果只携带服务端签发的文档、章节、块、图表或笔记 ID，不会把本地文件路径放进请求。
- 手动添加的项目默认只用于下一轮；点击图钉后会跨多轮保留，直到手动移除。固定状态只存在于当前页面会话，刷新后不会恢复。
- 可以逐项移除，也可以清空附加上下文；清空后短时间内可以撤销。
- 只选择章节、图表、笔记或段落而不输入文字也可以发送，系统会明确使用“请基于所选上下文回答”。
- 单轮最多添加 8 项显式上下文、关联 4 篇其他文档。文档重新解析后，旧项目会标记为“已失效”，不会静默匹配到新版本中的其他内容。
- 发送后，用户消息上方会保留本轮冻结的上下文摘要；页面随后切换不会改变已经发出的 snapshot。
当前对话模型需要带视觉能力（设置里带 vision 标签）。输入框右侧出现扫描按钮后：
- 点击「区域截图」，在 PDF 上拖出选区。
- 截图会出现在输入框上方，单轮最多 4 张；悬浮或点击可展开管理、删除单张。
- 可以直接输入问题后发送，也可以对最新一张使用快捷操作。
| 操作 | 作用 |
|---|---|
| 提问 | 聚焦输入框，自己写问题，截图作为附件一起发送 |
| 解释 | 立刻解读图中内容、趋势或文字要点 |
| 表格 | 把图中表格转成可复制的 Markdown |
| 公式 | 把图中公式转成 LaTeX |
| OCR 提取 | 只抽出文字，尽量保持原排版 |
| 翻译 | 把图中内容译成中文，代码和专有名词保留原文 |
| 复制 | 把这张截图复制到剪贴板 |
截图只跟随这一轮提问，发送后会从输入栏收起。可在「设置中心 → 界面 → 区域截图」关闭该按钮。表格核验走阅读里配置的视觉模型，不走检索辅助模型。
对「解读一下 figure 2」「图 3 在讲什么」「这张架构图」这类问题，回答正文下方会尽量挂上解析阶段抽出的原图，标签一般为「解析图表」。点击可回到 PDF 对应页。若解析时没有抽出这张图的位置，就只会看到文字解读。历史消息不会事后补图，需要再问一次。
在文档解析完成后，可以直接提问：
本文的损失函数在公开代码里怎么实现？请对照论文说明训练入口、关键参数和差异。
实现类问题不需要手动粘贴仓库地址。只要论文正文包含公开 GitHub 链接，Agent 就会自动识别并读取相关 README、目录和源码窗口；如果论文没有提供可读取的 GitHub，系统会明确说明并只使用论文证据回答。
在 PDF 里划选文字后，工具栏可以直接：
- 复制、高亮或下划线，颜色可改。
- 把选区存成引用笔记，并保留页码和坐标。
- 让对话解释或翻译这段话。
- 用设置里指定的搜索引擎检索选区。
- 调用系统分享，或把摘录复制出去。
开启「预翻译全文」后，已译好的段落可以悬浮查看译文，不必每次划词再翻译。
「设置中心 → 阅读」里这几项只影响打开文档后会不会自动调用模型：
| 开关 | 作用 |
|---|---|
| 智能阅读 | 关闭后打开文档不自动调用模型 |
| 大纲与总结 | 打开后生成左侧总结和大纲 |
| 预翻译全文 | 提前译好正文，悬浮即可查看；较耗额度 |
| 逐段要点 | 正文每段多一句要点；每段多一次模型调用 |
速览详细度（简略 / 标准 / 详细）只改默认深度，不会因为改档位就自动重新生成。
- 空对话会在输入框上方给出预设问题，点一下即可发送。
- 回答可以折叠思考过程；结束后可展开查看用时。
- 回答下方可能出现追问建议、思维导图、记忆命中和风险提示。
- 点赞回答会写入本机记忆，后续相关问题可以带上。
- 输入栏可以关联其他已解析文档，把多篇材料放进同一轮问答。
- 联网搜索有关闭、自动、强制三档；自动档由 Agent 决定是否搜索，不会把整段提问原样提交。
- Trace 面板列出本轮检索步骤和工具调用，方便核对引用从哪里来。
项目使用固定的 26 题多论文集合做开发回归。它不是公开排行榜；只有使用同一问题集和同一 index_source 的结果才可直接比较。
| 索引 | Faithfulness | Answer Relevancy | Context Precision | Context Recall | Answer Correctness |
|---|---|---|---|---|---|
A1 pdf_native |
0.8173 | 0.4268 | 0.7033 | 0.8077 | 0.7211 |
当前 mineru |
0.9695 | 0.3399 | 0.8765 | 0.9615 | 0.7528 |
17 题 numeric_table 子集结果：
| 索引 | Faithfulness | Context Precision | Context Recall | Answer Correctness |
|---|---|---|---|---|
A1 pdf_native |
0.8300 | 0.8140 | 0.8820 | 0.7600 |
当前 mineru |
0.9733 | 0.9533 | 1.0000 | 0.7986 |
当前 MinerU 索引在忠实度、上下文精度、召回率和答案正确性上高于 A1；Answer Relevancy 从 0.4268 降至 0.3399。该指标对短数值答案较敏感，本表仍按原值报告。
从 Releases 下载最新 Windows 安装包。已发布安装包内含前端和 Python 后端，不需要另装 Node.js 或 Python。
以下流程会先生成构建身份清单，再分别重建前端、冻结 Python 后端，最后生成 x64 NSIS 安装包：
scripts/build-all.bat默认产物位于 electron/release/。安装包文件名会包含版本号与 Git 短 SHA，并生成 release-manifest.json 与 .sha256 校验文件，便于定位用户实际安装的代码。打包规则会在 PyInstaller 和 Electron 资源复制两个阶段排除 data/、uploads/、logs/、cache/、history/、memory/、向量/语义索引、测试/课程/评测目录、PDF/数据库/序列化产物、.env、日志和 API Key 命名文件。不要手动将本机用户数据目录或开发环境的 data/ 复制到该目录。
版本信息以仓库根目录 version.json 为唯一来源；/version、/health、/capabilities、Electron 包版本和前端静态版本都必须与它一致。发布前可运行：
python scripts/release_metadata.py --check需要：
- Python 3.10+
- Node.js
^20.19.0或>=22.12.0 - npm
Windows：
git clone https://github.com/juyou4/ChatPDF-Pro.git
cd ChatPDF-Pro
.\start.batLinux / macOS：
git clone https://github.com/juyou4/ChatPDF-Pro.git
cd ChatPDF-Pro
chmod +x start.sh
./start.sh启动脚本会先检查 origin/main，在工作树干净且当前位于 main 时自动快进到最新提交，然后安装或校验运行所需依赖并打开 http://localhost:3000。如果本地有未提交改动，脚本不会覆盖文件，但会显示远端待更新提交数；网络失败也会显示诊断并继续使用当前版本。依赖文件变化时才会重新同步 Python 和前端依赖，不会每次启动都重装。需要离线启动时可设置 CHATPDF_SKIP_UPDATE=1。本地解析组件不会随基础依赖一起安装，第一次选择本地路线时再按界面提示安装。
后端：
cd backend
python -m pip install -r requirements-core.txt
python app.py前端另开一个终端：
cd frontend
npm install
npm run dev前端默认使用 http://localhost:3000，后端默认使用 http://127.0.0.1:8000。
除了内置问答，也可以让本机的 Codex、Claude Code、Gemini CLI、OpenCode、Qwen Code 或 Cursor 阅读论文、调用章节和代码仓库工具。无需手工复制 CLI 的登录凭据。
- 打开「设置中心 → 外部 Agent」，自动识别六种受支持的 CLI，无需填写路径。
- 未安装或版本过旧时，点击「安装 / 升级」并确认。自动安装需要 Node.js，只写入 ChatPDF 专用目录，不覆盖全局 CLI。Cursor 使用卡片上的「官方安装说明」，安装后点击重新检测。
- 点击「登录」：Codex / Claude Code 沿用官方浏览器授权；Gemini CLI、OpenCode 和 Qwen Code 打开官方 CLI 登录窗口。Qwen 在窗口内使用
/auth，OpenCode 在菜单中选择服务商。完成后退出窗口并重新检测；已配置的 CLI 可直接点击「使用」。 - 打开已解析的论文后提问，可通过
@附加章节、图表文字、笔记及关联文档。自定义路径、模型、思考档位和内置 Agent 委派开关都在「高级设置」中。
新增三种 Agent 使用 ACP 增量协议，同样经过本轮文档范围、MCP token 与引用账本。自动检测不会创建模型会话或弹出登录窗口。当前已核对的最低 CLI 版本为 Gemini 0.59.0、OpenCode 1.18.30、Qwen 0.23.1；不具备所需协议或工具限制参数时会提示升级。交互式登录窗口支持 Windows 和具有 x-terminal-emulator 的 Linux；其他环境可使用卡片中的登录说明。
Cursor 也通过 ACP 接入，使用只读 Ask 模式。点击「登录」完成官方浏览器授权，凭据由 CLI 保存到 ChatPDF 专用配置目录，不继承原来的 MCP、规则或插件。支持章节读取、论文引用与原生截图；截图须通过 CLI 图片能力检查。仅安装 Cursor 编辑器不等于安装了 Cursor CLI。
回答展示 CLI 实际输出的正文、思考摘要（如果提供）、工具执行记录和已读取证据的引用。支持停止和超时终止；未安装、未登录、协议过旧与模型不匹配均会明确报错，不会消耗草稿后留下一条空回答。
当前支持同机、只读任务：读取本轮最多五篇论文及论文中登记的公开代码仓库。文档搜索使用已配置的嵌入与重排服务；联网跟随输入框开关，查询过程和网页来源可查看。六种执行器均已接入原生截图传递，使用所选 Agent 的模型和登录状态，无需另外配置视觉 API。CLI 或模型不支持图片时会明确提示，不会自动转交其他视觉服务。回答中的论文图片可放大、定位。
外部问答也支持相关记忆、引用检查，以及配置辅助模型后的受控答案修复。正文和思考通过 SSE 增量显示，刷新或断线后可续接后台原任务；创建请求使用防重标识，避免网络重试重复生成。修复后的答案会重新对齐引用，删除会话也会清理关联运行记录和引用备份。每轮仍使用临时 CLI 会话，不使用 CLI 原生会话续跑，也不执行 Shell、修改代码或运行实验。
CLI 使用自身的登录、模型服务和计费设置；论文内容及所选笔记会随问题发送给对应模型服务。连接测试不生成模型回答，也不保证实际调用的余额或网络一定正常。ChatPDF 原有的 MinerU、嵌入、总结和速览配置保持不变。详细协议与限制见 外部 Agent 接入说明。
MCP 默认关闭。启用时必须同时配置独立 token，并且服务只接受 loopback 客户端：
$env:CHATPDF_MCP_ENABLED = "true"
$env:CHATPDF_MCP_TOKEN = "请换成高强度随机值"
python backend/app.pyStreamable HTTP 端点是 http://127.0.0.1:8000/mcp，使用 Authorization: Bearer <CHATPDF_MCP_TOKEN>。工具仅包含文档列表/详情、文档检索、块/章节/邻近块读取、结构地图、视觉资产检索和论文正文已登记的公开仓库读取；不提供 Shell、Python、任意文件、任意 URL、删除、密钥或模型配置。MCP token 不会返回 WebView。
源码模式的 CLI 复用同一公共工具合同，并只访问正在运行的后端：
cd backend
python chatpdf_cli.py document list --query adapter
python chatpdf_cli.py retrieve read-section DOC_ID SECTION_ID --max-chars 6000
python chatpdf_cli.py --pretty doctor scan DOC_ID
python chatpdf_cli.py doctor repair DOC_ID -y桌面/远程 token 模式下通过 CHATPDF_BACKEND_TOKEN 或 --token 提供后端令牌。CLI 默认向 stdout 输出紧凑 JSON；--pretty 格式化，--fields docId,title 只保留指定顶层字段。Doctor 修复和任务取消没有 -y 时返回 needs_confirmation，不会进入交互等待。
所有入口都在左下角「设置中心」。
| 配置 | 是否必需 | 用途 |
|---|---|---|
| 对话模型 | 是 | 问答、总结、速览和翻译 |
| 嵌入模型 | 是 | 构建和查询文档向量索引 |
| MinerU 服务 | 使用默认路线时需要 | 上传 PDF、获取结构化正文、章节和视觉资产 |
| 视觉模型 | 可选 | 图表解读、表格视觉核验和截图提问；可跟随具备视觉能力的对话模型 |
| 联网搜索 | 可选 | 搜索文档外的实时信息并附公开来源 |
推荐流程：
- 配置对话模型和嵌入模型。
- 在上传按钮旁选择 MinerU 或本地解析。
- 上传 PDF，等右上角任务面板显示解析和索引完成。
- 先看速览或大纲，再进入阅读和对话。
- 需要框选图表或公式提问时，把对话模型换成带视觉能力的模型，再点输入框旁的截图按钮。
回答不够可信时，先点引用回看原文，再展开 Trace 查看实际使用了哪些工具和证据。需要刷新速览、总结或大纲时使用对应的「重新生成」，不要通过反复切换视图触发。
| 层 | 主要技术 |
|---|---|
| 前端 | React 18.3、Vite 7.3、Tailwind CSS 3.4、Motion 12 |
| PDF 与内容渲染 | react-pdf 9、PDF.js 4.8、React Markdown、KaTeX / MathJax、Mermaid |
| 后端 | Python 3.10+、FastAPI 0.115、Uvicorn、Pydantic 2 |
| 文档与检索 | PyMuPDF 1.24、pdfplumber 0.11、FAISS 1.9、LangChain 0.3、jieba |
| 本地解析扩展 | OpenDataLoader、DocLayout-YOLO、Tesseract |
| 桌面端 | Electron 28、electron-builder 24、PyInstaller |
前端：
cd frontend
npm run lint
npm run test
npm run check:streaming后端：
cd backend
python -m pytest桌面打包：
cd electron
npm run package:win项目目录
ChatPDF/
├── frontend/
│ └── src/
│ ├── components/ # PDF、速览、阅读、对话与设置界面
│ ├── hooks/ # 文档、消息、流式输出与 UI 状态
│ ├── contexts/ # 模型、阅读、字体和全局设置
│ └── config/ # Provider 与系统模型定义
├── backend/
│ ├── app.py # FastAPI 入口
│ ├── routes/ # 文档、对话、搜索和模型接口
│ ├── services/ # 解析、索引、Agent、视觉、翻译和缓存
│ ├── tests/ # 后端回归与属性测试
│ └── requirements*.txt
├── electron/ # 桌面主进程、预加载和打包配置
├── docs/ # README 图片
├── scripts/ # 启动、构建与诊断脚本
├── start.bat
└── start.sh
不需要。MinerU 是默认路线，适合扫描件和复杂版面；原生文本 PDF 可以选择本地解析。本地路线第一次使用时会提示安装版面模型和 OCR 运行时，Java 11+ 只用于可选的 OpenDataLoader 清理。
安装包不包含用户历史。相同 Windows 账户下安装或升级时，桌面端会继续使用该账户已有的应用数据目录，因此本机旧记录仍会显示；新系统账户或没有既有应用数据的设备会从空库开始。
确认后端已启动（默认端口 8000），再检查浏览器控制台是否存在 CORS 或网络拦截错误。
先在「设置中心 → 解析设置 → MinerU 服务」测试连接。官方直连模式不会继承普通 HTTP 代理环境变量，但系统级虚拟网卡仍可能改变出口 IP；如果 MinerU 拒绝当前出口，请关闭虚拟网卡，或为 mineru.net 配置直连分流。Worker 模式还要确认 Worker 已部署对应的上传、查询和下载接口。
这是正常的。完整速览会按文档版本、解析路线、模型和深度缓存。点击「重新生成」可以主动刷新；重新解析、切换路线或更换相关模型后，旧缓存会自动失效。
这些功能要等主解析和问答索引一起发布。右上角任务面板会显示上传、解析、下载和索引进度。解析失败或被取消后，应先重试解析，不要在旧索引上继续生成下游内容。
本地文档库、聊天、笔记、高亮、任务状态和索引默认保存在本机。MinerU 路线会上传 PDF；云端模型会接收完成当前任务所需的文本或图片；联网搜索会发送查询，只有显式允许时才附带文档上下文。DOI/arXiv/标题导入会请求 Crossref、Semantic Scholar 等学术元数据源，并在确认候选后从公开来源下载 PDF。若要尽量在本机处理，请使用本地文件上传、本地解析、本地对话与嵌入模型，并关闭联网搜索。
确认 Ollama 已启动，并允许 ChatPDF 所在来源访问。Web 模式跨域失败时，可按 Ollama 文档配置 OLLAMA_ORIGINS；桌面模式优先使用本机接口地址。
截图提问要求当前对话模型具备视觉能力，并且「设置中心 → 界面 → 区域截图」保持开启。纯文本模型不会显示该按钮。换用带 vision 标签的模型后即可框选页面区域。
回答里的图来自解析阶段抽出的图表位置，不是模型生成的插图。文档还在解析、或解析结果里没有这张图的坐标时，就只会看到文字。解析完成后重新提问一次即可；旧消息不会补图。
在设置中心切换 KaTeX 或 MathJax。KaTeX 更快，MathJax 对复杂 LaTeX 的兼容性更好。
- 接入 Codex、Claude Code、Gemini CLI、OpenCode、Qwen Code 和 Cursor，提供自动识别、登录入口与原生截图能力检查。
- 外部问答共用文档检索、重排、图表资产、联网来源和相关记忆；图表支持预览、放大与 PDF 定位。
- 修复引用元数据缺失、修复后引用支撑关系未更新，以及大结果截断导致计数和分页游标不一致的问题。
- 增加请求防重、SSE 增量流和断线续接；按文档、查询和通道分别判断证据饱和。
- 删除会话同步取消关联任务并清理运行记录，阻止迟到结果重新写回；完善超时与截图错误反馈。
- v3.3.0：论文 Git 仓库识别与代码对照讲解、精读降级修复、多文档检索与引用回程、设置中心重整、回答结束后不再卡住生成态、悬浮译文防裁切。
- v3.2.0：流式思考与公式、问图对照原图、截图提问与设置优化。
- 上传前固定 MinerU / 本地主解析路线，下游统一使用同一解析身份。
- MinerU 章节、图表和表格结果进入统一块级索引，供速览、阅读和问答复用。
- 增加完整章节读取、邻域补读、引用授权和证据饱和停止。
- 联网搜索改为 Agent 规划查询，并支持继续读取已授权网页来源。
- 重做全文总结、大纲、翻译、笔记、任务进度和流式回答界面。
- 加强缓存失效、任务取消、旧代次写入拦截和桌面发布数据过滤。
当前源码版本为 v3.3.1。桌面安装包以 Releases 中实际发布的版本为准，本次源码更新不包含新版安装包。完整变更记录见 Git 提交历史。
欢迎提交 Issue 和 Pull Request。改动前请先确认问题可以复现，提交前运行与改动范围对应的测试。
- Fork 本仓库
- 创建分支（
git checkout -b feature/my-change） - 提交更改（
git commit -m "feat: describe the change"） - 推送分支（
git push origin feature/my-change） - 提交 Pull Request
语义意群和多粒度检索的设计参考了 Paper Burner X。依赖与第三方署名见 THIRD_PARTY_NOTICES.md。
本项目采用 MIT 许可证，详见 LICENSE。
ChatPDF Team