企业官网建设流程全解析

Thunderbolt社区参与指南：如何向Mozilla资助的开源AI客户端提交PR

【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt

Thunderbolt是一个由 Mozilla 资助（grant）的开源、跨平台 AI 客户端：你可以自由选择模型、完全掌控自己的数据，并彻底摆脱供应商锁定（"AI You Control"）。它支持 Web、macOS、Windows、Linux、iOS 与 Android，可以完全自托管在本地服务器上，采用 Mozilla Public License 2.0 许可证。无论你是第一次接触开源协作的新手，还是想体验一个真实生产级项目的完整 CI/CD 流程，这份指南都能帮你从克隆仓库一路走到提交第一个 PR。🚀

为什么值得参与 Thunderbolt 社区

Thunderbolt 由 Mozilla 旗下实体 MZLA Technologies 开发，通过 Mozilla 的资助计划支持（详见 docs/faq.md 中"How is Thunderbolt funded?"）。它目前正处于活跃开发期、安全审计和面向企业生产的准备阶段，官方明确表示"欢迎所有人的贡献"。

对新手来说，这个仓库有几个很友好的地方：

• 文档完备：快速上手、测试规范、架构说明一应俱全，见 docs/development/quick-start.md
• 自动化齐全：make doctor会检查你的环境并打印缺失工具的确切安装命令，大幅降低环境配置门槛
• 规范清晰：AGENTS.md 中详细写明了代码风格、React 模式与测试约定，照着做即可
• 流程可预期：PR 标题有自动化校验，CI 会自动跑类型检查、lint 和测试，反馈透明

先认识一下项目结构

在动手前花十分钟了解目录布局，能帮你快速找到要改的代码：

一键安装步骤：搭建本地开发环境

环境搭建是整个流程中最容易卡住新手的环节，而 Thunderbolt 把这件事做得很省心——一切从 Makefile 开始。

1. 克隆仓库

git clone https://gitcode.com/GitHub_Trending/thund/thunderbolt cd thunderbolt make doctor

make doctor会检查你的机器并打印缺失工具（如Bun 1.2+、Rust 工具链、Docker）的确切安装命令。

2. 安装依赖与配置

make setup # 安装前端+后端依赖，配置 agent 软链接 cp .env.example .env cp backend/.env.example backend/.env make doctor # 自动生成 BETTER_AUTH_SECRET 等密钥

你还需要至少一个 AI 提供商的 API Key（Anthropic、OpenAI 等），或使用本地 Ollama / llama.cpp 作为免费推理端点。

3. 启动服务

make up # Docker 启动 Postgres(:5433) + PowerSync(:8080) make run # 启动后端(:8000) + 前端(:1420)

打开http://localhost:1420，注册账号、发一条消息，跑通了就说明环境就绪 ✅

💡小贴士：常用命令还有make status（查看容器状态）、make down/make nuke（停止/清空容器）、make check（类型检查 + lint + 格式检查）、make format（统一格式化前后端与 Rust 代码）。完整说明见 Makefile。

读懂代码规范：动笔前先对齐

Thunderbolt 将工程规范集中写在 AGENTS.md（CLAUDE.md是其软链接），贡献前值得通读一遍。核心要点包括：

TypeScript 风格

• 永远不用any；优先type而非interface
• 优先箭头函数、const而非let、提前 return 而非深层嵌套
• 用bun代替npm，用bun test代替vitest

架构原则

• 偏向简洁优雅的解决方案，避免过度设计
• 前端数据一律软删除（设置deletedAt），不硬删除
• 网络请求使用应用内置的HttpClient，数据库迁移用bun db generate生成，不手写 SQL 迁移文件

React 纪律

• useEffect被视为"代码异味"，除非确有正当理由（DOM 事件、订阅、测量等）
• 状态逻辑抽成use[Component]State()hooks，与展示逻辑分离，便于测试

测试与质量检查：提交PR前的必经之路

提交 PR 前，确保 CI 会做的检查你本地都已通过：

⚠️新手最常见的坑：不要在仓库根目录直接运行裸的bun test——它会发现所有测试文件（包括需要真实服务的后端测试）导致卡死。一定要用带作用域的bun run test。

测试写法上，docs/development/testing.md 强调：优先依赖注入而非 mock（mock 模块会跨测试文件泄漏，是 CI 里"单独能跑、合起来就挂"的头号原因）；测试文件以<file>.test.ts放在源码旁。

如何写出能一次通过的 PR：标题与流程

PR 标题必须遵循 Conventional Commits

这是新手最容易忽略的细节。CI 中的Lint PR Title工作流（.github/workflows/lint-pr-title.yml）会严格校验 PR 标题，格式不合规会直接阻止合并：

feat: 为设置页新增导出按钮 fix(cli): 修复认证刷新后掉线的问题 chore(deps): 升级 @tauri-apps/api 到 2.11.0

允许的 type 包括：feat、fix、chore、docs、refactor、perf、test、ci、build、style。由于仓库使用 squash-merge，PR 标题就是合入main的提交信息，并直接驱动自动化 Changelog 生成——所以标题写得规范，Changelog 就漂亮。详细规则见 RELEASE.md 的 "PR Title Convention" 一节。

提交后会发生什么

打开 PR 后，CI（.github/workflows/ci.yml）会自动：

1. 检测变更文件，按 Rust / agent-core / CLI / 国际化等维度智能跳过无关构建，提速明显
2. 跑质量门禁：类型检查、lint、单元测试
3. 生成预览环境（preview-deploy.yml），方便审查者体验你的改动
4. 收集 PR 指标（pr-metrics.yml）用于复盘

负责任地参与：行为准则与安全报告

社区氛围和代码质量同样重要：

• 行为准则：CODE_OF_CONDUCT.md 要求"批评事，不批评人"、在公开渠道讨论、不修改不属于自己的 issue 标签。所有参与者同时承诺遵守 Mozilla 社区参与准则
• 安全漏洞：切勿在公开 issue 中报告！请通过仓库的私有漏洞报告表单负责任地披露，见 SECURITY.md
• 遥测隐私：项目对数据收集有完整说明，改动涉及遥测时请阅读 TELEMETRY.md

贡献渠道清单：从Issue到PR

1. 发现问题 / 有想法？先提交一个 issue，描述清楚复现步骤——很多社区贡献正是从好 issue 开始的
2. 认领开发：浏览 docs/development/quick-start.md 跑通本地环境，从小而完整的改动入手（文案、文档、单个 bug 修复都是好起点）
3. 提交 PR：遵循 Conventional Commits 标题，附上改动说明与（如适用）截图
4. 持续跟进：关注 CI 反馈，及时响应审查意见，保持 PR 更新

写在最后

参与 Thunderbolt 的贡献流程，本质上就是一次真实的现代软件工程实战：Makefile 驱动的环境自检、Conventional Commits 治理的提交历史、按文件维度优化的 CI、预览环境部署，以及清晰的架构文档。第一次 PR 被拒或被要求修改都很正常——这正是学习最快的时候。从 docs/development/quick-start.md 开始，跑通本地环境，然后选一个小 issue 动手吧。你的第一个 PR，可能就从make run之后看到的那次改动开始。⚡

核心文档速查：开发快速上手 · 测试指南 · 发布与PR规范 · 架构文档 · 自托管指南

【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt