贡献指南

开发环境搭建

你需要 Python 3.10+、Git、以及一个能跑 Docker 的环境（用来启动 PostgreSQL 和 Redis）。

# 1. Fork 仓库，然后 clone 你的 fork
git clone https://github.com/你的用户名/muyuan-ai.git
cd muyuan-ai

# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. 安装开发依赖
pip install -e ".[dev]"

# 4. 启动依赖服务
docker compose up -d postgres redis

# 5. 初始化数据库
alembic upgrade head

# 6. 跑测试，确认环境没问题
pytest -v

测试全部通过就说明环境搭好了。如果有测试失败，大概率是 Docker 服务没起来——检查一下 docker compose ps。

代码规范

我们用工具来保证代码风格一致，不靠人肉 review 格式问题。

格式化

用 Black，行宽 88 字符（Black 默认值）。提交前跑一下：

black .
# 或者只检查不修改
black --check .

Type Hints

所有公开函数必须有 type hints。内部函数建议加但不强制。我们用 mypy --strict 做静态检查。

# 好
def fetch_articles(source: str, limit: int = 100) -> list[Article]:
    ...

# 不好
def fetch_articles(source, limit=100):
    ...

Docstring

用 Google 风格。类和公开方法必须有 docstring。写清楚这个函数做什么、参数是什么、返回什么。不需要写废话。

def analyze_sentiment(text: str, model: str = "v2") -> float:
    """对文本做情感分析，返回 -1 到 1 的分数。

    Args:
        text: 待分析的文本，至少 10 个字符。
        model: 模型版本，"v1" 用词典方法，"v2" 用 BERT。

    Returns:
        情感分数。负数表示负面，正数表示正面，0 附近表示中性。

    Raises:
        ValueError: text 长度不足 10 个字符。
    """

Import 排序

用 isort，配置和 Black 兼容：

isort .

Lint

用 ruff。配置在 pyproject.toml 里，不需要额外设置。

ruff check .
ruff check --fix .  # 自动修复

PR 流程

分支命名

• 新功能：feat/简短描述，比如 feat/wechat-collector
• 修 bug：fix/简短描述，比如 fix/redis-connection-leak
• 文档：docs/简短描述
• 重构：refactor/简短描述

Commit Message

遵循 Conventional Commits：

feat: 新增微信公众号数据源
fix: 修复 Redis 连接池泄漏
docs: 更新 API 参考文档
refactor: 重构分析管道的 Stage 调度逻辑
test: 补充 CrossValidator 的边界测试
chore: 升级 httpx 到 0.27.0

PR 要求

• PR 描述里写清楚改了什么、为什么改
• 新功能要有测试。不需要 100% 覆盖，但核心逻辑要覆盖到
• CI 必须全绿（lint + test + type check）
• 如果改了公开 API，更新对应的文档
• 一个 PR 做一件事。如果你同时修了 bug 和加了新功能，拆成两个 PR

我们通常在 1-3 个工作日内 review。如果超过一周没回复，在 PR 里 @ 一下 maintainer。

Issue 模板

提 Issue 时请选择对应的模板：

• Bug Report — 描述问题、复现步骤、期望行为、实际行为、环境信息（Python 版本、OS、muyuan-ai 版本）
• Feature Request — 描述你想要什么功能、为什么需要、你设想的实现方式（可选）
• Data Source Request — 想接入的数据源名称、URL、数据格式、是否需要 API key

标了 good first issue 的 Issue 适合新手。我们会在 Issue 里提供足够的上下文和指引。

行为准则

简单说：

• 尊重每个参与者，不管技术水平高低
• 就事论事，不搞人身攻击
• 接受建设性的批评
• 不发垃圾信息、不做广告
• 遇到不当行为，发邮件到 conduct@muyuan.ai

完整版行为准则基于 Contributor Covenant v2.1，见仓库根目录的 CODE_OF_CONDUCT.md。

违反行为准则的参与者会被警告或移除。我们希望这个社区是友好的，但友好不意味着容忍恶意行为。