MindCite

把 Zotero 论文库变成一个可追溯、可复用、可扩展的本地研究工作台。

推荐方式：优先使用 Codex 智能部署；熟悉命令行的用户再看 快速开始。

MindCite 是一个面向研究者的本地文献工作流模板，用来把 Zotero、Obsidian 和 Codex 串成一条可复用的研究管线：先从 Zotero 建立本地索引，再把论文原文或全文缓存整理为结构化精读笔记，最后基于已生成的 notes 做问答、分类治理和理论/方法综述。

这个公开版是安全模板，不包含任何真实论文、真实索引、真实 Zotero 数据库、API key 或个人研究材料。仓库里的 examples/demo-vault 是完全虚构的演示数据，只用于试跑功能。

选择你的启动方式

如果你是	推荐入口	适合场景
Codex 用户	Codex 智能部署指令	让 Codex 自动拉库、配置、检查并只读连接 Zotero。
0 代码用户	Codex 指令手册	直接复制自然语言指令，让 Codex 代替你操作。
命令行用户	快速开始	自己复制命令并手动配置 `.env`。
先看效果	5 分钟体验路径	不配置真实 Zotero 和 API key，只跑合成 demo。
想做分类	分类指南	理解 theory/method/topic、审核队列和 Zotero dry-run。

工作流一览

flowchart LR
  Zotero["Zotero 本地库"] --> Index["本地索引"]
  Index --> Reading["精读 notes"]
  Reading --> QA["基于 notes 问答"]
  Reading --> Classify["分类审核队列"]
  Reading --> Tags["v0.3 标签体系审计"]
  Tags --> Taxonomy["正式 taxonomy"]
  Classify --> Synthesis["理论/方法/主题综述"]
  Classify --> DryRun["Zotero 写回 dry-run"]

项目主题

把 Zotero 论文库变成一个可追溯、可复用、可扩展的本地研究工作台。

MindCite 的核心不是“让 AI 替你读完所有论文”，而是帮你建立一条更稳的研究管线：Zotero 负责资料管理，Obsidian 负责长期沉淀，Codex 负责把重复的索引、精读、分类、检查和综述草稿自动化。

核心亮点

本地优先：真实 PDF、Zotero 数据库、API key、日志和个人研究笔记默认不进仓库。
可追溯：从 Zotero 索引到精读 notes，再到分类审核和综述草稿，每一步都有文件输出。
可试跑：内置 examples/demo-vault 合成演示数据，刚下载就能验证主流程。
可扩展：模型厂商、embedding、模板、分类维度和外部数据库都通过配置层扩展。
可守底线：v0.2 起加入 schema 校验、原子写入、迁移 dry-run、quarantine 和 smoke test。
分类更稳：v0.3 起支持“审标签体系”而不是逐篇审论文，用 a/p/m/r 管理新增、暂存、合并和丢弃。
面向研究者：重点服务“持续阅读、分类治理、理论/方法积累、后续论文写作”，不是一次性的聊天问答。

适合谁

你用 Zotero 管理论文，并希望把阅读结果沉淀到 Obsidian。
你想用 Codex 或其他 AI coding agent 帮你自动跑索引、精读、分类和综述。
你希望保留本地知识库能力，但不想把 Zotero 数据库、PDF、未发表论文和 API key 上传到云端。

不适合谁

你只想要一个无需配置、打开网页就能用的在线工具。
你还没有 Zotero 或 Obsidian 的基本使用习惯。
你希望把整库论文和私人研究资料直接上传到 GitHub 或云端。
你期待 AI 自动替代研究判断，而不是辅助整理、检索和生成草稿。

5 分钟体验路径

如果你只是先体验，不需要配置真实 Zotero 路径和 API key，直接跑合成演示数据：

git clone https://github.com/YYCCCHAOOO/MindCite.git MindCite
cd MindCite
python -m pip install -r requirements.txt
python tools/structure_check.py
python tools/validate_data_contracts.py --demo-only
$env:MINDCITE_ROOT=(Resolve-Path .\examples\demo-vault)
python _skills/Zotero-Library-Sync/scripts/vault_health_check.py
python _skills/Classification-Governance-System/scripts/build_classification_review_queue.py --all
python _skills/Classification-Governance-System/scripts/discover_open_tag_candidates.py --min-notes 1
python _skills/Classification-Governance-System/scripts/prioritize_open_tag_candidates.py
python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations
Remove-Item Env:\MINDCITE_ROOT

看到 ok: true 就说明本地结构、演示索引和分类审核队列都能正常跑通。之后再复制 .env.example，填自己的 Zotero 路径和模型 key。

目录结构

MindCite/
  _skills/                         # Codex 可读取的工作流技能与脚本
  config/                          # 通用配置模板
  docs/                            # 架构、Codex 配置、排障文档
  examples/demo-vault/             # 合成演示 Vault，不含真实研究信息
  indexes/                         # 运行时索引输出，默认不提交
  logs/                            # 运行日志，默认不提交
  migrations/                      # 数据结构迁移脚本
  notes/zotero_reading/_papers/    # 新版精读笔记输出，默认不提交
  schemas/                         # 核心数据契约
  templates/                       # 可放你的公开模板
  tools/                           # 发布安全检查工具

Codex 智能部署指令

如果你使用 Codex，推荐先不要手动配置。新建一个本地工作区后，直接复制下面这段话给 Codex：

请从 https://github.com/YYCCCHAOOO/MindCite 拉取仓库，帮我创建一个私有 MindCite Vault。请自动完成依赖安装、配置文件复制、结构检查和 demo smoke test。然后只读探测我的本机 Zotero 数据库和 storage 路径，写入本地 .env，并运行 update_zotero_index.py 生成本地索引。不要提交 .env、indexes、logs、notes、PDF、Zotero 数据库或任何 API key；不要执行任何 --apply；如果只是测试精读通路，请设置 MINDCITE_OFFLINE=1，避免调用远程模型。

Codex 应该完成：

克隆仓库并进入项目目录。
复制 .env.example 和 config/mindcite.example.json。
安装 requirements.txt。
运行 python tools/structure_check.py 和 python tools/smoke_test.py。
只读探测 ZOTERO_DB_PATH 与 ZOTERO_STORAGE_PATH。
生成本地 Zotero 索引，但不写回 Zotero。

更多 Codex 配置细节见 Codex Setup。

如果你没有代码基础，建议直接看 Codex 指令手册，里面按“部署、更新索引、精读、问答、分类、综述、安全检查”整理了可复制的自然语言指令。

快速开始

git clone https://github.com/YYCCCHAOOO/MindCite.git MindCite
cd MindCite

创建本地配置文件。

Copy-Item .env.example .env
Copy-Item config/mindcite.example.json config/mindcite.json

编辑 .env。至少建议填写：

ZOTERO_DB_PATH=<你的 Zotero 本地数据库文件路径>
ZOTERO_STORAGE_PATH=<你的 Zotero storage 文件夹路径>
MINDCITE_LLM_PROVIDER=deepseek
MINDCITE_EMBEDDING_PROVIDER=siliconflow
DEEPSEEK_API_KEY=<你的 DeepSeek API key>
SILICONFLOW_API_KEY=<你的 SiliconFlow API key>

如果你只是先看演示，不需要填写真实 Zotero 路径和 API key。

安装 Python 依赖。

python -m pip install -r requirements.txt

做一次结构和安全检查。

python tools/structure_check.py
python tools/validate_data_contracts.py --demo-only

运行空 Vault 健康检查。

python _skills/Zotero-Library-Sync/scripts/vault_health_check.py

用合成演示数据试跑。

$env:MINDCITE_ROOT=(Resolve-Path .\examples\demo-vault)
python _skills/Zotero-Library-Sync/scripts/vault_health_check.py
python _skills/Classification-Governance-System/scripts/build_classification_review_queue.py --all
Remove-Item Env:\MINDCITE_ROOT

三条主流程

1. 更新 Zotero 索引

索引脚本会只读连接 Zotero 本地数据库，生成 indexes/zotero_library_index.jsonl，并尝试记录 PDF、全文缓存、Zotero 分类和已有阅读状态。

python _skills/Zotero-Reading-System/scripts/update_zotero_index.py

如果报错 No readable Zotero database found，说明 .env 里的 ZOTERO_DB_PATH 还没有配置，或路径不可读。

2. 精读文献生成 notes

精读主流程默认优先使用 Zotero 全文缓存；没有缓存时再回退 PDF。生成的新版笔记进入 notes/zotero_reading/_papers，阅读状态进入 logs/reading_status.jsonl。

python _skills/Zotero-Reading-System/scripts/zotero_ai_reading_pipeline.py --next-count 2

也可以指定 Zotero item key：

python _skills/Zotero-Reading-System/scripts/zotero_ai_reading_pipeline.py --item-keys ABC12345,XYZ67890

3. 基于 notes 回答问题

Notes-QA-System 的原则是只使用已经生成的新版本 notes，不回头扫描 Zotero note、批注或旧版笔记。这样可以保证回答来源稳定、可追溯。

在 Codex 中可以直接说：

根据已精读笔记，总结金融传染理论下的核心机制。

如果当前 notes 证据不足，agent 应明确说明“当前新版 notes 中证据不足”。

分类治理与综述流程

分类是 MindCite 中最复杂、也最值得谨慎使用的模块。详细说明见分类指南。建议先按指南生成审核队列和 dry-run，不要一开始就写回 Zotero。

健康检查

python _skills/Zotero-Library-Sync/scripts/vault_health_check.py

输出：

indexes/vault_health_report.md
indexes/orphan_notes.jsonl

分类审核队列

python _skills/Classification-Governance-System/scripts/build_classification_review_queue.py --all

输出：

indexes/classification_review_queue.jsonl

标签体系审计

v0.3 推荐把分类治理拆成两层：旧流程继续生成“论文级审核队列”，新流程负责发现新标签、判断标签是否应该进入正式 taxonomy。你主要审标签是否值得存在，不需要逐篇确认每篇论文属于哪个标签。

宝宝级教程：v0.3 新功能怎么用

这个功能解决的是一个很具体的问题：你的 notes 越来越多以后，里面会出现很多新标签、缩写、英文别名、重复标签和导入噪声。v0.3 不要求你一篇篇论文去审，而是把这些“可能要进入长期分类体系的标签”集中成一张表，让你只判断标签本身要不要保留。

如果你没有代码基础，直接把这段话复制给 Codex：

请帮我运行 MindCite v0.3 标签体系审计。只做三步：发现开放标签候选、生成优先级审计表、生成决策预览。不要执行 --apply，不要写回 Zotero，不要批量修改 notes。完成后请告诉我 tag_taxonomy_open_candidate_priority.md 的路径，并用通俗语言解释哪些标签建议接受、哪些建议合并、哪些先暂存。

Codex 应该替你运行：

python _skills/Classification-Governance-System/scripts/discover_open_tag_candidates.py --min-notes 1
python _skills/Classification-Governance-System/scripts/prioritize_open_tag_candidates.py
python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations

运行完你只需要看一个文件：

indexes/tag_taxonomy_open_candidate_priority.md

把它理解成一张“标签体检表”：

你看到的列	宝宝级理解	你要不要改
`label`	系统发现的候选标签名	一般不改
`source_dimension`	它原来像 theory、method 还是 topic	一般不改
`suggested_operation`	系统给你的建议	只参考，不自动生效
`operation`	你的最终决定	重点只改这一列
`merge_target`	如果要合并，合并到哪个旧标签	只有 `operation=m` 时才需要看
`parent_choice`	如果这是子标签，挂到哪个父标签下面	不确定就先空着

operation 只填四种字母：

填什么	意思	例子
`a`	接受，加入正式标签体系	你确认“因果识别”以后会长期用
`p`	暂存，先观察	你觉得可能有用，但现在还不确定
`m`	合并到已有标签	`DCC` 合并到 `method:DCC-GARCH`
`r`	丢弃，加入黑名单	`metadata import` 这种导入噪声

推荐第一次这样做：

先不要追求一次整理完，只看前 20 个高优先级标签。
明显重复的填 m，并确认 merge_target 对不对。
明显有长期价值的填 a。
看不懂的全部保持 p。
明显不是研究标签的填 r。

改完表以后，再让 Codex 只做预览：

我已经修改了 tag_taxonomy_open_candidate_priority.md。请只运行 v0.3 标签决策预览，不要 --apply。请告诉我 accepted、merged、rejected、pending 各有多少个，并说明会不会修改 taxonomy。

对应命令是：

python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations

只有当你确认预览没问题，才可以让 Codex 应用：

我确认 preview 没问题。请执行 v0.3 标签决策 --apply。只允许修改 classification_taxonomy.json 和 tag_taxonomy_discard_blacklist.json，不要写回 Zotero，不要批量修改 notes。完成后运行 safety_scan 和 validate_data_contracts。

对应命令是：

python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations --apply

安全提醒：--apply 不是 Zotero 写回，它只更新本地标签体系文件；真正写回 Zotero 仍然必须走 Zotero dry-run 流程。新手建议前几次都停在 preview，不急着 apply。

如果你熟悉命令行，也可以直接运行下面这组三步：

python _skills/Classification-Governance-System/scripts/discover_open_tag_candidates.py --min-notes 1
python _skills/Classification-Governance-System/scripts/prioritize_open_tag_candidates.py
python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations

输出：

indexes/tag_taxonomy_open_candidates.md
indexes/tag_taxonomy_open_candidate_priority.md
indexes/tag_taxonomy_decision_preview_summary.md

在 tag_taxonomy_open_candidate_priority.md 里只改 operation 列：a 接受为正式标签，p 暂存观察，m 合并到 merge_target，r 丢弃到黑名单。确认无误后才运行：

python _skills/Classification-Governance-System/scripts/apply_tag_taxonomy_decisions.py --use-markdown-operations --apply

旧版审计报告仍可使用：

python _skills/Classification-Governance-System/scripts/build_tag_taxonomy_proposal.py
python _skills/Classification-Governance-System/scripts/build_tag_taxonomy_audit.py

Zotero 写回

写回功能默认是 dry-run。只有显式传 --apply 才会真实写入，并且 SQLite 写回会先备份数据库。公开版建议先只生成 dry-run 文件，不要急着写回。

python _skills/Classification-Governance-System/scripts/build_zotero_writeback_dryrun.py
python _skills/Classification-Governance-System/scripts/apply_zotero_writeback_sqlite.py --limit 5

真实写回前请先关闭 Zotero，并确认你已经备份本地数据库。

理论/方法/主题综述

python _skills/Theory-Method-Synthesis-System/scripts/build_classification_synthesis.py --dimension theory --tag 金融传染

综述草稿默认写入 notes/classification_synthesis。

配置说明

公开版所有路径都通过 .env、config/mindcite.json 或系统环境变量读取：

MINDCITE_ROOT：Vault 根目录；不填时默认当前仓库。
ZOTERO_DB_PATH：Zotero 本地数据库文件路径。
ZOTERO_SNAPSHOT_DB_PATH：可选的只读数据库快照路径。
ZOTERO_STORAGE_PATH：Zotero storage 文件夹路径，用来寻找 PDF 和全文缓存。
MINDCITE_LLM_PROVIDER：生成模型厂商，可选 deepseek、openai、qwen、zhipu、custom。
MINDCITE_EMBEDDING_PROVIDER：embedding 厂商，可选 siliconflow、openai、custom。
DEEPSEEK_API_KEY / OPENAI_API_KEY / DASHSCOPE_API_KEY / ZHIPU_API_KEY：对应厂商的生成模型 key。
SILICONFLOW_API_KEY：SiliconFlow embedding key；如果 embedding 也使用 OpenAI，则复用 OPENAI_API_KEY。
MINDCITE_CONFIG：可选的自定义配置文件路径。

LLM 与 embedding 的厂商、base URL、默认模型配置在 _skills/Zotero-Reading-System/config/reader_config.json。你可以通过 .env 改 *_MODEL 变量，也可以在 reader_config.json 里新增 OpenAI-compatible 厂商；真实 key 不要写进配置文件，只放 .env 或系统环境变量。

模型厂商示例

用途	`provider`	默认模型变量	API key 变量
生成	`deepseek`	`DEEPSEEK_MODEL=deepseek-chat`	`DEEPSEEK_API_KEY`
生成	`openai`	`OPENAI_MODEL=gpt-4o-mini`	`OPENAI_API_KEY`
生成	`qwen`	`DASHSCOPE_MODEL=qwen-plus`	`DASHSCOPE_API_KEY`
生成	`zhipu`	`ZHIPU_MODEL=glm-4-flash`	`ZHIPU_API_KEY`
生成	`custom`	`MINDCITE_LLM_MODEL`	`MINDCITE_LLM_API_KEY`
Embedding	`siliconflow`	`SILICONFLOW_EMBEDDING_MODEL=BAAI/bge-m3`	`SILICONFLOW_API_KEY`
Embedding	`openai`	`OPENAI_EMBEDDING_MODEL=text-embedding-3-small`	`OPENAI_API_KEY`
Embedding	`custom`	`MINDCITE_EMBEDDING_MODEL`	`MINDCITE_EMBEDDING_API_KEY`

安全底座

v0.2.0 开始，MindCite 把长期扩展风险显式拆出来；v0.3.0 进一步把分类体系变更变成可预览、可回滚、可黑名单化的治理流程：

schemas/：定义 index、reading status、note frontmatter、taxonomy、review queue 的数据契约。
_skills/common/safe_io.py：提供原子写入、备份和 quarantine。
tools/validate_data_contracts.py：校验 demo 或真实 Vault 是否符合当前契约。
tools/migrate.py：默认 dry-run，把旧数据升级到当前 schema_version。
tools/smoke_test.py：用 demo-vault 跑一遍回归检查。
tag_taxonomy_*：开放候选、优先级审计表和决策预览，正式改 taxonomy 前先留痕。

推荐在新增功能或迁移真实 Vault 前执行：

python tools/migrate.py --dry-run
python tools/smoke_test.py

真实迁移才使用：

python tools/migrate.py --apply

扩展新功能前，请先看 docs/extension-policy.md。

致谢与来源说明

MindCite 的部分工作流思想受到 GitHub 用户 cheneternity 的两个公开 Codex skill 仓库启发，包括 Zotero 到 Obsidian 的阅读工作流拆分，以及基于本地 Vault 笔记回答问题的原则。

本仓库不内置、不复制、不再分发上游仓库的文件或模板；公开版代码、配置层、数据契约、demo 数据、安全扫描和分类治理均为 MindCite 重新实现。详细说明见 NOTICE.md 和 Attribution Review。

常见问题

没有 PDF 怎么办？
精读流程会把条目标记为 needs_pdf，你补齐 PDF 或 Zotero 全文缓存后再继续。

没有全文缓存怎么办？
脚本会尝试回退到 PDF。若 PDF 也没有，就跳过并写日志。

API key 失败怎么办？
先确认 .env 是否存在、变量名是否正确、终端是否在仓库根目录运行。再确认 provider 额度和网络访问。

中文路径可以用吗？
可以，但建议 PowerShell 命令使用引号包住路径，Python 文件读写统一使用 UTF-8。

我可以直接上传自己的 Vault 吗？
不建议。请使用这个公开模板，再把自己的真实 notes、indexes、logs、PDF 和数据库留在本地。