openclaw-agent-dashboard 1.0.4

package/docs/RELEASE-MODEL-CONFIG.md

@@ -0,0 +1,95 @@
+# 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/release-guide.md

@@ -0,0 +1,259 @@
+# 发布与使用指南
+
+> 本文档说明如何提交更改、发布新版本以及使用一键安装功能。
+
+---
+
+## 一、提交当前更改
+
+### 1.1 查看待提交文件
+
+```bash
+git status --short
+```
+
+### 1.2 提交更改
+
+```bash
+# 方式一：提交所有更改
+git add .
+git commit -m "feat: 添加一键安装支持 + GitHub Actions 发布流程
+
+- 新增 scripts/install.sh 一键安装入口
+- 新增 scripts/install-python-deps.sh Python 依赖安装
+- 新增 scripts/release-pack.sh 发布打包
+- 新增 .github/workflows/release.yml CI/CD
+- 优化 plugin/index.js 优先使用 venv Python
+- 重构 scripts/install-plugin.sh 支持 VERBOSE/DRY_RUN
+- 更新 README.md 添加一键安装说明"
+
+git push origin main
+```
+
+```bash
+# 方式二：选择性提交
+git add .github/workflows/release.yml \
+        scripts/install.sh \
+        scripts/install-python-deps.sh \
+        scripts/release-pack.sh \
+        scripts/install-plugin.sh \
+        plugin/index.js \
+        README.md \
+        docs/
+
+git commit -m "feat: 添加一键安装支持 + GitHub Actions 发布流程"
+git push origin main
+```
+
+---
+
+## 二、发布新版本
+
+### 2.1 更新版本号
+
+编辑 `plugin/openclaw.plugin.json`，修改 version 字段：
+
+```json
+{
+  "id": "openclaw-agent-dashboard",
+  "name": "OpenClaw Agent Dashboard",
+  "version": "1.0.1",  // 修改此处
+  ...
+}
+```
+
+### 2.2 提交并打 Tag
+
+```bash
+# 提交版本更新
+git add plugin/openclaw.plugin.json
+git commit -m "release: v1.0.1"
+git push origin main
+
+# 创建 tag 并推送（触发 GitHub Actions 自动构建发布）
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+### 2.3 GitHub Actions 自动流程
+
+推送 tag 后，GitHub Actions 会自动执行：
+
+| 步骤 | 说明 |
+|------|------|
+| 1 | Checkout 代码 |
+| 2 | 安装 Node.js 依赖 |
+| 3 | 构建前端 (`npm run pack`) |
+| 4 | 生成 tgz 包 (`release-pack.sh`) |
+| 5 | 创建 GitHub Release |
+| 6 | 上传 tgz 到 Release Assets |
+
+### 2.4 验证发布
+
+1. 访问 GitHub Releases 页面：`https://github.com/Umarchen/openclaw-agent-dashboard/releases`
+2. 确认新版本已创建
+3. 确认 tgz 文件已上传
+
+---
+
+## 三、本地测试
+
+### 3.1 构建并打包
+
+```bash
+# 构建前端 + 打包插件
+npm run pack
+
+# 生成发布 tgz
+bash scripts/release-pack.sh
+```
+
+### 3.2 测试一键安装脚本
+
+```bash
+# 预览模式（不执行实际安装）
+DRY_RUN=1 bash scripts/install.sh
+
+# 使用本地 tgz 测试安装
+DASHBOARD_RELEASE_URL="file://$(pwd)/openclaw-agent-dashboard-v1.0.0.tgz" \
+  bash scripts/install.sh
+
+# 跳过 Python 依赖安装（快速测试）
+DASHBOARD_RELEASE_URL="file://$(pwd)/openclaw-agent-dashboard-v1.0.0.tgz" \
+  DASHBOARD_SKIP_PYTHON=1 \
+  bash scripts/install.sh
+```
+
+### 3.3 测试源码安装脚本
+
+```bash
+# 预览模式
+DRY_RUN=1 bash scripts/install-plugin.sh
+
+# 详细输出模式
+VERBOSE=1 bash scripts/install-plugin.sh
+```
+
+### 3.4 验证安装结果
+
+```bash
+# 检查插件目录
+ls -la ~/.openclaw/extensions/openclaw-agent-dashboard/
+
+# 检查插件配置
+openclaw plugins list
+```
+
+---
+
+## 四、清理构建产物
+
+```bash
+# 删除本地测试生成的 tgz（不需要提交到仓库）
+rm -f openclaw-agent-dashboard-v*.tgz
+
+# 清理前端构建产物
+rm -rf frontend/dist
+
+# 清理插件打包产物
+rm -rf plugin/dashboard plugin/frontend-dist
+```
+
+---
+
+## 五、用户安装方式
+
+### 5.1 一键安装（推荐）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
+```
+
+### 5.2 指定版本安装
+
+```bash
+DASHBOARD_VERSION=1.0.1 curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
+```
+
+### 5.3 从源码安装
+
+```bash
+git clone https://github.com/Umarchen/openclaw-agent-dashboard.git
+cd openclaw-agent-dashboard
+npm run deploy
+```
+
+---
+
+## 六、环境变量参考
+
+### install.sh 支持的环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DASHBOARD_VERSION` | 指定安装版本 | `latest` |
+| `DASHBOARD_RELEASE_URL` | 自定义下载地址 | GitHub Releases URL |
+| `DASHBOARD_SKIP_PYTHON` | 跳过 Python 依赖安装 | `0` |
+| `VERBOSE` | 显示详细输出 | `0` |
+| `DRY_RUN` | 仅预览，不执行 | `0` |
+
+### install-plugin.sh 支持的环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `VERBOSE` | 显示详细输出 | `0` |
+| `DRY_RUN` | 仅预览，不执行 | `0` |
+| `OPENCLAW_STATE_DIR` | OpenClaw 配置目录 | - |
+| `OPENCLAW_HOME` | 替代 HOME | `$HOME` |
+
+---
+
+## 七、常见问题
+
+### Q1: GitHub Actions 构建失败
+
+检查：
+- `plugin/openclaw.plugin.json` 格式是否正确
+- `npm run pack` 本地是否能正常运行
+- package.json 中的依赖是否完整
+
+### Q2: 下载 tgz 失败
+
+用户可能遇到网络问题，建议：
+- 设置代理：`export https_proxy=http://proxy:port`
+- 手动下载后使用本地文件：`DASHBOARD_RELEASE_URL=file:///path/to/tgz`
+
+### Q3: Python 依赖安装失败
+
+常见于 Debian/Ubuntu PEP 668 环境：
+```bash
+# 安装 python3-venv
+sudo apt install python3-venv python3-pip
+
+# 或手动安装依赖
+python3 -m pip install -r ~/.openclaw/extensions/openclaw-agent-dashboard/dashboard/requirements.txt --user
+```
+
+---
+
+## 八、快速命令参考
+
+```bash
+# 开发流程
+npm run pack                    # 构建前端 + 打包插件
+npm run deploy                  # 打包 + 安装到本地
+bash scripts/release-pack.sh    # 生成发布 tgz
+
+# 测试流程
+DRY_RUN=1 bash scripts/install.sh                    # 预览安装
+DASHBOARD_RELEASE_URL=file://... bash scripts/install.sh  # 本地 tgz 测试
+
+# 发布流程
+vim plugin/openclaw.plugin.json  # 更新版本号
+git add . && git commit -m "release: vX.X.X"
+git push origin main
+git tag vX.X.X && git push origin vX.X.X  # 触发 CI/CD
+
+# 清理
+rm -f openclaw-agent-dashboard-v*.tgz
+```

package/docs/release-operations-manual.md

@@ -0,0 +1,167 @@
+# OpenClaw Agent Dashboard 发布操作手册
+
+> 面向小白的发布流程说明，包含操作步骤和原理讲解。
+
+---
+
+## 一、整体流程概览
+
+```
+你写代码 → 推送到 GitHub → 打 tag → 自动构建 → 别人可以安装
+```
+
+| 阶段 | 你做什么 | 系统做什么 |
+|------|----------|------------|
+| 1. 开发 | 修改代码 | - |
+| 2. 提交 | `git add`、`git commit` | 记录到本地 |
+| 3. 推送 | `git push origin main` | 代码同步到 GitHub |
+| 4. 打 tag | `git tag v1.0.0` | 给当前代码打个「版本号」 |
+| 5. 发布 | `git push origin v1.0.0` | **触发自动构建**，生成安装包 |
+| 6. 完成 | 无 | 别人可以一键安装 |
+
+---
+
+## 二、核心概念
+
+### 2.1 什么是 tag？
+
+tag 就像给某次提交贴一个「版本标签」，例如 `v1.0.0`。
+
+- **作用**：标记「这是 1.0.0 正式版」
+- **和分支的区别**：分支会继续往前走，tag 一般固定在那次提交上
+- **命名习惯**：`v` + 版本号，如 `v1.0.0`、`v1.0.1`、`v2.0.0`
+
+### 2.2 什么是 GitHub Actions？
+
+GitHub 提供的**自动化流水线**，可以在你推送代码或 tag 时自动执行脚本。
+
+- **不是**：GitHub 自带的通用测试
+- **是**：项目里自己配置的「发布流水线」
+- **配置文件**：`.github/workflows/release.yml`
+
+### 2.3 为什么推送 tag 会触发构建？
+
+在 `release.yml` 里写了：
+
+```yaml
+on:
+  push:
+    tags:
+      - 'v*'   # 只要推送的 tag 以 v 开头，就触发
+```
+
+所以：`git push origin v1.0.0` → GitHub 检测到 tag 推送 → 自动跑 workflow。
+
+### 2.4 构建完成后会发生什么？
+
+1. 在 frontend 目录安装依赖、构建前端
+2. 打包 backend 和 frontend，生成 `.tgz` 安装包
+3. 在 GitHub 上创建 **Release**
+4. 把 `.tgz` 作为附件上传到 Release
+
+别人就可以通过 Release 下载安装包，或使用一键安装脚本。
+
+---
+
+## 三、常用操作
+
+### 3.1 首次发布（第一次发 v1.0.0）
+
+```bash
+# 1. 确保代码已提交并推送到 main
+git add .
+git commit -m "你的提交说明"
+git push origin main
+
+# 2. 打 tag
+git tag v1.0.0
+
+# 3. 推送 tag，触发构建
+git push origin v1.0.0
+```
+
+### 3.2 发布新版本（如 v1.0.1）
+
+```bash
+# 1. 代码已推送到 main 后
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+### 3.3 重新触发构建（tag 已存在，想再跑一次）
+
+有时 workflow 失败，修好代码后想用同一个版本号再跑一次：
+
+```bash
+# 删除本地 tag
+git tag -d v1.0.0
+
+# 在最新提交上重新打 tag
+git tag v1.0.0
+
+# 删除远程 tag
+git push origin :refs/tags/v1.0.0
+
+# 推送新 tag，触发构建
+git push origin v1.0.0
+```
+
+### 3.4 手动触发构建（不推 tag）
+
+在 GitHub 网页上：
+
+1. 打开 https://github.com/Umarchen/openclaw-agent-dashboard/actions
+2. 左侧选择 **Release** workflow
+3. 点击 **Run workflow** → **Run workflow**
+
+---
+
+## 四、重要说明
+
+### 4.1 推送 main 不会触发 Release
+
+- `git push origin main`：只同步代码，**不会**触发 Release workflow
+- `git push origin v1.0.0`：推送 tag，**会**触发 Release workflow
+
+### 4.2 tag 指向哪次提交，就用哪次提交的代码构建
+
+如果 tag 是之前打的，后来改了 `.github/workflows/release.yml` 但没重新打 tag，workflow 用的还是**旧配置**。需要把 tag 挪到最新提交上（见 3.3）。
+
+### 4.3 别人怎么安装
+
+| 方式 | 命令 |
+|------|------|
+| 一键安装 | `curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh \| bash` |
+| 源码安装 | `git clone ... && npm run deploy` |
+| 手动下载 | 从 [Releases](https://github.com/Umarchen/openclaw-agent-dashboard/releases) 下载 tgz，`openclaw plugins install xxx.tgz` |
+
+---
+
+## 五、故障排查
+
+### 5.1 构建失败：Dependencies lock file is not found
+
+**原因**：`setup-node` 的 `cache: 'npm'` 需要在根目录有 `package-lock.json`，本项目锁文件在 `frontend/` 下。
+
+**解决**：已在 `release.yml` 中移除 `cache: 'npm'`，无需再改。
+
+### 5.2 推送 tag 后没看到 workflow 运行
+
+- 检查：https://github.com/Umarchen/openclaw-agent-dashboard/actions
+- 确认 tag 已推送成功：`git ls-remote --tags origin`
+
+### 5.3 Release 里没有 tgz 附件
+
+说明 workflow 某一步失败了。在 Actions 里点进那次运行，查看失败步骤的日志。
+
+---
+
+## 六、快速参考
+
+| 目标 | 命令 |
+|------|------|
+| 发布 v1.0.0 | `git tag v1.0.0` → `git push origin v1.0.0` |
+| 发布 v1.0.1 | `git tag v1.0.1` → `git push origin v1.0.1` |
+| 重新触发 v1.0.0 构建 | 见 3.3 |
+| 查看构建状态 | https://github.com/Umarchen/openclaw-agent-dashboard/actions |
+| 查看 Release | https://github.com/Umarchen/openclaw-agent-dashboard/releases |