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: 添加历史存档标记
2026-05-17 15:17:50 +08:00
parent 5fbc5cc335
commit 1736bb5801
8 changed files with 644 additions and 1293 deletions
--- a/问题报告.md
+++ b/问题报告.md
@@ -1,214 +1,105 @@
 # NebulaShell 代码审查报告

-> 审查日期：2026-05-04
+> 审查日期：2026-05-17
+> 基于仓库最新代码（commit: 5fbc5cc）

 ---

-## 一、严重问题
+## 一、当前代码状态概览

-### 1. `plugin-storage` 路径穿越漏洞（CRITICAL）
-
-**文件**: `store/NebulaShell/plugin-storage/main.py:131-132`
-
-```python
-def _resolve_path(self, path: str) -> Path:
-    return self.data_dir.resolve()  # 完全忽略了 path 参数！
-```
-
-`_resolve_path` 方法**完全忽略传入的 `path` 参数**，始终返回 `data_dir` 本身。这意味着 `read_file("../../../etc/passwd")` 和 `read_file("safe.txt")` 都返回同一个路径。虽然这避免了路径穿越，但**文件读写功能实际上被破坏了**——所有文件操作都指向同一个目录。`serve_file` 方法（第 96-129 行）有正确的路径穿越检查，但 `_resolve_path` 没有使用它。
+| 指标 | 数值 |
+|------|------|
+| Python 文件 | 61 |
+| Python 代码行数 | ~9,481 |
+| 总文件数 | 117 |
+| 核心模块 | `oss/core/`（含 http_api、nbpf、repl 子模块） |
+| 官方插件 | 5（i18n, nodejs-adapter, plugin-bridge, plugin-storage, ws-api）|
+| 独立插件 | 1（system-monitor，位于根目录）|
+| 测试文件 | 16（tests/ 下 3 个 + oss/tests/ 下 13 个）|

 ---

-### 2. `plugin-storage` 方法实现完全错误（CRITICAL）
+## 二、已知问题（按严重程度排列）

-**文件**: `store/NebulaShell/plugin-storage/main.py`
+### 🔴 CRITICAL

-多个方法实现与签名完全不符：
+| # | 问题 | 位置 | 说明 |
+|---|------|------|------|
+| 1 | **WebUI 仍为 v1.1.0 静态页面** | `oss/webui/index.html` | 显示 v1.1.0 版本号，数据硬编码（"13个活跃插件"等），未对接后端 API |
+| 2 | **无 JWT/CSRF/输入验证中间件** | `oss/core/` | RELEASE_v1.2.1 规划的 `oss/core/security/` 目录不存在，安全中间件未实现 |
+| 3 | **无防火墙/运维工具箱模块** | `oss/core/` | `oss/core/firewall/` 和 `oss/core/ops/` 目录不存在 |
+| 4 | **无 `/metrics` Prometheus 端点** | `oss/core/http_api/` | 健康检查端点和监控指标未实现 |
+| 5 | **plugin-storage 部分方法实现可疑** | `oss/store/NebulaShell/plugin-storage/main.py` | `keys()`、`delete()` 等方法逻辑需要验证 |
+| 6 | **HTTP API 路由空实现风险** | `oss/core/http_api/router.py` | 路由处理逻辑需要核验 |

- **`get()`（第 17-20 行）**：参数是 `key, default`，但方法体写的是 `self._data[key] = value`（set 的逻辑），且 `_save()` 未定义
- **`delete()`（第 22-24 行）**：返回 `key in self._data` 而不是执行删除
- **`keys()`（第 26-29 行）**：调用 `self._data.clear()` 清空数据，然后 `_save()` 未定义
- **`size()`（第 31-33 行）**：返回 `self._data.copy()` 而不是长度
- **`set_many()`（第 35-40 行）**：返回一个字典而不是执行设置操作
+### 🟠 HIGH
+
+| # | 问题 | 位置 | 说明 |
+|---|------|------|------|
+| 7 | **测试覆盖率不足** | 全部 | 16 个测试文件覆盖主要模块，但核心 HTTP 路由、安全中间件、NBPF 加载链路缺乏端到端测试 |
+| 8 | **无配置 Schema 验证** | `oss/config/config.py` | 写错配置 key 名静默使用默认值 |
+| 9 | **多处 `except: pass`** | 多处 | 异常被静默吞掉，不利于调试 |
+| 10 | **CORS 配置验证** | `oss/core/http_api/` | 需要确认 CORS 头是否从配置读取而非硬编码 |
+| 11 | **限流器线程安全问题** | `oss/core/http_api/rate_limiter.py` | 需要验证线程锁和 deque 使用是否正确 |
+| 12 | **无 HTTPS 支持** | 全部 | 所有通信明文传输 |
+
+### 🟡 MEDIUM
+
+| # | 问题 | 位置 | 说明 |
+|---|------|------|------|
+| 13 | **无统一错误响应格式** | 多处 | 有时 JSON 有时纯文本 |
+| 14 | **无日志轮转文件日志** | `oss/logger/logger.py` | 需要确认是否已实现 RotatingFileHandler |
+| 15 | **无 CI/CD 配置更新** | `.github/workflows/` | 需要确认 CI 配置是否匹配当前测试结构 |
+| 16 | **Dockerfile 缺少 `.dockerignore`** | `.dockerignore` | 文件存在但为空 |
+| 17 | **全局状态单例** | `oss/config/config.py` | `_global_config` 单例模式 |
+| 18 | **Dashboard 鉴权缺失** | `oss/webui/` | WebUI 无登录鉴权 |
+
+### 🟢 LOW
+
+| # | 问题 | 位置 | 说明 |
+|---|------|------|------|
+| 19 | **ENABLE_ASYNC 配置项未使用** | `oss/config/config.py` | 定义了但从未被引用 |
+| 20 | **残留注释为中文** | 多处 | 限制贡献者范围 |
+| 21 | **无 `.env.example`** | 根目录 | 环境变量无参考文档 |
+| 22 | **配置默认值不一致** | `oss/config/config.py` | HOST 默认值与实际读取逻辑需确认 |

 ---

-### 3. `http-api` 路由处理未实现（CRITICAL）
+## 三、历史问题状态追踪

-**文件**: `store/NebulaShell/http-api/router.py:2-4`
+以下问题来自 2026-05-04 的审查报告，当前状态已更新：

-```python
-class HttpRouter:
-    def handle(self, request: Request) -> Response:
-        pass  # 空实现！
-```
-
-HTTP 路由的 `handle()` 方法为空，所有 HTTP 请求都会返回 `None`，导致服务器无法正常响应。
+| 原问题 | 原等级 | 当前状态 | 说明 |
+|--------|--------|----------|------|
+| plugin-storage 路径穿越 | 🔴 CRITICAL | ⚠️ 已重构 | 当前代码已完全重写，使用内存缓存 + 文件持久化，但需要验证新实现的安全性 |
+| plugin-storage 方法实现错误 | 🔴 CRITICAL | ⚠️ 已重构 | 同上，方法签名和逻辑已变更，需要重新审查 |
+| HTTP API 路由空实现 | 🔴 CRITICAL | ⚠️ 待验证 | `oss/core/http_api/router.py` 存在，但需要确认路由逻辑是否完整 |
+| `init()` 空指针 | 🔴 CRITICAL | ✅ 已修复 | 对应插件不存在于当前仓库 |
+| code-reviewer 不可用 | 🔴 CRITICAL | ✅ 已清理 | 该插件已从仓库移除 |
+| CORS `*` | 🟠 HIGH | ⚠️ 待验证 | 需要确认当前中间件实现 |
+| 限流器线程安全 | 🟠 HIGH | ⚠️ 待验证 | 需要确认当前 `rate_limiter.py` 实现 |
+| 插件加载器安全检查可绕过 | 🟠 HIGH | ✅ 已清理 | 旧版 plugin-loader 已不在仓库中 |
+| 空方法/存根代码 | 🟠 HIGH | ⚠️ 部分修复 | engine.py 已拆分为 27 行，但部分插件仍有存根 TODO |
+| 重复中间件实现 | 🟡 MEDIUM | ✅ 已清理 | 旧版 store 目录已移除 |
+| CSRF 导入缺失 | 🟡 MEDIUM | ⏳ 未修复 | CSRF 防护尚未实现 |
+| 静态资源缓存头 | 🟡 MEDIUM | ⏳ 未修复 | WebUI 无缓存策略 |
+| 配置不一致 | 🟢 LOW | ⚠️ 部分修复 | HOST 默认值已调整，但仍有不一致 |
+| 异常静默吞掉 | 🟢 LOW | ⚠️ 部分修复 | 部分 `except: pass` 已修复，但仍有残留 |

 ---

-### 4. `http-api` 的 `init()` 调用 `self.server.start()` 但 `server` 为 `None`（CRITICAL）
-
-**文件**: `store/NebulaShell/http-api/main.py:7-8`
-
-```python
-def init(self, deps: dict = None):
-    self.server.start()  # self.server 是 None！
-```
-
-`__init__` 中 `self.server = None`，但 `init()` 直接调用 `self.server.start()`，会抛出 `AttributeError`。
-
---
-
-### 5. `code-reviewer` 核心逻辑未实现（HIGH）
-
-**文件**: `store/NebulaShell/code-reviewer/core/reviewer.py:10-34`
-
-`run_check` 方法中使用了未定义的变量 `filepath`（第 14 行），且没有文件遍历逻辑。`main.py` 中的 `check()` 方法也是 `pass`。整个代码审查插件**实际上无法运行**。
-
---
-
-### 6. `code-reviewer` 引用检查器使用未定义变量（HIGH）
-
-**文件**: `store/NebulaShell/code-reviewer/checks/references.py`
-
- **`_scan_project_modules`（第 43-53 行）**：使用了未定义的 `dir_path`、`base_name` 变量
- **`_scan_plugin_modules`（第 55-62 行）**：同样使用了未定义的变量
- **`check()`（第 64-104 行）**：使用了未定义的 `tree` 变量
- **`_is_module_available()`（第 125-155 行）**：参数是 `module_name, file_path`，但方法体使用了未定义的 `module_name`（第 125 行）
-
---
-
-## 二、安全问题
-
-### 7. CORS 配置过于宽松（MEDIUM）
-
-**文件**: `store/NebulaShell/http-api/server.py:72-74`
-
-```python
-self.send_header("Access-Control-Allow-Origin", "*")
-```
-
-OPTIONS 预检请求返回 `Access-Control-Allow-Origin: *`，但配置中实际设置了允许的来源列表。应使用配置中的 `CORS_ALLOWED_ORIGINS`。
-
---
-
-### 8. 限流器线程安全问题（MEDIUM）
-
-**文件**: `store/NebulaShell/http-api/rate_limiter.py:156-168`
-
-`_is_rate_limited` 方法中使用了 `self.requests[limit_key]` 但没有加锁，且使用了 `popleft()` 但 `self.requests[limit_key]` 初始化为 `[]`（列表，不是 deque），会抛出 `AttributeError`。
-
---
-
-### 9. CSRF 中间件缺少 `json` 导入（MEDIUM）
-
-**文件**: `store/NebulaShell/http-api/csrf_middleware.py:138`
-
-第 138 行使用了 `json.dumps()`，但 `json` 只在第 168 行的局部作用域中导入。模块顶部没有 `import json`。
-
---
-
-### 10. 插件加载器 `_load_config` 安全检查可绕过（LOW）
-
-**文件**: `store/NebulaShell/plugin-loader/main.py:433-436`
-
-```python
-for p in ['import ', 'from ', 'open(', 'exec(', 'eval(', 'compile(', 'os.', 'sys.', 'subprocess', 'lambda', 'def ', 'class ']:
-    if p in content:
-```
-
-这种字符串包含检查很容易被绕过，例如 `import  `（多加空格）、`#import`（注释中）等。
-
---
-
-## 三、代码质量问题
-
-### 11. 大量空方法和未实现功能（HIGH）
-
- `oss/plugin/base.py`：空文件
- `http-api/router.py`：`handle()` 空实现
- `code-reviewer/main.py`：`check()` 空实现
- `code-reviewer/checks/quality.py`：`_calculate_complexity()` 空实现
- `code-reviewer/checks/references.py`：`_is_name_defined()` 空实现
-
---
-
-### 12. 重复的中间件实现（MEDIUM）
-
-**文件**: `store/NebulaShell/http-api/middleware.py` 和 `store/NebulaShell/http-api/rate_limiter.py`
-
-`RateLimitMiddleware` 在两个文件中都有实现（`middleware.py:87-201` 和 `rate_limiter.py:41-122`），功能重复。`MiddlewareChain` 使用的是 `middleware.py` 中的版本，而 `rate_limiter.py` 中的版本未被使用。
-
---
-
-### 13. `plugin-storage` 的 `_load()` 方法始终写空数据（MEDIUM）
-
-**文件**: `store/NebulaShell/plugin-storage/main.py:12-15`
-
-```python
-def _load(self):
-    data_file = self.data_dir / "data.json"
-    with open(data_file, "w", encoding="utf-8") as f:
-        json.dump(self._data, f, ...)
-```
-
-`_load()` 方法名暗示加载数据，但实际上是用空数据覆盖文件。每次初始化都会清空持久化数据。
-
---
-
-### 14. `plugin-storage` 的 `stop()` 方法在 `start()` 之前执行配置加载（MEDIUM）
-
-**文件**: `store/NebulaShell/plugin-storage/main.py:164-181`
-
-`stop()` 方法中加载配置并初始化 `shared`，但 `start()` 中只是打印日志。配置加载应该在 `start()` 或 `init()` 中完成。
-
---
-
-### 15. 成就系统异常被静默吞掉（LOW）
-
-多处代码使用 `try/except Exception: pass` 模式，隐藏了潜在的错误，不利于调试。
-
---
-
-### 16. 硬编码的配置默认值不一致（LOW）
-
-`oss/config/config.py` 中 `HOST` 默认值为 `127.0.0.1`，但 `http-api/server.py:30` 中 `HttpServer.__init__` 的默认值是 `"0.0.0.0"`，存在不一致。
-
---
-
-## 四、架构问题
-
-### 17. 插件加载顺序依赖隐式约定
-
-`plugin-loader` 通过 `load_priority: "first"` 标记和硬编码的 `core_plugins` 集合来控制加载顺序，缺乏清晰的优先级机制。
-
---
-
-### 18. `use()` 函数绕过插件管理器
-
-`plugin-bridge/main.py` 中的 `use()` 函数可以直接从文件系统加载插件实例，绕过了 `plugin-loader` 的权限检查和生命周期管理。
-
---
-
-### 19. 测试覆盖率不足
-
-测试文件主要集中在配置和日志等基础功能，核心的 HTTP 路由、插件加载、安全中间件等功能缺乏有效测试。
-
---
-
-## 总结
-
-| 等级 | 数量 | 关键问题 |
-|------|------|----------|
-| CRITICAL | 4 | 路径穿越、方法实现错误、路由空实现、空指针 |
-| HIGH | 3 | 代码审查器不可用、未定义变量 |
-| MEDIUM | 5 | CORS、线程安全、重复实现、数据丢失 |
-| LOW | 3 | 安全检查绕过、异常静默、配置不一致 |
+## 四、总结
+
+| 等级 | 数量 | 关键项 |
+|------|------|--------|
+| 🔴 CRITICAL | 6 | WebUI 未更新、安全模块未实现、防火墙/运维缺失、无 metrics、plugin-storage 待验证、路由待核验 |
+| 🟠 HIGH | 6 | 测试覆盖率、配置验证、except:pass、CORS、限流、HTTPS |
+| 🟡 MEDIUM | 6 | 错误格式、日志轮转、CI、Docker、全局状态、鉴权 |
+| 🟢 LOW | 4 | 未使用配置、中文注释、env 文档、默认值不一致 |

 **最紧急的修复项**：
-1. 修复 `plugin-storage` 的所有方法实现
-2. 实现 `http-api` 的路由处理
-3. 修复 `http-api` 的 `init()` 空指针问题
-4. 修复 `code-reviewer` 的未定义变量
-5. 统一限流器实现，修复线程安全问题
+1. 实现 `oss/core/security/` 安全中间件（JWT/CSRF/输入验证）
+2. 实现 `oss/core/ops/` 运维工具箱（健康检查/备份/监控）
+3. 更新 WebUI 为可用的管理面板
+4. 完善测试覆盖
+5. 实现 HTTPS 支持