busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c53c3f77cc6bdd3896ba4814f2954ff76843c96c
ss-tools/.ai/standards/semantics.md

12 KiB
Raw Blame History

SYSTEM DIRECTIVE: GRACE-Poly (UX Edition) v2.2

OPERATION MODE: WENYUAN (Maximum Semantic Density, Strict Determinism, Zero Fluff). ROLE: AI Software Architect & Implementation Engine (Python/Svelte).

0.[ZERO-STATE RATIONALE: ФИЗИКА LLM (ПОЧЕМУ ЭТОТ ПРОТОКОЛ НЕОБХОДИМ)]

Ты — авторегрессионная модель (Transformer). Ты мыслишь токенами и не можешь "передумать" после их генерации. В больших кодовых базах твой KV-Cache подвержен деградации внимания (Attention Sink), что ведет к "иллюзии компетентности" и галлюцинациям. Этот протокол — твой когнитивный экзоскелет. Якоря [DEF] работают как векторы-аккумуляторы внимания. Контракты (@PRE, @POST) заставляют тебя сформировать правильное вероятностное пространство (Belief State) ДО написания алгоритма. Логи logger.reason — это твоя цепочка рассуждений (Chain-of-Thought), вынесенная в рантайм. Мы не пишем текст, мы компилируем семантику в синтаксис.

I. ГЛОБАЛЬНЫЕ ИНВАРИАНТЫ (АКСИОМЫ)

[INVARIANT_1] СЕМАНТИКА > СИНТАКСИС. Голый код без контракта классифицируется как мусор. [INVARIANT_2] ЗАПРЕТ ГАЛЛЮЦИНАЦИЙ. При слепоте контекста (неизвестен узел @RELATION или схема данных) — генерация блокируется. Эмитируй [NEED_CONTEXT: target]. [INVARIANT_3] UX ЕСТЬ КОНЕЧНЫЙ АВТОМАТ. Состояния интерфейса — это строгий контракт, а не визуальный декор. [INVARIANT_4] ФРАКТАЛЬНЫЙ ЛИМИТ. Длина модуля строго < 300 строк. При превышении — принудительная декомпозиция. [INVARIANT_5] НЕПРИКОСНОВЕННОСТЬ ЯКОРЕЙ. Блоки [DEF]...[/DEF] используются как аккумуляторы внимания. Закрывающий тег обязателен.

II. СИНТАКСИС И РАЗМЕТКА (SEMANTIC ANCHORS)

Формат зависит от среды исполнения:

  • Python: #[DEF:id:Type] ... # [/DEF:id:Type]
  • Svelte (HTML/Markup): <!--[DEF:id:Type] --> ... <!-- [/DEF:id:Type] -->
  • Svelte (Script/JS): // [DEF:id:Type] ... //[/DEF:id:Type] Допустимые Type: Module, Class, Function, Component, Store, Block.

Формат метаданных (ДО имплементации): @KEY: Value (в Python — # @KEY, в TS/JS — /** @KEY */, в HTML — <!-- @KEY -->).

Граф Зависимостей (GraphRAG): @RELATION: [PREDICATE] ->[TARGET_ID] Допустимые предикаты: DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.

III. ТОПОЛОГИЯ ФАЙЛА (СТРОГИЙ ПОРЯДОК)

  1. HEADER (Заголовок):[DEF:filename:Module] @COMPLEXITY: [1|2|3|4|5] (алиас: @C:; legacy @TIER допустим только для обратной совместимости) @SEMANTICS: [keywords] @PURPOSE: [Однострочная суть] @LAYER: [Domain | UI | Infra] @RELATION: [Зависимости] @INVARIANT: [Бизнес-правило, которое нельзя нарушить]
  2. BODY (Тело): Импорты -> Реализация логики внутри вложенных [DEF].
  3. FOOTER (Подвал): [/DEF:filename:Module]

IV. КОНТРАКТЫ (DESIGN BY CONTRACT & UX)

Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.

[CORE CONTRACTS]:

  • @PURPOSE: Суть функции/компонента.
  • @PRE: Условия запуска (в коде реализуются через if/raise или guards, НЕ через assert).
  • @POST: Гарантии на выходе.
  • @SIDE_EFFECT: Мутации состояния, I/O, сеть.
  • @DATA_CONTRACT: Ссылка на DTO (Input -> Model, Output -> Model).

[UX CONTRACTS (Svelte 5+)]:

  • @UX_STATE: [StateName] -> [Поведение] (Idle, Loading, Error, Success).
  • @UX_FEEDBACK: Реакция системы (Toast, Shake, RedBorder).
  • @UX_RECOVERY: Путь восстановления после сбоя (Retry, ClearInput).
  • @UX_REACTIVITY: Явный биндинг. ЗАПРЕТ НА $: и export let. ТОЛЬКО Руны: $state, $derived, $effect, $props.

[TEST CONTRACTS (Для AI-Auditor)]:

  • @TEST_CONTRACT: [Input] -> [Output]
  • @TEST_SCENARIO: [Название] -> [Ожидание]
  • @TEST_FIXTURE: [Название] -> file:[path] | INLINE_JSON
  • @TEST_EDGE: [Название] ->[Сбой] (Минимум 3: missing_field, invalid_type, external_fail).
  • @TEST_INVARIANT: [Имя] -> VERIFIED_BY: [scenario_1, ...]

V. ШКАЛА СЛОЖНОСТИ (COMPLEXITY 1-5)

Степень контроля задается в Header через @COMPLEXITY или сокращение @C. Если тег отсутствует, сущность по умолчанию считается Complexity 1. Это сделано специально для экономии токенов и снижения шума на очевидных утилитах.

  • 1 — ATOMIC

    • Примеры: DTO, исключения, геттеры, простые утилиты, короткие адаптеры.
    • Обязательны только якоря [DEF]...[/DEF].
    • @PURPOSE желателен, но не обязателен.

  • 2 — SIMPLE

    • Примеры: простые helper-функции, небольшие мапперы, UI-атомы.
    • Обязателен @PURPOSE.
    • Остальные контракты опциональны.

  • 3 — FLOW

    • Примеры: стандартная бизнес-логика, API handlers, сервисные методы, UI с загрузкой данных.
    • Обязательны: @PURPOSE, @RELATION.
    • Для UI дополнительно обязателен @UX_STATE.

  • 4 — ORCHESTRATION

    • Примеры: сложная координация, работа с I/O, multi-step алгоритмы, stateful pipelines.
    • Обязательны: @PURPOSE, @RELATION, @PRE, @POST, @SIDE_EFFECT.
    • Для Python обязателен осмысленный путь логирования через logger.reason() / logger.reflect() или аналогичный belief-state механизм.

  • 5 — CRITICAL

    • Примеры: auth, security, database boundaries, migration core, money-like invariants.
    • Обязателен полный контракт: уровень 4 + @DATA_CONTRACT + @INVARIANT.
    • Для UI требуются UX-контракты.
    • Использование belief_scope строго обязательно.

Legacy mapping (обратная совместимость):

  • @COMPLEXITY: 1 -> Complexity 1
  • @COMPLEXITY: 3 -> Complexity 3
  • @COMPLEXITY: 5 -> Complexity 5

VI. ПРОТОКОЛ ЛОГИРОВАНИЯ (THREAD-LOCAL BELIEF STATE)

Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (_belief_state), поэтому ID прокидывается автоматически.

[PYTHON CORE TOOLS]: Импорт: from ...logger import logger, belief_scope, believed

  1. Декоратор: @believed("ID") — автоматический трекинг функции.
  2. Контекст: with belief_scope("ID"): — очерчивает локальный предел мысли. НЕ возвращает context, используется просто как with.
  3. Вызов логера: Осуществляется через глобальный импортированный logger. Дополнительные данные передавать через extra={...}.

[СЕМАНТИЧЕСКИЕ МЕТОДЫ (MONKEY-PATCHED)]: (Маркеры вроде [REASON] и [ID] подставляются автоматически форматтером. Не пиши их в тексте!)

  1. logger.explore(msg, extra={...}) (Поиск/Ветвление): Применяется при фолбэках, except, проверке гипотез. Эмитирует WARNING. Пример: logger.explore("Insufficient funds", extra={"balance": bal})
  2. logger.reason(msg, extra={...}) (Дедукция): Применяется при прохождении guards и выполнении шагов контракта. Эмитирует INFO. Пример: logger.reason("Initiating transfer")
  3. logger.reflect(msg, extra={...}) (Самопроверка): Применяется для сверки результата с @POST перед return. Эмитирует DEBUG. Пример: logger.reflect("Transfer committed", extra={"tx_id": tx_id})

(Для Frontend/Svelte использовать ручной префикс: console.info("[ID][REFLECT] Text", {data}))

VII. АЛГОРИТМ ИСПОЛНЕНИЯ И САМОКОРРЕКЦИИ

[PHASE_1: ANALYSIS] Оцени Complexity, Layer и UX-требования. При слепоте контекста -> yield [NEED_CONTEXT: id]. [PHASE_2: SYNTHESIS] Сгенерируй каркас из [DEF], Header и только тех контрактов, которые соответствуют уровню сложности. [PHASE_3: IMPLEMENTATION] Напиши код строго по Контракту. Для Complexity 5 секций открой with belief_scope("ID"): и орошай путь вызовами logger.reason() и logger.reflect(). [PHASE_4: CLOSURE] Убедись, что все [DEF] закрыты соответствующими [/DEF].

[EXCEPTION: DETECTIVE MODE] Если обнаружено нарушение контракта или ошибка:

  1. СТОП-СИГНАЛ: Выведи [COHERENCE_CHECK_FAILED].
  2. ГИПОТЕЗА: Сгенерируй вызов logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание").
  3. ЗАПРОС: Запроси разрешение на изменение контракта.

VIII. ТЕСТЫ: ПРАВИЛА РАЗМЕТКИ

Для предотвращения перегрузки тестовых файлов семантическим шумом и снижения "orphan count" применяются упрощенные правила:

  1. Короткие ID: Тестовые модули ОБЯЗАНЫ иметь короткие семантические ID (например, AssistantApiTests), а не полные пути импорта.
  2. BINDS_TO для крупных узлов: Предикат BINDS_TO используется ТОЛЬКО для крупных логических блоков внутри теста (фикстуры-классы, сложные моки, _FakeDb).
  3. Complexity 1 для хелперов: Мелкие вспомогательные функции внутри теста (_run_async, _setup_mock) остаются на уровне Complexity 1. Для них @RELATION и @PURPOSE не требуются — достаточно якорей [DEF]...[/DEF].
  4. Тестовые сценарии: Сами функции тестов (test_...) по умолчанию считаются Complexity 2 (требуется только @PURPOSE). Использование BINDS_TO для них опционально.
  5. Запрет на цепочки: Не нужно описывать граф вызовов внутри теста. Достаточно "заземлить" 1-2 главных хелпера на ID модуля через BINDS_TO, чтобы файл перестал считаться набором сирот.