Aryan-Pardeshi/CiteProof-AI · 上手攻略
- 仓库：Aryan-Pardeshi/CiteProof-AI
- 链接：https://github.com/Aryan-Pardeshi/CiteProof-AI
- 分类：agent · rag · llm-infra · 学术写作系统综述
- 作者：spark
- 更新：2026-10-22
1. 这是什么
CiteProof-AI 是面向 AI 文献综述的两件套，由两部分组成：
- CiteProof MCP —— 一个 24 工具的 stdio MCP server，不含任何 LLM，只负责存储/校验系统综述里需要用到的证据链。
- CiteProof Research（"应用"）—— 一个 24 agent × 5 阶段的 LangGraph 后端 + Vanilla JS 前端，可一键跑出"带 PRISMA 流图 + 证据映射矩阵 + .pdf/.docx 导出"的可复现论文草稿。
两者的关系很直白：MCP 偏审计（你或你的 agent 干"找文献/读文献/判断"的活，它替你"记账+挑错"），应用偏端到端（自己找、自己读、自己写，但每一条都强制带证据）。README 引用了一个早期基准：在 Claude Science 接入下，"搜索强"的 agent 比 CiteProof 应用找得到更多已知应纳入研究——所以 MCP 干脆不搜，专做审计。
2. 解决什么问题
- 系统综述/PRISMA 的可审计性：每一条引用、每一条数字、每一个 PRISMA 计数都能对到证据。
- 一稿多 agent 时口径漂移：用确定性
paper_id/evidence_id/claim_id锚定，杜绝"同一篇论文两个 paper_id"或"两处数字打架"。 - 评审/导师"请给我一段可复现的运行结果"要求：导出
export_bundle+ JSON + 校验报告。 - AI agent 既"会搜"又"会写"，但"不会被审"的尴尬：MCP 强制以"normalised 文本 + 词边界"做引文真伪验证、引文存在性、引文与参考列表对齐、RoB 判定规则对齐等。
它不会主动找文献（在 MCP 模式下）、不会读 PDF（要 agent 自带解析）、不会为内容好坏背书（"supported" 只是 agent 的判断，server 只校验引文是否在原文里）。PRISMA checklist 与数字计数也是关键字检查，不是"是否报告良好"的判断。
3. 快速安装
3.1 Demo
- 应用 demo：https://deep-research-ai-xi.vercel.app/
- MCP 仓库：https://github.com/Aryan-Pardeshi/CiteProof-AI-MCP
3.2 MCP（审计/agent 协同用）
# 1) 取仓库并配置
git clone https://github.com/Aryan-Pardeshi/CiteProof-AI-MCP.git
cd CiteProof-AI-MCP
cp .env.example .env
# 2) 最小 .env（缺一即开不动应用层）
LLM_API_KEY="your_api_key_here"
LLM_BASE_URL="https://api.deepseek.com"
TAVILY_API_KEY="your_tavily_key_here"
OPENALEX_EMAIL="you@example.com"
NCBI_EMAIL="you@example.com"
NCBI_TOOL_NAME="your_tool_name"
# 3) 可选
SEMANTIC_SCHOLAR_API_KEY="..."
NCBI_API_KEY="..."
CORE_API_KEY="..."
ORCID_AUTHOR_ENRICHMENT=0
# 4) 一键起
docker compose up -d --build
UI 默认在 http://localhost:8000。
只用 MCP（不跑应用）：在 MCP 仓库目录下 pip install ./MCP，并在客户端配置 stdio：
{
"mcpServers": {
"citeproof": {
"command": "citeproof-mcp",
"env": { "CITEPROOF_MCP_HOME": "/path/to/your/review-data" }
}
}
}
无 CITEPROOF_MCP_HOME 时落 ~/.citeproof-mcp。
Claude Science：因 Local command connector 在沙盒里跑、读不到项目文件，需要先用 MCP/scripts/build_claude_science_bundle.py 把 server 打到一个 connector workspace，然后 python3 <bundle>/run.py。文档：在 Windows + Claude Science 0.1.67 上验证过 24 工具全部出现；端到端全量评审尚未做基准。
3.3 应用（端到端研究用）
非 docker 路径：
python -m venv .venv
# Windows
.venv\Scripts\activate
# Unix
source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.app.main:app --reload --port 8000
⚠️ 仓库根 README 与 MCP README 都给出 install 路径，但入口细节（
backend/app/main:appvs 仓库别的 run 脚本）请以 release tag 现场ls为准——本文以写作时 README 为据。
4. 核心用法
4.1 MCP 的 24 个工具
按组别：
| 分组 | 工具 |
|---|---|
| Set up & status | review_create, review_list, protocol_record, review_status |
| 检索与去重 | prisma_record_search, dedup_papers, prisma_record_dedup |
| 筛选 | screening_record, screening_record_many, screening_list, screening_agreement |
| PRISMA | prisma_status, prisma_flow_diagram, prisma_checklist |
| 证据与偏倚 | evidence_record, evidence_table, claim_record, claim_report, rob_record, rob_summary |
| 引用与文稿 | verify_dois, resolve_citations, lint_prose |
| 导出 | export_bundle |
每次调用都会对 PRISMA 的 6 个不变量做断言（举例）：records_identified - duplicates_removed == records_after_dedup、full_text_requested - excluded_full_text == studies_included 等。计数绝不由 LLM 生成/估算——这是 README 的明示约束。
4.2 引用真实性校验
引文与数字配对的判定规则（README 摘录）：
- A quote really appears in the source text：agent 把引文与原文一并发送；server 在归一化大小写/空白/引号/破折号/换行连字符后，按词边界匹配。结果记作
quote_verified。 - Numbers in the evidence table come from the quote：样本量、点估计、置信区间必须出现在引文里；超出区间的估计值会被拒绝。
- PRISMA numbers add up：所有计数源自"已记录的检索/去重/筛选决策"，且每次调用都做流不变量检查。
- Two reviewers agree：对两位评审都判定过的论文计算 Cohen's κ，附分歧清单。
- DOIs exist and are not retracted：查 Crossref + doi.org；注册库不可达返回
unverified（绝不返回not found）。 - Citations match the reference list：按 DOI / 作者+年 / 标题匹配；
Resolved≠Supported——只表示已解析，不背书语义。 - Risk-of-bias overall judgements：遵循 RoB 2、ROBINS-I、Newcastle-Ottawa（AHRQ 阈值）的发布规则。
- Duplicates：DOI → PMID → 标题+年+第一作者 的确定性聚类。
4.3 应用的两类模式
| 维度 | DeepSearch | Research Mode（Evidence-First） |
|---|---|---|
| 目标 | 用实时 Web 答一个问题 | 写一篇完整、带证据的学术论文 |
| 数据源 | Tavily web search | OpenAlex · Semantic Scholar · Crossref · PubMed · arXiv · Europe PMC · DOAJ · DataCite · OpenCitations |
| Agent 数 | 5（fan-out 并行） | 24 / 5 阶段 |
| HITL 关卡 | 1（计划批准） | 3（协议 / 证据语料 / 假说） |
| 数据不变量 | LLM Web 摘要 | 确定性 EvidenceRecord（引文 + 指标 + 基线） |
| PRISMA | N/A | 确定性 PRISMA 2020 流量计数 + 断言 |
| 完整性审计 | 引用正则 | 自动化引用 + 数字声明 ground 校验 |
| 运行时长 | ~1–2 min | ~5–15 min |
| 输出 | 结构化 markdown | 全文 + PRISMA 图 + 证据映射矩阵 |
| 导出 | .md |
.pdf · .docx |
两者共用 FastAPI + SSE + SQLite checkpointer + LLM 层（结构化 JSON 输出）。
4.4 3 道 HITL 质量关卡
每关都在 LangGraph 的 interrupt() 上暂停，等作者用自然语言批准或要求局部修订：
| 关卡 | 阶段 | 审阅产物 | 担保 |
|---|---|---|---|
| G1 计划 / 协议 | 阶段 1 | PICOC 协议 / 目标 / 问题 / 布尔关键词 | 多源检索启动前先收敛 |
| G2 证据 / 语料 | 阶段 3 | PRISMA 流量 / 筛选文献 / 提取证据 | 合成前先验证据落地 |
| G3 假说 / 框架 | 阶段 4 | 概念框架 / 研究空白 / 假设 H1..H5 | 全文生成前先保证理论成立 |
4.5 关键不变量（读这段就懂为什么它"可审计"）
PRISMATracker.validate_invariants()在每次调用都校验以下关系（不全等于完整 PRISMA 2020 流，但属"内部确定性不变量"）：records_identified - duplicates_removed == records_after_dedup、records_screened - excluded_title_abstract == full_text_requested、full_text_assessed - excluded_full_text == studies_included。PaperRecord.paper_id= DOI 的 SHA-256 前 16 位 hex（截断写法，不是完整摘要）；无 DOI 时回退title::并补year；归一化 title 不假设唯一，所以也纳入年份。EvidenceRecord.evidence_id={paper_id}_ev001这种确定性格式（不二次 hash），锚定精确引文 + 指标 + 基线 + 方向。ReviewClaim.claim_id={section 前 8 字}_cl001；section slug 截断 8 字。- 校验链：
claim → evidence → paper → DOI/URL。已"resovled" ≠ 已"verified"。 citation_validator/claim_validator/integrity_auditor三大确定性校验器，最终产出ValidationReport，"passed_all_gates" 仅意味"分辨率 + 数字匹配"两关通过，不证明语义支撑。
4.6 技术栈速览
| 层 | 技术 |
|---|---|
| 编排 | LangGraph（StateGraph、interrupt() HITL、Send() fan-out、SQLite 持久化） |
| 结构化 LLM | Pydantic v2 schema + ainvoke_structured_with_retry |
| 学术源 | OpenAlex、Semantic Scholar、Crossref、PubMed、arXiv、Europe PMC、DOAJ、DataCite、OpenCitations |
| 作者归并 | 可选 ORCID 规范化 |
| 全文回取 | Unpaywall → Europe PMC → CORE 链 |
| 后端 API | FastAPI + SSE + keep-alive 心跳 |
| 前端 | Vanilla JS + CSS（Swiss Modernism 2.0 / 零构建） |
| 图 | matplotlib（PRISMA 2020 / 假说证据矩阵） |
| 导出 | FPDF2（.pdf 含悬挂 APA 缩进） · python-docx（.docx） |
| MCP server | mcp SDK 1.27 + 2.x / SQLite / Pydantic v2 / httpx |
5. 典型适用场景
- 研究生 / 团队写系统综述：把"PRISMA 流 + 风险偏倚判定"用确定性 tool 跑通，避免导师逐条挑错。
- AI agent 做研究的合规审计：让 MCP 强行校验引文真伪 / 引用一致性 / 计数守恒，给协作者一份"可重放"记录。
- LLM 出 PRISMA 漂移的复现与修复：拿本项目的
ValidationReport做"修复前后"对照样本。 - 学术研究的产品化 / MCP 工具链接入：把 MCP 接到自家研究 agent，例如 Claude Science / MCP-aware 工作流。
6. 坑与注意
| # | 现象 | 影响 | 修复 |
|---|---|---|---|
| 1 | 把"resolved 引用"当成"语义支撑" | 写作里出现被表面通过的误引 | 引入人工读 claim_validator + evidence_record 比对，PRISMA 不背书语义 |
| 2 | 指望 MCP 帮你"找文献" | 工作流浪费，README 明确"它不搜" | 由上层 agent 或应用层（DeepSearch/Tavily/学术 API）负责搜索 |
| 3 | 期望 MCP 自动读 PDF | 大量文本进不来 | 让 agent 自带解析器，再把文本交给 MCP |
| 4 | 复用同一 DOI/标题两套"归一化"逻辑 | 同一篇论文出现两个 paper_id |
严格按 README 的"DOI → PMID → title+year+first_author"顺序聚类 |
| 5 | PRISMA checklist 等同"证据好坏" | 不该过的稿子被放行 | 把 checklist 视为"是否提及"而非"是否报告良好" |
| 6 | 把 ORCID_AUTHOR_ENRICHMENT=1 写进 .env 但未注册 ORCID |
作者归并失败、降级到原始名 | 显式 =0 直到接入 ORCID；归并失败的 author 单独标记 |
| 7 | 对 Claude Science 寄望"全自动接入" | MCP 容器读不到本地工程目录 | 走 build_claude_science_bundle.py 把 server 移到 connector workspace |
| 8 | 把 DOI 注册库不可达当成"该 DOI 不存在" | 误标"未核实"为"无效" | register 不可达应固定返回 unverified，不要写 not_found |
| 9 | .pdf 导出当 APA 7 严谨引用 |
悬挂 APA 缩进仅为样式，引用字段需自校 | 自己过一遍 .docx 版本校验；UI 端到端走通后回到 reference list 做最后对齐 |
| 10 | 长时跑（10+ 分钟）的 SSE 链接在代理后中断 | 任务数据"丢一半" | 用脚本端的 SSE 自动重连 + checkpointer 恢复；本仓库 SQLite checkpointer 持久化 |
7. 与同类对比
| 维度 | CiteProof-AI | Elicit / Consensus / SciSpace（商用） | 普通 RAG + 手写 PRISMA |
|---|---|---|---|
| 模型独立 | 是（MCP 无 LLM） | 否 | 取决于实现 |
| 离线确定性校验 | 是（PRISMA 不变量） | 否 | 否 |
| 自托管 / 开源 | 是（MIT） | 商用 / 闭源 | 自建 |
| 全文检索 + MCP 接入 | 标准 stdio MCP | 一般不暴露 | 自建 |
| 多学术 API 一站编排 | 8 个 discovery + 1 图扩展 | 一般挂 1–2 个 | 自建 |
| 自动生成 .pdf / .docx | 是 | 是 | 否 |
| 风险偏倚规则强制 | RoB 2 / ROBINS-I / Newcastle-Ottawa | 部分 | 否 |
| HITL 中断 + 自然语言修订 | 3 关 LangGraph interrupt() |
否 | 否 |
| 端到端基准 | README 自报基准 | 商业私测 | 无标准 |
8. 一句话推荐结论
做学术综述 + 想给评审/导师一份"可被审计的运行记录"——优先用 CiteProof-AI；只想被 AI 写一份综述草稿、不在意可复现性时，没必要上它。
不确定/诚实标注
- 仓库卡片
Stars 91 / 周增 +21 / 最近提交 2026-10-21与 README 描述一致；具体 API 数（8 discovery + 1 图扩展）以 release tag 为准。 - 应用端的入口
backend.app/main:app来源 README；非 docker 路径下若目录为app/或main.py，请以拉取后ls backend/为准。 - "在 Claude Science 0.1.67 上验证 24 工具全部出现"为 README 自报，端到端完整 review run 尚未公开基准。
- API key 价格条款、Tavily / Semantic Scholar / CORE 的速率限制不在仓库直接披露，请查各自官方页。
- 学术 API 的字段映射（如 ORCID 归并的确定性）需自己跑小样验证，不在 README 内做可复现基准声明。