openclaw-agent-dashboard 1.0.21 → 1.0.23

package/docs/RELEASE-LATEST.md

@@ -1,189 +0,0 @@
-# 发布新 Latest 版本指南
-
-> 修改工程后，按本文步骤推送新 release，该版本会自动成为 GitHub 上的 **Latest**，用户一键安装即会装到该版本。
-
----
-
-## 一、发布前必读
-
-### 1.1 版本号从哪里来？
-
-Release 的 **tag 和安装包版本** 由仓库里**两个文件**的 `version` 字段决定（不是由你打的 git tag 名决定）：
-
-| 文件 | 作用 |
-|------|------|
-| `plugin/openclaw.plugin.json` | 插件元数据，**Release 流程会读这里的 version** 来创建 tag 和 tgz 包名。 |
-| `plugin/package.json` | Node 包配置，需与上面保持一致，否则包版本和展示会错乱。 |
-
-**重要**：先改这两个文件里的版本号并提交，再打同版本的 git tag。否则会出现「tag 是 v1.0.2、Release 却是 v1.0.0」的情况。
-
-### 1.2 流程概览
-
-```
-改代码 → 改两处 version → 提交并 push main → 打 tag 并 push tag → 自动构建并设为 Latest
-```
-
----
-
-## 二、操作步骤（以发布 v1.0.2 为例）
-
-### 步骤 1：在 main 上并拉取最新
-
-```bash
-git checkout main
-git pull origin main
-```
-
-### 步骤 2：修改两处版本号
-
-将 **`plugin/openclaw.plugin.json`** 和 **`plugin/package.json`** 中的 `"version"` 改为新版本，例如 `"1.0.2"`。
-
-- 编辑 `plugin/openclaw.plugin.json`，找到 `"version": "x.x.x"` 改为 `"1.0.2"`。
-- 编辑 `plugin/package.json`，同样把 `"version"` 改为 `"1.0.2"`。
-
-或用一条命令同时改（把下面的 `1.0.1` 换成你当前版本，`1.0.2` 换成目标版本）：
-
-```bash
-sed -i 's/"version": "1.0.1"/"version": "1.0.2"/' plugin/openclaw.plugin.json plugin/package.json
-```
-
-### 步骤 3：提交并推送到 main
-
-```bash
-git add plugin/openclaw.plugin.json plugin/package.json
-git commit -m "chore: bump version to 1.0.2"
-git push origin main
-```
-
-> 注意：提交信息用 `-m "..."`，不要写成 `git commit "..."`（会报错 pathspec）。
-
-### 步骤 4：打 tag 并推送（触发 Release）
-
-```bash
-git tag v1.0.2
-git push origin v1.0.2
-```
-
-推送 tag 后，GitHub Actions 会自动：
-
-1. 用该 tag 对应的 commit 构建
-2. 读取 `plugin/openclaw.plugin.json` 的 version，创建 Release 和 tgz
-3. 将本次 Release 设为 **Latest**
-
-### 步骤 5：验证
-
-- **Actions**：打开 [Actions](https://github.com/Umarchen/openclaw-agent-dashboard/actions)，确认 Release workflow 成功。
-- **Releases**：打开 [Releases](https://github.com/Umarchen/openclaw-agent-dashboard/releases)，确认出现 **v1.0.2**，且为 **Latest release**。
-
----
-
-## 三、用户如何安装
-
-默认一键安装即安装 **Latest**（即你刚发布的版本）：
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
-```
-
-安装指定版本：
-
-```bash
-DASHBOARD_VERSION=1.0.2 curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
-```
-
----
-
-## 四、快速命令清单（复制用）
-
-发布新版本时，把 `1.0.2` 换成你的目标版本号即可：
-
-```bash
-# 1. 同步 main
-git checkout main && git pull origin main
-
-# 2. 改版本号（两处文件，或手动编辑）
-# 编辑 plugin/openclaw.plugin.json 和 plugin/package.json 的 "version"
-
-# 3. 提交并推送
-git add plugin/openclaw.plugin.json plugin/package.json
-git commit -m "chore: bump version to 1.0.2"
-git push origin main
-
-# 4. 打 tag 并推送，触发 Release
-git tag v1.0.2
-git push origin v1.0.2
-```
-
----
-
-## 五、常见问题
-
-### 为什么 GitHub 上有的 release 没有「Set as latest」按钮？
-
-若该 release 被标成了 **Pre-release**，GitHub 不允许把它设为 Latest，所以只会显示 Pre-release 相关选项。当前流程发布的是正式版并自动设为 Latest，不会出现这种情况。
-
-### 推送 main 或 tag 报错：Could not read from remote repository / Connection closed
-
-多为网络或权限问题：检查本机能否访问 GitHub、SSH 密钥或 token 是否有效、仓库是否存在且有写权限。
-
-### 想重新用同一版本号再发一次（例如 workflow 之前失败了）
-
-需要**先删本地 tag、再删远程 tag**，在要发布的 commit（例如当前 main）上重新打 tag 并推送。否则你 push 的仍是旧 tag 指向的旧 commit，Release 会错。完整步骤见下方 [六、Git tag 说明](#六git-tag-说明)。也可参见 `docs/release-operations-manual.md` 的「重新触发构建」一节。
-
----
-
-## 六、Git tag 说明
-
-发布流程依赖 **git tag**。了解其行为可以避免「改了版本号、删了远程 tag 再 push，结果 Release 还是错的」。
-
-### 6.1 tag 是什么？
-
-- 每个 **commit** 有一个唯一的 SHA-1（如 `f7db4d1...`）。
-- **tag** 是给某个 commit 起的**固定名字**（如 `v1.0.1`），在 Git 里就是一个「名字 → 该 commit」的引用。
-- 可以理解为：**tag = 钉在某个 commit 上的书签**，不会跟着你后续的新提交自动移动。
-
-### 6.2 两种 tag
-
-| 类型 | 命令 | 说明 |
-|------|------|------|
-| **轻量 tag** | `git tag v1.0.1` | 只记录「名字 → 当前 commit」，常用。 |
-| **附注 tag** | `git tag -a v1.0.1 -m "Release 1.0.1"` | 会生成带作者、时间、说明的 tag 对象，再让名字指向它。 |
-
-本项目的发布用轻量 tag 即可。
-
-### 6.3 常用操作实际做了什么？
-
-| 操作 | 实际效果 |
-|------|----------|
-| `git tag v1.0.1` | 在当前 HEAD 指向的 commit 上，创建引用 `refs/tags/v1.0.1`，不提交、不改文件。 |
-| `git tag -d v1.0.1` | 删除**本地**的 `v1.0.1` 引用，commit 仍在。 |
-| `git push origin v1.0.1` | 把本地 `v1.0.1` 指向的 commit 的「名字」同步到远程。 |
-| `git push origin --delete v1.0.1` | 删除**远程**的 `v1.0.1` 引用，不删 commit。 |
-
-### 6.4 为什么 tag「不会自己更新」？
-
-Tag 的设计就是**给历史某一点打标签**（如「这是 1.0.1 正式版」），所以不会随 `git commit` 自动挪到新 commit。要换指向，只能：删掉旧 tag（本地 + 远程），在**新的** commit 上重新打 tag 再 push。
-
-### 6.5 把已有版本号重新发布到当前 main（完整步骤）
-
-例如 v1.0.1 已存在但指向了旧 commit，想让它指向当前 main 并重新跑 Release：
-
-```bash
-# 1. 确保在最新 main（已改好 version 的提交）
-git checkout main
-git pull origin main
-
-# 2. 删本地 tag（否则会一直指向旧 commit）
-git tag -d v1.0.1
-
-# 3. 在当前 commit 上重新打 tag
-git tag v1.0.1
-
-# 4. 删远程 tag（若存在）
-git push origin --delete v1.0.1
-
-# 5. 推送新 tag，触发 Release workflow
-git push origin v1.0.1
-```
-
-之后到 Actions / Releases 确认 v1.0.1 的 Release 和 tgz 是否正常。

package/docs/RELEASE-MODEL-CONFIG.md

@@ -1,95 +0,0 @@
-# openclaw-agent-dashboard 模型配置修改总结
-
-## 一、修改概览
-
-本工程对模型配置模块进行了调整，使显示与配置生效逻辑与 OpenClaw 保持一致。
-
----
-
-## 二、涉及文件
-
-| 文件 | 修改内容 |
-|------|----------|
-| `src/backend/data/agent_config_manager.py` | 白名单过滤、展示用 id、`_get_allowlist_model_ids` |
-| `src/backend/data/config_reader.py` | `get_model_display_name` 改为仅用 id |
-| `scripts/test_available_models.py` | 新增白名单、保存格式测试 |
-
----
-
-## 三、与 OpenClaw 配置格式的对应关系
-
-### 3.1 配置读取（Agent 生效时使用）
-
-| OpenClaw 配置路径 | 含义 | Dashboard 读取 |
-|-------------------|------|----------------|
-| `agents.defaults.model.primary` | 默认主模型 | `get_agent_model_config` 合并 |
-| `agents.defaults.model.fallbacks` | 默认备选 | 同上 |
-| `agents.list[].model.primary` | Agent 主模型 | 覆盖 defaults |
-| `agents.list[].model.fallbacks` | Agent 备选 | 覆盖 defaults |
-
-**生效格式**：`provider/model`（如 `zhipu/glm-4`、`openai/gpt-4`）
-
-### 3.2 配置写入（用户保存后）
-
-| 写入路径 | 格式 | 示例 |
-|----------|------|------|
-| `agents.list[id].model.primary` | model_id 字符串 | `"openai/gpt-4"` |
-| `agents.list[id].model.fallbacks` | model_id 数组 | `["zhipu/glm-4-flash"]` |
-
-**与 OpenClaw 一致**：`update_agent_model` 直接写入上述字段。
-
-### 3.3 可选模型列表（白名单）
-
-| 条件 | 显示来源 | 与 OpenClaw 一致 |
-|------|----------|------------------|
-| 有 `agents.defaults.models` | 仅白名单中的 model_id | ✓ buildAllowedModelSet |
-| 无白名单 + 有 `models.providers` | providers 全量 + agents 已用 | ✓ |
-| 无白名单 + 无 providers | 从 agents 收集 | ✓ |
-
-### 3.4 展示策略
-
-| 策略 | 实现 | 说明 |
-|------|------|------|
-| 使用 id 不用别名 | `_model_id_to_display_name` | `zhipu/glm-4` → `glm-4` |
-| 下拉 option value | `model.id`（model_id） | 保存时写入 primary/fallbacks |
-
----
-
-## 四、数据流
-
-```
-用户选择模型（下拉 option value = model_id）
-    ↓
-PUT /api/agent-config/{id}/model { primary, fallbacks }
-    ↓
-update_agent_model() 写入 agents.list[].model
-    ↓
-openclaw.json 格式符合 OpenClaw 约定
-    ↓
-OpenClaw 重启后读取 model.primary / model.fallbacks 生效
-```
-
----
-
-## 五、测试场景
-
-| 场景 | 验证点 |
-|------|--------|
-| 1 | 无 providers，从 agents 收集 |
-| 2 | 仅 defaults.model |
-| 3 | agents.list 为空 |
-| 3b | 白名单 + 展示用 id |
-| 3c | providers + 白名单，仅显示白名单 |
-| 3d | 配置保存格式（primary/fallbacks） |
-
----
-
-## 六、符合性结论
-
-| 维度 | 符合预期 |
-|------|----------|
-| 配置读取格式 | ✓ agents.list[].model.primary/fallbacks |
-| 配置写入格式 | ✓ 同上 |
-| 白名单逻辑 | ✓ agents.defaults.models 与 buildAllowedModelSet 一致 |
-| 展示策略 | ✓ 使用 id 不用别名 |
-| 无白名单时 | ✓ providers 或 agents 收集 |

package/docs/WINDOWS_INSTALL_TROUBLESHOOTING.md

@@ -1,171 +0,0 @@
-# Windows 安装问题排查指南
-
-本文档针对 `npx openclaw-agent-dashboard@1.0.8 --verbose` 在 Windows 下的安装问题进行说明和解决方案。
-
----
-
-## 一、问题概览
-
-根据安装日志，主要有以下几类问题：
-
-| 问题 | 严重程度 | 影响 |
-|------|----------|------|
-| Python 依赖安装失败 | 高 | Dashboard 后端无法启动 |
-| Node.js DEP0190 警告 | 低 | 仅提示，不影响功能 |
-| 安全模式警告 | 低 | 需配置 `plugins.allow` |
-
-> **v1.0.9+** 已移除 `plugins install` 步骤，openclaw 会自动发现 extensions 下的插件，不再出现「插件注册失败」。
-
----
-
-## 二、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` 命令。
-
----
-
-## 三、插件注册（已修复）
-
-**v1.0.9+** 安装流程已优化：仅将文件复制到 `extensions` 目录，不再调用 `openclaw plugins install`。  
-openclaw 会自动发现并加载 `extensions` 下的插件，无需手动注册。若仍看到 "plugin already exists" 等提示，请升级到最新版本。
-
----
-
-## 四、其他警告说明
-
-### 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. **Python 安装**：支持通过环境变量或参数指定 pip 镜像（如 `PIP_INDEX_URL`）。
-2. **帮助信息**：在 Windows 下增加代理、镜像、离线安装的说明。
-3. **runCommand**：考虑使用 `execSync(cmd, args, { shell: false })` 或 `spawn` 传参，消除 DEP0190 警告。