# AI 专业学习与研究助手（PubScholar Desktop）

这是一个共用同一份核心源码的 Windows 10/11 与 macOS 桌面软件。输入关键词后，程序优先通过 Crossref 官方
REST 元数据接口检索论文；主来源无结果或无法连接时，自动尝试 PubScholar 备用检索。

## 功能

- 中文关键词和英文关键词检索（Crossref 优先，PubScholar 备用）
- 展示相关论文的题名、作者、期刊、年份、摘要和数据来源；可打开 DOI 或详情页
- 论文收藏、最近 50 条搜索历史；每篇论文可一键“AI 总结”（需配置 AI 服务）
- 收藏论文可记录“在读 / 已读 / 精读”状态与阅读进度；研究篮支持 BibTeX、Markdown、GB/T 7714 引用导出
- 在论文详情的摘要或已加载全文中拖选文字，可直接保存为研究证据、复制原文或写入课程笔记
- 研究任务与证据摘录：把检索、研究篮、论文摘要/全文原文和下一步动作串成一条本地研究主线
- 学习空间：自行新建/重命名项目与课程，为课程添加本地文件
- 课程五大模块：课程文件、课程论文、课程笔记本、知识导图、AI 对话
- 文件存入与分类：真实磁盘文件管理（托管副本 + 文件夹 + 拖拽归类），支持「打开文件/文件夹」
- AI 照片识别：图片（png/jpg 等 ≤15MB）自动 OCR 提取文字入侧车
- AI 一键分类：把「待分类」文件夹里的文件按内容自动归入文件夹（真实移动）
- 文档智能解析入库：上传 PDF / Word / PPT，AI 自动生成学习计划（项目 + 课程 + 重点标注笔记 + 闪卡），可选联网分析考点
- 网页抓取/剪藏：抓取公开网页正文或粘贴文本，作为 AI 对话上下文，或一键生成笔记与闪卡
- AI 对话可保存为课程笔记
- “AI 整理知识”把课程资料分类为可编辑的知识模块；“生成详细思维导图”输出可导出 PNG 的完整导图
- 番茄钟专注计时 + 洞察区学习统计（闪卡掌握率、任务完成率、专注趋势）
- 全文搜索本地课程文件、笔记、论文、研究任务和证据摘录

## Windows 运行环境

1. Windows 10 或 Windows 11，64 位。
2. Python 3.10 或更高版本，建议安装 64 位版本，并在安装时勾选
   `Add Python to PATH`。
3. Microsoft Edge WebView2 Runtime。Windows 10/11 和 Microsoft Edge 通常已经包含它。

- Python 下载：https://www.python.org/downloads/windows/
- WebView2 下载：https://developer.microsoft.com/microsoft-edge/webview2/

## 最简单的启动方式

双击 `run.bat`。

正式分发优先使用自动构建产生的 `AIStudyAssistant-Windows-x64.zip`。用户完整解压后双击 `AIStudyAssistant.exe`，不需要安装 Python，也不要运行 `run.bat`。`run.bat` 仅保留给源码开发与故障诊断。

## 构建 Windows 独立程序

一键打包：双击 `build.bat`（自动打包后端 + 主程序并合并），产物在 `dist\AIStudyAssistant\`，
双击 `AIStudyAssistant.exe` 即可运行（无需 Python 环境）。依赖 `requirements-build.txt`（PyInstaller）。

仓库同时包含 `.github/workflows/build-windows.yml`。把完整项目推送到 GitHub 后，在 Actions 中
运行 `Build Windows exe`，成功后下载 `AIStudyAssistant-windows` 构建产物。

启动时会同时保留一个黑色启动窗口，用来显示环境准备或错误原因。软件运行期间不要关闭这个窗口；关闭软件后它会自动结束。如果启动失败，请把黑色窗口中的完整文字拍照发给开发者。

第一次运行会在当前目录创建 `.venv` 并从 PyPI 安装 `pywebview`，因此需要联网，
可能等待一到数分钟。以后再次双击会直接启动软件。

应用窗口打开后会依次完成界面载入、本地服务连接、历史与收藏读取。初始化进度达到
100% 后启动界面会自动消失；如果本地数据读取失败，可以直接点击“重新初始化”。

## 手动启动

在项目目录打开 PowerShell：

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py
```

## 搜索历史位置

历史记录只保存在本机：

```text
%LOCALAPPDATA%\PubScholarDesktop\history.json
```

只有成功返回论文的关键词才会进入历史记录；重复关键词会移动到最前面。

收藏论文保存在同一目录的 `favorites.json`，仅保存在本机。学习空间的项目、课程和文件路径保存在同一目录的 `workspace.json`。

macOS 使用 `~/Library/Application Support/AIStudyAssistant/` 保存对应的本地数据。课程笔记与论文课程归属也保存在 `workspace.json`；升级 V0.6A 不会清空旧项目、课程、文件或论文。

## 常见问题

### 提示缺少 WebView2

从上面的 WebView2 下载地址安装 Evergreen Standalone Installer，完成后重新运行
`run.bat`。

### 双击 run.bat 没有出现软件窗口

新版启动脚本不会隐藏错误。请查看同时出现的黑色启动窗口：

- 停在 `creating a Python environment`：通常是 Python 未正确安装或未加入 PATH。
- 停在 `Installing required packages`：通常是网络无法访问 PyPI。
- 显示 `No module named pip`：v0.2.2 起会先调用 Python 自带的 `ensurepip` 自动修复；如果仍失败，需要在 Windows“已安装的应用”中修复或重新安装完整版 Python。
- 显示 `startup failed`：请把窗口中的完整文字拍照发给开发者，并检查 WebView2。

### 搜索超时或无法连接

软件先尝试 Crossref（连接预算8秒），再尝试 PubScholar（备用预算15秒）。若两个来源都
不可用，请分别用系统浏览器访问 https://api.crossref.org/ 与
https://pubscholar.cn/explore，检查代理、防火墙、DNS 或网络连接。

### 突然无法读取结果

默认 Crossref 检索不依赖网页结构；只有备用 PubScholar 检索使用公开网页。如果网站
以后调整页面结构，可能需要更新 `pubscholar_adapter.py` 中的选择器和页面脚本。

## 隐私说明

- 软件不会上传搜索历史。
- AI 功能默认不启用；只有用户在“AI 设置”中自行配置并启用兼容服务后，才会调用该服务。
- 在课程“AI 对话”中发送问题时，软件会把当前课程中可提取的课程文件正文、关联论文信息与摘要、课程笔记正文作为上下文发送到用户配置的 AI 服务；每次最多发送约 36000 个字符。
- 课程资料不会发送到未启用的服务；发送的文件信息仅含文件名和可提取正文，不包含本机完整文件路径。扫描图片或无法提取文字的文件会自动跳过。
- 软件不要求登录、不下载论文全文、不读取浏览器中的账号数据。

## TXT 笔记导入

进入课程的“课程笔记本”，点击“导入 TXT”可选择一个 `.txt` 文件。软件会使用文本开头前五个非空白字符作为笔记标题，并把 TXT 全部正文保存在该笔记中；电脑中的原始 TXT 文件不会被删除或修改。

## 运行测试

测试使用 Python 自带的 `unittest`：

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
# 后端接口测试（在 backend 目录下执行）
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```
