# MindCite

**Repository Path**: putty_git/MindCite

## Basic Information

- **Project Name**: MindCite
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <a href="./README.md"><strong>中文</strong></a>
  ·
  <a href="./README_EN.md">English</a>
</p>

<h1 align="center">MindCite</h1>

<p align="center">
  <strong>把 Zotero 论文库变成一个可追溯、可复用、可扩展的本地研究工作台。</strong>
</p>

<p align="center">
  <a href="https://github.com/YYCCCHAOOO/MindCite/releases/tag/v0.3.0"><img alt="Release v0.3.0" src="https://img.shields.io/badge/release-v0.3.0-blue"></a>
  <img alt="Local First" src="https://img.shields.io/badge/local--first-safe-green">
  <img alt="Zotero" src="https://img.shields.io/badge/Zotero-ready-red">
  <img alt="Obsidian" src="https://img.shields.io/badge/Obsidian-ready-purple">
  <img alt="Codex" src="https://img.shields.io/badge/Codex-smart%20deploy-black">
</p>

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

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

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

## 选择你的启动方式

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

## 工作流一览

```mermaid
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，直接跑合成演示数据：

```powershell
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。

## 目录结构

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

## Codex 智能部署指令

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

```text
请从 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](docs/codex-setup.md)。

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

## 快速开始

1. 克隆仓库并进入目录。

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

2. 创建本地配置文件。

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

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

```text
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。

4. 安装 Python 依赖。

```powershell
python -m pip install -r requirements.txt
```

5. 做一次结构和安全检查。

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

6. 运行空 Vault 健康检查。

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

7. 用合成演示数据试跑。

```powershell
$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 分类和已有阅读状态。

```powershell
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`。

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

也可以指定 Zotero item key：

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

### 3. 基于 notes 回答问题

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

在 Codex 中可以直接说：

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

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

## 分类治理与综述流程

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

### 健康检查

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

输出：

- `indexes/vault_health_report.md`
- `indexes/orphan_notes.jsonl`

### 分类审核队列

```powershell
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：

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

Codex 应该替你运行：

```powershell
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
```

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

```text
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` 这种导入噪声 |

推荐第一次这样做：

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

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

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

对应命令是：

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

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

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

对应命令是：

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

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

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

```powershell
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` 丢弃到黑名单。确认无误后才运行：

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

旧版审计报告仍可使用：

```powershell
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 文件，不要急着写回。

```powershell
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，并确认你已经备份本地数据库。

### 理论/方法/主题综述

```powershell
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 前执行：

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

真实迁移才使用：

```powershell
python tools/migrate.py --apply
```

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

## 致谢与来源说明

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

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

## 常见问题

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

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

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

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

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