NebulaShell/README.md

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/NebulaShell-v1.2.0-6C47FF?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
    <img alt="NebulaShell" src="https://img.shields.io/badge/NebulaShell-v1.2.0-6C47FF?style=for-the-badge&logo=python&logoColor=white&labelColor=f0f0ff">
  </picture>
</p>

<p align="center">
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-6C47FF" alt="License"></a>
  <a href=""><img src="https://img.shields.io/badge/Build-Passing-22C55E" alt="Build"></a>
  <a href=""><img src="https://img.shields.io/badge/Security-AES--256--GCM%20%7C%20Ed25519%20%7C%20RSA--4096-EF4444" alt="Security"></a>
</p>

<p align="center">
  <b>插件化运行时框架</b> · 多重签名加密分发 · NIR 一次编译到处运行 · 企业级安全体系
</p>

<br>

---

## 目录

- [项目定位](#项目定位)
- [快速开始](#快速开始)
- [CLI 工具链](#cli-工具链)
- [插件开发](#插件开发)
- [权限白名单](#权限白名单manifestpermissionsimports)
- [NBPF 包格式](#nbpf-包格式)
- [内置插件](#内置插件)
- [安全体系](#安全体系)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

---

## 项目定位

NebulaShell 是一个**以安全为基石、以插件为灵魂**的运行时框架。核心只做两件事：**加载插件**与**调度插件**，其余一切功能均由插件生态提供。

### 设计原则

| 原则 | 说明 |
|:----|:-----|
| 🧩 **一切皆插件** | 框架本身只提供加载和调度能力，所有功能都来自插件 |
| 🔒 **安全默认** | 沙箱执行、签名验证、权限声明、完整性校验，层层防护 |
| 📦 **一次编译到处运行** | NIR 中间表示使插件可在任何 Python 3.10+ 平台运行 |
| 🎯 **最小权限** | 插件必须显式声明所需权限，未授权操作被拒绝 |
| 🔧 **开发者体验** | 脚手架生成、热重载、详细日志，让开发尽可能愉快 |

---

## 快速开始

### 一键启动（推荐）

```bash
# 非交互式启动（适合 Docker / CI / 后台服务）
python headless.py

# 自动信任所有 NBPF 插件
python headless.py --trust-all

# 仅检查运行环境
python headless.py --dry-run
```

### 手动启动

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

# 开发模式（热重载，推荐开发时使用）
python main.py dev

# 生产模式（交互式 REPL）
python main.py serve

# 生产模式（非交互，适合 Docker）
python main.py serve --headless
```

### 快速创建第一个模组

```bash
# 一行命令创建模组脚手架
python main.py create mod hello-world -a "我" -d "我的第一个模组"

# 编辑功能
cd hello-world
# vim main.py  # 实现你的功能

# 生成签名密钥
python main.py create key -o ./keys --name mykey

# 打包为 .nbpf
python main.py nbpf pack ./hello-world -o mods/hello-world.nbpf \
  --ed25519-key ./keys/mykey_ed25519.pem \
  --rsa-key ./keys/mykey_rsa.pem \
  --rsa-pub ./keys/mykey_rsa.pub.pem \
  --signer "我"

# 启动开发模式测试
python main.py dev
```

> 默认 HTTP 服务端口：**10086**（可在 `data/config.json` 或环境变量 `HTTP_API_PORT` 中修改）

---

## CLI 工具链

| 命令 | 说明 |
|:----|:------|
| `serve` | 启动 NebulaShell 服务端 |
| `serve --headless` | 🆕 非交互模式（不启动 REPL，适合 Docker/后台） |
| `dev` | 🆕 **开发模式** — 监听文件变化 + 自动热重载 |
| `version` | 显示版本信息 |
| `info` | 显示系统信息 |
| `create mod` | 🆕 **模组脚手架** — 交互式生成插件骨架 |
| `create key` | 🆕 快速生成 Ed25519 + RSA 签名密钥对 |
| `create list-templates` | 🆕 查看可用模板 |
| `nbpf pack` | 打包插件目录为 .nbpf 文件 |
| `nbpf unpack` | 解包 .nbpf 文件到目录 |
| `nbpf verify` | 验证 .nbpf 签名 |
| `nbpf sign` | 为 .nbpf 重新签名 |
| `nbpf keygen` | 生成 Ed25519 + RSA-4096 密钥对 |

### 典型用法

```bash
# 🚀 快速创建模组（脚手架）
nebula create mod my-plugin -a "我" -d "插件描述"
nebula create mod my-service --type service --with-keys

# 🔑 生成签名密钥
nebula create key -o ./keys --name mykey

# 💻 开发模式（热重载）
nebula dev                            # 监听当前目录
nebula dev ./my-plugin --port 10086   # 监听指定目录
nebula dev --skip-sign                # 跳过签名验证（调试用）

# 🚀 启动服务
nebula serve
nebula serve --headless               # 非交互模式

# 📦 打包插件
nebula nbpf pack ./my-plugin -o my-plugin.nbpf \
  --ed25519-key ./keys/ed25519.pem \
  --rsa-key ./keys/rsa.pem \
  --rsa-pub ./keys/rsa.pub.pem \
  --signer "作者名"

# ℹ️ 系统信息
nebula info
```

---

## 插件开发

### 模组结构（目录模式）

```
my-plugin/
├── manifest.json        ← 【必填】模组身份证
├── main.py              ← 【必填】模组代码（类 + New() 工厂函数）
└── README.md            ← 【推荐】说明文档
```

### main.py 规范

插件支持两种写法，**推荐使用类 + New() 工厂函数**以兼容目录和 nbpf 两种加载方式：

```python
class MyPlugin:
    name = "my-plugin"
    version = "1.0.0"
    description = "描述"

    def init(self, deps=None):  # 初始化，可获取依赖
        pass
    def start(self):            # 启动
        pass
    def stop(self):             # 停止，释放资源
        pass
    def reload(self, config):   # 热重载（可选）
        pass
    def health(self) -> dict:   # 健康检查（可选）
        return {"status": "ok"}

def New():
    """目录插件工厂函数（必需）"""
    return MyPlugin()
```

### manifest.json

```json
{
  "name": "@作者/模组名",
  "version": "1.0.0",
  "description": "描述",
  "author": "作者",
  "type": "example",
  "main": "main.py",
  "enabled": true,
  "priority": 999,
  "runtime": {
    "language": "python",
    "entry_point": "main.py",
    "requirements": []
  },
  "permissions": {
    "imports": []           ← 声明的系统模块导入权限
  },
  "services": {
    "provides": [],
    "consumes": []
  },
  "config": {}
}
```

### 开发流程

```bash
# 1. 使用脚手架创建模组（推荐）
nebula create mod my-plugin -a "我" -d "描述"

# 2. 编辑 main.py 实现功能
cd my-plugin
# vim main.py ...

# 3. 开发模式：边改边测，自动热重载
nebula dev ./my-plugin

# 4. 满意后生成签名密钥
nebula create key -o ./keys --name mykey

# 5. 打包为 .nbpf 发布
nebula nbpf pack ./my-plugin -o mods/my-plugin.nbpf \\
  --ed25519-key ./keys/mykey_ed25519.pem \\
  --rsa-key ./keys/mykey_rsa.pem \\
  --rsa-pub ./keys/mykey_rsa.pub.pem \\
  --signer "我"
```

---

## 权限白名单（manifest.permissions.imports）

NBPF 安全沙箱默认禁止导入 `os`、`threading`、`socket` 等系统模块。
如果插件确实需要，**必须在 manifest.json 的 `permissions.imports` 中显式声明**。

```json
{
  "permissions": {
    "imports": ["os", "threading", "json", "http"]
  }
}
```

| 声明方式 | 效果 |
|:---------|:-----|
| 不声明 `permissions` | 仅限纯 Python 计算，不可导入任何系统模块 |
| `"imports": ["os", "json"]` | 只允许导入 `os` 和 `json` |
| 使用未声明的模块 | **编译时报错**，拒绝打包 |
| 运行时突破白名单 | **安全沙箱拦截**，抛出 `ImportError` |

> **安全原则**：最小权限。只声明你真正需要的模块，不要图省事全写上。

---

## NBPF 包格式

`.nbpf` 是 NebulaShell 的插件分发格式，本质上是一个多层加密签名的 ZIP 包。

### 包结构

```
my-plugin.nbpf
├── META-INF/
│   ├── SIGNATURE          ← 外层 Ed25519 签名
│   ├── SIGNER.PEM         ← 签名者 Ed25519 公钥
│   ├── ENCRYPTION         ← 外层加密信息（RSA 加密 AES 密钥）
│   ├── INNER_SIGNATURE    ← 中层 RSA-4096 签名
│   ├── INNER_ENCRYPTION   ← 中层加密信息
│   ├── MODULE_SIGS        ← 内层 HMAC 模块签名
│   └── PLUGIN.MF          ← 插件清单
├── NIR/                   ← 编译后的 NIR 中间表示
│   └── main               ← 主模块序列化 code object
└── RES/                   ← 资源文件（README、图片等）
```

### 安全层级

```
外层: Ed25519 签名 → 验证包完整性 & 作者身份
  ↓
中层: RSA-4096 签名 → 验证 NIR 数据完整性
  ↓
内层: HMAC 签名 → 验证每个模块未被篡改
  ↓
执行: 安全沙箱 + 权限白名单 → 限制运行时能力
```

---

## 内置插件

NebulaShell 内置了以下官方插件（位于 `store/NebulaShell/`）：

| 插件 | 说明 |
|:----|:------|
| `plugin-bridge` | 事件总线 + 服务注册 + 跨插件 RPC |
| `plugin-storage` | 插件持久化 KV 存储 |
| `ws-api` | WebSocket 实时推送 |
| `i18n` | 国际化多语言支持 |
| `nodejs-adapter` | Node.js 运行时适配 |
| `system-monitor` 🆕 | **系统监控仪表盘** — CPU/内存/磁盘/网络/进程TOP |
| | 提供 HTML 仪表盘 + REST API，默认端口 **10087** |

### system-monitor API

```
http://localhost:10087/                → 📊 仪表盘 HTML
http://localhost:10087/health          → 💚 {"status": "ok"}
http://localhost:10087/stats           → 📄 系统状态 JSON
http://localhost:10087/stats/cpu       → 🧠 CPU 详情
http://localhost:10087/stats/memory    → 💾 内存详情
http://localhost:10087/stats/disk      → 💿 磁盘详情
http://localhost:10087/stats/network   → 🌐 网络详情
http://localhost:10087/stats/processes → ⚡ TOP 进程
http://localhost:10087/stats/history   → 📈 历史数据（最近60条）
```

---

## 安全体系

| 层级 | 措施 | 说明 |
|:----|:-----|:------|
| 🛡 **分发安全** | 三层签名（Ed25519 + RSA-4096 + HMAC） | 防止包被篡改或伪造 |
| 🔐 **传输安全** | AES-256-GCM 双层加密 | 插件代码在传输和存储中均加密 |
| 🏖 **执行沙箱** | NIR 安全沙箱 | 限制危险模块和内置函数 |
| 📋 **权限控制** | manifest 权限白名单 | 插件必须声明所需模块导入权限 |
| 🔍 **完整性检查** | SHA-256 文件 hash 监控 | 运行时定期校验插件文件完整性 |
| 🧠 **内存防护** | MemoryGuard 冻结核心属性 | 防止插件修改框架内部状态 |
| 📝 **行为审计** | AuditLogger | 记录所有插件操作行为 |
| 👀 **防篡改监控** | TamperMonitor 后台线程 | 自动检测篡改并停止被篡改插件 |
| 🔄 **降级恢复** | FallbackManager 自动重试 | 插件崩溃时自动重启（最多3次） |

---

## 贡献指南

### 开发环境

```bash
# 克隆仓库
git clone https://git.starlight-apk.cn/starlight-apk/NebulaShell.git
cd NebulaShell

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

# 启动开发模式
python main.py dev

# 运行测试
python -m pytest tests/
```

### 贡献流程

1. Fork 项目并创建特性分支
2. 编写代码，确保语法检查零错误
3. 添加或更新测试
4. 更新文档（README、注释等）
5. 提交 Pull Request

### 代码规范

- 遵循 PEP 8 编码规范
- 插件必须实现 `init()`、`start()`、`stop()` 方法
- 插件必须包含 `New()` 工厂函数（兼容目录 + nbpf 两种加载方式）
- 插件必须声明完整的 `permissions.imports` 权限白名单
- 提交前确保所有测试通过

---

## 许可证

Copyright 2026 Falck, yongwanxing, NebulaShell Contributors

Licensed under the [Apache License, Version 2.0](LICENSE).