★ FEATURED ARTICLE 【免费下载链接】free-claude-codeUse Claude Code for free in the terminal, VSCode extension, or via Discord项目地址https://gitcode.com/gh_mirrors/fre/free-claude-code点击查看免费下载free-claude-code 是一个把 Claude Code 的 API 请求免费路由到 NVIDIA NIM、OpenRouter 或 LM Studio 的轻量代理项目支持终端、VSCode 插件和 Discord 三种使用方式。想给它贡献代码却不知从何下手本文带你从零搭建开发环境吃透pytest 测试规范与CI 检查流程让你的第一个 PR 一次通过。项目为什么适合新手贡献在写第一行代码之前先了解这个项目的特点——它对新人非常友好优势说明 结构清晰每个模块职责单一api/负责路由与请求检测providers/负责各家模型适配messaging/负责 Discord/Telegram 机器人 测试覆盖完整tests/ 目录下有 50 个测试文件几乎每个模块都有对应测试照着写即可 规范文档齐全CLAUDE.md 明确了编码环境与检查顺序AGENTS.md 与它内容一致 扩展点明确官方鼓励的贡献方向新增 LLM Provider、新增消息平台、提升测试覆盖率贡献方向的完整说明见 README.md 的 Contributing 部分。开发环境一键搭建三步就绪环境搭建只依赖一个工具uvastral 出品的 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.tomluv会根据 .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/ # 各家模型 ProviderNIM / 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写新测试时优先复用而不是重复造轮子夹具用途provider_config/nim_provider/open_router_provider/lmstudio_provider三家 Provider 的现成测试实例mock_cli_session/mock_cli_manager模拟 CLI 会话避免真实启动 Claudemock_platform模拟消息平台不真正调用 Discord/Telegram APIincoming_message_factory工厂函数快速构造入站消息对象_isolate_from_dotenvautouse自动生效测试中屏蔽.env文件干扰保证隔离性两个值得学习的细节异步测试项目使用pytest-asyncio测试异步函数时直接async def即可日志断言_propagate_loguru_to_caplog夹具把 loguru 日志桥接到 pytest 的caplog你可以断言日志输出写测试的三条铁律来自 CLAUDE.md 的明确要求✅ 新功能必须补测试包括边界情况然后运行uv run pytest✅ 测试必须不依赖真实 API Keyconftest 已注入test_key❌ 禁止用# type: ignore或# ty: ignore掩盖类型问题——必须修复根源CI 流程全解5 道关卡逐一拆解CI 配置在 .github/workflows/tests.yml触发条件很简单推送到main/master分支或提交 PR 时自动运行见 tests.yml。任何一道关卡失败都会阻止合并本地先跑一遍是最快的调试方式顺序关卡CI 中的命令作用1️⃣禁止类型压制全仓库 grep# type: ignore出现即直接失败tests.yml2️⃣格式检查uv run ruff format --check检查代码格式是否符合规范3️⃣风格检查uv run ruff check检查未用导入、常见 bug 等规则见 pyproject.toml4️⃣类型检查uv run ty check静态类型检查目标 Python 3.145️⃣运行测试uv run pytest -v --tbshort跑完整测试套件小技巧本地执行顺序与 CI 完全一致建议直接按此顺序执行——先ruff format自动修复格式再ruff check然后ty check最后pytest。这套顺序同样写在 README.md 的 Development 部分。几个容易踩的坑行宽 88ruff 的line-length设为 88pyproject.toml超长行交给ruff format自动处理引号风格统一双引号quote-style doubleCI 超时 15 分钟测试跑得异常慢时要留意避免阻塞 CI贡献四步走从分支到 PR完整流程如下每一步都有对应检查点建分支git checkout -b my-feature分支名用短横线小写如add-groq-provider写代码 补测试改动尽量小而聚焦新逻辑在 tests/ 对应子目录补测试本地全绿按 CI 顺序执行uv run ruff format uv run ruff check uv run ty check uv run pytest提交 PR描述中说明 [改动的文件]、[修改的逻辑]、[验证方式] 与 [剩余风险]——这是 CLAUDE.md 总结标准的要求值得优先做的贡献方向方向说明参考位置➕ 新增 Provider继承OpenAICompatibleProvider适配 Groq、Together AI 等 OpenAI 兼容接口providers/openai_compat.py➕ 新增消息平台实现MessagingPlatform抽象类即可接入 Slack 等平台messaging/platforms/base.py 提升测试覆盖为尚未覆盖的边界分支补测试用例tests/conftest.py架构层面的原则共享逻辑下沉到providers/common/、避免硬编码、封装优于直接属性赋值等都写在 CLAUDE.md动手前读一遍能避免返工。常见问题 FAQQ本地测试通过但 CI 失败为什么最常见原因是漏跑了ruff formatCI 用--check模式只检查不修改或代码中出现了# type: ignore注释。按 CI 的 5 道关卡顺序在本地复现一次即可定位。Q需要配置 API Key 才能开发吗不需要。conftest 会注入测试用的假 keytest_key并屏蔽.env文件所有测试离线运行。Q语音转写相关的依赖很大必须安装吗不用。语音功能是可选依赖组voice/voice_local见 pyproject.toml普通开发uv sync默认不包含它们。写在最后参与 free-claude-code 开发的核心心法就一句话先读 CLAUDE.md按 CI 的 5 道关卡在本地跑绿再提 PR。项目结构清晰、测试夹具齐全、规范文档明确新手完全可以在一天内从克隆仓库走到提交第一个 PR。祝你顺利期待你的第一个贡献 赞分享【免费下载链接】free-claude-codeUse Claude Code for free in the terminal, VSCode extension, or via Discord项目地址https://gitcode.com/gh_mirrors/fre/free-claude-code点击查看免费下载相关推荐如何参与Drawbridge开发项目结构、代码规范、测试流程与贡献指南如何参与Drawbridge开发项目结构、代码规范、测试流程与贡献指南 Drawbridge 是一款面向 Claude Code 和 Cursor 的浏览器可如何参与Sunnify开发测试体系、代码规范与PR工作流完整教程如何参与Sunnify开发测试体系、代码规范与PR工作流完整教程 想为 Sunnify 这个开源 Spotify 下载器贡献代码吗Sunnify 是一款支持Dendrite 贡献开发全指南DCO 签名、代码规范、测试与 CI 流程Dendrite 贡献开发全指南DCO 签名、代码规范、测试与 CI 流程 Dendrite 是由 Matrix.org 基金会维护、使用 Go 语言编写的第后端即时通讯上一篇推荐项目iOS平台的实时人体姿态估计 - Pose Estimation for Core ML下一篇【亲测免费】 RFID Tools全面掌控RFID世界的开源神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
