# fde

**Repository Path**: wzcool/fde

## Basic Information

- **Project Name**: fde
- **Description**: fde
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# FDE 文档智能生成系统 · 开发计划

### 1. 项目概述
**目标**：构建一个能够通过语音、文本、图片、附件等多模态输入，与用户进行引导式对话，自动生成高质量 FDE（Forward Deploy Engineer）文档的协作式 AI 系统。文档输出需包含项目背景、用户/行业痛点、AI 赋能点、技术架构、数据库表结构、主题样式和业务流程图等核心章节。

**技术栈**：  
- 后端：Python + FastAPI + OAuth2 (JWT)  
- 前端：Vue3 + TypeScript + Pinia + TailwindCSS  
- AI 框架：LangGraph（有状态多智能体协作） + LangChain（工具/模型抽象）  
- 模型：支持 GPT-4o / Claude Sonnet 等多模态模型，本地方案可切换 Hermes 等开源模型  
- 基础设施：PostgreSQL + Redis + MinIO (对象存储) + WeasyPrint / Puppeteer (PDF导出)

---

### 2. 优点汲取与融合设计
我们从三个标杆项目中提取核心模式，并注入本系统：

| 源项目 | 汲取的优点 | 在本系统中的体现 |
|--------|------------|------------------|
| **Hermes Agent** | - 强大的函数调用与工具编排<br>- 长短期记忆管理<br>- 推理-行动循环（ReAct） | 使用 LangGraph 构造主控 Agent，拥有记忆（短期对话上下文 + 长期项目知识库），每个生成步骤都有明确工具调用，支持反思与修正。 |
| **Marvis** | - 多模态输入（语音、图片）<br>- 渐进式需求引导对话<br>- 缺失信息主动补齐 | 前端提供统一的输入栏（语音转文字、图片拖拽、附件上传），后端采用“需求澄清引擎”，在信息不完整时生成追问，逐步引导用户完成 FDE 各维度描述。 |
| **darwin-skil** | - 技能树（Skill Graph）模块化<br>- 技能可插拔、可组合<br>- 声明式配置生成工作流 | 将每个文档章节（痛点分析、架构设计、表结构生成等）封装为独立“技能”节点，通过 YAML 配置文件组合成不同 FDE 模板，技能可复用、可替换。 |

**融合后的核心工作流**：  
用户输入 → 多模态理解 → 需求澄清对话（若有必要） → 技能调度器根据 FDE 模板选择技能 DAG → 各技能并行/串行生成章节 → 章节内容组合与排版 → 输出预览（支持在线修改）→ 导出 PDF/Word。

---

### 3. 系统技术架构

```
┌──────────────────────────────────────────────────────┐
│                    Frontend (Vue3+TS)                │
│  ┌──────────┐ ┌───────────┐ ┌──────────────┐       │
│  │ Chat UI  │ │ Doc Preview│ │ Project Mgmt │       │
│  │ (流式)   │ │ (Markdown) │ │ (CRUD)       │       │
│  └──────────┘ └───────────┘ └──────────────┘       │
│         │              │               │            │
└─────────┼──────────────┼───────────────┼────────────┘
          │              │               │
┌─────────▼──────────────▼───────────────▼────────────┐
│                   API Gateway (FastAPI)              │
│  /ws (WebSocket 流式)  /docs  /projects  /skills    │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│               Backend Service Layer                  │
│                                                      │
│  ┌───────────────┐  ┌───────────────────┐           │
│  │ Auth (OAuth2) │  │ Skill Registry &  │           │
│  │ RBAC          │  │ Config Loader     │           │
│  └───────────────┘  └────────┬──────────┘           │
│                               │                      │
│  ┌───────────────────────────▼──────────────────┐   │
│  │           LangGraph Agent Orchestrator       │   │
│  │  ┌─────────┐  ┌──────────┐  ┌────────────┐  │   │
│  │  │Clarify  │  │Skill     │  │Compile     │  │   │
│  │  │Engine   │  │Scheduler │  │Engine      │  │   │
│  │  └─────────┘  └──────────┘  └────────────┘  │   │
│  │       │              │               │       │   │
│  └───────┼──────────────┼───────────────┼───────┘   │
│          │              │               │           │
│  ┌───────▼──────────────▼───────────────▼───────┐   │
│  │            Tool & Memory Services            │   │
│  │  Whisper  │ OCR/Vision │RAG(历史项目)│Web    │   │
│  │  (语音)  │ (图片解析) │ (向量检索) │Search │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│                   Data / Infra                       │
│  PostgreSQL  │  Redis(缓存/状态)  │  MinIO(文件)    │
└──────────────────────────────────────────────────────┘
```

---

### 4. 核心模块详细设计

#### 4.1 多模态输入与理解
- **语音**：前端录制或上传音频，后端调用 Whisper API 转为文本。
- **图片**：通过多模态 LLM（GPT-4o 等）提取图中的架构草图、手绘流程图、UI 参考等信息，转化为结构化描述。
- **附件**：支持 PDF/Word/PPT/Excel。使用 PyMuPDF 与 python-docx 提取全文，长文档先切片，再通过 LLM 摘要提取与 FDE 相关的关键需求。
- **统一上下文**：所有输入转换后的文本与元数据统一放入对话上下文窗口，由 Agent 管理。

#### 4.2 需求澄清引擎（汲取 Marvis 引导式交互）
- **原理**：维护一份“FDE 信息完备性模型”，标记每个章节必须收集的槽位（Slot）。如“项目背景”需要：客户行业、当前现状、期望目标。
- **流程**：每次用户输入后，Clarify Agent 检查槽位填充率。若低于阈值，生成不超过3个关键追问（避免压迫感），通过 WebSocket 推送到前端聊天界面。支持“跳过”选项，允许用户自主控制详细度。
- **状态机**：`IDLE -> COLLECTING -> CLARIFYING -> GENERATING -> REVIEWING -> EXPORTING`。

#### 4.3 技能树与调度器（汲取 darwin-skil 可组合性）
**技能定义结构（YAML）**：
```yaml
skill_id: "background"
name: "项目背景生成"
depends_on: []
required_slots: ["industry", "current_state", "goal"]
prompt_template: "你是售前专家，根据以下信息撰写项目背景..."
model: "gpt-4o"
tools: ["web_search"]  # 可选，如需查询行业信息
output_key: "project_background"
```
**FDE 模板示例**：
```yaml
template_id: "standard_fde"
skills: 
  - background
  - pain_points (depends: background)
  - ai_empower (depends: pain_points)
  - architecture (depends: background, pain_points)
  - table_schema (depends: architecture)
  - ui_theme (depends: background)
  - business_process (depends: background, pain_points)
```
**调度器**：根据依赖关系自动构建 DAG，使用 `asyncio` 并发执行无依赖的技能，按需分配 LLM 调用资源，控制并发数防止 API 限流。

#### 4.4 文档生成与编译
- **技术架构图**：LLM 生成 Mermaid.js 代码，前端实时渲染，支持手动微调后重新嵌入文档。
- **表结构**：生成 SQL DDL 语句 + 表关系描述（Markdown 表格）。可选调用代码解释器验证语法。
- **主题样式**：生成 CSS 变量建议或 Tailwind 配置片段，附带颜色预览（前端渲染色块）。
- **业务流程**：生成 BPMN 2.0 XML，前端用 bpmn-js 渲染。
- **编译引擎**：将各章节 Markdown 片段按模板拼接，通过 Jinja2 渲染最终文档，输出为 Markdown 或直接转为 PDF（WeasyPrint）供下载。

#### 4.5 记忆与个性化（汲取 Hermes 长短期记忆）
- **短期记忆**：对话历史全部保留在 LangGraph 的 Checkpointer（Redis/Postgres）中，支持上下文窗口管理。
- **长期记忆**：存储用户既往生成的 FDE 项目、客户名称、行业偏好等向量化信息，在新项目中通过 RAG 检索相似案例，辅助生成更贴合用户风格的文档。
- **用户配置**：可保存偏好的技术栈、文档风格（正式/活泼）、常用组件。

---

### 5. 数据流时序图（生成一次 FDE）
```
User -> Frontend: 输入语音+图片+文本
Frontend -> API: WebSocket 消息 (session_id)
API -> Input Processor: 多模态解析 -> 统一上下文
Input Processor -> Clarify Agent: 检查信息完备性
loop [如果信息不足]
    Clarify Agent -> Frontend: 追问消息 (流式)
    User -> Frontend: 补充回答
    Frontend -> Clarify Agent: 更新槽位
end
Clarify Agent -> Skill Scheduler: 启动 FDE 模板
Skill Scheduler -> Skill Nodes: 并行/串行执行技能
Skill Nodes -> LLM / Tools: 调用模型生成片段
LLM -> Skill Nodes: 流式返回内容
Skill Nodes -> Skill Scheduler: 收集章节结果
Skill Scheduler -> Compile Engine: 聚合与排版
Compile Engine -> Frontend: 流式推送完整文档预览
User -> Frontend: 在线修改（可选）
Frontend -> API: 保存/导出指令
API -> PDF Service: 生成最终交付件
```

---

### 6. 开发阶段与里程碑（总计 14 周）

#### 第1阶段：基础架构与骨架搭建（Week 1-2）
- 初始化项目仓库、CI/CD（GitHub Actions）
- FastAPI 项目结构、OAuth2+JWT 认证模块
- Vue3 前端骨架、路由、Pinia 状态管理、Tailwind 配置
- PostgreSQL 表设计（User, Project, Document, SkillConfig）
- Docker 开发环境编排
- **里程碑 M1**：前后端打通，可登录并创建空白项目

#### 第2阶段：多智能体框架与核心技能（Week 3-6）
- 集成 LangGraph，实现基础的 Agent 运行器与 Checkpointer
- 构建 Skill Registry 与 YAML 加载器
- 实现前5个核心技能：项目背景、痛点、AI赋能、架构、表结构
- 引入 LLM 抽象层（支持 OpenAI / Claude / 本地 Hermes）
- 编译引擎第一版：Markdown 拼接与实时预览 API
- **里程碑 M2**：给定完整上下文，可自动生成结构化的 FDE 草稿

#### 第3阶段：多模态与需求澄清（Week 7-9）
- 集成 Whisper 语音识别服务
- 集成多模态模型图片理解（上传架构草图 → 文本描述）
- 附件解析服务（PDF/Word）
- 实现 Clarify Agent 与槽位管理状态机
- WebSocket 流式通信，支持追问与状态更新
- **里程碑 M3**：通过自然对话即可补全信息并生成文档

#### 第4阶段：技能扩展与模板市场（Week 10-11）
- 实现 UI 主题样式生成、业务流程图生成技能
- 构建 FDE 模板选择界面，管理员可配置新模板
- 长期记忆与 RAG 集成（检索历史项目）
- 技能依赖图可视化（前端展示生成进度）
- **里程碑 M4**：支持多种行业 FDE 模板，生成内容质量达到可用水平

#### 第5阶段：文档编辑、导出与生产加固（Week 12-13）
- 前端 Markdown 富文本编辑器（支持实时修改生成内容）
- PDF 导出（支持自定义模板、水印、公司 Logo）
- 角色权限深化（管理员/普通用户/项目经理）
- 异常处理与降级（LLM 不可用时使用缓存版本）
- 性能优化（Redis 缓存、LLM 响应流式化）
- **里程碑 M5**：内部测试版上线，可完整走通从输入到导出 PDF 全流程

#### 第6阶段：测试、文档与试运行（Week 14）
- 端到端测试（Cypress / Playwright）
- 单元测试与集成测试覆盖核心 Agent 逻辑
- API 文档（自动生成 OpenAPI）
- 用户手册与部署说明
- 生产环境部署（Kubernetes + Nginx Ingress + 自动扩容）
- **里程碑 M6**：正式发布 V1.0

---

### 7. 关键技术挑战与应对
| 挑战 | 应对策略 |
|------|----------|
| LLM 生成内容质量不稳定，表格/代码可能错误 | 引入结构化输出（Function Calling / JSON Mode），对 SQL DDL 等添加格式校验；允许用户在线修正并重新编译。 |
| 长文档上下文溢出 | 采用 LangGraph 的摘要记忆，自动压缩旧对话；对附件采用 RAG 切片检索，只将最相关片段放入提示。 |
| 多技能并发下的 API 成本与延迟 | 实施并发池限制（最多 5 个 LLM 调用同时进行），使用 LangSmith 追踪，对非关键技能使用 cheaper 模型。 |
| 实时流式体验与状态同步 | WebSocket + Pinia 前端状态管理，后端使用 Server-Sent Events 块推送，LangGraph 的 `astream_events` 细粒度事件。 |
| 安全与数据隐私 | 所有文件加密存储（MinIO 服务端加密），对话记录可选择不清洗用于模型训练，OAuth 细粒度 scope 控制。 |

---

### 8. 团队配置建议
- **后端工程师 2人**：FastAPI + LangGraph + Agent 调度
- **AI/ML 工程师 1人**：Prompt 调优、技能设计、RAG 质量优化
- **前端工程师 2人**：Vue3 + 聊天组件 + 文档编辑器 + 可视化（Mermaid/BPMN）
- **DevOps 工程师 1人**：CI/CD、K8s 部署、监控与日志
- **产品经理/领域专家 1人**：定义 FDE 标准结构，评估文档质量，培训模板


理解需求——系统需要支持**灵活切换本地 LLM 与 DashScope（阿里云百炼平台）云端 API 调用**，这本质上是为 Agent 体系添加一个**多模型后端适配层**。结合原有架构，我们在以下维度进行深化设计。

---

# 补充：多模型后端可切换架构

### 1. 设计目标
- **模型后端可插拔**：OpenAI 兼容接口、DashScope、本地 vLLM/Ollama 部署的 Hermes 模型等均通过统一适配器接入。
- **配置级切换**：可在部署时（环境变量）、项目级（数据库配置）甚至技能级（YAML 模板）选择不同模型。
- **成本/性能平衡**：允许对关键技能使用高精度云端大模型，对摘要、翻译等非核心技能使用本地模型降本。
- **运行时健康检查**：自动检测后端可用性，支持故障切换（fallback）。

### 2. 架构中新增 `LLM Gateway` 层

```
┌──────────────────────────────────────────────┐
│                  LLM Gateway                  │
│  ┌────────────┐  ┌────────────┐  ┌─────────┐ │
│  │ OpenAI     │  │ DashScope  │  │ Local   │ │
│  │ Compatible │  │ Provider   │  │ Provider│ │
│  │ (GPT-4o,   │  │ (Qwen-Max, │  │ (Hermes │ │
│  │  Claude...) │  │  Llama...) │  │ via     │ │
│  │            │  │            │  │ vLLM)   │ │
│  └────────────┘  └────────────┘  └─────────┘ │
│          ▲              ▲              ▲      │
│          └──────────────┼──────────────┘      │
│                         │                     │
│              Model Router & Auth              │
│              (根据配置选择 Provider)           │
└─────────────────────────┬─────────────────────┘
                          │
              Agent / Skill 调用
```

该层提供统一的 `invoke(messages, tools)` 接口，内部根据 `model_id` 路由到对应 Provider。

---

```
flowchart LR
    A[用户输入] --> B["_extract_slots_from_message<br/>(gateway.invoke 无 model_ref)"]
    B --> C["LLM Gateway<br/>_parse_model_ref → provider=local"]
    C --> D["ChatOpenAI<br/>base_url=http://localhost:11434/v1<br/>model=qwen3-vl:8b<br/>(来自 config.py DEFAULT_MODEL_PROVIDER)"]
    
    A --> E["技能生成 (graph.py)"]
    E --> F["skill.model_override<br/>provider:local, model:qwen3-vl:8b"]
    F --> D

```

### 3. 配置体系设计

#### 3.1 部署环境变量（全局默认）
```env
# 默认模型后端类型: openai | dashscope | local
DEFAULT_MODEL_PROVIDER=dashscope
# DashScope 配置
DASHSCOPE_API_KEY=sk-xxx
DASHSCOPE_DEFAULT_MODEL=qwen-max
# 本地模型服务端点（OpenAI 兼容）
LOCAL_LLM_BASE_URL=http://vllm-service:8000/v1
LOCAL_LLM_API_KEY=not-needed
# OpenAI 兼容
OPENAI_API_KEY=sk-xxx
OPENAI_DEFAULT_MODEL=gpt-4o
```

#### 3.2 项目/用户级覆盖（存储在 PostgreSQL）
`project_config` 表增加 `model_preference` JSON 字段：
```json
{
  "provider": "dashscope",
  "model": "qwen-max",
  "fallback_provider": "local",
  "fallback_model": "hermes-3-llama-3.1"
}
```
前端项目管理页面提供图形化模型选择器，展示可用模型列表及其状态。

#### 3.3 技能级精度控制（YAML）
在技能定义中添加 `model` 字段，覆盖项目设置：
```yaml
skill_id: "architecture"
name: "技术架构生成"
model: 
  provider: "openai"
  model: "gpt-4o"
  temperature: 0.3
# 也可简洁写法
# model: "dashscope:qwen-max"
```
调度器读取该配置，调用 Gateway 时传入。

---

### 4. 各 Provider 适配实现要点

| Provider | 集成方式 | 函数调用支持 | 多模态支持 | 备注 |
|----------|---------|------------|-----------|------|
| **OpenAI 兼容** | LangChain ChatOpenAI | ✅ 原生 | ✅ | 覆盖 OpenAI、Azure、vLLM、Ollama 等 |
| **DashScope** | LangChain ChatDashScope (langchain-community) | ✅ qwen-max 等 | ✅ 通义千问视觉模型 | 需申请 API Key，导入 `dashscope` 包 |
| **本地 Hermes** | 通过 vLLM/Ollama 暴露 OpenAI 兼容接口 | ✅ 若模型支持工具调用 | 部分支持 | 需内置模型工具调用 prompt 模板 |

- 本地模型建议使用 **vLLM + Hermes-3-Llama-3.1**，启用了 OpenAI 兼容服务的 `--tool-call-parser hermes`。
- DashScope 的 ChatDashScope 已实现标准 LangChain BaseChatModel 接口，可直接替换。

---

### 5. 后端模块实现（Python）

```python
# llm_gateway.py
from langchain_core.language_models import BaseChatModel
from langchain_openai import ChatOpenAI
from langchain_community.chat_models import ChatDashScope
from typing import Optional, Dict, Any

class LLMGateway:
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self._cache = {}

    def get_model(self, model_ref: Optional[str] = None) -> BaseChatModel:
        """根据 model_ref 格式 'provider:model_name' 获取模型实例"""
        if model_ref and ":" in model_ref:
            provider, model_name = model_ref.split(":", 1)
        else:
            provider = self.config.get("provider", "dashscope")
            model_name = self.config.get("model", "qwen-max")

        cache_key = f"{provider}:{model_name}"
        if cache_key not in self._cache:
            if provider == "openai":
                self._cache[cache_key] = ChatOpenAI(
                    model=model_name,
                    temperature=0.2,
                    api_key=self.config["openai_api_key"],
                    base_url=self.config.get("openai_base_url")
                )
            elif provider == "dashscope":
                self._cache[cache_key] = ChatDashScope(
                    model=model_name,
                    temperature=0.2,
                    api_key=self.config["dashscope_api_key"],
                )
            elif provider == "local":
                # 本地服务用 OpenAI 兼容接口
                self._cache[cache_key] = ChatOpenAI(
                    model=model_name,
                    temperature=0.2,
                    api_key="not-needed",
                    base_url=self.config.get("local_base_url", "http://127.0.0.1:8000/v1")
                )
            else:
                raise ValueError(f"不支持的 provider: {provider}")
        return self._cache[cache_key]
```

**多模态调用**：对于图片输入，统一使用多模态模型（如 GPT-4o、Qwen-VL-Max），Gateway 根据 model 支持情况自动注入多部分消息内容。

---

### 6. 项目阶段调整

需在原有开发计划中，明确在第2阶段 **多智能体框架与核心技能** 中增加：

- **Week 3-4**：实现 LLM Gateway 抽象层，支持 OpenAI 兼容和 DashScope 两个 Provider，并完成单元测试。
- **Week 4-5**：实现模型配置管理 API（列出可用模型、切换项目默认模型），前端增加模型选择下拉框。
- **集成测试**：分别在 DashScope (qwen-max) 和本地 Hermes 模型上运行核心技能，验证生成质量与工具调用功能。
- **故障切换**：在 Gateway 中加入指数退避重试，如果一个 Provider 连续失败 3 次，自动切换到 fallback 配置。

**新里程碑 M2.1**：用户可在界面中切换云端/本地模型，Agent 在两种后端下均能完成 FDE 生成闭环。

---

## 快速开始

### 环境准备

- Python 3.10+
- Node.js 18+
- Docker & Docker Compose（可选，用于本地基础设施）

### 1. 克隆仓库

```bash
git clone <repository-url>
cd fde
```

### 2. 一键启动全部服务（Docker Desktop）

推荐使用 Docker Desktop 一键启动前后端及所有依赖：

```bash
make up
# 或手动
docker compose -f infra/docker-compose.yml up -d
```

这将启动：
- **PostgreSQL**（15432）
- **Redis**（16379）
- **MinIO**（19000 / 19001）
- **Backend**（18000）
- **Frontend**（15173）

首次启动后，只需配置 API Key 即可使用：

```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，填入你的 API Key（DASHSCOPE_API_KEY 或 OPENAI_API_KEY）
```

然后重启后端容器生效：

```bash
cd infra && docker compose restart backend
```

访问地址：
- 前端：http://localhost:15173
- API 文档：http://localhost:18000/docs

> **注意**：`make up` 会以前端 `dev` 模式运行（支持热重载），后端启用 `--reload`（代码变更自动重启）。

---

### 3. 仅启动基础设施（本地开发前后端）

如果你希望前后端在本地运行、只通过 Docker 启动数据库等基础设施：

```bash
docker compose -f infra/docker-compose.yml up -d postgres redis minio
```

然后配置环境变量：

```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，填入你的 API Key
```

必要变量：
- `SECRET_KEY`
- `DASHSCOPE_API_KEY` 或 `OPENAI_API_KEY`

> 数据库连接支持两种方式（密码含 `@` 等特殊字符时，推荐方式2）：
> - 方式1：`DATABASE_URL=postgresql+asyncpg://user:pass@host:port/db`（需手动 URL encode 密码）
> - 方式2：`DB_HOST=localhost`、`DB_PORT=15432`、`DB_USER=fde`、`DB_PASSWORD=fde123`、`DB_NAME=fde`（自动编码）

### 4. 启动后端（本地）

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

API 文档：http://localhost:8000/docs

### 5. 启动前端（本地）

```bash
cd frontend
npm install
npm run dev
```

前端地址：http://localhost:5173

---

## 用户手册

### 注册与登录

1. 访问前端首页，点击"注册"创建账户。
2. 使用邮箱/用户名登录，获取 JWT Token。
3. 支持三种角色：`admin`、`project_manager`、`user`。

### 创建项目

1. 登录后进入项目管理页，点击"新建项目"。
2. 填写项目名称、描述、行业等基本信息。
3. 可选配置模型偏好（云端/本地模型）。

### 需求澄清与文档生成

1. 进入项目详情页，切换到"聊天"标签。
2. 通过文本、语音或附件输入项目信息。
3. 系统自动检查信息完整度，不足时生成追问。
4. 信息收集完整后，点击"生成文档"。
5. 系统按技能 DAG 并行/串行生成各章节，实时推送进度。

### 文档编辑与导出

1. 切换到"预览"标签查看生成的 Markdown 文档。
2. 切换到"编辑"标签，按章节修改内容。
3. 点击"导出 PDF"，支持水印、封面自定义。

### 模板市场

- 内置模板：`standard_fde`（5 技能）、`full_fde`（7 技能）。
- Admin 可在"技能管理"中创建自定义技能模板。

---

## 测试

### 后端测试

```bash
cd backend
pytest tests/ -v
```

当前测试覆盖：
- **单元测试**：LLM Gateway、Skill Registry、Compile Engine、Clarify Engine、Input Processor、Cache、RBAC、RAG、Template Market。
- **集成测试**：API 端到端（Auth、Project CRUD、Skills、Document Generate/Export）。
- **总计**：121 passed，4 skipped（PDF 依赖 WeasyPrint）。

### 前端 E2E 测试

```bash
cd frontend
npx playwright install chromium
npm run test:e2e
```

---

## 部署

### Docker Compose（开发/测试）

适用于本地 Docker Desktop 一键全量部署。

```bash
make up       # 启动所有服务（前后端 + 数据库 + 缓存 + MinIO）
make logs     # 查看日志
make down     # 停止并移除服务
make shell-be # 进入后端容器
make shell-fe # 进入前端容器
```

环境变量通过 `infra/docker-compose.yml` 自动注入，敏感信息（API Key）通过 `.env` 文件或 Shell 环境变量传入。数据库和 Redis 密码中的 `@` 等特殊字符已做自动编码，无需手动处理 URL encode。

### Kubernetes（生产）

```bash
# 1. 创建命名空间和配置
kubectl apply -f infra/k8s/namespace.yaml
kubectl apply -f infra/k8s/configmap.yaml
kubectl apply -f infra/k8s/secret.yaml

# 2. 部署数据库和缓存
kubectl apply -f infra/k8s/postgres.yaml
kubectl apply -f infra/k8s/redis.yaml

# 3. 构建并推送镜像
docker build -t your-registry/fde-backend:latest backend/
docker build -t your-registry/fde-frontend:latest frontend/
docker push your-registry/fde-backend:latest
docker push your-registry/fde-frontend:latest

# 4. 部署应用层
kubectl apply -f infra/k8s/backend.yaml
kubectl apply -f infra/k8s/frontend.yaml

# 5. 配置 Ingress
kubectl apply -f infra/k8s/ingress.yaml
```

---

### 7. 安全与效率考量
- **API Key 安全**：所有密钥存储在环境变量或 Vault 中，数据库只存 provider+model 标识，不暴露密钥。
- **成本控制**：项目配置可设定 Token 预算上限，通过 Callback 统计消费并预警。
- **本地模型部署建议**：提供 Docker Compose 一键部署 vLLM + Hermes 模型，降低启动门槛。

---