Agentic Internship Coach

面向后端实习求职的智能管理系统 —— 从投递管理到 AI 岗位匹配，再到 RAG 学习助手和 Agent 自动规划。

架构

routes → services → repositories → models
  ↓         ↓           ↓            ↓
HTTP层    业务规则    数据访问     ORM模型

层	目录	职责
Routes	src/api/routes/	HTTP 端点，请求/响应处理
Services	src/services/	业务规则，校验，异常定义
Repositories	src/repositories/	数据库操作，查询封装
Models	src/models/	SQLAlchemy ORM 模型
Schemas	src/schemas/	Pydantic 请求/响应模型
AI	src/ai/	LLM Client + Prompt
Cache	src/cache/	Redis 缓存
RAG	src/rag/	关键词检索 + RAG 服务
Agent	src/agent/	工具注册 + ReAct 循环

快速开始

本地启动

pip install -r requirements.txt
alembic upgrade head
uvicorn src.main:app --reload --port 8000

访问 http://127.0.0.1:8000/docs 查看 Swagger 文档。

Docker 启动

docker compose up -d
curl http://localhost:8000/health

API 列表

所有接口前缀：/api/v1

Companies / Jobs / Applications / Resumes

模块	端点	特性
Companies	CRUD + 分页	名称唯一约束，有岗位时禁止删除
Jobs	CRUD + 按公司/技术栈筛选	同公司标题唯一，有投递时禁止删除
Applications	CRUD + 按岗位/状态筛选	7 状态流转，幂等，自动 applied_at
Resumes	CRUD + 分页	简历内容存储

AI 岗位匹配

方法	路径	说明
POST	/ai/jobs/{id}/match	AI 分析岗位-简历匹配度

每次调用记录 AiCallLog（模型、耗时、成功/失败）。结果缓存到 Redis（24h TTL），Redis 不可用时降级直接调 LLM。

Knowledge & RAG

方法	路径	说明
POST	/knowledge/documents	上传学习笔记
GET	/knowledge/documents	笔记列表（按 source_type 筛选）
GET	/knowledge/documents/{id}	笔记详情
DELETE	/knowledge/documents/{id}	删除笔记
POST	/rag/answer	关键词 RAG 问答（返回带来源的答案）

Study Tasks

方法	路径	说明
POST	/study-tasks	创建学习任务
GET	/study-tasks?status=&priority=	任务列表（双维度筛选）
GET	/study-tasks/{id}	任务详情
PATCH	/study-tasks/{id}/status	更新状态（done 自动设 completed_at）
DELETE	/study-tasks/{id}	删除任务

Agent

方法	路径	说明
POST	/agent/chat	ReAct Agent（自动调工具生成学习计划）

Agent 工具：get_job_requirements / get_resume_skills / search_learning_notes / create_study_task（受 create_tasks 开关控制）。

数据库迁移

alembic upgrade head       # 应用所有迁移
alembic downgrade -1       # 回退一个版本
alembic revision --autogenerate -m "描述"   # 生成新迁移

测试

pytest -v                                               # 运行测试
pytest -v --cov=src --cov-fail-under=80                 # 覆盖率
ruff check .                                            # 代码检查

技术栈

• 框架: FastAPI + Pydantic
• 数据库: SQLite + SQLAlchemy + Alembic
• 缓存: Redis（降级可用）
• LLM: OpenAI-compatible API（默认 DeepSeek）
• RAG: jieba 分词 + TF 关键词检索
• Agent: 手写 ReAct Loop + 工具白名单 + Pydantic 参数校验
• 测试: pytest + pytest-cov + monkeypatch (全部外部服务 mock)
• 代码质量: ruff
• 部署: Docker + docker-compose + GitHub Actions CI

技术亮点

• 分层架构: routes → services → repositories → models，每层可独立测试
• 数据库迁移: 7 个 Alembic 迁移，支持 upgrade/downgrade
• 状态机: Application 7 状态声明式转换表，幂等 200，自动时间戳
• 级联删除保护: 外键依赖存在时拒绝删除，返回 409
• AI 调用审计: 每次 LLM 调用记录 AiCallLog/AgentCallLog
• Redis 降级: 缓存不可用时自动回退直接调 LLM
• RAG 来源追踪: 每个回答附带检索到的文档来源和匹配分
• Agent 安全: 工具白名单 + Pydantic 参数校验 + 副作用开关 + 重复检测 + 迭代上限
• 测试覆盖: 73 条测试，90% 覆盖率，外部依赖全部 mock

当前范围

单用户本地 MVP，SQLite 数据库，不含认证/多租户/权限。

Phase 10-14（BM25+Milvus、LangChain 迁移、独立扩展项目）规划在技术文档中，不阻塞主线交付。