Skip to content

LovingCode_Technical_Design.md

Latest commit

 

History

History
253 lines (199 loc) · 8.82 KB

LovingCode_Technical_Design.md

File metadata and controls

253 lines (199 loc) · 8.82 KB

LovingCode 技术架构设计文档 (Technical Design Document)

版本： v1.0
日期： 2026-01-16
状态： 草稿 (Draft)

1. 引言与目标

本文档旨在为 LovingCode 平台提供详细的技术实现方案。基于产品需求文档 (PRD v1.0)，我们将构建一个以 "From Coding to Architecting" 为核心理念的 AI 辅助编程挑战平台。

核心技术目标：

  • 高性能交互： 复杂的编辑器状态同步与流式 AI 响应。
  • 安全沙盒： 隔离执行用户生成的代码，防止恶意攻击。
  • 可扩展性： 支持多种 LLM 模型切换及高并发评测。

2. 技术栈选型

2.1 前端 (Client Side)

  • 核心框架： Vue 3 (Composition API)
  • 构建工具： Vite
  • 语言： TypeScript
  • 状态管理： Pinia (持久化 + 复杂状态流转)
  • UI 组件库： Tailwind CSS (原子化样式) + Element Plus (通用组件)
  • 代码编辑器： Monaco Editor (VS Code 内核)
  • 路由管理： Vue Router 4
  • 数据获取： Axios + TanStack Query (Vue Query)
  • 实时通信： Socket.io Client

2.2 后端 (Server Side)

  • 运行环境： Node.js (v20+ LTS)
  • Web 框架： NestJS (推荐) 或 Express (考虑到架构扩展性，建议使用 NestJS)
  • 语言： TypeScript
  • API 协议： RESTful API (常规业务) + WebSocket (代码运行输出、AI流式对话)
  • ORM： Prisma 或 TypeORM
  • 队列服务： BullMQ (基于 Redis，用于处理代码执行任务队列)

2.3 基础设施与存储

  • 数据库： PostgreSQL (存储用户、题目、提交记录)
  • 缓存/消息代理： Redis (Session 缓存、任务队列、实时消息)
  • 代码沙盒： Docker + gVisor (安全容器运行时)
  • 对象存储： AWS S3 / MinIO (存储题目资源、图片)

3. 系统架构设计

3.1 总体架构图 (Conceptual)

graph TD
    Client[Vue 3 Client] -->|REST API| Gateway[API Gateway / Load Balancer]
    Client -->|WebSocket| Gateway
    
    Gateway --> Service_Auth[Auth Service]
    Gateway --> Service_Core[Core API Service]
    
    Service_Core --> DB[(PostgreSQL)]
    Service_Core --> Cache[(Redis)]
    Service_Core --> Queue[Task Queue (Redis)]
    
    Queue --> Worker_Sandbox[Sandbox Worker (Node.js)]
    Worker_Sandbox --> Docker[Docker Engine]
    
    Service_Core --> Service_LLM[LLM Gateway Service]
    Service_LLM --> OpenAI[OpenAI API]
    Service_LLM --> Anthropic[Anthropic API]
Loading

4. 前端设计详解 (Vue 3)

4.1 目录结构规范

src/
├── assets/             # 静态资源
├── components/         # 通用基础组件 (Button, Modal)
├── composables/        # 组合式函数 (useAuth, useWebSocket)
├── layouts/            # 页面布局 (MainLayout, AuthLayout)
├── modules/            # 业务模块 (核心)
│   ├── challenge/      # 挑战相关
│   │   ├── components/ # 题目面板, 约束条
│   │   └── store/      # 题目状态
│   ├── workshop/       # 代码工作台
│   │   ├── components/ # MonacoWrapper, Terminal, DiffView
│   │   └── composables/# 代码执行逻辑
│   └── commander/      # Prompt 指令台
│       ├── components/ # PromptEditor, ChatHistory
│       └── utils/      # Prompt 模板处理
├── router/             # 路由配置
├── services/           # API 接口封装
├── stores/             # 全局状态 (User, Settings)
└── utils/              # 工具函数

4.2 核心组件设计

A. 代码工作台 (The Workshop)

  • MonacoEditor.vue: 封装 Monaco Editor 实例。
    • Props: code, language, readOnly, decorations (用于 Cue 高亮).
    • Events: update:code, selection-change (触发 Cue 悬浮).
  • DiffViewer.vue: 使用 Monaco Editor 的 Diff Editor 模式，展示 AI 修改前后的对比。
  • TerminalPanel.vue: 集成 xterm.js，通过 WebSocket 连接后端容器流。

B. Prompt 指令台 (The Commander)

  • PromptInput.vue: 支持 Slash Command (/) 的富文本输入框。
  • ThoughtTree.vue: 可视化展示思维链分支 (Tree of Thoughts)，允许用户回溯和分叉对话。

C. Cue 微调系统 (The Precision Tool)

  • CueFloatingWidget.vue: 监听编辑器选区事件，计算绝对坐标进行定位。
    • 功能: 输入微调指令，调用 In-painting 接口。

4.3 状态管理 (Pinia)

  • useChallengeStore:
    • currentChallenge: 题目详情。
    • constraints: 当前 Token/Turn 消耗情况。
  • useWorkshopStore:
    • files: 虚拟文件系统结构。
    • activeFile: 当前编辑文件。
    • executionStatus: 运行中/成功/失败。
  • useChatStore:
    • messages: 对话历史 (Role, Content)。
    • branches: 思维链分支数据。

5. 后端设计详解 (Node.js)

5.1 模块划分 (NestJS Modules)

1. AuthModule

  • 处理注册、登录、JWT 签发。
  • 集成 GitHub/Google OAuth。

2. ChallengeModule

  • 管理题目 CRUD。
  • 获取题目详情、附件、约束条件。

3. LLMModule (AI 核心)

  • Prompt Manager: 组装 System Prompt，注入题目上下文 (Context)。
  • Model Router: 根据策略路由到 GPT-4o 或 GPT-4o-mini。
  • Token Counter: 计算消耗，更新用户配额。
  • Streaming Service: 处理流式响应，推送到前端。

4. SandboxModule (执行核心)

  • Container Manager: 使用 dockerode 库管理容器生命周期。
  • Execution Strategy: 针对不同语言 (JS, Python) 的执行策略。
  • Output Stream: 捕获容器 stdout/stderr 并通过 WebSocket 转发。

5.2 数据库设计 (ERD)

Users (用户表)

  • id (UUID)
  • email, username
  • token_balance (剩余 Token 数)

Challenges (题目表)

  • id (UUID)
  • title, description (Markdown)
  • difficulty
  • constraints (JSON: { max_tokens, max_turns, allowed_models })
  • starter_code (Text)
  • test_cases (JSON/Text)

Sessions (挑战会话表)

  • id (UUID)
  • user_id, challenge_id
  • status (active, completed)
  • token_usage, turn_count

Prompts (对话记录表)

  • id (UUID)
  • session_id
  • role (user, assistant, system)
  • content (Text)
  • parent_id (UUID, 用于支持思维链分支)

Executions (执行记录表)

  • id (UUID)
  • session_id
  • code_snapshot
  • output
  • status (success, error)
  • score

6. 关键功能实现方案

6.1 代码沙盒 (The Sandbox)

为了安全运行用户代码，我们将采用 按需容器 方案。

  1. 触发: 用户点击 "Run Code"。
  2. 创建: 后端 SandboxService 收到请求，分配一个唯一的 execution_id。
  3. 启动: 使用 Docker 启动一个临时容器（限制 CPU/内存/网络）。
    • 镜像: lovingcode-runtime-node 或 lovingcode-runtime-python。
    • 挂载: 将用户代码作为 Volume 挂载或写入容器 /app 目录。
  4. 执行: 运行 npm test 或 python main.py。
  5. 流式反馈: Docker 的 Log Stream 通过 WebSocket 实时推送到前端 TerminalPanel。
  6. 清理: 执行结束后立即销毁容器，或保留短时间以供复用（Warm Pool 策略）。

6.2 Cue 微调 (In-painting)

如何实现只修改选中的 5 行代码？

  1. 前端: 获取选区代码 selection，以及选区前代码 prefix 和选区后代码 suffix。
  2. 后端: 构造特殊的 Prompt 给 LLM。 
    You are a code editing assistant.
Original Code Context:
[PRE]
${prefix}
[SEL]
${selection}
[SUF]
${suffix}

User Instruction: "${user_cue}"

Task: Rewrite the [SEL] part to satisfy the instruction. Output ONLY the replaced code.
  3. 应用: 前端接收到新代码，使用 Monaco 的 executeEdits API 替换选区。

6.3 智能 Diff (Smart Diff)

当 AI 生成全新版本的代码时：

  1. 后端不直接覆盖文件。
  2. 前端接收到 AI 响应的新代码字符串。
  3. 调用 monaco.editor.createDiffEditor。
  4. Original Model = 当前编辑器内容。
  5. Modified Model = AI 生成的内容。
  6. 用户在 Diff 视图中逐个或全部 Accept 变更。

7. 部署与运维

  • CI/CD: GitHub Actions 自动构建 Docker 镜像并部署。
  • 前端托管: Vercel (自动对接 GitHub)。
  • 后端托管: AWS EC2 或 DigitalOcean Droplet (Docker Compose 编排)。
  • 监控:
    • Sentry: 前后端错误追踪。
    • Prometheus + Grafana: 监控 API 延迟、容器数量、Token 消耗速率。

8. 下一步计划 (Next Steps)

  1. 初始化仓库: 设置 Monorepo (Turborepo) 或独立仓库。
  2. 搭建基础脚手架: 配置 Vue 3 + Tailwind, NestJS + Prisma。
  3. PoC (概念验证): 实现一个简单的 "Hello World" 代码通过 API 在 Docker 中运行并返回结果。