65e95a458d
- Мульти-провайдер: PAPAYU_LLM_PROVIDERS — сбор планов от нескольких ИИ (Claude, OpenAI), агрегация - Тренды дизайна и иконок: вкладка в модалке, поиск по безопасным доменам (Tavily include_domains) - Snyk Code: PAPAYU_SNYK_SYNC, REST API issues → snyk_findings в agent-sync - Documatic: architecture_summary из .papa-yu/architecture.md в agent-sync - Личная автоматизация: capability personal-automation (терминал git/npm/cargo, открытие URL) - agent_sync расширен: snyk_findings, architecture_summary; analyze_project_cmd и run_batch пишут sync - Документация: SNYK_AND_DOCUMATIC_SYNC.md, SECURITY_AND_PERSONAL_AUTOMATION.md, обновлён CLAUDE_AND_AGENT_SYNC Co-authored-by: Cursor <cursoragent@cursor.com>
238 lines
9.4 KiB
Markdown
238 lines
9.4 KiB
Markdown
# Отладка EDIT_FILE на реальном файле (чеклист)
|
||
|
||
Этот документ — практический чеклист для end-to-end проверки v3 EDIT_FILE в papa-yu:
|
||
propose → preview → apply → (repair / fallback) → golden trace.
|
||
|
||
---
|
||
|
||
## Предварительные условия
|
||
|
||
### Включить трассы и протокол v3
|
||
Рекомендуемые переменные окружения:
|
||
|
||
- PAPAYU_TRACE=1
|
||
- PAPAYU_PROTOCOL_VERSION=3
|
||
- PAPAYU_LLM_STRICT_JSON=1 (если провайдер поддерживает response_format)
|
||
- PAPAYU_MEMORY_AUTOPATCH=0 (на время отладки, чтобы исключить побочные эффекты)
|
||
- PAPAYU_NORMALIZE_EOL=lf (если используешь нормализацию EOL)
|
||
|
||
Для Online fallback/notes (опционально):
|
||
- PAPAYU_ONLINE_RESEARCH=1
|
||
- PAPAYU_ONLINE_AUTO_USE_AS_CONTEXT=1 (если хочешь тестировать auto-use)
|
||
- PAPAYU_TAVILY_API_KEY=...
|
||
|
||
---
|
||
|
||
## Цель проверки (Definition of Done)
|
||
|
||
Сценарий считается успешно пройденным, если:
|
||
1) v3 выдаёт APPLY с EDIT_FILE (и/или PATCH_FILE как fallback внутри v3),
|
||
2) preview показывает diff, apply применяет изменения,
|
||
3) base_sha256 проверяется, base mismatch ловится и чинится repair'ом (sha-injection),
|
||
4) ошибки anchor/before/ambiguous воспроизводимы и дают корректные коды ERR_EDIT_*,
|
||
5) golden traces v3 проходят (make test-protocol / cargo test golden_traces).
|
||
|
||
---
|
||
|
||
## Быстрый E2E сценарий (минимальный)
|
||
|
||
### Шаг 1 — выбрать простой файл
|
||
Выбери небольшой UTF-8 файл (лучше < 2000 строк), например:
|
||
- src/*.rs
|
||
- src/lib/*.ts
|
||
- любой текстовый конфиг (не secrets)
|
||
|
||
Избегай:
|
||
- бинарных/сжатых файлов
|
||
- автогенерации (dist/, build/, vendor/)
|
||
- protected paths (.env, *.pem, secrets/)
|
||
|
||
### Шаг 2 — PLAN
|
||
В UI:
|
||
- ввод: `plan: исправь <конкретная правка>`
|
||
или просто текст с явным "fix", чтобы сработала эвристика PLAN.
|
||
|
||
Ожидаемо:
|
||
- actions=[] (PLAN режим)
|
||
- summary объясняет, какой файл будет правиться и какие anchors будут использованы
|
||
|
||
### Шаг 3 — APPLY (OK)
|
||
Нажми OK / "apply" / "да".
|
||
|
||
Ожидаемо:
|
||
- actions содержит EDIT_FILE
|
||
- EDIT_FILE включает:
|
||
- base_sha256 (64 hex)
|
||
- edits[] (min 1)
|
||
- anchor и before должны быть точными фрагментами из файла
|
||
|
||
### Шаг 4 — PREVIEW
|
||
Preview должен:
|
||
- показать unified diff
|
||
- bytes_before/bytes_after заполнены (если у тебя это в DiffItem)
|
||
|
||
Если preview падает — это уже диагностируемая ошибка (см. разделы ниже).
|
||
|
||
### Шаг 5 — APPLY
|
||
Apply должен:
|
||
- применить изменения
|
||
- записать файл
|
||
- если включён auto_check/run_tests — пройти (или корректно откатиться)
|
||
- в trace появится APPLY_SUCCESS или APPLY_ROLLBACK
|
||
|
||
---
|
||
|
||
## Где смотреть диагностику
|
||
|
||
### stderr события (runtime)
|
||
По trace_id в stderr:
|
||
- LLM_REQUEST_SENT / LLM_RESPONSE_OK / LLM_RESPONSE_REPAIR_RETRY
|
||
- VALIDATION_FAILED code=...
|
||
- PREVIEW_READY ...
|
||
- APPLY_SUCCESS / APPLY_ROLLBACK
|
||
- PROTOCOL_FALLBACK ... (если был)
|
||
|
||
### Трассы в .papa-yu/traces/
|
||
- основной propose trace: .papa-yu/traces/<trace_id>.json
|
||
- online research: online_<uuid>.json (если включено)
|
||
|
||
Ищи поля:
|
||
- protocol_default / protocol_attempts / protocol_fallback_reason / protocol_repair_attempt
|
||
- repair_injected_sha256, repair_injected_paths
|
||
- notes_injected (если notes включены)
|
||
- online_context_injected / online_context_dropped
|
||
- context_stats / cache_stats
|
||
|
||
---
|
||
|
||
## Типовые ошибки EDIT_FILE и как чинить
|
||
|
||
### ERR_NON_UTF8_FILE
|
||
Причина:
|
||
- файл не UTF-8 (байтовый/смешанная кодировка)
|
||
|
||
Действие:
|
||
- v3 должен fallback'нуть (обычно сразу) к v2 или отказаться и попросить альтернативу.
|
||
- если это код/текст — проверь, что файл реально UTF-8.
|
||
|
||
### ERR_EDIT_BASE_MISMATCH (или ERR_EDIT_BASE_SHA256_INVALID)
|
||
Причина:
|
||
- base_sha256 не совпал с текущим содержимым файла
|
||
- или base_sha256 не 64 hex
|
||
|
||
Ожидаемое поведение:
|
||
- repair prompt должен подставить правильный sha256 из контекста:
|
||
`FILE[path] (sha256=...)`
|
||
- trace: repair_injected_sha256=true, repair_injected_paths=[path]
|
||
|
||
Как воспроизвести:
|
||
- вручную измени файл между PLAN и APPLY
|
||
- или подложи неправильный base_sha256 в фикстуре/в тесте
|
||
|
||
### ERR_EDIT_ANCHOR_NOT_FOUND
|
||
Причина:
|
||
- anchor строка отсутствует в файле
|
||
|
||
Чиним:
|
||
- anchor должен быть буквальным кусочком из `FILE[...]` блока
|
||
- лучше выбирать "устойчивый" anchor: сигнатура функции, имя класса, уникальный комментарий
|
||
|
||
### ERR_EDIT_BEFORE_NOT_FOUND
|
||
Причина:
|
||
- before не найден в окне вокруг anchor (±4000 chars по твоей текущей реализации)
|
||
|
||
Чиним:
|
||
- before должен быть рядом с anchor (не из другого участка файла)
|
||
- увеличить точность: добавить контекст в before (несколько слов/строк)
|
||
|
||
### ERR_EDIT_AMBIGUOUS
|
||
Причина:
|
||
- before встречается больше одного раза в окне вокруг anchor
|
||
|
||
Чиним:
|
||
- сделать before длиннее/уникальнее
|
||
- сделать anchor более узким/уникальным
|
||
- если в твоей реализации поддержан occurrence (для before), укажи occurrence явно; если нет — уточняй before.
|
||
|
||
### ERR_EDIT_APPLY_FAILED
|
||
Причина:
|
||
- внутренний сбой применения (невалидные индексы, неожиданные boundary, и т.п.)
|
||
- чаще всего: крайние случаи UTF-8 границ или очень большие вставки
|
||
|
||
Чиним:
|
||
- сократить before/after до минимального фрагмента
|
||
- избегать массовых замен/реформатирования
|
||
- если повторяется — добавь golden trace и воспроизведение
|
||
|
||
---
|
||
|
||
## Проверка repair-first и fallback (v3 → v2)
|
||
|
||
### Repair-first
|
||
Для ошибок из V3_REPAIR_FIRST:
|
||
- первый retry: repair_attempt=0
|
||
- второй (если не помог): fallback repair_attempt=1 → protocol override = 2
|
||
|
||
Проверяй в trace:
|
||
- protocol_repair_attempt: 0/1
|
||
- protocol_fallback_reason
|
||
- protocol_fallback_stage (обычно apply)
|
||
|
||
### Immediate fallback
|
||
Для ошибок из V3_IMMEDIATE_FALLBACK:
|
||
- fallback сразу (без repair), если так настроено
|
||
|
||
---
|
||
|
||
## Как сделать Golden trace из реального запуска
|
||
|
||
1) Убедись, что PAPAYU_TRACE=1
|
||
2) Выполни сценарий (PLAN→APPLY)
|
||
3) Найди trace_id в stderr (или в .papa-yu/traces/)
|
||
4) Сгенерируй fixture:
|
||
- make golden TRACE_ID=<id>
|
||
или
|
||
- cargo run --bin trace_to_golden -- <trace_id> docs/golden_traces/v3/NNN_name.json
|
||
5) Прогон:
|
||
- make test-protocol
|
||
или
|
||
- cargo test golden_traces
|
||
|
||
Совет:
|
||
- Делай отдельные golden traces для:
|
||
- ok apply edit
|
||
- base mismatch repair injected sha
|
||
- anchor not found
|
||
- no changes
|
||
|
||
---
|
||
|
||
## Реальные edge cases (на что смотреть)
|
||
|
||
1) Несколько одинаковых anchors в файле:
|
||
- occurrence должен выбрать правильный (если модель указала)
|
||
2) before содержит повторяющиеся шаблоны:
|
||
- ambiguity ловится, и это нормально
|
||
3) Window ±4000 chars не покрывает before:
|
||
- значит before слишком далеко от anchor — модель ошиблась
|
||
4) Большие after-вставки:
|
||
- риск превышения лимитов/перформанса
|
||
5) EOL normalization:
|
||
- следи, чтобы diff не "красил" весь файл из-за CRLF→LF
|
||
|
||
---
|
||
|
||
## Мини-набор команд для быстрой диагностики
|
||
|
||
- Прогнать протокол-тесты:
|
||
- make test-protocol
|
||
|
||
- Прогнать всё:
|
||
- make test-all
|
||
|
||
- Посмотреть свежие traces:
|
||
- ls -lt .papa-yu/traces | head
|
||
|
||
- Найти ошибки по коду:
|
||
- rg "ERR_EDIT_" -n .papa-yu/traces
|