feat: add resume agent MVP

2026-07-20 14:48:41 +08:00
commit 48599bf55b
65 changed files with 10988 additions and 0 deletions
@@ -0,0 +1,89 @@
+# OfferPai Resume Agent MVP
+
+This directory is an isolated, runnable implementation of the zero-profile resume onboarding PRD. The production Vue and Python repositories were not present in the workspace, so the MVP keeps business integration behind replaceable boundaries instead of editing compiled artifacts.
+
+完整产品需求文档见 [`PRD.md`](PRD.md)。
+
+## What is implemented
+
+- One Vue conversation timeline containing text, structured input cards, status cards, and resume patches.
+- Explicit Python finite-state machine; no LangChain, LangGraph, RAG, or multi-agent runtime.
+- Privacy, phone source, name, and job type handled as typed component events rather than model input.
+- Open-ended first-experience description followed by targeted components for only the missing fields.
+- Exact first-anchor gates for education, work, internship, and project records.
+- SQLite session/timeline persistence, stale-component protection, phone masking, and idempotent resume creation.
+- Official OpenAI Python SDK integration for OpenAI-compatible gateways, with Pydantic-validated structured output and deterministic fallback services.
+- AI-polished experience text is proposed in a confirmation card and is written to the business resume only after the user accepts it.
+
+The model is deliberately limited to experience extraction and resume wording. The Python state machine still owns stages, components, gates, validation, and database writes. Structured profile PII is excluded from model payloads; phone-like text, email addresses, and labeled WeChat IDs in chat messages are redacted at the SDK boundary.
+
+## Run
+
+Backend:
+
+```powershell
+cd F:\offerpai_web\resume-agent-mvp\backend
+python -m pip install -r requirements.txt
+Copy-Item .env.example .env
+# Edit .env to add a real key, model, and compatible base URL when using the LLM.
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+Frontend:
+
+```powershell
+cd F:\offerpai_web\resume-agent-mvp\frontend
+Copy-Item .env.example .env
+npm install
+npm run dev
+```
+
+`VITE_DEMO_ACCOUNT_PHONE` simulates the phone supplied by production authentication. In production, remove this development input and inject the account phone server-side.
+
+Open `http://localhost:5173` for the UI, `http://localhost:8000/docs` for the API explorer, or `http://localhost:8000/health` for a backend health check.
+
+## LLM modes
+
+Copying `.env.example` with an empty `OPENAI_API_KEY` runs the deterministic rule services, so the complete workflow remains testable offline.
+
+To exercise the real OpenAI-compatible API, set these values in `backend/.env`:
+
+```dotenv
+RESUME_AGENT_LLM_PROVIDER=openai
+OPENAI_API_KEY=your-private-key
+OPENAI_BASE_URL=https://re.94xy.cn
+OPENAI_MODEL=your-gateway-model-id
+RESUME_AGENT_LLM_FALLBACK_TO_RULES=false
+```
+
+`RESUME_AGENT_LLM_FALLBACK_TO_RULES=false` is recommended for a live integration smoke test because an upstream error is then visible instead of being handled by the offline fallback. Set it back to `true` when graceful degradation is preferred.
+
+The base URL is passed directly to `openai.OpenAI(base_url=...)`. Do not append `/chat/completions`; append `/v1` only when the gateway documents that its SDK base URL requires it. If the gateway rejects `json_schema`, set `OPENAI_STRUCTURED_OUTPUT_MODE=json_object`.
+
+The concrete adapter is in [`backend/app/llm_services.py`](backend/app/llm_services.py), runtime configuration is in [`backend/app/settings.py`](backend/app/settings.py), and the full environment reference is documented in [`backend/README.md`](backend/README.md).
+
+## Verify
+
+```powershell
+cd F:\offerpai_web\resume-agent-mvp\backend
+pytest -q
+
+cd ..\frontend
+npm run typecheck
+npm run build
+```
+
+The automated tests use injected/fake clients and do not consume LLM quota. A real endpoint check requires valid gateway credentials and must be run separately with the live LLM settings above.
+
+After installing the SDK, run one real extraction request with:
+
+```powershell
+cd F:\offerpai_web\resume-agent-mvp\backend
+python scripts\smoke_llm.py
+```
+
+The script prints the base URL, model ID, and extracted fields, but never prints the API key.
+
+## Production migration
+
+Replace the local SQLite business-resume writer with an authenticated gateway to the real profile/resume API. The state machine must continue to own stages and gates; the model adapter may only extract or rewrite content and must never select UI stages or write business data directly.