2026-01-21 10:44:44 +00:00
|
|
|
|
---
|
|
|
|
|
|
title: 代码风格与贡献指南
|
2026-01-26 07:28:33 +00:00
|
|
|
|
description: 了解 LobeHub 的代码规范和贡献流程，确保代码一致性。
|
|
|
|
|
|
tags:
|
|
|
|
|
|
- 代码风格
|
|
|
|
|
|
- 贡献指南
|
|
|
|
|
|
- LobeHub
|
|
|
|
|
|
- ESLint
|
|
|
|
|
|
- Prettier
|
2026-01-21 10:44:44 +00:00
|
|
|
|
---
|
|
|
|
|
|
|
2024-01-16 12:57:44 +00:00
|
|
|
|
# 代码风格与贡献指南
|
|
|
|
|
|
|
2026-01-26 07:28:33 +00:00
|
|
|
|
欢迎来到 LobeHub 的代码风格与贡献指南。本指南将帮助您理解我们的代码规范和贡献流程，确保代码的一致性和项目的顺利进行。
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
## 代码风格
|
|
|
|
|
|
|
2026-01-26 07:28:33 +00:00
|
|
|
|
在 LobeHub 中，我们使用 [@lobehub/lint](https://github.com/lobehub/lobe-lint) 程序包来统一代码风格。该程序包内置了 `ESLint`、`Prettier`、`remarklint` 和 `stylelint` 的配置，以确保我们的 JavaScript、Markdown 和 CSS 文件遵循相同的编码标准。
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
### ESLint
|
|
|
|
|
|
|
|
|
|
|
|
我们的项目使用 ESLint 来检查 JavaScript 代码中的问题。您可以在项目根目录下找到 `.eslintrc.js` 文件，其中包含了我们对 `@lobehub/lint` 的 ESLint 配置的扩展和自定义规则。
|
|
|
|
|
|
|
|
|
|
|
|
为了与 Next.js 框架兼容，我们在配置中添加了 `plugin:@next/next/recommended`。此外，我们禁用了一些规则，以适应我们项目的特定需求。
|
|
|
|
|
|
|
|
|
|
|
|
### Prettier
|
|
|
|
|
|
|
|
|
|
|
|
Prettier 负责代码格式化，以保证代码的一致性。您可以在 `.prettierrc.js` 中找到我们的 Prettier 配置，它是从 `@lobehub/lint` 导入的。
|
|
|
|
|
|
|
2025-04-08 14:23:16 +00:00
|
|
|
|
在保存文件时，建议您配置您的编辑器以自动运行 Prettier。
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
### remarklint
|
|
|
|
|
|
|
|
|
|
|
|
对于 Markdown 文件，我们使用 remarklint 来确保文档格式的统一。您可以在项目中找到相应的配置文件。
|
|
|
|
|
|
|
|
|
|
|
|
### stylelint
|
|
|
|
|
|
|
|
|
|
|
|
我们使用 stylelint 来规范 CSS 代码的风格。在 `stylelint` 的配置文件中，我们基于 `@lobehub/lint` 的配置进行了一些自定义规则的调整。
|
|
|
|
|
|
|
2025-04-08 14:23:16 +00:00
|
|
|
|
### 风格检查
|
|
|
|
|
|
|
|
|
|
|
|
你不需要手动运行这些检查，项目配置了 husky 会在您提交代码时自动运行 lint-staged 检查你提交的文件是否符合以上规范。
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
## 贡献流程
|
|
|
|
|
|
|
2026-01-26 07:28:33 +00:00
|
|
|
|
LobeHub 采用 gitmoji 和 semantic release 作为我们的代码提交和发布流程。
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
### Gitmoji
|
|
|
|
|
|
|
|
|
|
|
|
在提交代码时，请使用 gitmoji 来标注您的提交信息。这有助于其他贡献者快速理解您提交的内容和目的。
|
|
|
|
|
|
|
|
|
|
|
|
Gitmoji commit messages 使用特定的 emoji 来表示提交的类型或意图。以下是一个示例：
|
|
|
|
|
|
|
2025-04-08 14:23:16 +00:00
|
|
|
|
```markdown
|
2024-01-16 12:57:44 +00:00
|
|
|
|
📝 Update README with contribution guidelines
|
|
|
|
|
|
|
|
|
|
|
|
- Added section about code style preferences
|
|
|
|
|
|
- Included instructions for running tests
|
|
|
|
|
|
- Corrected typos and improved formatting
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
在这个示例中，📝 emoji 代表了文档的更新。提交信息清晰地描述了更改的内容，提供了具体的细节。
|
|
|
|
|
|
|
|
|
|
|
|
### Semantic Release
|
|
|
|
|
|
|
📝 docs: improve development guides to reflect current architecture (#12174)
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server
Fix MDX extension crash caused by Cursor's bundled TypeScript version
* 🔧 chore(claude): add skills symlink to .claude directory
* 📝 docs: update development guides with current tech stack and architecture
- Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next
- Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/)
- Expand src/server/ with detailed subdirectory descriptions
- Add complete SPA routing architecture with desktop and mobile route tables
- Add tRPC router grouping details (lambda, async, tools, mobile)
- Add data flow diagram
- Simplify dev setup section to link to setup-development guide
- Fix i18n default language description (English, not Chinese)
- Sync all changes between zh-CN and English versions
* 📝 docs: expand data flow diagram in folder structure guide
Replace the single-line data flow with a detailed layer-by-layer
flow diagram showing each layer's location and responsibility.
* 📝 docs: modernize feature development guide
- Remove outdated clientDB/pglite/indexDB references
- Update schema path to packages/database/src/schemas/
- Update types path to packages/types/src/
- Replace inline migration steps with link to db-migrations guide
- Add complete layered architecture table (Client Service, WebAPI,
tRPC Router, Server Service, Server Module, Repository, DB Model)
- Clarify Client Service as frontend code
- Add i18n handling section with workflow and key naming convention
- Remove verbose CSS style code, keep core business logic only
- Expand testing section with commands, skill refs, and CI tip
* 🔥 docs: remove outdated frontend feature development guide
Content is superseded by the comprehensive feature-development guide
which covers the full chain from schema to testing.
* 📝 docs: add LobeHub ecosystem and community resources
Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts,
LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community
platforms (Agent Market, MCP Market, YouTube, X, Discord).
* 📝 docs: improve contributing guidelines and resources
- Clarify semantic release triggers (feat/fix vs style/chore)
- Add testing section with Vitest/E2E/CI requirements
- Update contribution steps to include CI check
- Add LobeHub ecosystem packages and community platforms to resources
* 📝 docs: rewrite architecture guide to reflect current platform design
* 📝 docs: add code quality tools to architecture guide
* 📝 docs: rewrite chat-api guide to reflect current architecture
- Update sequence diagram with Agent Runtime loop as core execution engine
- Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin)
- Update all path references (model-runtime, agent-runtime, fetch-sse packages)
- Split old AgentRuntime section into Model Runtime + Agent Runtime
- Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated)
- Add client-side vs server-side execution section
- Remove outdated adapter pseudo-code examples
* 📝 docs: update file paths in add-new-image-model guide
- src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/
- src/config/aiModels/ → packages/model-bank/src/aiModels/
- src/libs/model-runtime/ → packages/model-runtime/src/providers/
* 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides
The S3_PUBLIC_DOMAIN env var was incorrectly removed from all
documentation in commit 4a87b31. This variable is still required
by the code (src/server/services/file/impls/s3.ts) to generate
public URLs for uploaded files. Without it, image URLs sent to
vision models are just S3 keys instead of full URLs.
Closes #12161
* 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors
@lobehub/ui 4.34.0 introduced breaking type changes in SortableList
where SortableListItem became strict, causing type incompatibility
in onChange and renderItem callbacks across 6 files. Pin to 4.33.4
via pnpm overrides to enforce consistent version across monorepo.
* 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable
- Add dom.asynciterable to tsconfig lib for ReadableStream async iteration
- Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array>
- Update stream function return types from ReadableStream<string> to
ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts)
- Remove @ts-ignore from for-await loops in test files
- Add explicit string[] type for chunks arrays
* Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides"
This reverts commit 24073f83d3d5e9a89c29e9a96a6689d2baa0edde.
2026-02-07 14:29:14 +00:00
|
|
|
|
我们使用 semantic release 来自动化版本控制和发布流程。当 PR 合并到主分支后，系统会根据提交信息中的 gitmoji 前缀自动判断是否需要发布新版本：
|
|
|
|
|
|
|
|
|
|
|
|
- `✨ feat` 和 `🐛 fix` 前缀的提交会**触发新版本发布**
|
|
|
|
|
|
- 如果只是小修改不想发新版本，可以使用 `💄 style` 或 `🔨 chore` 等前缀
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
### Commitlint
|
|
|
|
|
|
|
|
|
|
|
|
为了确保提交信息的一致性，我们使用 `commitlint` 来检查提交信息格式。您可以在 `.commitlintrc.js` 配置文件中找到相关规则。
|
|
|
|
|
|
|
|
|
|
|
|
在您提交代码之前，请确保您的提交信息遵循我们的规范。
|
|
|
|
|
|
|
📝 docs: improve development guides to reflect current architecture (#12174)
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server
Fix MDX extension crash caused by Cursor's bundled TypeScript version
* 🔧 chore(claude): add skills symlink to .claude directory
* 📝 docs: update development guides with current tech stack and architecture
- Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next
- Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/)
- Expand src/server/ with detailed subdirectory descriptions
- Add complete SPA routing architecture with desktop and mobile route tables
- Add tRPC router grouping details (lambda, async, tools, mobile)
- Add data flow diagram
- Simplify dev setup section to link to setup-development guide
- Fix i18n default language description (English, not Chinese)
- Sync all changes between zh-CN and English versions
* 📝 docs: expand data flow diagram in folder structure guide
Replace the single-line data flow with a detailed layer-by-layer
flow diagram showing each layer's location and responsibility.
* 📝 docs: modernize feature development guide
- Remove outdated clientDB/pglite/indexDB references
- Update schema path to packages/database/src/schemas/
- Update types path to packages/types/src/
- Replace inline migration steps with link to db-migrations guide
- Add complete layered architecture table (Client Service, WebAPI,
tRPC Router, Server Service, Server Module, Repository, DB Model)
- Clarify Client Service as frontend code
- Add i18n handling section with workflow and key naming convention
- Remove verbose CSS style code, keep core business logic only
- Expand testing section with commands, skill refs, and CI tip
* 🔥 docs: remove outdated frontend feature development guide
Content is superseded by the comprehensive feature-development guide
which covers the full chain from schema to testing.
* 📝 docs: add LobeHub ecosystem and community resources
Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts,
LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community
platforms (Agent Market, MCP Market, YouTube, X, Discord).
* 📝 docs: improve contributing guidelines and resources
- Clarify semantic release triggers (feat/fix vs style/chore)
- Add testing section with Vitest/E2E/CI requirements
- Update contribution steps to include CI check
- Add LobeHub ecosystem packages and community platforms to resources
* 📝 docs: rewrite architecture guide to reflect current platform design
* 📝 docs: add code quality tools to architecture guide
* 📝 docs: rewrite chat-api guide to reflect current architecture
- Update sequence diagram with Agent Runtime loop as core execution engine
- Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin)
- Update all path references (model-runtime, agent-runtime, fetch-sse packages)
- Split old AgentRuntime section into Model Runtime + Agent Runtime
- Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated)
- Add client-side vs server-side execution section
- Remove outdated adapter pseudo-code examples
* 📝 docs: update file paths in add-new-image-model guide
- src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/
- src/config/aiModels/ → packages/model-bank/src/aiModels/
- src/libs/model-runtime/ → packages/model-runtime/src/providers/
* 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides
The S3_PUBLIC_DOMAIN env var was incorrectly removed from all
documentation in commit 4a87b31. This variable is still required
by the code (src/server/services/file/impls/s3.ts) to generate
public URLs for uploaded files. Without it, image URLs sent to
vision models are just S3 keys instead of full URLs.
Closes #12161
* 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors
@lobehub/ui 4.34.0 introduced breaking type changes in SortableList
where SortableListItem became strict, causing type incompatibility
in onChange and renderItem callbacks across 6 files. Pin to 4.33.4
via pnpm overrides to enforce consistent version across monorepo.
* 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable
- Add dom.asynciterable to tsconfig lib for ReadableStream async iteration
- Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array>
- Update stream function return types from ReadableStream<string> to
ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts)
- Remove @ts-ignore from for-await loops in test files
- Add explicit string[] type for chunks arrays
* Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides"
This reverts commit 24073f83d3d5e9a89c29e9a96a6689d2baa0edde.
2026-02-07 14:29:14 +00:00
|
|
|
|
### 测试
|
|
|
|
|
|
|
|
|
|
|
|
LobeHub 配置了完善的单元测试（Vitest）和 E2E 测试（Cucumber + Playwright），并通过 GitHub Actions CI 在每次 PR 提交时自动运行。提交 PR 或请求合并前，请务必确保所有测试通过。
|
|
|
|
|
|
|
|
|
|
|
|
你可以在本地运行指定测试文件来验证：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 运行指定测试（不要运行 bun run test，全量测试耗时很长）
|
|
|
|
|
|
bunx vitest run --silent='passed-only' '[file-path]'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
更多测试相关信息请参阅 [测试指南](/zh/docs/development/basic/test)。
|
|
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
### Gitmoji 参考表
|
|
|
|
|
|
|
|
|
|
|
|
提交信息请使用以下 emoji 作为前缀：
|
|
|
|
|
|
|
2026-03-30 13:42:29 +00:00
|
|
|
|
| Emoji | 代码 | 类型 | 说明 | 触发发布？ |
|
|
|
|
|
|
| ----- | ------------------------ | -------- | --------- | ----- |
|
|
|
|
|
|
| ✨ | `:sparkles:` | feat | 新功能 | 是 |
|
|
|
|
|
|
| 🐛 | `:bug:` | fix | Bug 修复 | 是 |
|
|
|
|
|
|
| 📝 | `:memo:` | docs | 文档更新 | 否 |
|
|
|
|
|
|
| 💄 | `:lipstick:` | style | UI / 样式更改 | 否 |
|
|
|
|
|
|
| ♻️ | `:recycle:` | refactor | 代码重构 | 否 |
|
|
|
|
|
|
| ✅ | `:white_check_mark:` | test | 测试相关 | 否 |
|
|
|
|
|
|
| 🔨 | `:hammer:` | chore | 维护任务 | 否 |
|
|
|
|
|
|
| 🚀 | `:rocket:` | perf | 性能优化 | 否 |
|
|
|
|
|
|
| 🌐 | `:globe_with_meridians:` | i18n | 国际化 | 否 |
|
2026-03-03 08:01:41 +00:00
|
|
|
|
|
2024-01-16 12:57:44 +00:00
|
|
|
|
### 如何贡献
|
|
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
**1. Fork 并克隆仓库**
|
|
|
|
|
|
|
2026-03-14 14:06:09 +00:00
|
|
|
|
在 GitHub 上 Fork [lobehub/lobehub](https://github.com/lobehub/lobehub)，然后克隆你的 Fork 到本地。
|
2026-03-03 08:01:41 +00:00
|
|
|
|
|
|
|
|
|
|
**2. 创建分支**
|
|
|
|
|
|
|
|
|
|
|
|
使用分支命名格式：`用户名/类型/描述`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-03-18 16:35:20 +00:00
|
|
|
|
git checkout -b feat/add-voice-input
|
|
|
|
|
|
git checkout -b fix/message-duplication
|
|
|
|
|
|
git checkout -b docs/update-api-guide
|
2026-03-03 08:01:41 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**3. 进行更改**
|
|
|
|
|
|
|
|
|
|
|
|
遵循上方的代码风格指南。提交前运行代码检查：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pnpm lint:ts # TypeScript/JavaScript
|
|
|
|
|
|
pnpm lint:style # CSS/样式
|
|
|
|
|
|
bun run type-check # 类型检查
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**4. 使用 gitmoji 提交**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
git commit -m "✨ feat: 添加语音输入支持"
|
|
|
|
|
|
git commit -m "🐛 fix: 修复群聊消息重复问题"
|
|
|
|
|
|
git commit -m "📝 docs: 更新安装指南"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**5. 创建 Pull Request**
|
|
|
|
|
|
|
|
|
|
|
|
<Callout type={'warning'}>
|
2026-03-18 16:35:20 +00:00
|
|
|
|
PR 的目标分支必须是 **`canary`**，而非 `main`。`canary` 是当前活跃的开发分支，向 `main` 发起的 PR
|
|
|
|
|
|
会被重定向。
|
2026-03-03 08:01:41 +00:00
|
|
|
|
</Callout>
|
|
|
|
|
|
|
|
|
|
|
|
请使用 `.github/PULL_REQUEST_TEMPLATE.md` 中的 PR 模板：
|
|
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
|
## Description
|
2026-03-18 16:35:20 +00:00
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
清晰描述此 PR 的改动内容。
|
|
|
|
|
|
|
|
|
|
|
|
## Type of Change
|
2026-03-18 16:35:20 +00:00
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
- [ ] ✨ 新功能
|
|
|
|
|
|
- [ ] 🐛 Bug 修复
|
|
|
|
|
|
- [ ] 📝 文档
|
|
|
|
|
|
- [ ] ♻️ 重构
|
|
|
|
|
|
|
|
|
|
|
|
## Checklist
|
2026-03-18 16:35:20 +00:00
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
- [ ] 代码符合项目风格指南
|
|
|
|
|
|
- [ ] 已添加/更新测试
|
|
|
|
|
|
- [ ] 已更新文档
|
|
|
|
|
|
- [ ] 所有测试通过
|
|
|
|
|
|
|
|
|
|
|
|
## Related Issues
|
2026-03-18 16:35:20 +00:00
|
|
|
|
|
2026-03-03 08:01:41 +00:00
|
|
|
|
Fixes #123
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**PR 标题中带有 `✨ feat:` 或 `🐛 fix:` 前缀时将自动触发新版本发布。** 不需要发布新版本的改动请使用其他前缀。
|
|
|
|
|
|
|
|
|
|
|
|
**6. 代码审查**
|
|
|
|
|
|
|
|
|
|
|
|
每次 PR 会自动运行：ESLint、TypeScript 类型检查、Vitest 单元测试、E2E 测试和构建验证。请根据审查意见向同一分支推送新的提交。
|
|
|
|
|
|
|
|
|
|
|
|
### 同步 Fork 与上游代码
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-03-14 14:06:09 +00:00
|
|
|
|
git remote add upstream https://github.com/lobehub/lobehub.git
|
2026-03-03 08:01:41 +00:00
|
|
|
|
git fetch upstream
|
|
|
|
|
|
git rebase upstream/canary
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 贡献方向
|
|
|
|
|
|
|
2026-03-14 14:06:09 +00:00
|
|
|
|
- **功能开发** — 查看 [标注为 `good first issue` 的 Issue](https://github.com/lobehub/lobehub/issues?q=is%3Aissue+label%3A%22good+first+issue%22)，找到适合新手的任务
|
2026-03-03 08:01:41 +00:00
|
|
|
|
- **Bug 修复** — 搜索标注为 `bug` 的开放 Issue
|
|
|
|
|
|
- **文档改善** — 完善文档、修正错别字、添加示例
|
|
|
|
|
|
- **测试补充** — 为缺少覆盖的代码路径添加测试
|
|
|
|
|
|
- **翻译** — 添加缺失的 i18n 键（参见 [i18n 指南](/zh/docs/development/internationalization/internationalization-implementation)）
|
2024-01-16 12:57:44 +00:00
|
|
|
|
|
|
|
|
|
|
感谢您遵循这些指导原则，它们有助于我们维护项目的质量和一致性。我们期待您的贡献！
|