# NebulaShell 代码审查报告

> 审查日期：2026-05-04

---

## 一、严重问题

### 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` 没有使用它。

---

### 2. `plugin-storage` 方法实现完全错误（CRITICAL）

**文件**: `store/NebulaShell/plugin-storage/main.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 行）**：返回一个字典而不是执行设置操作

---

### 3. `http-api` 路由处理未实现（CRITICAL）

**文件**: `store/NebulaShell/http-api/router.py:2-4`

```python
class HttpRouter:
    def handle(self, request: Request) -> Response:
        pass  # 空实现！
```

HTTP 路由的 `handle()` 方法为空，所有 HTTP 请求都会返回 `None`，导致服务器无法正常响应。

---

### 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 | 安全检查绕过、异常静默、配置不一致 |

**最紧急的修复项**：
1. 修复 `plugin-storage` 的所有方法实现
2. 实现 `http-api` 的路由处理
3. 修复 `http-api` 的 `init()` 空指针问题
4. 修复 `code-reviewer` 的未定义变量
5. 统一限流器实现，修复线程安全问题