# 文献对话 · Citation Dialogue

在 Zotero 里沿着引用关系发现论文，按累计被引寻找尚未获取的文献，把带来源的研究笔记保存到 Obsidian 或 Notion，并让 Claude / Codex 操作同一张图谱。

**Zotero 9.0.x · MIT 开源 · 本地 MCP · 无需本项目的付费订阅。** 已在 macOS Zotero 9.0.6 实测。其他操作系统尚未实机验证。

[下载安装包](https://github.com/6forwater29/citation-dialogue/releases/latest) · [连接与分享指南](docs/CONNECT.md) · [隐私说明](PRIVACY.md) · [反馈问题](https://github.com/6forwater29/citation-dialogue/issues)

![图谱示例：独立测试库，非个人文库](docs/graph-preview.png)

## 安装和打开

1. 从 Releases 下载 `citation-dialogue-0.3.1.xpi`。
2. Zotero → 工具 → 插件 → 齿轮 → 从文件安装插件，选中 XPI。已有旧版时直接更新。
3. 选中论文，右键 → **文献对话 · 所选论文节点图**；也可右键一个集合打开整个集合（含子集合）。
4. 点击节点查看详情，展开“它引用的”和“引用它的”论文。工具菜单也有打开入口。

## 主要功能

- **20 种界面语言**：右上角 🌐 可立即切换并记住选择，也可跟随系统。支持简繁中文、英语、日语、韩语、德语、法语、西班牙语、巴西葡萄牙语、意大利语、荷兰语、波兰语、俄语、阿拉伯语、印地语、孟加拉语、印尼语、土耳其语、越南语和泰语。阿拉伯语使用从右向左布局。论文内容保持原文，部分底层诊断使用英文回退；译文尚未经过全面母语审校。
- **被引数量看得见**：默认节点大小反映 OpenAlex 累计被引，经过对数缩放以保持可读；详情、悬浮提示和候选列表显示具体数量。未知数值保留为“未知”。也可切换为当前图谱的连接数。
- **寻找尚未获取的论文**：右侧“找未获取文献”支持“库外论文”“库内无本地 PDF”“两类一起”和全部；按累计被引、发表年份或当前图谱连接数排序。先查看重要候选，再决定是否去获取全文。插件不自动下载或导入论文。
- **前后向引用分色**：以当前选中论文为中心，蓝色表示它引用的文献（后向），橙色表示引用它的论文（前向），紫色表示双向关系；虚线边框表示库外论文。箭头 A → B 始终表示 A 引用 B。
- **笔记目标直接在插件里设置**：点“笔记与 AI”，选择 Obsidian 笔记库，或连接 Notion 父页面，再保存单篇论文或图谱摘要。Obsidian 更新生成区并保留人工笔记；Notion 首次创建后保留原页面，重复保存不覆盖、不重复建页。
- **Claude / Codex 共用当前图谱**：启用本机 AI 连接后，可查看图谱、读取候选、展开文献；单独允许 AI 写笔记后，可把带当前图谱来源的研究草稿保存到已配置的目标。
- **原生导出**：导出图谱数据会打开 Zotero 保存窗口，保存含节点和引用关系的 JSON。没有 PDF、密钥、笔记或图形坐标；本版暂无 JSON 导入功能。

## 连接 AI

先在 Zotero 中打开图谱，点击 **笔记与 AI → 启用本机 AI 连接**。

- **Claude Desktop**：下载配套 `.mcpb` 本地扩展，安装时选择插件显示的 `mcp-connection.json` 文件；或使用插件内“复制 Claude 配置”。
- **Codex**：使用插件内“复制 Codex 配置”，在 Codex 的 MCP 设置中添加。需要本机 Node.js 20 或更新版本。
- AI 写笔记默认关闭；可以只让 AI 读图谱。整个过程中 Zotero 需要保持运行。纯网页 Claude 的远程连接器不能直接访问本机服务。

可直接对 AI 说：

> 在当前图谱中找出我尚未入库、被引较高的 10 篇论文。区分观察到的引用关系和你的解释，并保留 DOI。选出 3 篇后续研究展开，帮我形成一份带来源的 Obsidian 研究备忘录。

详情见[连接指南](docs/CONNECT.md)。每位使用者在自己的 Zotero 中配置目标；分享安装包即可，不要分享个人连接文件、令牌或 Zotero 配置目录。

## 数据范围与解释

这是按需扩展的部分网络。候选排序只覆盖**当前已加载的节点**，不是检索整个 OpenAlex 或扫描整个 Zotero 文库的结果。一个图谱最多 200 篇种子、600 个节点；默认先为前 12 篇种子各取一小批前后向文献。可继续手动或通过 AI 展开。

累计被引来自 OpenAlex，可能滞后、缺失或合并错误。它体现累积关注，也受论文年龄和学科影响，不能直接代表论文质量。引用关系不等于支持、批评或理论传承；这些判断需要原文。库内无本地 PDF 指当前机器未找到本地 PDF，不能推断其他设备或云端没有文件。

DOI 优先匹配；标题回退要求规范化标题和年份一致，歧义匹配保持未解析。OpenAlex 响应缓存 24 小时，“刷新引文”可重新获取。插件不编辑、导入或删除 Zotero 书目与附件。

## 开发与验证

Node.js 20+ 和系统 `zip` 即可，无需安装项目依赖：

```sh
npm run check
npm test
npm run build
```

构建生成 Zotero XPI、Claude MCPB、带实际包哈希的 Registry `server.json` 和校验文件。GitHub 的版本标签触发免费公开仓库 CI：测试 → Release → 官方 MCP Registry（使用 GitHub OIDC，无需把个人令牌写入仓库）。

测试覆盖图谱去重、引用方向、分页与缓存、原生导出、计数和排序、笔记保留、Notion 请求及去重、本机鉴权和 MCP stdio。独立 Zotero 测试库的 36 项检查已验证全部语言切换保留节点、真实 OpenAlex 数据、界面、Obsidian 写入和真实 MCP → Zotero 调用。**Notion 已通过接口契约测试，尚需在使用者账户中完成首次真实保存。**

## English overview

Citation Dialogue is a Zotero 9 plugin with an interactive OpenAlex citation graph. Node size reflects global citation counts; a ranked discovery panel separates external papers from library items without a local PDF. Reference and citing relations use distinct colours relative to the selected paper. Built-in Obsidian / Notion destinations and a local, authenticated stdio MCP bridge let Claude Desktop or Codex explore the same active graph and save source-linked drafts. No model API key or hosted intermediary is required by this project. External services and the AI client retain their own quotas and terms.

The graph is bounded and incrementally loaded. Citation counts are not quality scores, and metadata is not evidence of full-text reading. See [privacy](PRIVACY.md) and [setup](docs/CONNECT.md).

## 致谢

基于 Julian Schelb 的 MIT [Citation Graph](https://github.com/julianschelb/zotero-citation-graph) 启动、资源页、标签页模式及图标开发，保留原作者许可。交互界面、OpenAlex 图模型、发现排序、笔记集成及 MCP 为本项目扩展。D3 按 ISC 许可随包提供。见 [LICENSE](LICENSE) 和 [第三方说明](THIRD-PARTY-NOTICES.md)。