openclaw-agent-dashboard 1.0.4

package/frontend/src/types/task.ts

@@ -0,0 +1,38 @@
+// 任务状态类型定义
+
+export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+export interface Task {
+  id: string
+  name: string
+  task?: string // 完整任务内容（用于显示全量）
+  status: TaskStatus
+  progress: number // 0-100
+  startTime?: number
+  endTime?: number
+  agentId?: string
+  agentName?: string
+  agentWorkspace?: string  // Agent 工作区路径
+  taskPath?: string
+  subtasks?: Task[]
+  error?: string
+  output?: string // 任务成功时 Agent 的输出内容
+  generatedFiles?: string[] // 本次任务生成/修改的文件路径
+  metadata?: Record<string, unknown>
+}
+
+export interface TaskStatusSummary {
+  tasks: Task[]
+  total: number
+  completed: number
+  failed: number
+  running: number
+  pending: number
+  cancelled: number
+}
+
+export interface TaskFilters {
+  status?: TaskStatus[]
+  search?: string
+  agentId?: string
+}

package/frontend/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8000',
+        changeOrigin: true
+      },
+      '/ws': {
+        target: 'ws://localhost:8000',
+        ws: true
+      }
+    }
+  }
+})

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "openclaw-agent-dashboard",
+  "version": "1.0.4",
+  "description": "多 Agent 可视化看板 - 状态、任务、API、工作流、协作流程",
+  "bin": {
+    "openclaw-agent-dashboard": "scripts/install.js"
+  },
+  "scripts": {
+    "pack": "node scripts/build-plugin.js",
+    "install-plugin": "node scripts/install.js",
+    "deploy": "npm run pack && npm run install-plugin",
+    "upgrade": "git pull && npm run deploy",
+    "bundle": "bash scripts/bundle.sh",
+    "start": "node scripts/start.js"
+  },
+  "keywords": ["openclaw", "agent", "dashboard", "visualization"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Umarchen/openclaw-agent-dashboard.git"
+  }
+}

package/plugin/README.md

@@ -0,0 +1,99 @@
+# OpenClaw Agent Dashboard 插件
+
+多 Agent 可视化看板 - 作为 OpenClaw 插件安装后，随 OpenClaw 启动自动运行。
+
+## 快速开始
+
+克隆仓库后，在项目根目录执行：
+
+```bash
+npm run deploy
+```
+
+该命令会自动完成：
+1. 检查前置条件（Node.js、Python 3、OpenClaw）
+2. 构建前端
+3. 打包并安装插件到 `~/.openclaw/extensions/`
+4. 自动安装 Python 依赖（fastapi、uvicorn 等）
+
+**前置要求**：
+- Node.js（构建前端）
+- Python 3.10+
+- OpenClaw（`npm install -g openclaw`）
+
+安装完成后，执行任意 `openclaw` 命令即可自动启动 Dashboard。
+
+---
+
+## 命令说明
+
+| 命令 | 说明 |
+|------|------|
+| `npm run deploy` | 打包 + 安装到 OpenClaw（首次安装或升级） |
+| `npm run upgrade` | 拉取最新代码 + 部署（推荐用于升级） |
+| `npm run pack` | 仅打包插件，不安装（开发调试用） |
+| `npm run bundle` | 生成可分发的压缩包（给同事用） |
+
+### 升级插件
+
+```bash
+cd openclaw-agent-dashboard
+npm run upgrade
+```
+
+输出示例：
+```
+=== OpenClaw Agent Dashboard 插件升级 ===
+
+  1.0.0 → 1.1.0
+
+✓ 前置条件检查通过
+>>> 1/4 构建前端...
+>>> 2/4 打包插件...
+>>> 3/4 移除旧版本...
+>>> 4/4 安装新版本...
+>>> 检查 Python 依赖...
+✓ Python 依赖已就绪
+
+=== 升级完成 (1.0.0 → 1.1.0) ===
+```
+
+---
+
+## 使用
+
+插件加载后（执行任意 `openclaw` 命令时）会自动启动 Dashboard 服务。
+
+**访问地址**：http://localhost:38271（或你配置的端口）
+
+### 端口配置（便于移植，无需改 openclaw.json）
+
+优先级从高到低：
+
+1. **环境变量**：`DASHBOARD_PORT=38271`
+2. **独立配置文件**：`~/.openclaw-agent-dashboard/config.json`（可与 `OPENCLAW_AGENT_DASHBOARD_DATA` 环境变量配合）
+   ```json
+   { "port": 38271 }
+   ```
+3. **openclaw.json**：`plugins.entries.openclaw-agent-dashboard.config.port`
+4. **默认**：38271
+
+端口被占用时会自动尝试 38272、38273...
+
+---
+
+## 手动安装（故障恢复）
+
+若 `npm run deploy` 失败，可分步执行：
+
+```bash
+# 1. 打包
+npm run pack
+
+# 2. 安装插件
+openclaw plugins install ./plugin
+
+# 3. 安装 Python 依赖（通常不需要，脚本会自动完成；Debian/Ubuntu 请用 venv）
+cd ~/.openclaw/extensions/openclaw-agent-dashboard/dashboard
+python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+```

package/plugin/config.json.example

@@ -0,0 +1 @@
+{"port":38271}

package/plugin/index.js

@@ -0,0 +1,250 @@
+/**
+ * OpenClaw Agent Dashboard - 插件入口
+ * 仅在 Gateway 进程内自动启动 FastAPI 后端（检测 OPENCLAW_GATEWAY_PORT）
+ *
+ * 启动条件：OPENCLAW_GATEWAY_PORT 已设置（即 Gateway 进程）且 autoStart !== false
+ *
+ * 端口配置优先级（高到低）：
+ * 1. 环境变量 DASHBOARD_PORT
+ * 2. ~/.openclaw-agent-dashboard/config.json（或 OPENCLAW_AGENT_DASHBOARD_DATA/config.json）
+ * 3. openclaw.json 中 plugins.entries.openclaw-agent-dashboard.config.port
+ * 4. 默认 38271
+ */
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const net = require('net');
+const { spawn, execFileSync } = require('child_process');
+
+let dashboardProcess = null;
+
+function getOpenClawHome() {
+  return process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+}
+
+/** Dashboard 数据目录，与 Python 端一致：本工程数据统一放此，不写入 ~/.openclaw */
+function getDashboardDataDir() {
+  return process.env.OPENCLAW_AGENT_DASHBOARD_DATA || path.join(os.homedir(), '.openclaw-agent-dashboard');
+}
+
+function getDashboardDir() {
+  const pluginDir = __dirname;
+  return path.join(pluginDir, 'dashboard');
+}
+
+/** 兼容旧路径：若存在 ~/.openclaw/dashboard 或 ~/.openclaw-dashboard 下的 config.json 则迁移到新目录一次 */
+function migrateLegacyConfigIfNeeded() {
+  const openclawHome = getOpenClawHome();
+  const newDir = getDashboardDataDir();
+  const newPath = path.join(newDir, 'config.json');
+  if (fs.existsSync(newPath)) return;
+  const legacyPaths = [
+    path.join(openclawHome, 'dashboard', 'config.json'),
+    path.join(os.homedir(), '.openclaw-dashboard', 'config.json')
+  ];
+  for (const legacyPath of legacyPaths) {
+    if (!fs.existsSync(legacyPath)) continue;
+    try {
+      if (!fs.existsSync(newDir)) fs.mkdirSync(newDir, { recursive: true });
+      fs.copyFileSync(legacyPath, newPath);
+    } catch (_) {}
+    return;
+  }
+}
+
+/**
+ * 加载配置，优先级：env > 用户 config.json（新路径 > 旧路径）> api.pluginConfig > 默认
+ */
+function loadConfig(apiPluginConfig = {}) {
+  const openclawHome = getOpenClawHome();
+  let config = { port: 38271, autoStart: true }; // 使用罕见端口避免冲突
+
+  if (apiPluginConfig && typeof apiPluginConfig.port === 'number') {
+    config.port = apiPluginConfig.port;
+  }
+  if (apiPluginConfig && typeof apiPluginConfig.autoStart === 'boolean') {
+    config.autoStart = apiPluginConfig.autoStart;
+  }
+
+  const projectConfigPath = path.join(getDashboardDir(), 'config.json');
+  if (fs.existsSync(projectConfigPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(projectConfigPath, 'utf8'));
+      if (typeof data.port === 'number') config.port = data.port;
+    } catch (_) {}
+  }
+
+  migrateLegacyConfigIfNeeded();
+  const userConfigPath = path.join(getDashboardDataDir(), 'config.json');
+  const legacyUserConfigPath = path.join(openclawHome, 'dashboard', 'config.json');
+  const prevUserConfigPath = path.join(os.homedir(), '.openclaw-dashboard', 'config.json');
+  const pathToRead = fs.existsSync(userConfigPath) ? userConfigPath
+    : (fs.existsSync(prevUserConfigPath) ? prevUserConfigPath : legacyUserConfigPath);
+  if (pathToRead && fs.existsSync(pathToRead)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(pathToRead, 'utf8'));
+      if (typeof data.port === 'number') config.port = data.port;
+    } catch (_) {}
+  }
+
+  const envPort = process.env.DASHBOARD_PORT;
+  if (envPort) {
+    const p = parseInt(envPort, 10);
+    if (!isNaN(p) && p > 0) config.port = p;
+  }
+
+  return config;
+}
+
+/** 检测端口是否可用 */
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '0.0.0.0');
+  });
+}
+
+/** 检测端口是否已被占用（有进程在监听） */
+function isPortInUse(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(true));
+    server.once('listening', () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+/** 找到可用端口，从 basePort 开始尝试 */
+async function findAvailablePort(basePort, maxAttempts = 10) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = basePort + i;
+    if (await isPortAvailable(port)) return port;
+  }
+  return basePort;
+}
+
+function startDashboard(config = {}) {
+  // 仅在 Gateway 进程内自动启动（OPENCLAW_GATEWAY_PORT 由 Gateway 设置）
+  // CLI 命令（status、health 等）加载插件时不会设置此变量，故不启动
+  if (!process.env.OPENCLAW_GATEWAY_PORT?.trim()) {
+    return;
+  }
+
+  if (dashboardProcess) {
+    console.log('[OpenClaw-Dashboard] 服务已在运行');
+    return;
+  }
+
+  const dashboardDir = getDashboardDir();
+  const openclawHome = getOpenClawHome();
+
+  if (!fs.existsSync(dashboardDir)) {
+    console.warn('[OpenClaw-Dashboard] dashboard 目录不存在，请先执行 npm run deploy 安装插件');
+    return;
+  }
+
+  const basePort = config.port ?? 38271;
+  const isExplicitPort = basePort !== 38271; // 用户显式配置了端口（非默认 38271）
+  const autoStart = config.autoStart !== false; // 默认 true，可配置为 false 禁用自动启动
+
+  if (!autoStart) {
+    return;
+  }
+
+  const portPromise = isExplicitPort
+    ? Promise.resolve(basePort)
+    : findAvailablePort(basePort);
+
+  portPromise.then(async (port) => {
+    if (dashboardProcess) return;
+
+    // 若端口已被占用，认为 Dashboard 已在其他进程运行，跳过启动，避免重复实例
+    if (await isPortInUse(port)) {
+      console.log(`[OpenClaw-Dashboard] 端口 ${port} 已被占用，Dashboard 可能已在运行，跳过启动`);
+      return;
+    }
+
+    const env = {
+      ...process.env,
+      OPENCLAW_HOME: openclawHome,
+      DASHBOARD_PORT: String(port),
+    };
+
+    // 优先使用插件 venv 的 Python（安装时 venv 优先，避免 PEP 668）
+    // 若 venv 存在但不完整（如缺 python3-venv 导致 ensurepip 失败、无 uvicorn），回退到 python3
+    const venvPythonUnix = path.join(dashboardDir, '.venv', 'bin', 'python');
+    const venvPythonWin = path.join(dashboardDir, '.venv', 'Scripts', 'python.exe');
+    let pythonCmd = process.env.PYTHON_CMD;
+    if (!pythonCmd) {
+      const venvPython = fs.existsSync(venvPythonUnix) ? venvPythonUnix : (fs.existsSync(venvPythonWin) ? venvPythonWin : null);
+      if (venvPython) {
+        try {
+          execFileSync(venvPython, ['-c', 'import uvicorn'], { stdio: 'ignore', timeout: 3000 });
+          pythonCmd = venvPython;
+        } catch (_) {
+          pythonCmd = 'python3'; // venv 不完整，回退到系统 python3
+        }
+      } else {
+        pythonCmd = 'python3';
+      }
+    }
+    const args = ['-m', 'uvicorn', 'main:app', '--host', '0.0.0.0', '--port', String(port)];
+
+    if (!isExplicitPort && port !== basePort) {
+      console.log(`[OpenClaw-Dashboard] 端口 ${basePort} 被占用，使用 ${port}`);
+    }
+    console.log(`[OpenClaw-Dashboard] 插件服务已启动`);
+    console.log(`[OpenClaw-Dashboard] 访问地址: http://localhost:${port}`);
+
+    dashboardProcess = spawn(pythonCmd, args, {
+      env,
+      cwd: dashboardDir,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+
+    dashboardProcess.on('error', (err) => {
+      console.error('[OpenClaw-Dashboard] 启动失败:', err.message);
+      dashboardProcess = null;
+    });
+    dashboardProcess.on('exit', (code, signal) => {
+      dashboardProcess = null;
+      if (code !== 0 && code !== null) {
+        console.log(`[OpenClaw-Dashboard] 进程退出 code=${code} signal=${signal}`);
+      }
+    });
+  });
+}
+
+function stopDashboard() {
+  if (dashboardProcess) {
+    dashboardProcess.kill('SIGTERM');
+    dashboardProcess = null;
+    console.log('[OpenClaw-Dashboard] 服务已停止');
+  }
+}
+
+/**
+ * OpenClaw 插件入口
+ * @param {object} api - OpenClaw 插件 API，pluginConfig 来自 openclaw.json 的 config 字段
+ */
+function DashboardPlugin(api) {
+  console.log('[OpenClaw-Dashboard] 插件已加载');
+
+  const pluginConfig = (api && api.pluginConfig) || {};
+  const config = loadConfig(pluginConfig);
+  startDashboard(config);
+
+  return {
+    stop() {
+      stopDashboard();
+    },
+  };
+}
+
+module.exports = DashboardPlugin;

package/plugin/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "openclaw-agent-dashboard",
+  "name": "OpenClaw Agent Dashboard",
+  "description": "多 Agent 可视化看板 - 状态、任务、API、工作流、协作流程",
+  "version": "1.0.4",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "port": {
+        "type": "number",
+        "default": 38271,
+        "description": "Dashboard 服务端口"
+      }
+    }
+  }
+}

package/plugin/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "openclaw-agent-dashboard",
+  "version": "1.0.4",
+  "description": "多 Agent 可视化看板 - OpenClaw 插件",
+  "main": "index.js",
+  "openclaw": {
+    "extensions": ["./index.js"]
+  },
+  "keywords": ["openclaw", "dashboard", "agent", "monitoring"],
+  "license": "MIT",
+  "files": [
+    "openclaw.plugin.json",
+    "index.js",
+    "dashboard",
+    "frontend-dist"
+  ],
+  "scripts": {
+    "pack": "node ../scripts/build-plugin.js",
+    "prepublishOnly": "npm run pack"
+  }
+}

package/scripts/build-plugin.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * 插件打包脚本
+ * 1. 构建前端
+ * 2. 复制 backend 到 plugin/dashboard
+ * 3. 复制 frontend/dist 到 plugin/frontend-dist
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PLUGIN_DIR = path.join(ROOT, 'plugin');
+const BACKEND_SRC = path.join(ROOT, 'src', 'backend');
+const FRONTEND_DIR = path.join(ROOT, 'frontend');
+const DASHBOARD_DEST = path.join(PLUGIN_DIR, 'dashboard');
+const FRONTEND_DEST = path.join(PLUGIN_DIR, 'frontend-dist');
+
+function rmrf(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true });
+  }
+}
+
+function copyDir(src, dest, exclude = []) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (exclude.includes(entry.name)) continue;
+    if (entry.name.endsWith('.pyc') || entry.name.endsWith('.log')) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, exclude);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+console.log('[pack] 1. 构建前端...');
+// 检查是否需要安装依赖：无 node_modules 或缺少 .bin（如 Windows 下 .bin 未生成）时都执行 install
+const nodeModulesPath = path.join(FRONTEND_DIR, 'node_modules');
+const binVite = path.join(nodeModulesPath, '.bin', 'vite');
+const binViteCmd = path.join(nodeModulesPath, '.bin', 'vite.cmd'); // Windows
+const needInstall = !fs.existsSync(nodeModulesPath) ||
+  !(fs.existsSync(binVite) || fs.existsSync(binViteCmd));
+if (needInstall) {
+  console.log('[pack] 安装前端依赖...');
+  execSync('npm install --no-audit', { cwd: FRONTEND_DIR, stdio: 'inherit', env: process.env });
+}
+execSync('npm run build', { cwd: FRONTEND_DIR, stdio: 'inherit', env: process.env });
+
+console.log('[pack] 2. 复制 backend -> plugin/dashboard');
+rmrf(DASHBOARD_DEST);
+copyDir(BACKEND_SRC, DASHBOARD_DEST, ['__pycache__', '.pytest_cache']);
+
+console.log('[pack] 3. 复制 frontend/dist -> plugin/frontend-dist');
+rmrf(FRONTEND_DEST);
+const frontendDist = path.join(FRONTEND_DIR, 'dist');
+if (fs.existsSync(frontendDist)) {
+  copyDir(frontendDist, FRONTEND_DEST);
+} else {
+  console.warn('[pack] frontend/dist 不存在，跳过');
+}
+
+console.log('[pack] 完成');

package/scripts/bundle.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+#
+# 打包项目为可分发的压缩包
+# 用法: npm run bundle
+#
+set -e
+cd "$(dirname "$0")/.."
+ROOT=$(pwd)
+
+VERSION=$(grep '"version"' "$ROOT/plugin/openclaw.plugin.json" | sed 's/.*"version": *"\([^"]*\)".*/\1/')
+OUTPUT="openclaw-agent-dashboard-v$VERSION.tar.gz"
+
+echo "=== 打包分发文件 ==="
+echo ""
+echo "  版本: $VERSION"
+echo "  输出: $OUTPUT"
+echo ""
+
+# 临时目录
+TMPDIR=$(mktemp -d)
+DISTDIR="$TMPDIR/openclaw-agent-dashboard"
+
+mkdir -p "$DISTDIR"
+
+# 复制需要的文件
+echo ">>> 复制文件..."
+cp -r "$ROOT/frontend" "$DISTDIR/"
+cp -r "$ROOT/src" "$DISTDIR/"
+cp -r "$ROOT/plugin" "$DISTDIR/"
+cp -r "$ROOT/scripts" "$DISTDIR/"
+cp "$ROOT/package.json" "$DISTDIR/"
+cp "$ROOT/README.md" "$DISTDIR/"
+
+# 清理不需要的文件
+echo ">>> 清理 node_modules..."
+rm -rf "$DISTDIR/frontend/node_modules"
+rm -rf "$DISTDIR/frontend/dist"
+rm -rf "$DISTDIR/plugin/frontend-dist"
+rm -rf "$DISTDIR/plugin/dashboard"
+find "$DISTDIR" -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+find "$DISTDIR" -name ".pytest_cache" -type d -exec rm -rf {} + 2>/dev/null || true
+
+# 打包
+echo ">>> 压缩..."
+cd "$TMPDIR"
+tar -czf "$ROOT/$OUTPUT" openclaw-agent-dashboard
+
+# 清理临时目录
+rm -rf "$TMPDIR"
+
+# 显示结果
+echo ""
+echo "=== 打包完成 ==="
+echo ""
+echo "  文件: $OUTPUT"
+echo "  大小: $(du -h "$ROOT/$OUTPUT" | cut -f1)"
+echo ""
+echo "同事使用方式:"
+echo "  1. 解压: tar -xzf $OUTPUT"
+echo "  2. 进入: cd openclaw-agent-dashboard"
+echo "  3. 安装: npm run deploy"
+echo ""