第82章　SAI + API

本章大纲

API 接口
API Information
API Controller
Central
Individual
Decision
Action
JSON Response
完整 API 案例

1. API 接口

API 是 SAI 与外部软件、系统或服务进行结构化信息交换的接口。

Web 主要面向 Browser：

Browser
   ↓
Request
   ↓
SAI
   ↓
Response

API 则主要面向：

Application
System
Website
Device System
Enterprise System
Service

基本结构：

External System
       ↓
     API
       ↓
  API Controller
       ↓
     Central
       ↓
   Individual
       ↓
    Decision
       ↓
     Action
       ↓
   Expression
       ↓
  JSON Response
       ↓
External System

API 的核心作用是：

将外部系统的结构化请求交给 SAI，并将 SAI 的结构化结果返回给外部系统。

因此：

API ≠ Individual
API ≠ Cognition
API ≠ Reasoning
API ≠ Decision
API ≠ Action

API 是接口层。

2. API Information

API Information 是通过 API 进入 SAI 的结构化信息。

例如外部系统请求启动设备：

{
    "device_id": "Motor_A",
    "action": "START"
}

进入 SAI 后，可以转换成：

API Information
{
    type: ACTION_REQUEST

    object:
        Motor_A

    action:
        START
}

API Information 可以包含：

id
type
source
target
action
parameters
timestamp
request_id

例如：

$information = array(
    'id'        => 'info_001',
    'type'      => 'ACTION_REQUEST',
    'source'    => 'ExternalSystem',
    'target'    => 'Motor_A',
    'action'    => 'START',
    'parameters'=> array(),
    'timestamp' => time()
);

这里必须区分：

API Request
      ↓
API Information

Request 是接口协议层的数据。

Information 是进入 SAI 后可以参与内部处理的数据结构。

因此：

Request
    = 外部接口请求

Information
    = SAI 接收到的信息

3. API Controller

API Controller 是 API 请求进入 SAI 的控制入口。

主要负责：

接收 API Request
检查 Request
解析 JSON
检查必要参数
创建 API Information
调用 Central
接收结果
返回 JSON Response

例如：

class ApiController
{
    protected $central;

    public function __construct($central)
    {
        $this->central = $central;
    }

    public function handle($request)
    {
        if (!isset($request['device_id'])) {
            return array(
                'state' => 'INVALID',
                'error' => 'device_id required'
            );
        }

        $information = array(
            'type'       => 'ACTION_REQUEST',
            'target'     => $request['device_id'],
            'action'     => isset($request['action'])
                ? $request['action']
                : null,
            'parameters' => isset($request['parameters'])
                ? $request['parameters']
                : array()
        );

        return $this->central->process(
            $information
        );
    }
}

Controller 的边界：

API Controller
      ↓
接口控制
      ↓
Central

Controller 不负责替代：

Cognition
Reasoning
Decision
Action

4. Central

Central 是 API 与 Individual 之间的中央协调层。

结构：

API Controller
       ↓
     Central
       ↓
   Individual

例如：

class Central
{
    protected $individual;

    public function __construct($individual)
    {
        $this->individual = $individual;
    }

    public function process($information)
    {
        return $this->individual->process(
            $information
        );
    }
}

Central 可以进一步负责：

Request Context
Individual Selection
Input Routing
Result Routing
Error Routing

例如存在多个 Individual：

Central
 ├── Individual_A
 ├── Individual_B
 └── Individual_C

Central 可以根据请求目标选择对应 Individual。

因此：

Central = 协调
Individual = 个体运行

5. Individual

Individual 是 SAI 的具体认知运行主体。

API 请求进入 Individual 后，不应该简单地把：

API Request
    ↓
直接执行 Action

而应该根据请求类型进入相应的 SAI 内部流程。

例如设备控制：

API Information
       ↓
Perception
       ↓
Cognition
       ↓
Understanding
       ↓
Memory
       ↓
Reasoning
       ↓
Decision
       ↓
Behavior
       ↓
Action

Individual 可以形成：

class Individual
{
    public function process($information)
    {
        $perception = $this->perception(
            $information
        );

        $cognition = $this->cognition(
            $perception
        );

        $decision = $this->decision(
            $cognition
        );

        return $this->action(
            $decision
        );
    }

    protected function perception($information)
    {
        return $information;
    }

    protected function cognition($information)
    {
        return $information;
    }

    protected function decision($cognition)
    {
        return array(
            'state'  => 'DECIDED',
            'action' => $cognition['action'],
            'target' => $cognition['target']
        );
    }

    protected function action($decision)
    {
        return array(
            'state'  => 'SUCCESS',
            'target' => $decision['target'],
            'action' => $decision['action']
        );
    }
}

这是架构示例。

真正的 Individual 可以连接前面已经定义的：

PerceptionEngine
Cognition
Matching
Understanding
Memory
ReasoningEngine
Decision
Behavior
Action
Expression

6. Decision

API 最重要的特点之一，是外部系统可以提出：

“我要什么？”

但 SAI 不应该简单地把请求等同于执行命令。

例如 API 请求：

{
    "device_id": "Motor_A",
    "action": "START"
}

进入 Individual 后，需要判断：

Motor_A 是否存在？
       ↓
当前状态是什么？
       ↓
是否允许启动？
       ↓
是否存在风险？
       ↓
是否存在冲突？
       ↓
是否具有 START 能力？
       ↓
是否满足启动条件？
       ↓
Decision

因此：

API Request
     ↓
Intent / Information
     ↓
Cognition
     ↓
Reasoning
     ↓
Decision

Decision 可以产生：

$decision = array(
    'id'     => 'decision_001',
    'target' => 'Motor_A',
    'action' => 'START',
    'state'  => 'DECIDED',
    'reason' => array(
        'device_exists' => true,
        'state_allowed' => true,
        'risk_allowed'  => true
    )
);

如果条件不满足：

Decision
   ↓
REJECTED

而不是继续执行 Action。

所以：

Request ≠ Decision
Decision ≠ Action

7. Action

Action 是实际执行的具体操作。

例如 Decision：

target = Motor_A
action = START

形成 Action：

$action = array(
    'id'         => 'action_001',
    'target'     => 'Motor_A',
    'method'     => 'START',
    'parameters' => array(),
    'state'      => 'READY'
);

然后：

Action
   ↓
ActionExecutor
   ↓
DeviceAdapter
   ↓
Motor_A

设备返回：

DeviceResponse

例如：

{
    "device_id": "Motor_A",
    "action": "START",
    "state": "SUCCESS"
}

ActionResult：

$actionResult = array(
    'action_id' => 'action_001',
    'state'     => 'SUCCESS',
    'target'    => 'Motor_A',
    'output'    => array(
        'state' => 'RUNNING'
    )
);

于是：

Decision
    ↓
Action
    ↓
ActionExecutor
    ↓
External Device
    ↓
ActionResult

8. JSON Response

API 最终需要把 SAI 的结构化结果转换成 JSON。

基本过程：

ActionResult
      ↓
Expression
      ↓
Api Template
      ↓
SATE
      ↓
ApiRenderer
      ↓
JSON
      ↓
API Response

Expression：

$expression = array(
    'type' => 'ACTION_RESULT',

    'target' => 'Motor_A',

    'action' => 'START',

    'state' => 'SUCCESS',

    'result' => array(
        'device_state' => 'RUNNING'
    )
);

经过 ApiRenderer 后：

{
    "type": "ACTION_RESULT",
    "target": "Motor_A",
    "action": "START",
    "state": "SUCCESS",
    "result": {
        "device_state": "RUNNING"
    }
}

HTTP Response：

HTTP/1.1 200 OK
Content-Type: application/json

因此：

Expression
     ↓
SATE
     ↓
ApiRenderer
     ↓
JSON Response

这里正好连接前面第63章的 ApiRenderer 和第80章的 Custom Template。

9. 完整 API 案例

建立一个完整案例：

外部系统通过 API 请求启动 Motor_A。

9.1 外部系统发送 Request

POST /api/device/action
Content-Type: application/json

Body：

{
    "device_id": "Motor_A",
    "action": "START"
}

9.2 API Controller

Controller 接收：

$request = array(
    'device_id' => 'Motor_A',
    'action'    => 'START'
);

检查：

device_id 存在
action 存在

然后形成 API Information：

ACTION_REQUEST
        │
        ├── target = Motor_A
        └── action = START

9.3 Central

Controller 调用：

$central->process($information);

Central：

API Controller
      ↓
Central
      ↓
Individual

9.4 Individual

Individual 获取：

Target:
Motor_A

Requested Action:
START

查询已有对象和状态：

Motor_A
state = STOPPED

并检查：

Motor_A 存在       → TRUE
START 方法存在     → TRUE
当前状态允许启动   → TRUE
风险允许           → TRUE
冲突               → NONE

9.5 Decision

形成：

$decision = array(
    'id'     => 'decision_001',
    'target' => 'Motor_A',
    'action' => 'START',
    'state'  => 'DECIDED'
);

即：

Decision = START Motor_A

9.6 Action

形成：

$action = array(
    'id'         => 'action_001',
    'target'     => 'Motor_A',
    'method'     => 'START',
    'parameters' => array(),
    'state'      => 'READY'
);

执行：

Action
   ↓
DeviceAdapter
   ↓
Motor_A

设备实际返回：

SUCCESS

并且状态：

STOPPED
   ↓
RUNNING

9.7 ActionResult

形成：

$actionResult = array(
    'action_id' => 'action_001',
    'target'    => 'Motor_A',
    'state'     => 'SUCCESS',

    'changes' => array(
        'state' => array(
            'from' => 'STOPPED',
            'to'   => 'RUNNING'
        )
    )
);

9.8 Expression

Individual 将 ActionResult 转换成 Expression：

$expression = array(
    'type'   => 'ACTION_RESULT',
    'target' => 'Motor_A',
    'action' => 'START',
    'state'  => 'SUCCESS',

    'result' => array(
        'device_state' => 'RUNNING'
    )
);

9.9 SATE

使用 API Template：

device_action_result

模板：

{
    "type": "{{type}}",
    "target": "{{target}}",
    "action": "{{action}}",
    "state": "{{state}}",
    "result": {
        "device_state": "{{result.device_state}}"
    }
}

SATE 完成数据映射。

9.10 ApiRenderer

ApiRenderer 将模板结果转换成 JSON：

{
    "type": "ACTION_RESULT",
    "target": "Motor_A",
    "action": "START",
    "state": "SUCCESS",
    "result": {
        "device_state": "RUNNING"
    }
}

9.11 API Response

最终：

HTTP/1.1 200 OK
Content-Type: application/json

Body：

{
    "type": "ACTION_RESULT",
    "target": "Motor_A",
    "action": "START",
    "state": "SUCCESS",
    "result": {
        "device_state": "RUNNING"
    }
}

外部系统收到：

Request
   ↓
API Controller
   ↓
Central
   ↓
Individual
   ↓
Decision
   ↓
Action
   ↓
ActionResult
   ↓
Expression
   ↓
SATE
   ↓
ApiRenderer
   ↓
JSON Response

本章核心模型

第82章把前面的 ICAI、Decision、Action、Expression、SATE、ApiRenderer 正式连接成 API 通信链路：

                 External System
                       │
                       ↓
                  API Request
                       │
                       ↓
                 API Controller
                       │
                       ↓
                    Central
                       │
                       ↓
                  Individual
                       │
             ┌─────────┴─────────┐
             ↓                   ↓
         Cognition             Memory
             ↓
         Reasoning
             ↓
          Decision
             ↓
          Behavior
             ↓
           Action
             ↓
       External Device/System
             ↓
        ActionResult
             ↓
         Expression
             ↓
            SATE
             ↓
        Api Template
             ↓
        ApiRenderer
             ↓
        JSON Response
             │
             ↓
       External System

核心职责

API
    = SAI 与外部系统的接口

API Information
    = 进入 SAI 的结构化信息

API Controller
    = API 请求控制

Central
    = 中央协调

Individual
    = 个体认知运行

Decision
    = 决定是否以及采取什么行动

Action
    = 执行具体操作

Expression
    = 内部结果的外部表现结构

SATE
    = 按模板组织输出

ApiRenderer
    = 转换为 API 表现格式

JSON Response
    = 返回外部系统的结构化结果

最终可以形成一个非常清晰的边界：

外部系统
    ↓
API
    ↓
SAI 接口层
    ↓
Central
    ↓
ICAI Individual
    ↓
认知 / 理解 / 推理
    ↓
Decision
    ↓
Action
    ↓
Expression
    ↓
SATE
    ↓
ApiRenderer
    ↓
JSON
    ↓
API
    ↓
外部系统

其中 API 只是通信接口，JSON 只是数据表现格式；真正的认知、推理、决策和行动仍然属于 SAI/ICAI 内部。

第82章 SAI + API

第82章 SAI + API

本章大纲

1. API 接口

2. API Information

3. API Controller

4. Central

5. Individual

6. Decision

7. Action

8. JSON Response

9. 完整 API 案例

9.1 外部系统发送 Request

9.2 API Controller

9.3 Central

9.4 Individual

9.5 Decision

9.6 Action

9.7 ActionResult

9.8 Expression

9.9 SATE

9.10 ApiRenderer

9.11 API Response

本章核心模型

核心职责