Skill: strongking666/usage-monitor (version 2.0.0)

--- name: usage-monitor description: Monitor any service usage dashboard and alert when threshold is reached. User-configurable URL and threshold. metadata: { "openclaw": { "requires": { "bins": [] }, "install": [], }, } --- # Usage Monitor - 通用用量监控 Skill 通用的用量/配额监控 Skill，支持用户自定义监控面板 URL 和告警阈值。 ## 特性 - 🔗 **自定义 URL** - 支持任意用量/配额面板页面 URL（如：OpenClaw Token 面板、云服务用量页等） - 🎯 **自定义阈值** - 支持设置任意告警百分比（1-100） - 📊 **多维度监控** - 支持多个时间维度的用量数据 - 🔔 **主动提醒** - 达到阈值时自动发送消息 ## 快速开始 ### 步骤 1：配置用户参数 复制 `config.example.json` 为 `config.json` 并填写： ```json { "panelUrl": "你的用量面板页面 URL", "alertThreshold": 80, "serviceName": "服务名称（可选）", "checkIntervalHours": 4 } ``` ### 步骤 2：添加到 HEARTBEAT.md ```markdown - [ ] 检查服务用量 ``` ### 步骤 3：运行 ```bash node skills/usage-monitor/check.js ``` ## 配置参数说明 | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | `panelUrl` | string | ✅ | - | 用量面板页面 URL（从浏览器地址栏复制） | | `alertThreshold` | number | ✅ | 80 | 告警阈值百分比（1-100） | | `serviceName` | string | ❌ | "服务" | 服务名称，用于告警消息 | | `checkIntervalHours` | number | ❌ | 4 | 检查间隔（小时） | ## URL 获取方法 1. 打开你的用量/配额面板页面（如：OpenClaw Token 数量面板、云服务用量页等） 2. 复制浏览器地址栏的完整 URL 3. 粘贴到 `config.json` 的 `panelUrl` 字段 **URL 示例：** ``` https://example.com/usage/dashboard https://platform.example.com/token/quota ``` ## 告警消息示例 ``` ⚠️ 服务使用量提醒 📊 服务：OpenClaw Token 📈 当前用量：85% 📈 可用额度：15% ⏰ 剩余天数：30 天 🔗 查看：<你的面板 URL> 当前用量已达告警阈值（80%），请及时关注用量或考虑增加额度。 ``` ## 注意事项 1. URL 必须是完整的 HTTP/HTTPS 地址 2. 阈值范围 1-100 3. 浏览器自动化需要保持登录状态（如需要） 4. 首次使用需手动访问一次页面完成登录（如需要） ## 适用场景 - ✅ OpenClaw Token 数量监控 - ✅ 云服务用量监控（阿里云、AWS、腾讯云等） - ✅ API 调用配额监控 - ✅ 资源包用量监控 - ✅ 任何有用量/配额面板的场景

path: check.js
content: #!/usr/bin/env node

/**
 * Usage Monitor - 通用用量监控脚本
 * 
 * 特性:
 * - 用户自定义面板 URL
 * - 用户自定义告警阈值
 * - 支持多维度用量监控
 * 
 * 配置:
 * 复制 config.example.json 为 config.json 并填写你的配置
 */

const path = require('path');
const fs = require('fs');

// 脚本目录
const SCRIPT_DIR = __dirname;

// 配置文件路径
const CONFIG_PATH = path.join(SCRIPT_DIR, 'config.json');
const CONFIG_EXAMPLE_PATH = path.join(SCRIPT_DIR, 'config.example.json');
const USAGE_LOG_PATH = path.join(SCRIPT_DIR, 'usage-log.md');

// 默认配置
const DEFAULT_CONFIG = {
  panelUrl: 'https://example.com/usage',
  alertThreshold: 80,
  serviceName: '服务',
  checkIntervalHours: 4,
  remainingDays: 30,
};

/**
 * 加载用户配置
 * @returns {Object} 配置对象
 */
function loadConfig() {
  // 检查配置文件是否存在
  if (!fs.existsSync(CONFIG_PATH)) {
    console.error('❌ 配置文件不存在！');
    console.error('');
    console.error('请复制 config.example.json 为 config.json 并填写配置：');
    console.error('');
    console.error(`  cp "${CONFIG_EXAMPLE_PATH}" "${CONFIG_PATH}"`);
    console.error('');
    console.error('然后编辑 config.json，填写你的：');
    console.error('  - panelUrl: 用量面板页面 URL');
    console.error('  - alertThreshold: 告警阈值百分比 (1-100)');
    console.error('');
    process.exit(1);
  }

  try {
    const configContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
    const config = JSON.parse(configContent);
    
    // 合并默认配置
    return { ...DEFAULT_CONFIG, ...config };
  } catch (e) {
    console.error('❌ 配置文件解析失败！');
    console.error(`错误信息：${e.message}`);
    console.error('');
    console.error('请检查 config.json 格式是否正确。');
    process.exit(1);
  }
}

/**
 * 验证配置
 * @param {Object} config 配置对象
 * @returns {boolean} 是否有效
 */
function validateConfig(config) {
  const errors = [];

  // 验证 URL
  if (!config.panelUrl || typeof config.panelUrl !== 'string') {
    errors.push('panelUrl 必须是有效的字符串');
  } else if (!config.panelUrl.startsWith('http://') && !config.panelUrl.startsWith('https://')) {
    errors.push('panelUrl 必须以 http:// 或 https:// 开头');
  }

  // 验证阈值
  if (typeof config.alertThreshold !== 'number') {
    errors.push('alertThreshold 必须是数字');
  } else if (config.alertThreshold < 1 || config.alertThreshold > 100) {
    errors.push('alertThreshold 必须在 1-100 之间');
  }

  // 验证检查间隔
  if (typeof config.checkIntervalHours !== 'number') {
    errors.push('checkIntervalHours 必须是数字');
  } else if (config.checkIntervalHours < 1 || config.checkIntervalHours > 24) {
    errors.push('checkIntervalHours 必须在 1-24 之间');
  }

  if (errors.length > 0) {
    console.error('❌ 配置验证失败：');
    errors.forEach(err => console.error(`  - ${err}`));
    console.error('');
    console.error('请参考 config.example.json 修正配置。');
    return false;
  }

  return true;
}

/**
 * 读取用量日志
 * @returns {string} 日志内容
 */
function readUsageLog() {
  try {
    if (fs.existsSync(USAGE_LOG_PATH)) {
      return fs.readFileSync(USAGE_LOG_PATH, 'utf-8');
    }
  } catch (e) {
    // 忽略读取错误
  }
  return '';
}

/**
 * 更新用量日志
 * @param {Object} data 用量数据
 */
function updateUsageLog(data) {
  const today = new Date().toISOString().split('T')[0];
  const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
  
  let log = readUsageLog();
  
  if (!log) {
    // 创建新日志
    log = `# Usage Log

## Current Status (Last Updated: ${timestamp})

### Service Info
- **Service:** ${data.serviceName}
- **Status:** 正常
- **Remaining Days:** ${data.remainingDays}
- **Alert Threshold:** ${data.threshold}%

### Usage Tracking

| Date | Current | Notes |
|------|---------|-------|
| ${today} | ${data.current}% | Auto-check |

### Panel URL
${data.panelUrl}

---

## Monitoring Setup

- **Check Frequency:** Every ${data.checkIntervalHours} hours
- **Last Check:** ${timestamp}
`;
    fs.writeFileSync(USAGE_LOG_PATH, log);
    return;
  }
  
  // 添加新记录到表格
  const newLine = `| ${today} | ${data.current}% | Auto-check |`;
  
  if (!log.includes(`| ${today} |`)) {
    const tableRegex = /(\| Date \| Current \| Notes \|\n\|------\|---------\|-------\|)/;
    if (tableRegex.test(log)) {
      log = log.replace(tableRegex, `$1\n${newLine}`);
    }
  }
  
  // 更新最后检查时间
  log = log.replace(/Last Check:.*$/, `Last Check: ${timestamp}`);
  
  fs.writeFileSync(USAGE_LOG_PATH, log);
}

/**
 * 创建告警消息
 * @param {Object} data 用量数据
 * @returns {string} 告警消息
 */
function createAlertMessage(data) {
  return `⚠️ 服务使用量提醒

📊 服务：${data.serviceName}
📈 当前用量：${data.current}%
📈 可用额度：${100 - data.current}%
⏰ 剩余天数：${data.remainingDays} 天
🔗 查看：${data.panelUrl}

当前用量已达告警阈值（${data.threshold}%），请及时关注用量或考虑增加额度。`;
}

/**
 * 检查用量并返回结果
 * @param {Object} usageData 用量数据
 * @param {Object} config 配置
 * @returns {Object} 检查结果
 */
function checkUsage(usageData, config) {
  console.log('🔍 开始检查服务使用量...');
  console.log(`📋 告警阈值：${config.alertThreshold}%`);
  console.log(`📊 当前用量：${usageData.current}%`);
  console.log('');
  
  const alerts = [];
  
  if (usageData.current >= config.alertThreshold) {
    alerts.push(`当前用量已达 ${usageData.current}%`);
  }
  
  if (alerts.length > 0) {
    console.log('⚠️  触发告警：' + alerts.join(', '));
    return {
      alert: true,
      message: createAlertMessage({ 
        ...usageData, 
        threshold: config.alertThreshold,
        serviceName: config.serviceName,
        panelUrl: config.panelUrl,
        remainingDays: config.remainingDays,
      }),
      alerts,
    };
  } else {
    console.log('✅ 用量正常，未触发告警');
    return {
      alert: false,
      message: null,
      alerts: [],
    };
  }
}

/**
 * 显示使用说明
 */
function showUsage() {
  console.log('📝 使用流程（OpenClaw）:');
  console.log('');
  console.log('1. 配置参数:');
  console.log('   cp config.example.json config.json');
  console.log('   编辑 config.json，填写你的 URL 和阈值');
  console.log('');
  console.log('2. 通过 browser 工具访问用量面板页面:');
  console.log('   browser.open(config.panelUrl)');
  console.log('   browser.snapshot()');
  console.log('');
  console.log('3. 解析快照中的用量百分比数据');
  console.log('');
  console.log('4. 检查是否触发告警:');
  console.log('   const result = checkUsage(');
  console.log('     { current: 85 },');
  console.log('     config');
  console.log('   )');
  console.log('');
  console.log('5. 如有告警，发送消息:');
  console.log('   if (result.alert) {');
  console.log('     message.send(result.message)');
  console.log('   }');
  console.log('');
  console.log('6. 更新用量日志:');
  console.log('   updateUsageLog({');
  console.log('     current: 85,');
  console.log('     serviceName: config.serviceName,');
  console.log('     threshold: config.alertThreshold,');
  console.log('     panelUrl: config.panelUrl,');
  console.log('     checkIntervalHours: config.checkIntervalHours,');
  console.log('     remainingDays: config.remainingDays,');
  console.log('   })');
  console.log('');
}

/**
 * 主函数
 */
async function main() {
  console.log('╔════════════════════════════════════════════════════════╗');
  console.log('║          Usage Monitor - 通用用量监控工具              ║');
  console.log('╚════════════════════════════════════════════════════════╝');
  console.log('');
  
  // 加载配置
  const config = loadConfig();
  
  // 验证配置
  if (!validateConfig(config)) {
    process.exit(1);
  }
  
  console.log('✅ 配置加载成功！');
  console.log('');
  console.log('📋 当前配置:');
  console.log(`   用量面板 URL: ${config.panelUrl}`);
  console.log(`   告警阈值：${config.alertThreshold}%`);
  console.log(`   服务名称：${config.serviceName}`);
  console.log(`   检查间隔：每 ${config.checkIntervalHours} 小时`);
  console.log(`   剩余天数：${config.remainingDays} 天`);
  console.log('');
  
  // 显示使用说明
  showUsage();
  
  return {
    status: 'ready',
    message: '监控脚本已就绪，请按照上述流程使用',
    config: config,
  };
}

// 导出函数供外部调用
module.exports = { 
  loadConfig,
  validateConfig,
  checkUsage, 
  createAlertMessage, 
  updateUsageLog,
  showUsage,
  DEFAULT_CONFIG,
};

// 如果直接运行则执行 main
if (require.main === module) {
  main().catch(console.error);
}


path: config.example.json
content: {
  "$schema": "./config.schema.json",
  "_comment": "复制此文件为 config.json 并填写你的配置",
  
  "panelUrl": "https://example.com/usage/dashboard",
  "alertThreshold": 80,
  "serviceName": "服务名称",
  "checkIntervalHours": 4,
  "remainingDays": 30,
  
  "_notes": {
    "panelUrl": "从浏览器地址栏复制的用量面板 URL",
    "alertThreshold": "告警阈值百分比，1-100 之间的整数",
    "serviceName": "服务名称，用于告警消息显示",
    "checkIntervalHours": "检查间隔小时数",
    "remainingDays": "剩余额度天数"
  }
}


path: config.schema.json
content: {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Usage Monitor Configuration",
  "description": "用户配置参数 - 复制 config.example.json 为 config.json 并填写",
  "type": "object",
  "required": ["panelUrl", "alertThreshold"],
  "properties": {
    "panelUrl": {
      "type": "string",
      "format": "uri",
      "description": "用量面板页面 URL",
      "examples": [
        "https://platform.example.com/token/quota",
        "https://console.cloud.com/usage/dashboard"
      ],
      "minLength": 10
    },
    "alertThreshold": {
      "type": "integer",
      "description": "告警阈值百分比",
      "minimum": 1,
      "maximum": 100,
      "default": 80,
      "examples": [50, 70, 80, 90]
    },
    "serviceName": {
      "type": "string",
      "description": "服务名称",
      "default": "服务",
      "examples": ["OpenClaw Token", "云服务用量", "API 配额"]
    },
    "checkIntervalHours": {
      "type": "integer",
      "description": "检查间隔（小时）",
      "minimum": 1,
      "maximum": 24,
      "default": 4
    },
    "remainingDays": {
      "type": "integer",
      "description": "剩余额度天数（可选，用于告警消息）",
      "minimum": 0,
      "default": 30
    }
  },
  "additionalProperties": false
}


path: INSTALL.md
content: # 快速安装指南

## 3 分钟快速开始

### 1️⃣ 复制 Skill

```bash
# Windows PowerShell
Copy-Item -Recurse "D:\openclaw_self_skill\usage-monitor" "$env:USERPROFILE\.openclaw\workspace\skills\"
```

### 2️⃣ 配置参数

```bash
cd skills/usage-monitor
copy config.example.json config.json
notepad config.json
```

**必须填写的配置：**

```json
{
  "panelUrl": "从这里粘贴你的用量面板 URL",
  "alertThreshold": 80
}
```

### 3️⃣ 获取你的 URL

1. 打开浏览器，访问你的用量/配额面板页面（如：OpenClaw Token 数量面板）
2. **复制浏览器地址栏的完整 URL**
3. 粘贴到 `config.json` 的 `panelUrl` 字段

### 4️⃣ 测试运行

```bash
node check.js
```

看到 `✅ 配置加载成功！` 即表示配置正确。

### 5️⃣ 启用自动监控

编辑工作区的 `HEARTBEAT.md`，添加：

```markdown
- [ ] 检查服务用量
```

## 配置示例

### 示例 1：基础配置（80% 告警）

```json
{
  "panelUrl": "https://platform.example.com/token/quota",
  "alertThreshold": 80
}
```

### 示例 2：保守配置（50% 告警）

```json
{
  "panelUrl": "https://platform.example.com/token/quota",
  "alertThreshold": 50,
  "serviceName": "OpenClaw Token",
  "remainingDays": 30
}
```

### 示例 3：宽松配置（90% 告警）

```json
{
  "panelUrl": "https://console.cloud.com/usage/dashboard",
  "alertThreshold": 90,
  "checkIntervalHours": 6
}
```

## 常见问题

### Q: URL 从哪里复制？

**A:** 从浏览器地址栏复制！打开你的用量/配额面板页面，地址栏显示的就是你的专属 URL。

### Q: 阈值设置多少合适？

**A:** 
- 保守型：50-70%（提前预警）
- 标准型：80%（推荐）
- 宽松型：90-95%（接近用完再提醒）

### Q: 如何修改配置？

**A:** 直接编辑 `config.json`，保存后下次运行自动生效。

### Q: 可以监控多个用量页面吗？

**A:** 当前版本支持单个 URL。如需监控多个，可复制多份配置并分别运行。

## 下一步

配置完成后，参考 `README.md` 了解详细使用方法。

---

**需要帮助？** 查看 `README.md` 或 `SKILL.md`


path: README.md
content: # Usage Monitor Skill

> 通用的用量/配额监控 Skill - 支持任意服务用量面板监控

[![License: MIT-0](https://img.shields.io/badge/License-MIT--0-yellow.svg)](https://opensource.org/licenses/MIT-0)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skill-blue)](https://openclaw.ai)
[![ClawHub](https://img.shields.io/badge/ClawHub-available-green)](https://clawhub.ai/skills/usage-monitor)

## ✨ 特性

- 🔗 **自定义 URL** - 支持任意用量/配额面板页面 URL
- 🎯 **自定义阈值** - 支持设置任意告警百分比（1-100 可配置）
- 📊 **多维度监控** - 支持多个时间维度的用量数据
- 🔔 **主动提醒** - 达到阈值时自动发送消息
- 🔒 **隐私保护** - 所有配置本地存储

## 🚀 快速开始

### 安装

```bash
# 通过 ClawHub 安装
clawhub install usage-monitor

# 或手动安装
git clone https://github.com/YOUR_USERNAME/usage-monitor-skill.git
cp -r usage-monitor-skill ~/.openclaw/workspace/skills/
```

### 配置

```bash
cd skills/usage-monitor
cp config.example.json config.json
# 编辑 config.json 填写你的配置
```

### 使用

```bash
node check.js
```

## 📋 配置参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `panelUrl` | string | ✅ | - | 用量面板页面 URL |
| `alertThreshold` | number | ✅ | 80 | 告警阈值百分比（1-100） |
| `serviceName` | string | ❌ | "服务" | 服务名称 |
| `checkIntervalHours` | number | ❌ | 4 | 检查间隔（小时） |

## 🎯 适用场景

- ✅ OpenClaw Token 数量监控
- ✅ 云服务用量监控（阿里云、AWS、腾讯云等）
- ✅ API 调用配额监控
- ✅ 资源包用量监控
- ✅ 任何有用量百分比显示的面板

## 📖 文档

- [安装指南](INSTALL.md)
- [配置指南](USER-GUIDE.md)

## 📁 文件结构

```
usage-monitor/
├── SKILL.md              # Skill 定义
├── README.md             # 使用说明
├── INSTALL.md            # 快速安装指南
├── USER-GUIDE.md         # 配置指南
├── check.js              # 监控脚本
├── config.example.json   # 配置模板
├── config.schema.json    # 配置验证规则
└── usage-log.template.md # 用量日志模板
```

## 📄 许可证

MIT-0 License - 自由使用、修改和分发

---

**版本：** 2.0.0  
**最后更新：** 2026-03-15


path: usage-log.template.md
content: # Usage Log

> ⚠️ 此文件会在首次运行时自动创建，无需手动创建

## Current Status

- **Last Updated:** <自动填充>
- **Service:** <从 config.json 读取>
- **Alert Threshold:** <从 config.json 读取>%

## Usage History

| Date | Current | Notes |
|------|---------|-------|
| <自动填充> | <自动填充> | <自动填充> |

## Panel URL

<从 config.json 读取>

---

*此文件由监控脚本自动维护*


path: USER-GUIDE.md
content: # 用量监控 Skill v2.0 - 用户自定义配置指南

## 🎯 核心改进

### v1.0 vs v2.0 对比

| 功能 | v1.0 | v2.0 |
|------|------|------|
| 面板 URL | 硬编码（固定） | ✅ **用户自定义** |
| 告警阈值 | 硬编码 80% | ✅ **用户自定义 (1-100)** |
| 服务名称 | 硬编码 | ✅ **用户自定义** |
| 检查频率 | 固定 | ✅ **用户自定义** |
| 配置方式 | TOOLS.md | ✅ **独立 config.json** |

## 📝 用户需要填写什么？

用户只需填写 **2 个必填参数**：

### 1️⃣ panelUrl（必填）

**从哪里获取：**
1. 打开你的用量/配额面板页面（如：OpenClaw Token 数量面板、云服务用量页等）
2. **复制浏览器地址栏的完整 URL**

**示例：**
```json
{
  "panelUrl": "https://platform.example.com/token/quota"
}
```

**注意：** 每个用户的 URL 可能不同（包含用户特定的参数），所以必须由用户自己提供。

### 2️⃣ alertThreshold（必填）

**设置你的告警阈值百分比（1-100 的整数）**

**示例：**
```json
{
  "alertThreshold": 50   // 50% 时告警（保守）
}
```

```json
{
  "alertThreshold": 80   // 80% 时告警（推荐）
}
```

```json
{
  "alertThreshold": 95   // 95% 时告警（宽松）
}
```

## 📋 完整配置示例

### 最小配置（仅必填项）

```json
{
  "panelUrl": "你的用量面板页面 URL",
  "alertThreshold": 80
}
```

### 推荐配置（包含可选参数）

```json
{
  "panelUrl": "https://platform.example.com/token/quota",
  "alertThreshold": 80,
  "serviceName": "OpenClaw Token",
  "checkIntervalHours": 4,
  "remainingDays": 30
}
```

## 🔧 安装步骤

### 步骤 1：复制 Skill

```bash
# Windows PowerShell
Copy-Item -Recurse "D:\openclaw_self_skill\usage-monitor" "$env:USERPROFILE\.openclaw\workspace\skills\"
```

### 步骤 2：创建配置

```bash
cd skills/usage-monitor
copy config.example.json config.json
```

### 步骤 3：编辑配置

用文本编辑器打开 `config.json`，填写：

```json
{
  "panelUrl": "从这里粘贴你的 URL",
  "alertThreshold": 80
}
```

### 步骤 4：测试运行

```bash
node check.js
```

看到 `✅ 配置加载成功！` 即表示配置正确。

## ❓ 常见问题

### Q: 为什么 URL 不能固定？

**A:** 用量面板的 URL 可能包含用户特定的参数（如工作区 ID、地域等），每个用户的 URL 都不同。硬编码会导致其他用户无法使用。

### Q: 阈值为什么让用户自己设置？

**A:** 不同用户有不同的使用习惯：
- 保守型用户希望 50% 就告警
- 标准用户希望 80% 告警
- 宽松用户希望 90% 以上再告警

让用户自己选择更灵活。

### Q: 配置错了怎么办？

**A:** 直接编辑 `config.json`，保存后下次运行自动生效。脚本会自动验证配置格式。

### Q: 可以多人共用这个 Skill 吗？

**A:** 可以！Skill 本身（check.js 等）是通用的，每个人只需创建自己的 `config.json` 填写个人配置即可。

## 🔒 隐私保护

- ✅ `config.json` 包含个人 URL，**不要分享给他人**
- ✅ `usage-log.md` 包含用量数据，**不要上传到公开仓库**
- ✅ Skill 代码（check.js 等）可以安全分享
- ✅ `.gitignore` 已配置，自动忽略敏感文件

## 📁 文件说明

| 文件 | 是否包含个人信息 | 是否可以分享 |
|------|-----------------|-------------|
| `check.js` | ❌ 否 | ✅ 可以 |
| `SKILL.md` | ❌ 否 | ✅ 可以 |
| `README.md` | ❌ 否 | ✅ 可以 |
| `config.example.json` | ❌ 否（模板） | ✅ 可以 |
| `config.json` | ✅ 是（用户创建） | ❌ 不要分享 |
| `usage-log.md` | ✅ 是（运行时创建） | ❌ 不要分享 |

## 🎯 适用场景

本 Skill 可用于监控任何有用量/配额面板的服务：

- ✅ OpenClaw Token 数量监控
- ✅ 云服务用量监控（阿里云、AWS、腾讯云等）
- ✅ API 调用配额监控
- ✅ 资源包用量监控
- ✅ 订阅套餐用量监控
- ✅ 任何有用量百分比显示的面板

---

**版本：** 2.0.0  
**更新日期：** 2026-03-15


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)