starlight-apk/NebulaShell
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 创建文档目录 + 更新LICENSE + 规范项目文档

Browse Source 
- 创建 docs/ 文档目录，包含快速开始、架构说明、插件列表、插件开发、API参考、贡献指南
- 更新 LICENSE 完整 Apache 2.0 模板，添加作者 yongwanxing
- README 许可证引用更新为 Copyright 2026 Falck, yongwanxing
This commit is contained in:
Falck
2026-05-03 09:44:43 +08:00
parent 6460b28060
commit ba58b3939a
8 changed files with 510 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
LICENSE
View File

@@ -167,7 +167,7 @@
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
on Your own behalf and on your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
@@ -175,7 +175,18 @@
END OF TERMS AND CONDITIONS
Copyright 2026 Falck
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2026 Falck, yongwanxing
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.

271
README.md
View File

@@ -1,50 +1,24 @@
# NebulaShell — 企业级插件化运行时框架
# NebulaShell
<div align="center">
[![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![build](https://img.shields.io/badge/build-passing-brightgreen)]()
![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python)
![License](https://img.shields.io/badge/license-Apache--2.0-green)
![Status](https://img.shields.io/badge/build-passing-brightgreen)
![Plugins](https://img.shields.io/badge/plugins-26-informational)
**进程级隔离 · 声明式依赖管理 · 多语言运行时 · 热插拔架构**
[快速开始](#快速开始) · [架构](#架构设计) · [插件生态](#插件生态) · [开发指南](#开发你的第一个插件) · [贡献指南](#贡献指南)
</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).

69
docs/api/http-api.md Normal file
View File

@@ -0,0 +1,69 @@
# HTTP API
`http-api` 插件提供 RESTful API 服务。启动后默认监听 `http://localhost:8080`。
## 路由
所有内置 API 端点以 `/api/` 开头。
### 系统
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/status` | 系统状态（无需认证） |
| GET | `/api/health` | 健康检查 |
### 插件
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/plugins` | 列出所有已加载插件 |
| GET | `/api/plugins/{name}` | 获取插件信息 |
| POST | `/api/plugins/{name}/init` | 初始化插件 |
| POST | `/api/plugins/{name}/start` | 启动插件 |
| POST | `/api/plugins/{name}/stop` | 停止插件 |
### 仪表盘
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/dashboard/stats` | 系统实时状态（CPU/内存/网络） |
| GET | `/api/dashboard/history` | 历史数据 |
### 包管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/packages/search` | 搜索可用插件 |
| GET | `/api/packages/list` | 列出已安装插件 |
| POST | `/api/packages/install` | 安装插件 |
| POST | `/api/packages/uninstall` | 卸载插件 |
### 国际化
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/i18n/locales` | 获取支持的语言列表 |
| GET | `/api/i18n/translate` | 翻译文本 |
| POST | `/api/i18n/locale` | 切换语言 |
## 认证
如果配置了 `API_KEY`，所有 API 请求需要在 Header 中携带：
```
Authorization: Bearer <your-api-key>
```
当 `API_KEY` 为空时，认证中间件自动禁用，所有端点公开访问。
## 自定义路由
在插件中注册自定义路由：
```python
from store.NebulaShell.plugin_bridge.main import use
http_api = use("http-api")
http_api.router.get("/api/my-endpoint", my_handler)
```

69
docs/dev/contributing.md Normal file
View File

@@ -0,0 +1,69 @@
# 贡献指南
## 提交规范
采用 Conventional Commits 格式：
```
<type>: <描述>
feat: 新功能
fix: 修复 bug
refactor: 代码重构
docs: 文档变更
test: 测试相关
chore: 构建/工具/依赖
perf: 性能优化
style: 代码风格调整
```
## 开发环境
```bash
# 克隆并安装
git clone https://github.com/Starlight-apk/NebulaShell.git
cd NebulaShell
python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt
# 创建特性分支
git checkout -b feature/your-feature
```
## 代码规范
- Python 代码遵循 PEP 8
- 使用 `black` 格式化（行长度 88）
- 使用 `pylint` 进行静态检查
```bash
# 代码格式化
black oss/ store/
# 语法检查
python -m pylint oss/ store/ --exit-zero
```
## 语法检查
所有 `.py` 文件必须通过 `py_compile` 检查：
```bash
find . -name "*.py" \
-not -path "./venv/*" \
-not -path "./.git/*" \
| xargs -I{} python3 -m py_compile {}
```
## 测试
```bash
pytest oss/tests/
```
## Pull Request
1. 确保代码通过语法检查和测试
2. 更新相关文档
3. 提交 PR 时描述变更内容和动机

74
docs/guide/architecture.md Normal file
View File

@@ -0,0 +1,74 @@
# 架构说明
## 设计原则
NebulaShell 遵循「最小化核心」设计哲学：
- 核心框架（`oss/`）只负责加载 `plugin-loader` 这一个插件
- 所有功能皆由插件实现，包括 HTTP 服务、WebSocket、WebUI 等
- 插件加载器负责发现、加载、管理所有其他插件
## 架构分层
```
用户/客户端
│
▼
┌─────────────────────────────┐
│ HTTP API / WebSocket │ ← 由 http-api / ws-api 插件提供
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Plugin Loader │ ← 由 oss/plugin/manager.py 加载
│ • 插件发现与加载 │
│ • 依赖解析与注入 │
│ • 生命周期管理 │
└─────────────────────────────┘
│
├── 核心插件
│ ├── plugin-bridge 插件间通信
│ ├── lifecycle 生命周期
│ ├── plugin-storage 持久化存储
│ └── i18n 国际化
│
├── 网络服务
│ ├── http-api RESTful API
│ ├── ws-api WebSocket
│ └── http-tcp TCP 适配
│
├── 管理工具
│ ├── webui 管理控制台
│ ├── dashboard 系统仪表盘
│ ├── log-terminal 日志终端
│ └── pkg-manager 包管理
│
└── 扩展
├── firewall 防火墙
├── ftp-server 文件服务
├── frp-proxy 内网穿透
└── ...
```
## 插件加载流程
1. `oss/plugin/manager.py` 通过 `PluginLoader` 加载 `plugin-loader` 插件
2. `plugin-loader` 扫描 `store/` 目录下所有插件的 `manifest.json`
3. 按 `load_priority` 排序，优先加载标记为 `"first"` 的插件（如 `plugin-bridge`）
4. 加载所有插件，解析 `dependencies` 字段并注入依赖
5. 按依赖顺序调用每个插件的 `init()` → `start()`
## 插件间通信
插件通过 `plugin-bridge` 提供的机制通信：
- **事件总线**：发布/订阅模式，解耦通信
- **服务注册表**：RPC 式服务调用
- **`use()` 函数**：直接获取已加载的插件实例
```python
from store.NebulaShell.plugin_bridge.main import use
storage = use("plugin-storage")
http_api = use("http-api")
```

34
docs/guide/getting-started.md Normal file
View File

@@ -0,0 +1,34 @@
# 快速开始
## 前置条件
- Python >= 3.10
- Linux / macOS / WSL2
## 安装
```bash
git clone https://github.com/Starlight-apk/NebulaShell.git
cd NebulaShell
pip install -r requirements.txt
```
## 启动
```bash
python main.py
```
启动后访问 http://localhost:8080 进入管理控制台。
## 配置
首次启动会自动生成 `oss.config.json`，位于项目根目录。主要配置项：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `HOST` | `127.0.0.1` | 监听地址 |
| `HTTP_API_PORT` | `8080` | HTTP 服务端口 |
| `STORE_DIR` | `store` | 插件存放目录 |
| `DATA_DIR` | `data` | 数据存储目录 |
| `API_KEY` | 空 | API 认证密钥（为空时禁用认证） |

130
docs/plugins/development.md Normal file
View File

@@ -0,0 +1,130 @@
# 插件开发
## 目录结构
```
store/NebulaShell/your-plugin/
├── manifest.json # 插件元数据与依赖声明（必需）
├── main.py # 插件入口（必需）
└── SIGNATURE # 签名文件（可选，签名验证用）
```
## manifest.json
```json
{
"metadata": {
"name": "your-plugin",
"version": "1.0.0",
"author": "Your Name",
"description": "插件描述",
"type": "plugin"
},
"config": {
"enabled": true,
"args": {}
},
"dependencies": [],
"permissions": []
}
```
| 字段 | 说明 |
|------|------|
| `metadata.name` | 插件名，用于 `use()` 调用和依赖声明 |
| `metadata.type` | 插件类型：`core` 为核心插件，`plugin` 为普通插件 |
| `config.enabled` | 是否启用 |
| `dependencies` | 依赖的其他插件名列表 |
| `permissions` | 权限声明列表 |
| `metadata.load_priority` | 设为 `"first"` 可在插件加载器中优先加载 |
## main.py
插件需实现 `Plugin` 基类，并暴露 `New()` 工厂函数：
```python
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()
```
### 生命周期
| 方法 | 调用时机 | 说明 |
|------|----------|------|
| `__init__` | 插件实例创建时 | 初始化成员变量，不要做耗时操作 |
| `init(deps)` | 所有插件加载后 | 初始化资源，此时可安全调用其他插件 |
| `start()` | 所有插件 init 完成后 | 启动服务、注册路由、开始监听 |
| `stop()` | 关闭时 | 清理资源、保存状态 |
## 使用其他插件
通过 `use()` 函数获取已加载的插件实例：
```python
from store.NebulaShell.plugin_bridge.main import use
class YourPlugin(Plugin):
def init(self, deps: dict = None):
storage = use("plugin-storage")
if storage:
storage.set("my_key", "my_value")
def start(self):
http_api = use("http-api")
if http_api and hasattr(http_api, 'router'):
http_api.router.get("/api/hello", self._hello_handler)
def _hello_handler(self, request):
from oss.plugin.types import Response
return Response(status=200, body='{"message": "Hello"}',
headers={"Content-Type": "application/json"})
```
`use()` 会自动扫描 `store/` 下所有命名空间目录，读取 `manifest.json` 匹配插件名。已加载的插件会被缓存，不会重复加载。
## 注册 HTTP 路由
如果依赖了 `http-api` 插件，可以在其 router 上注册路由：
```python
http_api = use("http-api")
http_api.router.get("/api/my-endpoint", my_handler)
http_api.router.post("/api/my-endpoint", my_handler)
```
## 注册 WebUI 页面
如果依赖了 `webui` 插件，可以注册管理页面：
```python
webui = use("webui")
webui.register_page(
path='/my-page',
content_provider=my_content_provider,
nav_item={'icon': 'ri-star-line', 'text': '我的页面'}
)
```
## 使用事件总线
`plugin-bridge` 提供事件总线，实现插件间解耦通信：
```python
bridge = use("plugin-bridge")
bridge.event_bus.on("user.login", self._on_user_login)
bridge.event_bus.emit(
bridge.BridgeEvent(type="user.login", source_plugin="my-plugin")
)
```

64
docs/plugins/list.md Normal file
View File

@@ -0,0 +1,64 @@
# 插件列表
所有插件位于 `store/NebulaShell/` 目录下，每个插件包含 `manifest.json`（元数据）和 `main.py`（入口）。
## 基础设施
| 插件 | 说明 | 依赖 |
|------|------|------|
| plugin-loader | 插件加载核心，负责发现、加载、管理所有插件 | 无 |
| plugin-bridge | 插件间通信：事件总线、服务注册表、广播 | plugin-storage, i18n |
| plugin-storage | 插件持久化存储，提供键值存储和文件读写 | i18n |
| lifecycle | 插件生命周期管理，管理启动/停止顺序 | 无 |
| hot-reload | 文件变更监听，支持插件热重载 | 无 |
| i18n | 国际化支持，多语言翻译 | 无 |
| dependency | 依赖关系解析，拓扑排序 | 无 |
## 网络服务
| 插件 | 说明 | 依赖 |
|------|------|------|
| http-api | RESTful API 服务，路由注册与请求处理 | i18n |
| ws-api | WebSocket 服务，实时双向通信 | i18n |
| http-tcp | TCP 协议适配，将 TCP 连接转为 HTTP 请求 | i18n |
## 管理工具
| 插件 | 说明 | 依赖 |
|------|------|------|
| webui | Web 管理控制台，插件页面注册容器 | http-api, i18n |
| dashboard | 系统仪表盘，CPU/内存/网络实时监控 | http-api, webui |
| log-terminal | 日志查看器与 SSH 终端 | http-api, webui |
| pkg-manager | 插件包管理器，从 Gitee 仓库安装/卸载插件 | http-api, webui, plugin-storage, i18n |
## 安全
| 插件 | 说明 | 依赖 |
|------|------|------|
| signature-verifier | 插件签名验证，确保插件完整性 | plugin-storage, i18n |
| plugin-loader-pro | 高级插件加载器：熔断、降级、容错、自动修复 | plugin-loader |
## 开发者工具
| 插件 | 说明 | 依赖 |
|------|------|------|
| code-reviewer | 代码审查，检查代码质量、安全、风格 | 无 |
| nodejs-adapter | Node.js 运行时适配，在插件中运行 JavaScript | 无 |
| performance-optimizer | 性能优化器，缓存、对象池、字符串驻留 | 无 |
| auto-dependency | 系统依赖自动检测与安装 | plugin-loader |
| json-codec | JSON 编解码，提供高性能序列化 | 无 |
## 网络扩展
| 插件 | 说明 | 依赖 |
|------|------|------|
| firewall | 动态防火墙规则管理 | http-api, i18n |
| ftp-server | FTP 文件服务 | http-api, i18n |
| frp-proxy | FRP 内网穿透代理 | http-api, i18n |
| polyglot-deploy | 多语言项目部署（Python/Node.js/Go） | http-api, i18n, pkg-manager |
## 示例
| 插件 | 说明 | 依赖 |
|------|------|------|
| example-with-deps | 依赖声明示例（仅 manifest，无 main.py） | 无 |