企业官网建设流程全解析

Resume Matcher 面向 Agent 的文档导航体系：代码库结构、核心文档索引与任务驱动阅读路径

【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters & more, locally with 100+ LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher

Resume Matcher 是一个用于根据职位描述（JD）定制简历（Tailor Resume）、生成 PDF、求职信与拓展信息的 AI 应用，其代码库同时包含 FastAPI + Python 后端与 Next.js + React 前端。本文以仓库中的 Agent 文档入口 docs/agent/README.md 为核心骨架，系统梳理这套为 AI Agent 与开发者设计的文档导航体系：文档如何分类、代码库如何组织，以及面对"新任务、后端改动、前端改动、模板/PDF 改动"四类典型场景时应当沿哪条文档阅读路径切入。读完本文，你将获得一张可直接对照使用的"文档地图"，知道每个文档解决什么问题、对应哪些源码与测试，从而在 Resume Matcher 仓库中快速定位与安全改动。

一、为什么需要一个面向 Agent 的文档索引

大型代码库对人工开发者友好，但对 AI Agent（LLM 驱动的编码代理）并不总是如此：Agent 无法依赖 IDE 的目录树直觉，也不宜在每次任务开始时通读全部源码。Resume Matcher 在docs/agent/下维护了一套project-specific（项目专属）参考文档，其定位在 docs/agent/README.md 的开篇说明中非常明确：

• 该目录只收录与 Resume Matcher 本身绑定的文档；
• 通用、可复用的指南（Swiss 设计系统、Next.js 性能优化）被拆分为portable packs（可移植包），存放在 docs/portable/，可整体"搬出"仓库应用到任何项目；
• 每个文档用一句话标注 Purpose（用途），让 Agent 在动手前 30 秒内判断"该读哪篇"。

这种"索引页 + 单主题文档 + 可移植包"的三层结构，本身就是一种值得借鉴的 Agent 友好文档实践：入口文档只做导航、不重复内容，分类按任务语义（架构 / API / 设计 / 功能 / LLM 集成）而非源码目录一一对应。

二、文档体系总览：五类文档 + 可移植包

原索引将文档划分为以下类别，下表完整继承其分类与用途说明，并补充了对应的仓库相对路径：

核心文档（Core docs）

架构文档（Architecture）

API 文档

设计文档（Resume Matcher 专属设计）

设计系统本身（色彩、组件、反模式）属于可移植包，见 docs/portable/swiss-design-system/。

功能文档（Features）

LLM 集成

可移植包（存放于本目录之外）

值得注意的是，docs/agent/features/application-tracker.md（求职申请追踪看板）也存在于该目录中，与仓库中apps/backend/app/routers/applications.py及前端 apps/frontend/components/tracker/ 等组件对应，是功能文档体系中未被索引表收录但实际存在的一部分。

三、项目结构速览：backend 与 frontend 双应用

原索引给出了仓库的顶层骨架（docs/agent/README.md 的 "Project Structure" 一节），这里完整继承并补充真实目录细节：

apps/ ├── backend/ # FastAPI + Python │ ├── app/ │ │ ├── main.py # 入口（lifespan：TinyDB→SQLite 迁移、旧 key 折叠） │ │ ├── routers/ # API 端点（health/config/resumes/jobs/applications/enrichment） │ │ ├── services/ # 业务逻辑（parser/improver/cover_letter/refiner） │ │ ├── schemas/ # Pydantic 模型 │ │ ├── prompts/ # LLM 提示词模板 │ │ ├── config.py # Pydantic 设置 + 加密 API key 读写 │ │ ├── crypto.py # Fernet 加密/解密 │ │ ├── database.py # 异步 SQLAlchemy/SQLite 门面（返回纯 dict） │ │ ├── db_engine.py # SQLite 引擎/会话工厂 + PRAGMA │ │ ├── llm.py # LiteLLM 多提供商封装 │ │ └── pdf.py # Playwright PDF 渲染 │ └── data/ # 数据库存储 │ └── frontend/ # Next.js + React ├── app/ # 页面（(default)/、print/） ├── components/ # UI 组件（ui/builder/preview/resume/tailor/tracker） └── lib/ # 工具、API client、context

从 apps/backend/app/ 的实际源码看，后端不止上表列出的文件，还包含config_cache.py、db_engine.py、models.py、pdf.py以及scripts/migrate_tinydb_to_sqlite.py（一次性 TinyDB 导入器）；prompts/目录下除了templates.py还有enrichment.py、refinement.py、resume_wizard.py等按功能拆分的提示词文件。前端在components/下还新增了enrichment/、resume-wizard/、tailor/、tracker/、settings/等目录，说明该索引中的结构图是"稳定主干"，具体以各架构文档与源码为准。

四、任务驱动的文档阅读路径（How to Use）

原索引以四类典型任务给出了阅读顺序，这是整个文档体系最实用的部分，完整继承如下，并补充每步读取的目的：

1. 新任务（New tasks）：先读 scope-and-principles（了解哪些事能做、哪些禁止）→ quickstart（掌握安装/运行/测试命令）→ workflow（遵守提交与 PR 约定）。
2. 后端改动（Backend changes）：读 backend-architecture（模块与 API 全貌）→ front-end-apis（API 契约）→ llm-integration（LLM 调用方式）。
3. 前端改动（Frontend changes）：读 frontend-architecture → 可移植包 swiss-design-system → 可移植包 nextjs-performance → coding-standards。
4. 模板/PDF 改动（Template/PDF changes）：读 pdf-template-guide → template-system。

这套路径的设计哲学是"按任务聚类、按依赖排序"：后端改动链把架构（怎么组织）→ 契约（暴露什么）→ LLM 集成（AI 怎么调）串成一条完整链路；前端改动链则强制先读可移植设计系统与性能规范，再读编码规范，避免 UI 改动违反 Swiss 风格约束。

五、核心文档深入：Scope、Quickstart 与 Workflow

5.1 项目是什么（scope-and-principles）

docs/agent/scope-and-principles.md 是Agent 行为规则的权威来源（Canonical source），其技术栈描述与仓库源码高度一致：

• 后端：FastAPI + Python 3.13+，通过 LiteLLM 支持多提供商 LLM；
• 前端：Next.js + React 19（注意：该文档写 Next.js 16，而 frontend-architecture 写 Next.js 15，可移植包标题为 "Next.js 15 performance optimizations"，两处版本表述以 apps/frontend/package.json 实际依赖为准），采用 Swiss International Style 设计；
• 数据库：SQLite，通过异步 SQLAlchemy（aiosqlite）访问；
• PDF 生成：通过 Playwright 调用无头 Chromium。

文档还定义了不可妥协的规则（Non-Negotiable Rules）：

• 所有前端改动必须遵循 Swiss 设计系统；所有后端函数必须带类型提示（type hints）；
• 提交前必须运行npm run lint与npm run format（Prettier）；
• 错误处理：后端在服务端记录详细错误、向客户端返回通用消息；前端使用错误边界（Error Boundary）与用户友好的错误状态；
• 安全：绝不在客户端响应中暴露 API key 或敏感数据；共享资源初始化使用asyncio.Lock()；可变默认值必须使用copy.deepcopy()。

范围外（Out of Scope）事项明确列出：不得修改.github/workflows/、不得未经明确请求改动 CI/CD 配置、不得改动 Docker 构建行为、不得删除或禁用测试。

5.2 快速开始（quickstart）

docs/agent/quickstart.md 给出了可直接执行的完整命令序列：

前置要求：Node.js 22+、Python 3.13+、uv（Python 包管理器）。

安装（从仓库根目录执行）：

# 后端 cd apps/backend uv sync # 前端 cd apps/frontend npm install

开发（两个终端并行）：

# 终端 1：后端 cd apps/backend uv run uvicorn app.main:app --reload --port 8000 # 终端 2：前端 cd apps/frontend npm run dev

质量检查：

# 在 apps/frontend 下 npm run lint # 前端 lint npm run format # Prettier 格式化

后端测试：

cd apps/backend uv run pytest

环境变量初始化：

# 后端 cp apps/backend/.env.example apps/backend/.env # 前端 cp apps/frontend/.env.sample apps/frontend/.env.local

首次使用流程：

1. 打开 http://localhost:3000/settings
2. 选择 AI 提供商并输入 API key
3. 点击 "Test Connection"（对应POST /api/v1/config/llm-test端点）
4. 上传第一份简历

5.3 工作流约定（workflow）

docs/agent/workflow.md 定义了提交、PR 与测试规范：

• 提交信息：使用简洁的句子式主题（如Add custom funding link to FUNDING.yml）；若使用前缀，采用祈使句type: summary格式；用Fixes #123关联 issue；
• PR 要求：在描述中引用 issue；schema 或 prompt 改动必须显式标注，以便 reviewer 对下游 Agent 做冒烟测试；列出本地验证命令；UI/API 改动附截图；
• 测试约定：前端测试以*.test.tsx命名（仓库中 apps/frontend/tests/ 等真实遵循此约定）；后端测试用test_*.py命名，置于apps/backend/tests/，需使用匿名化的简历/职位 fixtures（见 apps/backend/tests/conftest.py）；
• Definition of Done：代码可编译、lint 通过、新功能有测试、UI 遵循 Swiss 包、schema/prompt 改动在 PR 中标注、UI 改动附截图、以 PR 中列出的命令完成本地验证。

六、架构文档：后端与前端的两份"地图"

6.1 后端架构（backend-architecture）

docs/agent/architecture/backend-architecture.md 是对 apps/backend/app/ 源码结构的权威说明，几个关键设计值得展开：

API 端点一览（均挂载于/api/v1前缀）：

数据库设计：SQLite 文件位于data/resume_matcher.db，由database.py（异步门面，返回纯 dict而非 ORM 行）、models.py（声明式Base+Resume/Job/Improvement/Application/ApiKey模型）与db_engine.py（引擎/会话工厂）协作。数据库有两个引擎、一个文件：模块级异步引擎服务文档表与applications表；同步引擎服务加密的api_keys表——因为该表在同步的 LLM 热路径（get_llm_config→load_config_file→resolve_api_key）上被读取，异步不必穿透到llm.py。源码 apps/backend/app/db_engine.py 中可见，两个引擎连接时都执行PRAGMA journal_mode=WAL、PRAGMA foreign_keys=ON、PRAGMA busy_timeout=5000。

关键不变量与迁移：

• 单一主简历（single-master）：通过asyncio.Lock（create_resume_atomic_master）+is_master上的部分唯一索引保证；
• 动态流水线字段（preview_hash/preview_hashes、job_keywords、company/role）存放在metadata_jsonJSON 列中，读取时扁平化；
• Application通过UniqueConstraint在(job_id, resume_id)上去重；
• 一次性导入器scripts/migrate_tinydb_to_sqlite.py：启动 lifespan 时若存在旧 TinyDB 文件data/database.json且 SQLite 为空，则导入行并重命名为database.json.migrated（可回滚工件），幂等——SQLite 已有数据则跳过；
• 加密 API key：crypto.py使用 Fernet 对称加解密，密钥位于data/.secret_key（自动生成、chmod 600、gitignored、原子写入），明文只存在于内存；migrate_legacy_keys()在启动时将旧明文 key 折叠进加密存储（幂等、不覆盖）。

LLM 集成（llm.py）：提供商为 OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter、Ollama。三个核心异步函数：

await check_llm_health(config) # 30s 超时 await complete(prompt, ...) # 120s 超时 await complete_json(prompt, ...) # 180s 超时，JSON 模式 + 重试

特性包括：API key 直接传参（避免os.environ竞态）；受支持提供商自动启用 JSON 模式；带更低温度的重试；括号匹配 JSON 提取。源码 apps/backend/app/llm.py 进一步证实了超时常量（30/120/180 秒）以及MAX_JSON_EXTRACTION_RECURSION = 10、MAX_JSON_CONTENT_SIZE = 1MB、DEFAULT_JSON_MAX_TOKENS = 8192等安全上限。

配置优先级：非机密配置（provider/model/base/features）存放在data/config.json，优先级高于环境变量；API key 绝不写入config.json，只加密存于 SQLiteapi_keys表，仅在读取时注入配置字典。

6.2 前端架构与工作流（frontend-architecture / frontend-workflow）

docs/agent/architecture/frontend-architecture.md 与 docs/agent/architecture/frontend-workflow.md 共同勾勒了前端全貌：

核心用户流：

Dashboard → Upload Master Resume → Tailor for Job → View/Edit → Download PDF

主要页面：

• /dashboard：主简历卡片 + 定制简历瓦片；状态机loading | pending | processing | ready | failed；窗口聚焦时自动刷新；用 localStorage 的master_resume_id记录主简历；
• /builder：左侧编辑器（表单 + 格式控制），右侧 WYSIWYG 分页预览；Resume / Cover Letter / Outreach 三个标签页；自动保存到 localStorage；数据优先级为 URL 参数 → Context → localStorage → 默认值；
• /tailor：JD 文本域（最少 50 字符）；流程为POST /jobs/upload→POST /resumes/improve→ 跳转/resumes/[new_id]；
• /settings：6 个提供商选择、API key 输入、系统状态（缓存，30 分钟刷新）；
• 打印路由/print/resumes/[id]、/print/cover-letter/[id]：由无头 Chrome 为 PDF 渲染，支持 template、pageSize、margins、spacing 查询参数。

状态管理：StatusCacheProvider缓存系统状态（30 分钟自动刷新 + 乐观计数更新）；LanguageProvider管理内容生成语言（en、es、zh、ja），对应仓库中的 apps/frontend/lib/context/language-context.tsx 与 apps/frontend/i18n/config.ts。

localStorage 键：master_resume_id（主简历 UUID）、resume_builder_draft（表单自动保存）、resume_builder_settings（模板偏好）。

分页系统：usePagination钩子计算分页断点，尊重.resume-item边界、防止孤立标题（orphaned headers）、150ms 防抖；分页规则为"区块可以跨页、单个条目保持完整、页面至少 50% 满才断页、标题永不孤立"。

关键 CSS 规则：PDF 生成依赖globals.css中的打印白名单：

@media print { body * { visibility: hidden !important; } .resume-print, .resume-print * { visibility: visible !important; } .cover-letter-print, .cover-letter-print * { visibility: visible !important; } }

七、API 文档：契约与请求/响应流程

docs/agent/apis/api-flow-maps.md 以流程图形式呈现了各端点的内部调用链，是排查问题的第一手材料。以下是几个最关键的流程（完整继承并适当注解）：

简历上传：

POST /api/v1/resumes/upload ├── 校验文件（PDF/DOCX，≤4MB） ├── parse_document() → Markdown ├── db.create_resume(status="processing") ├── parse_resume_to_json() → LLM │ ├── 成功：status="ready" │ └── 失败：status="failed" └── 返回 {resume_id}

简历定制（Improvement）：

POST /api/v1/resumes/improve ├── 从 DB 取简历 + 职位 ├── extract_job_keywords() → LLM ├── improve_resume() → LLM ├── [若启用] generate_cover_letter() → LLM ├── [若启用] generate_outreach_message() → LLM ├── [若启用] generate_interview_prep() → LLM ├── db.create_resume(improved) ├── db.create_improvement() └── 返回 {data, cover_letter, outreach_message, interview_prep}

PDF 生成：

GET /api/v1/resumes/{id}/pdf ├── 从 DB 取简历 ├── 构造 URL：{frontend}/print/resumes/{id}?{params} ├── Playwright 渲染（等待 .resume-print） └── 返回 PDF 字节

系统状态（部分失败仍 200）：

GET /api/v1/status # 每项检查隔离 → 200（部分/降级），绝不 500 ├── try: get_llm_config() │ ├── llm_configured = api_key 已设置 或 provider ∈ {ollama, openai_compatible} │ └── check_llm_health() → llm_healthy # 此处失败只降级该字段 ├── try: db.get_stats() # 失败 → 空统计，仍 200 └── 返回 {status, llm_configured, llm_healthy, has_master_resume, database_stats}

按提供商加密的 API key：

GET /api/v1/config/api-keys └── 返回 {providers: [{provider, configured, masked_key}]} # 始终掩码 POST /api/v1/config/api-keys ├── 对每个提供的 key：Fernet 加密 → upsert 进 SQLite api_keys 表 # 其他提供商 key 不受影响 └── 返回 {message, updated_providers} DELETE /api/v1/config/api-keys/{provider} # 删除单个提供商 key DELETE /api/v1/config/api-keys?confirm=... # 清空所有 key

求职追踪器（Application Tracker）：GET /applications按 7 个状态键分组返回（saved / applied / no_response / response / interview / accepted / rejected）；手动新增时若缺 company/role 会做一次 best-effort 的extract_job_keywords()LLM 调用；PATCH /applications/{id}时服务端会重排position。值得注意的自动创建逻辑：POST /resumes/improve/confirm（及旧版POST /resumes/improve）在持久化定制简历后会自动创建一个applied卡片——这是 best-effort 行为（追踪器失败不会破坏定制主流程），company/role 复用缓存的 keyword 提取结果，不产生额外 LLM 调用。

八、设计文档：模板系统与 PDF 渲染

8.1 模板系统（template-system）

docs/agent/design/template-system.md 完整列出了 7 套模板（仓库中对应文件见 apps/frontend/components/resume/）：

模板设置的权威定义在 apps/frontend/lib/types/template-settings.ts（TemplateSettings、DEFAULT_TEMPLATE_SETTINGS及 CSS 变量映射），当前形态包括：pageSize（A4/LETTER）、margins（各 5–25mm）、spacing（section/item/lineHeight 各 1–5 级）、fontSize（base/headerScale 1–5 级，headerFont/bodyFont 可选 serif/sans-serif/mono）、compactMode、showContactIcons、accentColor（blue/green/orange/red，适用于 modern、modern-two-column、vivid）。

自定义区块由AddSectionDialog支持三种类型：text（GenericTextForm，用于 Objective、statement）、itemList（GenericItemForm，用于 Publications、research）、stringList（GenericListForm，用于 Hobbies、interests）。间距变量通过 CSS 变量计算：--section-spacing: calc(4px * var(--spacing-level))、--item-spacing: calc(2px * var(--spacing-level))、--line-height: calc(1.4 + 0.1 * var(--line-height-level))。

新增模板的步骤（docs/agent/features/adding-resume-templates.md 有更详细说明）：

1. 创建components/resume/resume-{name}.tsx；
2. 实现TemplateProps接口；
3. 从components/resume/index.ts导出；
4. 加入FormattingControls选择器；
5. 生成预览缩略图。

8.2 PDF 渲染流水线（pdf-template-guide）

PDF 渲染使用 Playwright 无头 Chromium，核心函数为render_resume_pdf(url, page_size, selector=".resume-print")。关键约束是globals.css中的打印类白名单（见上文 6.2），这解释了为什么前端路由中单独存在print/目录：打印路由是专为 PDF 渲染设计的、去交互的页面形态。

九、LLM 集成细节：LiteLLM、JSON 模式与重试

docs/agent/llm-integration.md 提供了多提供商接入的完整说明，其中几个关键实现值得强调：

提供商矩阵：Ollama（本地、免费）、OpenAI（GPT-5 Nano、GPT-4o）、Anthropic（Claude Haiku 4.5）、Gemini（Gemini 3 Flash）、OpenRouter（多模型聚合）、DeepSeek（DeepSeek Chat）。

API key 传参方式：直接传给litellm.acompletion()的api_key参数，而非os.environ——后者在异步上下文中存在竞态风险：

# 正确 await litellm.acompletion( model=model, messages=messages, api_key=api_key # 直接传参 ) # 错误 —— 不要在异步代码中使用 os.environ os.environ["OPENAI_API_KEY"] = key # 竞态风险

JSON 模式：complete_json()对支持的提供商（OpenAI、Anthropic、Gemini、DeepSeek、主流 OpenRouter 模型）自动启用response_format={"type": "json_object"}；JSON 完成带 2 次自动重试且温度逐次降低（第 1 次 0.1、第 2 次 0.0）；_extract_json()使用健壮的括号匹配算法处理畸形响应、Markdown 代码块、边界情况，并带有递归保护（源码中MAX_JSON_EXTRACTION_RECURSION = 10）。

超时配置（源码 apps/backend/app/llm.py 与文档一致）：健康检查 30s、普通完成 120s、JSON 操作 180s。

提示词指南：新提示词加入 apps/backend/app/prompts/templates.py；使用{variable}单大括号替换；结构化输出必须给出示例 JSON schema；指令保持简洁（"Output ONLY the JSON object, no other text"）。

健康检查注意：Docker 健康检查必须使用/api/v1/health（而非/health），这一点在部署场景下容易被忽略。

十、可移植包：独立于项目的最佳实践沉淀

索引特别强调两个可移植包（存放于 docs/portable/）：

• swiss-design-system：完整 Swiss 风格设计系统（tokens、组件、布局、反模式），前端工作的必读材料；其中的 tokens.md 与 components.md 是触碰 UI 前的强制阅读项（见 scope-and-principles 规则第 1 条）；
• nextjs-performance：Next.js 性能优化实践（水合瀑布、包体积、Server Actions 安全、服务端性能），对 apps/frontend/ 的改造工作具有直接指导价值。

这种"把通用知识做成可移植包、项目专属知识留在 agent 目录"的划分，是文档体系的关键设计：它让跨项目复用的内容不被项目细节污染，也让 Agent 只需在项目内查找专属约定。

十一、总结：如何使用这份文档地图

对任何要在 Resume Matcher 仓库中工作的 Agent 或开发者，推荐的实践路径是：

1. 新任务起步：scope-and-principles→quickstart→workflow，先建立行为边界、工具命令与协作约定；
2. 定位问题域：根据任务类型选择架构（后端/前端）、API（契约/流程）、设计（模板/PDF）或功能文档，配合 apps/backend/tests/ 与 apps/frontend/tests/ 中的测试用例验证行为；
3. 深入实现：通过各文档给出的源码相对路径（如 apps/backend/app/llm.py、apps/backend/app/db_engine.py、apps/frontend/lib/types/template-settings.ts）直达底层实现；
4. 遵循交付标准：以workflow.md的 Definition of Done 为完成标准，涉及 schema/prompt 改动时在 PR 中显式标注。

这份索引的价值在于：它把"代码库知识"组织成了可检索、可排序、按任务导航的结构，既服务于人类开发者，也服务于需要高效定位代码的 AI Agent——这也是它被命名为 "Agent Documentation Index" 的原因所在。

【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters & more, locally with 100+ LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher