references/lobe-chat
1
0
Fork 0
mirror of https://github.com/lobehub/lobe-chat.git synced 2026-06-13 19:20:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 docs(workflow): optimize documentation structure and development setup (#8934)

Browse Source
This commit is contained in:
YuTengjing
2025-08-26 18:21:22 +08:00
committed by GitHub
parent 45f05a0169
commit 9a6657e52e
7 changed files with 214 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/add-provider-doc.mdc
+183
View File
@@ -0,0 +1,183 @@
---
description: Complete guide for adding a new AI provider documentation to LobeChat
alwaysApply: false
---
# Adding New AI Provider Documentation
This document provides a step-by-step guide for adding documentation for a new AI provider to LobeChat, based on the complete workflow used for adding providers like BFL (Black Forest Labs) and FAL.
## Overview
Adding a new provider requires creating both user-facing documentation and technical configuration files. The process involves:
1. Creating usage documentation (EN + CN)
2. Adding environment variable documentation (EN + CN)
3. Updating Docker configuration files
4. Updating .env.example file
5. Preparing image resources
## Step 1: Create Provider Usage Documentation
Create user-facing documentation that explains how to use the new provider.
### Required Files
Create both English and Chinese versions:
- `docs/usage/providers/{provider-name}.mdx` (English)
- `docs/usage/providers/{provider-name}.zh-CN.mdx` (Chinese)
### Documentation Structure
Follow the structure and format used in existing provider documentation. For reference, see:
- `docs/usage/providers/fal.mdx` (English template)
- `docs/usage/providers/fal.zh-CN.mdx` (Chinese template)
### Key Requirements
- **Images**: Prepare 5-6 screenshots showing the process
- **Cover Image**: Create or obtain a cover image for the provider
- **Accurate URLs**: Use real registration and dashboard URLs
- **Service Type**: Specify whether it's for image generation, text generation, etc.
- **Pricing Warning**: Include pricing information callout
### Important Notes
- **🔒 API Key Security**: Never include real API keys in documentation. Always use placeholder format (e.g., `bfl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
- **🖼️ Image Hosting**: Use LobeHub's CDN for all images: `hub-apac-1.lobeobjects.space`
## Step 2: Update Environment Variables Documentation
Add the new provider's environment variables to the self-hosting documentation.
### Files to Update
- `docs/self-hosting/environment-variables/model-provider.mdx` (English)
- `docs/self-hosting/environment-variables/model-provider.zh-CN.mdx` (Chinese)
### Content to Add
Add two sections for each provider:
```markdown
### `{PROVIDER}_API_KEY`
- Type: Required
- Description: This is the API key you applied for in the {Provider Name} service.
- Default: -
- Example: `{api-key-format-example}`
### `{PROVIDER}_MODEL_LIST`
- Type: Optional
- Description: Used to control the {Provider Name} model list. Use `+` to add a model, `-` to hide a model, and `model_name=display_name` to customize the display name of a model. Separate multiple entries with commas. The definition syntax follows the same rules as other providers' model lists.
- Default: `-`
- Example: `-all,+{model-id-1},+{model-id-2}={display-name}`
The above example disables all models first, then enables `{model-id-1}` and `{model-id-2}` (displayed as `{display-name}`).
[model-list]: /docs/self-hosting/advanced/model-list
```
### Important Notes
- **API Key Format**: Use proper UUID format for examples (e.g., `12345678-1234-1234-1234-123456789abc`)
- **Real Model IDs**: Use actual model IDs from the codebase, not placeholders
- **Consistent Naming**: Follow the pattern `{PROVIDER}_API_KEY` and `{PROVIDER}_MODEL_LIST`
## Step 3: Update Docker Configuration Files
Add environment variables to all Docker configuration files to ensure the provider works in containerized deployments.
### Files to Update
All Dockerfile variants must be updated:
- `Dockerfile`
- `Dockerfile.database`
- `Dockerfile.pglite`
### Changes Required
Add the new provider's environment variables at the **end** of the ENV section, just before the final line:
```dockerfile
# Previous providers...
# 302.AI
AI302_API_KEY="" AI302_MODEL_LIST="" \
# {New Provider 1}
{PROVIDER1}_API_KEY="" {PROVIDER1}_MODEL_LIST="" \
# {New Provider 2}
{PROVIDER2}_API_KEY="" {PROVIDER2}_MODEL_LIST=""
```
### Important Rules
- **Position**: Add new providers at the **end** of the list
- **Ordering**: When adding multiple providers, use alphabetical order (e.g., FAL before BFL)
- **Consistency**: Maintain identical ordering across all Dockerfile variants
- **Format**: Follow the pattern `{PROVIDER}_API_KEY="" {PROVIDER}_MODEL_LIST="" \`
## Step 4: Update .env.example File
Add example configuration entries to help users understand how to configure the provider locally.
### File to Update
- `.env.example`
### Content to Add
Add new sections before the "Market Service" section:
```bash
### {Provider Name} ###
# {PROVIDER}_API_KEY={provider-prefix}-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
### Format Guidelines
- **Section Header**: Use `### {Provider Name} ###` format
- **Commented Example**: Use `#` to comment out the example
- **Key Format**: Use appropriate prefix for the provider (e.g., `bfl-`, `fal-`, `sk-`)
- **Position**: Add before the Market Service section
- **Spacing**: Maintain consistent spacing with existing entries
## Step 5: Image Resources
Prepare all necessary image resources for the documentation.
### Required Images
1. **Cover Image**: Provider logo or branded image
2. **API Dashboard Screenshots**: 3-4 screenshots showing API key creation process
3. **LobeChat Configuration Screenshots**: 2-3 screenshots showing provider setup in LobeChat
### Image Guidelines
- **Quality**: Use high-resolution screenshots
- **Consistency**: Maintain consistent styling across all screenshots
- **Privacy**: Remove or blur any sensitive information
- **Format**: Use PNG format for screenshots
- **Hosting**: Use LobeHub's CDN (`hub-apac-1.lobeobjects.space`) for all images
## Checklist
Before submitting your provider documentation:
- [ ] Created both English and Chinese usage documentation
- [ ] Added environment variable documentation (EN + CN)
- [ ] Updated all 3 Dockerfile variants with consistent ordering
- [ ] Updated .env.example with proper key format
- [ ] Prepared all required screenshots and images
- [ ] Used actual model IDs from the codebase
- [ ] Verified no real API keys are included in documentation
- [ ] Used LobeHub CDN for all image hosting
- [ ] Tested the documentation for clarity and accuracy
## Reference
This guide was created based on the implementation of BFL (Black Forest Labs) provider documentation. For a complete example, refer to:
- Commits: `d2da03e1a` (documentation) and `6a2e95868` (environment variables)
- Files: `docs/usage/providers/bfl.mdx`, `docs/usage/providers/bfl.zh-CN.mdx`
- PR: Current branch `tj/feat/bfl-docs`
.cursor/rules/debug.mdc
-193
View File
@@ -1,193 +0,0 @@
---
description: Debug 调试指南
globs:
alwaysApply: false
---
# Debug 调试指南
## 💡 调试流程概览
当遇到问题时，请按照以下优先级进行处理：
1. **快速判断** - 对于熟悉的错误，直接提供解决方案
2. **信息收集** - 使用工具搜索相关代码和配置
3. **网络搜索** - 查找现有解决方案
4. **定位调试** - 添加日志进行问题定位
5. **临时方案** - 如果找不到根本解决方案，提供临时解决方案
6. **解决实施** - 提供可维护的最终解决方案
## 🔍 错误信息分析
### 错误来源识别
错误信息可能来自：
- **Terminal 输出** - 构建、运行时错误
- **浏览器控制台** - 前端 JavaScript 错误
- **开发工具** - ESLint、TypeScript、测试框架等
- **服务器日志** - API、数据库连接等后端错误
- **截图或文本** - 用户直接提供的错误信息
## 🛠️ 信息收集工具
### 代码搜索工具
使用以下工具收集相关信息，并根据场景选择最合适的工具：
- **`codebase_search` (语义搜索)**
- **何时使用**: 当你不确定具体的代码实现，想要寻找相关概念、功能或逻辑时。
- **示例**: `查询"文件上传"功能的实现`
- **`grep_search` (精确/正则搜索)**
- **何时使用**: 当你知道要查找的确切字符串、函数名、变量名或一个特定的模式时。
- **示例**: `查找所有使用了 'useState' 的地方`
- **`file_search` (文件搜索)**
- **何时使用**: 当你知道文件名的一部分，需要快速定位文件时。
- **示例**: `查找 'Button.tsx' 组件`
- **`read_file` (内容读取)**
- **何时使用**: 在定位到具体文件后，用于查看其完整内容和上下文。
- **`web_search` (网络搜索)**
- **何时使用**: 当错误信息可能与第三方库、API 或常见问题相关时，用于获取外部信息。
### 环境与依赖检查
- **检查 `package.json`**: 查看 `scripts` 了解项目如何运行、构建和测试。查看 `dependencies` 和 `devDependencies` 确认库版本，版本冲突有时是问题的根源。
- **运行测试**: 使用 `ni vitest` 运行单元测试和集成测试，这可以快速定位功能回归或组件错误。
### 项目特定搜索目标
针对 lobe-chat 项目，重点关注：
- **配置文件**: [package.json](mdc:package.json), [next.config.mjs](mdc:next.config.mjs)
- **核心功能**: `src/features/` 下的相关模块
- **状态管理**: `src/store/` 下的 Zustand stores
- **数据库**: `src/database/` 和 `src/migrations/`
- **类型定义**: `src/types/` 下的类型文件
- **服务层**: `src/services/` 下的 API 服务
- **启动流程**: [apps/desktop/src/main/core/App.ts](mdc:apps/desktop/src/main/core/App.ts) - 了解应用启动流程
## 🌐 网络搜索策略
### 搜索顺序优先级
1. **和问题相关的项目的 github issue**
2. **技术社区**
- Stack Overflow
- GitHub Discussions
- Reddit
3. **官方文档**
- 使用 `mcp_context7_resolve-library-id` 和 `mcp_context7_get-library-docs` 工具
- 查阅官方文档网站
### 搜索关键词策略
- **错误信息**: 完整的错误消息
- **技术栈**: "Next.js 15" + "error message"
- **上下文**: 添加功能相关的关键词
## 🔧 问题定位与结构化思考
如果问题比较复杂，我们要按照先定位问题，再解决问题的大方向进行。
### 结构化思考工具
对于复杂或多步骤的调试任务，使用 `mcp_sequential-thinking_sequentialthinking` 工具来结构化思考过程。这有助于：
- **分解问题**: 将大问题拆解成可管理的小步骤。
- **清晰追踪**: 记录每一步的发现和决策，避免遗漏。
- **自我修正**: 在过程中评估和调整调试路径。
### 日志调试
在问题产生的路径上添加日志，可以简单使用 `console.log` 或者参考 [debug-usage.mdc](mdc:.cursor/rules/debug-usage.mdc) 使用 `debug` 模块。添加完日志后，请求我运行相关的代码并提供关键输出和错误信息。
### 引导式交互调试
虽然我无法直接操作浏览器开发者工具，但我可以引导你进行交互式调试：
1. **设置断点**: 我会告诉你可以在哪些关键代码行设置断点。
2. **检查变量**: 我会请你在断点处检查特定变量的值或 `props`/`state`。
3. **分析调用栈**: 我会请你提供调用栈信息，以帮助理解代码执行流程。
## 💡 临时解决方案策略
当无法找到根本解决方案时，提供临时解决方案：
### 临时方案准则
- **快速修复** - 优先让功能可用
- **最小修改** - 减少对现有代码的影响
- **清晰标记** - 明确标注这是临时方案
- **后续计划** - 说明后续如何找到更好的解决方案
### 临时方案模板
```markdown
## 临时解决方案 ⚠️
**问题**: [简要描述问题]
**临时修复**:
[具体的临时修复步骤]
**风险说明**:
- [可能的副作用或限制]
- [需要注意的事项]
**后续计划**:
- [ ] 深入调研根本原因
- [ ] 寻找更优雅的解决方案
- [ ] 监控是否有其他影响
```
## ✅ 解决方案准则
### 方案质量标准
提供的解决方案应该：
- **✅ 低侵入性** - 最小化对现有代码的修改
- **✅ 可维护性** - 易于理解和后续维护
- **✅ 类型安全** - 符合 TypeScript 规范
- **✅ 最佳实践** - 遵循项目的编码规范
- **✅ 测试友好** - 便于编写和运行测试
- **❌ 避免长期 Hack** - 临时方案可以 hack，但要明确标注
### 解决方案模板
```markdown
## 问题原因
[简要说明问题产生的根本原因]
## 解决方案
[详细的解决步骤]
## 代码修改
[具体的代码变更]
## 验证方法
[如何验证问题已解决]
## 预防措施
[如何避免类似问题再次发生]
```
## 🔄 迭代调试流程
如果初次解决方案无效：
1. **重新收集信息** - 基于新的错误信息搜索
2. **深入代码分析** - 查看更多相关代码文件
3. **运行相关测试** - 编写或运行一个失败的测试来稳定复现问题。
4. **扩大搜索范围** - 搜索更广泛的相关问题
5. **请求更多日志** - 添加更详细的调试信息
6. **提供临时方案** - 如果根本解决方案复杂，先提供临时修复
7. **分解问题** - 将复杂问题拆解为更小的子问题
.github/workflows/release.yml
+3 -3
View File
@@ -16,6 +16,8 @@ jobs:
POSTGRES_PASSWORD: postgres
options: >-
--health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
ports:
- 5432:5432
@@ -38,10 +40,8 @@ jobs:
- name: Lint
run: bun run lint
- uses: pnpm/action-setup@v4
- name: Test Database Coverage
run: pnpm --filter @lobechat/database test
run: bun run --filter @lobechat/database test
env:
DATABASE_TEST_URL: postgresql://postgres:postgres@localhost:5432/postgres
DATABASE_DRIVER: node
.github/workflows/test.yml
+3 -7
View File
@@ -23,8 +23,6 @@ jobs:
with:
node-version: 22
- uses: pnpm/action-setup@v4
- name: Install bun
uses: oven-sh/setup-bun@v1
with:
@@ -34,7 +32,7 @@ jobs:
run: bun i
- name: Test ${{ matrix.package }} package with coverage
run: pnpm --filter @lobechat/${{ matrix.package }} test:coverage
run: bun run --filter @lobechat/${{ matrix.package }} test:coverage
- name: Upload ${{ matrix.package }} coverage to Codecov
uses: codecov/codecov-action@v4
@@ -111,17 +109,15 @@ jobs:
- name: Lint
run: bun run lint
- uses: pnpm/action-setup@v4
- name: Test Client DB
run: pnpm --filter @lobechat/database test:client-db
run: bun run --filter @lobechat/database test:client-db
env:
KEY_VAULTS_SECRET: LA7n9k3JdEcbSgml2sxfw+4TV1AzaaFU5+R176aQz4s=
S3_PUBLIC_DOMAIN: https://example.com
APP_URL: https://home.com
- name: Test Coverage
run: pnpm --filter @lobechat/database test:coverage
run: bun run --filter @lobechat/database test:coverage
env:
DATABASE_TEST_URL: postgresql://postgres:postgres@localhost:5432/postgres
DATABASE_DRIVER: node
CLAUDE.md
+6 -6
View File
@@ -21,7 +21,11 @@ read @.cursor/rules/project-structure.mdc
### Package Management
this is a monorepo project and we use `pnpm` as package manager
This repository adopts a monorepo structure.
- Use `pnpm` as the primary package manager for dependency management
- Use `bun` to run npm scripts at the root level
- Use `bunx` to run executable npm packages
### TypeScript Code Style Guide
@@ -75,6 +79,7 @@ Some useful rules of this project. Read them when needed.
- `react-component.mdc` - antd-style, Lobe UI usage
- `drizzle-schema-style-guide.mdc` - Schema naming, patterns
- `define-database-model.mdc` - Model templates, CRUD patterns
- `i18n.mdc` - Internationalization workflow
**State & UI**
@@ -94,8 +99,3 @@ Some useful rules of this project. Read them when needed.
- `desktop-menu-configuration.mdc` - App menu, context menu, tray menu
- `desktop-window-management.mdc` - Window creation, state management, multi-window
- `desktop-controller-tests.mdc` - Controller unit testing guide
**Development Tools**
- `i18n.mdc` - Internationalization workflow
- `debug.mdc` - Debugging strategies
docs/development/basic/setup-development.mdx
+10 -13
View File
@@ -17,10 +17,14 @@ Before starting development on LobeChat, you need to install and configure some
First, you need to install the following software:
- Node.js: LobeChat is built on Node.js, so you need to install Node.js. We recommend installing the latest stable version.
- Yarn: We use Yarn as the preferred package manager. You can download and install it from the Yarn official website.
- PNPM: We use PNPM as an auxiliary package manager. You can download and install it from the PNPM official website.
- PNPM: We use PNPM as the preferred package manager. You can download and install it from the [PNPM official website](https://pnpm.io/installation).
- Bun: We use Bun as the npm scripts runner. You can download and install it from the [Bun official website](https://bun.com/docs/installation).
- Git: We use Git for version control. You can download and install it from the Git official website.
- IDE: You can choose your preferred integrated development environment (IDE). We recommend using WebStorm, a powerful IDE particularly suitable for TypeScript development.
- IDE: You can choose your preferred integrated development environment (IDE). We recommend using WebStorm/VSCode.
### VSCode Users
We recommend installing the extensions listed in [.vscode/extensions.json](https://github.com/lobehub/lobe-chat/blob/main/.vscode/extensions.json) for the best development experience.
### Project Setup
@@ -32,24 +36,17 @@ After installing the above software, you can start setting up the LobeChat proje
git clone https://github.com/lobehub/lobe-chat.git
```
2. **Install dependencies**: Then, navigate to the project directory and use Yarn to install the project's dependencies:
2. **Install dependencies**: Then, navigate to the project directory and use PNPM to install the project's dependencies:
```bash
cd lobe-chat
yarn install
```
If you are using PNPM, you can execute:
```bash
cd lobe-chat
pnpm install
pnpm i
```
3. **Start the development server**: After installing the dependencies, you can start the development server:
```bash
yarn run dev
bun run dev
```
Now, you can open `http://localhost:3010` in your browser, and you should see the welcome page of LobeChat. This indicates that you have successfully set up the development environment.
docs/development/basic/setup-development.zh-CN.mdx
+9 -12
View File
@@ -17,10 +17,14 @@
首先，你需要安装以下软件：
- Node.js：LobeChat 是基于 Node.js 构建的，因此你需要安装 Node.js。我们建议安装最新的稳定版。
- Bun：我们使用 Bun 作为首选包管理器。你可以从 Bun 的官方网站上下载并安装。
- PNPM：我们使用 PNPM 作为辅助包管理器。你可以从 pnpm 的官方网站上下载并安装。
- PNPM：我们使用 PNPM 作为管理器。你可以从 [pnpm 的官方网站](https://pnpm.io/installation) 上下载并安装。
- Bun：我们使用 Bun 作为 npm scripts runner, 你可以从 [Bun 的官方网站](https://bun.com/docs/installation) 上下载并安装。
- Git：我们使用 Git 进行版本控制。你可以从 Git 的官方网站上下载并安装。
- IDE：你可以选择你喜欢的集成开发环境（IDE）。我们推荐使用 WebStorm，它是一款功能强大的 IDE，特别适合 TypeScript 开发。
- IDE：你可以选择你喜欢的集成开发环境（IDE），我们推荐使用 WebStorm/VSCode。
### VSCode 用户
推荐安装 [.vscode/extensions.json](https://github.com/lobehub/lobe-chat/blob/main/.vscode/extensions.json) 中推荐安装的扩展获得最佳开发体验。
### 项目设置
@@ -32,14 +36,7 @@
git clone https://github.com/lobehub/lobe-chat.git
```
2. **安装依赖**：然后，进入项目目录，并使用 bun 安装项目的依赖包：
```bash
cd lobe-chat
bun i
```
如果你使用 pnpm ，可以执行:
2. **安装依赖**：然后，进入项目目录，并使用 `pnpm` 安装项目的依赖包：
```bash
cd lobe-chat
@@ -54,7 +51,7 @@ bun run dev
现在，你可以在浏览器中打开 `http://localhost:3010`，你应该能看到 LobeChat 的欢迎页面。这表明你已经成功地设置了开发环境。
![](https://github-production-user-asset-6210df.s3.amazonaws.com/28616219/274655364-414bc31e-8511-47a3-af17-209b530effc7.png)
![Chat Page](https://hub-apac-1.lobeobjects.space/docs/fc7b157a3bc016bc97719065f80c555c.png)
在开发过程中，如果你在环境设置上遇到任何问题，或者有任何关于 LobeChat 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！