第107章　如何开发 SAI Object

第106章建立了 SAI Engine。

Engine 解决的是：

一个具体功能如何接收 Input、执行 Processing、产生 Result。

但是，Engine 处理的并不只是孤立的数据。

SAI 需要对现实世界中的：

机器人
设备
人员
道路
障碍物
传感器
机器
订单
任务
文件
系统

进行统一的结构化表示。

因此需要 SAI Object。

本章解决的问题是：

如何定义一个 Object，并为 Object 建立 Property、Method、Relation、State，以及如何通过 ObjectManager 和 ObjectRegistry 对 Object 进行统一管理。

核心结构：

Object
├── Property
├── Method
├── Relation
└── State

管理结构：

Object
 ↓
Object Registration
 ↓
Object Manager
 ↓
Object Runtime

1. Object Interface

1.1 Object 定义

SAI Object 是 Individual 对一个实体进行结构化表示后的基本对象。

例如：

Robot_A
Machine_A
Obstacle_A
Sensor_A
Road_A
Person_A

Object 本身具有：

Identity
Property
Method
Relation
State

可以表示为：

Object =
Identity
+
Properties
+
Methods
+
Relations
+
State

1.2 ObjectInterface

首先定义统一 Interface。

<?php

interface ObjectInterface
{
    public function getId();

    public function getName();

    public function getType();

    public function getState();

    public function setState($state);

    public function getProperty($name);

    public function setProperty($name, $value);

    public function addRelation($relation);

    public function getRelations();

    public function executeMethod($name, $parameters = array());
}

1.3 Interface 的作用

有了统一 Interface，系统就可以用相同的方法管理不同 Object：

Robot Object
Machine Object
Device Object
Obstacle Object
Sensor Object

例如：

$object->getState();

$object->getProperty('speed');

$object->setProperty('speed', 1.2);

上层系统不需要知道 Object 内部的具体实现。

2. Property

2.1 Property 定义

Property 是 Object 的属性。

例如：

Robot_A

具有：

speed = 1.2
battery = 76
direction = NORTH

这些都是 Property。

2.2 Property 结构

一个完整 Property 可以包含：

Property
├── name
├── value
├── type
├── unit
├── writable
├── readable
└── state

例如：

$property = array(
    'name' => 'speed',
    'value' => 1.2,
    'type' => 'FLOAT',
    'unit' => 'm/s',
    'writable' => true,
    'readable' => true,
    'state' => 'ACTIVE'
);

2.3 Property 类型

可以定义：

STRING
INTEGER
FLOAT
BOOLEAN
DATE
TIME
DATETIME
ARRAY
OBJECT
LOCATION
STATE
RELATION

例如：

Robot_A
│
├── speed → FLOAT
├── battery → INTEGER
├── active → BOOLEAN
├── position → LOCATION
└── state → STATE

2.4 Property 不等于 State

例如：

speed = 1.2

是 Property。

state = MOVING

是 State。

两者有关联：

speed > 0
        ↓
可能表示
        ↓
MOVING

但不能简单认为：

Property = State

3. Method

3.1 Method 定义

Method 是 Object 可以执行的操作。

例如 Robot：

MOVE
STOP
TURN_LEFT
TURN_RIGHT

这些是 Method。

3.2 Method 结构

Method
├── name
├── parameters
├── return_type
├── state
└── permissions

例如：

$method = array(
    'name' => 'setSpeed',

    'parameters' => array(
        'speed'
    ),

    'return_type' => 'BOOLEAN',

    'state' => 'ACTIVE'
);

3.3 Property 与 Method

可以简单理解为：

Property = Object 有什么

Method = Object 能做什么

例如：

Robot_A
│
├── Property
│   ├── speed = 1.2
│   ├── battery = 76
│   └── direction = NORTH
│
└── Method
    ├── move()
    ├── stop()
    └── turn()

4. Relation

4.1 Relation 定义

Relation 描述 Object 与其他 Object 之间的关系。

例如：

Robot_A
   ↓
FRONT_OF
   ↓
Obstacle_A

又例如：

Robot_A
   ↓
LOCATED_ON
   ↓
Road_A

4.2 Relation 结构

$relation = array(
    'id' => 'Relation_001',

    'source' => 'Robot_A',

    'type' => 'FRONT_OF',

    'target' => 'Obstacle_A',

    'state' => 'ACTIVE'
);

4.3 常见 Relation

可以定义：

FRONT_OF
BEHIND
NEAR
FAR
LEFT_OF
RIGHT_OF
ABOVE
BELOW
INSIDE
CONTAINS
PART_OF
LOCATED_ON
CONNECTED_TO
DEPENDS_ON
CONTROLS
OWNED_BY

4.4 Relation 是 Object 之间的连接

例如：

Robot_A
    │
    ├── FRONT_OF ───→ Obstacle_A
    │
    ├── LOCATED_ON ─→ Road_A
    │
    └── CONNECTED_TO → Sensor_A

这样多个 Object 可以组成结构化关系网络。

这里的“网络”是对象和关系的离散结构，不是神经网络。

5. State

5.1 State 定义

State 表示 Object 当前处于什么状态。

例如 Robot：

OFF
READY
MOVING
STOPPED
ERROR

5.2 State 与 Property

例如：

Robot_A

当前：

speed = 1.2
state = MOVING

其中：

speed → Property
MOVING → State

5.3 State 生命周期

Object State 可以设计为：

NEW
 ↓
INITIALIZING
 ↓
READY
 ↓
ACTIVE
 ↓
INACTIVE
 ↓
ARCHIVED

异常：

ERROR
CONFLICT
UNKNOWN
INVALID

不同类型 Object 可以拥有自己的状态集合。

例如 Robot：

OFF
INITIALIZING
READY
MOVING
PAUSED
STOPPING
STOPPED
ERROR
DISCONNECTED

6. Object Manager

6.1 ObjectManager 定义

如果系统中只有一个 Object：

$robot = new RobotObject();

还比较简单。

但是一个真正的 SAI 可能同时存在：

Robot_A
Robot_B
Sensor_A
Sensor_B
Obstacle_A
Obstacle_B
Road_A
Machine_A

因此需要 ObjectManager。

6.2 ObjectManager 基本功能

ObjectManager 负责：

Register
Get
Remove
Exists
Find
Update
Count

它负责管理 Object。

不负责：

Cognition
Reasoning
Decision
Learning

6.3 ObjectManager 示例

<?php

class ObjectManager
{
    protected $objects = array();

    public function register(ObjectInterface $object)
    {
        $this->objects[$object->getId()] = $object;

        return true;
    }

    public function get($id)
    {
        if (!isset($this->objects[$id])) {
            return null;
        }

        return $this->objects[$id];
    }

    public function exists($id)
    {
        return isset($this->objects[$id]);
    }

    public function remove($id)
    {
        if (!$this->exists($id)) {
            return false;
        }

        unset($this->objects[$id]);

        return true;
    }

    public function count()
    {
        return count($this->objects);
    }

    public function all()
    {
        return $this->objects;
    }
}

7. Object Registration

7.1 Object Registry

ObjectManager 管理运行中的 Object。

Registry 则记录 Object 的注册信息。

例如：

$registry = array(
    'robot_a' => array(
        'id' => 'robot_a',
        'name' => 'Robot A',
        'type' => 'robot',
        'class' => 'RobotObject',
        'path' => 'objects/RobotObject.php',
        'enabled' => true,
        'state' => 'REGISTERED'
    )
);

7.2 Registry 与 Manager

两者不能混淆。

Object Registry
=
系统登记了哪些 Object

Object Manager
=
当前运行环境中管理哪些 Object

例如：

Registry
│
├── Robot_A
├── Robot_B
├── Sensor_A
└── Machine_A

当前运行：

ObjectManager
│
├── Robot_A
└── Sensor_A

因此：

Registered ≠ Loaded
Loaded ≠ Running

7.3 Object Registration 流程

Object Definition
        ↓
Registry
        ↓
File Check
        ↓
Class Check
        ↓
Interface Check
        ↓
Create Object
        ↓
ObjectManager
        ↓
Object Runtime

8. 完整 Object 示例

现在创建一个简单的：

RobotObject

它具有：

Identity
Property
Method
Relation
State

8.1 ObjectInterface.php

<?php

interface ObjectInterface
{
    public function getId();

    public function getName();

    public function getType();

    public function getState();

    public function setState($state);

    public function getProperty($name);

    public function setProperty($name, $value);

    public function addRelation($relation);

    public function getRelations();

    public function executeMethod($name, $parameters = array());
}

8.2 RobotObject.php

<?php

require_once 'ObjectInterface.php';

class RobotObject implements ObjectInterface
{
    protected $id = 'Robot_A';

    protected $name = 'Robot A';

    protected $type = 'robot';

    protected $state = 'READY';

    protected $properties = array(
        'speed' => 0,
        'battery' => 100,
        'direction' => 'NORTH'
    );

    protected $methods = array(
        'move',
        'stop',
        'turnLeft',
        'turnRight'
    );

    protected $relations = array();

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

    public function getName()
    {
        return $this->name;
    }

    public function getType()
    {
        return $this->type;
    }

    public function getState()
    {
        return $this->state;
    }

    public function setState($state)
    {
        $this->state = $state;

        return true;
    }

    public function getProperty($name)
    {
        if (!isset($this->properties[$name])) {
            return null;
        }

        return $this->properties[$name];
    }

    public function setProperty($name, $value)
    {
        $this->properties[$name] = $value;

        return true;
    }

    public function addRelation($relation)
    {
        $this->relations[] = $relation;

        return true;
    }

    public function getRelations()
    {
        return $this->relations;
    }

    public function executeMethod($name, $parameters = array())
    {
        if (!in_array($name, $this->methods)) {
            return array(
                'state' => 'INVALID_METHOD'
            );
        }

        switch ($name) {

            case 'move':

                $this->state = 'MOVING';

                if (isset($parameters['speed'])) {
                    $this->properties['speed'] =
                        $parameters['speed'];
                }

                return array(
                    'state' => 'SUCCESS',
                    'action' => 'MOVE',
                    'speed' => $this->properties['speed']
                );

            case 'stop':

                $this->properties['speed'] = 0;

                $this->state = 'STOPPED';

                return array(
                    'state' => 'SUCCESS',
                    'action' => 'STOP'
                );

            case 'turnLeft':

                $this->properties['direction'] = 'WEST';

                return array(
                    'state' => 'SUCCESS',
                    'action' => 'TURN_LEFT'
                );

            case 'turnRight':

                $this->properties['direction'] = 'EAST';

                return array(
                    'state' => 'SUCCESS',
                    'action' => 'TURN_RIGHT'
                );
        }

        return array(
            'state' => 'UNKNOWN'
        );
    }
}

9. 注册 Robot Object

建立：

index.php

<?php

require_once 'RobotObject.php';
require_once 'ObjectManager.php';

$manager = new ObjectManager();

$robot = new RobotObject();

$manager->register($robot);

echo "Object ID: ";
echo $robot->getId();
echo "\n";

echo "Object Name: ";
echo $robot->getName();
echo "\n";

echo "Object Type: ";
echo $robot->getType();
echo "\n";

echo "Object State: ";
echo $robot->getState();
echo "\n";

结果：

Object ID:
Robot_A

Object Name:
Robot A

Object Type:
robot

Object State:
READY

10. 设置 Property

$robot->setProperty('speed', 1.2);

$robot->setProperty('battery', 76);

读取：

echo $robot->getProperty('speed');

得到：

1.2

此时：

Robot_A
│
├── speed = 1.2
├── battery = 76
└── direction = NORTH

11. 添加 Relation

加入障碍物：

Obstacle_A

建立关系：

$robot->addRelation(
    array(
        'source' => 'Robot_A',
        'type' => 'FRONT_OF',
        'target' => 'Obstacle_A',
        'state' => 'ACTIVE'
    )
);

结果：

Robot_A
     │
     │ FRONT_OF
     ↓
Obstacle_A

再建立道路关系：

$robot->addRelation(
    array(
        'source' => 'Robot_A',
        'type' => 'LOCATED_ON',
        'target' => 'Road_A',
        'state' => 'ACTIVE'
    )
);

形成：

Robot_A
│
├── FRONT_OF → Obstacle_A
│
└── LOCATED_ON → Road_A

12. 执行 Method

现在 Robot Object 可以执行自己的 Method。

$result = $robot->executeMethod(
    'move',
    array(
        'speed' => 1.2
    )
);

print_r($result);

得到：

state  = SUCCESS
action = MOVE
speed  = 1.2

Object 状态：

READY
 ↓
MOVING

停止

$result = $robot->executeMethod('stop');

print_r($result);

结果：

state  = SUCCESS
action = STOP

Robot：

MOVING
 ↓
STOPPED

13. Object 与 Action

这里需要特别区分 Object Method 与 SAI Action。

例如：

Decision
 ↓
Behavior
 ↓
Action
 ↓
RobotAdapter
 ↓
Robot

Action：

SET_SPEED = 0

RobotAdapter 最终可能调用 Robot Object 对应的 Method：

setSpeed()

因此：

Action = 当前具体操作
Method = Object 提供的操作能力

例如：

Action:
STOP

Method:
stop()

Action 不等于 Method。

14. Object 与 Cognition

Object 本身不等于 Cognition。

例如：

Robot_A
speed = 1.2
state = MOVING

这是 Object 状态。

Perception 获取：

speed = 1.2

Cognition 理解：

Robot_A is moving

Reasoning：

Obstacle distance < 1.0
AND
Robot_A is moving

→ risk HIGH

Decision：

STOP

因此：

Object
 ↓
提供结构
 ↓
Perception
 ↓
Cognition
 ↓
Reasoning
 ↓
Decision

Object 不应该自己承担整个 SAI 的认知流程。

15. Object 的完整结构

一个成熟的 SAI Object 可以逐渐扩展为：

Object
│
├── Identity
│
├── Properties
│
├── Methods
│
├── Relations
│
├── State
│
├── Abilities
│
├── Conditions
│
├── Events
│
├── History
│
└── Metadata

例如 Robot：

Robot_A
│
├── Identity
│
├── Properties
│   ├── speed
│   ├── battery
│   └── position
│
├── Methods
│   ├── move()
│   ├── stop()
│   └── turn()
│
├── Relations
│   ├── FRONT_OF
│   └── LOCATED_ON
│
├── State
│   └── MOVING
│
├── Abilities
│   ├── MOVE
│   └── STOP
│
└── History

本章核心定义

Object

SAI 对一个实体进行结构化表示后的基本对象。

Property

Object 所具有的属性、数据和值。

Method

Object 可以执行的操作或功能。

Relation

Object 与其他 Object 之间的结构化关系。

State

Object 当前所处的状态。

ObjectManager

对运行环境中的 Object 进行注册、获取、删除、查询和管理的组件。

ObjectRegistry

记录 Object 身份、Class、路径、版本、状态和配置的注册结构。

本章最终模型

                    Object
                       │
          ┌────────────┼────────────┐
          ↓            ↓            ↓
       Property      Method       Relation
          │            │            │
          └────────────┼────────────┘
                       ↓
                     State

Object 的基本定义可以进一步表示为：

Object =
Identity
+
Property
+
Method
+
Relation
+
State

管理流程：

Object Definition
       ↓
Object Registry
       ↓
Registration
       ↓
Loading
       ↓
ObjectManager
       ↓
Object Runtime

与 SAI 的关系：

Information
     ↓
Perception
     ↓
Object
     ↓
Property + State + Relation
     ↓
Cognition
     ↓
Reasoning
     ↓
Decision
     ↓
Behavior
     ↓
Action
     ↓
Object Method / Adapter

因此，第107章完成了一个重要的基础层：

SAI 不再只处理抽象的 Input 和 Result，而开始拥有能够表示现实实体的 Object 结构。

最终形成：

SAI Framework
│
├── Individual
│
├── Module
│
├── Engine
│
├── Object
│   ├── Property
│   ├── Method
│   ├── Relation
│   └── State
│
├── Memory
├── Event
├── Task
├── Adapter
└── Renderer

其中 Object 是连接“世界信息”与“SAI 内部认知结构”的重要基础单位。

第107章 如何开发 SAI Object

第107章 如何开发 SAI Object

1. Object Interface

1.1 Object 定义

1.2 ObjectInterface

1.3 Interface 的作用

2. Property

2.1 Property 定义

2.2 Property 结构

2.3 Property 类型

2.4 Property 不等于 State

3. Method

3.1 Method 定义

3.2 Method 结构

3.3 Property 与 Method

4. Relation

4.1 Relation 定义

4.2 Relation 结构

4.3 常见 Relation

4.4 Relation 是 Object 之间的连接

5. State

5.1 State 定义

5.2 State 与 Property

5.3 State 生命周期

6. Object Manager

6.1 ObjectManager 定义

6.2 ObjectManager 基本功能

6.3 ObjectManager 示例

7. Object Registration

7.1 Object Registry

7.2 Registry 与 Manager

7.3 Object Registration 流程

8. 完整 Object 示例

8.1 ObjectInterface.php

8.2 RobotObject.php

9. 注册 Robot Object

10. 设置 Property

11. 添加 Relation

12. 执行 Method

停止

13. Object 与 Action

14. Object 与 Cognition

15. Object 的完整结构

本章核心定义

Object

Property

Method

Relation

State

ObjectManager

ObjectRegistry

本章最终模型