# 📦 @goodandready/dsh-agent-orchestrator

<div align="center">

<h3>Мульти-агентная декомпозиция задач, DAG-оркестрация и оптимизатор Prompt Caching для DeepSeek Harness</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/@goodandready/dsh-agent-orchestrator"><img src="https://img.shields.io/npm/v/@goodandready/dsh-agent-orchestrator.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-agent-orchestrator.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
</p>

<p align="center">
  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
</p>

<p align="center">
  <a href="README.md"><b>🇬🇧 English</b></a> •
  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
</p>

<table align="center">
  <tr>
    <td align="center">
      ⭐ <strong>Если вам понравился этот плагин, поставьте звезду на GitHub</strong> — это показывает востребованность разработки и мотивирует развивать проект дальше.
      <br><br>
      🐛 <strong>Если вы нашли ошибку или хотите предложить улучшение</strong>, откройте issue на GitHub на любом удобном языке — предложения рассматриваются для будущих версий.
    </td>
  </tr>
</table>

</div>

---

## ⚡ Обзор и решаемая проблема

При выполнении комплексных многоэтапных проектов один агент неизбежно сталкивается с перегрузкой контекста: в один монолитный запрос смешиваются архитектура, дизайн, верстка, бэкенд, тестирование и написание документации. Это приводит к галлюцинациям, нарушению контрактов и неоправданным затратам токенов.

Кроме того, запуск независимых субагентов обычно сбрасывает KV-кэш языковой модели на каждом шаге, теряя преимущества префиксного кэширования (Prompt Caching) и приводя к долгим задержкам ответа.

**`@goodandready/dsh-agent-orchestrator`** внедряет автономную мульти-агентную оркестрацию в DeepSeek Harness:

1. **Триаж и декомпозиция**: Анализирует задачу из чата или карточки Канбана и разбивает её на этапы между **12 специализированными ролями агентов**.
2. **Графовый DAG-движок**: Планирует задачи на основе направленного ациклического графа, исполняя независимые ветки параллельно и контролируя блокеры.
3. **Оптимизатор Prompt Caching (KV-кэш)**: Гарантирует побайтовое совпадение префикса для агентов с одинаковыми моделями, обеспечивая 80–90% Cache Hit и моментальный старт генерации.
4. **Строгое разделение труда**: Бэкенд, UI-дизайн и клиентский фронтенд строго изолированы по разным ролям и этапам.
5. **Два режима работы**: Через команду `/orchestrate` в чате DSH (с плавающей карточкой прогресса в шапке) или через доску задач `@goodandready/dsh-kanban`.

---

## 🏗️ Архитектура

```mermaid
graph TD
    Trigger["Входная задача<br/>(/orchestrate в чате или карточка Канбана)"] --> Main["Главный оркестратор (Триаж)"]
    
    subgraph Engine ["Движок DAG и Prompt Caching"]
        L1["Уровень 1: Канонический базовый якорь (>1024 токенов)"]
        L2["Уровень 2: Общий якорь задачи"]
        L3["Уровень 3: Накопленные артефакты (Append-Only)"]
        L4["Уровень 4: Суффиксная директива роли"]
    end

    Main --> Engine

    subgraph AgentPool ["Настроенные персоны агентов (Автономно в настройках)"]
        R1["ТЗ-аналитик"]
        R2["Системный архитектор"]
        R3["UI/UX Дизайнер"]
        R4["Бэкенд-разработчик"]
        R5["Фронтенд-разработчик"]
        R6["QA Automation инженер"]
        R7["Технический писатель"]
    end

    Engine --> AgentPool
    AgentPool --> Delivery["Поставка результата<br/>(Карточка в шапке и синхронизация с Канбаном)"]
```

---

## 👥 12 встроенных специализированных ролей агентов

Все профили агентов **хранятся и настраиваются исключительно внутри настроек плагина** (без внешних файлов):

| Код роли | Название | Специализация | Жёсткие границы |
|---|---|---|---|
| `spec` | ТЗ-аналитик | Требования, критерии приёмки (DoD), структуры данных | Не пишет код реализации и стили |
| `architecture` | Системный архитектор | Системный дизайн, DESIGN.md, ADR, модульные контракты | Не реализует прод-код и не деплоит |
| `ui_design` | UI/UX Дизайнер | Макеты, токены темы (`--dsw-alias-*`), слоты | Не пишет серверные сервисы Cordis |
| `frontend` | Фронтенд-разработчик | React-компоненты, хуки клиента, DOM-события | Не меняет бэкенд-роуты и схемы БД |
| `backend` | Бэкенд-разработчик | Сервисы Cordis, WebServer-роуты, хранилище | Не пишет клиентский React JSX и CSS |
| `fullstack` | Фуллстек-интегратор | Связка клиент-серверного контракта, сквозной поток | Строго следует границам модулей |
| `qa_tests` | QA Automation инженер | Модульные тесты (`node:test`), проверка границ | Тестирует без внешних сетевых вызовов |
| `bugfix` | Hotfix-инженер | Поиск первопричины, минимальный точечный фикс | Не рефакторит несвязанный код |
| `docs` | Технический писатель | Трёхъязычная документация (en/ru/zh), релизы | Не перезаписывает прежнюю документацию |
| `refactoring` | Рефакторинг-специалист | Устранение оверинжиниринга (YAGNI), сжатие бандла | Сохраняет обратную совместимость |
| `research` | Исследователь (Spike) | Сравнение библиотек, архитектурные пробы | Готовит отчёт, не мержит спайк-код |
| `devops` | DevOps-инженер | Манифесты пакетов, валидация сборки, systemd | Не раскрывает приватные учетные данные |

---

## 🔄 Сценарии сложности

1. **Hotfix / Минорный (1 этап)**: Точечное устранение дефекта или правка одного параметра.
2. **Простой (2 этапа)**: Обсуждение и ТЗ $
ightarrow$ Целевая реализация.
3. **Средний (3–4 этапа)**: ТЗ $
ightarrow$ UI-дизайн $
ightarrow$ Фронтенд $
ightarrow$ QA-тесты.
4. **Комплексный (5–6 этапов)**: ТЗ $
ightarrow$ Архитектура $
ightarrow$ UI-дизайн $
ightarrow$ Реализация $
ightarrow$ QA $
ightarrow$ Трёхъязычная документация.
5. **Корпоративный / Enterprise (7 этапов)**: Исследовательский спайк $
ightarrow$ ТЗ $
ightarrow$ Архитектура $
ightarrow$ Параллельная разработка бэкенда и UI-дизайна $
ightarrow$ Сборка фронтенда $
ightarrow$ Полное QA-тестирование $
ightarrow$ Контроль документации.
6. **Пользовательские DAG-сценарии**: Полностью настраиваются в параметрах плагина с произвольными этапами и чекбоксами блокировок.

---

## ⚡ Механика Prompt Caching

Современные LLM кэшируют KV-состояния строго от первого токена вперёд. Случайные временные метки или ID в шапке промпта сбрасывают Cache Hit до 0%.

`dsh-agent-orchestrator` обеспечивает **4-слойную каноническую структуру**:
1. **Уровень 1: Статический базовый якорь (>1024 токенов)**: Побайтово идентичные правила и инструменты, общие для всех агентов.
2. **Уровень 2: Общий якорь задачи**: Стабильное описание цели пользователя и целевого репозитория.
3. **Уровень 3: Накопленный контекст (Append-Only)**: Результаты предыдущих этапов дописываются строго в конец, сохраняя 100% предыдущего KV-кэша.
4. **Уровень 4: Директива роли (Суффикс)**: Промпт роли, специализированные инструкции и локальный скоуп этапа.

Такая архитектура даёт **80–95% попаданий в кэш** между субагентами на одной модели, снижая TTFT и сокращая затраты на токены на ~90%.

---

## 💻 Использование

### 1. В чате DSH через слэш-команду
```text
/orchestrate Спроектируй и разработай карточку настроек для плагина финансов
```

Явный выбор сценария сложности:
```text
/orchestrate complex Разработай провайдер мультитенантной аутентификации
/orchestrate hotfix Исправь обращение к null в store.js
```

Короткий алиас:
```text
/orc Рефакторинг управления состоянием
```

### 2. В @goodandready/dsh-kanban
- Открой любую карточку задачи на доске.
- Нажми **[Собрать пайплайн]**.
- Выбери пресет сложности или оставь авто-триаж.
- Карточка отображает переходы между этапами и автоматически переводится в `Review` по готовности.

---

## 🧪 Верификация и тестирование

Запуск нативного набора тестов (121 тест без внешних сетевых зависимостей):

```bash
node --test test/*.test.mjs
```

Проверка размера бандла перед публикацией (<256 КБ):

```bash
npm pack --dry-run --json
```

---

## 🖼️ Визуальная верификация

Приёмка v0.1.6 в окружении DSH — карточка настроек, темная и светлая темы:

![dsh-agent-orchestrator v0.1.6 visual verification](media/visual-verification.png)

---

## 📄 Лицензия

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)