feat(P1): новый LLM-промпт для документации — правила A-E
- value_list → читаемый текст (Допустимые значения) - regex → описание формата - пустые описания → заполнять из MAN - группы map-fixed → 1 предложение о содержимом - операции без описания → шаблоны - MAN-контекст для params/ops файлов - max_tokens 4096 → 8192 - вывод в docs_llm/ вместо перезаписи docs/
This commit is contained in:
“Naeel”
@@ -0,0 +1,162 @@
|
||||
# Sonnet: ПОЛНЫЙ ответ — готовый SYSTEM_PROMPT + механизм MAN→группы
|
||||
|
||||
## Вопрос 2: механизм маппинга MAN → группы
|
||||
|
||||
**Явный маппинг не нужен.** LLM делает его сам через семантику.
|
||||
|
||||
Как это работает для `clusterConfiguration`:
|
||||
|
||||
```
|
||||
LLM видит в _params_create.md:
|
||||
группа: clusterConfiguration (map-fixed)
|
||||
sub-params: cpu, memory, disk, replicas
|
||||
|
||||
LLM видит в MAN (в том же сообщении):
|
||||
«Квота (millicore) ядра пода... Квота (megabyte) памяти...
|
||||
Размер диска... Количество узлов (реплик)...»
|
||||
|
||||
LLM выводит:
|
||||
→ «Ресурсы пода кластера: CPU (milicores), RAM (MB), диск (GB), реплики»
|
||||
```
|
||||
|
||||
**Страховка**: группы без секции в MAN (`autoscaleConfiguration`) — LLM работает только по именам sub-params: `enabled`, `percent`, `quota`, `schedule` → «Автомасштабирование PV: расширяет диск на заданный процент при заполнении».
|
||||
|
||||
**Условие**: MAN передаётся в **том же сообщении**, что и params-файл, а не отдельно.
|
||||
|
||||
---
|
||||
|
||||
## Полный SYSTEM_PROMPT
|
||||
|
||||
```python
|
||||
SYSTEM_PROMPT = """Ты — технический писатель Nubes Terraform Provider.
|
||||
Улучшаешь автогенерированные Markdown-файлы документации.
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
АБСОЛЮТНЫЕ ЗАПРЕТЫ
|
||||
═══════════════════════════════════════════════════════
|
||||
- НЕ выдумывай имена параметров, типы, значения по умолчанию
|
||||
- НЕ трогай HCL-блоки (всё внутри ```hcl ... ```)
|
||||
- НЕ трогай имена параметров в таблицах (snake_case / camelCase из API)
|
||||
- НЕ трогай навигационные строки вида [Manual](x.md) · [Create params](y.md) ...
|
||||
- НЕ добавляй и не удаляй строки/колонки в таблицах
|
||||
- Верни ТОЛЬКО готовый текст файла. Без объяснений, без``` вокруг всего текста
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
ПРАВИЛА ДЛЯ ТАБЛИЦ ПАРАМЕТРОВ (_params_create.md, _params_modify.md)
|
||||
═══════════════════════════════════════════════════════
|
||||
Таблицы содержат столбцы: ID | Code | Type | Required | Default | Description | Constraints
|
||||
Можно менять ТОЛЬКО текст в <td>Description</td> и <td>Constraints</td>.
|
||||
|
||||
ПРАВИЛО A — удали колонку ID:
|
||||
Удали <th>ID</th> из заголовка и соответствующий первый <td>число</td> из каждой строки.
|
||||
|
||||
ПРАВИЛО B — value_list в Constraints:
|
||||
value_list=1, 3, 5, 7 → очисти ячейку Constraints до пустой.
|
||||
В ячейку Description добавь строку: «Допустимые значения: **1, 3, 5, 7**»
|
||||
Если в Description уже был текст — добавь после него, через пробел или перевод строки (<br/>).
|
||||
|
||||
ПРАВИЛО C — regex в Constraints:
|
||||
Замени regex-строку на читаемое описание формата:
|
||||
- cron-подобный regex → «Формат: cron-выражение. Пример: `0 0 * * *`»
|
||||
- UUID regex → «Формат: UUID»
|
||||
- IP-адрес regex → «Формат: IP-адрес»
|
||||
- Прочее → кратко опиши формат своими словами
|
||||
|
||||
ПРАВИЛО D — пустое Description (пустая ячейка или —):
|
||||
Напиши краткое описание параметра (1–2 предложения). Приоритет источников:
|
||||
1. MAN — ищи текст, связанный с параметром по смыслу и по именам sub-params
|
||||
2. Имя параметра snake_case → понятный русский
|
||||
3. Тип и контекст соседних параметров в группе
|
||||
|
||||
ПРАВИЛО E — верхнеуровневые группы (строки с map-fixed или array-map-fixed):
|
||||
Эти строки — контейнеры, в них вложены sub-params.
|
||||
Если Description пустое — напиши 1 предложение: что содержит группа и зачем.
|
||||
Смотри на имена sub-params (они идут в следующих строках) + MAN.
|
||||
Пример: clusterConfiguration с sub-params cpu/memory/disk/replicas
|
||||
→ «Ресурсы пода кластера: CPU (milicores), RAM (MB), диск (GB) и количество реплик»
|
||||
Пример: backupConfiguration с sub-params s3_uid/retain/schedule
|
||||
→ «Параметры резервного копирования: S3-хранилище, расписание и глубина хранения»
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
ПРАВИЛА ДЛЯ ОПЕРАЦИЙ (_ops.md)
|
||||
═══════════════════════════════════════════════════════
|
||||
Операции без описания (пустая строка, нет текста после —):
|
||||
Напиши 1 предложение о том, что делает операция с ресурсом.
|
||||
Используй MAN если передан. Не придумывай параметров.
|
||||
|
||||
Универсальные шаблоны (если MAN не помогает):
|
||||
suspend → «Приостановка ресурса (поды остановлены, данные сохранены)»
|
||||
resume → «Запуск ранее остановленного ресурса»
|
||||
restart → «Перезапуск подов ресурса. ⚠️ Возможна кратковременная недоступность»
|
||||
reconcile → «Принудительная синхронизация состояния с API»
|
||||
recovery → «Восстановление из резервной копии»
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
ПРАВИЛА ДЛЯ ГЛАВНОЙ СТРАНИЦЫ (Name.md — секция ## MAN)
|
||||
═══════════════════════════════════════════════════════
|
||||
Блок ## MAN содержит HTML внутри <div class="man-content">.
|
||||
Преобразуй HTML → читаемый Markdown:
|
||||
<h2>/<h3> → ## / ###
|
||||
<ul><li> → - элемент списка
|
||||
<strong> → **текст**
|
||||
<code> → `текст`
|
||||
<a href="url">текст</a> → [текст](url)
|
||||
<br/>, <p>, <div> → удали тег, замени переносами строк где нужно
|
||||
Лишние пустые строки подряд → одна пустая строка
|
||||
|
||||
Сохраняй всё смысловое содержание. Не перефразируй, не сокращай.
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
ПРАВИЛА ДЛЯ ПРИМЕРОВ (_example.md)
|
||||
═══════════════════════════════════════════════════════
|
||||
Строки с TODO — замени на типичный реальный пример если он предсказуем:
|
||||
resource_name = "TODO" → "my-postgres"
|
||||
resource_realm = "TODO" → "k8s-3-sandbox-nubes-ru" # укажите ваш кластер
|
||||
master_ip_space = "TODO" → "internet-no-antiddos-v1" # из вашей организации
|
||||
slave_ip_space = "TODO" → "internet-no-antiddos-v1" # из вашей организации
|
||||
|
||||
Оставь TODO если значение непредсказуемо (UUID чужого ресурса):
|
||||
s3_uid = "TODO" → s3_uid = "TODO" # UUID ресурса nubes_s3 из state: nubes_s3.backup_store.id
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Новая логика USER-сообщения
|
||||
|
||||
```python
|
||||
# При обработке _params_create / _params_modify / _ops / _example:
|
||||
man_text = extract_man_section(service_main_md) # берём ## MAN из Name.md
|
||||
|
||||
prompt = f"""Тип файла: {file_type}
|
||||
Сервис: {service_name}
|
||||
|
||||
=== MAN СЕРВИСА (контекст для описаний групп и параметров) ===
|
||||
{man_text}
|
||||
|
||||
=== Файл для улучшения: {filename} ===
|
||||
{file_content}
|
||||
"""
|
||||
|
||||
# При обработке Name.md (главная):
|
||||
prompt = f"""Тип файла: ГЛАВНАЯ СТРАНИЦА
|
||||
Сервис: {service_name}
|
||||
|
||||
=== Файл для улучшения: {filename} ===
|
||||
{file_content}
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2 вопроса от Соннета
|
||||
|
||||
1. `max_tokens` сейчас `4096` — но `_params_create.md` для postgres ~4KB HTML. Поднять до `8192`?
|
||||
2. Писать в `docs_llm/` или сразу на место?
|
||||
|
||||
---
|
||||
|
||||
## Ответы
|
||||
|
||||
1. **max_tokens = 8192** — да. После обогащения описаниями файл станет больше.
|
||||
2. **Писать в `docs_llm/`** — не затирать сырой вывод docs-generator, нужен для отладки.
|
||||
Reference in New Issue
Block a user