dwe render workspace

Рендерит принадлежащие workspace пакеты шаблонов в корень проекта: корневые документы для агентов, .mcp.json, конфигурацию инструментов вроде .ralphex/ или другие общие файлы. Пакеты находятся в workspace/templates/workspace/<pack>/; пути назначения считаются относительно каталога с корневым workspace.yml.

Workspace-пакеты используют общую схему manifest и локальные оверрайды. У них нет выбора сервисов, разрешения extends или неявного пакета по умолчанию.

Активация и слои конфигурации

Объявите пакеты для рендера в списке верхнего уровня render.workspace:

render:
  workspace: [ralphex, root-agents]

Без аргументов dwe render workspace рендерит этот список в объявленном порядке. Отсутствующий или пустой список выводит no workspace packs configured in render.workspace и завершает команду успешно. Каждый выбранный пакет должен существовать; отсутствие пакета — ошибка, без резервного варианта.

Список следует обычному порядку слоёв конфигурации: корневой workspace.yml → workspace/defaults.yml → workspace/local.yml. Поздние списки полностью заменяют ранние, а не дополняют их. Чтобы локально отключить настроенные пакеты:

render:
  workspace: []

Имена пакетов должны соответствовать [A-Za-z0-9][A-Za-z0-9_-]*; повторяющиеся имена запрещены. Эти проверки выполняются при рендере и валидации шаблонов, а не при загрузке конфигурации.

Рендер запускается явно. dwe run и deploy не рендерят workspace-пакеты автоматически. Проект может включить рендер шагом конвейера уровня проекта:

- name: render-workspace
  type: dwe
  cmd: "render workspace"

Структура пакета и manifest

Минимальный пакет:

workspace/templates/workspace/root-agents/
├── manifest.yml
├── AGENTS.md.tmpl
└── workspace-notes.txt

render:
  - from: AGENTS.md.tmpl
    to: AGENTS.md
  - from: workspace-notes.txt
    to: workspace-notes.txt

Manifest декодируется строго: неизвестные поля, пустые файлы и пустые манифесты считаются ошибками. Обрабатываются только объявленные источники; остальные файлы пакета игнорируются.

Поле	Значение
`render[].from`	Обязательный путь источника относительно пакета. Должен разрешаться в обычный файл внутри пакета или его локального оверрайда.
`render[].to`	Обязательный путь результата относительно корня проекта. Вложенные пути разрешены; абсолютные пути, сам корень и выход за его пределы запрещены.
`symlinks[].link`	Обязательный путь ссылки относительно корня проекта с теми же защитами назначения.
`symlinks[].to`	Обязательная цель относительно корня проекта. Должна совпадать с `render[].to` в том же манифесте.

Например, чтобы открыть AGENTS.md под вторым именем для другого инструмента:

symlinks:
  - link: GEMINI.md
    to: AGENTS.md

Каталог пакета, manifest, источники и их родительские пути не должны быть симлинками. Генерируемые симлинки используют относительные цели, вычисленные от расположения ссылки. Существующая ссылка сохраняется, если цель верна, или перенаправляется; обычный файл или каталог на месте ссылки — ошибка.

Шаблоны, дословное копирование и права

Обработка определяется именем источника:

`from`	Обработка
Заканчивается на `.tmpl`	Выполнение как Go `text/template` с `missingkey=error`.
Любое другое имя	Точное копирование байтов без разбора шаблона и подстановки переменных.

Например, config.tmpl может использовать {{ .Project.Name }}, а источник промпта blocks/task.md сохраняет {{PLAN_FILE}} для потребляющего инструмента. Имя результата всегда задаётся явным to; суффиксы автоматически не удаляются. Workspace-пакеты не раскрывают ${...}.

Права зависят от разрешённого источника, в том числе локального оверрайда:

Любой исполняемый бит источника даёт режим 0755.
Источник без исполняемых битов даёт режим 0644.

DWE явно применяет режим при каждом рендере, включая существующие файлы. Добавление или удаление исполняемого бита источника поэтому меняет исполняемый бит результата при следующем рендере. Другие различия прав источника не сохраняются.

Данные шаблона

Файлы .tmpl получают общие данные пакетов с заполненными полями уровня проекта:

Поле или метод	Значение
`.Project`	Объединённый блок `project:`.
`.Runtime`	Объединённый блок `runtime:`.
`.Services`	Все эффективные конфигурации сервисов, включая отключённые.
`.AppServices`, `.ToolServices`, `.InfraServices`	Карты сервисов, отфильтрованные по типу.
`.Cfg`	Объединённая конфигурация в режиме sanitization; `.Cfg.Raw` — нормализованная объединённая карта.
`.Commands`	Индекс объявленных публичных команд, отсортированный по id.
`.CommandGroups`	Авторские группы команд с объявленными количествами, отсортированные по id.
`.Service`, `.Resolved`	Пустые строки: текущего сервиса нет.
`.ServiceCfg`	Нулевое значение конфигурации сервиса.
`.ServiceCommands`, `.ServiceCommandGroups`	Пустые: привязки к сервису нет.

Например, AGENTS.md.tmpl может перечислить сервисы и команды:

# {{ .Project.Name }}

## Services
{{ range $name, $svc := .Services }}- {{ $name }} ({{ $svc.Type }})
{{ end }}
## Declared commands
{{ range .Commands }}- {{ .ID }}: {{ .Summary }}
{{ end }}

Индекс команд использует авторские английские строки и игнорирует условия hide:; отслеживаемый результат поэтому не меняется с локалью или текущим состоянием стека. Приватные команды исключены. Если файлы команд не загрузились, рендер выводит предупреждение и продолжается с пустым индексом; диагностируйте ошибку через dwe validate commands. Поля записей описаны в разделе Индекс объявленных команд.

Доступны только стандартные функции Go text/template: index, printf, and, or и другие; workspace-пакеты не регистрируют sprout или appURL. Отсутствующий ключ карты при обращении через точку — ошибка. Защищайте необязательные карты через with, а ключи, непригодные для dot-синтаксиса, читайте через index.

Конфигурация загружается в режиме sanitization: зашифрованные скалярные секреты остаются маркерами ENC[age:…], даже если у разработчика есть рабочий ключ расшифровки. Sanitization не удаляет обычные открытые значения. Избегайте локальных и чувствительных значений .Cfg.Raw в отслеживаемых результатах: локальная конфигурация всё равно участвует в объединении.

Локальные оверрайды

Поместите альтернативный источник по тому же относительному пути в соседний каталог workspace/templates/workspace/<pack>.local/:

workspace/templates/workspace/root-agents/AGENTS.md.tmpl
workspace/templates/workspace/root-agents.local/AGENTS.md.tmpl

Существующий оверрайд имеет приоритет; отсутствующие файлы берутся из канонического пакета. Симлинк, каталог или другой некорректный оверрайд — ошибка, а не повод использовать исходный файл. Канонический пакет остаётся обязательным, и всегда используется его manifest.yml; оверрайды заменяют источники, а не манифесты или пути назначения.

Для приватных оверрайдов добавьте шаблон вроде workspace/templates/*/*.local/ в .gitignore проекта. Рендер всё равно пишет в корневые назначения манифеста, которые могут отслеживаться Git: игнорируемый источник не делает результат приватным. CLI сообщает о каждом использованном локальном оверрайде.

Защищённые пути и коллизии

Назначение рендера или расположение симлинка на одном из этих корневых путей либо под ним запрещено:

Защищённый корневой путь	Назначение
`workspace.yml`	Корневая конфигурация проекта.
`workspace/`	Отслеживаемая конфигурация, команды, скрипты и источники шаблонов.
`services/`	Хабы сервисов и репозитории.
`.dwe/`	Runtime-состояние DWE.
`.git/`	Метаданные корневого Git-репозитория.
`.env`	Генерируемый корневой файл окружения.

Защита сравнивает компоненты очищенного пути без учёта регистра: Workspace.yml и .GIT/hooks/pre-commit также защищены. .env.example — отдельный путь, он разрешён.

Назначения всех выбранных пакетов должны различаться. Сравнение не учитывает регистр и включает конфликт файла с каталогом: .ralphex конфликтует с .ralphex/config, а AGENTS.md — с agents.md. Проверки применяются и к файлам, и к расположениям симлинков, включая записи одного пакета. Победителя или порядка перезаписи при коллизиях нет.

Планирование и запись

Рендер состоит из двух фаз:

Спланировать все выбранные пакеты вместе: загрузить и проверить манифесты, разрешить источники и оверрайды, исключить защищённые пути и коллизии, подготовить каждый результат в памяти и проверить все пути назначения по текущей файловой системе.
Записать подготовленные файлы и создать или обновить симлинки в порядке пакетов и записей манифеста. Отсутствующие родительские каталоги создаются.

Ошибка планирования ничего не записывает, даже если она в последнем пакете. Проверки отвергают выходящие за корень пути, родительские симлинки и назначения файлов, которые уже являются симлинками, каталогами или другими объектами, не являющимися обычными файлами. Существующие обычные файлы перезаписываются без запроса подтверждения.

Фаза записи повторно проверяет пути, но не является транзакцией. Поздняя ошибка файловой системы или прав не откатывает уже записанные файлы. Избегайте конкурентных изменений путей назначения во время рендера.

CLI и валидация

dwe render workspace                       # использовать render.workspace
dwe render workspace ralphex root-agents   # использовать только эти пакеты
dwe validate templates workspace           # спланировать настроенный список без записи

Явные имена заменяют настроенный список на этот вызов. Можно выбрать пакет, отсутствующий в render.workspace; валидация по-прежнему проверяет настроенный список, поэтому добавьте туда пакет для регулярной валидации проекта.

Shell completion предлагает доступные канонические каталоги пакетов, исключая уже указанные имена и каталоги оверрайдов .local. Некорректный путь проекта или конфигурации не даёт ни дополнений, ни диагностических сообщений. Актуальный CLI-интерфейс показывает dwe render workspace --help.

Рендер использует человекочитаемый вывод и не имеет JSON-режима. Он не запускает preflight и не захватывает проектные блокировки операций. Валидатор работает без записи и использует ту же фазу планирования и данные шаблонов в режиме sanitization, включая проверку межпакетных коллизий. Пустой список даёт информационную диагностику. Диагностика workspace-шаблонов не входит в preflight-гейт lifecycle-команд.

Стартовые пакеты

Репозиторий содержит проверенные стартовые пакеты для владения workspace в examples/workspace-packs/README.md:

ralphex — область нескольких репозиториев, конфигурация инструмента, скрипты и блоки промптов. Следуйте руководству Запуск ralphex в workspace.
root-agents — корневой AGENTS.md из шаблона и дословно копируемый файл. Сначала перенесите существующий корневой документ в шаблон: рендер его перезапишет.

Берите примеры из release tag, соответствующего установленному dwe --version, затем поддерживайте собственные копии. Они не встраиваются в бинарник и не устанавливаются через dwe init.

Ограничения

Удаление записи манифеста или отключение пакета оставляет старые результаты на диске; DWE не отслеживает владельцев и не удаляет эти файлы.
Manifest рендерит файлы и создаёт симлинки; он не исполняет хуки и команды. Генерацию для конкретного инструмента запускайте отдельно объявленной командой.
Workspace-пакеты не расшифровывают источники .age и не используют хранилище ${generated.*} конфигов сервисов. Источники без .tmpl копируются дословно.
Автоматического рендера в lifecycle-командах и отката фазы записи нет.

Связанные справочники

Индекс render — виды пакетов, общие манифесты и локальные оверрайды.
Конфигурация workspace — корневой render и слои объединения.
Шаблоны — подложки шаблонов и контекст на каждом участке.
Валидация — домены и диагностический вывод.