第八十一章

WSaiOS Data Exchange Specification

数据交换规范

原因很简单：

所有 Engine、Service、Capability、Workflow、API 最终都要交换数据。

如果没有统一的数据交换规范，整个系统无法稳定运行。

第八十一章

WSaiOS Data Exchange Specification

数据交换规范

81.1 为什么需要数据交换规范

前面的章节已经定义：

• Cognitive Object
• Service
• Workflow
• API

但是：

模块之间：

如何交换数据？

例如：

Knowledge：

输出：

{
    "entity":"Electric Toothbrush"
}

Reasoning：

如果：

需要：

{
    "keyword":"Electric Toothbrush"
}

那么：

接口：

立即：

失效。

因此：

WSaiOS：

必须：

统一数据交换。

81.2 工程目标

Data Exchange：

负责：

统一：

Input

↓

Object

↓

Transfer

↓

Receive

↓

Validate

↓

Output

不是：

业务逻辑。

81.3 Data Package

WSaiOS：

统一：

Data Package。

例如：

{
    "header":{

        "id":"UUID",

        "version":"1.0",

        "timestamp":"2026-07-24T10:00:00Z"

    },

    "payload":{

    },

    "metadata":{

    }

}

任何模块：

全部：

接收：

Data Package。

81.4 Header

Header：

固定。

包括：

Message ID

Version

Sender

Receiver

Timestamp

Type

方便：

日志。

追踪。

调试。

81.5 Payload

Payload：

业务数据。

例如：

{
    "keyword":"electric toothbrush supplier California"
}

Knowledge：

Reasoning：

Decision：

全部：

放：

Payload。

81.6 Metadata

Metadata：

附加信息。

例如：

{
    "priority":1,

    "language":"en",

    "market":"USA"
}

以后：

无需：

修改：

Payload。

81.7 Serialization

第一版：

统一：

JSON。

例如：

json.dumps()

以后：

支持：

• MessagePack
• Protocol Buffers
• CBOR

但：

对象模型保持一致。

81.8 Object Mapping

Data Package：

进入：

统一：

Object。

例如：

request = CognitiveObject.from_package(package)

输出：

package = object.to_package()

实现：

双向转换。

81.9 Data Validation

收到：

Package：

必须：

验证。

检查：

• Header 是否完整；
• Version 是否兼容；
• Payload 是否为空；
• Metadata 是否正确。

否则：

拒绝。

81.10 Compatibility

Version：

例如：

v1.0

v1.1

v2.0

规则：

高版本：

兼容：

低版本。

低版本：

允许：

拒绝：

未知字段。

81.11 Data Repository

所有：

交换数据：

统一：

记录。

例如：

SQLite：

exchange_log

记录：

• Message ID
• Sender
• Receiver
• Time
• Result

便于：

问题定位。

81.12 工程目录

建议：

exchange/

├── package.py
├── serializer.py
├── validator.py
├── mapper.py
├── repository.py
└── version.py

81.13 最小验证

建立：

Knowledge：

发送：

Package。

Reasoning：

接收：

Package。

验证：

• Header；
• Payload；
• Metadata；
• Version。

确认：

接口：

全部：

一致。

81.14 数据交换模型

Knowledge
      │
      ▼
Data Package
      │
Serializer
      │
Transport
      │
Deserializer
      │
Reasoning

注意：

Transport 可以是：

• 进程内调用
• Event Bus
• HTTP
• WebSocket
• RPC

数据格式保持一致。

81.15 本章总结

完成：

WSaiOS Data Exchange Specification

建立：

• Data Package
• Header
• Payload
• Metadata
• JSON序列化
• Object Mapping
• Data Validation
• Version Compatibility
• Exchange Log