第6章 SAI Framework 项目目录结构
本章大纲
- 根目录
publicappCoreInformationSceneIndividualCentralCognitionMemoryReasoningDecisionBehaviorTemplateRendererAdapterDeviceFeedbackExperienceLearningMaintenanceExtensionconfigtemplatesstorageextensionsbootstrap.php- 完整目录关系
6.1 根目录
SAI Framework 的根目录是整个框架的工程边界。
它不是某一个 Web 页面，也不是某一个 PHP 类，而是把：
- 核心代码
- Individual
- 信息处理
- 场景处理
- 认知
- 记忆
- 推理
- 决策
- 行为
- 模板
- 输出
- 外部设备
- 学习
- 自我维护
- 扩展
- 配置
- 数据存储
组织在一起。
一个完整的 SAI Framework 根目录可以设计为：
sai/
│
├── app/
├── config/
├── templates/
├── storage/
├── extensions/
├── public/
│
└── bootstrap.php这里需要特别区分：
代码
配置
模板
运行数据
扩展
入口它们承担不同职责。
6.2 public
public 是外部访问入口目录。
如果 SAI 运行在 Web 环境中，可以通过：
HTTP Request
↓
public/index.php进入 SAI。
例如：
public/
└── index.phpindex.php 的主要职责不是实现认知，而是启动框架。
例如：
<?php
require_once dirname(__DIR__) . '/bootstrap.php';
$app = new \SAI\Core\Application();
$app->run();因此：
public/index.php只是入口。
它不是：
Cognition
Reasoning
Decision的实现位置。
非 Web 环境
SAI 并不依赖 public。
例如机器人、车辆或者工业设备，可以直接通过：
Device
↓
Adapter
↓
SAI进入系统。
所以：
public是 SAI 的一种外部入口，而不是 SAI Framework 的核心。
6.3 app
app 是 SAI Framework 的核心代码目录。
主要的 Individual 构建能力都放在这里。
例如：
app/
├── Core/
├── Information/
├── Scene/
├── Individual/
├── Central/
├── Element/
├── Object/
├── Relation/
├── Rule/
├── Perception/
├── Cognition/
├── Memory/
├── Reasoning/
├── Decision/
├── Behavior/
├── Expression/
├── Template/
├── Renderer/
├── Adapter/
├── Device/
├── Feedback/
├── Experience/
├── Learning/
├── Maintenance/
└── Extension/可以把 app 理解为：
SAI Framework 的内部能力空间。
6.4 Core
Core 是框架基础层。
它不负责直接产生“智能”，而是提供框架运行所需要的基础工程能力。
例如：
Core/
├── Application.php
├── Container.php
├── Request.php
├── Response.php
├── Route.php
├── Controller.php
├── Model.php
└── Engine.phpApplication
负责整个 SAI 应用生命周期。
Application
↓
启动
↓
初始化
↓
运行 Individual
↓
结束Container
负责对象和服务的组织。
例如：
$container->set(
'memory',
new MemoryEngine()
);Request
可以承载 Web 请求，但不能认为 SAI 的所有输入都是 Request。
Response
负责一种外部响应形式。
Controller
负责外部入口控制。
注意：
Controller ≠ CentralEngine
定义框架中各种 Engine 的工程基础。
例如：
CognitionEngine
ReasoningEngine
LearningEngine
MemoryEngine6.5 Information
Information 负责信息。
目录可以设计为：
Information/
├── Information.php
├── InformationType.php
├── InformationSource.php
├── InformationReceiver.php
└── InformationManager.php基本信息结构：
$information = array(
'type' => 'sensor',
'source' => 'temperature_sensor',
'content' => 32,
'time' => time(),
'state' => 'active',
'context' => 'room'
);信息可能来自：
人
↓
文字 / 语言 / 指令
环境
↓
场景信息
设备
↓
设备状态
传感器
↓
传感数据
外部系统
↓
API / 数据库 / 网络所以 SAI 的输入不是单一的：
Request而是：
Information6.6 Scene
Scene 负责场景。
例如：
Scene/
├── Scene.php
├── SceneInformation.php
├── SceneCollector.php
├── SceneObject.php
├── SceneState.php
└── SceneManager.php一个场景可能包括：
Room
├── Temperature
├── Light
├── Person
├── Door
├── Fan
└── Window场景还包含：
位置
距离
方向
运动
状态
环境
对象例如：
Room.temperature = 32
Person.state = PRESENT
Fan.state = OFF这些信息共同构成一个场景状态。
6.7 Individual
Individual 是 SAI Framework 最重要的目标对象。
目录：
Individual/
├── Individual.php
├── Identity.php
├── State.php
├── Ability.php
└── IndividualManager.php一个 Individual 可以拥有：
Identity
State
Ability
Memory
Cognition
Learning
Behavior结构：
Individual
├── Identity
├── State
├── Ability
├── Memory
├── Cognition
├── Learning
└── Behavior因此：
Framework 是构建工具，Individual 才是最终构建对象。
6.8 Central
Central 是 Individual 内部的协调中心。
目录：
Central/
├── Central.php
├── Dispatcher.php
├── Coordinator.php
├── Lifecycle.php
└── StateManager.phpCentral 可以协调：
Information
↓
Perception
↓
Cognition
↓
Memory
↓
Reasoning
↓
Decision
↓
Behavior
↓
Feedback例如：
$central->receive($information);
$central->process();但 Central 本身不应该把所有功能都写进去。
错误设计：
Central
├── 感知代码
├── 认知代码
├── 推理代码
├── 决策代码
├── 学习代码
└── 行为代码正确设计：
Central
↓
协调
↓
调用不同模块6.9 Cognition
Cognition 负责认知。
目录：
Cognition/
├── Cognition.php
├── CognitionEngine.php
├── Understanding.php
├── Matching.php
└── CognitionManager.php认知的基本过程：
感知结果
↓
元素
↓
对象
↓
属性
↓
关系
↓
匹配
↓
理解例如：
temperature = 32感知阶段只是获得：
32认知阶段可能得到：
Room.temperature = 32进一步形成：
Room
Property: temperature
Value: 326.10 Memory
Memory 负责 Individual 的记忆机制。
目录：
Memory/
├── Memory.php
├── ShortMemory.php
├── LongMemory.php
├── FactMemory.php
├── ExperienceMemory.php
├── StateMemory.php
├── MemoryIndex.php
└── MemoryEngine.php可以划分：
Memory
├── ShortMemory
├── LongMemory
├── FactMemory
├── ExperienceMemory
└── StateMemory例如：
FactMemory
记录事实：
Room.temperature = 32StateMemory
记录状态：
Fan.state = OFFExperienceMemory
记录经验：
过去：
温度 > 30
人员存在
风扇开启
结果：
温度下降Memory 因此不是简单的：
数据库而是 Individual 内部的信息保留机制。
6.11 Reasoning
Reasoning 负责推理。
目录：
Reasoning/
├── Reasoning.php
├── ReasoningEngine.php
├── FactResolver.php
├── RuleResolver.php
└── Conclusion.php基本关系：
Facts
+
Objects
+
Relations
+
Rules
+
Experience
↓
Reasoning
↓
Conclusion例如：
Fact:
Room.temperature = 32
Fact:
Person.state = PRESENT
Fact:
Fan.state = OFF规则：
IF
Room.temperature > 30
AND
Person.state = PRESENT
AND
Fan.state = OFF
THEN
Fan.turnOn()Reasoning 得到：
Fan should turn on6.12 Decision
Decision 负责决策。
目录：
Decision/
├── Decision.php
├── DecisionEngine.php
├── Candidate.php
├── Priority.php
├── Risk.php
└── DecisionResult.php推理结果并不一定直接成为最终行为。
例如可能产生：
Candidate A：打开风扇
Candidate B：打开空调
Candidate C：不执行Decision 进行：
条件分析
↓
风险分析
↓
优先级分析
↓
选择最终：
DecisionResult例如：
Action = Fan.turnOn()6.13 Behavior
Behavior 负责行为。
目录：
Behavior/
├── Behavior.php
├── BehaviorEngine.php
├── BehaviorType.php
├── Action.php
└── BehaviorResult.php关系：
Decision
↓
Behavior
↓
Action例如：
Decision:
turn_on_fan转化为：
Behavior:
CoolingBehavior然后产生：
Action:
Fan.turnOn()因此：
Decision ≠ Behavior
Behavior ≠ Action三者具有不同职责。
6.14 Template
Template 负责行为表达模板。
目录：
Template/
├── Template.php
├── TemplateEngine.php
├── TemplateManager.php
├── TemplateCompiler.php
└── TemplateRegistry.php模板可以把内部行为映射为外部表达。
例如：
Behavior:
Fan.turnOn()可以根据不同模板形成：
Web
API
UI
Device模板不是认知系统。
它不负责：
Reasoning
Decision
Learning
Memory6.15 Renderer
Renderer 负责表达结果的呈现。
例如：
Renderer/
├── Renderer.php
├── RendererManager.php
├── WebRenderer.php
├── UiRenderer.php
├── ApiRenderer.php
└── DeviceRenderer.php同一个行为：
Fan.turnOn()可能产生：
WebRenderer
→ 页面状态
ApiRenderer
→ JSON
UiRenderer
→ UI状态
DeviceRenderer
→ 设备表达所以 Renderer 解决的是：
如何把结果表达出来。
6.16 Adapter
Adapter 负责外部设备和外部协议适配。
目录：
Adapter/
├── Adapter.php
├── AdapterManager.php
├── DeviceAdapter.php
├── RobotAdapter.php
├── SensorAdapter.php
└── MachineAdapter.php例如：
SAI Action
↓
RobotAdapter
↓
机器人控制接口或者：
SAI Action
↓
MachineAdapter
↓
工业设备Adapter 解决的是：
SAI 内部对象如何与外部世界连接。
6.17 Device
Device 把外部设备作为 SAI 可以认识和管理的对象。
目录：
Device/
├── Device.php
├── DeviceState.php
├── DeviceManager.php
├── DeviceCommand.php
└── DeviceResponse.php设备可以具有：
Identity
Property
State
Method
Relation例如：
Fan
├── id
├── speed
├── direction
├── state
└── turnOn()于是设备也可以进入 SAI 的对象体系：
Element
↓
Object
↓
Property
↓
Method
↓
Relation6.18 Feedback
Feedback 负责接收行为执行后的反馈。
目录：
Feedback/
├── Feedback.php
├── FeedbackEngine.php
└── FeedbackManager.php完整闭环：
Decision
↓
Behavior
↓
Action
↓
Device
↓
结果
↓
Feedback
↓
Information例如：
Fan.turnOn()设备返回：
Fan.state = ON这个结果就是反馈信息。
6.19 Experience
Experience 负责经验。
目录：
Experience/
├── Experience.php
├── ExperienceEngine.php
└── ExperienceManager.php经验不是单独一个事实。
例如：
Fact:
temperature = 32只是事实。
而：
场景
+
决策
+
行为
+
结果可以形成经验：
当室温超过30℃且有人存在时，
开启风扇能够降低室温。因此经验具有过程性。
6.20 Learning
Learning 负责学习。
目录：
Learning/
├── Learning.php
├── LearningEngine.php
├── KnowledgeExtraction.php
├── AbilityUpdate.php
└── LearningManager.php基本流程：
Feedback
↓
Experience
↓
Pattern
↓
Knowledge
↓
Ability Update
↓
Memory Update学习的目的不是简单保存数据，而是：
获得知识
↓
形成能力资源
↓
改善以后行为6.21 Maintenance
Maintenance 负责 Individual 的自我维护。
目录：
Maintenance/
├── Detection.php
├── Risk.php
├── Conflict.php
├── Diagnosis.php
├── Repair.php
└── Verification.php完整过程：
Detection
↓
Risk
↓
Conflict
↓
Diagnosis
↓
Repair
↓
Verification例如：
发现 MemoryIndex 异常
↓
判断风险
↓
定位问题
↓
执行修复
↓
重新检查Maintenance 不属于普通业务行为，而是框架内部的维护能力。
6.22 Extension
Extension 是框架扩展机制。
目录：
Extension/
├── Extension.php
├── ExtensionManager.php
├── Registry.php
└── Hook.php通过 Extension 可以扩展：
Engine
Adapter
Renderer
Template
Device
Information Collector例如：
CustomRobotEngine
CustomRobotAdapter
CustomSensorAdapter
CustomRenderer这样 SAI Framework 不需要修改核心代码就可以增加能力。
6.23 config
config 保存配置。
例如：
config/
├── app.php
├── individual.php
├── information.php
├── scene.php
├── memory.php
├── behavior.php
├── template.php
├── device.php
└── extension.php例如：
return array(
'name' => 'SAI Framework',
'version' => '0.1.0',
'debug' => true
);配置与程序代码分离：
程序逻辑
≠
运行配置这样可以减少硬编码。
6.24 templates
templates 保存具体模板资源。
例如：
templates/
├── web/
├── ui/
├── api/
├── device/
└── custom/这里与：
app/Template/有所区别。
app/Template
保存模板引擎代码：
TemplateEngine
TemplateManager
TemplateCompilertemplates
保存实际模板：
HTML
JSON
Device Command
UI Expression
Custom Expression因此：
Template Engine
↓
读取
↓
Template Resource6.25 storage
storage 是运行数据存储区域。
例如：
storage/
├── memory/
├── experience/
├── state/
├── cache/
├── logs/
└── runtime/必须注意：
Storage 不等于 Memory。
例如：
Memory是 SAI 的内部记忆机制。
而：
storage/memory/只是保存数据的工程位置。
关系是：
Memory Engine
↓
Storage
↓
文件 / 数据库 / 其他持久化方式6.26 extensions
extensions 是实际扩展模块的存放位置。
例如：
extensions/
├── information/
├── scene/
├── renderer/
├── adapter/
├── device/
└── template/区别：
app/Extension/是扩展机制本身。
而：
extensions/是实际扩展内容。
例如：
app/Extension/
↓
ExtensionManager
↓
extensions/robot/
↓
RobotAdapter6.27 bootstrap.php
bootstrap.php 是框架启动文件。
主要负责：
加载配置
↓
注册 Autoload
↓
初始化基础环境
↓
初始化核心服务
↓
准备 Application例如：
<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');
spl_autoload_register(function ($class) {
$prefix = 'SAI\\';
if (strpos($class, $prefix) !== 0) {
return;
}
$relative = substr($class, strlen($prefix));
$file = __DIR__
. '/app/'
. str_replace('\\', '/', $relative)
. '.php';
if (is_file($file)) {
require_once $file;
}
});这里的代码只是教程中的示例实现，不代表当前已经建立或验证了一个实际 SAI Framework 项目。
6.28 完整目录关系
综合前面的模块，可以形成完整目录：
sai/
│
├── public/
│ └── index.php
│
├── app/
│ │
│ ├── Core/
│ │ ├── Application.php
│ │ ├── Container.php
│ │ ├── Request.php
│ │ ├── Response.php
│ │ ├── Route.php
│ │ ├── Controller.php
│ │ ├── Model.php
│ │ └── Engine.php
│ │
│ ├── Information/
│ ├── Scene/
│ ├── Individual/
│ ├── Central/
│ ├── Element/
│ ├── Object/
│ ├── Relation/
│ ├── Rule/
│ ├── Perception/
│ ├── Cognition/
│ ├── Memory/
│ ├── Reasoning/
│ ├── Decision/
│ ├── Behavior/
│ ├── Expression/
│ ├── Template/
│ ├── Renderer/
│ ├── Adapter/
│ ├── Device/
│ ├── Feedback/
│ ├── Experience/
│ ├── Learning/
│ ├── Maintenance/
│ └── Extension/
│
├── config/
│ ├── app.php
│ ├── individual.php
│ ├── information.php
│ ├── scene.php
│ ├── memory.php
│ ├── behavior.php
│ ├── template.php
│ ├── device.php
│ └── extension.php
│
├── templates/
│ ├── web/
│ ├── ui/
│ ├── api/
│ ├── device/
│ └── custom/
│
├── storage/
│ ├── memory/
│ ├── experience/
│ ├── state/
│ ├── cache/
│ ├── logs/
│ └── runtime/
│
├── extensions/
│ ├── information/
│ ├── scene/
│ ├── renderer/
│ ├── adapter/
│ ├── device/
│ └── template/
│
└── bootstrap.php6.29 SAI Framework 的纵向关系
目录只是横向组织代码，真正重要的是模块之间的运行关系。
可以把核心运行结构理解为：
SAI Framework
│
▼
Individual
│
▼
Central
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Information Scene Individual
│ │
└──────────┬───────┘
▼
Perception
│
▼
Element
│
▼
Object
│
┌────┴────┐
▼ ▼
Property Relation
│ │
└────┬────┘
▼
Cognition
│
▼
Memory
│
▼
Reasoning
│
▼
Decision
│
▼
Behavior
│
▼
Action
│
▼
Expression
│
▼
Template
│
┌──────┴──────┐
▼ ▼
Renderer Adapter
│ │
▼ ▼
Output Device
│ │
└──────┬──────┘
▼
Feedback
│
▼
Experience
│
▼
Learning
│
▼
Memory Update6.30 目录结构与 SAI 生命周期
最终可以把目录与生命周期对应起来：
| SAI 生命周期 | Framework 模块 |
|---|---|
| 信息接收 | Information |
| 场景采集 | Scene |
| 感知 | Perception |
| 元素 | Element |
| 对象 | Object |
| 属性 | Property |
| 关系 | Relation |
| 认知 | Cognition |
| 记忆 | Memory |
| 推理 | Reasoning |
| 决策 | Decision |
| 行为 | Behavior |
| 表达 | Expression |
| 模板 | Template |
| 输出 | Renderer |
| 外部设备 | Adapter / Device |
| 反馈 | Feedback |
| 经验 | Experience |
| 学习 | Learning |
| 自我维护 | Maintenance |
| 扩展 | Extension |
这样目录就不再是简单的：
文件夹集合而是对应 SAI Individual 的内部结构。
6.31 一个完整运行示例
假设存在一个：
SAI Individual
ID = indoor_001环境中存在：
Room
TemperatureSensor
Fan
Person温度传感器产生：
32℃首先：
Sensor
↓
Information进入：
app/Information/然后进入：
Scene
↓
Perception形成：
Room.temperature = 32再经过：
Element
↓
Object
↓
Property形成对象关系。
然后：
Cognition
↓
Memory
↓
Reasoning匹配规则：
IF Room.temperature > 30
AND Person.state = PRESENT
AND Fan.state = OFF
THEN Fan.turnOn()然后：
Reasoning
↓
Decision
↓
Behavior
↓
Action如果是设备：
Action
↓
Adapter
↓
Device
↓
Fan.turnOn()风扇返回：
state = ON形成：
Feedback
↓
Experience
↓
Learning
↓
Memory Update最终再次进入下一轮：
Information
↓
Scene
↓
Perception
↓
...这就形成真正的闭环。
6.32 Web 在目录结构中的位置
这里可以进一步明确 SAI 与 Web Framework 的关系。
Web 只是：
public/提供的一种入口和：
Renderer/提供的一种输出方式。
例如：
Browser
│
▼
public/index.php
│
▼
Controller
│
▼
Information
│
▼
SAI Individual
│
▼
Decision
│
▼
Behavior
│
▼
WebRenderer
│
▼
Response
│
▼
Browser因此：
Web 是 SAI Framework 的应用环境之一，而不是 SAI Framework 的定义。
同一个 SAI 可以离开 Web：
Robot
↓
Adapter
↓
SAI
↓
Decision
↓
Robot Action也可以运行在：
Vehicle
Industrial Machine
Embedded Device
Desktop Application
Command Line
Server6.33 本章完整结构图
最终可以把整个 SAI Framework 压缩成下面这张结构图：
SAI Framework
│
▼
Individual
│
▼
Central
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
Information Scene Core
│ │
└───────┬────────┘
▼
Perception
│
▼
Element
│
▼
Object
/ \
Property Relation
\ /
▼
Cognition
│
▼
Memory
│
▼
Reasoning
│
▼
Decision
│
▼
Behavior
│
▼
Action
│
▼
Expression
│
▼
Template
│
┌──────┴──────┐
▼ ▼
Renderer Adapter
│ │
▼ ▼
Output Device
│ │
└──────┬──────┘
▼
Feedback
│
▼
Experience
│
▼
Learning
│
▼
Memory Update
│
▼
Maintenance
│
▼
Extension同时，工程支撑层位于外围：
┌─────────────────────────┐
│ config/ │
│ templates/ │
│ storage/ │
│ extensions/ │
│ public/ │
│ bootstrap.php │
└────────────┬────────────┘
│
▼
SAI Framework本章小结
第6章解决的不是“某个类怎么写”，而是首先确定 SAI Framework 的工程空间。
核心关系可以记成：
根目录
│
├── public 外部入口
├── app 核心代码
│ ├── Core 框架基础
│ ├── Information
│ ├── Scene
│ ├── Individual
│ ├── Central
│ ├── Cognition
│ ├── Memory
│ ├── Reasoning
│ ├── Decision
│ ├── Behavior
│ ├── Template
│ ├── Renderer
│ ├── Adapter
│ ├── Device
│ ├── Feedback
│ ├── Experience
│ ├── Learning
│ ├── Maintenance
│ └── Extension
│
├── config 配置
├── templates 模板资源
├── storage 持久化数据
├── extensions 实际扩展
└── bootstrap.php 启动而从 SAI 的核心运行机制来看：
Information
↓
Scene
↓
Perception
↓
Element
↓
Object
↓
Relation
↓
Cognition
↓
Memory
↓
Reasoning
↓
Decision
↓
Behavior
↓
Action
↓
Expression
↓
Template
↓
Renderer / Adapter
↓
World / Device
↓
Feedback
↓
Experience
↓
Learning
↓
Memory Update因此，SAI Framework 的目录结构实际上就是 SAI Individual 生命周期的工程化映射。
需要再次强调：本章目录、类名和代码均属于教程架构设计与示例，并不表示这些文件目前已经实际创建、安装或运行验证。