Cognitum Seed 遥测异常检测实战ruflo-iot-cognitum 的 iot-anomalies 技能与 Z-score 源码级解析【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本文以 ruflo 仓库中 iot-anomalies 技能 为骨架完整讲解如何在 Cognitum Seed 物联网设备上执行基于 Z-score 的遥测异常检测从技能调用方式、六类异常分类、0.7/0.9 双阈值处置策略到底层 anomaly-detection-service.ts 的实现原理与后台扫描 worker 的调度机制。读完本文你将掌握一条从设备上报异常指标到分类 → 打分 → 隔离建议 → 模式学习回写的完整可落地流水线并能独立读懂并复现该插件的异常检测测试用例。一、iot-anomalies 技能是什么iot-anomalies是 ruflo-iot-cognitum 插件 提供的五个技能之一其余为iot-register、iot-fleet、iot-firmware、iot-witness-verify。它的定位非常聚焦对单个 Cognitum Seed 设备最近一段时间的遥测数据执行 Z-score 异常检测并给出分类、分数与处置建议。按照 SKILL.md 的 frontmatter该技能的设计意图是当某个设备上报的指标看起来异常odd metrics时在批准一次固件金丝雀canary版本推进之前或在排查全舰队健康告警fleet-wide health alerts时。技能元信息定义了其运行边界字段值nameiot-anomaliesallowed-toolsBash(npx *)、mcp__plugin_ruflo-core_ruflo__memory_store、Readargument-hintdevice-id其中allowed-tools很关键该技能只允许通过npx执行 CLI、通过 ruflo-core 的 memory_store MCP 工具写入学习模式以及只读操作——这保证了技能在 Agent 上下文中是只读检测 结果落库的安全行为。二、前置条件与设备接入该技能依赖真实硬件Cognitum Seed——一款具备板载向量库、Ed25519 加密身份、OTA 固件升级、Mesh 组网与见证链witness chain的 edge 设备。在运行异常检测前设备需要先完成注册# 安装插件在仓库内以插件目录方式加载 claude --plugin-dir plugins/ruflo-iot-cognitum # 注册设备默认端点即 Seed 的 link-local USB 以太网地址 npx -y -p claude-flow/plugin-iot-cognitumlatest cognitum-iot register注册默认指向http://169.254.42.1/USB-C link-local免认证、只读。若在 LAN 上使用 HTTPS可在.env中配置认证COGNITUM_SEED_TOKENyour-bearer-token-here # 可选覆盖项 COGNITUM_SEED_ENDPOINThttps://169.254.42.1:8443 # 设置了 token 后的默认端点 IOT_FLEET_IDmy-fleet IOT_ZONE_IDzone-1 IOT_TLS_INSECUREtrue # 接受自签名证书默认 trueCLI 会从当前目录向上查找.env且不覆盖已存在的环境变量。设备注册后进入 5 级信任模型UNKNOWN → REGISTERED → PROVISIONED → CERTIFIED → FLEET_TRUSTED遥测摄入telemetry ingest能力要到PROVISIONED0.4 分及以上才开放详见 REFERENCE.md。三、技能执行步骤一次完整的异常检测SKILL.md 定义了四个执行步骤步骤 1运行 Z-score 异常检测npx -y -p claude-flow/plugin-iot-cognitumlatest cognitum-iot anomalies DEVICE_ID该命令的完整形式为anomalies device-id与插件其他子命令风格一致完整 25 个子命令清单见 commands/iot.md 与 README.md。步骤 2审查检测出的异常类型检测结果会标注六种类型之一spike尖峰、flatline平线、drift漂移、oscillation振荡、pattern-break模式断裂、cluster-outlier簇外点。各类型的判定规则与典型成因见下文第四节。步骤 3分数 0.9 时建议隔离quarantine步骤 4将异常模式存入学习库mcp__plugin_ruflo-core_ruflo__memory_store({ key: iot-anomaly-DEVICEID, value: TYPE at SCORE, namespace: iot-anomalies })这一步将异常类型分数写入iot-anomalies命名空间供后续跨设备关联与预测性维护使用。四、Z-score 检测算法源码剖析技能的算法核心位于 anomaly-detection-service.tsAnomalyDetectionService类检测管线分为基线计算与异常判定两阶段。4.1 基线计算逐维度均值与标准差computeBaseline(deviceId, readings)读取一个窗口内的历史遥测读数对每个向量维度计算均值meanVector与标准差stdVectorconst mean new Arraynumber(dim).fill(0); for (const r of readings) { for (let i 0; i dim; i) mean[i] r.vector[i] / n; } // ... for (let i 0; i dim; i) std[i] Math.sqrt(std[i]);基线以MapdeviceId, TelemetryBaseline缓存在服务实例内getBaseline(deviceId)可随时取回。若对空读数计算基线会直接抛出Cannot compute baseline from empty readings。4.2 异常判定Z-score 合成打分对每条新读数逐维度计算 Z-score偏离基线的标准差倍数const zScores reading.vector.map((v, i) { const s baseline.stdVector[i]; return s 0 ? Math.abs(v - baseline.meanVector[i]) / s : 0; }); const maxZ Math.max(...zScores); const meanZ zScores.reduce((a, b) a b, 0) / zScores.length; const score Math.min(1, meanZ / 3);核心公式为score min(1, meanZ / 3)平均 Z 值达到 3 个标准差时分数即封顶为 1.0。这一复合打分同时考虑了多维度整体偏移meanZ与单维度极端偏移maxZ。若设备尚无基线detect()返回score: 0, type: drift, suggestedAction: log并附带metadata: { reason: no-baseline }——这正是 测试用例 中returns score 0 with no-baseline metadata所验证的行为。4.3 双阈值处置策略suggestAction(score)实现了技能文档中分数 0.9 建议隔离的底层逻辑并补充了中间档分数区间建议动作含义score 0.7log仅记录不告警0.7 ≤ score 0.9alert触发告警score ≥ 0.9quarantine建议隔离设备两个阈值可通过AnomalyDetectionConfig调整anomalyThreshold默认 0.7quarantineThreshold默认 0.9baselineWindowSize默认 100用于置信度归一。4.4 置信度随基线样本量增长const confidence Math.min(1, baseline.sampleCount / this.config.baselineWindowSize);置信度 min(1, 基线样本数 / baselineWindowSize)。测试confidence scales with sample count验证了窗口 100 时仅用 10 条样本置信度恰好为 0.1。这说明早期基线置信度低时检测结果更应人工复核。五、六类异常的分类规则与成因分类逻辑位于classifyAnomaly(reading, zScores, maxZ)结合 telemetry-analyzer Agent 的成因说明可汇总为下表类型判定规则典型成因spikemaxZ 5传感器瞬时故障flatline所有维度 Z 0.5 且所有原始指标为 0传感器断开drift高 Z 维度数为 1–2 个渐进式校准丢失oscillation高/低值交替出现反馈回路振荡pattern-break中等 Z、多维度环境突变cluster-outlier高 Z 维度占比 50%多传感器同时失效其中flatline的判定在源码中要求同时满足两个条件Z 分数全低zScores.every(z z 0.5)且原始指标全为 0rawMetrics中每个值都等于 0spike判定优先于其他类型maxZ 5直接短路。这些规则均被 anomaly-detection-service.test.ts 覆盖例如classifies spike when maxZ 5与classifies flatline when all metrics are zero。遥测读数的数据模型见 telemetry.ts每条TelemetryReading包含readingId、deviceId、fleetId、时间戳、用于相似检索的vector嵌入向量、rawMetrics原始传感器指标、anomalyScore与metadata检测结果AnomalyDetection则额外携带type、confidence、baselinePattern与suggestedAction。注意AnomalyAction枚举还定义了recalibrate、rollback-firmware、human-review三种动作为后续处置扩展预留了空间。六、后台扫描AnomalyScanWorker除按需手动执行外异常检测还由后台 worker 周期性驱动。anomaly-scan-worker.ts 的AnomalyScanWorker每 300 秒构造参数intervalMs默认值插件 README 中按 120s 调度遍历已注册设备刷新信任分若trustScore.overall 0.5则触发onAnomalyDetected回调。REFERENCE.md 给出了完整 worker 清单HealthProbeWorker30s事件iot:device-offline、TelemetryIngestWorker60s、AnomalyScanWorker120s事件iot:anomaly-detected、MeshSyncWorker120s事件iot:mesh-partition、FirmwareWatchWorker300s事件iot:firmware-mismatch、WitnessAuditWorker600s事件iot:witness-gap。这些 worker 由宿主守护进程在插件加载时调度可通过ruflo hooks worker list与ruflo hooks worker status验证运行状态。七、异常检测与信任分、固件发布的联动异常检测不是孤立的它深度嵌入设备信任评估与固件发布流程信任分联动信任分公式见 REFERENCE.md中anomalyHistory占 0.10 权重定义为1.0 减去归一化异常计数trustScore 0.30 · pairingIntegrity # mTLS 链有效、指纹匹配 0.15 · firmwareCurrency # 当前固件 vs 最新可用 0.20 · uptimeStability # 滚动 24h 在线率 0.15 · witnessIntegrity # Ed25519 链无缺口 0.10 · anomalyHistory # 1.0 减去归一化异常计数 0.10 · meshParticipation # mesh 拓扑中的活跃边异常频发的设备会拉低anomalyHistory进而影响其信任层级而信任分又决定设备的操作权限如CERTIFIED及以上才允许固件部署。固件金丝雀联动README 中的固件发布状态机为pending → canary → rolling → complete其中canary 阶段部署到ceil(deviceCount × canaryPercentage/100)台设备后若 canary 阶段的异常分数超过回滚阈值则强制回滚rolled-back。这正是 SKILL.md 中在批准固件 canary 推进前先跑异常检测的完整闭环异常检测充当了固件灰度发布的守门员。SONA 神经网络联动见 telemetry-analyzer.md异常模式以anomaly:{type}:{deviceId}形式馈入 SONA 做跨设备关联漂移向量用于预测性维护遥测轨迹用于强化学习异常 负奖励正常 正奖励predictAnomalyRisk()在风险超阈值时返回风险类型与置信度。八、结果持久化AgentDB 命名空间异常检测结果通过 AgentDBHNSW 向量索引持久化命名空间划分见 README.md命名空间用途iot-devices每台 Seed 的信任历史iot-telemetry遥测向量HNSWM16, efConstruction200iot-telemetry-anomalies按类型 处置动作标记的异常iot-anomalies技能级异常索引上者的别名iot-audit见证链缺口记录命名遵循 ruflo-agentdb 的plugin-stem-intentkebab-case 约定pattern、claude-memories、default等保留命名空间不可占用。SKILL.md 步骤 4 中通过mcp__plugin_ruflo-core_ruflo__memory_store写入的iot-anomalies命名空间正是该索引体系的一部分实现检测即学习。九、测试与验证该技能的算法正确性由 239 个单元 集成测试守护核心测试文件为 anomaly-detection-service.test.ts覆盖基线计算均值/标准差正确性、空读数抛错、单条读数std0、按设备缓存检测判定无基线时返回 0 分 no-baseline元数据、基线附近读数不告警、远离基线读数分数 0.5、spike/flatline 分类、高分建议 quarantine、置信度随样本量线性增长阈值判断isAnomalous在分数 ≥ 阈值时为 true。插件级验证入口为 smoke.sh预期输出12 passed, 0 failed另有真实设备链式冒烟测试 full-plugin-smoke.mjs。十、实操要点与最佳实践先建基线再检测cognitum-iot baseline DEVICE_ID --compute可查看或重算基线。无基线时检测结果恒为 0 分no-baseline毫无判别力基线样本量低于baselineWindowSize默认 100时置信度不足应谨慎采信。按分数分档处置 0.7仅记录0.7–0.9告警并复查 0.9按 SKILL.md 建议直接隔离并结合固件回滚状态机canary 阶段异常分数超阈即rolled-back。每次检测后回写学习用memory_store写入iot-anomaly-device-idvalue 形如spike at 0.95让 SONA 与 AgentDB 持续积累跨设备模式。结合信任分解读异常历史权重仅 0.10但它是信任分层降级demotion的触发因素之一配合cognitum-iot status DEVICE_ID查看信任分与各分量判断异常是孤立事件还是系统性信任下滑。适用前提以上命令与行为均以当前仓库所绑定的claude-flow/plugin-iot-cognitumlatest为准并需真实 Cognitum Seed 设备或通过SEED_ENDPOINT指向的测试端点才能产生有效遥测数据仅安装插件而无可达设备时anomalies命令将无法返回有意义的检测结果。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考