QQcode

  ▇▇▇▇      ▇▇▇▇
▇▇    ▇▇  ▇▇    ▇▇
▇▇    ▇▇  ▇▇    ▇▇
▇▇  ▇▇▇▇  ▇▇  ▇▇▇▇
  ▇▇▇▇▇▇    ▇▇▇▇▇▇

Открытый исходный код CLI-помощника для программирования.

QQcode — это командный помощник для программирования на базе ИИ-моделей. Он предоставляет разговорный интерфейс к вашей кодовой базе, позволяя использовать естественный язык для изучения, изменения и взаимодействия с проектами с помощью мощного набора инструментов.

Поддержка: MacOS, Linux, Windows (экспериментальная).

Благодарности

QQcode является форком Mistral Vibe, оригинального CLI-помощника для программирования, разработанного Mistral AI.

Установка в одну строку (рекомендуется)

Linux и macOS

curl -LsSf https://raw.githubusercontent.com/qnguyen3/qqcode/main/scripts/install.sh | bash

Windows

Сначала установите uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Затем используйте команду uv ниже.

Использование uv

uv tool install qqcode

Использование pip

pip install qqcode

Возможности

• Интерактивный чат: Разговорный ИИ-агент, который понимает ваши запросы и разбивает сложные задачи на части.
• Мощный набор инструментов: Набор инструментов для работы с файлами, поиска кода, управления версиями и выполнения команд прямо из чата.
  • Чтение, запись и редактирование файлов.
  • Выполнение команд оболочки в терминале с сохранением состояния (bash).
  • Рекурсивный поиск кода с помощью grep (с поддержкой ripgrep).
  • Управление списком todo для отслеживания работы агента.
  • Навыки агента загружаются по требованию для предоставления дополнительного контекста.
• Контекст, осведомлённый о проекте: QQcode автоматически сканирует структуру файлов проекта и статус Git, чтобы предоставить агенту релевантный контекст, улучшая его понимание кодовой базы.
• Продвинутый CLI-опыт: Построен на современных библиотеках для плавного и эффективного рабочего процесса.
  • Автозаполнение для команд со слешем (/) и путей к файлам (@).
  • Сохранение истории команд.
  • Красивые темы.
• Высокая настраиваемость: Настройте модели, провайдеров, разрешения инструментов и предпочтения интерфейса через простой файл config.toml.
• Безопасность превыше всего: Функция подтверждения выполнения инструментов.

Быстрый старт

1. Перейдите в корневой каталог вашего проекта:

   bash cd /путь/к/вашему/проекту

2. Запустите QQcode:

   bash qqcode

3. Если вы запускаете QQcode впервые, он:

   • Создаст файл конфигурации по умолчанию в ~/.qqcode/config.toml
   • Предложит ввести ваш API-ключ, если он ещё не настроен
   • Сохранит ваш API-ключ в ~/.qqcode/.env для дальнейшего использования

4. Начните взаимодействовать с агентом!

   ```

   Можешь найти все упоминания слова "TODO" в проекте?

   🤖 Пользователь хочет найти все упоминания "TODO". Для этого идеально подходит инструмент grep. Я использую его для поиска в текущем каталоге.

   grep(pattern="TODO", path=".")

   ... (вывод инструмента grep) ...

   🤖 Я нашёл следующие комментарии "TODO" в вашем проекте. ```

Использование

Интерактивный режим

Просто запустите qqcode, чтобы войти в интерактивный чат.

• Многострочный ввод: Нажмите Ctrl+J или Shift+Enter (для некоторых терминалов), чтобы вставить новую строку.
• Пути к файлам: Ссылайтесь на файлы в запросе с помощью символа @ для умного автозаполнения (например, > Прочитай файл @src/agent.py).
• Команды оболочки: Добавьте префикс ! к любой команде, чтобы выполнить её напрямую в оболочке, минуя агента (например, > !ls -l).

Вы можете запустить QQcode с подсказкой, используя следующую команду:

qqcode "Refactor the main function in cli/main.py to be more modular."

Примечание: Флаг --auto-approve автоматически подтверждает выполнение всех инструментов без запроса. В интерактивном режиме вы также можете переключать автоподтверждение с помощью Shift+Tab.

Программный режим

Вы можете запускать QQcode неинтерактивно, передавая ввод через конвейер или используя флаг --prompt. Это полезно для скриптов.

qqcode --prompt "Refactor the main function in cli/main.py to be more modular."

по умолчанию используется режим auto-approve.

Команды со слешем

Используйте команды со слешем для мета-действий и изменений конфигурации во время сеанса.

Навыки

QQcode поддерживает Навыки, которые работают точно так же, как Claude Skills. Навыки позволяют расширять возможности QQcode с помощью пользовательских рабочих процессов, шаблонов и экспертных знаний в конкретной области. Чтобы создать навык, поместите директорию вашего навыка в .qqcode/skills/[ваш-навык], чтобы он был автоматически зарегистрирован и доступен агенту. Каждый навык должен содержать файл SKILL.md, в котором определены название, описание и инструкции навыка.

Пример структуры навыка:

.qqcode/
  skills/
    my-skill/
      SKILL.md
      scripts/
      templates/

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

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

QQcode настраивается через файл config.toml. Сначала он ищет этот файл в ./.qqcode/config.toml, а затем — в ~/.qqcode/config.toml.

Поддерживаемые провайдеры

QQcode поддерживает несколько провайдеров ИИ:

• Подписка Anthropic Claude Max: Доступ к моделям Claude с вашей подпиской на Claude.ai (запустите qqcode --login anthropic)
• OpenRouter: Доступ к нескольким моделям ИИ через единый API
• Mistral AI: Использование моделей Mistral напрямую

Настройка API-ключей

QQcode поддерживает несколько способов настройки API-ключей:

1. Интерактивная настройка (рекомендуется для новых пользователей): При первом запуске QQcode или если API-ключ отсутствует, QQcode предложит ввести его. Ключ будет надёжно сохранён в ~/.qqcode/.env для будущих сессий.

2. Переменные окружения: Установите API-ключ как переменную окружения:

   bash export OPENROUTER_API_KEY="ваш_openrouter_api_ключ"

3. Файл .env: Создайте файл .env в ~/.qqcode/ и добавьте свои API-ключи:

   bash OPENROUTER_API_KEY=ваш_openrouter_api_ключ

   QQcode автоматически загружает API-ключи из ~/.qqcode/.env при запуске. Переменные окружения имеют приоритет над файлом .env, если установлены оба варианта.

Примечание: Файл .env предназначен специально для API-ключей и других учётных данных провайдеров. Общая конфигурация QQcode должна выполняться в config.toml.

Пользовательские системные промпты

Вы можете создавать пользовательские системные промпты, чтобы заменить стандартный (prompts/cli.md). Создайте markdown-файл в директории ~/.qqcode/prompts/ с содержимым вашего пользовательского промпта.

Чтобы использовать пользовательский системный промпт, установите system_prompt_id в вашей конфигурации, чтобы он соответствовал имени файла (без расширения .md):

# Use a custom system prompt
system_prompt_id = "my_custom_prompt"

Это загрузит промпт из ~/.qqcode/prompts/my_custom_prompt.md.

Пользовательские конфигурации агентов

Вы можете создавать пользовательские конфигурации агентов для конкретных сценариев использования (например, red-teaming, специализированные задачи), добавляя TOML-файлы агентов в директорию ~/.qqcode/agents/.

Чтобы использовать пользовательского агента, запустите QQcode с флагом --agent:

qqcode --agent my_custom_agent

QQcode будет искать файл с именем my_custom_agent.toml в директории агентов и применит его конфигурацию.

Пример пользовательской конфигурации агента (~/.qqcode/agents/redteam.toml):

# Custom agent configuration for red-teaming
active_model = "devstral-2"
system_prompt_id = "redteam"

# Disable some tools for this agent
disabled_tools = ["edit", "write_file"]

# Override tool permissions for this agent
[tools.bash]
permission = "always"

[tools.read_file]
permission = "always"

Примечание: это подразумевает, что у вас настроен промпт redteam с именем ~/.qqcode/prompts/redteam.md

Конфигурация MCP-серверов

Вы можете настраивать MCP-серверы (Model Context Protocol) для расширения возможностей QQcode. Добавьте конфигурации MCP-серверов в секцию mcp_servers:

# Example MCP server configurations
[[mcp_servers]]
name = "my_http_server"
transport = "http"
url = "http://localhost:8000"
headers = { "Authorization" = "Bearer my_token" }
api_key_env = "MY_API_KEY_ENV_VAR"
api_key_header = "Authorization"
api_key_format = "Bearer {token}"

[[mcp_servers]]
name = "my_streamable_server"
transport = "streamable-http"
url = "http://localhost:8001"
headers = { "X-API-Key" = "my_api_key" }

[[mcp_servers]]
name = "fetch_server"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]

Поддерживаемые транспорты:

• http: Стандартный HTTP-транспорт
• streamable-http: HTTP-транспорт с поддержкой потоковой передачи
• stdio: Транспорт стандартного ввода/вывода (для локальных процессов)

Ключевые поля:

• name: Короткий псевдоним сервера (используется в именах инструментов)
• transport: Тип транспорта
• url: Базовый URL для HTTP-транспортов
• headers: Дополнительные HTTP-заголовки
• api_key_env: Переменная окружения, содержащая API-ключ
• command: Команда для запуска при stdio-транспорте
• args: Дополнительные аргументы для stdio-транспорта

Инструменты MCP именуются по шаблону {имя_сервера}_{имя_инструмента} и могут быть настроены с разрешениями, как встроенные инструменты:

# Configure permissions for specific MCP tools
[tools.fetch_server_get]
permission = "always"

[tools.my_http_server_query]
permission = "ask"

Включение/отключение инструментов с помощью шаблонов

Вы можете управлять тем, какие инструменты активны, используя enabled_tools и disabled_tools. Эти поля поддерживают точные имена, шаблоны glob и регулярные выражения.

Примеры:

# Only enable tools that start with "serena_" (glob)
enabled_tools = ["serena_*"]

# Regex (prefix with re:) — matches full tool name (case-insensitive)
enabled_tools = ["re:^serena_.*$"]

# Heuristic regex support (patterns like `serena.*` are treated as regex)
enabled_tools = ["serena.*"]

# Disable a group with glob; everything else stays enabled
disabled_tools = ["mcp_*", "grep"]

Примечания:

• Имена инструментов MCP используют подчёркивания, например, serena_list, а не serena.list.
• Шаблоны регулярных выражений сопоставляются с полным именем инструмента с помощью fullmatch.

Пользовательская домашняя директория QQcode

По умолчанию QQcode хранит свою конфигурацию в ~/.qqcode/. Вы можете переопределить это, установив переменную окружения QQCODE_HOME:

export QQCODE_HOME="/path/to/custom/qqcode/home"

Это влияет на то, где QQcode ищет:

• config.toml — основная конфигурация
• .env — API-ключи
• agents/ — пользовательские конфигурации агентов
• prompts/ — пользовательские системные промпты

• tools/ — Пользовательские инструменты
• logs/ — Журналы сессий

Ресурсы

• ЖУРНАЛ ИЗМЕНЕНИЙ — Узнайте, что нового в каждой версии
• РУКОВОДСТВО ПО ВКЛАДУ — Рекомендации по обратной связи и сообщениям об ошибках

Лицензия

Авторские права 2025 QQcode Team

Лицензировано на условиях лицензии Apache версии 2.0 («Лицензия»); использование этого файла допускается только в соответствии с Лицензией. Вы можете получить копию Лицензии по адресу:

http://www.apache.org/licenses/LICENSE-2.0

Если иное не требуется применимым законодательством или не согласовано в письменной форме, программное обеспечение, распространяемое на условиях Лицензии, распространяется на условиях «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, явных или подразумеваемых. Полный текст Лицензии см. в файле LICENSE.