understand-dashboard

/understand-dashboard

启动 Understand Anything 仪表板，以可视化当前项目的知识图谱。

Instructions

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 的真实路径向上两级（相对于自身的回退路径）
   • ~/.copilot/skills/understand-dashboard 的真实路径向上两级（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。访问知识图谱数据需要此令牌 — 没有令牌时，仪表板会显示“需要访问令牌”的拦截页面。

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= 参数。如果省略，用户将被令牌拦截页面阻止，并且必须手动从终端输出中查找令牌。

Notes

• 快速路径（步骤 4）会从 GitHub 发布页面下载固定到特定版本的独立查看器 — 不会在插件目录中安装任何内容，也不会执行构建
• 仪表板会在默认浏览器中自动打开（查看器和 Vite 的 --open 均如此）
• 如果端口 5173 已被占用，则会选择下一个可用端口（两种路径均如此）
• 在回退方案中，GRAPH_DIR 环境变量会告知开发服务器知识图谱的位置