EAN 2.0 edgeCore ↔ EdgeOS 改造指南

文档版本: 1.12
日期: 2026-08-04
适用范围: edgeCore Capability Runtime（本仓库）与 EdgeOS Coordination Platform（对端必须实现）
协议基线: edgeCore通信协议规范(MQTT-NATS).md 规划基线: AI协同组件规划.md 迁移评估: V1-to-EAN-Migration-Assessment.md

1. 背景与目标

1.1 背景

Edge Agent Network（EAN）2.0 在现有 edgeCore + EdgeOS 架构上增加统一 Agent 协作层：

• edgeCore：Capability Runtime（能力注册、发现发布、Invoke 执行、Event 上报）
• EdgeOS：Coordination Platform（全局发现索引、跨节点编排、Invoke 发起、Event 订阅与规则）

协议层统一为：Agent / Capability / Discovery / Invoke / Event，传输同时支持 MQTT 与 NATS，MQTT Topic 使用 $edgeos/... 斜杠形式，NATS Subject 映射为对应点分形式（/→.、+→*、#→>）。

1.2 本轮目标（已落地）

1.3 非目标

• 不替换 V1.0 edgeCore/*（MQTT）与 edgeCore.*（NATS）兼容层
• AI 产出仍须 Human-in-the-loop 确认后落库（禁止自动写 config）
• AI Invoke 不得进入 ScanEngine / Pipeline Worker 热路径

2. edgeCore 侧已实现能力总览

2.1 模块地图

MQTT/NATS/MCP/HTTP
        │
        ▼
 Capability Runtime          internal/capability/
   ├─ Registry               registry.go / generator.go
   ├─ Invoke Dispatcher      dispatcher.go
   ├─ Discovery Publisher    discovery_publisher.go
   └─ Event Publisher        event_publisher.go
        │
        ▼
 CapabilityMapper            internal/execution/capability_mapper.go
        │
        ├─ DriverExecutor    internal/execution/driver_executor.go
        │     └─ Southbound (Shadow / Driver / Scan)
        └─ AIAdapter         internal/execution/ai_adapter.go
              └─ ai_agent.Agent（协议逆向 / 文档解析流水线）
        │
        ▼
 ShadowCore (COW)            internal/core/shadow_*.go
        │ notify(delta + previous_value)
        ▼
 ShadowEventBridge           internal/capability/shadow_events.go
        │
        ▼
 MQTT / NATS Event topics

2.2 关键代码路径

Shadow→Event 的 EventPublisher 列表在 EAN Runtime 启停/连接生命周期刷新（SetOnEANRuntimeChanged → refreshEANEventPublishers），不在每次 Shadow delta 热路径上刷新。通知回调同步执行；若北向管理器正在持写锁则延迟阻塞刷新，避免死锁并消除异步窗口内仍用旧 publisher 列表的竞态。

2.3 EAN Topic / Subject（MQTT 斜杠 Topic / NATS 点分 Subject）

NATS 侧将 / 映射为 .（点分 Subject）：$edgeos/discovery/agent → $edgeos.discovery.agent；通配符 +→*、#→>。与 MQTT 斜杠 Topic 语义一一对应。V1.0 NATS 仍用 edgeCore.*。

2.4 默认 Capability 清单（edgeCore 自动注册）

MCP Runtime（统一模式，7 条）：

北向 EAN Runtime（协议特定模式，63 条）：15 协议 × 4 操作 + 3 系统/AI，Capability ID 格式 {protocol}.read_point（读单个数据）/ {protocol}.write_point（写单个数据）/ {protocol}.scan_devices / {protocol}.list_points。中性命名（v1.12）：所有协议统一用 read_point/write_point，不再用 Modbus 专属的 read_holding_register/write_register（对 Ethernet/IP、PROFINET 等无”保持寄存器”概念的协议语义统一）。协议集合见 KnownDriverProtocols（modbus-tcp、modbus-rtu、opc-ua、bacnet-ip、s7 等 15 种）。

2.5 Invoke 流程

1. EdgeOS 向 $edgeos/invoke/{agent_id} 发布 invoke_capability 信封
2. edgeCore Runtime 校验 target / Capability / 权限
3. CapabilityMapper → DriverCommand
4. DriverExecutor 或 AIAdapter 执行
5. 向 $edgeos/reply/{source} 回 invoke_response（含 invoke_id / status / result）
6. 可选发布 capability.invoked Event

AI Invoke 约定：

{
  "invoke_id": "inv-ai-1",
  "target": "edgeCore-node-001",
  "capability": "ai.protocol_reverse",
  "arguments": {
    "payload": {
      "protocol_id": "modbus-tcp",
      "filename": "sample.pcap"
    },
    "wait": true,
    "wait_timeout_sec": 30
  }
}

• 无 wait：立即返回 task_id + status=queued/processing...
• wait=true：阻塞至 waiting_confirm / failed / 超时，并带回 deliverables
• 落库仍需 通过 AI 任务 Confirm API（Human-in-the-loop）

2.6 Event 与 previous_value

ShadowCore COW 写入时，在 通知克隆 中附加变更前值（不写入持久快照）：

{
  "event_type": "temperature.changed",
  "device_id": "slave-1",
  "point_id": "temperature",
  "value": 45.2,
  "previous_value": 42.1,
  "metadata": { "quality": "good", "channel_id": "ch-1" }
}

首次出现的点位 previous_value 可省略（null/缺省）。

2.7 V1.0 兼容层（仍保留）

EAN 与 V1 并行：新功能用 $edgeos/*；旧 EdgeOS 可继续用 V1。

设备清单 device_report（edgeCore 行为）：

1. 连接成功后主动发布（与重注册命令路径一致），不唯依赖 register_response
2. register_response status=success 时再发一次（EdgeOS 确认后对齐）
3. 5s 超时兜底：若本连接周期内尚未成功发出过 report，再重试一次（覆盖 publish 丢失 / 从未收到 success 的空窗）
4. 重注册命令（node_register）路径同样立即 publishDeviceReport（节点已存在时 EdgeOS 可能不再回 register_response）
5. 动态变更重新上报（v1.10）：通道/设备增删改（addChannel/updateChannel/removeChannel/addDevice/updateDevice/removeDevice）或北向 Devices 映射变更时，edgeCore 重新发布 edgeCore/devices/report，EdgeOS ReconcileDevices 据此增删设备——设备列表无需重启即可同步（联机复测：新增设备 8→9、删除 9→8 自动更新）。

EdgeOS 若仍依赖 V1 设备清单对账，必须同时订阅 MQTT edgeCore/devices/report 与 NATS edgeCore.devices.report（双传输对称）；漏订任一侧会导致该传输上的设备数空窗或滞后。

device_report 消息体格式（edgeCore 发布，EdgeOS 必须解析）：

Topic: edgeCore/devices/report（MQTT） / edgeCore.devices.report（NATS）

{
  "header": {
    "message_id": "msg_uuid",
    "timestamp": 1722672000000,
    "source": "edgeCore-node-01",
    "message_type": "device_report",
    "version": "1.0"
  },
  "body": {
    "node_id": "edgeCore-node-01",
    "devices": [
      {
        "device_id": "dev_0723120134",
        "device_name": "智能电表_01",
        "device_profile": "modbus-tcp",
        "service_name": "Modbus-TCP-通道1",
        "labels": [],
        "description": "",
        "admin_state": "ENABLED",
        "operating_state": "ENABLED",
        "station_name": "海府一体化冷站",
        "station_code": "HKO.HFJLZ",
        "room_name": "海府动力机房/1楼/1号电力室",
        "room_code": "HKO.HFJDD01",
        "properties": {
          "protocol": "modbus-tcp",
          "channel_id": "ch-001",
          "slave_id": 1
        }
      }
    ]
  }
}

空间属性字段说明：

空间属性为可选字段，未配置时不上报（omitempty）。EdgeOS 侧应将这四个字段持久化到设备记录中，用于设备资产管理、位置检索和拓扑展示。

3. EdgeOS 端必须实现的功能

以下为 EdgeOS 开发落地清单（缺一则无法完成 EAN 2.0 闭环）。

3.1 消息总线与连接

本机联调默认：

• MQTT: tcp://127.0.0.1:18083
• NATS: nats://127.0.0.1:4222

3.2 Discovery Center（必须）

Agent Descriptor 关键字段（edgeCore 发布）：id、kind、version、status、transport、heartbeat_interval_sec、metadata。

Capability Descriptor 关键字段：id、agent_id、description、category、input_schema、output_schema、timeout_sec、permission、metadata。

3.3 Invoke Orchestrator（必须）

InvokeRequest 最小字段：

{
  "invoke_id": "uuid",
  "target": "edgeCore-node-001",
  "capability": "system.diagnostics",
  "arguments": {}
}

InvokeResponse 最小字段：invoke_id、status（completed|failed|...）、result.success、result.values / result.error。

3.4 Event Center（必须）

点位变化 Event 契约（EdgeOS 必须兼容）：

3.5 平台治理（必须/强烈建议）

3.6 EdgeOS 侧「不要做」的事

• 不要在 EdgeOS 直接驱动南向设备（读/写走 edgeCore Capability Invoke）
• 不要假设 AI Invoke 会自动写配置（必须等待人工 Confirm 或显式 apply API）
• 不要把 NATS subject 重新改回 $edgeos/discovery/agent 这类斜杠形式——NATS 须用点分（$edgeos.discovery.agent），/→.、+→*、#→>

4. MQTT 与 NATS 对称说明

NATS 使用标准点分 Subject，与 MQTT 斜杠 Topic 语义对称：/→.、+→*、#→>。例如 $edgeos/discovery/agent（MQTT）↔ $edgeos.discovery.agent（NATS）。

集成测试：

• internal/northbound/edgos_mqtt/ean_integration_test.go
• internal/northbound/edgos_nats/ean_integration_test.go

NATS 订阅 V1 数据面警示（v1.6，联合调试发现）：订阅 edgeCore.* 数据面时勿用双 > 通配（如 edgeCore.data.>.>）——nats-server（MQTT gateway 版）会拒绝并关闭连接（EdgeOS 曾因此 NATS 断连）。用单 >（edgeCore.data.>）即可匹配 edgeCore.data.{node}.{device}，语义与 MQTT edgeCore/data/+/+ 一致。

5. V1.0 兼容策略

5.0 协议共识：数据面默认开放，EAN 能力层按需开启（EdgeOS 必读）

EdgeOS(MQTT/NATS) 北向通道是两层协议，由通道配置的 ean_enabled 开关控制：

约定：

• EdgeOS 建北向通道时，即使不开启 EAN，也必须订阅 V1 数据面 Topic 以接收节点/设备/点位/实时数据。
• 开启 ean_enabled=true 后，EdgeOS 才可发现 Capability 并发起 Invoke（读写设备）。未开启时不应向 $edgeos/invoke/* 发调用——edgeCore 无 Runtime 订阅，消息将静默丢弃。
• ean_event_auto_publish=false（默认）时，EAN Runtime 正常收发 Invoke/Discovery/Heartbeat，但不自动广播点位变化 Event；置 true 才发布 $edgeos/event/{agent} 点位变化事件。
• MCP Runtime 是进程内基础能力层，与北向通道无关，始终可用（供本地 LLM 调用，不走 MQTT/NATS）。

EdgeOS 对接验收：ean_enabled=false 时验证 V1 数据面贯通 + $edgeos/# 无 Discovery 流量；ean_enabled=true 时验证 63 条 Capability 发现 + Invoke/Reply 闭环 + Heartbeat。

1. 并行运行：EAN $edgeos/* 与 V1 edgeCore/*（MQTT）/edgeCore.*（NATS）同时可用。
2. 新功能只加 EAN：Capability / Discovery / Invoke / Event 新能力不回灌 V1。
3. 迁移建议：EdgeOS 先实现 EAN Discovery+Invoke+Event，再逐步将 V1 控制面切到 Invoke。
4. 双写窗口：过渡期 edgeCore 可同时发 V1 点位上报与 EAN Event；EdgeOS 应以 EAN Event 为准做新规则。

Phase 4（v1.7→v1.9）V1 命令面状态：

• edgeCore 侧：V1 命令 Topic（edgeCore/cmd/*）订阅已全面下线（v1.9 v1_command_enabled=false）：不再订阅/发布 edgeCore/cmd/*、不再发布 V1 节点注册、不运行 V1 心跳循环；命令统一走 EAN Invoke。
• EdgeOS 侧：V1→EAN Bridge（轮询合成 Agent/心跳/点位 Event）已移除（OS-P4）；edgeCore/cmd/responses/# 订阅已移除，PublishCommand 跳过（v1_command_enabled=false）；命令统一 $edgeos/invoke/*。
• 保留：V1 数据面（edgeCore/data/*、edgeCore/points/*、edgeCore/devices/*）与告警（edgeCore/events/*）长期保留。
• 全面下线开关（v1.8/1.9 V1CommandEnabled）：edgeCore 北向通道（EdgeOSMQTTConfig/EdgeOSNATSConfig）与 EdgeOS ean.v1_command_enabled 开关——v1.9 已置 false（全面下线）：edgeCore 停止订阅/发布 edgeCore/cmd/* 与 edgeCore/nodes/*、V1 心跳循环，EdgeOS 跳过 PublishCommand/主动发现；V1 数据面/告警不受影响。

6. 联调步骤

6.1 前置

# NATS（本机）
# 确认监听 4222
nats server check connection --server=nats://127.0.0.1:4222
# 或
nc -vz 127.0.0.1 4222

# MQTT（本机 EMQX/Mosquitto 等）
nc -vz 127.0.0.1 18083

6.2 跑 edgeCore 集成测试

cd d:/code/edgeCore

# NATS：Discovery + Invoke(system.diagnostics) + Event(previous_value)
go test ./internal/northbound/edgos_nats/ -run TestEANIntegrationNATSDiscoveryInvokeEvent -v -count=1

# MQTT：同上（broker 不可达时自动 Skip）
go test ./internal/northbound/edgos_mqtt/ -run TestEANIntegrationMQTTDiscoveryInvokeEvent -v -count=1

# AI Adapter + Capability 路由
go test ./internal/execution/ -run 'AI|DriverExecutor' -v -count=1

# Shadow previous_value
go test ./internal/core/ -run TestShadowCore_NotifyIncludesPreviousValue -v -count=1

# 构建
go build -o /dev/null ./cmd/

6.3 手工联调（NATS 示例）

1. 启动 edgeCore，配置 northbound.edgeos_nats：url=nats://127.0.0.1:4222，node_id=edgeCore-node-001，enable=true
2. EdgeOS（或 nats CLI）订阅（NATS 点分 Subject）：
   • $edgeos.discovery.agent
   • $edgeos.discovery.capability
   • $edgeos.event.edgeCore-node-001
   • $edgeos.reply.edgeos-planner
3. 发布 Invoke：

{
  "header": {
    "message_id": "msg-1",
    "timestamp": 0,
    "source": "edgeos-planner",
    "message_type": "invoke_capability",
    "version": "2.0",
    "correlation_id": "corr-1"
  },
  "body": {
    "invoke_id": "inv-1",
    "target": "edgeCore-node-001",
    "capability": "system.diagnostics",
    "arguments": {}
  }
}

Subject: $edgeos.invoke.edgeCore-node-001

1. 确认 Reply status=completed
2. 制造点位变化（或调用 Runtime Event），确认 Event 含 previous_value

MQTT 手工步骤相同，仅把 NATS Publish/Subscribe 换成 MQTT，Broker 127.0.0.1:18083。

7. 验收清单

7.1 edgeCore

• Capability Runtime 随 MQTT/NATS 连接自动 Start / OnConnected
• Discovery 发布 agent + capability
• Invoke system.diagnostics 成功
• Invoke ai.protocol_reverse / ai.doc_parse 不再报「未接线」，返回 task / deliverables
• Shadow 点位变化 Event 含 previous_value
• NATS 集成测试通过（127.0.0.1:4222）
• MQTT 集成测试通过（127.0.0.1:18083 可达时）
• go build ./cmd/ 通过
• V1 命令面标记 DEPRECATED（订阅/发布 WARN；EX-P4-01/02，v1.7）

7.2 EdgeOS（对端验收）

• 双传输订阅 $edgeos/discovery/* 并建立索引
• 能向任意 online Agent 发起 Invoke 并解析 Reply
• 订阅 Event 并正确使用 previous_value（差值/告警/审计）
• Agent 心跳超时标记 offline，与 discovery/agent/offline 一致
• 权限：限制 write/admin/AI Capability 的调用方
• 与 V1 并存时无 Topic 冲突 / 双处理重复副作用
• V1 设备清单：MQTT 订 edgeCore/devices/report，NATS 订 edgeCore.devices.report（双传输对称）

以上 EdgeOS 验收项已于 2026-08-03 两端联合联调 在本机（192.168.3.104，MQTT 18083 + NATS 4222）全部验证通过，详见 V1-to-EAN-Migration-Assessment §7.0。

8. 已知限制与后续

9. 附录：本轮 edgeCore 改动摘要

维护者: edgeCore / edgeOS 团队
下一步: V1 命令面已全面下线（v1_command_enabled=false，v1.9）；命令路径完全由 EAN Invoke 承载，联机复测通过。V1 数据面与告警长期保留。
关联文档: AI协同组件规划.md · V1-to-EAN-Migration-Assessment.md · edgeCore通信协议规范(MQTT-NATS).md