From 45f05a01697b9d101263bfc77c317b7317ace3d6 Mon Sep 17 00:00:00 2001 From: YuTengjing Date: Tue, 26 Aug 2025 17:26:45 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20BFL=20provider?= =?UTF-8?q?=20documentation=20(#8933)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 8 +++ Dockerfile | 6 +- Dockerfile.database | 6 +- Dockerfile.pglite | 6 +- .../environment-variables/model-provider.mdx | 29 +++++++- .../model-provider.zh-CN.mdx | 29 +++++++- docs/usage/providers/bfl.mdx | 68 +++++++++++++++++++ docs/usage/providers/bfl.zh-CN.mdx | 67 ++++++++++++++++++ 8 files changed, 212 insertions(+), 7 deletions(-) create mode 100644 docs/usage/providers/bfl.mdx create mode 100644 docs/usage/providers/bfl.zh-CN.mdx diff --git a/.env.example b/.env.example index 4b9c1fb37b4..735a996251a 100644 --- a/.env.example +++ b/.env.example @@ -153,6 +153,14 @@ OPENAI_API_KEY=sk-xxxxxxxxx # AIHUBMIX_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +### BFL ### + +# BFL_API_KEY=bfl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +### FAL ### + +# FAL_API_KEY=fal-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + ######################################## ############ Market Service ############ diff --git a/Dockerfile b/Dockerfile index 3e285f918ad..8dbcbc5aa0e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -249,7 +249,11 @@ ENV \ # Infini-AI INFINIAI_API_KEY="" INFINIAI_MODEL_LIST="" \ # 302.AI - AI302_API_KEY="" AI302_MODEL_LIST="" + AI302_API_KEY="" AI302_MODEL_LIST="" \ + # FAL + FAL_API_KEY="" FAL_MODEL_LIST="" \ + # BFL + BFL_API_KEY="" BFL_MODEL_LIST="" USER nextjs diff --git a/Dockerfile.database b/Dockerfile.database index 523c01ef602..ce39459d6da 100644 --- a/Dockerfile.database +++ b/Dockerfile.database @@ -291,7 +291,11 @@ ENV \ # Infini-AI INFINIAI_API_KEY="" INFINIAI_MODEL_LIST="" \ # 302.AI - AI302_API_KEY="" AI302_MODEL_LIST="" + AI302_API_KEY="" AI302_MODEL_LIST="" \ + # FAL + FAL_API_KEY="" FAL_MODEL_LIST="" \ + # BFL + BFL_API_KEY="" BFL_MODEL_LIST="" USER nextjs diff --git a/Dockerfile.pglite b/Dockerfile.pglite index 2bee1996a4d..1c3f4e43456 100644 --- a/Dockerfile.pglite +++ b/Dockerfile.pglite @@ -247,7 +247,11 @@ ENV \ # Infini-AI INFINIAI_API_KEY="" INFINIAI_MODEL_LIST="" \ # 302.AI - AI302_API_KEY="" AI302_MODEL_LIST="" + AI302_API_KEY="" AI302_MODEL_LIST="" \ + # FAL + FAL_API_KEY="" FAL_MODEL_LIST="" \ + # BFL + BFL_API_KEY="" BFL_MODEL_LIST="" USER nextjs diff --git a/docs/self-hosting/environment-variables/model-provider.mdx b/docs/self-hosting/environment-variables/model-provider.mdx index 5d5592f19e6..b419c0869cc 100644 --- a/docs/self-hosting/environment-variables/model-provider.mdx +++ b/docs/self-hosting/environment-variables/model-provider.mdx @@ -646,8 +646,33 @@ If you need to use Azure OpenAI to provide model services, you can refer to the - Type: Optional - Description: Used to control the FAL 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,+fal-model-1,+fal-model-2=fal-special` +- Example: `-all,+flux/schnell,+flux-pro/kontext=FLUX.1 Kontext [pro]` -The above example disables all models first, then enables `fal-model-1` and `fal-model-2` (displayed as `fal-special`). +The above example disables all models first, then enables `flux/schnell` and `flux-pro/kontext` (displayed as `FLUX.1 Kontext [pro]`). + +## BFL + +### `ENABLED_BFL` + +- Type: Optional +- Description: Enables BFL as a model provider by default. Set to `0` to disable the BFL service. +- Default: `1` +- Example: `0` + +### `BFL_API_KEY` + +- Type: Required +- Description: This is the API key you applied for in the BFL service. +- Default: - +- Example: `12345678-1234-1234-1234-123456789abc` + +### `BFL_MODEL_LIST` + +- Type: Optional +- Description: Used to control the BFL 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,+flux-pro-1.1,+flux-kontext-pro=FLUX.1 Kontext [pro]` + +The above example disables all models first, then enables `flux-pro-1.1` and `flux-kontext-pro` (displayed as `FLUX.1 Kontext [pro]`). [model-list]: /docs/self-hosting/advanced/model-list diff --git a/docs/self-hosting/environment-variables/model-provider.zh-CN.mdx b/docs/self-hosting/environment-variables/model-provider.zh-CN.mdx index 4d5d4f9d049..ddbdd6b6384 100644 --- a/docs/self-hosting/environment-variables/model-provider.zh-CN.mdx +++ b/docs/self-hosting/environment-variables/model-provider.zh-CN.mdx @@ -645,8 +645,33 @@ LobeChat 在部署时提供了丰富的模型服务商相关的环境变量， - 类型：可选 - 描述：用来控制 FAL 模型列表，使用 `+` 增加一个模型，使用 `-` 来隐藏一个模型，使用 `模型名=展示名` 来自定义模型的展示名，用英文逗号隔开。模型定义语法规则与其他 provider 保持一致。 - 默认值：`-` -- 示例：`-all,+fal-model-1,+fal-model-2=fal-special` +- 示例：`-all,+flux/schnell,+flux-pro/kontext=FLUX.1 Kontext [pro]` -上述示例表示先禁用所有模型，再启用 `fal-model-1` 和 `fal-model-2`（显示名为 `fal-special`）。 +上述示例表示先禁用所有模型，再启用 `flux/schnell` 和 `flux-pro/kontext`（显示名为 `FLUX.1 Kontext [pro]`）。 + +## BFL + +### `ENABLED_BFL` + +- 类型：可选 +- 描述：默认启用 BFL 作为模型供应商，当设为 0 时关闭 BFL 服务 +- 默认值：`1` +- 示例：`0` + +### `BFL_API_KEY` + +- 类型：必选 +- 描述：这是你在 BFL 服务中申请的 API 密钥 +- 默认值：- +- 示例：`12345678-1234-1234-1234-123456789abc` + +### `BFL_MODEL_LIST` + +- 类型：可选 +- 描述：用来控制 BFL 模型列表，使用 `+` 增加一个模型，使用 `-` 来隐藏一个模型，使用 `模型名=展示名` 来自定义模型的展示名，用英文逗号隔开。模型定义语法规则与其他 provider 保持一致。 +- 默认值：`-` +- 示例：`-all,+flux-pro-1.1,+flux-kontext-pro=FLUX.1 Kontext [pro]` + +上述示例表示先禁用所有模型，再启用 `flux-pro-1.1` 和 `flux-kontext-pro`（显示名为 `FLUX.1 Kontext [pro]`）。 [model-list]: /zh/docs/self-hosting/advanced/model-list diff --git a/docs/usage/providers/bfl.mdx b/docs/usage/providers/bfl.mdx new file mode 100644 index 00000000000..57f2ff28663 --- /dev/null +++ b/docs/usage/providers/bfl.mdx @@ -0,0 +1,68 @@ +--- +title: Using Black Forest Labs API Key in LobeChat +description: >- + Learn how to integrate Black Forest Labs API Key in LobeChat for AI image generation using advanced models and high-quality output. + +tags: + - Black Forest Labs + - Image Generation + - API Key + - Web UI +--- + +# Using Black Forest Labs in LobeChat + +{'Using + +[Black Forest Labs](https://bfl.ai/) is currently the world's top-tier AI image generation research lab, having developed the FLUX series of high-quality image generation models and the FLUX Kontext series of image editing models. This document will guide you on how to use Black Forest Labs in LobeChat: + + + ### Step 1: Obtain Black Forest Labs API Key + + - Register for a [Black Forest Labs account](https://auth.bfl.ai/). + - Navigate to the [API Keys dashboard](https://dashboard.bfl.ai/api/keys) and click **Add Key** to generate a new API key. + - Copy the generated API key and keep it secure; it will only be shown once. + + {'Open + + {'Create + + {'Retrieve + + ### Step 2: Configure Black Forest Labs in LobeChat + + - Visit the `Settings` page in LobeChat. + - Under **AI Service Provider**, locate the **Black Forest Labs** configuration section. + + {'Enter + + - Paste the API key you obtained. + - Choose a Black Forest Labs model for image generation. + + {'Select + + + During usage, you may incur charges according to Black Forest Labs's pricing policy. Please review Black Forest Labs's + official pricing before heavy usage. + + + +You can now use Black Forest Labs's advanced image generation models directly within LobeChat to create stunning visual content. diff --git a/docs/usage/providers/bfl.zh-CN.mdx b/docs/usage/providers/bfl.zh-CN.mdx new file mode 100644 index 00000000000..65436fea2e4 --- /dev/null +++ b/docs/usage/providers/bfl.zh-CN.mdx @@ -0,0 +1,67 @@ +--- +title: 在 LobeChat 中使用 Black Forest Labs API Key +description: >- + 学习如何在 LobeChat 中配置和使用 Black Forest Labs API Key，使用先进模型进行高质量 AI 图像生成。 + +tags: + - Black Forest Labs + - 图像生成 + - API Key + - Web UI +--- + +# 在 LobeChat 中使用 Black Forest Labs + +{'在 + +[Black Forest Labs](https://bfl.ai/) 是当前世界最顶级的 AI 图像生成实验室团队，研发了 FLUX 系列高质量图像生成模型，FLUX Kontext 系列图像编辑模型。本文将指导你如何在 LobeChat 中使用 Black Forest Labs： + + + ### 步骤一：获取 Black Forest Labs API Key + + - 注册 [Black Forest Labs](https://auth.bfl.ai/) 账户； + - 前往 [API Keys 控制台](https://dashboard.bfl.ai/api/keys)，点击 **Add Key** 创建新的 API 密钥； + - 复制生成的 API Key 并妥善保存，它只会显示一次。 + + {'打开 + + {'创建 + + {'获取 + + ### 步骤二：在 LobeChat 中配置 Black Forest Labs + + - 访问 LobeChat 的 `设置` 页面； + - 在 `AI服务商` 下找到 `Black Forest Labs` 的设置项； + + {'填入 + + - 粘贴获取到的 API Key； + - 选择一个 Black Forest Labs 模型用于图像生成。 + + {'选择 + + + 在使用过程中，你可能需要向 Black Forest Labs 支付相应费用，请在大量调用前查阅 Black Forest Labs 的官方计费政策。 + + + +至此，你已经可以在 LobeChat 中使用 Black Forest Labs 提供的先进图像生成模型来创作精美的视觉内容了。 From 9a6657e52e8a2466bac4bf6b0969209729f7e294 Mon Sep 17 00:00:00 2001 From: YuTengjing Date: Tue, 26 Aug 2025 18:21:22 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20docs(workflow):=20optimize?= =?UTF-8?q?=20documentation=20structure=20and=20development=20setup=20(#89?= =?UTF-8?q?34)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/rules/add-provider-doc.mdc | 183 +++++++++++++++++ .cursor/rules/debug.mdc | 193 ------------------ .github/workflows/release.yml | 6 +- .github/workflows/test.yml | 10 +- CLAUDE.md | 12 +- docs/development/basic/setup-development.mdx | 23 +-- .../basic/setup-development.zh-CN.mdx | 21 +- 7 files changed, 214 insertions(+), 234 deletions(-) create mode 100644 .cursor/rules/add-provider-doc.mdc delete mode 100644 .cursor/rules/debug.mdc diff --git a/.cursor/rules/add-provider-doc.mdc b/.cursor/rules/add-provider-doc.mdc new file mode 100644 index 00000000000..b6af7fa16ae --- /dev/null +++ b/.cursor/rules/add-provider-doc.mdc @@ -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` \ No newline at end of file diff --git a/.cursor/rules/debug.mdc b/.cursor/rules/debug.mdc deleted file mode 100644 index f4a455a9ca2..00000000000 --- a/.cursor/rules/debug.mdc +++ /dev/null @@ -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. **分解问题** - 将复杂问题拆解为更小的子问题 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bdd6eb10758..abf83c97c21 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a2cac5bcf89..a00561aa0ed 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index 7501f4b9e2c..77c26914acf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/docs/development/basic/setup-development.mdx b/docs/development/basic/setup-development.mdx index 96dccdec126..e7c816d4b59 100644 --- a/docs/development/basic/setup-development.mdx +++ b/docs/development/basic/setup-development.mdx @@ -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: - -```bash -cd lobe-chat -yarn install -``` - -If you are using PNPM, you can execute: +2. **Install dependencies**: Then, navigate to the project directory and use PNPM to install the project's dependencies: ```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. diff --git a/docs/development/basic/setup-development.zh-CN.mdx b/docs/development/basic/setup-development.zh-CN.mdx index cbd28530b75..439b2edafc9 100644 --- a/docs/development/basic/setup-development.zh-CN.mdx +++ b/docs/development/basic/setup-development.zh-CN.mdx @@ -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 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！