oryxos: Instructions file for Claude Code

OryxOS — Claude Code 项目指南

OryxOS 是用 Java 实现的面向企业场景的 Distributed AI Agent OS。装在企业自己的 K8s 或服务器上，作为统一底座运行多个业务 Agent，共享渠道接入、模型路由、工具调用、记忆系统、沙箱执行能力。数据完全留在企业自己的基础设施，不锁任何云生态。

长期目标：走进 Apache 基金会，成为 Apache 顶级项目。

详细背景：docs/DemandAnalysis.md（需求）、docs/TechnicalSolution.md（技术方案）、docs/IndustryResearch.md（业界调研）、docs/AiProgrammingGuide.md（AI 编程指南）、docs/oryxos.md（项目定位）

---

技术栈

组件	选型
语言 / 运行时	Java 21（必须，virtual thread 处理并发）
框架	Spring Boot 3.x
LLM 调用	Spring AI Alibaba（仅用协议转换 + @Tool schema 生成）
HTTP 服务	Spring MVC + Java 21 Virtual Thread
命令行	Picocli
YAML 解析	SnakeYAML
持久化	SQLite（默认零配置）/ PostgreSQL 14+（部署选项，url 自动识别）+ Spring Data JPA；表结构由 Flyway 管理（db/migration/{vendor}/）
日志	Logback + SLF4J（结构化 JSON）
构建	Maven 多模块

---

模块结构（14 个）

oryxos/
├── oryxos-core          # 核心抽象：OryxTool 接口、Session、Profile、ContextLoader、
│                        #   ReActLoop、PromptBuilder、ToolExecutor、AgentService
├── oryxos-persona       # 025 人格库（copy-in 模板库）：PersonaPresetCatalog（内置 12 只读、
│                        #   classpath）、PersonaStore/PersonaService（.oryxos/personas/ 自定义 CRUD）
├── oryxos-provider      # 能力一：ProviderService、Function Calling 适配、
│                        #   多 Provider 显式映射
├── oryxos-memory        # 能力三：MemoryService 门面、LongTermMemory 三档后端、
│                        #   MemoryRecallEngine 三路召回 + MemoryVectorIndex（015）、
│                        #   MemoryTools（save/recall）
├── oryxos-knowledge     # 知识库（014）：LocalKnowledgeBackend（契约第一个插件）、
│                        #   解析/切分/向量化索引流水线、双路召回+RRF 检索、
│                        #   ChunkStore 可插拔存储、KnowledgeTools（retrieve_knowledge）
│                        #   （契约与绑定服务在 oryxos-core/knowledge/，依赖倒置）
├── oryxos-tool          # 能力四：内置 Tool（文件/Shell/HTTP）、MCP Client、
│                        #   ToolRegistry、SandboxChecker
├── oryxos-channel-cli   # CLI Channel：oryxos chat 实现
├── oryxos-channel-feishu # 飞书 IM 入站渠道（017）：oapi-sdk 长连接收 im.message.receive_v1、
│                        #   FeishuEventNormalizer（@ 判定/剥离）、FeishuMessageSender（分段+沙箱）
│                        #   （入站渠道契约与共享编排在 oryxos-core/channel/，依赖倒置）
├── oryxos-channel-wecom  # 企微智能机器人入站渠道（对称飞书）：长连接收消息、免公网回调，
│                        #   WeComEventNormalizer（@ 判定/剥离）、WeComMessageSender（分段+沙箱）
│                        #   （入站渠道契约与共享编排在 oryxos-core/channel/，依赖倒置）
├── oryxos-channel-dingtalk # 钉钉机器人入站渠道（对称飞书/企微）：Stream 长连接收消息、
│                        #   DingTalkEventNormalizer（@ 判定/剥离）、DingTalkMessageSender（分段+沙箱）、
│                        #   断线自动重连（对齐企微）
│                        #   （入站渠道契约与共享编排在 oryxos-core/channel/，依赖倒置）
├── oryxos-web           # 能力五：WebServer、ApiController、GlobalExceptionHandler、
│                        #   OpenAPI
├── oryxos-storage       # 持久化：SQLite、SessionRepository、
│                        #   ToolInvocationRepository、LlmCallRepository
├── oryxos-cli           # 命令行入口：Picocli 主入口、13 个子命令、ConfigLoader（025：agent import）
└── oryxos-boot          # Spring Boot 启动模块：主类、自动配置、依赖聚合