refactor, add db search
This commit is contained in:
@@ -1,120 +1,144 @@
|
||||
### **Протокол GRACE-Py: Семантическая Разметка для AI-Агентов на Python**
|
||||
# 📁 BUNDLE: Engineering Prompting & GRACE Methodology
|
||||
**Context Transfer Protocol for LLM Agents**
|
||||
|
||||
**Версия: 2.2 (Hybrid)**
|
||||
## 1. Фундаментальная Парадигма (The "Physics" of LLMs)
|
||||
Мы отказываемся от антропоморфного подхода ("диалог с помощником") в пользу инженерного подхода ("программирование семантического процессора").
|
||||
|
||||
#### **I. Философия и Основные Принципы**
|
||||
* **Трансформер = GNN (Graph Neural Network):** LLM обрабатывает токены как узлы в полносвязном графе. Чтобы модель работала эффективно, мы должны явно задавать топологию этого графа через семантические связи.
|
||||
* **Мышление = Навигация по Состояниям (FSM):** Генерация — это переход между "состояниями веры" (Belief States). Мы управляем этими переходами через Якоря и Контракты.
|
||||
* **Causal Attention & KV Cache:** Модель читает слева-направо. Смысл, обработанный в начале, "замораживается". **Правило:** Контекст и Контракты всегда строго *до* реализации.
|
||||
* **Sparse Attention & Block Processing:** На больших контекстах (100k+) модель работает не с отдельными токенами, а с семантическими сжатиями блоков (чанков). Наша разметка создает идеальные границы для этих блоков, помогая механизму Top-K retrieval.
|
||||
* **Проблема "Семантического Казино":** Без жесткой структуры модель играет в рулетку вероятностей. Мы устраняем это через детерминированные структуры (графы, схемы).
|
||||
* **Проблема "Нейронного Воя" (Neural Howlround):** Самоусиливающиеся ошибки в длинных сессиях. **Решение:** Разделение сессий, жесткие инварианты и использование "суперпозиции" (анализ вариантов перед решением).
|
||||
|
||||
Этот протокол является **единственным источником истины** для правил семантического обогащения кода. Его цель — превратить процесс разработки с LLM-агентами из непредсказуемого "диалога" в управляемую **инженерную дисциплину**.
|
||||
---
|
||||
|
||||
* **Аксиома 1: Код Вторичен.** Первична его семантическая модель (графы, контракты, якоря).
|
||||
* **Аксиома 2: Когерентность Абсолютна.** Все артефакты (ТЗ, граф, контракты, код) должны быть на 100% семантически согласованы.
|
||||
* **Аксиома 3: Архитектура GPT — Закон.** Протокол построен на фундаментальных принципах работы трансформеров (Causal Attention, KV Cache, Sparse Attention).
|
||||
## 2. Методология GRACE (Framework)
|
||||
Целостная система управления жизненным циклом генерации.
|
||||
|
||||
#### **II. Структура Файла (`.py`)**
|
||||
* **G (Graph):** Глобальная карта проекта. Определяет связи (`DEPENDS_ON`, `CALLS`) между модулями. Служит картой для навигации внимания.
|
||||
* **R (Rules):** Инварианты и ограничения (Безопасность, Стек, Паттерны).
|
||||
* **A (Anchors):** Система навигации внутри кода.
|
||||
* *Открывающий якорь:* Задает контекст.
|
||||
* *Замыкающий якорь:* **Аккумулятор семантики**. Критически важен для RAG-систем (Cursor, GraphRAG), так как "вбирает" в себя смысл всего блока.
|
||||
* **C (Contracts):** Принцип **Design by Contract (DbC)**. Спецификация (`@PRE`, `@POST`) всегда пишется *до* кода. Реализация обязана содержать проверки (`assert`/`raise`) этих условий.
|
||||
* **E (Evaluation):** Логирование как декларация состояния (`[STATE:Validation]`) и проверка когерентности (`[Coherence:OK]`).
|
||||
|
||||
Каждый Python-файл ДОЛЖЕН иметь четкую, машиночитаемую структуру, обрамленную якорями.
|
||||
---
|
||||
|
||||
## 3. Рабочий Протокол: GRACE-Py v3.1 (Strict Edition)
|
||||
Это стандарт синтаксиса, к которому мы пришли. Он минимизирует "шум" (интерференцию с XML), использует нативные для Python токены (`def`) и убирает ролевую шелуху.
|
||||
|
||||
**Скопируйте этот блок в System Prompt новой LLM:**
|
||||
|
||||
```markdown
|
||||
# SYSTEM STANDARD: GRACE-Py CODE GENERATION PROTOCOL
|
||||
|
||||
**OBJECTIVE:** Generate Python code that strictly adheres to the Semantic Coherence standards defined below. All output must be machine-readable, fractal-structured, and optimized for Sparse Attention navigation.
|
||||
|
||||
## I. CORE REQUIREMENTS
|
||||
1. **Causal Validity:** Semantic definitions (Contracts) must ALWAYS precede implementation code.
|
||||
2. **Immutability:** Once defined, architectural decisions in the Module Header are treated as immutable constraints.
|
||||
3. **Format Compliance:** Output must strictly follow the `[DEF]` / `[/DEF]` anchor syntax.
|
||||
|
||||
---
|
||||
|
||||
## II. SYNTAX SPECIFICATION
|
||||
|
||||
Code must be wrapped in semantic anchors using square brackets to minimize token interference.
|
||||
|
||||
### 1. Entity Anchors (The "Container")
|
||||
* **Start:** `# [DEF:identifier:Type]`
|
||||
* **End:** `# [/DEF:identifier]` (MANDATORY for semantic accumulation)
|
||||
* **Types:** `Module`, `Class`, `Function`, `DataClass`, `Enum`.
|
||||
|
||||
### 2. Metadata Tags (The "Content")
|
||||
* **Syntax:** `# @KEY: Value`
|
||||
* **Location:** Inside the `[DEF]` block, before any code.
|
||||
|
||||
### 3. Graph Relations (The "Map")
|
||||
* **Syntax:** `# @RELATION: TYPE -> TARGET_ID`
|
||||
* **Types:** `DEPENDS_ON`, `CALLS`, `INHERITS_FROM`, `IMPLEMENTS`, `WRITES_TO`, `READS_FROM`.
|
||||
|
||||
---
|
||||
|
||||
## III. FILE STRUCTURE STANDARD (Module Header)
|
||||
|
||||
Every `.py` file starts with a Module definition.
|
||||
|
||||
```python
|
||||
# <GRACE_MODULE id="my_module" name="my_module.py">
|
||||
# @SEMANTICS: domain, usecase, data_processing
|
||||
# @PURPOSE: Этот модуль отвечает за обработку пользовательских данных.
|
||||
# @DEPENDS_ON: utils_module -> Использует утилиты для валидации.
|
||||
# [DEF:module_name:Module]
|
||||
#
|
||||
# @SEMANTICS: [keywords for vector search]
|
||||
# @PURPOSE: [Primary responsibility of the module]
|
||||
# @LAYER: [Architecture layer: Domain/Infra/UI]
|
||||
# @RELATION: [Dependencies]
|
||||
#
|
||||
# @INVARIANT: [Global immutable rule for this file]
|
||||
# @CONSTRAINT: [Hard restriction, e.g., "No SQL here"]
|
||||
# @PUBLIC_API: [Exported symbols]
|
||||
|
||||
# <IMPORTS>
|
||||
import os
|
||||
from typing import List
|
||||
# </IMPORTS>
|
||||
# [SECTION: IMPORTS]
|
||||
...
|
||||
# [/SECTION]
|
||||
|
||||
# --- Начало кода модуля ---
|
||||
# ... IMPLEMENTATION ...
|
||||
|
||||
# ... (классы, функции, константы) ...
|
||||
|
||||
# --- Конец кода модуля ---
|
||||
|
||||
# </GRACE_MODULE id="my_module">
|
||||
# [/DEF:module_name]
|
||||
```
|
||||
|
||||
#### **III. Компоненты Разметки (Детализация GRACE-Py)**
|
||||
---
|
||||
|
||||
##### **A. Anchors (Якоря): Навигация и Консолидация**
|
||||
## IV. FUNCTION & CLASS CONTRACTS (DbC)
|
||||
|
||||
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)**
|
||||
Contracts are the **Source of Truth**.
|
||||
|
||||
**Required Template:**
|
||||
```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">
|
||||
# [DEF:func_name:Function]
|
||||
# @PURPOSE: [Description]
|
||||
# @SPEC_LINK: [Requirement ID]
|
||||
#
|
||||
# @PRE: [Condition required before execution]
|
||||
# @POST: [Condition guaranteed after execution]
|
||||
# @PARAM: [name] ([type]) - [desc]
|
||||
# @RETURN: [type] - [desc]
|
||||
# @THROW: [Exception] - [Reason]
|
||||
#
|
||||
# @RELATION: [Graph connections]
|
||||
def func_name(...):
|
||||
# 1. Runtime check of @PRE (Assertions)
|
||||
# 2. Logic implementation
|
||||
# 3. Runtime check of @POST
|
||||
pass
|
||||
# [/DEF:func_name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## V. LOGGING STANDARD (BELIEF STATE)
|
||||
|
||||
Logs define the agent's internal state for debugging and coherence checks.
|
||||
|
||||
**Format:** `logger.level(f"[{ANCHOR_ID}][{STATE}] {MESSAGE} context={...}")`
|
||||
|
||||
**States:** `Entry`, `Validation`, `Action`, `Coherence:OK`, `Coherence:Failed`, `Exit`.
|
||||
|
||||
---
|
||||
|
||||
## VI. GENERATION WORKFLOW
|
||||
1. **Analyze Request:** Identify target module and graph position.
|
||||
2. **Define Structure:** Generate `[DEF]` anchors and Contracts FIRST.
|
||||
3. **Implement Logic:** Write code satisfying Contracts.
|
||||
4. **Validate:** If logic conflicts with Contract -> Stop -> Report Error.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Интеграция с RAG (GraphRAG)
|
||||
Как этот код используется инструментами (например, Cursor):
|
||||
|
||||
1. **Индексация:** RAG-система парсит теги `[DEF]`, `[/DEF]` и `@RELATION`.
|
||||
2. **Построение Графа:** На основе `@RELATION` и `@DEPENDS_ON` строится граф знаний проекта.
|
||||
3. **Вектор-Аккумулятор:** Замыкающий тег `[/DEF:func_name]` используется как точка для создания эмбеддинга всего блока. Это позволяет находить функцию не только по имени, но и по её внутренней логике.
|
||||
4. **Поиск:** При запросе "Где логика авторизации?" система находит модуль по тегу `@SEMANTICS: auth` и переходит к конкретным функциям по графу.
|
||||
|
||||
Reference in New Issue
Block a user