### Quick start installation for WeKnora MCP Server

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Install dependencies, set environment variables, and start the server. This is a streamlined process for getting started quickly.

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 设置环境变量
export WEKNORA_BASE_URL="http://localhost:8080/api/v1"
export WEKNORA_API_KEY="your_api_key"

# 3. 启动服务器
python main.py
```

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

### Install and Start WeKnora Services

Source: https://github.com/tencent/weknora/blob/main/README_CN.md

Clone the repository, configure the environment variables by copying the example file, and start the core services using Docker Compose. Access the Web UI at http://localhost after successful startup.

```bash
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env   # 按需编辑 .env，详见文件内注释
docker compose up -d   # 启动核心服务
```

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

### Install WeKnora CLI from Source

Source: https://github.com/tencent/weknora/blob/main/cli/README.md

Steps to clone the repository, build the CLI, and install it to the system path.

```bash
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora/cli
go build -o weknora .
sudo mv weknora /usr/local/bin/   # or anywhere on $PATH
```

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

### Start Development Infrastructure

Source: https://github.com/tencent/weknora/blob/main/README_CN.md

Use this command to start the necessary infrastructure for development. This is part of the recommended fast development mode.

```bash
make dev-start
```

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

### Start Backend with Development Script

Source: https://github.com/tencent/weknora/blob/main/docs/快速开发模式说明.md

Execute this script in the second terminal to start the backend application.

```bash
./scripts/dev.sh app
```

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

### Local Apache Doris Setup with Docker

Source: https://github.com/tencent/weknora/blob/main/docs/使用其他向量数据库.md

Provides the command to start Apache Doris locally using Docker Compose and the command to create the necessary database if it doesn't exist.

```bash
docker compose --profile doris up -d
docker exec -it WeKnora-doris-fe mysql -h 127.0.0.1 -P 9030 -uroot \
    -e "CREATE DATABASE IF NOT EXISTS weknora;"
```

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

### Start Neo4j with Docker Compose

Source: https://github.com/tencent/weknora/blob/main/docs/KnowledgeGraph.md

Use this command to start the Neo4j database as a Docker container. Ensure Docker Compose is installed and the relevant profile is configured.

```bash
docker-compose --profile neo4j up -d
```

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

### Start Frontend with Development Script

Source: https://github.com/tencent/weknora/blob/main/docs/快速开发模式说明.md

Execute this script in the third terminal to start the frontend application.

```bash
./scripts/dev.sh frontend
```

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

### Prepare Script: Install Docker, Pull Runtime, and Install Firstboot

Source: https://github.com/tencent/weknora/blob/main/scripts/cloud-image/README.md

The `prepare.sh` script is responsible for setting up the Docker environment, pulling the necessary WeKnora runtime images, and installing the `firstboot` script. It uses `curl` and `tar` to download essential configuration files without cloning the entire repository.

```bash
#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

# --- Configuration ---
# Base URL for downloading WeKnora runtime components.
WEKNORA_BASE_URL="https://raw.githubusercontent.com/tencent/weknora/main/scripts/cloud-image"
# Directory to store downloaded components on the host.
RUNTIME_DIR="./"
# Docker Compose file name.
DOCKER_COMPOSE_FILE="docker-compose.yml"
# Environment file name.
ENV_FILE=".env"
# Configuration file name.
CONFIG_FILE="config/config.yaml"
# Preloaded skills directory.
SKILLS_DIR="skills/preloaded"

# --- Functions ---

# Function to download a file using curl.
# Arguments: $1 - URL, $2 - Destination path
download_file() {
  local url="$1"
  local dest="$2"
  echo "Downloading $url to $dest..."
  curl -fsSL "$url" -o "$dest"
}

# Function to download and extract a tarball.
# Arguments: $1 - URL, $2 - Destination directory
download_and_extract() {
  local url="$1"
  local dest_dir="$2"
  echo "Downloading and extracting $url to $dest_dir..."
  mkdir -p "$dest_dir"
  curl -fsSL "$url" | tar -xz -C "$dest_dir"
}

# --- Main Execution ---

# Ensure runtime directory exists.
mkdir -p "$RUNTIME_DIR"
mkdir -p "$(dirname "$CONFIG_FILE")"
mkdir -p "$SKILLS_DIR"

# Download docker-compose.yml
download_file "$WEKNORA_BASE_URL/$DOCKER_COMPOSE_FILE" "$RUNTIME_DIR/$DOCKER_COMPOSE_FILE"

# Download .env file
download_file "$WEKNORA_BASE_URL/$ENV_FILE" "$RUNTIME_DIR/$ENV_FILE"

# Download config.yaml
download_file "$WEKNORA_BASE_URL/$CONFIG_FILE" "$RUNTIME_DIR/$CONFIG_FILE"

# Download preloaded skills tarball and extract
# Assuming the skills are provided as a tarball at a specific URL
# This URL needs to be correctly set based on where the skills tarball is hosted.
# For example, if skills are in a separate repo or artifact.
# Placeholder URL - replace with actual URL if skills are not part of the main repo structure for download.
# If skills are part of the main repo and can be downloaded directly, adjust accordingly.
# Example: If skills are in a tar.gz in the same repo structure:
# SKILLS_URL="$WEKNORA_BASE_URL/skills.tar.gz"
# download_and_extract "$SKILLS_URL" "$SKILLS_DIR"

# For now, let's assume skills are not downloaded via tarball in this script, or the structure is different.
# If skills are expected to be downloaded, this part needs a valid URL and tarball.
# As per the README, skills are in `skills/preloaded/`, implying they might be part of the repo.
# If the goal is to download them, a mechanism to do so is needed.
# For the purpose of this script's example, we'll skip the tarball download for skills
# and assume they are either present or handled differently.

# Install Docker (example using convenience script)
if ! command -v docker &> /dev/null; then
    echo "Docker not found. Installing Docker..."
    curl -fsSL https://get.docker.com -o get-docker.sh
    sh get-docker.sh
    rm get-docker.sh
    # Add current user to docker group to avoid sudo
    usermod -aG docker $USER
    echo "Docker installed. Please log out and log back in for group changes to take effect."
else
    echo "Docker is already installed."
fi

# Install firstboot script
download_file "$WEKNORA_BASE_URL/firstboot.sh" "$RUNTIME_DIR/firstboot.sh"
chmod +x "$RUNTIME_DIR/firstboot.sh"

# Install systemd service files
# Assuming systemd service files are also downloadable
# Example: Download weknora.service
download_file "$WEKNORA_BASE_URL/systemd/weknora.service" "/etc/systemd/system/weknora.service"
# Example: Download weknora-firstboot.service
download_file "$WEKNORA_BASE_URL/systemd/weknora-firstboot.service" "/etc/systemd/system/weknora-firstboot.service"

# Reload systemd daemon
systemctl daemon-reload

echo "Preparation script finished. Docker and firstboot components are set up."

```

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

### Product Manual to Introductory Course Requirement Example

Source: https://github.com/tencent/weknora/blob/main/skills/preloaded/openmaic-classroom/references/requirement-builder.md

Example of converting content from a product manual into an introductory course requirement for new users.

```text
Retrieval Results:
- Document: "Product User Manual v2.0.pdf"
- Key Content: Product overview, Quick start, Core features, Common issues

Constructed Requirement:
"Based on Product User Manual v2.0, create an introductory course for new users.
Help users quickly understand the product's core features, master basic operations,
and be able to complete common tasks independently. Course language is Chinese."
```

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

### Install WeKnora CLI via Homebrew or Go

Source: https://github.com/tencent/weknora/blob/main/cli/README.md

Alternative installation methods for the WeKnora CLI using Homebrew or `go install`.

```bash
brew install weknora
```

```bash
go install github.com/Tencent/WeKnora/cli@latest
```

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

### Start Frontend for Development

Source: https://github.com/tencent/weknora/blob/main/README_CN.md

Execute this command in a new terminal to start the frontend service. Frontend changes are automatically hot-reloaded.

```bash
make dev-frontend
```

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

### Start WeKnora MCP Server

Source: https://github.com/tencent/weknora/blob/main/mcp-server/EXAMPLES.md

Use the main entry point to start the server. Options include checking environment configuration and enabling verbose logging.

```bash
# 推荐方式 - 使用主入口点
python main.py
```

```bash
# 检查环境配置
python main.py --check-only
```

```bash
# 启用详细日志
python main.py --verbose
```

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

### Enable and Start Systemd Service

Source: https://github.com/tencent/weknora/blob/main/mcp-server/INSTALL.md

Commands to enable the WeKnora MCP systemd service to start on boot and to start the service immediately.

```bash
sudo systemctl enable weknora-mcp
sudo systemctl start weknora-mcp
```

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

### Install Package - Production Mode

Source: https://github.com/tencent/weknora/blob/main/mcp-server/INSTALL.md

Installs the package for production use.

```bash
pip install .
```

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

### Install and run WeKnora MCP Server via command line

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Install the package in development mode and then run the server using its command-line interface. Aliases are also available.

```bash
pip install -e .
weknora-mcp-server               # 主命令
weknora-server                   # 别名命令
```

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

### Install WeKnora MCP Server for production

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Install the package for production use and run the server using its global command-line interface.

```bash
pip install .
weknora-mcp-server              # 全局命令
```

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

### Start MCP Server

Source: https://github.com/tencent/weknora/blob/main/mcp-server/EXAMPLES.md

Starts the MCP server. Use the --verbose flag for more detailed output.

```bash
# 1. 启动服务器
python main.py --verbose

# 2. 在 MCP 客户端中执行以下步骤：
```

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

### 启动生产环境

Source: https://github.com/tencent/weknora/blob/main/docs/wiki/开发部署/开发指南.md

Starts all services in the production environment after images have been built.

```bash
sh scripts/start_all.sh
```

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

### Start Backend for Development

Source: https://github.com/tencent/weknora/blob/main/README_CN.md

Run this command in a new terminal to start the backend service during development. It supports fast restarts and IDE debugging.

```bash
make dev-app
```

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

### Start WeKnora with Optional Services

Source: https://github.com/tencent/weknora/blob/main/README_CN.md

Use Docker Compose profiles to start additional services like Neo4j, MinIO, or Langfuse alongside the core services. Multiple profiles can be combined. To stop all services, use 'docker compose down'.

```bash
docker compose --profile full up -d
```

```bash
docker compose --profile neo4j up -d
```

```bash
docker compose --profile minio up -d
```

```bash
docker compose --profile langfuse up -d
```

```bash
docker compose --profile neo4j --profile minio up -d
```

```bash
docker compose down
```

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

### Dex Static Client Configuration Example

Source: https://github.com/tencent/weknora/blob/main/docs/OIDC认证调用流程.md

Example of static client configuration for Dex, specifying client ID, redirect URIs, and display name. Ensure Provider registration matches frontend redirect URIs.

```yaml
staticClients:
  - id: weknora
    redirectURIs:
      - 'http://127.0.0.1:5173/api/v1/auth/oidc/callback'
      - 'http://127.0.0.1/api/v1/auth/oidc/callback'
    name: 'WeKnora'
    # secret: <YOUR_SECRET_HERE>
```

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

### Install Air for Backend Hot Reloading

Source: https://github.com/tencent/weknora/blob/main/docs/快速开发模式说明.md

Install the Air tool globally to enable automatic recompilation and restarting of the backend upon code changes.

```bash
go install github.com/air-verse/air@latest
```

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

### Create Session and Perform Q&A

Source: https://github.com/tencent/weknora/blob/main/client/README.md

Shows how to create a session with specific Q&A strategies and then perform both standard and streaming knowledge Q&A. Optional parameters like `KnowledgeBaseIDs` and `WebSearchEnabled` can be used for fine-tuning queries.

```Go
// 创建会话
sessionRequest := &client.CreateSessionRequest{
    KnowledgeBaseID: knowledgeBaseID,
    SessionStrategy: &client.SessionStrategy{
        MaxRounds:        10,
        EnableRewrite:    true,
        FallbackStrategy: "fixed_answer",
        FallbackResponse: "抱歉，我无法回答这个问题",
        EmbeddingTopK:    5,
        KeywordThreshold: 0.5,
        VectorThreshold:  0.7,
        RerankModelID:    "rerank_model_id",
        RerankTopK:       3,
        RerankThreshold:  0.8,
        SummaryModelID:   "summary_model_id",
    },
}

session, err := apiClient.CreateSession(context.Background(), sessionRequest)
if err != nil {
    // 处理错误
}

// 普通问答
answer, err := apiClient.KnowledgeQA(context.Background(), session.ID, &client.KnowledgeQARequest{
    Query: "什么是人工智能?",
})
if err != nil {
    // 处理错误
}

// 流式问答
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, &client.KnowledgeQARequest{
    Query:            "什么是机器学习?",
    KnowledgeBaseIDs: []string{knowledgeBaseID}, // 可选：指定知识库
    WebSearchEnabled: false,                      // 可选：是否启用网络搜索
}, func(response *client.StreamResponse) error {
    // 处理每个响应片段
    fmt.Print(response.Content)
    return nil
})
if err != nil {
    // 处理错误
}
```

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

### Response for Get All Tenants

Source: https://github.com/tencent/weknora/blob/main/docs/api/tenant.md

Example JSON response structure for the 'Get All Tenants' API call.

```json
{
    "data": {
        "items": [
            {
                "id": 10001,
                "name": "weknora-1",
                "description": "weknora tenants 1",
                "status": "active",
                "business": "wechat",
                "created_at": "2025-08-11T20:37:28.39698+08:00",
                "updated_at": "2025-08-11T20:37:28.405693+08:00"
            },
            {
                "id": 10002,
                "name": "weknora-2",
                "description": "weknora tenants 2",
                "status": "active",
                "business": "wechat",
                "created_at": "2025-08-11T20:52:58.05679+08:00",
                "updated_at": "2025-08-11T20:52:58.060495+08:00"
            }
        ]
    },
    "success": true
}
```

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

### Shared Agent Response Example

Source: https://github.com/tencent/weknora/blob/main/docs/api/organization.md

Example JSON response for the GET /shared-agents endpoint, detailing shared agent information.

```json
{
    "data": [
        {
            "agent": {
                "id": "agent-00000001",
                "name": "智能客服助手"
            },
            "share_id": "as-00000001",
            "organization_id": "org-00000001",
            "org_name": "AI 技术团队",
            "permission": "viewer",
            "source_tenant_id": 1,
            "shared_at": "2025-08-15T11:00:00+08:00",
            "shared_by_user_id": "user-00000001",
            "shared_by_username": "admin",
            "disabled_by_me": false
        }
    ],
    "total": 1,
    "success": true
}
```

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

### Create Knowledge Base and Upload File

Source: https://github.com/tencent/weknora/blob/main/client/README_EN.md

Demonstrates creating a new knowledge base with specified configurations and then uploading a file to it. Ensure the file path is correct and metadata is properly formatted.

```go
// Create knowledge base
kb := &client.KnowledgeBase{
    Name:        "Test Knowledge Base",
    Description: "This is a test knowledge base",
    ChunkingConfig: client.ChunkingConfig{
        ChunkSize:    500,
        ChunkOverlap: 50,
        Separators:   []string{"\n\n", "\n", ". ", "? ", "! "},
    },
    ImageProcessingConfig: client.ImageProcessingConfig{
        ModelID: "image_model_id",
    },
    EmbeddingModelID: "embedding_model_id",
    SummaryModelID:   "summary_model_id",
}

kb, err := apiClient.CreateKnowledgeBase(context.Background(), kb)
if err != nil {
    // Handle error
}

// Upload knowledge file with metadata
metadata := map[string]string{
    "source": "local",
    "type":   "document",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), kb.ID, "path/to/file.pdf", metadata)
if err != nil {
    // Handle error
}
```

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

### Shared Knowledge Base Response Example

Source: https://github.com/tencent/weknora/blob/main/docs/api/organization.md

Example JSON response for the GET /shared-knowledge-bases endpoint, detailing shared knowledge base information.

```json
{
    "data": [
        {
            "knowledge_base": {
                "id": "kb-00000001",
                "name": "技术文档库"
            },
            "share_id": "kbs-00000001",
            "organization_id": "org-00000001",
            "org_name": "AI 技术团队",
            "permission": "viewer",
            "source_tenant_id": 1,
            "shared_at": "2025-08-15T10:00:00+08:00"
        }
    ],
    "total": 1,
    "success": true
}
```

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

### Create Knowledge Base and Upload File

Source: https://github.com/tencent/weknora/blob/main/client/README.md

Demonstrates creating a new knowledge base with specified configurations and then uploading a file to it, associating metadata. Ensure file paths and IDs are correct.

```Go
// 创建知识库
kb := &client.KnowledgeBase{
    Name:        "测试知识库",
    Description: "这是一个测试知识库",
    ChunkingConfig: client.ChunkingConfig{
        ChunkSize:    500,
        ChunkOverlap: 50,
        Separators:   []string{"\n\n", "\n", ". ", "? ", "! "},
    },
    ImageProcessingConfig: client.ImageProcessingConfig{
        ModelID: "image_model_id",
    },
    EmbeddingModelID: "embedding_model_id",
    SummaryModelID:   "summary_model_id",
}

kb, err := apiClient.CreateKnowledgeBase(context.Background(), kb)
if err != nil {
    // 处理错误
}

// 上传知识文件并添加元数据
metadata := map[string]string{
    "source": "local",
    "type":   "document",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), kb.ID, "path/to/file.pdf", metadata)
if err != nil {
    // 处理错误
}
```

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

### Get Current User Information Response

Source: https://github.com/tencent/weknora/blob/main/docs/api/auth.md

Example JSON response when fetching current user information.

```json
{
    "success": true,
    "user": {
        "id": "usr-வுகளில்",
        "username": "alice",
        "email": "alice@example.com",
        "avatar": "",
        "tenant_id": 1,
        "is_active": true,
        "can_access_all_tenants": false,
        "created_at": "2026-05-11T10:00:00+08:00",
        "updated_at": "2026-05-11T10:00:00+08:00"
    }
}
```

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

### Get Local Ollama Models

Source: https://github.com/tencent/weknora/blob/main/docs/api/initialization.md

Retrieve a list of all models currently available in your local Ollama installation. Includes model name, size, and last modified date.

```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/models' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```

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

### Get Single FAQ Entry Response JSON

Source: https://github.com/tencent/weknora/blob/main/docs/api/faq.md

Example JSON response when retrieving a single FAQ entry. It contains the FAQ's ID, associated knowledge base and chunk IDs, question details, answers, and metadata.

```json
{
    "data": {
        "id": 1,
        "chunk_id": "chunk-00000001",
        "knowledge_id": "knowledge-00000001",
        "knowledge_base_id": "kb-00000001",
        "tag_id": 12,
        "tag_name": "账户",
        "is_enabled": true,
        "is_recommended": false,
        "standard_question": "如何重置密码？",
        "similar_questions": ["忘记密码怎么办", "密码找回"],
        "negative_questions": [],
        "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
        "answer_strategy": "all",
        "index_mode": "hybrid",
        "chunk_type": "faq",
        "created_at": "2025-08-12T10:00:00+08:00",
        "updated_at": "2025-08-12T10:00:00+08:00"
    },
    "success": true
}
```

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

### 启动开发环境（脚本）

Source: https://github.com/tencent/weknora/blob/main/docs/wiki/开发部署/开发指南.md

Alternative method to start development infrastructure, backend, and frontend using a script.

```bash
./scripts/dev.sh start
./scripts/dev.sh app
./scripts/dev.sh frontend
```

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

### NDJSON Event Stream Example

Source: https://github.com/tencent/weknora/blob/main/cli/skills/weknora-rag-search/references/chat.md

The CLI emits an NDJSON event log, starting with an 'init' line, followed by various response types. Accumulate 'answer' content pieces for the final response. Keep 'session_id' and 'message_id' for session management and recovery.

```jsonc
{"event":"init","session_id":"sess_abc","message_id":"msg_xyz","profile":"prod"}
{"response_type":"thinking","content":"…"}
{"response_type":"tool_call","tool_calls":[…]}
{"response_type":"tool_result","content":"…"}
{"response_type":"references","knowledge_references":[…]}
{"response_type":"answer","content":"partial text…"}
{"response_type":"complete","done":true}
```

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

### Run WeKnora MCP Server using main.py

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Use main.py for basic startup, environment checks, verbose logging, or to display help information. This is the recommended startup method.

```bash
python main.py                    # 基本启动
python main.py --check-only       # 仅检查环境
python main.py --verbose          # 详细日志
python main.py --help            # 显示帮助
```

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

### Create Session and Perform Q&A

Source: https://github.com/tencent/weknora/blob/main/client/README_EN.md

Shows how to create a chat session with custom strategies and then perform both regular and streaming Q&A. The `KnowledgeQAStream` function requires a callback to handle response chunks.

```go
// Create session
sessionRequest := &client.CreateSessionRequest{
    KnowledgeBaseID: knowledgeBaseID,
    SessionStrategy: &client.SessionStrategy{
        MaxRounds:        10,
        EnableRewrite:    true,
        FallbackStrategy: "fixed_answer",
        FallbackResponse: "Sorry, I cannot answer this question",
        EmbeddingTopK:    5,
        KeywordThreshold: 0.5,
        VectorThreshold:  0.7,
        RerankModelID:    "rerank_model_id",
        RerankTopK:       3,
        RerankThreshold:  0.8,
        SummaryModelID:   "summary_model_id",
    },
}

session, err := apiClient.CreateSession(context.Background(), sessionRequest)
if err != nil {
    // Handle error
}

// Regular Q&A
answer, err := apiClient.KnowledgeQA(context.Background(), session.ID, &client.KnowledgeQARequest{
    Query: "What is artificial intelligence?",
})
if err != nil {
    // Handle error
}

// Streaming Q&A
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, "What is machine learning?", func(response *client.StreamResponse) error {
    // Handle each response chunk
    fmt.Print(response.Content)
    return nil
})
if err != nil {
    // Handle error
}
```

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

### Run Server - Main Entry Point

Source: https://github.com/tencent/weknora/blob/main/mcp-server/INSTALL.md

Executes the server using the main entry point script, which is the recommended method.

```bash
python main.py
```

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

### Install uv with Homebrew on macOS

Source: https://github.com/tencent/weknora/blob/main/mcp-server/MCP_CONFIG.md

Installs the 'uv' package manager using the Homebrew package manager. This is an alternative installation method for macOS users.

```bash
# 或使用 Homebrew (macOS)
brew install uv
```

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

### Start MinIO Service

Source: https://github.com/tencent/weknora/blob/main/docs/QA.md

Commands to start the MinIO service, which is used for multimodal functionality. You can start MinIO standalone or as part of the full service stack.

```bash
# 启动 MinIO 服务
docker-compose --profile minio up -d
```

```bash
# 或者启动完整服务（包括 MinIO、Neo4j、Qdrant）
docker-compose --profile full up -d
```

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

### Run Skills Demo

Source: https://github.com/tencent/weknora/blob/main/examples/skills/README.md

Execute the main entry point for the skills demo application.

```bash
go run ./cmd/skills-demo/main.go
```

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

### Install Dependencies

Source: https://github.com/tencent/weknora/blob/main/mcp-server/INSTALL.md

Installs all required Python packages listed in the requirements.txt file.

```bash
pip install -r requirements.txt
```

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

### Start Development Environment with Script

Source: https://github.com/tencent/weknora/blob/main/docs/快速开发模式说明.md

Execute this script in the first terminal to initiate the overall development environment.

```bash
./scripts/dev.sh start
```

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

### Client Initialization

Source: https://github.com/tencent/weknora/blob/main/client/README.md

Demonstrates how to create an instance of the WeKnora API client with authentication and timeout configurations.

```APIDOC
## Client Initialization

### Description
Initializes the WeKnora API client with the base URL, authentication token, and request timeout.

### Method
`client.NewClient(baseURL string, options ...client.Option)`

### Parameters
- **baseURL** (string) - Required - The base URL of the WeKnora API.
- **options** ([]client.Option) - Optional - A variadic list of options to configure the client.
  - `client.WithToken(token string)`: Sets the authentication token.
  - `client.WithTimeout(timeout time.Duration)`: Sets the request timeout.

### Request Example
```go
import (
    "context"
    "github.com/Tencent/WeKnora/client"
    "time"
)

apiClient := client.NewClient(
    "http://api.example.com", 
    client.WithToken("your-auth-token"),
    client.WithTimeout(30*time.Second),
)
```
```

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

### Delete Chunk Response Example

Source: https://github.com/tencent/weknora/blob/main/docs/api/chunk.md

This is an example of a successful response when deleting a chunk.

```json
{
    "message": "Chunk deleted",
    "success": true
}
```

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

### API Response Example

Source: https://github.com/tencent/weknora/blob/main/docs/api/session.md

This is an example of a successful response from the session management API endpoints.

```json
{
    "success": true,
    "message": "Sessions deleted successfully"
}
```

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

### Max File Size Configuration Example

Source: https://github.com/tencent/weknora/blob/main/docreader/README.md

Illustrates setting the maximum allowed file size for uploads in MB via an .env file.

```bash
# .env 文件
MAX_FILE_SIZE_MB=100  # 允许最大 100MB 的文件
```

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

### 启动独立前端开发

Source: https://github.com/tencent/weknora/blob/main/docs/wiki/开发部署/开发指南.md

Navigate to the frontend directory and run the development server. This connects to the backend API at http://localhost:8080.

```bash
cd frontend
npm run dev
```

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

### API Response Example for All Sessions Deleted

Source: https://github.com/tencent/weknora/blob/main/docs/api/session.md

This is an example of a successful response when all sessions for a tenant are deleted.

```json
{
    "success": true,
    "message": "All sessions deleted successfully"
}
```

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

### GET /messages/chat-history-stats - Get Chat History Statistics

Source: https://github.com/tencent/weknora/blob/main/docs/api/message.md

Retrieves statistics related to the chat history.

```APIDOC
## GET /messages/chat-history-stats

### Description
Retrieves statistics related to the chat history.

### Method
GET

### Endpoint
`/messages/chat-history-stats`
```

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

### Initialize Event System

Source: https://github.com/tencent/weknora/blob/main/internal/event/usage_example.md

This snippet shows the complete initialization flow for the event system, including setting up monitoring, analytics, and optional Prometheus monitoring or structured logging.

```go
// cmd/server/main.go 或 internal/container/container.go

func Initialize() {
    // 1. 初始化事件系统
    eventBus := event.GetGlobalEventBus()
    
    // 2. 设置监控
    event.NewMonitoringHandler(eventBus)
    
    // 3. 设置分析
    event.NewAnalyticsHandler(eventBus)
    
    // 4. 设置 Prometheus 监控（如果需要）
    // monitoring.SetupEventMonitoring()
    
    // 5. 设置结构化日志（如果需要）
    // logging.SetupEventLogging()
    
    // 6. 其他初始化...
}
```

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

### Run WeKnora MCP Server using run_server.py

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Execute the original server startup script.

```bash
python run_server.py
```

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

### Technical Document to Course Requirement Example

Source: https://github.com/tencent/weknora/blob/main/skills/preloaded/openmaic-classroom/references/requirement-builder.md

Example of converting retrieved content from a technical document into a structured course requirement.

```text
Retrieval Results:
- Document: "Kubernetes Deployment Guide.pdf"
- Key Content: Pod management, Service configuration, Ingress routing, Storage volumes

Constructed Requirement:
"Based on the Kubernetes Deployment Guide, create an intermediate course for DevOps engineers.
Focus on: Pod lifecycle management, Service and Ingress network configuration, persistent storage volume management.
The course should include practical operation segments."
```

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

### Build and Verify

Source: https://github.com/tencent/weknora/blob/main/docs/wiki/集成扩展/添加网络搜索引擎.md

Build the project and call the API to verify the new search engine type is registered.

```bash
go build ./...
# 调用 API 验证
curl http://localhost:8080/api/v1/web-search-providers/types
```

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

### Client Initialization

Source: https://github.com/tencent/weknora/blob/main/client/README_EN.md

Demonstrates how to create a new WeKnora client instance with basic configuration, including the API endpoint, authentication token, and request timeout.

```APIDOC
## Client Initialization

### Description
Initializes a new WeKnora client instance.

### Usage
```go
import (
    "context"
    "github.com/Tencent/WeKnora/client"
    "time"
)

// Create client instance
apiClient := client.NewClient(
    "http://api.example.com", 
    client.WithToken("your-auth-token"),
    client.WithTimeout(30*time.Second),
)
```

### Parameters
- `apiEndpoint` (string): The base URL of the WeKnora API.
- `options` ([]client.ClientOption): Optional configurations for the client.
  - `client.WithToken(token string)`: Sets the authentication token.
  - `client.WithTimeout(timeout time.Duration)`: Sets the request timeout.
```

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

### Update Chunk Response Example

Source: https://github.com/tencent/weknora/blob/main/docs/api/chunk.md

This is an example of a successful response when updating a chunk. It includes the updated chunk's details.

```json
{
    "data": {
        "id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7",
        "content": "更新后的分块内容",
        "is_enabled": true,
        "...": "其他字段同 GET 响应"
    },
    "success": true
}
```

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

### 查看服务状态 (Make)

Source: https://github.com/tencent/weknora/blob/main/docs/开发指南.md

使用 Make 命令查看当前所有开发服务的运行状态。

```bash
make dev-status
```

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

### Production mode installation for WeKnora MCP Server

Source: https://github.com/tencent/weknora/blob/main/mcp-server/PROJECT_SUMMARY.md

Install the package for production use and run the server using its command-line interface.

```bash
pip install .
weknora-mcp-server
```

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

### Install uv on macOS/Linux

Source: https://github.com/tencent/weknora/blob/main/mcp-server/MCP_CONFIG.md

Installs the 'uv' package manager using a curl script. This is the recommended method for macOS and Linux systems.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```