openclaw-agent-dashboard 1.0.4

package/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Build and pack plugin
+        run: npm run pack
+
+      - name: Generate release tgz
+        run: bash scripts/release-pack.sh
+
+      - name: Get version
+        id: version
+        run: |
+          VERSION=$(jq -r '.version' plugin/openclaw.plugin.json)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: plugin-tgz
+          path: openclaw-agent-dashboard-v*.tgz
+          retention-days: 30
+
+      - name: Create Release
+        if: github.event_name == 'push'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          name: Release ${{ steps.version.outputs.tag }}
+          generate_release_notes: true
+          make_latest: true
+          files: |
+            openclaw-agent-dashboard-v*.tgz

package/README.md

@@ -0,0 +1,302 @@
+# OpenClaw Agent Dashboard
+
+多 Agent 可视化看板 - 实时展示 OpenClaw Agent 状态、任务进度和错误分析。
+
+## 功能特性
+
+- **工位视图** - 以卡片形式展示主 Agent 和子 Agent 状态
+- **时序视图** - 展示 Agent 执行步骤的时间线
+- **链路视图** - 展示主 Agent 与子 Agent 的任务派发链路
+- **Agent 配置** - 查看和修改 Agent 的模型配置
+- **错误分析** - 错误根因分析、分类和修复建议
+- **API 状态** - 展示 API 服务异常和限流情况
+- **性能监控** - Token 使用、响应时间等
+
+## 系统要求
+
+| 组件 | 要求 |
+|------|------|
+| **openclaw** | 已安装 (`npm install -g openclaw`) |
+| **Node.js** | 16+ |
+| **Python** | 3.8+ |
+| **pip** | python3-pip |
+| **venv** | python3-venv（Linux 推荐） |
+
+### 各系统依赖安装
+
+**Debian / Ubuntu:**
+```bash
+sudo apt update
+sudo apt install python3 python3-pip python3-venv
+```
+
+**Fedora / CentOS / RHEL:**
+```bash
+sudo dnf install python3 python3-pip
+```
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Windows:**
+1. 安装 [Node.js](https://nodejs.org/)（LTS 版本）
+2. 安装 [Python 3](https://www.python.org/downloads/)
+   - ⚠️ 安装时务必勾选 **"Add Python to PATH"**
+3. 安装 [Git for Windows](https://git-scm.com/download/win)（可选，用于 `curl | bash` 安装方式）
+
+## 快速安装
+
+### 方式一：一键安装（推荐）
+
+```bash
+# 一键安装（需已安装 openclaw：npm install -g openclaw）
+curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
+```
+
+安装完成后，执行任意 `openclaw` 命令时 Dashboard 会自动启动。
+
+访问地址: http://localhost:38271
+
+**可选参数**:
+
+```bash
+# 安装指定版本
+DASHBOARD_VERSION=1.0.0 curl -fsSL https://raw.githubusercontent.com/Umarchen/openclaw-agent-dashboard/main/scripts/install.sh | bash
+
+# 使用自定义下载地址
+DASHBOARD_RELEASE_URL=https://example.com/openclaw-agent-dashboard-v1.0.0.tgz curl -fsSL ... | bash
+
+# 跳过 Python 依赖安装
+DASHBOARD_SKIP_PYTHON=1 curl -fsSL ... | bash
+
+# 显示详细输出（调试用）
+VERBOSE=1 curl -fsSL ... | bash
+
+# 预览安装过程（不执行实际安装）
+DRY_RUN=1 curl -fsSL ... | bash
+```
+
+### 方式二：从源码安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/Umarchen/openclaw-agent-dashboard.git
+cd openclaw-agent-dashboard
+
+# 部署到 OpenClaw（构建前端 + 打包插件 + 安装）
+npm run deploy
+```
+
+**Windows 用户**：源码安装使用 Node.js 脚本，无需 Git Bash，在 PowerShell 或 CMD 中直接运行：
+
+```powershell
+# 克隆仓库
+git clone https://github.com/Umarchen/openclaw-agent-dashboard.git
+cd openclaw-agent-dashboard
+
+# 部署（跨平台）
+npm run deploy
+```
+
+### 方式三：手动下载安装
+
+从 [GitHub Releases](https://github.com/Umarchen/openclaw-agent-dashboard/releases) 下载 tgz 包：
+
+```bash
+# 下载
+curl -LO https://github.com/Umarchen/openclaw-agent-dashboard/releases/download/v1.0.0/openclaw-agent-dashboard-v1.0.0.tgz
+
+# 安装
+openclaw plugins install openclaw-agent-dashboard-v1.0.0.tgz
+
+# 安装 Python 依赖（Debian/Ubuntu 请用 venv，避免 PEP 668 报错）
+cd ~/.openclaw/extensions/openclaw-agent-dashboard/dashboard
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+## 命令说明
+
+| 命令 | 说明 |
+|------|------|
+| `npm run deploy` | 打包 + 安装到 OpenClaw（首次安装或升级） |
+| `npm run upgrade` | 拉取最新代码 + 部署（推荐用于升级） |
+| `npm run pack` | 仅打包插件，不安装（开发调试用） |
+| `npm run bundle` | 生成可分发的压缩包（给同事用） |
+| `npm run start` | 独立启动 Dashboard（插件未自动启动时使用） |
+
+## 离线分发（给同事）
+
+如果 git clone 失败，可以打包分发：
+
+```bash
+# 生成压缩包
+npm run bundle
+# 输出: openclaw-agent-dashboard-v1.0.0.tar.gz
+```
+
+同事收到后：
+
+```bash
+# 解压
+tar -xzf openclaw-agent-dashboard-v1.0.0.tar.gz
+
+# 进入目录
+cd openclaw-agent-dashboard
+
+# 安装
+npm run deploy
+```
+
+## Python 依赖安装策略
+
+安装脚本采用以下策略安装 Python 依赖：
+
+1. **venv（推荐）** - 在插件目录下创建 `.venv`，隔离依赖，不受 PEP 668 影响；Debian/Ubuntu 下**必须**用此方式（系统禁止 pip 装到系统/用户目录）。
+2. **pip --user（回退）** - 仅在不支持 venv 或非 Debian/Ubuntu 环境下尝试，安装到 `~/.local/`。
+
+若安装失败，请确保已安装系统依赖（见 [系统要求](#系统要求)）。
+
+详见 [Python 环境兼容性](docs/python-environment-compatibility.md)。
+
+## 独立运行（不作为插件）
+
+如果需要独立运行（不作为插件）：
+
+```bash
+# 1. 安装后端依赖（Debian/Ubuntu 建议用 venv：python3 -m venv .venv && .venv/bin/pip install -r requirements.txt）
+cd src/backend
+pip install -r requirements.txt
+
+# 2. 构建前端
+cd ../../frontend
+npm install
+npm run build
+
+# 3. 启动后端
+cd ../src/backend
+uvicorn main:app --host 0.0.0.0 --port 38271
+```
+
+## 项目结构
+
+```
+openclaw-agent-dashboard/
+├── frontend/              # Vue 3 前端
+│   └── src/              # 组件源码
+├── src/backend/           # FastAPI 后端
+│   ├── api/              # API 路由
+│   ├── data/             # 数据读取层
+│   └── main.py           # 入口
+├── plugin/                # 插件打包配置
+├── scripts/               # 安装与构建脚本
+│   ├── lib/              # 公共函数库
+│   ├── install.sh        # 一键安装
+│   └── install-plugin.sh # 源码安装
+├── .github/workflows/     # CI/CD
+└── docs/                  # 设计文档
+```
+
+## 主要 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/agents` | Agent 列表及状态 |
+| GET | `/api/agent-config/:id` | Agent 配置 |
+| PUT | `/api/agent-config/:id/model` | 更新模型配置 |
+| GET | `/api/error-analysis/:id` | 错误分析 |
+| GET | `/api/timeline/:id` | 时序数据 |
+| GET | `/api/chains` | 任务链路 |
+
+完整 API 文档: http://localhost:38271/docs
+
+## 数据源
+
+- `~/.openclaw/openclaw.json` - Agent 配置
+- `~/.openclaw/subagents/runs.json` - 子代理运行记录
+- `~/.openclaw/agents/*/sessions/*.jsonl` - 会话消息
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OPENCLAW_STATE_DIR` | OpenClaw 配置根目录（优先级最高） | - |
+| `OPENCLAW_HOME` | 替代 HOME，用于解析 `~/.openclaw` | `$HOME` |
+
+插件安装路径与 `openclaw` 命令一致：`$OPENCLAW_STATE_DIR/extensions/` 或 `$OPENCLAW_HOME/.openclaw/extensions/` 或 `~/.openclaw/extensions/`，确保 Gateway 能正确发现插件。
+
+## 开发调试
+
+```bash
+# 修改代码后重新部署
+npm run deploy
+openclaw gateway restart
+```
+
+## 故障排查
+
+### Python 依赖安装失败
+
+```
+❌ Python 依赖安装失败
+```
+
+**解决方案：**
+
+```bash
+# Debian/Ubuntu（需安装 python3-venv，否则请用下方 venv 手动安装）
+sudo apt update && sudo apt install python3 python3-pip python3-venv
+
+# 重新安装（安装脚本会优先使用 venv）
+npm run deploy
+
+# 或手动用 venv 安装依赖（推荐，避免 externally-managed-environment）
+cd ~/.openclaw/extensions/openclaw-agent-dashboard/dashboard
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+### 无法访问 Dashboard
+
+若 http://localhost:38271 无法访问，可能是插件未随 Gateway 自动启动，可手动启动：
+
+```bash
+# 方式一：在项目目录下（需先 npm run deploy）
+npm run start
+
+# 方式二：使用已安装的插件目录（若有 .venv 可用 .venv/bin/python 替代 python3）
+cd ~/.openclaw/extensions/openclaw-agent-dashboard/dashboard
+OPENCLAW_HOME=~/.openclaw python3 -m uvicorn main:app --host 0.0.0.0 --port 38271
+```
+
+说明：`openclaw gateway restart` 重启的是 Gateway 网关（端口 18789），不是 Agent Dashboard（38271）。Dashboard 作为插件随 Gateway 加载，若 systemd 方式运行的 Gateway 未正确加载插件，需手动启动 Dashboard。
+
+### 安装报错：plugin not found / Invalid config
+
+若出现 `plugins.allow: plugin not found: openclaw-agent-dashboard` 或 `Invalid config`，说明配置中有脏数据（插件曾被加入 allow 但当前未被发现）。按以下步骤处理：
+
+**方式一：先清理再安装（推荐）**
+
+```bash
+# 1. 卸载旧配置
+openclaw plugins uninstall openclaw-agent-dashboard
+
+# 2. 重新安装
+npm run deploy
+```
+
+**方式二：手动编辑配置**
+
+编辑 `~/.openclaw/openclaw.json`，在 `plugins` 下：
+
+- 若存在 `allow` 数组且包含 `"openclaw-agent-dashboard"`，将其移除
+- 若存在 `entries.openclaw-agent-dashboard`，可删除
+- 若存在 `installs.openclaw-agent-dashboard`，可删除
+
+保存后执行 `npm run deploy`。
+
+## 许可证
+
+MIT

package/docs/CHANGELOG_AGENT_MODIFICATIONS.md

@@ -0,0 +1,132 @@
+# OpenClaw Agent Dashboard — 修改点汇总
+
+本文档汇总近期对 **openclaw-agent-dashboard** 工程的修改，便于他人评审与追溯。  
+修改范围：TPM/RPM 统计、连接状态、Windows 启动、调试能力及文档。
+
+---
+
+## 一、TPM 趋势无值 / 多接口 usage 兼容
+
+### 问题
+- 性能监控中 **TPM 趋势** 一直为 0，RPM 趋势有值。
+- 原因：TPM 仅依赖 `usage.totalTokens`，而不同大模型/网关返回的 usage 格式不一（如 `input`/`output`、`input_tokens`/`output_tokens` 等），或上游未写入 totalTokens 导致为 0。
+
+### 修改策略
+- **不再枚举字段名**：采用两段逻辑——
+  1. 若有明确总量字段（`totalTokens` / `total_tokens` / `total`）且 > 0，直接使用；
+  2. 否则对 `usage` 内**所有数值**求和作为总 token 数，兼容任意命名。
+- 避免对同一用量重复计算：有总量时只返回总量，不再参与求和。
+
+### 涉及文件
+| 文件 | 修改内容 |
+|------|----------|
+| `plugin/dashboard/api/performance.py` | `_tokens_from_usage()` 重写；新增 `GET /api/performance/debug-usage` 调试接口 |
+| `src/backend/api/performance.py` | 同上（与 plugin 保持一致的逻辑与调试接口） |
+| `plugin/dashboard/performance.py` | `_tokens_from_usage()` 与 plugin api 一致 |
+| `src/backend/performance.py` | 同上 |
+
+### 调试接口
+- **GET** `/api/performance/debug-usage?limit=5`
+- 返回：`openclaw_path`、`agents_path_exists`、`samples[]`（含 `usage_raw`、`tokens_computed`）。
+- 用于确认 session 中实际 usage 结构及 TPM 为 0 是否因上游未写入 token 数。
+
+### 说明
+- 若 session 中 `usage` 各字段均为 0（如部分 vLLM/本地模型未回传 token），TPM 仍会为 0，需在**写 session 的上游**（OpenClaw/网关/模型适配层）补齐 usage 写入。
+
+---
+
+## 二、右上角「连接错误」与 WebSocket 回退
+
+### 问题
+- Dashboard 右上角连接状态显示「连接错误」。
+- 原因：WebSocket `ws://localhost:38271/ws` 连接失败或建立后因发送初始状态异常而断开；前端未及时进入 HTTP 轮询。
+
+### 后端修改
+- **发送初始状态失败时**：捕获异常后仍发送最小 `full_state` payload（空列表/空对象），保持连接不因异常关闭。
+- **心跳协议**：同时支持纯文本 `ping` 与 JSON `{"type":"ping",...}`，并统一以 JSON 回复 `{"type":"pong",...}`，与前端一致。
+
+### 前端修改
+- **WebSocket onerror**：除设置状态为 error 外，调用 `handleDisconnect()`，进入重连或 HTTP 轮询，避免一直停在「连接错误」。
+- **重连次数**：默认由 5 次改为 3 次，更快 fallback 到 HTTP 轮询。
+
+### 涉及文件
+| 文件 | 修改内容 |
+|------|----------|
+| `plugin/dashboard/api/websocket.py` | 初始状态异常时发最小 payload；心跳支持 JSON ping/pong |
+| `src/backend/api/websocket.py` | 同上 |
+| `frontend/src/managers/RealtimeDataManager.ts` | onerror 时调用 handleDisconnect()；reconnectMaxAttempts 默认 3 |
+
+---
+
+## 三、Windows 下 `npm run start` 报错
+
+### 问题
+- 在 Windows PowerShell 执行 `npm run start` 报错：`'OPENCLAW_HOME' 不是内部或外部命令`。
+- 原因：`package.json` 的 start 脚本使用 Linux/Mac 环境变量语法（`OPENCLAW_HOME=${OPENCLAW_HOME:-$HOME/.openclaw} ...`），在 Windows CMD 下无法解析。
+
+### 修改
+- 新增 **Node 跨平台启动脚本** `scripts/start.js`：
+  - 根据 `OPENCLAW_HOME`、`DASHBOARD_PORT` 环境变量或默认值设置；
+  - Windows 使用 `python`，非 Windows 使用 `python3`；
+  - 在 `src/backend` 目录下执行 `uvicorn main:app --host 0.0.0.0 --port <port>`。
+- **package.json**：`start` 脚本改为 `node scripts/start.js`。
+
+### 涉及文件
+| 文件 | 修改内容 |
+|------|----------|
+| `scripts/start.js` | 新增，跨平台启动 Dashboard 后端 |
+| `package.json` | `"start": "node scripts/start.js"` |
+
+### 说明
+- 不影响 Ubuntu/Debian 等 Linux 行为；若已设置 `OPENCLAW_HOME`、`DASHBOARD_PORT`，仍会生效。
+
+---
+
+## 四、文档与运维
+
+### 新增/更新文档
+| 文件 | 用途 |
+|------|------|
+| `RESTART_AND_BUILD.md` | 重启服务、是否需重新打包、一条龙命令（含 Windows PowerShell）；插件部署与独立运行两种方式 |
+| `docs/CHANGELOG_AGENT_MODIFICATIONS.md` | 本修改汇总文档，供他人评审 |
+
+---
+
+## 五、修改文件清单（便于 diff / code review）
+
+```
+openclaw-agent-dashboard-main/
+├── package.json                              # start 改为 node scripts/start.js
+├── RESTART_AND_BUILD.md                      # 新增：重启与打包说明
+├── scripts/
+│   └── start.js                              # 新增：跨平台启动脚本
+├── docs/
+│   └── CHANGELOG_AGENT_MODIFICATIONS.md      # 本文件
+├── frontend/src/managers/
+│   └── RealtimeDataManager.ts               # WebSocket 失败回退与重连次数
+├── plugin/dashboard/api/
+│   ├── performance.py                       # _tokens_from_usage + debug-usage
+│   └── websocket.py                          # 初始状态容错 + JSON 心跳
+├── plugin/dashboard/
+│   └── performance.py                        # _tokens_from_usage 与 api 一致
+├── src/backend/api/
+│   ├── performance.py                       # 同 plugin/dashboard/api/performance
+│   └── websocket.py                          # 同 plugin/dashboard/api/websocket
+└── src/backend/
+    └── performance.py                        # _tokens_from_usage 与 api 一致
+```
+
+---
+
+## 六、建议评审关注点
+
+1. **TPM 逻辑**：`_tokens_from_usage` 先取总量、再对 usage 全数值求和的策略是否满足业务（有无误把非 token 数字加进去的风险）。
+2. **WebSocket**：初始状态失败时发最小 payload 是否与前端约定一致；JSON ping/pong 与现有客户端兼容性。
+3. **前端**：onerror 时立即 handleDisconnect 与 onclose 的重复调用是否会导致双重重连定时器（当前实现中 scheduleReconnect 会先 stopReconnect，一般只保留一个定时器）。
+4. **Windows 启动**：`scripts/start.js` 中 `OPENCLAW_HOME` 默认路径、`python`/`python3` 选择在目标环境是否均可用。
+
+---
+
+**文档版本**：v1.0  
+**整理日期**：2026-03-13  
+**工程**：openclaw-agent-dashboard（含 plugin 与 src/backend 两套路径）

package/docs/RELEASE-LATEST.md

@@ -0,0 +1,189 @@
+# 发布新 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 是否正常。