# Literature Manager

> 学术文献库管理助手。支持存储、分类、标注、检索、去重、导出文献。使用 persistent storage 跨对话维护文献库，同时支持导出为 JSON/BibTeX/RIS/Markdown 格式（可导入 Zotero/Mendeley/EndNote）。当用户提到"文献管理"、"文献库"、"加入文献库"、"保存这篇文献"、"我的文献"、"阅读笔记"、"批注"、"导出文献"、"导出 bib"、"导出参考文献"、"引用列表"、"reference list"、"bibliography"、"citation manager"、"Zotero"、"管理论文"、"论文笔记"、"文献去重"、"文献分类"、"我收藏的论文"、"之前找的文献"、"查看文献库"、"library"等关键词时触发。也适用于用户在文献检索后说"把这些存起来"、"帮我管理这些文献"等场景。与 literature-search-omfs 配合使用：检索结果可一键存入管理库。

- Skill: `skydooooog0221/literature-manager` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add skydooooog0221/literature-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/skydooooog0221/literature-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Skydooooog0221 (https://skillmd.com/u/skydooooog0221)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/skydooooog0221/literature-manager

---


# 学术文献库管理助手

使用 persistent storage 维护跨对话文献库，支持导出备份。

> **参考文件**（操作前按需读取）：
> - `references/schema.md` — 完整数据 schema（字段规范、key 规划、倒排索引结构）
> - `scripts/convert_to_bib.py` — JSON → BibTeX 转换脚本
> - `scripts/convert_to_ris.py` — JSON → RIS 转换脚本

---

## 架构：双轨制

- **persistent storage**（工作台）：跨对话持续编辑，方便快捷
- **导出文件**（安全备份）：每次重要更新后主动提醒导出，本地 JSON 可随时重新导入

原则：persistent storage 提供便利性，导出文件提供安全性。即使账号或存储出问题，用户手上有最新的导出文件。

---

## 数据结构概览

详细 schema 见 `references/schema.md`，这里只列关键结构：

### 存储 key 布局

| key | 内容 |
|-----|------|
| `library:index` | 主索引（轻量摘要，一次加载即可浏览全库） |
| `entry:{id}` | 单条文献完整数据 |
| `library:tag_index` | 标签 → 文献 ID 列表（倒排索引） |
| `library:author_index` | 作者 → 文献 ID 列表 |
| `library:domain_index` | 领域/子领域 → 文献 ID 列表 |
| `library:year_index` | 年份 → 文献 ID 列表 |
| `library:export_log` | 导出历史记录 |

### 核心原则

- **索引与数据分离**：浏览用索引，编辑用完整 entry，减少读写量
- **倒排索引同步维护**：增/改/删文献时同步更新四个倒排索引
- **索引不一致时以 entry 为准**：可随时从 entry 数据重建索引

---

## 操作指令

### 1. 初始化文献库

首次使用时（`library:index` 不存在），创建空索引和空倒排索引。

### 2. 添加文献

**从检索 skill 导入**：用户在使用 literature-search-omfs 后说"存入文献库"或"保存这些"时，将检索结果中的文献转为 entry 格式存入。需要从检索结果中提取：标题、作者、年份、来源、DOI、领域、标签、信息可及度、置信度、一句话概括。

**手动添加**：用户提供文献信息，交互式补全缺失字段。至少需要标题和年份。

**添加流程**：
1. 生成 `id`（格式 `e_{YYYYMMDD}_{seq}`，seq 从 `library:index.next_id_seq` 取）
2. 存储 `entry:{id}`
3. 更新 `library:index`（添加轻量摘要，递增 next_id_seq）
4. 更新四个倒排索引
5. 确认添加成功，显示入库信息

**批量添加**：检索结果通常有多篇，支持一次性添加，逐条确认或用户说"全部添加"。

### 3. 浏览文献库

- **全库概览**：读取 `library:index`，显示总数、各领域/集合分布
- **按标签查找**：读取 `library:tag_index`，列出匹配文献
- **按作者查找**：读取 `library:author_index`
- **按领域查找**：读取 `library:domain_index`
- **按年份查找**：读取 `library:year_index`
- **按集合查找**：从 `library:index.entries` 中筛选 collections 字段
- **查看单条详情**：读取 `entry:{id}`，显示完整信息

浏览时使用简洁列表格式：
```
[1] Zhang Y et al. (2024) Virtual Surgical Planning... 🟢📑 IJOMS Q1 IF=2.7
[2] Vaswani A et al. (2017) Attention Is All You Need 🟢📄 NeurIPS T1
```

### 4. 添加/编辑笔记

读取 `entry:{id}`，在 `notes` 数组中追加或修改笔记条目。每条笔记带 `note_id`、`content`、`created_at`、`updated_at`。更新后写回 entry 并更新 `library:index` 中的 `updated_at`。

### 5. 管理文献关系

在 `entry:{id}` 的 `relations` 字段中添加/删除关系。支持的关系类型：cites、cited_by、related、supersedes、superseded_by、contradicts、extends。

添加关系时，如果 target 也在库中，双向更新（如 A cites B → B 的 relations 加 cited_by A）。

### 6. 管理集合（Collections）

集合是跨领域的文献分组（如"毕业论文引用"、"2024年3月TMJ检索"）。

- **创建集合**：在 `library:index.collections` 中添加，给相关 entry 的 `collections` 字段加上集合名
- **向集合添加/移除文献**：更新 entry 的 `collections` 字段和索引中对应条目
- **查看集合**：筛选 `library:index.entries` 中属于该集合的文献

### 7. 去重检查

检测策略（按优先级）：
1. **DOI 完全匹配**：同一 DOI → 确定重复
2. **标题高度相似**：忽略大小写和标点后匹配 → 疑似重复，提醒用户确认
3. **同作者+同年份+相似标题**：疑似重复

添加新文献时自动运行去重检查。用户也可主动触发全库去重扫描。

发现重复时：展示两条文献的差异，让用户选择保留哪条或合并信息。

### 8. 导出

**导出格式**：

| 格式 | 用途 | 方法 |
|------|------|------|
| JSON（canonical） | 备份/重新导入 | 直接从 storage 序列化 |
| BibTeX (.bib) | Zotero/JabRef | JSON → `scripts/convert_to_bib.py` |
| RIS (.ris) | Zotero/Mendeley/EndNote | JSON → `scripts/convert_to_ris.py` |
| Markdown (.md) | 人类可读参考列表 | 直接生成 |

**导出流程**：
1. 确定范围：全量 / 增量（自上次导出以来）/ 指定集合 / 指定筛选条件
2. 从 storage 加载对应 entries
3. 生成 JSON 文件（含 export_meta manifest）
4. 如用户需要 BibTeX/RIS，运行转换脚本
5. 更新 `library:export_log` 和各 entry 的 `export_history`
6. 输出文件供用户下载

**增量导出**：比较每条 entry 的 `updated_at` 与上次导出时间 `library:index.last_export`，只导出更新的条目。manifest 中记录 new/updated/deleted 数量。

**导出提醒**：当累计新增或修改 ≥5 条文献且距上次导出 >1 天时，在对话结束前主动提醒"建议导出备份"。

### 9. 导入

从用户上传的 canonical JSON 文件重建文献库：
1. 解析 JSON，验证 schema
2. 逐条写入 `entry:{id}`
3. 重建 `library:index` 和所有倒排索引
4. 报告导入结果

支持合并导入（与现有库合并，按 DOI/id 去重）和覆盖导入（清空后重建）。

### 10. 重建索引

如果索引损坏或不一致：
1. 用 `list` 方法枚举所有 `entry:*` key
2. 逐条读取 entry
3. 重建 `library:index` 和四个倒排索引
4. 报告重建结果

---

## 与文献检索 skill 的集成

当用户在使用 literature-search-omfs 检索后要求存入文献库时：

1. 从检索结果中提取文献元数据
2. 映射到 entry schema（accessibility/confidence 直接继承检索结果的标签）
3. 运行去重检查
4. 批量添加
5. 询问是否创建新集合（如"TMJ关节镜2024检索"）

当用户在管理文献时需要补充检索，可以直接调用检索 skill。

---

## 交互风格

- 操作成功后简洁确认，不要冗长复述
- 浏览文献时用紧凑列表，不要逐条展开
- 用户说"查看"或"看看我的库"时加载索引，给出概览统计 + 最近添加的几条
- 编辑操作前确认，删除操作必须确认
- 导出后简洁告知文件位置和内容摘要

---

## 错误处理

- persistent storage 操作失败 → 告知用户，建议稍后重试或检查网络
- 索引不存在 → 询问是否初始化新库 or 从文件导入
- entry 不存在但索引中有 → 标记为"数据缺失"，建议重建索引或从备份恢复
- JSON 导入格式错误 → 指出具体字段问题，尝试修复或要求用户检查