Add architecture package and application skeleton
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
# Доменная модель
|
||||
|
||||
## Слои
|
||||
|
||||
### Domain
|
||||
|
||||
Чистые сущности, value objects, state machines, классификация рисков, события.
|
||||
|
||||
### Application
|
||||
|
||||
Use cases:
|
||||
|
||||
- create_task
|
||||
- submit_chat_message
|
||||
- plan_task
|
||||
- execute_ready_nodes
|
||||
- request_confirmation
|
||||
- approve_confirmation
|
||||
- reject_confirmation
|
||||
- register_worker
|
||||
- ingest_worker_result
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- storage adapters
|
||||
- config loader
|
||||
- event publisher
|
||||
- model providers
|
||||
- MCP transport
|
||||
- worker gateway
|
||||
- artifact persistence
|
||||
|
||||
### Delivery
|
||||
|
||||
- HTTP API
|
||||
- SSE task events
|
||||
- worker WebSocket session endpoint
|
||||
|
||||
## Главные сущности
|
||||
|
||||
### ProjectConfig
|
||||
|
||||
Описывает:
|
||||
|
||||
- model slots
|
||||
- policy modes
|
||||
- execution limits
|
||||
- enabled MCP servers
|
||||
- worker access rules
|
||||
|
||||
### Conversation
|
||||
|
||||
Контейнер пользовательского диалога и связанных задач.
|
||||
|
||||
### Task
|
||||
|
||||
Единица выполнения пользовательской цели.
|
||||
|
||||
Поля:
|
||||
|
||||
- `id`
|
||||
- `project_id`
|
||||
- `conversation_id`
|
||||
- `goal`
|
||||
- `inputs`
|
||||
- `status`
|
||||
- `requested_mode`
|
||||
- `effective_mode`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `result_summary`
|
||||
|
||||
### ExecutionGraph
|
||||
|
||||
Набор node definitions и execution dependencies для конкретной task.
|
||||
|
||||
### Node
|
||||
|
||||
Типы:
|
||||
|
||||
- `planner`
|
||||
- `model_call`
|
||||
- `tool_call`
|
||||
- `local_worker_call`
|
||||
- `reviewer`
|
||||
- `finalizer`
|
||||
- `confirmation`
|
||||
|
||||
### ConfirmationRequest
|
||||
|
||||
Отдельная сущность для действий, требующих подтверждения.
|
||||
|
||||
### WorkerSession
|
||||
|
||||
Онлайн-сессия thin local worker.
|
||||
|
||||
### ModelInvocation
|
||||
|
||||
Record вызова model router/provider.
|
||||
|
||||
### ToolInvocation
|
||||
|
||||
Record вызова MCP tool или worker command.
|
||||
|
||||
### Artifact
|
||||
|
||||
Материализованный результат: patch, file diff, report, log bundle.
|
||||
|
||||
### Event
|
||||
|
||||
Audit и UI-событие в единой taxonomy.
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# State Machines
|
||||
|
||||
## TaskStatus
|
||||
|
||||
```text
|
||||
created
|
||||
-> planned
|
||||
-> running
|
||||
-> waiting_confirmation
|
||||
-> waiting_manual
|
||||
-> completed
|
||||
-> failed
|
||||
-> cancelled
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- `created -> planned`: planner graph создан;
|
||||
- `planned -> running`: есть готовые к исполнению nodes;
|
||||
- `running -> waiting_confirmation`: execution остановлен на pending approval;
|
||||
- `running -> waiting_manual`: policy/manual gate остановил автостарт;
|
||||
- `running -> completed`: finalizer сформировал итог;
|
||||
- `running -> failed`: unrecoverable error;
|
||||
- `waiting_confirmation -> running`: approval получен;
|
||||
- `waiting_manual -> running`: пользователь вручную продолжил выполнение.
|
||||
|
||||
## NodeStatus
|
||||
|
||||
```text
|
||||
pending
|
||||
-> ready
|
||||
-> running
|
||||
-> waiting_confirmation
|
||||
-> completed
|
||||
-> failed
|
||||
-> skipped
|
||||
-> cancelled
|
||||
```
|
||||
|
||||
## ConfirmationStatus
|
||||
|
||||
```text
|
||||
pending
|
||||
-> approved
|
||||
-> rejected
|
||||
-> expired
|
||||
-> cancelled
|
||||
```
|
||||
|
||||
## WorkerSessionStatus
|
||||
|
||||
```text
|
||||
connecting
|
||||
-> online
|
||||
-> busy
|
||||
-> stale
|
||||
-> disconnected
|
||||
```
|
||||
|
||||
## Retry Principles
|
||||
|
||||
- retry выполняется только для явно retryable failures;
|
||||
- retry history фиксируется в node attempts и event log;
|
||||
- confirmation-required state не считается failure;
|
||||
- idempotency must be explicit for side-effecting nodes.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# Internal Interfaces
|
||||
|
||||
## Orchestrator Application Ports
|
||||
|
||||
### TaskRepository
|
||||
|
||||
- create task
|
||||
- update task
|
||||
- get task by id
|
||||
- list active tasks
|
||||
|
||||
### GraphRepository
|
||||
|
||||
- save graph
|
||||
- get graph
|
||||
- update node state
|
||||
- list ready nodes
|
||||
|
||||
### ConfirmationRepository
|
||||
|
||||
- create confirmation
|
||||
- get confirmation
|
||||
- resolve confirmation
|
||||
|
||||
### WorkerRepository
|
||||
|
||||
- register session
|
||||
- update heartbeat
|
||||
- assign command
|
||||
- complete command
|
||||
|
||||
### EventStore
|
||||
|
||||
- append event
|
||||
- list events by task
|
||||
|
||||
### PolicyEvaluator
|
||||
|
||||
- evaluate action descriptor against project policy
|
||||
|
||||
### ModelRouter
|
||||
|
||||
- execute model request and return structured invocation result
|
||||
|
||||
### ToolGateway
|
||||
|
||||
- call MCP tool and return normalized result
|
||||
|
||||
### WorkerGateway
|
||||
|
||||
- dispatch command to worker and receive normalized result
|
||||
|
||||
## Design Rule
|
||||
|
||||
Application services зависят только от этих портов.
|
||||
Ни один use case не должен напрямую импортировать HTTP handlers, DB session objects или конкретный MCP/WebSocket client.
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# Error Model
|
||||
|
||||
## Error Families
|
||||
|
||||
### ValidationError
|
||||
|
||||
Некорректный вход, schema mismatch, invalid command envelope.
|
||||
|
||||
### PolicyError
|
||||
|
||||
Действие запрещено текущей конфигурацией или требует manual/confirm остановки.
|
||||
|
||||
### RetryableInfrastructureError
|
||||
|
||||
Временная ошибка транспорта, timeout, transient upstream failure.
|
||||
|
||||
### NonRetryableInfrastructureError
|
||||
|
||||
Постоянная ошибка конфигурации, unsupported capability, broken contract.
|
||||
|
||||
### ExecutionError
|
||||
|
||||
Ошибка бизнес-исполнения конкретного node.
|
||||
|
||||
### CancellationError
|
||||
|
||||
Task или node остановлены по explicit cancel.
|
||||
|
||||
## User-Facing Behavior
|
||||
|
||||
- validation и policy ошибки должны быть ясными и краткими;
|
||||
- infra ошибки должны сохранять technical details в logs/events;
|
||||
- task итог должен различать `failed` и `waiting for action`.
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# Execution Model
|
||||
|
||||
## Базовый цикл
|
||||
|
||||
1. Пользователь создает `Task`.
|
||||
2. Planner materializes `ExecutionGraph`.
|
||||
3. Graph engine отмечает `ready` узлы.
|
||||
4. Orchestrator выбирает runner для каждого ready node.
|
||||
5. Перед side-effecting action выполняется policy evaluation.
|
||||
6. Если нужен `confirm`, создается `ConfirmationRequest` и graph останавливается.
|
||||
7. Если action разрешен, runner выполняет node.
|
||||
8. Node результат сохраняется как output + event trail + optional artifacts.
|
||||
9. Reviewer может валидировать промежуточный результат.
|
||||
10. Finalizer формирует user-facing result и cards.
|
||||
|
||||
## Node Families
|
||||
|
||||
### Planner
|
||||
|
||||
Создает или пересобирает graph. Не выполняет side effects.
|
||||
|
||||
### Model Call
|
||||
|
||||
Использует `ModelRouter`.
|
||||
Может инициировать fallback, но только внутри router contract.
|
||||
|
||||
### Tool Call
|
||||
|
||||
Использует `ToolGateway` для MCP.
|
||||
|
||||
### Local Worker Call
|
||||
|
||||
Использует `WorkerGateway` для thin executor.
|
||||
|
||||
### Reviewer
|
||||
|
||||
Системный шаг quality gate:
|
||||
|
||||
- schema validation
|
||||
- semantic validation
|
||||
- retry recommendation
|
||||
- escalate to strong model
|
||||
|
||||
### Finalizer
|
||||
|
||||
Преобразует execution result в user result:
|
||||
|
||||
- message text
|
||||
- cards
|
||||
- artifacts metadata
|
||||
- summary
|
||||
|
||||
## Execution Rules
|
||||
|
||||
- workers не создают новые workers;
|
||||
- model/router adapters не меняют graph напрямую;
|
||||
- только orchestrator меняет task/node state;
|
||||
- side effects всегда проходят через policy decision;
|
||||
- event log пишется на каждом значимом переходе.
|
||||
|
||||
## Manual And Resume
|
||||
|
||||
`manual` означает, что orchestrator не стартует следующий шаг автоматически.
|
||||
Task остается в `waiting_manual` до явного resume action.
|
||||
|
||||
## Replay
|
||||
|
||||
Replay не означает повтор side effects автоматически.
|
||||
Replay должен уметь:
|
||||
|
||||
- восстанавливать graph state из persisted state;
|
||||
- переиздавать progress view;
|
||||
- запускать retry только для разрешенных retryable nodes.
|
||||
|
||||
Reference in New Issue
Block a user