NebulaShell/README.md

NebulaShell — 企业级插件化运行时框架

进程级隔离 · 声明式依赖管理 · 多语言运行时 · 热插拔架构

快速开始 · 架构 · 插件生态 · 开发指南 · 贡献指南

---

项目简介

NebulaShell 是一个面向 普通用户 和 开发者 的企业级插件化运行时框架，旨在提供类似 Koishi Plus 的终端交互体验。核心设计哲学是「最小化核心」—— 所有功能皆由插件实现，系统核心仅保留最精简的加载与调度能力。

• 零配置部署：安装即用，自动处理依赖关系
• 进程级隔离：不可信插件运行在独立进程中，保障宿主安全
• 声明式依赖：插件自行声明所需依赖，系统自动解析与安装
• 热插拔架构：运行时动态加载/卸载/重载插件，业务零中断
• 多语言支持：Python/Node.js/Go 等运行时无缝集成

---

快速开始

前置要求

• Python >= 3.10
• Linux / macOS / WSL2

安装与启动

# 克隆仓库
git clone https://github.com/Starlight-apk/NebulaShell.git
cd NebulaShell

# 安装依赖
pip install -r requirements.txt

# 启动核心
python main.py

启动后访问 http://localhost:8080 进入管理控制台。

---

架构设计

用户/客户端
    │
    ▼
┌─────────────────────────────┐
│      HTTP API / WebSocket     │
│      (统一安全网关)           │
└─────────────────────────────┘
    │
    ▼
┌─────────────────────────────┐
│       NebulaShell 微内核      │
│  ┌───────────────────────┐  │
│  │   Plugin Loader       │  │
│  │   • 插件发现与加载    │  │
│  │   • 依赖解析与注入    │  │
│  │   • 生命周期管理      │  │
│  └───────────────────────┘  │
└─────────────────────────────┘
    │
    ├── 核心插件层 (可信域)
    │   ├── HTTP API 服务
    │   ├── WebSocket 服务
    │   ├── 数据持久化
    │   ├── 审计中心
    │   └── 监控探针
    │
    └── 隔离插件层 (不可信域)
        ├── 动态防火墙
        ├── 内网穿透
        ├── FTP 文件服务
        ├── 多语言运行时
        ├── 运维工具箱
        └── 安全网关

核心组件

组件	职责	技术选型
Plugin Loader	插件发现、加载、依赖注入	Python importlib + 进程隔离
Plugin Bridge	插件间通信（事件总线/RPC）	自定义事件驱动架构
HTTP API	RESTful API 网关	Python http.server
WebSocket API	实时双向通信	自定义 WebSocket 实现
WebUI	管理控制台	纯静态 HTML/CSS/JS

---

插件生态

当前共有 26 个官方插件，涵盖基础设施、安全、网络、运维、开发者工具等领域。

基础设施

插件	描述	状态
plugin-loader	插件加载核心	稳定
plugin-bridge	插件间通信/事件总线/RPC	稳定
plugin-storage	插件持久化存储	稳定
lifecycle	插件生命周期管理	稳定
hot-reload	热重载支持	稳定
i18n	国际化支持	稳定
dependency	依赖关系解析	稳定

网络与安全

插件	描述	状态
http-api	RESTful API 服务	稳定
http-tcp	TCP 协议适配	稳定
ws-api	WebSocket 服务	稳定
firewall	动态防火墙	Beta
ftp-server	FTP 文件服务	Beta
frp-proxy	内网穿透	Beta

运维与管理

插件	描述	状态
webui	Web 管理控制台	稳定
dashboard	系统仪表盘	稳定
log-terminal	日志查看与 SSH 终端	稳定
pkg-manager	插件包管理器	稳定
auto-dependency	系统依赖自动安装	稳定
performance-optimizer	性能优化器	Beta

开发者工具

插件	描述	状态
code-reviewer	代码审查	Beta
nodejs-adapter	Node.js 运行时适配	Beta
signature-verifier	插件签名验证	稳定
plugin-loader-pro	高级插件加载器（熔断/降级/容错）	Beta

插件依赖管理

插件通过 manifest.json 声明其依赖关系，系统自动处理：

{
  "metadata": {
    "name": "plugin-bridge",
    "version": "1.1.0",
    "type": "core"
  },
  "dependencies": ["plugin-storage", "i18n"],
  "permissions": ["plugin-storage", "lifecycle"]
}

依赖注入通过 use() 函数实现，无需硬编码路径：

from store.NebulaShell.plugin_bridge.main import use

storage = use("plugin-storage")
i18n = use("i18n")

---

开发你的第一个插件

目录结构

store/NebulaShell/your-plugin/
├── manifest.json      # 插件元数据与依赖声明
├── main.py            # 插件入口
└── SIGNATURE          # 签名文件（可选）

manifest.json

{
  "metadata": {
    "name": "your-plugin",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "你的插件描述",
    "type": "plugin"
  },
  "config": {
    "enabled": true,
    "args": {}
  },
  "dependencies": [],
  "permissions": []
}

main.py

插件需实现 Plugin 基类，并暴露 New() 工厂函数：

from oss.plugin.types import Plugin

class YourPlugin(Plugin):
    def init(self, deps: dict = None):
        pass

    def start(self):
        pass

    def stop(self):
        pass

def New():
    return YourPlugin()

使用其他插件

from store.NebulaShell.plugin_bridge.main import use

class YourPlugin(Plugin):
    def init(self, deps: dict = None):
        http_api = use("http-api")
        if http_api:
            http_api.router.get("/api/your-endpoint", self.handler)

---

贡献指南

我们欢迎所有形式的贡献，包括但不限于：新功能、Bug 修复、文档改进、测试覆盖。

开发流程

1. Fork 仓库并创建特性分支
2. 编写代码并添加测试
3. 确保通过代码风格检查
4. 提交 Pull Request

提交规范

采用 Conventional Commits 规范：

feat: 新功能
fix: 修复 Bug
refactor: 代码重构
docs: 文档变更
test: 测试相关
chore: 构建/工具/依赖

---

许可证

本项目基于 Apache License 2.0 开源。

---

Built with ❤️ by NebulaShell Team

GitHub · Gitee