digital-employee-platform/docs/plans/2026-05-05-digital-employee-plan.md

数字员工平台实施计划

日期：2026-05-05 依据设计文档：docs/plans/2026-05-05-digital-employee-design.md 状态：待批准

总览

MVP 共分 5 个批次，每批次 3 个任务，预计总工时 ~15 人天。

批次	范围	任务数
B1	项目脚手架 + 数据模型 + 租户管理	3
B2	数字员工配置 + LLM Provider 抽象层	3
B3	对话接口（SSE 流式）+ 对话历史	3
B4	RAG 知识库 + 文档处理	3
B5	集成测试 + 错误处理 + 启动脚本	3

---

批次 B1：项目脚手架 + 数据模型 + 租户管理

Task 1.1：初始化项目脚手架

• 修改目标：创建项目目录结构、Python 依赖配置、FastAPI 入口
• 涉及文件：
  • backend/pyproject.toml — 依赖声明
  • backend/app/__init__.py
  • backend/app/main.py — FastAPI app 工厂
  • backend/app/config.py — Settings（pydantic-settings）
  • backend/app/database.py — async SQLAlchemy 引擎 + session
  • backend/.env.example
  • backend/tests/conftest.py — pytest fixtures（async client + test DB）
• 验证方式：uv run uvicorn app.main:app --reload 启动无报错，/docs 可访问
• 完成判定：服务启动 + Swagger UI 可访问 + test DB fixture 可用

Task 1.2：创建 SQLAlchemy 数据模型

• 修改目标：定义全部核心 ORM 模型（Tenant, TenantConfig, DigitalEmployee, Conversation, Message, KnowledgeBase, Document）
• 涉及文件：
  • backend/app/models/__init__.py
  • backend/app/models/tenant.py — Tenant, TenantConfig
  • backend/app/models/employee.py — DigitalEmployee
  • backend/app/models/conversation.py — Conversation, Message
  • backend/app/models/knowledge.py — KnowledgeBase, Document
  • backend/app/database.py — 添加 Base.metadata.create_all 初始化逻辑
• 验证方式：启动时自动建表，sqlite 文件包含全部表
• 完成判定：sqlite3 test.db .tables 输出全部 7 张表

Task 1.3：租户管理 API（CRUD + LLM 配置）

• 修改目标：实现租户 CRUD 端点 + LLM 配置更新端点，含 AES-256 加密存储 API Key
• 涉及文件：
  • backend/app/schemas/tenant.py — Pydantic request/response schemas
  • backend/app/api/deps.py — DB session 依赖注入
  • backend/app/api/v1/__init__.py — v1 router
  • backend/app/api/v1/tenants.py — 5 个端点
  • backend/app/services/tenant_service.py — 业务逻辑 + 加密
  • backend/app/middleware/tenant.py — 租户上下文中间件（预留）
• 验证方式：
  • RED：test_tenants.py 先写失败测试（创建/读取/更新/删除/配置更新）
  • GREEN：实现端点让测试通过
• 完成判定：全部租户测试通过，API Key 写入后数据库为密文

---

批次 B2：数字员工配置 + LLM Provider 抽象层

Task 2.1：数字员工配置 API

• 修改目标：实现数字员工 CRUD 端点，支持关联知识库
• 涉及文件：
  • backend/app/schemas/employee.py
  • backend/app/api/v1/employees.py
  • backend/app/services/employee_service.py
  • backend/tests/test_employees.py
• 验证方式：TDD — RED/GREEN/REFACTOR
• 完成判定：全部员工测试通过，创建时可关联知识库 ID 列表

Task 2.2：LLM Provider 抽象层

• 修改目标：实现 BaseLLMProvider 接口 + OpenAIProvider + QwenProvider
• 涉及文件：
  • backend/app/providers/__init__.py
  • backend/app/providers/base.py — BaseLLMProvider ABC + LLMMessage/LLMResponse
  • backend/app/providers/openai_provider.py — chat / chat_stream / embed
  • backend/app/providers/qwen_provider.py — 兼容 OpenAI SDK 格式
  • backend/tests/test_providers.py
• 验证方式：TDD — mock LLM API 响应，验证接口一致性和 Provider 注册表路由
• 完成判定：两个 Provider 的 chat/chat_stream/embed 单测通过（mock 模式）

Task 2.3：Provider 集成到租户配置

• 修改目标：tenant_service 根据 tenant_config 动态实例化 Provider，API 端点可验证 Provider 可用性
• 涉及文件：
  • backend/app/services/tenant_service.py — 新增 get_provider_for_tenant()
  • backend/app/api/v1/tenants.py — 新增 POST /tenants/{id}/test-provider 端点
  • backend/tests/test_providers.py — 补充集成验证测试
• 验证方式：TDD — mock Provider 测试路由正确性
• 完成判定：test-provider 端点根据租户配置返回正确的 Provider 实例信息

---

批次 B3：对话接口（SSE 流式）+ 对话历史

Task 3.1：对话与消息数据模型 + API

• 修改目标：实现 Conversation / Message CRUD + 消息发送端点（非流式先实现）
• 涉及文件：
  • backend/app/schemas/conversation.py
  • backend/app/api/v1/conversations.py
  • backend/app/services/conversation_service.py
  • backend/tests/test_conversations.py
• 验证方式：TDD — 创建对话 / 发送消息 / 获取历史
• 完成判定：全部对话基础测试通过

Task 3.2：SSE 流式响应

• 修改目标：实现 SSE 事件流（message_start / token / sources / message_end / error），集成 Provider.chat_stream
• 涉及文件：
  • backend/app/api/v1/conversations.py — 改造 messages 端点为 SSE
  • backend/app/services/conversation_service.py — 流式处理 + 持久化
  • backend/tests/test_conversations.py — 补充 SSE 测试
• 验证方式：TDD — 用 TestClient 验证 SSE 事件格式；手动用 curl 验证流式输出
• 完成判定：SSE 事件格式正确，token 按序到达，message_end 含 token_count

Task 3.3：会话上下文管理

• 修改目标：实现 max_context_messages 窗口裁剪、system_prompt 注入、对话历史加载
• 涉及文件：
  • backend/app/services/conversation_service.py — 新增 build_messages()
  • backend/tests/test_conversations.py — 补充上下文窗口测试
• 验证方式：TDD — 验证消息超过 max_context_messages 时自动裁剪
• 完成判定：上下文窗口裁剪正确，system_prompt 始终在首位

---

批次 B4：RAG 知识库 + 文档处理

Task 4.1：知识库 CRUD + 文档上传 API

• 修改目标：实现知识库和文档的 CRUD 端点，含文件上传
• 涉及文件：
  • backend/app/schemas/knowledge.py
  • backend/app/api/v1/knowledge.py
  • backend/app/services/knowledge_service.py
  • backend/tests/test_knowledge.py
• 验证方式：TDD — 创建知识库 / 上传文档 / 列出 / 删除
• 完成判定：知识库 CRUD 测试通过，文件上传持久化到本地存储

Task 4.2：文档解析与分块

• 修改目标：实现 PDF/DOCX/TXT/MD 文件解析 → RecursiveCharacterTextSplitter 分块
• 涉及文件：
  • backend/app/services/knowledge_service.py — 新增解析与分块逻辑
  • backend/tests/test_knowledge.py — 补充文档解析测试（用小文件 fixture）
• 验证方式：TDD — 上传小 PDF/TXT，验证分块结果数量和内容
• 完成判定：4 种文件类型均能正确解析分块，chunk_size=500, overlap=50

Task 4.3：RAG Pipeline（嵌入 + 检索 + 注入）

• 修改目标：实现嵌入生成 → ChromaDB 存储 → 相似度检索 → 上下文注入对话
• 涉及文件：
  • backend/app/services/rag_service.py — RAG 全流程
  • backend/app/services/conversation_service.py — 集成 RAG 检索
  • backend/tests/test_knowledge.py — 补充 RAG 检索测试（mock embedding）
  • backend/tests/test_conversations.py — 补充 RAG 注入测试
• 验证方式：TDD — mock embedding，验证 ChromaDB 写入/检索/上下文注入逻辑
• 完成判定：上传文档后对话能检索到相关知识片段并注入 prompt

---

批次 B5：集成测试 + 错误处理 + 启动脚本

Task 5.1：端到端集成测试

• 修改目标：编写完整链路集成测试：创建租户 → 配置员工 → 上传知识库 → 对话
• 涉及文件：
  • backend/tests/test_integration.py
• 验证方式：运行集成测试（mock LLM Provider），验证全链路数据流正确
• 完成判定：集成测试全部通过

Task 5.2：统一错误处理 + 安全加固

• 修改目标：
  • 全局异常处理器（Provider 错误、数据库错误、校验错误）
  • 租户隔离校验（所有查询强制 tenant_id 过滤）
  • 输入限制（文件大小、消息长度、速率限制）
• 涉及文件：
  • backend/app/middleware/tenant.py — 租户隔离中间件实现
  • backend/app/main.py — 注册异常处理器
  • backend/app/api/deps.py — 租户上下文注入
  • backend/tests/test_tenants.py — 补充越权测试
• 验证方式：TDD — 验证租户 A 无法访问租户 B 资源、错误返回正确状态码
• 完成判定：安全测试通过，越权返回 403

Task 5.3：启动脚本 + README + .env.example

• 修改目标：提供一键启动脚本和开发文档
• 涉及文件：
  • backend/.env.example — 环境变量模板
  • scripts/dev.sh — 一键启动脚本
  • README.md — 项目说明与快速开始
• 验证方式：从零 pip install → 配置 .env → ./scripts/dev.sh 启动成功
• 完成判定：按 README 步骤能成功启动服务，Swagger UI 可访问

---

依赖关系

B1 ──→ B2 ──→ B3 ──→ B4 ──→ B5
        │              │
        └── Provider ──┘

• B2 依赖 B1（数据模型）
• B3 依赖 B2（需要 Provider 调用 LLM）
• B4 依赖 B2（需要 Provider 生成嵌入）
• B5 依赖 B1-B4（集成测试覆盖全部模块）

验证命令

# 单测
cd backend && uv run pytest tests/ -v

# 集成测试
cd backend && uv run pytest tests/test_integration.py -v

# Lint
cd backend && uv run ruff check app/ tests/

# Type check
cd backend && uv run mypy app/

# 启动开发服务
cd backend && uv run uvicorn app.main:app --reload --port 8000

风险与待确认项

风险	影响	缓解措施
ChromaDB 嵌入式版本并发性能有限	多租户同时上传文档可能阻塞	MVP 阶段文档上传串行处理，V1 迁移 pgvector
OpenAI/通义 API 不稳定	对话功能不可用	重试 + 降级提示
SSE 在测试中验证较复杂	测试覆盖可能不足	使用 TestClient 的 stream 模式 + 事件格式断言
SQLite 写并发锁	多并发写入可能超时	MVP 阶段 WAL 模式缓解，V1 迁移 PostgreSQL