第273章 Device API｜设备 API

一、提出背景

在第272章中，Action API 完成了：

Behavior
↓
Action

的标准化。

但是，Action 本身并不能改变现实世界。

动作必须通过某一个能够执行该动作的设备、执行机构或物理主体完成。

因此，ICAI 的执行链必须继续向下延伸：

Cognition
↓
Method
↓
Behavior
↓
Action
↓
Device
↓
World Change
↓
Feedback

其中，Device 是 Action 进入现实执行层的重要对象。

例如：

Action
↓
Grasp
↓
需要执行抓取
↓
Device
↓
Robot Hand
↓
执行抓取

或者：

Action
↓
Move
↓
Device
↓
Motor
↓
Physical Movement

因此，ICAI 需要建立一个统一的 Device API，用于管理设备对象、设备能力、设备状态、设备参数、设备匹配、设备执行以及执行反馈。

这就是 Device API 的基本工程意义。

---

二、Device API 的概念定义

Device API｜设备 API 是 ICAI 系统中用于创建、查询、更新、验证、匹配、控制和管理设备对象的标准应用程序接口（Application Programming Interface）。

Device API 的核心作用是：

Action
↓
Device API
↓
Device Object
↓
Capability Matching
↓
State Validation
↓
Execution
↓
Feedback

Device API 不是设备本身。

它是软件认知系统与设备执行系统之间的标准接口。

因此：

ICAI Runtime
↓
Device API
↓
Device Interface
↓
Physical Device

Device API 负责建立统一的软件设备模型，而具体设备接口负责连接真实设备。

---

三、Device 的定义

Device｜设备 是能够接受动作输入，并按照自身能力和当前状态执行相应动作的执行对象。

设备可以表示为：

D = (
    I,
    Type,
    Capability,
    Parameters,
    State,
    Position,
    Interface,
    Relation
)

其中：

• I：设备 ID
• Type：设备类型
• Capability：设备能力
• Parameters：设备参数
• State：设备当前状态
• Position：设备空间位置
• Interface：设备接口
• Relation：设备与其他对象之间的关系

例如一个机械手设备可以表示为：

Device
{
    ID: D001
    Type: RobotHand
    Capability:
        Grasp
        Hold
        Release
        ApplyForce
    State:
        Ready
    Position:
        P
}

因此 Device 不是简单的“机器名称”。

它是一个具有：

Identity
+
Type
+
Capability
+
State
+
Parameter
+
Interface

的结构化对象。

---

四、Device 与 Action 的关系

Action 与 Device 具有明确的上下层关系：

Action
↓
Requirement
↓
Device Capability
↓
Device

Action 描述：

需要执行什么动作

Device 描述：

谁能够执行这个动作

因此：

Action ≠ Device

例如：

Action = Grasp

并不意味着：

Device = RobotHand

系统需要经过能力匹配：

Grasp Requirement
↓
Capability Matching
↓
Robot Hand

如果存在多个设备：

Device₁
Device₂
Device₃

则系统需要从中寻找满足当前动作要求的设备。

---

五、设备能力模型

Capability｜能力 是设备能够执行某一类动作或提供某一种功能的结构化描述。

设备能力可以表示为：

C_D = {
    c₁,c₂,...,cₙ
}

其中：

• C_D：设备能力集合
• c_i：单项设备能力

例如：

RobotHand
↓
{
    Grasp,
    Hold,
    Release,
    ApplyForce
}

另一个设备可能为：

RobotArm
↓
{
    Move,
    Rotate,
    Lift,
    Lower
}

因此不同设备可以具有不同能力集合。

---

六、Action 与 Device 的能力匹配

动作执行前必须判断：

Device 是否具有执行 Action 的能力？

可以定义：

Match(A,D)=1

当：

Capability(D) ⊇ Requirement(A)

成立时：

Match(A,D)=1

否则：

Match(A,D)=0

例如：

Action
Requirement:
    Grasp

设备：

Device₁
Capability:
    Move
    Rotate

则：

Match(Action,Device₁)=0

另一个设备：

Device₂
Capability:
    Grasp
    Hold
    Release

则：

Match(Action,Device₂)=1

这就是设备能力匹配的基本逻辑。

---

七、设备选择模型

当多个设备都满足能力要求时，需要形成设备选择结果。

可以表示为：

D* = Select({D_i | Match(A,D_i)=1})

其中：

• D*：最终选择的设备
• D_i：候选设备
• Match(A,D_i)：动作与设备能力的匹配结果

进一步可以增加：

Distance
Availability
State
Position
Load
Precision
Capacity
Constraint

等条件。

因此设备选择可以表示为：

D*
=
Select(
    Capability,
    Availability,
    State,
    Position,
    Constraint
)

这使设备选择成为一个结构化匹配过程，而不是固定指定某一个设备。

---

八、设备状态

设备不仅具有能力，还具有当前状态。

例如：

Ready
Running
Busy
Paused
Stopped
Error
Offline
Maintenance

可以定义设备状态：

DS_t ∈ {
    Ready,
    Running,
    Busy,
    Paused,
    Stopped,
    Error,
    Offline,
    Maintenance
}

其中：

• DS_t：时间 t 的设备状态

设备状态随执行过程发生变化：

Ready
↓
Running
↓
Busy
↓
Completed
↓
Ready

发生故障时：

Running
↓
Error

设备状态因此属于动态数据。

---

九、设备可执行条件

具有某项能力，并不意味着设备当前一定能够执行动作。

因此：

CapabilityValid

只是第一层条件。

完整执行条件可以表示为：

Executable(A,D)
=
CapabilityValid
∧
Available
∧
StateValid
∧
ParameterValid
∧
ConstraintValid

其中：

• CapabilityValid：设备能力满足动作要求
• Available：设备当前可用
• StateValid：设备当前状态允许执行
• ParameterValid：动作参数有效
• ConstraintValid：执行约束满足

因此：

Capability
≠
Executable

这是 Device API 中非常重要的区别。

---

十、设备参数

设备具有自身参数。

例如机械设备可能具有：

MaximumForce
MaximumVelocity
MaximumAcceleration
Range
Precision
LoadCapacity

可以表示：

P_D =
[
    Force_max,
    Velocity_max,
    Acceleration_max,
    Range,
    Precision,
    Load_max
]^T

动作参数则可以表示：

P_A =
[
    Force,
    Velocity,
    Acceleration,
    Distance,
    Duration
]^T

执行前需要检查：

P_A ⊆ CapabilityRange(D)

例如：

Force_Action ≤ Force_Max(Device)

如果：

Force_Action > Force_Max(Device)

则：

Executable(A,D)=0

设备无法安全执行当前动作。

---

十一、设备空间属性

设备本身也可以是 ICAI 世界中的对象。

因此设备具有空间属性：

Position
Orientation
Distance
Direction

例如：

D.Position = (x,y,z)

如果 Action 的目标对象为：

O.Position = (x_o,y_o,z_o)

则可以计算：

Distance(D,O)

例如三维空间距离：

d =
√[
(x_d-x_o)²
+
(y_d-y_o)²
+
(z_d-z_o)²
]

其中：

• d：设备与目标对象之间的距离
• (x_d,y_d,z_d)：设备位置
• (x_o,y_o,z_o)：目标对象位置

因此设备选择不仅需要考虑能力，也可以考虑空间关系。

Capability
+
Position
+
Distance
+
State
↓
Device Selection

---

十二、设备与对象的关系

Device 也是世界中的对象，因此可以参与 Relation。

例如：

Device
↓
Near
↓
Object

或者：

Device
↓
Connected
↓
Sensor

或者：

Device
↓
Holding
↓
Object

因此设备可以进入统一关系模型：

R = (
    Source,
    Type,
    Target,
    Value,
    State,
    Time
)

例如：

RobotHand
↓
Holding
↓
Glass

这意味着 Device 不应该被设计成一个脱离 ICAI 世界模型的特殊程序对象。

它仍然属于结构化世界中的对象。

---

十三、设备执行模型

Action 经过设备匹配后进入设备执行。

完整过程：

Action
↓
Action Validation
↓
Device Matching
↓
Device Selection
↓
Device Validation
↓
Execution Command
↓
Device Interface
↓
Physical Device

因此可以定义：

Execute(A,D)=F(A,D,S_D,P_A)

其中：

• A：动作
• D：设备
• S_D：设备状态
• P_A：动作参数

设备执行并不意味着动作已经成功。

执行结果必须通过反馈进行确认。

---

十四、设备反馈

设备执行后产生反馈：

Device
↓
Execution
↓
Feedback

Feedback 可以表示为：

F_t = (
    Source,
    Type,
    Value,
    State,
    Timestamp
)

例如：

{
    Source: Device001,
    Type: ForceFeedback,
    Value: 8N,
    State: Completed,
    Timestamp: ...
}

反馈可以进入：

Device
↓
Feedback
↓
State
↓
Scene
↓
Cognition

因此设备执行不会终止认知过程。

---

十五、设备故障与异常

设备执行过程中可能出现：

Overload
Error
Timeout
Disconnected
Blocked
PositionError
ForceError

这些异常必须转换为结构化设备状态。

例如：

Running
↓
Overload
↓
Error

然后：

Error
↓
Feedback
↓
State Update
↓
Behavior Update
↓
Action Re-evaluation

因此设备异常可以参与 ICAI 的重新认知过程。

系统不是简单地：

Error → Stop

而是：

Device Error
↓
Feedback
↓
World State Update
↓
Scene Update
↓
Cognition
↓
Method Re-selection
↓
Behavior Update
↓
New Action

这使设备层进入完整认知闭环。

---

十六、Device API 接口

Device API 可以建立标准接口：

/api/device/create
/api/device/get
/api/device/update
/api/device/delete
/api/device/list
/api/device/query
/api/device/validate
/api/device/capability
/api/device/match
/api/device/select
/api/device/status
/api/device/execute
/api/device/stop
/api/device/pause
/api/device/resume
/api/device/feedback
/api/device/history

也可以使用资源形式：

/api/devices
/api/devices/{device_id}
/api/devices/{device_id}/capabilities
/api/devices/{device_id}/status
/api/devices/{device_id}/execute
/api/devices/{device_id}/feedback

其中：

GET

主要用于查询。

POST

主要用于创建、匹配和执行。

PUT

用于更新。

DELETE

用于删除设备对象。

---

十七、Device API 数据结构

设备可以使用结构化 JSON 表示：

{
    "id": "D001",
    "type": "RobotHand",
    "capabilities": [
        "Grasp",
        "Hold",
        "Release",
        "ApplyForce"
    ],
    "parameters": {
        "max_force": 20,
        "max_velocity": 2,
        "precision": 0.01
    },
    "state": "Ready",
    "position": {
        "x": 10,
        "y": 20,
        "z": 30
    }
}

这里：

JSON

只是 Device Data 的通信表示。

它不等于 Device Object，也不等于设备本身。

结构关系仍然是：

Device Theory
↓
Device Object Model
↓
Device Runtime Object
↓
Device Data
↓
JSON
↓
API

---

十八、PHP OOP 工程映射

Device API 可以继续采用 ICAI 的统一 MVC + Service + Engine + Model + Repository 结构：

DeviceApiController
        ↓
DeviceService
        ↓
DeviceEngine
        ↓
DeviceModel
        ↓
DeviceRepository
        ↓
MySQL

DeviceApiController

class DeviceApiController
{
    public function create($request)
    {
        return $this->deviceService->create($request);
    }

    public function get($request)
    {
        return $this->deviceService->get($request);
    }

    public function match($request)
    {
        return $this->deviceService->match($request);
    }

    public function execute($request)
    {
        return $this->deviceService->execute($request);
    }

    public function feedback($request)
    {
        return $this->deviceService->feedback($request);
    }
}

DeviceService

class DeviceService
{
    public function create($data)
    {
        return $this->engine->createDevice($data);
    }

    public function match($action, $devices)
    {
        return $this->engine->matchDevice($action, $devices);
    }

    public function execute($action, $device)
    {
        return $this->engine->executeDevice($action, $device);
    }
}

DeviceEngine

class DeviceEngine
{
    public function matchDevice($action, $device)
    {
        // Capability matching
    }

    public function validateDevice($device)
    {
        // Device validation
    }

    public function executeDevice($action, $device)
    {
        // Execution preparation
    }
}

DeviceModel

class DeviceModel
{
    public $id;
    public $type;
    public $capabilities;
    public $parameters;
    public $state;
    public $position;
    public $interface;
    public $relations;
}

DeviceRepository

class DeviceRepository
{
    public function save($device)
    {
        // Save device
    }

    public function find($id)
    {
        // Find device
    }

    public function update($device)
    {
        // Update device
    }

    public function findByCapability($capability)
    {
        // Find capable devices
    }
}

因此形成统一的软件工程结构：

API
↓
Controller
↓
Service
↓
Engine
↓
Model
↓
Repository
↓
Database

---

十九、数据库模型

设备对象可以建立：

cognitive_devices

主要字段：

id
device_type
name
capabilities
parameters
state
position
interface_data
created_at
updated_at

设备能力可以独立保存：

cognitive_device_capabilities

主要字段：

id
device_id
capability_type
parameters
status
created_at

设备状态历史：

cognitive_device_history

主要字段：

id
device_id
state
parameters
feedback
timestamp

形成：

Device
├── Capability
├── Parameter
├── State
├── Relation
└── History

---

二十、Device API 与 Runtime

Device API 必须接入 ICAI Runtime。

完整结构为：

World
↓
Real-Time Data
↓
Element
↓
Object
↓
Attribute
↓
Relation
↓
State
↓
Scene
↓
Cognition
↓
Method
↓
Behavior
↓
Action
↓
Device API
↓
Device
↓
World Change
↓
Feedback

因此 Device API 是：

ICAI Cognitive Runtime

与：

Execution Runtime

之间的连接层。

它不应该取代 Cognitive Engine，也不应该取代 Device Driver。

它负责的是：

Cognitive Action
↓
Structured Device Request

以及：

Device Result
↓
Structured Feedback

---

二十一、Device Interface 与 Physical Device

Device API 与真实设备之间还存在一个重要的软件层：

Device API
↓
Device Interface
↓
Physical Device

Device Interface 可以根据不同设备建立适配结构。

例如：

Action
↓
Device API
↓
RobotHand Interface
↓
Robot Hand

或者：

Action
↓
Device API
↓
Motor Interface
↓
Motor

因此 ICAI 上层 Action 不需要直接了解每一个具体设备的底层控制方式。

可以形成：

Generic Action
↓
Generic Device Model
↓
Device Interface
↓
Specific Device

这保证认知层与具体硬件之间保持结构化分离。

---

二十二、设备能力的动态变化

设备能力并不一定永久固定。

设备可能：

Available
↓
Busy
↓
Unavailable

或者：

Normal
↓
Degraded
↓
Error

因此实际可用能力可以定义为：

C_t^{available}
=
F(C_D,S_D,P_D)

其中：

• C_D：设备理论能力
• S_D：设备当前状态
• P_D：设备当前参数
• C_t^{available}：当前实际可用能力

例如设备理论上具有：

Grasp

但是如果：

State = Error

那么：

AvailableCapability(Grasp)=0

因此：

Device Capability

和：

Current Available Capability

需要区分。

---

二十三、设备执行与世界变化

设备执行的最终目的不是产生一个软件结果，而是改变世界状态。

因此：

Action
↓
Device
↓
Execution
↓
World

可以表示为：

W_{t+1}=F(W_t,A_t,D_t)

其中：

• W_t：执行前世界状态
• A_t：动作
• D_t：执行设备
• W_{t+1}：执行后的世界状态

例如：

Object
Position = P₁

经过：

Move
↓
Robot
↓
Execution

之后：

Object
Position = P₂

于是：

P₁ → P₂

世界结构发生了变化。

传感系统随后重新获取：

P₂

形成新的 Element。

因此：

World Change
↓
Real-Time Data
↓
Element
↓
Object Update
↓
State Update
↓
Scene Update

---

二十四、Device Feedback 与重新认知

设备反馈最终必须重新进入认知系统。

完整闭环：

Action
↓
Device
↓
Execution
↓
Feedback
↓
State
↓
Scene
↓
Cognition
↓
Method
↓
Behavior
↓
Action

因此可以表示：

C_{t+1}
=
F(
O_{t+1},
A_{t+1},
R_{t+1},
S_{t+1},
Sc_{t+1},
G_{t+1}
)

其中新的认知由新的对象、属性、关系、状态、场景和目标共同形成。

这意味着：

Device

不是认知系统的终点。

真正的结构是：

Device Execution
↓
World Change
↓
Feedback
↓
Re-Cognition

---

二十五、Device API 的完整运行模型

至此，Device API 可以完整表示为：

Action
↓
Device API
↓
Device Discovery
↓
Capability Matching
↓
Device Selection
↓
State Validation
↓
Parameter Validation
↓
Constraint Validation
↓
Execution
↓
Physical Device
↓
World Change
↓
Feedback
↓
State Update
↓
Scene Update
↓
Cognition Update

数学模型可以表示为：

D* = Select({D_i | Match(A,D_i)=1})

然后：

Execute(A,D*)

执行后的世界状态：

W_{t+1}=F(W_t,A_t,D_t)

反馈：

F_t=Feedback(D_t)

最终：

F_t
→
S_{t+1}
→
Sc_{t+1}
→
C_{t+1}

形成新的认知状态。

---

二十六、ICAI API 执行链的完成

经过第261—273章，ICAI API 已经形成完整的结构化认知—执行接口链：

Element API
↓
Object API
↓
Attribute API
↓
Relation API
↓
State API
↓
Scene API
↓
Cognition API
↓
Method API
↓
Behavior API
↓
Action API
↓
Device API

其对应的完整认知执行链为：

World
↓
Real-Time Data
↓
Element
↓
Object
↓
Attribute
↓
Relation
↓
State
↓
Scene
↓
Cognition
↓
Method
↓
Behavior
↓
Action
↓
Device
↓
World Change
↓
Feedback
↓
Re-Cognition

这条链把：

世界结构

与：

软件对象

以及：

认知结构

和：

执行结构

连接起来。

---

二十七、本章总结

Device API 建立了 ICAI 中：

Action → Device

之间的标准工程接口。

Device 不再只是一个硬件名称，而是一个具有：

Identity
+
Type
+
Capability
+
Parameter
+
State
+
Position
+
Interface
+
Relation

的结构化设备对象。

Device API 的核心过程是：

Action
↓
Capability Matching
↓
Device Selection
↓
State Validation
↓
Parameter Validation
↓
Constraint Validation
↓
Execution
↓
Feedback

核心匹配模型：

Match(A,D)=1

当：

Capability(D) ⊇ Requirement(A)

成立时，设备才具有执行当前动作的基本能力。

而最终执行条件为：

Executable(A,D)
=
CapabilityValid
∧
Available
∧
StateValid
∧
ParameterValid
∧
ConstraintValid

因此：

Capability
≠
Availability
≠
Executable

设备执行之后：

Device
↓
World Change
↓
Feedback
↓
State
↓
Scene
↓
Cognition

重新进入 ICAI 认知循环。

至此，ICAI 已经建立：

Cognition
→
Method
→
Behavior
→
Action
→
Device
→
World

这一完整的认知执行结构。

第273章完成了 Action → Device 的接口定义。下一阶段可以继续进入 第274章 Feedback API｜反馈 API，建立：

Device
↓
Feedback API
↓
State
↓
Scene
↓
Cognition

从而把整个 ICAI API 链真正闭合。