1. 项目概述一个为AI智能体设计的深度学术研究技能如果你是一名研究生、科研人员或者任何需要快速、系统地梳理某个领域文献的人那么你肯定体会过那种面对海量论文时的无力感。传统的流程是打开Google Scholar输入关键词手动筛选几十甚至上百篇论文下载PDF阅读摘要整理笔记最后再艰难地组织成一篇结构化的综述。这个过程不仅耗时耗力而且极易因为个人偏见或搜索策略不当遗漏关键文献。今天要介绍的这个项目scholar-deep-research就是为了解决这个痛点而生的。它不是一个简单的文献搜索工具而是一个完整的、由脚本驱动的、端到端的学术研究工作流。它的核心目标是让一个AI智能体比如Claude Code、OpenCode等能够像一位经验丰富的研究员一样从你提出的一个研究问题出发自动执行一套严谨的、分阶段的流程最终生成一份结构清晰、引用规范、并经过自我批判性审查的学术报告。简单来说你只需要对你的AI助手说“帮我深入研究一下CRISPR碱基编辑治疗杜氏肌营养不良症的现状。” 接下来这个技能就会接管一切它会分解你的问题从多个学术数据库联合搜索去重、排序、深入阅读PDF、追踪引用网络、进行主题聚类最后生成一份带完整参考文献的综述报告。整个过程是透明的、可审计的并且每一步都有“质量关卡”确保研究的严谨性。这个项目最吸引我的地方在于它的“脚本优先MCP可选”设计哲学。它不依赖于任何特定的、可能不稳定或需要付费的AI模型服务MCP工具而是基于Python脚本和公开的学术API如OpenAlex、arXiv构建。这意味着整个工作流是确定性的、可复现的并且在没有网络或特定工具的情况下也能降级运行。对于追求研究可重复性和过程透明度的我来说这简直是福音。2. 核心设计思路与工作流拆解2.1 为什么是八阶段工作流scholar-deep-research将研究过程严格划分为八个阶段Phase 0 到 Phase 7每个阶段都有明确的目标和输出并且阶段间的过渡由强制性的“关卡”Gate控制。这种设计并非为了增加复杂性而是为了模拟并固化一个严谨的学术研究思维过程防止AI智能体或人类研究员跳过关键步骤。Phase 0界定范围。这是研究的起点。AI会解析你的初始问题将其分解为更具体的搜索子问题并根据你的研究意图是写文献综述、系统综述还是比较分析选择合适的报告模板。同时它会初始化一个核心文件——research_state.json。这个文件是整个研究的“记忆中枢”后续所有操作、决策、数据都会记录在这里确保研究是可中断、可恢复、可审计的。Phase 1发现文献。这是搜索阶段。技能会并行查询四个主要的学术源OpenAlex主源覆盖2.4亿作品、arXiv预印本、CrossrefDOI元数据和PubMed生物医学。这里的关键在于“联合搜索与去重”。不同数据库的覆盖范围有重叠直接合并结果会产生大量重复。该技能采用“DOI优先标题相似度兜底”的策略进行智能去重确保每篇论文在系统中只有一个记录。更聪明的是它的“饱和停止”机制。传统的AI搜索可能只进行一轮或者无休止地进行下去。这里技能会进行多轮搜索直到满足“饱和”条件新一轮搜索发现的新论文数量少于总论文数的20%并且新论文中没有引用量超过100的“高影响力新星”。这模拟了研究员在感觉“挖不到新东西了”时的直觉判断用数据给出了一个理性的停止信号。Phase 2筛选与排序。收集到论文后如何选出最相关的这里摒弃了黑箱算法采用了“透明排序公式”。每篇论文会得到一个综合得分α·相关性 β·引用量 γ·新颖性 δ·期刊/会议权重。权重α, β, γ, δ根据你选择的报告类型如文献综述更看重引用量和权威性动态调整。最重要的是每个组成部分的分数都会明文写入research_state.json你可以在最终报告的方法论部分引用这个排序逻辑极大增强了研究的透明度。Phase 3深度阅读。对筛选出的Top N论文技能会尝试获取并解析PDF全文。它使用pypdf库进行文本提取并能检测扫描版PDF提示你需要额外OCR。对于有DOI的论文它会通过paper-fetch工具链或Unpaywall回退尝试获取合法的开放获取版本。这一步会为每篇论文提取关键证据和发现为后续的综合分析打下基础。Phase 4引用追踪。这是文献综述中“滚雪球”法的自动化实现。以Phase 2选出的高排名论文为“种子”技能会通过OpenAlex的引用图谱同时进行“前向追踪”查找引用了这些种子的新论文和“后向追踪”查找这些种子引用的更早的基础论文。这能有效发现那些可能被关键词搜索遗漏但在学术对话网络中处于核心位置的重要文献。Phase 5综合与主题映射。基于深度阅读提取的证据技能会对所有论文进行主题聚类例如可能聚出“递送载体”、“编辑效率”、“脱靶安全性”等主题。更重要的是它会识别不同研究之间的“张力图”比如指出有三篇论文在“AAV血清型最优选择”这一问题上存在分歧。这有助于在报告中构建批判性讨论而非简单罗列事实。Phase 6自我批判。这是我认为该项目最具创新性的一环。在生成报告前必须强制通过一个包含14个检查点的对抗性清单。这个清单会检查诸如“报告中是否有未锚定到具体引用的断言”、“文献来源是否过度偏向某个特定期刊或作者”、“是否因过度追求新颖性而忽略了经典奠基工作”、“是否检查了高被引论文的可靠性”等问题。如果发现问题工作流甚至会跳回Phase 1发起针对性的补充搜索。这个阶段确保了最终报告不是AI的“自信幻觉”而是经过严格质控的产物。Phase 7报告生成与导出。最后根据Phase 0选定的模板文献综述、系统综述等技能将所有的发现、主题、张力以及自我批判的结果渲染成一篇完整的Markdown报告。报告中每一个事实性断言都必须带有[^id]这样的引用锚点连接到文末的参考文献。参考文献会自动以BibTeX、CSL-JSON或RIS格式导出方便导入Zotero、EndNote等文献管理软件。2.2 状态管理与确定性研究可复现的基石整个工作流围绕一个中心文件——research_state.json运转。这个文件记录了从问题定义、每一轮搜索查询和结果、去重合并记录、每篇论文的详细元数据和评分组件、到最终报告引用的所有信息。这带来了几个巨大优势可恢复性研究可以在任何阶段中断比如AI对话超时下次只需从状态文件恢复就能继续无需重头开始。可审计性你可以像查看实验日志一样审查AI做出的每一个决策。为什么选这篇论文它的得分构成是什么自我批判阶段提出了哪些问题这一切都白纸黑字记录在案。可复现性给定相同的初始问题和相同的research_state.json整个工作流将产生完全相同的输出。这对于学术研究的严谨性至关重要。“关卡”机制是另一个精妙的设计。阶段不能随意跳转。例如从Phase 1发现进入Phase 2排序前必须通过“G1”关卡该关卡会检查是否已完成至少一轮搜索且已达到饱和状态。如果未通过AI会收到一个结构化的错误信息其中甚至包含了建议执行的下一步命令如python scripts/search_openalex.py ...引导其自动修复问题而不是陷入困惑。幂等性设计所有会修改状态文件的操作命令如ingest,rank都支持--idempotency-key参数。这意味着如果AI因网络波动等原因重复执行了同一个命令只要密钥相同后续调用将直接返回第一次的结果而不会重复修改状态或重复执行搜索完美支持了AI在崩溃恢复时的鲁棒性。3. 核心功能模块深度解析3.1 多源联合搜索与去重策略为什么选择这四个数据源OpenAlex作为主源因为它是一个免费的、开放的学术图谱覆盖广2.4亿作品且提供了丰富的元数据和引用关系API是进行引用追踪和透明排序的理想基础。arXiv捕获最新的预印本研究对于计算机科学、物理学、数学等快速发展的领域至关重要。Crossref提供权威的DOI元数据是论文去重和获取出版信息的关键。PubMed专注于生物医学领域是该领域研究者的必备数据库。实操要点与避坑速率限制处理所有脚本都内置了礼貌的请求间隔。但对于OpenAlex和Crossref我强烈建议在命令中加上--email your-emailexample.com参数。这会将你的请求放入“礼貌池”获得更高的速率限制。这在实际使用中能显著提升搜索效率避免因429错误而中断。搜索策略项目在references/search_strategies.md中提供了高级搜索策略如布尔逻辑、PICO框架等。AI智能体会根据你的问题复杂度自动选择。对于复杂问题手动提示AI使用更精确的策略如“使用PICO框架构建PubMed搜索式”可能会得到更好的初始结果。去重算法细节去重是联合搜索的难点。技能首先尝试用DOI匹配这是最精确的。对于没有DOI或DOI冲突的记录它会计算标题的相似度如Jaccard或余弦相似度。这里有个细节相似度阈值是预先设定好的但你可以通过修改scripts/dedupe_papers.py中的title_similarity_threshold变量来调整严格程度。对于某些标题较短或格式不规范的领域如某些会议论文可能需要调低阈值以避免误合并。3.2 透明排序公式告别黑箱排序公式Score α·relevance β·citations γ·recency δ·venue_prior是理解AI筛选逻辑的关键。相关性基于搜索查询与论文标题、摘要的词汇匹配程度计算。目前是词袋模型但代码结构为嵌入模型如Sentence-BERT的重排序预留了接口。如果你有本地嵌入模型可以计算语义相似度并写回state.papers[i].score_components.relevance字段实现更智能的排序。引用量直接使用OpenAlex等源提供的引用计数。对于arXiv等没有引用数据的源此项为0。注意引用量是历史影响力的指标但可能不利于新兴领域的最新工作。通过调整β权重可以控制其影响。新颖性基于出版年份。γ权重控制你对最新研究的偏好程度。写文献综述时γ可以设低一些写前沿报告时γ可以设高。来源权重venue_prior是对期刊/会议声望的量化。项目内置了一个简单的分级顶会/顶刊 一般会议/期刊 预印本等。δ权重控制你对“权威性”的看重程度。我的实操心得在开始一个研究前花点时间思考你的报告类型。如果是“系统综述”你可能需要更高的β和δ强调权威和高被引如果是“范围综述”或“背景调研”可能需要更高的γ以覆盖最新动态。你可以在Phase 0之后手动编辑research_state.json中的ranking_weights字段来微调这些参数让AI的排序更贴合你的具体需求。3.3 自我批判阶段对抗AI的“幻觉”与偏见Phase 6的14点检查清单是这个项目的“灵魂”。它强制AI进行一轮反事实思考这是普通AI提示难以稳定实现的。清单中的关键检查点包括引用锚点完整性报告正文中每个事实陈述是否都链接到了具体的参考文献[^id]没有“裸奔”的断言。来源多样性检查是否过度依赖某一两个期刊或作者群这能防止报告陷入“回音室”效应。时效性偏差是否因为过度追求“最新”而忽略了该领域5-10年前的奠基性工作清单会检查高被引的经典论文是否被纳入。高引论文核实对于排名靠前的高被引论文是否核实过其未被撤稿是否检查过其主要结论是否仍被后续研究支持对立观点搜寻是否主动搜索并包含了与当前主要结论相矛盾的研究踩过的坑在一次关于“机器学习在天气预报中的应用”的研究中自我批判阶段发现初始报告严重偏向于最近3年深度学习模型如Transformer的论文而完全忽略了更早但至关重要的数值天气预报同化方法方面的研究。AI根据批判结果自动发起了针对“data assimilation”和“numerical weather prediction”的补充搜索最终使报告的历史脉络和技术对比变得完整和平衡。这个阶段输出的批判性发现会直接作为附录写入最终报告这不仅增加了报告的深度也展示了研究过程的严谨性。3.4 报告模板与引用管理项目提供了五种报告原型模板这不是简单的格式不同而是结构思维的体现文献综述按主题或时间线组织强调领域的发展脉络和现状。系统综述有明确的方法论章节描述搜索、筛选、质量评估流程通常用于回答一个具体的临床或政策问题。范围综述旨在快速摸清一个新兴领域的规模和性质更注重广度而非深度。比较分析侧重于对比不同方法、技术或理论的优劣结构围绕比较维度展开。项目背景用于基金申请或项目开题强调研究空白和本项目的必要性。引用锚点强制机制在Phase 7生成报告时导出脚本会扫描正文寻找没有[^id]锚点的陈述。如果发现生成会失败并提示错误。这从根本上杜绝了AI生成“无源之水”式的内容。你必须为每个事实找到对应的论文证据。这虽然严格但却是学术写作的黄金标准。4. 安装、配置与多平台实战指南4.1 环境准备与依赖安装项目的核心依赖极其精简只有httpx用于高效的HTTP请求和pypdf用于PDF解析。这降低了部署门槛和依赖冲突的风险。# 1. 克隆项目仓库 git clone https://github.com/Agents365-ai/scholar-deep-research.git cd scholar-deep-research # 2. 创建并激活虚拟环境强烈推荐避免污染系统Python python -m venv .venv # Windows: .venv\Scripts\activate # Linux/Mac: source .venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt注意事项Python版本确保你的Python版本≥3.9。一些较老的系统默认可能是3.6或3.7需要升级。虚拟环境尤其是在使用Claude Code等AI编码智能体时它们可能会在项目目录下自动操作。使用虚拟环境可以确保依赖被隔离不会影响其他项目。网络问题httpx和pypdf都是纯Python库通常安装顺利。如果遇到超时可以考虑使用国内镜像源如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。4.2 在不同AI智能体平台上的安装这是该项目作为“技能”的核心价值所在——它被设计成可以无缝集成到各种AI编码助手中。安装的本质就是把技能文件放到各个平台约定的技能目录下。最推荐的方式让AI自己安装直接在Claude Code、OpenCode等聊天窗口中输入请为我安装 https://github.com/Agents365-ai/scholar-deep-research 这个技能并在其目录内运行 pip install -r requirements.txt。一个合格的、支持Agent Skills格式的AI会识别出这是一个技能仓库自动将其克隆到正确的本地目录并安装依赖。这是最省心的方法。手动安装路径参考表平台全局安装路径 (对所有项目可用)项目级安装路径 (仅当前项目可用)Claude Code~/.claude/skills/scholar-deep-research/.claude/skills/scholar-deep-research/OpenCode~/.config/opencode/skills/scholar-deep-research/.opencode/skills/scholar-deep-research/OpenClaw~/.openclaw/skills/scholar-deep-research/skills/scholar-deep-research/Hermes Agent~/.hermes/skills/research/scholar-deep-research/需在配置文件中指定外部目录pi-mono~/.pimo/skills/scholar-deep-research/通常只支持全局安装OpenAI Codex~/.agents/skills/scholar-deep-research/.agents/skills/scholar-deep-research/我的实操心得项目级安装优先除非你频繁在所有项目中都用这个技能否则我推荐使用项目级安装。这样你的技能版本和依赖可以与当前项目绑定避免不同项目间的冲突。当你把项目文件夹打包或上传到Git时技能也包含在内确保了研究环境的可复现性。检查技能加载安装后可以在AI对话中问一句“你现在有哪些可用的技能”或“列出已加载的研究相关技能”来确认scholar-deep-research是否成功加载。ClawHub/SkillsMP用户如果你通过clawhub install或skills install安装更新也应该通过对应的包管理器命令如clawhub update进行。技能内的自动更新脚本会检测到非git安装方式并跳过避免冲突。4.3 自动更新机制详解项目内置了一个非常贴心的自动更新机制。每次技能被触发开始一项新研究时Phase 0 Step 0它会自动运行python scripts/check_update.py。它的工作流程是静默检查尝试git fetch远程仓库查看是否有新提交。安全更新如果本地没有未提交的修改它会自动执行git merge --ff-only进行快进合并更新到最新版本。保护本地修改如果你在技能目录里做了一些自定义修改比如调整了排序权重它会检测到并跳过更新只在日志中提示“检测到本地修改已跳过更新”绝不会覆盖你的工作。依赖检查它会对比更新前后requirements.txt的差异。如果依赖有变化它会给出提示但绝不会自动运行pip install。这是出于安全考虑因为脚本不知道你使用哪个Python环境或虚拟环境。优雅降级如果网络不通、不是git仓库更新检查会安静地失败研究流程会继续使用当前版本绝不会因为更新问题而卡住。如何控制更新默认行为用最新版省心。锁定版本如果你正在撰写一篇论文需要确保研究过程完全可复现可以设置环境变量export SCHOLAR_SKIP_UPDATE_CHECK1。这样技能就会固定使用磁盘上的当前版本。你甚至可以结合git checkout 具体的commit哈希来锁定一个历史版本。手动更新任何时候进入技能目录运行git pull --ff-only和pip install -r requirements.txt如果需要即可。5. 完整工作流实操案例与问题排查5.1 实战演练从问题到报告假设我们想研究“图神经网络在推荐系统中的应用的最新进展”。第一步启动研究在已安装技能的AI对话窗口中直接输入请对“图神经网络在推荐系统中的应用的最新进展”进行一次深入的文献综述研究。AI会识别出这是一个需要学术研究技能的任务并自动触发scholar-deep-research。第二步观察阶段演进AI日志输出你会看到类似以下的阶段输出这是理解AI在做什么的关键[Phase 0] 正在界定范围... 问题解析用户希望了解GNN在推荐系统中的最新进展。这需要一个能覆盖最新技术、对比不同方法、并指出趋势的综述。 选定报告原型literature_review (文献综述)。 初始化状态文件./research_state.json[Phase 1] 开始文献发现... 搜索集群1: “graph neural network recommendation system” (OpenAlex, arXiv) 搜索集群2: “GNN recommender system” (Crossref, PubMed) 搜索集群3: “social recommendation graph neural” (OpenAlex) 第1轮从4个源共获得235条结果去重后得到189篇唯一论文。 第2轮基于新发现论文标题扩展查询获得76条结果15篇新论文。 饱和检查新增论文占比7.9% (20%)且无新增高引论文(100次引用)。达到饱和停止发现。[Phase 2] 论文筛选与透明排序... 应用literature_review权重 (α0.4, β0.3, γ0.2, δ0.1)。 为189篇论文计算综合得分。排名前25的论文已被选中。 每篇论文的得分组件相关性、引用、新颖性、来源权重已写入状态文件。[Phase 3] 深度阅读... 尝试为25篇精选论文获取全文PDF。 成功获取并解析21篇PDF。4篇仅提供摘要1篇付费墙3篇仅会议摘要。 为每篇论文提取了核心方法、实验设置、关键结果等证据片段。[Phase 4] 引用追踪... 以排名前10的论文为种子进行深度为1的引用图谱扩展查找引用了它们的论文以及它们引用的论文。 通过前向追踪新增18篇候选后向追踪新增12篇候选。 经过重新排序有5篇新论文进入Top 25列表。[Phase 5] 综合分析与主题映射... 识别出5个主要主题1) 基于用户-物品二部图的GNN 2) 融合社交关系的GNN 3) 动态时序图神经网络推荐 4) 可解释性GNN推荐 5) 基于知识图谱的GNN推荐。 发现张力在“动态GNN推荐”主题中关于如何处理长期兴趣漂移有三篇论文提出了不同的架构解决方案。[Phase 6] 自我批判... 运行14点检查清单。 发现问题#3报告初稿中提及“GNN已普遍取代传统协同过滤”此断言过于绝对且未锚定到具体比较研究。 发现问题#8文献来源中KDD、WWW、RecSys等计算机会议占主导可能忽略了信息系统或市场营销领域的相关研究。 根据批判结果启动针对性补充搜索“traditional collaborative filtering vs graph neural network recommendation”、“recommender system journal marketing”。 补充搜索新增3篇重要论文已整合入分析。[Phase 7] 生成报告... 使用literature_review模板渲染最终报告。 确保所有断言均带有引用锚点。 生成报告文件reports/gnn-recommender-system_20231027.md 导出参考文献reports/gnn-recommender-system_20231027.bib第三步获取成果在项目根目录下的reports/文件夹中你会找到生成的Markdown报告和BibTeX文件。报告结构清晰包含摘要、引言、各个主题的详细论述、张力讨论、批判性附录以及完整的参考文献列表。5.2 常见问题与排查技巧在实际使用中你可能会遇到一些问题。以下是我总结的常见问题及解决方法问题现象可能原因排查与解决步骤AI没有触发技能1. 技能未正确安装到平台目录。2. AI平台不支持或未启用Agent Skills功能。1. 检查技能是否存在于正确的平台技能路径见上表。2. 确认你使用的AI平台如Claude Code是否支持SKILL.md格式。尝试让AI“列出可用技能”。3. 尝试在问题中更明确地提及“使用scholar-deep-research技能”。Phase 1搜索结果太少1. 初始问题过于狭窄或术语不标准。2. 某个学术源API暂时不可用或速率受限。1. 查看research_state.json中queries字段看AI生成了哪些搜索词。可以手动提示AI使用更宽泛的同义词或相关术语。2. 检查命令行输出是否有HTTP 429过多请求错误。考虑添加--email参数提升速率限制或稍后再试。3. 提示AI参考references/search_strategies.md使用更高级的搜索策略。Phase 3大量PDF获取失败1. 论文本身是付费墙。2. DOI解析服务paper-fetch/Unpaywall网络超时。3. PDF是扫描图片无法提取文本。1. 这是正常情况。技能会回退到仅使用摘要。报告会在“局限性”部分说明哪些论文未能获取全文。2. 检查网络连接。对于关键论文可以手动下载PDF放入项目目录然后通过修改状态文件手动关联。3. 对于扫描PDF技能会标记is_scanned: true。你需要使用OCR工具如Tesseract单独处理这些PDF然后将文本内容手动补充到对应的论文证据字段中。Phase 6自我批判后陷入循环批判检查点反复发现同一类问题如来源单一但补充搜索无法解决。1. 这可能表明该研究领域本身存在发表偏倚。此时可以手动编辑research_state.json在报告的“局限性”部分主动说明此问题。2. 可以调整自我批判的严格程度通过修改assets/prompts/self_critique.md但这需谨慎以免降低报告质量。生成的报告内容空洞1. 筛选出的论文质量不高。2. 深度阅读阶段提取的证据不充分。1. 回顾Phase 2的排序结果。检查research_state.json中论文的score_components看是否是相关性分数普遍偏低可能需要调整搜索词。2. 检查Phase 3的evidence字段。如果证据太短可能是PDF解析出了问题。可以尝试对关键论文手动提供更详细的摘要或笔记并更新到状态文件中。状态文件research_state.json损坏或混乱1. 手动编辑时格式错误。2. 多个AI实例意外同时写入。1. 该文件有对应的.lock锁文件防止并发写入。如果遇到问题先确保没有其他进程在使用。2. 最好的备份策略是在进入每个新阶段Phase前复制一份research_state.json作为备份。3. 该文件是JSON格式可以使用在线JSON校验工具检查语法。修复后可以从最近一个完好的阶段重新执行advance命令。一个高级技巧手动干预与微调scholar-deep-research的强大之处在于它的透明和可操作性。你完全可以中途介入引导研究走向。调整搜索在Phase 1之后如果你觉得搜索方向有偏差可以直接在research_state.json的queries列表里添加新的搜索查询字符串然后重新运行Phase 1的脚本或让AI去做。手动增删论文在papers列表里你可以手动添加一篇AI遗漏的关键论文的元数据DOI、标题等或者将一篇不相关的论文标记为selected: false。修改排序权重在Phase 2之前直接修改ranking_weights对象可以完全改变论文的排名优先级。 记住这个技能是增强你的研究能力而不是完全取代你。把它看作一个极其高效、严谨且听话的研究助理而你始终是把握方向的导师。