OfferCat

OfferCat 是一个以技术面试为业务场景的 Agent 质量治理系统，基于 Spring Boot 3 与 Spring AI Alibaba 构建。项目保留简历解析、面试预设、受控出题、作答收集、结构化报告和题库知识库导入等面试主链路，但核心竞争力不是“调用大模型生成题”，而是围绕 LLM 输出不稳定的问题，建设可控生成、质量评估、失败反思、审核注入和负反馈隔离的 Agent 工程闭环。

一句话定位：

面试业务是载体，Agent 治理是主线。

核心亮点

• 受控出题 Agent：题目生成基于简历事实、岗位要求、题库候选、历史已出题记录和能力画像；模型只生成候选内容，服务层负责结构化校验、证据绑定、去重修复、状态流转、落库和 SSE 推送。
• Trace 可观测：基于 AgentRun / AgentStep 记录规则注入、输出校验、修复提示和持久化等关键步骤，并在会话详情页回放 Agent 运行证据链，解释每次出题为什么发生、哪里被修复过。
• 简历事实与 RAG grounding：简历文件通过 MinIO 存储、Apache Tika 提取文本，并沉淀为 ResumeProfile / ResumeFact；出题时结合 Milvus 向量召回和 MySQL 结构化数据，降低无依据出题风险。
• 自适应追问：根据回答中的量化结果、根因分析、技术取舍和个人职责等信号更新 session 级能力画像，驱动后续问题围绕薄弱维度继续追问。
• Eval Lab 质量评估：使用 EvalRun / EvalItemResult 对出题质量、报告质量、Trace 健康度和上下文安全风险做规则化评估，支持 Prompt 与 Agent 输出的回归对比。
• AgentLesson 改进闭环：低分 Eval 样本反思成 PENDING AgentLesson，审核通过后才会变成 ACTIVE 并被注入后续 Prompt；如果后续持续负反馈，则自动进入 QUARANTINED，避免坏经验污染 Agent。
• Agent Lab 治理台：在 /app/evals 展示 EvalRun、失败项、经验规则状态、审核动作、正负反馈计数和隔离原因，让 Agent 迭代过程可观察、可复盘、可演示。
• 工程化治理：Flyway 管理 schema 迁移，Redis 维护会话心跳和运行状态，JWT + UserBoundary 保护用户边界，核心 Agent 治理链路有测试覆盖。

架构概览

flowchart LR
    U["User"] --> API["Spring Boot API"]
    API --> AUTH["JWT + UserBoundary"]
    API --> FILE["MinIO + Apache Tika"]
    FILE --> RESUME["ResumeProfile / ResumeFact"]
    RESUME --> RAG["Milvus Vector Recall"]
    API --> SESSION["InterviewSession State Machine"]
    SESSION --> QP["QuestionPlanAgent"]
    QP --> VALIDATE["Schema / Grounding / Dedup / Verification"]
    VALIDATE --> TRACE["AgentRun / AgentStep Trace"]
    TRACE --> DB["MySQL"]
    VALIDATE --> DB["MySQL"]
    VALIDATE --> SSE["SSE Progress"]
    API --> REPORT["ReportGenerationAgent"]
    DB --> EVAL["Eval Lab"]
    EVAL --> REFLECT["AgentReflection"]
    REFLECT --> LESSON["PENDING AgentLesson"]
    LESSON --> REVIEW["Review Gate"]
    REVIEW --> ACTIVE["ACTIVE-only Injection"]
    ACTIVE --> QP
    EVAL --> FEEDBACK["Feedback / Quarantine"]
    FEEDBACK --> LESSON

Loading

Agent 治理闭环

sequenceDiagram
    participant Eval as EvalRun
    participant Reflect as AgentReflectionService
    participant Lesson as AgentLesson
    participant Review as Review Gate
    participant QP as QuestionPlanAgent
    participant Feedback as AgentLessonFeedbackService

    Eval->>Reflect: failed EvalItemResult
    Reflect->>Lesson: create PENDING rule
    Review->>Lesson: activate / reject / archive
    Lesson->>QP: inject ACTIVE lessonHints only
    QP->>Feedback: record AgentLessonUsage
    Eval->>Feedback: apply score feedback
    Feedback->>Lesson: positive / negative count
    Feedback->>Lesson: quarantine repeated negative rules

Loading

这不是模型训练，也不是让 LLM 自动修改生产 Prompt。它是工程层面的可审核经验规则闭环：失败样本只能生成待审核规则，审核通过后才能受控注入，后续再通过 Eval 反馈决定保留、归档或隔离。

技术栈

• Backend: Spring Boot 3, Spring AI Alibaba, Spring Security, JPA, Flyway
• Storage: MySQL, Redis, Milvus, MinIO
• AI/RAG: LLM Chat API, Ollama Embedding, Vector Recall, Agent Tools, SSE
• Parsing: Apache Tika
• Frontend: React, Vite, TanStack Query
• Local Infra: Docker Compose

本地启动

前置依赖：

• Java 17
• Maven Wrapper 或 Maven
• Docker Desktop
• Node.js 与 npm，只有重建前端时需要
• OpenAI-compatible chat endpoint
• Ollama embedding model

启动本地依赖：

docker compose up -d

可选检查脚本：

.\scripts\check-local.ps1

运行后端：

.\mvnw.cmd spring-boot:run -Dspring-boot.run.profiles=local

重建前端静态资源：

cd frontend
npm install
npm run build

打开页面：

http://localhost:8080/app

本地端口：

• MySQL: localhost:3307
• Redis: localhost:6380
• MinIO API: localhost:9001
• MinIO Console: localhost:9002
• Milvus: localhost:19531
• Attu: localhost:3001

鉴权

本地 demo 登录：

POST /api/auth/dev-login
Content-Type: application/json

{
  "userId": 10001
}

后续请求携带：

Authorization: Bearer <token>

核心 API 流程

面试主链路：

1. 上传简历：POST /api/interview/resume-documents?userId=10001
2. 创建面试预设：POST /api/interview/presets
3. 创建面试会话：POST /api/interview/sessions
4. 监听出题 SSE：GET /api/interview/sessions/{id}/question-plan/stream?userId=10001
5. 保存作答草稿：POST /api/interview/sessions/{id}/answers/draft
6. 提交整场评估：POST /api/interview/sessions/{id}/evaluation/submit
7. 查看结构化报告：GET /api/interview/sessions/{id}/report?userId=10001

Agent 治理链路：

1. 运行 Session Review：POST /api/interview/evals/session-review
2. 查看 EvalRun：GET /api/interview/evals/runs?userId=10001
3. 反思失败项：POST /api/interview/evals/runs/{runId}/reflect?userId=10001
4. 查看待审核规则：GET /api/interview/evals/agent-lessons?userId=10001&status=PENDING
5. 激活规则：POST /api/interview/evals/agent-lessons/{lessonId}/activate
6. 拒绝规则：POST /api/interview/evals/agent-lessons/{lessonId}/reject
7. 归档规则：POST /api/interview/evals/agent-lessons/{lessonId}/archive
8. 对比两次 EvalRun：GET /api/interview/evals/runs/compare?userId=10001&baselineRunId=1&candidateRunId=2
9. 打开治理台：http://localhost:8080/app/evals

完整手动演示见 docs/demo-flow.md。

验证命令

后端编译。当前仓库验证记录使用系统 Maven；如果你的 Maven Wrapper 正常，也可以把 mvn 替换成 .\mvnw.cmd：

mvn -q -DskipTests compile

后端测试：

mvn -q test

Agent 治理重点测试：

mvn -q "-Dtest=EvalRunComparisonServiceTests,InterviewTracePersistenceServiceTests,AgentReflectionServiceTests,AgentLessonReviewServiceTests,AgentLessonRetrieverTests,AgentLessonFeedbackServiceTests,AgentVerificationServiceTests,InterviewPayloadBuilderTests" test

可选 demo seed 与 Flyway 集成验证，需要本地 MySQL Docker 已启动：

mvn -q clean "-Dtest=FlywayBaselineIntegrationTests" "-Doffercat.docker.mysql.it=true" test

前端构建：

cd frontend
npm run build

简历表达

\datedline{\textbf{OfferCat：面向技术面试场景的 Agent 质量治理系统}}{2026.03 -- 2026.05}

\textbf{项目介绍：} 基于 Spring Boot 3 与 Spring AI Alibaba 构建的 AI 技术面试 Agent 系统，以简历解析、受控出题、结构化报告为业务场景，重点实现 Agent 输出校验、Trace 回放、Eval 质量评估、Prompt 回归门禁、经验规则审核注入和负反馈隔离，提升大模型长链路任务的可控性、可观测性和可迭代性。

\begin{itemize}
    \item \textbf{受控出题 Agent：} 基于简历事实、岗位要求、题库候选、历史已出题记录和能力画像生成结构化问题；服务层负责格式校验、证据绑定、去重修复、状态流转、落库和 \textbf{SSE} 推送。
    \item \textbf{Agent 质量治理：} 建设 \textbf{AgentRun / AgentStep + EvalRun / EvalItemResult + AgentLesson} 闭环，对出题、报告、Trace 和上下文安全进行规则化评估；支持 baseline/candidate 回归对比，并通过 \textbf{ACTIVE-only} 注入、正负反馈统计和负反馈隔离控制规则生命周期。
    \item \textbf{上下文与状态治理：} 基于 \textbf{MinIO + Apache Tika} 完成简历解析，结合 \textbf{ResumeProfile / ResumeFact} 与 Milvus 向量召回提供可追溯上下文；使用 Redis 维护会话心跳和长任务运行态。
\end{itemize}

更多面试话术见 docs/offercat-resume-and-interview-pack.md，代码学习路径见 docs/agent-lab-learning-guide.md，简历亮点到代码证据的映射见 docs/offercat-agent-governance-evidence-map.md。

重要文件

• src/main/java/com/share/offercat/service/QuestionPlanJobService.java：出题任务编排、校验、修复、落库和 SSE 推送
• src/main/java/com/share/offercat/service/agent/InterviewPayloadBuilder.java：Prompt payload 与 grounding context 构建
• src/main/java/com/share/offercat/service/agent/verify/AgentVerificationService.java：Agent 输出校验
• src/main/java/com/share/offercat/service/eval/：Eval Lab 评估服务
• src/main/java/com/share/offercat/service/agent/reflection/AgentReflectionService.java：失败 Eval 反思
• src/main/java/com/share/offercat/service/agent/lesson/：AgentLesson 审核、检索、使用记录、反馈和隔离
• frontend/src/pages/EvalLabPage.tsx：Agent Lab 页面
• frontend/src/components/eval/AgentLessonPanel.tsx：经验规则治理面板
• src/main/resources/db/migration：Flyway 迁移
• docs/aegis/specs/2026-05-25-agent-governance-north-star.md：后续主线北极星

注意事项

• application.properties 包含默认本地配置，Docker Compose 开发优先使用 application-local.properties。
• OFFERCAT_JWT_SECRET 应在正式环境外部配置，仓库内 fallback 只用于本地 demo。
• Flyway 负责 schema 创建和迁移，Hibernate 使用 ddl-auto=validate。
• Agent 质量治理闭环是 rule-governed and auditable，不是模型微调，也不是自动训练。