Add README, .gitignore, and fix build.sh Sage root detection

.gitignore

@@ -0,0 +1,4 @@
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/

README.md

@@ -1,2 +1,45 @@
-# bashboard_for_sage
+# Dashboard for Sage
 
+Sage 数据看板模块，基于 bricks-framework 的 ECharts 扩展控件实现。
+
+## 功能
+
+1. **今日调用笔数和交易金额** - 每10秒自动刷新 llmusage 数据
+2. **用户总数** - 系统中注册用户数
+3. **当前并发用户数** - 近5分钟内有活跃记录的用户数
+4. **Top 3 模型排名** - 按当天调用数量和交易金额排名
+
+## 目录结构
+
+```
+dashboard_for_sage/
+├── dashboard_for_sage/
+│   ├── __init__.py
+│   └── init.py           # 模块注册
+├── wwwroot/
+│   ├── index.ui           # 主看板页面
+│   ├── menu.ui            # 菜单
+│   ├── api/
+│   │   ├── get_today_usage.dspy   # 今日用量API
+│   │   ├── get_user_stats.dspy    # 用户统计API
+│   │   └── get_top_models.dspy    # Top模型API
+│   └── scripts/
+│       └── dashboard_refresh.js   # 10秒自动刷新脚本
+├── pyproject.toml
+└── build.sh
+```
+
+## 部署
+
+```bash
+cd ~/repos/dashboard_for_sage
+bash build.sh
+# 设置RBAC权限（在生产服务器上执行）
+cd ~/repos/sage && ./py3/bin/python set_role_perm.py logined /dashboard_for_sage/%
+# 重启Sage
+./stop.sh && ./start.sh
+```
+
+## 访问地址
+
+`/dashboard_for_sage/index.ui`

build.sh

@@ -2,14 +2,26 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-SAGE_ROOT="$(cd "$SCRIPT_DIR/../.." 2>/dev/null && pwd || echo "$SCRIPT_DIR")"
-VENV_PYTHON="$SAGE_ROOT/py3/bin/python"
+MODULE_NAME="dashboard_for_sage"
+
+# Try to find Sage root
+for candidate in "$SCRIPT_DIR/../.." "$SCRIPT_DIR/../../../sage" "$HOME/repos/sage"; do
+    if [ -d "$candidate/wwwroot" ] && [ -d "$candidate/py3/bin" ]; then
+        SAGE_ROOT="$(cd "$candidate" && pwd)"
+        break
+    fi
+done
+
+if [ -z "$SAGE_ROOT" ]; then
+    echo "ERROR: Cannot find Sage root. Run this script from within a Sage environment."
+    exit 1
+fi
+
 VENV_PIP="$SAGE_ROOT/py3/bin/pip"
 WWWROOT="$SAGE_ROOT/wwwroot"
 
-MODULE_NAME="dashboard_for_sage"
-
 echo "=== Building $MODULE_NAME ==="
+echo "Sage root: $SAGE_ROOT"
 
 # Install the module
 cd "$SCRIPT_DIR"
@@ -20,7 +32,7 @@ MODULE_WWWROOT="$SCRIPT_DIR/wwwroot"
 SAGE_MODULE_WWWROOT="$WWWROOT/$MODULE_NAME"
 
 echo "Linking wwwroot..."
-mkdir -p "$SAGE_MODULE_WWWROOT"
+mkdir -p "$SAGE_MODULE_WWWROOT/api" "$SAGE_MODULE_WWWROOT/scripts"
 
 # Link all .ui files
 for f in "$MODULE_WWWROOT"/*.ui; do
@@ -28,13 +40,11 @@ for f in "$MODULE_WWWROOT"/*.ui; do
 done
 
 # Link api/ directory
-mkdir -p "$SAGE_MODULE_WWWROOT/api"
 for f in "$MODULE_WWWROOT/api"/*.dspy; do
     [ -f "$f" ] && ln -sf "$f" "$SAGE_MODULE_WWWROOT/api/"
 done
 
 # Link scripts/ directory
-mkdir -p "$SAGE_MODULE_WWWROOT/scripts"
 for f in "$MODULE_WWWROOT/scripts"/*.js; do
     [ -f "$f" ] && ln -sf "$f" "$SAGE_MODULE_WWWROOT/scripts/"
 done