企业官网建设流程全解析

free-claude-code 是一个把 Claude Code 的 API 请求免费路由到 NVIDIA NIM、OpenRouter 或 LM Studio 的轻量代理项目，支持终端、VSCode 插件和 Discord 三种使用方式。想给它贡献代码却不知从何下手？本文带你从零搭建开发环境，吃透pytest 测试规范与CI 检查流程，让你的第一个 PR 一次通过。

项目为什么适合新手贡献

在写第一行代码之前，先了解这个项目的特点——它对新人非常友好：

贡献方向的完整说明见 README.md 的 Contributing 部分。

开发环境一键搭建：三步就绪

环境搭建只依赖一个工具：uv（astral 出品的 Python 包与虚拟环境管理器）。

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/fre/free-claude-code cd free-claude-code

第 2 步：同步依赖（自动安装 Python 3.14 与全部 dev 依赖）

uv sync

项目要求Python ≥ 3.14（见 pyproject.toml），uv会根据 .python-version 自动处理，无需手动装 Python。

第 3 步：跑一遍测试验证环境

uv run pytest

看到一片绿（PASSED）就说明环境就绪。项目所有命令都通过uv run执行，这是 CLAUDE.md 中的硬性约定——不要用全局python命令。

上面就是本项目运行后的效果：Claude Code 无需 Anthropic API Key 即可工作

项目结构快速导航

动手前花两分钟熟悉目录，修改代码时能少走弯路：

free-claude-code/ ├── server.py # 服务入口 ├── api/ # FastAPI 路由、请求检测、优化处理器 ├── providers/ # 各家模型 Provider（NIM / OpenRouter / LM Studio） │ └── common/ # 共享工具：SSE 构建器、消息转换器、解析器 ├── messaging/ # Discord / Telegram 机器人、会话管理 ├── config/ # 配置与日志 ├── cli/ # CLI 会话与进程管理 └── tests/ # Pytest 测试套件（与源码目录一一对应）

两个高频文件值得先看：

• config/settings.py：全部配置项的集中定义，环境变量的"说明书"（.env.example 也同步了这些变量）
• providers/base.py：所有 Provider 的抽象基类，写新 Provider 时从这里继承

测试规范详解：pytest + conftest 夹具

测试如何组织

测试目录与源码目录一一对应，例如：

• tests/providers/ → 测试providers/下的模型适配与消息转换
• tests/api/ → 测试 API 路由与请求优化逻辑
• tests/messaging/ → 测试 Discord/Telegram 平台与树状会话

conftest.py：测试的"公共工具箱"

tests/conftest.py 定义了全套可复用夹具（fixtures），写新测试时优先复用而不是重复造轮子：

两个值得学习的细节：

1. 异步测试：项目使用pytest-asyncio，测试异步函数时直接async def即可
2. 日志断言：_propagate_loguru_to_caplog夹具把 loguru 日志桥接到 pytest 的caplog，你可以断言日志输出

写测试的三条铁律

来自 CLAUDE.md 的明确要求：

• ✅ 新功能必须补测试，包括边界情况，然后运行uv run pytest
• ✅ 测试必须不依赖真实 API Key（conftest 已注入test_key）
• ❌ 禁止用# type: ignore或# ty: ignore掩盖类型问题——必须修复根源

CI 流程全解：5 道关卡逐一拆解

CI 配置在 .github/workflows/tests.yml，触发条件很简单：推送到main/master分支，或提交 PR 时自动运行（见 tests.yml）。

任何一道关卡失败都会阻止合并，本地先跑一遍是最快的调试方式：

💡小技巧：本地执行顺序与 CI 完全一致，建议直接按此顺序执行——先ruff format自动修复格式，再ruff check，然后ty check，最后pytest。这套顺序同样写在 README.md 的 Development 部分。

几个容易踩的坑：

• 行宽 88：ruff 的line-length设为 88（pyproject.toml），超长行交给ruff format自动处理
• 引号风格：统一双引号quote-style = "double"
• CI 超时 15 分钟：测试跑得异常慢时要留意，避免阻塞 CI

贡献四步走：从分支到 PR

完整流程如下，每一步都有对应检查点：

1. 建分支：git checkout -b my-feature，分支名用短横线小写（如add-groq-provider）
2. 写代码 + 补测试：改动尽量小而聚焦；新逻辑在 tests/ 对应子目录补测试
3. 本地全绿：按 CI 顺序执行uv run ruff format && uv run ruff check && uv run ty check && uv run pytest
4. 提交 PR：描述中说明 [改动的文件]、[修改的逻辑]、[验证方式] 与 [剩余风险]——这是 CLAUDE.md 总结标准的要求

值得优先做的贡献方向

架构层面的原则（共享逻辑下沉到providers/common/、避免硬编码、封装优于直接属性赋值等）都写在 CLAUDE.md，动手前读一遍能避免返工。

常见问题 FAQ

Q：本地测试通过但 CI 失败，为什么？最常见原因是漏跑了ruff format（CI 用--check模式只检查不修改），或代码中出现了# type: ignore注释。按 CI 的 5 道关卡顺序在本地复现一次即可定位。

Q：需要配置 API Key 才能开发吗？不需要。conftest 会注入测试用的假 key（test_key）并屏蔽.env文件，所有测试离线运行。

Q：语音转写相关的依赖很大，必须安装吗？不用。语音功能是可选依赖组（voice/voice_local，见 pyproject.toml），普通开发uv sync默认不包含它们。

写在最后

参与 free-claude-code 开发的核心心法就一句话：先读 CLAUDE.md，按 CI 的 5 道关卡在本地跑绿，再提 PR。项目结构清晰、测试夹具齐全、规范文档明确，新手完全可以在一天内从克隆仓库走到提交第一个 PR。祝你顺利，期待你的第一个贡献！ 🎉