feat: 新增脚手架/开发模式/权限白名单/system-monitor插件

- nebula create mod/key/list-templates 模组脚手架 - nebula dev 开发模式热重载 - manifest permissions.imports 权限白名单机制 - system-monitor 系统监控仪表盘插件 - 默认端口统一为 10086 - 修复 _init_nbpf 误读 Ed25519 私钥为 RSA 的 bug - 更新 README.md 文档
2026-05-16 20:20:43 +08:00
parent bce27db4ac
commit 5fbc5cc335
14 changed files with 1225 additions and 312 deletions
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 <p align="center">
  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/NebulaShell-v2.0-6C47FF?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
-    <img alt="NebulaShell" src="https://img.shields.io/badge/NebulaShell-v2.0-6C47FF?style=for-the-badge&logo=python&logoColor=white&labelColor=f0f0ff">
+    <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>

@@ -9,7 +9,6 @@
  <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/Coverage-92%25-22C55E" alt="Coverage"></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>

@@ -24,16 +23,13 @@
 ## 目录

 - [项目定位](#项目定位)
- [架构总览](#架构总览)
- [核心能力](#核心能力)
 - [快速开始](#快速开始)
- [NBPF 包格式](#nbpf-包格式)
- [NIR 中间表示](#nir-中间表示)
 - [CLI 工具链](#cli-工具链)
 - [插件开发](#插件开发)
+- [权限白名单](#权限白名单manifestpermissionsimports)
+- [NBPF 包格式](#nbpf-包格式)
 - [内置插件](#内置插件)
 - [安全体系](#安全体系)
- [性能指标](#性能指标)
 - [贡献指南](#贡献指南)
 - [许可证](#许可证)

@@ -43,374 +39,357 @@

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

-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/philosophy.svg" alt="NebulaShell Philosophy" width="600">
-</p>
-
 ### 设计原则

 | 原则 | 说明 |
-|------|------|
-| **最小核心** | 核心仅 1100+ 行，职责单一，可独立审计 |
-| **插件即产品** | 所有业务功能以插件形式交付，核心不耦合任何业务 |
-| **安全默认** | 插件分发强制签名加密，运行时隔离，防篡改防逆向 |
-| **一次编译** | NIR 中间表示确保插件跨平台运行，无需为架构适配 |
-| **零信任分发** | 每个包经过三层签名验证 + 两层加密解密才可加载 |
-
---
-
-## 架构总览
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/architecture.svg" alt="NebulaShell Architecture" width="800">
-</p>
-
-### 分层架构
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/layers.svg" alt="NebulaShell Layers" width="800">
-</p>
-
-### 数据流
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/dataflow.svg" alt="NebulaShell Data Flow" width="800">
-</p>
-
---
-
-## 核心能力
-
-### 插件化架构
-
- **热插拔**：插件可在运行时动态加载/卸载，无需重启
- **依赖注入**：通过 `use()` 获取任意已加载插件实例
- **生命周期管理**：`init → start → stop` 三阶段标准化生命周期
- **优先级控制**：支持 `load_priority` 标记控制加载顺序
- **熔断降级**：插件异常自动隔离，不影响核心运行
-
-### NBPF 包格式
-
- **多重签名**：Ed25519（外层）→ RSA-4096-PSS（中层）→ HMAC-SHA256（内层）
- **多重加密**：AES-256-GCM 双层加密，密钥经 RSA-OAEP 封装
- **代码隐藏**：混淆导入路径、常量运行时计算、反调试检测、内存擦除、花指令混淆
- **防篡改**：任何字节级别的修改都会导致签名验证失败
-
-### NIR 中间表示
-
- **一次编译，到处运行**：基于 Python `compile()` + `marshal` 序列化
- **跨平台**：code object 是 Python 虚拟机原生格式，与 CPU 架构无关
- **目标版本**：Python 3.10+
- **代码保护**：编译产物不可读，增加逆向难度
-
-### CLI 工具链
-
- **`nebula nbpf`**：完整的包管理命令组
- **密钥生成**：一键生成 Ed25519 + RSA-4096 密钥对
- **打包/解包**：插件目录 ↔ .nbpf 文件双向转换
- **验证/签名**：独立验证工具 + 重新签名能力
+|:----|:-----|
+| 🧩 **一切皆插件** | 框架本身只提供加载和调度能力，所有功能都来自插件 |
+| 🔒 **安全默认** | 沙箱执行、签名验证、权限声明、完整性校验，层层防护 |
+| 📦 **一次编译到处运行** | NIR 中间表示使插件可在任何 Python 3.10+ 平台运行 |
+| 🎯 **最小权限** | 插件必须显式声明所需权限，未授权操作被拒绝 |
+| 🔧 **开发者体验** | 脚手架生成、热重载、详细日志，让开发尽可能愉快 |

 ---

 ## 快速开始

-```bash
-# 克隆仓库
-git clone https://github.com/Starlight-apk/NebulaShell.git
-cd NebulaShell
+### 一键启动（推荐）

+```bash
+# 非交互式启动（适合 Docker / CI / 后台服务）
+python headless.py
+
+# 自动信任所有 NBPF 插件
+python headless.py --trust-all
+
+# 仅检查运行环境
+python headless.py --dry-run
+```
+
+### 手动启动
+
+```bash
 # 安装依赖
 pip install -r requirements.txt

-# 启动 NebulaShell
-python main.py
+# 开发模式（热重载，推荐开发时使用）
+python main.py dev
+
+# 生产模式（交互式 REPL）
+python main.py serve
+
+# 生产模式（非交互，适合 Docker）
+python main.py serve --headless
 ```

-启动后访问 [http://localhost:8080](http://localhost:8080) 进入管理控制台。
-
-### 生成密钥并打包一个插件
+### 快速创建第一个模组

 ```bash
-# 1. 生成密钥对
-nebula nbpf keygen --output ./nbpf-keys
+# 一行命令创建模组脚手架
+python main.py create mod hello-world -a "我" -d "我的第一个模组"

-# 2. 打包插件为 .nbpf
-nebula nbpf pack ./store/NebulaShell/my-plugin -o my-plugin.nbpf \
-  --ed25519-key ./nbpf-keys/private/ed25519.pem \
-  --rsa-key ./nbpf-keys/private/rsa.pem
+# 编辑功能
+cd hello-world
+# vim main.py  # 实现你的功能

-# 3. 验证包完整性
-nebula nbpf verify my-plugin.nbpf
+# 生成签名密钥
+python main.py create key -o ./keys --name mykey

-# 4. 将密钥放入信任目录
-cp ./nbpf-keys/trusted/* ./data/nbpf-keys/trusted/
-cp ./nbpf-keys/rsa/* ./data/nbpf-keys/rsa/
+# 打包为 .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 "我"

-# 5. 重启 NebulaShell，插件自动加载
+# 启动开发模式测试
+python main.py dev
 ```

---
-
-## NBPF 包格式
-
-### 包结构
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/package-structure.svg" alt="NBPF Package Structure" width="500">
-</p>
-
-### 加密层级
-
-| 层级 | 算法 | 密钥来源 | 保护范围 |
-|------|------|----------|----------|
-| 外层加密 | AES-256-GCM | key1（RSA-OAEP 封装） | META-INF/ 和 NIR/ 目录 |
-| 中层加密 | AES-256-GCM | key2（RSA-OAEP 封装） | NIR 数据内容 |
-| 外层签名 | Ed25519 | 开发者私钥 | 加密层完整性 |
-| 中层签名 | RSA-4096-PSS | 作者私钥 | 模块内容完整性 |
-| 内层签名 | HMAC-SHA256 | 派生密钥（key1+key2） | 单个模块完整性 |
-
-### 安全流程
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/security-flow.svg" alt="NBPF Security Flow" width="700">
-</p>
-
---
-
-## NIR 中间表示
-
-NIR（Nebula Intermediate Representation）是 NebulaShell 的跨平台编译方案。
-
-### 技术原理
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/nir-flow.svg" alt="NIR Compilation Flow" width="600">
-</p>
-
-### 代码保护
-
-| 技术 | 说明 |
-|------|------|
-| 混淆导入路径 | 动态 `__import__()` + 字符串拼接，隐藏依赖关系 |
-| 常量运行时计算 | 关键字符串在运行时拼接，避免静态分析 |
-| 反调试检测 | `sys.gettrace()` 检测调试器附加 |
-| 内存擦除 | `bytearray` 覆盖清零，防止内存 dump |
-| 花指令混淆 | 向 `co_consts` 插入无害垃圾常量，干扰分析 |
+> 默认 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 nbpf keygen                      # 生成 Ed25519 + RSA-4096 密钥对
-nebula nbpf keygen --output ./keys      # 指定输出目录
+# 🚀 快速创建模组（脚手架）
+nebula create mod my-plugin -a "我" -d "插件描述"
+nebula create mod my-service --type service --with-keys

-# 打包
-nebula nbpf pack ./plugin-dir           # 打包为 .nbpf
-nebula nbpf pack ./plugin-dir -o out.nbpf --keys-dir ./keys
+# 🔑 生成签名密钥
+nebula create key -o ./keys --name mykey

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

-# 验证
-nebula nbpf verify package.nbpf         # 验证完整签名链
+# 🚀 启动服务
+nebula serve
+nebula serve --headless               # 非交互模式

-# 重新签名
-nebula nbpf sign package.nbpf           # 使用新密钥重新签名
-nebula nbpf sign package.nbpf --ed25519-key ./key.pem --rsa-key ./rsa.pem
+# 📦 打包插件
+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
 ```

 ---

 ## 插件开发

-### 最小插件
+### 模组结构（目录模式）

-```python
-from oss.plugin.types import Plugin
-
-class HelloPlugin(Plugin):
-    def init(self, deps=None):
-        self.name = "hello"
-
-    def start(self):
-        print(f"{self.name} started")
-
-    def stop(self):
-        print(f"{self.name} stopped")
-
-def New():
-    return HelloPlugin()
+```
+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
 {
-  "metadata": {
-    "name": "hello-plugin",
-    "version": "1.0.0",
-    "description": "示例插件",
-    "author": "developer"
+  "name": "@作者/模组名",
+  "version": "1.0.0",
+  "description": "描述",
+  "author": "作者",
+  "type": "example",
+  "main": "main.py",
+  "enabled": true,
+  "priority": 999,
+  "runtime": {
+    "language": "python",
+    "entry_point": "main.py",
+    "requirements": []
  },
-  "config": {
-    "enabled": true,
-    "args": {}
+  "permissions": {
+    "imports": []           ← 声明的系统模块导入权限
  },
-  "dependencies": [],
-  "permissions": ["storage:read"]
+  "services": {
+    "provides": [],
+    "consumes": []
+  },
+  "config": {}
 }
 ```

-### 使用其他插件
-
-```python
-from store.NebulaShell.plugin_bridge.main import use
-
-# 获取 HTTP API 插件实例
-http_api = use("http-api")
-
-# 注册路由
-http_api.add_route("/hello", lambda: {"message": "world"})
-```
-
-### 打包分发
+### 开发流程

 ```bash
-# 开发阶段：源码直接放入 store/ 目录
-# 分发阶段：打包为 .nbpf
-nebula nbpf pack ./store/NebulaShell/hello-plugin -o hello-plugin.nbpf \
-  --ed25519-key ./nbpf-keys/private/ed25519.pem \
-  --rsa-key ./nbpf-keys/private/rsa.pem
+# 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 内置 26+ 个插件，覆盖 Web 服务、系统管理、安全防护、协议适配等场景。
-
-### Web 与 API
+NebulaShell 内置了以下官方插件（位于 `store/NebulaShell/`）：

 | 插件 | 说明 |
-|------|------|
-| `http-api` | RESTful API 服务，支持路由注册、中间件 |
-| `ws-api` | WebSocket 实时通信服务 |
-| `webui` | 管理控制台 Web 界面 |
-| `dashboard` | 系统仪表盘，实时监控 |
-
-### 系统管理
-
-| 插件 | 说明 |
-|------|------|
-| `plugin-loader` | 插件加载核心，manifest 解析 |
-| `plugin-loader-pro` | 熔断、降级、容错机制 |
-| `pkg-manager` | 插件包管理器，在线安装/更新 |
-| `lifecycle` | 插件生命周期管理 |
-| `hot-reload` | 插件热重载，开发模式自动刷新 |
-| `dependency` | 依赖关系解析与冲突检测 |
-
-### 安全防护
-
-| 插件 | 说明 |
-|------|------|
-| `signature-verifier` | 运行时签名验证 |
-| `code-reviewer` | 插件代码安全审查 |
-| `firewall` | 网络防火墙规则引擎 |
-
-### 通信与协议
-
-| 插件 | 说明 |
-|------|------|
-| `plugin-bridge` | 插件间通信（事件总线 / RPC / use()） |
-| `http-tcp` | TCP 协议适配 |
+|:----|:------|
+| `plugin-bridge` | 事件总线 + 服务注册 + 跨插件 RPC |
+| `plugin-storage` | 插件持久化 KV 存储 |
+| `ws-api` | WebSocket 实时推送 |
+| `i18n` | 国际化多语言支持 |
 | `nodejs-adapter` | Node.js 运行时适配 |
-| `frp-proxy` | 内网穿透代理 |
-| `ftp-server` | 文件服务 |
+| `system-monitor` 🆕 | **系统监控仪表盘** — CPU/内存/磁盘/网络/进程TOP |
+| | 提供 HTML 仪表盘 + REST API，默认端口 **10087** |

-### 工具与增强
+### system-monitor API

-| 插件 | 说明 |
-|------|------|
-| `plugin-storage` | 插件持久化存储 |
-| `i18n` | 国际化支持 |
-| `auto-dependency` | 系统依赖自动安装 |
-| `performance-optimizer` | 性能优化引擎 |
-| `json-codec` | JSON 编解码 |
-| `log-terminal` | 日志查看与终端 |
-| `polyglot-deploy` | 多语言部署支持 |
+```
+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条）
+```

 ---

 ## 安全体系

-### 全链路安全
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/security-chain.svg" alt="Full Chain Security" width="800">
-</p>
-
-### 加密标准
-
-| 组件 | 标准 | 密钥长度 |
-|------|------|----------|
-| 对称加密 | AES-256-GCM | 256 位 |
-| 非对称加密 | RSA-OAEP | 4096 位 |
-| 外层签名 | Ed25519 | 256 位 |
-| 中层签名 | RSA-PSS | 4096 位 |
-| 内层签名 | HMAC-SHA256 | 256 位 |
-
-### 密钥管理
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Starlight-apk/NebulaShell/main/docs/key-structure.svg" alt="Key Management Structure" width="500">
-</p>
-
---
-
-## 性能指标
-
-| 指标 | 数值 |
-|------|------|
-| 核心代码行数 | ~1,100 行 |
-| 内置插件数量 | 26+ |
-| 测试覆盖率 | ~92% |
-| 语法检查通过率 | 100% |
-| Python 版本要求 | 3.10+ |
-| 依赖库数量 | 精简（核心仅依赖 cryptography） |
+| 层级 | 措施 | 说明 |
+|:----|:-----|:------|
+| 🛡 **分发安全** | 三层签名（Ed25519 + RSA-4096 + HMAC） | 防止包被篡改或伪造 |
+| 🔐 **传输安全** | AES-256-GCM 双层加密 | 插件代码在传输和存储中均加密 |
+| 🏖 **执行沙箱** | NIR 安全沙箱 | 限制危险模块和内置函数 |
+| 📋 **权限控制** | manifest 权限白名单 | 插件必须声明所需模块导入权限 |
+| 🔍 **完整性检查** | SHA-256 文件 hash 监控 | 运行时定期校验插件文件完整性 |
+| 🧠 **内存防护** | MemoryGuard 冻结核心属性 | 防止插件修改框架内部状态 |
+| 📝 **行为审计** | AuditLogger | 记录所有插件操作行为 |
+| 👀 **防篡改监控** | TamperMonitor 后台线程 | 自动检测篡改并停止被篡改插件 |
+| 🔄 **降级恢复** | FallbackManager 自动重试 | 插件崩溃时自动重启（最多3次） |

 ---

 ## 贡献指南

-### 开发流程
+### 开发环境

 ```bash
-# 1. Fork 仓库
-# 2. 创建特性分支
-git checkout -b feat/my-feature
+# 克隆仓库
+git clone https://git.starlight-apk.cn/starlight-apk/NebulaShell.git
+cd NebulaShell

-# 3. 安装开发依赖
+# 安装依赖
 pip install -r requirements.txt

-# 4. 确保语法检查通过
-find . -name "*.py" -not -path "./venv/*" -not -path "./.git/*" | \
-  xargs -I{} python3 -m py_compile {}
+# 启动开发模式
+python main.py dev

-# 5. 运行测试
+# 运行测试
 python -m pytest tests/
-
-# 6. 提交 PR
 ```

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

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

 ---