openclaw-agent-dashboard 1.0.7 → 1.0.9

package/docs/WINDOWS_INSTALL_TROUBLESHOOTING.md

@@ -0,0 +1,209 @@
+# Windows 安装问题排查指南
+
+本文档针对 `npx openclaw-agent-dashboard@1.0.8 --verbose` 在 Windows 下的安装问题进行说明和解决方案。
+
+---
+
+## 一、问题概览
+
+根据安装日志，主要有以下几类问题：
+
+| 问题 | 严重程度 | 影响 |
+|------|----------|------|
+| Python 依赖安装失败 | 高 | Dashboard 后端无法启动 |
+| 插件注册失败 | 中 | 需手动配置或重新安装 |
+| Node.js DEP0190 警告 | 低 | 仅提示，不影响功能 |
+| 安全模式警告 | 低 | 需配置 `plugins.allow` |
+
+---
+
+## 二、Python 依赖安装失败（核心问题）
+
+### 2.1 错误现象
+
+```
+[Errno 11001] getaddrinfo failed
+Failed to establish a new connection
+ERROR: Could not find a version that satisfies the requirement fastapi==0.109.0
+ERROR: No matching distribution found for fastapi==0.109.0
+```
+
+### 2.2 根本原因
+
+`[Errno 11001] getaddrinfo failed` 是 **Windows 网络/DNS 解析错误**，表示 pip 无法连接到 PyPI (pypi.org) 下载包。
+
+常见原因：
+
+1. **企业网络限制**：公司防火墙或代理阻止访问 pypi.org
+2. **代理未配置**：使用代理上网但 pip 未设置代理
+3. **DNS 解析失败**：无法解析 pypi.org 域名
+4. **VPN 或网络策略**：限制外网访问
+
+### 2.3 解决方案
+
+#### 方案 A：配置 pip 代理（如有 HTTP/HTTPS 代理）
+
+```powershell
+# 临时设置（当前会话）
+$env:HTTP_PROXY = "http://代理地址:端口"
+$env:HTTPS_PROXY = "http://代理地址:端口"
+
+# 或使用 pip 配置
+python -m pip config set global.proxy "http://代理地址:端口"
+```
+
+#### 方案 B：使用国内 PyPI 镜像
+
+```powershell
+# 使用清华镜像
+python -m pip install -r C:\Users\h00427263\.openclaw\extensions\openclaw-agent-dashboard\dashboard\requirements.txt --user -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+# 或阿里云镜像
+python -m pip install -r C:\Users\h00427263\.openclaw\extensions\openclaw-agent-dashboard\dashboard\requirements.txt --user -i https://mirrors.aliyun.com/pypi/simple/
+```
+
+#### 方案 C：离线安装（完全无外网时）
+
+1. 在有网络的机器上下载依赖：
+
+   ```powershell
+   pip download -r requirements.txt -d ./pip-packages
+   ```
+
+2. 将 `pip-packages` 目录和 `requirements.txt` 拷贝到目标机器
+3. 在目标机器执行：
+
+   ```powershell
+   pip install --no-index --find-links=./pip-packages -r requirements.txt --user
+   ```
+
+#### 方案 D：跳过 Python 依赖安装
+
+若暂时无法解决网络问题，可先完成插件安装，后续再手动安装：
+
+```powershell
+npx openclaw-agent-dashboard@1.0.8 --verbose --skip-python
+```
+
+然后等网络恢复后手动执行：
+
+```powershell
+python -m pip install -r C:\Users\h00427263\.openclaw\extensions\openclaw-agent-dashboard\dashboard\requirements.txt --user
+```
+
+> **注意**：Windows 下若 `python3` 不可用，请使用 `python` 命令。
+
+---
+
+## 三、插件注册失败
+
+### 3.1 错误现象
+
+```
+plugin already exists: C:\Users\h00427263\.openclaw\extensions\openclaw-agent-dashboard (delete it first)
+⚠ 插件注册失败（Dashboard 可能需要在 openclaw 配置中手动添加）
+```
+
+### 3.2 原因说明
+
+安装脚本会先执行 `openclaw plugins uninstall`，再复制文件，最后执行 `openclaw plugins install`。  
+`uninstall` 可能只从配置中移除插件，**不会删除扩展目录**。当 `install` 发现目标目录已存在时，会报 "plugin already exists"。
+
+### 3.3 解决方案
+
+#### 方案 A：安装前手动删除旧目录
+
+```powershell
+# 删除旧插件目录
+Remove-Item -Recurse -Force "C:\Users\h00427263\.openclaw\extensions\openclaw-agent-dashboard" -ErrorAction SilentlyContinue
+
+# 重新安装
+npx openclaw-agent-dashboard@1.0.8 --verbose
+```
+
+#### 方案 B：手动配置 openclaw
+
+若插件文件已正确安装，可在 openclaw 配置中手动添加插件。配置文件通常位于：
+
+- `C:\Users\h00427263\.openclaw\config.json` 或
+- 环境变量 `OPENCLAW_STATE_DIR` 指向的目录
+
+在 `plugins.allow` 中添加 `openclaw-agent-dashboard`，例如：
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-agent-dashboard"]
+  }
+}
+```
+
+---
+
+## 四、其他警告说明
+
+### 4.1 Node.js DEP0190 警告
+
+```
+(node:32244) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true...
+```
+
+- **含义**：在 `shell: true` 下传递参数时，Node.js 提示存在潜在安全风险。
+- **影响**：当前仅为警告，不影响安装和运行。
+- **处理**：可忽略，或等待后续版本改用更安全的调用方式。
+
+### 4.2 安全模式警告
+
+```
+WARNING: Plugin "openclaw-agent-dashboard" contains dangerous code patterns: Shell command execution detected (child_process)
+plugins.allow is empty; discovered non-bundled plugins may auto-load
+```
+
+- **含义**：插件使用了 `child_process` 执行命令，被识别为“危险模式”。
+- **影响**：插件可能被当作未受信任代码，需要显式允许。
+- **处理**：在 openclaw 配置中设置 `plugins.allow: ["openclaw-agent-dashboard"]`。
+
+---
+
+## 五、推荐安装流程（Windows + 企业网络）
+
+1. **删除旧版本（若存在）**：
+
+   ```powershell
+   Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw\extensions\openclaw-agent-dashboard" -ErrorAction SilentlyContinue
+   ```
+
+2. **使用国内镜像安装**：
+
+   ```powershell
+   npx openclaw-agent-dashboard@1.0.8 --verbose --skip-python
+   ```
+
+3. **手动安装 Python 依赖（使用镜像）**：
+
+   ```powershell
+   python -m pip install -r "$env:USERPROFILE\.openclaw\extensions\openclaw-agent-dashboard\dashboard\requirements.txt" --user -i https://pypi.tuna.tsinghua.edu.cn/simple
+   ```
+
+4. **配置 openclaw 信任插件**（如仍有警告）：
+
+   编辑 `%USERPROFILE%\.openclaw\config.json`，添加：
+
+   ```json
+   {
+     "plugins": {
+       "allow": ["openclaw-agent-dashboard"]
+     }
+   }
+   ```
+
+5. **验证**：执行 `openclaw tui`，Dashboard 应自动启动，访问 http://localhost:38271。
+
+---
+
+## 六、后续改进建议（项目维护者）
+
+1. **安装脚本**：在 `openclaw plugins install` 前先 `rmrf(pluginPath)`，或改为传入 `extractedPluginDir` 让 openclaw 自行复制，避免 "plugin already exists"。
+2. **Python 安装**：支持通过环境变量或参数指定 pip 镜像（如 `PIP_INDEX_URL`）。
+3. **帮助信息**：在 Windows 下增加代理、镜像、离线安装的说明。
+4. **runCommand**：考虑使用 `execSync(cmd, args, { shell: false })` 或 `spawn` 传参，消除 DEP0190 警告。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agent-dashboard",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "多 Agent 可视化看板 - 状态、任务、API、工作流、协作流程",
   "bin": {
     "openclaw-agent-dashboard": "scripts/install.js"

package/plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-agent-dashboard",
   "name": "OpenClaw Agent Dashboard",
   "description": "多 Agent 可视化看板 - 状态、任务、API、工作流、协作流程",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agent-dashboard",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "多 Agent 可视化看板 - OpenClaw 插件",
   "main": "index.js",
   "openclaw": {

package/scripts/install-python-deps.js

@@ -111,6 +111,23 @@ function getVenvPython(venvDir) {
   return null;
 }
 
+// ============================================
+// Pip 镜像
+// ============================================
+
+/**
+ * 获取 pip 镜像参数
+ * 支持环境变量 PIP_INDEX_URL 或 PIP_MIRROR
+ * @returns {string[]}
+ */
+function getPipMirrorArgs() {
+  const mirror = process.env.PIP_INDEX_URL || process.env.PIP_MIRROR || '';
+  if (mirror) {
+    return ['-i', mirror, '--trusted-host', new URL(mirror).hostname];
+  }
+  return [];
+}
+
 // ============================================
 // Python 依赖安装
 // ============================================
@@ -150,17 +167,31 @@ function installWithVenv(reqFile, venvDir, silent) {
   }
 
   // 升级 pip（静默，失败不影响）
-  runCommand(venvPython, ['-m', 'pip', 'install', '--upgrade', 'pip', '-q'], { silent: true });
+  // 如果设了镜像，升级 pip 也用镜像
+  const pipMirrorArgs = getPipMirrorArgs();
+  runCommand(venvPython, ['-m', 'pip', 'install', '--upgrade', 'pip', '-q', ...pipMirrorArgs], { silent: true });
 
   // 安装依赖
   logInfo('  安装依赖...');
   const installResult = runCommand(
     venvPython,
-    ['-m', 'pip', 'install', '-r', reqFile, '-q'],
+    ['-m', 'pip', 'install', '-r', reqFile, '-q', ...pipMirrorArgs],
     { silent, timeout: 180000 }
   );
 
   if (!installResult.success) {
+    // 默认源失败，尝试清华镜像
+    if (!pipMirrorArgs.length) {
+      logWarn('  默认源失败，尝试清华镜像...');
+      const tsinghuaArgs = ['-i', 'https://pypi.tuna.tsinghua.edu.cn/simple', '--trusted-host', 'pypi.tuna.tsinghua.edu.cn'];
+      runCommand(venvPython, ['-m', 'pip', 'install', '--upgrade', 'pip', '-q', ...tsinghuaArgs], { silent: true, timeout: 60000 });
+      const retryResult = runCommand(
+        venvPython,
+        ['-m', 'pip', 'install', '-r', reqFile, '-q', ...tsinghuaArgs],
+        { silent, timeout: 180000 }
+      );
+      if (retryResult.success) return true;
+    }
     logWarn('  venv 安装依赖失败');
     if (!silent) {
       console.log('    错误:', installResult.output);
@@ -180,11 +211,12 @@ function installWithVenv(reqFile, venvDir, silent) {
 function installWithPipUser(reqFile, silent) {
   logInfo('  尝试: pip --user（PEP 668 兜底）');
 
+  const pipMirrorArgs = getPipMirrorArgs();
+  const tsinghuaArgs = ['-i', 'https://pypi.tuna.tsinghua.edu.cn/simple', '--trusted-host', 'pypi.tuna.tsinghua.edu.cn'];
+
   const pipCommands = [
-    { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q', '--user'], name: 'pip --user' },
-    { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q'], name: 'pip' },
-    { cmd: 'pip', args: ['install', '-r', reqFile, '-q', '--user'], name: 'pip --user' },
-    { cmd: 'pip3', args: ['install', '-r', reqFile, '-q', '--user'], name: 'pip3 --user' },
+    { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q', '--user', ...pipMirrorArgs], name: 'pip --user' },
+    { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q', ...pipMirrorArgs], name: 'pip' },
   ];
 
   for (const { cmd, args, name } of pipCommands) {
@@ -196,6 +228,20 @@ function installWithPipUser(reqFile, silent) {
     }
   }
 
+  // 默认源失败，尝试清华镜像
+  if (!pipMirrorArgs.length) {
+    logWarn('  默认源失败，尝试清华镜像...');
+    const retryCommands = [
+      { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q', '--user', ...tsinghuaArgs], name: 'pip --user (tsinghua)' },
+      { cmd: getPythonCmd(), args: ['-m', 'pip', 'install', '-r', reqFile, '-q', ...tsinghuaArgs], name: 'pip (tsinghua)' },
+    ];
+    for (const { cmd, args, name } of retryCommands) {
+      if (!commandExists(cmd)) continue;
+      const result = runCommand(cmd, args, { silent, timeout: 180000 });
+      if (result.success) return { success: true, method: name };
+    }
+  }
+
   return { success: false, method: null };
 }
 

package/scripts/lib/common.js

@@ -191,10 +191,24 @@ function shellEscape(arg) {
  */
 function runCommand(cmd, args = [], options = {}) {
   const { cwd, silent = true, timeout = 120000 } = options;
+  const isWin = process.platform === 'win32';
 
   try {
-    // 构建命令字符串，对参数进行转义
-    const cmdStr = [cmd, ...args.map(shellEscape)].join(' ');
+    // Windows 用双引号，Unix 用单引号
+    const esc = (arg) => {
+      if (!arg) return '""';
+      if (isWin) {
+        // Windows: 用双引号包裹含空格/特殊字符的路径
+        if (/[^a-zA-Z0-9_\-./:=@]/.test(arg)) {
+          return '"' + arg.replace(/"/g, '""') + '"';
+        }
+        return arg;
+      } else {
+        return shellEscape(arg);
+      }
+    };
+
+    const cmdStr = [cmd, ...args.map(esc)].join(' ');
 
     const result = execSync(
       cmdStr,
@@ -203,7 +217,7 @@ function runCommand(cmd, args = [], options = {}) {
         encoding: 'utf8',
         timeout,
         stdio: silent ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-        shell: process.platform === 'win32',
+        shell: true,
       }
     );
     return { success: true, code: 0, output: result || '' };