-
+### 核心组件
+
+| 组件 | 职责 | 技术选型 |
+|------|------|----------|
+| **Plugin Loader** | 插件发现、加载、依赖注入 | Python `importlib` + 进程隔离 |
+| **Plugin Bridge** | 插件间通信（事件总线/RPC） | 自定义事件驱动架构 |
+| **HTTP API** | RESTful API 网关 | Python `http.server` |
+| **WebSocket API** | 实时双向通信 | 自定义 WebSocket 实现 |
+| **WebUI** | 管理控制台 | 纯静态 HTML/CSS/JS |
+
+---
+
+## 插件生态
+
+当前共有 **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` 声明其依赖关系，系统自动处理：
+
+```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",
+ "version": "1.0.0",
+ "author": "Your Name",
+ "description": "你的插件描述",
+ "type": "plugin"
+ },
+ "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):
+ pass
+
+ def start(self):
+ pass
+
+ def stop(self):
+ pass
+
+def New():
+ return YourPlugin()
+```
+
+### 使用其他插件
+
+```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)
+```
+
+---
+
+## 贡献指南
+
+我们欢迎所有形式的贡献，包括但不限于：新功能、Bug 修复、文档改进、测试覆盖。
+
+### 开发流程
+
+1. Fork 仓库并创建特性分支
+2. 编写代码并添加测试
+3. 确保通过代码风格检查
+4. 提交 Pull Request
+
+### 提交规范
+
+采用 Conventional Commits 规范：
+
+```
+feat: 新功能
+fix: 修复 Bug
+refactor: 代码重构
+docs: 文档变更
+test: 测试相关
+chore: 构建/工具/依赖
+```
+
+---
+
+## 许可证
+
+本项目基于 [Apache License 2.0](LICENSE) 开源。
---
📜 查看完整许可证文本 (点击展开)
+## 架构设计 ``` - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to the Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - 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 - 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 - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - Copyright 2026 Falck - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +用户/客户端 + │ + ▼ +┌─────────────────────────────┐ +│ HTTP API / WebSocket │ +│ (统一安全网关) │ +└─────────────────────────────┘ + │ + ▼ +┌─────────────────────────────┐ +│ NebulaShell 微内核 │ +│ ┌───────────────────────┐ │ +│ │ Plugin Loader │ │ +│ │ • 插件发现与加载 │ │ +│ │ • 依赖解析与注入 │ │ +│ │ • 生命周期管理 │ │ +│ └───────────────────────┘ │ +└─────────────────────────────┘ + │ + ├── 核心插件层 (可信域) + │ ├── HTTP API 服务 + │ ├── WebSocket 服务 + │ ├── 数据持久化 + │ ├── 审计中心 + │ └── 监控探针 + │ + └── 隔离插件层 (不可信域) + ├── 动态防火墙 + ├── 内网穿透 + ├── FTP 文件服务 + ├── 多语言运行时 + ├── 运维工具箱 + └── 安全网关 ``` -
-## 🌟 星光闪耀时刻
+**Built with ❤️ by NebulaShell Team**
-### 如果这个项目帮助到了你，请给我们一个 ⭐ Star！
-
-[](https://github.com/Starlight-apk/NebulaShell)
-[](https://github.com/Starlight-apk/NebulaShell/fork)
-[](https://github.com/Starlight-apk/NebulaShell/watchers)
-
----
-
-### 👥 致谢所有贡献者
-
-
- 
-
-
----
-
-*🚀 **Built with ❤️ by [NebulaShell Team](https://github.com/Starlight-apk)** *
-*✨ **面向未来，安全随行 - 让插件开发从未如此简单** *
-*🌍 **Made possible by our amazing community** *
-
----
-
-
diff --git a/ai.md b/ai.md
index d2bb112..166908a 100644
--- a/ai.md
+++ b/ai.md
@@ -1,7 +1,7 @@
# NebulaShell 生产级就绪分析报告
> 生成时间: 2026-05-02
-> 最后更新: 2026-05-02 (完整兼容/安全/性能审计)
+> 最后更新: 2026-05-03 (P0修复 + 废弃代码清理 + README重写)
> 代码行数: ~8,500+，100+ 文件
> Python 版本: 3.10+
@@ -37,7 +37,8 @@
### ✅ 已有优点
- 清晰的顶层分离：`oss/`（核心框架）、`store/`（插件）、`data/`（运行时数据）
-- 良好的插件架构：两个命名空间 `@{NebulaShell}`（26 插件）、`@{Falck}`（2 插件）
+- 良好的插件架构：命名空间 `NebulaShell`（26 插件）
+- 遵循"最小核心"哲学：核心只加载 `plugin-loader`，由它管理所有其他插件
- 遵循"最小核心"哲学：核心只加载 `plugin-loader`，由它管理所有其他插件
- 插件 `New()` 工厂函数约定一致
@@ -761,14 +762,18 @@ Phase 4 (长期) — K8s部署、ADR、类型检查、pre-commit、异步I/O
## 20. 待修复计划
-### Phase A：清理
-- [ ] 删除 `store/@{Falck}/` 整个目录（废弃的旧代码）
-- [ ] 删除 `oss/store/@{NebulaShell}/nodejs-adapter/`（`store/NebulaShell/nodejs-adapter/` 的重复副本）
-- [ ] 删除根目录冗余文件：`test_fixes.py`、`FATAL_FIXES_REPORT.md`
-- [ ] 清理 `oss/tests/` 下无效的测试文件
+### Phase A：清理 ✅
+- [x] 删除 `store/@{Falck}/` 整个目录（废弃的旧代码）
+- [x] 删除 `oss/store/@{NebulaShell}/nodejs-adapter/`（`store/NebulaShell/nodejs-adapter/` 的重复副本）
+- [x] 删除根目录冗余文件：`test_fixes.py`、`FATAL_FIXES_REPORT.md`
+- [x] 删除废弃的 `oss/tui/` 目录
+- [x] 清理 `oss/tests/` 下无效的测试文件
+- [x] 清理所有 `__pycache__` 和 `.pyc` 缓存文件
-### Phase B：修复高危兼容性问题
-- [ ] 修复 ~30 个损坏 Python 文件的类定义头（缺少 `class XxxPlugin:` 等）
+### Phase B：修复高危兼容性问题 ✅
+- [x] 修复 40+ 个损坏 Python 文件的类定义头（缺少 `class XxxPlugin:` 等）
+- [x] 创建符号链接 `plugin_bridge -> plugin-bridge` 解决连字符路径问题
+- [x] 全量语法检查通过，零错误
- [ ] 补全插件缺少的 `set_i18n()` 方法（14 个插件声明了 i18n 依赖）
### Phase C：修复高危安全问题
@@ -786,3 +791,17 @@ Phase 4 (长期) — K8s部署、ADR、类型检查、pre-commit、异步I/O
### Phase E：低优先级
- [ ] 配置默认 API_KEY（当前为 "" 时绕过认证）
- [ ] pkg-manager 连接池 + 并行下载
+
+---
+
+## 21. 变更记录
+
+### 2026-05-03
+- **P0 修复完成**：修复 40+ 损坏 Python 文件的 class 定义头和语法错误
+- **符号链接**：创建 `plugin_bridge -> plugin-bridge` 解决连字符路径问题
+- **废弃清理**：删除 `store/@{Falck}/`、`oss/tui/`、`oss/store/@{NebulaShell}/`、冗余测试文件、所有 `__pycache__`
+- **`use()` 机制**：所有官方插件改为通过 `use()` 获取依赖，保留 `set_xxx()` 向后兼容
+- **优先加载机制**：`plugin-bridge` 通过 `load_priority: "first"` 标记率先加载
+- **README 重写**：805 行 → 283 行，企业级开源项目风格
+- **分支清理**：删除 Gitee/Github 上除 main 外的所有远程分支
+- **全量语法检查**：零错误通过
-
-[🏠 官网首页](https://nebulashell.date)
-
-
+[GitHub](https://github.com/Starlight-apk/NebulaShell) · [Gitee](https://gitee.com/NebulaBase/NebulaShell)