@goodandready/dsh-moa 0.2.8 → 0.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +64 -37
  2. package/docs/README.ru.md +64 -37
  3. package/docs/README.zh.md +70 -27
  4. package/docs/design/DESIGN.md +43 -41
  5. package/docs/plans/47-client-js-split-plan.md +57 -0
  6. package/lib/client.js +666 -465
  7. package/lib/file-workspace.js +3 -1
  8. package/lib/history.js +4 -1
  9. package/lib/index.js +66 -12
  10. package/lib/live-canvas.js +34 -0
  11. package/lib/moa-runner.js +665 -351
  12. package/lib/pricing.js +17 -3
  13. package/package.json +1 -1
package/README.md CHANGED
@@ -34,13 +34,13 @@ Single-model AI generation often suffers from blind spots, single-perspective bi
34
34
  1. **Adaptive Clarification Questionnaire**: For broad or underspecified prompts, advisor models formulate clarifying options and the judge synthesizes a structured 2–4 question questionnaire before generating code.
35
35
  2. **Parallel Proposers Fan-Out & Workspace Isolation**: Multiple independent models evaluate the prompt concurrently. Each candidate's proposed files are written to isolated disk sandboxes (`.moa/candidate-N/`), avoiding cross-pollution.
36
36
  3. **Frontier Judge Evaluation & File Promotion**: A flagship reasoning model critically benchmarks all proposals, selects the winning candidate via machine markers (`WINNER_CANDIDATE_INDEX: N`), and promotes the winner's files directly into the project root directory.
37
- 4. **Instant Live Canvas Previewing**: When web applications or UI components are generated, `dsh-moa` integrates seamlessly with `@goodandready/dsh-live-canvas`, automatically spawning sandboxes for 1-click browser previewing.
38
- 5. **Token-Saving Chat Summarization**: Replaces massive code dumps in chat bubbles with compact file listings and clean architectural summaries.
39
- 6. **One-Shot Session Model Restoration**: Executes cleanly as a one-shot turn modifier, automatically reverting back to the user's primary session model immediately after completion.
40
- 7. **Dynamic Model Pricing Catalog & Token Estimation**: Real-time rate resolution for 300+ models fetched automatically in the background from OpenRouter's public catalog (cached locally in `~/.dsh/storages/dsh-moa-catalog.json` for 24h), plus support for direct vendor rates and custom `prices` overrides in `settings.yaml`.
41
- 8. **Refinement Mode (Incremental Edits)**: Automatically detects existing codebase context to generate precise delta modifications instead of destructive full-file rewrites.
42
- 9. **Fast Mode & Custom Judge Criteria**: Ultra-fast single-model preset for quick tasks and customizable evaluation guidelines for the judge.
43
- 10. **Run History & Win-Rate Leaderboard**: Persistent logging with built-in REST endpoints (`/dsh-moa/history` and `/dsh-moa/leaderboard`).
37
+ 4. **Token-Saving Chat Summarization**: Replaces massive code dumps in chat bubbles with compact file listings and clean architectural summaries.
38
+ 5. **One-Shot Session Model Restoration**: Executes cleanly as a one-shot turn modifier, automatically reverting back to the user's primary session model immediately after completion.
39
+ 6. **Dynamic Model Pricing Catalog & Token Estimation**: Real-time rate resolution for 300+ models fetched automatically in the background from OpenRouter's public catalog (cached locally in `~/.dsh/storages/dsh-moa-catalog.json` for 24h), plus support for direct vendor rates and custom `prices` overrides in `settings.yaml`.
40
+ 7. **Refinement Mode (Incremental Edits)**: Automatically detects existing codebase context to generate precise delta modifications instead of destructive full-file rewrites.
41
+ 8. **Fast Mode & Custom Judge Criteria**: Ultra-fast single-model preset for quick tasks and customizable evaluation guidelines for the judge.
42
+ 9. **Run History & Win-Rate Leaderboard**: Persistent logging of every run kind (synthesis, fast mode, questionnaire) with built-in REST endpoints (`/dsh-moa/history`, `/dsh-moa/leaderboard`, `/dsh-moa/runs/<id>`).
43
+ 10. **Live Canvas 1-Click Preview (optional)**: when the `@goodandready/dsh-live-canvas` plugin is installed in the same profile, the promoted HTML is pushed to its sandbox and the MoA answer carries a one-click preview link; without it the step is skipped silently.
44
44
 
45
45
  ---
46
46
 
@@ -67,7 +67,6 @@ graph TD
67
67
  Aggregator["Frontier Judge Model<br/>(Cross-Evaluation & Code Critique)"]
68
68
  WinnerMarker{"WINNER_CANDIDATE_INDEX"}
69
69
  Promote["Promote Winner Files<br/>(Move to project root & cleanup sandboxes)"]
70
- LiveCanvas["Live Canvas Integration<br/>(Auto-open Web UI sandbox)"]
71
70
  Summary["Token-Saving Summary<br/>(File overview & architecture highlights)"]
72
71
  end
73
72
 
@@ -81,7 +80,6 @@ graph TD
81
80
  WS1 & WS2 & WS3 --> Aggregator
82
81
  Aggregator --> WinnerMarker
83
82
  WinnerMarker --> Promote
84
- Promote --> LiveCanvas
85
83
  Promote --> Summary
86
84
  ```
87
85
 
@@ -99,7 +97,13 @@ Integrated directly into the DeepSeek Harness composer via client input triggers
99
97
  Or target a specific named preset:
100
98
 
101
99
  ```text
102
- /moa:code-review audit the auth middleware and security boundaries
100
+ /moa code-review audit the auth middleware and security boundaries
101
+ ```
102
+
103
+ The flag form is equivalent:
104
+
105
+ ```text
106
+ /moa --preset=deep-reasoning solve this math problem step by step
103
107
  ```
104
108
 
105
109
  ### 2. Adaptive Questionnaire Gate
@@ -115,14 +119,15 @@ Unlike standard chat-only MoA, `dsh-moa` isolates file generation onto the files
115
119
  * The Judge compares implementations and selects the optimal solution with `WINNER_CANDIDATE_INDEX: N`.
116
120
  * The winner's files are promoted to the workspace root, and temporary candidate directories are pruned automatically.
117
121
 
118
- ### 5. Live Canvas 1-Click Preview
119
- If web files (`index.html`, React/JSX components, Vue, CSS) are generated, `dsh-moa` communicates with `@goodandready/dsh-live-canvas` via its REST endpoint to instantiate a live preview container with 1-click instant access.
120
-
121
- ### 6. Native Settings Card & Presets
122
+ ### 5. Native Settings Card & Presets
122
123
  Configure your models in `Settings → Plugins → Mixture of Agents`:
123
124
  * Set custom Proposer models (e.g., fast generative models for diverse ideas).
124
125
  * Set the Aggregator / Judge model (e.g., deep reasoning models for rigorous critique).
125
- * Configure named presets (`default`, `code-review`, `deep-reasoning`).
126
+ * Configure named presets (`default`, `fast`, `deep-reasoning`), judge criteria and temperatures.
127
+ * Enable or disable MoA and see the real host status chip; the telemetry grid shows total runs and average run cost.
128
+
129
+ ### 6. Live Canvas 1-Click Preview (optional)
130
+ If `@goodandready/dsh-live-canvas` is installed in the same profile, `dsh-moa` pushes the promoted HTML file to the Live Canvas REST contract (`POST /dsh-live-canvas/api/preview`, served by the same harness webServer) and appends a one-click preview link (`/dsh-live-canvas/sandbox/<id>`) to the answer. Without the plugin the step is skipped silently — no errors in the log, no dead links.
126
131
 
127
132
  ---
128
133
 
@@ -140,22 +145,13 @@ Restart your DeepSeek Harness instance and refresh the browser.
140
145
 
141
146
  ## ⚙️ Configuration (`settings.yaml`)
142
147
 
143
- Configure presets and model pipelines in `settings.yaml` or through the Web UI Settings panel:
148
+ Configure presets and model pipelines in `settings.yaml` or through the Web UI Settings panel (Settings → Plugins → Mixture of Agents):
144
149
 
145
150
  ```yaml
146
151
  # settings.yaml
147
152
  dsh-moa:
148
- defaultPreset: "default"
149
- presets:
150
- default:
151
- references:
152
- - provider: "your-fast-provider"
153
- model: "your-creative-model"
154
- - provider: "your-fast-provider"
155
- model: "your-balanced-model"
156
- aggregator:
157
- provider: "your-reasoning-provider"
158
- model: "your-judge-model"
153
+ enabled: true
154
+ default_preset: "default"
159
155
  prices:
160
156
  "my-provider/my-model":
161
157
  input: 0.20
@@ -163,26 +159,52 @@ dsh-moa:
163
159
  "ollama/*":
164
160
  input: 0
165
161
  output: 0
166
- code-review:
167
- references:
162
+ presets:
163
+ - name: default
164
+ ask_clarifying_questions: true
165
+ reference_models:
168
166
  - provider: "your-fast-provider"
169
- model: "your-security-model"
167
+ model: "your-creative-model"
170
168
  - provider: "your-fast-provider"
171
- model: "your-performance-model"
169
+ model: "your-balanced-model"
172
170
  aggregator:
173
171
  provider: "your-reasoning-provider"
174
172
  model: "your-judge-model"
173
+ reference_temperature: 0.6
174
+ aggregator_temperature: 0.4
175
+ max_tokens: 4096
176
+ judge_criteria: ""
177
+ - name: fast
178
+ ask_clarifying_questions: false
179
+ reference_models:
180
+ - provider: "your-fast-provider"
181
+ model: "your-fast-model"
182
+ aggregator:
183
+ provider: "your-fast-provider"
184
+ model: "your-fast-model"
175
185
  ```
176
186
 
177
187
  ### Configuration Parameters
178
188
 
179
189
  | Parameter | Type | Default | Description |
180
190
  |:---|:---|:---|:---|
181
- | `defaultPreset` | `string` | `"default"` | Default preset invoked when typing `/moa <prompt>` |
182
- | `presets.<name>.references` | `array` | `[...]` | List of proposer models queried concurrently during the proposal phase |
183
- | `presets.<name>.aggregator` | `object` | `{...}` | Frontier judge model responsible for synthesis, critique, and winner selection |
184
- | `enableQuestionnaire` | `boolean` | `true` | Enable interactive clarifying questionnaire for underspecified requests |
185
- | `autoPromoteWinner` | `boolean` | `true` | Automatically promote the judge's selected winner files into the project workspace |
191
+ | `enabled` | `boolean` | `true` | Master switch for the `/moa` command, turn routing and `POST /dsh-moa/run` (editable in the settings card) |
192
+ | `default_preset` | `string` | `"default"` | Preset invoked when typing `/moa <prompt>` without an explicit preset |
193
+ | `presets` | `array` | `[...]` | Named presets; selected via `/moa <name> <prompt>` or `/moa --preset=<name> <prompt>` |
194
+ | `presets[].reference_models` | `array` | `[...]` | Proposer models queried concurrently during the proposal phase |
195
+ | `presets[].aggregator` | `object` | `{...}` | Judge model responsible for synthesis, critique, and winner selection |
196
+ | `presets[].ask_clarifying_questions` | `boolean` | `true` | Synthesize a clarifying questionnaire for broad/underspecified prompts (per preset) |
197
+ | `presets[].curator_synthesis` | `boolean` | `false` | Curator mode: evaluates strongest parts across candidates using the antipatterns rubric and advises an assembler model |
198
+ | `presets[].stream_aggregator` | `boolean` | `true` | Stream judge/aggregator tokens live in real-time with zero TTFT wait |
199
+ | `presets[].quorum_enabled` | `boolean` | `false` | Straggler mitigation: proceed with synthesis once >= 60% candidates respond |
200
+ | `presets[].grace_period_sec` | `number` | `10` | Grace period in seconds to wait for stragglers after quorum is reached |
201
+ | `presets[].aggregator_fallbacks` | `array` | `[]` | Ordered fallback judge models tried if primary aggregator encounters transient errors |
202
+ | `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | Sampling temperatures for proposers and judge |
203
+ | `presets[].max_tokens` | `number` | `4096` | Max output tokens per model call |
204
+ | `presets[].judge_criteria` | `string` | `""` | Optional extra evaluation criteria passed to the judge |
205
+ | `prices` | `map` | `{}` | Custom USD-per-1M-token rates (`"provider/model"`, `"provider/*"`, `"*"`) applied to cost estimation |
206
+
207
+ > **Privacy note:** in refinement mode, readable project files (up to ~16k characters; dotfiles such as `.env*` are excluded) are included in the prompts sent to the configured candidate and judge providers. Avoid running `/moa` in projects whose non-dotfile files contain secrets.
186
208
 
187
209
  ---
188
210
 
@@ -190,9 +212,14 @@ dsh-moa:
190
212
 
191
213
  | Endpoint | Method | Description |
192
214
  |:---|:---|:---|
193
- | `/dsh-moa/presets` | `GET` | Returns list of configured MoA presets |
215
+ | `/dsh-moa/status` | `GET` | Health/enablement snapshot used by the settings card status chip |
216
+ | `/dsh-moa/presets` | `GET` | Returns the configured MoA presets and default preset |
217
+ | `/dsh-moa/presets` | `POST` | Replaces presets/default preset/enabled after schema validation (400 on invalid payload) |
218
+ | `/dsh-moa/models` | `GET` | Lists models available for candidate/judge slots |
194
219
  | `/dsh-moa/history?limit=20&offset=0` | `GET` | Returns recent MoA runs with candidates, winner, cost, and tokens |
195
220
  | `/dsh-moa/leaderboard` | `GET` | Computes model win-rate leaderboard and average execution costs |
221
+ | `/dsh-moa/runs/<id>` | `GET` | Returns a single recorded run by id |
222
+ | `/dsh-moa/run` | `POST` | Runs the full MoA pipeline over HTTP (400 when `enabled: false`) |
196
223
 
197
224
  ---
198
225
 
package/docs/README.ru.md CHANGED
@@ -34,13 +34,13 @@
34
34
  1. **Адаптивный опросник для уточнения требований**: Если запрос пользователя сформулирован слишком широко или не содержит ключевых деталей, модели-советники формируют уточняющие варианты, а модель-судья синтезирует структурированный интерактивный опросник (2–4 вопроса) до начала генерации кода.
35
35
  2. **Параллельный опрос моделей (Proposers) и изоляция на диске**: Несколько независимых моделей анализируют задачу одновременно. Файлы каждого кандидата сохраняются в изолированные директории (`.moa/candidate-N/`), исключая конфликты.
36
36
  3. **Оценка флагманским судьей (Judge) и автоматический промоушн файлов**: Модель глубоких рассуждений проводит критический сравнительный анализ всех предложенных решений, выбирает победителя с помощью машинного маркера (`WINNER_CANDIDATE_INDEX: N`) и переносит готовые файлы победителя напрямую в корень проекта.
37
- 4. **Мгновенный предпросмотр через Live Canvas**: При создании веб-приложений и UI-компонентов `dsh-moa` бесшовно интегрируется с `@goodandready/dsh-live-canvas`, автоматически инициализируя контейнер для предпросмотра в браузере в 1 клик.
38
- 5. **Экономия токенов в чате**: Вместо вывода огромных листингов кода в чат формируется компактный отчет с перечнем созданных файлов и архитектурным резюме.
39
- 6. **Одноразовый модификатор сессии**: Команда выполняется в рамках одного такта и автоматически возвращает исходную модель сессии пользователя сразу после завершения.
40
- 7. **Динамический каталог тарифов и подсчет токенов**: Актуальные цены на 300+ моделей автоматически подтягиваются из публичного каталога OpenRouter (без ключей и авторизации), кешируются в `~/.dsh/storages/dsh-moa-catalog.json` на 24 часа, а также поддерживают прямые вендорские тарифы и пользовательские оверрайды `prices` в `settings.yaml`.
41
- 8. **Режим доработки (Refinement Mode)**: Автоматически считывает контекст существующего проекта и генерирует точечные дельта-правки без перетирания всей кодовой базы.
42
- 9. **Быстрый режим (Fast Mode) и критерии судьи**: Режим для одиночных быстрых задач без судьи и гибкая настройка фокуса оценки (безопасность, производительность, минимализм).
43
- 10. **История запусков и лидерборд моделей**: Персистентное логирование запусков и REST-эндпоинты (`/dsh-moa/history` и `/dsh-moa/leaderboard`).
37
+ 4. **Экономия токенов в чате**: Вместо вывода огромных листингов кода в чат формируется компактный отчет с перечнем созданных файлов и архитектурным резюме.
38
+ 5. **Одноразовый модификатор сессии**: Команда выполняется в рамках одного такта и автоматически возвращает исходную модель сессии пользователя сразу после завершения.
39
+ 6. **Динамический каталог тарифов и подсчет токенов**: Актуальные цены на 300+ моделей автоматически подтягиваются из публичного каталога OpenRouter (без ключей и авторизации), кешируются в `~/.dsh/storages/dsh-moa-catalog.json` на 24 часа, а также поддерживают прямые вендорские тарифы и пользовательские оверрайды `prices` в `settings.yaml`.
40
+ 7. **Режим доработки (Refinement Mode)**: Автоматически считывает контекст существующего проекта и генерирует точечные дельта-правки без перетирания всей кодовой базы.
41
+ 8. **Быстрый режим (Fast Mode) и критерии судьи**: Режим для одиночных быстрых задач без судьи и гибкая настройка фокуса оценки (безопасность, производительность, минимализм).
42
+ 9. **История запусков и лидерборд моделей**: Персистентное логирование всех видов запусков (синтез, fast mode, опросник) и REST-эндпоинты (`/dsh-moa/history`, `/dsh-moa/leaderboard`, `/dsh-moa/runs/<id>`).
43
+ 10. **Live Canvas 1-клик предпросмотр (опционально)**: если в профиле установлен `@goodandready/dsh-live-canvas`, промоученный HTML отправляется в его песочницу, а ответ MoA содержит ссылку на предпросмотр в 1 клик; без плагина шаг тихо пропускается.
44
44
 
45
45
  ---
46
46
 
@@ -67,7 +67,6 @@ graph TD
67
67
  Aggregator["Флагманская модель-судья<br/>(Сравнительный анализ и аудит кода)"]
68
68
  WinnerMarker{"WINNER_CANDIDATE_INDEX"}
69
69
  Promote["Промоушн файлов победителя<br/>(Перенос в корень и очистка песочниц)"]
70
- LiveCanvas["Интеграция с Live Canvas<br/>(Автозапуск веб-песочницы)"]
71
70
  Summary["Компактный отчет<br/>(Обзор файлов и архитектурное резюме)"]
72
71
  end
73
72
 
@@ -81,7 +80,6 @@ graph TD
81
80
  WS1 & WS2 & WS3 --> Aggregator
82
81
  Aggregator --> WinnerMarker
83
82
  WinnerMarker --> Promote
84
- Promote --> LiveCanvas
85
83
  Promote --> Summary
86
84
  ```
87
85
 
@@ -99,7 +97,13 @@ graph TD
99
97
  Или вызов именованного пресета:
100
98
 
101
99
  ```text
102
- /moa:code-review проведи аудит middleware авторизации и границ безопасности
100
+ /moa code-review проведи аудит middleware авторизации и границ безопасности
101
+ ```
102
+
103
+ Эквивалентная форма с флагом:
104
+
105
+ ```text
106
+ /moa --preset=deep-reasoning реши эту математическую задачу по шагам
103
107
  ```
104
108
 
105
109
  ### 2. Адаптивный гейт уточнения требований
@@ -115,14 +119,15 @@ graph TD
115
119
  * Судья сопоставляет реализации и выбирает лучшую через маркер `WINNER_CANDIDATE_INDEX: N`.
116
120
  * Файлы победителя автоматически переносятся в корень рабочей области, а временные папки удаляются.
117
121
 
118
- ### 5. Интеграция с Live Canvas (1-клик предпросмотр)
119
- При создании веб-файлов (`index.html`, компоненты React/JSX, Vue, стили CSS) плагин отправляет запрос в `@goodandready/dsh-live-canvas` для мгновенного развертывания интерактивного предпросмотра.
120
-
121
- ### 6. Нативная карточка настроек и пресеты
122
+ ### 5. Нативная карточка настроек и пресеты
122
123
  Настройка моделей в меню `Настройки → Плагины → Mixture of Agents`:
123
124
  * Выбор моделей-советников (быстрые генеративные модели для разнообразия идей).
124
125
  * Выбор модели-судьи (модель глубоких рассуждений для строгого аудита).
125
- * Конфигурация именованных пресетов (`default`, `code-review`, `deep-reasoning`).
126
+ * Конфигурация именованных пресетов (`default`, `fast`, `deep-reasoning`), критериев судьи и температур.
127
+ * Включение/отключение MoA и фактический статус-бейдж хоста; сетка телеметрии показывает общее число запусков и среднюю стоимость.
128
+
129
+ ### 6. Live Canvas 1-клик предпросмотр (опционально)
130
+ Если в профиле установлен `@goodandready/dsh-live-canvas`, `dsh-moa` отправляет промоученный HTML-файл в REST-контракт Live Canvas (`POST /dsh-live-canvas/api/preview`, тот же webServer харнесса) и добавляет к ответу ссылку на предпросмотр (`/dsh-live-canvas/sandbox/<id>`). Без плагина шаг пропускается тихо — без ошибок в журнале и без битых ссылок.
126
131
 
127
132
  ---
128
133
 
@@ -140,22 +145,13 @@ dsh plugin --profile web add @goodandready/dsh-moa
140
145
 
141
146
  ## ⚙️ Конфигурация (`settings.yaml`)
142
147
 
143
- Настройка пресетов и пайплайнов моделей доступна в `settings.yaml` или через графический интерфейс настроек:
148
+ Настройка пресетов и пайплайнов моделей доступна в `settings.yaml` или через интерфейс (Настройки → Плагины → Mixture of Agents):
144
149
 
145
150
  ```yaml
146
151
  # settings.yaml
147
152
  dsh-moa:
148
- defaultPreset: "default"
149
- presets:
150
- default:
151
- references:
152
- - provider: "your-fast-provider"
153
- model: "your-creative-model"
154
- - provider: "your-fast-provider"
155
- model: "your-balanced-model"
156
- aggregator:
157
- provider: "your-reasoning-provider"
158
- model: "your-judge-model"
153
+ enabled: true
154
+ default_preset: "default"
159
155
  prices:
160
156
  "my-provider/my-model":
161
157
  input: 0.20
@@ -163,26 +159,52 @@ dsh-moa:
163
159
  "ollama/*":
164
160
  input: 0
165
161
  output: 0
166
- code-review:
167
- references:
162
+ presets:
163
+ - name: default
164
+ ask_clarifying_questions: true
165
+ reference_models:
168
166
  - provider: "your-fast-provider"
169
- model: "your-security-model"
167
+ model: "your-creative-model"
170
168
  - provider: "your-fast-provider"
171
- model: "your-performance-model"
169
+ model: "your-balanced-model"
172
170
  aggregator:
173
171
  provider: "your-reasoning-provider"
174
172
  model: "your-judge-model"
173
+ reference_temperature: 0.6
174
+ aggregator_temperature: 0.4
175
+ max_tokens: 4096
176
+ judge_criteria: ""
177
+ - name: fast
178
+ ask_clarifying_questions: false
179
+ reference_models:
180
+ - provider: "your-fast-provider"
181
+ model: "your-fast-model"
182
+ aggregator:
183
+ provider: "your-fast-provider"
184
+ model: "your-fast-model"
175
185
  ```
176
186
 
177
187
  ### Параметры конфигурации
178
188
 
179
189
  | Параметр | Тип | По умолчанию | Описание |
180
190
  |:---|:---|:---|:---|
181
- | `defaultPreset` | `string` | `"default"` | Пресет по умолчанию, вызываемый командой `/moa <запрос>` |
182
- | `presets.<name>.references` | `array` | `[...]` | Список моделей-советников, опрашиваемых параллельно |
183
- | `presets.<name>.aggregator` | `object` | `{...}` | Модель-судья, отвечающая за синтез, критику и выбор победителя |
184
- | `enableQuestionnaire` | `boolean` | `true` | Включение интерактивного опросника при неоднозначных запросах |
185
- | `autoPromoteWinner` | `boolean` | `true` | Автоматический перенос файлов выбранного победителя в корень проекта |
191
+ | `enabled` | `boolean` | `true` | Главный выключатель команды `/moa`, маршрутизации тактов и `POST /dsh-moa/run` (редактируется в карточке настроек) |
192
+ | `default_preset` | `string` | `"default"` | Пресет по умолчанию, вызываемый командой `/moa <запрос>` без явного пресета |
193
+ | `presets` | `array` | `[...]` | Именованные пресеты; выбираются через `/moa <имя> <запрос>` или `/moa --preset=<имя> <запрос>` |
194
+ | `presets[].reference_models` | `array` | `[...]` | Список моделей-советников, опрашиваемых параллельно |
195
+ | `presets[].aggregator` | `object` | `{...}` | Модель-судья, отвечающая за синтез, критику и выбор победителя |
196
+ | `presets[].ask_clarifying_questions` | `boolean` | `true` | Синтез опросника для широких/неоднозначных запросов (на уровне пресета) |
197
+ | `presets[].curator_synthesis` | `boolean` | `false` | Режим куратора: извлечение сильных сторон решений по рубрике антипаттернов и выбор ведущей модели-сборщика |
198
+ | `presets[].stream_aggregator` | `boolean` | `true` | Потоковый стриминг ответа судьи в реальном времени с нулевым временем первого токена (TTFT) |
199
+ | `presets[].quorum_enabled` | `boolean` | `false` | Защита от зависших моделей (stragglers): запуск синтеза при ответе от >= 60% кандидатов |
200
+ | `presets[].grace_period_sec` | `number` | `10` | Грейс-период (в секундах) ожидания оставшихся моделей после достижения кворума |
201
+ | `presets[].aggregator_fallbacks` | `array` | `[]` | Список запасных моделей-судей при сбоях основной модели агрегатора |
202
+ | `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | Температуры сэмплирования советников и судьи |
203
+ | `presets[].max_tokens` | `number` | `4096` | Максимум выходных токенов на вызов модели |
204
+ | `presets[].judge_criteria` | `string` | `""` | Опциональные дополнительные критерии оценки для судьи |
205
+ | `prices` | `map` | `{}` | Пользовательские тарифы USD за 1M токенов (`"provider/model"`, `"provider/*"`, `"*"`) для расчета стоимости |
206
+
207
+ > **Примечание о приватности:** в режиме доработки читаемые файлы проекта (до ~16 тыс. символов; dotfile-файлы вида `.env*` исключены) включаются в промпты, отправляемые настроенным моделям-кандидатам и судье. Не запускайте `/moa` в проектах, где не-dotfile файлы содержат секреты.
186
208
 
187
209
  ---
188
210
 
@@ -190,9 +212,14 @@ dsh-moa:
190
212
 
191
213
  | Эндпоинт | Метод | Описание |
192
214
  |:---|:---|:---|
193
- | `/dsh-moa/presets` | `GET` | Возвращает список настроенных пресетов MoA |
215
+ | `/dsh-moa/status` | `GET` | Снимок здоровья/включенности для статус-бейджа карточки настроек |
216
+ | `/dsh-moa/presets` | `GET` | Возвращает настроенные пресеты MoA и пресет по умолчанию |
217
+ | `/dsh-moa/presets` | `POST` | Заменяет пресеты/пресет по умолчанию/enabled после валидации схемой (400 при невалидном payload) |
218
+ | `/dsh-moa/models` | `GET` | Список моделей, доступных для слотов кандидатов и судьи |
194
219
  | `/dsh-moa/history?limit=20&offset=0` | `GET` | История запусков с кандидатами, победителем, токенами и ценой |
195
220
  | `/dsh-moa/leaderboard` | `GET` | Лидерборд побед моделей и средняя стоимость генерации |
221
+ | `/dsh-moa/runs/<id>` | `GET` | Возвращает один записанный запуск по id |
222
+ | `/dsh-moa/run` | `POST` | Запускает полный пайплайн MoA по HTTP (400 при `enabled: false`) |
196
223
 
197
224
  ---
198
225
 
package/docs/README.zh.md CHANGED
@@ -34,9 +34,13 @@
34
34
  1. **自适应澄清问卷 (Questionnaire Gate)**：针对宽泛或不明确的提示词，顾问模型（Proposers）自动提炼关键分歧点，裁判模型（Judge）在生成代码前合成结构化的 2–4 题交互式问卷。
35
35
  2. **多模型并行生成与工作区沙箱隔离**：多个独立模型并行分析任务。每个候选方案的文件生成均写入独立的磁盘沙箱 (`.moa/candidate-N/`)，彻底避免跨模型文件污染。
36
36
  3. **旗舰裁判模型评估与文件自动提升 (Promotion)**：深度推理模型对所有候选方案进行交叉评审，通过机器标记 (`WINNER_CANDIDATE_INDEX: N`) 评选胜出方案，并将胜出者的完整文件自动同步到项目根目录。
37
- 4. **Live Canvas 即时一键预览**：当生成 Web 应用或 UI 组件时，`dsh-moa` 与 `@goodandready/dsh-live-canvas` 深度联动，自动创建沙箱容器，支持在浏览器中 1 键即时运行与交互。
38
- 5. **极简对话摘要与 Token 节省**：对话界面不输出冗长的原始代码块，而是生成整洁的文件清单与架构设计摘要。
39
- 6. **单轮会话即时恢复**：作为一次性会话修改器运行，任务完成后自动恢复用户原本的会话主力模型。
37
+ 4. **极简对话摘要与 Token 节省**：对话界面不输出冗长的原始代码块，而是生成整洁的文件清单与架构设计摘要。
38
+ 5. **单轮会话即时恢复**：作为一次性会话修改器运行，任务完成后自动恢复用户原本的会话主力模型。
39
+ 6. **动态定价目录与 Token 成本估算**：300+ 模型的实时价格自动从 OpenRouter 公开目录后台获取（无需鉴权，缓存于 `~/.dsh/storages/dsh-moa-catalog.json`，24 小时刷新），同时支持直连厂商价格与 `settings.yaml` 中的自定义 `prices` 覆盖。
40
+ 7. **增量修改模式 (Refinement Mode)**：自动感知现有代码库上下文，生成精确的增量修改而非破坏性的整文件重写。
41
+ 8. **快速模式与自定义评审标准**：面向快速任务的单模型极简管线，以及可自定义的裁判评审准则。
42
+ 9. **运行历史与胜率排行榜**：对每一类运行（综合、快速模式、问卷）进行持久化记录，并内置 REST 端点（`/dsh-moa/history`、`/dsh-moa/leaderboard`、`/dsh-moa/runs/<id>`）。
43
+ 10. **Live Canvas 一键预览（可选）**：当同一 profile 中安装了 `@goodandready/dsh-live-canvas` 时，提升到项目根目录的 HTML 会被推入其沙箱，MoA 回答附带一键预览链接；未安装时该步骤静默跳过。
40
44
 
41
45
  ---
42
46
 
@@ -63,7 +67,6 @@ graph TD
63
67
  Aggregator["旗舰裁判模型<br/>(交叉对比与代码审查)"]
64
68
  WinnerMarker{"WINNER_CANDIDATE_INDEX"}
65
69
  Promote["提升胜出者文件<br/>(移至根目录并清理沙箱)"]
66
- LiveCanvas["Live Canvas 联动<br/>(自动启动 Web 预览)"]
67
70
  Summary["紧凑型摘要<br/>(文件清单与架构亮点)"]
68
71
  end
69
72
 
@@ -77,7 +80,6 @@ graph TD
77
80
  WS1 & WS2 & WS3 --> Aggregator
78
81
  Aggregator --> WinnerMarker
79
82
  WinnerMarker --> Promote
80
- Promote --> LiveCanvas
81
83
  Promote --> Summary
82
84
  ```
83
85
 
@@ -95,7 +97,13 @@ graph TD
95
97
  或指定命名预设：
96
98
 
97
99
  ```text
98
- /moa:code-review 审查身份验证中间件和安全边界
100
+ /moa code-review 审查身份验证中间件和安全边界
101
+ ```
102
+
103
+ 等效的 flag 形式：
104
+
105
+ ```text
106
+ /moa --preset=deep-reasoning 逐步求解这道数学题
99
107
  ```
100
108
 
101
109
  ### 2. 自适应澄清问卷
@@ -111,14 +119,15 @@ graph TD
111
119
  * 裁判模型对比各版本实现，通过 `WINNER_CANDIDATE_INDEX: N` 指定最优方案。
112
120
  * 胜出方案自动提升至项目根目录，临时沙箱随后自动清理。
113
121
 
114
- ### 5. Live Canvas 1 键即时预览
115
- 若生成了前端文件（`index.html`、React/JSX 组件、Vue、CSS），插件通过 REST API 自动调用 `@goodandready/dsh-live-canvas` 容器，实现免构建一键预览。
116
-
117
- ### 6. 原生设置卡片与预设管理
122
+ ### 5. 原生设置卡片与预设管理
118
123
  在 `设置 → 插件 → Mixture of Agents` 中可视化配置模型：
119
124
  * 配置顾问模型列表（快速生成多样化构想）。
120
125
  * 配置裁判模型（强推理模型进行严谨审查）。
121
- * 自定义命名预设 (`default`, `code-review`, `deep-reasoning`)。
126
+ * 自定义命名预设 (`default`, `fast`, `deep-reasoning`)、裁判评审准则与温度。
127
+ * 启用/停用 MoA 开关并查看真实的主机状态徽章；遥测网格展示总运行次数与平均运行成本。
128
+
129
+ ### 6. Live Canvas 一键预览（可选）
130
+ 若同一 profile 中安装了 `@goodandready/dsh-live-canvas`，`dsh-moa` 会将提升后的 HTML 文件推送到 Live Canvas 的 REST 契约（`POST /dsh-live-canvas/api/preview`，由同一 harness webServer 提供服务），并在回答中附上一键预览链接（`/dsh-live-canvas/sandbox/<id>`）。未安装该插件时此步骤静默跳过——日志无报错，也不会出现死链接。
122
131
 
123
132
  ---
124
133
 
@@ -136,15 +145,24 @@ dsh plugin --profile web add @goodandready/dsh-moa
136
145
 
137
146
  ## ⚙️ 配置 (`settings.yaml`)
138
147
 
139
- 可在 `settings.yaml` 中配置预设与模型管道，或通过 Web UI 设置面板进行调整：
148
+ 可在 `settings.yaml` 中配置预设与模型管道，或通过 Web UI 设置面板（设置 → 插件 → Mixture of Agents）进行调整：
140
149
 
141
150
  ```yaml
142
151
  # settings.yaml
143
152
  dsh-moa:
144
- defaultPreset: "default"
153
+ enabled: true
154
+ default_preset: "default"
155
+ prices:
156
+ "my-provider/my-model":
157
+ input: 0.20
158
+ output: 0.80
159
+ "ollama/*":
160
+ input: 0
161
+ output: 0
145
162
  presets:
146
- default:
147
- references:
163
+ - name: default
164
+ ask_clarifying_questions: true
165
+ reference_models:
148
166
  - provider: "your-fast-provider"
149
167
  model: "your-creative-model"
150
168
  - provider: "your-fast-provider"
@@ -152,26 +170,51 @@ dsh-moa:
152
170
  aggregator:
153
171
  provider: "your-reasoning-provider"
154
172
  model: "your-judge-model"
155
- code-review:
156
- references:
173
+ reference_temperature: 0.6
174
+ aggregator_temperature: 0.4
175
+ max_tokens: 4096
176
+ judge_criteria: ""
177
+ - name: fast
178
+ ask_clarifying_questions: false
179
+ reference_models:
157
180
  - provider: "your-fast-provider"
158
- model: "your-security-model"
159
- - provider: "your-fast-provider"
160
- model: "your-performance-model"
181
+ model: "your-fast-model"
161
182
  aggregator:
162
- provider: "your-reasoning-provider"
163
- model: "your-judge-model"
183
+ provider: "your-fast-provider"
184
+ model: "your-fast-model"
164
185
  ```
165
186
 
166
187
  ### 配置项说明
167
188
 
168
189
  | 参数 | 类型 | 默认值 | 说明 |
169
190
  |:---|:---|:---|:---|
170
- | `defaultPreset` | `string` | `"default"` | 输入 `/moa <prompt>` 时默认调用的预设 |
171
- | `presets.<name>.references` | `array` | `[...]` | 并行提案阶段并发调用的顾问模型列表 |
172
- | `presets.<name>.aggregator` | `object` | `{...}` | 负责综合评审、代码审查与裁决胜出者的裁判模型 |
173
- | `enableQuestionnaire` | `boolean` | `true` | 对模糊需求启用交互式澄清问卷 |
174
- | `autoPromoteWinner` | `boolean` | `true` | 自动将裁判选中的胜出方案文件提升至项目根目录 |
191
+ | `enabled` | `boolean` | `true` | `/moa` 命令、回合路由与 `POST /dsh-moa/run` 的总开关（可在设置卡片中切换） |
192
+ | `default_preset` | `string` | `"default"` | 输入 `/moa <prompt>` 且未显式指定预设时调用的预设 |
193
+ | `presets` | `array` | `[...]` | 命名预设列表；通过 `/moa <name> <prompt>` 或 `/moa --preset=<name> <prompt>` 选择 |
194
+ | `presets[].reference_models` | `array` | `[...]` | 并行提案阶段并发调用的顾问模型列表 |
195
+ | `presets[].aggregator` | `object` | `{...}` | 负责综合评审、代码审查与裁决胜出者的裁判模型 |
196
+ | `presets[].ask_clarifying_questions` | `boolean` | `true` | 针对宽泛需求合成澄清问卷（预设级别开关） |
197
+ | `presets[].reference_temperature` / `.aggregator_temperature` | `number` | `0.6` / `0.4` | 顾问与裁判的采样温度 |
198
+ | `presets[].max_tokens` | `number` | `4096` | 每次模型调用的最大输出 Token 数 |
199
+ | `presets[].judge_criteria` | `string` | `""` | 传给裁判的可选附加评审准则 |
200
+ | `prices` | `map` | `{}` | 自定义美元/百万 Token 费率（`"provider/model"`、`"provider/*"`、`"*"`），用于成本估算 |
201
+
202
+ > **隐私提示：** 在增量修改模式下，可读的项目文件（最多约 1.6 万字符；`.env*` 等点文件已被排除）会随提示词发送给所配置的候选模型与裁判模型。请勿在非点文件中包含密钥的项目里运行 `/moa`。
203
+
204
+ ---
205
+
206
+ ## 📊 REST API 端点
207
+
208
+ | 端点 | 方法 | 说明 |
209
+ |:---|:---|:---|
210
+ | `/dsh-moa/status` | `GET` | 供设置卡片状态徽章使用的健康/启用状态快照 |
211
+ | `/dsh-moa/presets` | `GET` | 返回已配置的 MoA 预设与默认预设 |
212
+ | `/dsh-moa/presets` | `POST` | 经 schema 校验后替换预设/默认预设/enabled（非法载荷返回 400） |
213
+ | `/dsh-moa/models` | `GET` | 列出可用于候选/裁判槽位的模型 |
214
+ | `/dsh-moa/history?limit=20&offset=0` | `GET` | 返回近期运行记录（含候选、胜出者、Token 与成本） |
215
+ | `/dsh-moa/leaderboard` | `GET` | 计算模型胜率排行榜与平均执行成本 |
216
+ | `/dsh-moa/runs/<id>` | `GET` | 按 id 返回单条运行记录 |
217
+ | `/dsh-moa/run` | `POST` | 通过 HTTP 运行完整 MoA 管线（`enabled: false` 时返回 400） |
175
218
 
176
219
  ---
177
220