Skip to content

RipeMangoBox/BITE

BranchesTags

Repository files navigation

BITE logo

BITE

Bibliographic Intelligence for Thought Emergence

让每一个 idea 都有 出处，让每一个判断都有 锚点。

中文 | English

Semi-automated Markdown first Knowledge base MinerU powered Claude Code compatible Codex CLI compatible Obsidian optional MIT license

🔥 BITE 社区交流 | 💬 微信交流 / BITE微信交流群

🔥 News：BITE 的公开证据层已发布至 HuggingFace dataset PaperBite-Assets，覆盖 L0-L3 的结构化论文资产（Markdown 分析笔记 + 图表 + manifests）。可直接用 scripts/sync_assets_from_hf.py 增量同步；如果你本身做 AI 相关研究，建议在此之上构建自己的 evidence vault。

🔥 News：正式本地分析链已更新为 v06 四段式 note：集成 MinerU 解析/复用、chunk anchor 抽取、主分析 JSON、分段写作、图表 slot 选择和结构校验。默认最多保留 6 个核心图表，减少冗余贴图和单篇分析成本；批量队列在 API quota 允许时推荐 --jobs 50 并行。

BITE 核心思想示意图

BITE 是什么？ BITE 是一个本地优先的研究工作流框架，面向研究 Agent 的结构化论文分析与 Research Memory，帮助你将论文分析转化为结构化笔记，并构建可复用的个人 research memory。

适合谁？ 适合想构建论文知识库、证据驱动研究 workflow、或让 agent 参与文献理解与 idea 生成的研究者。

🧠 先构建知识，再让 Agent 行动。 大多数 AI 科研工具关注“帮你跑实验、写论文”。 BITE 更关注上游问题：你的 agent 在做决策时，手里有没有足够的、结构化的、可检索的论文证据？

🧩 把结构化论文分析沉淀为可复用的 research memory。 BITE 把论文 PDF 和论文列表组织成层次化的本地资产：原始文献、单点分析、领域知识面构建、跨领域资产沉淀与碰撞，从而支持智能的涌现与溯源。

🪶 本地优先，低锁定。 默认 workflow 完全基于本地文件： PDF、Markdown、JSONL 索引和 idea notes 都位于 obsidian-vault/ 下。正常使用不需要数据库、后端服务或在线部署。

💡 BITE 是一种方法论和本地知识工作流，不是封闭平台。真正有价值的是你持续积累的多级科研资产。

🧠 核心思想

BITE 的核心不在于“先产出一个看起来合理的 idea”，而在于先沉淀结构化证据， 再让研究方向从证据中自然涌现，最后用审稿视角做压力测试，避免在证据薄弱时过早推进实验。

🗂️ 资产层级

BITE 资产层级示意图

本图展示 BITE 的六层资产结构：L0-L3 由 PaperBite 驱动，完成知识积累与建库；L4 是观点涌现层；L5 是实验验证层。

下表按自底向上顺序对应图片中的六层结构：

层级 产物 作用
L0 论文 PDF 保留原始文献
L1 单篇论文分析 提取 main idea、core design、experiment proofs
L2 单领域 Research Vault 支持领域内归纳、演绎与对比
L3 多领域 Research Vault 支持跨领域启发与方向涌现
L4 Idea Vault 涌现层
L5 Experiment Vault 验证层

🎯 工作方式

给 BITE 一个研究方向，它可以帮你把知识库逐步建起来：

collect candidate papers / import local PDFs
  -> download when needed
  -> integrated analysis chain
     (MinerU parse/reuse -> structured analysis -> vault export)
  -> optional index refresh
  -> query / ideate / review / export

你可以用四种常见模式使用它：

模式 用途 常用入口
Build 收集候选论文、下载或导入 PDF、运行集成分析链并按需刷新索引 research-workflow
Query 按主题、任务、方法、venue、年份、标题或技术标签检索论文 papers-query-knowledge-base
Decision 在选择 baseline、修改方案或写 related work 前对比方法 papers-query-knowledge-base
Idea 基于本地知识库生成、收敛并压力测试研究方向 research-brainstorm-from-kb, idea-focus-coach, reviewer-stress-test

🛠️ 环境配置

📦 1. 创建 conda 环境

git clone https://github.com/<your-username>/BITE.git
cd BITE
conda env create -f environment/environment.yml
conda activate bite

🔐 2. 配置模型和解析工具

需要设置模型密钥、模型名或 parser override 时，在仓库根目录创建自己的 .env， 并参考 environment/.env.example。

📄 3. 安装或配置 MinerU

MinerU 是 BITE 本地分析链里的 PDF 解析组件。现在默认不需要先单独跑一轮 MinerU 批处理；scripts/run_local_paper_analysis.py 可以在分析时调用 MinerU， 也可以复用已有解析结果。最小验证方式：mineru --help 能运行，或在 .env 中设置 MINERU_CLI_PATH。

🧭 使用方式

🧠 1. 从 workflow skill 开始

/research-workflow
我想从 PDF 构建 controllable motion generation 的论文知识库。
请告诉我下一步应该做什么，以及会生成哪些结果。

📥 2. 可选：同步公开证据层

如需直接使用 BITE 已沉淀的结构化论文资产，从 HuggingFace 按需同步：

pip install huggingface_hub

# 只下载论文分析笔记（analysis/ + index/，~43 MB）
python scripts/sync_assets_from_hf.py --mode text

# 只下载图表资产（assets/，~1.8 GB）
python scripts/sync_assets_from_hf.py --mode assets

# 下载全部（默认）
python scripts/sync_assets_from_hf.py --mode all --dry-run   # 先看看需要多少
python scripts/sync_assets_from_hf.py                        # 正式下载

# 如果你想用 PaperBite 的公开清单替换本地清单，显式同步 paper_list.csv
python scripts/sync_assets_from_hf.py --mode paper-list --overwrite-paper-list

PaperBite shard 内部路径是 vault-relative 的 analysis/、index/ 和 assets/，默认会解压到 obsidian-vault/ 下，适合直接作为 BITE 的公开 evidence vault 使用。paper_list.csv 需要显式同步；默认不会覆盖你自己的本地 清单。当前公开资产不包含完整原始 PDF corpus，paperPDFs/ 仍按需本地下载或 导入。

如果你维护的是课题组内部私有 Hugging Face dataset，也可以使用同一个同步脚本。 脚本会自动识别公开 PaperBite shard 布局、私有 shard 布局和私有 direct 布局：

# 需要先 hf auth login，并且账号有私有 dataset 访问权限
python scripts/sync_assets_from_hf.py \
  --repo-id <org-or-user>/<private-dataset> \
  --repo-type dataset \
  --layout auto \
  --mode all \
  --sync-paper-list \
  --overwrite-paper-list \
  --git-skip-worktree

建议私有仓库同时包含 direct 文件和 shard manifests：direct 文件便于网页端 浏览单篇 note，shards 便于新成员首次全量同步。维护者上传时可使用：

python scripts/upload_bite_hf_private.py \
  --repo-id <org-or-user>/<private-dataset> \
  --with-shards

私有 direct 文件应包含 vault-relative 的 analysis/、assets/ 和 paper_list.csv。同步脚本会忽略 HF 或本地 .cache 元数据；当 manifests 存在时，--layout auto 会优先走 shard 下载，避免逐个拉取数万个小文件。 如果你把私有 evidence 同步到已跟踪公开 vault 的 main clone 中，建议保留 --git-skip-worktree，这样本地私有笔记覆盖不会污染日常 git status。

⚙️ 3. 运行集成本地分析链

单篇论文可以直接从 PDF 进入完整链路：MinerU 解析或复用、分块证据抽取、 主分析 JSON、章节写作、图表放置、vault 导出和结构校验。已有 MinerU 输出时 再传 --mineru-output 或 --mineru-output-root 复用即可。

python3 scripts/run_local_paper_analysis.py \
  --pdf "obsidian-vault/paperPDFs/<Venue_Year>/<Paper>.pdf" \
  --conf-year "<Venue_Year>" \
  --export-vault

当前默认输出为四个正文段落：概要、核心方法与创新机理、 实验与关键发现、定位与知识库关联。--max-note-images 6 是默认值， 用于保留任务定义、核心 pipeline、关键结果/消融等必要图表，避免把补充表格 机械贴入顶层 note。

批量分析时，队列 runner 会逐行调用同一条正式分析链。对已经下载 PDF 且 模型/API quota 足够的队列，可以用 --jobs 50 并行降低总耗时：

python3 scripts/run_paper_list_analysis.py \
  --source obsidian-vault/paper_list.csv \
  --state Downloaded \
  --jobs 50 \
  --export-vault \
  --max-note-images 6

如果遇到 provider 限流、MinerU I/O 压力或本机内存不足，先降到 --jobs 10 或 --jobs 20，再按失败日志恢复运行。脚本默认 --resume，已完成或已存在 的 note 会跳过。

📚 延伸简介

📖 使用示例

从零构建一个主题知识库 
/research-workflow
我想构建 text-driven reactive motion generation 的论文知识库。
请从候选论文收集开始，告诉我每个阶段应该使用哪个 skill。
从 GitHub 论文列表收集候选论文 
/papers-collect-from-github-repo
从这个 GitHub repository 收集 controllable human motion generation 相关论文：<URL>
只保留 diffusion、controllability、real-time generation 或 long-form motion 相关条目。
输出适合后续下载 workflow 使用的候选列表。
运行正式本地分析链

默认从 PDF 直接运行完整链路：

python3 scripts/run_local_paper_analysis.py \
  --pdf "obsidian-vault/paperPDFs/<Venue_Year>/<Paper>.pdf" \
  --conf-year "<Venue_Year>" \
  --export-vault \
  --reasoning-effort max \
  --part-thinking disabled \
  --writer-thinking disabled

已有 MinerU 输出时再复用解析结果：

python3 scripts/run_local_paper_analysis.py \
  --mineru-output "<mineru_output_dir>" \
  --paper-pdf "obsidian-vault/paperPDFs/<Venue_Year>/<Paper>.pdf" \
  --conf-year "<Venue_Year>" \
  --export-vault

批量分析时，队列 runner 会逐行调用同一条正式分析链：

python3 scripts/run_paper_list_analysis.py \
  --source obsidian-vault/paper_list.csv \
  --state Downloaded \
  --jobs 50 \
  --export-vault

✨ 核心能力

需求 Skill
判断下一步 pipeline research-workflow
从网页收集候选论文 papers-collect-from-web
从 GitHub 论文列表收集候选论文 papers-collect-from-github-repo
根据候选列表下载 PDF papers-download-from-list
生成结构化单篇论文分析 scripts/run_local_paper_analysis.py
重建本地索引 papers-build-index
基于本地笔记查询 / 对比论文 papers-query-knowledge-base
基于知识库生成研究想法 research-brainstorm-from-kb
把想法收敛为可执行计划 idea-focus-coach
做 reviewer 风格压力测试 reviewer-stress-test
导出可分享 Markdown notes-export-share-version

完整 skill 地图见 .claude/skills/README.md。

🤖 Agent 兼容

BITE 有意保持朴素：文件夹、Markdown、JSONL、CSV 和 SKILL.md。因此同一 份 research memory 可以被多个 Agent 共享：

  • Claude Code / Cursor 可以直接读取 .claude/skills。
  • Codex CLI 可以用 scripts/setup_shared_skills.py 生成本地 alias。
  • 其他能读取文件的 Agent 可以直接读取 obsidian-vault/index/index.jsonl 和 obsidian-vault/analysis/。

补充配置

Codex CLI compatibility

Claude Code / Cursor 不需要这一步；Codex CLI 需要。

python3 scripts/setup_shared_skills.py
python3 scripts/setup_shared_skills.py --check
Obsidian setup
  • Obsidian 是可选但推荐的可视化层。
  • 如果需要 graph view、backlinks 和人工浏览，可以把 obsidian-vault/ 作为 Obsidian vault 打开。
  • 不要把 Obsidian 页面当作独立 source of truth。

Citation

@misc{lin2026bite,
  title        = {{BITE}: Bibliographic Intelligence for Thought Emergence},
  author       = {Jingzhong Lin and Ziheng Huang},
  year         = {2026},
  howpublished = {\url{https://github.com/RipeMangoBox/BITE}},
  note         = {GitHub repository}
}

License

MIT

About

Semi-automated research assistant and local knowledge base for paper analysis, ideation, coding, experiments, writing, and publication workflows.

Topics

knowledge-base obsidian research-assistant paper-analysis academic-research research-automation claude-code codex-cli research-workflow semi-automated-research

Resources

Readme

License

MIT license
Activity

Stars

59 stars

Watchers

1 watching

Forks

13 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages