# Mazzy Command Center

[English](README.md) · **Русский** · [Deutsch](README.de.md) · [中文](README.zh.md) · [日本語](README.ja.md) · [한국어](README.ko.md)

**Локальный оркестратор агентов и командный центр с родительской аттестацией для агента [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).**

_Автор: **Mazurov N.N.** — https://github.com/mazurovn · Лицензия **PolyForm
Noncommercial 1.0.0**: свободно для личного, научного и учебного использования;
коммерческое использование — по отдельной лицензии (см. [LICENSE](LICENSE))._

Mazzy Command Center — это **полноценный оркестратор агентов и командный центр**,
собранный как проектное расширение Pi. Он превращает сессию Pi в надёжный,
проверяемый центр, из которого работа агентов планируется, делегируется,
исполняется, проходит ревью и запоминается: трекер задач + оркестратор + собственный
субагентный движок + креатор субагентов + мета-агенты + многоуровневая память +
граф знаний спецификация↔код↔беклог — всё поверх единого встроенного SQLite-ядра.

> **Статус: аутентифицированный локальный пилот, активно развивающийся к полному
> командному центру.** Пилот сегодня включает надёжное ядро, дашборд, граф-вью и
> оркестрацию с аттестацией. Собственный субагентный движок, креатор субагентов,
> мета-агенты и многоуровневая память / DAG / RAG / векторы — это направление
> продукта, внедряемое постепенно. См. [Дорожную карту](#дорожная-карта) и
> [Безопасность и ограничения](#безопасность-и-ограничения).

---

## Что это такое

Mazzy — это **командный центр, которому принадлежит оркестрация**: он решает, *что
запускать следующим, каким агентом, при каком бюджете и потолке возможностей*, и
хранит устойчивый план, доказательства, память и граф знаний. Он построен вокруг
чёткого **разделения трёх видов власти**, чтобы владение мощным движком никогда не
превращало веб-поверхность в оракул удалённого исполнения:

1. **Планирование** (ядро) — чистый планировщик вычисляет, что запускать дальше, из
   устойчивых типизированных записей.
2. **Диспетчеризация** (собственный executor Mazzy) — отдельный, **без сетевого
   доступа**, живущий во время жизни родителя процесс — единственное, что реально
   запускает работу.
3. **Провайдер исполнения** — заменяемый runtime за этим executor'ом (сегодня
   `pi-subagents`; Mazzy владеет интерфейсом провайдера и растит собственный движок).

- **Надёжный трекер задач** — эпики / фичи / задачи / баги с версионируемым
  жизненным циклом (`DRAFT → BACKLOG → READY → CLAIMED → RUNNING → REVIEW → DONE`,
  плюс `BLOCKED / FAILED / CANCELLED`), с проверкой оптимистичной конкурентности.
- **Оркестратор с аттестуемой диспетчеризацией** — Mazzy планирует и запускает
  работу, привязывает *наблюдаемый* прогон к задаче и требует для `DONE`
  независимого доказательства PASS.
- **Собственный субагентный движок и креатор** *(направление)* — первопартийный
  движок исполнения и декларативный креатор субагентов: определяйте агентов,
  потолки возможностей, бюджеты и промпт-контракты и запускайте их через свой executor.
- **Мета-агенты** *(направление)* — агенты, чей вывод — это *предложения*, на которые
  действуют другие агенты, по тому же аттестуемому пути с потолком возможностей.
- **Многоуровневая память + знания** *(направление)* — hot / warm / cold память с
  гибридным поиском (RAG) и векторами, плюс план-DAG — как контекст, никогда как власть.
- **Аутентифицированный локальный дашборд** — самодостаточный веб-интерфейс на
  `localhost` с capability-токеном, живыми обновлениями по SSE, Kanban-доской и
  панелью обсуждения задачи.
- **Граф знаний SDD/ADR** — визуализация в браузере, связывающая пункты спецификации
  (ADR/INV/FR), компоненты кода и элементы беклога в один фильтруемый граф (память и
  векторы подключаются как первоклассные источники).
- **Безопасный скаффолдинг** — `mazzy-init` создаёт переносимые шаблоны проекта с
  режимом dry-run по умолчанию, защищённым `--force` и `--rollback`.

---

## Архитектура кратко

Mazzy владеет оркестрацией через **разделение трёх видов власти**, чтобы мощный
движок никогда не превращал веб-поверхность в оракул удалённого исполнения:

```
Человек / планировщик ── команды Pi / аутентиф. браузер localhost ──┐
                                                                    v
Ядро Mazzy Command Center (власть оркестрации) ── SQLite-ядро
   • план / доказательства / память и знания (направл.)  │
   • выдаёт одноразовую авторизацию диспетчеризации     │
                                                        v
                        Executor Mazzy  (отдельный процесс без сети)
                                                        │
                                                        v
                        провайдер исполнения — сегодня pi-subagents,
                        собственный движок Mazzy (направл.) — заменяемый
```

**Основные принципы (инварианты):**

- **Никакого исполнения, вызванного через HTTP** — ни один процесс, завершающий
  HTTP-сокет, не имеет власти диспетчеризации; работу запускает только отдельный
  executor и только против одноразовой авторизации.
- **Свободный текст не управляет исполнением** — планирование это чистая функция
  типизированных записей; память, векторы и кэш — это *контекст, никогда не власть*.
- **Только родитель пишет** — изменения ядра требуют интерактивного родителя;
  унаследованные дочерние процессы отклоняются.
- **Никакие host-пути не пересекают API** — за пределы localhost выходят только
  непрозрачные id, enum'ы и относительные ссылки.
- **Комментарии — никогда не доказательство** — авторитетный канал PASS/FAIL — это
  доказательства ревьюера/верификатора.
- **Все вызовы `git` защищены** — конфигурация/хуки репозитория и унаследованное
  окружение не могут повлиять на исполнение.

---

## Инструменты и команды

**Инструменты только для родителя** (поверхность, видимая LLM):

| Инструмент | Назначение |
|---|---|
| `mazzy_task` | Создание / список / получение / обновление задач (версионируемые; `DONE` требует PASS-доказательства). |
| `mazzy_route` | Read-only предпроверка политики делегирования (никогда не порождает). |
| `mazzy_assignment` | Привязка прогона, импорт завершения и доказательства ревьюера с аттестацией. |
| `mazzy_discussion` | Чтение/ответ на надёжное обсуждение задачи. |
| `mazzy_control` | Claim/complete/fail для запросов GO / PAUSE / STOP из дашборда. |

**Slash-команды:** `/mazzy` (статус + URL дашборда), `/mazzy-url` (URL доступа с
токеном), `/mazzy-server` (start/stop/status), `/mazzy-menu` (`Ctrl+Alt+M`),
`/mazzy-init`, `/mazzy-doctor`, `/mazzy-registry`, `/mazzy-clean`.

---

## Установка

**Требования**

| Компонент | Версия |
|---|---|
| Node.js | `>= 22.19.0` |
| `@earendil-works/pi-coding-agent` | `0.84.2` |
| `@earendil-works/pi-ai` | `0.84.2` |
| `@earendil-works/pi-tui` | `0.84.2` |

**Установка из npm:**

```bash
pi install npm:@mazurovn/mazzy-command-center
# затем перезапустите Pi, чтобы он обнаружил расширение.
```

**Установка из GitHub:**

```bash
pi install git:github.com/mazurovn/Mazzy-Command-Center
```

**Проверка:**

```bash
npm run typecheck
npm test
```

В сессии Pi выполните `/mazzy` для статуса и URL дашборда или `/mazzy-url` для
получения аутентифицированного URL доступа (токен никогда не пишется в логи).

---

## Безопасность и ограничения

Это **аутентифицированный локальный пилот**, и его не следует воспринимать как
заявление о промышленной безопасности.

- Одна машина, один доверенный пользователь; границы процессов «родитель/потомок».
- Это **не** многопользовательская авторизация, **не** изоляция арендаторов,
  **не** удалённая идентификация и **не** распределённая блокировка писателя.
- Действие на дашборде, отправленный запрос управления или подтверждение родителя
  **не** являются доказательством исполнения или верификации.

О проблемах безопасности сообщайте по приватному каналу, а не в публичном трекере.

---

## Лицензия

**Открытый исходный код по [PolyForm Noncommercial License 1.0.0](LICENSE).**
Copyright (c) 2025 Mazurov N.N.

- ✅ **Свободно** использовать, изучать, изменять и распространять для любых
  **некоммерческих** целей — личное использование, наука и исследования, обучение.
- ⛔ **Никакого коммерческого использования.** Компаниям и коммерческим
  продуктам/сервисам нужна отдельная коммерческая лицензия. Коммерческие лицензии и отдельная редакция **Mazzy Command Center Enterprise**
  планируются / предоставляются по запросу.
- ⛔ Необходимо сохранять все указания автора/копирайта/лицензии; нельзя
  переименовывать ПО, убирать атрибуцию или выдавать изменённые версии под тем же
  именем («Mazzy Command Center» / «Mazzy») без письменного разрешения.

По вопросам коммерческой лицензии или использования сверх этих условий: https://github.com/mazurovn