ToolKit локальный агент навыков

Локальный помощник по навыкам, основанный на протоколе MCP (Model Context Protocol), поддерживающий пользовательские навыки, такие как калькулятор, запрос погоды и т.д., предоставляющий веб-интерфейс и API-интерфейс.

Структура проекта

..
├── .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

Технологический стек

Бэкенд-фреймворк: Python + Flask для создания веб-сервиса, предоставляющего RESTful API и интерфейс потоковой передачи SSE.

Протокол AI и вызов моделей: Основан на совместимом с OpenAI SDK для подключения к API больших моделей, поддерживает доступ к моделям в формате OpenAI, таким как Doubao.

Основной протокол: MCP (Model Context Protocol) для стандартизации вызовов инструментов, унификации регистрации и планирования навыков.

Асинхронная архитектура: Асинхронная обработка asyncio + изоляция пула потоков для решения проблем блокировки асинхронных вызовов в синхронной среде Flask.

Персистентность данных: SQLite для хранения контекста многосеансовых диалогов, поддержка управления сеансами и загрузки истории.

Плагины навыков: Модульная система навыков, поддержка расширяемых инструментов, таких как калькулятор, погода, поиск в сети и т.д.

Фронтенд: Веб-интерфейс на нативном HTML/JS, поддержка рендеринга Markdown, эффект потоковой печати, отображение цепочки рассуждений.

Инженерия: Конфигурация переменных API (.env), управление зависимостями (uv/pip), механизмы повторных попыток при ошибках и деградации, кэширование вызовов инструментов.

Основные функции

✅ Стабильная асинхронная обработка - Исправлена проблема прямого использования asyncio.run() в маршрутах Flask, используется пул потоков для выполнения асинхронных функций.

✅ Персистентность истории диалогов - Использование SQLite для хранения истории диалогов, данные не теряются при перезапуске службы, поддержка управления несколькими сеансами.

✅ Отказоустойчивость вызова инструментов - Механизм автоматического повтора, при сбое вызова инструмента происходит переход к прямому ответу модели.

✅ Кэширование инструментов MCP - Кэширование списка инструментов после первого получения для уменьшения накладных расходов на повторную инициализацию.

✅ Потоковый вывод - Реализован полный интерфейс потоковой передачи SSE, поддерживающий посимвольный вывод.

✅ Подсказки при вызове инструментов - При вызове навыка отображается подсказка "【Вызван инструмент: {название инструмента}】".

✅ Поддержка нескольких платформ - Предоставление как веб-интерфейса, так и интерфейса командной строки.

✅ Богатый набор навыков - Встроенные навыки калькулятора, запроса погоды и поиска в сети.

✅ Управление навыками - Визуальное управление навыками во фронтенде, возможность свободного включения/выключения навыков.

✅ Рендеринг Markdown - Поддержка ответов в формате Markdown, подсветка кода, таблицы, списки, математические формулы и т.д.

✅ Отображение цепочки рассуждений - Сворачиваемое отображение процесса мышления AI для облегчения понимания логики рассуждений.

✅ Управление несколькими сеансами - Поддержка создания нескольких независимых диалогов, каждый из которых сохраняет свою историю отдельно.

✅ Загрузка истории диалогов - Автоматическая загрузка истории диалогов при переключении сеансов, полная запись процесса взаимодействия.

Системные требования

• Python 3.11+

• openaiSDK(api)

• Инструмент управления пакетами uv (рекомендуется) или pip

Установка

Способ 1: Использование инструмента управления пакетами uv (рекомендуется)

1. Установка uv

   # 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. Клонирование проекта

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

3. Создание виртуальной среды

   uv venv

4. Установка зависимостей

   uv sync

Способ 2: Использование pip

1. Клонирование проекта

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

2. Создание виртуальной среды

   python -m venv venv

3. Активация виртуальной среды

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

4. Установка зависимостей

   pip install -r requirements.txt

Конфигурация

• Настройка ключа API во фронтенде

• Или заполнение ключа API в файле .env:

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

Запуск

Способ 1: Полный запуск (рекомендуется)

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

• Доступ к фронтенду: http://localhost:5000

• API-интерфейс: http://localhost:5000/api/*

Способ 2: Интерфейс командной строки

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

• Диалог прямо в терминале

• Поддержка многоходовых диалогов и истории

• Введите clear или 清除历史 для очистки истории диалогов

• Введите exit, quit или 退出 для выхода из программы

API-интерфейс

Примеры запросов API

Интерфейс чата

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"
  }'

Интерфейс потокового чата

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"
  }'

Интерфейс очистки истории

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

Как использовать

Веб-интерфейс

1. Настройка API

   • Введите API Key и Endpoint ID на панели конфигурации слева

   • Нажмите кнопку «Тест» для проверки подключения

2. Чат

   • Введите вопрос в поле ввода

   • Поддерживаемые навыки:

     • Калькулятор: 计算 123+456

     • Запрос погоды: 北京天气

     • Поиск в сети: 搜索 最新AI新闻

3. Управление навыками

   • Нажмите «🔧 技能管理» слева, чтобы развернуть панель

   • Просмотрите все доступные навыки и их описания

   • Нажмите переключатель для включения/выключения навыков

   • Будут вызываться только включенные навыки

4. Управление несколькими сеансами

   • Нажмите «💬 对话管理» слева, чтобы развернуть панель

   • Нажмите «➕ 新建对话» для создания нового сеанса

   • Нажмите на элемент списка сеансов для переключения на соответствующий диалог

   • Нажмите 🗑️ для удаления ненужного диалога

   • Каждый сеанс сохраняет историю отдельно

5. Просмотр результатов

   • Система автоматически вызовет соответствующий навык и вернет результат

   • Поддержка ответов в формате Markdown (подсветка кода, таблицы, списки и т.д.)

   • Можно нажать «🧠 思考过程» для просмотра логики рассуждений AI

   • Поддержка многоходовых диалогов

Интерфейс командной строки

1. Запуск программы

   python main.py

2. Ввод вопроса

   • Введите свой вопрос прямо в терминале

   • Поддерживаемые навыки:

     • Калькулятор: 计算 123+456

     • Запрос погоды: 北京天气

3. Просмотр результатов

   • Система автоматически вызовет соответствующий навык и вернет результат

   • Поддержка многоходовых диалогов

   • Введите clear или 清除历史 для очистки истории диалогов

Как добавить новый навык

Шаг 1: Создание файла навыка

Создайте новый файл навыка в каталоге skills/, например 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)}"

Шаг 2: Регистрация навыка

Отредактируйте skills/__init__.py, добавив функцию регистрации нового навыка:

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"
]

Шаг 3: Обновление службы MCP

Отредактируйте mcp_server.py, добавив регистрацию нового навыка:

from skills import register_calculator_tool, register_weather_tool, register_my_skill

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

Шаг 4: Перезапуск службы

Перезапустите службу MCP и бэкенд-службу, после чего новый навык можно будет использовать.

Спецификация разработки навыков

1. Именование файлов: используйте строчные буквы и подчеркивания

2. Именование функций: формат register_xxx_tool

3. Декоратор инструмента: используйте декоратор @mcp.tool()

4. Строка документации: должна содержать описание функции, примеры и описание параметров

5. Обработка ошибок: перехватывайте исключения и возвращайте дружелюбные подсказки

6. Типы параметров: используйте аннотации типов

Как создать сложный навык (с SKILL.md)

Для навыков с более сложной функциональностью рекомендуется создавать отдельный каталог навыка, содержащий реализацию навыка и файл описания SKILL.md.

Структура каталогов

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

Шаг 1: Создание каталога навыка и файла реализации

Создайте новый каталог навыка в каталоге skills/, например skills/my_complex_skill/

1.1 Создание файла реализации навыка my_skill.py

"""我的复杂技能实现"""
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 для экспорта конфигурации

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

__all__ = ["register_my_complex_skill"]

1.3 Создание документа описания SKILL.md

# 我的复杂技能

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

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

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

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

Формат возвращаемых результатов

• Результат 1: xxx

• Результат 2: xxx

Обработка исключений

Меры предосторожности

1. Меры предосторожности 1

2. Меры предосторожности 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"  # 新增
]

Шаг 3: Обновление mcp_server.py

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)  # 新增

Шаг 4: Установка дополнительных зависимостей (если требуется)

Если новому навыку требуются дополнительные пакеты Python, импортируйте их с помощью uv add или добавьте в requirements.txt:

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

Затем выполните:

uv sync
# 或
pip install 包名称

Шаг 5: Перезапуск службы

Перезапустите службу, после чего новый навык можно будет использовать.

Спецификация SKILL.md

Примеры навыков

Навык калькулятора

• Функция: поддержка сложения, вычитания, умножения, деления, скобок, возведения в степень

• Вызов: 计算 (10+5)*2

Навык запроса погоды

• Функция: запрос погоды в городе и прогноз

• Вызов: 上海天气 или 北京天气 3天

Навык поиска в сети

• Функция: использование DuckDuckGo для поиска последних новостей

• Вызов: 搜索 Python最新版本 или 搜索 今天科技新闻

• Зависимость: библиотека ddgs (pip install duckduckgo-search)

Технические особенности

1. Оптимизация асинхронной обработки - Использование пула потоков для выполнения асинхронных функций, что позволяет избежать проблемы создания нового цикла событий при каждом запросе

2. Персистентность истории диалогов - Персистентное хранилище на основе SQLite, данные не теряются при перезапуске службы, поддержка изоляции нескольких сеансов

3. Отказоустойчивость вызова инструментов - Автоматический повтор при сбое 2 раза, переход к прямому ответу модели, повышение надежности

4. Кэширование инструментов MCP - Уменьшение накладных расходов на повторную инициализацию, повышение скорости отклика

5. Реализация потокового вывода - Полный интерфейс потоковой передачи SSE, обеспечивающий лучший пользовательский опыт

6. Подсказки при вызове инструментов - Четкие подсказки при вызове инструментов, улучшающие пользовательский опыт

7. Поддержка нескольких платформ - Одновременное предоставление веб-интерфейса и интерфейса командной строки

8. Система управления навыками - Визуальное управление навыками во фронтенде, поддержка гибкого включения/выключения

9. Рендеринг Markdown - Полная поддержка Markdown, включая подсветку кода, таблицы и т.д.

10. Отображение цепочки рассуждений - Сворачиваемое отображение процесса рассуждений AI

11. Управление несколькими сеансами - Полная функциональность создания, переключения и удаления сеансов

12. Загрузка истории диалогов - Автоматическая загрузка и отображение истории сеансов

Меры предосторожности

1. Безопасность ключа API: не отправляйте ключ API в систему контроля версий

2. Безопасность навыков: избегайте выполнения опасных операций в навыках

3. Оптимизация производительности: для длительных операций рассмотрите возможность использования асинхронной обработки

4. Обработка ошибок: убедитесь, что навык может корректно обрабатывать исключительные ситуации

Устранение неполадок

• Ошибка подключения: проверьте ключ API и сетевое подключение

• Навык не отвечает: проверьте, нормально ли работает служба MCP

• Не отображается во фронтенде: проверьте консоль браузера на наличие ошибок

• Проблемы с потоковым интерфейсом: убедитесь, что сетевое соединение стабильно, избегайте разрывов

• Ошибка базы данных: проверьте права доступа к файлу chat_history.db, убедитесь, что он доступен для чтения и записи

Хранение данных

Проект использует базу данных SQLite для персистентного хранения истории диалогов:

• Файл базы данных: chat_history.db (в корневом каталоге проекта, создается автоматически при первом запуске)

• Структура таблицы:

  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
  )

• Просмотр истории: используйте инструменты SQLite или командную строку

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

Предложения по расширению

1. Больше навыков: добавление перевода, запроса акций, новостей и т.д.

2. Поддержка нескольких языков: добавление многоязычного интерфейса

3. Оптимизация развертывания: использование контейнеризации Docker

4. Рынок навыков: создание рынка навыков, поддержка обмена и загрузки навыков пользователями

5. Переключение моделей: поддержка переключения между различными большими языковыми моделями

Журнал обновлений

2026-03-29 Крупное обновление

Обновление способа вызова API

• httpx → OpenAI SDK: все вызовы API изменены с прямых HTTP-запросов httpx на использование SDK openai>=1.0.0

• Переименование полей конфигурации:

  • DOUBAO_API_KEY → OPENAI_API_KEY

  • DOUBAO_ENDPOINT_ID → OPENAI_MODEL

  • DOUBAO_BASE_URL → OPENAI_BASE_URL (удален суффикс /chat/completions)

Оптимизация вызова инструментов

• Очистка схемы: автоматическое удаление полей title, default и других, не поддерживаемых API Doubao

• Очистка описания: сжатие лишних пробельных символов, оптимизация формата

• Преобразование сообщений: добавлена функция _msg_to_dict() для корректной обработки объекта ChatCompletionMessage, возвращаемого SDK OpenAI

• Второй вызов: исправлена проблема формата сообщений при повторном запросе после вызова инструмента

Исправление ошибок

• ✅ Исправлена ошибка "Object of type ChatCompletionMessage is not JSON serializable"

• ✅ Исправлена проблема преобразования типов при сохранении истории сообщений

• ✅ Добавлена подробная трассировка стека исключений для облегчения отладки

Улучшения архитектуры

• Добавлена вспомогательная функция _msg_to_dict() для унификации преобразования формата сообщений

• Добавлено определение типа API (API Xunfei автоматически пропускает параметр tools)

• Оптимизирована обработка исключений и вывод логов в маршруте chat()