ruflo-iot-cognitum 运维参考指南：Cognitum Seed 设备 5 级信任模型、工具目录与后台 Worker 调度

ruflo-iot-cognitum 运维参考指南：Cognitum Seed 设备 5 级信任模型、工具目录与后台 Worker 调度

【免费下载链接】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

导读

REFERENCE.md是 ruflo-iot-cognitum 插件面向运维的按需加载参考手册（Operations Reference），集中存放设备协调器 Agent 在 spawn 时按需读取的信任等级表、工具目录与后台 Worker 调度表。本篇指南以该参考文档为主体，结合插件源码（v3/@claude-flow/plugin-iot-cognitum/src下的生命周期服务、异常检测服务、6 个 Worker 与固件编排状态机）深入展开，帮助你理解：Cognitum Seed 设备的 5 级信任模型与 6 分量信任评分公式、完整的cognitum-iotCLI 工具目录、后台 Worker 的周期与事件语义，以及这套"Agent 提示词瘦身 + 参考文档外置"的 token 优化设计（对应 ADR-098）。

一、这份 Reference 是什么：Agent 提示词的"按需加载"搭档

1.1 设计动机：把表格从 Agent 提示词里搬出来

ruflo-iot-cognitum 插件的 Agent 提示词被刻意保持精简（≤ 60 行），依据是 ADR-098 Part 2（Plugin Capability Sync + Token Optimization）。该 ADR 的审计结论指出：ruflo-iot-cognitum的device-coordinator提示词曾因内联信任等级表达到约 80 行——每行约 12 token，每次 spawn 仅 Agent 定义就要消耗约 1000+ token，乘以 spawn 频率就是可观的运行时开销。

解决方案正是本文件：将信任等级表、工具目录、后台 Worker 调度表等"冷数据"外置到REFERENCE.md，Agent 只在真正需要执行某项操作时才读取该文件。device-coordinatorAgent 提示词中明确写道"完整的工具目录与后台 Worker 调度表位于 REFERENCE.md——当你需要职责之外的操作时读取它"，并标注该做法每次 spawn 节省约 40% token（见 device-coordinator.md）。

1.2 使用方式

• 人类运维：直接阅读本参考，掌握全部运维命令与调度语义；
• Agent 运行时：由device-coordinator、fleet-manager、telemetry-analyzer、witness-auditor四个 Agent 按需引用；
• 契约保障：冒烟脚本 的第 12 项检查要求REFERENCE.md存在且非空，确保参考文档不会因重构而丢失。

二、5 级信任模型（Trust Tiers）

2.1 等级表

设备从注册到获得完整舰队操作权限，共经历 5 个信任等级：

2.2 升降级规则

升级要求设备在全部 6 个信任分量上同时达到下一等级的下界；降级则是"单分量悬崖"机制——任意一个分量不达标（例如固件版本落后）即整体下降一个等级，直到缺陷修复为止。

2.3 源码级实现证据

等级枚举定义在 device-trust-level.ts：

export enum DeviceTrustLevel { UNKNOWN = 0, // Seen on the network but not paired REGISTERED = 1, // Paired, identity verified via Ed25519 PROVISIONED = 2, // Firmware verified, policies applied, security zone assigned CERTIFIED = 3, // Extended uptime, clean witness chain, anomaly-free history FLEET_TRUSTED = 4, // Fleet-level attestation across multiple devices }

注意源码中的枚举注释与参考文档的语义完全对应：REGISTERED意味着已配对且 Ed25519 身份验证通过；PROVISIONED意味着固件已验证、策略已应用、安全分区已分配——这与 CLI 命令中pair提升信任等级、unpair回退等级的行为一致。

分值到等级的映射实现在 device-lifecycle-service.ts 的evaluateTrustLevel()：

evaluateTrustLevel(score: DeviceTrustScore): DeviceTrustLevel { if (score.overall < 0.3) return DeviceTrustLevel.UNKNOWN; if (score.overall < 0.5) return DeviceTrustLevel.REGISTERED; if (score.overall < 0.7) return DeviceTrustLevel.PROVISIONED; if (score.overall < 0.85) return DeviceTrustLevel.CERTIFIED; return DeviceTrustLevel.FLEET_TRUSTED; }

一个值得注意的细节：CERTIFIED的临界值在参考文档中标注为 0.6–0.79，而源码中FLEET_TRUSTED的下界为0.85（而非 0.8）。也就是说，即使综合评分达到 0.8，若未超过 0.85，设备仍停留在CERTIFIED——这一阈值差异正是文档 2.2 节"必须达到下一等级下界"规则的量化体现。

三、信任评分公式逐分量拆解

3.1 完整公式

trustScore = 0.30 · pairingIntegrity # mTLS chain valid, expected fingerprint + 0.15 · firmwareCurrency # current firmware vs latest available + 0.20 · uptimeStability # rolling 24h uptime ratio + 0.15 · witnessIntegrity # Ed25519 chain has no gaps + 0.10 · anomalyHistory # 1.0 minus normalized anomaly count + 0.10 · meshParticipation # active edges in the mesh topology

3.2 各分量含义

3.3 关键失效场景：witness verify 失败

参考文档明确了一条硬规则：设备一旦witness verify失败，witnessIntegrity立即归零——该单点失败将设备综合评分上限封死在 0.85，必然从FLEET_TRUSTED强制降级。这与 2.2 节的"单分量悬崖"机制互为印证：witnessIntegrity权重 0.15，归零后理论最高分 = 1 − 0.15 = 0.85，恰好低于FLEET_TRUSTED的源码阈值 0.85（严格小于），因此必然被挡在最高等级之外。

3.4 源码中的评分实现

device-lifecycle-service.ts 的computeTrustScore()是公式的落地实现：

const pairingIntegrity = paired !== undefined ? (paired ? 1.0 : 0.0) : (device.trustScore?.components?.pairingIntegrity ?? 0.0); const firmwareCurrency = 1.0; // version comparison TBD const uptimeStability = Math.min(1.0, uptimeSecs / SEVEN_DAYS_SECS); // 604_800s const witnessIntegrity = Math.min(1.0, witnessDepth / EXPECTED_WITNESS_DEPTH); // 10_000 const anomalyHistory = 1.0; const meshParticipation = 0.5; const overall = 0.3 * pairingIntegrity + 0.15 * firmwareCurrency + 0.2 * uptimeStability + 0.15 * witnessIntegrity + 0.1 * anomalyHistory + 0.1 * meshParticipation;

实现细节可以印证文档公式：

• uptimeStability以 7 天（604,800 秒）为满额窗口计算uptime_secs / 604800并钳制到 1.0，对应文档"rolling 24h uptime ratio"的语义扩展（实现取 7 天窗口）；
• witnessIntegrity以见证链深度 10,000 为期望满额，min(1.0, witnessDepth / 10000)；
• pair成功后pairingIntegrity置 1.0，unpair后置 0.0——对应等级表中配对状态对能力门的直接控制；
• 从源码结构看，firmwareCurrency、anomalyHistory目前在服务中为占位常量（注释标明"version comparison TBD"、"No anomaly detection yet"），实际完整评估由固件编排与异常检测服务在 Worker 链路中承担，读者可据此判断当前版本的评分边界。

四、设备协调器工具目录（cognitum-iot CLI）

4.1 默认端点

未指定端点时，默认端点为http://169.254.42.1/——Cognitum Seed 的 link-local USB Ethernet 地址（USB-C 直连、免认证）。LAN 场景下则为https://169.254.42.1:8443（需要 bearer token 进行状态变更类操作）。

4.2 完整命令目录

# Lifecycle（生命周期） npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot register [endpoint] npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot pair <device-id> npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot unpair <device-id> npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot remove <device-id> # Inspection（巡检） npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot status <device-id> npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot list npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot mesh <device-id> # Witness audit（见证审计） npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot witness <device-id> npx -y -p @claude-flow/plugin-iot-cognitum@latest cognitum-iot witness verify <device-id>

4.3 完整的 25 个子命令面

在插件命令文件 commands/iot.md 中，/iot命令覆盖 25 个子命令主题，除上述生命周期/巡检/见证外，还包括：

query的--vector参数要求 JSON 数字数组，源码 cli-commands.ts 中parseVector()会严格校验：非数组或含非数字元素即抛错（--vector must be a JSON array of numbers），确保向量维度合法性后再执行 k-NN 搜索。

4.4 与 Agent/Skill 的协同

工具目录与 Agent 职责一一对应：device-coordinator负责生命周期与信任评分（对应 Skill iot-register），fleet-manager负责舰队与固件（对应 iot-fleet、iot-firmware），telemetry-analyzer负责异常分析（对应 iot-anomalies），witness-auditor负责见证链验证（对应 iot-witness-verify）。四个 Agent 的模型分层为：前三者为sonnet，witness-auditor为haiku（纯校验型任务，低成本模型即可胜任）。

五、后台 Worker 调度表

5.1 调度总览

插件被宿主守护进程加载后即派发 6 个后台 Worker，可通过ruflo hooks worker list与ruflo hooks worker status验证运行状态：

5.2 源码实现佐证

• HealthProbeWorker（health-probe-worker.ts）：默认intervalMs30,000，遍历coordinator.listDevices()逐台探测；维护lastKnownStatus状态表，仅在状态翻转时触发onDeviceOffline/onDeviceOnline回调（避免重复告警），探测异常统一走onProbeError。这就是iot:device-offline事件的产生源头。
• WitnessAuditWorker（witness-audit-worker.ts）：默认intervalMs600,000（10 分钟），按 epoch 升序排序后逐对检查entry[i].epoch === entry[i-1].epoch + 1，发现actual > expected即回调onGapDetected(deviceId, fromEpoch, toEpoch)——即iot:witness-gap事件，载荷为{ deviceId, fromEpoch, toEpoch }。
• 事件载荷汇总（来自 fleet-manager.md）：

5.3 见证链验证算法

witness-verification-service.ts 实现了见证链完整性评分：integrityScore = max(0, 1 − gapRatio) × (hashValid ? 1 : 0.5)，其中gapRatio为缺口 epoch 数占链长的比例，哈希链校验通过则乘 1、失败乘 0.5。整体流程为：拉取链 → 按 epoch 升序排序 → 检查 epoch 连续性 → 校验previous_hash链接 → 输出完整性评分与缺口报告。

六、与信任/异常/网格/固件相关的深度机制

6.1 异常检测：Z-score 复合评分

telemetry-analyzer采用min(1, meanZ/3)的复合评分，分类规则：

源码 anomaly-detection-service.ts 定义了三个关键阈值：anomalyThreshold（默认 0.7，高于此值判定为异常）、quarantineThreshold（默认 0.9，触发隔离动作）、baselineWindowSize（默认 100，基线计算窗口）。对应动作分级：score < 0.7 记录日志、0.7–0.9 告警、> 0.9 隔离。基线通过窗口内逐维度求均值与标准差（meanVector/stdVector）计算。

6.2 SONA 神经学习集成

sona-integration-service.ts 将异常模式以anomaly:{type}:{deviceId}键写入 SONA 模式库，供跨设备关联；漂移向量记录为baseline-shift:{deviceId}用于预测性维护；遥测轨迹以奖励式学习（异常为负、正常为正）。minConfidence默认 0.6，predictAnomalyRisk()在置信度超阈值时返回风险类型。

6.3 固件发布状态机

pending → canary → rolling → complete ↘ rolled-back ↙

• canary：部署到ceil(deviceCount × canaryPercentage/100)台设备；
• rolling：若 canary 阶段异常评分低于回滚阈值，则向其余设备铺开；
• rolled-back：异常阈值被突破或人工命令触发强制回滚。

源码 firmware-orchestration-service.ts 将状态机扩展为pending | canary | rolling | complete | rolled-back | failed六态，canary 数量取max(1, ceil(N × percentage))，回滚阈值与异常评分通过getDeviceAnomalyScore()动态评估。配套的舰队默认策略（来自 fleet-manager.md）：

6.4 网格与数据平面

MeshService 聚合 AP 状态、自动组网、集群健康与对端列表为拓扑快照；遥测向量经 agentdb-telemetry-repository.ts 持久化到 AgentDBiot-telemetry命名空间，HNSW 索引参数 M=16、efConstruction=200，支持 k-NN 相似度检索。

七、命名空间与生态关联

7.1 AgentDB 命名空间协调

插件持有 5 个 AgentDB 命名空间，全部符合 ruflo-agentdb ADR-0001 命名约定（<plugin-stem>-<intent>kebab-case）：

保留命名空间（pattern、claude-memories、default）不得被遮蔽。

7.2 与联邦信任模型的平行结构

本插件的 5 级设备信任模型（UNKNOWN → REGISTERED → PROVISIONED → CERTIFIED → FLEET_TRUSTED）与 ruflo-federation 5 级信任模型（UNTRUSTED → VERIFIED → ATTESTED → TRUSTED → PRIVILEGED）形态一致：评分驱动晋升、能力门控的原则相同，只是作用面不同（IoT 设备 vs 联邦对等节点）、命名不同。

7.3 安装与验证

# 安装插件 claude --plugin-dir plugins/ruflo-iot-cognitum # 契约验证（ADR-0001 定义的 smoke-as-contract 门禁，12 项结构检查） bash plugins/ruflo-iot-cognitum/scripts/smoke.sh # 预期输出: 12 passed, 0 failed

冒烟脚本 的 12 项检查覆盖：插件版本与关键词、5 技能 + 4 Agent + 1 命令存在性、/iot子命令主题、6 个 Worker 文档化、5 级信任模型、6 类异常类型、固件状态机、v3.6 CLI 版本锁定、命名空间协调、联邦信任模型交叉引用、ADR-0001 状态、REFERENCE.md非空——其中最后一项正是本文档的契约保障。

八、小结

REFERENCE.md通过"冷数据外置"策略，把运维表格从 Agent 提示词中剥离，配合 6 个后台 Worker 的事件驱动模型，形成了一套完整的 Cognitum Seed 设备治理闭环：注册发现（HealthProbe/注册）→ 信任评分（6 分量公式）→ 等级门控（5 级升降级）→ 遥测分析（Z-score + SONA）→ 固件演进（canary/rolling/rollback）→ 溯源审计（Ed25519 见证链）。运维人员可直接沿用本文档的工具目录与调度表进行设备舰队管理；开发者则可在v3/@claude-flow/plugin-iot-cognitum/src中找到每个表项对应的服务与 Worker 实现，作为深入定制与二次开发的起点。

【免费下载链接】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