### Frontend Project Setup and Start with NPM

Source: https://context7.com/context7/doc_bella_top/llms.txt

This snippet shows how to install project dependencies and start the frontend development server using npm. This is a standard procedure for Node.js-based frontend applications.

```bash
cd frontend npm install npm start
```

--------------------------------

### Clone and Run Bella-Knowledge with Docker Compose

Source: https://doc.bella.top/docs/bella-knowledge/intro

This snippet demonstrates how to clone the bella-knowledge project from GitHub and start it using Docker Compose. It's the recommended way for quick setup and deployment. Ensure Docker and Docker Compose are installed.

```bash
git clone https://github.com/LianjiaTech/bella-knowledge.git
cd bella-knowledge
cd docker
docker-compose up -d
```

--------------------------------

### Authorize Admin Script Execution

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

This script is used to authorize administrator users after the system is initialized. It can be run manually or may be triggered automatically during the initial system setup. It guides the user through the authorization process.

```shell
./authorize-admin.sh
```

--------------------------------

### Advanced WebSocket Configuration with Jinja2 (JSON)

Source: https://doc.bella.top/docs/bella-openapi/core/realtime

An advanced configuration example for the WebSocket start message, demonstrating the use of Jinja2 templating for message rewriting with main and worker LLM models. It also includes TTS options.

```json
{
  "llm_option": {
    "main": {
      "model": "qwen2.5-coder:3b",
      "sys_prompt": "你是一个全能的语音助理，你的回复会转成音频给用户，所以请尽可能简洁的回复，同时首句话尽快结束以便更好的进行流式合成语音。"
    },
    "workers": [
      {
        "model": "qwen2.5-coder:3b",
        "blocking": true,
        "variable_name": "rewrite_user_message",
        "sys_prompt": "你是一个user message rewrite专家，负责将基于voice转录的用户消息进行改写，让其更通顺和连贯，同时完成必须的指代消歧。不要解释，直接改写，如果不需要改写，则直接输出用户的原始内容",
        "prompt": "## 用户历史对话\n<history_messages>\n{% for message in history_messages %}\n{% if message.role == \"user\" %}\n  <user timestamp=\"{{loop.index}}\">{{{ message.content }}}</user>\n{% elif message.role == \"assistant\" %}\n  <agent timestamp=\"{{loop.index}}\">{{{ message.content }}}</agent>\n{% endif %}\n{% endfor %}\n\n</history_messages>\n\n## 用户最新消息\n<user_message>\n  {{user_message}}\n</user_message>\n\n请进行消息改写吧！\n"
      }
    ]
  },
  "tts_option": {
    "model": "chat-tts",
    "voice": "zh_female",
    "sample_rate": 24000
  }
}
```

--------------------------------

### Install Document Parser Library

Source: https://doc.bella.top/docs/bella-domify/standalone-quick-start

This snippet shows the command to install the document_parser library using pip. Ensure you have Python 3.9 or higher installed.

```shell
pip install document_parser
```

--------------------------------

### Tool Use Request Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

An example of a request configured for tool use, allowing the model to call functions.

```APIDOC
## Tool Use Request Example

### Description
Demonstrates how to configure the API for tool usage, enabling the model to call predefined functions.

### Method
POST (Assumed)

### Endpoint
/chat/completions (Assumed)

### Request Body
```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市名称，如北京、上海"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位"
            }
          },
          "required": ["location"]
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}
```
```

--------------------------------

### Install Claude Code Agent via npm

Source: https://doc.bella.top/en/docs/claude-code/introduce/use-in-ide

This snippet shows the command to install the Claude Code agent globally using npm. Ensure you have Node.js and npm installed.

```bash
npm install -g @anthropic-ai/claude-code  

```

--------------------------------

### Basic Request Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

A sample request demonstrating a basic chat completion interaction.

```APIDOC
## Basic Request Example

### Description
Shows a standard request to the chat completions endpoint.

### Method
POST (Assumed)

### Endpoint
/chat/completions (Assumed)

### Request Body
```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "你好，请介绍一下自己。"
    }
  ],
  "temperature": 0.7,
  "stream": false
}
```
```

--------------------------------

### Python Client Example for Document Parsing

Source: https://doc.bella.top/en/docs/bella-openapi/core/document-parse

This Python code snippet provides a basic example of how to use the `requests`, `json`, and `time` libraries to interact with the document parsing API. It sets up necessary imports and includes placeholder comments for further implementation.

```python
import requests
import json
import time

```

--------------------------------

### Tool Use Response Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

An example of a response where the model decides to call a tool, including the `tool_calls` field.

```APIDOC
## Tool Use Response Example

### Description
Illustrates a response where the model indicates a need to call a tool, featuring the `tool_calls` field.

### Method
POST (Assumed)

### Endpoint
/chat/completions (Assumed)

### Response Example (Success - 200)
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "reasoning_content": "用户询问北京的天气，我需要调用",
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"北京\",\"unit\":\"celsius\"}"
          }
        }
      ]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 25,
    "total_tokens": 107
  }
}
```
```

--------------------------------

### Tool Call Request Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

An example of a request that utilizes the tool-calling capability. It defines a `get_weather` function that the model can call to retrieve weather information for a specified location and unit.

```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市名称，如北京、上海"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位"
            }
          },
          "required": ["location"]
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}
```

--------------------------------

### Streaming Tool Call Response Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

This example shows the raw streaming output received when a tool call is made. The response is broken down into multiple chunks, with each chunk containing a part of the tool call or reasoning. This allows for real-time processing of tool call initiation and argument construction.

```json
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"reasoning_content":"用户询问北京的天气，我需要调用"},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"reasoning_content":"天气查询函数来获取这一信息。"},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_abc123","type":"function","function":{"name":"get_weather"}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\""}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"location"}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\":\""}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"北京"}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\",\""}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"unit"}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\":\""}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"celsius"}}]},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"}"}}]}},"finish_reason":null}]}
  
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","system_fingerprint":"fp_44709d6fcb","usage":{"prompt_tokens": 1042,"completion_tokens": 65,"total_tokens": 1107},"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}
  
data: [DONE]  
```

--------------------------------

### Submit Tool Results Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

This JSON example demonstrates how to submit the results of a tool's execution back into the conversation flow. It shows the structure for a user message, an assistant's tool call, and the subsequent tool result being sent.

```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"北京\",\"unit\":\"celsius\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "name": "get_weather",
      "content": "{\"temperature\":32,\"unit\":\"celsius\",\"description\":\"晴朗\",\"humidity\":45}"
    }
  ]
}
```

--------------------------------

### Initiating Sub-agent Manager

Source: https://doc.bella.top/docs/claude-code/case/sub-agents-use

Command to start the sub-agent manager interface within the Claude Code environment.

```bash
/agents
```

--------------------------------

### Tool Result Submission Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

Shows how to submit the result of a tool execution back to the conversation. Includes the model, messages, and tool call information.

```APIDOC
## POST /api/chat/completions

### Description
Submits the result of a tool execution to the conversation.  This allows the model to incorporate the tool's output into its response.

### Method
POST

### Endpoint
/api/chat/completions

### Request Body
- **model** (string) - Required - The name of the model being used (e.g., "gpt-4o").
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the message sender (e.g., "user", "assistant", "tool").
  - **content** (string) - Optional - The content of the message. Null if the assistant is calling a tool.
  - **tool_calls** (array) - Optional - An array of tool call objects.
    - **id** (string) - Required - The ID of the tool call.
    - **type** (string) - Required - The type of tool call (e.g., "function").
    - **function** (object) - Required - Information about the function to be called.
      - **name** (string) - Required - The name of the function.
      - **arguments** (string) - Required - A JSON string containing the arguments for the function.
  - **tool_call_id** (string) - Optional - The ID of the tool call that this message is responding to.
  - **name** (string) - Optional - The name of the tool that was called.

### Request Example
```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"北京\",\"unit\":\"celsius\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "name": "get_weather",
      "content": "{\"temperature\":32,\"unit\":\"celsius\",\"description\":\"晴朗\",\"humidity\":45}"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the chat completion.
- **object** (string) - The type of object returned (e.g., "chat.completion").
- **created** (integer) - The timestamp of when the chat completion was created.
- **model** (string) - The model used for the chat completion.
- **system_fingerprint** (string) - A fingerprint of the system used.
- **choices** (array) - An array of choice objects.
  - **index** (integer) - The index of the choice.
  - **message** (object) - The message object.
    - **role** (string) - The role of the message sender (e.g., "assistant").
    - **content** (string) - The content of the message.
    - **reasoning_content** (string) - Explanation behind the content.
  - **finish_reason** (string) - The reason the chat completion finished (e.g., "stop").
- **usage** (object) - Usage statistics.
  - **prompt_tokens** (integer) - The number of tokens in the prompt.
  - **completion_tokens** (integer) - The number of tokens in the completion.
  - **total_tokens** (integer) - The total number of tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-456",
  "object": "chat.completion",
  "created": 1677652290,
  "model": "gpt-4o",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "北京今天的天气晴朗，气温32°C，湿度45%。天气较热，建议做好防晒措施，多补充水分。",
      "reasoning_content": "根据天气API返回的数据，北京今天天气晴朗，温度32摄氏度，湿度45%。这属于较热的天气，应该提醒用户注意防晒和补水。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 110,
    "completion_tokens": 42,
    "total_tokens": 152
  }
}
```
```

--------------------------------

### Qwen Deep Reasoning

Source: https://doc.bella.top/docs/bella-openapi/features/thinking

Example of using the Qwen protocol to enable deep reasoning, requiring a streaming request.

```APIDOC
## 通义千问 Deep Reasoning

*   Only supports streaming requests when enabling deep reasoning

**Qwen Protocol Method:**

```
{
  "model": "qwen3-235b-a22b",
  "messages": [
    {
      "role": "user",
      "content": "Please solve this logical problem step by step..."
    }
  ],
  "enable_thinking": true,
  "stream": true
}
```

```

--------------------------------

### Image Input Response Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

This JSON shows a typical response from the model when processing an image input. It includes the assistant's generated content, describing the image, and reasoning content, explaining how the description was formulated.

```json
{
  "id": "chatcmpl-789",
  "object": "chat.completion",
  "created": 1677652295,
  "model": "gpt-4o",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "这张图片展示了一只橙色的猫咪坐在窗台上，望向窗外。窗外可以看到一些绿色的树木和蓝色的天空。猫咪看起来很放松，尾巴卷曲在身体旁边。",
      "reasoning_content": "图片中有一只橙色的猫，它坐在窗台上看向窗外。我可以看到窗外有树木和天空。猫咪的姿势显示它很放松。我应该详细描述我看到的内容，包括猫的颜色、位置、周围环境和姿态。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 1042,
    "completion_tokens": 65,
    "total_tokens": 1107
  }
}
```

--------------------------------

### Image Input Example

Source: https://doc.bella.top/docs/bella-openapi/core/chat-completions

Demonstrates how to include images in user messages, specifying the image URL and detail level. Supports both internet accessible URLs and Base64 encoded image data.

```APIDOC
## POST /api/chat/completions

### Description
Submits an image as part of the user message to be processed.  Allows the model to analyze the image and incorporate its content into the response.

### Method
POST

### Endpoint
/api/chat/completions

### Request Body
- **model** (string) - Required - The name of the model being used (e.g., "gpt-4o").
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the message sender ("user").
  - **content** (array) - Required - An array containing the text and image url objects.
    - **type** (string) - Required - The type of content (e.g., "text", "image_url").
    - **text** (string) - Optional - The text content.
    - **image_url** (object) - Optional - The image URL object.
      - **url** (string) - Required - The URL of the image (either internet accessible or Base64 encoded).
      - **detail** (string) - Optional - The detail level for image analysis ("high", "low", or "auto").

### Request Example
```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "这张图片是什么内容？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg",
            "detail": "high"
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the chat completion.
- **object** (string) - The type of object returned (e.g., "chat.completion").
- **created** (integer) - The timestamp of when the chat completion was created.
- **model** (string) - The model used for the chat completion.
- **system_fingerprint** (string) - A fingerprint of the system used.
- **choices** (array) - An array of choice objects.
  - **index** (integer) - The index of the choice.
  - **message** (object) - The message object.
    - **role** (string) - The role of the message sender (e.g., "assistant").
    - **content** (string) - The content of the message.
    - **reasoning_content** (string) - Explanation behind the content.
  - **finish_reason** (string) - The reason the chat completion finished (e.g., "stop").
- **usage** (object) - Usage statistics.
  - **prompt_tokens** (integer) - The number of tokens in the prompt.
  - **completion_tokens** (integer) - The number of tokens in the completion.
  - **total_tokens** (integer) - The total number of tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-789",
  "object": "chat.completion",
  "created": 1677652295,
  "model": "gpt-4o",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "这张图片展示了一只橙色的猫咪坐在窗台上，望向窗外。窗外可以看到一些绿色的树木和蓝色的天空。猫咪看起来很放松，尾巴卷曲在身体旁边。",
      "reasoning_content": "图片中有一只橙色的猫，它坐在窗台上看向窗外。我可以看到窗外有树木和天空。猫咪的姿势显示它很放松。我应该详细描述我看到的内容，包括猫的颜色、位置、周围环境和姿态。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 1042,
    "completion_tokens": 65,
    "total_tokens": 1107
  }
}
```
```

--------------------------------

### Authentication Header Example

Source: https://doc.bella.top/docs/bella-rag/api

This code snippet shows the required Authorization header for API authentication. It includes a placeholder for your OPEN_API_KEY, which must be replaced with your actual key.

```text
Authorization: Bearer {OPEN_API_KEY}
```

--------------------------------

### Configure Claude Code Permissions

Source: https://doc.bella.top/en/docs/claude-code/introduce/use-in-ide

Example of granting Claude Code permissions to edit and write files within the IDE. This is configured in the `~/.claude/settings.json` file. Use with caution.

```json
"Edit(**)",  
      "Write(**)"  

```

--------------------------------

### Execute Start Script with Options

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

This script initiates the service and can be used for building and pushing Docker images. It supports options for skipping authentication, building images, pushing to a registry, and specifying version numbers. Requires Docker and appropriate registry credentials.

```shell
./start.sh
./start.sh --skip-auth
./start.sh --build --push --registry 用户名 --version v1.0.0
./start.sh --registry 用户名 --version v1.0.0
./start.sh --registry 用户名 --version v1.1.0 --github-oauth CLIENT_ID:CLIENT_SECRET --google-oauth CLIENT_ID:CLIENT_SECRET --server http://example.com
```

--------------------------------

### Docker Image Management

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

Instructions for building, pushing, and deploying Docker images for the Bella Top project. This enables efficient deployment in production environments.

```APIDOC
## Docker Image Management

### Push Docker Images
To facilitate deployment in production environments, you can build and push Docker images locally to Docker Hub or other repositories. This allows you to pull and start these images directly on servers without building them on-site.

### Build and Push Images
```bash
# Build and push images to Docker Hub
./start.sh --build --push --registry <your-dockerhub-username> --version v1.0.0
```

**Parameter Description:**
*   `--build`: Builds the Docker image.
*   `--push`: Pushes the image to the registry after building.
*   `--registry <your-dockerhub-username>`: Specifies your Docker Hub username.
*   `--version v1.0.0`: Specifies the image version (defaults to `v1.0.0`).

Executing this command will:
1.  Build Docker images for the API and Web services.
2.  Tag the images as `<your-dockerhub-username>/bella-openapi-api:v1.0.0` and `<your-dockerhub-username>/bella-openapi-web:v1.0.0`.
3.  Simultaneously tag them as `<your-dockerhub-username>/bella-openapi-api:latest` and `<your-dockerhub-username>/bella-openapi-web:latest`.
4.  Push these images to Docker Hub.

### Deploy on Production Server
On the production server, you can start the service using the pushed images directly:

```bash
# Pull and start pushed images
./start.sh --registry <your-dockerhub-username> --version v1.0.0
```

This command pulls the specified version of the image from Docker Hub and starts the service, eliminating the need for an on-server build process and significantly reducing deployment time and resource consumption.

### Use Specific Version Images
If you need to use a specific version of the image, specify it using the `--version` parameter:

```bash
# Use a specific version image and configure your own login options
./start.sh --registry <your-dockerhub-username> --version v1.1.0 --github-oauth CLIENT_ID:CLIENT_SECRET --google-oauth CLIENT_ID:CLIENT_SECRET --server http://example.com
```

### Notes
1.  Ensure you are logged into Docker Hub:
    ```bash
    docker login
    ```
2.  Before pushing images, ensure you have sufficient permissions to access the specified Docker Hub repository.
3.  In production environments, it is recommended to use specific version numbers instead of the `latest` tag to ensure deployment consistency and traceability.
4.  If using a private Docker registry, adjust the `--registry` parameter accordingly.
```

--------------------------------

### System API Key Generation and Management

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

This section details the process of generating, checking, and managing system API keys. It explains how the script interacts with the database, saves keys to a file, and emphasizes the importance of security.

```APIDOC
## System API Key Generation and Management

### Description
This process involves checking for an existing system API key in the database. If none exists, a new one is generated and stored. If it already exists, its information is displayed. The API key details are also saved to a `system-apikey.txt` file.

**Important Notes:**
*   System API Keys have the highest privileges; keep them secure.
*   API Keys are only displayed once upon generation; subsequent views will show a masked version.
*   If an API Key is lost, a new one must be generated. For system keys, the old one needs to be invalidated before generating a new one.
*   Generated API Keys have the `all` role, granting access to all endpoints.
*   The script must run within a Docker environment and will automatically connect to the MySQL container.

### Example Output
```
正在生成系统API key...
检查数据库中是否已存在系统API key...
在数据库中插入新的系统API key...
成功生成并插入系统API key到数据库。
API Key Code: ak-026e84f5-8a1c-4243-a800-d44581f0f1b7
API Key: 9be9d54d-d4ae-4510-8819-a62a4e69e57b
API Key SHA-256: d58ed6447aa8da22d6fa3064d242f8f8dd74a6df4a1663084f4003b2d559b9ea
API Key Display: 9b****e57b
API key详细信息已保存到 system-apikey.txt
重要: 请妥善保管此信息，API key只会显示一次！
完成。
```
```

--------------------------------

### Sub-agent Configuration for Comprehensive Code Quality Improvement

Source: https://doc.bella.top/en/docs/claude-code/case/sub-agents-use

Example sub-agent setup for improving code quality across multiple dimensions. It lists specialized agents for security auditing, performance analysis, and adherence to code quality standards and best practices.

```plain text
子代理配置：    
- security-auditor: 专业安全漏洞检测  
- performance-analyzer: 性能瓶颈识别和优化  
- code-quality-guardian: 代码规范和最佳实践  
```

--------------------------------

### Administrator Authorization

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

This section outlines the procedure for authorizing administrator users after system initialization. It covers both automated authorization during service startup and manual authorization using scripts or cURL commands.

```APIDOC
## Administrator Authorization

### Description
After system initialization, administrators need to be authorized. Administrators can manage API Keys, user permissions, and other system resources. The authorization process can be initiated automatically upon service startup or performed manually.

### Authorization Flow
1.  **Start the Service and Generate System API Key:**
    ```bash
    ./start.sh
    ```
    If a new system API key is generated, the administrator authorization process will begin automatically. To skip this prompt during startup (while still checking for API key generation), use the `--skip-auth` flag:
    ```bash
    ./start.sh --skip-auth
    ```
    *Note: If an API key already exists, the script will skip the administrator authorization step. Authorization is only prompted when a new API key is generated.* 

2.  **Follow Prompts:** The script will ask if you want to authorize an administrator. 
    *   Select 'Yes' to proceed with the guided authorization flow.
    *   Select 'No' to complete authorization later manually.
    *   The `--skip-auth` flag bypasses this prompt entirely.

3.  **Log in to Frontend:** Access the frontend page (`http://localhost:3000`) using a third-party account (e.g., Google, GitHub) to obtain a User ID or email address. Click on your avatar in the top right corner to view your profile information.

4.  **Input User Information:** The authorization script will prompt you to enter the User ID or email address obtained in the previous step.

5.  **Manual Authorization (Later):** If you need to authorize an administrator later, run:
    ```bash
    ./authorize-admin.sh
    ```

6.  **Log out and Log in:** After authorization, log out of the system and log back in to gain administrator privileges.

### Manual Authorization using cURL

#### Authorize by User ID
```bash
curl --location 'http://localhost:8080/console/userInfo/manager' \
--header 'Authorization: Bearer YOUR_SYSTEM_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "managerAk": "YOUR_SYSTEM_API_KEY_CODE",
    "userId": YOUR_USER_ID,
    "userName": "YOUR_USER_NAME"
}'
```

#### Authorize by Email
```bash
curl --location 'http://localhost:8080/console/userInfo/manager' \
--header 'Authorization: Bearer YOUR_SYSTEM_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "managerAk": "YOUR_SYSTEM_API_KEY_CODE",
    "source": "google",
    "email": "YOUR_EMAIL@gmail.com",
    "userId": 0,
    "userName": "YOUR_USER_NAME"
}'
```
```

--------------------------------

### Manual Administrator Authorization with Curl

Source: https://doc.bella.top/docs/bella-openapi/startup-deployment-details

These examples demonstrate how to manually authorize an administrator user using curl commands. They require the system API key and either user ID or email for authorization. Ensure correct API key and user details are provided.

```shell
curl --location 'http://localhost:8080/console/userInfo/manager' \
--header 'Authorization: Bearer YOUR_SYSTEM_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{ \
    "managerAk": "YOUR_SYSTEM_API_KEY_CODE", \
    "userId": YOUR_USER_ID, \
    "userName": "YOUR_USER_NAME" \
}'

curl --location 'http://localhost:8080/console/userInfo/manager' \
--header 'Authorization: Bearer YOUR_SYSTEM_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{ \
    "managerAk": "YOUR_SYSTEM_API_KEY_CODE", \
    "source": "google", \
    "email": "YOUR_EMAIL@gmail.com", \
    "userId": 0, \
    "userName": "YOUR_USER_NAME" \
}'
```

--------------------------------

### Basic IDE Configuration File for Claude Code

Source: https://doc.bella.top/en/docs/claude-code/introduce/use-in-ide

A minimal example of the `settings.json` file for Claude Code, located at `~/.claude/settings.json`. It includes essential API settings and model configurations.

```json
{
  "ANTHROPIC_BASE_URL": "YOUR_BELLA_OPENAPI_URL",
  "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
  "ANTHROPIC_MODEL": "claude-3-opus-20240229",
  "ANTHROPIC_SMALL_FAST_MODEL": "claude-3-haiku-20240307",
  "permissions": [
    "Edit(**)",
    "Write(**)"
  ]
}

```

--------------------------------

### GET /v1/files/{file_id}/url

Source: https://doc.bella.top/docs/bella-knowledge/api/files/url

Fetches the URL for a specified file, enabling direct download. Optionally, you can set an expiration time for the URL.

```APIDOC
## GET /v1/files/{file_id}/url

### Description
Retrieves the URL for a specific file based on its ID. This URL can be used to download the file. An optional query parameter allows setting the expiration time for the generated URL.

### Method
GET

### Endpoint
`https://{{Host}}/v1/files/{file_id}/url`

### Parameters
#### Path Parameters
- **file_id** (string) - Required - The ID of the file for which to retrieve the URL.

#### Query Parameters
- **expires** (string) - Optional - The expiration time for the URL in seconds. If not provided, the default expiration is 1 day. This is applicable for signed URLs.

### Request Example
```bash
curl -L 'https://{{Host}}/v1/files/{file_id}/url' \
  -H 'Authorization: Bearer $OPEN_API_KEY'
```

### Response
#### Success Response (200)
- **url** (string) - The URL that can be used to download the file.

#### Response Example
```json
{
  "url": "http://test-storage.lianjia.com/test/assistants/file-2412171824220019000001-277459125.jpg"
}
```
```

--------------------------------

### Create a Run Request Sample

Source: https://doc.bella.top/en/api-docs/bella-assistants

This is a sample JSON payload for creating a run. It includes optional metadata for tracking purposes. The specific properties within metadata can be customized as needed.

```json
{
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}
```

--------------------------------

### RAG Chat Request Example

Source: https://doc.bella.top/docs/bella-rag/api

Example JSON request for the RAG chat API. It details parameters like query, scope, user, response type, model, and the RAG mode.

```json
{
    "query": "机器学习的主要算法有哪些？",
    "scope": [{
        "type": "file",
        "ids": ["file_123", "file_456"]
    }],
    "user": "user_00000000",
    "response_type": "stream",
    "model": "gpt-4o",
    "mode": "deep"
}
```

--------------------------------

### Knowledge Search Request Example

Source: https://doc.bella.top/docs/bella-rag/api

An example JSON request body for the knowledge search API. It includes the query, scope (specifying type and IDs), limit, user, and search mode.

```json
{
    "query": "机器学习的主要算法有哪些？",
    "scope": [{
        "type": "file",
        "ids": ["file_123", "file_456"]
    }],
    "limit": 5,
    "user": "user_00000000",
    "mode": "normal"
}
```

--------------------------------

### Knowledge Search Response Example

Source: https://doc.bella.top/docs/bella-rag/api

Example JSON response structure for the knowledge search API. It includes a status code, message, total results, and a list of documents with their text, score, and annotation.

```json
{
  "code": 0,
  "message": "Success",
  "data": {
    "total": 10,
    "docs": [
      {
        "type": "text",
        "text": "召回文本内容...",
        "score": 0.92,
        "annotation": {
          "file_id": "12345",
          "file_name": "example_document.txt",
          "paths": [[1, 12, 1], [1, 12, 2]]
        }
      }
    ]
  }
}
```

--------------------------------

### Clone Project and Backend Deployment with Git and CDK

Source: https://context7.com/context7/doc_bella_top/llms.txt

This snippet demonstrates cloning the project repository using Git and deploying the backend infrastructure using AWS CDK. The deployment requires specifying an allowed IP address for security.

```bash
git clone  cd amazon-bedrock-rag
cd backend npm install
cdk deploy --context allowedip="xxx.xxx.xxx.xxx/32"
```

--------------------------------

### File Upload API Response Example

Source: https://doc.bella.top/docs/bella-knowledge/api/files/upload

This is an example of a successful response from the file upload API. It includes details about the uploaded file such as its ID, object type, size in bytes, creation timestamp, original filename, and purpose.

```json
{
    "id": "file-2412182151040021019136-277459125",
    "object": "file",
    "bytes": 640549,
    "created_at": 1734529865000,
    "filename": "test.jpg",
    "purpose": "vision"
}
```

--------------------------------

### Create Directory API Request Example (cURL)

Source: https://doc.bella.top/docs/bella-knowledge/api/files/mkdir

This snippet demonstrates how to create a directory using the BellaTop API via a cURL request. It includes the endpoint, necessary headers (Authorization and Content-Type), and the JSON payload specifying the directory name and its ancestor ID.

```bash
curl --location 'http(s)://{{Host}}/v1/files/mkdir' \
--header 'Authorization: Bearer $OPEN_API_KEY' \
--header 'Content-Type: application/json' \
--data '{  
    "name": "${name_of_the_directory}",  
    "ancestor_id": null  
}'
```

--------------------------------

### Explicit Sub-agent Invocation Examples

Source: https://doc.bella.top/en/docs/claude-code/case/sub-agents-use

Examples of how to explicitly invoke specific sub-agents for targeted tasks. These commands demonstrate direct interaction with specialized agents for code review and query performance checks.

```bash
> 让代码审查代理分析我的最新提交  
> 使用性能优化代理检查这个查询  
```