# Zotero 文献知识库

把 Zotero 里的文献变成本地知识库：AI 能搜到带页码的原文片段、能按页精读、
能记住你试过的哪些方法有效。检索、切片、向量、模型全部在本机完成，
只有「找新文献」那一步需要联网。

```
① 找文献  →  ② 抓进 Zotero  →  ③ 拆成知识库  →  ④ 喂给 AI  →  ⑤ 经验回流
```

第 ⑤ 步的经验会回流到第 ④ 步：下次检索时「验证过有效」的文献自动排在前面。

## 能做什么

1. **搜到相关文献**：关键词与语义两路混合，中英文都行，返回带页码的原文片段。
2. **按页精读**：需要哪几页取哪几页，不用把整篇塞进上下文；图注与表格单独可查。
3. **按层面看一篇**：Zotero 里右键「打开知识库」，或在管理面板点「打开知识库」，
   选一个层面双击即打开对应文件 ——

   | 层面 | 内容 |
   |---|---|
   | 摘要与要点 | 元数据、结构化字段、摘要、AI 要点、笔记要点，几百字 |
   | 分节纲要 | 按章节给「这一节在做什么 + 关键点/参数/结论」，每节带页码范围；**需要模型**（本地 Ollama 或外部 API）才能生成 |
   | 完整档案 | 元数据 + 摘要 + 每页首段 + 笔记与高亮标注 |
   | 按页正文 | 带 `## p.N` 页码锚点的正文（公式为 LaTeX） |
   | 图注与表格 | 散在各页末尾的图注与表格汇总成一份 |
   | 权重与经验 | 检索权重、重点标记、人工加减分，以及这篇的全部使用经验 |

4. **在 Zotero 右侧栏读**：条目右侧栏多一个「知识库预览」分区，就地切层面、
   调字号（只影响这个分区），对着 PDF 原文看，公式按数学排版显示。
5. **找新文献并抓进库**：搜 → 列候选表（标题可点开看原文、带摘要与被引）→ 勾选 →
   由 Zotero 自己抓取入馆，校园网与机构订阅的权限自然生效，不用下载再手工拖。
6. **记住用过的经验**：上次试过哪几篇、哪个有效、哪个因为初值敏感失败。
7. **越用越准**：验证有效或标为重点的文献，下次检索自动排前。
8. **（可选）MinerU 解析**：装上后正文更干净、公式变成可检索的 LaTeX、表格与扫描件更稳；
   在面板「PDF 解析」页选档位点一下，全库正文即换成 MinerU 的结果（按 PDF 指纹跳过没变的，
   失败按篇回落）。装在项目内的 `.mineru\`，删目录即卸载；不装也能用。
9. **删了也不怕、还原能秒回**：在 Zotero 里把条目移进回收站时，知识库把这一篇的切片、图注、
   向量与解析产物**归档**起来（`kb_search` 立刻搜不到它，面板「知识库结构」页能看到归档占多少）；
   从回收站**还原**时把归档直接装回知识库（秒级，不重跑模型）；在回收站里**彻底删除**才真正清掉归档。
10. **条目右键生成分节纲要**：不用先开面板 —— 右键一篇（可多选）即可生成"这一节在做什么"的
    中间层；生成过程中菜单里会多出「停止生成纲要」，停下那一篇不会留下半份。

## 界面

**管理面板**（双击 `scripts\0-panel.vbs`）集中管知识库：每个文件都写清「是什么、占多大、
能不能删」。

- 顶部状态栏：知识库位置、条目/切片/向量/经验条数、正文总字数、用的嵌入模型
- 页签（10 个）：知识库结构 · 经验库 · 分类建议 · 分节纲要 · 运行环境 · PDF 解析 · 损坏查询 · 元数据 · 高级 · 提示词
- 底部：实时运行日志（长任务在后台跑，进度打在这里）
- 核心按钮：手动更新 · 全部重建 · 环境自检 · 备份 · 打开知识库 · **对账**（知识库 vs Zotero 的差异报告）· 文献管理器中查看

**Zotero 插件设置**（Zotero → 编辑 → 设置 → 文献知识库）分两组：知识库位置与自动处理
（位置、可选的跨机同步方式、分类列表、新文献自动处理、从 DSH 导入、测试连接）；
本地模型与运行环境（本地服务地址、访问 token、用哪个本地模型、项目目录 / Python 解释器 /
Ollama 程序，后三项留空则自动探测）。运行环境那三项在面板「运行环境」页也能改，
写的是同一份配置。

## 为什么比「把 PDF 丢给 AI」好用

| | 直接把 PDF 丢进对话 | 只用 Zotero 自带搜索 | 本方案 |
|---|---|---|---|
| 上下文成本 | 每次重传，长文直接爆 | — | 建库一次，之后按需取页 |
| 能搜到的范围 | 只限于你此刻记得的那篇 | 只匹配标题/作者/年份 | 关键词 + 语义两路混合 |
| 精度 | 模型现场读，读到哪算哪 | — | 返回带页码的原文片段，可回溯核对 |
| 跨对话记忆 | 换个对话就忘 | — | 经验层持续累积，影响下次排序 |
| 数据去向 | PDF 上传到云端 | 本地 | 全本地 |

几个具体场景：

- 「我库里有没有讲过 XX 的？」→ 混合检索直接给带页码的片段，不用回想是哪篇
- 「这几篇的方法有什么区别？」→ 按页读正文 + 查图表注，而不是靠摘要猜
- 「这个方法我试过了吗？」→ 经验层回答：试过、什么条件、有效还是无效、为什么
- 「这个方向还有哪些新文献？」→ 对话里搜 → 列候选 → 勾选 → 进库 → 立刻可搜

## 快速开始

```powershell
# 1. 拿到项目（不想装 git 就去 Releases 下 Source code zip 解压）
git clone https://github.com/Authentic3096/zotero-kb.git D:\zotero-kb

# 2. 一键装 Python 环境（本机没装 Python 也行，它会自己下载一个）
D:\zotero-kb\scripts\install-env.cmd

# 3. 建知识库
D:\zotero-kb\scripts\1-convert.cmd

# 4. 装 Zotero 插件：到 Releases 下载 zotero-kb-<版本>.xpi →
#    Zotero → 工具 → 插件 → 右上角齿轮 → Install Plugin From File… → 完全退出 Zotero 再打开
```

完整步骤（含怎么验证装好了、日常使用、常见问题、卸载）见 [INSTALL.md](INSTALL.md)。

**环境**：Windows；Zotero 7 ~ 10；Python 3.12+（第 2 步会自动装）。
本地模型可选（Ollama + `qwen3:4b-instruct`），用于分类建议、元数据补全与**生成分节纲要**；不装不影响检索。
不接 AI 也能用：管理面板与 Zotero 插件可独立工作；接 AI 的部分走标准 MCP
（13 个工具 + 4 个资源），任何支持 MCP 的客户端都能接。

## 文档

| 文档 | 讲什么 |
|---|---|
| [INSTALL.md](INSTALL.md) | 从零装到能用：安装四步、验证、日常使用、常见问题、卸载 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 架构与关键实现：三块怎么分工、四条链路、正文从哪来、检索怎么算分、插件机制 |
| [docs/DESIGN.md](docs/DESIGN.md) | 设计与用法详解：各功能怎么用、为什么这么做、边界与已知限制 |
| [docs/知识库层级设计.md](docs/知识库层级设计.md) | 知识库的层级结构：索引 / 原始 / 正文 / 档案 / 视图 / **归档**各是什么、谁生成、能不能删 |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 给要改这个项目的人：目录结构、构建与测试、发版流程、排错入口 |

## 许可证

[MIT](LICENSE) © 2026 Authentic3096

打包分发的插件（`zotero-kb-*.xpi`）与本仓库的 Python 代码、DSH skill 适用同一许可证。
Zotero 是独立的第三方软件（AGPL-3.0），本项目只通过其公开扩展接口调用，
不包含也不修改 Zotero 源码。