dsh-department 0.1.0 → 0.2.0

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.
package/README.ru.md ADDED
@@ -0,0 +1,289 @@
1
+ # dsh-department — ИИ-отдел разработки для DeepSeek Harness
2
+
3
+ [English](README.md) · **Русский**
4
+
5
+ ![CI](https://github.com/Vldimirus/dsh-department/actions/workflows/ci.yml/badge.svg)
6
+ ![npm](https://img.shields.io/npm/v/dsh-department.svg)
7
+ ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
8
+
9
+ Плагин превращает DeepSeek Harness в **отдел разработки**: задача проходит анализ →
10
+ концепцию → ТЗ → план → этапы, а внутри этапа — реализацию, тесты, независимое ревью и
11
+ коммит с тегом. Человек утверждает только концепцию и ТЗ, остальное отдел решает сам
12
+ по политике автономии.
13
+
14
+ ## Скриншоты
15
+
16
+ | Панель отдела (EN) | Офис: работа |
17
+ |---|---|
18
+ | ![Панель](docs/screenshots/panel-en.png) | ![Офис](docs/screenshots/office.png) |
19
+
20
+ | Пауза: все в комнате отдыха | 16 персонажей |
21
+ |---|---|
22
+ | ![Пауза](docs/screenshots/office-paused.png) | ![Персонажи](docs/screenshots/characters.png) |
23
+
24
+ ## Возможности
25
+
26
+ - **Доска задач** по всем проектам: стадия, прогресс, гейты, последнее событие.
27
+ - **Карточка задачи** на вкладках: обзор, документы, вопросы, аудит, события, git;
28
+ кнопки утверждения, ответы на вопросы, поправки к ТЗ.
29
+ - **Офис отдела**: кто работает, за каким столом, что делает; клик — проект, задача,
30
+ файлы и история действий.
31
+ - **Схема проекта**: файлы и связи импортов по группам (папкам), drill-down до файла.
32
+ - **Бюджет**: расход токенов по сессиям, стоимость по ценам за 1M, лимит задачи.
33
+ - **Отчётность**: `dept_report` — этап, гейты, кто чем занят, открытые вопросы.
34
+ - **Вопросы к человеку** (`dept_ask` / `dept_answer`) — отдел не останавливается.
35
+ - **Поправки ТЗ** (`dept_amend`): с подписью человека или автономно (с лимитом).
36
+ - **Повторы по циклу** «данные → анализ → план → изменения → тесты»; повтор без анализа
37
+ блокируется, повторяющийся провал переводит этап в `blocked`.
38
+ - **Git**: коммит этапа, тег, push ветки и тегов; коммит заблокирован без свежих гейтов.
39
+
40
+ ## Установка
41
+
42
+ Плагин ставится в профиль DSH как локальный (`link:`) или из репозитория:
43
+
44
+ ```bash
45
+ dsh plugin add link:/path/to/dsh-department
46
+ ```
47
+
48
+ Затем включите bundle `dsh-department` в менеджере плагинов и перезагрузите вкладку.
49
+ В сайдбаре появится «ИИ-отдел», в основном окне — доска, офис и схема.
50
+
51
+ ## Инструменты модели
52
+
53
+ | Инструмент | Назначение |
54
+ |---|---|
55
+ | `dept_start` | создать задачу: состояние, ветка, task.md |
56
+ | `dept_status` | состояние задачи и сводка |
57
+ | `dept_stage` | переход стадии (кроме утверждений) |
58
+ | `dept_approve` | утверждение концепции/ТЗ человеком |
59
+ | `dept_gate` | гейт тестов (exit code) или ревью (PASS/FAIL) |
60
+ | `dept_verify` | аудит: состояние ↔ артефакты ↔ git |
61
+ | `dept_commit` | коммит этапа, тег, push |
62
+ | `dept_amend` | поправка к документу (подпись человека или `autonomous`) |
63
+ | `dept_ask` | вопрос человеку без остановки работы |
64
+ | `dept_answer` | ответ человека на вопрос |
65
+ | `dept_report` | отчёт о состоянии отдела |
66
+ | `dept_health` | «жив ли отдел»: работает / стоит / ждёт человека / готов к коммиту |
67
+ | `dept_modules` | план модулей и владение файлами для параллельной работы |
68
+ | `dept_art` | нарисовать пиксельный спрайт и сохранить PNG |
69
+ | `dept_pixelize` | PNG/JPEG → пиксельная сетка + палитра + спрайт (для перерисовки по референсу) |
70
+ | `dept_compose` | собрать большое PNG из маленьких спрайтов (холст, фон, слои) |
71
+ | `dept_roles` | роли и модели (researcher, designer, artist, senior-coder, supervisor, beta-tester, ...) |
72
+ | `dept_bug` | баг-репорт бета-тестера (шаги, ожидаемое/фактическое, критичность) |
73
+ | `dept_browse` | браузер: открыть localhost/file, клики, ввод, скриншот в evidence |
74
+ | `dept_gui` | нативная программа: команда, env, таймаут, вывод, скриншот через хук/команду |
75
+
76
+ ## HTTP API
77
+
78
+ | Маршрут | Метод | Назначение |
79
+ |---|---|---|
80
+ | `/api/department/tasks` | GET | задачи по проектам |
81
+ | `/api/department/task?root=&taskId=` | GET | карточка задачи |
82
+ | `/api/department/activity` | GET | живая активность агентов |
83
+ | `/api/department/approve` | POST | утвердить документ |
84
+ | `/api/department/answer` | POST | ответить на вопрос |
85
+ | `/api/department/amend` | POST | подписать поправку |
86
+ | `/api/department/budget?root=&taskId=` | GET/POST | бюджет и цены |
87
+ | `/api/department/blueprint?root=` | GET | схема проекта |
88
+ | `/api/department/asset?name=` | GET | ассеты офиса |
89
+
90
+ ## Правила процесса
91
+
92
+ 1. Этапы: `analysis (обсуждение) → spec → spec_review → concept → concept_review → executing → release → done`.
93
+ `release` — подготовка к продакшену: `dept_handover` собирает `delivery/` с RUN.md,
94
+ MANUAL-QA.md, CHANGELOG.md и копиями главных документов; без пакета `done` недоступен.
95
+ 2. Утверждения — только человеком (`dept_approve`), стадия двигается только через них.
96
+ 4. Каждый этап закрывается коммитом с тегом `stage-N`; тег пушится вместе с веткой.
97
+ 5. Гейты сбрасываются после коммита: pass предыдущего этапа не переезжает.
98
+ 6. Провал тестов пишет `stages/NN/failure.md`; повтор запрещён, пока не заполнены
99
+ «Анализ» и «План».
100
+ 7. Автономные поправки — не более 5 на задачу, дальше эскалация человеку.
101
+
102
+ ## Совместная работа над концепцией и ТЗ
103
+
104
+ - Каждый специалист пишет свой раздел через `dept_section` (дизайнер — стиль,
105
+ художник — что рисуем, исследователь — данные и статистика, тестер — стратегия
106
+ проверки, архитектор — решения, аналитик — требования).
107
+ - Спорные решения архитектор оформляет как идеи (`dept_ideas`): 2–3 варианта.
108
+ - Специалисты рецензируют идеи (`dept_critique`): `approve`/`reject` и severity.
109
+ Жёсткое отклонение (`high`) убивает идею; два одобрения без жёсткой критики
110
+ принимают её. Отклонённую идею в работу не берут — архитектор предлагает новую.
111
+ - Исследователь может собирать статистику и факты в интернете.
112
+
113
+ ## Автономность (цель вместо таймера)
114
+
115
+ - Руководитель создаёт цель: «довести задачу до done по plan.md» и не закрывает её
116
+ до конца. DSH сам гоняет раунды — таймер не нужен.
117
+ - Каждый раунд: `dept_health` → если `stalled`, найти причину и позвать специалиста:
118
+ данные — researcher, визуал — designer, картинки — artist, конфликт — supervisor,
119
+ архитектура — architect, сборочные правки — senior-coder.
120
+ - `waiting_human` не останавливает: решение принимает команда, записка ждёт человека.
121
+ - Защита от пустых раундов: если 2–3 раунда нет новых событий — зафиксировать
122
+ `blocked` и служебную записку, а не крутиться.
123
+ - Когда задача done — перейти к следующей; когда закрыты все — вечеринка (баннер в офисе).
124
+
125
+ ## Автономность
126
+
127
+ - Руководитель вызывает `dept_health` после каждого шага и не останавливается:
128
+ `stalled` → следующий шаг плана, `waiting_human` → решает тактически сам,
129
+ `ready_to_commit` → проверка и коммит.
130
+ - Для длинных задач создаётся цель (goal), чтобы раунды шли без участия человека.
131
+ - `supervisor` анализирует застой и решает так, как решил бы заказчик.
132
+ - `researcher` ищет в интернете, `designer` подбирает визуал, `artist` рисует через `dept_art`.
133
+ - Параллельная работа: `dept_modules` раздаёт файлы модулям, кодеры не пересекаются,
134
+ `senior-coder` собирает и назначает доработки.
135
+
136
+ ## Тестирование
137
+
138
+ - **Тестер** — автоматические проверки: тесты, инварианты, exit code. Это гейт этапа.
139
+ - **Бета-тестер** — играет/работает как пользователь: проходит сценарии, ловит
140
+ непонятные места, сломанные потоки, визуальные баги; пишет баг-репорт через
141
+ `dept_bug` (шаги, ожидаемое/фактическое, критичность, доказательство).
142
+ Для игры/интерфейса использует `dept_browse`: открывает страницу, кликает,
143
+ вводит и прикладывает скриншот к багрепорту.
144
+ - Перед релизом руководитель запускает бета-тест и разбирает баги: критичные —
145
+ в работу, остальные — в backlog.
146
+
147
+ ### Нативные приложения (C++/Qt)
148
+
149
+ - `dept_gui` запускает программу с аргументами/env и таймаутом, перехватывает вывод.
150
+ - Скриншот: либо приложение само сохраняет кадр по флагу (`--screenshot file.png`,
151
+ `QWidget::grab()` / `QQuickWindow::grabWindow()`), либо внешняя команда
152
+ (`import -window root shot.png` под Xvfb).
153
+ - Рекомендуемый путь для Qt: тестовый хук `--scenario`/`--selftest`, который проходит
154
+ сценарий и сохраняет скриншоты; тогда бета-тест детерминирован и работает в CI.
155
+ - Интерактивная GUI-автоматизация (клики мышью) требует Xvfb/xdotool; в текущем
156
+ окружении их нет, поэтому ставка на хуки приложения и Qt Test.
157
+
158
+ ## Подготовка к релизу (штатная фаза)
159
+
160
+ Офис делает не только продукт, но и его выпуск. Релиз — не разовая просьба, а фаза после `done`:
161
+
162
+ - `dept_start release=true` — бриф задачи получает шаблон `templates/release.md`
163
+ (пакет, документация пользователя, QA-чек-лист, changelog, версия, тег, передача);
164
+ - артефакт: `release/<продукт>-<версия>/` + архив `.zip`;
165
+ - документация: `README.md` (запуск, управление), `MANUAL-QA.md` (ручное тестирование),
166
+ `CHANGELOG.md`, известные ограничения;
167
+ - проверка: тесты проекта, `dept_verify`, бета-тест по чек-листу (`dept_bug`);
168
+ - фиксация: `dept_commit` с тегом `v<версия>`, тег в remote;
169
+ - отчёт: где забрать, как запустить, что проверять руками.
170
+
171
+ Критерий приёмки релиза: человек забирает артефакт и запускает без подсказок;
172
+ документация отвечает на «как запустить», «что умеет», «что ограничено».
173
+
174
+ ## Библиотека документов и журнал событий
175
+
176
+ - Вкладка «Документы» — как почта: слева список документов (поиск по названию,
177
+ фильтр по типу, сортировка по дате), справа содержимое.
178
+ - Типы: служебная записка, отчёт этапа, ревью, баг-репорт, раздел специалиста,
179
+ план переработки, ТЗ, концепция, план, бэклог.
180
+ - Вкладка «События» — список слева, подробности выбранного события справа.
181
+ - Markdown в документах отображается как разметка: заголовки, списки, таблицы,
182
+ inline-код и блоки кода с подсветкой (JS/TS/C++/Python-ключевые слова).
183
+ - Служебные записки, ждущие решения, помечены «ТРЕБУЕТ РЕШЕНИЯ» и подняты наверх
184
+ списка; на доске у задачи бейдж «✍ N», в офисе — жёлтый маркер над руководителем,
185
+ в шапке карточки — счётчик записок.
186
+
187
+ ## Цели (goal)
188
+
189
+ - Перед `update_goal` всегда вызывай `get_goal` и используй актуальную ревизию.
190
+ - Ошибка `stale goal ref` значит, что ревизия уже сменилась: перечитай `get_goal`
191
+ и повтори один раз с новой ревизией — не угадывай.
192
+ - Пауза отдела не ставит цель на паузу: цель живёт отдельно (это DSH).
193
+
194
+ ## Пауза и возобновление
195
+
196
+ - `dept_pause` (или кнопка в карточке) — задача встаёт на паузу: гейты, коммит,
197
+ правки блокируются, токены не тратятся, состояние остаётся на диске.
198
+ - Сторож не будит задачу на паузе.
199
+ - `paused=false` (подпись человека) — работа продолжается с того же места,
200
+ в том числе после выключения/включения сервера.
201
+ - В офисе пауза видна: баннер «отдел на паузе» и руководитель сидит в комнате отдыха.
202
+
203
+
204
+ ## Мультиязычность
205
+
206
+ Интерфейс панели — **русский и английский**:
207
+
208
+ - кнопка **EN/RU** в шапке доски; выбор запоминается (`localStorage['dept-lang']`);
209
+ - по умолчанию — язык браузера, fallback русский;
210
+ - переводятся: навигация, карточка задачи, вкладки, стадии, события, аудит,
211
+ типы документов, роли, бюджет, офис, схема проекта, графики.
212
+ - **Содержимое документов** пишут агенты на языке задачи — это не UI-строки;
213
+ язык документации задаётся в брифе (`lang` в task.md) или в промпте.
214
+
215
+ Словарь: `LOCALES` в `client.js` (ru/en), ключи `dot.case`, интерполяция `{n}`.
216
+ План развития — `docs/I18N.md`.
217
+
218
+ ## Сторож входящих данных
219
+
220
+ - Каждые 5 минут плагин проверяет задачи отделов: новые корректировки (`new`),
221
+ ответы на вопросы (`answered`), замечания к запискам (`changes_requested`).
222
+ - Если появились новые данные — собирает пакет и будит руководителя (`followup`),
223
+ один раз на каждый новый элемент; повторно то же самое не присылает.
224
+ - Руководитель занят — сторож подождёт следующей проверки.
225
+ - **Антизалипание**: если задача активна (не paused/done/blocked), агент простаивает,
226
+ а последнее событие старше 15 минут — сторож будит руководителя подсказкой
227
+ (dept_verify/commit или следующий шаг). Не чаще одного раза в 30 минут на задачу.
228
+
229
+ ## Корректировки
230
+
231
+ - Вкладка «Корректировка» — письмо руководителю: к чему относится (концепция/ТЗ/план/
232
+ код/данные/интерфейс), тема и текст. Сохраняется в истории корректировок.
233
+ - `dept_correction` — руководитель видит список, берёт в работу (`in_progress`),
234
+ собирает специалистов на анализ и закрывает (`done`) с итогом.
235
+ - По корректировкам дорабатываются концепция, ТЗ и план (`dept_amend`, `dept_section`).
236
+
237
+ ## Вопросы и служебные записки
238
+
239
+ Вопрос к человеку не останавливает работу:
240
+
241
+ 1. `dept_ask` — вопрос записан, отдел продолжает.
242
+ 2. `dept_propose` — супервайзер предлагает варианты решения.
243
+ 3. `dept_critique` — специалисты критикуют; принятое решение фиксируется.
244
+ 4. `dept_memo` — служебная записка: вопрос, варианты, критика, решение команды
245
+ (файл `docs/department/<task>/memos/<question>.md`).
246
+ 5. `dept_review` — человек утверждает (`approve`) или пишет замечания (`changes`).
247
+ 6. `dept_rework` — архитектор готовит план переработки по замечаниям
248
+ (`docs/department/<task>/rework/<question>.md`).
249
+
250
+ ## Мультипроект
251
+
252
+ - Вкладка «Проекты» — агрегаты по корням: задачи, стадии, бюджет, последнее событие.
253
+ - Каждый корень — отдельный отдел: задачи создаются через `dept_start root=...`,
254
+ доска показывает все проекты, фильтр — по проекту.
255
+ - Для параллельной работы внутри проекта: `dept_modules` (владение файлами) +
256
+ `dept_worktree` (изолированные каталоги на модуль), слияние — сеньор-кодер.
257
+ - Лимит одновременных кодеров — `maxInstances` у роли.
258
+
259
+ ## Художник и референсы
260
+
261
+ - `dept_art` рисует по сетке символов: вход — `rows` (символ = пиксель) и `palette`
262
+ (символ → #rrggbb), выход — PNG (RGBA), масштаб 1–16.
263
+ - `dept_pixelize` берёт PNG/JPEG/WebP, уменьшает до сетки (4–96), квантует в палитру
264
+ (2–64 цвета или заданную), сохраняет PNG и возвращает `rows` + `palette` —
265
+ художник правит пиксели вручную, чтобы получить похожий, но свой спрайт.
266
+ - Референс — для стиля (палитра, пропорции), не для копирования чужой графики.
267
+
268
+ ### Художник работает не спеша
269
+
270
+ - Скорость не критерий: качество важнее. Художник рисует по частям:
271
+ референс/палитра → базовые формы → детали → проверка → композиция.
272
+ - Каждый шаг — отдельный файл-чекпоинт (`assets/...png`), его можно пересмотреть.
273
+ - Большая картинка не рисуется одним куском: маленькие спрайты + `dept_compose`.
274
+ - Роль: `reasoning: high`, до 6 попыток; руководитель дробит задачу на элементы,
275
+ а не даёт художнику «нарисуй всё».
276
+
277
+ ## Ограничения
278
+
279
+ - Офис и схема — визуализация по данным сессий; арт простой.
280
+ - Blueprint строит только статические импорты (JS/TS/C/C++/Python).
281
+ - У каждой роли лимит одновременных экземпляров (`maxInstances`), у кодера по умолчанию 2:
282
+ руководитель не может запускать больше кодеров, чем указано.
283
+ - Роли можно включать/выключать (кроме manager/coder/tester); `beta-tester`
284
+ по умолчанию выключен — запуск приложений и поток скриншотов дороги по ресурсам.
285
+ - Бюджет считает usage, который отдают адаптеры модели; цены задаются вручную.
286
+
287
+ ## Лицензия
288
+
289
+ MIT. Ассеты офиса (папка `assets/`) — собственные и/или CC0; сторонние паки не входят.