第八十章

WSaiOS API Specification

WSaiOS API规范

80.1 API规范概述

在前面的章节中，我们已经完成：

Kernel
Runtime
Service
Workflow
Capability
Execution Engine
SDK架构

但是：

所有模块之间虽然可以通信，却没有统一的 API 规范。

如果没有 API 标准：

不同模块可能采用不同的调用方式：

knowledge.query(...)

knowledge.search(...)

knowledge.find(...)

都会造成接口不统一。

因此：

WSaiOS 定义统一 API 标准。

80.2 API设计原则

WSaiOS API 遵循以下原则：

（1）接口职责单一

每个 API 完成一种明确功能。

例如：

query()

负责查询。

而不是：

query_and_update()

同时执行多个职责。

（2）统一命名

所有模块采用一致的命名方式：

操作	API
创建	create()
查询	query()
更新	update()
删除	delete()
执行	execute()
验证	validate()

避免：

find()

search()

lookup()

混用。

（3）统一参数

统一：

request

对象。

例如：

service.execute(request)

而不是：

execute(a,b,c,d,e)

（4）统一返回

所有 API：

统一：

Result

对象。

例如：

Result(
    success=True,
    code=0,
    message="OK",
    data={}
)

80.3 API层次

WSaiOS API：

分为四层：

Application API
        │
Capability API
        │
Service API
        │
Kernel API

Application：

永远：

调用：

Capability。

不会直接：

调用：

Kernel。

80.4 Kernel API

Kernel提供：

生命周期管理。

统一接口：

kernel.start()

kernel.stop()

kernel.restart()

kernel.status()

80.5 Service API

统一：

service.initialize()

service.execute(request)

service.shutdown()

Service：

全部一致。

80.6 Capability API

例如：

capability.execute(request)

或者：

capability.validate(request)

能力：

保持统一。

80.7 Workflow API

Workflow：

统一：

workflow.start()

workflow.pause()

workflow.resume()

workflow.cancel()

workflow.status()

生命周期完整。

80.8 Scheduler API

统一：

scheduler.submit(task)

scheduler.cancel(task_id)

scheduler.status(task_id)

所有任务：

统一调度。

80.9 Knowledge API

统一：

knowledge.create()

knowledge.query()

knowledge.update()

knowledge.delete()

符合 CRUD 模式。

80.10 Execution API

统一：

execution.execute(action)

execution.validate(action)

execution.result(action_id)

执行：

职责清晰。

80.11 Event API

统一：

event.publish()

event.subscribe()

event.unsubscribe()

所有模块：

通过：

Event Bus：

通信。

80.12 API错误规范

统一：

错误码。

例如：

Code	说明
0	Success
1001	Invalid Request
1002	Object Not Found
1003	Validation Failed
2001	Workflow Error
3001	Execution Timeout
5000	Internal Error

错误对象：

class ErrorResult:

    code:int

    message:str

80.13 API版本管理

建议：

采用：

v1

v2

v3

接口：

例如：

/api/v1/workflow

避免：

未来：

破坏兼容性。

80.14 API文档规范

建议：

每个 API：

必须说明：

功能
输入
输出
错误码
示例
注意事项

例如：

API:
workflow.start()

Input:
WorkflowRequest

Output:
Result

方便自动生成开发文档。

80.15 API验证

建立自动化测试：

验证：

参数合法性
返回对象结构
错误码一致性
性能指标

例如：

assert result.success is True
assert result.code == 0

80.16 WSaiOS API体系

                 Application

                       │

               Capability API

                       │

                 Service API

                       │

                 Workflow API

                       │

                 Scheduler API

                       │

                  Execution API

                       │

                   Kernel API

注意：

这是逻辑分层，不是调用链。实际调用通常是：

应用 → Capability API
Capability 内部协调 Service API
Service 根据需要调用 Workflow、Scheduler 等 API

Kernel API 主要用于系统生命周期管理，而不是业务接口。

80.17 本章总结

完成：

WSaiOS API Specification

建立：

API命名规范
API层次
Kernel API
Service API
Capability API
Workflow API
Scheduler API
Knowledge API
Execution API
Event API
错误码规范
API版本管理

一个建议：开始补充真正的工程规范

从第80章开始，建议尽量加入可以直接验证和实现的内容，例如：

API 请求/响应数据结构（JSON Schema 或 Pydantic 模型）
Python 接口定义（abc.ABC 抽象基类）
状态机（FSM）定义
OpenAPI 3.1 示例
单元测试示例（pytest）

这样，WSaiOS 将不仅有架构图和流程图，还能直接生成代码、接口文档和自动化测试，实现“工程理论必须能实现验证”的目标。

第八十章 WSaiOS API Specification WSaiOS API规范