understand-dashboard

/understand-dashboard

現在のプロジェクトのナレッジグラフを可視化する Understand Anything ダッシュボードを起動します。

手順

1. プロジェクトディレクトリとデータディレクトリを特定します。

   • $ARGUMENTS にパスが含まれている場合は、それをプロジェクトディレクトリとして使用します
   • それ以外の場合は、現在の作業ディレクトリを使用します
   • .understand-anything/ データディレクトリが存在する場合は優先し、存在しない場合は .ua/ を使用します

   Bash ツールを使用して解決します。

   PROJECT_ARG="$ARGUMENTS"
   if [ -n "$PROJECT_ARG" ]; then
     PROJECT_DIR=$(cd "$PROJECT_ARG" 2>/dev/null && pwd -P)
   else
     PROJECT_DIR=$(pwd -P)
   fi
   
   if [ -z "$PROJECT_DIR" ] || [ ! -d "$PROJECT_DIR" ]; then
     echo "Error: Project directory not found: ${PROJECT_ARG:-$PWD}"
     exit 1
   fi
   
   if [ -d "$PROJECT_DIR/.understand-anything" ]; then
     UA_DIR="$PROJECT_DIR/.understand-anything"
   else
     UA_DIR="$PROJECT_DIR/.ua"
   fi
   

2. プロジェクトディレクトリに $UA_DIR/knowledge-graph.json が存在することを確認します。存在しない場合は、ユーザーに次のように伝えます。

   No knowledge graph found. Run /understand first to analyze this project.
   

   Bash ツールを使用して確認します。

   if [ ! -f "$UA_DIR/knowledge-graph.json" ]; then
     echo "No knowledge graph found. Run /understand first to analyze this project."
     exit 1
   fi
   

3. ダッシュボードのコードを見つけます。ダッシュボードは、このプラグインのルートディレクトリを基準とした packages/dashboard/ にあります。次のパスを順番に確認し、最初に存在するものを使用します。

   • ${CLAUDE_PLUGIN_ROOT}/packages/dashboard/（Claude Code のランタイムルート、最優先）
   • ~/.understand-anything-plugin/packages/dashboard/（共通シンボリックリンク、すべてのインストール）
   • ~/.agents/skills/understand-dashboard の実パスから 2 階層上（自身を基準にしたフォールバック）
   • ~/.copilot/skills/understand-dashboard の実パスから 2 階層上（Copilot の個人スキル用フォールバック）
   • 一般的なクローンベースのインストールルート：
     • ~/.codex/understand-anything/understand-anything-plugin/packages/dashboard/
     • ~/.opencode/understand-anything/understand-anything-plugin/packages/dashboard/
     • ~/.pi/understand-anything/understand-anything-plugin/packages/dashboard/
     • ~/understand-anything/understand-anything-plugin/packages/dashboard/

   Bash ツールを使用して解決します。

   SKILL_REAL=$(realpath ~/.agents/skills/understand-dashboard 2>/dev/null || readlink -f ~/.agents/skills/understand-dashboard 2>/dev/null || echo "")
   SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
   COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand-dashboard 2>/dev/null || readlink -f ~/.copilot/skills/understand-dashboard 2>/dev/null || echo "")
   COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
   
   PLUGIN_ROOT=""
   for candidate in \
     "${CLAUDE_PLUGIN_ROOT}" \
     "$HOME/.understand-anything-plugin" \
     "$SELF_RELATIVE" \
     "$COPILOT_SELF_RELATIVE" \
     "$HOME/.codex/understand-anything/understand-anything-plugin" \
     "$HOME/.opencode/understand-anything/understand-anything-plugin" \
     "$HOME/.pi/understand-anything/understand-anything-plugin" \
     "$HOME/understand-anything/understand-anything-plugin"; do
     if [ -n "$candidate" ] && [ -d "$candidate/packages/dashboard" ]; then
       PLUGIN_ROOT="$candidate"; break
     fi
   done
   
   if [ -z "$PLUGIN_ROOT" ]; then
     echo "Error: Cannot find the understand-anything plugin root."
     echo "Checked:"
     echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
     echo "  - $HOME/.understand-anything-plugin"
     echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-dashboard>}"
     echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-dashboard>}"
     echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
     echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
     echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
     echo "  - $HOME/understand-anything/understand-anything-plugin"
     echo "Make sure you followed the installation instructions for your platform."
     exit 1
   fi
   
   DASHBOARD_DIR="$PLUGIN_ROOT/packages/dashboard"
   

4. 高速パス — まずビルド済みビューアを試します（インストールもビルドも不要）。 各リリースには自己完結型のビューアーの tarball が含まれています。インストール済みのプラグインバージョンを指定して実行します。

   : "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
   : "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"
   PLUGIN_VERSION=$(node -p "require('$PLUGIN_ROOT/package.json').version")
   VIEWER_URL="https://github.com/Egonex-AI/Understand-Anything/releases/download/v${PLUGIN_VERSION}/understand-anything-viewer.tgz"
   npx --yes "$VIEWER_URL" "$PROJECT_DIR"
   

   バックグラウンドで実行します。開発サーバーと同じ 🔑 Dashboard URL の行が出力されます。

   • この行が表示された場合は、手順 5～6 をスキップして手順 7 に進みます。
   • この行を出力せずにプロセスが終了した場合（このバージョン用のリリースアセットがない、またはネットワークに接続できない場合）は、手順 5～6 に進みます。

5. フォールバック：必要に応じて依存関係をインストールし、ビルドします。

   : "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
   DASHBOARD_DIR="${DASHBOARD_DIR:-$PLUGIN_ROOT/packages/dashboard}"
   cd "$DASHBOARD_DIR" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install)
   

   次に、ダッシュボードが依存するコアパッケージがビルド済みであることを確認します。

   : "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
   cd "$PLUGIN_ROOT" && pnpm --filter @understand-anything/core build
   

6. フォールバック：プロジェクトのナレッジグラフを参照するように Vite 開発サーバーを起動します。

   : "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"
   : "${DASHBOARD_DIR:?Run step 5 first so DASHBOARD_DIR is set}"
   cd "$DASHBOARD_DIR" && GRAPH_DIR="$PROJECT_DIR" npx vite --host 127.0.0.1
   

   ユーザーが作業を続けられるよう、バックグラウンドで実行します。

7. サーバー出力からアクセストークン付き URL を取得します。 サーバー（ビューアーまたは Vite）は、次のような行を出力します。

   🔑  Dashboard URL: http://127.0.0.1:<PORT>?token=<TOKEN>
   

   ?token= パラメーターを含む完全な URL を抽出します。ナレッジグラフのデータにアクセスするにはトークンが必要です。トークンがないと、ダッシュボードには「Access Token Required」というゲートが表示されます。

8. 完全なトークン付き URL を含めて、ユーザーに報告します。

   Dashboard started at http://127.0.0.1:<PORT>?token=<TOKEN>
   Viewing: $UA_DIR/knowledge-graph.json
   
   The dashboard is running in the background. Press Ctrl+C in the terminal to stop it.
   

   重要： 共有する URL には必ず ?token= パラメーターを含めてください。これを省略すると、ユーザーはトークンゲートによってアクセスをブロックされ、ターミナル出力からトークンを手動で探す必要があります。

メモ

• 高速パス（手順 4）では、バージョンを指定した自己完結型ビューアーを GitHub リリースからダウンロードします。プラグインディレクトリには何もインストールされず、ビルドも実行されません
• ダッシュボードはデフォルトのブラウザーで自動的に開きます（ビューアーと Vite の --open の両方）
• ポート 5173 がすでに使用されている場合は、次に利用可能なポートが選ばれます（どちらのパスでも同様）
• フォールバックでは、GRAPH_DIR 環境変数によって開発サーバーがナレッジグラフの場所を認識します