水质监测因子时间序列预测插件

插件简介

基于历史水质监测数据，使用多种时间序列预测算法（ARIMA、指数平滑、线性回归、移动平均）对水质因子浓度进行预测。支持溶解氧(DO)、总氮(TN)、氨氮(NH3-N)、化学需氧量(COD)、高锰酸盐指数(CODMn)、总磷(TP)、pH值等多种水质因子，提供多步预测和置信区间输出。

适用场景

• 水质监测站点数据趋势预测
• 水质预警和风险评估
• 环境质量评价报告编制
• 水污染防治决策支持
• 多算法对比和模型选择

目录结构

water-quality-forecast/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 项目配置
├── README.md                    # 本文档
├── SKILL.md                     # 技能说明（兜底入口）
├── src/
│   ├── schemas/
│   │   └── config.schema.js     # 配置和输入 Schema
│   └── shared/
│       ├── water-quality-forecast.executor.js  # 核心预测逻辑
│       └── water-quality-forecast.types.js     # 类型定义
├── resources/
│   └── skills/
│       └── water-quality-forecast/
│           └── SKILL.md         # 平台可发现的 Skill 资源
├── scripts/
│   ├── sdk-shim.js              # SDK 兼容层
│   ├── check-plugin.js          # 自检脚本
│   ├── run-skill.js             # Skill 运行脚本
│   ├── invoke-tool.js           # 工具调用脚本
│   └── package-zip.js           # zip 打包脚本
└── examples/
    └── skill-input.example.json # 示例输入

安装和使用

1. 安装依赖

npm install

2. 运行自检

npm run check

3. 运行示例

# 使用示例文件运行预测
npm run skill:run

# 或指定输入文件
node scripts/run-skill.js examples/skill-input.example.json

# 调用工具
npm run tool:invoke

4. 发布安装

npm 方式（默认）

# 发布到 npm
npm publish --access public --registry https://registry.npmjs.org/

# 在 XpertAI 平台安装
# 通过平台 API 调用 /api/plugin 接口

zip 方式

# 打包为 zip
npm run package:zip

# 上传到 XpertAI 平台
# 通过平台 API 调用 /api/plugin/archive 接口

配置项说明

插件支持以下运行时配置（通过 createMiddleware(options) 传入）：

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | defaultAlgorithm | string | arima | 默认预测算法 | | defaultForecastSteps | number | 7 | 默认预测步数 | | defaultConfidenceLevel | number | 0.95 | 默认置信水平 | | maxHistoricalPoints | number | 10000 | 最大历史数据点数 | | minHistoricalPoints | number | 3 | 最小历史数据点数 |

Agent Middleware 工具列表

1. water_quality_forecast

功能: 水质因子时间序列预测

输入参数:

• factor (string, 必填): 水质因子名称（DO/TN/NH3-N/COD/CODMn/TP/pH等）
• historicalData (array, 必填): 历史数据数组，至少 3 个点
• forecastSteps (number, 可选): 预测步数，默认 7
• algorithm (string, 可选): 预测算法，默认 arima
• confidenceLevel (number, 可选): 置信水平，默认 0.95

输出:

• predictions: 预测值数组（含时间戳、预测值、置信区间）
• modelMetrics: 模型评估指标（MAE/RMSE/MAPE）
• algorithm: 使用的算法
• factor: 水质因子名称

2. water_quality_forecast_compare

功能: 多算法对比预测

输入参数:

• factor (string, 必填): 水质因子名称
• historicalData (array, 必填): 历史数据数组，至少 5 个点
• forecastSteps (number, 可选): 预测步数，默认 7
• algorithms (array, 可选): 要对比的算法列表
• confidenceLevel (number, 可选): 置信水平，默认 0.95

输出:

• 各算法的预测结果和评估指标
• bestAlgorithm: 推荐的最优算法（按 RMSE）

Skill 兜底运行说明

当平台无法直接调用 Agent Middleware Tool 时，可通过 Skill 间接运行：

何时使用 SKILL.md

• 插件安装后 skills、mcpServers、apps 显示为空
• 智能体编排中未出现中间件工具
• 需要本地测试或调试预测逻辑

运行步骤

1. 准备输入 JSON 文件（参考 examples/skill-input.example.json）
2. 执行命令：

   node scripts/run-skill.js examples/skill-input.example.json

3. 查看输出的 JSON 结果
4. 如需调用特定工具：

   node scripts/invoke-tool.js water_quality_forecast examples/skill-input.example.json

输入输出映射

Skill 输入 JSON 与工具输入参数完全一致，Skill 脚本内部调用同一个 executeForecast() 函数，确保结果一致。

scripts 目录说明

| 脚本 | 用途 | 命令示例 | |------|------|----------| | sdk-shim.js | SDK 兼容层，本地缺少宿主 SDK 时提供 mock | 自动加载 | | check-plugin.js | 自检脚本，验证插件结构和导出 | npm run check | | run-skill.js | Skill 运行脚本，执行预测逻辑 | npm run skill:run | | invoke-tool.js | 工具调用脚本，调用 middleware tool | npm run tool:invoke | | package-zip.js | zip 打包脚本，生成可上传的 zip 文件 | npm run package:zip |

版本与 API 兼容说明

• Node.js: 20+
• @langchain/core: ^0.3.70（使用 tool() 函数）
• @nestjs/common: ^10.0.0
• reflect-metadata: ^0.2.0
• zod: ^3.23.0（v3 兼容写法）
• @xpert-ai/plugin-sdk: ^3.14.0（peerDependency，由平台宿主提供）

本地开发和自检时，scripts/sdk-shim.js 会 mock @xpert-ai/plugin-sdk 的关键导出，避免 MODULE_NOT_FOUND 错误。

首次运行顺序

1. npm install - 安装依赖
2. npm run check - 运行自检，确保所有检查通过
3. 根据安装方式执行：
   • npm: npm publish 后通过平台 API 安装
   • zip: npm run package:zip 后通过平台 API 上传

禁止跳过自检直接发布或上传！

入参说明

historicalData 格式

[
  { "timestamp": "2024-06-01T08:00:00Z", "value": 7.2 },
  { "timestamp": "2024-06-02T08:00:00Z", "value": 7.5 }
]

• timestamp: ISO 8601 格式时间戳
• value: 浓度值（数值类型）
• 数据点按时间升序排列
• 至少 3 个数据点（推荐 10+ 个以获得更好的预测效果）

支持的水质因子

DO（溶解氧）、TN（总氮）、NH3-N（氨氮）、COD（化学需氧量）、CODMn（高锰酸盐指数）、TP（总磷）、pH、BOD5、氟化物、硒、砷、汞、镉、六价铬、铅、铜、锌、氰化物、挥发酚、阴离子表面活性剂、硫化物、粪大肠菌群等。

返回值说明

predictions 数组

每个预测点包含：

• timestamp: 预测时间戳（ISO 8601）
• value: 预测浓度值
• lowerBound: 置信区间下界
• upperBound: 置信区间上界

modelMetrics 对象

• mae: 平均绝对误差（Mean Absolute Error）
• rmse: 均方根误差（Root Mean Square Error）
• mape: 平均绝对百分比误差（%）

调用示例

示例 1: 预测溶解氧未来 7 天

node scripts/run-skill.js examples/skill-input.example.json

示例 2: 使用线性回归预测总氮

{
  "factor": "TN",
  "historicalData": [
    { "timestamp": "2024-01-01T00:00:00Z", "value": 1.2 },
    { "timestamp": "2024-01-02T00:00:00Z", "value": 1.5 },
    { "timestamp": "2024-01-03T00:00:00Z", "value": 1.3 },
    { "timestamp": "2024-01-04T00:00:00Z", "value": 1.8 },
    { "timestamp": "2024-01-05T00:00:00Z", "value": 1.6 }
  ],
  "forecastSteps": 3,
  "algorithm": "linear_regression"
}

示例 3: 多算法对比

node scripts/invoke-tool.js water_quality_forecast_compare examples/skill-input.example.json

常见错误和处理方式

| 错误 | 原因 | 解决方法 | |------|------|----------| | 历史数据不足 | 数据点少于 3 个 | 提供至少 3 个历史数据点 | | 无效的数据值 | value 字段非数值 | 检查并修正数据格式 | | 缺少必要参数 | factor 或 historicalData 缺失 | 补齐必填字段 | | MODULE_NOT_FOUND | 缺少依赖或 SDK | 运行 npm install，本地脚本会自动使用 sdk-shim |

安全注意事项

1. 预测结果仅供参考：不应作为环境决策的唯一依据
2. 置信区间估计：基于历史数据残差，实际误差可能更大
3. 极端事件：对于突发污染等极端事件，模型预测能力有限
4. 综合评估：建议结合专业判断和其他监测手段
5. 数据质量：预测效果依赖于历史数据的质量和代表性

技术实现说明

算法实现

所有预测算法均为纯 JavaScript 实现，无外部依赖：

• ARIMA(1,1,0): 一阶差分后拟合 AR(1) 模型，使用自协方差估计参数
• Holt 线性趋势指数平滑: 双参数指数平滑，捕捉趋势成分
• 线性回归: 最小二乘法拟合直线
• 移动平均: 滑动窗口平均值

置信区间计算

• 使用留一交叉验证估计残差标准差
• 根据置信水平选择 z-score（0.95 → 1.96）
• 置信区间随预测步长逐渐扩大

模型评估

• 使用最后 30% 数据进行留一验证
• 计算 MAE、RMSE、MAPE 三个指标
• MAPE 排除实际值为 0 的点

下一步

在 http://10.161.48.53:3300 使用插件：

1. 登录平台
2. 进入插件管理页面，确认插件已安装
3. 在智能体编排中添加"水质监测因子时间序列预测中间件"
4. 配置默认参数（可选）
5. 在对话中调用 water_quality_forecast 或 water_quality_forecast_compare 工具