f2f33e24d6
- Golden traces: docs/golden_traces/v1/, format protocol/request/context/result - trace_to_golden bin, golden_traces_v1_validate test - Makefile: make golden, make test-protocol - npm scripts: golden, test-protocol - CI: .github/workflows/protocol-check.yml - PROTOCOL_V1.md, PROTOCOL_V2_PLAN.md - Policy for updating golden traces in README Co-authored-by: Cursor <cursoragent@cursor.com>
75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# План Protocol v2
|
||
|
||
Минимальный набор изменений для v2 — без «воды».
|
||
|
||
---
|
||
|
||
## 3.1. Главная цель v2
|
||
|
||
Снизить риск/стоимость «UPDATE_FILE целиком» и улучшить точность правок:
|
||
- частичные патчи,
|
||
- «операции редактирования» вместо полной перезаписи.
|
||
|
||
---
|
||
|
||
## 3.2. Минимальный набор изменений
|
||
|
||
### A) Новый action kind: `PATCH_FILE`
|
||
|
||
Вместо полного `content`, передаётся unified diff:
|
||
|
||
```json
|
||
{ "kind": "PATCH_FILE", "path": "src/app.py", "patch": "@@ -1,3 +1,4 @@\n..." }
|
||
```
|
||
|
||
- Валидация патча локально.
|
||
- Применение патча транзакционно.
|
||
- Preview diff становится тривиальным.
|
||
|
||
### B) Новый action kind: `REPLACE_RANGE`
|
||
|
||
Если unified diff сложен:
|
||
|
||
```json
|
||
{
|
||
"kind": "REPLACE_RANGE",
|
||
"path": "src/app.py",
|
||
"start_line": 120,
|
||
"end_line": 180,
|
||
"content": "новый блок"
|
||
}
|
||
```
|
||
|
||
Плюсы: проще валидировать. Минусы: зависит от line numbers (хрупко при изменениях).
|
||
|
||
### C) «Base hash» для UPDATE/PATCH
|
||
|
||
Исключить race (файл изменился между plan/apply):
|
||
|
||
```json
|
||
{ "kind": "PATCH_FILE", "path": "...", "base_sha256": "...", "patch": "..." }
|
||
```
|
||
|
||
Если hash не совпал → Err и переход в PLAN.
|
||
|
||
---
|
||
|
||
## 3.3. Совместимость v1/v2
|
||
|
||
- `schema_version=1` → нынешний формат (UPDATE_FILE, CREATE_FILE, …).
|
||
- `schema_version=2` → допускает `PATCH_FILE` / `REPLACE_RANGE` и расширенные поля.
|
||
|
||
В коде:
|
||
- Компилировать обе схемы: `llm_response_schema_v1.json`, `llm_response_schema_v2.json`.
|
||
- Выбор активной по env: `PAPAYU_PROTOCOL_VERSION=1|2`.
|
||
- Валидация/парсер: сначала проверить schema v2 (если включена), иначе v1.
|
||
|
||
---
|
||
|
||
## 3.4. Порядок внедрения v2 без риска
|
||
|
||
1. Добавить v2 schema + валидаторы + apply engine, **не включая по умолчанию**.
|
||
2. Добавить «LLM prompt v2» (рекомендовать PATCH_FILE вместо UPDATE_FILE).
|
||
3. Прогнать на своих проектах и собрать golden traces v2.
|
||
4. Когда стабильно — сделать v2 дефолтом, сохранив совместимость v1.
|