📋

Process Rules

Нормативные правила для всех процессов

Source: process_rules.md — нормативный документ платформы. Все процессы обязаны следовать этим правилам.

1Process = Contract

Каждый процесс обязан иметь Process Contract (в БД + в workflow pack).

Обязательные поля:

  • • process_key — unique identifier
  • • version — semver
  • • jtbd — Jobs To Be Done
  • • input_schema — JSON Schema
  • • output_schema — JSON Schema
  • • steps_expected — список шагов

SLA и Policy:

  • • sla — p50, p95, max_steps, max_retries
  • • fallback_policy — поведение при ошибках
  • • kpi — success_rate, fallback_rate, redo_rate
  • • visibility — что показываем юзеру
  • • safety_policy — SSRF, PII, финансы

Rule: Если нет контракта — это не process template.

2Audit-first Runtime

Ни один run/step не живет только в памяти. Истина в Postgres:

clowbot.process_runs

Запуски процессов

clowbot.process_run_steps

История шагов

clowbot.process_artifacts

Артефакты

clowbot.automation_events

Trace events

Минимум для любого run:

{
  "requested_by": 123,      // кто запустил (user_id)
  "chat_id": 456,           // где запущено
  "template_key": "web_search",
  "template_version": "1.0.0",
  "current_step_key": "synthesize",
  "status": "running"       // queued|running|waiting_user|succeeded|degraded|failed|cancelled
}

3Unified Status Dictionary

queued
В очереди
running
Выполняется
waiting_user
Ждёт пользователя
succeeded
Успешно завершён
degraded
С fallback
failed
Ошибка
cancelled
Отменён

Compatibility: legacy done нормализуется в succeeded.

4Telegram Smart Message

Один run = одна run-панель (process_run_panels), которая редактируется по мере прохождения шага.

Панель содержит:

  • • process name/code
  • • run_id
  • • status + progress
  • • current step
  • • runtime summary

Inline actions:

  • • 📄 details
  • • 🧾 logs
  • • 🧩 artifacts
  • • 🔄 refresh
  • • 🙈 hide

Команды:

/process <run_id>     → открыть run-панель
/run <process_code> <task> → создать run + панель

5n8n Interface Contract

n8n внутри может быть любым, но наружу обязан быть детерминирован:

POST /internal/process/events/run

Run events (start, complete, fail)

POST /internal/process/events/step

Step events

POST /internal/process/artifacts

Artifacts

Rule: n8n не источник истины. Источник истины — Postgres.

6Fallback as First-class Behavior

Каждый контракт обязан описывать fallback стратегии:

•Fallback при недоступности Ollama
•Fallback при n8n/web timeout, error, SSRF block
•Лимиты retries/backoff
•User-facing degraded response policy (честный degraded)
# Пример из process_runner.py
response = {
    "model": fallback_model,
    "message": {"content": degraded_text},
    "degraded": True,
    "error": "timeout_fallback_exhausted"
}

7Test Matrix (Mandatory)

Для каждого process template обязательны тесты:

Happy Path

Нормальное выполнение

Degraded Path

Выполнение с fallback

Failure Path

Обработка ошибок

Group/Thread Path

Если процесс групповой

Done Criteria:

  • ✓ Есть row в process_runs
  • ✓ Есть step history
  • ✓ Есть user-facing output в Telegram
  • ✓ Есть trace в automation_events

8Prompt-grounded Factual Answers

  • Runtime facts in context:Текущее datetime/timezone и другие факты должны передаваться в model context.
  • No narrow handlers:Избегать узких hardcoded handlers для conversational intents (date/time/day), если это не требуется policy/safety.
  • Deep-redo on feedback:Если 1⭐ + 🔄 redo, regeneration переключается на deep-redo policy:
    • • Stricter anti-hallucination behavior
    • • Explicit use of runtime factual context
    • • Auditable trace in DB/runtime events

9Swarm Live Process Test Profile

Для релизной готовности обязателен live swarm-профиль в тестовой группе:

Startup Message

bot поднялся с базовой статусной моделью run/step

Bot-to-bot Chain Scenario

/swarm_test start ...  → проверка адресного вызова без fan-out

Full Process Smoke Matrix

/swarm_test processes [all|n8n|local] [limit]

Quality Gate

  • • Smoke результат в process_template_tests
  • • Проверка через mart.vw_process_test_gate
  • • DB trace: reminders, messages, runtime events
← Process RunsProcess Testing→