helperium

Imported from trash2bin/helperium (AGENTS.md). Install upstream with npx skills add trash2bin/helperium. Copyright stays with the author.

AGENTS.md — навигация и операционный контракт, а не дневник разработки. Датированные аудиты, benchmark runs и исполненные планы сохраняются как evidence в doc/; их выводы не заменяют проверку текущего кода и тестов.

Назначение и границы

Helperium — self-hosted платформа, которая подключает клиентскую SQL-базу в read-only режиме, интроспектирует схему и предоставляет LLM-агенту tenant-scoped MCP-инструменты. Встраиваемый чат отвечает по живым данным; администратор управляет tenant-конфигурацией, агентами и policy.

demo/autoparts-store — автономный поддерживаемый demo consumer, а не часть production runtime Helperium (но используется в публичном демо). Его код и deployment-конфигурацию можно менять для security, integration design и воспроизводимости; не останавливай, не seed'ируй и не очищай его контейнеры или PostgreSQL без отдельного прямого разрешения. Он должен подключаться как обычный demo tenant.

Критический data flow

Embed widget → api-service → LLM/orchestrator → MCPClient
  → mcp-gateway /mcp → data-service ( or RAG) → tenant DB
  → SSE (tool_call/tool_result/final/error/done) → widget

Admin flow: admin-dashboard → api-service/data-service; tenant onboarding идёт через POST /admin/tenants, затем manifest/config generation. Агент не должен получать сырой DSN, секреты или cross-tenant scope из browser-controlled headers.

Неподвижные контракты

Как работать с репозиторием

Сначала прочитай релевантный маршрут ниже (или похожий), затем используй graph/codebase memory/grep/find, и подтверди связи кодом или tests. Используй services READMEs и test suite — не делай предположений по старому audit text.

Меняй контракт API, schema, tenant model или public tool surface только после явного подтверждения пользователя. Обычные bug fixes, безопасная documentation hygiene, broken links и isolated test regressions можно исправлять самостоятельно. Каждый подтверждённый defect получает regression test; каждый code change проходит ближайший targeted suite и, если затронуты сервисные границы, Docker E2E

При нахождении бага и особенно уязвимости безопасности сначала test потом рабочий код (тест обязан падать!).

Проверка

make ci                         # полный local CI
make ci-docs                    # links и AGENTS catalog coverage
make ci-test-py                 # Python unit/integration
make ci-test-go                 # Go suites
make ci-test-embed              # widget tests + build
make ci-admin                   # admin-dashboard tests

Полный isolated Docker E2E. compose.sh --profile test принудительно заменяет local .env на test-only secure MCP/API credentials, explicit MCP Origin policy и повышенные только для E2E rate limits; не передавай production-named secrets вручную. При необходимости используй только MCP_TEST_* и API_TEST_BEARER_TOKEN.

# ci-state-init is a one-shot permission bootstrap; do not attach it to
# --abort-on-container-exit. Start long-lived dependencies, then run e2e alone.
ADMIN_TOKEN=ci-admin-token VIEWER_TOKEN=ci-viewer-token CORS_ALLOW_ORIGINS=http://localhost:8080 \
  ./infra/scripts/compose.sh --profile test up -d data-service mcp-gateway api admin-dashboard web
ADMIN_TOKEN=ci-admin-token VIEWER_TOKEN=ci-viewer-token CORS_ALLOW_ORIGINS=http://localhost:8080 \
  ./infra/scripts/compose.sh --profile test run --rm e2e

После Docker run очисти только Helperium test resources:

ADMIN_TOKEN=ci-admin-token VIEWER_TOKEN=ci-viewer-token CORS_ALLOW_ORIGINS=http://localhost:8080 \
  ./infra/scripts/compose.sh --profile test down -v

Не трогай autoparts-store-* это отдельный демо с виджетом и своей бд на pg. Shared infra_helperium-net может остаться, если им пользуется заранее поднятый infra-rag-1 или внешний storefront.

Документация и артефакты

Живые service guides находятся рядом с кодом. Датированные audits, incidents, plans и benchmark analyses — архивные evidence snapshots: не удаляй их молча и не называй их current verdict без проверки текущего HEAD. Новый архивный документ добавляй только когда он содержит самостоятельное измерение/решение; иначе обновляй существующий README или guide.

CHANGELOG.md пополняется одной краткой записью на commit. Не используй его как рабочие заметки или полный отчёт тестового прогона. Verification markers в документах описывают commit, на котором текст сверялся; при содержательной правке обновляй marker и ссылку на актуальный test evidence.

Полный каталог для discoverability

Коммит происходит только по скиллу, а также перед коммитом работает pre-commit, который способен править файлы тем самым раняя git commit. Файлы убираются из индекса и их стоит заново git add.