@lobehub/lobehub 2.1.19 → 2.1.21

package/.eslintrc.js

@@ -20,6 +20,7 @@ config.rules['unicorn/no-array-for-each'] = 0;
 config.rules['unicorn/prefer-number-properties'] = 0;
 config.rules['unicorn/prefer-query-selector'] = 0;
 config.rules['unicorn/no-array-callback-reference'] = 0;
+config.rules['unicorn/text-encoding-identifier-case'] = 0;
 config.rules['@typescript-eslint/no-use-before-define'] = 0;
 // FIXME: Linting error in src/app/[variants]/(main)/chat/features/Migration/DBReader.ts, the fundamental solution should be upgrading typescript-eslint
 config.rules['@typescript-eslint/no-useless-constructor'] = 0;

package/.github/workflows/release.yml

@@ -18,6 +18,7 @@ concurrency:
 jobs:
   release:
     name: Release
+    if: github.repository == 'lobehub/lobehub'
     runs-on: ubuntu-latest
 
     services:

package/.github/workflows/sync-main-to-dev.yaml

@@ -0,0 +1,42 @@
+name: 🔄 Branch Synchronization
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Git
+        run: |
+          git config --global user.name 'GitHub Actions'
+          git config --global user.email 'actions@github.com'
+
+      - name: Prepare sync branch
+        id: branch
+        run: |
+          echo "SYNC_BRANCH_MAIN_DEV=sync/main-to-dev-$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - name: Sync main to dev
+        if: github.ref == 'refs/heads/main'
+        run: |
+          # Sync main to dev
+          git checkout main
+          SYNC_BRANCH_DEV=${{ env.SYNC_BRANCH_MAIN_DEV }}
+          git checkout -B $SYNC_BRANCH_DEV
+          DIFF=$(git diff origin/dev...)
+          if [ -z "$DIFF" ]; then
+            echo "No changes to sync"
+            exit 0
+          fi
+          git push origin $SYNC_BRANCH_DEV -f
+          gh pr create --base dev --head $SYNC_BRANCH_DEV --title "Sync main branch to dev branch" --body "Automatic sync" || exit 0
+        env:
+          GH_TOKEN: ${{ github.token }}

package/.vscode/settings.json

@@ -24,6 +24,7 @@
     // support mdx
     "mdx"
   ],
+  "mdx.server.enable": false,
   "npm.packageManager": "pnpm",
   "search.exclude": {
     "**/node_modules": true,
@@ -51,6 +52,7 @@
     // make stylelint work with tsx antd-style css template string
     "typescriptreact"
   ],
+  "typescript.tsdk": "node_modules/typescript/lib",
   "vitest.maximumConfigs": 20,
   "workbench.editor.customLabels.patterns": {
     "**/app/**/[[]*[]]/[[]*[]]/page.tsx": "${dirname(2)}/${dirname(1)}/${dirname} • page component",

package/CHANGELOG.md

@@ -2,6 +2,168 @@
 
 # Changelog
 
+### [Version 2.1.21](https://github.com/lobehub/lobe-chat/compare/v2.1.20...v2.1.21)
+
+<sup>Released on **2026-02-08**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Add end-user info on OpenAI Responses API call, enable vertical scrolling for topic list on mobile.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Add end-user info on OpenAI Responses API call, closes [#12134](https://github.com/lobehub/lobe-chat/issues/12134) ([72a85ac](https://github.com/lobehub/lobe-chat/commit/72a85ac))
+- **misc**: Enable vertical scrolling for topic list on mobile, closes [#12157](https://github.com/lobehub/lobe-chat/issues/12157) [lobehub/lobe-chat#12029](https://github.com/lobehub/lobe-chat/issues/12029) ([bd4e253](https://github.com/lobehub/lobe-chat/commit/bd4e253))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.21](https://github.com/lobehub/lobe-chat/compare/v2.1.20...v2.1.21)
+
+<sup>Released on **2026-02-08**</sup>
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.21](https://github.com/lobehub/lobe-chat/compare/v2.1.20...v2.1.21)
+
+<sup>Released on **2026-02-08**</sup>
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.20](https://github.com/lobehub/lobe-chat/compare/v2.1.19...v2.1.20)
+
+<sup>Released on **2026-02-08**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Add api/version and api/desktop to public routes, show notification when file upload fails due to storage plan limit.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Add api/version and api/desktop to public routes, closes [#12194](https://github.com/lobehub/lobe-chat/issues/12194) ([ea81cd4](https://github.com/lobehub/lobe-chat/commit/ea81cd4))
+- **misc**: Show notification when file upload fails due to storage plan limit, closes [#12176](https://github.com/lobehub/lobe-chat/issues/12176) ([f26d0df](https://github.com/lobehub/lobe-chat/commit/f26d0df))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.20](https://github.com/lobehub/lobe-chat/compare/v2.1.19...v2.1.20)
+
+<sup>Released on **2026-02-08**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Add api/version and api/desktop to public routes, show notification when file upload fails due to storage plan limit.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Add api/version and api/desktop to public routes, closes [#12194](https://github.com/lobehub/lobe-chat/issues/12194) ([ea81cd4](https://github.com/lobehub/lobe-chat/commit/ea81cd4))
+- **misc**: Show notification when file upload fails due to storage plan limit, closes [#12176](https://github.com/lobehub/lobe-chat/issues/12176) ([f26d0df](https://github.com/lobehub/lobe-chat/commit/f26d0df))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.20](https://github.com/lobehub/lobe-chat/compare/v2.1.19...v2.1.20)
+
+<sup>Released on **2026-02-07**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Show notification when file upload fails due to storage plan limit.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Show notification when file upload fails due to storage plan limit, closes [#12176](https://github.com/lobehub/lobe-chat/issues/12176) ([f26d0df](https://github.com/lobehub/lobe-chat/commit/f26d0df))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.20](https://github.com/lobehub/lobe-chat/compare/v2.1.19...v2.1.20)
+
+<sup>Released on **2026-02-07**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Show notification when file upload fails due to storage plan limit.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Show notification when file upload fails due to storage plan limit, closes [#12176](https://github.com/lobehub/lobe-chat/issues/12176) ([f26d0df](https://github.com/lobehub/lobe-chat/commit/f26d0df))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 2.1.19](https://github.com/lobehub/lobe-chat/compare/v2.1.18...v2.1.19)
 
 <sup>Released on **2026-02-06**</sup>

package/apps/desktop/src/main/controllers/ShellCommandCtr.ts

@@ -16,15 +16,26 @@ import { ControllerModule, IpcMethod } from './index';
 const logger = createLogger('controllers:ShellCommandCtr');
 
 // Maximum output length to prevent context explosion
-const MAX_OUTPUT_LENGTH = 10_000;
+const MAX_OUTPUT_LENGTH = 80_000;
+
+/**
+ * Strip ANSI escape codes from terminal output
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+const stripAnsi = (str: string): string => str.replaceAll(ANSI_REGEX, '');
 
 /**
  * Truncate string to max length with ellipsis indicator
  */
 const truncateOutput = (str: string, maxLength: number = MAX_OUTPUT_LENGTH): string => {
-  if (str.length <= maxLength) return str;
+  const cleaned = stripAnsi(str);
+  if (cleaned.length <= maxLength) return cleaned;
   return (
-    str.slice(0, maxLength) + '\n... [truncated, ' + (str.length - maxLength) + ' more characters]'
+    cleaned.slice(0, maxLength) +
+    '\n... [truncated, ' +
+    (cleaned.length - maxLength) +
+    ' more characters]'
   );
 };
 

package/apps/desktop/src/main/controllers/__tests__/ShellCommandCtr.test.ts

@@ -193,6 +193,62 @@ describe('ShellCommandCtr', () => {
         expect(result.stderr).toBe('error message\n');
       });
 
+      it('should strip ANSI escape codes from output', async () => {
+        let exitCallback: (code: number) => void;
+        let stdoutCallback: (data: Buffer) => void;
+        let stderrCallback: (data: Buffer) => void;
+
+        mockChildProcess.on.mockImplementation((event: string, callback: any) => {
+          if (event === 'exit') {
+            exitCallback = callback;
+            setTimeout(() => exitCallback(0), 10);
+          }
+          return mockChildProcess;
+        });
+
+        mockChildProcess.stdout.on.mockImplementation((event: string, callback: any) => {
+          if (event === 'data') {
+            stdoutCallback = callback;
+            // Simulate output with ANSI color codes
+            setTimeout(
+              () =>
+                stdoutCallback(
+                  Buffer.from(
+                    '\x1b[38;5;250m███████╗\x1b[0m\n\x1b[1;32mSuccess\x1b[0m\n\x1b[31mError\x1b[0m',
+                  ),
+                ),
+              5,
+            );
+          }
+          return mockChildProcess.stdout;
+        });
+
+        mockChildProcess.stderr.on.mockImplementation((event: string, callback: any) => {
+          if (event === 'data') {
+            stderrCallback = callback;
+            setTimeout(
+              () => stderrCallback(Buffer.from('\x1b[33mwarning:\x1b[0m something happened')),
+              5,
+            );
+          }
+          return mockChildProcess.stderr;
+        });
+
+        const result = await shellCommandCtr.handleRunCommand({
+          command: 'npx skills find react',
+          description: 'search skills',
+        });
+
+        expect(result.success).toBe(true);
+        // ANSI codes should be stripped
+        expect(result.stdout).not.toContain('\x1b[');
+        expect(result.stdout).toContain('███████╗');
+        expect(result.stdout).toContain('Success');
+        expect(result.stdout).toContain('Error');
+        expect(result.stderr).not.toContain('\x1b[');
+        expect(result.stderr).toContain('warning: something happened');
+      });
+
       it('should truncate long output to prevent context explosion', async () => {
         let exitCallback: (code: number) => void;
         let stdoutCallback: (data: Buffer) => void;
@@ -208,8 +264,8 @@ describe('ShellCommandCtr', () => {
         mockChildProcess.stdout.on.mockImplementation((event: string, callback: any) => {
           if (event === 'data') {
             stdoutCallback = callback;
-            // Simulate very long output (15k characters)
-            const longOutput = 'x'.repeat(15_000);
+            // Simulate very long output (100k characters, exceeding 80k MAX_OUTPUT_LENGTH)
+            const longOutput = 'x'.repeat(100_000);
             setTimeout(() => stdoutCallback(Buffer.from(longOutput)), 5);
           }
           return mockChildProcess.stdout;
@@ -223,8 +279,8 @@ describe('ShellCommandCtr', () => {
         });
 
         expect(result.success).toBe(true);
-        // Output should be truncated to ~10k + truncation message
-        expect(result.stdout!.length).toBeLessThan(15_000);
+        // Output should be truncated to 80k + truncation message
+        expect(result.stdout!.length).toBeLessThan(100_000);
         expect(result.stdout).toContain('truncated');
         expect(result.stdout).toContain('more characters');
       });

package/changelog/v2.json

@@ -1,4 +1,22 @@
 [
+  {
+    "children": {
+      "fixes": [
+        "Add end-user info on OpenAI Responses API call, enable vertical scrolling for topic list on mobile."
+      ]
+    },
+    "date": "2026-02-08",
+    "version": "2.1.21"
+  },
+  {
+    "children": {
+      "fixes": [
+        "Add api/version and api/desktop to public routes, show notification when file upload fails due to storage plan limit."
+      ]
+    },
+    "date": "2026-02-08",
+    "version": "2.1.20"
+  },
   {
     "children": {
       "fixes": [

package/docs/development/basic/add-new-image-model.mdx

@@ -15,7 +15,7 @@ tags:
 
 ## Parameter Standardization
 
-All image generation models must use the standard parameters defined in `src/libs/standard-parameters/index.ts`. This ensures parameter consistency across different Providers, creating a more unified user experience.
+All image generation models must use the standard parameters defined in `packages/model-bank/src/standard-parameters/index.ts`. This ensures parameter consistency across different Providers, creating a more unified user experience.
 
 **Supported Standard Parameters**:
 
@@ -32,7 +32,7 @@ All image generation models must use the standard parameters defined in `src/lib
 
 These models can be requested using the OpenAI SDK, with request parameters and return values consistent with DALL-E and GPT-Image-X series.
 
-Taking Zhipu's CogView-4 as an example, which is an OpenAI-compatible model, you can add it by adding the model configuration in the corresponding AI models file `src/config/aiModels/zhipu.ts`:
+Taking Zhipu's CogView-4 as an example, which is an OpenAI-compatible model, you can add it by adding the model configuration in the corresponding AI models file `packages/model-bank/src/aiModels/zhipu.ts`:
 
 ```ts
 const zhipuImageModels: AIImageModelCard[] = [
@@ -71,7 +71,7 @@ Most Providers use `openaiCompatibleFactory` for OpenAI compatibility. You can p
 
 1. **Read Provider documentation and standard parameter definitions**
    - Review the Provider's image generation API documentation to understand request and response formats
-   - Read `src/libs/standard-parameters/index.ts` to understand supported parameters
+   - Read `packages/model-bank/src/standard-parameters/index.ts` to understand supported parameters
    - Add image model configuration in the corresponding AI models file
 
 2. **Implement custom createImage method**
@@ -87,7 +87,7 @@ Most Providers use `openaiCompatibleFactory` for OpenAI compatibility. You can p
 **Code Example**:
 
 ```ts
-// src/libs/model-runtime/provider-name/createImage.ts
+// packages/model-runtime/src/providers/<provider-name>/createImage.ts
 export const createProviderImage = async (
   payload: ImageGenerationPayload,
   options: any,
@@ -112,7 +112,7 @@ export const createProviderImage = async (
 ```
 
 ```ts
-// src/libs/model-runtime/provider-name/index.ts
+// packages/model-runtime/src/providers/<provider-name>/index.ts
 export const LobeProviderAI = openaiCompatibleFactory({
   constructorOptions: {
     // ... other configurations
@@ -130,7 +130,7 @@ If your Provider has an independent class implementation, you can directly add t
 
 1. **Read Provider documentation and standard parameter definitions**
    - Review the Provider's image generation API documentation
-   - Read `src/libs/standard-parameters/index.ts`
+   - Read `packages/model-bank/src/standard-parameters/index.ts`
    - Add image model configuration in the corresponding AI models file
 
 2. **Implement createImage method in Provider class**
@@ -144,7 +144,7 @@ If your Provider has an independent class implementation, you can directly add t
 **Code Example**:
 
 ```ts
-// src/libs/model-runtime/provider-name/index.ts
+// packages/model-runtime/src/providers/<provider-name>/index.ts
 export class LobeProviderAI {
   async createImage(
     payload: ImageGenerationPayload,

package/docs/development/basic/add-new-image-model.zh-CN.mdx

@@ -13,7 +13,7 @@ tags:
 
 ## 参数标准化
 
-所有图像生成模型都必须使用 `src/libs/standard-parameters/index.ts` 中定义的标准参数。这确保了不同 Provider 之间的参数一致性，让用户体验更加统一。
+所有图像生成模型都必须使用 `packages/model-bank/src/standard-parameters/index.ts` 中定义的标准参数。这确保了不同 Provider 之间的参数一致性，让用户体验更加统一。
 
 **支持的标准参数**：
 
@@ -30,7 +30,7 @@ tags:
 
 指的是可以使用 openai SDK 进行请求，并且请求参数和和返回值和 dall-e 以及 gpt-image-x 系列一致。
 
-以智谱的 CogView-4 为例，它是一个兼容 openai 请求格式的模型。你只需要在对应的 ai models 文件 `src/config/aiModels/zhipu.ts` 中，添加模型配置，例如：
+以智谱的 CogView-4 为例，它是一个兼容 openai 请求格式的模型。你只需要在对应的 ai models 文件 `packages/model-bank/src/aiModels/zhipu.ts` 中，添加模型配置，例如：
 
 ```ts
 const zhipuImageModels: AIImageModelCard[] = [
@@ -69,7 +69,7 @@ const zhipuImageModels: AIImageModelCard[] = [
 
 1. **阅读 Provider 官方文档和标准参数定义**
    - 查看 Provider 的图像生成 API 文档，了解请求格式和响应格式
-   - 阅读 `src/libs/standard-parameters/index.ts`，了解支持的参数
+   - 阅读 `packages/model-bank/src/standard-parameters/index.ts`，了解支持的参数
    - 在对应的 ai models 文件中增加 image model 配置
 
 2. **实现自定义的 createImage 方法**
@@ -85,7 +85,7 @@ const zhipuImageModels: AIImageModelCard[] = [
 **代码示例**：
 
 ```ts
-// src/libs/model-runtime/provider-name/createImage.ts
+// packages/model-runtime/src/providers/<provider-name>/createImage.ts
 export const createProviderImage = async (
   payload: ImageGenerationPayload,
   options: any,
@@ -110,7 +110,7 @@ export const createProviderImage = async (
 ```
 
 ```ts
-// src/libs/model-runtime/provider-name/index.ts
+// packages/model-runtime/src/providers/<provider-name>/index.ts
 export const LobeProviderAI = openaiCompatibleFactory({
   constructorOptions: {
     // ... 其他配置
@@ -128,7 +128,7 @@ export const LobeProviderAI = openaiCompatibleFactory({
 
 1. **阅读 Provider 官方文档和标准参数定义**
    - 查看 Provider 的图像生成 API 文档
-   - 阅读 `src/libs/standard-parameters/index.ts`
+   - 阅读 `packages/model-bank/src/standard-parameters/index.ts`
    - 在对应的 ai models 文件中增加 image model 配置
 
 2. **在 Provider 类中实现 createImage 方法**
@@ -142,7 +142,7 @@ export const LobeProviderAI = openaiCompatibleFactory({
 **代码示例**：
 
 ```ts
-// src/libs/model-runtime/provider-name/index.ts
+// packages/model-runtime/src/providers/<provider-name>/index.ts
 export class LobeProviderAI {
   async createImage(
     payload: ImageGenerationPayload,

package/docs/development/basic/architecture.mdx

@@ -1,50 +1,114 @@
 ---
 title: Architecture Design
 description: >-
-  Explore the architecture of LobeHub, an AI chat app built on Next.js,
-  featuring frontend, APIs, and markets.
+  Explore the architecture of LobeHub, an open-source AI Agent platform
+  built on Next.js, covering frontend, backend, runtime, and data storage.
 tags:
   - LobeHub
-  - AI Chat Application
-  - Next.js
   - Architecture Design
-  - Frontend Development
+  - Agent Platform
+  - Next.js
 ---
 
 # Architecture Design
 
-LobeHub is an AI chat application built on the Next.js framework, aiming to provide an AI productivity platform that enables users to interact with AI through natural language. The following is an overview of the architecture design of LobeHub:
+LobeHub is an open-source AI Agent platform built on Next.js, enabling users to interact with AI through natural language, use tools, manage knowledge bases, and more. The following is an overview of LobeHub's architecture design.
 
 ## Application Architecture Overview
 
-The overall architecture of LobeHub consists of the frontend, EdgeRuntime API, Agents Market, Plugin Market, and independent plugins. These components collaborate to provide a complete AI experience.
+The overall architecture of LobeHub consists of the following core layers:
+
+```plaintext
++---------------------+--------------------------------------------------+
+| Layer               | Description                                      |
++---------------------+--------------------------------------------------+
+| Frontend            | Next.js RSC + React Router DOM hybrid SPA        |
+| Backend API         | RESTful WebAPI + tRPC Routers                    |
+| Runtime             | Model Runtime + Agent Runtime                    |
+| Auth                | Better Auth (email/password + SSO)               |
+| Data Storage        | PostgreSQL + Redis + S3                          |
+| Marketplace         | Agent Market + MCP Tool Market                   |
++---------------------+--------------------------------------------------+
+```
 
 ## Frontend Architecture
 
-The frontend of LobeHub adopts the Next.js framework, leveraging its powerful server-side rendering (SSR) capability and routing functionality. The frontend utilizes a stack of technologies, including the antd component library, lobe-ui AIGC component library, zustand state management, swr request library, i18next internationalization library, and more. These technologies collectively support the functionality and features of LobeHub.
+The frontend uses the Next.js framework with a **Next.js RSC + React Router DOM hybrid routing** approach: Next.js App Router handles server-rendered pages (e.g., auth pages), while React Router DOM powers the main SPA.
+
+Key tech stack:
+
+- **UI Components**: `@lobehub/ui`, antd
+- **CSS-in-JS**: antd-style
+- **State Management**: zustand (slice pattern)
+- **Data Fetching**: SWR + tRPC
+- **i18n**: react-i18next
+
+Frontend code is organized by responsibility under `src/`. See [Directory Structure](/docs/development/basic/folder-structure) for details.
+
+## Backend API
+
+The backend provides two API styles:
+
+- **RESTful WebAPI** (`src/app/(backend)/webapi/`): Handles endpoints requiring special processing such as chat streaming, TTS, and file serving
+- **tRPC Routers** (`src/server/routers/`): Type-safe main business routes, grouped by runtime:
+  - `lambda/` — Main business (agent, session, message, topic, file, knowledge, settings, etc.)
+  - `async/` — Long-running async operations (file processing, image generation, RAG evaluation)
+  - `tools/` — Tool invocations (search, MCP, market)
+  - `mobile/` — Mobile-specific routes
+
+## Runtime
+
+### Model Runtime
+
+`@lobechat/model-runtime` (`packages/model-runtime/`) is the LLM API adapter layer that normalizes API differences across 30+ AI providers (OpenAI, Anthropic, Google, Bedrock, Ollama, etc.), providing a unified calling interface. Each provider has its own adapter implementation. It is stateless — each call is independent.
+
+### Agent Runtime
+
+`@lobechat/agent-runtime` (`packages/agent-runtime/`) is the agent orchestration engine that sits above Model Runtime, driving the full lifecycle of multi-step AI agent behavior:
 
-The components in the frontend architecture include app, components, config, const, features, helpers, hooks, layout, locales, migrations, prompts, services, store, styles, types, and utils. Each component has specific responsibilities and collaborates with others to achieve different functionalities.
+- **Plan-Execute Loop**: Core state machine cycling through LLM calls → tool execution → result processing
+- **Tool Invocation & Batch Execution**: Supports single and batch tool calls
+- **Human-in-the-Loop**: Security checks and human approval flows
+- **Context Compression**: Manages context window limits
+- **Usage & Cost Tracking**: Accumulates token usage and monetary costs
+- **Multi-Agent Orchestration**: `GroupOrchestrationRuntime` supports Supervisor + Executor pattern for multi-agent collaboration
 
-## Edge Runtime API
+In short: Model Runtime handles "how to communicate with an LLM provider"; Agent Runtime handles "how to run a complete agent using LLMs, tools, and human approvals."
 
-The Edge Runtime API is one of the core components of LobeHub, responsible for handling the core logic of AI conversations. It provides interaction interfaces with the AI engine, including natural language processing, intent recognition, and response generation. The EdgeRuntime API communicates with the frontend, receiving user input and returning corresponding responses.
+## Authentication
 
-## Agents Market
+LobeHub uses [Better Auth](https://www.better-auth.com/) as the authentication framework, supporting:
 
-The Agents Market is a crucial part of LobeHub, providing various AI agents for different scenarios to handle specific tasks and domains. The Agents Market also offers functionality for discovering and uploading agents, allowing users to find agents created by others and easily share their own agents in the market.
+- Email + password registration and login
+- SSO single sign-on (GitHub, Google, and various OAuth providers)
 
-## Plugin Market
+Auth configuration is in `src/auth.ts`, with related routes under `src/app/(backend)/api/`.
 
-The Plugin Market is another key component of LobeHub, offering various plugins to extend the functionality and features of LobeHub. Plugins can be independent functional modules or integrated with agents from the Agents Market. During conversations, the assistant automatically identifies user input, recognizes suitable plugins, and passes them to the corresponding plugins for processing and returns the results.
+## Data Storage
 
-## Security and Performance Optimization
+```plaintext
++---------------+----------------------------------------------+
+| Storage       | Usage                                        |
++---------------+----------------------------------------------+
+| PostgreSQL    | Primary database for users, sessions,        |
+|               | messages, agent configs, etc.                |
+| Redis         | Caching, session state, rate limiting        |
+| S3            | File storage (uploads, images, knowledge     |
+|               | base files, etc.)                            |
++---------------+----------------------------------------------+
+```
 
-LobeHub's security strategy includes authentication and permission management. Users need to authenticate before using LobeHub, and operations are restricted based on the user's permissions.
+Database operations use Drizzle ORM, with schemas defined in `packages/database/src/schemas/`.
 
-To optimize performance, LobeHub utilizes Next.js SSR functionality to achieve fast page loading and response times. Additionally, a series of performance optimization measures are implemented, including code splitting, caching, and resource compression.
+## Marketplace
 
-## Development and Deployment Process
+- **Agent Market**: Provides AI agents for various scenarios; users can discover, use, and share agents
+- **MCP Tool Market**: Discover and integrate MCP tools to extend agent capabilities
 
-LobeHub's development process includes version control, testing, continuous integration, and continuous deployment. The development team uses version control systems for code management and conducts unit and integration testing to ensure code quality. Continuous integration and deployment processes ensure rapid delivery and deployment of code.
+## Development and Deployment
 
-The above is a brief introduction to the architecture design of LobeHub, detailing the responsibilities and collaboration of each component, as well as the impact of design decisions on application functionality and performance.
+- **Version Control**: Git + GitHub, gitmoji commit conventions
+- **Code Quality**: ESLint, Stylelint, TypeScript type checking, circular dependency detection (dpdm), dead code detection (knip)
+- **Testing**: Vitest unit tests + Cucumber/Playwright E2E tests
+- **CI/CD**: GitHub Actions for automated testing, building, and releasing
+- **Deployment**: Supports Vercel, Docker, and self-hosting on major cloud platforms