ToolKit lokaler Skill-Agent

Ein lokaler Skill-Assistent auf Basis des MCP-Protokolls (Model Context Protocol), der benutzerdefinierte Skills wie Taschenrechner und Wetterabfragen unterstützt und eine Web-Oberfläche sowie API-Schnittstellen bietet.

Projektstruktur

..
├── .env                    # 大模型 API 配置
├── chat_history.db         # SQLite 对话历史数据库（自动生成）
├── index.html              # 前端 Web 界面
├── main.py                 # 主入口（命令行界面）
├── mcp_server.py          # MCP 服务端（核心）
├── server.py               # Flask 后端服务
├── requirements.txt        # 依赖清单
├── README.md               # 项目说明
├── tree.txt                # 目录结构
├── client/                 # 客户端目录
│   ├── doubao_mcp_client.py  # 豆包 API 客户端
│   └── __init__.py
├── config/                 # 配置目录
│   ├── settings.py         # 全局配置
│   └── __init__.py
└── skills/                 # 技能实现目录
    ├── calculator.py       # 计算器技能
    ├── weather.py          # 天气查询技能
    ├── web_search/         # 网络搜索技能目录
    │   └── web_search.py   # DuckDuckGo搜索实现
    |   └── SKILL.md  # skill描述
    |   └── _init_.py   
    └── __init__.py

Related MCP server: MCP Connection Hub

Tech-Stack

Backend-Framework: Python + Flask für den Web-Service, bietet RESTful API und SSE-Streaming-Schnittstellen.

KI-Protokoll & Modellaufruf: Basiert auf dem OpenAI-kompatiblen SDK zur Anbindung von Large Language Model APIs, unterstützt Modelle im OpenAI-Format wie Doubao.

Kernprotokoll: MCP (Model Context Protocol) zur Standardisierung von Tool-Aufrufen sowie zur einheitlichen Skill-Registrierung und -Steuerung.

Asynchrone Architektur: asyncio-asynchrone Verarbeitung + Thread-Pool-Isolierung zur Lösung von Blockaden bei asynchronen Aufrufen in der synchronen Flask-Umgebung.

Datenpersistenz: SQLite zur Speicherung des Dialogkontexts über mehrere Sitzungen hinweg, unterstützt Sitzungsverwaltung und das Laden von Historien.

Skill-Plugin-System: Modulares Skill-System, unterstützt erweiterbare Tools wie Taschenrechner, Wetter, Websuche usw.

Frontend: Native HTML/JS-Weboberfläche, unterstützt Markdown-Rendering, Streaming-Schreibeffekte und die Anzeige von Gedankengängen (Chain of Thought).

Engineering: API-Variablenkonfiguration (.env), Abhängigkeitsmanagement (uv/pip), Fehlerwiederholungs- und Fallback-Mechanismen, Caching von Tool-Aufrufen.

Kernfunktionen

✅ Stabile asynchrone Verarbeitung - Problem behoben, bei dem asyncio.run() direkt in Flask-Routen verwendet wurde; stattdessen wird ein Thread-Pool zur Ausführung asynchroner Funktionen genutzt.

✅ Persistenz der Dialoghistorie - Verwendung von SQLite zur Speicherung der Dialoghistorie, kein Verlust bei Neustart des Dienstes, Unterstützung für Multi-Session-Management.

✅ Fehlertoleranz bei Tool-Aufrufen - Automatischer Wiederholungsmechanismus; bei Fehlschlagen eines Tool-Aufrufs erfolgt ein Fallback auf eine direkte Antwort des Modells.

✅ MCP-Tool-Caching - Zwischenspeicherung der Tool-Liste nach dem ersten Abruf, um wiederholten Initialisierungsaufwand zu reduzieren.

✅ Streaming-Ausgabe - Implementierung einer vollständigen SSE-Streaming-Schnittstelle für eine wortweise Ausgabe.

✅ Hinweise zu Tool-Aufrufen - Bei Aufruf eines Skills wird der Hinweis "【Tool aufgerufen: {Tool-Name}】" angezeigt.

✅ Multi-Plattform-Unterstützung - Bietet sowohl eine Web-Oberfläche als auch eine Befehlszeilenschnittstelle (CLI).

✅ Umfangreiche Skills - Integrierte Skills für Taschenrechner, Wetterabfragen und Websuche.

✅ Skill-Management - Visuelle Skill-Verwaltung im Frontend, Skills können frei aktiviert/deaktiviert werden.

✅ Markdown-Rendering - Unterstützung für Markdown-Antworten, inklusive Code-Highlighting, Tabellen, Listen, mathematischen Formeln usw.

✅ Anzeige von Gedankengängen - Aufklappbare Anzeige des KI-Denkprozesses zur besseren Nachvollziehbarkeit der Schlussfolgerungslogik.

✅ Multi-Session-Management - Unterstützung für die Erstellung mehrerer unabhängiger Dialoge, wobei jeder Dialog seine Historie separat speichert.

✅ Laden der Dialoghistorie - Automatisches Laden der Historie beim Wechsel zwischen Sitzungen, vollständige Aufzeichnung des Interaktionsverlaufs.

Systemanforderungen

• Python 3.11+

• openaiSDK(api)

• uv Paketmanager (empfohlen) oder pip

Installation

Methode 1: Verwendung des uv-Paketmanagers (empfohlen)

1. uv installieren

   # Windows
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 
   irm https://astral.sh/uv/install.ps1 | iex
   
   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Projekt klonen

   git clone https://github.com/taffy123d/Doubao-MCP-agent
   cd <项目目录>

3. Virtuelle Umgebung erstellen

   uv venv

4. Abhängigkeiten installieren

   uv sync

Methode 2: Verwendung von pip

1. Projekt klonen

   git clone https://github.com/taffy123d/Doubao-MCP-agent
   cd <项目目录>

2. Virtuelle Umgebung erstellen

   python -m venv venv

3. Virtuelle Umgebung aktivieren

   # Windows
   venv\Scripts\activate
   
   # macOS / Linux
   source venv/bin/activate

4. Abhängigkeiten installieren

   pip install -r requirements.txt

Konfiguration

• API-Schlüssel im Frontend konfigurieren

• Oder API-Schlüssel in der .env-Datei eintragen:

# OpenAI 兼容格式的 API 配置
OPENAI_API_KEY=你的API密钥
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
OPENAI_MODEL=你的模型ID

Ausführung

Methode 1: Vollständiger Start (empfohlen)

uv run server.py
#或者
python server.py

• Frontend-Zugriff: http://localhost:5000

• API-Schnittstelle: http://localhost:5000/api/*

Methode 2: Befehlszeilenschnittstelle (CLI)

uv run main.py
#或者
python main.py

• Dialog direkt im Terminal führen

• Unterstützt Multi-Turn-Dialoge und Historie

• Eingabe von clear oder 清除历史 löscht die Dialoghistorie

• Eingabe von exit, quit oder 退出 beendet das Programm

API-Schnittstellen

API-Anfragebeispiele

Chat-Schnittstelle

curl -X POST http://localhost:5000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "你的API密钥",
    "model": "你的模型ID",
    "base_url": "https://ark.cn-beijing.volces.com/api/v3",
    "message": "北京天气",
    "session_id": "default"
  }'

Streaming-Chat-Schnittstelle

curl -X POST http://localhost:5000/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "你的API密钥",
    "model": "你的模型ID",
    "base_url": "https://ark.cn-beijing.volces.com/api/v3",
    "message": "北京天气",
    "session_id": "default"
  }'

Historie löschen

curl -X POST http://localhost:5000/api/chat/clear \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "default"
  }'

Verwendung

Web-Oberfläche

1. API konfigurieren

   • API-Key und Endpoint-ID im Konfigurationspanel auf der linken Seite eingeben.

   • Auf "Test" klicken, um die Verbindung zu verifizieren.

2. Chatten

   • Frage in das Eingabefeld eingeben.

   • Unterstützte Skills:

     • Taschenrechner: 计算 123+456

     • Wetterabfrage: 北京天气

     • Websuche: 搜索 最新AI新闻

3. Skill-Management

   • Auf "🔧 Skill-Management" links klicken, um das Panel zu öffnen.

   • Alle verfügbaren Skills und deren Beschreibungen einsehen.

   • Schalter zum Aktivieren/Deaktivieren von Skills nutzen.

   • Nur aktivierte Skills werden aufgerufen.

4. Multi-Session-Management

   • Auf "💬 Dialog-Management" links klicken, um das Panel zu öffnen.

   • Auf "➕ Neuer Dialog" klicken, um eine neue Sitzung zu erstellen.

   • Auf einen Eintrag in der Liste klicken, um zur entsprechenden Sitzung zu wechseln.

   • Auf 🗑️ klicken, um nicht benötigte Dialoge zu löschen.

   • Jeder Dialog speichert seine Historie separat.

5. Ergebnisse anzeigen

   • Das System ruft automatisch den entsprechenden Skill auf und liefert das Ergebnis.

   • Unterstützung für Markdown-Antworten (Code-Highlighting, Tabellen, Listen etc.).

   • Auf "🧠 Denkprozess" klicken, um die Schlussfolgerungslogik der KI einzusehen.

   • Unterstützung für Multi-Turn-Dialoge.

Befehlszeilenschnittstelle (CLI)

1. Programm ausführen

python main.py

2. Frage eingeben

   • Frage direkt im Terminal eingeben.

   • Unterstützte Skills:

     • Taschenrechner: 计算 123+456

     • Wetterabfrage: 北京天气

3. Ergebnisse anzeigen

   • Das System ruft automatisch den entsprechenden Skill auf und liefert das Ergebnis.

   • Unterstützung für Multi-Turn-Dialoge.

   • Eingabe von clear oder 清除历史 löscht die Dialoghistorie.

Wie man neue Skills hinzufügt

Schritt 1: Skill-Datei erstellen

Erstellen Sie eine neue Skill-Datei im Verzeichnis skills/, z. B. my_skill.py:

"""我的自定义技能"""
from mcp.server.fastmcp import FastMCP

def register_my_skill(mcp: FastMCP):
    """注册技能到 MCP 服务"""
    
    @mcp.tool()
    def my_skill(param1: str, param2: int = 1) -> str:
        """
        我的自定义技能描述
        示例：my_skill(param1="值", param2=2)
        
        Args:
            param1: 参数1描述
            param2: 参数2描述（默认值）
        Returns:
            技能执行结果
        """
        try:
            # 技能逻辑实现
            result = f"处理结果: {param1} - {param2}"
            return result
        except Exception as e:
            return f"处理失败: {str(e)}"

Schritt 2: Skill registrieren

Bearbeiten Sie skills/__init__.py und fügen Sie die Registrierungsfunktion für den neuen Skill hinzu:

from .calculator import register_calculator_tool
from .weather import register_weather_tool
from .my_skill import register_my_skill

__all__ = [
    "register_calculator_tool", 
    "register_weather_tool",
    "register_my_skill"
]

Schritt 3: MCP-Dienst aktualisieren

Bearbeiten Sie mcp_server.py und fügen Sie die Registrierung des neuen Skills hinzu:

from skills import register_calculator_tool, register_weather_tool, register_my_skill

# 注册所有技能工具
register_calculator_tool(mcp)
register_weather_tool(mcp)
register_my_skill(mcp)  # 添加这一行

Schritt 4: Dienst neu starten

Starten Sie den MCP-Dienst und den Backend-Dienst neu, damit der neue Skill verwendet werden kann.

Skill-Entwicklungsrichtlinien

1. Dateibenennung: Verwenden Sie Kleinbuchstaben und Unterstriche.

2. Funktionsbenennung: Format register_xxx_tool.

3. Tool-Dekorator: Verwenden Sie @mcp.tool().

4. Docstrings: Enthalten Funktionsbeschreibung, Beispiele und Parametererklärungen.

5. Fehlerbehandlung: Fangen Sie Ausnahmen ab und geben Sie benutzerfreundliche Hinweise zurück.

6. Parametertypen: Verwenden Sie Typannotationen.

Wie man komplexe Skills erstellt (mit SKILL.md)

Für komplexere Skills wird empfohlen, ein separates Skill-Verzeichnis zu erstellen, das die Implementierung und eine SKILL.md-Beschreibungsdatei enthält.

Verzeichnisstruktur

skills/
└── my_complex_skill/          # skill 目录
    ├── __init__.py            # 导出配置（必选）
    ├── my_skill.py            # 技能实现（必选）
    └── SKILL.md               # skill 描述文档（必选）

Schritt 1: Skill-Verzeichnis und Implementierungsdatei erstellen

Erstellen Sie ein neues Skill-Verzeichnis im Verzeichnis skills/, z. B. skills/my_complex_skill/

1.1 Skill-Implementierungsdatei my_skill.py erstellen

"""我的复杂技能实现"""
from mcp.server.fastmcp import FastMCP
from duckduckgo_search import AsyncDuckDuckGoSearcher  # 示例依赖

def register_my_complex_skill(mcp: FastMCP):
    """注册复杂技能到 MCP 服务"""
    
    @mcp.tool()
    async def my_complex_skill(query: str, limit: int = 5) -> str:
        """
        我的复杂技能描述
        
        Args:
            query: 查询关键词
            limit: 返回结果数量，默认5
        
        Returns:
            格式化的搜索结果
        """
        try:
            async with AsyncDuckDuckGoSearcher() as searcher:
                results = await searcher.atext(query, max_results=limit)
                # 处理并返回结果
                return f"找到 {len(results)} 条结果..."
        except Exception as e:
            return f"搜索失败: {str(e)}"

1.2 __init__.py zur Konfigurationsexportierung erstellen

"""my_complex_skill - 我的复杂技能"""
from .my_skill import register_my_complex_skill

__all__ = ["register_my_complex_skill"]

1.3 SKILL.md-Beschreibungsdokument erstellen

# 我的复杂技能

## 功能描述
一句话描述技能功能...

## 使用场景
### ✅ 适用场景
- 场景1
- 场景2

## 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | - | 查询关键词 |

## 使用示例
```python
# 示例1
my_complex_skill(query="关键词")

Format der Rückgabeergebnisse

• Ergebnis 1: xxx

• Ergebnis 2: xxx

Fehlerbehandlung

Hinweise

1. Hinweis 1

2. Hinweis 2

### 步骤 2：更新 skills/__init__.py

```python
from .calculator import register_calculator_tool
from .weather import register_weather_tool
from .web_search import register_web_search_tool
from .my_complex_skill import register_my_complex_skill  # 新增

__all__ = [
    "register_calculator_tool", 
    "register_weather_tool",
    "register_web_search_tool",
    "register_my_complex_skill"  # 新增
]

Schritt 3: mcp_server.py aktualisieren

from skills import (
    register_calculator_tool, 
    register_weather_tool, 
    register_web_search_tool,
    register_my_complex_skill  # 新增
)

# 注册所有技能工具
register_calculator_tool(mcp)
register_weather_tool(mcp)
register_web_search_tool(mcp)
register_my_complex_skill(mcp)  # 新增

Schritt 4: Zusätzliche Abhängigkeiten installieren (falls erforderlich)

Wenn der neue Skill zusätzliche Python-Pakete benötigt, fügen Sie diese mit uv add hinzu oder tragen Sie sie in die requirements.txt ein:

uv add 包名称
或
包名称 >=版本号 #requirements.txt

Führen Sie dann aus:

uv sync
# 或
pip install 包名称

Schritt 5: Dienst neu starten

Starten Sie den Dienst neu, damit der neue Skill verwendet werden kann.

SKILL.md-Spezifikation

Beispiel-Skills

Taschenrechner-Skill

• Funktion: Unterstützt Addition, Subtraktion, Multiplikation, Division, Klammern und Potenzrechnung.

• Aufruf: 计算 (10+5)*2

Wetterabfrage-Skill

• Funktion: Abfrage von Stadtwetter und Vorhersagen.

• Aufruf: 上海天气 oder 北京天气 3天

Websuche-Skill

• Funktion: Nutzt DuckDuckGo zur Suche nach aktuellen Informationen.

• Aufruf: 搜索 Python最新版本 oder 搜索 今天科技新闻

• Abhängigkeit: ddgs-Bibliothek (pip install duckduckgo-search)

Technische Highlights

1. Optimierung der asynchronen Verarbeitung - Verwendung eines Thread-Pools zur Ausführung asynchroner Funktionen, um das Problem der Erstellung neuer Event-Loops bei jeder Anfrage zu vermeiden.

2. Persistenz der Dialoghistorie - SQLite-basierte persistente Speicherung, kein Verlust bei Neustart, Unterstützung für Sitzungsisolierung.

3. Fehlertoleranz bei Tool-Aufrufen - Automatischer Wiederholungsversuch (2x) bei Fehlern, Fallback auf direkte Modellantwort zur Erhöhung der Robustheit.

4. MCP-Tool-Caching - Reduzierung des Initialisierungsaufwands, Verbesserung der Reaktionsgeschwindigkeit.

5. Streaming-Ausgabe - Vollständige SSE-Streaming-Schnittstelle für bessere Benutzererfahrung.

6. Hinweise zu Tool-Aufrufen - Klare Hinweise bei Tool-Aufrufen zur Verbesserung der Benutzererfahrung.

7. Multi-Plattform-Unterstützung - Bietet gleichzeitig Web-Oberfläche und CLI.

8. Skill-Management-System - Visuelle Skill-Verwaltung im Frontend mit flexibler Aktivierung/Deaktivierung.

9. Markdown-Rendering - Vollständige Markdown-Unterstützung, inklusive Code-Highlighting, Tabellen etc.

10. Anzeige von Gedankengängen - Aufklappbare Anzeige des KI-Schlussfolgerungsprozesses.

11. Multi-Session-Management - Vollständige Funktionen zum Erstellen, Wechseln und Löschen von Sitzungen.

12. Laden der Dialoghistorie - Automatisches Laden und Anzeigen der Sitzungshistorie.

Hinweise

1. API-Schlüssel-Sicherheit: API-Schlüssel nicht in die Versionskontrolle einchecken.

2. Skill-Sicherheit: Vermeiden Sie gefährliche Operationen innerhalb von Skills.

3. Performance-Optimierung: Erwägen Sie bei zeitaufwendigen Operationen die Verwendung asynchroner Verarbeitung.

4. Fehlerbehandlung: Stellen Sie sicher, dass Skills Ausnahmen elegant behandeln.

Fehlerbehebung

• Verbindungsfehler: API-Schlüssel und Netzwerkverbindung prüfen.

• Skill reagiert nicht: Prüfen, ob der MCP-Dienst ordnungsgemäß läuft.

• Frontend zeigt nichts an: Browser-Konsole auf Fehler prüfen.

• Probleme mit Streaming-Schnittstelle: Stabile Netzwerkverbindung sicherstellen, Verbindungsabbrüche vermeiden.

• Datenbankfehler: Berechtigungen der Datei chat_history.db prüfen, Lese-/Schreibzugriff sicherstellen.

Datenspeicherung

Das Projekt verwendet eine SQLite-Datenbank zur Persistenz der Dialoghistorie:

• Datenbankdatei: chat_history.db (im Projektstammverzeichnis, wird beim ersten Start automatisch generiert).

• Tabellenstruktur:

  CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,    -- 会话ID，支持多会话隔离
    role TEXT NOT NULL,           -- 角色（user/assistant/tool）
    content TEXT NOT NULL,        -- 消息内容
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
  )

• Historie abfragen: SQLite-Tools oder Befehlszeile verwenden.

  sqlite3 chat_history.db "SELECT * FROM messages ORDER BY timestamp DESC LIMIT 10;"

Erweiterungsvorschläge

1. Weitere Skills: Übersetzung, Aktienabfrage, Nachrichten usw. hinzufügen.

2. Mehrsprachigkeit: Mehrsprachige Benutzeroberfläche hinzufügen.

3. Deployment-Optimierung: Containerisierung mit Docker.

4. Skill-Marktplatz: Erstellung eines Marktplatzes zum Teilen und Herunterladen von Skills.

5. Modellwechsel: Unterstützung für den Wechsel zwischen verschiedenen Large Language Models.

Änderungsprotokoll

2026-03-29 Großes Update

Upgrade der API-Aufrufmethode

• httpx → OpenAI SDK: Alle API-Aufrufe wurden von direkten httpx-HTTP-Anfragen auf das openai>=1.0.0 SDK umgestellt.

• Umbenennung von Konfigurationsfeldern:

  • DOUBAO_API_KEY → OPENAI_API_KEY

  • DOUBAO_ENDPOINT_ID → OPENAI_MODEL

  • DOUBAO_BASE_URL → OPENAI_BASE_URL (Suffix /chat/completions entfernt).

Optimierung der Tool-Aufrufe

• Schema-Bereinigung: Automatische Entfernung von Feldern wie title, default etc., die von der Doubao-API nicht unterstützt werden.

• Beschreibung-Bereinigung: Komprimierung überflüssiger Leerzeichen, Formatoptimierung.

• Nachrichtenkonvertierung: Funktion _msg_to_dict() hinzugefügt, um das vom OpenAI SDK zurückgegebene ChatCompletionMessage-Objekt korrekt zu verarbeiten.

• Zweiter Aufruf: Problem mit dem Nachrichtenformat bei Zweitanfragen nach einem Tool-Aufruf behoben.

Fehlerbehebungen

• ✅ Fehler "Object of type ChatCompletionMessage is not JSON serializable" behoben.

• ✅ Problem bei der Typkonvertierung beim Speichern der Nachrichtenhistorie behoben.

• ✅ Detaillierte Stack-Traces für Ausnahmen zur einfacheren Fehlersuche hinzugefügt.

Architekturverbesserungen

• Hilfsfunktion _msg_to_dict() hinzugefügt, um die Nachrichtenformatkonvertierung zu vereinheitlichen.

• API-Typ-Erkennung hinzugefügt (Xunfei-API überspringt automatisch den tools-Parameter).

• Fehlerbehandlung und Protokollierung der chat()-Route optimiert.