# OctoAgent_Core

**Repository Path**: octoagent/octoagent_core

## Basic Information

- **Project Name**: OctoAgent_Core
- **Description**: OctoAgent-Core 是 OctoAgent 智能管理系统的微内核引擎，采用“本地优先”架构实现算力成本降低 90%。作为核心底座，它通过热插拔集成七大核心功能模块：算力节约模块（智能路由降本）、智能交互模块（自然语言驱动）、动态组织模块（零代码生成架构）、流程生成模块（业务描述转可执行流程）、沙箱验证模块（逻辑严谨性保障）、执行引擎模块（自动化流转）及数据融合模块（三流合一预警）。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OctoAgent-Core

#### 介绍
OctoAgent-Core – 企业级智能管理系统的微内核主程序
一、 软件概述
OctoAgent-Core 是 OctoAgent 智能管理系统的微内核引擎，采用“本地优先”架构实现算力成本降低 90%。作为核心底座，它通过热插拔集成七大核心功能模块：算力节约模块（智能路由降本）、智能交互模块（自然语言驱动）、动态组织模块（零代码生成架构）、流程生成模块（业务描述转可执行流程）、沙箱验证模块（逻辑保障）、执行引擎模块（自动流转）及数据融合模块（三流合一），实现项目工作智能管理。

二、 主程序核心功能
1. 微内核容器

极简内核设计，不包含具体业务逻辑，仅作为功能模块的运行容器。
支持插件的动态发现、加载和卸载，实现真正的热插拔。
2. 插件生命周期管理

自动扫描符合命名规范的插件包，完成实例化与注册。
统一管理插件的初始化、执行与释放。
3. 标准接口定义

定义 BaseModule 抽象基类，规范所有模块必须实现的元数据、初始化与执行方法。
确保插件生态的统一性与可维护性。
4. 统一 API 网关

基于 FastAPI 构建统一入口，支持 RESTful 与 WebSocket 协议。
实现请求路由、权限校验与流式响应，为前端与第三方系统提供标准接口。
5. 全局配置与通信管理

集中管理环境变量、数据库连接等配置信息。
提供事件总线机制，支持插件间的解耦通信。

三、 功能模块概述
所有功能模块以插件形式存在，通过标准接口与主程序交互，实现高内聚、低耦合的模块化架构：

1. 算力节约模块

智能路由决策：根据任务复杂度与数据位置，自动选择本地模型或云端服务。
成本优化：最大化本地计算，降低云端 API 依赖，节省算力成本。
2. 智能交互模块

自然语言驱动：支持文字、语音、文件等多模态输入，实现零门槛操作。
意图解析：将用户指令转化为结构化任务，支持多轮对话与上下文记忆。
3. 动态组织架构模块

零代码生成：通过自然语言或图片动态创建部门与岗位模块。
热插拔注册：生成的模块实时生效，支持组织结构的灵活调整。
4. 流程构建与沙箱验证模块

流程自动生成：将业务描述转化为可执行的 BPMN 流程定义。
逻辑严谨性保障：通过形式化验证算法，自动检测死循环、断路等逻辑错误。
5. 业务流程执行引擎模块

状态机驱动：管理流程实例的流转、挂起、回退与终止。
任务分发：自动触发审批、通知等业务操作。
6. 数据融合与智能预警模块

三流合一：构建物资流、信息流、资金流的关联图谱。
智能预警：基于规则引擎实现风险前置感知与实时告警。
7. 知识资产管理模块

GraphRAG 检索：实现文档知识的向量化存储与语义检索。
知识库问答：支持基于企业历史数据的智能问答与经验复用。

四、 技术特点
微内核架构：核心极简，功能扩展通过插件实现，系统稳定性高。
标准契约：统一的插件接口规范，确保生态兼容性。
高性能网关：FastAPI 异步框架，支持高并发与实时通信。
Apache 2.0 协议：提供明确的专利授权保护，适合商业集成。


#### 软件架构
软件架构说明
1. 架构概览
OctoAgent-Core 采用 微内核 架构模式。该架构的核心思想是将系统划分为一个极简的 核心层 和多个独立的功能 插件层。核心层仅负责插件的生命周期管理、通信总线与对外接口，不包含任何具体业务逻辑。所有业务功能均以标准插件形式存在，实现了系统的高度可扩展性与解耦。

1.1 逻辑架构视图
系统自下而上分为基础设施层、核心层、插件层和接入层。

┌──────────────────────────────────────────────────────────────────────────┐
│                              接入层                       │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐              │
│  │  Web UI (Vue3) │  │  API Client    │  │  MCP Client    │              │
│  │  (单一对话框)   │  │  (第三方调用)   │  │  (生态互联)     │              │
│  └───────┬────────┘  └───────┬────────┘  └───────┬────────┘              │
└──────────┼───────────────────┼───────────────────┼───────────────────────┘
           │ (HTTPS/WS)        │ (REST)            │ (MCP Protocol)
           ▼                   ▼                   ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                           主程序                        │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                        核心层                          │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │  │
│  │  │ API Gateway │  │ Plugin Mgr  │  │ Event Bus   │              │  │
│  │  │ (FastAPI)   │  │ (Loader)    │  │ (AsyncIO)   │              │  │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │  │
│  │         │                │                │                     │  │
│  │         └────────────────┼────────────────┘                     │  │
│  └──────────────────────────┼──────────────────────────────────────┘  │
│                             │ (BaseModule Interface)                  │
└─────────────────────────────┼────────────────────────────────────────┘
                              ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                            插件层                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                  │
│  │ 算力节约模块  │  │ 智能交互模块  │  │ 组织架构模块  │                  │
│  │ (Router)     │  │ (Chat)       │  │ (Org)        │                  │
│  └──────────────┘  └──────────────┘  └──────────────┘                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                  │
│  │ 流程构建模块  │  │ 执行引擎模块  │  │ 数据融合模块  │                  │
│  │ (Flow)       │  │ (Engine)     │  │ (Data)       │                  │
│  └──────────────┘  └──────────────┘  └──────────────┘                  │
└──────────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼────────────────────────────────────────┐
│                      基础设施层                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                │
│  │ 数据存储      │  │ 模型服务      │  │ 外部服务      │                │
│  │ (PG/Neo4j)   │  │ (Ollama/LLM) │  │ (SAP/ERP)    │                │
│  └──────────────┘  └──────────────┘  └──────────────┘                │
└────────────────────────────────────────────────────────────────────────┘

2. 核心层设计详解
核心层是微内核的大脑，负责维持系统的基本运转。

2.1 API 网关
技术组件：FastAPI + Uvicorn。
职责：
统一入口：所有外部请求（HTTP/WebSocket）均通过网关进入。
路由分发：解析请求中的 module_name，将请求转发给对应的插件实例。
协议适配：支持 RESTful API 和 MCP (Model Context Protocol) 协议，实现生态互联。
异常处理：全局捕获插件执行异常，统一返回标准错误格式。
2.2 插件管理器
核心机制：基于 Python 的 importlib 和 pkgutil 实现。
生命周期：
扫描：系统启动时，扫描 Python 环境中所有符合命名规则（octoagent_*）的包。
加载：动态导入包，调用 entry_point() 函数获取插件实例。
注册：将插件实例存入内存注册表。
调度：接收网关指令，调用插件的 execute() 方法。
代码体现：src/core/loader.py。
2.3 标准接口定义
核心契约：BaseModule 抽象类。
规范内容：
metadata：模块身份标识（名称、版本、描述）。
initialize()：模块初始化钩子（如连接数据库、加载模型）。
execute()：业务逻辑执行入口（接收输入，返回输出）。
设计意图：确保所有插件具有统一的行为模式，实现“即插即用”。
2.4 事件总线
技术组件：基于 asyncio Queue 或 Redis Pub/Sub。
职责：实现插件间的松耦合通信。
应用场景：
当“组织架构模块”创建了新部门时，发布 ORG_CREATED 事件。
“权限模块”订阅该事件并自动初始化权限。

3. 插件体系设计
插件是 OctoAgent 业务逻辑的载体。

3.1 插件规范
所有插件必须遵循以下规范：

包名约定：必须以 octoagent_ 开头（如 octoagent_router）。
入口函数：必须在 __init__.py 中定义 entry_point() 函数。
接口实现：必须继承 BaseModule 类。
3.2 插件分类
核心功能插件：如算力节约模块，直接嵌入系统核心流程。
业务应用插件：如合同管理、审批流程，可按需安装。
连接器插件：如 SAP 连接器，用于对接外部系统。

4. 数据与计算架构
4.1 本地优先计算
系统采用分层计算模型，优先利用本地算力：
| 层级 | 计算位置 | 响应延迟 | 典型场景 |
| :--- | :--- | :--- | :--- |
| **L1** | 内存缓存 | <1ms | 会话状态、高频权限查询 |
| **L2** | 本地数据库 | 1-10ms | 结构化数据查询、事务处理 |
| **L3** | 本地模型 | 10-100ms | 意图识别、文本生成 |
| **L5** | 云端模型 | >200ms | 复杂推理、创意生成 |

4.2 数据存储策略
PostgreSQL + JSONB：存储动态 Schema 的业务数据。
Neo4j：构建“三流合一”（物资、信息、资金）关联图谱。
Milvus：存储向量数据，支持语义检索。

5. 部署架构
系统支持灵活的部署模式以适应不同场景：

单机模式：适用于个人开发或内网环境，使用 SQLite 本地数据库。
私有化部署：适用于企业内网，数据完全本地化，支持 GPU 服务器。
云原生模式：基于 Kubernetes (K8s) 部署，支持弹性伸缩。

6.安全性设计
认证鉴权：集成 OAuth2 / JWT，支持细粒度的 RBAC 权限控制。
数据隔离：基于租户的数据隔离策略。
安全传输：全链路 HTTPS / WSS 加密。
代码审计：核心代码开源，接受社区安全审计。


#### 安装教程

🚀 安装教程
1. 环境要求
Python 3.10 或更高版本
pip 包管理工具
2. 安装主程序
建议创建一个虚拟环境进行隔离：
# 1. 克隆项目
git clone https://gitee.com/octoagent/octoagent-core.git
cd octoagent-core

# 2. 创建虚拟环境 (可选但推荐)
python -m venv venv
# Windows 激活: venv\Scripts\activate
# Linux/Mac 激活: source venv/bin/activate

# 3. 安装主程序包
pip install -e .

3. 安装功能插件 (重要)
微内核本身不包含业务功能，您需要安装所需的插件。以下是官方提供的两个核心插件：

安装交互模块：
pip install git+https://gitee.com/octoagent/octoagent-interaction.git
安装组织模块：
pip install git+https://gitee.com/octoagent/octoagent-organization.git
(注：如果您是在本地开发，请进入各插件目录执行 pip install -e .)


#### 使用说明

📘 使用说明
1. 启动后端服务
使用 Uvicorn 启动主程序：
uvicorn octoagent_core.main:app --reload --port 8000
关键检查：
观察终端输出，确保看到以下日志，说明插件加载成功：
===== 开始扫描插件... =====
>>> [成功] 加载插件: interaction
>>> [成功] 加载插件: organization
===== 插件扫描完成，共加载 2 个模块。 =====
INFO:     Uvicorn running on http://127.0.0.1:8000
2. 启动前端界面
主程序内置了静态文件服务，启动后直接访问：
👉 http://localhost:8000/static/index.html

3. 功能体验
场景一：对话与意图识别

在对话框输入：你好，帮我计算一下
系统将调用 interaction 模块，返回意图解析结果。
场景二：动态创建部门

在对话框输入：创建采购部，包含经理岗位
系统将调用 organization 模块。
左侧列表将自动更新，显示“采购部”卡片。
点击卡片上的“进入模块”，可查看组织架构图。

🛠️ 开发指南：
编写您的第一个插件
开发一个符合规范的插件只需三步：

创建项目：包名必须以 octoagent_ 开头。
实现接口：继承 BaseModule 并实现 initialize 和 execute 方法。
定义入口：在 __init__.py 中定义 entry_point 函数。
示例代码 (main.py)：
from octoagent_core.core.base_module import BaseModule, ModuleMetadata

class MyModule(BaseModule):
    @property
    def metadata(self):
        return ModuleMetadata(name="my_module", version="1.0", description="Demo")

    def initialize(self, config): pass
    
    def execute(self, task_input):
        return {"success": True, "message": "Hello!"}

📂 项目结构
octoagent-core/
├── src/
│   └── octoagent_core/
│       ├── api/              # FastAPI 接口与静态文件挂载
│       ├── core/             # 插件加载器与基类定义
│       ├── config.py         # 全局配置
│       └── main.py           # 启动入口
├── static/                   # 前端 UI 界面 (Vue3)
├── tests/                    # 单元测试
└── pyproject.toml
#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)