第267章　State API｜状态 API

267.1 提出背景

在 ICAI 机器认知工程中，机器对现实世界的认识不能停留在“有什么对象、对象有什么属性、对象之间有什么关系”。

系统还必须回答一个更加重要的问题：

对象当前处于什么状态？

例如，同一个鸡蛋对象，在不同时间可能处于：

静止
↓
接近
↓
接触
↓
受力
↓
抓取
↓
移动
↓
释放
↓
静止

对象本身没有发生身份变化：

Object = Egg-001

但是对象的属性、关系以及状态不断发生变化。

因此，ICAI 需要建立一个专门负责状态形成、状态计算、状态更新、状态查询、状态历史以及状态变化传播的工程接口。

这个接口就是 State API（状态 API）。

前面的工程链：

Element API
↓
Element
↓
Object API
↓
Object
↓
Attribute API
↓
Attribute
↓
Relation API
↓
Relation

进入 State API 后形成：

Element
↓
Object
↓
Attribute
+
Relation
↓
State
↓
Scene
↓
Cognition

因此：

State API 是 ICAI 机器认知系统中负责对象当前状态形成、计算、更新、验证、查询和传播的标准工程接口，是从对象动态结构进入场景和认知的重要工程层。

267.2 State API 的定义

State API 是 ICAI 系统针对 Object State（对象状态）建立的标准工程接口。

对象状态可以定义为：

$St=F(At,Rt,Ct,Et)S_t=F(A_t,R_t,C_t,E_t)$

其中：

$StS_t$ ：对象在时间 $tt$ 的状态；
$AtA_t$ ：对象在时间 $tt$ 的属性；
$RtR_t$ ：对象在时间 $tt$ 的关系；
$CtC_t$ ：对象类别及其状态条件；
$EtE_t$ ：当前环境条件。

在简单情况下，可以表示为：

$St=F(At,Rt)S_t=F(A_t,R_t)$

例如：

Force = 0
Velocity = 0
Touch = false

可以形成：

State = Stable

当：

Force > 0
Velocity > 0
Touch = true

则状态可能变为：

State = Moving

因此状态并不是简单的数据字段，而是由当前对象结构计算得到的运行时认知结构。

267.3 State API 的核心目的

State API 的核心目的不是简单保存：

state = "stable"

而是建立：

Attribute
+
Relation
+
Condition
+
Time
↓
State

的工程机制。

它主要解决：

当前对象处于什么状态？
↓
状态由什么条件形成？
↓
状态什么时候发生？
↓
状态如何变化？
↓
状态是否有效？
↓
状态变化如何影响场景？
↓
状态变化如何影响认知？

因此：

Attribute API
+
Relation API
↓
State API
↓
Scene API
↓
Cognition API

构成连续的机器认知结构链。

267.4 状态不是属性

Attribute 与 State 在 ICAI 中必须严格区分。

Attribute 描述对象具有的特征：

Mass = 0.06kg
Position = (120,80,50)
Velocity = (0,0,10)
Force = 2.3N
Temperature = 25℃

State 描述对象当前所处的状态：

Stable
Moving
Contact
Grasping
Falling
Stopped
Broken

因此：

Attribute
=
对象具有的数据特征

State
=
对象当前处于的状态

两者存在因果关系：

Attribute
+
Relation
+
Condition
↓
State

而不是：

Attribute = State

267.5 状态形成

状态形成是 State API 的核心逻辑。

例如：

Velocity = 0
Force = 0
Relation = None

经过状态规则：

Velocity == 0
AND
Force == 0
↓
Stable

又例如：

Velocity > 0
↓
Moving

又例如：

Touch(Hand, Object)
+
Force > 0
↓
Contact

因此可以定义：

$S=Rule(A,R,C)S=Rule(A,R,C)$

其中：

$AA$ ：属性集合；
$RR$ ：关系集合；
$CC$ ：状态判断条件；
$SS$ ：状态结果。

这是一种离散规则形式的状态计算。

267.6 状态条件

State Condition（状态条件）用于描述状态成立所需要满足的条件。

例如：

Stable
Condition:
Velocity = 0

Moving
Condition:
Velocity ≠ 0

Contact
Condition:
Distance ≤ d

其中 $dd$ 是接触距离阈值。

再例如：

Grasping
Condition:
Touch = true
AND
Force > F_min

其中 $FminF_{min}$ 是最小抓取力量。

因此：

$Condition(S)=TrueCondition(S)=True$

表示状态 $SS$ 当前成立。

多个条件可以组合：

$C=C1∧C2∧C3C=C_1\land C_2\land C_3$

其中：

$C1C_1$ ：条件一；
$C2C_2$ ：条件二；
$C3C_3$ ：条件三。

只有全部满足时：

$C=TrueC=True$

对应状态才能成立。

267.7 状态转换

对象状态不是固定的。

定义：

$St→St+1S_t\rightarrow S_{t+1}$

例如：

Stable
↓
Moving
↓
Contact
↓
Grasping
↓
Moving
↓
Released
↓
Stable

状态转换可以定义为：

$St+1=T(St,At,Rt,Ct)S_{t+1}=T(S_t,A_t,R_t,C_t)$

其中：

$StS_t$ ：当前状态；
$AtA_t$ ：当前属性；
$RtR_t$ ：当前关系；
$CtC_t$ ：状态转换条件；
$TT$ ：状态转换函数；
$St+1S_{t+1}$ ：下一状态。

因此状态系统具有时间结构。

267.8 状态更新

实时数据发生变化后，State API 需要重新计算对象状态。

例如：

t1
Velocity = 0
↓
State = Stable

新的 Element 到达：

t2
Velocity = 10
↓
Attribute Update
↓
State Calculation
↓
State = Moving

因此：

$At→At+1A_t\rightarrow A_{t+1}$

进一步：

$St→St+1S_t\rightarrow S_{t+1}$

形成：

New Element
↓
Attribute Update
↓
Relation Update
↓
State Update

状态不是独立变化，而是由底层对象结构变化驱动。

267.9 状态历史

动态认知系统不能只知道当前状态，还需要知道状态变化过程。

例如：

t1 → Stable
t2 → Moving
t3 → Contact
t4 → Grasping
t5 → Moving
t6 → Released

可以形成 State History（状态历史）：

$HS={(t1,S1),(t2,S2),…,(tn,Sn)}H_S=\{(t_1,S_1),(t_2,S_2),\ldots,(t_n,S_n)\}$

其中：

$tit_i$ ：状态发生的时间；
$SiS_i$ ：对应时间的状态。

状态历史可以用于：

状态变化追踪
行为过程分析
动作结果判断
反馈处理

因此：

Current State
+
State History

共同构成对象的动态状态信息。

267.10 状态变化事件

状态发生变化时，可以产生 State Event（状态事件）。

例如：

State Created
State Changed
State Activated
State Deactivated
State Recovered

例如：

Stable
↓
Moving

产生：

StateChanged
Old = Stable
New = Moving

事件进一步进入：

State Event
↓
Scene Engine
↓
Cognitive Engine

因此：

Attribute Change
↓
State Change
↓
State Event
↓
Scene Update
↓
Cognition Update

这使状态成为整个动态认知系统中的重要变化节点。

267.11 状态与关系

某些状态必须由 Relation 决定。

例如：

Hand
↓
Touch
↓
Egg

如果同时：

Force > F_min

则：

State = Grasping

因此：

$St=F(At,Rt,Ct)S_t=F(A_t,R_t,C_t)$

如果 Relation 从：

Near

变为：

Touch

那么状态可能从：

Approaching

变为：

Contact

因此：

Relation Change
↓
State Change

是 ICAI 动态场景的重要结构。

267.12 状态与属性向量

对象当前多个属性可以形成 Attribute Vector：

$Xt=[PositionVelocityForcePressureDistanceStability]X_t= \begin{bmatrix} Position\\ Velocity\\ Force\\ Pressure\\ Distance\\ Stability \end{bmatrix}$

状态可以表示为：

$St=F(Xt,Rt)S_t=F(X_t,R_t)$

例如：

X_t
↓
Position
Velocity
Force
Pressure
Stability
↓
State Function
↓
Current State

这种方式使状态计算可以建立在统一的数学数据结构上。

例如：

Velocity = 0
Force = 0
Stability = 1

对应：

Stable

而：

Velocity > 0
Stability = 1

对应：

Moving

因此 Attribute Vector 是 State API 的重要计算输入。

267.13 状态与离散时间

ICAI 的运行系统可以采用离散时间模型。

定义：

$t0,t1,t2,…,tnt_0,t_1,t_2,\ldots,t_n$

每个运行周期获得新的数据：

t0
↓
Data
↓
State

t1
↓
Data
↓
State

t2
↓
Data
↓
State

因此：

$St+1=F(St,Xt)S_{t+1}=F(S_t,X_t)$

其中：

$StS_t$ ：当前状态；
$XtX_t$ ：当前属性向量；
$FF$ ：状态更新函数；
$St+1S_{t+1}$ ：下一时刻状态。

这种离散状态模型非常适合工程软件实现。

在 PHP 运行环境中，不需要把连续世界直接转换成连续数学过程，而可以按照系统的实时更新周期逐步计算。

267.14 状态与动态行为

Behavior（行为）需要知道对象当前状态。

例如：

Goal = Grasp
Object = Egg
State = Stable

系统可以产生：

Approach

当：

State = Contact

则行为进入：

Grasp

当：

State = Grasping

则行为进入：

Lift

因此：

Goal
+
Object
+
State
↓
Behavior

可以表示为：

$Bt=F(Gt,Ot,St)B_t=F(G_t,O_t,S_t)$

更加完整时：

$Bt=F(Gt,Ot,At,Rt,St,Sct)B_t=F(G_t,O_t,A_t,R_t,S_t,Sc_t)$

因此 State API 为行为系统提供了当前对象状态。

267.15 状态与方法

Method（方法）也可以根据当前状态选择不同的执行逻辑。

例如：

State = Stable
↓
Approach Method

State = Contact
↓
Grasp Method

State = Grasping
↓
Lift Method

因此：

$Mt=F(Gt,Ot,St)M_t=F(G_t,O_t,S_t)$

其中：

$MtM_t$ ：当前方法；
$GtG_t$ ：目标；
$OtO_t$ ：对象；
$StS_t$ ：当前状态。

这样方法不是固定地执行，而是根据当前动态状态进入不同的处理阶段。

267.16 State API 与 Scene API

对象状态是场景状态的重要组成部分。

定义：

$Sct=F(Ot,At,Rt,St,Et,Pt,Tt)Sc_t=F(O_t,A_t,R_t,S_t,E_t,P_t,T_t)$

其中：

$OtO_t$ ：对象集合；
$AtA_t$ ：属性集合；
$RtR_t$ ：关系集合；
$StS_t$ ：状态集合；
$EtE_t$ ：环境；
$PtP_t$ ：空间；
$TtT_t$ ：时间。

因此：

Object State
↓
Scene State

例如：

Egg = Stable
Hand = Moving
Robot = Active
Table = Stable

共同形成当前场景状态。

当：

Egg = Stable

变成：

Egg = Grasping

整个 Scene Model 也需要更新。

267.17 State API 与 Cognitive API

Cognition（认知）依赖当前状态。

可以表示：

$Ct=F(Gt,Ot,At,Rt,St,Sct)C_t=F(G_t,O_t,A_t,R_t,S_t,Sc_t)$

因此：

State API
↓
Current State
↓
Cognitive Model
↓
Cognition

例如：

Goal = Pick Up Egg
+
Object = Egg
+
State = Stable

与：

Goal = Pick Up Egg
+
Object = Egg
+
State = Broken

产生的认知结果可能完全不同。

所以，State 是认知计算的重要输入。

267.18 State API 的状态查询

State API 应当能够支持当前状态查询。

例如：

GET
/api/objects/O1001/state

{
    "object_id": "O1001",
    "state": "grasping",
    "timestamp": "2026-09-04 10:00:00"
}

也可以查询状态历史：

GET
/api/objects/O1001/state/history

{
    "object_id": "O1001",
    "history": [
        {
            "state": "stable",
            "timestamp": "t1"
        },
        {
            "state": "contact",
            "timestamp": "t2"
        },
        {
            "state": "grasping",
            "timestamp": "t3"
        }
    ]
}

JSON 只是状态数据的交换形式。

真正的状态计算仍然发生在 ICAI Runtime 内部。

267.19 State API 的接口

State API 可以提供：

/api/state/create
/api/state/get
/api/state/update
/api/state/delete
/api/state/list
/api/state/current
/api/state/history
/api/state/transition
/api/state/validate

也可以采用对象资源形式：

/api/objects/{object_id}/state
/api/objects/{object_id}/state/history
/api/objects/{object_id}/state/transitions

其工程意义分别对应：

Create
↓
建立状态

Current
↓
获取当前状态

Update
↓
更新状态

History
↓
获取状态历史

Transition
↓
获取状态转换

Validate
↓
验证状态

267.20 State Engine

在 PHP OOP 工程中，可以建立 StateEngine：

class StateEngine
{
    public function calculate($attributes, $relations)
    {
        $velocity = isset($attributes['velocity'])
            ? $attributes['velocity']
            : 0;

        $force = isset($attributes['force'])
            ? $attributes['force']
            : 0;

        if ($velocity == 0 && $force == 0) {
            return 'stable';
        }

        if ($velocity != 0) {
            return 'moving';
        }

        if ($force > 0) {
            return 'contact';
        }

        return 'unknown';
    }
}

这个例子只是说明工程结构。

实际系统可以将状态条件、状态转换和状态类型进一步独立为规则对象。

其基本运行：

Attributes
+
Relations
↓
State Engine
↓
State Rules
↓
Current State

267.21 State Model

可以建立 StateModel：

class StateModel
{
    protected $objectId;
    protected $state;
    protected $previousState;
    protected $timestamp;
    protected $source;

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

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

    public function getPreviousState()
    {
        return $this->previousState;
    }
}

这样可以直接表达：

Previous State
↓
Current State

例如：

Stable
↓
Moving

系统可以明确知道：

Previous = Stable
Current = Moving

而不是只保存一个：

state = Moving

267.22 State Controller

StateApiController 负责接收外部状态 API 请求：

class StateApiController
{
    protected $service;

    public function current($objectId)
    {
        return $this->service->getCurrentState($objectId);
    }

    public function history($objectId)
    {
        return $this->service->getHistory($objectId);
    }
}

运行结构：

HTTP Request
↓
StateApiController
↓
StateService
↓
StateEngine
↓
StateModel
↓
StateRepository
↓
MySQL

保持与前面的 API 工程结构一致。

267.23 State API 与数据库

状态可以存储于：

cognitive_states

基本字段：

id
object_id
state_type
state_value
previous_state
source
timestamp
created_at
updated_at

状态历史可以保存每一次状态变化：

cognitive_state_history

例如：

Object O1001

t1 → Stable
t2 → Moving
t3 → Contact
t4 → Grasping
t5 → Moving
t6 → Released

数据库负责状态持久化。

StateEngine 负责状态计算。

State API 负责外部通信。

三者保持工程边界：

State API
↓
State Engine
↓
State Model
↓
Repository
↓
Database

267.24 State API 的验证

状态必须满足定义条件。

可以定义：

$Valid(S)=Valid(Object)∧Valid(StateType)∧Valid(Time)Valid(S)=Valid(Object)\land Valid(StateType)\land Valid(Time)$

其中：

$Valid(Object)Valid(Object)$ ：对象存在；
$Valid(StateType)Valid(StateType)$ ：状态类型合法；
$Valid(Time)Valid(Time)$ ：时间有效。

如果状态转换也具有明确条件，则：

$Valid(St→St+1)=TransitionRule(St,St+1,At,Rt)Valid(S_t\rightarrow S_{t+1})=TransitionRule(S_t,S_{t+1},A_t,R_t)$

即状态转换必须满足相应规则。

例如：

Stable
↓
Grasping

如果没有：

Touch
+
Force

则系统可以判定该转换不满足条件。

因此状态 API 不只是存储结果，也可以维护状态转换的有效性。

267.25 状态转换表

为了便于工程实现，可以定义状态转换规则。

例如：

Current State    Condition          Next State

Stable           Velocity > 0       Moving

Moving           Distance <= d      Contact

Contact          Force > F_min      Grasping

Grasping         Lift = true        Moving

Grasping         Release = true     Released

Released         Velocity = 0       Stable

其本质是：

$St+1=T(St,Ct)S_{t+1}=T(S_t,C_t)$

其中：

$StS_t$ ：当前状态；
$CtC_t$ ：当前条件；
$TT$ ：状态转换函数；
$St+1S_{t+1}$ ：下一状态。

这种状态转换结构可以直接转化为 PHP 中的规则对象、条件对象和状态引擎。

267.26 State API 与反馈闭环

设备执行动作以后，世界发生变化。

例如：

Action
↓
Device
↓
Egg Movement
↓
Sensor
↓
Element
↓
Attribute Update
↓
Relation Update
↓
State Update
↓
Scene Update
↓
Re-Cognition

因此：

$St→Action→Worldt+1→St+1S_t\rightarrow Action\rightarrow World_{t+1}\rightarrow S_{t+1}$

形成状态反馈闭环。

完整结构：

Cognition
↓
Behavior
↓
Action
↓
Device
↓
World
↓
Sensor
↓
Element API
↓
Object API
↓
Attribute API
↓
Relation API
↓
State API
↓
Scene
↓
Re-Cognition

状态因此成为“行动之后世界发生了什么变化”的重要机器表示。

267.27 State API 的核心工程价值

State API 的核心价值，不是保存一个状态字段，而是建立：

Attribute
+
Relation
+
Condition
+
Time
↓
State

的统一工程机制。

这样 ICAI 可以区分：

Object
↓
它是什么

Attribute
↓
它有什么

Relation
↓
它与什么发生关系

State
↓
它现在处于什么状态

这四层结构共同构成机器对象的动态描述：

$Ot=F(I,C,At,Rt,St,Pt,Tt)O_t=F(I,C,A_t,R_t,S_t,P_t,T_t)$

因此对象从静态对象进一步成为动态对象。

267.28 本章总结

第267章建立了 State API 的工程定义。

State API 是 ICAI 系统中负责对象状态形成、计算、更新、查询、验证、历史管理和状态变化传播的标准工程接口。

状态定义为：

$St=F(At,Rt,Ct,Et)S_t=F(A_t,R_t,C_t,E_t)$

其中：

$AtA_t$ ：当前属性；
$RtR_t$ ：当前关系；
$CtC_t$ ：状态条件；
$EtE_t$ ：环境；
$StS_t$ ：当前状态。

状态具有时间变化：

$St→St+1S_t\rightarrow S_{t+1}$

并可以通过状态转换函数：

$St+1=T(St,At,Rt,Ct)S_{t+1}=T(S_t,A_t,R_t,C_t)$

实现动态状态更新。

因此 ICAI 的对象工程结构进一步形成：

Element API
↓
Element
↓
Object API
↓
Object
↓
Attribute API
↓
Attribute
↓
Relation API
↓
Relation
↓
State API
↓
State
↓
Scene API
↓
Scene
↓
Cognition API
↓
Cognition

前三个 API 解决：

Element
↓
Object
↓
Attribute

第266章增加：

Relation

第267章进一步形成：

Attribute
+
Relation
+
Condition
↓
State

因此，机器对象已经从单纯的：

Object

发展为：

Object
├── Attribute
├── Relation
└── State

并能够随着实时数据持续变化：

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

这为下一层 第268章 Scene API｜场景 API 建立基础。

第268章将进一步解决一个新的工程问题：

当多个动态 Object 具有不同 Attribute、Relation 和 State 时，如何在当前时间、空间和环境条件下动态形成一个完整的 Scene Instance。

第267章 State API｜状态 API

第267章 State API｜状态 API

267.1 提出背景

267.2 State API 的定义

267.3 State API 的核心目的

267.4 状态不是属性

267.5 状态形成

267.6 状态条件

267.7 状态转换

267.8 状态更新

267.9 状态历史

267.10 状态变化事件

267.11 状态与关系

267.12 状态与属性向量

267.13 状态与离散时间

267.14 状态与动态行为

267.15 状态与方法

267.16 State API 与 Scene API

267.17 State API 与 Cognitive API

267.18 State API 的状态查询

267.19 State API 的接口

267.20 State Engine

267.21 State Model

267.22 State Controller

267.23 State API 与数据库

267.24 State API 的验证

267.25 状态转换表

267.26 State API 与反馈闭环

267.27 State API 的核心工程价值

267.28 本章总结