a.tolmachev
188 lines
5.6 KiB
Markdown
188 lines
5.6 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-mapping/
|
|
crank-schema/
|
|
```
|
|
|
|
Поверх существующих 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-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.5. `crank-runtime`
|
|
|
|
Назначение:
|
|
|
|
- исполнение published operation;
|
|
- резолв `auth_profile_ref -> secret -> request auth`;
|
|
- orchestration window/session/job execution;
|
|
- запись invocation events;
|
|
- возврат нормализованного результата.
|
|
|
|
Дополнительное правило для split:
|
|
|
|
- `crank-runtime` должен собираться как `REST-only` base даже без premium adapter crates;
|
|
- premium protocol adapters подключаются через feature seams, а не как безусловная зависимость Community runtime.
|
|
|
|
### 4.6. Protocol adapters
|
|
|
|
- `crank-adapter-rest`
|
|
|
|
Community runtime в этом репозитории поддерживает только `REST`.
|
|
|
|
### 4.7. `apps/admin-api`
|
|
|
|
Должен содержать сервисные группы:
|
|
|
|
- `workspaces`
|
|
- `secrets`
|
|
- `memberships`
|
|
- `operations`
|
|
- `auth_profiles`
|
|
- `agents`
|
|
- `agent_keys`
|
|
- `platform_clients`
|
|
- `logs`
|
|
- `usage`
|
|
- `streaming`
|
|
|
|
### 4.8. `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. Что остается в `crank-community`
|
|
|
|
В этом репозитории должны жить:
|
|
|
|
- Community domain model;
|
|
- Community runtime;
|
|
- Community UI;
|
|
- extension seams для коммерческих возможностей;
|
|
- capability model по редакциям.
|
|
|
|
### 5.2. Что должно выноситься в private delivery
|
|
|
|
За пределами `crank-community` должны жить:
|
|
|
|
- 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.
|