Участие в разработке

Спасибо за вклад в VibeOS. Здесь: dev-окружение, ориентация в коде и как довести PR до merge.

Приоритеты

В таком порядке:

1. Багфиксы — краши, неверное поведение, потеря данных
2. Кроссплатформа — macOS, дистрибутивы Linux, WSL2
3. Безопасность — shell injection, prompt injection, path traversal
4. Надёжность и перф — retries, ошибки, graceful degradation
5. Новые навыки — широко полезные (см. Создание навыков)
6. Новые tools — редко; большинство capability → навыки
7. Документация — правки, пояснения, примеры

Типичные входы

• Custom/local tool без правок core → Создать плагин VibeOS
• Новый встроенный core tool → Добавление инструментов
• Новый навык → Создание навыков
• Новый inference-провайдер → Добавление провайдеров

Настройка разработки

Предварительные требования

Требование	Примечания
Гит	При установленном расширении git-lfs
Python 3.11+	uv установит его, если он отсутствует
УФ	Быстрый менеджер пакетов Python (install)
Node.js 20+	Необязательно — необходимо для инструментов браузера и моста WhatsApp (соответствует корневому движку package.json)

Установка с помощью стандартного установщика

Для большинства участников лучшая загрузочная программа для разработки это тот же путь, пользователи принимайте: запустите стандартный установщик, а затем работайте внутри клонированного репозитория. Установщик создает VibeOS venv, подключает команду vibeos, отмечает метод install для vibeos update и клонирует полный проект git в $VIBEOS_HOME/vibeos-agent (обычно ~/.vibeos/vibeos-agent). Благодаря этому ваша среда разработки будет иметь тот же макет, что и CLI, средство обновления, отложенная зависимость установщик, шлюз и документация.

curl -fsSL https://vibeos.com.ru/downloads/install.sh | bash
cd "${VIBEOS_HOME:-$HOME/.vibeos}/vibeos-agent"

# Add dev/test extras on top of the standard install.
uv pip install -e ".[all,dev]"

# Optional: browser tools / docs site dependencies.
npm install

После этого создайте ветки и запустите тесты из этой проверки:

git checkout -b fix/description
scripts/run_tests.sh

Резервное клонирование вручную

Используйте это только в том случае, если вы намеренно не хотите, чтобы VibeOS' управлял макет установки (например, одноразовый клон внутри контейнера или задания CI). Если вы устанавливаете таким образом, убедитесь, что вы запустили точку входа vibeos из этого venv; запуск системы python3 -m vibeos_cli.main может загрузить несвязанную систему Python packages.

git clone https://github.com/Linx72/VibeOS.git
cd vibeos-agent

# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras (messaging, cron, CLI menus, dev tools)
uv pip install -e ".[all,dev]"

# Optional: browser tools
npm install

Настройка для разработки

mkdir -p ~/.vibeos/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.vibeos/config.yaml
touch ~/.vibeos/.env

# Add at minimum an LLM provider key:
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.vibeos/.env

Запустить

# The standard installer already put `vibeos` on PATH.
vibeos doctor
vibeos chat -q "Hello"

Если вы использовали резервное клонирование вручную, запустите ./vibeos из оформления заказа или symlink явно на venv этого клона:

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/vibeos" ~/.local/bin/vibeos

Выполнить тесты

scripts/run_tests.sh

Стиль кода

• PEP 8 с практическими исключениями (без строгого соблюдения длины строки)
• Комментарии: Только при объяснении неочевидных намерений, компромиссов, или API quirks
• Обработка ошибок: перехват определенных исключений. Используйте logger.warning()/logger.error() с exc_info=True для непредвиденных ошибок
• Кроссплатформенность: Никогда не предполагайте, что Unix (см. ниже)
• Пути, безопасные для профиля: Никогда не закодируйте ~/.vibeos — используйте get_vibeos_home() от vibeos_constants для путей кода и display_vibeos_home() для сообщений, предназначенных для пользователя. Полные правила см. в AGENTS.md.

Межплатформенная совместимость

См. [Платформа] Поддержка](../getting-started/platform-support.md). Собственный Windows использует Git Bash (из Git for Windows) для команд оболочки. Некоторые функции требуют POSIX примитивов ядра и являются закрытыми: для встроенной панели терминала PTY панели мониторинга (/chat вкладка) требуется POSIX PTY (Linux, macOS или WSL2). Если вы используете Windows-heavy dev, запустите Windows-footgun lint (scripts/check-windows-footguns.py) перед отправкой.

При добавлении кода соблюдайте эти правила. помните:

• Не добавляйте незащищенные ссылки signal.SIGKILL. Это не определено в Windows. Либо маршрут через gateway.status.terminate_pid(pid, force=True) (централизованный примитив, который выполняет taskkill /T /F на Windows и SIGKILL на POSIX), либо откат с помощью getattr(signal, "SIGKILL", signal.SIGTERM).
• Перехват OSError вместе с ProcessLookupError на зондах os.kill(pid, 0). Windows вызывает OSError (WinError 87, "параметр неверен") для уже исчезнувшего PID вместо ProcessLookupError.
• Не заставляйте терминал принудительно использовать семантику POSIX. os.setsid, os.killpg, os.getpgid, os.fork все поднять на Windows — закройте их с помощью if sys.platform != "win32": или if os.name != "nt":.
• Открывайте файлы с явным encoding="utf-8". Python по умолчанию на Windows это системный языковой стандарт (часто cp1252), который моджибаксируется или аварийно завершает работу при тексте, не написанном на латинице.
• Используйте pathlib.Path / os.path.join — никогда не объединяйте вручную с /. Это имеет меньшее значение для строк, которые возвращает нам ОС, и больше для строк, которые мы создаем для передачи подпроцессам.

Ключевые шаблоны:

1. termios и fcntl являются Только для Unix

Всегда ловить оба ImportError и NotImplementedError:

try:
    from simple_term_menu import TerminalMenu
    menu = TerminalMenu(options)
    idx = menu.show()
except (ImportError, NotImplementedError):
    # Fallback: numbered menu
    for i, opt in enumerate(options):
        print(f"  {i+1}. {opt}")
    idx = int(input("Choice: ")) - 1

2. Кодировка файла

В некоторых средах файлы .env могут сохраняться в форматах, отличных от UTF-8. кодировки:

try:
    load_dotenv(env_path)
except UnicodeDecodeError:
    load_dotenv(env_path, encoding="latin-1")

3. Управление процессами

os.setsid(), os.killpg() и обработка сигналов различаются в зависимости от платформы:

import platform
if platform.system() != "Windows":
    kwargs["preexec_fn"] = os.setsid

4. Разделители путей

Используйте pathlib.Path вместо конкатенации строк с помощью /.

Вопросы безопасности

VibeOS имеет терминальный доступ. Безопасность имеет значение.

Существующие средства защиты

Слой	Реализация
Передача паролей Sudo	Использует shlex.quote() для предотвращения внедрения оболочки
Обнаружение опасных команд	Шаблоны регулярных выражений в tools/approval.py с потоком одобрения пользователей
Быстрое внедрение Cron	Сканер блокирует шаблоны переопределения инструкций
Создание списка запретов	Защищенные пути разрешены с помощью os.path.realpath(), чтобы предотвратить обход символических ссылок
Навыки охраны	Сканер безопасности для навыков, установленных в хабе
Песочница выполнения кода	Дочерний процесс запускается с удаленными ключами API
Упрочнение контейнера	Docker: все возможности отключены, повышение привилегий отсутствует, PID ограничения

Внесение чувствительного к безопасности кода

• Всегда использовать shlex.quote() при интерполяции вводимых пользователем данных в команды оболочки
• Разрешать символические ссылки с помощью os.path.realpath() перед проверками контроля доступа
• Не регистрировать секреты
• Отлавливать общие исключения, связанные с выполнением инструмента
• Протестируйте на всех платформах, если ваше изменение затрагивает пути к файлам или процессы

Процесс запроса на включение

Именование ветвей

fix/description        # Bug fixes
feat/description       # New features
docs/description       # Documentation
test/description       # Tests
refactor/description   # Code restructuring

Перед отправкой

1. Выполните тесты: scripts/run_tests.sh для проверки четности CI. Используйте прямой python -m pytest ... только в том случае, если оболочка недоступна или вы намеренно выполняете отладку вне оболочки.
2. Проверьте вручную: запустите vibeos и проверьте путь кода, который вы изменили
3. Проверьте влияние кроссплатформенности: рассмотрите macOS, Linux, WSL2 и встроенный Windows. Если вы коснетесь файла I/O, управления процессами, обработки терминала, подпроцессов или сигналов, запустите scripts/check-windows-footguns.py.
4. Сосредоточьтесь на PR: Одно логическое изменение на PR

PR Описание

Включите:

• Что изменилось и почему
• Как протестировать
• На каких платформах вы тестировали
• Укажите любые связанные проблемы

Подтвердить Сообщения

Мы используем Обычные фиксации:

<type>(<scope>): <description>

Тип	Используйте для
fix	Исправления ошибок
feat	Новые возможности
docs	Документация
test	Тесты
refactor	Реструктуризация кода
chore	Сборка, CI, обновления зависимостей

Области применения: cli, gateway, tools, skills, agent, install, whatsapp, security

Примеры:

fix(cli): prevent crash in save_config_value when model is a string
feat(gateway): add WhatsApp multi-user session isolation
fix(security): prevent shell injection in sudo password piping

Отчеты о проблемах

• Используйте GitHub Проблемы
• Включите: ОС, Python версия, VibeOS версия (vibeos version), полная отслеживание ошибок
• Включите шаги по воспроизведению
• Проверьте существующие проблемы перед созданием дубликатов
• Об уязвимостях безопасности сообщите конфиденциально

Сообщество

• Проблемы: support@vibeos.com.ru
• GitHub Обсуждения: Для предложений по дизайну и обсуждений архитектуры
• Центр навыков: загружайте специальные навыки и делитесь ими с сообществом

License

Внося свой вклад, вы соглашаетесь, что ваши материалы будут лицензироваться по MIT License.