Сценарий 17: Редактирование файлов

Хирургические модификации кода на основе AST с предпросмотром diff, резервным копированием/отменой и многоинтерфейсным доступом (CLI, REST API, MCP).

Содержание¶

• Быстрый старт
• Как это работает
• Архитектура
• Определение намерения
• AST-парсинг
• Поиск целей
• Режимы редактирования и типы целей
• Модели данных
• Форматы diff
• Интеграция с SSR
• Примеры использования
• Поиск целей кода
• Предпросмотр изменений с diff
• Применение с резервным копированием
• Операция переименования
• Конфигурация
• Использование CLI
• REST API
• Инструмент MCP
• Примеры вопросов
• Связанные сценарии

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

/select 17

Как это работает¶

Архитектура¶

Модуль редактирования (src/editing/) состоит из 5 компонентов, связанных в конвейер:

Запрос пользователя
    |
    v
ASTParser (tree-sitter + regex-резерв)
    |
    v
TargetFinder (CPG + AST, 7 методов поиска)
    |
    v
CodeModifier (6 режимов, резервное копирование/отмена)
    |
    v
DiffGenerator (4 формата вывода)
    |
    v
Предпросмотр / Применение

SSRAdapter ──> CodeModifier
  (мост GoCPG RewriteResult → EditOperation)

Определение намерения¶

Рабочий процесс (src/workflow/scenarios/file_editing.py) определяет намерение редактирования через is_file_editing_query() с использованием 27 двуязычных ключевых слов:

Функция file_editing_workflow() зарегистрирована в LangGraph через graph_builder.py и маршрутизируется через intent_classifier.py → router.py. Опциональное обогащение через EnrichmentAdapter добавляет векторный контекст из документации и комментариев кода.

AST-парсинг¶

ASTParser поддерживает два режима парсинга:

1. tree-sitter (основной) — точный AST через пакет tree-sitter-languages
2. Regex-резерв — парсинг по шаблонам, когда tree-sitter недоступен

Поддерживаемые расширения файлов (14):

Regex-шаблоны доступны для Python, C, C++, JavaScript и Go — покрывают определения функций, классов, методов, структур, интерфейсов и стрелочных функций.

Поиск целей¶

TargetFinder предоставляет 7 методов поиска, комбинирующих CPG-запросы и AST-парсинг:

При наличии результатов и CPG, и AST метод _merge_targets() объединяет их — предпочитая AST для точного расположения и добавляя метаданные CPG.

Режимы редактирования и типы целей¶

Режимы редактирования (6)¶

Типы целей (7)¶

Модели данных¶

CodeTarget (13 полей)¶

EditOperation (8 полей)¶

EditResult (10 полей)¶

Форматы diff¶

DiffGenerator поддерживает 4 формата вывода через перечисление DiffFormat:

Дополнительные методы: - summarize_changes() — текстовая сводка (напр., “+4 строки добавлено, -2 удалено (+2 итого)”) - get_colored_diff() — цветной вывод в терминал через ANSI (красный/зелёный/голубой) - get_changed_lines() — кортеж (добавленные, удалённые, изменённые) номера строк

Интеграция с SSR¶

SSRAdapter (ssr_adapter.py) связывает результаты структурного поиска-и-замены GoCPG с модулем редактирования:

GoCPG scan --fix --dry-run
    |
    v
Diff-результаты RewriteResult (unified diff + метаданные)
    |
    v
rewrite_results_to_edit_operations()  ──> List[EditOperation]
    |
    v
CodeModifier.apply_multiple()  ──> List[EditResult]

Две функции-адаптера: - rewrite_results_to_edit_operations(diffs) — разбор diff-фрагментов или явных line_start/fix_preview в объекты EditOperation с EditMode.REPLACE - edit_operations_from_findings(findings) — обёртка, фильтрующая находки с исправлениями из GoCPGScanResult

Примеры использования¶

Поиск целей кода¶

> Найти функцию heap_insert в src/backend/access/heap/heapam.c

## Найден код

**Имя:** heap_insert
**Тип:** функция
**Файл:** src/backend/access/heap/heapam.c
**Строки:** 2156-2298

  void heap_insert(Relation relation,
                   HeapTuple tup,
                   CommandId cid,
                   int options,
                   BulkInsertState bistate)
  { ... }

Предпросмотр изменений с diff¶

> Редактировать функцию validate_input для добавления проверки границ

## Предпросмотр изменений

**Цель:** validate_input (функция)
**Файл:** src/utils/validation.c:45-67

### Изменения:
  @@ -45,6 +45,10 @@
   bool validate_input(const char *input, size_t len)
   {
  +    /* Проверка границ */
  +    if (len > MAX_INPUT_SIZE) {
  +        return false;
  +    }
       if (input == NULL) {
           return false;
       }

Используйте `/edit apply` для применения изменений.

Применение с резервным копированием¶

CodeModifier автоматически создаёт резервные копии (формат: name.YYYYMMDD_HHMMSS.hash.bak) и поддерживает стек отмены (до 50 записей). Операции с одним файлом сортируются по номеру строки в обратном порядке для предотвращения сдвигов строк.

Операция переименования¶

Режим RENAME использует regex по границам слов (\bOldName\b) для замены всех вхождений в файле без затрагивания частичных совпадений.

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

Класс данных EditingConfig (9 параметров):

editing:
  ast_parser: "tree-sitter"         # Основной парсер
  fallback_parser: "regex"           # Резерв при недоступности tree-sitter
  preserve_formatting: true          # Сохранять исходное форматирование
  preserve_comments: true            # Сохранять комментарии вокруг целей
  diff_context_lines: 5              # Строки контекста в diff-выводе
  backup_before_edit: true           # Создавать копии перед правками
  backup_dir: "./backups/edits"      # Директория резервных копий
  max_file_size_mb: 10               # Максимальный размер файла для редактирования
  supported_extensions:              # Обрабатываемые типы файлов
    - .py
    - .c
    - .h
    - .cpp
    - .js
    - .ts
    - .go
    - .rb

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

# Поиск целей по имени
python -m src.cli.import_commands edit find "heap_insert" --file src/heap.c --exact

# Поиск всех функций по шаблону в директории
python -m src.cli.import_commands edit find "validate_*" --file src/ --type function --limit 20

# Предпросмотр правки (формат цели: file.py::name или file.py:line)
python -m src.cli.import_commands edit preview src/utils/validation.c::validate_input \
    --new-code "bool validate_input(...) { ... }" \
    --format unified --context 5

# Предпросмотр с кодом из файла
python -m src.cli.import_commands edit preview src/file.c::func_name \
    --new-code-file patch.txt

# Применить правку
python -m src.cli.import_commands edit apply --backup

# Отмена последней правки (восстановление из копии)
python -m src.cli.import_commands edit undo --steps 1

# Показать историю правок
python -m src.cli.import_commands edit history --limit 10 --file src/utils/

REST API¶

5 эндпоинтов в src/api/routers/editing.py:

Пример:

# Поиск целей
curl -X POST http://localhost:8000/api/v1/edit/find-target \
  -H "Content-Type: application/json" \
  -d '{"file_path": "src/utils/validation.c", "name_pattern": "validate_input", "target_type": "function"}'

# Предпросмотр правки
curl -X POST http://localhost:8000/api/v1/edit/preview \
  -H "Content-Type: application/json" \
  -d '{"file_path": "src/file.c", "target_name": "func", "new_code": "...", "diff_format": "unified"}'

Инструмент MCP¶

codegraph_edit_preview(file_path, target_name, target_type="function")

Находит цель в CPG и возвращает тип, расположение и предпросмотр кода — полезно для безопасного рефакторинга из ИИ-ассистента. Использует TargetFinder с CPG-сервисом для семантического понимания.

Примеры вопросов¶

Поиск целей: - «Найти функцию heap_insert в src/heap.c» - «Найти все классы в src/backend/executor/» - «Какие функции вызывают heap_insert?»

Редактирование: - «Редактировать функцию validate_input — добавить проверку null» - «Вставить логирование перед функцией process_request» - «Удалить неиспользуемую функцию old_helper» - «Обернуть функцию обработкой ошибок» - «Переименовать класс TransactionHandler в TxHandler»

Предпросмотр и история: - «Показать текущий предпросмотр редактирования» - «Показать историю правок» - «Отменить последнюю правку»

Связанные сценарии¶

• Рефакторинг (S05) — Очистка и рефакторинг кода
• Оптимизация кода (S18) — Оптимизация с помощью ИИ (использует S17 для правок)
• Проверка стандартов (S19) — Исправление нарушений стандартов (вызывает S17)
• Массовый рефакторинг (S13) — Масштабные изменения