# Zotero 文献知识库

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

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

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

**当前版本 2.0.8。** 普通用户下载 **便携运行包**即可（运行代码、脚本、Skill 与
插件 xpi 都在包里），不用再下整个源码；2.0 把管理面板搬进了 Zotero、并去掉了常驻的
本地 HTTP 服务（**不再监听任何端口**）。升级前请读 [发布说明](docs/RELEASE-2.0.8.md)。

## 能做什么

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

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

4. **在 Zotero 右侧栏读**：条目右侧栏多一个「知识库预览」分区，就地切层面，
   对着 PDF 原文看（字号在面板「偏好设置 → 侧栏」里按 px 调，只影响这个分区）。
   公式按数学排版显示（KaTeX），图片、表格都能正常渲染。

   **与 PDF 并排**：打开一篇 PDF 后，**从右侧那一列（rail 上的图标）打开知识库** ——
   点一下，**右边就是这一页的知识库正文**（左边照旧是 Zotero 自己的 PDF，同一个窗口；
   打开时停在正在读的那一页，之后由你手动翻找）。
   （2026-10-16 起入口只有这一处：原来阅读器工具栏上还有一个「对照」按钮，
   与 rail 是同一个动作的重复入口，已按用户要求删除。）
   发现解析错了就地改：
   「改这一页」会把这一页按段/公式/表格/图片切开，**左边改、右边实时预览**，
   保存后立刻重切重向量。「恢复原版」逐字节还原。
   **公式错了更省事**：在 PDF 上**右键那一块公式**（不用先画标注）→ 弹出编辑区
   （左边是这块公式的原文图，右边是可改的 LaTeX 并实时预览）→ 点「应用」只改这一条。
   想用 MathType 排版也可以：编辑区里「用 MathType 编辑」会把当前 LaTeX 放进剪贴板并
   打开 MathType，排好后复制回来即可（**MathType 是外部可选工具，不装也能手改**）。
5. **找新文献并抓进库**：搜 → 列候选表（标题可点开看原文、带摘要与被引）→ 勾选 →
   由 Zotero 自己抓取入馆，校园网与机构订阅的权限自然生效，不用下载再手工拖。
6. **记住用过的经验**：上次试过哪几篇、哪个有效、哪个因为初值敏感失败。
7. **越用越准**：验证有效或标为重点的文献，下次检索自动排前。
8. **（可选）MinerU 解析**：装上后正文更干净、公式变成可检索的 LaTeX、表格与扫描件更稳；
   面板「偏好设置 → 可选组件安装引导」有「开始安装」（装到项目内 `.mineru\`，删目录即卸载）；
   再在「PDF 解析」页点「只补缺失 / 全库重解析」把正文换成 MinerU 的结果
   （按 PDF 指纹跳过没变的，失败按篇回落）。不装也能用。
9. **删了也不怕、还原能秒回**：在 Zotero 里把条目移进回收站时，知识库把这一篇的切片、图注、
   向量与解析产物**归档**起来（`kb_search` 立刻搜不到它，面板「知识库结构」页能看到归档占多少）；
   从回收站**还原**时把归档直接装回知识库（秒级，不重跑模型）；在回收站里**彻底删除**才真正清掉归档。
10. **条目右键生成分节纲要**：不用先开面板 —— 右键一篇（可多选）即可生成"这一节在做什么"的
    中间层；生成过程中菜单里会多出「停止生成纲要」，停下那一篇不会留下半份。

## 界面

**管理面板**集中管知识库：每个文件都写清「是什么、占多大、能不能删」。

- 入口：Zotero **工具 →「知识库管理…」**（主工具栏那个按钮、条目右键
  「打开知识库 → 打开知识库管理面板」也指向同一个面板）。
- 页签（按顺序，共 11 个）：知识库结构 · PDF 解析 · 分节纲要 · 经验库 · 元数据 ·
  分类建议 · 损坏查询 · 运行环境 · 偏好设置 · 高级 · 提示词
- 「知识库结构」页第一屏是状态数字：文献 / 切片 / 向量 / 经验 / 正文字数 / 标重点，
  右边还有嵌入模型名与建库时间
- 底部：实时运行日志（长任务在后台跑，进度打在这里）
- 各页自身的动作按钮写在页内；日常维护都收在「高级」页：
  **索引重建**（增量更新 / 全部重建）、**维护动作**（统计 / 环境自检 / 备份索引 /
  对账巡检 / 补齐分级文件 / 重载技能到 DSH），以及权重榜翻页

面板是 **Zotero 自己的一个窗口**（不是另开 Python 进程），页面从
`resource://zotero-kb/content/admin.html` 加载。它与知识库之间**没有监听端口、没有 token、
没有常驻服务**：插件按需拉起一个 Python 引擎子进程，用父子进程的 stdin/stdout 说话，
**随 Zotero 退出**。

**设置只有一个地方**：管理面板（Zotero → 工具 →「知识库管理…」）。
「运行环境」页管八个位置与模型配置（值从哪来、就地改、点「浏览…」、恢复自动）；
「偏好设置」页管插件行为（新文献自动处理、从 DSH 导入、分类列表、侧栏显示、
可选的跨机同步、可选组件安装引导、排查用开关）。
Zotero 自带的「设置 → 文献知识库」窗格在 2.0.4 已下线，不要再去那里找。

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

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

几个具体场景：

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

## 快速开始

普通用户**不用下整个源码**：到 [Releases](https://github.com/Authentic3096/zotero-kb/releases)
下载最新版的 `zotero-kb-<版本>-win64.zip`（运行代码、脚本、两份 Skill 和插件 xpi 都在包里），
解压到**路径里没有中文和空格**的目录，例如 `C:\zotero-kb`。

**顺序：先装插件，再装环境，最后在面板里建库。**

1. **先装 Zotero 插件**：Zotero → 工具 → 插件 → 右上角齿轮 →
   **Install Plugin From File…** → 选 `zotero-plugin\zotero-kb-<版本>.xpi` →
   **完全退出 Zotero 再打开**。
2. **装 Python 环境**（只装前置依赖，不建库）：
   ```powershell
   cd C:\zotero-kb
   .\scripts\install-env.cmd
   ```
3. **首次建库**：Zotero → 工具 →「知识库管理…」→ **高级** →
   **「索引重建」→「全部重建」**，等运行日志跑完。
4. **可选组件**：管理面板 →「偏好设置」→「可选组件安装引导」，
   按需装 Ollama / MinerU；**不装也能用基础功能**。
   首次建库用上面的「全部重建」；「PDF 解析 → 全库重解析」只是装 MinerU 后
   切换正文来源，**不是首次建库的必需步骤**。
5. **接 AI（可选）**：MCP 按客户端配置接入；Skill 复制到 agent 的 skill 目录
   （DSH 示例 `~/.dsh/skills`）。

一页版见 [QUICKSTART.md](QUICKSTART.md)；完整步骤（验证、日常使用、常见问题、卸载）
见 [INSTALL.md](INSTALL.md)。源码包只给开发者（要改代码、自己构建 xpi 时用）。

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

## 文档

> 便携包里只带本文件、`INSTALL.md`、`QUICKSTART.md`、`LICENSE` 与
> `docs/RELEASE-2.0.8.md`；`ARCHITECTURE.md` 的链接指向源码仓库（GitHub），
> 便携包里没有这份设计文档。

| 文档 | 讲什么 |
|---|---|
| [QUICKSTART.md](QUICKSTART.md) | 一页版：普通用户 5 步安装、3 步升级、MCP 与 Skill 怎么接 |
| [INSTALL.md](INSTALL.md) | 从零装到能用：安装五步、验证、日常使用、目录层级、常见问题、卸载 |
| [ARCHITECTURE.md](https://github.com/Authentic3096/zotero-kb/blob/main/ARCHITECTURE.md) | 架构与设计：三块怎么分工、五条链路、正文从哪来、检索怎么算分、各功能的实现与用法、边界、开发与维护 |
| [docs/RELEASE-2.0.8.md](docs/RELEASE-2.0.8.md) | 2.0.8 的对外说明：这一版改了什么、怎么装/升 |

## 许可证

[MIT](LICENSE) © 2026 Authentic3096

打包分发的插件（`zotero-kb-*.xpi`）与本仓库的 Python 代码、DSH skill 适用同一许可证。
插件内置了两个第三方库用于渲染侧栏正文与公式：**markdown-it** 14.1.0 与 **KaTeX** 0.16.11
（均为 MIT，原样引入、未修改，各自的 LICENSE 与字体随包分发在 `zotero-plugin/content/vendor/`）。
Zotero 是独立的第三方软件（AGPL-3.0），本项目只通过其公开扩展接口调用，
不包含也不修改 Zotero 源码。