121 lines
8.4 KiB
Markdown
121 lines
8.4 KiB
Markdown
### **Протокол GRACE-Py: Семантическая Разметка для AI-Агентов на Python**
|
||
|
||
**Версия: 2.2 (Hybrid)**
|
||
|
||
#### **I. Философия и Основные Принципы**
|
||
|
||
Этот протокол является **единственным источником истины** для правил семантического обогащения кода. Его цель — превратить процесс разработки с LLM-агентами из непредсказуемого "диалога" в управляемую **инженерную дисциплину**.
|
||
|
||
* **Аксиома 1: Код Вторичен.** Первична его семантическая модель (графы, контракты, якоря).
|
||
* **Аксиома 2: Когерентность Абсолютна.** Все артефакты (ТЗ, граф, контракты, код) должны быть на 100% семантически согласованы.
|
||
* **Аксиома 3: Архитектура GPT — Закон.** Протокол построен на фундаментальных принципах работы трансформеров (Causal Attention, KV Cache, Sparse Attention).
|
||
|
||
#### **II. Структура Файла (`.py`)**
|
||
|
||
Каждый Python-файл ДОЛЖЕН иметь четкую, машиночитаемую структуру, обрамленную якорями.
|
||
|
||
```python
|
||
# <GRACE_MODULE id="my_module" name="my_module.py">
|
||
# @SEMANTICS: domain, usecase, data_processing
|
||
# @PURPOSE: Этот модуль отвечает за обработку пользовательских данных.
|
||
# @DEPENDS_ON: utils_module -> Использует утилиты для валидации.
|
||
|
||
# <IMPORTS>
|
||
import os
|
||
from typing import List
|
||
# </IMPORTS>
|
||
|
||
# --- Начало кода модуля ---
|
||
|
||
# ... (классы, функции, константы) ...
|
||
|
||
# --- Конец кода модуля ---
|
||
|
||
# </GRACE_MODULE id="my_module">
|
||
```
|
||
|
||
#### **III. Компоненты Разметки (Детализация GRACE-Py)**
|
||
|
||
##### **A. Anchors (Якоря): Навигация и Консолидация**
|
||
|
||
1. **Назначение:** Якоря — это основной инструмент для управления вниманием ИИ, создания семантических каналов и обеспечения надежной навигации в больших кодовых базах (Sparse Attention).
|
||
2. **Синтаксис:** Используются парные комментарии в псевдо-XML формате.
|
||
* **Открывающий:** `# <ANCHOR id="[уникальный_id]" type="[тип_из_таксономии]">`
|
||
* **Закрывающий (Обязателен!):** `# </ANCHOR id="[уникальный_id]">`
|
||
3. **"Якорь-Аккумулятор":** Закрывающий якорь консолидирует всю семантику блока (контракт + код), создавая мощный вектор для RAG-систем.
|
||
4. **Семантические Каналы:** `id` якоря ДОЛЖЕН совпадать с именем сущности для создания устойчивой семантической связи.
|
||
5. **Таксономия Типов (`type`):** `Module`, `Class`, `Interface`, `Object`, `DataClass`, `SealedInterface`, `EnumClass`, `Function`, `UseCase`, `ViewModel`, `Repository`.
|
||
|
||
##### **C. Contracts (Контракты): Тактические Спецификации**
|
||
|
||
1. **Назначение:** Предоставление ИИ точных инструкций для генерации и валидации кода.
|
||
2. **Расположение:** Контракт всегда располагается **внутри открывающего якоря**, ДО декларации кода (`def` или `class`).
|
||
3. **Синтаксис:** JSDoc-подобный стиль с `@tag` для лаконичности и читаемости.
|
||
```python
|
||
# <ANCHOR id="process_data" type="Function">
|
||
# @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
|
||
# @SPEC_LINK: tz-req-005
|
||
# @PRE: `raw_data` не должен быть пустым.
|
||
# @POST: Возвращаемый словарь содержит ключ 'is_valid'.
|
||
# @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
|
||
# @RETURN: Dict[str, any] - Обработанные и валидированные данные.
|
||
# @TEST: input='{"user_id": 123}', expected_output='{"is_valid": True}'
|
||
# @THROW: ValueError - Если 'user_id' отсутствует.
|
||
# @RELATION: CALLS -> validate_user_id
|
||
# @CONSTRAINT: Не использовать внешние сетевые вызовы.
|
||
```
|
||
4. **Реализация в Коде:** Предусловия и постусловия, описанные в контракте, ДОЛЖНЫ быть реализованы в коде с использованием `assert`, `require()`/`check()` или явных `if...raise`.
|
||
|
||
##### **G. Graph (Граф Знаний)**
|
||
|
||
1. **Назначение:** Описание высокоуровневых зависимостей между сущностями.
|
||
2. **Реализация:** Граф определяется тегами `@RELATION` внутри GRACE блока (якоря). Это создает распределенный граф, который легко парсить.
|
||
* **Синтаксис:** `@<PREDICATE>: <object_id> -> [опциональное описание]`
|
||
* **Таксономия Предикатов (`<PREDICATE>`):** `DEPENDS_ON`, `CALLS`, `CREATES_INSTANCE_OF`, `INHERITS_FROM`, `IMPLEMENTS`, `READS_FROM`, `WRITES_TO`, `DISPATCHES_EVENT`, `OBSERVES`.
|
||
|
||
##### **E. Evaluation (Логирование)**
|
||
|
||
1. **Назначение:** Декларация `belief state` агента и обеспечение трассируемости для отладки.
|
||
2. **Формат:** `logger.level(f"[ANCHOR_ID][STATE] Сообщение")`
|
||
* **`ANCHOR_ID`:** `id` якоря, в котором находится лог.
|
||
* **`STATE`:** Текущее состояние логики (например, `Entry`, `Validation`, `Exit`, `CoherenceCheckFailed`).
|
||
3. **Пример:** `logger.debug(f"[process_data][Validation] Проверка `raw_data`...")`
|
||
|
||
#### **IV. Запреты и Ограничения**
|
||
|
||
1. **Запрет на Обычные Комментарии:** Комментарии в стиле `//` или `/* */` **ЗАПРЕЩЕНЫ**. Вся мета-информация должна быть в структурированных GRACE блоках.
|
||
* **Исключение:** `# [AI_NOTE]: ...` для прямых указаний агенту в конкретной точке кода.
|
||
|
||
#### **V. Полный Пример Разметки Функции (GRACE-Py 2.2)**
|
||
|
||
```python
|
||
# <ANCHOR id="process_data" type="Function">
|
||
# @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
|
||
# @SPEC_LINK: tz-req-005
|
||
# @PRE: `raw_data` не должен быть пустым.
|
||
# @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
|
||
# @RETURN: Dict[str, any] - Обработанные и валидированные данные.
|
||
# @TEST: input='{}', expected_exception='AssertionError'
|
||
# @RELATION: CALLS -> some_helper_function
|
||
def process_data(raw_data: dict) -> dict:
|
||
"""
|
||
Docstring для стандартных инструментов Python.
|
||
Не является источником истины для ИИ-агентов.
|
||
"""
|
||
logger.debug(f"[process_data][Entry] Начало обработки данных.")
|
||
|
||
# Реализация контракта
|
||
assert raw_data, "Precondition failed: raw_data must not be empty."
|
||
|
||
# ... Основная логика ...
|
||
processed_data = {"is_valid": True}
|
||
processed_data.update(raw_data)
|
||
|
||
logger.info(f"[process_data][CoherenceCheck:Passed] Код соответствует контракту.")
|
||
logger.debug(f"[process_data][Exit] Завершение обработки.")
|
||
|
||
return processed_data
|
||
# </ANCHOR id="process_data">
|
||
```
|
||
|