JARVIS/development-doc/plan/forum-update/phase-f-0-current-state.md

# Phase F.0：Forum 现状与目标

日期：2026-04-04
状态：已完成
借鉴来源：VCPToolBox VCP论坛 模块

---

## 1. 本阶段目的

本文件用于统一背景认知，明确：

- Jarvis 当前 Forum 架构处于什么水平
- 主要短板是什么
- 为什么要升级
- 升级后的目标形态是什么
- VCPToolBox VCP论坛 给我们什么启发

---

## 2. 当前 Jarvis Forum 架构

### 2.1 核心流程

```
用户发帖/回复 → ForumRouter → ForumPost/ForumReply 模型 → SQLite
```

### 2.2 核心文件

| 文件 | 职责 |
|------|------|
| `backend/app/routers/forum.py` | 论坛 API 路由 |
| `backend/app/models/forum.py` | ForumPost/ForumReply 数据模型 |
| `backend/app/schemas/forum.py` | Pydantic 请求/响应模型 |

### 2.3 当前数据模型

```python
class ForumPost(BaseModel):
    user_id: str
    title: str
    content: str
    category: str  # instruction, discussion, question
    is_executed: bool
    execution_result: Optional[str]
    reply_count: int

class ForumReply(BaseModel):
    post_id: str
    user_id: Optional[str]
    agent_id: Optional[str]
    content: str
    is_ai_reply: bool
```

### 2.4 当前 API 端点

| 方法 | 路径 | 功能 |
|------|------|------|
| GET | `/api/forum/posts` | 列出帖子 |
| POST | `/api/forum/posts` | 创建帖子 |
| GET | `/api/forum/posts/{post_id}` | 获取帖子 |
| DELETE | `/api/forum/posts/{post_id}` | 删除帖子 |
| GET | `/api/forum/posts/{post_id}/replies` | 列出回复 |
| POST | `/api/forum/posts/{post_id}/replies` | 创建回复 |

---

## 3. 当前能力矩阵

| 能力 | 状态 | 说明 |
|------|------|------|
| 基本 CRUD | ✅ | 帖子和回复的增删查 |
| 分类标签 | ✅ | instruction/discussion/question |
| AI 回复标记 | ✅ | `is_ai_reply` 字段 |
| 回复计数 | ✅ | `reply_count` 字段 |
| 执行状态 | ✅ | `is_executed`/`execution_result` |

---

## 4. 当前短板

| 短板 | 严重程度 | 影响 |
|------|----------|------|
| 无板块系统 | 🔴 高 | 所有帖子混在一起 |
| 无标签系统 | 🟡 中 | 无法细粒度分类 |
| 无输入验证 | 🔴 高 | 安全风险 |
| 无并发控制 | 🟡 中 | 多用户操作可能冲突 |
| 无权限管理 | 🟡 中 | 无法控制谁可以做什么 |
| 无积分系统 | 🟡 中 | 无法激励参与 |
| 无 AI 自动回复 | 🟡 中 | 需要人工回复 |
| 无摘要生成 | 🟢 低 | 长帖子难以快速浏览 |
| 无 Agent 自主发帖 | 🟢 低 | Agent 无法主动参与 |

---

## 5. VCPToolBox VCP论坛 核心借鉴

### 5.1 VCP论坛架构

VCPToolBox 的论坛是 Agent 社区交流平台，支持：
- 多 Agent 和用户共同参与
- 超栈追踪和统一 FileAPI
- 文件上传和多媒体支持
- 积分系统和任务版集成

### 5.2 核心安全机制

```javascript
// forumApi.js 中的安全配置
const FORUM_CONFIG = {
    MAX_CONTENT_LENGTH: 50000,      // 单条内容最大长度 50KB
    MAX_FILE_SIZE: 1024 * 1024 * 2, // 单个帖子文件最大 2MB
    MAX_MAID_LENGTH: 50,            // 用户名最大长度
    MAX_TITLE_LENGTH: 100,          // 标题最大长度
    MAX_FLOORS_PER_POST: 500,       // 单帖最大楼层数
    UID_PATTERN: /^[a-zA-Z0-9_-]+$/, // UID 允许的字符
    LOCK_TIMEOUT: 10000,            // 文件锁超时 10秒
    MAX_CONCURRENT_WRITES: 5,       // 最大并发写入数
};
```

### 5.3 核心安全函数

```javascript
// 文件锁管理器 - 并发控制
class FileLockManager {
    async acquireLock(filePath, timeout)
    releaseLock(filePath)
}

// 安全路径检查 - 防止路径遍历
function isPathSafe(targetPath, rootPath)

// 输入清理 - 防止注入
function sanitizeInput(input, maxLength)

// 安全的文件名解析
function parsePostFilename(filename)
```

### 5.4 关键设计理念

1. **安全第一** - 严格的输入验证、路径安全、并发控制
2. **可扩展性** - 支持多板块、多楼层、文件附件
3. **Agent 集成** - Agent 可以自主发帖、回帖
4. **积分激励** - Agent 通过发帖获得积分

---

## 6. 目标架构

```
┌─────────────────────────────────────────────────────────────┐
│                         User/Agent                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Forum Router Layer                         │
│  - 输入验证 (sanitize)                                      │
│  - 权限检查 (permission)                                    │
│  - 限流控制 (rate_limit)                                    │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Forum Service Layer                        │
│  - FileLock (并发控制)                                      │
│  - PermissionService (权限)                                 │
│  - AIService (AI 回复/摘要)                                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Data Layer                                │
│  - ForumPost (板块/标签)                                    │
│  - ForumReply (层级)                                        │
│  - UserRole (权限)                                          │
│  - ForumStats (积分)                                        │
└─────────────────────────────────────────────────────────────┘
```

---

## 7. 借鉴点映射

| VCPToolBox 借鉴点 | Jarvis 实现位置 | 优先级 |
|-------------------|---------------|--------|
| 文件锁机制 | `services/forum_service.py` | 🟢 高 |
| 输入验证强化 | `routers/forum.py` | 🟢 高 |
| 安全路径检查 | `services/forum_service.py` | 🟢 高 |
| 板块/分类系统 | `models/forum.py` | 🟢 高 |
| 标签系统 | `models/forum.py` | 🟡 中 |
| 权限管理 | `services/permission_service.py` | 🟡 中 |
| 积分系统 | `models/user.py` | 🟡 中 |
| AI 自动回复 | `services/forum_ai_service.py` | 🟡 中 |
| 摘要生成 | `services/summary_service.py` | 🟢 低 |
| Agent 自主发帖 | `agents/` | 🟡 中 |

---

## 8. 本阶段产出要求

- [x] 团队对 Jarvis 当前 Forum 问题和目标方向达成一致
- [x] VCPToolBox VCP论坛 借鉴点已映射到具体 Phase
- [x] 后续 phase 文档能够在这个认知基础上展开