系统架构

OryxOS 的目标形态是运行在 JDK 21 上的 Spring Boot 3.x 单体应用，以 Maven 多模块组织，打包为单可执行 JAR。

整体关系

一条处理链路

1. CLI、REST API 或定时任务产生消息。
2. AgentService.process 选择 Profile、管理上下文并编排执行。
3. PromptBuilder 组装 Agent 指令、Bootstrap、记忆、历史与可用工具。
4. ProviderService 调用模型，由模型决定响应或调用工具。
5. ToolExecutor 统一执行工具，实际 IO 前检查应用白名单。
6. 工具结果追加到会话，进入下一轮推理，直到完成或达到迭代上限。
7. 会话与模型、工具调用记录持久化，结果返回触发入口。

模型适配与执行控制

Spring AI / Spring AI Alibaba 负责模型协议转换与工具 schema 生成。OryxOS 自己实现 ReAct，禁用 Spring AI 自动工具执行，防止工具被重复调用。

Provider 维护显式的 provider name → ChatModel 映射，避免在多 Provider 并存时靠 Bean 类型猜测厂商。

上下文与状态

• Agent 定义、公共 Skill 与 Bootstrap 位于文件系统。
• 长期记忆默认保存在 MEMORY.md，通过 MemoryService 统一访问。
• Session、tool_invocations、llm_calls 默认落 SQLite。
• 定时规则从 Profile 动态注册，更新时清理旧句柄，避免重复触发。

工具边界

内置工具、MCP 与 Java 工具统一适配 OryxTool，通过工具执行链路调度。WhitelistSandbox 校验文件路径、可执行命令与网络目标。

应用白名单不是容器级隔离。解释器仍拥有宿主进程权限；不可信代码与多租户执行需要后续独立容器或 MicroVM Runner。

REST 接口设计

核心阶段规划 10 个端点，前缀为 /api/v1：

方法	路径	功能
POST	/sessions	创建会话
POST	/sessions/{id}/messages	发送消息
GET	/sessions/{id}	查询对话
DELETE	/sessions/{id}	归档会话
POST	/agents/{name}/invoke	无状态调用
GET	/profiles	列配置
GET	/memory	长期记忆
GET	/tools	可用工具
GET	/health	健康检查
GET	/info	运行信息

接口采用 ApiResponse 信封：code、message、data、timestamp。以上为设计说明，暂不提供在线运行时服务。

详细模块目录与演进内容见 技术方案。