@goodandready/dsh-moa 0.2.11 → 0.2.13

package/README.md

@@ -17,10 +17,20 @@
 
 <p align="center">
   <a href="README.md"><b>🇬🇧 English</b></a> •
-  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
-  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</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>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -143,8 +153,44 @@ Restart your DeepSeek Harness instance and refresh the browser.
 
 ---
 
+## ⚡ 10 Specialized Built-in Presets & Candidate Personas
+
+v0.2.13 introduces 10 ready-to-use presets engineered for real-world software workflows:
+
+| Preset Name | Purpose | Default Aggregator | Peer Critique | Blind Eval |
+| :--- | :--- | :--- | :---: | :---: |
+| `default` | Balanced multi-model generation | `codex:gpt-5.6-sol` | Optional | Off |
+| `code-review` | Thorough peer review & vulnerability detection | `codex:gpt-5.6-sol` | On | On |
+| `fast-audit` | Ultra-fast single-model audit (Fast Mode) | `codex:gpt-5.6-sol` | Off | Off |
+| `deep-architect` | Distributed systems & complex architectures | `codex:gpt-5.6-sol` | On | Off |
+| `bug-hunter` | Root cause discovery & adversarial edge cases | `codex:gpt-5.6-sol` | On | Off |
+| `refactor-cleanup` | Dead-code pruning & standard-library simplicity | `codex:gpt-5.6-sol` | Off | Off |
+| `frontend-ui` | High-fidelity responsive web interfaces | `codex:gpt-5.6-sol` | Off | Off |
+| `security-audit` | Zero-trust threat analysis & sanitization | `codex:gpt-5.6-sol` | On | On |
+| `math-logic` | Deterministic algorithmic proofs & math logic | `codex:gpt-5.6-sol` | On | Off |
+| `creative-brainstorm`| Divergent lateral thinking & ideation | `codex:gpt-5.6-sol` | Off | Off |
+
+### Candidate Personas (`role_persona`)
+Assign archetypal engineering mentalities to individual candidate slots to ensure genuine perspective divergence:
+- **`minimalist` (Ponytail Senior)**: standard library first, zero external dependencies, minimal moving parts.
+- **`robustness`**: defensive coding, boundary validation, graceful fallback handling, idempotent operations.
+- **`performance`**: algorithmic complexity minimization, memory efficiency, zero-copy operations.
+- **`tester`**: test-driven methodology, high branch coverage, explicit assertion design.
+- **`general`**: balanced standard engineering approach.
+
+---
+
+## 🤝 Consilium Round 2 (Peer Critique) & Syntax Auto-Fix Gate
+
+- **Consilium (Round 2)**: Enable `peer_critique_enabled: true` in preset settings. Each candidate receives peer proposals and submits an improved, hardened iteration before judge evaluation.
+- **Syntax Pre-Check Gate**: In-memory JS/MJS and JSON syntax verification runs automatically on all candidate files. If a proposal contains syntax errors, it is flagged with `[⚠️ Syntax Warning]` and the judge receives a strict mandate: *if this candidate has superior design, auto-correct the syntax in the synthesized deliverable and award them the win*.
+- **User Candidate Override**: Enable `allow_candidate_override: true` to preserve candidate sandboxes in `.moa/candidate-N/`. At any time, promote any candidate using `/moa promote <runId> <candidateIndex>` or the UI button.
+
+---
+
 ## ⚙️ Configuration (`settings.yaml`)
 
+
 Configure presets and model pipelines in `settings.yaml` or through the Web UI Settings panel (Settings → Plugins → Mixture of Agents):
 
 ```yaml
@@ -199,6 +245,7 @@ dsh-moa:
 | `presets[].quorum_enabled` | `boolean` | `false` | Straggler mitigation: proceed with synthesis once >= 60% candidates respond |
 | `presets[].grace_period_sec` | `number` | `10` | Grace period in seconds to wait for stragglers after quorum is reached |
 | `presets[].aggregator_fallbacks` | `array` | `[]` | Ordered fallback judge models tried if primary aggregator encounters transient errors |
+| `presets[].blind_evaluation` | `boolean` | `false` | Anonymize candidate model names for the judge/curator to eliminate family/brand bias |
 | `presets[].reference_timeout_sec` | `number` | `60` | Per-candidate execution timeout in seconds |
 | `presets[].aggregator_timeout_sec` | `number` | `180` | Aggregator/judge synthesis timeout in seconds |
 | `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | Sampling temperatures for proposers and judge |

package/README.ru.md

@@ -0,0 +1,287 @@
+# 📦 @goodandready/dsh-moa
+
+<div align="center">
+
+<h3>Движок мультимодельного взаимодействия и синтеза Mixture of Agents (MoA) для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-moa"><img src="https://img.shields.io/npm/v/@goodandready/dsh-moa.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-moa.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="Витрина GoodAndReady"></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>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+Генерация кода и архитектурных решений силами одной модели часто страдает от слепых зон, предвзятости одного подхода, галлюцинаций в структуре проекта и нестабильного качества на сложных инженерных задачах. При работе с неоднозначными требованиями одиночная модель нередко делает поспешные предположения и выдает монолитный, непроверенный результат.
+
+**`@goodandready/dsh-moa`** интегрирует архитектуру **Mixture of Agents (MoA)** прямо в DeepSeek Harness через слеш-команду `/moa`:
+
+1. **Адаптивный опросник для уточнения требований**: Если запрос пользователя сформулирован слишком широко или не содержит ключевых деталей, модели-советники формируют уточняющие варианты, а модель-судья синтезирует структурированный интерактивный опросник (2–4 вопроса) до начала генерации кода.
+2. **Параллельный опрос моделей (Proposers) и изоляция на диске**: Несколько независимых моделей анализируют задачу одновременно. Файлы каждого кандидата сохраняются в изолированные директории (`.moa/candidate-N/`), исключая конфликты.
+3. **Оценка флагманским судьей (Judge) и автоматический промоушн файлов**: Модель глубоких рассуждений проводит критический сравнительный анализ всех предложенных решений, выбирает победителя с помощью машинного маркера (`WINNER_CANDIDATE_INDEX: N`) и переносит готовые файлы победителя напрямую в корень проекта.
+4. **Экономия токенов в чате**: Вместо вывода огромных листингов кода в чат формируется компактный отчет с перечнем созданных файлов и архитектурным резюме.
+5. **Одноразовый модификатор сессии**: Команда выполняется в рамках одного такта и автоматически возвращает исходную модель сессии пользователя сразу после завершения.
+6. **Динамический каталог тарифов и подсчет токенов**: Актуальные цены на 300+ моделей автоматически подтягиваются из публичного каталога OpenRouter (без ключей и авторизации), кешируются в `~/.dsh/storages/dsh-moa-catalog.json` на 24 часа, а также поддерживают прямые вендорские тарифы и пользовательские оверрайды `prices` в `settings.yaml`.
+7. **Режим доработки (Refinement Mode)**: Автоматически считывает контекст существующего проекта и генерирует точечные дельта-правки без перетирания всей кодовой базы.
+8. **Быстрый режим (Fast Mode) и критерии судьи**: Режим для одиночных быстрых задач без судьи и гибкая настройка фокуса оценки (безопасность, производительность, минимализм).
+9. **История запусков и лидерборд моделей**: Персистентное логирование всех видов запусков (синтез, fast mode, опросник) и REST-эндпоинты (`/dsh-moa/history`, `/dsh-moa/leaderboard`, `/dsh-moa/runs/<id>`).
+10. **Live Canvas 1-клик предпросмотр (опционально)**: если в профиле установлен `@goodandready/dsh-live-canvas`, промоученный HTML отправляется в его песочницу, а ответ MoA содержит ссылку на предпросмотр в 1 клик; без плагина шаг тихо пропускается.
+
+---
+
+## 🏗️ Архитектура
+
+```mermaid
+graph TD
+    subgraph Input ["Взаимодействие с пользователем (Композер чата)"]
+        Cmd["Слеш-команда: /moa [preset] &lt;запрос&gt;"]
+        Gate{"Проверка неоднозначности"}
+        QModal["Интерактивные уточняющие вопросы<br/>(Выбор вариантов и текстовые ответы)"]
+    end
+
+    subgraph Proposers ["Слой параллельных советников (Proposers)"]
+        P1["Модель 1<br/>(Креативный подход)"]
+        P2["Модель 2<br/>(Альтернативный дизайн)"]
+        P3["Модель 3<br/>(Производительная стратегия)"]
+        WS1[".moa/candidate-1/<br/>(Изолированные файлы)"]
+        WS2[".moa/candidate-2/<br/>(Изолированные файлы)"]
+        WS3[".moa/candidate-3/<br/>(Изолированные файлы)"]
+    end
+
+    subgraph Judge ["Слой синтеза и промоушна (Judge)"]
+        Aggregator["Флагманская модель-судья<br/>(Сравнительный анализ и аудит кода)"]
+        WinnerMarker{"WINNER_CANDIDATE_INDEX"}
+        Promote["Промоушн файлов победителя<br/>(Перенос в корень и очистка песочниц)"]
+        Summary["Компактный отчет<br/>(Обзор файлов и архитектурное резюме)"]
+    end
+
+    Cmd --> Gate
+    Gate -->|Широкий/Неточный запрос| QModal
+    QModal -->|Ответы пользователя| P1 & P2 & P3
+    Gate -->|Точный/Детальный запрос| P1 & P2 & P3
+    P1 --> WS1
+    P2 --> WS2
+    P3 --> WS3
+    WS1 & WS2 & WS3 --> Aggregator
+    Aggregator --> WinnerMarker
+    WinnerMarker --> Promote
+    Promote --> Summary
+```
+
+---
+
+## ✨ Возможности и функциональность
+
+### 1. Слеш-команда (`/moa`) и автодополнение
+Плагин интегрируется напрямую в композер DeepSeek Harness. Ввод `/moa` открывает всплывающее меню с готовыми пресетами и автодополнением:
+
+```text
+/moa разработай реактивный дашборд с графиками и обновлениями по websocket
+```
+
+Или вызов именованного пресета:
+
+```text
+/moa code-review проведи аудит middleware авторизации и границ безопасности
+```
+
+Эквивалентная форма с флагом:
+
+```text
+/moa --preset=deep-reasoning реши эту математическую задачу по шагам
+```
+
+### 2. Адаптивный гейт уточнения требований
+Когда запрос сформулирован слишком обобщенно (например, *"сделай калькулятор"*), советники определяют недостающие архитектурные требования и формулируют целевые вопросы (стиль интерфейса, сохранение состояния, стек технологий) до генерации кода.
+
+### 3. Параллельный запуск с живыми пульсами прогресса
+* Советники опрашиваются параллельно со статусами выполнения в реальном времени (`⏳ [3s] Processing...`, индивидуальный прогресс каждой модели).
+* Из контекстов советников удаляются громоздкие системные промпты и схемы инструментов, что предотвращает ошибки отказа из-за отсутствия инструментов и экономит контекст.
+
+### 4. Файловая изоляция кандидатов и промоушн
+В отличие от обычных чатовых реализаций MoA, `dsh-moa` работает с реальной файловой системой:
+* Каждый советник генерирует файлы в изолированные папки `.moa/candidate-1/`, `.moa/candidate-2/` и т.д.
+* Судья сопоставляет реализации и выбирает лучшую через маркер `WINNER_CANDIDATE_INDEX: N`.
+* Файлы победителя автоматически переносятся в корень рабочей области, а временные папки удаляются.
+
+### 5. Нативная карточка настроек и пресеты
+Настройка моделей в меню `Настройки → Плагины → Mixture of Agents`:
+* Выбор моделей-советников (быстрые генеративные модели для разнообразия идей).
+* Выбор модели-судьи (модель глубоких рассуждений для строгого аудита).
+* Конфигурация именованных пресетов (`default`, `fast`, `deep-reasoning`), критериев судьи и температур.
+* Включение/отключение MoA и фактический статус-бейдж хоста; сетка телеметрии показывает общее число запусков и среднюю стоимость.
+
+### 6. Live Canvas 1-клик предпросмотр (опционально)
+Если в профиле установлен `@goodandready/dsh-live-canvas`, `dsh-moa` отправляет промоученный HTML-файл в REST-контракт Live Canvas (`POST /dsh-live-canvas/api/preview`, тот же webServer харнесса) и добавляет к ответу ссылку на предпросмотр (`/dsh-live-canvas/sandbox/<id>`). Без плагина шаг пропускается тихо — без ошибок в журнале и без битых ссылок.
+
+---
+
+## 📦 Установка
+
+Установка в веб-профиль DeepSeek Harness:
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-moa
+```
+
+Перезапустите экземпляр DeepSeek Harness и обновите вкладку в браузере.
+
+---
+
+## ⚡ 10 встроенных пресетов и инженерные персоны
+
+В версии v0.2.13 добавлены 10 специализированных пресетов под реальные задачи разработки:
+
+| Имя пресета | Назначение | Судья по умолчанию | Рецензия (Round 2) | Слепая оценка |
+| :--- | :--- | :--- | :---: | :---: |
+| `default` | Сбалансированная генерация | `codex:gpt-5.6-sol` | Опционально | Выкл |
+| `code-review` | Глубокое взаимное ревью кода | `codex:gpt-5.6-sol` | Вкл | Вкл |
+| `fast-audit` | Сверхбыстрый экспресс-аудит (Fast Mode) | `codex:gpt-5.6-sol` | Выкл | Выкл |
+| `deep-architect` | Проектирование распределенных систем | `codex:gpt-5.6-sol` | Вкл | Выкл |
+| `bug-hunter` | Поиск скрытых багов и граничных случаев | `codex:gpt-5.6-sol` | Вкл | Выкл |
+| `refactor-cleanup` | Чистка легаси и удаление оверинжиниринга | `codex:gpt-5.6-sol` | Выкл | Выкл |
+| `frontend-ui` | Качественные адаптивные веб-интерфейсы | `codex:gpt-5.6-sol` | Выкл | Выкл |
+| `security-audit` | Анализ уязвимостей и санитайзинг | `codex:gpt-5.6-sol` | Вкл | Вкл |
+| `math-logic` | Алгоритмы, математическая логика и доказательства | `codex:gpt-5.6-sol` | Вкл | Выкл |
+| `creative-brainstorm`| Нестандартные идеи и дивергентный поиск | `codex:gpt-5.6-sol` | Выкл | Выкл |
+
+### Инженерные персоны кандидатов (`role_persona`)
+Задавайте кандидатам четкие роли для максимального разнообразия подходов:
+- **`minimalist` (Ponytail)**: решение на стандартной библиотеке, 0 лишних зависимостей, минимальный код.
+- **`robustness`**: защитное программирование, валидация границ, идемпотентность, устойчивость к сбоям.
+- **`performance`**: минимальная алгоритмическая сложность, экономия памяти, zero-copy.
+- **`tester`**: test-driven архитектура, 100% покрытие веток, четкие ассерты.
+- **`general`**: сбалансированный подход общего назначения.
+
+---
+
+## 🤝 Консилиум Раунд 2, Синтаксический гейт и Override
+
+- **Консилиум (Раунд 2)**: флаг `peer_critique_enabled: true` включает этап взаимного ревью, в котором кандидаты изучают предложения оппонентов и дорабатывают код перед финальным судейством.
+- **Синтаксический гейт**: мгновенная валидация JS/JSON через `node:vm` и `JSON.parse`. Если в коде кандидата есть опечатка, он помечается `[⚠️ Syntax Warning]`, а судья получает жесткую директиву: *если архитектура кандидата превосходит конкурентов, исправить синтаксис в финальном решении и присудить ему победу*.
+- **Пользовательский выбор кандидата (Override)**: флаг `allow_candidate_override: true` сохраняет папки `.moa/candidate-N/`. Любой кандидат может быть повышен в проект командой `/moa promote <runId> <candidateIndex>` или кнопкой в карточке настроек.
+
+---
+
+## ⚙️ Конфигурация (`settings.yaml`)
+
+
+Настройка пресетов и пайплайнов моделей доступна в `settings.yaml` или через интерфейс (Настройки → Плагины → Mixture of Agents):
+
+```yaml
+# settings.yaml
+dsh-moa:
+  enabled: true
+  default_preset: "default"
+  prices:
+    "my-provider/my-model":
+      input: 0.20
+      output: 0.80
+    "ollama/*":
+      input: 0
+      output: 0
+  presets:
+    - name: default
+      ask_clarifying_questions: true
+      reference_models:
+        - provider: "your-fast-provider"
+          model: "your-creative-model"
+        - provider: "your-fast-provider"
+          model: "your-balanced-model"
+      aggregator:
+        provider: "your-reasoning-provider"
+        model: "your-judge-model"
+      reference_temperature: 0.6
+      aggregator_temperature: 0.4
+      max_tokens: 4096
+      judge_criteria: ""
+    - name: fast
+      ask_clarifying_questions: false
+      reference_models:
+        - provider: "your-fast-provider"
+          model: "your-fast-model"
+      aggregator:
+        provider: "your-fast-provider"
+        model: "your-fast-model"
+```
+
+### Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `enabled` | `boolean` | `true` | Главный выключатель команды `/moa`, маршрутизации тактов и `POST /dsh-moa/run` (редактируется в карточке настроек) |
+| `default_preset` | `string` | `"default"` | Пресет по умолчанию, вызываемый командой `/moa <запрос>` без явного пресета |
+| `presets` | `array` | `[...]` | Именованные пресеты; выбираются через `/moa <имя> <запрос>` или `/moa --preset=<имя> <запрос>` |
+| `presets[].reference_models` | `array` | `[...]` | Список моделей-советников, опрашиваемых параллельно |
+| `presets[].aggregator` | `object` | `{...}` | Модель-судья, отвечающая за синтез, критику и выбор победителя |
+| `presets[].ask_clarifying_questions` | `boolean` | `true` | Синтез опросника для широких/неоднозначных запросов (на уровне пресета) |
+| `presets[].curator_synthesis` | `boolean` | `false` | Режим куратора: извлечение сильных сторон решений по рубрике антипаттернов и выбор ведущей модели-сборщика |
+| `presets[].stream_aggregator` | `boolean` | `true` | Потоковый стриминг ответа судьи в реальном времени с нулевым временем первого токена (TTFT) |
+| `presets[].quorum_enabled` | `boolean` | `false` | Защита от зависших моделей (stragglers): запуск синтеза при ответе от >= 60% кандидатов |
+| `presets[].grace_period_sec` | `number` | `10` | Грейс-период (в секундах) ожидания оставшихся моделей после достижения кворума |
+| `presets[].aggregator_fallbacks` | `array` | `[]` | Список запасных моделей-судей при сбоях основной модели агрегатора |
+| `presets[].blind_evaluation` | `boolean` | `false` | Обезличивание имен кандидатов («Candidate 1», «Candidate 2») для исключения предвзятости судьи |
+| `presets[].reference_timeout_sec` | `number` | `60` | Таймаут опроса каждого кандидата в секундах |
+| `presets[].aggregator_timeout_sec` | `number` | `180` | Таймаут синтеза решения судьей в секундах |
+| `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | Температуры сэмплирования советников и судьи |
+| `presets[].max_tokens` | `number` | `4096` | Максимум выходных токенов на вызов модели |
+| `presets[].judge_criteria` | `string` | `""` | Опциональные дополнительные критерии оценки для судьи |
+| `prices` | `map` | `{}` | Пользовательские тарифы USD за 1M токенов (`"provider/model"`, `"provider/*"`, `"*"`) для расчета стоимости |
+
+> **Примечание о приватности:** в режиме доработки читаемые файлы проекта (до ~16 тыс. символов; dotfile-файлы вида `.env*` исключены) включаются в промпты, отправляемые настроенным моделям-кандидатам и судье. Не запускайте `/moa` в проектах, где не-dotfile файлы содержат секреты.
+
+---
+
+## 📊 REST API эндпоинты
+
+| Эндпоинт | Метод | Описание |
+|:---|:---|:---|
+| `/dsh-moa/status` | `GET` | Снимок здоровья/включенности для статус-бейджа карточки настроек |
+| `/dsh-moa/presets` | `GET` | Возвращает настроенные пресеты MoA и пресет по умолчанию |
+| `/dsh-moa/presets` | `POST` | Заменяет пресеты/пресет по умолчанию/enabled после валидации схемой (400 при невалидном payload) |
+| `/dsh-moa/models` | `GET` | Список моделей, доступных для слотов кандидатов и судьи |
+| `/dsh-moa/history?limit=20&offset=0` | `GET` | История запусков с кандидатами, победителем, токенами и ценой |
+| `/dsh-moa/leaderboard` | `GET` | Лидерборд побед моделей и средняя стоимость генерации |
+| `/dsh-moa/runs/<id>` | `GET` | Возвращает один записанный запуск по id |
+| `/dsh-moa/run` | `POST` | Запускает полный пайплайн MoA по HTTP (400 при `enabled: false`) |
+
+---
+
+## 🧪 Тестирование
+
+Запуск автоматического набора тестов:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,243 @@
+# 📦 @goodandready/dsh-moa
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的 Mixture of Agents (MoA) 多模型协作与代码综合引擎</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-moa"><img src="https://img.shields.io/npm/v/@goodandready/dsh-moa.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-moa.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="GoodAndReady 作品展"></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 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
+      <br><br>
+      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
+## ⚡ 概述与解决的核心痛点
+
+在面对复杂的软件工程任务时，单一模型生成往往容易受到视角盲区、架构幻觉以及生成质量不稳定的限制。当用户输入模糊或缺乏技术细节的提示词时，单一模型容易做出主观假设，生成未经充分验证的单体代码。
+
+**`@goodandready/dsh-moa`** 通过 `/moa` 斜杠命令将 **Mixture of Agents (MoA)** 混合智能体架构原生引入 DeepSeek Harness：
+
+1. **自适应澄清问卷 (Questionnaire Gate)**：针对宽泛或不明确的提示词，顾问模型（Proposers）自动提炼关键分歧点，裁判模型（Judge）在生成代码前合成结构化的 2–4 题交互式问卷。
+2. **多模型并行生成与工作区沙箱隔离**：多个独立模型并行分析任务。每个候选方案的文件生成均写入独立的磁盘沙箱 (`.moa/candidate-N/`)，彻底避免跨模型文件污染。
+3. **旗舰裁判模型评估与文件自动提升 (Promotion)**：深度推理模型对所有候选方案进行交叉评审，通过机器标记 (`WINNER_CANDIDATE_INDEX: N`) 评选胜出方案，并将胜出者的完整文件自动同步到项目根目录。
+4. **极简对话摘要与 Token 节省**：对话界面不输出冗长的原始代码块，而是生成整洁的文件清单与架构设计摘要。
+5. **单轮会话即时恢复**：作为一次性会话修改器运行，任务完成后自动恢复用户原本的会话主力模型。
+6. **动态定价目录与 Token 成本估算**：300+ 模型的实时价格自动从 OpenRouter 公开目录后台获取（无需鉴权，缓存于 `~/.dsh/storages/dsh-moa-catalog.json`，24 小时刷新），同时支持直连厂商价格与 `settings.yaml` 中的自定义 `prices` 覆盖。
+7. **增量修改模式 (Refinement Mode)**：自动感知现有代码库上下文，生成精确的增量修改而非破坏性的整文件重写。
+8. **快速模式与自定义评审标准**：面向快速任务的单模型极简管线，以及可自定义的裁判评审准则。
+9. **运行历史与胜率排行榜**：对每一类运行（综合、快速模式、问卷）进行持久化记录，并内置 REST 端点（`/dsh-moa/history`、`/dsh-moa/leaderboard`、`/dsh-moa/runs/<id>`）。
+10. **Live Canvas 一键预览（可选）**：当同一 profile 中安装了 `@goodandready/dsh-live-canvas` 时，提升到项目根目录的 HTML 会被推入其沙箱，MoA 回答附带一键预览链接；未安装时该步骤静默跳过。
+
+---
+
+## 🏗️ 架构图
+
+```mermaid
+graph TD
+    subgraph Input ["用户交互 (聊天输入框)"]
+        Cmd["斜杠命令: /moa [preset] &lt;prompt&gt;"]
+        Gate{"模糊需求判断"}
+        QModal["交互式澄清问卷<br/>(多选选项与自定义输入)"]
+    end
+
+    subgraph Proposers ["并行顾问模型层 (Proposers)"]
+        P1["提案模型 1<br/>(创新方案)"]
+        P2["提案模型 2<br/>(替代架构)"]
+        P3["提案模型 3<br/>(高性能策略)"]
+        WS1[".moa/candidate-1/<br/>(隔离文件)"]
+        WS2[".moa/candidate-2/<br/>(隔离文件)"]
+        WS3[".moa/candidate-3/<br/>(隔离文件)"]
+    end
+
+    subgraph Judge ["综合评估与提升层 (Judge)"]
+        Aggregator["旗舰裁判模型<br/>(交叉对比与代码审查)"]
+        WinnerMarker{"WINNER_CANDIDATE_INDEX"}
+        Promote["提升胜出者文件<br/>(移至根目录并清理沙箱)"]
+        Summary["紧凑型摘要<br/>(文件清单与架构亮点)"]
+    end
+
+    Cmd --> Gate
+    Gate -->|需求宽泛/模糊| QModal
+    QModal -->|用户确认选项| P1 & P2 & P3
+    Gate -->|需求明确/详尽| P1 & P2 & P3
+    P1 --> WS1
+    P2 --> WS2
+    P3 --> WS3
+    WS1 & WS2 & WS3 --> Aggregator
+    Aggregator --> WinnerMarker
+    WinnerMarker --> Promote
+    Promote --> Summary
+```
+
+---
+
+## ✨ 特性与能力
+
+### 1. 斜杠命令 (`/moa`) 与实时补全
+深度集成于 DeepSeek Harness 输入框。输入 `/moa` 即可触发预设菜单与自动补全：
+
+```text
+/moa 开发一个包含图表与 WebSocket 实时更新的响应式仪表盘
+```
+
+或指定命名预设：
+
+```text
+/moa code-review 审查身份验证中间件和安全边界
+```
+
+等效的 flag 形式：
+
+```text
+/moa --preset=deep-reasoning 逐步求解这道数学题
+```
+
+### 2. 自适应澄清问卷
+当需求过于抽象（例如 *"制作一个计算器"*）时，系统会在生成代码前主动询问 UI 风格、数据持久化方式或框架偏好。
+
+### 3. 并行调用与实时心跳反馈
+* 多个顾问模型并发执行，并伴随实时心跳进度条 (`⏳ [3s] Processing...`，显示各模型独立进度)。
+* 自动清理顾问上下文中的冗余系统提示词与工具定义，消除“缺少工具”的拒绝报错并大幅节约 Token。
+
+### 4. 磁盘级沙箱隔离与胜出者提升
+与仅停留在聊天文本层面的 MoA 不同，`dsh-moa` 针对真实工程项目：
+* 各提案模型在 `.moa/candidate-1/`、`.moa/candidate-2/` 等独立目录生成工程代码。
+* 裁判模型对比各版本实现，通过 `WINNER_CANDIDATE_INDEX: N` 指定最优方案。
+* 胜出方案自动提升至项目根目录，临时沙箱随后自动清理。
+
+### 5. 原生设置卡片与预设管理
+在 `设置 → 插件 → Mixture of Agents` 中可视化配置模型：
+* 配置顾问模型列表（快速生成多样化构想）。
+* 配置裁判模型（强推理模型进行严谨审查）。
+* 自定义命名预设 (`default`, `fast`, `deep-reasoning`)、裁判评审准则与温度。
+* 启用/停用 MoA 开关并查看真实的主机状态徽章；遥测网格展示总运行次数与平均运行成本。
+
+### 6. Live Canvas 一键预览（可选）
+若同一 profile 中安装了 `@goodandready/dsh-live-canvas`，`dsh-moa` 会将提升后的 HTML 文件推送到 Live Canvas 的 REST 契约（`POST /dsh-live-canvas/api/preview`，由同一 harness webServer 提供服务），并在回答中附上一键预览链接（`/dsh-live-canvas/sandbox/<id>`）。未安装该插件时此步骤静默跳过——日志无报错，也不会出现死链接。
+
+---
+
+## 📦 安装
+
+在 DeepSeek Harness Web 配置文件中安装：
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-moa
+```
+
+重启 DeepSeek Harness 实例并刷新浏览器页面。
+
+---
+
+## ⚙️ 配置 (`settings.yaml`)
+
+可在 `settings.yaml` 中配置预设与模型管道，或通过 Web UI 设置面板（设置 → 插件 → Mixture of Agents）进行调整：
+
+```yaml
+# settings.yaml
+dsh-moa:
+  enabled: true
+  default_preset: "default"
+  prices:
+    "my-provider/my-model":
+      input: 0.20
+      output: 0.80
+    "ollama/*":
+      input: 0
+      output: 0
+  presets:
+    - name: default
+      ask_clarifying_questions: true
+      reference_models:
+        - provider: "your-fast-provider"
+          model: "your-creative-model"
+        - provider: "your-fast-provider"
+          model: "your-balanced-model"
+      aggregator:
+        provider: "your-reasoning-provider"
+        model: "your-judge-model"
+      reference_temperature: 0.6
+      aggregator_temperature: 0.4
+      max_tokens: 4096
+      judge_criteria: ""
+    - name: fast
+      ask_clarifying_questions: false
+      reference_models:
+        - provider: "your-fast-provider"
+          model: "your-fast-model"
+      aggregator:
+        provider: "your-fast-provider"
+        model: "your-fast-model"
+```
+
+### 配置项说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `enabled` | `boolean` | `true` | `/moa` 命令、回合路由与 `POST /dsh-moa/run` 的总开关（可在设置卡片中切换） |
+| `default_preset` | `string` | `"default"` | 输入 `/moa <prompt>` 且未显式指定预设时调用的预设 |
+| `presets` | `array` | `[...]` | 命名预设列表；通过 `/moa <name> <prompt>` 或 `/moa --preset=<name> <prompt>` 选择 |
+| `presets[].reference_models` | `array` | `[...]` | 并行提案阶段并发调用的顾问模型列表 |
+| `presets[].aggregator` | `object` | `{...}` | 负责综合评审、代码审查与裁决胜出者的裁判模型 |
+| `presets[].ask_clarifying_questions` | `boolean` | `true` | 针对宽泛需求合成澄清问卷（预设级别开关） |
+| `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | 顾问与裁判的采样温度 |
+| `presets[].max_tokens` | `number` | `4096` | 每次模型调用的最大输出 Token 数 |
+| `presets[].judge_criteria` | `string` | `""` | 传给裁判的可选附加评审准则 |
+| `prices` | `map` | `{}` | 自定义美元/百万 Token 费率（`"provider/model"`、`"provider/*"`、`"*"`），用于成本估算 |
+
+> **隐私提示：** 在增量修改模式下，可读的项目文件（最多约 1.6 万字符；`.env*` 等点文件已被排除）会随提示词发送给所配置的候选模型与裁判模型。请勿在非点文件中包含密钥的项目里运行 `/moa`。
+
+---
+
+## 📊 REST API 端点
+
+| 端点 | 方法 | 说明 |
+|:---|:---|:---|
+| `/dsh-moa/status` | `GET` | 供设置卡片状态徽章使用的健康/启用状态快照 |
+| `/dsh-moa/presets` | `GET` | 返回已配置的 MoA 预设与默认预设 |
+| `/dsh-moa/presets` | `POST` | 经 schema 校验后替换预设/默认预设/enabled（非法载荷返回 400） |
+| `/dsh-moa/models` | `GET` | 列出可用于候选/裁判槽位的模型 |
+| `/dsh-moa/history?limit=20&offset=0` | `GET` | 返回近期运行记录（含候选、胜出者、Token 与成本） |
+| `/dsh-moa/leaderboard` | `GET` | 计算模型胜率排行榜与平均执行成本 |
+| `/dsh-moa/runs/<id>` | `GET` | 按 id 返回单条运行记录 |
+| `/dsh-moa/run` | `POST` | 通过 HTTP 运行完整 MoA 管线（`enabled: false` 时返回 400） |
+
+---
+
+## 🧪 测试
+
+运行自动化测试套件：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)