docs: 创建文档目录 + 更新LICENSE + 规范项目文档
- 创建 docs/ 文档目录，包含快速开始、架构说明、插件列表、插件开发、API参考、贡献指南 - 更新 LICENSE 完整 Apache 2.0 模板，添加作者 yongwanxing - README 许可证引用更新为 Copyright 2026 Falck, yongwanxing
This commit is contained in:
Falck
271
README.md
271
README.md
@@ -1,50 +1,24 @@
|
||||
# NebulaShell — 企业级插件化运行时框架
|
||||
# NebulaShell
|
||||
|
||||
<div align="center">
|
||||
[](https://python.org)
|
||||
[](LICENSE)
|
||||
[]()
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**进程级隔离 · 声明式依赖管理 · 多语言运行时 · 热插拔架构**
|
||||
|
||||
[快速开始](#快速开始) · [架构](#架构设计) · [插件生态](#插件生态) · [开发指南](#开发你的第一个插件) · [贡献指南](#贡献指南)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 项目简介
|
||||
|
||||
NebulaShell 是一个面向 **普通用户** 和 **开发者** 的企业级插件化运行时框架，旨在提供类似 Koishi Plus 的终端交互体验。核心设计哲学是「最小化核心」—— 所有功能皆由插件实现，系统核心仅保留最精简的加载与调度能力。
|
||||
|
||||
- **零配置部署**：安装即用，自动处理依赖关系
|
||||
- **进程级隔离**：不可信插件运行在独立进程中，保障宿主安全
|
||||
- **声明式依赖**：插件自行声明所需依赖，系统自动解析与安装
|
||||
- **热插拔架构**：运行时动态加载/卸载/重载插件，业务零中断
|
||||
- **多语言支持**：Python/Node.js/Go 等运行时无缝集成
|
||||
NebulaShell 是一个插件化运行时框架。一切功能皆由插件实现，核心仅保留插件加载与调度能力。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- Python `>= 3.10`
|
||||
- Linux / macOS / WSL2
|
||||
|
||||
### 安装与启动
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
# 克隆
|
||||
git clone https://github.com/Starlight-apk/NebulaShell.git
|
||||
cd NebulaShell
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 启动核心
|
||||
# 启动
|
||||
python main.py
|
||||
```
|
||||
|
||||
@@ -52,232 +26,101 @@ python main.py
|
||||
|
||||
---
|
||||
|
||||
## 架构设计
|
||||
## 插件
|
||||
|
||||
```
|
||||
用户/客户端
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ HTTP API / WebSocket │
|
||||
│ (统一安全网关) │
|
||||
└─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ NebulaShell 微内核 │
|
||||
│ ┌───────────────────────┐ │
|
||||
│ │ Plugin Loader │ │
|
||||
│ │ • 插件发现与加载 │ │
|
||||
│ │ • 依赖解析与注入 │ │
|
||||
│ │ • 生命周期管理 │ │
|
||||
│ └───────────────────────┘ │
|
||||
└─────────────────────────────┘
|
||||
│
|
||||
├── 核心插件层 (可信域)
|
||||
│ ├── HTTP API 服务
|
||||
│ ├── WebSocket 服务
|
||||
│ ├── 数据持久化
|
||||
│ ├── 审计中心
|
||||
│ └── 监控探针
|
||||
│
|
||||
└── 隔离插件层 (不可信域)
|
||||
├── 动态防火墙
|
||||
├── 内网穿透
|
||||
├── FTP 文件服务
|
||||
├── 多语言运行时
|
||||
├── 运维工具箱
|
||||
└── 安全网关
|
||||
```
|
||||
所有功能以插件形式提供，位于 `store/NebulaShell/` 目录下。当前内置 26 个插件。
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 职责 | 技术选型 |
|
||||
|------|------|----------|
|
||||
| **Plugin Loader** | 插件发现、加载、依赖注入 | Python `importlib` + 进程隔离 |
|
||||
| **Plugin Bridge** | 插件间通信（事件总线/RPC） | 自定义事件驱动架构 |
|
||||
| **HTTP API** | RESTful API 网关 | Python `http.server` |
|
||||
| **WebSocket API** | 实时双向通信 | 自定义 WebSocket 实现 |
|
||||
| **WebUI** | 管理控制台 | 纯静态 HTML/CSS/JS |
|
||||
| 插件 | 说明 |
|
||||
|------|------|
|
||||
| `plugin-loader` | 插件加载核心 |
|
||||
| `plugin-bridge` | 插件间通信（事件总线 / RPC） |
|
||||
| `http-api` | RESTful API 服务 |
|
||||
| `ws-api` | WebSocket 服务 |
|
||||
| `webui` | 管理控制台 |
|
||||
| `dashboard` | 系统仪表盘 |
|
||||
| `log-terminal` | 日志查看与终端 |
|
||||
| `pkg-manager` | 插件包管理器 |
|
||||
| `lifecycle` | 生命周期管理 |
|
||||
| `i18n` | 国际化 |
|
||||
| `plugin-storage` | 插件持久化存储 |
|
||||
| `dependency` | 依赖关系解析 |
|
||||
| `hot-reload` | 热重载 |
|
||||
| `signature-verifier` | 签名验证 |
|
||||
| `code-reviewer` | 代码审查 |
|
||||
| `plugin-loader-pro` | 熔断/降级/容错 |
|
||||
| `auto-dependency` | 系统依赖自动安装 |
|
||||
| `performance-optimizer` | 性能优化 |
|
||||
| `nodejs-adapter` | Node.js 运行时适配 |
|
||||
| `http-tcp` | TCP 协议适配 |
|
||||
| `firewall` | 防火墙 |
|
||||
| `ftp-server` | 文件服务 |
|
||||
| `frp-proxy` | 内网穿透 |
|
||||
| `json-codec` | JSON 编解码 |
|
||||
| `log-terminal` | 日志终端 |
|
||||
| `polyglot-deploy` | 多语言部署 |
|
||||
|
||||
---
|
||||
|
||||
## 插件生态
|
||||
## 开发一个插件
|
||||
|
||||
当前共有 **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` 声明其依赖关系，系统自动处理：
|
||||
在 `store/NebulaShell/` 下创建目录，包含 `manifest.json` 和 `main.py`：
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "plugin-bridge",
|
||||
"version": "1.1.0",
|
||||
"type": "core"
|
||||
},
|
||||
"dependencies": ["plugin-storage", "i18n"],
|
||||
"permissions": ["plugin-storage", "lifecycle"]
|
||||
}
|
||||
```
|
||||
|
||||
依赖注入通过 `use()` 函数实现，无需硬编码路径：
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "your-plugin",
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "Your Name",
|
||||
"description": "你的插件描述",
|
||||
"type": "plugin"
|
||||
},
|
||||
"config": {
|
||||
"enabled": true,
|
||||
"args": {}
|
||||
"description": "我的插件"
|
||||
},
|
||||
"config": { "enabled": true, "args": {} },
|
||||
"dependencies": [],
|
||||
"permissions": []
|
||||
}
|
||||
```
|
||||
|
||||
### main.py
|
||||
|
||||
插件需实现 `Plugin` 基类，并暴露 `New()` 工厂函数：
|
||||
|
||||
```python
|
||||
from oss.plugin.types import Plugin
|
||||
|
||||
class YourPlugin(Plugin):
|
||||
def init(self, deps: dict = None):
|
||||
class MyPlugin(Plugin):
|
||||
def init(self, deps=None):
|
||||
pass
|
||||
|
||||
def start(self):
|
||||
pass
|
||||
|
||||
def stop(self):
|
||||
pass
|
||||
|
||||
def New():
|
||||
return YourPlugin()
|
||||
return MyPlugin()
|
||||
```
|
||||
|
||||
### 使用其他插件
|
||||
|
||||
通过 `use()` 获取已加载的插件实例：
|
||||
|
||||
```python
|
||||
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)
|
||||
http_api = use("http-api")
|
||||
webui = use("webui")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 贡献指南
|
||||
## 贡献
|
||||
|
||||
我们欢迎所有形式的贡献，包括但不限于：新功能、Bug 修复、文档改进、测试覆盖。
|
||||
欢迎提交 Issue 和 Pull Request。
|
||||
|
||||
### 开发流程
|
||||
请确保代码通过语法检查：
|
||||
|
||||
1. Fork 仓库并创建特性分支
|
||||
2. 编写代码并添加测试
|
||||
3. 确保通过代码风格检查
|
||||
4. 提交 Pull Request
|
||||
|
||||
### 提交规范
|
||||
|
||||
采用 Conventional Commits 规范：
|
||||
|
||||
```
|
||||
feat: 新功能
|
||||
fix: 修复 Bug
|
||||
refactor: 代码重构
|
||||
docs: 文档变更
|
||||
test: 测试相关
|
||||
chore: 构建/工具/依赖
|
||||
```bash
|
||||
find . -name "*.py" -not -path "./venv/*" -not -path "./.git/*" | \
|
||||
xargs -I{} python3 -m py_compile {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目基于 [Apache License 2.0](LICENSE) 开源。
|
||||
Copyright 2026 Falck, yongwanxing
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Built with ❤️ by NebulaShell Team**
|
||||
|
||||
[GitHub](https://github.com/Starlight-apk/NebulaShell) · [Gitee](https://gitee.com/NebulaBase/NebulaShell)
|
||||
|
||||
</div>
|
||||
Licensed under the [Apache License, Version 2.0](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user