a.tolmachev
200 lines
5.7 KiB
Markdown
200 lines
5.7 KiB
Markdown
# Декомпозиция модулей
|
||
|
||
## 1. Цель документа
|
||
|
||
Этот документ фиксирует детальную структуру проекта под целевую модель `workspace -> agent -> operations`.
|
||
|
||
Основной принцип: каждый crate отвечает за один слой системы. Внутри crate модули маленькие, тематические и с минимальным количеством публичных сущностей.
|
||
|
||
## 2. Общие архитектурные правила
|
||
|
||
- `core` содержит только базовую доменную модель, идентификаторы, типы ошибок и общие контракты.
|
||
- `registry` отвечает только за хранение и загрузку workspace-scoped конфигурации.
|
||
- `runtime` исполняет операции, но не знает о способе их хранения.
|
||
- адаптеры знают только свой протокол и общий контракт runtime.
|
||
- `admin-api` оркестрирует use case для UI, но не содержит протокольной логики.
|
||
- `mcp-server` публикует agent-scoped tools и вызывает runtime.
|
||
- `ui` работает только через HTTP API.
|
||
|
||
## 3. Workspace-структура
|
||
|
||
```text
|
||
crank/
|
||
apps/
|
||
admin-api/
|
||
mcp-server/
|
||
ui/
|
||
crates/
|
||
crank-core/
|
||
crank-registry/
|
||
crank-runtime/
|
||
crank-adapter-rest/
|
||
crank-adapter-graphql/
|
||
crank-adapter-grpc/
|
||
crank-adapter-websocket/
|
||
crank-adapter-soap/
|
||
crank-mapping/
|
||
crank-schema/
|
||
crank-proto/
|
||
```
|
||
|
||
Поверх существующих crates должны появиться новые логические поддомены:
|
||
|
||
- workspace/access domain;
|
||
- secret management domain;
|
||
- agent publishing domain;
|
||
- observability domain.
|
||
- streaming execution domain.
|
||
|
||
## 4. Детальная декомпозиция по crate
|
||
|
||
### 4.1. `crank-core`
|
||
|
||
Назначение:
|
||
|
||
- базовые доменные типы;
|
||
- идентификаторы;
|
||
- метаданные workspace, operation и agent;
|
||
- общие контракты и ошибки.
|
||
|
||
Внутренние модули:
|
||
|
||
- `ids`
|
||
- `protocol`
|
||
- `workspace`
|
||
- `operation`
|
||
- `agent`
|
||
- `auth`
|
||
- `secret`
|
||
- `observability`
|
||
- `streaming`
|
||
- `errors`
|
||
|
||
### 4.2. `crank-schema`
|
||
|
||
Назначение:
|
||
|
||
- внутренняя модель схем;
|
||
- нормализация входа и выхода;
|
||
- представление полей для UI и runtime.
|
||
|
||
### 4.3. `crank-mapping`
|
||
|
||
Назначение:
|
||
|
||
- mapping DSL;
|
||
- `JSONPath` parsing;
|
||
- input/output mapping;
|
||
- draft inference из samples.
|
||
|
||
### 4.4. `crank-proto`
|
||
|
||
Назначение:
|
||
|
||
- работа с `.proto` и descriptor set;
|
||
- извлечение services, methods и message schemas;
|
||
- преобразование protobuf metadata во внутренние типы.
|
||
|
||
### 4.5. `crank-registry`
|
||
|
||
Назначение:
|
||
|
||
- хранение workspace-scoped operations и version snapshots;
|
||
- хранение workspace-scoped secrets и secret versions;
|
||
- хранение agents и agent versions;
|
||
- хранение agent keys и выданных agent tokens;
|
||
- хранение stream sessions и async jobs;
|
||
- auth profiles;
|
||
- platform client credentials;
|
||
- logs и usage aggregates;
|
||
- metadata по sample artifacts и descriptors.
|
||
|
||
### 4.6. `crank-runtime`
|
||
|
||
Назначение:
|
||
|
||
- исполнение published operation;
|
||
- резолв `auth_profile_ref -> secret -> request auth`;
|
||
- orchestration window/session/job execution;
|
||
- запись invocation events;
|
||
- возврат нормализованного результата.
|
||
|
||
### 4.7. Protocol adapters
|
||
|
||
- `crank-adapter-rest`
|
||
- `crank-adapter-graphql`
|
||
- `crank-adapter-grpc`
|
||
- `crank-adapter-websocket`
|
||
- `crank-adapter-soap`
|
||
|
||
Каждый adapter знает только свой протокол.
|
||
|
||
### 4.8. `apps/admin-api`
|
||
|
||
Должен содержать сервисные группы:
|
||
|
||
- `workspaces`
|
||
- `secrets`
|
||
- `memberships`
|
||
- `operations`
|
||
- `auth_profiles`
|
||
- `agents`
|
||
- `agent_keys`
|
||
- `platform_clients`
|
||
- `logs`
|
||
- `usage`
|
||
- `streaming`
|
||
|
||
### 4.9. `apps/mcp-server`
|
||
|
||
Назначение:
|
||
|
||
- публикация published agent bindings как MCP tools;
|
||
- transport handling;
|
||
- JSON-RPC lifecycle;
|
||
- SSE lifecycle и `Mcp-Session-Id`;
|
||
- tool-family generation для `session` и `async_job`;
|
||
- вызов runtime.
|
||
|
||
Антипаттерн:
|
||
|
||
не превращать `mcp-server` во второй `admin-api`.
|
||
|
||
## 5. Разделение open-source и commercial модулей
|
||
|
||
### 5.1. Что остается в public repository
|
||
|
||
В этом репозитории должны жить:
|
||
|
||
- Community domain model;
|
||
- Community runtime;
|
||
- Community UI;
|
||
- extension seams для коммерческих возможностей;
|
||
- capability model по редакциям.
|
||
|
||
### 5.2. Что должно выноситься в private delivery
|
||
|
||
За пределами public repo должны жить:
|
||
|
||
- short-lived и one-time token issuers;
|
||
- enterprise access services;
|
||
- `SSO`, `2FA`, `RBAC`, `audit log`;
|
||
- metering и billing;
|
||
- cloud control plane;
|
||
- premium protocol families, если они не входят в Community edition.
|
||
|
||
### 5.3. Техническое правило
|
||
|
||
Public code не должен содержать скрытую private business logic.
|
||
|
||
Допустимо:
|
||
|
||
- trait boundaries;
|
||
- capability flags;
|
||
- edition-aware service contracts.
|
||
|
||
Недопустимо:
|
||
|
||
- полноценная коммерческая реализация в open-source исходниках;
|
||
- UI, который реально включает premium flow без server-side gating.
|