Skip to content

README_ru.md

Latest commit

 

History

History
181 lines (137 loc) · 12.3 KB

README_ru.md

File metadata and controls

181 lines (137 loc) · 12.3 KB
Raw

FS-XML Interpreter (FS-XML v1.2)

Графическое приложение (GUI) на Python / PySide6 для автоматизированного, безопасного применения изменений в коде, сгенерированных нейросетями (ChatGPT, Claude, DeepSeek и др.), по спецификации FS-XML v1.2.

Зачем нужен этот проект? (Проблема и решение)

Проблема:

При разработке программ с помощью нейросетей разработчики сталкиваются с рутиной:

  1. Ручное копирование: ИИ выдает фрагменты кода для 5 разных файлов. Приходится вручную открывать каждый файл, искать нужное место и вставлять код.
  2. Риск сломать проект: Легко ошибиться при вставке, пропустить скобку или затереть важную функцию.
  3. Сложность отката: Если предложенный ИИ вариант не заработал, откатывать изменения вручную по нескольким файлам долго и неудобно.
  4. Безопасность системных файлов: Нейросеть может случайно переписать конфигурационные файлы, которые трогать нельзя.

Решение:

AI Code Custom Interpreter решает эти проблемы полностью:

  • Автоматическое применение: Нейросеть формирует ответ в формате XML (FS-XML), а приложение за 1 клик самостоятельно создает файлы или точечно меняет нужные фрагменты кода.
  • Безопасный контекст и разграничение прав: Вы сами выбираете, какие файлы проекта доступны для редактирования ([WRITABLE]), а какие защищены от изменений ([READ_ONLY]).
  • Генератор дампа контекста: Приложение собирает выбранные файлы проекта в единый аккуратный текстовый дамп со специальной инструкцией для нейросети.
  • История и откат в 1 клик (Rollback): Все изменения сохраняются в локальную базу данных (SQLite). Любую сессию правок можно мгновенно откатить к исходному состоянию диска.
  • Защита от перезаписи ручных правок: Если после применения кода ИИ вы отредактировали файл вручную, система предупредит вас об этом перед откатом.

Основные возможности

  1. Менеджер проектов и контекста:

    • Ведение нескольких проектов одновременно.
    • Древовидный выбор файлов/папок с гибкой установкой прав:
      • 🟢 Writable (W) — файлы разрешено создавать и редактировать.
      • 🟡 Read-Only (RO) — файлы только для чтения (ИИ видит контекст, но не может их менять).

  2. Создание дампа контекста (context_dump.txt):

    • Автоматическая сборка содержимого выбранных файлов в один документ вместе с инструкциями FS-XML v1.2.
    • Автоматический пропуск бинарных файлов (картинки, .pyc, .exe) и защита от ошибок кодировки.

  3. Парсер и Исполнитель XML (FS-XML Parser & Executor):

    • Распознавание тегов <fs_create> (создание файлов) и <fs_edit> (частичная замена <fs_search>/<fs_replace> или полная перезапись <all />).
    • Защита Path Traversal: Предотвращение выхода за пределы рабочей папки проекта (защита от путей вида ../../).
    • Проверка наличия прав на запись перед каждым изменением.

  4. История изменений и Откаты:

    • Хранение всех операций и исходных снимков файлов (snapshots) в базе данных SQLite.
    • Кнопка «Откатить» для возврата к состоянию ДО применения XML.
    • Кнопка «Применить снова» для повторного наката отмененных изменений.
    • Детекция ручных правок поверх изменений ИИ.

💡 Рекомендации по работе с нейросетями (Важно)

Для стабильной и эффективной работы с ИИ придерживайтесь следующих правил:

  1. Обучение нейросети формату: Перед началом сессии скопируйте всё содержимое файла спецификации FS-XML v1.2.txt и вставьте его в поле System Instructions (системные инструкции / Custom Instructions / System Prompt) в настройках вашего чата с нейросетью. Это обучит модель правильному синтаксису создания и редактирования файлов.

  2. Копирование ответов «как есть»: Вам абсолютно не важно, как именно ИИ форматирует ответ — оборачивает ли он XML в блоки разметки markdown (xml ... ) или пишет теги прямо в тексте сообщения. Просто скопируйте всё сообщение целиком и вставьте его в текстовое поле программы. Парсер без проблем переварит любой лишний текст, комментарии и оформление, вычленив только валидные XML-инструкции.

    Совет для эстетов: При желании вы можете дописать в конец системной инструкции требование: «Всегда оборачивай XML-инструкции в блоки кода markdown». Но даже если верстка ИИ «поплывет» или развалится — пережимать код не нужно, парсер справится.

  3. Решение ошибки «Блок поиска не найден»: Если программа сообщает, что замена не удалась, так как блок поиска не найден, это означает, что нейросеть потеряла контекст или попыталась изменить устаревший код. Просто создайте свежий дамп контекста в программе и отправьте его нейросети, чтобы обновить её знания о проекте.

  4. Ограничение на создание файлов: Инструкция <fs_create> может создать файл на диске только в том случае, если его еще не существует. Если файл уже есть, нейросеть должна использовать инструкцию <fs_edit> (для полной перезаписи существующего файла ИИ может использовать тег <all /> внутри поиска).

  5. Гигиена чата и актуализация контекста: При отправке нового дампа контекста в чат с ИИ настоятельно рекомендуется удалять предыдущие дампы из истории сообщений (или очищать историю/начинать новый диалог). Это не позволит нейросети путаться в старых и новых версиях одних и тех же файлов.

Рабочий процесс (Workflow)

[ Проект на диске ] ──> (Выбор файлов W/RO) ──> [ Создать дамп контекста ]
                                                             │
                                                             ▼
                                                [ Отправка дампа в ИИ ]
                                                             │
                                                             ▼
[ Файл на диске изменен ] <── (Нажать "ВЫПОЛНИТЬ") <── [ XML-ответ ИИ ]
          │
          └──> При необходимости: [ Нажать "Откатить" ] ──> [ Исходный файл ]

🛠️ Формат FS-XML v1.2 (Коротко)

Нейросеть генерирует инструкции в следующих форматах:

1. Создание нового файла

<fs_create path="src/utils/logger.py">
import datetime

def log(msg):
    print(f"[{datetime.datetime.now()}] {msg}")
</fs_create>

2. Частичное изменение файла (Search & Replace)

<fs_edit path="src/utils/logger.py">
<fs_search>
def log(msg):
    print(f"[{datetime.datetime.now()}] {msg}")
</fs_search>
<fs_replace>
def log(msg, level="INFO"):
    print(f"[{datetime.datetime.now()}] [{level}] {msg}")
</fs_replace>
</fs_edit>

3. Полная перезапись файла

<fs_edit path="config.py">
<fs_search><all /></fs_search>
<fs_replace>
DEBUG = True
DATABASE_URL = "sqlite:///app.db"
</fs_replace>
</fs_edit>

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

Требования

  • Python 3.10 или выше.
  • PySide6, pytest (для запуска тестов).

Установка и запуск

  1. Клонируйте репозиторий / Перейдите в папку с проектом:

    cd project_folder

  2. Установите зависимости:

    pip install PySide6 pytest

  3. Запустите приложение:

    python main.py

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

.
├── main.py            # Точка входа в приложение
├── database.py        # Взаимодействие с БД SQLite (проекты, файлы, история, снимки)
├── parser.py          # Модуль парсинга XML-инструкций FS-XML v1.2
├── executor.py        # Исполнитель изменений, проверка прав, откаты, дамп контекста
├── test_app.py        # Автоматические бэкенд и E2E GUI тесты (pytest + pytest-qt)
├── FS-XML v1.2.txt    # Спецификация формата управления файлами
└── ui/                # Графический интерфейс на PySide6
    ├── main_window.py # Главное окно (панели проектов, редактора, истории)
    ├── modals.py      # Модальные окна (выбор файлов контекста, просмотрщик)
    └── theme.py       # Темная тема оформления (CSS / QSS)

🧪 Запуск тестов

Проект полностью покрыт автоматическими тестами (БД, парсер, безопасное исполнение и E2E тесты интерфейса PySide6):

pytest test_app.py