langchain-learning-kit/docs/langchain-learning-kit/TASK_langchain-learning-kit.md

# TASK - LangChain Learning Kit 任务拆分

## 任务依赖图

```mermaid
graph TB
    T1[T1: 项目初始化]
    T2[T2: 数据库层实现]
    T3[T3: 配置和工具模块]
    T4[T4: ModelManager]
    T5[T5: AsyncJobManager]
    T6[T6: KnowledgeBaseManager]
    T7[T7: ConversationManager]
    T8[T8: AgentOrchestrator]
    T9[T9: Model API]
    T10[T10: KB API]
    T11[T11: Conversation API]
    T12[T12: Agent API]
    T13[T13: FastAPI 主程序]
    T14[T14: Docker 配置]
    T15[T15: 测试框架]
    T16[T16: 项目文档]

    T1 --> T2
    T1 --> T3
    T2 --> T4
    T3 --> T4
    T3 --> T5
    T4 --> T6
    T5 --> T6
    T4 --> T7
    T4 --> T8
    T6 --> T8
    T4 --> T9
    T6 --> T10
    T7 --> T11
    T8 --> T12
    T9 --> T13
    T10 --> T13
    T11 --> T13
    T12 --> T13
    T13 --> T14
    T13 --> T15
    T14 --> T16
    T15 --> T16
```

---

## T1: 项目初始化

### 输入契约
- **前置依赖**: 无
- **输入数据**: 设计文档 DESIGN_langchain-learning-kit.md
- **环境依赖**: Python 3.11+, Git

### 输出契约
- **输出数据**:
  - 完整的项目目录结构
  - requirements.txt 依赖文件
  - .env.example 环境变量模板
  - .gitignore 文件
  - README.md 基础文档
- **验收标准**:
  - [x] 目录结构符合设计文档
  - [x] requirements.txt 包含所有必要依赖
  - [x] .env.example 包含所有配置项
  - [x] .gitignore 排除敏感文件和缓存

### 实现约束
- **技术栈**: Python 3.11
- **质量要求**:
  - 依赖版本使用范围约束 (>=x.y,<x+1)
  - 环境变量命名遵循 UPPER_SNAKE_CASE

### 依赖关系
- **后置任务**: T2, T3
- **并行任务**: 无

---

## T2: 数据库层实现

### 输入契约
- **前置依赖**: T1 (项目结构已创建)
- **输入数据**: 数据库表设计 (DESIGN 文档第4节)
- **环境依赖**: MySQL 8.0+, Python 环境

### 输出契约
- **输出数据**:
  - `app/db/models.py`: SQLAlchemy 模型定义
  - `app/db/session.py`: 数据库会话管理
  - `app/db/alembic/`: Alembic 迁移配置
  - `app/db/alembic/versions/001_initial.py`: 初始迁移脚本
- **交付物**: 可执行的数据库迁移脚本
- **验收标准**:
  - [x] 所有表模型定义完整 (models, knowledge_bases, documents, conversations, messages, tool_calls)
  - [x] 外键关系正确
  - [x] 索引定义完整
  - [x] Alembic 迁移可执行 (`alembic upgrade head` 成功)
  - [x] 数据库连接池配置正确

### 实现约束
- **技术栈**: SQLAlchemy 2.0+, Alembic 1.12+, PyMySQL
- **接口规范**:
  - 使用 `declarative_base()` 定义模型
  - 会话管理使用 `sessionmaker` + 依赖注入
- **质量要求**:
  - 类型提示完整
  - 模型包含 `__repr__` 方法

### 依赖关系
- **前置任务**: T1
- **后置任务**: T4, T6, T7, T8
- **并行任务**: T3

---

## T3: 配置和工具模块

### 输入契约
- **前置依赖**: T1 (项目结构已创建)
- **输入数据**: 配置设计 (DESIGN 文档第7节)
- **环境依赖**: Python 环境

### 输出契约
- **输出数据**:
  - `app/config.py`: Pydantic Settings 配置类
  - `app/utils/logger.py`: 结构化日志配置
  - `app/utils/exceptions.py`: 自定义异常类
  - `app/utils/text_splitter.py`: 文本分块工具
  - `app/utils/faiss_helper.py`: FAISS 辅助函数
- **验收标准**:
  - [x] 配置类支持环境变量读取
  - [x] 日志输出为 JSON 格式
  - [x] 异常类包含 code, message, status_code
  - [x] 文本分块支持按字符数和句子分割
  - [x] FAISS 辅助函数支持保存/加载索引

### 实现约束
- **技术栈**: pydantic-settings, structlog, langchain-text-splitters
- **接口规范**:
  - Settings 继承 BaseSettings
  - 异常类继承 Exception
- **质量要求**:
  - 完整的文档字符串
  - 类型提示

### 依赖关系
- **前置任务**: T1
- **后置任务**: T4, T5, T6
- **并行任务**: T2

---

## T4: ModelManager 实现

### 输入契约
- **前置依赖**: T2 (数据库模型), T3 (配置和异常)
- **输入数据**: ModelManager 设计 (DESIGN 文档 3.1 节)
- **环境依赖**: OpenAI API Key (可选，用于测试)

### 输出契约
- **输出数据**:
  - `app/services/model_manager.py`: ModelManager 类实现
- **验收标准**:
  - [x] 实现 CRUD 方法 (create_model, get_model, list_models, update_model, delete_model)
  - [x] 实现 get_llm() 方法返回 LangChain LLM 实例
  - [x] 实现 get_embedding() 方法返回 Embeddings 实例
  - [x] 支持默认模型逻辑
  - [x] 配置中的 ${VAR} 变量替换功能
  - [x] 异常处理完善

### 实现约束
- **技术栈**: langchain-openai, SQLAlchemy
- **接口规范**:
```python
class ModelManager:
    def __init__(self, db_session: Session, settings: Settings)
    def create_model(name: str, type: str, config: Dict) -> Model
    def get_llm(name: Optional[str] = None) -> BaseLLM
    def get_embedding(name: Optional[str] = None) -> Embeddings
```
- **质量要求**:
  - 单元测试覆盖核心方法
  - 配置验证

### 依赖关系
- **前置任务**: T2, T3
- **后置任务**: T6, T7, T8, T9
- **并行任务**: T5

---

## T5: AsyncJobManager 实现

### 输入契约
- **前置依赖**: T3 (日志和异常)
- **输入数据**: AsyncJobManager 设计 (DESIGN 文档 3.5 节)
- **环境依赖**: Python asyncio

### 输出契约
- **输出数据**:
  - `app/services/job_manager.py`: AsyncJobManager 类实现
- **验收标准**:
  - [x] 支持异步任务提交 (submit_job)
  - [x] 任务状态查询 (get_job_status)
  - [x] 任务结果等待 (wait_for_job)
  - [x] 异常捕获和记录
  - [x] 任务 ID 生成 (UUID)

### 实现约束
- **技术栈**: Python asyncio, UUID
- **接口规范**:
```python
class AsyncJobManager:
    async def submit_job(job_fn: Callable, *args, **kwargs) -> str
    async def get_job_status(job_id: str) -> Dict
    async def wait_for_job(job_id: str, timeout: int) -> Any
```
- **质量要求**:
  - 线程安全
  - 超时处理

### 依赖关系
- **前置任务**: T3
- **后置任务**: T6
- **并行任务**: T4

---

## T6: KnowledgeBaseManager 实现

### 输入契约
- **前置依赖**: T2 (数据库模型), T3 (工具模块), T4 (ModelManager), T5 (JobManager)
- **输入数据**: KBManager 设计 (DESIGN 文档 3.2 节)
- **环境依赖**: FAISS, OpenAI Embeddings

### 输出契约
- **输出数据**:
  - `app/services/kb_manager.py`: KnowledgeBaseManager 类实现
- **验收标准**:
  - [x] 知识库 CRUD (create_kb, get_kb, list_kb, delete_kb)
  - [x] 文档摄取 (ingest_documents) - 支持异步
  - [x] 向量检索 (query_kb)
  - [x] FAISS 索引持久化 (save_index, load_index)
  - [x] 文档分块处理
  - [x] 批量嵌入计算
  - [x] 索引状态查询

### 实现约束
- **技术栈**: FAISS, langchain-community, langchain-openai
- **接口规范**:
```python
class KnowledgeBaseManager:
    def __init__(self, db_session, model_manager, job_manager, settings)
    def create_kb(name: str, description: str) -> KnowledgeBase
    async def ingest_documents(kb_id: int, docs: List[Dict], embedding_name: str) -> str
    def query_kb(kb_id: int, query: str, k: int, embedding_name: str) -> List[Document]
    def save_index(kb_id: int) -> bool
    def load_index(kb_id: int) -> FAISS
```
- **质量要求**:
  - FAISS 索引路径管理清晰
  - 错误处理完善
  - 单元测试和集成测试

### 依赖关系
- **前置任务**: T2, T3, T4, T5
- **后置任务**: T8, T10
- **并行任务**: T7

---

## T7: ConversationManager 实现

### 输入契约
- **前置依赖**: T2 (数据库模型), T4 (ModelManager)
- **输入数据**: ConvManager 设计 (DESIGN 文档 3.3 节)
- **环境依赖**: LangChain Memory

### 输出契约
- **输出数据**:
  - `app/services/conv_manager.py`: ConversationManager 类实现
- **验收标准**:
  - [x] 会话 CRUD (create_conversation, get_conversation)
  - [x] 消息管理 (add_message, get_messages)
  - [x] 聊天功能 (chat) - 支持 RAG
  - [x] 会话历史构建
  - [x] Prompt 模板管理

### 实现约束
- **技术栈**: LangChain, langchain-openai
- **接口规范**:
```python
class ConversationManager:
    def __init__(self, db_session, model_manager, kb_manager, settings)
    def create_conversation(user_id: int, title: str) -> Conversation
    async def chat(conv_id: int, user_input: str, kb_id: int, llm_name: str, use_rag: bool) -> Message
    def get_messages(conv_id: int, limit: int, offset: int) -> List[Message]
```
- **质量要求**:
  - RAG 上下文注入正确
  - 消息历史管理

### 依赖关系
- **前置任务**: T2, T4
- **后置任务**: T11
- **并行任务**: T6

---

## T8: AgentOrchestrator 实现

### 输入契约
- **前置依赖**: T2 (数据库模型), T4 (ModelManager), T6 (KBManager)
- **输入数据**: Agent 设计 (DESIGN 文档 3.4 节)
- **环境依赖**: LangChain Agents

### 输出契约
- **输出数据**:
  - `app/services/agent_orchestrator.py`: AgentOrchestrator 类实现
  - `app/tools/retriever.py`: Retriever Tool
  - `app/tools/calculator.py`: Calculator Tool
- **验收标准**:
  - [x] Agent 执行 (run_agent)
  - [x] 工具调用日志 (log_tool_call, get_logs)
  - [x] Retriever Tool 实现
  - [x] Calculator Tool 实现
  - [x] Agent 工具注册机制

### 实现约束
- **技术栈**: LangChain Agents, langchain-openai
- **接口规范**:
```python
class AgentOrchestrator:
    def __init__(self, db_session, model_manager, kb_manager, settings)
    async def run_agent(agent_name: str, input: str, llm_name: str, tools: List[str], kb_id: int) -> Dict
    def get_logs(run_id: str) -> List[ToolCall]

class RetrieverTool:
    name = "knowledge_base_search"
    def run(query: str, kb_id: int) -> str

class CalculatorTool:
    name = "calculator"
    def run(expression: str) -> str
```
- **质量要求**:
  - 工具调用审计完整
  - 异常处理

### 依赖关系
- **前置任务**: T2, T4, T6
- **后置任务**: T12
- **并行任务**: T7

---

## T9: Model API 实现

### 输入契约
- **前置依赖**: T4 (ModelManager)
- **输入数据**: API 设计 (DESIGN 文档 5.2 节)
- **环境依赖**: FastAPI

### 输出契约
- **输出数据**:
  - `app/api/v1/models.py`: Model API 路由
- **验收标准**:
  - [x] POST /api/v1/models (创建模型)
  - [x] GET /api/v1/models (列出模型)
  - [x] GET /api/v1/models/{id} (获取模型)
  - [x] PUT /api/v1/models/{id} (更新模型)
  - [x] DELETE /api/v1/models/{id} (删除模型)
  - [x] Pydantic 请求/响应模型
  - [x] 统一响应格式

### 实现约束
- **技术栈**: FastAPI, Pydantic
- **接口规范**: RESTful API
- **质量要求**:
  - 参数验证
  - 错误处理
  - OpenAPI 文档

### 依赖关系
- **前置任务**: T4
- **后置任务**: T13
- **并行任务**: T10, T11, T12

---

## T10: Knowledge Base API 实现

### 输入契约
- **前置依赖**: T6 (KBManager)
- **输入数据**: API 设计 (DESIGN 文档 5.2 节)
- **环境依赖**: FastAPI

### 输出契约
- **输出数据**:
  - `app/api/v1/kb.py`: KB API 路由
- **验收标准**:
  - [x] POST /api/v1/kb (创建知识库)
  - [x] GET /api/v1/kb (列出知识库)
  - [x] POST /api/v1/kb/{kb_id}/ingest (文档摄取)
  - [x] POST /api/v1/kb/{kb_id}/query (向量检索)
  - [x] GET /api/v1/kb/{kb_id}/status (索引状态)
  - [x] 文件上传支持 (txt)
  - [x] 异步任务响应

### 实现约束
- **技术栈**: FastAPI, UploadFile
- **接口规范**: RESTful API
- **质量要求**:
  - 文件大小限制
  - 异步处理
  - 进度查询

### 依赖关系
- **前置任务**: T6
- **后置任务**: T13
- **并行任务**: T9, T11, T12

---

## T11: Conversation API 实现

### 输入契约
- **前置依赖**: T7 (ConvManager)
- **输入数据**: API 设计 (DESIGN 文档 5.2 节)
- **环境依赖**: FastAPI

### 输出契约
- **输出数据**:
  - `app/api/v1/conv.py`: Conversation API 路由
- **验收标准**:
  - [x] POST /api/v1/conversations (创建会话)
  - [x] GET /api/v1/conversations/{id} (获取会话)
  - [x] POST /api/v1/conversations/{id}/messages (发送消息)
  - [x] GET /api/v1/conversations/{id}/messages (消息历史)
  - [x] 分页支持

### 实现约束
- **技术栈**: FastAPI, Pydantic
- **接口规范**: RESTful API
- **质量要求**:
  - 流式响应 (可选)
  - 分页查询

### 依赖关系
- **前置任务**: T7
- **后置任务**: T13
- **并行任务**: T9, T10, T12

---

## T12: Agent API 实现

### 输入契约
- **前置依赖**: T8 (AgentOrchestrator)
- **输入数据**: API 设计 (DESIGN 文档 5.2 节)
- **环境依赖**: FastAPI

### 输出契约
- **输出数据**:
  - `app/api/v1/agent.py`: Agent API 路由
- **验收标准**:
  - [x] POST /api/v1/agent/run (执行 Agent)
  - [x] GET /api/v1/agent/logs/{run_id} (获取日志)
  - [x] 工具选择参数

### 实现约束
- **技术栈**: FastAPI, Pydantic
- **接口规范**: RESTful API
- **质量要求**:
  - 执行日志详细
  - 超时处理

### 依赖关系
- **前置任务**: T8
- **后置任务**: T13
- **并行任务**: T9, T10, T11

---

## T13: FastAPI 主程序实现

### 输入契约
- **前置依赖**: T9, T10, T11, T12 (所有 API 路由)
- **输入数据**: 架构设计
- **环境依赖**: FastAPI

### 输出契约
- **输出数据**:
  - `app/main.py`: FastAPI 应用入口
  - `app/api/v1/__init__.py`: 路由聚合
- **验收标准**:
  - [x] FastAPI 应用初始化
  - [x] 所有路由注册
  - [x] 全局异常处理器
  - [x] CORS 中间件
  - [x] 健康检查端点
  - [x] OpenAPI 文档配置
  - [x] 应用可启动 (uvicorn)

### 实现约束
- **技术栈**: FastAPI, uvicorn
- **接口规范**:
  - API 前缀 `/api/v1`
  - 自动生成 OpenAPI 文档
- **质量要求**:
  - 依赖注入配置
  - 中间件配置

### 依赖关系
- **前置任务**: T9, T10, T11, T12
- **后置任务**: T14, T15
- **并行任务**: 无

---

## T14: Docker 配置实现

### 输入契约
- **前置依赖**: T13 (应用可运行)
- **输入数据**: 部署设计 (DESIGN 文档第10节)
- **环境依赖**: Docker

### 输出契约
- **输出数据**:
  - `docker/Dockerfile`: 应用镜像定义
  - `docker/docker-compose.yml`: 服务编排
  - `.dockerignore`: 构建排除文件
- **验收标准**:
  - [x] Dockerfile 多阶段构建
  - [x] docker-compose 包含 MySQL 和 App 服务
  - [x] 数据卷挂载正确
  - [x] 环境变量传递
  - [x] 健康检查配置
  - [x] 容器可成功启动

### 实现约束
- **技术栈**: Docker, Docker Compose
- **质量要求**:
  - 镜像体积优化
  - 安全最佳实践

### 依赖关系
- **前置任务**: T13
- **后置任务**: T16
- **并行任务**: T15

---

## T15: 测试框架实现

### 输入契约
- **前置依赖**: T13 (应用完整)
- **输入数据**: 测试策略 (DESIGN 文档第9节)
- **环境依赖**: pytest

### 输出契约
- **输出数据**:
  - `tests/conftest.py`: pytest 配置和 fixture
  - `tests/unit/test_model_manager.py`: ModelManager 单元测试
  - `tests/unit/test_kb_manager.py`: KBManager 单元测试
  - `tests/integration/test_api_models.py`: Model API 集成测试
  - `tests/integration/test_api_kb.py`: KB API 集成测试
  - `pytest.ini`: pytest 配置文件
- **验收标准**:
  - [x] 测试数据库 fixture
  - [x] 核心服务单元测试
  - [x] API 集成测试
  - [x] 测试覆盖率 > 60%
  - [x] 所有测试通过

### 实现约束
- **技术栈**: pytest, httpx, pytest-asyncio
- **质量要求**:
  - 测试隔离
  - Mock 外部依赖

### 依赖关系
- **前置任务**: T13
- **后置任务**: T16
- **并行任务**: T14

---

## T16: 项目文档实现

### 输入契约
- **前置依赖**: T14, T15 (完整系统)
- **输入数据**: 所有实现代码
- **环境依赖**: Markdown

### 输出契约
- **输出数据**:
  - `README.md`: 项目介绍和快速开始
  - `docs/architecture.md`: 架构文档
  - `docs/runbook.md`: 运维手册
  - `docs/api.md`: API 使用指南
- **验收标准**:
  - [x] README 包含完整的安装和运行步骤
  - [x] 架构文档包含系统设计图
  - [x] Runbook 包含常见问题和解决方案
  - [x] API 文档包含所有端点的示例

### 实现约束
- **技术栈**: Markdown
- **质量要求**:
  - 文档清晰易懂
  - 代码示例可运行

### 依赖关系
- **前置任务**: T14, T15
- **后置任务**: 无
- **并行任务**: 无

---

## 任务执行顺序总结

### 第一批 (可并行):
- T1: 项目初始化

### 第二批 (可并行):
- T2: 数据库层
- T3: 配置和工具

### 第三批 (可并行):
- T4: ModelManager
- T5: AsyncJobManager

### 第四批 (可并行):
- T6: KnowledgeBaseManager
- T7: ConversationManager

### 第五批:
- T8: AgentOrchestrator

### 第六批 (可并行):
- T9: Model API
- T10: KB API
- T11: Conversation API
- T12: Agent API

### 第七批:
- T13: FastAPI 主程序

### 第八批 (可并行):
- T14: Docker 配置
- T15: 测试框架

### 第九批:
- T16: 项目文档

---

## 总体复杂度评估

| 任务 | 复杂度 | 预估时间 | 风险等级 |
|------|--------|----------|----------|
| T1   | 低     | 30分钟   | 低       |
| T2   | 中     | 1小时    | 低       |
| T3   | 中     | 1小时    | 低       |
| T4   | 中     | 1.5小时  | 中       |
| T5   | 低     | 45分钟   | 低       |
| T6   | 高     | 2小时    | 中       |
| T7   | 中     | 1.5小时  | 中       |
| T8   | 高     | 2小时    | 中       |
| T9   | 低     | 45分钟   | 低       |
| T10  | 中     | 1小时    | 低       |
| T11  | 低     | 45分钟   | 低       |
| T12  | 低     | 45分钟   | 低       |
| T13  | 低     | 30分钟   | 低       |
| T14  | 中     | 1小时    | 低       |
| T15  | 中     | 1.5小时  | 中       |
| T16  | 低     | 1小时    | 低       |

**总计**: 约 17 小时