Hyperresearch源码阅读指南1.1万行Python核心模块从哪读起【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearchHyperresearch 是一个 Agent 驱动的深度研究知识库AI 代理负责采集、检索并综合网络研究内容最终沉淀为可持久化、可全文搜索的个人研究 Wiki。面对它约 2.8 万行的 Python 代码其中core/目录就超过 1.1 万行很多新手会问源码阅读应该从哪读起这份源码阅读指南会给你一条从薄壳到深水区的完整路径帮你 30 分钟建立全局认知。项目全景9 个目录撑起一套深度研究流水线先建立一张地图。项目源码位于src/hyperresearch/下各目录职责清晰目录代码规模一句话职责core/约 1.16 万行核心领域Vault 数据模型、SQLite 索引、同步、OA 全文恢复、运行清单cli/约 0.98 万行Typer 命令行薄壳30 个子命令scholar/约 2600 行8 个学术源 ProviderOpenAlex、Crossref、CORE 等web/约 2000 行网页抓取 Providercrawl4ai、exa、tavily 等search/约 300 行SQLite FTS5 全文搜索引擎serve//mcp/各约 400–800 行本地 Web UI 与 MCP 服务器skills/16 个 Markdown16 步研究流水线的步骤技能文件这套架构最棒的一点是分层极其克制cli/只负责解析参数真正的业务逻辑全部收敛在core/与各能力目录里。所以读源码的正确姿势就是沿着命令 → 核心 → 深水区的顺序往下钻。7 步阅读路径从薄壳到深水区 先拿到代码git clone https://gitcode.com/GitHub_Trending/hy/hyperresearch第 1 步从 pyproject.toml 定位入口点一切从 pyproject.toml 开始。两个关键信息[project.scripts]声明了命令入口hyperresearch和hpr都指向hyperresearch.cli:app核心依赖只有 typer、rich、pydantic、httpx 等少数几个数据库用的是标准库 SQLite——没有重型 ORM这是能快速读懂它的重要原因。第 2 步cli/ 只是薄壳扫一眼就够打开 src/hyperresearch/cli/init.py你会看到 Typer 应用在这里把fetch、search、note、run等子命令注册进来。挑 main.pyinit/status/sync读一遍你就掌握了命令如何调用 core的固定模式解析参数 → 打开 Vault → 调 core 函数 → 格式化输出。这个模式在所有 CLI 文件里重复出现所以 30 多个命令文件扫读即可不必逐行精读。第 3 步core/vault.py——Markdown 是真相的数据模型这是整个项目的地基src/hyperresearch/core/vault.py。Vault类管理研究库的根目录布局research/notes/、research/runs/等与配置读取。配套读两个小文件就能理解设计哲学db.pySQLite 表结构注意注释里的Markdown is truth, SQLite is cache——笔记本体是带 YAML frontmatter 的纯 Markdown数据库只是可随时重建的缓存frontmatter.py仅 55 行 note.pyfrontmatter 的解析/序列化与笔记读写。第 4 步sync.py——索引是如何长出来的读完数据模型下一个问题SQLite 索引和 Markdown 文件如何保持一致答案在 src/hyperresearch/core/sync.py。重点看两个函数compute_sync_plan对比 mtime/哈希算出变更计划和execute_sync把笔记 upsert 进库并重建链接。理解了它你就理解了hyperresearch sync和watch命令的全部行为。第 5 步search/ 与 web/——检索层与抓取层两条数据进出通道值得一读进src/hyperresearch/web/base.py 定义了 Web Provider 协议src/hyperresearch/core/fetcher.py 的fetch_and_save是抓取落库的统一入口出src/hyperresearch/search/fts.py 展示了如何用 SQLite FTS5 做全文检索——包括把gpt4o拆成gpt 4 o这类贴心的查询预处理篇幅不长非常适合精读。学术检索同理src/hyperresearch/scholar/registry.py 用注册表统一管理 8 个 Providerproviders/下每个文件对应一个学术源结构一目了然。第 6 步runs.py 与 oa.py——两个最厚的核心模块到了含金量最高的部分src/hyperresearch/core/runs.py680 行每次研究运行的 manifest 管理——init_run、set_step、resume_position、verify_run。崩溃后可从断点精确恢复这一招牌能力全靠这一个文件src/hyperresearch/core/oa.py887 行付费墙论文的开源全文恢复。当抓取只拿到摘要时它依次询问 Unpaywall、Europe PMC、CORE 寻找合法全文副本且所有替换都会四处披露。逻辑链条长而严谨是锻炼阅读耐心的好材料。第 7 步深水区——hooks.py、profiles 与 16 步流水线最后才是真正的大件src/hyperresearch/core/hooks.py4200 行全项目最大文件把 16 个步骤技能和一批子代理fetcher、critic、patcher……安装到 Claude Code 的.claude/目录。建议先读它生成的产物再回头读源码——产物就是 src/hyperresearch/skills/ 里的 16 个 Markdown 步骤文件和 tests/fixtures/golden_prompts/agents/ 里的代理提示词全是纯文字非常好读profiles.py render.pylight / full / premier档位gear如何渲染进步骤技能的模板变量安全设计彩蛋untrusted.py62 行——网页正文会被包进untrusted-source围栏防止网页里的文字反过来指挥你的 AI 代理篇幅小、思想含量高强烈推荐一读。新手阅读技巧3 个小方法从小文件建立信心frontmatter.py55 行→untrusted.py62 行→quality.py75 行这三个文件各自独立、注释清晰读通它们你就掌握了项目的编码风格。源码与测试对读tests/ 的目录结构与源码一一对应如 test_sync.py、test_oa_recovery.py不确定某函数行为时测试用例就是最可靠的活文档。看产出理解意图读 docs/roadmap-2.0/README.md 了解各阶段的规划动机再对照 example-reports/rl-exploration-trajectory-planning.md 看流水线最终产出的报告长什么样代码里的每个模块为什么存在就都讲得通了。按这条路径走完你大约用 2–3 小时就能从1.1 万行不知道从哪读起进阶到能独立改core/里任何一个模块的水平。【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考