Gitnexus Explorer

使用 GitNexus 索引代碼庫，並通過 Web UI + Cloudflare 隧道提供交互式知識圖譜服務。

技能元數據


來源	可選 — 使用 `hermes skills install official/research/gitnexus-explorer` 安裝
路徑	`optional-skills/research/gitnexus-explorer`
版本	`1.0.0`
作者	Hermes Agent + Teknium
許可證	MIT
標籤	`gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization`
相關技能	`native-mcp`, `codebase-inspection`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

GitNexus Explorer

將任意代碼庫索引為知識圖譜，並提供交互式 Web UI 以探索符號、調用鏈、集群和執行流。通過 Cloudflare 隧道實現遠程訪問。

何時使用

用戶希望可視化地探索代碼庫的架構
用戶請求倉庫的知識圖譜/依賴圖譜
用戶希望與他人共享交互式代碼庫瀏覽器

前置條件

Node.js (v18+) — GitNexus 和代理所需
git — 倉庫必須包含 .git 目錄
cloudflared — 用於隧道連接（如果缺失，會自動安裝到 ~/.local/bin）

大小警告

Web UI 會在瀏覽器中渲染所有節點。文件數少於 ~5,000 的倉庫運行良好。大型倉庫（30k+ 節點）會導致瀏覽器標籤頁運行緩慢或崩潰。CLI/MCP 工具在任何規模下均可正常工作 — 僅 Web 可視化存在此限制。

步驟

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. 修補 Web UI 以支持遠程訪問

Web UI 默認使用 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 在 server: { } 塊內添加 allowedHosts: true（僅在運行開發模式而非生產構建時需要）：

server: {
    allowedHosts: true,
    // ... existing config
},

然後構建生產包：

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

3. 索引目標倉庫

cd /path/to/target-repo
npx gitnexus analyze --skip-agents-md
rm -rf .claude/    # remove Claude Code-specific artifacts

添加 --embeddings 以啟用語義搜索（速度較慢 — 需要幾分鐘而不是幾秒）。

索引存儲在倉庫內的 .gitnexus/ 目錄中（自動被 git 忽略）。

4. 創建代理腳本

將其寫入文件（例如 $GITNEXUS_DIR/proxy.mjs）。它服務於生產版 Web UI，並將 /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. 啟動服務

# Terminal 1: GitNexus backend API
npx gitnexus serve &

# Terminal 2: Proxy (web UI + API on one port)
node "$GITNEXUS_DIR/proxy.mjs" "$GITNEXUS_DIR/gitnexus-web/dist" 8888 &

驗證：curl -s http://localhost:8888/api/repos 應返回已索引的倉庫。

6. 使用 Cloudflare 隧道（可選 — 用於遠程訪問）

# Install cloudflared if needed (no 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

# Start tunnel (--config /dev/null avoids conflicts with existing named tunnels)
cloudflared tunnel --config /dev/null --url http://localhost:8888 --no-autoupdate --protocol http2

隧道 URL（例如 https://random-words.trycloudflare.com）會打印到 stderr。分享該鏈接 — 任何擁有鏈接的人都可以探索圖譜。

7. 清理

# Stop services
pkill -f "gitnexus serve"
pkill -f "proxy.mjs"
pkill -f cloudflared

# Remove index from the target repo
cd /path/to/target-repo
npx gitnexus clean
rm -rf .claude/

常見陷阱

如果用戶在 ~/.cloudflared/config.yml 中存在現有的命名隧道配置，則 cloudflared 需要 --config /dev/null。如果沒有它，配置中的通配入口規則會對所有快速隧道請求返回 404。
隧道連接必須使用生產構建。 Vite 開發服務器默認阻止非 localhost 主機（allowedHosts）。生產構建 + Node 代理完全避免了這個問題。
Web UI 不會創建 .claude/ 或 CLAUDE.md。 這些文件由 npx gitnexus analyze 創建。使用 --skip-agents-md 抑制 markdown 文件的生成，然後使用 rm -rf .claude/ 清理其餘部分。這些是 Claude Code 集成，hermes-agent 用戶不需要它們。
瀏覽器內存限制。 Web UI 將整個圖譜加載到瀏覽器內存中。擁有 5k+ 文件的倉庫可能會運行緩慢。30k+ 文件很可能會導致標籤頁崩潰。
嵌入向量是可選的。 --embeddings 啟用語義搜索，但在大型倉庫上需要幾分鐘。為了快速探索可以跳過它；如果你希望通過 AI 聊天面板進行自然語言查詢，則可以添加它。
多個倉庫。 gitnexus serve 服務於所有已索引的倉庫。索引多個倉庫，啟動一次 serve，Web UI 允許你在它們之間切換。

技能元數據​

參考：完整 SKILL.md​

GitNexus Explorer

何時使用​

前置條件​

大小警告​

步驟​

1. 克隆並構建 GitNexus（一次性設置）​

2. 修補 Web UI 以支持遠程訪問​

3. 索引目標倉庫​

4. 創建代理腳本​

5. 啟動服務​

6. 使用 Cloudflare 隧道（可選 — 用於遠程訪問）​

7. 清理​

常見陷阱​