NebulaShell/README.md

插件化运行时框架 · 多重签名加密分发 · NIR 一次编译到处运行 · 企业级安全体系

---

目录

• 项目定位
• 快速开始
• CLI 工具链
• 插件开发
• 权限白名单
• NBPF 包格式
• 内置插件
• 安全体系
• 贡献指南
• 许可证

---

项目定位

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

设计原则

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

---

快速开始

一键启动（推荐）

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

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

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

手动启动

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

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

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

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

快速创建第一个模组

# 一行命令创建模组脚手架
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 密钥对

典型用法

# 🚀 快速创建模组（脚手架）
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 两种加载方式：

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

{
  "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": {}
}

开发流程

# 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 中显式声明。

{
  "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次）

---

贡献指南

开发环境

# 克隆仓库
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.