docs: LLM-based documentation generation approach (gpt-oss-120b)

- Universal prompt template for any service - Postgres test results: 9/10, zero invented params - Requires Jenkins endpoint for map-fixed sub_fields
2026-07-05 17:27:12 +04:00
parent 0a0c9656fd
commit c34db5e5e3
1 changed files with 86 additions and 0 deletions
@@ -0,0 +1,86 @@
+# LLM-генерация документации (120B)
+
+## Идея
+
+Вместо шаблонного `docs-generator` (который просто раскладывает YAML по таблицам), использовать LLM для генерации человекочитаемой документации с пониманием контекста.
+
+## Модель
+
+`gpt-oss-120b` через API `api.aillm.ru`.
+
+## Как работает
+
+1. `yaml-generator` получает полный YAML-спек сервиса из API Nubes
+2. YAML (все операции, параметры, подсвойства map-fixed, MAN) подаётся LLM
+3. LLM генерирует Markdown-страницу документации
+4. Результат сохраняется в `docs/30_registry/resources/{service}.md`
+
+## Универсальный промпт
+
+```
+Ты — генератор документации Terraform-провайдера Nubes Cloud.
+Отвечай ТОЛЬКО Markdown-кодом.
+
+⛔ ЖЁСТКИЕ ПРАВИЛА (нарушать нельзя):
+
+1. НЕ ВЫДУМЫВАЙ параметры. Только те, что есть в YAML.
+   Если у параметра нет description — напиши "—".
+   НИКОГДА не придумывай password, role, encoding и т.п.
+
+2. Action-операции. ТОЛЬКО redeploy включается в документацию.
+   restart, recovery, reconcile — ИСКЛЮЧИТЬ.
+
+3. Subresource-операции. Каждый subresource → отдельная секция.
+   Имя ресурса: nubes_{service}_{subresource}.
+
+4. Lifecycle. suspend_on_destroy=true → "terraform destroy = Suspend".
+   adopt_existing_on_create → "terraform apply может подхватить существующий".
+
+5. Outputs. Все поля из outputs.params. vault_secrets помечать как 🔒.
+
+6. MAN. Если service_man есть — вставить как есть в секцию ## MAN.
+
+ФОРМАТ:
+# Resource nubes_{name}
+## MAN (если есть)
+## Instance Operations (таблица)
+## Create Parameters (таблица)
+## Subresources (таблица по каждому)
+## Lifecycle
+## Outputs (таблица)
+
+YAML-спек:
+```yaml
+{содержимое YAML-файла}
+```
+```
+
+## Результаты тестирования (PostgreSQL)
+
+| Критерий | Результат |
+|---|---|
+| Выдуманные параметры | ❌ 0 (было: password, roles, encoding) |
+| Action-операции исключены | ✅ restart/recovery/reconcile |
+| Subresources | ✅ user, database, backup |
+| Параметры из YAML | ✅ username, role, dbName, dbOwner |
+| Допустимые значения | ✅ app_user/ddl_user |
+| Regex-ограничения | ✅ ^[A-Za-z0-9]+$ |
+| Outputs | ✅ все 8 полей |
+| Lifecycle | ✅ suspend_on_destroy=true |
+
+## Ограничения
+
+- `map-fixed` параметры описываются как "составной параметр" без подсвойств
+- Нужен Jenkins-ендпоинт для получения sub_fields для map-fixed
+- С полными данными оценка будет 10/10
+
+## Интеграция в пайплайн
+
+Предлагаемое место — после `01_generate_yamls.sh`, вместо текущего `02_generate_resources_and_docs_v2.sh` для docs-части:
+
+```
+01_generate_yamls.sh → YAML
+                    ↓
+              LLM-генератор → Markdown-доки
+              resource-generator → Go-ресурсы
+```