Context Guardian 插件重构后数据重复推送与统计异常修复指南

## 问题现象

Context Guardian 插件重构后出现以下问题：

- **重复推送**：同一条上下文数据被推送多次（如两次及以上）。
- **统计值显示 `undefined`**：原本应显示文件大小、路径、智能体名称等字段的位置变成了 `undefined`。
- **路径和文件名丢失**：此前按智能体分目录的路径结构和包含智能体标识的命名规则失效。

重构前，推送和统计均正常，且路径规则能正确区分不同智能体。

---

## 原因分析

插件重构可能导致以下配置不兼容：

1. **路径模板变量变更**：旧版使用的模板变量（如 `{agent_name}`、`{date}`）在新版中可能被移除或重命名。
2. **命名规则参数缺省**：重构后未读取原有的命名规则配置，导致输出时字段匹配失败，显示 `undefined`。
3. **推送逻辑重复**：重构可能修改了推送触发条件或去重机制，造成同一条数据被多次推送。

---

## 诊断步骤

### 1. 进入容器并查看日志

进入 OpenClaw 容器，使用 `docker exec` 或 `kubectl exec`（根据部署方式），然后查看 Context Guardian 插件日志：

```bash
# 假设容器名为 openclaw-app
docker exec -it openclaw-app bash

# 进入插件日志目录（常见路径，请根据实际调整）
cd /var/log/openclaw/plugins/context-guardian/

# 查看最新日志，重点关注 ERROR、WARN 及推送相关的行
tail -n 200 guardian.log | grep -E "push|undefined|duplicate"
```

日志中通常会有类似如下信息：

```
[WARN] Missing field: agent_name in push payload
[ERROR] Duplicate push detected: msg_id=abc123
[DEBUG] Template variable {AGENT_NAME} not resolved, using undefined
```

### 2. 检查当前路径与命名配置

插件配置文件通常位于容器内 `/etc/openclaw/plugins/context-guardian/config.yaml` 或类似位置。读取并对比重构前后的差异：

```bash
cat /etc/openclaw/plugins/context-guardian/config.yaml
```

常见配置项示例：

```yaml
backup:
  path_template: "/backup/{agent_id}/{date}/"
  filename_template: "{agent_name}_{timestamp}.tar.gz"
push:
  deduplication: true
  dedup_window_seconds: 300
  channels:
    - type: wecom
      webhook: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=XXXX"
```

如果路径或文件名中包含 `{agent_name}` 但日志显示未解析，说明新版不再支持该变量。

### 3. 确认环境中的智能体标识

列出所有正在运行的智能体及其 ID/名称：

```bash
# 假设通过 OpenClaw API 或配置文件查看
openclaw-cli agent list
# 或直接查看智能体配置文件
ls -la /etc/openclaw/agents/
```

确保每个智能体有唯一的 `id` 和 `name`。

---

## 修复步骤

### 1. 还原/更新路径与命名规则

根据新版插件文档调整模板变量。常见变量对照：

| 旧变量            | 新变量（推荐）          | 说明                 |
| ----------------- | ----------------------- | -------------------- |
| `{agent_name}`    | `{agent_id}`            | 智能体唯一 ID        |
| `{date}`          | `{backup_date}`         | 备份日期（YYYYMMDD） |
| `{timestamp}`     | `{backup_timestamp}`    | Unix 时间戳          |
| `{agent_label}`   | `{agent_display_name}`  | 智能体显示名称       |

修改配置文件：

```yaml
backup:
  path_template: "/backup/{agent_id}/{backup_date}/"
  filename_template: "{agent_id}_{backup_timestamp}.tar.gz"
```

保存文件后，无需重启即可生效（若插件支持热加载），否则需重启插件服务。

### 2. 启用/修复去重推送

在推送配置中显式开启去重，并设置合适的窗口时间：

```yaml
push:
  deduplication: true
  dedup_window_seconds: 600   # 10分钟内不推送相同的消息
  dedup_key: "{message_hash}" # 基于消息内容哈希去重，避免重复
```

### 3. 修复统计字段 `undefined`

日志中若出现 `undefined`，通常是因为推送模板中引用了不存在的变量。检查推送消息模板：

```yaml
push:
  message_template: 
    【上下文备份通知】
    智能体：{agent_display_name}
    文件：{file_path}
    大小：{file_size}
    时间：{backup_time}
```

确保所有变量名与插件新版本支持的名称一致。可通过插件自带的变量测试接口验证：

```bash
# 假设插件提供测试命令
context-guardian test-template --template '{agent_display_name} | {file_size}'
```

如果输出仍显示 `undefined`，则需查看插件变更日志或使用硬编码字符串作为临时方案。

### 4. 重启插件（如需要）

若配置文件未自动加载，重启插件容器或服务：

```bash
# 重启 Docker 容器（视部署方式而定）
docker restart openclaw-app

# 或者仅重启插件进程（若支持）
kill -HUP $(pgrep context-guardian)
```

---

## 验证修复

确认日志中不再出现重复推送和 `undefined`：

```bash
tail -n 50 /var/log/openclaw/plugins/context-guardian/guardian.log | grep -v "undefined"
```

触发一次手动备份推送，检查推送消息是否完整显示路径、文件名、大小等信息，且不产生重复消息。

---

## 参考资源

- [Context Guardian 插件官方文档](https://docs.openclaw.io/plugins/context-guardian/)（变量对照表）
- [OpenClaw 配置指南 - 路径模板](https://docs.openclaw.io/config/path-templates/)
- [推送去重机制说明](https://docs.openclaw.io/plugins/push-dedup/)

---

> **注意事项**  
> - 所有配置修改前建议备份原文件：`cp config.yaml config.yaml.bak`  
> - 模板变量严格区分大小写，请使用 `{agent_id}` 而非 `{Agent_ID}`  
> - 若重启后问题依旧，请检查插件版本号并与文档支持版本对比。