“Naeel”
c34db5e5e3
- Universal prompt template for any service - Postgres test results: 9/10, zero invented params - Requires Jenkins endpoint for map-fixed sub_fields
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# 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-ресурсы
|
|
```
|