Gitnexus Explorer

Индексируйте кодовую базу с помощью GitNexus и разверните интерактивный граф знаний через веб-интерфейс + туннель Cloudflare.

Метаданные навыка

Источник	Опционально — установка: vibeos skills install official/research/gitnexus-explorer
Путь	optional-skills/research/gitnexus-explorer
Версия	1.0.0
Автор	VibeOS + Teknium
Лицензия	MIT
Платформы	linux, macos, windows
Теги	gitnexus, code-intelligence, knowledge-graph, visualization
Связанные навыки	native-mcp, codebase-inspection

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это инструкции, которые видит агент, когда навык активен.

GitNexus Explorer

Индексируйте любую кодовую базу в граф знаний и разверните интерактивный веб-интерфейс для изучения символов, цепочек вызовов, кластеров и потоков выполнения. Туннелирование через Cloudflare для удалённого доступа.

Когда использовать

• Пользователь хочет визуально изучить архитектуру кодовой базы
• Пользователь запрашивает граф знаний / граф зависимостей репозитория
• Пользователь хочет поделиться интерактивным обозревателем кодовой базы с кем-то

Предварительные требования

• Node.js (v18+) — требуется для GitNexus и прокси
• git — репозиторий должен содержать каталог .git
• cloudflared — для туннелирования (автоматически устанавливается в ~/.local/bin, если отсутствует)

Предупреждение о размере

Веб-интерфейс отображает все узлы в браузере. Репозитории до ~5 000 файлов работают хорошо. Крупные репозитории (30 000+ узлов) будут тормозить или приводить к сбою вкладки браузера. Инструменты CLI/MCP работают при любом масштабе — ограничение касается только веб-визуализации.

Шаги

1. Клонирование и сборка GitNexus (однократная настройка)

GITNEXUS_DIR="${GITNEXUS_DIR:-$HOME/.local/share/gitnexus}"

if [ ! -d "$GITNEXUS_DIR/gitnexus-web/dist" ]; then
  git clone https://github.com/abhigyanpatwari/GitNexus.git "$GITNEXUS_DIR"
  cd "$GITNEXUS_DIR/gitnexus-shared" && npm install && npm run build
  cd "$GITNEXUS_DIR/gitnexus-web" && npm install
fi

2. Патч веб-интерфейса для удалённого доступа

Веб-интерфейс по умолчанию использует localhost:4747 для API-вызовов. Исправьте его на тот же источник, чтобы он работал через туннель/прокси:

Файл: $GITNEXUS_DIR/gitnexus-web/src/config/ui-constants.ts Измените:

export const DEFAULT_BACKEND_URL = 'http://localhost:4747';

На:

export const DEFAULT_BACKEND_URL = typeof window !== 'undefined' && window.location.hostname !== 'localhost' ? window.location.origin : 'http://localhost:4747';

Файл: $GITNEXUS_DIR/gitnexus-web/vite.config.ts Добавьте allowedHosts: true внутрь блока server: { } (только если запускается в режиме разработки вместо production-сборки):

server: {
    allowedHosts: true,
    // ... остальная конфигурация
},

Затем соберите production-бандл:

cd "$GITNEXUS_DIR/gitnexus-web" && npx vite build

3. Индексация целевого репозитория

cd /path/to/target-repo
npx gitnexus analyze --skip-agents-md
rm -rf .claude/    # удалить артефакты, специфичные для Claude Code

Добавьте --embeddings для семантического поиска (медленнее — минуты вместо секунд).

Индекс хранится в .gitnexus/ внутри репозитория (автоматически добавляется в .gitignore).

4. Создание скрипта прокси

Запишите это в файл (например, $GITNEXUS_DIR/proxy.mjs). Он обслуживает production веб-интерфейс и проксирует /api/* на бэкенд GitNexus — один источник, без CORS-проблем, без sudo, без nginx.

import http from 'node:http';
import fs from 'node:fs';
import path from 'node:path';

const API_PORT = parseInt(process.env.API_PORT || '4747');
const DIST_DIR = process.argv[2] || './dist';
const PORT = parseInt(process.argv[3] || '8888');

const MIME = {
  '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css',
  '.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml',
  '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff',
  '.wasm': 'application/wasm',
};

function proxyToApi(req, res) {
  const opts = {
    hostname: '127.0.0.1', port: API_PORT,
    path: req.url, method: req.method, headers: req.headers,
  };
  const proxy = http.request(opts, (upstream) => {
    res.writeHead(upstream.statusCode, upstream.headers);
    upstream.pipe(res, { end: true });
  });
  proxy.on('error', () => { res.writeHead(502); res.end('Backend unavailable'); });
  req.pipe(proxy, { end: true });
}

function serveStatic(req, res) {
  let filePath = path.join(DIST_DIR, req.url === '/' ? 'index.html' : req.url.split('?')[0]);
  if (!fs.existsSync(filePath)) filePath = path.join(DIST_DIR, 'index.html');
  const ext = path.extname(filePath);
  const mime = MIME[ext] || 'application/octet-stream';
  try {
    const data = fs.readFileSync(filePath);
    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'public, max-age=3600' });
    res.end(data);
  } catch { res.writeHead(404); res.end('Not found'); }
}

http.createServer((req, res) => {
  if (req.url.startsWith('/api')) proxyToApi(req, res);
  else serveStatic(req, res);
}).listen(PORT, () => console.log(`GitNexus proxy on http://localhost:${PORT}`));

5. Запуск сервисов

# Терминал 1: бэкенд API GitNexus
npx gitnexus serve &

# Терминал 2: прокси (веб-интерфейс + API на одном порту)
node "$GITNEXUS_DIR/proxy.mjs" "$GITNEXUS_DIR/gitnexus-web/dist" 8888 &

Проверка: curl -s http://localhost:8888/api/repos должен вернуть проиндексированные репозитории.

6. Туннелирование через Cloudflare (опционально — для удалённого доступа)

# Установка cloudflared при необходимости (без sudo)
if ! command -v cloudflared &>/dev/null; then
  mkdir -p ~/.local/bin
  curl -sL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
    -o ~/.local/bin/cloudflared
  chmod +x ~/.local/bin/cloudflared
  export PATH="$HOME/.local/bin:$PATH"
fi

# Запуск туннеля (--config /dev/null предотвращает конфликты с существующими именованными туннелями)
cloudflared tunnel --config /dev/null --url http://localhost:8888 --no-autoupdate --protocol http2

URL туннеля (например, https://random-words.trycloudflare.com) выводится в stderr. Поделитесь им — любой, у кого есть ссылка, сможет исследовать граф.

7. Очистка

# Остановка сервисов
pkill -f "gitnexus serve"
pkill -f "proxy.mjs"
pkill -f cloudflared

# Удаление индекса из целевого репозитория
cd /path/to/target-repo
npx gitnexus clean
rm -rf .claude/

Подводные камни

• --config /dev/null обязателен для cloudflared, если у пользователя есть существующая конфигурация именованного туннеля в ~/.cloudflared/config.yml. Без этого параметра правило catch-all ingress в конфиге возвращает 404 для всех запросов быстрого туннеля.

• Production-сборка обязательна для туннелирования. Dev-сервер Vite по умолчанию блокирует хосты, отличные от localhost (allowedHosts). Production-сборка + Node-прокси полностью обходят эту проблему.

• Веб-интерфейс НЕ создаёт .claude/ или CLAUDE.md. Они создаются командой npx gitnexus analyze. Используйте --skip-agents-md, чтобы подавить markdown-файлы, затем rm -rf .claude/ для остального. Это интеграции Claude Code, которые не нужны пользователям vibeos-agent.

• Ограничение памяти браузера. Веб-интерфейс загружает весь граф в память браузера. Репозитории с 5 000+ файлов могут тормозить. 30 000+ файлов, скорее всего, приведут к сбою вкладки.

• Эмбеддинги опциональны. --embeddings включает семантический поиск, но занимает минуты на крупных репозиториях. Пропустите для быстрого исследования; добавьте, если хотите запросы на естественном языке через панель AI-чата.

• Несколько репозиториев. gitnexus serve обслуживает ВСЕ проиндексированные репозитории. Проиндексируйте несколько репозиториев, запустите serve один раз, и веб-интерфейс позволит переключаться между ними.