EPIC — Hercules Studio

Статус: Planning Owner: Victor V (techbuzzz) Started: 2026-08-14 License: AGPL-3.0 (Community / Non-profit) + Commercial License для корпоративного использования

Hercules Studio — десктопное IDE-приложение (Electron + Vue 3) для управления, настройки и оркестрации агентов Hercules. Не замена src/hercules-web (он остаётся лёгкой веб-админкой), а супер-расширение для power users: подключение к нескольким агентам, тонкая настройка, редактор навыков с C# file-based apps, mesh explorer, консилиум агентов с BPMN-подобной оркестрацией.

Документы

Документ	Назначение
SYSTEM-DESIGN.md	Архитектура, компоненты, потоки данных, стек
ROADMAP.md	9 этапов разработки с целями и зависимостями
ARCHITECTURE.md	Детальные технические диаграммы, IPC-контракты, модели данных
adr/	Architecture Decision Records (выбор Electron, Vue, портов, auth)
tasks/	Task-level планы для каждого этапа (stage_00 … stage_09)

Ключевые решения (summary)

Платформа: Windows x64 (MVP), macOS/Linux позже
Стек: Electron 30+ / electron-vite / Vue 3 (Composition API) / Pinia / Vite / Tailwind CSS 4 / shadcn-vue / Monaco Editor / xterm.js / Vue Flow / better-sqlite3 / Tabler Icons
Порт агента: 8421-8521 (100 портов, мнемоника “степени двойки”). Дефолт 8421. Legacy 5000 сканируется как fallback
Auth: Dual API keys (contribute + system) + CheckIn/CheckOut (heartbeat TTL 60s). System key = read-only monitor может подключаться параллельно. Workflow-server использует clientId/clientSecret
Репозиторий: Монорепо src/hercules-studio/ внутри Hercules. Отдельный репо позже если станет отдельным продуктом
Лицензия: AGPL-3.0 + commercial license. Trust-based для MVP, license consent dialog при first-run
Сборка: electron-vite для dev, electron-builder (NSIS) для packaging. GitHub Actions CI. Agent + Studio независимые версии, совместимость по API contract
Локальное хранилище Studio: userData/studio.db (SQLite) для chat history, skill drafts, workflows, scan cache. Connections/settings в JSON + safeStorage
hercules-workflow-server: Отдельный .NET сервис для workflow execution (Этап 8 production). Триггеры: webhook + cron (MVP), file watcher + event bus позже
SkillSdk: NuGet-пакет Hercules.SkillSdk — IHttpClient, IMcpClient, ILlmClient, IMemoryClient, ISkillLogger, ISessionContext. C# file-based apps hosted в процессе агента, whitelist approach
Context distillation: Hierarchical (recent=raw, older=summary, ancient=key facts). Доработка бэкенда /api/context/*
i18n: en/ru с самого начала (vue-i18n)
Theme: Dark + Light, switchable. Dark = базовый

Скоуп Epic

Studio (этапы 0-9)

Stage 0 — Skeleton: Electron + Vue + Vite, IPC, layout, Pinia, SQLite, SDK, license consent
Stage 1 — Agent Scanner + Connection Manager + CheckIn/CheckOut
Stage 2 — Chat (1 агент) + Skill Editor (Monaco)
Stage 3 — Skill Authoring + Push на агента
Stage 4 — Mesh Explorer + визуализация topology
Stage 5 — Tool Registry + MCP management
Stage 6 — Тонкая настройка + restart + context distillation + Postgres centralized storage + SkillSdk
Stage 7 — Консилиум (multi-agent chat + агрегация)
Stage 8 — BPMN Workflow Designer (MVP Studio-orchestrator → production backend-executor)
Stage 9 — Packaging: tray, auto-updater, NSIS installer, tests

Backend prerequisites (Phase 8 в backlog)

Доработки Hercules.WebApi и новых сервисов, необходимые для Studio:

Port migration 5000 → 8421 (отдельный PR до старта Studio)
Dual API keys (contribute + system roles)
CheckIn/CheckOut protocol
POST /api/system/restart supervisor protocol
McpClientService : IConfigReload (MCP hot-reload)
SkillSdk (Hercules.SkillSdk NuGet + HerculesSkillContext)
Context distillation (/api/context/distill, /api/context/summary)
Postgres session store (ISessionStore abstraction)
hercules-workflow-server (отдельный .NET сервис)
Workflow engine (graph model, executor, /api/workflows/*)

Полный список задач prerequisite — в docs/roadmap/backlog.md (раздел Phase 8).

Совместимость

Studio	Agent	Notes
0.1.x	текущая + port migration	Basic: chat, skills, config
0.2.x	+ dual API keys + CheckIn/CheckOut	Scanner, multi-agent
0.3.x	+ McpClientService reload	MCP management
0.4.x	+ restart protocol + SkillSdk + context distillation	Full config, C# skills
0.5.x	+ Postgres session store	Centralized storage
0.6.x	+ hercules-workflow-server	BPMN workflows

Ссылки

SYSTEM-DESIGN.md — полная архитектура
ROADMAP.md — этапы
tasks/ — детальные планы задач
adr/ — архитектурные решения
../roadmap/backlog.md — backlog Hercules (включая Phase 8 prerequisites)
Stage 2 code execution (DotnetFileBasedExecutor, sandbox, SkillSdk) — PLAN-v2.md was referenced here but does not exist in this repo; see ../roadmap/tasks/ for the implemented work items.