@vadim-epifanov/dsh-orchestrator 1.0.0 → 1.1.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/INSTRUCTION.md ADDED
@@ -0,0 +1,183 @@
1
+ # Инструкция: правила оркестратора
2
+
3
+ Короткая инструкция по файлу правил плагина «Оркестратор»: из чего он состоит, как его создать в новом рабочем пространстве и что в нём писать нельзя. Установка, обновление и настройки — в [README.md](README.md); здесь только `rules.md`.
4
+
5
+ Читают её двое: DSH, когда пользователь просит «создай правила для пространства X», и человек, которому нужно понять, где что лежит.
6
+
7
+ ## 1. Что это за файл и где он лежит
8
+
9
+ Правила, шаблоны и роли пространства живут в одном файле:
10
+
11
+ ```text
12
+ <пространство>\.orch\orchestrator\rules.md
13
+ ```
14
+
15
+ На Windows, например:
16
+
17
+ ```text
18
+ C:\Work\my-project\.orch\orchestrator\rules.md
19
+ ```
20
+
21
+ - **Одно пространство — один файл.** Имя файла одинаково для всех пространств, пространство задаёт каталог: `RULES_SUBDIR` и `RULES_FILE_NAME`, путь собирает `rulesFileFor`.
22
+ - **Один файл содержит всё:** текст правил, шаблоны заданий и роли с их моделями.
23
+ - **Каталога может не быть.** `.orch\orchestrator` создаётся при первом сохранении (`writeTextFile`).
24
+ - **Отсутствие файла — норма**: пространство просто неактивно, пока правила пусты (`workspaceUse`, `workspaceDiagnostics`).
25
+
26
+ Плагин читает файл сам — при старте и после каждого сохранения; страница настроек «Оркестратор» правит тот же файл.
27
+
28
+ ## 2. Как создать `rules.md` по запросу пользователя
29
+
30
+ Порядок для DSH: только файл правил, ничего не запускать и не удалять.
31
+
32
+ 1. **Определить каталог пространства.** Это корень рабочего каталога (`C:\Work\my-project`), а не подкаталог `.orch`: путь к файлу — `<корень>\.orch\orchestrator\rules.md`. Каталог должен быть в списке рабочих пространств плагина (`<профиль>\orchestrator\settings.json`, ключ `workspaces[].path`): правила читаются только для известных пространств (`resolveWorkspace`, `writeRules`). Нет в списке — сначала человек добавляет пространство на странице «Оркестратор».
33
+ 2. **Создать каталог** `.orch\orchestrator`, если его нет. Плагин делает это сам при сохранении, ручное создание ничего не ломает.
34
+ 3. **Записать файл** с тремя разделами в фиксированном порядке: `RULES` → `TEMPLATES` → `ROLES` (`composeRules`). Каждый тег — отдельной строкой и ровно в таком написании: границы ищутся по строке целиком (`splitRules`).
35
+ 4. **Проверить первую непустую строку:** она должна быть ровно `<!-- RULES -->`. По ней импорт отличает файл оркестратора от чужого (`parseImportFile`); текст вне блоков при чтении отбрасывается молча (`splitRules`).
36
+ 5. **Ничего не удалять в существующем файле без явной просьбы.** Сохранение из интерфейса перезаписывает файл целиком тем, что было на странице (`writeRules`).
37
+
38
+ Если файл правят руками, пока открыта страница настроек, сохранение со страницы будет отклонено с кодом `conflict`: страница помнит состояние файла на момент загрузки и не даёт затереть чужую правку. Это нормально и защищает правку — скопируйте свой текст из редактора, нажмите «Обновить» (она снимает несохранённый черновик и показывает файл как есть) и внесите правку заново.
39
+
40
+ Кодировка — UTF-8. BOM ставить не нужно, но и не мешает: при разборе он снимается (раздел 5).
41
+
42
+ Заготовка, которую можно скопировать и заполнить:
43
+
44
+ ```markdown
45
+ <!-- RULES -->
46
+ <!-- RULES_END -->
47
+
48
+ <!-- TEMPLATES -->
49
+ <!-- TEMPLATES_END -->
50
+
51
+ <!-- ROLES -->
52
+ <!-- ROLES_END -->
53
+ ```
54
+
55
+ Пустой раздел остаётся парой тегов, поэтому файл всегда одной формы (`rulesSection`).
56
+
57
+ ## 3. Устройство файла: три раздела
58
+
59
+ | Раздел | Границы | Что внутри |
60
+ |---|---|---|
61
+ | Правила | `<!-- RULES -->` … `<!-- RULES_END -->` | текст, который оркестратор читает как свои указания |
62
+ | Шаблоны | `<!-- TEMPLATES -->` … `<!-- TEMPLATES_END -->` | блоки `<!-- TEMPLATE_<slug> - NAME: <название> -->` … `<!-- TEMPLATE_<slug>_END -->` |
63
+ | Роли | `<!-- ROLES -->` … `<!-- ROLES_END -->` | блоки `<!-- ROLE - ID: <id> … -->` … `<!-- ROLE_END - ID: <id> -->` |
64
+
65
+ Теги разделов — единственные границы (`RULES_TAG`, `TEMPLATES_TAG`, `ROLES_TAG`); заголовки `## …` внутри блоков — обычный текст, ролей и шаблонов из них не создаётся (`splitRules`).
66
+
67
+ ### Правила
68
+
69
+ Текст между `<!-- RULES -->` и `<!-- RULES_END -->` — указания оркестратору: как делить работу, какие роли звать, что запрещено. Внутри можно писать обычный markdown, включая заголовки `## …` и таблицы.
70
+
71
+ ### Шаблоны
72
+
73
+ - Открывающий тег: `<!-- TEMPLATE_<slug> - NAME: <название> -->`; ключ `- NAME:` необязателен (`TEMPLATE_TAG_PATTERN`).
74
+ - Slug — латиница, цифры, `-` и `_`, от 1 до 32 символов (`TEMPLATE_SLUG_PATTERN`). Точка, пробел и кириллица в теге недопустимы: такой тег не распознаётся.
75
+ - Закрывающий тег повторяет slug: `<!-- TEMPLATE_<slug>_END -->` (`TEMPLATE_END_TAG_PATTERN`).
76
+ - Транслитерация кириллицы работает только при разборе свободного markdown (`templateSlug`): в теге slug пишется латиницей вручную.
77
+ - Раздел можно написать и обычным markdown — каждый заголовок `## ` станет отдельным шаблоном (`parseTemplatesSection`). Теги надёжнее: видно границы.
78
+
79
+ ### Роли
80
+
81
+ Открывающий тег:
82
+
83
+ ```text
84
+ <!-- ROLE - ID: <id> NAME: <имя> PROVIDER: <провайдер> MODEL: <модель> EFFORT: <уровень> -->
85
+ ```
86
+
87
+ - `ID` обязателен и стоит первым; id — латиница, цифры, `.`, `-`, `_`, до 32 символов (`ROLE_ID_PATTERN`).
88
+ - Ключи только `NAME`, `PROVIDER`, `MODEL`, `EFFORT`; плагин пишет их в этом порядке (`ROLE_TAG_KEYS`, `roleRulesTag`).
89
+ - Пустые поля означают «взять из настроек»: сначала запись роли в `settings.json`, затем модель агентов по умолчанию (`mergeRoleMeta`; `effectiveModel`). Имя не задано — роль называется своим id (`workspaceUse`).
90
+ - `PROVIDER: orchestrator` — особое значение: роль получает модель того агента, который её запустил (`ORCHESTRATOR_PROVIDER`, `effectiveModel`).
91
+ - Тело блока начинается заголовком `## <id>`; он только для читаемости и при разборе отбрасывается (`roleTextOf`).
92
+ - Закрывающий тег повторяет id: `<!-- ROLE_END - ID: <id> -->` (`ROLE_END_TAG_PATTERN`). Если id не совпал, в лог уходит предупреждение, а роль читается по открывающему тегу (`splitRules`).
93
+ - Значение поля не может содержать ключ вида `MODEL:` — см. раздел 5.
94
+
95
+ ## 4. Как это работает вместе
96
+
97
+ - **Правила** — что делать: как делить работу, какие роли звать, что запрещено.
98
+ - **Шаблоны** — готовые формулировки, которые оркестратор подставляет в задания ролям.
99
+ - **Роли** — кто делает и на какой модели; по каждой роли регистрируется инструмент `delegate_<id>` (`ROLE_PREFIX`, `createRoleTool`).
100
+
101
+ **Что видит оркестратор.** Правила пространства целиком входят в системный промпт вместе с перечнем ролей; если шаблоны есть, в промпт попадает указание, в каком файле их читать (`orchestratorPrompt`). Сами шаблоны в промпт не вставляются (`orchestratorPrompt`) — их читают перед составлением задания.
102
+
103
+ **Что видит роль.** Только свой текст из блока роли и текст задания (`composeTaskPrompt`). Правила оркестратора роли не передаются (`runRole`), переписку заказчика роль не видит: всё нужное должно быть в задании.
104
+
105
+ **Модель.** Берётся из тега роли, пустые поля — из настроек (раздел 3). Смена модели на странице настроек применяется к открытым сессиям без перезапуска: сохранение переписывает файл и обновляет кэш правил (`writeRules`) и пересобирает инструменты (`syncLiveAgents`; `updateRoleTool`).
106
+
107
+ **Когда плагин работает.** Оркестратор включён в главных настройках, пространство включено, правила непусты, у каждой роли есть текст и модель, есть провайдер субагентов с выбором модели (`workspaceUse`). Иначе инструменты ролей не регистрируются, а промпт пуст.
108
+
109
+ ## 5. Запреты и типичные ошибки
110
+
111
+ **Служебные теги в тексте.** В тексте правил, роли и шаблона нельзя писать подстроки из `SERVICE_TAGS`:
112
+
113
+ ```text
114
+ <!-- RULES --> <!-- RULES_END --> <!-- TEMPLATES --> <!-- TEMPLATES_END -->
115
+ <!-- ROLES --> <!-- ROLES_END --> <!-- TEMPLATE_ <!-- ROLE <!-- ROLE_END
116
+ ```
117
+
118
+ Проверка идёт по вхождению подстроки, а не по строке целиком (`serviceTagIn`), поэтому запрещены и `<!-- RULES`, `<!-- TEMPLATES`, `<!-- ROLES`, `<!-- TEMPLATE_`, `<!-- ROLE `, `<!-- ROLE_END` в любом месте текста. Сохранение отклоняется с сообщением, в каком блоке тег (`rejectServiceTag`; `writeRules`): при следующем чтении такой тег оборвёт блок, и текст пропадёт молча (`SERVICE_TAGS`).
119
+
120
+ **Дубли id ролей.** Два блока с одинаковым `ID` — сохранение отклоняется (`writeRules`). Если дубль уже есть в файле, плагин предупреждает в лог и берёт последний блок (`splitRules`).
121
+
122
+ **Заголовки `## …`** — обычный текст. Единственное исключение — первая строка тела роли `## <id>`: она отбрасывается при разборе (`roleTextOf`).
123
+
124
+ **Ключи в значениях метаданных.** Значение поля в теге роли не может содержать подстроку вида `СЛОВО:` — заглавные латинские буквы, цифры и `_` перед двоеточием (`ROLE_TAG_KEY_PATTERN`). Известный ключ (`MODEL:` и подобные) разорвёт тег и подменит соседнее поле, неизвестный — оставит роль с пустыми метаданными (`parseRoleTag`). Сохранение со страницы в таком случае отклоняется: «метаданные роли … не сохранятся» (`assertRulesRoundTrip`).
125
+
126
+ **Типичные ошибки:**
127
+
128
+ - **BOM в начале файла — не ошибка.** `splitRules` сравнивает строки после `trim`, а `trim` удаляет U+FEFF, поэтому файл с BOM читается так же, как без него: первый тег совпадает. Хранить файл лучше без BOM — это гигиена, а не причина пустых правил: правила читаются пустыми, когда тега `<!-- RULES -->` нет или он стоит не отдельной строкой (пункт ниже).
129
+ - **Тег не отдельной строкой.** Границы разделов ищутся по строке, равной тегу (`splitRules`); тег посреди абзаца не сработает. Тег шаблона должен заканчиваться на `-->` (`TEMPLATE_TAG_PATTERN`, `TEMPLATE_END_TAG_PATTERN`), иначе он не распознаётся; у тега роли хвост после `-->` оставляет роль без метаданных (`ROLE_TAG_PATTERN`).
130
+ - **Нет закрывающего тега.** Незакрытый блок дочитывается до конца файла, в лог уходит предупреждение (`splitRules`): роль без `<!-- ROLE_END -->` тянет за собой следующий текст.
131
+ - **Негодный slug шаблона.** При чтении — предупреждение в лог, блок не читается (`splitRules`); при сохранении со страницы — отказ с подсказкой про slug (`writeRules`).
132
+ - **Файл вне известных пространств.** Правила читаются только для каталогов из настроек (`resolveWorkspace`): файл в другом каталоге никто не увидит.
133
+
134
+ ## 6. Пример полного файла
135
+
136
+ Одна роль, один шаблон, короткие правила. Замените `<провайдер>`, `<модель>` и `<уровень>` на реальные значения или оставьте поля пустыми — тогда они возьмутся из настроек.
137
+
138
+ ```markdown
139
+ <!-- RULES -->
140
+ Ты оркестратор этого пространства. Сам файлы не правишь: делишь работу между ролями.
141
+
142
+ - Задачу, которая требует правок, начинай с плана и согласуй его с пользователем.
143
+ - В задание роли вставляй нужный шаблон из раздела `TEMPLATES` целиком.
144
+ - Двум ролям не давай один и тот же файл: правки идут в рабочий каталог без отката.
145
+ <!-- RULES_END -->
146
+
147
+ <!-- TEMPLATES -->
148
+ <!-- TEMPLATE_zadanie - NAME: Задание на правку -->
149
+
150
+ ЗАДАЧА: <что должно получиться>
151
+ ФАЙЛЫ:
152
+ менять: <пути>
153
+ читать: <пути>
154
+ ПРИЗНАКИ ГОТОВНОСТИ:
155
+ 1. <проверяемая формулировка>
156
+ ОТВЕТ: блоки СДЕЛАНО / ФАЙЛЫ / ПРОВЕРКА / ОТСТУПЛЕНИЯ / РИСКИ.
157
+ <!-- TEMPLATE_zadanie_END -->
158
+ <!-- TEMPLATES_END -->
159
+
160
+ <!-- ROLES -->
161
+ <!-- ROLE - ID: executor NAME: Исполнитель PROVIDER: <провайдер> MODEL: <модель> EFFORT: <уровень> -->
162
+ ## executor
163
+
164
+ Ты исполнитель. Правишь только файлы из задания и не выходишь за его границы. Переписку заказчика ты не видишь — всё нужное есть в тексте задания.
165
+
166
+ Верни блоки `СДЕЛАНО / ФАЙЛЫ / ПРОВЕРКА / ОТСТУПЛЕНИЯ / РИСКИ`.
167
+ <!-- ROLE_END - ID: executor -->
168
+ <!-- ROLES_END -->
169
+ ```
170
+
171
+ Разбор по коду: теги парные, первая строка — `<!-- RULES -->`, slug `zadanie` — латиница до 32 символов, у роли тег начинается с `ID`, тело открывается заголовком `## executor`, закрывающий тег повторяет id. Такой файл читается без предупреждений.
172
+
173
+ ## 7. Что делать, если файл уже есть
174
+
175
+ 1. Прочитать файл целиком и править точечно: не пересобирать с нуля и не терять чужие правки.
176
+ 2. Не смешивать два способа: сохранение со страницы перезаписывает файл целиком тем, что было в форме (`writeRules`). Правили руками — перечитайте страницу до сохранения.
177
+ 3. Теги на месте, разделы в порядке — файл читается как есть. Расхождения в id ролей и незакрытые блоки видны в логе плагина предупреждениями (`splitRules`).
178
+
179
+ **Файл в старом формате.** В файле прежней версии тегов формата 2 нет вовсе: это обычный markdown с текстом правил, шаблонами и заголовками ролей. Поэтому плагин читает его как пустой — 0 правил, 0 ролей, 0 шаблонов, пространство неактивно (блокировки `no-orchestrator-rules` и `no-roles`). Сохранение со страницы его отклоняет с кодом `invalid` и сообщением, что в файле нет тегов: без этой защиты текст был бы стёрт (`writeRules`). Файл выгрузки прежней версии, у которого первая строка — `<!-- dsh-orchestrator bundle: 1 -->`, при импорте отвергается: первой непустой строкой должна быть `<!-- RULES -->` (`parseImportFile`).
180
+
181
+ Поэтому файл переписывают в формат 2 вручную: сначала копия в `.orch\orchestrator\backup-format1-<дата>\`, затем новый `rules.md` по разделам 2–3. Копию плагин не делает — её создаёт человек.
182
+
183
+ **Файл без тегов** (обычный markdown с правилами и заголовками `## `) плагин читает как пустой, а сохранение со страницы отклоняет с сообщением про формат 2 — иначе текст был бы стёрт (`writeRules`). Такой файл тоже переписывают вручную.
package/README.md CHANGED
@@ -1,22 +1,31 @@
1
1
  # Оркестратор
2
2
 
3
- Плагин DSH, который раздаёт задачу субагентам: у каждой роли свои правила и своя модель, а число ролей, работающих одновременно, ограничено. Настройки задаются отдельно для каждого рабочего пространства (рабочей папки), поэтому в одном проекте правила могут быть одни, в другом — другие.
3
+ Плагин DSH, который раздаёт задачу ролям: у каждой роли свои правила и своя модель, а число ролей, работающих одновременно, ограничено. Настройки задаются отдельно для каждого рабочего пространства (рабочей папки), поэтому в одном проекте правила могут быть одни, в другом — другие.
4
4
 
5
5
  Для кого: для тех, кто работает в DSH с несколькими проектами и хочет, чтобы исследование, проверка, правка кода и документация шли параллельно, каждая на подходящей модели, но по общим правилам проекта.
6
6
 
7
+ ## Словарь
8
+
9
+ - **Роль** — сущность плагина: имя, провайдер, модель, уровень рассуждений, правила и инструмент `delegate_<id>`. Роль задаётся блоком `<!-- ROLE - ID: <id> … -->` … `<!-- ROLE_END - ID: <id> -->` в разделе `ROLES` файла `rules.md`.
10
+ - **Субагент** — механизм рантайма, которым роль запускается: провайдер субагентов, глубина делегирования (роль не заводит своих субагентов), сервис `c.subagents`. Роль настраивают, субагент исполняет запуск.
11
+
7
12
  ## Возможности
8
13
 
9
14
  - **Роли с собственными правилами и моделями.** У каждой роли свой текст правил, а также свой провайдер, модель и уровень рассуждений. Типовой набор ролей — `explorer` (исследователь), `reviewer` (проверяющий), `executor` (исполнитель), `documentalis` (документалист), `master` (мастер). По id роли регистрируется инструмент `delegate_<id>`, которым оркестратор её запускает.
10
15
  - **Ограничение числа одновременных ролей.** Для каждого пространства задаётся `maxParallel` (от 1 до 8): лишние вызовы не отклоняются, а ждут очереди.
11
16
  - **Настройки на каждое рабочее пространство.** Правила, шаблоны, роли и предел параллельности — свои у каждой рабочей папки; главный выключатель и модель агентов по умолчанию — общие для всех.
12
17
  - **Страница настроек «Оркестратор» в Web UI** с блоками:
18
+ - строка «Инструкция по файлу правил» со ссылкой, открывающей `INSTRUCTION.md`, — сразу под путём к `settings.json`, над главными настройками;
13
19
  - «Главные настройки» — выключатель «Оркестратор включён» и модель агентов по умолчанию;
14
20
  - «Настройки для рабочих пространств» — список пространств, каталог, `maxParallel` и роли;
15
21
  - «Правила оркестратора»;
16
22
  - «Шаблоны оркестратора»;
17
23
  - «Роли».
18
- - **Правила и шаблоны — обычные файлы внутри рабочей папки:** `.orch\orchestrator\rules.md` и `.orch\orchestrator\templates.md`. Их можно править и на странице настроек, и любым редактором.
19
- - **Путь к файлу в настройках — ссылка:** клик открывает `rules.md` или `templates.md` приложением, которое система назначила для файлов `*.md`.
24
+ - **Правила, шаблоны и роли — один обычный файл внутри рабочей папки:** `.orch\orchestrator\rules.md`. Его можно править и на странице настроек, и любым редактором.
25
+ - **Выгрузка в файл — то же содержимое и тот же порядок разделов, без собственной шапки:** кнопка «Сохранить» собирает выгрузку из формы; для файла, записанного самим плагином, она совпадает с `rules.md` побайтово, а у правленного руками лишние пустые строки по краям блоков могут исчезнуть — текст при этом не теряется; импорт читает такой файл тем же разбором.
26
+ - **Сохранение без перезапуска.** Изменения, сохранённые на странице настроек, применяются к уже открытым сессиям: инструменты ролей и их модели пересобираются на месте.
27
+ - **Защита от потери правки.** Страница запоминает состояние файла правил на момент загрузки и сверяет его при сохранении: если файл успели изменить — другая вкладка, другая роль или правка руками, — сохранение отклоняется с кодом `conflict`, а введённый текст остаётся в редакторе. Кнопка «Обновить» снимает несохранённый черновик и показывает файл как есть, поэтому нужный текст скопируйте до обновления.
28
+ - **Путь к файлу в настройках — ссылка:** клик открывает `rules.md` приложением, которое система назначила для файлов `*.md`; у раздела шаблонов ссылка ведёт в тот же файл.
20
29
 
21
30
  ## Требования
22
31
 
@@ -33,14 +42,26 @@
33
42
  ```
34
43
  plugin_manager
35
44
  action: install_bundle
36
- target: "@vadim-epifanov/dsh-orchestrator@1.0.0"
45
+ target: "@vadim-epifanov/dsh-orchestrator@1.1.0"
37
46
  ```
38
47
 
39
48
  После установки перезапустите DSH, откройте в Web настройки «Оркестратор», включите плагин, добавьте рабочее пространство, заполните правила и роли.
40
49
 
50
+ Инструмент `plugin_manager` доступен не в каждом профиле: он входит в пресет Creator, а в пресете standard его нет. Вызов требует разрешения `danger-full-access` либо одобрения пользователя. Если инструмента нет, тот же бандл ставится со страницы Plugins в веб-интерфейсе DSH.
51
+
41
52
  ## Обновление версии
42
53
 
43
- Та же команда с новым номером версии:
54
+ Обновление — два шага: сначала снять установленный бандл, затем поставить новый. Поставить новую версию поверх установленной можно не всегда: на профиле с включённым HMR установщик может отклонить установку с кодом `already-installed` и сам посоветовать сначала вызвать `remove_bundle` — тогда снятие обязательно.
55
+
56
+ Снять текущую версию:
57
+
58
+ ```
59
+ plugin_manager
60
+ action: remove_bundle
61
+ target: "@vadim-epifanov/dsh-orchestrator"
62
+ ```
63
+
64
+ Поставить новую:
44
65
 
45
66
  ```
46
67
  plugin_manager
@@ -48,7 +69,25 @@ plugin_manager
48
69
  target: "@vadim-epifanov/dsh-orchestrator@<новая версия>"
49
70
  ```
50
71
 
51
- После установки перезапустите DSH. Настройки профиля и файлы правил в рабочих папках при обновлении остаются на месте.
72
+ После установки перезапустите DSH: без перезапуска останется прежний код плагина. Настройки профиля и файлы правил в рабочих папках при обновлении остаются на месте.
73
+
74
+ ### Если обновляетесь с версии старше 1.1.0
75
+
76
+ Начиная с 1.1.0 формат файла правил изменился. Раньше текст правил лежал в `rules.md`, шаблоны — в отдельном `templates.md`, а роли задавались заголовками `## <id>`. Теперь всё в одном `rules.md`: три раздела в скрытых тегах `<!-- RULES -->`, `<!-- TEMPLATES -->` и `<!-- ROLES -->`, а метаданные роли — в её открывающем теге. `templates.md` больше не читается и не пишется.
77
+
78
+ Автоматически изменение не применяется: плагин не переписывает и не переносит старые файлы. После обновления старый `rules.md` читается как пустой — 0 правил, 0 ролей, 0 шаблонов, пространство неактивно, — а сохранение со страницы отклоняется, иначе текст был бы стёрт.
79
+
80
+ Перенос делает человек, вручную, в таком порядке:
81
+
82
+ 1. Сделайте копию каталога `.orch\orchestrator\` целиком: плагин резервных копий не создаёт.
83
+ 2. Обновите пакет и перезапустите DSH (см. выше).
84
+ 3. Приведите `rules.md` к формату 2 — вручную или взяв за основу `examples\rules.example.md`.
85
+ 4. Перенесите шаблоны из старого `templates.md` в раздел `TEMPLATES`.
86
+ 5. Откройте страницу настроек и убедитесь, что правила, роли и шаблоны видны.
87
+
88
+ **Порядок важен.** Если привести файл к формату 2 до обновления сборки, старая сборка прочитает его по заголовкам, и в правила попадут теги. Сначала обновление и перезапуск, потом файл.
89
+
90
+ У кого файлы уже в формате 2, делать ничего не нужно.
52
91
 
53
92
  ## Удаление
54
93
 
@@ -64,16 +103,56 @@ plugin_manager
64
103
 
65
104
  | Что | Где |
66
105
  |---|---|
67
- | Настройки плагина (формат 2, ключей и секретов в нём нет) | `<каталог профиля>\orchestrator\settings.json` |
68
- | Правила оркестратора и ролей | `<рабочее пространство>\.orch\orchestrator\rules.md` |
69
- | Шаблоны заданий и карточка задачи | `<рабочее пространство>\.orch\orchestrator\templates.md` |
106
+ | Настройки плагина (формат 2, ключей и секретов в нём нет; роли — ключ `workspaces[].roles`) | `<каталог профиля>\orchestrator\settings.json` |
107
+ | Правила оркестратора, шаблоны и роли — всё в одном файле: разделы `RULES`, `TEMPLATES`, `ROLES`; метаданные роли — в её открывающем теге | `<рабочее пространство>\.orch\orchestrator\rules.md` |
70
108
  | Карточки задач | `<рабочее пространство>\.orch\tasks\` |
71
109
 
110
+ Шаблоны заданий и формат карточки задачи — раздел `TEMPLATES` того же `rules.md`; отдельного `templates.md` больше нет, плагин его не читает и не пишет. Каталог с копиями прежних файлов (`rules.md` и `templates.md` прежнего формата) — `<рабочее пространство>\.orch\orchestrator\backup-format1-<дата>\` — создаёт человек перед переводом файла в формат 2; плагин его не создаёт, не трогает и в своих сообщениях не упоминает — имя каталога это соглашение для человека. Сами карточки задач оркестратор пишет в `.orch\tasks\` — это отдельный каталог, а не файл шаблонов.
111
+
112
+ Метаданные роли — имя, провайдер, модель и уровень рассуждений — хранятся в `rules.md`: в открывающем теге `<!-- ROLE - ID: <id> NAME: … PROVIDER: … MODEL: … EFFORT: … -->` блока роли, ключи в этом порядке, пустые не пишутся. Роль — это блок до закрывающего тега `<!-- ROLE_END - ID: <id> -->`: удалили блок — роль удалена (заголовок `## <id>` внутри блока только для читаемости). Записи ролей в `settings.json` (ключ `workspaces[].roles`) — откат: из них берётся то, чего нет в теге (пока файла правил нет вовсе — всё описание роли); при первом сохранении со страницы метаданные попадают в теги, а записи ролей из `settings.json` удаляются. Старый ключ `workspaces[].subagents` читается, но при сохранении заменяется на `roles`.
113
+
72
114
  Каталог профиля — это значение `$env:DSH_PROFILE_DIR` в запущенной сессии DSH.
73
115
 
116
+ ## Формат файла правил
117
+
118
+ `rules.md` состоит из трёх разделов, и границы разделов задают только скрытые теги: заголовки `## …` и `### …` внутри блоков — обычный текст, роли из них не создаются, а пустой раздел остаётся парой тегов. При чтении порядок разделов не важен: каждый раздел находится по своим тегам в любом порядке; при записи плагин всегда пишет их в порядке `RULES` → `TEMPLATES` → `ROLES`:
119
+
120
+ ```markdown
121
+ <!-- RULES -->
122
+ <правила оркестратора>
123
+ <!-- RULES_END -->
124
+
125
+ <!-- TEMPLATES -->
126
+ <!-- TEMPLATE_plan - NAME: План -->
127
+
128
+ <текст шаблона>
129
+ <!-- TEMPLATE_plan_END -->
130
+ <!-- TEMPLATES_END -->
131
+
132
+ <!-- ROLES -->
133
+ <!-- ROLE - ID: explorer NAME: Исследователь PROVIDER: <провайдер> MODEL: <модель> EFFORT: <уровень> -->
134
+ ## explorer
135
+
136
+ <правила роли explorer>
137
+ <!-- ROLE_END - ID: explorer -->
138
+ <!-- ROLES_END -->
139
+ ```
140
+
141
+ Заголовок `## <id>` сразу под открывающим тегом плагин пишет сам при сборке файла; он нужен только для читаемости и при разборе отбрасывается — правила роли начинаются с текста под ним.
142
+
143
+ `slug` шаблона — латиница, цифры, `-` и `_`, до 32 символов; кириллическое название транслитерируется («Формат карточки задачи» → `format-kartochki-zadachi`), а ключ `- NAME:` можно не писать. Транслитерация работает только при разборе свободного markdown, где название берётся из заголовка `## `, — там негодное название даёт `template-N`. В теге `<!-- TEMPLATE_<slug> … -->` slug пишется латиницей вручную, и тег с негодным slug (например, с пробелом) при чтении не распознаётся: в лог плагина уходит предупреждение, а блок не читается; при сохранении со страницы такой тег даёт отказ с подсказкой про slug. Если id в закрывающем теге роли не совпал с открывающим, роль читается по открывающему тегу, а в лог плагина пишется предупреждение; незакрытый блок дочитывается до конца файла — тоже с предупреждением.
144
+
145
+ Служебные теги в тексте запрещены: если текст правил оркестратора, текст роли или текст шаблона содержит любую из подстрок `<!-- RULES`, `<!-- RULES_END`, `<!-- TEMPLATES`, `<!-- TEMPLATES_END`, `<!-- ROLES`, `<!-- ROLES_END`, `<!-- ROLE `, `<!-- ROLE_END`, `<!-- TEMPLATE_`, сохранение отклоняется с сообщением, в каком блоке тег. Иначе тег оборвал бы блок при следующем чтении, и текст пропал бы молча.
146
+
147
+ Дубли id ролей запрещены: два блока с одинаковым `ID` — сохранение отклоняется. Если такой дубль уже есть в файле, плагин пишет предупреждение в лог и берёт последний блок.
148
+
149
+ Выгрузка кнопкой «Сохранить» собирается из того же содержимого и тем же порядком разделов, что и `rules.md`: те же теги, без собственной шапки. У файла, записанного самим плагином, она совпадает с ним побайтово; у файла, правленного руками, лишние пустые строки по краям блоков при выгрузке исчезают — тексты обрезаются по краям, — но сам текст не теряется. Импорт распознаёт формат 2 по первой непустой строке: ею должен быть `<!-- RULES -->` — любая выгрузка `rules.md` начинается с него, потому что она собрана из того же файла. Файл, который начинается с чего-то другого (например, README), отвергается с сообщением «это не файл оркестратора». Файл выгрузки прежней версии (первая строка `<!-- dsh-orchestrator bundle: 1 -->`) исключением больше не является: при импорте он отвергается так же, как чужой файл, и его нужно переписать в формат 2 (см. «Обновление версии»).
150
+
151
+ Файл старого формата (есть текст, нет тегов формата 2) плагин читает как пустой, а сохранение такого файла отклоняется — его нужно привести к формату 2. Копию прежнего файла перед этим делает человек, плагин её не создаёт (см. «Обновление версии»).
152
+
74
153
  ## Подробная инструкция
75
154
 
76
- Полная инструкция — установка, обновление, перенос правил между пространствами и разбор типовых ошибок — лежит в файле `orchestrator_setup.md`. Он идёт отдельно от пакета, в архиве `orchestrator_setup.zip`, и в пакет не входит.
155
+ Краткая инструкция по файлу правил лежит рядом с плагином, в каталоге пакета: `INSTRUCTION.md`; её же можно открыть со страницы настроек ссылкой «Инструкция по файлу правил». Полная инструкция — установка, обновление, перенос правил между пространствами и разбор типовых ошибок — поставляется отдельным архивом `orchestrator_setup.zip` и в пакет не входит: у потребителя из npm её нет. В архиве — та же инструкция `orchestrator_setup.md` и текущая сборка плагина в каталоге `dsh-orchestrator\` (код, локали и тесты); каталог `examples\` с образцами файла правил и файла настроек лежит в корне архива, рядом с `dsh-orchestrator\`. Архив пересобирается из текущих файлов, поэтому конкретные размеры и хеши здесь не приводятся. Если архива под рукой нет, ориентируйтесь на этот README.
77
156
 
78
157
  ## Лицензия
79
158