Этот маршрут рассчитан на уже развёрнутый CodeGraph. Администратор должен сообщить адреса UI и
API, выдать личную учётную запись и доступ к группе проектов. Для нового сервера сначала
используйте руководство по установке. В примерах ниже <UI_URL> и <API_URL>
означают адреса именно вашего экземпляра; адрес API указывайте без завершающего /api/v1.
1. Проверьте доступность экземпляра
Откройте <UI_URL>/dashboard/login и войдите под личной учётной записью. Каталог проектов находится
по адресу <UI_URL>/dashboard/projects. Проверьте <API_URL>/api/v1/health/ready;
успешный ответ подтверждает доступность API. Интерактивная схема всех REST-запросов находится по
адресу <API_URL>/api/docs, OpenAPI JSON — <API_URL>/api/openapi.json.
Для администратора: создайте учётную запись и выдайте доступ
Если учётной записи ещё нет, администратор создаёт её через POST /api/v1/admin/identity/users.
Сначала он получает токен через POST /api/v1/auth/token с телом
{"username":"<admin-login>","password":"<admin-password>"} и находит идентификатор существующей
группы через GET /api/v1/groups. Пример тела запроса создания пользователя:
{
"username": "engineer.one",
"role": "analyst",
"tenant_id": "<GROUP_ID_FROM_GET_GROUPS>",
"change_reason": "Создание личной учётной записи инженера"
}
Запрос передают с Authorization: Bearer <admin-access-token>. tenant_id задаёт контекст
административного действия в журнале. Доступ к проекту выдайте отдельным запросом, описанным ниже.
Ответ содержит id и одноразовый
temporary_password: передайте пароль человеку по защищённому каналу. Системная роль analyst
подходит обычному разработчику; reviewer имеет дополнительные права на review, согласования и
операции повышенного риска. viewer предназначен для просмотра, admin — для администрирования.
Доступ к исходникам проекта администратор выдаёт отдельно через
PUT /api/v1/admin/identity/users/{user_id}/access, где {user_id} — id из ответа выше:
{
"tenant_id": "<GROUP_ID_FROM_GET_GROUPS>",
"change_reason": "Доступ инженера к выбранному проекту",
"assignments": [{
"group_id": "<GROUP_ID_FROM_GET_GROUPS>",
"role": "editor",
"project_scope_mode": "selected",
"allowed_project_ids": ["<PROJECT_ID_FROM_GET_PROJECTS>"]
}]
}
editor — роль пользователя в группе. Системную роль и роль в группе назначают отдельно.
В группе также есть viewer и admin. Идентификатор проекта берите из GET /api/v1/projects после импорта. Если проект ещё не
создан, сначала импортируйте его, затем выдайте доступ. PUT /access заменяет весь набор
назначений пользователя: перед изменением существующего аккаунта прочитайте
GET /api/v1/admin/identity/users/{user_id}/access и сохраните нужные назначения.
После назначения доступа повторите GET /api/v1/admin/identity/users/{user_id}/access и проверьте роль editor, режим selected и ID выбранного проекта. Затем войдите под учётной записью инженера и откройте каталог проектов.
2. Выберите или импортируйте проект
Откройте <UI_URL>/dashboard/repositories, выберите подключённого Git-провайдера и импортируйте
репозиторий. Затем проверьте проект в <UI_URL>/dashboard/projects. Для импорта без подключения
провайдера используйте REST-пример и серверную CLI-команду.
Не помещайте логин или токен в URL репозитория.
CPG (Code Property Graph) — граф исходного кода, включая функции, вызовы и зависимости.
Каталог показывает зарегистрированные проекты. Перед анализом проверьте статус задания импорта
и актуальность CPG выбранного проекта. При stale, pending или failed сначала обновите граф.
3. Выполните первую задачу
Для первого аудита администратор подключается по SSH к Ubuntu-серверу, переходит в каталог установки CodeGraph и выполняет команду ниже. Путь к базе берите из настроенного проекта; путь к исходникам должен быть виден контейнеру API. Это детерминированный JSON-отчёт без вывода языковой модели:
sudo docker compose -f docker-compose.yml exec -T api python -m src.cli audit \
--db '<CPG_DB_PATH>' --source-path '<PROJECT_SOURCE_PATH>' \
--profile standard --format json --skip-llm-conclusion --skip-persistence \
--output '<AUDIT_OUTPUT_PATH>'
Замените все три шаблона путями внутри контейнера API. Каталог отчёта должен существовать
и быть доступен для записи. --skip-persistence отключает сохранение отчёта в хранилище
и автоматическое обновление CPG; указанный JSON-файл команда всё равно записывает.
При ошибке audit_cpg_refresh_required обновите проект через согласованный процесс импорта
и повторите ту же команду на актуальном графе.
Проверьте файл отчёта, ревизию исходников и ограничения анализа. Подробности — в руководстве по аудиту CPG. Затем начните с вопроса с проверяемым результатом, например:
- найдите точки входа компонента;
- оцените последствия изменения конкретного символа;
- проверьте ограниченный диапазон коммитов;
- объясните цепочку зависимости и укажите исходные файлы.
Для первой задачи выберите один компонент или диапазон коммитов. Проверьте, что ответ указывает выбранный проект и исходные файлы. Сопоставьте результат с актуальностью графа и доступностью данных.
4. Подключите клиент и документацию проекта
Установите Codex CLI или поддерживаемый Agent Plugins-клиент на Windows, macOS либо Ubuntu.
Адрес MCP и пакет клиента получите у администратора вашего экземпляра; для опубликованного
удалённого сервиса используйте инструкцию по OAuth и MCP.
После входа вызовите read-only инструмент codegraph_runtime_stack_status_get с пустым объектом
аргументов. Полный MCP-вызов выглядит так:
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"codegraph_runtime_stack_status_get","arguments":{}}}
Отправляйте запрос через инициализированную MCP-сессию после авторизации. Сначала
проверьте tools/list в настроенном подключении. Если инструмент недоступен в активном
профиле, запросите у администратора подключение для просмотра состояния среды. Ответ инструмента
содержит адаптеры агентов, пулы runtime, профили песочницы и управляемые сессии.
Проверьте health.status и health.worker_health для настроенных адаптеров.
Готовность графа выбранного проекта проверьте по заданию импорта
и актуальности CPG, как описано в шаге 2.
Откройте локальный checkout выбранного проекта. В его AGENTS.md укажите фактический каталог
документации. Удобный минимум: README.md с назначением и запуском, docs/ с архитектурой,
API, эксплуатацией и проверками. Если команда использует OpenSpec, укажите существующий каталог
спецификаций.
Для небольшого исправления создайте именованную лёгкую задачу с владельцем, областью и критерием готовности. Для новой функции подготовьте требования, критерии приёмки и полную задачу по принятому в вашей команде процессу. Права и доступность инструментов определяет администратор.
Если нужен поиск по документации и долговременная память, попросите администратора включить OpenViking по руководству конфигурации. Для аудита только исходного кода эта подсистема не обязательна.
5. Посмотрите встроенное демо
Чтобы изучить интерфейс без импорта документов заказчика, откройте
/dashboard/onboarding-research и выберите демо-профиль. Демонстрационные данные объясняют
сценарий работы; результаты по вашему проекту появляются после его импорта и построения CPG.
Настройте автоматические проверки проекта
После импорта подключите события репозитория. Вебхук push передаёт новые коммиты для обновления CPG; события pull request или merge request запускают подготовку ревью. Выберите руководство вашего Git-сервера:
- GitHub: подключение репозитория, вебхук и ревью pull request.
- GitLab: подключение репозитория, вебхук и ревью merge request.
- GitVerse: вебхук, синхронизация и публикация ревью pull request.
- SourceCraft: координаты репозитория, вебхук и ревью merge request.
Настройте события для выбранных веток и проверьте обработку тестового push: дождитесь задания синхронизации и сравните коммит CPG с коммитом репозитория. Для PR/MR проверьте результат ревью и его публикацию в целевом запросе.
Контроль архитектуры объясняет, как описать компоненты и разрешённые зависимости в YAML, проверить правила и включить их в проверку изменений.
Чтобы запускать проверки регулярно, настройте автоматические аудиты проекта: выберите периодичность, часовой пояс, сервисный аккаунт и правила обработки пропущенных запусков. Проверьте первый запуск и сохранённый отчёт.
Если первый запуск не удался
- Проект не виден: попросите администратора проверить tenant- и project-доступ.
- CPG отсутствует или устарел: дождитесь обновления проекта или запросите его.
- Результат заблокирован: сохраните причину и идентификатор сессии для поддержки.
- Ответ не содержит исходных свидетельств: сузьте вопрос и проверьте выбранный проект.
Далее: Установка · Конфигурация · Каталог сценариев