# 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, 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 小时