CoverCraft AI by Ambuj Kumar Tripathi

---

🎯 工程理念

❌ “玩具 AI 生成器”的谬误

互联网上 99% 的求职信工具都只是简单的提示词封装，在技术招聘筛选时会让求职者立即出局：

• 捏造指标： 虚构量化成果（“使用 Docker 将收入提高了 43%”，但候选人只在技能栏中列出了 Docker）。
• 空话与谄媚： 塞入泛泛而谈、令人尴尬的吹捧（“我一直非常钦佩贵公司具有革命性、定义行业的协同效应”）。
• 缺乏公司背景： 无法实时了解近期的工程方向调整、当前技术栈或公司子公司。
• 隐藏的第三方陷阱： 无法发现招聘信息实际来自伪装成直接雇主的第三方招聘或薪资代理机构。

✅ CoverCraft 架构：可验证的证据图谱

CoverCraft 并非模板填充器，而是一个以证据为依据的职业工作空间和主张验证引擎，专为资深工程师和审慎的招聘团队设计。

Candidate Resume (PDF)          Job Description (JD)           Live Web (Tavily + Jina AI)
        │                               │                                 │
        ▼                               ▼                                 ▼
┌──────────────────┐           ┌──────────────────┐             ┌────────────────────┐
│ Deterministic    │           │ Deterministic    │             │ 8-Page Multi-Board │
│ Text & Evidence  │           │ Fallback Regex   │             │ Crawl & Markdown   │
│ Extraction Layer │           │ & Vendor Auditor │             │ Deep Extraction    │
└─────────┬────────┘           └────────┬─────────┘             └─────────┬──────────┘
          │                             │                                 │
          └─────────────────────────────┼─────────────────────────────────┘
                                        │
                                        ▼
                        ┌─────────────────────────────────┐
                        │   Human-in-the-Loop Gateway     │
                        │   (Source Approval & Selection) │
                        └───────────────┬─────────────────┘
                                        │
                                        ▼
                        ┌─────────────────────────────────┐
                        │   Evidence-Grounded Generator   │
                        │   • Strict Verbatim Anchors     │
                        │   • Evidence-Grounded Claim Validation │
                        │   • Citation Footnotes [1], [2] │
                        └───────────────┬─────────────────┘
                                        │
                                        ▼
                        ┌─────────────────────────────────┐
                        │   Interview-Defensible Output   │
                        │   (Every claim backed by facts) │
                        └─────────────────────────────────┘

---

⚡ 核心架构支柱

1. 多源实时情报与深度 Markdown 爬取

• Tavily 8 页权威爬取： 查询企业的实时在线信息，重点关注 careers、linkedin、naukri 和 ambitionbox。
• Jina AI Reader（r.jina.ai）深度抓取： 清除 HTML 杂项、弹窗和 Cookie 墙，返回干净、高保真的 Markdown，并在超时后采用指数退避回退机制。
• 三级域名分类器： 将接收到的情报分为公司官方信息、招聘门户与评价和外部工程新闻。

2. 确定性回退正则表达式与四层公司情报

当大模型 JSON 结构延迟或仅部分填充时，确定性正则表达式处理流程会直接从原始职位描述（JD）词元中提取真实信息：

• 📋 职位背景子标签页（默认）： 提取职位、工作模式（远程／混合／现场办公）、经验范围和薪资披露状态。
• ⚠️ 第三方／人力服务检测： 标记人力服务供应商、C2H（合同转雇用）和薪资代发中介，并直接从 JD 中提取原文引述。
• 🏢 公司身份子标签页： 验证企业属于直接雇主、服务供应商、GCC（全球能力中心）还是产品公司。缺失字段一律显示 "Not verified from available sources"。
• ⚡ 招聘信号子标签页： 提取技术重点、正在进行的计划和近期招聘激增情况，并附上引用 [1]、[2]。
• 🔗 来源覆盖范围子标签页： 显示完整 URL 引用和抓取状态。

3. 基于证据的生成、用户体验与声明验证策略

• 基于证据的综合生成器： 系统指令要求求职信中的每一项成就声明都必须直接对应候选人简历中经过验证的要点。
• 交互式行内证据标记与整洁的提交导出： 屏幕上的交互式徽标（[Resume Anchor] 和 [Source Citation]）允许候选人将鼠标悬停其上，查看准确的来源引述，并通过实时的 [Evidence Markers: ON/OFF] 开关控制标记显示。候选人点击 Copy to Clipboard 或 Download Markdown/PDF 时，系统会自动移除内部引用标签，为招聘人员提供 100% 整洁、可直接提交的求职信。
• 对抗式过度声明红队审查器（真实性审计关卡）： 将生成的文本与候选人简历中的动词进行比对，识别资历夸大（例如，简历写的是“协助团队推出 Kubernetes”，而草稿写的是“主导企业级迁移”）。引擎会自动将未经验证的动词弱化为符合真实基础证据的表述，并记录审计日志。
• 实时步骤进度追踪器与动态计时器： 事件驱动的四阶段执行追踪器（01. Competency Match → 02. MCP Company Research → 03. Human Approval → 04. Evidence Synthesis），配有实时计时器（00:04s）和活动工具指示器，让候选人清楚了解实时执行进度，避免困惑或误以为流程停滞。
• 人在回路（HITL）关卡： 在任何外部情报进入大模型生成提示词之前，用户都可以明确检查网页抓取来源、评估其可信度分数，并切换其启用／停用状态。

4. 原生 Model Context Protocol（MCP）集成（8 个生产级工具）

提示

🛡️ 经三大注册平台验证的 FastMCP 服务（Glama · Smithery · M8ven）：
CoverCraft 的 FastMCP 服务及其 8 个已注册工具已通过领先注册平台的独立审计与验证，获得 Glama A 级 - A、**M8ven 信任评分 89/100（B 级）**和 Smithery 已验证（8 个工具），并接受持续实时监控，且无安全漏洞。

• 包含一个使用 Python 3.11 编写的独立 Anthropic Model Context Protocol（MCP） 服务（mcp-server/）。
• 通过标准 Model Context Protocol stdio 传输和 Streamable HTTP SSE 传输提供 8 个已注册工具：
  1. company_research：通过 Tavily 实时搜索网络，并提供可追溯的来源引用。
  2. evidence_validator：根据源数据验证 Claim Ledger，并返回 VERIFIED / PARTIAL / UNSUPPORTED。
  3. jd_analyzer：将简历与职位描述进行有证据支持的匹配，并提供实际佐证依据。
  4. ats_readiness：对关键词覆盖率、格式完整性和长度进行确定性启发式审计。
  5. source_filter：按算法进行域名权威度分级、过滤噪声，并筛除过时新闻和陈旧技术（公司计划不超过 9 个月，工程技术栈不超过 18 个月，并添加 [Historical Context] 标签）。
  6. cover_letter_generator：基于证据进行综合，添加结构化行内引用标记，并确保绝不过度声称。
  7. github_proofer：实时验证候选人的 GitHub 项目集与提交历史（$0 免费版 PAT，每小时 5,000 次请求）。检查公开仓库，提取提交 SHA 和消息，并将简历中的技术声明直接关联到可验证的代码证据，绝不过度声称。
  8. huggingface_proofer：自主验证 GenAI 模型与权重（$0 免费版 HF Token，每小时 30,000 次请求）。检查候选人在 Hugging Face 上公开的模型、Spaces、数据集及汇总下载指标（例如，700+ 次模型下载、qLoRA 微调、GGUF 量化），并将 AI 相关声明与可验证的权重交叉核验。
• 支持双传输方式：通过 stdio_server 在本地与 Claude Desktop/Cursor 搭配运行，或使用 --transport=sse 部署为独立流式微服务。

5. 实时 GitHub 代码证明与提交审计工具（MCP 工具 #7）

• **可验证的公开代码证据：**通过官方 GitHub MCP 工具（mcp-server/tools/github_proofer.py）和 Next.js 路由 /api/github-verify，连接候选人的 GitHub 个人资料。
• **提交级哈希：**提取实时提交 SHA（例如 sha: 7f2a1b9）、提交信息、仓库描述和架构文件，以可验证的代码历史为技术声明提供依据。
• **零成本免费套餐：**使用具有只读公开范围的 GitHub Personal Access Token（PAT），每小时可发起 5,000 次请求，成本为 $0，且速率限制隔离可靠性达 100%。
• **对抗性夸大声明哨兵：**如果候选人声称使用某个框架，却没有公开仓库或提交记录作为证明，CoverCraft 会标记这一缺口，并提示申请者进行澄清，而不是捏造虚假的企业经验。

6. 自主 Hugging Face 权重与模型审计工具（MCP 工具 #8）

• **可验证的开源权重与模型：**通过官方 MCP 工具（mcp-server/tools/huggingface_proofer.py）和 Next.js 路由 /api/hf-verify，连接候选人的 Hugging Face 个人资料。
• **真实下载与社区证明：**审计真实的社区采用指标（例如，726+ 次模型下载、39 个社区点赞/星标），并将 GenAI 声明（微调、LoRA、QLoRA、GGUF 量化、Legal AI）与可验证的可下载权重交叉核对。
• **交互式 AI 演示依据（Gradio Spaces）：**检查候选人实时交互式 Gradio 空间（例如 ambuj-ai-chatbot、legal-india-chatbot），以数学方式验证实时模型部署和边缘推理能力。
• **零成本免费 API 套餐：**使用 Hugging Face 用户访问令牌（$0 免费套餐），每小时可处理 30,000 次请求，并提供 5 分钟的 stale-while-revalidate 缓存和高可用回退机制。
• **反夸大声明哨兵：**区分仅会向商业 API 输入提示词的候选人，以及能够微调、量化并发布真实权重、且获得社区关注的 AI 工程师。

7. 候选人隐私优先架构与双重自动提取引擎

• **PII 加固与电话号码移除：**已从 UI 和后端架构中彻底移除手机号码，以保护申请者隐私。
• 双重智能自动提取：
  • **简历导入自动填充（/api/parse-resume）：**通过正则表达式和 LLM 提取，从上传的 PDF 简历中自动提取候选人的姓名、邮箱、LinkedIn URL 和 GitHub 个人资料 URL，并预填生成器表单。
  • **职位描述自动检测（InputForm.jsx）：**用户粘贴职位描述后，自动检测目标职位和公司名称，无需重复手动输入。

8. 生产可观测性：Langfuse LLM 跟踪与 MongoDB Atlas

• **Langfuse LLM 可观测性与跟踪：**全面跟踪遥测数据，涵盖端到端生成延迟、提示词/补全 token 消耗、Gemini 模型参数，以及全部 8 项 MCP 工具操作中的 span 级子跟踪。
• **具备韧性的非阻塞执行：**可观测性 span 在受保护的异步 try/catch 块中执行；即使出现网络限制，生成也能无缝继续，不会增加用户延迟。
• **MongoDB Atlas 遥测：**记录匿名化的生成延迟、token 用量、语气选择和错误分布。

5. 生产可观测性与多阶段容器化

• **MongoDB Atlas 遥测：**记录匿名化的生成延迟、token 用量、语气选择和错误分布。
• **生产 Docker 架构：**Next.js 16 独立构建将 Docker 镜像大小从 1.2 GB 减至约 120 MB，并以非特权用户 nextjs:nodejs 运行，消除 root 权限漏洞。

---

🛠️ 完整技术栈

层级	技术 / 服务	用途
前端框架	Next.js 16.1.6 (App Router) + React 19	Server Components、流式 SSR、高性能 Hydration
样式与动效	Vanilla Tailwind CSS v4 + HSL 设计令牌	现代暗色模式、磨砂玻璃表面、触感弹簧微交互
语言模型	三级多提供商级联：主模型 gemini-3.5-flash-lite、第二级 gemini-3.1-flash-lite-preview、第三级 nvidia/nemotron-3-ultra-550b-a55b:free（OpenRouter）	熔断器、指数退避、零停机弹性
网页爬取	Tavily AI Search API（8 页爬取）	实时搜索门户网站与新闻，并按域名筛选
页面提取器	Jina AI Reader (r.jina.ai)	深度转换网页为 Markdown，并通过 Bearer 令牌进行身份验证
Agent 协议	Anthropic Model Context Protocol (MCP)	用于调用外部 LLM Agent 的 Python 3.11 stdio 服务（8 个工具）
代码验证	GitHub REST API 与 MCP Proofer	实时验证公开提交 SHA 和代码仓库依据（$0 免费层级）
模型与权重验证	Hugging Face Hub API 与 MCP Proofer	实时验证开源权重、GGUF/LoRA 量化版本和社区下载量（$0 免费层级）
LLM 可观测性	Langfuse Node SDK	全链路追踪延迟、令牌消耗和多 Agent 子跨度
身份验证	NextAuth.js v4（Google OAuth 2.0 Provider）	安全的会话管理与 OAuth 回调流程
数据库与遥测	MongoDB Atlas（Mongoose Driver）	持久化遥测架构、审计轨迹、使用情况跟踪
部署	Vercel Serverless Edge + Docker Standalone	冷启动耗时 0 秒、全球 CDN 缓存、容器可移植性

---

📐 端到端系统时序

sequenceDiagram
    autonumber
    actor Candidate as User / Recruiter
    participant Web as Next.js 16 Frontend
    participant API as Route Handlers (/api/*)
    participant Tavily as Tavily Search Engine
    participant Jina as Jina AI Reader
    participant GitHub as GitHub MCP Proofer
    participant Langfuse as Langfuse Observability
    participant LLM as Google Gemini 2.5 Flash Lite
    participant DB as MongoDB Atlas

    Candidate->>Web: Upload Resume (PDF) & Paste Job Description
    Web->>API: POST /api/parse-resume & /api/analyze
    API->>API: Auto-Extract Candidate Name, Email, LinkedIn & GitHub Handle
    API->>API: Auto-Detect Target Role & Company from JD
    API->>GitHub: GET /api/github-verify (MCP Tool #7 Commit Auditor)
    GitHub-->>API: Verified Public Repositories, Commit SHAs & Timestamps
    API->>LLM: Schema-Enforced Extraction (Skills & Match Matrix)
    LLM-->>API: Structured Match Matrix & Vendor Indicators
    API->>Langfuse: Log Trace & Child Spans (Latency, Tokens, Model)
    API-->>Web: Render Evidence Match, GitHub Code Proof, Hugging Face Proof & 4-Tier Job Context Tabs

    Candidate->>Web: Trigger Real-Time Research
    Web->>API: POST /api/research { company, role }
    API->>Tavily: Crawl 8 Authoritative URLs (Careers, News, Reviews)
    Tavily-->>API: Raw Search Results
    API->>Jina: Deep Scrape Top URLs to Clean Markdown
    Jina-->>API: High-Fidelity Content
    API-->>Web: Display HITL Source Cards (User Approves Sources)

    Candidate->>Web: Select Tone & Click "Generate Cover Letter"
    Web->>API: POST /api/generate { approvedSources, evidenceMap }
    API->>LLM: Evidence-Grounded Generation Prompt (Claim Validation)
    LLM-->>API: Streamed Verified Cover Letter + Citations
    API->>DB: Log Telemetry & Audit Record
    API-->>Web: Render Final Letter with Copy, Download & Interview Defense

---

📂 项目目录结构

career-workspace-ambujsystems/
├── web/                             # Next.js 16 Fullstack Application
│   ├── public/                      # Static assets & SVG icons
│   ├── src/
│   │   ├── app/
│   │   │   ├── api/
│   │   │   │   ├── analyze/         # Resume parsing & JD matching handler
│   │   │   │   ├── auth/            # NextAuth Google OAuth endpoints
│   │   │   │   ├── generate/        # Evidence-grounded generation pipeline
│   │   │   │   └── research/        # Tavily 8-page crawl + Jina Reader pipeline
│   │   │   ├── docs/                # Interactive Architectural Documentation
│   │   │   ├── generate/            # Main interactive workspace interface
│   │   │   ├── globals.css          # Design system tokens, tactile spring curves & glow utilities
│   │   │   ├── layout.js            # Root layout with NextAuth Provider
│   │   │   └── page.js              # High-conversion Obsidian Black landing page
│   │   ├── components/
│   │   │   ├── ResultsPanel.jsx     # 4-tier tabbed intel & vendor verification UI
│   │   │   ├── SourceCard.jsx       # Human-in-the-loop approved source cards
│   │   │   └── ...                  # Reusable UI component modules
│   │   ├── lib/
│   │   │   ├── gemini.js            # Resilient Google Gemini client with retry
│   │   │   └── mongodb.js           # Production connection-cached MongoDB client
│   │   └── prompts/                 # Strict system prompts & JSON schemas
│   ├── Dockerfile                   # Multi-stage standalone Next.js container (~120MB)
│   ├── next.config.mjs              # Standalone output configuration
│   └── package.json                 # Dependencies & build scripts
├── mcp-server/                      # Anthropic Model Context Protocol (MCP)
│   ├── server.py                    # Stdio protocol handler with analysis tools
│   ├── Dockerfile                   # Python 3.11-slim container definition
│   └── requirements.txt             # MCP protocol SDK & utilities
├── docker-compose.yml               # Multi-service local orchestrator
└── README.md                        # Production Engineering Specification

---

🚀 本地快速开始

前置条件

• Node.js：v20.x 或 v22.x
• Docker & Docker Compose（可选，用于容器化运行）
• API 密钥：Google Gemini API、Tavily Search API、Jina AI API、MongoDB Atlas URI

1. 克隆代码仓库

git clone https://github.com/Ambuj123-lab/career-workspace-ambujsystems.git
cd career-workspace-ambujsystems/web

2. 配置环境变量

在 web/ 文件夹中创建 .env.local（或从代码仓库根目录复制 .env.example）：

# --- Core AI & Grounding Search (Required) ---
GEMINI_API_KEY=your_gemini_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

# --- Authentication & Security (NextAuth.js) ---
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_random_32_character_secret_here

# --- Candidate Proofing & Verification (Optional) ---
GITHUB_TOKEN=your_github_token_here
HF_TOKEN=your_huggingface_token_here
JINA_API_KEY=your_jina_api_key_here

# --- LLM Provider Fallback & Telemetry (Optional) ---
OPENROUTER_API_KEY=your_openrouter_api_key_here
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/?appName=CoverCraft
MONGODB_DB_NAME=covercraft_db

凭据审计与透明度（M8ven 已验证）

凭据 / 变量	范围	要求	用途与审计说明
GEMINI_API_KEY	Server / LLM	必需	主要合成引擎（Google AI Studio Gemini 2.5 / Flash）
TAVILY_API_KEY	Server / Web Search	必需	实时网页依据与目标公司情报爬取
GOOGLE_CLIENT_SECRET	NextAuth OAuth	身份验证必需	用于候选人登录的 Google OAuth 2.0 客户端密钥
GOOGLE_CLIENT_ID	NextAuth OAuth	身份验证必需	Google OAuth 2.0 客户端 ID
NEXTAUTH_SECRET	Web Security	身份验证必需	用于 JWT 会话 Cookie 的加密签名密钥
GITHUB_TOKEN	MCP / API	可选	提高候选人公开 GitHub 代码仓库审计的速率限制
HF_TOKEN	MCP / API	可选	验证候选人的 Hugging Face ML 模型、Spaces 和数据集
JINA_API_KEY	Web Crawler	可选	目标公司落地页的 Markdown 解析器备用方案
OPENROUTER_API_KEY	LLM Fallback	可选	主 Gemini API 配额受限时的多模型提供商备用方案
MONGODB_URI	Telemetry / DB	可选	持久化遥测数据、生成审计日志和用户反馈

3. 安装依赖并启动

npm install
npm run dev

在浏览器中打开 http://localhost:3000。

---

🐳 Docker 生产环境部署

在本地构建并运行多阶段独立容器：

# Build multi-stage image (~120MB footprint)
docker build -t covercraft-web:latest ./web

# Run standalone container
docker run -p 3000:3000 --env-file ./web/.env.local covercraft-web:latest

或者通过 Docker Compose 部署 Next.js 应用和 Python MCP 服务：

docker compose up -d --build

---

🌐 生产部署与链接

资产	链接	状态
🚀 生产应用	career-workspace-ambujsystems.vercel.app
📖 交互式架构文档	career-workspace-ambujsystems.vercel.app/docs
💻 GitHub 仓库	Ambuj123-lab/career-workspace-ambujsystems
👤 工程师作品集	ambuj-ai-portfolio.vercel.app
📰 UptimeRobot 官方专题报道	社区专题文章

---

👨‍💻 架构师与作者

Ambuj 的其他旗舰工程项目：

• 🏛️ Agentic Financial Parser — 包含 WhatsApp 机器人和混合 RAG 的 11 节点 LangGraph StateGraph 金融流水线。
• 🛡️ Citizen Safety Awareness AI — 面向印度法律与公民保护的实时 PII 脱敏线性 RAG 助手。
• ⚖️ Constitution of India AI Expert — 稳健的 Qdrant + Jina AI 父子分块法律 RAG 系统。

---

📜 许可证

本项目为开源项目，采用 MIT License 许可。