diff --git a/.cursor/rules/add-provider-doc.mdc b/.cursor/rules/add-provider-doc.mdc new file mode 100644 index 0000000000..b6af7fa16a --- /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 f4a455a9ca..0000000000 --- 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 bdd6eb1075..abf83c97c2 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 a2cac5bcf8..a00561aa0e 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 7501f4b9e2..77c26914ac 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 96dccdec12..e7c816d4b5 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: +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. diff --git a/docs/development/basic/setup-development.zh-CN.mdx b/docs/development/basic/setup-development.zh-CN.mdx index cbd28530b7..439b2edafc 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 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！