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>
57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
# Golden traces — эталонные артефакты
|
||
|
||
Фиксируют детерминированные результаты papa-yu без зависимости от LLM.
|
||
Позволяют ловить регрессии в валидации, парсинге, диете, кеше.
|
||
|
||
## Структура
|
||
|
||
```
|
||
docs/golden_traces/
|
||
README.md
|
||
v1/ # Protocol v1 fixtures
|
||
001_fix_bug_plan.json
|
||
002_fix_bug_apply.json
|
||
...
|
||
```
|
||
|
||
## Формат fixture (без секретов)
|
||
|
||
Минимальный стабильный JSON:
|
||
- `protocol` — schema_version, schema_hash
|
||
- `request` — mode, input_chars, token_budget, strict_json, provider, model
|
||
- `context` — context_digest (опц.), context_stats, cache_stats
|
||
- `result` — validated_json (объект), validation_outcome, error_code
|
||
|
||
Без raw_content, без секретов.
|
||
|
||
## Генерация из трасс
|
||
|
||
```bash
|
||
cd src-tauri
|
||
cargo run --bin trace_to_golden -- <trace_id> [output_path]
|
||
cargo run --bin trace_to_golden -- <path/to/trace.json> [output_path]
|
||
```
|
||
|
||
Читает trace из `.papa-yu/traces/<trace_id>.json` или из файла. Пишет в `docs/golden_traces/v1/`.
|
||
|
||
## Регрессионный тест
|
||
|
||
```bash
|
||
cargo test golden_traces_v1_validate
|
||
# или
|
||
make test-protocol
|
||
npm run test-protocol
|
||
```
|
||
|
||
---
|
||
|
||
## Политика обновления golden traces
|
||
|
||
**Когда обновлять:** только при намеренном изменении протокола или валидатора (path/content/conflicts, schema, диета).
|
||
|
||
**Как обновлять:** `trace_to_golden` — `make golden` (из последней трассы) или `make golden TRACE_ID=<id>`.
|
||
|
||
**Как добавлять новый сценарий:** выполни propose с PAPAYU_TRACE=1, затем `make golden` и сохрани вывод в `v1/NNN_<name>.json` с номером NNN.
|
||
|
||
**При смене schema_hash:** либо bump schema_version (новый документ v2), либо обнови все fixtures (`trace_to_golden` на свежие трассы) и зафиксируй в CHANGELOG.
|