paper-piggy

<div align="center"> # 🐷 论文小猪 · PaperPiggy **把你的文献库，变成 AI 能真正读懂、并且不会瞎编的研究助手** 面向法学 / 社科研究者的桌面应用 [](LICENSE) []() []() [](https://github.com/DrinkTea905/paper-piggy/releases) [](https://github.com/DrinkTea905/paper-piggy/stargazers) </div> --- ## 这是什么 把你的 Zotero 文库（或任意一个装满 PDF 的文件夹）建成索引，然后**让 Claude Code 这类 AI agent 直接接管它**——不是把 PDF 拖进对话框那种"接管"，而是 agent 能自己检索、自己翻到第几页、自己核对引文真伪、自己把结论沉淀成可累积的知识页。 --- ## 🤖 Agent 能做什么（这是本项目的重点） 通过 MCP 接入后，AI 拿到 **32 个工具**。它们不是"搜索"一个动作的花式包装，而是一整套研究工作流。 ### 它能读，而且知道自己读到了第几页 检索命中不只给你一段 220 字的片段——agent 可以**读原文全文**（逐页），并且每一页都带着**期刊印刷页码**（就是你翻纸刊看到的那个页码，不是"PDF 第 37 页"）。 这意味着 AI 写出来的脚注，你可以直接抄进论文。 ### 它不能瞎编，因为有工具专门抓它瞎编 这是和"把 PDF 喂给聊天框"最本质的区别： | 工具 | 干什么 | |---|---| | **引文核对** | 给一句引文，回答"这句话到底在不在原文里、在第几页"。写脚注前先过一遍，杜绝伪造引用。 | | **论断核验** | 给一个实质论断，返回**三态**：有库内文献支撑 / 库内证据与之矛盾 / 库里根本没有相关证据。第三种情况下，AI 必须承认"这我不知道"，而不是编一个看起来很像的出处。 | | **覆盖度诚实标注** | 生成综述时逐子题标 ◎充分 ○部分 △薄弱 ▲基本缺失，并明确写出"资料缺口在哪"——不把"你库里没有"粉饰成"学界空白"。 | ### 它有自己的工作区，而且是人类可读的 接入后，PaperPiggy 会在**安装目录里**（就是索引和模型待的地方，比如 `D:\PaperPiggy\`）多出两个文件夹，和你的 Zotero 文库互不干扰： ``` 0_Agent资料库/ ← AI 干活要用的东西（不是你的文献） ├─ 记忆/ │ ├─ 项目记忆.md 当前定了什么：你是谁、你的偏好、已拍板的决策、正在做什么 │ └─ 变更日志.md 历史流水账（只增不改） ├─ 技能/ ★ 工作流，一个流程一个 .md —— 你可以直接改 │ ├─ 写论文与综述.md │ ├─ 维护综述库.md │ └─ 跨学科发散与补文献.md ├─ 参考格式/ 放一份你的范本 .docx，AI 就照着它排版 ├─ 交付模板/ 改这里 = 改 AI 给你产出的样子 └─ 定时任务/ 定时干什么、多久一次、成果放哪 0_Agent交付物/ ← 成品放这儿（论文初稿、资料汇编、周报） ``` **关键在于：这些全是 markdown，留在你本机，你随时能进去看、能改。** - **换 AI 助手不用重来。** 从 Claude Code 换到别的 agent？新助手读一遍 `0_Agent资料库/`，就接上了你之前所有的决策、偏好和进度。记忆不锁在某家厂商的服务器里。 - **工作流是你的，不是我的。** `技能/写论文与综述.md` 只是出厂默认。嫌它引注风格不对？直接和 AI 商量着改这个文件。你改过的文件，应用升级时**不会覆盖你**（它会另存一份新版让你自己合并）。 ### 三条开箱即用的工作流 | 工作流 | 干什么 | |---|---| | **写论文与综述** | 选题拆解 → 三级大纲（每节挂 ★核心/☆辅助 文献）→ 逐节召回证据 → 写成带页级引注的综述 → 标注资料缺口和补检索建议 | | **维护综述库** | 把散落的结论整理成互相链接的知识页；体检孤儿页、断链、过期页 | | **跨学科发散与补文献** | 写作**之前**用的：打开理论视野，从别的学科找可迁移的框架，并建议该补哪些外文文献 | ### 它会主动告诉你"你的旧结论过时了" 新文献入库后，agent 可以反查：**这篇新文献影响了哪些既有的知识页、每页该怎么改**。 综述库里的页面会被自动标记为"可能过期"（stale），并在检索中显著降权——这样你不会拿着一个三个月前、在新判例出来之前写的结论去投稿。 ### 还有 - **收单篇**：对话里丢一个 PDF 路径，agent 直接把它收进库 - **找相似**：给一篇，返回**向量近邻**（不是关键词匹配）——精读完一篇后换角度扩展检索面 - **看新东西**：久没碰的库，先问"上次之后进了什么" - **AI 使用声明**：按你选的页面，生成一份《生成式 AI 使用声明》——很多期刊现在要这个 > 📎 具体工具清单见 [MCP 接入说明](src/MCP接入说明.md)（由代码自动生成，不会与实现漂移）。 > 接入方式：打开应用的 **🤖 Agent** 页，复制那行命令即可，**无需手动安装任何技能包**。 --- ## 🔍 检索引擎 Agent 再聪明，检索不准也是白搭。所以底下这层做得很实： - **混合检索**：向量（LanceDB）+ BM25 词法 → RRF 融合 → 重排序（bge-reranker-v2-m3） - **期刊权重加成**：顶刊、C 刊、法源、报告分层加权（内置期刊分级引擎，含 SJR / 北大核心 / CSSCI 目录） - **中文法学优化**：法律术语分词词典、法条切分、法源时效识别 - **三档渐进索引**：词法（秒级可用）→ 语义（分钟级）→ 深索（读 PDF 全文，可后台跑） ## 🧠 综合层 Wiki RAG 之上还有一层：把问答结果**沉淀**成带引用、可累积、互相链接的知识页，而不是让答案烂在聊天记录里。 页面会随新文献入库而标记过期，也会被体检出孤儿页和断链。这是这个项目和普通 RAG 工具最不一样的地方。 --- ## 安装 **[⬇️ 下载最新版](https://github.com/DrinkTea905/paper-piggy/releases/latest)** → `PaperPiggy-x.y.z-win64.exe`（约 177 MB） Windows 10/11 64 位。无需预装 Python 或 VC++ 运行库。缺 WebView2 时安装器会自动装。 **不需要管理员权限**，安装时不弹 UAC。 检索引擎二选一：**本地 ONNX**（模型跑在你机器上，首启按需下载约 900 MB）或 **API 模式**（省磁盘省内存，无需下载）。首启向导里选。 ### 你的数据放在哪 **和程序在同一个文件夹里。** 安装时可以选位置——比如装到 `D:\PaperPiggy`，那么索引、模型、综述 wiki、 `0_Agent交付物`、`0_Agent资料库` 全都在这个文件夹内，C 盘一点不占，整个文件夹拷走就能换台电脑接着用。 （默认位置是 `C:\Users\<你>\AppData\Local\Programs\PaperPiggy`，想放别处就在安装向导里改。） - **升级**：应用内「⚙ 设置 → ⬆️ 应用更新」一键升级（只换程序本体、数据不动、自动重启）；也可以直接运行新版安装器，效果一样。 - **卸载**：你的数据会**留在**那个文件夹里，不会被删。重装即可接着用；确认不要了再自己删。 - ⚠️ **别手动删整个文件夹**——数据在里面。要清空请先备份。 - ⛔ **别装在 OneDrive / 坚果云 / Dropbox 等云盘同步目录里。** 索引是一个持续读写的向量数据库（几个 G，会被反复改写和合并），云盘会反复上传它、 在同步时锁文件、冲突时造出重复副本——轻则写入失败，重则索引损坏。 装到普通本地目录（例如 `D:\PaperPiggy`）。 - ⚠️ 本项目以明文 `.py` 分发，你可以直接改包里的代码。应用内升级会把你改过的 `app\` 文件 存到「你改过的旧代码-<版本>」文件夹；但**用安装器覆盖安装会直接盖掉**，改过就先备份。 ### 国内下载慢？配个镜像 应用从 GitHub 下载（首启的模型、应用内更新的增量包），国内连 GitHub 偶尔超时。 **应用内更新**只下载一个约 1MB 的增量包，给它配个镜像兜底很轻： 1. 每次发版时，把 Release 里的 `paper-piggy-app-<版本>.zip` 和同名 `.sha256`（就这两个小文件） 传到一个国内能快速访问的地方——**Gitee Release** 最省事（免费、免备案），或对象存储（Cloudflare R2 / 阿里云 OSS 等）。 2. 在应用「⚙ 设置 → ⬆️ 应用更新 → 国内镜像」里，填这两个文件所在的**目录前缀**（以 `/` 结尾），例如 `https://gitee.com/你的名/paper-piggy/releases/download/v<版本>/`。 3. 之后应用内更新会先试 GitHub、连不上就走镜像。检查更新仍走 GitHub API（小、通常能连）。 （首启的模型下载走另一套镜像位 `models_manifest.json` 的 `mirror_base`，那是 900MB 的大文件、 需要托管在带宽足的对象存储上，属于另一件事。） --- ## 从源码运行 ```powershell git clone https://github.com/DrinkTea905/paper-piggy.git cd paper-piggy python -m venv .venv .\.venv\Scripts\pip install -r src\requirements.lock # 用 lock，这是唯一被实机验证过的组合 $env:LOCALKB_MODELS = 'X:\path\to\models' # 本地模式需要；API 模式可跳过 .\.venv\Scripts\python src\launcher.py # 原生窗口 .\.venv\Scripts\python src\server.py # 或只起后端，浏览器开 http://127.0.0.1:8770 ``` **在 macOS / Linux 上跑？** 正式发布只有 Windows 安装器，但整套是纯 Python + 本地网页， **从源码直接跑得起来**（数据落点、Zotero 探测、依赖已按平台分流）——见 **[MAC-从源码运行.md](MAC-从源码运行.md)**（面向技术型个人自用，含 macOS 专属注意事项）。 **AI agent 接手这个项目做开发？** 先读 [CLAUDE.md](CLAUDE.md)，那是给你的入口。 ## 文档 | | | |---|---| | [CLAUDE.md](CLAUDE.md) | AI 开发 agent 总纲（工作规则、改代码铁律、踩过的坑） | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 架构：进程模型、三档索引、检索管线、Wiki、Agent 层 | | [docs/MAINTENANCE.md](docs/MAINTENANCE.md) | 维护：「改了 X → 必须同步 Y」映射表 | | [docs/RELEASE.md](docs/RELEASE.md) | 打包与自动更新 | | [MAC-从源码运行.md](MAC-从源码运行.md) | 在 macOS 上从源码运行（技术型个人自用） | | [src/MCP接入说明.md](src/MCP接入说明.md) | MCP 接入（32 个工具，由代码自动生成） | ## 技术栈 Python 3.12 · FastAPI · pywebview(WebView2) · LanceDB · bm25s · ONNX Runtime · BAAI/bge-m3（嵌入）· BAAI/bge-reranker-v2-m3（重排）· jieba · pypdfium2 前端是**无构建步骤**的原生 JS。后端是**明文 `.py`，不编译不混淆**——你可以直接改包里的代码。 （升级方式：应用内「⚙ 设置 → ⬆️ 应用更新」一键升级——只替换程序本体，你的数据不动，你改过的 `.py` 会保留到「你改过的旧代码-<版本>」文件夹。也可以随时去 GitHub 下新版安装器覆盖安装，效果一样，但覆盖安装会直接盖掉你改过的 `app\` 文件、**先自行备份**。） ## 许可 [Apache-2.0](LICENSE)。第三方组件声明见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。