Skip to content

badhope/ai-robot

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

�� AI Robot

English 銝剜�

��������������������������������������������������������������������
�?                                                                 �?
�?       �� AI Robot - Intelligent Group Chat Assistant ��         �?
�?                                                                 �?
�?       �箄蝢方��拇� - Smart QQ/WeChat Group Chat AI Bot          �?
�?                                                                 �?
��������������������������������������������������������������������

�� Plug-and-Play QQ Group AI Bot | Multi-Platform API Support | One-Click Launch | Ready to Use

Version License Platform Node Stars


�� English Documentation

Table of Contents


Project Overview

AI Robot is a sophisticated, production-ready intelligent group chat assistant designed for QQ and WeChat platforms. Built with modern technologies (Electron, Vue 3, TypeScript), it provides seamless AI-powered conversations with support for multiple LLM providers.

Key Highlights

Feature Description
� Zero-Configuration Download �?Install �?API Key �?Launch
�� Multi-Platform AI Alibaba Cloud, DeepSeek, Zhipu, Moonshot, OpenAI, Google, Ollama
� Smart Conversations @ mentions, command triggers, auto-reply in private chats
�儭?Vision Support Image recognition with multimodal AI (Pro version)
� Voice Reply Text-to-speech responses (Pro version)
�� Plugin System Extensible plugin architecture
� Session Persistence SQLite storage, survives restarts
� Modern UI Electron + Vue 3, smooth and beautiful
�� Dark Theme Eye-friendly dark interface

Architecture

AI Robot follows a modular, adapter-based architecture that separates concerns and enables easy extensibility.

�����������������������������������������������������������������������������������������������������������������������������������?
�?                         AI Robot                               �?
�����������������������������������������������������������������������������������������������������������������������������������?
�?                                                                �?
�?  ���������������������������?    ���������������������������?    ���������������������������?     �?
�?  �? QQ Adapter �?    �?IM Adapters �?    �?WeChat      �?     �?
�?  �? (NapCatQQ) �?    �? (Platform) �?    �?(Future)    �?     �?
�?  �������������砂������������?    �������������砂������������?    �������������砂������������?     �?
�?         �?                 �?                 �?             �?
�?         �������������������������������������潑������������������������������������?             �?
�?                            �?                                  �?
�?                   �����������������������������������?                         �?
�?                   �?  Core Layer    �?                         �?
�?                   �? - IM Handler   �?                         �?
�?                   �? - LLM Selector �?                         �?
�?                   �? - Storage      �?                         �?
�?                   �? - Plugin       �?                         �?
�?                   �����������������砂����������������?                         �?
�?                            �?                                  �?
�?         �������������������������������������潑������������������������������������?               �?
�?         �?                 �?                 �?               �?
�?  ���������������������������?   ���������������������������?   ���������������������������?      �?
�?  �?Alibaba     �?   �?Ollama      �?   �?Future      �?      �?
�?  �?Adapter     �?   �?Adapter     �?   �?Providers   �?      �?
�?  ���������������������������?   ���������������������������?   ���������������������������?      �?
�?                                                                �?
�?  ���������������������������?   ���������������������������?                          �?
�?  �?  Setup UI  �?   �? SQLite     �?                          �?
�?  �? (Console)  �?   �? Storage    �?                          �?
�?  ���������������������������?   ���������������������������?                          �?
�?                                                                �?
�����������������������������������������������������������������������������������������������������������������������������������?

Core Components

Component Location Responsibility
apps/server apps/server/ Main service entry, HTTP/WebSocket server, component initialization
apps/setup-ui apps/setup-ui/ Visual console, environment detection, configuration wizard
packages/core packages/core/ Core logic: IM handling, LLM routing, storage, plugins
packages/qq-adapter packages/qq-adapter/ NapCatQQ WebSocket integration
packages/wechat-adapter packages/wechat-adapter/ WeChat HTTP adapter (reserved)
packages/alibaba-adapter packages/alibaba-adapter/ Alibaba Cloud/DashScope API
packages/ollama-adapter packages/ollama-adapter/ Local Ollama model integration
packages/sqlite-storage packages/sqlite-storage/ SQLite session persistence
packages/doctor packages/doctor/ Environment diagnostics

Features

�� AI Capabilities

Capability Description Status
Multi-turn Conversation Context-aware dialogue with session memory �?
System Prompts Customizable AI personality and behavior �?
Temperature Control Adjust response creativity �?
Token Limits Configure max response length �?
Vision (Multimodal) Image understanding and description �� Pro
Voice Synthesis Text-to-speech responses �� Pro

� Messaging Features

Feature Description
@ Mention Trigger Bot responds when mentioned in groups
Command Prefix Use /ai or custom prefix to trigger
Private Auto-Reply Automatic responses in private chats
Group Smart Reply Intelligent group conversation handling
Message Quoting Reply to specific messages

��儭?Configuration Options

Option Type Default Description
LLM_PROVIDER string alibaba AI provider selection
ALIBABA_API_KEY string - Alibaba Cloud API key
ALIBABA_MODEL string qwen-plus Model selection
OLLAMA_BASE_URL string http://localhost:11434 Ollama server URL
SESSION_STORAGE string sqlite Storage backend
SESSION_MAX_MESSAGES number 100 Max messages per session
CHAT_PREFIX string /ai Command trigger prefix
PRIVATE_AUTO_REPLY boolean true Auto-reply in private chats
GROUP_AI_TRIGGER string both Group trigger mode: at, prefix, both

System Requirements

Minimum Requirements

Platform Requirement
Windows Windows 10 64-bit
macOS macOS 10.15 (Catalina)
Linux Ubuntu 20.04 LTS

Recommended Configuration

Platform Recommendation
Windows Windows 11 64-bit
macOS macOS 12+ (Monterey)
Linux Ubuntu 22.04 LTS

Software Dependencies

Software Version Required For
Node.js 18.0.0+ Source build
pnpm 8.0.0+ Source build
NapCatQQ Latest QQ integration
Ollama Latest Local models (optional)

Installation

Method 1: Pre-built Release (Recommended)

  1. Visit the Releases page
  2. Download the installer for your platform
  3. Install and launch the application
  4. Select your AI platform and enter your API Key
  5. Start NapCatQQ and scan QR code to login
  6. Click "Start Bot" to begin

Method 2: Build from Source

# Clone repository
git clone https://github.com/badhope/ai-robot.git
cd ai-robot

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build for production
pnpm build:win   # Windows
pnpm build:mac   # macOS
pnpm build:linux # Linux

Method 3: Docker Deployment

# Build image
docker build -t ai-robot .

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Run container
cd deployments
docker-compose up -d

Quick Start Guide

Step 1: Get Your API Key

�� How to obtain API keys

Alibaba Cloud (Recommended)

  1. Visit Alibaba Cloud Bailian
  2. Login or register an account
  3. Enable DashScope service
  4. Navigate to "API-KEY Management" �?"Create API Key"

DeepSeek

  1. Visit DeepSeek Platform
  2. Register an account
  3. Go to "API Keys" �?"Create API Key"

Zhipu AI

  1. Visit Zhipu Open Platform
  2. Register an account
  3. Go to "API Keys" �?"Add API Key"

OpenAI

  1. Visit OpenAI Platform
  2. Create an account
  3. Generate an API key from the dashboard

Step 2: Configure NapCatQQ

�� NapCatQQ Setup Guide
  1. Download NapCatQQ
  2. Extract and run the application
  3. Scan QR code with your bot QQ account
  4. Ensure WebSocket port is set to 3001

For detailed instructions, see NapCatQQ Guide

Step 3: Start the Bot

# Run the application
pnpm dev

# Or use the desktop app
# Simply click "Start Bot" in the UI

Step 4: Test the Bot

In a QQ group:

@YourBot Hello, how are you?

Or use the command prefix:

/ai What's the weather today?

Configuration

Environment Variables

Create a .env file in the project root:

# ====================
# Server Configuration
# ====================
APP_HOST=0.0.0.0
APP_PORT=3000

# ====================
# QQ Configuration
# ====================
QQ_ENABLED=true
QQ_HTTP_PORT=3001
QQ_WS_URL=ws://localhost:3001
QQ_NUMBER=123456789
QQ_TOKEN=

# ====================
# AI Provider Configuration
# ====================
LLM_PROVIDER=alibaba

# Alibaba Cloud (Default)
ALIBABA_API_KEY=your-api-key-here
ALIBABA_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
ALIBABA_MODEL=qwen-plus
ALIBABA_TIMEOUT=120000

# Ollama (Local Mode)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
OLLAMA_TIMEOUT=120000

# ====================
# Session Storage
# ====================
SESSION_STORAGE=sqlite
SQLITE_DB_PATH=./data/sessions.db
SESSION_MAX_MESSAGES=100

# ====================
# Trigger Rules
# ====================
CHAT_PREFIX=/ai
PRIVATE_AUTO_REPLY=true
GROUP_AI_TRIGGER=both

# ====================
# Logging
# ====================
LOG_LEVEL=info

Supported AI Platforms

Platform Features Free Tier Rating
�� Alibaba Cloud Fast, stable Yes 潃�潃�潃?
�� DeepSeek Cost-effective Yes 潃�潃�潃?
�� Zhipu AI Chinese LLM Yes 潃�潃�
�� Moonshot Long context Yes 潃�潃�
�� OpenAI GPT-4 Limited 潃�潃�
�� Google Gemini Large free tier Yes 潃�潃�
� Local Ollama Completely free Unlimited 潃�潃?(GPU required)

Protocol Documentation

Overview

AI Robot implements multiple protocols for communication between components, external services, and messaging platforms. This section documents all protocols used in the system.


1. IM Platform Protocol

Purpose

The IM (Instant Messaging) Platform Protocol defines the standard interface for integrating different messaging platforms (QQ, WeChat, etc.) into AI Robot.

Interface Specification
interface IMAdapter {
  name: string;
  platform: 'wechat' | 'qq' | 'mock';
  start(): Promise<void>;
  stop(): Promise<void>;
  sendReply(event: ChatMessageEvent, reply: ChatReply): Promise<void>;
  onMessage(handler: (event: ChatMessageEvent) => Promise<void>): void;
}
Message Event Structure
interface ChatMessageEvent {
  platform: Platform;
  chatType: 'private' | 'group';
  messageId: string;
  senderId: string;
  senderName?: string;
  roomId?: string;
  roomName?: string;
  text: string;
  mentions?: string[];
  isAt?: boolean;
  replyToMessageId?: string;
  timestamp: number;
  raw?: unknown;
}
Reply Structure
interface ChatReply {
  text: string;
  replyToMessageId?: string;
}
Implementation Details
Adapter Protocol Transport Port
NapCatQQ WebSocket WS 3001
WeChat HTTP REST Configurable
Usage Example
import { NapCatQQAdapter } from '@ai-robot/qq-adapter';

const adapter = new NapCatQQAdapter({
  httpPort: 3001,
  wsUrl: 'ws://localhost:3001',
  qqNumber: '123456789',
});

await adapter.start();

adapter.onMessage(async (event) => {
  console.log(`Message from ${event.senderName}: ${event.text}`);
  await adapter.sendReply(event, { text: 'Hello!' });
});

2. LLM Provider Protocol

Purpose

The LLM (Large Language Model) Provider Protocol defines the standard interface for integrating different AI providers into AI Robot.

Interface Specification
interface LLMProvider {
  name: string;
  kind: 'local' | 'remote' | 'experimental';
  generate(input: LLMGenerateRequest): Promise<LLMGenerateResponse>;
  healthCheck(): Promise<boolean>;
  listModels?(): Promise<string[]>;
}
Request Structure
interface LLMGenerateRequest {
  model?: string;
  systemPrompt?: string;
  messages: Array<{
    role: 'system' | 'user' | 'assistant';
    content: string;
  }>;
  temperature?: number;
  topP?: number;
  maxTokens?: number;
  metadata?: Record<string, unknown>;
}
Response Structure
interface LLMGenerateResponse {
  provider: string;
  model: string;
  content: string;
  usage?: {
    promptTokens?: number;
    completionTokens?: number;
    totalTokens?: number;
  };
  raw?: unknown;
}
Supported Providers
Provider Kind API Endpoint Authentication
Alibaba Cloud remote dashscope.aliyuncs.com Bearer Token
Ollama local localhost:11434 None
OpenAI remote api.openai.com Bearer Token
DeepSeek remote api.deepseek.com Bearer Token
Usage Example
import { AlibabaProvider } from '@ai-robot/alibaba-adapter';

const provider = new AlibabaProvider({
  apiKey: 'sk-xxx',
  model: 'qwen-plus',
});

const response = await provider.generate({
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
  temperature: 0.7,
});

console.log(response.content);

3. NapCatQQ WebSocket Protocol

Purpose

NapCatQQ uses WebSocket for real-time bidirectional communication between the QQ client and AI Robot.

Connection Details
Parameter Value
Protocol WebSocket
Default URL ws://localhost:3001
Message Format JSON
Encoding UTF-8
Message Types

Incoming Message (from NapCatQQ)

{
  "post_type": "message",
  "message_type": "group",
  "sub_type": "normal",
  "user_id": 123456789,
  "group_id": 987654321,
  "group_name": "Test Group",
  "sender": {
    "nickname": "User",
    "card": "Card Name"
  },
  "message_id": 12345,
  "message": [
    { "type": "text", "text": "Hello" },
    { "type": "at", "data": { "qq": 987654321 } }
  ],
  "raw_message": "Hello @bot",
  "time": 1234567890
}

Outgoing Message (to NapCatQQ)

{
  "message_type": "group",
  "group_id": 987654321,
  "message": "Reply text here"
}
Reconnection Strategy
Parameter Value
Max Attempts 10
Base Delay 1000ms
Max Delay 30000ms
Backoff Exponential

4. Alibaba Cloud API Protocol

Purpose

Alibaba Cloud DashScope API provides access to Qwen series language models.

API Endpoint
Environment URL
Production https://dashscope.aliyuncs.com/compatible-mode/v1
Chat Completions /chat/completions
Authentication
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
Request Format
{
  "model": "qwen-plus",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "max_tokens": 2048
}
Response Format
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "qwen-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
Available Models
Model Context Description
qwen-turbo 8K Fast, cost-effective
qwen-plus 32K Balanced performance
qwen-max 32K Best quality
qwen-long 1M Long context

5. Ollama API Protocol

Purpose

Ollama provides a local REST API for running open-source language models.

API Endpoint
Endpoint URL
Base URL http://localhost:11434
Chat API /api/chat
Models List /api/tags
Request Format
{
  "model": "qwen2.5:7b",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_predict": 512
  }
}
Response Format
{
  "model": "qwen2.5:7b",
  "created_at": "2024-01-01T00:00:00Z",
  "message": {
    "role": "assistant",
    "content": "Hello! How can I help you?"
  },
  "done": true,
  "total_duration": 1000000000,
  "prompt_eval_count": 10,
  "eval_count": 20
}

6. Session Storage Protocol

Purpose

The Session Storage Protocol defines how conversation history is persisted and retrieved.

Interface Specification
interface SessionStore {
  getSession(sessionId: string): Promise<SessionMessage[]>;
  appendMessage(sessionId: string, message: SessionMessage): Promise<void>;
  clearSession(sessionId: string): Promise<void>;
}
Message Structure
interface SessionMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
  timestamp?: number;
}
SQLite Schema
CREATE TABLE sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  role TEXT NOT NULL,
  content TEXT NOT NULL,
  timestamp INTEGER NOT NULL,
  created_at INTEGER DEFAULT (strftime('%s', 'now'))
);

CREATE INDEX idx_session_id ON sessions(session_id);
CREATE INDEX idx_timestamp ON sessions(session_id, timestamp);
Usage Example
import { SQLiteSessionStore } from '@ai-robot/sqlite-storage';

const store = new SQLiteSessionStore({
  dbPath: './data/sessions.db',
  maxMessages: 100,
});

// Get session history
const messages = await store.getSession('group_123456');

// Append message
await store.appendMessage('group_123456', {
  role: 'user',
  content: 'Hello!',
  timestamp: Date.now(),
});

7. HTTP API Protocol

Purpose

The HTTP API provides REST endpoints for external integrations and the setup UI.

Endpoints
Method Path Description
GET /health Health check
POST /send Send message
GET /status Bot status
Send Message Request
POST /send HTTP/1.1
Content-Type: application/json

{
  "message_type": "group",
  "group_id": 123456789,
  "message": "Hello from HTTP API"
}

8. Plugin Protocol

Purpose

The Plugin Protocol enables extensibility through custom message processors.

Interface Specification
interface Plugin {
  name: string;
  priority: number;
  process(event: ChatMessageEvent, context: PluginContext): Promise<PluginResult | null>;
}

interface PluginContext {
  provider: LLMProvider;
  storage: SessionStore;
  config: Record<string, unknown>;
}

interface PluginResult {
  handled: boolean;
  reply?: string;
}

Advanced Usage

Custom System Prompts

Create custom prompts in the prompts/ directory:

prompts/
���� default/
�?  ���� friendly.txt
�?  ���� tech-expert.txt
���� group/
�?  ���� active.txt
�?  ���� concise.txt
���� helper/
    ���� assistant.txt

Switching Providers at Runtime

// In configuration
LLM_PROVIDER=ollama  // Switch to local model
OLLAMA_MODEL=llama3:8b

Custom Trigger Rules

# Only respond to @ mentions
GROUP_AI_TRIGGER=at

# Only respond to prefix commands
GROUP_AI_TRIGGER=prefix

# Respond to both (default)
GROUP_AI_TRIGGER=both

Troubleshooting

Quick Diagnostics

pnpm doctor

This checks:

  • Node.js version
  • Configuration files
  • API connectivity
  • NapCatQQ connection
  • SQLite status

Common Issues

� Bot not responding
  1. Verify NapCatQQ is running
  2. Check WebSocket connection (ws://localhost:3001)
  3. Ensure QQ_ENABLED=true in .env
  4. Verify API key is configured
  5. Check bot is mentioned correctly with @
� API connection failed
  1. Verify API key is correct
  2. Check account has available credits
  3. Test network connectivity: ping dashscope.aliyuncs.com
  4. Verify base URL is correct
� SQLite errors
  1. Check directory permissions
  2. Verify disk space available
  3. Delete and recreate database:
    rm data/sessions.db
� Ollama connection issues
  1. Verify Ollama is installed: ollama --version
  2. Check Ollama service: ollama serve
  3. Verify model is downloaded: ollama list
  4. Check configuration:
    LLM_PROVIDER=ollama
    OLLAMA_BASE_URL=http://localhost:11434

Error Codes

Error Meaning Solution
401 Unauthorized Invalid API key Check API key configuration
Connection refused Service not running Start the required service
WebSocket closed NapCatQQ disconnected Restart NapCatQQ
Model not found Model doesn't exist Download model or check name
Out of credit Insufficient balance Add credits to account

Contributing

We welcome all contributions! Please follow these guidelines:

Getting Started

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/AmazingFeature
  3. Make your changes
  4. Run tests: pnpm test
  5. Commit: git commit -m 'Add AmazingFeature'
  6. Push: git push origin feature/AmazingFeature
  7. Open a Pull Request

Development Setup

# Install dependencies
pnpm install

# Run in development
pnpm dev

# Run linter
pnpm lint

# Type check
pnpm typecheck

# Build
pnpm build

Code Style

  • Use TypeScript for all new code
  • Follow existing code conventions
  • Add appropriate comments
  • Update documentation

See CONTRIBUTING.md for detailed guidelines.


License

This project uses a dual-license model:

Component License
Open Source Parts MIT License
Commercial Parts Commercial License

See LICENSE for details.


Changelog

See CHANGELOG.md for version history.

Recent Changes

[2.0.0] - 2024-03-26

  • �� New Electron desktop application architecture
  • � Vue 3 + TypeScript modern UI
  • �� Star theme UI design
  • � Simple and Expert mode toggle
  • � Visual configuration wizard
  • �� Multi-platform AI API support
  • � Local Ollama model support
  • �� Plugin system architecture
  • �� Pro version features
  • �� Conversation statistics
  • �� Dark theme support

Contact

Channel Link
� Email contact@ai-robot.dev
� QQ Group 123456789
�� Website https://ai-robot.dev
�� Documentation https://docs.ai-robot.dev
�� Issues GitHub Issues

�� 銝剜��﹝

�桀�


憿寧璁膩

AI Robot �臭�銝芣�����鈭批停蝏芰��箄蝢方��拇�嚗�銝?QQ �凝靽∪像�啗挽霈~�鈭隞���舀�嚗lectron�ue 3�ypeScript嚗�撱綽���瘚��?AI 撖寡�雿�嚗��蝘之霂剛�璅∪�����?

�詨�鈭桃

�寞�? �膩
� *�餌�撘�雿? 銝蝸 �?摰� �?憛怠� API Key �?銝��桀�?
�� *憭像�唳�? �輸�鈭�eepSeek�靚晞��銋��U�penAI�oogle��?Ollama
� �箄撖寡� �舀� @ 閫血��隞方圻�����典�憭?
�儭?�曄�霂 霂�曄��捆嚗�璅⊥�?AI �舀�嚗�銝�嚗?
� 霂剝�� ��頧祈祗�喳�憭�銝���
�� �辣蝟餌� 銝啣���隞嗥����舀撅��?
� *隡����? SQLite 摮嚗��臭�銝W仃
� �唬誨� Electron + Vue 3嚗���閫?
�� �銝駁� �斤�楛�脩��?

蝟餌��嗆�

AI Robot �璅∪������冽芋撘��嗆�嚗��啣瘜函�氖��鈭撅�?

�����������������������������������������������������������������������������������������������������������������������������������?
�?                         AI Robot                               �?
�����������������������������������������������������������������������������������������������������������������������������������?
�?                                                                �?
�?  ���������������������������?    ���������������������������?    ���������������������������?     �?
�?  �? QQ ���? �?    �?IM ���?  �?    �?敺桐縑���? �?     �?
�?  �? (NapCatQQ) �?    �? (撟喳)     �?    �?(憸�)      �?     �?
�?  �������������砂������������?    �������������砂������������?    �������������砂������������?     �?
�?         �?                 �?                 �?             �?
�?         �������������������������������������潑������������������������������������?             �?
�?                            �?                                  �?
�?                   �����������������������������������?                         �?
�?                   �?   �詨�撅?     �?                         �?
�?                   �? - IM 憭��?  �?                         �?
�?                   �? - LLM ��? �?                         �?
�?                   �? - 摮撅?     �?                         �?
�?                   �? - �辣蝟餌�    �?                         �?
�?                   �����������������砂����������������?                         �?
�?                            �?                                  �?
�?         �������������������������������������潑������������������������������������?               �?
�?         �?                 �?                 �?               �?
�?  ���������������������������?   ���������������������������?   ���������������������������?      �?
�?  �?�輸�鈭?     �?   �?Ollama      �?   �?�芣        �?      �?
�?  �?���?     �?   �?���?     �?   �?���?     �?      �?
�?  ���������������������������?   ���������������������������?   ���������������������������?      �?
�?                                                                �?
�?  ���������������������������?   ���������������������������?                          �?
�?  �? 霈曄蔭�   �?   �? SQLite     �?                          �?
�?  �? (�批�?   �?   �? 摮       �?                          �?
�?  ���������������������������?   ���������������������������?                          �?
�?                                                                �?
�����������������������������������������������������������������������������������������������������������������������������������?

�詨�蝏辣

蝏辣 雿蔭 �提
apps/server apps/server/ 銝餅��∪���HTTP/WebSocket �嚗�隞嗅�憪�
apps/setup-ui apps/setup-ui/ �航���嗅嚗憓�瘚��蔭�紡
packages/core packages/core/ �詨��餉�嚗M 憭�嚗LM 頝舐嚗��剁��辣
packages/qq-adapter packages/qq-adapter/ NapCatQQ WebSocket ��
packages/wechat-adapter packages/wechat-adapter/ 敺桐縑 HTTP ���剁�憸�嚗?
packages/alibaba-adapter packages/alibaba-adapter/ �輸�鈭?DashScope API
packages/ollama-adapter packages/ollama-adapter/ �砍 Ollama 璅∪���
packages/sqlite-storage packages/sqlite-storage/ SQLite 隡����?
packages/doctor packages/doctor/ �臬�霂

��寞�?

�� AI �賢�

�賢� �膩 �嗆�?
憭蔭撖寡� 銝����亦�撖寡�嚗蒂隡�霈啣� �?
蝟餌��內霂? �航摰� AI 鈭箸��銝? �?
皜拙漲�批 靚�����? �?
Token � �蔭��憭批�憭摨? �?
閫�嚗�璅⊥�� �曉��圾��餈? �� 銝��?
霂剝�� ��頧祈祗�喳�憭? �� 銝��?

� 瘨�

� �膩
@ ��閫血� 蝢方�銝剛◤ @ �嗅�摨?
�賭誘�� 雿輻 /ai �摰���閫血�
蝘��芸�� 蝘�銝剛�典�摨?
蝢方��箄�� �箄蝢方�撖寡�憭�
瘨撘 ���孵�瘨

蝟餌�閬�

��雿�瘙?

撟喳 閬�
Windows Windows 10 64 雿?
macOS macOS 10.15 (Catalina)
Linux Ubuntu 20.04 LTS

�刻��蔭

撟喳 �刻�
Windows Windows 11 64 雿?
macOS macOS 12+ (Monterey)
Linux Ubuntu 22.04 LTS

頧臭辣靘�

頧臭辣 � �券�?
Node.js 18.0.0+ 皞��遣
pnpm 8.0.0+ 皞��遣
NapCatQQ ���啁� QQ ��
Ollama ���啁� �砍璅∪�嚗��

摰���

�孵�銝�嚗�蝻��嚗��

  1. �� Releases 憿菟
  2. 銝蝸撖孵�撟喳��鋆�
  3. 摰�撟嗅�典��?
  4. � AI 撟喳嚗‵�?API Key
  5. �臬 NapCatQQ 撟嗆�敶?
  6. �孵��冽�其犖��憪蝙�?

�孵�鈭�隞���撱?

# ��隞�
git clone https://github.com/badhope/ai-robot.git
cd ai-robot

# 摰�靘�
pnpm install

# 撘��芋撘?
pnpm dev

# �遣�漣�
pnpm build:win   # Windows
pnpm build:mac   # macOS
pnpm build:linux # Linux

�孵�銝�Docker �函蔡

# �遣��
docker build -t ai-robot .

# �蔭�臬�
cp .env.example .env
# 蝻� .env 憛怠 API 撖

# 餈�摰孵
cd deployments
docker-compose up -d

敹恍��憪?

甇仿炊 1嚗�?API Key

�� 憒��瑕� API Key

*�輸�鈭��刻�嚗?

  1. �� [�輸�鈭�奭(https://bailian.console.aliyun.com/)
  2. �餃�/瘜典��輸�鈭揭�?
  3. 撘��?DashScope �
  4. �孵撌虫儒�PI-KEY 蝞∠�����撱?API Key�?

DeepSeek

  1. �� DeepSeek 摰�
  2. 瘜典�韐血
  3. 餈�PI Keys����撱?API Key�?

�箄停 AI

  1. �� [�箄停撘��曉像�財(https://open.bigmodel.cn/)
  2. 瘜典�韐血
  3. 餈�PI 撖���溶�?API 撖�?

甇仿炊 2嚗�蝵?NapCatQQ

�� NapCatQQ 霈曄蔭��
  1. 銝蝸 NapCatQQ
  2. 閫��撟嗉�銵?
  3. �怎��餃�雿� QQ �箏鈭箄揭�?
  4. 蝖桐� WebSocket 蝡臬銝?3001

霂衣���霂瑟�?NapCatQQ 雿輻��

甇仿炊 3嚗�冽�其犖

# 餈�摨
pnpm dev

# �蝙�冽��W��?
# �函��V葉�孵��冽�其犖�?

甇仿炊 4嚗�霂�其犖

�?QQ 蝢支葉嚗?

@雿��箏鈭?雿末嚗�憭拙予瘞���瘀�

�蝙�典隞文�蝻�嚗?

/ai 隞予憭拇����瘀�

�蔭霂湔�

�臬���

�券★�格�桀��遣 .env �辣嚗?

# ====================
# ��券�蝵?
# ====================
APP_HOST=0.0.0.0
APP_PORT=3000

# ====================
# QQ �蔭
# ====================
QQ_ENABLED=true
QQ_HTTP_PORT=3001
QQ_WS_URL=ws://localhost:3001
QQ_NUMBER=123456789
QQ_TOKEN=

# ====================
# AI ����蝵?
# ====================
LLM_PROVIDER=alibaba

# �輸�鈭�暺恕嚗?
ALIBABA_API_KEY=your-api-key-here
ALIBABA_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
ALIBABA_MODEL=qwen-plus
ALIBABA_TIMEOUT=120000

# Ollama嚗�唳芋撘�
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
OLLAMA_TIMEOUT=120000

# ====================
# 隡�摮
# ====================
SESSION_STORAGE=sqlite
SQLITE_DB_PATH=./data/sessions.db
SESSION_MAX_MESSAGES=100

# ====================
# 閫血�閫�
# ====================
CHAT_PREFIX=/ai
PRIVATE_AUTO_REPLY=true
GROUP_AI_TRIGGER=both

# ====================
# �亙�
# ====================
LOG_LEVEL=info

�舀��?AI 撟喳

撟喳 �寧 �晶憸漲 �刻��
�� �輸�鈭�� ��敹恬�蝔喳� �? 潃�潃�潃?
�� DeepSeek �找遠瘥� �? 潃�潃�潃?
�� �箄停 AI �賭漣憭扳芋�? �? 潃�潃�
�� ��� �踵��砍撩 �? 潃�潃�
�� OpenAI GPT-4 �� 潃�潃�
�� Google Gemini �晶憸漲憭? �? 潃�潃�
� �砍 Ollama 摰�晶 �� 潃�潃����曉嚗

�悅�﹝

璁膩

AI Robot 摰鈭�蝘�霈桃鈭�隞園�縑���冽��∪�瘨撟喳����扇敶頂蝏葉雿輻����霈柴�?


1. IM 撟喳�悅

�桃�

IM嚗�園�悖嚗像�啣�霈桀�銋�撠����臬像�堆�QQ�凝靽∠�嚗�� AI Robot ������?

�亙閫�
interface IMAdapter {
  name: string;
  platform: 'wechat' | 'qq' | 'mock';
  start(): Promise<void>;
  stop(): Promise<void>;
  sendReply(event: ChatMessageEvent, reply: ChatReply): Promise<void>;
  onMessage(handler: (event: ChatMessageEvent) => Promise<void>): void;
}
瘨鈭辣蝏�
interface ChatMessageEvent {
  platform: Platform;
  chatType: 'private' | 'group';
  messageId: string;
  senderId: string;
  senderName?: string;
  roomId?: string;
  roomName?: string;
  text: string;
  mentions?: string[];
  isAt?: boolean;
  replyToMessageId?: string;
  timestamp: number;
  raw?: unknown;
}
摰蝏�
���? �悅 隡��孵� 蝡臬
NapCatQQ WebSocket WS 3001
敺桐縑 HTTP REST �舫�蝵?

2. LLM ����霈?

�桃�

LLM嚗之霂剛�璅∪�嚗�靘��悅摰�鈭�銝� AI ����� AI Robot ������?

�亙閫�
interface LLMProvider {
  name: string;
  kind: 'local' | 'remote' | 'experimental';
  generate(input: LLMGenerateRequest): Promise<LLMGenerateResponse>;
  healthCheck(): Promise<boolean>;
  listModels?(): Promise<string[]>;
}
霂瑟�蝏�
interface LLMGenerateRequest {
  model?: string;
  systemPrompt?: string;
  messages: Array<{
    role: 'system' | 'user' | 'assistant';
    content: string;
  }>;
  temperature?: number;
  topP?: number;
  maxTokens?: number;
  metadata?: Record<string, unknown>;
}
��蝏�
interface LLMGenerateResponse {
  provider: string;
  model: string;
  content: string;
  usage?: {
    promptTokens?: number;
    completionTokens?: number;
    totalTokens?: number;
  };
  raw?: unknown;
}

3. NapCatQQ WebSocket �悅

�桃�

NapCatQQ 雿輻 WebSocket 摰 QQ 摰X蝡臭� AI Robot 銋���嗅���縑�?

餈霂行�
� �?
�悅 WebSocket
暺恕 URL ws://localhost:3001
瘨�澆� JSON
蝻� UTF-8
瘨蝐餃�

*隡瘨嚗�?NapCatQQ嚗?

{
  "post_type": "message",
  "message_type": "group",
  "user_id": 123456789,
  "group_id": 987654321,
  "sender": {
    "nickname": "�冽",
    "card": "蝢文��?
  },
  "message": [
    { "type": "text", "text": "雿末" },
    { "type": "at", "data": { "qq": 987654321 } }
  ],
  "raw_message": "雿末 @�箏鈭?,
  "time": 1234567890
}

*隡瘨嚗�� NapCatQQ嚗?

{
  "message_type": "group",
  "group_id": 987654321,
  "message": "���捆"
}

4. �輸�鈭?API �悅

�桃�

�輸�鈭?DashScope API ��撖寥��蝟餃�霂剛�璅∪��挪�柴�?

API 蝡舐
�臬� URL
�漣�臬� https://dashscope.aliyuncs.com/compatible-mode/v1
撖寡�銵亙 /chat/completions
霈方��孵�
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
霂瑟��澆�
{
  "model": "qwen-plus",
  "messages": [
    { "role": "system", "content": "雿銝�銝芣�撣桀���? },
    { "role": "user", "content": "雿末嚗? }
  ],
  "temperature": 0.7,
  "max_tokens": 2048
}
�舐璅∪�
璅∪� 銝��? �膩
qwen-turbo 8K 敹恍���找遠瘥�
qwen-plus 32K 撟唾﹛�扯
qwen-max 32K ��雿唾捶�?
qwen-long 1M �蹂�銝�

5. Ollama API �悅

�桃�

Ollama ���砍 REST API �其�餈�撘�皞祗閮�璅∪��?

API 蝡舐
蝡舐 URL
�箇� URL http://localhost:11434
撖寡� API /api/chat
璅∪��” /api/tags
霂瑟��澆�
{
  "model": "qwen2.5:7b",
  "messages": [
    { "role": "user", "content": "雿末嚗? }
  ],
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_predict": 512
  }
}

6. 隡�摮�悅

�桃�

隡�摮�悅摰�鈭笆霂��脩�����璉�蝝X撘�?

�亙閫�
interface SessionStore {
  getSession(sessionId: string): Promise<SessionMessage[]>;
  appendMessage(sessionId: string, message: SessionMessage): Promise<void>;
  clearSession(sessionId: string): Promise<void>;
}
SQLite �唳摨��?
CREATE TABLE sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  role TEXT NOT NULL,
  content TEXT NOT NULL,
  timestamp INTEGER NOT NULL,
  created_at INTEGER DEFAULT (strftime('%s', 'now'))
);

CREATE INDEX idx_session_id ON sessions(session_id);
CREATE INDEX idx_timestamp ON sessions(session_id, timestamp);

擃漣�冽�

�芸�銋頂蝏�蝷箄�

�?prompts/ �桀��遣�芸�銋�蝷箄�嚗?

prompts/
���� default/
�?  ���� friendly.txt
�?  ���� tech-expert.txt
���� group/
�?  ���� active.txt
�?  ���� concise.txt
���� helper/
    ���� assistant.txt

餈��嗅��X�靘�

// �券�蝵桐葉
LLM_PROVIDER=ollama  // ��唳�唳芋�?
OLLAMA_MODEL=llama3:8b

�芸�銋圻���?

# 隞�摨?@ ��
GROUP_AI_TRIGGER=at

# 隞�摨�蝻��賭誘
GROUP_AI_TRIGGER=prefix

# 銝方���嚗�霈歹�
GROUP_AI_TRIGGER=both

���

敹恍���?

pnpm doctor

璉��仿★�殷�

  • Node.js �
  • �蔭�辣
  • API 餈
  • NapCatQQ 餈
  • SQLite �嗆�?

撣貉��桅�

� �箏鈭箸瓷��摨?/summary>
  1. 蝖株恕 NapCatQQ 甇�餈�
  2. 璉��?WebSocket 餈嚗ws://localhost:3001`嚗?
  3. 蝖桐� .env 銝?QQ_ENABLED=true
  4. 撉� API Key 撌脤�蝵?
  5. 璉��交�行迤蝖?@ �箏鈭?
� API 餈憭梯揖
  1. 撉� API Key 甇�&
  2. 璉��亥揭�瑟��舐憸漲
  3. 瘚�蝵�餈嚗ping dashscope.aliyuncs.com`
  4. 撉� Base URL 甇�&
� SQLite �秤
  1. 璉��亦敶��?
  2. 撉�蝤�蝛粹
  3. �撟園�撱箸�桀�嚗?
    rm data/sessions.db

�秤隞��

�秤 �思� 閫��寞�
401 Unauthorized API Key �� 璉��?API Key �蔭
Connection refused ��芸�? �臬撖孵��
WebSocket closed NapCatQQ �剖� � NapCatQQ
Model not found 璅∪�銝��? 銝蝸璅∪����亙�蝘?
Out of credit 雿�銝雲 ��潸揭�?

韐∠��

�賑甈Z����耦撘�韐∠嚗?

撘�憪插�?

  1. Fork �砌�摨?
  2. �遣�寞�批��荔�git checkout -b feature/AmazingFeature
  3. 餈��湔
  4. 餈�瘚�嚗pnpm test`
  5. �漱嚗git commit -m 'Add AmazingFeature'`
  6. �券��git push origin feature/AmazingFeature
  7. �漱 Pull Request

撘��挽蝵?

# 摰�靘�
pnpm install

# 撘��芋撘�銵?
pnpm dev

# 餈�隞��璉��?
pnpm lint

# 蝐餃�璉��?
pnpm typecheck

# �遣
pnpm build

霂西� CONTRIBUTING.md


撘�皞�霈?

�祇★�桅��典��悅璅∪�嚗?

蝏辣 �悅
撘�皞�? MIT License
���典� ��霈詨�悅

霂西� LICENSE


�湔�亙�

霂西� CHANGELOG.md

��餈�?

[2.0.0] - 2024-03-26

  • �� �冽�?Electron 獢摨�嗆�
  • � �箔� Vue 3 + TypeScript �隞���
  • �� �劓銝駁� UI 霈曇恣
  • � 蝞��芋撘�銝�璅∪��芋撘��?
  • � �航���蝵桀�撖?
  • �� �舀�憭像�?AI API
  • � �舀��砍 Ollama 璅∪�
  • �� �辣蝟餌��嗆�
  • �� 銝���韐孵��?
  • �� �銝駁��舀�

�頂�賑

皜� �暹
� �桃拳 contact@ai-robot.dev
� QQ蝢? 123456789
�� 摰� https://ai-robot.dev
�� �﹝ https://docs.ai-robot.dev
�� �桅��� GitHub Issues

Star History

Star History Chart


Made with �歹� by AI Robot Team

*潃?憒�餈葵憿寧撖嫣��葬�抬�霂瑞�銝�銝?Star 潃?

About

AI Robot - Your AI-Powered QQ Assistant. One-click installation, anti-ban protection, multi-model support. Windows/macOS/Linux.

Topics

Resources

License

Code of conduct

Contributing

Stars

Watchers

Forks

Packages

 
 
 

Contributors