第63章 ApiRenderer
1. API 表现
ApiRenderer 是 SATE 中专门负责 API 数据表现 的 Renderer。
第62章的 WebRenderer 面向：
Browser
HTML
CSS
JavaScript
HTTP Web Page而 ApiRenderer 面向：
API
↓
Structured Data
↓
JSON / XML
↓
API Response
↓
External SystemApiRenderer 的核心职责是：
将已经确定的结构化 Expression 转换为 API 可以传输和识别的结构化数据表现。
基本流程：
ActionResult
↓
Expression
↓
ApiRenderer
↓
JSON
↓
API ResponseApiRenderer 不负责：
认知
推理
决策
学习
记忆例如：
Decision
↓
决定执行什么
Action
↓
实际执行
ActionResult
↓
执行产生什么结果
ApiRenderer
↓
把结果转换成 API 表现所以：
ApiRenderer ≠ Action
ApiRenderer ≠ API Business Logic
ApiRenderer ≠ Reasoning2. JSON
JSON 是 ApiRenderer 最常用的表现格式之一。
JSON 特别适合表达：
- 对象
- 属性
- 数组
- 状态
- 结果
- 关系
- 参数
- 错误
- API 数据
例如：
{
"id": 1001,
"name": "Product A",
"state": "available"
}对应结构：
Object
├── id
├── name
└── state复杂对象：
{
"product": {
"id": 1001,
"name": "Product A",
"price": 29.90,
"state": "available"
}
}数组：
{
"products": [
{
"id": 1001,
"name": "Product A"
},
{
"id": 1002,
"name": "Product B"
}
]
}JSON 在这里不是知识生成机制。
它只是：
Structured Data
↓
JSON Representation因此：
JSON 是数据表现格式，而不是认知机制。
3. Action → JSON
Action 执行以后产生 ActionResult。
例如：
Action
{
id: 1001,
type: "CREATE",
target: "Order",
parameters: {
product: "Product A",
quantity: 100
}
}ActionExecutor 执行：
Action
↓
ActionExecutor
↓
Method
↓
Execution产生：
ActionResult
{
action_id: 1001,
state: "SUCCESS",
output: {
order_id: 5001,
product: "Product A",
quantity: 100
}
}如果需要通过 API 返回，可以将 ActionResult 转换为 JSON：
{
"action_id": 1001,
"state": "SUCCESS",
"output": {
"order_id": 5001,
"product": "Product A",
"quantity": 100
}
}流程：
Action
↓
ActionExecutor
↓
ActionResult
↓
ApiRenderer
↓
JSON需要注意：
Action → JSON不是说 Action 自己生成 JSON。
准确关系是：
Action
↓
ActionResult
↓
Expression
↓
ApiRenderer
↓
JSON这样可以保持各层职责清晰。
4. Expression → JSON
Expression 是 ApiRenderer 更标准的输入。
例如：
Expression
{
id: 2001,
type: "RESULT",
target: "API",
data: {
order_id: 5001,
product: "Product A",
quantity: 100,
state: "created"
}
}ApiRenderer 读取 Expression 中的数据：
Expression
↓
Data
↓
Object
↓
Property
↓
JSON形成：
{
"order_id": 5001,
"product": "Product A",
"quantity": 100,
"state": "created"
}如果需要保留 Expression 类型：
{
"type": "RESULT",
"data": {
"order_id": 5001,
"product": "Product A",
"quantity": 100,
"state": "created"
}
}如果 API 需要统一结构：
{
"success": true,
"data": {
"order_id": 5001,
"product": "Product A",
"quantity": 100,
"state": "created"
},
"error": null
}这说明 ApiRenderer 可以根据 API Template 对 Expression 进行结构化表现。
核心：
Expression
+
API Template
↓
ApiRenderer
↓
JSON5. API Response
JSON 形成之后，还需要成为 API Response。
完整过程：
Expression
↓
API Template
↓
TemplateEngine
↓
ApiRenderer
↓
JSON
↓
API ResponseAPI Response 可以具有：
Response
{
status
headers
content_type
body
}例如成功响应：
Response
{
status: 200,
headers: {
"Content-Type":
"application/json; charset=UTF-8"
},
content_type: "application/json",
body: "{...JSON...}"
}JSON：
{
"success": true,
"data": {
"order_id": 5001,
"state": "created"
},
"error": null
}错误情况也应该结构化。
例如：
{
"success": false,
"data": null,
"error": {
"code": "ORDER_NOT_FOUND",
"message": "Order does not exist"
}
}这里：
ApiRenderer
↓
负责 JSON 表现
ApiAdapter
↓
负责 API 输出
HTTP Response
↓
负责 HTTP 层传输所以：
ApiRenderer
↓
JSON
ApiAdapter
↓
HTTP/API Output不能把 ApiRenderer 和 API 业务处理混为一体。
6. API 实际案例
下面建立一个完整的 ApiRenderer 运行案例。
假设系统已经完成：
Information
↓
Perception
↓
Cognition
↓
Understanding
↓
Reasoning
↓
Decision
↓
Behavior
↓
Action用户请求：
创建一个 Product A 订单，
数量 100。系统经过前面的认知、推理和决策之后形成：
Action
{
id: 1001,
type: "CREATE",
target: "Order",
parameters: {
product: "Product A",
quantity: 100
}
}第一步：执行 Action
Action
↓
ActionExecutor
↓
Create Order产生：
ActionResult
{
action_id: 1001,
state: "SUCCESS",
output: {
order_id: 5001,
product: "Product A",
quantity: 100,
state: "created"
}
}第二步：形成 Expression
Expression
{
id: 2001,
type: "RESULT",
target: "API",
data: {
order_id: 5001,
product: "Product A",
quantity: 100,
state: "created"
}
}第三步：API Template
可以定义：
{
"success": {{success}},
"data": {
"order_id": {{order_id}},
"product": "{{product}}",
"quantity": {{quantity}},
"state": "{{state}}"
},
"error": {{error}}
}Context：
success = true
order_id = 5001
product = "Product A"
quantity = 100
state = "created"
error = null第四步：ApiRenderer
执行：
Expression
↓
API Template
↓
TemplateEngine
↓
ApiRenderer形成：
{
"success": true,
"data": {
"order_id": 5001,
"product": "Product A",
"quantity": 100,
"state": "created"
},
"error": null
}第五步：API Response
最终：
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8Response Body：
{
"success": true,
"data": {
"order_id": 5001,
"product": "Product A",
"quantity": 100,
"state": "created"
},
"error": null
}完整链路：
User Request
↓
Information
↓
Perception
↓
Cognition
↓
Understanding
↓
Reasoning
↓
Decision
↓
Behavior
↓
Action
↓
ActionResult
↓
Expression
↓
API Template
↓
TemplateEngine
↓
ApiRenderer
↓
JSON
↓
ApiAdapter
↓
API Response
↓
External SystemApiRenderer 核心结构
第63章最终可以形成：
Expression
↓
API Template
↓
TemplateEngine
↓
ApiRenderer
↓
┌───────┴───────┐
↓ ↓
JSON XML
↓ ↓
ApiAdapter XmlAdapter
↓ ↓
API Response其中：
Action
= 执行行动
ActionResult
= 行动结果
Expression
= 定义表现内容
ApiRenderer
= API表现转换
JSON
= API数据表现格式
ApiAdapter
= API输出
API Response
= 最终接口响应核心定义
ApiRenderer 是 SATE 中面向 API 环境的 Renderer，用于将 Expression 中已经确定的结构化数据按照 API Template 转换为 JSON、XML 等确定性的接口表现，并由 ApiAdapter 形成最终 API Response。
最终模型：
Action
↓
ActionResult
↓
Expression
↓
API Template
↓
TemplateEngine
↓
ApiRenderer
↓
JSON / XML
↓
ApiAdapter
↓
API Response因此，ApiRenderer 的核心不是“生成智能答案”，而是：
结构化结果
↓
确定性格式转换
↓
API 表现这与 WSaiOS/ICAI 的认知、推理、决策体系保持清晰分层。