---

Проверки без неявного долгого прогона

Обычные test, check и coverage используют быстрый набор. Долгие интеграционные проверки и реальные ожидания retry/timeout сохраняются в slowTest и запускаются только вручную: cd backend && ./gradlew slowTest либо через GitHub Actions Manual slow integration. В release verifier для этого нужен явный --run-slow; по умолчанию этап отмечается NOT_RUN. Live/E2E также требуют явного запуска.

Для быстрого backend-набора зафиксирован измеренный coverage baseline 79,05%; прежний общий порог 79,38% сохранён в ручном fullCheck. Порог bot остаётся 82,47%. Отчёты разделены: быстрый coverage не читает старый slowTest.exec.

🎯 Позиционирование

Java Agent — Java/Spring Boot agent-платформа для FerrPOINT: LLM runtime, OpenAI-compatible API, built-in tools, MCP client/server, Telegram gateway и standalone CLI REPL.

AGENTS.md — канонический development guide; README — публичная точка входа.

📌 Snapshot

Поле	Значение
Модули	backend, telegram-bot, cli (+ shared DTO)
Runtime	Temurin 25.0.4.1+1 LTS, Spring Boot 4.1; workspace Gradle 9.6.1, standalone backend 9.8.1
Data	PostgreSQL 16, JPA/Hibernate, Flyway
AI/tooling	LangChain4j 1.18, MCP Java SDK 2.0, Repomix MCP, built-in tool registry
Interfaces	REST/SSE, OpenAI-compatible /v1/*, Telegram bot, CLI REPL
Base workspace	Local Compose: API 1180, PostgreSQL 1181, Telegram gateway 1182, SearXNG 1183 (all loopback-only)
Тесты	6221 (backend 4710 + bot 1511), 567 файлов, 0 падений
License	FerrPOINT Proprietary Source-Available Evaluation License v1.0

✨ Features

Feature	Описание
Agent runtime	Sync и SSE chat, sessions, checkpoints, rollback и undo.
OpenAI-compatible API	Chat completions, streaming, models, capabilities и toolsets.
Built-in tools	File, terminal, web, browser, memory, skills, cron, delegation, TTS, image generation и vision.
Context engine	Compression, history sanitizing, replay cleanup и runtime settings.
Memory loop	Background review с approval gate и prompt injection одобренных фактов.
MCP	Client/server, dynamic tool discovery и Repomix integration.
Telegram gateway	Streaming, media handling, model override, steer mode, busy-ack, group filters и inline keyboards.
CLI REPL	92 slash-команды, SSE streaming, JLine autocomplete и markdown rendering.
Deployment/test matrix	Production, local и E2E compose-профили, Flyway migrations и большой regression suite.

🔧 Core Stack

Layer	Stack
Backend	Java 25, Spring Boot 4.1, Spring Framework 7, Spring Security, WebSocket, Actuator
Persistence	PostgreSQL 16, JPA/Hibernate, Flyway 12, Testcontainers
LLM/MCP	LangChain4j 1.21.0, OpenAI-compatible clients, MCP Java SDK 2.0, Repomix
CLI	Spring Boot, Picocli, JLine, ANSI Markdown renderer
Bot	Telegram Bot API client, polling/webhook, streaming/edit-message delivery
Codegen/helpers	Lombok, MapStruct, Jackson 3, Pebble templates, Resilience4j

🔌 API

Endpoint	Назначение
POST /api/v1/agent/chat	Sync chat
POST /api/v1/agent/chat/stream	SSE streaming chat
POST /api/v1/agent/steer	Inject message в активный run
POST /v1/chat/completions	OpenAI-compatible chat completions
GET /v1/models	Model list
GET /v1/capabilities	Machine-readable capabilities
GET /v1/toolsets	Toolsets и tools
GET/POST /api/v2/sessions	Session list/create
GET/POST /api/v1/admin/users	Multi-user admin: create/list users
POST /api/v1/admin/users/{id}/keys	Issue per-user API key (raw key возвращается один раз)
DELETE /api/v1/admin/users/keys/{keyId}	Revoke an API key
GET /health	Safe runtime health summary
GET /bot/health (gateway)	Состояние процесса bot-сервиса; не end-to-end проверка Telegram API

Multi-user и аутентификация

Общий вход SDLC включается явно через agent.central-auth.enabled=true: используется bearer собственного Auth, действующая сессия и owner scope без fallback на global key. Настройки и ограничения — общая авторизация. Ниже описан standalone-режим при выключенном общем входе.

• Global key (agent.security.api-key, env API_SERVER_KEY) — админ-доступ; когда пуст — auth выключен (dev-режим).
• Per-user ключи (agk_…) выдаются админом через /api/v1/admin/users/{id}/keys, хранится только SHA-256 fingerprint. Держатель ключа получает свою userId-область: сессии, память, cron, чекпойнты, usage; приватные скиллы других юзеров недоступны.
• CLI: ключ задаётся env AGENT_API_KEY (или CLI_API_KEY) и уходит заголовком X-API-Key на каждый запрос.
• Порядок включения: задать API_SERVER_KEY → создать админа/юзеров через REST (глобальным ключом) → выдать per-user ключи → раздать юзерам.

Доступ пользователей Telegram-бота

Доступ задаётся только списком числовых Telegram user ID в BOT_ALLOWED_USER_IDS; это не ID чата и не username. Пустой список запрещает доступ всем. Для добавления или удаления измените список через запятую, сохранив ID остальных пользователей:

BOT_ALLOWED_USER_IDS=123456789,987654321

Пример ID условный. На systemd-установке отредактируйте environment-файл, указанный в EnvironmentFile сервиса java-agent-bot.service (для текущего dev — /opt/dev/java-agent/.env), и перезапустите только бот:

sudo systemctl restart java-agent-bot.service
sudo systemctl is-active java-agent-bot.service

Для Docker Compose измените значение в используемом env-файле и пересоздайте сервис бота командой docker compose --env-file <env-файл> -f <compose-файл> up -d --no-deps --force-recreate <сервис-бота>; обычный restart не обновляет переменные контейнера. Список читается при запуске, поэтому изменения не действуют до перезапуска или пересоздания. Проверяйте доступ с разрешённого и удалённого аккаунтов; статус процесса сам по себе проверку доступа не заменяет. Эти настройки не управляют доступом к backend API.

🖥️ CLI

Build jars:

./gradlew :backend:bootJar :telegram-bot:bootJar :cli:bootJar

Run backend:

cd backend
java -jar build/libs/backend-0.0.1-SNAPSHOT.jar \
  --spring.profiles.active=dev \
  --server.port=8090

Run a NoOp backend без LLM/PostgreSQL:

cd backend
java -jar build/libs/backend-0.0.1-SNAPSHOT.jar \
  --spring.profiles.active=noop \
  --server.port=8090

Run CLI:

cd cli
java -jar build/libs/cli-0.0.1-SNAPSHOT.jar --backend.url=http://localhost:8090

Streaming smoke:

curl -N -X POST http://localhost:8090/api/v1/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message":"Привет"}'

OpenAI-compatible smoke:

curl -s -X POST http://localhost:8090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"kimi-k2.6","messages":[{"role":"user","content":"hi"}]}'

CLI — отдельный Spring Boot модуль, не зависит от backend-кода и общается с ним через REST: REPL со slash-командами (/new, /status, /compress, /undo, /checkpoint, /rollback, /memory, /skills, /help и др.), SSE streaming и JLine autocomplete.

В CLI и Telegram-боте /help показывает короткий старт и основные доступные команды. /help all открывает полный каталог; существующие aliases продолжают работать. Неизвестный аргумент справки объясняет эти два варианта. Справка формируется локально из registry и не вызывает AI-провайдера.

🏗️ Architecture

flowchart TD
    Client[REST/SSE clients] --> Backend[Spring Boot backend]
    OpenAI[OpenAI-compatible clients] --> Backend
    CLI[CLI REPL] --> Backend
    Bot[Telegram bot] --> Backend
    Backend --> Runtime[Agent runtime]
    Runtime --> Tools[Tool registry]
    Runtime --> Context[Context + memory]
    Runtime --> Model[LLM providers]
    Tools --> MCP[MCP clients/servers]
    Runtime --> DB[(PostgreSQL)]
    Bot --> Telegram[Telegram API]

Loading

🚀 Deployment

# Bash launcher for the existing initialized SDLC workspace.
SDLC_WORKSPACE_DIR=/path/to/sdlc2 SDLC_PROJECT=sdlc2 ./scripts/deploy-dev-docker.sh

Launcher вызывает PowerShell7 workspace.ps1 Start -Service java-agent-backend в явно выбранном workspace. Он запускает уже принятый образ; Build/Apply нового кандидата выполняются отдельно штатным helper. Профиль должен совпадать с SDLC_PROJECT (sdlc1, sdlc2, sdlc3), иметь initialized=true и существующий runtime внутри своего workspace. При необходимости путь к Python3 задаётся через SDLC_PYTHON; тот же interpreter передаётся workspace helper. Docker/systemd команды, chown, создание volumes и fresh init этим launcher не выполняются. Launcher и квалифицированный Base helper должны быть установлены в выбранном workspace.

Standalone Compose-файлы ниже остаются отдельными шаблонами, не маршрутом запуска инициализированного SDLC. Временные локальные QA/build из этих шаблонов оформляются через Base ComposeHelper v2 с собственным project и cleanup; постоянный SDLC управляется workspace helper.

Пути состояния, права, перенос старого writable layer, rollback и TTL описаны в контракте хранения.

The CLI image packages LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md inside its executable JAR under META-INF, alongside the license metadata. Profile regression tests load the shipped application.yml and verify that AGENT_MODEL_* overrides retain priority over legacy Ollama/OpenAI variables, while the legacy settings and operational defaults continue to work. CI enforces the existing backend and bot coverage floors after all module tests finish; a missing required LINE report fails the gate.

Compose file	Назначение
scripts/deploy-dev-docker.sh	Адресный Start существующего Java backend через helper выбранного workspace
docker-compose.dev.yml	Отдельный standalone-шаблон backend/bot; workspace launcher его не использует
docker-compose.prod.yml	Production-like stack на порту 8080 с PostgreSQL 5432
docker-compose.local.yml	Local dev fixture на 18090/18091
docker-compose.e2e.yml	E2E testing stack

Docker images используют eclipse-temurin:25-jre-noble; slim-образы ставят Chromium at runtime.

🧱 Boundaries

• Production deployment обязан предоставить реальные model credentials, DB credentials, API keys и настройки secret redaction.
• Browser, file, terminal и network tools требуют явной operational policy до exposures за пределами trusted environments.
• server.shutdown: immediate сохраняется как workaround Spring Boot 4.1.
• Actuator readiness проверяет БД; LLM, browser и MCP availability — отдельные operational concerns и readiness не блокируют.
• Java/Gradle артефакты упаковываются с proprietary license metadata; сторонние зависимости остаются под своими лицензиями.

🛡️ Quality Bar

Проверка	Команда
Full local evidence	python3 scripts/release_verify.py
Module tests	./gradlew :backend:test :telegram-bot:test :cli:test --no-daemon
Slow PostgreSQL integration	./gradlew :backend:slowTest --no-daemon
Coverage reports	./gradlew :backend:jacocoTestReport :telegram-bot:jacocoTestReport --no-daemon
Docs & test-standard ratchet	python3 scripts/check_docs_standard.py (baseline: docs/standards/coverage-baseline.json)
Ratchet + coverage floors	python3 scripts/check_docs_standard.py --check-coverage
Local Docker E2E	./scripts/e2e-docker-compose-test.sh
README invariants	python3 -m unittest scripts.tests.test_verify_readme -v и python3 scripts/verify_readme.py
Compose bot/backend auth wiring	python3 scripts/check-compose-backend-auth.py

release_verify.py фиксирует pass/fail/not-run gates, точные счётчики тестов, JaCoCo-метрики и консервативный endpoint-reference inventory в build/release-verification.json. HTTP и CLI E2E опциональны: им нужен живой локальный backend; Docker E2E опционален, потому что поднимает изолированный стек.

Стандарт документации и тестов

Usage записывается через UsagePersistenceService: блокировка строки сессии и insert выполняются в одной транзакции. Если удаление завершилось первым, запись пропускается; если первой записалась usage, последующее удаление очищает её через существующий ON DELETE CASCADE. JVM mutex не заменяет эту гарантию: Spring завершает транзакцию после возврата сервисного метода.

Mid-turn batches также проверяют и блокируют сессию внутри транзакции записи. Если удаление завершилось первым, batch считается flushed, чтобы следующий tool batch не повторял запись в удалённую сессию. Проверка снаружи транзакции не защищает от удаления, включая вызов prune во внешней транзакции.

Обычная запись user/turn messages также блокирует сессию один раз на всю транзакцию. Streaming auto-title вызывается после successful commit и освобождения mutex; при ошибке сохранения transcript генерация title пропускается.

OpenAI-compatible history/turn, runtime incoming/batch, streaming, compression и cron mirror используют тот же parent WRITE lock внутри транзакции записи. Compression snapshot и immutable watermark хранятся в текущем вызове: параллельная compression другой сессии не меняет набор исходных message IDs.

CI проверяет обе очередности usage и всех перечисленных transcript writers, порядок блокировок compression/delete и границы title на PostgreSQL командой ./gradlew :backend:slowTest --tests 'com.azhukov.agent.service.*PersistenceConcurrencyTest' --no-daemon. Для локальной проверки задать USAGE_PERSISTENCE_TEST_JDBC_URL, USAGE_PERSISTENCE_TEST_DB_USER, USAGE_PERSISTENCE_TEST_DB_PASSWORD отдельной QA базы; без URL тест использует H2. Тест создаёт и удаляет только собственную уникальную schema. Локальный PostgreSQL запускать через временный Compose project по правилам Base LOCAL_GROUPS.md.

Действует для всего кода: docs/standards/documentation.md (краткая версия — в AGENTS.md). Суть:

• Javadoc на классах ≥50 строк и кросс-пакетных контрактах; без воды («responsible for», «utility class» — линтер отклоняет).
• @AgentTool.description — контракт для LLM, не подпись.
• Каждый багфикс — regression-тест; каждая backend refuse-ветка — lane в бот-классификаторе ошибок; enum-сравнения провайдер-мета — оба регистра.
• Ratchet в CI (job docs): нарушения документации и LINE-покрытие не могут деградировать ниже baseline (docs/standards/coverage-baseline.json); baseline растёт только вместе с тестами.

GitHub Actions прогоняет README-evidence, docs-ratchet, tests, bootJar build и Markdown/YAML lint; Docker Compose E2E и smoke запускаются локально по необходимости.

🧭 Project Map

java-agent/
├── backend/       # REST API, agent runtime, tools, MCP, persistence
├── telegram-bot/  # Telegram gateway, command handlers, streaming, media
├── cli/           # standalone REPL и REST client
├── shared/        # общие REST DTO и client helpers
├── e2e/           # декларативные HTTP и CLI сценарные наборы
├── docs/          # архитектура, parity, hardening и operational документация
└── scripts/       # детерминированные локальные проверки

📚 Документы

• AGENTS.md — канонический development guide и текущие факты проекта.
• docs/standards/documentation.md — действующий стандарт документации и тестов (ratchet, baseline).
• docs/README.md — обзор документации.
• docs/01-scope.md, docs/02-core-architecture.md, docs/03-dependency-map.md — scope и архитектура.
• docs/09-builtin-tools.md — built-in tools.
• docs/10-production-readiness.md, backend/docs/13-production-hardening.md — hardening notes.
• backend/docs/11-chromium.md, backend/docs/12-streaming.md — browser и streaming детали.
• backend/docs/conventions.md — Lombok, records и MapStruct конвенции.
• e2e/README.md — карта исполненных сценариев и ограничения evidence.

🔒 License

Proprietary source-available. Not open source.

Viewing/evaluation only.

Commercial, production, resale, redistribution, SaaS/hosting use require written license from FerrPOINT. См. LICENSE, NOTICE и THIRD_PARTY_NOTICES.md.

Разработка UI со справочником Base

Порядок для разработчика и ИИ: версия UI → check → поиск/карточка → один пример → интеграция → проверка поведения. Применять при разработке web UI; Java/CLI/Telegram не требуют установки UI. CLI читается прямо из явно выбранного Base checkout на Node 22. Полный каталог и запуск Storybook/API для offline-поиска не нужны. Общие компоненты и брендинг исправляются в Base, данные и правила остаются у продукта.