535 lines
13 KiB
Markdown
535 lines
13 KiB
Markdown
# IMPLEMENTATION PLAN
|
||
|
||
Этот документ описывает рекомендуемый порядок реализации `ducklm` от пустого репозитория до рабочего локального runtime с тестовым веб-чатом.
|
||
|
||
План опирается на [`TASK_3.md`](/home/mirivlad/git/ducklm/TASK_3.md) и [`ARCHITECTURE.md`](/home/mirivlad/git/ducklm/ARCHITECTURE.md).
|
||
|
||
## 1. Goal
|
||
|
||
Собрать систему по этапам так, чтобы после каждого этапа оставался рабочий, проверяемый инкремент, а не набор недоделанных слоёв.
|
||
|
||
Главный принцип:
|
||
|
||
- сначала каркас и контракты
|
||
- потом runtime core
|
||
- потом execution path
|
||
- потом memory / critic / recovery
|
||
- потом удобные интерфейсы проверки
|
||
|
||
## 2. Milestones Overview
|
||
|
||
1. Project skeleton and typed contracts
|
||
2. Config system and dependency wiring
|
||
3. Runtime loop skeleton
|
||
4. Event bus and event store
|
||
5. State persistence and checkpointing
|
||
6. Context builder and orchestrator adapter
|
||
7. Router and directive flow
|
||
8. Execution engine and task graph
|
||
9. Permission system and tool sandbox
|
||
10. MVP tools
|
||
11. FastAPI API and health surface
|
||
12. Web chat test client
|
||
13. Coder integration
|
||
14. Critic integration
|
||
15. Memory system
|
||
16. Memory write policy
|
||
17. Retry, recovery, replay
|
||
18. CLI and operator utilities
|
||
19. Hardening and tests
|
||
|
||
## 3. Detailed Stages
|
||
|
||
### Stage 1. Project Skeleton and Typed Contracts
|
||
|
||
Цель:
|
||
|
||
- создать структуру директорий
|
||
- завести базовые модели данных
|
||
- убрать двусмысленность интерфейсов между слоями
|
||
|
||
Сделать:
|
||
|
||
- создать `app/`, `config/`, `data/`, `tests/`
|
||
- добавить core contracts:
|
||
- `UserTask`
|
||
- `PlanStep`
|
||
- `ToolCall`
|
||
- `ToolResult`
|
||
- `CriticScore`
|
||
- `RuntimeEvent`
|
||
- `TaskCheckpoint`
|
||
- `ExecutionDirective`
|
||
|
||
Результат этапа:
|
||
|
||
- проект компилируется
|
||
- типы и схемы являются source of truth для остальных модулей
|
||
|
||
Проверка:
|
||
|
||
- unit tests на валидацию схем
|
||
|
||
### Stage 2. Config System and Dependency Wiring
|
||
|
||
Цель:
|
||
|
||
- вынести runtime behavior в конфиги
|
||
- зафиксировать единый способ загрузки настроек
|
||
|
||
Сделать:
|
||
|
||
- `config/models.json`
|
||
- `config/prompts.json`
|
||
- `config/permissions.json`
|
||
- `config/runtime.json`
|
||
- loader и typed config models
|
||
|
||
Результат этапа:
|
||
|
||
- runtime можно запускать с консистентной конфигурацией
|
||
|
||
Проверка:
|
||
|
||
- config load smoke test
|
||
|
||
### Stage 3. Runtime Loop Skeleton
|
||
|
||
Цель:
|
||
|
||
- создать heart of system без полной бизнес-логики
|
||
|
||
Сделать:
|
||
|
||
- `runtime_loop.py`
|
||
- `runtime_controller.py`
|
||
- минимальный lifecycle:
|
||
- receive task
|
||
- create state
|
||
- build empty context
|
||
- emit initial event
|
||
- return placeholder directive/result
|
||
|
||
Результат этапа:
|
||
|
||
- есть центральный control loop
|
||
- остальные слои начинают подстраиваться под него, а не наоборот
|
||
|
||
Проверка:
|
||
|
||
- smoke test на прохождение задачи через loop skeleton
|
||
|
||
### Stage 4. Event Bus and Event Store
|
||
|
||
Цель:
|
||
|
||
- создать внутреннюю event backbone
|
||
|
||
Сделать:
|
||
|
||
- `event_bus.py`
|
||
- `event_types.py`
|
||
- `event_store.py`
|
||
- monotonic sequence per task
|
||
- append-only storage
|
||
- базовый replay reader
|
||
|
||
Результат этапа:
|
||
|
||
- у каждой задачи есть воспроизводимая хронология
|
||
|
||
Проверка:
|
||
|
||
- event ordering tests
|
||
- dedup/idempotency tests
|
||
|
||
### Stage 5. State Persistence and Checkpointing
|
||
|
||
Цель:
|
||
|
||
- убрать зависимость task lifecycle от памяти процесса
|
||
|
||
Сделать:
|
||
|
||
- `task_state_store.py`
|
||
- `checkpoint_store.py`
|
||
- SQLite backend
|
||
- checkpoint after critical transitions
|
||
- resume loading primitives
|
||
|
||
Результат этапа:
|
||
|
||
- runtime готов к recovery после падения
|
||
|
||
Проверка:
|
||
|
||
- save/load checkpoint tests
|
||
|
||
### Stage 6. Context Builder and Orchestrator Adapter
|
||
|
||
Цель:
|
||
|
||
- зафиксировать правильный вход в reasoning path
|
||
|
||
Сделать:
|
||
|
||
- `context_builder.py`
|
||
- token-budget-aware assembly
|
||
- orchestrator adapter abstraction
|
||
- planning mode / orchestration mode interfaces
|
||
|
||
Результат этапа:
|
||
|
||
- все будущие вызовы reasoning model идут через один нормализованный путь
|
||
|
||
Проверка:
|
||
|
||
- tests на context assembly priorities
|
||
|
||
### Stage 7. Router and Directive Flow
|
||
|
||
Цель:
|
||
|
||
- зафиксировать router как pure decision layer
|
||
|
||
Сделать:
|
||
|
||
- `router.py`
|
||
- `state + context -> ExecutionDirective`
|
||
- no side effects
|
||
- routing rules for:
|
||
- retrieval needed
|
||
- planning needed
|
||
- permission needed
|
||
- critic needed
|
||
|
||
Результат этапа:
|
||
|
||
- runtime loop применяет решения, а не изобретает их сам
|
||
|
||
Проверка:
|
||
|
||
- unit tests на routing decisions
|
||
|
||
### Stage 8. Execution Engine and Task Graph
|
||
|
||
Цель:
|
||
|
||
- получить управляемое исполнение шагов, а не “вызовы по месту”
|
||
|
||
Сделать:
|
||
|
||
- `execution_engine.py`
|
||
- `execution_scheduler.py`
|
||
- task graph validation
|
||
- sequential DAG scheduler
|
||
- adapters for tool/coder execution
|
||
|
||
Результат этапа:
|
||
|
||
- runtime может исполнять direct action и multi-step plans
|
||
|
||
Проверка:
|
||
|
||
- task graph validation tests
|
||
- step ordering tests
|
||
|
||
### Stage 9. Permission System and Tool Sandbox
|
||
|
||
Цель:
|
||
|
||
- не дать runtime выполнять опасные действия напрямую
|
||
|
||
Сделать:
|
||
|
||
- permission rules
|
||
- persistent approval store
|
||
- shell safety classifier
|
||
- sandbox execution adapter
|
||
- timeout/resource/path restrictions
|
||
|
||
Результат этапа:
|
||
|
||
- опасные команды требуют policy decision до запуска
|
||
|
||
Проверка:
|
||
|
||
- permission flow tests
|
||
- sandbox boundary smoke tests
|
||
|
||
### Stage 10. MVP Tools
|
||
|
||
Цель:
|
||
|
||
- сделать минимально полезный execution path
|
||
|
||
Сделать:
|
||
|
||
- `shell_exec`
|
||
- `file_read`
|
||
- `file_write`
|
||
- unified tool registry
|
||
- unified `ToolResult`
|
||
|
||
Результат этапа:
|
||
|
||
- runtime уже может выполнять реальные локальные задачи
|
||
|
||
Проверка:
|
||
|
||
- integration tests для трёх базовых tools
|
||
|
||
### Stage 11. FastAPI API and Health Surface
|
||
|
||
Цель:
|
||
|
||
- открыть runtime наружу через стабильный backend interface
|
||
|
||
Сделать:
|
||
|
||
- `POST /chat`
|
||
- `WS /stream`
|
||
- `GET /health`
|
||
- базовый request/response models
|
||
- error handling
|
||
|
||
Результат этапа:
|
||
|
||
- систему уже можно дергать из внешнего клиента
|
||
|
||
Проверка:
|
||
|
||
- API smoke tests
|
||
|
||
### Stage 12. Web Chat Test Client
|
||
|
||
Цель:
|
||
|
||
- получить быстрый способ руками проверить поведение всей системы через браузер
|
||
|
||
Сделать:
|
||
|
||
- минимальный локальный веб-чат
|
||
- простую страницу с:
|
||
- вводом задачи
|
||
- окном сообщений
|
||
- панелью streaming events
|
||
- индикацией permission requests
|
||
- отображением final result
|
||
- подключение к `POST /chat` и `WS /stream`
|
||
|
||
Требования:
|
||
|
||
- это не production UI
|
||
- это не отдельный продуктовый frontend
|
||
- это thin test client для ручной проверки runtime
|
||
|
||
Лучше всего разместить как:
|
||
|
||
- `app/api/static/` или отдельный `web/` модуль с минимальным стеком
|
||
|
||
Результат этапа:
|
||
|
||
- можно открыть браузер и увидеть, как runtime планирует, исполняет шаги и стримит события
|
||
|
||
Проверка:
|
||
|
||
- ручной e2e smoke test через браузер
|
||
|
||
### Stage 13. Coder Integration
|
||
|
||
Цель:
|
||
|
||
- подключить отдельную coding model без смешивания ролей
|
||
|
||
Сделать:
|
||
|
||
- `core/coder.py`
|
||
- `generate_code`
|
||
- `fix_code`
|
||
- `refactor_code`
|
||
- structured coder result
|
||
|
||
Результат этапа:
|
||
|
||
- runtime может делегировать кодогенерацию специализированной модели
|
||
|
||
Проверка:
|
||
|
||
- tests на coder request/response flow
|
||
|
||
### Stage 14. Critic Integration
|
||
|
||
Цель:
|
||
|
||
- получить formal evaluation layer после tools/coder
|
||
|
||
Сделать:
|
||
|
||
- critic adapter
|
||
- `CriticScore`
|
||
- fallback policy when critic unavailable
|
||
|
||
Результат этапа:
|
||
|
||
- результаты можно оценивать единообразно
|
||
|
||
Проверка:
|
||
|
||
- critic scoring contract tests
|
||
|
||
### Stage 15. Memory System
|
||
|
||
Цель:
|
||
|
||
- добавить долговременную retrieval memory
|
||
|
||
Сделать:
|
||
|
||
- SQLite metadata store
|
||
- FAISS/hnswlib vector index
|
||
- insert/search/delete/reindex
|
||
- embedding versioning
|
||
|
||
Результат этапа:
|
||
|
||
- runtime получает semantic retrieval вместо контекста “только текущая задача”
|
||
|
||
Проверка:
|
||
|
||
- memory insert/search tests
|
||
|
||
### Stage 16. Memory Write Policy
|
||
|
||
Цель:
|
||
|
||
- не допустить хаотичной записи всего подряд
|
||
|
||
Сделать:
|
||
|
||
- deterministic write policy
|
||
- threshold model
|
||
- dedup / merge rules
|
||
- conflict handling
|
||
|
||
Результат этапа:
|
||
|
||
- память пополняется контролируемо, а не по одному score cutoff
|
||
|
||
Проверка:
|
||
|
||
- memory policy decision tests
|
||
|
||
### Stage 17. Retry, Recovery, Replay
|
||
|
||
Цель:
|
||
|
||
- довести runtime до устойчивого long-running поведения
|
||
|
||
Сделать:
|
||
|
||
- planner retry
|
||
- tool retry for allowed cases
|
||
- partial failure recovery
|
||
- replay path from event store
|
||
- resume from checkpoint
|
||
|
||
Результат этапа:
|
||
|
||
- система может переживать ошибки без полной потери исполнения
|
||
|
||
Проверка:
|
||
|
||
- recovery smoke tests
|
||
- replay tests
|
||
|
||
### Stage 18. CLI and Operator Utilities
|
||
|
||
Цель:
|
||
|
||
- дать локальный интерфейс помимо API/веб-чата
|
||
|
||
Сделать:
|
||
|
||
- send task
|
||
- show result
|
||
- follow events
|
||
- memory search
|
||
- replay task history
|
||
|
||
Результат этапа:
|
||
|
||
- разработчик может проверять runtime без браузера
|
||
|
||
Проверка:
|
||
|
||
- CLI smoke tests
|
||
|
||
### Stage 19. Hardening and Tests
|
||
|
||
Цель:
|
||
|
||
- довести проект до инженерно приемлемого состояния
|
||
|
||
Сделать:
|
||
|
||
- structured logging refinement
|
||
- failure-path tests
|
||
- concurrency edge cases
|
||
- docs refresh
|
||
- cleanup of temporary stubs
|
||
|
||
Результат этапа:
|
||
|
||
- проект становится пригодным для реальной итеративной разработки
|
||
|
||
Проверка:
|
||
|
||
- full critical-path smoke suite
|
||
|
||
## 4. Recommended First Working Demo
|
||
|
||
Первый нормальный demo checkpoint должен быть на этапе `Stage 12`.
|
||
|
||
Что должно работать к этому моменту:
|
||
|
||
- браузерный веб-чат открывается локально
|
||
- пользователь отправляет задачу
|
||
- runtime принимает task
|
||
- событие начала работы видно в UI
|
||
- если нужен plan, это видно в events panel
|
||
- tool execution видно в events panel
|
||
- final response возвращается в чат
|
||
|
||
На этом этапе memory, critic и recovery ещё могут быть частично stubbed, но:
|
||
|
||
- runtime loop
|
||
- event bus
|
||
- state persistence
|
||
- router
|
||
- execution engine
|
||
- permissions
|
||
- базовые tools
|
||
- API
|
||
- web chat
|
||
|
||
должны быть уже реальными.
|
||
|
||
## 5. Order Rationale
|
||
|
||
Почему веб-чат не в самом конце:
|
||
|
||
- он нужен как live inspection surface для runtime
|
||
- через него проще проверять streaming, permissions и event ordering
|
||
- он быстрее выявляет архитектурные проблемы, чем голые unit tests
|
||
|
||
Но веб-чат ставится только после:
|
||
|
||
- runtime core
|
||
- event bus
|
||
- persistence
|
||
- basic execution path
|
||
- API
|
||
|
||
Иначе он станет красивой оболочкой над несуществующей системой.
|