Cognitum Seed 遥测异常检测实战：ruflo-iot-cognitum 的 iot-anomalies 技能与 Z-score 源码级解析

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）时。

技能元信息定义了其运行边界：

其中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-cognitum@latest cognitum-iot register

注册默认指向http://169.254.42.1/（USB-C link-local，免认证、只读）。若在 LAN 上使用 HTTPS，可在.env中配置认证：

COGNITUM_SEED_TOKEN=your-bearer-token-here # 可选覆盖项： COGNITUM_SEED_ENDPOINT=https://169.254.42.1:8443 # 设置了 token 后的默认端点 IOT_FLEET_ID=my-fleet IOT_ZONE_ID=zone-1 IOT_TLS_INSECURE=true # 接受自签名证书（默认 true）

CLI 会从当前目录向上查找.env，且不覆盖已存在的环境变量。设备注册后进入 5 级信任模型（UNKNOWN → REGISTERED → PROVISIONED → CERTIFIED → FLEET_TRUSTED），遥测摄入（telemetry ingest）能力要到PROVISIONED（0.4 分）及以上才开放，详见 REFERENCE.md。

三、技能执行步骤：一次完整的异常检测

SKILL.md 定义了四个执行步骤：

步骤 1：运行 Z-score 异常检测

npx -y -p @claude-flow/plugin-iot-cognitum@latest 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.ts（AnomalyDetectionService类），检测管线分为"基线计算"与"异常判定"两阶段。

4.1 基线计算：逐维度均值与标准差

computeBaseline(deviceId, readings)读取一个窗口内的历史遥测读数，对每个向量维度计算均值meanVector与标准差stdVector：

const mean = new Array<number>(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]);

基线以Map<deviceId, 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 建议隔离"的底层逻辑，并补充了中间档：

两个阈值可通过AnomalyDetectionConfig调整：anomalyThreshold默认 0.7，quarantineThreshold默认 0.9，baselineWindowSize默认 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 的成因说明，可汇总为下表：

其中flatline的判定在源码中要求同时满足两个条件：Z 分数全低（zScores.every(z => z < 0.5)）且原始指标全为 0（rawMetrics中每个值都等于 0）；spike判定优先于其他类型（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 清单：HealthProbeWorker（30s，事件iot:device-offline）、TelemetryIngestWorker（60s）、AnomalyScanWorker（120s，事件iot:anomaly-detected）、MeshSyncWorker（120s，事件iot:mesh-partition）、FirmwareWatchWorker（300s，事件iot:firmware-mismatch）、WitnessAuditWorker（600s，事件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 命名空间

异常检测结果通过 AgentDB（HNSW 向量索引）持久化，命名空间划分见 README.md：

命名遵循 ruflo-agentdb 的<plugin-stem>-<intent>kebab-case 约定；pattern、claude-memories、default等保留命名空间不可占用。SKILL.md 步骤 4 中通过mcp__plugin_ruflo-core_ruflo__memory_store写入的iot-anomalies命名空间正是该索引体系的一部分，实现"检测即学习"。

九、测试与验证

该技能的算法正确性由 239 个单元 + 集成测试守护，核心测试文件为 anomaly-detection-service.test.ts，覆盖：

• 基线计算：均值/标准差正确性、空读数抛错、单条读数（std=0）、按设备缓存；
• 检测判定：无基线时返回 0 分 +no-baseline元数据、基线附近读数不告警、远离基线读数分数 > 0.5、spike/flatline 分类、高分建议 quarantine、置信度随样本量线性增长；
• 阈值判断：isAnomalous在分数 ≥ 阈值时为 true。

插件级验证入口为 smoke.sh（预期输出12 passed, 0 failed），另有真实设备链式冒烟测试 full-plugin-smoke.mjs。

十、实操要点与最佳实践

1. 先建基线再检测：cognitum-iot baseline DEVICE_ID --compute可查看或重算基线。无基线时检测结果恒为 0 分（no-baseline），毫无判别力；基线样本量低于baselineWindowSize（默认 100）时置信度不足，应谨慎采信。
2. 按分数分档处置：< 0.7仅记录；0.7–0.9告警并复查；> 0.9按 SKILL.md 建议直接隔离，并结合固件回滚状态机（canary 阶段异常分数超阈即rolled-back）。
3. 每次检测后回写学习：用memory_store写入iot-anomaly-<device-id>，value 形如spike at 0.95，让 SONA 与 AgentDB 持续积累跨设备模式。
4. 结合信任分解读：异常历史权重仅 0.10，但它是信任分层降级（demotion）的触发因素之一；配合cognitum-iot status DEVICE_ID查看信任分与各分量，判断异常是孤立事件还是系统性信任下滑。

适用前提：以上命令与行为均以当前仓库所绑定的@claude-flow/plugin-iot-cognitum@latest为准，并需真实 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