贡献指南

感谢您考虑为诺贝尔奖知识图谱项目做出贡献！

开发环境搭建

前置条件

• Python >= 3.12
• uv 包管理工具
• OpenAI API 密钥（用于 LLM 功能）

搭建步骤

git clone https://github.com/example/nobel-kg.git
cd nobel-kg
uv sync
cp .env.example .env  # 配置您的 API 密钥

项目结构

src/
├── __init__.py           # 共享配置加载器
├── data_loader.py        # 阶段 1：数据加载
├── content_enricher.py   # 阶段 1.5：内容富化
├── openalex_enricher.py  # 阶段 2a：OpenAlex 富化
├── concept_extractor.py  # 阶段 2b：LLM 抽取
├── graph_builder.py      # 阶段 3+4：图谱构建
├── visualize.py          # 阶段 5：可视化
└── insight_analyzer.py   # 阶段 6：分析

编码规范

代码风格

• 遵循 PEP 8 代码风格指南
• 使用类型注解定义函数签名
• 为所有公共函数添加 docstring
• 使用 Polars 进行 DataFrame 操作（优先于 Pandas）

模块模式

每个模块遵循一致的模式：

"""模块描述。"""

from src import load_config, ROOT_DIR

def process_data(...):
    """处理描述。"""
    ...

def run():
    """该阶段的入口点。"""
    cfg = load_config()
    ...

if __name__ == "__main__":
    run()

API 缓存

所有外部 API 调用必须被缓存：

cache_path = Path(cache_dir) / f"{sanitized_id}.json"
if cache_path.exists():
    return json.loads(cache_path.read_text())

# ... 执行 API 调用 ...

cache_path.write_text(json.dumps(result))

添加新的流水线阶段

1. 按照上述模块模式创建 src/new_module.py
2. 在 main.py 中适当位置添加该阶段
3. 如需新配置，更新 config/settings.yaml
4. 在 docs/src/en/pipeline/ 和 docs/src/zh/pipeline/ 中添加文档
5. 在 docs/src/en/api/ 和 docs/src/zh/api/ 中添加 API 参考

文档

构建文档

cd docs
pip install -r requirements.txt
mkdocs serve     # 本地预览 http://localhost:8000
mkdocs build     # 构建静态站点到 docs/site/

添加文档

• 英文文档放在 docs/src/en/
• 中文文档放在 docs/src/zh/
• 两个版本应保持相同的结构和内容

报告问题

报告问题时，请包含：

1. 您尝试做什么
2. 实际发生了什么
3. 复现步骤
4. Python 版本和操作系统
5. 相关日志输出