e76236dc55
- Schema version (x_schema_version, schema_hash) в prompt/trace - Кеш read/search/logs/env (ContextCache) в plan-цикле - Контекст-диета: MAX_FILES=8, MAX_FILE_CHARS=20k, MAX_TOTAL_CHARS=120k - Plan→Apply двухфазность, NO_CHANGES, path sanitization - Protected paths, content validation, EOL normalization - Trace (PAPAYU_TRACE), redaction (PAPAYU_TRACE_RAW) - Preview diff, undo/redo, transactional apply Co-authored-by: Cursor <cursoragent@cursor.com>
142 lines
17 KiB
Markdown
142 lines
17 KiB
Markdown
# PAPA YU: оценка обновлений и сценарий рассказа о программе
|
||
|
||
---
|
||
|
||
## Часть 1. Нуждается ли программа в обновлении или улучшении?
|
||
|
||
### Текущее состояние (после внедрённых улучшений)
|
||
|
||
**Уже сделано:**
|
||
- **Архитектура:** типы вынесены в `src/lib/types.ts`, единый API-слой в `src/lib/tauri.ts`; страница Tasks разбита на компоненты PathSelector, AgenticResult и хук useUndoRedo.
|
||
- **Безопасность (v2.4.4):** лимиты профиля (`max_actions_per_tx`, `timeout_sec`) применяются в `apply_actions_tx` и `run_batch`; в `verify_project` добавлен таймаут на выполнение проверок (cargo check, npm run build и т.д.).
|
||
- **Иконка:** используется RGBA-иконка из папки «папа-ю», сборка Tauri проходит успешно.
|
||
|
||
**Программа работоспособна и готова к использованию.** При этом остаются направления для развития.
|
||
|
||
### Что имеет смысл улучшить (по приоритету)
|
||
|
||
| Область | Рекомендация | Зачем |
|
||
|--------|---------------|--------|
|
||
| **UX** | История сессий в UI, отображение профиля и лимитов в форме, фильтр расширений при «Прикрепить файл», горячие клавиши (Ctrl+Enter, Escape) | Удобство и прозрачность для пользователя |
|
||
| **Тестирование** | Юнит-тесты для `detect_project_type`, `is_protected_file`, `build_plan`; E2E-сценарии (анализ → применение → undo) | Надёжность и уверенность при изменениях |
|
||
| **Документация** | Обновить README до актуальной версии (2.4.x), вести CHANGELOG | Проще онбординг и откат версий |
|
||
| **Дальнейшие фичи** | LLM-планировщик вместо чисто эвристического плана; контекст прикреплённых файлов при анализе; allowlist команд verify в конфиге | Расширение возможностей и гибкость |
|
||
|
||
**Вывод:** программа не «сломана» и не требует срочного обновления для базового сценария. Улучшения из списка выше повысят удобство, предсказуемость и расширяемость — их можно планировать поэтапно.
|
||
|
||
---
|
||
|
||
## Часть 2. Сценарий рассказа о программе (по модулям, технологиям, защите и уникальности)
|
||
|
||
Ниже — готовый сценарий для устного или письменного рассказа о PAPA YU: модули, достоинства, технологии, защищённость, возможности и уникальность.
|
||
|
||
---
|
||
|
||
### Введение
|
||
|
||
PAPA YU — это десктопное приложение для анализа кодовой базы и безопасного автоматического улучшения проектов: добавление README, .gitignore, тестов, приведение структуры к принятым практикам. Всё это делается с полным контролем пользователя: предпросмотр изменений, подтверждение применения и возможность отката одной кнопкой.
|
||
|
||
Рассказ удобно строить по слоям: интерфейс, единый слой работы с бэкендом, бэкенд по модулям, безопасность и уникальность.
|
||
|
||
---
|
||
|
||
### Модуль 1. Интерфейс (React + Vite)
|
||
|
||
**Что это:** одностраничное приложение на React 18 и Vite 5. Одна основная страница — «Задачи» (Tasks): выбор папок и файлов, поле ввода пути, лента сообщений (чат с системой и ассистентом), блоки с отчётом, превью изменений и результатами автоматического прогона.
|
||
|
||
**Модульная структура фронта:**
|
||
- **PathSelector** — блок выбора папок и прикреплённых файлов, кнопки «Выбрать папку» и «Прикрепить файл», список выбранных путей.
|
||
- **AgenticResult** — блок результата «исправить автоматически»: таблица попыток, статусы проверок, кнопки «Скачать отчёт», «Скачать diff», «Откатить».
|
||
- **useUndoRedo** — хук для состояния отката/повтора и вызова команд undo/redo через единый API-слой.
|
||
- **Единая точка типов и API:** все типы (Action, AnalyzeReport, AgenticRunResult и др.) лежат в `src/lib/types.ts`; все вызовы бэкенда идут через `src/lib/tauri.ts`, без прямых `invoke` в компонентах.
|
||
|
||
**Достоинства:** понятная структура, переиспользуемые компоненты и типы, один слой общения с Tauri — проще поддерживать и тестировать.
|
||
|
||
**Технологии:** React 18, Vite 5, TypeScript, React Router, Tauri 2 (плагины: dialog, shell). Алиас `@/` для импортов, строгий TypeScript.
|
||
|
||
---
|
||
|
||
### Модуль 2. Единый слой API (src/lib/tauri.ts)
|
||
|
||
**Что это:** все обращения к бэкенду проходят через функции в `tauri.ts`: `getProjectProfile`, `runBatchCmd`, `applyActionsTx`, `agenticRun`, `generateActionsFromReport`, `proposeActions`, `undoLastTx`, `undoLast`, `redoLast`, работа с папками и сессиями и т.д.
|
||
|
||
**Достоинства:** один контракт между UI и Rust; проще менять форматы запросов/ответов, добавлять логирование и обработку ошибок без правок во всех компонентах.
|
||
|
||
**Технологии:** `@tauri-apps/api/core` (invoke), типы из `@/lib/types`.
|
||
|
||
---
|
||
|
||
### Модуль 3. Бэкенд: команды и оркестрация (Tauri 2, Rust)
|
||
|
||
**Структура по модулям:**
|
||
|
||
- **analyze_project** — сканирование выбранных путей, эвристики (README, .gitignore, tests, структура), формирование отчёта с findings, recommendations, actions, action_groups, fix_packs.
|
||
- **get_project_profile** — определение типа проекта (React/Vite, Next.js, Node, Rust, Python, unknown) по файлам в корне; возврат профиля с лимитами (`max_actions_per_tx`, `timeout_sec`, `max_files`), шаблоном цели и флагом safe_mode.
|
||
- **run_batch** — единый сценарий: анализ → превью (если есть действия) → при необходимости применение с проверками. Перед применением проверяется лимит `max_actions_per_tx` из профиля; при превышении возвращается ошибка.
|
||
- **apply_actions_tx** — транзакционное применение: снимок состояния до изменений, применение действий, при включённом auto_check — запуск проверок (cargo check / npm run build и т.д.) с таймаутом из профиля; при падении проверки — автоматический откат. Проверка числа действий против `max_actions_per_tx`.
|
||
- **preview_actions** — расчёт diff без записи на диск.
|
||
- **undo_last_tx / undo_last / redo_last, get_undo_redo_state_cmd, undo_status** — откат и повтор последней транзакции, состояние undo/redo для UI.
|
||
- **generate_actions_from_report** — генерация списка безопасных действий по отчёту (например, только создание файлов/папок) без LLM.
|
||
- **propose_actions** — план исправлений по отчёту и цели пользователя (эвристический планировщик).
|
||
- **agentic_run** — цикл: анализ → план → превью → применение → проверка (verify); при неудаче проверки — откат и повтор в пределах max_attempts.
|
||
- **verify** — проверка проекта после изменений (cargo check, npm run build/test и т.д.) по allowlist команд, с таймаутом на каждый запуск.
|
||
- **projects / store** — проекты и сессии (list_projects, add_project, append_session_event, list_sessions), хранение в userData.
|
||
|
||
**Достоинства:** чёткое разделение по командам, переиспользование типов и лимитов профиля, единый контур «превью → применение → проверка → откат при ошибке».
|
||
|
||
**Технологии:** Rust, Tauri 2, serde, uuid, стандартная библиотека (fs, path, process, thread, time), allowlist команд и таймауты для внешних процессов.
|
||
|
||
---
|
||
|
||
### Модуль 4. Транзакции и откат (tx/)
|
||
|
||
**Что это:** снимки состояния файлов до применения, запись манифестов транзакций, откат к снимку при падении проверок или по запросу пользователя, стек undo/redo.
|
||
|
||
**Достоинства:** пользователь и система всегда могут откатить последнее применение; данные на диске остаются консистентными после отката.
|
||
|
||
**Технологии:** копирование/восстановление файлов и директорий, манифесты в JSON, привязка к AppHandle и путям проекта.
|
||
|
||
---
|
||
|
||
### Защищённость и ограничения рисков
|
||
|
||
- **Защита путей:** запрет изменения системных и служебных путей (например, .git, node_modules, target, dist); проверка, что изменяются только допустимые текстовые файлы (`is_protected_file`, `is_text_allowed`).
|
||
- **Подтверждение пользователя:** применение изменений только при явном `user_confirmed`; в UI — кнопки «Применить» и при необходимости диалог подтверждения.
|
||
- **Лимиты из профиля:** ограничение числа действий в одной транзакции (`max_actions_per_tx`) и таймауты на проверки (`timeout_sec`) снижают риск «зависания» и перегрузки.
|
||
- **Allowlist команд в verify:** запускаются только заранее разрешённые команды (cargo check, npm run build и т.д.) с фиксированными аргументами, без произвольного shell.
|
||
- **Таймауты:** проверки (verify, auto_check) выполняются с ограничением по времени; при превышении процесс завершается, пользователь получает сообщение (например, TIMEOUT), откат при необходимости уже выполнен.
|
||
|
||
В совокупности это даёт контролируемую среду: автоматизация без неограниченного доступа к системе и без «тихого» изменения критичных путей.
|
||
|
||
---
|
||
|
||
### Возможности для пользователя
|
||
|
||
- Выбор одной или нескольких папок и прикрепление файлов; ввод пути вручную.
|
||
- Один запуск анализа с получением отчёта: проблемы, рекомендации, группы действий и пакеты исправлений.
|
||
- Предпросмотр изменений (diff) до применения.
|
||
- Применение выбранных или рекомендованных исправлений с автоматической проверкой (сборка/тесты); при падении проверки — автоматический откат.
|
||
- Режим «исправить автоматически» (agentic run): несколько попыток с откатом при неудачной проверке.
|
||
- Режим «безопасные исправления в один клик»: генерация безопасных действий по отчёту → превью → применение с проверкой.
|
||
- Откат последнего применения и повтор (undo/redo).
|
||
- Скачивание отчёта и diff для аудита и отладки.
|
||
- Определение типа проекта и отображение профиля (в т.ч. лимитов) для прозрачности.
|
||
|
||
---
|
||
|
||
### Уникальность
|
||
|
||
- **Транзакционность и откат на уровне файловой системы:** не «патч и надежда», а снимок → применение → проверка → при ошибке откат к снимку и явное сообщение пользователю.
|
||
- **Профиль проекта и лимиты:** тип и лимиты (число действий, таймауты) задаются по структуре проекта и соблюдаются в apply и run_batch, что снижает риски и предсказуемо ограничивает автоматизацию.
|
||
- **Единый сценарий от анализа до отката:** анализ → план → превью → применение → проверка с таймаутом → откат при неудаче — реализован и в batch, и в agentic run, с одной и той же моделью безопасности.
|
||
- **Десктоп на Tauri 2:** нативный бэкенд на Rust, быстрый и контролируемый доступ к файлам и процессам, без веб-сервера и без открытия кода в браузере.
|
||
- **Гибрид эвристик и подготовки к LLM:** уже есть структура (propose_actions, agentic_run, отчёт с narrative и actions); планировщик можно заменить на LLM без смены контура выполнения.
|
||
|
||
---
|
||
|
||
### Заключение сценария
|
||
|
||
PAPA YU — это не просто «генератор README», а инструмент с чёткой архитектурой, контролем рисков и расширяемостью. Модули фронта и бэкенда разделены, типы и API централизованы, применение изменений транзакционно с откатом и проверками по таймауту и лимитам. Защита путей, подтверждение пользователя и allowlist команд делают автоматизацию предсказуемой и безопасной. Уникальность — в сочетании транзакционности, профилей проекта и единого сценария «анализ → превью → применение → проверка → откат при ошибке» в одном десктопном приложении.
|
||
|
||
При необходимости следующий шаг — улучшения UX (история сессий, горячие клавиши, фильтр файлов), тесты и обновление README/CHANGELOG, а затем — опционально LLM-планировщик и контекст прикреплённых файлов.
|