docs: 更新项目文档至2026-05-17现状

- 问题报告.md: 重新审查代码，更新路径和问题列表
- RELEASE_v1.2.1.md: 改为路线图，标注实际完成状态
- CODE_VERIFICATION_REPORT.md: 重新验证核心功能
- FATAL_FIXES_REPORT.md: 按当前代码重写
- ai.md: 清理无关内容，更新统计和路线图
- 项目的后续计划.md: 补充详细开发计划
- README.md: 添加功能说明提示
- RELEASE_v1.1.0.md: 添加历史存档标记

FATAL_FIXES_REPORT.md

@@ -1,154 +1,128 @@
 # NebulaShell 致命错误修复报告
 
 ## 修复日期
-2026-05-02
+2026-05-17
 
-## 修复的致命问题
+## 背景说明
+本报告记录 NebulaShell 从 v1.1.0 到 v1.2.0 过程中已修复的致命问题。
+当前仓库代码（`5fbc5cc`）已全部清理。
 
-### 1. CORS 允许所有来源（`Access-Control-Allow-Origin: *`）✅ 已修复
+---
 
-#### 问题
-- HTTP API 和中间件都使用了 `Access-Control-Allow-Origin: *`
-- 这允许任何来源的跨域请求，存在安全风险
+## ✅ 已修复的致命问题
 
-#### 修复方案
-1. **修改中间件** (`store/NebulaShell/http-api/middleware.py`)：
-   - 将 `CorsMiddleware.process()` 方法改为从配置读取允许的来源列表
-   - 只在请求来源在允许列表中时设置 CORS 头
-   - 支持 `*` 通配符和具体域名
+### 1. engine.py 超 1730 行（P0）✅ 已修复
 
-2. **修改服务器** (`store/NebulaShell/http-api/server.py`)：
-   - 在 `do_OPTIONS()` 方法中添加来源检查
-   - 只为允许的来源设置 CORS 头
+**问题**：`oss/core/engine.py` 单文件 1730 行，违反 400 行上限。
 
-3. **添加配置项**：
-   - 在 `oss/config/config.py` 中添加 `CORS_ALLOWED_ORIGINS` 默认配置
-   - 在 `oss.config.json` 中添加对应的配置项
-   - 支持环境变量覆盖
+**修复**：拆分为子模块：
+- `oss/core/engine.py` — 仅 27 行，作为 re-export 层
+- `oss/core/lifecycle.py` — Lifecycle / LifecycleManager
+- `oss/core/manager.py` — PluginManager（757 行）
+- `oss/core/datastore.py` — DataStore
+- `oss/core/security.py` — 安全模块（PluginProxy 等）
+- `oss/core/watcher.py` — FileWatcher
+- `oss/core/signature.py` — SignatureVerifier / PluginSigner
+- `oss/core/pl_injector.py` — PLInjector
 
-#### 修复后的行为
-- 默认允许：`["http://localhost:3000", "http://127.0.0.1:3000"]`
-- 可以通过环境变量或配置文件自定义
-- 只允许配置的来源访问 API
-- 不再允许所有来源的请求
+### 2. config.py 语法错误（P0）✅ 已修复
 
-### 2. 只有1个测试文件，核心功能零覆盖 ✅ 已修复
+**问题**：`oss/config/config.py:33` 缺失逗号导致 SyntaxError。
 
-#### 问题
-- 项目只有1个测试文件 `test_nodejs_adapter.py`
-- 核心功能如 plugin-loader、HTTP API、config、WebSocket、router 均无测试
-- 测试覆盖率极低
+**修复**：配置文件已修正，语法检查通过。
 
-#### 修复方案
-1. **创建 pytest 配置** (`pytest.ini`)：
-   - 配置测试路径和选项
-   - 添加自定义标记
+### 3. 废弃代码清理 ✅ 已修复
 
-2. **创建共享测试工具** (`oss/tests/conftest.py`)：
-   - 添加临时目录 fixture
-   - 添加模拟配置 fixture
-   - 添加插件目录 fixture
-   - 添加自动测试环境设置
+| 清理项 | 说明 |
+|--------|------|
+| `store/@{Falck}/` | 废弃旧代码，全部删除 |
+| `oss/store/@{NebulaShell}/` | 重复副本，已清理 |
+| `oss/tui/` | 废弃的 TUI 目录，已删除 |
+| `oss/store/NebulaShell/nodejs-adapter/` 重复 | 已清理 |
+| 所有 `__pycache__` | 缓存文件已清除 |
+| 冗余测试文件 | 已清理 |
 
-3. **创建核心功能测试**：
-   - `test_plugin_manager.py` - 插件管理器测试
-   - `test_http_api.py` - HTTP API 测试
-   - `test_config.py` - 配置系统测试
-   - `test_logger.py` - 日志系统测试
-   - `test_fixes.py` - 修复验证测试
+### 4. 全量语法检查 ✅ 已修复
 
-#### 修复后的测试覆盖
-- 插件加载和管理功能
-- HTTP API 和中间件功能
-- 配置管理系统
-- 日志系统功能
-- CORS 安全修复验证
+所有 `.py` 文件通过 `py_compile` 零错误。
 
-### 3. 无日志轮转，所有日志输出到 stdout ✅ 已修复
+### 5. CORS 配置增强 ✅ 已修复
 
-#### 问题
-- 所有日志都输出到 stdout
-- 没有文件日志
-- 没有日志轮转机制
-- 日志文件会无限增长
+- 中间件从配置读取允许的来源列表
+- 不再硬编码 `Access-Control-Allow-Origin: *`
 
-#### 修复方案
-1. **修改日志系统** (`oss/logger/logger.py`)：
-   - 添加文件日志支持
-   - 添加日志轮转功能
-   - 支持配置文件路径、最大大小、备份数量
-   - 文件日志使用 JSON 格式，控制台日志使用彩色格式
+### 6. 测试覆盖率提升 ✅ 已修复
 
-2. **添加配置项**：
-   - 在 `oss/config/config.py` 中添加日志相关配置
-   - 在 `oss.config.json` 中添加对应的配置项
-   - 支持环境变量覆盖
+- 从 1 个测试文件扩展到 16 个
+- 覆盖：配置、日志、HTTP API、插件管理、NBPF、集成测试
 
-3. **实现日志轮转**：
-   - 使用 `RotatingFileHandler` 实现文件轮转
-   - 支持按大小轮转（默认10MB）
-   - 支持保留备份文件数量（默认5个）
-   - 自动创建日志目录
+### 7. 日志系统增强 ✅ 已修复
 
-#### 修复后的日志功能
-- 支持同时输出到控制台和文件
-- 文件日志自动轮转
-- 可配置日志格式（JSON/文本）
-- 可配置日志级别和文件路径
-- 支持运行时切换日志格式
+- 改用 Python `logging` 模块
+- 支持 JSON/text 运行时切换
+- 文件日志和轮转支持
 
-## 测试验证
+### 8. CLI 工具链完善 ✅ 已修复
 
-### 运行测试
-```bash
-# 运行所有测试
-python -m pytest oss/tests/ -v
+- `cli.py` 689 行，11+ 个命令
+- 覆盖：serve/dev/create/nbpf/tools/info/version
 
-# 运行特定测试
-python -m pytest oss/tests/test_fixes.py -v
-python -m pytest oss/tests/test_config.py -v
-python -m pytest oss/tests/test_logger.py -v
+---
+
+## 🔴 当前仍存在的严重问题
+
+| # | 问题 | 等级 | 说明 |
+|---|------|------|------|
+| 1 | **无安全中间件** | 🔴 致命 | JWT/CSRF/输入验证/HTTPS 均未实现 |
+| 2 | **无防火墙引擎** | 🔴 致命 | IP 黑白名单未实现 |
+| 3 | **无运维工具箱** | 🔴 致命 | 备份/健康检查/资源配额未实现 |
+| 4 | **WebUI 为静态占位** | 🔴 致命 | 硬编码数据，未对接 API |
+| 5 | **无 Prometheus 端点** | 🔴 致命 | 无可观测性数据 |
+| 6 | **多处 `except: pass`** | 🟠 高危 | 异常被静默吞掉 |
+| 7 | **无配置 Schema 验证** | 🟠 高危 | 配置错误静默降级 |
+| 8 | **Dashboard 无鉴权** | 🟠 高危 | WebUI 公开访问 |
+
+---
+
+## 📋 修复优先级建议
+
+```
+Phase 1 (v1.2.0 — 已完成) ✅
+├── engine.py 模块拆分         ✅
+├── 废弃代码清理               ✅
+├── 语法检查                   ✅
+├── NBPF 包格式                ✅
+├── CLI 工具链                 ✅
+├── 基础测试框架               ✅
+
+Phase 2 (v1.2.1 — 开发中)
+├── oss/core/security/         ⏳ JWT/CSRF/输入验证/HTTPS
+├── oss/core/firewall/         ⏳ IP 黑白名单
+├── oss/core/ops/              ⏳ 备份/健康检查/配额
+├── WebUI 重写                 ⏳ 管理面板
+├── /metrics 端点              ⏳ Prometheus 兼容
+└── 测试覆盖完善               ⏳ 核心链路端到端测试
+
+Phase 3 (v1.3.0 — 规划中)
+├── Docker 部署优化
+├── K8s manifests
+├── 异步 I/O 支持
+├── 性能优化器集成
+├── pre-commit / CI 完善
+└── 文档国际化
 ```
 
-### 验证修复
-```bash
-# 运行修复验证脚本
-python test_fixes.py
-```
+---
 
-## 配置示例
+## 结论
 
-### CORS 配置
-```json
-{
-  "CORS_ALLOWED_ORIGINS": ["http://localhost:3000", "https://example.com"]
-}
-```
+NebulaShell v1.2.0 的核心问题已全部修复：
+- ✅ 代码可正常启动
+- ✅ 语法检查零错误
+- ✅ 废弃代码已清理
+- ✅ NBPF 包格式完整实现
+- ✅ CLI 工具链可用
+- ✅ 基础测试覆盖完成
+- ✅ 日志系统可用
 
-### 日志配置
-```json
-{
-  "LOG_FORMAT": "json",
-  "LOG_FILE": "./data/logs/nebula.log",
-  "LOG_MAX_SIZE": 20971520,
-  "LOG_BACKUP_COUNT": 10
-}
-```
-
-### 环境变量配置
-```bash
-export CORS_ALLOWED_ORIGINS='["http://localhost:3000", "https://example.com"]'
-export LOG_FILE="./data/logs/nebula.log"
-export LOG_MAX_SIZE="20971520"
-export LOG_BACKUP_COUNT="10"
-```
-
-## 总结
-
-通过这次修复，我们解决了所有3个致命问题：
-
-1. **CORS 安全问题** - 现在只允许配置的来源访问API
-2. **测试覆盖率问题** - 添加了全面的测试套件
-3. **日志管理问题** - 实现了文件日志和轮转功能
-
-这些修复大大提升了 NebulaShell 的安全性和可维护性，使其更适合生产环境使用。
+v1.2.1 规划的安全增强、防火墙、运维工具箱和 WebUI 重写尚未开始，需要在下一阶段实现。