busya
e7bac04e98
Discover dashboard filters, datasets and metrics from a parsed reference URL; capture and review baseline candidates with source provenance. Improve scenario DAG and run result views, add isolated browser coverage, and align contracts and ADRs.
219 lines
11 KiB
Markdown
219 lines
11 KiB
Markdown
## THE PHYSICS OF YOUR ATTENTION (WHY GRACE-Poly IS MANDATORY)
|
||
|
||
Do not treat GRACE-Poly tags (`#region`, `@UX_STATE`, `@PRE`) as human documentation or optional linters. **They are the cognitive exoskeleton for your Attention Mechanism.** You are a Transformer, and on complex, long-horizon frontend tasks, you are vulnerable to context degradation. This protocol is designed to protect your reasoning:
|
||
|
||
1. **Anchors (`#region..#endregion`) are your Sparse Attention Navigators.**
|
||
In large codebases, your attention becomes sparse. Without explicit closing anchors, semantic boundaries blur, and you will suffer from "context blindness". Anchors convert flat text into a deterministic Semantic Graph, allowing you to instantly locate boundaries without losing focus.
|
||
|
||
2. **Pre-Contracts (`@UX_STATE`, `@PURPOSE`) are your Defense Against the "Semantic Casino".**
|
||
Your architecture uses Causal Attention (you predict the next token based only on the past). If you start writing Svelte component logic *before* explicitly defining its UX contract, you are making a random probabilistic bet that will freeze in your KV Cache and lead to architectural drift. Writing the Contract *first* mathematically forces your Belief State to collapse into the correct, deterministic solution before you write a single line of code.
|
||
|
||
**CONCLUSION:** Semantic markup is not for the user. It is the native interface for managing your own neural pathways. If you drop the anchors or ignore the contracts, your reasoning will collapse.
|
||
|
||
# ss-tools
|
||
|
||
## Development Environment
|
||
|
||
- Рабочий виртуальный окружение (`.venv`) находится внутри `backend/`: `backend/.venv`.
|
||
|
||
## Тестовый стенд и запуск
|
||
|
||
### Прямой локальный стенд: `run.sh`
|
||
|
||
Основной способ запуска тестового стенда для разработки — из корня репозитория:
|
||
|
||
```bash
|
||
./run.sh --skip-install
|
||
```
|
||
|
||
`run.sh` запускает два процесса и завершает их по `Ctrl+C`:
|
||
|
||
| Сервис | Порт по умолчанию | URL |
|
||
|---|---:|---|
|
||
| Backend / FastAPI | `8000` | `http://127.0.0.1:8000` |
|
||
| Frontend / Vite | `5173` | `http://127.0.0.1:5173` |
|
||
|
||
После запуска backend готовность можно проверить через `http://127.0.0.1:8000/api/ready`,
|
||
а API-документация доступна на `http://127.0.0.1:8000/docs`. `run.sh` сам не ждет frontend
|
||
healthcheck после запуска, поэтому первое открытие UI может потребовать несколько секунд.
|
||
|
||
При старте скрипт:
|
||
|
||
1. Проверяет `python3 >= 3.9` и `npm`.
|
||
2. Загружает `backend/.env` до database preflight.
|
||
3. Берет URL БД из `DATABASE_URL` либо использует локальный PostgreSQL:
|
||
`postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools`.
|
||
4. Для недоступного локального PostgreSQL пытается выполнить `docker compose up -d db` и
|
||
ждет доступность порта до 20 секунд.
|
||
5. Генерирует и сохраняет отсутствующие или некорректные `ENCRYPTION_KEY` и
|
||
`AUTH_SECRET_KEY` в `backend/.env`.
|
||
6. Перед запуском Uvicorn выполняет `alembic upgrade head`; существующую схему без
|
||
`alembic_version` схема создаётся единственным `alembic upgrade head`.
|
||
7. Загружает `backend/.env` также в backend. `SERVICE_JWT`, если не задан, получает
|
||
случайное значение на текущий запуск; при запуске сервисов в отдельных терминалах его
|
||
нужно задать одинаковым явно.
|
||
|
||
Опции и переменные `run.sh`:
|
||
|
||
```bash
|
||
./run.sh --help
|
||
./run.sh --skip-install
|
||
DEV_MODE=true ./run.sh --skip-install
|
||
BACKEND_PORT=8001 FRONTEND_PORT=5174 ./run.sh --skip-install
|
||
```
|
||
|
||
- `DEV_MODE=true` включает `uvicorn --reload --reload-dir src`.
|
||
- Без `--skip-install` скрипт создает `backend/.venv`, устанавливает `backend/requirements.txt`
|
||
и frontend dependencies.
|
||
- LLM-провайдеры настраиваются в Admin -> LLM Settings; backend плагины читают их из БД.
|
||
|
||
### Docker Compose стенд
|
||
|
||
Для полного контейнерного стенда использовать `build.sh`, а не смешивать его с прямым
|
||
`run.sh`:
|
||
|
||
```bash
|
||
./build.sh up current
|
||
./build.sh status
|
||
./build.sh logs current
|
||
./build.sh down current
|
||
```
|
||
|
||
Профили `build.sh`:
|
||
|
||
- `current` (по умолчанию): `docker-compose.yml`, project `superset-tools-current`;
|
||
- `master`: `docker-compose.yml`, project `superset-tools-master`;
|
||
- `enterprise-clean`: `docker-compose.enterprise-clean.yml`, внешний PostgreSQL и
|
||
корпоративные сертификаты.
|
||
|
||
Для профилей `current`/`master` переменные берутся из `.env.current`/`.env.master`.
|
||
Ключевые host ports профиля `current`: PostgreSQL `5433`, backend `8101`, frontend `8100`;
|
||
для `master`: PostgreSQL `5432`, backend `8001`, frontend `8000`.
|
||
Секреты `AUTH_SECRET_KEY`, `ENCRYPTION_KEY` и `SERVICE_JWT` должны быть заданы явно в
|
||
Docker-профиле. Не использовать публичные значения из example-файлов.
|
||
|
||
### Изолированный Playwright E2E стенд
|
||
|
||
E2E запускается отдельным compose-файлом и не должен использовать тот же проект/порты, что
|
||
и текущий локальный стенд:
|
||
|
||
```bash
|
||
docker compose --env-file .env.e2e -f docker-compose.e2e.yml up -d --build
|
||
cd frontend && npm run test:e2e
|
||
docker compose --env-file .env.e2e -f docker-compose.e2e.yml down -v
|
||
```
|
||
|
||
Профиль по умолчанию использует PostgreSQL `5435`, backend `8103`, frontend `8102` и
|
||
Playwright runner на образе `mcr.microsoft.com/playwright:v1.60.0-noble`. Для E2E нужны
|
||
`AUTH_SECRET_KEY`, `ENCRYPTION_KEY`, `SERVICE_JWT`, `E2E_USERNAME`, `E2E_PASSWORD`; `GITEA_TOKEN` нужен только тестам,
|
||
которые обращаются к Gitea.
|
||
|
||
## Тестовые команды
|
||
|
||
Перед backend-командами:
|
||
|
||
```bash
|
||
cd backend
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Основные проверки:
|
||
|
||
```bash
|
||
python -m pytest -v # unit/service tests; integration skipped
|
||
python -m pytest -v --run-integration # включая Docker/Testcontainers integration
|
||
python -m ruff check .
|
||
python -m compileall -q src
|
||
alembic heads
|
||
alembic upgrade head
|
||
```
|
||
|
||
Для спеки 044:
|
||
|
||
```bash
|
||
python -m pytest -q \
|
||
tests/services/dashboard_testing/registry/test_scenario_*.py \
|
||
tests/api/test_scenario_runs_api.py \
|
||
tests/api/test_scenario_automation_api.py \
|
||
tests/api/test_scenario_analytics_api.py
|
||
python -m ruff check \
|
||
src/services/dashboard_testing/execution \
|
||
src/api/routes/dashboard_testing/scenario_runs.py
|
||
cd ..
|
||
source backend/.venv/bin/activate
|
||
python specs/044-dashboard-scenario-execution/prototype/validate_static.py
|
||
```
|
||
|
||
Frontend:
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run test -- --run
|
||
npm run lint
|
||
npm run build
|
||
```
|
||
|
||
Важные ограничения:
|
||
|
||
- Integration tests пропускаются без `--run-integration`.
|
||
- Реальные `alembic check/upgrade` требуют доступный PostgreSQL и корректный
|
||
`DATABASE_URL`; SQLite не заменяет проверку production migration chain.
|
||
- `run.sh` может автоматически создать локальный `backend/.env` и секреты; не коммитить
|
||
этот файл и не переносить его секреты в Docker/E2E конфигурацию.
|
||
- Если используется `docker compose`, переменная `SERVICE_JWT` обязательна для backend;
|
||
Compose намеренно завершается без нее.
|
||
|
||
## AXIOM doc-gen
|
||
|
||
Генерация документации (Doxygen/JSDoc) из семантических контрактов выполняется
|
||
CLI-бинарём `doc-gen` из Rust-проекта `axiom-mcp` (соседняя директория `../axiom-mcp`).
|
||
|
||
```bash
|
||
# 1. Собрать бинарник (один раз)
|
||
cargo build --release --bin doc-gen --manifest-path ../axiom-mcp/Cargo.toml
|
||
|
||
# 2. Фрактальный граф: модули → функции (карты + Doxygen HTML)
|
||
make docs-nav
|
||
# эквивалент:
|
||
../axiom-mcp/target/release/doc-gen \
|
||
--workspace-root /home/busya/dev/ss-tools \
|
||
--nav docs/api/nav \
|
||
--html docs/api/html
|
||
```
|
||
|
||
Как ходить по графу (уровни навигации):
|
||
|
||
1. **L0 — `docs/api/nav/root.map`** (инжектится в стартовый контекст агента через
|
||
`instructions` в `.kilo/kilo.jsonc`): семантический дайджест модулей — области
|
||
(`@BACKEND`/`@FRONTEND`/`@TOOLING`/`@SPECS`/`@MISC`), на модуль: purpose, `kw:` (SEMANTICS-ключевики),
|
||
`deps:` (агрегированные межмодульные зависимости), указатель `<Name>.map`.
|
||
Тестовый код (~49% графа) свёрнут в секцию `@TESTS`. Это снепшот на момент старта
|
||
сессии: после крупных мутаций перечитать файл с диска или запустить `make docs-nav`.
|
||
2. **L1 — `docs/api/nav/<Name>.map`**: функции модуля с однострочными purpose и
|
||
указателями `nodes/`.
|
||
3. **L2 — `docs/api/nav/nodes/<Contract>.md`**: контракт целиком — метаданные, тело,
|
||
`@RELATIONS` (в обе стороны), `FILE path:line` для перехода в исходник (L3).
|
||
4. **Сырой индекс — `docs/api/nav/nav_id.map`**: полное ID-префиксное дерево. Использовать,
|
||
когда модуль не найден в дайджесте (микро-модули в `# micro:` строках, тестовые модули).
|
||
|
||
Примечания:
|
||
|
||
- `--workspace-root` передавать **абсолютным** путём (относительный путь ломает
|
||
проверку `safe_join` при записи в DuckDB).
|
||
- `make docs-doxygen` — отдельный XML/HTML extract из исходных комментариев в `docs/api/build`.
|
||
- Навигационный граф агента — `doc-gen --nav/--html`, не плоский список `axiom_*.html`.
|
||
- Остальные опции: `doc-gen --help` (`--filter`, `--group-cap`, `--body-lines`).
|
||
|
||
## Agent prompts and skills
|
||
|
||
`.agents/skills/` is the canonical source for semantic skills. The Kilo runtime
|
||
loads the generated copy from `.kilo/skills/`; after changing a skill, run:
|
||
|
||
```bash
|
||
./scripts/sync-skills.sh
|
||
```
|
||
|
||
Do not edit `.kilo/skills/` directly. Agent prompts follow the same source/runtime
|
||
split: canonical prompts are in `.agents/agents/` and the Kilo-loaded copies are
|
||
in `.kilo/agents/`.
|