首页 理论 架构 工程 文档 白皮书 著作 研究 案例 下载 博客 关于 开始使用 →
首页 › 第二十四部分 ICAI API + JSON 261–290› 第263章 Element API｜元素 API

第263章 Element API｜元素 API

📅 2026年09月04日 👤 东塬一老翁 📂 第二十四部分 ICAI API + JSON 261–290

第263章 Element API｜元素 API

263.1 提出背景

第261章建立了 ICAI API Architecture｜ICAI API 架构，确定了 ICAI 与外部系统之间的通信边界。

第262章进一步建立了 JSON Cognitive Data｜JSON 认知数据，使 ICAI 内部的认知结构能够通过 JSON 进行标准化表示。

此时，ICAI 已经形成：

External System
↓
API
↓
JSON
↓
Cognitive Data
↓
ICAI Runtime

但是，统一认知数据还需要进一步分解为可以被独立访问的认知资源。

ICAI 的认知结构从最基础的 Element 开始：

Real-Time Data
↓
Element
↓
Object
↓
Relation
↓
State
↓
Scene
↓
Cognition

因此，API 工程首先需要解决最基础的数据对象通信问题：

外部系统如何向 ICAI 提交一个 Element？

ICAI 如何向外部系统返回一个 Element？

一个 Element 如何在 API 中被创建、读取、更新和删除？

由此建立：

Element API｜元素 API。

Element API 是 ICAI API 体系中最基础的对象级 API 之一。

263.2 Element API 的定义

Element API｜元素 API，是 ICAI 用于接收、创建、读取、更新和传输 Element Data｜元素数据的标准化程序接口。

其基本关系为：

Element API=F(Request,Element,Response)Element\ API = F(Request,Element,Response)

其中：

  • Request：外部请求；
  • Element：ICAI 元素对象；
  • Response：元素处理结果。

基本流程为：

External System
↓
Element API
↓
Element Controller
↓
Element Service
↓
Element Engine
↓
Element Model

返回：

Element Model
↓
Element Engine
↓
Element Service
↓
Element Controller
↓
JSON Response
↓
External System

因此：

Element API
≠
Element Engine

API 是通信入口。

Engine 是内部处理机制。

Model 是元素的内部结构。

263.3 Element API 在 ICAI 中的位置

Element API 位于 ICAI 认知系统的底层数据入口。

整体结构为：

                    External System
                          ↓
                     Element API
                          ↓
                  Element Controller
                          ↓
                   Element Service
                          ↓
                    Element Engine
                          ↓
                    Element Model
                          ↓
                       Object
                          ↓
                       Scene
                          ↓
                     Cognition

如果 Element 来自现实世界，则形成：

World
↓
Real-Time Data
↓
Element API
↓
Element
↓
Object
↓
Scene
↓
Cognition

因此 Element API 可以成为外部实时数据进入 ICAI 认知系统的重要入口。

263.4 Element 的 API 数据结构

第209章已经定义了 Dynamic Attribute｜动态属性的基本结构。

对于 Element，可以建立统一数据结构：

E=(ID,Type,Value,Unit,Time,Source)E=(ID,Type,Value,Unit,Time,Source)

其中：

  • IDID：元素唯一标识；
  • TypeType：元素类型；
  • ValueValue：元素值；
  • UnitUnit：单位；
  • TimeTime：产生时间；
  • SourceSource：数据来源。

对应 JSON：

{
    "element": {
        "id": "element_001",
        "type": "position",
        "value": [10, 20, 30],
        "unit": "mm",
        "timestamp": 1756980000,
        "source": "sensor_001"
    }
}

这就是 Element API 的基础数据结构。

263.5 Element Type｜元素类型

Element 不只是一个 Value。

系统必须能够知道这个数据是什么类型。

例如：

position
velocity
force
pressure
temperature
distance
orientation
image
sound
touch
state
time

因此：

{
    "id": "element_002",
    "type": "force",
    "value": 2.5,
    "unit": "N"
}

与：

{
    "id": "element_003",
    "type": "position",
    "value": [10, 20, 30],
    "unit": "mm"
}

虽然都是 Element，但具有不同的类型。

因此：

ElementType→MeaningElementType \rightarrow Meaning

Element Type 是后续对象构建和认知计算的重要依据。

263.6 Element Value｜元素值

Element Value 是元素所承载的具体数据。

Value 可以是：

Scalar
Vector
Boolean
String
Array
Structured Value

例如标量：

{
    "type": "force",
    "value": 2.5
}

向量：

{
    "type": "position",
    "value": [10, 20, 30]
}

布尔值：

{
    "type": "stable",
    "value": true
}

因此：

Value∈{Scalar,Vector,Boolean,String,Array,Object}Value\in \{Scalar,Vector,Boolean,String,Array,Object\}

Element API 不规定所有元素必须使用相同的数据形式。

而是允许不同类型的 Element 保存不同结构的数据。

263.7 Element Timestamp｜元素时间

动态认知系统中的 Element 必须具有时间属性。

定义：

Et=(ID,Type,Value,Unit,t,Source)E_t=(ID,Type,Value,Unit,t,Source)

其中 tt 表示元素产生或采集的时间。

例如：

{
    "id": "element_004",
    "type": "velocity",
    "value": [0.5, 0, 0],
    "unit": "m/s",
    "timestamp": 1756980010
}

通过 Timestamp，ICAI 可以判断：

Element(t0)
↓
Element(t1)
↓
Element(t2)

从而形成动态数据序列。

因此 Element API 不只是传递“数据是什么”，还传递：

数据什么时候产生。

263.8 Element Source｜元素来源

Element 还需要记录数据来源。

例如：

sensor
device
camera
microphone
external_system
user
software
calculation

JSON：

{
    "id": "element_005",
    "type": "pressure",
    "value": 1.2,
    "unit": "N/cm2",
    "source": "sensor_003"
}

Source 可以帮助 ICAI 判断数据来源及其所属系统。

因此：

Element=Data+SourceElement = Data+Source

对于需要进行数据追踪的系统，Source 是重要的结构信息。

263.9 Element API Endpoint｜元素 API 端点

Element API 可以建立标准 Endpoint｜接口端点。

例如：

/api/element/create
/api/element/get
/api/element/update
/api/element/delete
/api/element/list

也可以采用资源型结构：

/api/elements
/api/elements/{id}

其基本关系为：

Element API
│
├── Create
├── Get
├── Update
├── Delete
└── List

这些接口负责 Element 数据的基本生命周期管理。

263.10 Create Element｜创建元素

外部系统可以通过 Create Element API 提交新的元素。

请求：

{
    "type": "force",
    "value": 2.5,
    "unit": "N",
    "timestamp": 1756980010,
    "source": "sensor_001"
}

API 接收以后：

Request
↓
Validation
↓
Element Creation
↓
Element Model
↓
Element Storage
↓
Response

系统可以生成：

{
    "status": "success",
    "element": {
        "id": "element_101",
        "type": "force",
        "value": 2.5,
        "unit": "N"
    }
}

这样外部系统获得一个 ICAI Element ID。

263.11 Get Element｜读取元素

外部系统可以根据 Element ID 请求元素。

例如：

GET /api/elements/element_101

处理流程：

Request
↓
Element Controller
↓
Element Service
↓
Element Model
↓
JSON Response

返回：

{
    "status": "success",
    "element": {
        "id": "element_101",
        "type": "force",
        "value": 2.5,
        "unit": "N",
        "timestamp": 1756980010,
        "source": "sensor_001"
    }
}

因此 Element API 可以作为外部系统访问 ICAI 元素数据的统一入口。

263.12 Update Element｜更新元素

动态认知系统中的 Element 会不断变化。

例如：

Force(t0)=2.0Force(t_0)=2.0

经过一段时间：

Force(t1)=2.5Force(t_1)=2.5

再变化为：

Force(t2)=3.0Force(t_2)=3.0

因此：

Element(t0)
↓
Element(t1)
↓
Element(t2)

API 可以通过 Update Element 完成：

External Data
↓
Element API
↓
Element Update
↓
Object Update
↓
Scene Update
↓
Cognition Update

例如：

{
    "id": "element_101",
    "value": 3.0,
    "timestamp": 1756980020
}

更新后的元素将成为新的 Runtime 数据。

263.13 Element History｜元素历史

对于动态元素，仅保存当前值可能不足以描述完整变化过程。

因此可以建立：

Element History

例如：

{
    "element_id": "element_101",
    "history": [
        {
            "value": 2.0,
            "timestamp": 1756980000
        },
        {
            "value": 2.5,
            "timestamp": 1756980010
        },
        {
            "value": 3.0,
            "timestamp": 1756980020
        }
    ]
}

这样可以得到：

E(t0)→E(t1)→E(t2)E(t_0)\rightarrow E(t_1)\rightarrow E(t_2)

元素历史可以为后续状态变化、动态计算和反馈分析提供数据基础。

263.14 Delete Element｜删除元素

Element 具有生命周期。

其基本状态可以表示为：

Created
↓
Active
↓
Updated
↓
Inactive
↓
Deleted

API 可以提供 Delete Element 操作。

但是对于认知系统而言，删除并不一定意味着物理数据立即消失。

可以采用逻辑状态：

active = false

表示该元素已经不再参与当前认知运行。

因此：

Physical Data
≠
Current Cognitive Data

现实数据可能仍然存在，但 ICAI 当前运行状态中可以将其标记为 inactive。

263.15 Element Validation｜元素验证

Element API 接收到数据后，不能直接进入 Runtime。

需要进行基本验证：

Request
↓
ID Validation
↓
Type Validation
↓
Value Validation
↓
Unit Validation
↓
Timestamp Validation
↓
Source Validation
↓
Element

例如：

force
↓
Value = 2.5
↓
Unit = N

如果 Value 不是有效数值，则不能形成有效 Force Element。

因此：

Valid(E)=Valid(ID)∧Valid(Type)∧Valid(Value)∧Valid(Time)Valid(E)= Valid(ID) \land Valid(Type) \land Valid(Value) \land Valid(Time)

只有：

Valid(E)=1Valid(E)=1

时，Element 才可以进入下一层处理。

263.16 Element API 与 Object API

Element API 并不等同于 Object API。

两者处于不同层级。

Element API
↓
Element
↓
Object API
↓
Object

Element 是基础认知数据。

Object 是多个元素经过结构化组织后形成的认知对象。

例如：

position
weight
shape
color
temperature

多个 Element 可以共同参与：

Object

的构建。

因此：

Object=F(E1,E2,…,En)Object=F(E_1,E_2,\ldots,E_n)

这里：

  • E1,E2,…,EnE_1,E_2,\ldots,E_n 表示多个 Element；
  • FF 表示对象构建关系。

263.17 Element API 与 Scene API

Scene 更高一层。

其结构为：

Element
↓
Object
↓
Relation
↓
State
↓
Scene

因此：

Element API

负责元素级通信。

而未来的：

Object API
Scene API
Cognitive API
Behavior API
Device API

则分别处理更高层级的认知结构。

可以形成 API 层次：

Element API
↓
Object API
↓
Relation API
↓
State API
↓
Scene API
↓
Cognitive API
↓
Behavior API
↓
Action API
↓
Device API
↓
Feedback API

这与 ICAI 的认知对象层次保持一致。

263.18 Element API 与 Runtime

Element API 最终不能停留在数据 CRUD 层。

真正重要的是：

Element API
↓
Runtime

例如外部系统提交一个新的 Position Element：

Position Element
↓
Element API
↓
Element Engine
↓
Object Update
↓
Scene Update
↓
Cognition Update

如果这个元素改变了对象状态：

Position
↓
Distance
↓
Reachability
↓
State
↓
Cognition

因此 Element API 可以触发整个认知链条。

263.19 Element API 的事件机制

当 Element 创建或更新以后，可以产生事件：

ElementCreated
ElementUpdated
ElementChanged
ElementExpired
ElementDeleted

例如：

ElementUpdated
↓
ObjectEngine
↓
ObjectUpdated
↓
SceneEngine
↓
SceneChanged
↓
CognitiveEngine
↓
CognitionChanged

因此：

ElementEvent→RuntimeEventElementEvent \rightarrow RuntimeEvent

Element API 与 ICAI Runtime 的事件系统可以形成连接。

263.20 Element API 的 PHP OOP 工程结构

可以建立：

ElementApiController
ElementService
ElementEngine
ElementModel
ElementRepository

其结构为：

ElementApiController
↓
ElementService
↓
ElementEngine
↓
ElementModel
↓
ElementRepository

其中：

ElementApiController

负责 API 请求和响应。

ElementService

负责元素业务服务组织。

ElementEngine

负责元素处理与更新。

ElementModel

表示元素对象。

ElementRepository

负责元素数据存取。

263.21 PHP Element API Controller

可以建立：

class ElementApiController
{
    protected $elementService;

    public function create($request)
    {
        $data = $this->validate($request);

        $element = $this->elementService->create($data);

        return $this->response($element);
    }

    public function get($id)
    {
        $element = $this->elementService->get($id);

        return $this->response($element);
    }

    protected function validate($request)
    {
        return $request;
    }

    protected function response($element)
    {
        return array(
            'status' => 'success',
            'element' => $element
        );
    }
}

这里 Controller 仍然不负责认知计算。

它只负责 API 层的控制。

263.22 PHP Element Service

Service 负责调用 Element Engine。

class ElementService
{
    protected $elementEngine;

    public function create($data)
    {
        return $this->elementEngine->create($data);
    }

    public function get($id)
    {
        return $this->elementEngine->get($id);
    }

    public function update($id, $data)
    {
        return $this->elementEngine->update($id, $data);
    }
}

形成：

API Controller
↓
Element Service
↓
Element Engine

这样 API 层不会直接耦合底层 Element 数据结构。

263.23 PHP Element Engine

Element Engine 负责元素内部处理。

class ElementEngine
{
    protected $repository;

    public function create($data)
    {
        return $this->repository->create($data);
    }

    public function get($id)
    {
        return $this->repository->find($id);
    }

    public function update($id, $data)
    {
        return $this->repository->update($id, $data);
    }
}

进一步可以在 Engine 中加入：

Type Check
Value Check
Unit Check
Timestamp Check
Source Check
State Update
Event Dispatch

因此 Engine 是 Element API 与内部 Runtime 之间的处理层。

263.24 Element API Request Model

一个标准 Element Request 可以定义：

ER={Type,Value,Unit,Timestamp,Source}ER= \{Type,Value,Unit,Timestamp,Source\}

例如：

{
    "type": "distance",
    "value": 25,
    "unit": "mm",
    "timestamp": 1756980030,
    "source": "sensor_004"
}

API Controller 接收到以后：

Request
↓
Validation
↓
Element
↓
Element Engine

最终形成 ICAI 内部 Element Object。

263.25 Element API Response Model

Response 可以定义：

EP={ID,Type,Value,Unit,Timestamp,Source,Status}EP= \{ID,Type,Value,Unit,Timestamp,Source,Status\}

例如：

{
    "status": "success",
    "element": {
        "id": "element_105",
        "type": "distance",
        "value": 25,
        "unit": "mm",
        "timestamp": 1756980030,
        "source": "sensor_004"
    }
}

Response 不仅告诉外部系统数据内容，还告诉外部系统：

Request 是否成功
+
Element 是否有效
+
Element 当前状态

263.26 Element API 与实时数据

ICAI 是动态认知系统，因此 Element API 可以成为实时数据入口。

例如：

Sensor
↓
Real-Time Data
↓
Element API
↓
Element
↓
Object
↓
Scene
↓
Cognition

如果连续产生数据：

Sensor
↓
E1
↓
E2
↓
E3
↓
E4
↓
E5

则 ICAI 可以形成：

E1→E2→E3→E4→E5E_1\rightarrow E_2\rightarrow E_3\rightarrow E_4\rightarrow E_5

进一步计算：

Xt=[x1(t),x2(t),…,xn(t)]X_t=[x_1(t),x_2(t),…,x_n(t)]

形成动态属性向量。

因此 Element API 可以成为实时认知数据流进入 ICAI 的底层通信接口。

263.27 Element API 与认知闭环

Element API 最终进入完整认知闭环：

External Data
↓
Element API
↓
Element
↓
Object
↓
Relation
↓
State
↓
Scene
↓
Cognition
↓
Behavior
↓
Action
↓
Device
↓
Feedback
↓
Element Update
↓
Re-Cognition

因此，Element API 并不是一个孤立的数据接口。

它位于认知闭环的数据入口和更新位置。

263.28 Element API 的完整架构

综合本章，可以建立：

                         External System
                               │
                               ↓
                         Element API
                               │
                               ↓
                    Element API Controller
                               │
                               ↓
                       Element Service
                               │
                               ↓
                        Element Engine
                               │
                               ↓
                        Element Model
                               │
                               ↓
                            Object
                               │
                               ↓
                            Scene
                               │
                               ↓
                          Cognition
                               │
                               ↓
                           Behavior
                               │
                               ↓
                            Action
                               │
                               ↓
                            Device
                               │
                               ↓
                            Feedback
                               │
                               ↓
                        Element Update

这形成了 Element API 与 ICAI Runtime 之间的完整关系。

263.29 Element API 的核心原则

Element API 建立过程中需要保持几个基本原则。

第一，元素独立

Element API 只负责 Element 层的数据，不直接承担完整对象认知。

第二，结构统一

所有 Element 都遵循统一的数据结构：

E=(ID,Type,Value,Unit,Time,Source)E=(ID,Type,Value,Unit,Time,Source)

第三，动态更新

Element 可以随时间变化：

Et→Et+1E_t\rightarrow E_{t+1}

第四，来源明确

每一个动态元素都可以记录 Source。

第五，时间明确

每一个动态元素都可以记录 Timestamp。

第六，认知解耦

API、Element Engine、Object Engine、Cognitive Engine 各自保持独立。

第七，数据驱动

新的实时元素进入系统后，可以根据当前对象、关系和场景动态参与认知。

因此不需要为每一种具体对象建立独立的 Element API。

263.30 本章总结

第263章建立了 Element API｜元素 API。

本章将第262章的 JSON Cognitive Data 进一步落实到最基础的认知对象层。

其核心结构为：

External System
↓
Element API
↓
Element Controller
↓
Element Service
↓
Element Engine
↓
Element Model
↓
Object
↓
Scene
↓
Cognition

Element 的统一结构为：

E=(ID,Type,Value,Unit,Time,Source)E=(ID,Type,Value,Unit,Time,Source)

并支持：

Create
Get
Update
Delete
List
History
Validation
Event

因此形成：

Real-Time Data
↓
Element API
↓
Element
↓
Object
↓
Scene
↓
Cognition

同时，当反馈产生以后，又可以反向进入：

Feedback
↓
Element Update
↓
Object Update
↓
Scene Update
↓
Re-Cognition

由此，Element API 成为 ICAI API Architecture 中最底层的认知数据通信接口。

第261章解决：

ICAI 如何对外通信？

第262章解决：

认知数据如何通过 JSON 表示？

第263章进一步解决：

最基础的 Element 如何通过 API 进入和离开 ICAI？

由此下一层可以自然进入：

Element API
↓
Object API
↓
Object JSON
↓
Object Instance
↓
Object Runtime

因此下一章进入：

第264章 Object API｜对象 API

← 第262章 JSON Cognitive Data｜JSON 认知数据
第264章 Object API｜对象 API →

Leave a Reply

Your email address will not be published. Required fields are marked *