第261章 ICAI API Architecture｜ICAI API 架构

261.1 提出背景

第260章完成了 ICAI MVC Runtime｜ICAI MVC 认知运行系统的建立。

经过前面的工程建设，ICAI 已经形成：

Object Model
↓
Scene Model
↓
Cognitive Model
↓
Behavior Model
↓
Device Model

并通过：

Object Engine
↓
Scene Engine
↓
Cognitive Engine
↓
Behavior Engine
↓
Device Engine

完成内部认知与执行过程。

在 MVC 层又形成：

Controller
↓
Engine
↓
Model
↓
Smarty
↓
Runtime

此时 ICAI 已经具备一个完整的软件运行体系。

但是，一个完整运行的软件系统与一个能够被其他软件系统调用的独立能力系统并不是同一个概念。

如果外部系统希望请求 ICAI：

“分析这个对象。”

“识别当前场景。”

“计算当前状态。”

“判断下一步行为。”

“生成一个可执行动作。”

就需要一个明确的系统通信入口。

因此，在第二十四部分中，需要建立：

ICAI API Architecture｜ICAI API 架构。

API 的作用不是重新建立认知理论，而是把已经存在于 ICAI Runtime 内部的认知能力，通过标准化通信接口暴露给外部系统。

其核心转换为：

External System
↓
ICAI API
↓
ICAI Controller
↓
ICAI Runtime
↓
Cognitive System
↓
JSON Response
↓
External System

因此，API 是 ICAI 与外部软件之间的系统边界。

---

261.2 ICAI API 的定义

ICAI API｜ICAI Application Programming Interface，ICAI 应用程序编程接口，是 ICAI 向外部软件系统提供结构化认知服务的标准通信接口。

其基本定义为：

APIt=F(It,Rt,Ot)API_t=F(I_t,R_t,O_t)

其中：

• APItAPI_t：时刻 tt 的 API 服务；
• ItI_t：External Input，外部输入；
• RtR_t：ICAI Runtime，ICAI 运行状态；
• OtO_t：Structured Output，结构化输出。

API 的基本任务是：

External Request
↓
Input Validation
↓
Request Parsing
↓
ICAI Runtime
↓
Cognitive Processing
↓
Structured Result
↓
Response

因此 API 并不是认知引擎本身。

：

API
≠
Cognitive Engine

而是：

API
↓
Controller
↓
Engine
↓
Model

API 位于系统边界，而认知逻辑仍然保留在 ICAI 内部。

---

261.3 ICAI API 的系统位置

ICAI API 位于 ICAI Runtime 与外部系统之间。

完整结构为：

                    External System
                          │
                          ↓
                     ICAI API
                          │
                          ↓
                    API Controller
                          │
                          ↓
                    ICAI Runtime
                          │
             ┌────────────┼────────────┐
             ↓            ↓            ↓
           Model        Engine       State
             │            │            │
             └────────────┼────────────┘
                          ↓
                    Cognitive Runtime
                          │
                          ↓
                    JSON Response
                          │
                          ↓
                    External System

因此：

API 是边界，Runtime 是内部运行体系。

---

261.4 ICAI API Architecture｜ICAI API 架构

ICAI API 架构可以划分为六个主要层次：

① External System Layer
        ↓
② API Interface Layer
        ↓
③ API Controller Layer
        ↓
④ Cognitive Service Layer
        ↓
⑤ ICAI Runtime Layer
        ↓
⑥ Model / Engine Layer

其结构为：

External System
↓
API Interface
↓
API Controller
↓
Cognitive Service
↓
ICAI Runtime
↓
Model + Engine

返回方向：

Model + Engine
↓
ICAI Runtime
↓
Cognitive Service
↓
API Controller
↓
JSON
↓
External System

这形成完整的双向通信结构。

---

261.5 External System Layer｜外部系统层

External System Layer 是 ICAI API 的调用方。

外部系统可以是：

Web Application
Mobile Application
Desktop Application
Robot System
Device System
Business System
Management System
Other AI System
Independent Software

这里的重点是：

ICAI 不要求外部系统了解 ICAI 内部全部实现。

外部系统只需要知道：

API Address
+
Request Structure
+
Response Structure

例如外部系统发送：

Object
+
Attributes
+
Scene
+
Goal

ICAI 接收以后，在内部完成：

Object Recognition
↓
State Evaluation
↓
Scene Construction
↓
Cognition
↓
Behavior

最后返回结构化结果。

---

261.6 API Interface Layer｜API 接口层

API Interface Layer 负责定义外部系统可以访问的接口。

例如：

/api/cognitive/analyze
/api/object/analyze
/api/scene/analyze
/api/state/evaluate
/api/behavior/execute
/api/device/status

这些接口代表不同的系统能力入口。

例如：

/api/cognitive/analyze

可以表示：

认知分析接口。

其逻辑为：

Request
↓
Cognitive API
↓
Cognitive Controller
↓
Cognitive Runtime
↓
Cognitive Result
↓
Response

API 地址本身并不承担认知计算。

它只是告诉外部系统：

通过这个入口可以访问 ICAI 的某项认知能力。

---

261.7 API Controller｜API 控制器

API Controller 是 API 与 ICAI Runtime 之间的控制层。

基本关系：

External Request
↓
API Controller
↓
Service
↓
Runtime

API Controller 的主要任务包括：

Request Receive
↓
Request Validation
↓
Request Parsing
↓
Service Selection
↓
Runtime Call
↓
Result Processing
↓
Response Building

因此：

API Controller
≠
Cognitive Engine

Controller 不负责完成全部认知计算。

它主要负责：

“请求应该进入 ICAI 的哪一个能力。”

---

261.8 Cognitive Service Layer｜认知服务层

为了避免 API Controller 直接操作大量 Engine，可以建立：

Cognitive Service｜认知服务。

例如：

CognitiveService
ObjectService
SceneService
BehaviorService
DeviceService

其作用是把 API 请求转换为 ICAI 内部的服务调用。

例如：

/api/cognitive/analyze
↓
CognitiveController
↓
CognitiveService
↓
CognitiveEngine
↓
CognitiveModel

这样形成：

API
↓
Controller
↓
Service
↓
Engine
↓
Model

这种结构可以避免 API 层与内部认知对象直接耦合。

---

261.9 Request｜请求结构

ICAI API 接收的数据应该是结构化数据，而不是依赖自然语言表达。

一个认知请求可以表示为：

Request={ID,Goal,Object,Scene,Data,Context}Request= \{ID,Goal,Object,Scene,Data,Context\}

其中：

• IDID：请求标识；
• GoalGoal：目标；
• ObjectObject：对象数据；
• SceneScene：场景数据；
• DataData：实时数据；
• ContextContext：当前上下文。

例如：

{
    "request_id": "REQ001",
    "goal": {
        "type": "grasp",
        "target": "object_001"
    },
    "object": {
        "id": "object_001",
        "class": "container",
        "attributes": {
            "position": [10, 20, 30],
            "weight": 0.25,
            "stability": 0.92
        }
    }
}

这里的数据只是输入结构。

真正的认知处理仍然发生在 ICAI Runtime 内部。

---

261.10 Request → Cognitive Runtime

API 收到 Request 后，不直接执行最终动作。

而是进入 ICAI Runtime：

Request
↓
Element
↓
Object Instance
↓
Object Model
↓
Relation
↓
State
↓
Scene Model
↓
Cognitive Model
↓
Behavior Model
↓
Action

因此 API 实际上完成了一次：

外部结构化数据 → ICAI 内部认知对象结构

的转换。

可以表示为：

Dexternal→DICAID_{external}\rightarrow D_{ICAI}

其中：

• DexternalD_{external}：外部系统数据；
• DICAID_{ICAI}：ICAI 内部结构化认知数据。

---

261.11 Response｜响应结构

ICAI 完成认知计算以后，需要向外部系统返回结构化结果。

响应可以表示为：

Response={ID,Status,Cognition,Behavior,Action,Result,Feedback}Response= \{ID,Status,Cognition,Behavior,Action,Result,Feedback\}

其中：

• IDID：请求标识；
• StatusStatus：处理状态；
• CognitionCognition：认知结果；
• BehaviorBehavior：行为结果；
• ActionAction：动作结果；
• ResultResult：执行结果；
• FeedbackFeedback：反馈信息。

例如：

{
    "request_id": "REQ001",
    "status": "success",
    "cognition": {
        "object": "object_001",
        "state": "stable",
        "scene": "reachable"
    },
    "behavior": {
        "type": "grasp"
    },
    "action": {
        "type": "move_and_grasp"
    },
    "result": {
        "status": "ready"
    }
}

这样外部系统无需理解 ICAI 内部 PHP Class 的具体实现。

只需要理解 JSON 数据结构即可。

---

261.12 JSON｜ICAI 的结构化通信格式

在 ICAI API 架构中，JSON 可以作为系统之间的结构化数据交换格式。

其基本关系为：

ICAI Object
↓
Array / Structure
↓
JSON
↓
API
↓
External System

反向：

External JSON
↓
API
↓
PHP Array / Object
↓
ICAI Object
↓
ICAI Model

因此：

JSON↔ICAI ObjectJSON \leftrightarrow ICAI\ Object

JSON 本身不是认知模型。

它只是：

认知数据的通信表示形式。

因此必须保持：

JSON
≠
Cognition

而是：

Cognition
↓
Structured Data
↓
JSON

---

261.13 API 与 ICAI MVC Runtime 的关系

第260章建立：

Controller
↓
Engine
↓
Model
↓
Smarty
↓
Runtime

第261章在其外部增加 API：

External System
↓
API
↓
API Controller
↓
ICAI MVC Runtime

形成：

External System
        ↓
      ICAI API
        ↓
  API Controller
        ↓
     Service
        ↓
ICAI MVC Runtime
        ↓
 Model + Engine
        ↓
 Cognitive Runtime

因此，API 并没有破坏原来的 MVC Runtime。

它只是增加了一条新的外部访问通道。

原有：

Runtime
↓
Controller
↓
Smarty
↓
HTML

新增：

Runtime
↓
API Controller
↓
JSON
↓
External System

这样，同一个 ICAI Runtime 可以同时服务于：

Web Interface
+
API Client
+
Independent Software

---

261.14 Web Interface 与 API Interface

ICAI 可以同时存在两种主要输出方式：

Web 输出

ICAI Runtime
↓
Controller
↓
Smarty
↓
HTML
↓
Human

API 输出

ICAI Runtime
↓
API Controller
↓
JSON
↓
Software

二者使用相同的内部认知模型。

因此：

                ICAI Runtime
                     │
          ┌──────────┴──────────┐
          ↓                     ↓
      Web Interface         API Interface
          ↓                     ↓
       Smarty                  JSON
          ↓                     ↓
        Human              External System

这是 ICAI 独立系统化的重要一步。

---

261.15 API 不改变 ICAI 认知逻辑

建立 API 后，ICAI 内部核心逻辑保持不变：

Object
↓
Attribute
↓
Relation
↓
State
↓
Scene
↓
Cognition
↓
Method
↓
Behavior
↓
Action
↓
Device
↓
Feedback

API 只改变：

数据进入方式
+
数据输出方式

而不改变：

认知结构
+
认知计算
+
行为逻辑
+
设备执行逻辑

因此可以表达为：

CognitionAPI=CognitionRuntimeCognition_{API}=Cognition_{Runtime}

API 调用与本地调用最终进入同一个 ICAI Runtime。

---

261.16 API 的独立性

ICAI API 的建立，使 ICAI 开始具有独立软件系统的边界。

其边界可以表示为：

┌─────────────────────────────────────┐
│             ICAI System             │
│                                     │
│  API → Controller → Runtime         │
│                    ↓                │
│              Model / Engine         │
│                    ↓                │
│          Cognitive Runtime          │
│                                     │
└─────────────────────────────────────┘
              ↑
              │
        JSON Communication
              │
              ↓
        External System

外部系统无法直接修改 ICAI 内部 Model。

而是：

External Request
↓
API
↓
Controller
↓
Runtime

这样可以形成清晰的系统边界。

---

261.17 PHP OOP 工程映射

在 PHP 工程中，可以建立独立 API Controller：

class CognitiveApiController
{
    protected $cognitiveService;

    public function analyze($request)
    {
        $data = $this->validateRequest($request);

        $result = $this->cognitiveService->analyze($data);

        return $this->buildResponse($result);
    }

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

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

Service：

class CognitiveService
{
    protected $runtime;

    public function analyze($data)
    {
        return $this->runtime->process($data);
    }
}

Runtime：

class IcaRuntime
{
    public function process($data)
    {
        // Object
        // Scene
        // Cognition
        // Behavior
        // Action
        // Feedback

        return $data;
    }
}

最终形成：

CognitiveApiController
↓
CognitiveService
↓
IcaRuntime
↓
CognitiveEngine
↓
CognitiveModel

---

261.18 API 请求生命周期

一个完整的 ICAI API 请求可以经历：

① External Request
↓
② API Receive
↓
③ Request Validation
↓
④ Request Parsing
↓
⑤ Controller
↓
⑥ Service
↓
⑦ ICAI Runtime
↓
⑧ Object Update
↓
⑨ Scene Update
↓
⑩ Cognition
↓
⑪ Behavior
↓
⑫ Action
↓
⑬ Result
↓
⑭ JSON Response
↓
⑮ External System

如果涉及真实设备，则继续：

Action
↓
Device Engine
↓
Device
↓
World Change
↓
Feedback
↓
Runtime Update
↓
JSON Response

因此 API 不仅可以传递静态认知结果，也可以成为实时认知系统的通信入口。

---

261.19 ICAI API 的核心架构模型

综合本章，可以建立：

                    External System
                          │
                          ↓
                    HTTP / API
                          │
                          ↓
                  API Interface
                          │
                          ↓
                  API Controller
                          │
                          ↓
                  Cognitive Service
                          │
                          ↓
                   ICAI Runtime
                          │
             ┌────────────┼────────────┐
             ↓            ↓            ↓
           Model        Engine        State
             │            │            │
             └────────────┼────────────┘
                          ↓
                    Cognition
                          ↓
                     Behavior
                          ↓
                       Action
                          ↓
                       Device
                          ↓
                        World
                          ↓
                      Feedback
                          ↓
                    ICAI Runtime
                          │
                          ↓
                       JSON
                          │
                          ↓
                   External System

这就是 ICAI API Architecture 的基本结构。

---

261.20 ICAI API 的工程意义

第261章并不是简单增加一个 HTTP 接口。

真正重要的是，它建立了：

ICAI Runtime → Independent System Communication

这一工程关系。

此前：

ICAI
=
一个独立运行的软件系统

现在：

ICAI
=
一个可以被外部系统调用的认知系统

因此：

ICAIRuntime→ICAIAPI→External SystemICAI_{Runtime} \rightarrow ICAI_{API} \rightarrow External\ System

ICAI 的认知能力开始具备系统级复用能力。

一个外部系统无需重新建立：

Object Model
Scene Model
Cognitive Model
Behavior Model

即可通过 API 调用 ICAI 已经形成的认知能力。

---

261.21 本章总结

第261章建立了 ICAI API Architecture｜ICAI API 架构。

本章的核心不是重新建立认知能力，而是建立 ICAI 与外部软件之间的通信边界。

其基本结构为：

External System
↓
API
↓
API Controller
↓
Service
↓
ICAI MVC Runtime
↓
Model + Engine
↓
Cognition
↓
Behavior
↓
Action
↓
Device
↓
Feedback
↓
Runtime
↓
JSON
↓
External System

由此形成：

External System↔ICAI API↔ICAI RuntimeExternal\ System \leftrightarrow ICAI\ API \leftrightarrow ICAI\ Runtime

API 负责通信。

Controller 负责控制。

Service 负责服务组织。

Engine 负责认知计算。

Model 负责认知结构。

Runtime 负责持续运行。

JSON 负责结构化数据交换。

因此，第二十四部分从第261章开始，ICAI 正式从：

内部认知运行系统

进入：

独立认知系统通信工程

下一步的核心问题将进一步从“API 架构”进入“API 数据结构”，即建立统一的 ICAI JSON Data Model｜ICAI JSON 数据模型，解决 Object、Scene、Cognition、Behavior、Action、Device、Feedback 如何被标准化表示和传输的问题。

核心转换关系为：

ICAI Object / Model
↓
Structured Data
↓
JSON Object
↓
API Request / Response
↓
Independent System