航體系：代碼庫(kù)結(jié)構(gòu)、核心文檔索引與任務(wù)驅(qū)動(dòng)閱讀路徑)
Resume Matcher 面向 Agent 的文檔導(dǎo)航體系代碼庫(kù)結(jié)構(gòu)、核心文檔索引與任務(wù)驅(qū)動(dòng)閱讀路徑【免費(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-MatcherResume Matcher 是一個(gè)用于根據(jù)職位描述JD定制簡(jiǎn)歷Tailor Resume、生成 PDF、求職信與拓展信息的 AI 應(yīng)用其代碼庫(kù)同時(shí)包含 FastAPI Python 后端與 Next.js React 前端。本文以倉(cāng)庫(kù)中的 Agent 文檔入口 docs/agent/README.md 為核心骨架系統(tǒng)梳理這套為 AI Agent 與開發(fā)者設(shè)計(jì)的文檔導(dǎo)航體系文檔如何分類、代碼庫(kù)如何組織以及面對(duì)新任務(wù)、后端改動(dòng)、前端改動(dòng)、模板/PDF 改動(dòng)四類典型場(chǎng)景時(shí)應(yīng)當(dāng)沿哪條文檔閱讀路徑切入。讀完本文你將獲得一張可直接對(duì)照使用的文檔地圖知道每個(gè)文檔解決什么問題、對(duì)應(yīng)哪些源碼與測(cè)試從而在 Resume Matcher 倉(cāng)庫(kù)中快速定位與安全改動(dòng)。一、為什么需要一個(gè)面向 Agent 的文檔索引大型代碼庫(kù)對(duì)人工開發(fā)者友好但對(duì) AI AgentLLM 驅(qū)動(dòng)的編碼代理并不總是如此Agent 無法依賴 IDE 的目錄樹直覺也不宜在每次任務(wù)開始時(shí)通讀全部源碼。Resume Matcher 在docs/agent/下維護(hù)了一套project-specific項(xiàng)目專屬參考文檔其定位在 docs/agent/README.md 的開篇說明中非常明確該目錄只收錄與 Resume Matcher 本身綁定的文檔通用、可復(fù)用的指南Swiss 設(shè)計(jì)系統(tǒng)、Next.js 性能優(yōu)化被拆分為portable packs可移植包存放在 docs/portable/可整體搬出倉(cāng)庫(kù)應(yīng)用到任何項(xiàng)目每個(gè)文檔用一句話標(biāo)注 Purpose用途讓 Agent 在動(dòng)手前 30 秒內(nèi)判斷該讀哪篇。這種索引頁(yè) 單主題文檔 可移植包的三層結(jié)構(gòu)本身就是一種值得借鑒的 Agent 友好文檔實(shí)踐入口文檔只做導(dǎo)航、不重復(fù)內(nèi)容分類按任務(wù)語義架構(gòu) / API / 設(shè)計(jì) / 功能 / LLM 集成而非源碼目錄一一對(duì)應(yīng)。二、文檔體系總覽五類文檔 可移植包原索引將文檔劃分為以下類別下表完整繼承其分類與用途說明并補(bǔ)充了對(duì)應(yīng)的倉(cāng)庫(kù)相對(duì)路徑核心文檔Core docs文檔用途倉(cāng)庫(kù)路徑scope-and-principles規(guī)則、范圍內(nèi)/范圍外事項(xiàng)docs/agent/scope-and-principles.mdquickstart安裝、運(yùn)行、測(cè)試命令docs/agent/quickstart.mdworkflowGit、PR、測(cè)試約定docs/agent/workflow.mdcoding-standards前端/后端編碼規(guī)范docs/agent/coding-standards.md架構(gòu)文檔Architecture文檔用途倉(cāng)庫(kù)路徑backend-architecture后端模塊、API、服務(wù)docs/agent/architecture/backend-architecture.mdbackend-guide后端逐模塊導(dǎo)覽docs/agent/architecture/backend-guide.mdfrontend-architecture組件、頁(yè)面、狀態(tài)docs/agent/architecture/frontend-architecture.mdfrontend-workflow前端用戶流程docs/agent/architecture/frontend-workflow.mdprompt-workflow-designImprover 流水線設(shè)計(jì)已廢棄保留作歷史參考docs/agent/architecture/prompt-workflow-design.mdAPI 文檔文檔用途倉(cāng)庫(kù)路徑front-end-apisAPI 契約docs/agent/apis/front-end-apis.mdapi-flow-maps請(qǐng)求/響應(yīng)流程docs/agent/apis/api-flow-maps.mdbackend-requirements后端行為需求docs/agent/apis/backend-requirements.md設(shè)計(jì)文檔Resume Matcher 專屬設(shè)計(jì)文檔用途倉(cāng)庫(kù)路徑template-system簡(jiǎn)歷模板架構(gòu)docs/agent/design/template-system.mdpdf-template-guidePDF 渲染流水線docs/agent/design/pdf-template-guide.mdprint-pdf-design-spec打印/PDF 設(shè)計(jì)規(guī)范docs/agent/design/print-pdf-design-spec.mdresume-template-design-spec簡(jiǎn)歷模板設(shè)計(jì)規(guī)范docs/agent/design/resume-template-design-spec.mdtemplates/swiss-single-spec單欄 Swiss 模板規(guī)范docs/agent/design/templates/swiss-single-spec.mdtemplates/swiss-two-column-spec雙欄 Swiss 模板規(guī)范docs/agent/design/templates/swiss-two-column-spec.md設(shè)計(jì)系統(tǒng)本身色彩、組件、反模式屬于可移植包見 docs/portable/swiss-design-system/。功能文檔Features文檔用途倉(cāng)庫(kù)路徑custom-sections動(dòng)態(tài)自定義區(qū)塊docs/agent/features/custom-sections.mdresume-templates模板類型與控制項(xiàng)docs/agent/features/resume-templates.mdadding-resume-templates如何新增模板docs/agent/features/adding-resume-templates.mdenrichmentAI 信息補(bǔ)全流程docs/agent/features/enrichment.mdjd-match職位描述匹配docs/agent/features/jd-match.mdi18n國(guó)際化docs/agent/features/i18n.mdi18n-preparationi18n 搭建筆記docs/agent/features/i18n-preparation.mdLLM 集成文檔用途倉(cāng)庫(kù)路徑llm-integration通過 LiteLLM 的多提供商 AI 接入docs/agent/llm-integration.md可移植包存放于本目錄之外包用途倉(cāng)庫(kù)路徑swiss-design-system完整 Swiss 風(fēng)格設(shè)計(jì)系統(tǒng)前端工作的必讀材料docs/portable/swiss-design-system/README.mdnextjs-performanceNext.js 15 性能優(yōu)化前端工作的必讀材料docs/portable/nextjs-performance/README.md值得注意的是docs/agent/features/application-tracker.md求職申請(qǐng)追蹤看板也存在于該目錄中與倉(cāng)庫(kù)中apps/backend/app/routers/applications.py及前端 apps/frontend/components/tracker/ 等組件對(duì)應(yīng)是功能文檔體系中未被索引表收錄但實(shí)際存在的一部分。三、項(xiàng)目結(jié)構(gòu)速覽backend 與 frontend 雙應(yīng)用原索引給出了倉(cāng)庫(kù)的頂層骨架docs/agent/README.md 的 Project Structure 一節(jié)這里完整繼承并補(bǔ)充真實(shí)目錄細(xì)節(jié)apps/ ├── backend/ # FastAPI Python │ ├── app/ │ │ ├── main.py # 入口lifespanTinyDB→SQLite 遷移、舊 key 折疊 │ │ ├── routers/ # API 端點(diǎn)health/config/resumes/jobs/applications/enrichment │ │ ├── services/ # 業(yè)務(wù)邏輯parser/improver/cover_letter/refiner │ │ ├── schemas/ # Pydantic 模型 │ │ ├── prompts/ # LLM 提示詞模板 │ │ ├── config.py # Pydantic 設(shè)置 加密 API key 讀寫 │ │ ├── crypto.py # Fernet 加密/解密 │ │ ├── database.py # 異步 SQLAlchemy/SQLite 門面返回純 dict │ │ ├── db_engine.py # SQLite 引擎/會(huì)話工廠 PRAGMA │ │ ├── llm.py # LiteLLM 多提供商封裝 │ │ └── pdf.py # Playwright PDF 渲染 │ └── data/ # 數(shù)據(jù)庫(kù)存儲(chǔ) │ └── frontend/ # Next.js React ├── app/ # 頁(yè)面(default)/、print/ ├── components/ # UI 組件ui/builder/preview/resume/tailor/tracker └── lib/ # 工具、API client、context從 apps/backend/app/ 的實(shí)際源碼看后端不止上表列出的文件還包含config_cache.py、db_engine.py、models.py、pdf.py以及scripts/migrate_tinydb_to_sqlite.py一次性 TinyDB 導(dǎo)入器prompts/目錄下除了templates.py還有enrichment.py、refinement.py、resume_wizard.py等按功能拆分的提示詞文件。前端在components/下還新增了enrichment/、resume-wizard/、tailor/、tracker/、settings/等目錄說明該索引中的結(jié)構(gòu)圖是穩(wěn)定主干具體以各架構(gòu)文檔與源碼為準(zhǔn)。四、任務(wù)驅(qū)動(dòng)的文檔閱讀路徑How to Use原索引以四類典型任務(wù)給出了閱讀順序這是整個(gè)文檔體系最實(shí)用的部分完整繼承如下并補(bǔ)充每步讀取的目的新任務(wù)New tasks先讀 scope-and-principles了解哪些事能做、哪些禁止→ quickstart掌握安裝/運(yùn)行/測(cè)試命令→ workflow遵守提交與 PR 約定。后端改動(dòng)Backend changes讀 backend-architecture模塊與 API 全貌→ front-end-apisAPI 契約→ llm-integrationLLM 調(diào)用方式。前端改動(dòng)Frontend changes讀 frontend-architecture → 可移植包 swiss-design-system → 可移植包 nextjs-performance → coding-standards。模板/PDF 改動(dòng)Template/PDF changes讀 pdf-template-guide → template-system。這套路徑的設(shè)計(jì)哲學(xué)是按任務(wù)聚類、按依賴排序后端改動(dòng)鏈把架構(gòu)怎么組織→ 契約暴露什么→ LLM 集成AI 怎么調(diào)串成一條完整鏈路前端改動(dòng)鏈則強(qiáng)制先讀可移植設(shè)計(jì)系統(tǒng)與性能規(guī)范再讀編碼規(guī)范避免 UI 改動(dòng)違反 Swiss 風(fēng)格約束。五、核心文檔深入Scope、Quickstart 與 Workflow5.1 項(xiàng)目是什么scope-and-principlesdocs/agent/scope-and-principles.md 是Agent 行為規(guī)則的權(quán)威來源Canonical source其技術(shù)棧描述與倉(cāng)庫(kù)源碼高度一致后端FastAPI Python 3.13通過 LiteLLM 支持多提供商 LLM前端Next.js React 19注意該文檔寫 Next.js 16而 frontend-architecture 寫 Next.js 15可移植包標(biāo)題為 Next.js 15 performance optimizations兩處版本表述以 apps/frontend/package.json 實(shí)際依賴為準(zhǔn)采用 Swiss International Style 設(shè)計(jì)數(shù)據(jù)庫(kù)SQLite通過異步 SQLAlchemyaiosqlite訪問PDF 生成通過 Playwright 調(diào)用無頭 Chromium。文檔還定義了不可妥協(xié)的規(guī)則Non-Negotiable Rules所有前端改動(dòng)必須遵循 Swiss 設(shè)計(jì)系統(tǒng)所有后端函數(shù)必須帶類型提示type hints提交前必須運(yùn)行npm run lint與npm run formatPrettier錯(cuò)誤處理后端在服務(wù)端記錄詳細(xì)錯(cuò)誤、向客戶端返回通用消息前端使用錯(cuò)誤邊界Error Boundary與用戶友好的錯(cuò)誤狀態(tài)安全絕不在客戶端響應(yīng)中暴露 API key 或敏感數(shù)據(jù)共享資源初始化使用asyncio.Lock()可變默認(rèn)值必須使用copy.deepcopy()。范圍外Out of Scope事項(xiàng)明確列出不得修改.github/workflows/、不得未經(jīng)明確請(qǐng)求改動(dòng) CI/CD 配置、不得改動(dòng) Docker 構(gòu)建行為、不得刪除或禁用測(cè)試。5.2 快速開始quickstartdocs/agent/quickstart.md 給出了可直接執(zhí)行的完整命令序列前置要求Node.js 22、Python 3.13、uvPython 包管理器。安裝從倉(cāng)庫(kù)根目錄執(zhí)行# 后端 cd apps/backend uv sync # 前端 cd apps/frontend npm install開發(fā)兩個(gè)終端并行# 終端 1后端 cd apps/backend uv run uvicorn app.main:app --reload --port 8000 # 終端 2前端 cd apps/frontend npm run dev質(zhì)量檢查# 在 apps/frontend 下 npm run lint # 前端 lint npm run format # Prettier 格式化后端測(cè)試cd apps/backend uv run pytest環(huán)境變量初始化# 后端 cp apps/backend/.env.example apps/backend/.env # 前端 cp apps/frontend/.env.sample apps/frontend/.env.local首次使用流程打開 http://localhost:3000/settings選擇 AI 提供商并輸入 API key點(diǎn)擊 Test Connection對(duì)應(yīng)POST /api/v1/config/llm-test端點(diǎn)上傳第一份簡(jiǎn)歷5.3 工作流約定workflowdocs/agent/workflow.md 定義了提交、PR 與測(cè)試規(guī)范提交信息使用簡(jiǎn)潔的句子式主題如Add custom funding link to FUNDING.yml若使用前綴采用祈使句type: summary格式用Fixes #123關(guān)聯(lián) issuePR 要求在描述中引用 issueschema 或 prompt 改動(dòng)必須顯式標(biāo)注以便 reviewer 對(duì)下游 Agent 做冒煙測(cè)試列出本地驗(yàn)證命令UI/API 改動(dòng)附截圖測(cè)試約定前端測(cè)試以*.test.tsx命名倉(cāng)庫(kù)中 apps/frontend/tests/ 等真實(shí)遵循此約定后端測(cè)試用test_*.py命名置于apps/backend/tests/需使用匿名化的簡(jiǎn)歷/職位 fixtures見 apps/backend/tests/conftest.pyDefinition of Done代碼可編譯、lint 通過、新功能有測(cè)試、UI 遵循 Swiss 包、schema/prompt 改動(dòng)在 PR 中標(biāo)注、UI 改動(dòng)附截圖、以 PR 中列出的命令完成本地驗(yàn)證。六、架構(gòu)文檔后端與前端的兩份地圖6.1 后端架構(gòu)backend-architecturedocs/agent/architecture/backend-architecture.md 是對(duì) apps/backend/app/ 源碼結(jié)構(gòu)的權(quán)威說明幾個(gè)關(guān)鍵設(shè)計(jì)值得展開API 端點(diǎn)一覽均掛載于/api/v1前綴類別端點(diǎn)說明健康GET /health存活探針不調(diào)用 LLM狀態(tài)GET /status完整系統(tǒng)狀態(tài)LLM 探針 DB 統(tǒng)計(jì)各檢查隔離 → 部分失敗仍返回 200 與降級(jí)狀態(tài)配置GET/PUT /config/llm-api-keyLLM 配置不再持久化 key配置POST /config/llm-test測(cè)試連接配置GET/POST/DELETE /config/api-keys按提供商加密存儲(chǔ)的 API key簡(jiǎn)歷POST /resumes/upload、GET /resumes、GET /resumes/list、POST /resumes/improve、PATCH /resumes/{id}、GET /resumes/{id}/pdf、DELETE /resumes/{id}簡(jiǎn)歷全生命周期職位POST /jobs/upload、GET /jobs/{id}職位描述應(yīng)用GET/POST /applications、GET/PATCH/DELETE /applications/{id}、PATCH /applications/bulk、POST /applications/bulk-deleteKanban 追蹤器數(shù)據(jù)庫(kù)設(shè)計(jì)SQLite 文件位于data/resume_matcher.db由database.py異步門面返回純 dict而非 ORM 行、models.py聲明式BaseResume/Job/Improvement/Application/ApiKey模型與db_engine.py引擎/會(huì)話工廠協(xié)作。數(shù)據(jù)庫(kù)有兩個(gè)引擎、一個(gè)文件模塊級(jí)異步引擎服務(wù)文檔表與applications表同步引擎服務(wù)加密的api_keys表——因?yàn)樵摫碓谕降?LLM 熱路徑get_llm_config→load_config_file→resolve_api_key上被讀取異步不必穿透到llm.py。源碼 apps/backend/app/db_engine.py 中可見兩個(gè)引擎連接時(shí)都執(zhí)行PRAGMA journal_modeWAL、PRAGMA foreign_keysON、PRAGMA busy_timeout5000。關(guān)鍵不變量與遷移單一主簡(jiǎn)歷single-master通過asyncio.Lockcreate_resume_atomic_masteris_master上的部分唯一索引保證動(dòng)態(tài)流水線字段preview_hash/preview_hashes、job_keywords、company/role存放在metadata_jsonJSON 列中讀取時(shí)扁平化Application通過UniqueConstraint在(job_id, resume_id)上去重一次性導(dǎo)入器scripts/migrate_tinydb_to_sqlite.py啟動(dòng) lifespan 時(shí)若存在舊 TinyDB 文件data/database.json且 SQLite 為空則導(dǎo)入行并重命名為database.json.migrated可回滾工件冪等——SQLite 已有數(shù)據(jù)則跳過加密 API keycrypto.py使用 Fernet 對(duì)稱加解密密鑰位于data/.secret_key自動(dòng)生成、chmod 600、gitignored、原子寫入明文只存在于內(nèi)存migrate_legacy_keys()在啟動(dòng)時(shí)將舊明文 key 折疊進(jìn)加密存儲(chǔ)冪等、不覆蓋。LLM 集成llm.py提供商為 OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter、Ollama。三個(gè)核心異步函數(shù)await check_llm_health(config) # 30s 超時(shí) await complete(prompt, ...) # 120s 超時(shí) await complete_json(prompt, ...) # 180s 超時(shí)JSON 模式 重試特性包括API key 直接傳參避免os.environ競(jìng)態(tài)受支持提供商自動(dòng)啟用 JSON 模式帶更低溫度的重試?yán)ㄌ?hào)匹配 JSON 提取。源碼 apps/backend/app/llm.py 進(jìn)一步證實(shí)了超時(shí)常量30/120/180 秒以及MAX_JSON_EXTRACTION_RECURSION 10、MAX_JSON_CONTENT_SIZE 1MB、DEFAULT_JSON_MAX_TOKENS 8192等安全上限。配置優(yōu)先級(jí)非機(jī)密配置provider/model/base/features存放在data/config.json優(yōu)先級(jí)高于環(huán)境變量API key 絕不寫入config.json只加密存于 SQLiteapi_keys表僅在讀取時(shí)注入配置字典。6.2 前端架構(gòu)與工作流frontend-architecture / frontend-workflowdocs/agent/architecture/frontend-architecture.md 與 docs/agent/architecture/frontend-workflow.md 共同勾勒了前端全貌核心用戶流Dashboard → Upload Master Resume → Tailor for Job → View/Edit → Download PDF主要頁(yè)面/dashboard主簡(jiǎn)歷卡片 定制簡(jiǎn)歷瓦片狀態(tài)機(jī)loading | pending | processing | ready | failed窗口聚焦時(shí)自動(dòng)刷新用 localStorage 的master_resume_id記錄主簡(jiǎn)歷/builder左側(cè)編輯器表單 格式控制右側(cè) WYSIWYG 分頁(yè)預(yù)覽Resume / Cover Letter / Outreach 三個(gè)標(biāo)簽頁(yè)自動(dòng)保存到 localStorage數(shù)據(jù)優(yōu)先級(jí)為 URL 參數(shù) → Context → localStorage → 默認(rèn)值/tailorJD 文本域最少 50 字符流程為POST /jobs/upload→POST /resumes/improve→ 跳轉(zhuǎn)/resumes/[new_id]/settings6 個(gè)提供商選擇、API key 輸入、系統(tǒng)狀態(tài)緩存30 分鐘刷新打印路由/print/resumes/[id]、/print/cover-letter/[id]由無頭 Chrome 為 PDF 渲染支持 template、pageSize、margins、spacing 查詢參數(shù)。狀態(tài)管理StatusCacheProvider緩存系統(tǒng)狀態(tài)30 分鐘自動(dòng)刷新 樂觀計(jì)數(shù)更新LanguageProvider管理內(nèi)容生成語言en、es、zh、ja對(duì)應(yīng)倉(cāng)庫(kù)中的 apps/frontend/lib/context/language-context.tsx 與 apps/frontend/i18n/config.ts。localStorage 鍵master_resume_id主簡(jiǎn)歷 UUID、resume_builder_draft表單自動(dòng)保存、resume_builder_settings模板偏好。分頁(yè)系統(tǒng)usePagination鉤子計(jì)算分頁(yè)斷點(diǎn)尊重.resume-item邊界、防止孤立標(biāo)題orphaned headers、150ms 防抖分頁(yè)規(guī)則為區(qū)塊可以跨頁(yè)、單個(gè)條目保持完整、頁(yè)面至少 50% 滿才斷頁(yè)、標(biāo)題永不孤立。關(guān)鍵 CSS 規(guī)則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 文檔契約與請(qǐng)求/響應(yīng)流程docs/agent/apis/api-flow-maps.md 以流程圖形式呈現(xiàn)了各端點(diǎn)的內(nèi)部調(diào)用鏈?zhǔn)桥挪閱栴}的第一手材料。以下是幾個(gè)最關(guān)鍵的流程完整繼承并適當(dāng)注解簡(jiǎn)歷上傳POST /api/v1/resumes/upload ├── 校驗(yàn)文件PDF/DOCX≤4MB ├── parse_document() → Markdown ├── db.create_resume(statusprocessing) ├── parse_resume_to_json() → LLM │ ├── 成功statusready │ └── 失敗statusfailed └── 返回 {resume_id}簡(jiǎn)歷定制ImprovementPOST /api/v1/resumes/improve ├── 從 DB 取簡(jiǎn)歷 職位 ├── 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 取簡(jiǎn)歷 ├── 構(gòu)造 URL{frontend}/print/resumes/{id}?{params} ├── Playwright 渲染等待 .resume-print └── 返回 PDF 字節(jié)系統(tǒng)狀態(tài)部分失敗仍 200GET /api/v1/status # 每項(xiàng)檢查隔離 → 200部分/降級(jí)絕不 500 ├── try: get_llm_config() │ ├── llm_configured api_key 已設(shè)置 或 provider ∈ {ollama, openai_compatible} │ └── check_llm_health() → llm_healthy # 此處失敗只降級(jí)該字段 ├── try: db.get_stats() # 失敗 → 空統(tǒng)計(jì)仍 200 └── 返回 {status, llm_configured, llm_healthy, has_master_resume, database_stats}按提供商加密的 API keyGET /api/v1/config/api-keys └── 返回 {providers: [{provider, configured, masked_key}]} # 始終掩碼 POST /api/v1/config/api-keys ├── 對(duì)每個(gè)提供的 keyFernet 加密 → upsert 進(jìn) SQLite api_keys 表 # 其他提供商 key 不受影響 └── 返回 {message, updated_providers} DELETE /api/v1/config/api-keys/{provider} # 刪除單個(gè)提供商 key DELETE /api/v1/config/api-keys?confirm... # 清空所有 key求職追蹤器Application TrackerGET /applications按 7 個(gè)狀態(tài)鍵分組返回saved / applied / no_response / response / interview / accepted / rejected手動(dòng)新增時(shí)若缺 company/role 會(huì)做一次 best-effort 的extract_job_keywords()LLM 調(diào)用PATCH /applications/{id}時(shí)服務(wù)端會(huì)重排position。值得注意的自動(dòng)創(chuàng)建邏輯POST /resumes/improve/confirm及舊版POST /resumes/improve在持久化定制簡(jiǎn)歷后會(huì)自動(dòng)創(chuàng)建一個(gè)applied卡片——這是 best-effort 行為追蹤器失敗不會(huì)破壞定制主流程company/role 復(fù)用緩存的 keyword 提取結(jié)果不產(chǎn)生額外 LLM 調(diào)用。八、設(shè)計(jì)文檔模板系統(tǒng)與 PDF 渲染8.1 模板系統(tǒng)template-systemdocs/agent/design/template-system.md 完整列出了 7 套模板倉(cāng)庫(kù)中對(duì)應(yīng)文件見 apps/frontend/components/resume/模板布局適用場(chǎng)景swiss-single全寬縱向1–2 頁(yè)簡(jiǎn)歷swiss-two-column65% 主欄 35% 側(cè)欄內(nèi)容密集modern單欄 強(qiáng)調(diào)色標(biāo)題彩色單欄modern-two-column65% 主欄 35% 側(cè)欄 強(qiáng)調(diào)色彩色密集內(nèi)容latex單欄、襯線、規(guī)則線標(biāo)題經(jīng)典/學(xué)術(shù)簡(jiǎn)歷clean單欄、極簡(jiǎn)無襯線低調(diào)現(xiàn)代簡(jiǎn)歷vivid63% 主欄 37% 側(cè)欄 強(qiáng)調(diào)色Awesome-CV 風(fēng)格彩色簡(jiǎn)歷模板設(shè)置的權(quán)威定義在 apps/frontend/lib/types/template-settings.tsTemplateSettings、DEFAULT_TEMPLATE_SETTINGS及 CSS 變量映射當(dāng)前形態(tài)包括pageSizeA4/LETTER、margins各 5–25mm、spacingsection/item/lineHeight 各 1–5 級(jí)、fontSizebase/headerScale 1–5 級(jí)headerFont/bodyFont 可選 serif/sans-serif/mono、compactMode、showContactIcons、accentColorblue/green/orange/red適用于 modern、modern-two-column、vivid。自定義區(qū)塊由AddSectionDialog支持三種類型textGenericTextForm用于 Objective、statement、itemListGenericItemForm用于 Publications、research、stringListGenericListForm用于 Hobbies、interests。間距變量通過 CSS 變量計(jì)算--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 有更詳細(xì)說明創(chuàng)建components/resume/resume-{name}.tsx實(shí)現(xiàn)TemplateProps接口從components/resume/index.ts導(dǎo)出加入FormattingControls選擇器生成預(yù)覽縮略圖。8.2 PDF 渲染流水線pdf-template-guidePDF 渲染使用 Playwright 無頭 Chromium核心函數(shù)為render_resume_pdf(url, page_size, selector.resume-print)。關(guān)鍵約束是globals.css中的打印類白名單見上文 6.2這解釋了為什么前端路由中單獨(dú)存在print/目錄打印路由是專為 PDF 渲染設(shè)計(jì)的、去交互的頁(yè)面形態(tài)。九、LLM 集成細(xì)節(jié)LiteLLM、JSON 模式與重試docs/agent/llm-integration.md 提供了多提供商接入的完整說明其中幾個(gè)關(guān)鍵實(shí)現(xiàn)值得強(qiáng)調(diào)提供商矩陣Ollama本地、免費(fèi)、OpenAIGPT-5 Nano、GPT-4o、AnthropicClaude Haiku 4.5、GeminiGemini 3 Flash、OpenRouter多模型聚合、DeepSeekDeepSeek Chat。API key 傳參方式直接傳給litellm.acompletion()的api_key參數(shù)而非os.environ——后者在異步上下文中存在競(jìng)態(tài)風(fēng)險(xiǎn)# 正確 await litellm.acompletion( modelmodel, messagesmessages, api_keyapi_key # 直接傳參 ) # 錯(cuò)誤 —— 不要在異步代碼中使用 os.environ os.environ[OPENAI_API_KEY] key # 競(jìng)態(tài)風(fēng)險(xiǎn)JSON 模式complete_json()對(duì)支持的提供商OpenAI、Anthropic、Gemini、DeepSeek、主流 OpenRouter 模型自動(dòng)啟用response_format{type: json_object}JSON 完成帶 2 次自動(dòng)重試且溫度逐次降低第 1 次 0.1、第 2 次 0.0_extract_json()使用健壯的括號(hào)匹配算法處理畸形響應(yīng)、Markdown 代碼塊、邊界情況并帶有遞歸保護(hù)源碼中MAX_JSON_EXTRACTION_RECURSION 10。超時(shí)配置源碼 apps/backend/app/llm.py 與文檔一致健康檢查 30s、普通完成 120s、JSON 操作 180s。提示詞指南新提示詞加入 apps/backend/app/prompts/templates.py使用{variable}單大括號(hào)替換結(jié)構(gòu)化輸出必須給出示例 JSON schema指令保持簡(jiǎn)潔Output ONLY the JSON object, no other text。健康檢查注意Docker 健康檢查必須使用/api/v1/health而非/health這一點(diǎn)在部署場(chǎng)景下容易被忽略。十、可移植包獨(dú)立于項(xiàng)目的最佳實(shí)踐沉淀索引特別強(qiáng)調(diào)兩個(gè)可移植包存放于 docs/portable/swiss-design-system完整 Swiss 風(fēng)格設(shè)計(jì)系統(tǒng)tokens、組件、布局、反模式前端工作的必讀材料其中的 tokens.md 與 components.md 是觸碰 UI 前的強(qiáng)制閱讀項(xiàng)見 scope-and-principles 規(guī)則第 1 條nextjs-performanceNext.js 性能優(yōu)化實(shí)踐水合瀑布、包體積、Server Actions 安全、服務(wù)端性能對(duì) apps/frontend/ 的改造工作具有直接指導(dǎo)價(jià)值。這種把通用知識(shí)做成可移植包、項(xiàng)目專屬知識(shí)留在 agent 目錄的劃分是文檔體系的關(guān)鍵設(shè)計(jì)它讓跨項(xiàng)目復(fù)用的內(nèi)容不被項(xiàng)目細(xì)節(jié)污染也讓 Agent 只需在項(xiàng)目?jī)?nèi)查找專屬約定。十一、總結(jié)如何使用這份文檔地圖對(duì)任何要在 Resume Matcher 倉(cāng)庫(kù)中工作的 Agent 或開發(fā)者推薦的實(shí)踐路徑是新任務(wù)起步scope-and-principles→quickstart→workflow先建立行為邊界、工具命令與協(xié)作約定定位問題域根據(jù)任務(wù)類型選擇架構(gòu)后端/前端、API契約/流程、設(shè)計(jì)模板/PDF或功能文檔配合 apps/backend/tests/ 與 apps/frontend/tests/ 中的測(cè)試用例驗(yàn)證行為深入實(shí)現(xiàn)通過各文檔給出的源碼相對(duì)路徑如 apps/backend/app/llm.py、apps/backend/app/db_engine.py、apps/frontend/lib/types/template-settings.ts直達(dá)底層實(shí)現(xiàn)遵循交付標(biāo)準(zhǔn)以workflow.md的 Definition of Done 為完成標(biāo)準(zhǔn)涉及 schema/prompt 改動(dòng)時(shí)在 PR 中顯式標(biāo)注。這份索引的價(jià)值在于它把代碼庫(kù)知識(shí)組織成了可檢索、可排序、按任務(wù)導(dǎo)航的結(jié)構(gòu)既服務(wù)于人類開發(fā)者也服務(wù)于需要高效定位代碼的 AI Agent——這也是它被命名為 Agent Documentation Index 的原因所在。【免費(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Resume Matcher 面向 Agent 的文檔導(dǎo)航體系：代碼庫(kù)結(jié)構(gòu)、核心文檔索引與任務(wù)驅(qū)動(dòng)閱讀路徑
Resume Matcher 面向 Agent 的文檔導(dǎo)航體系代碼庫(kù)結(jié)構(gòu)、核心文檔索引與任務(wù)驅(qū)動(dòng)閱讀路徑【免費(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-MatcherResume Matcher 是一個(gè)用于根據(jù)職位描述JD定制簡(jiǎn)歷Tailor Resume、生成 PDF、求職信與拓展信息的 AI 應(yīng)用其代碼庫(kù)同時(shí)包含 FastAPI Python 后端與 Next.js React 前端。本文以倉(cāng)庫(kù)中的 Agent 文檔入口 docs/agent/README.md 為核心骨架系統(tǒng)梳理這套為 AI Agent 與開發(fā)者設(shè)計(jì)的文檔導(dǎo)航體系文檔如何分類、代碼庫(kù)如何組織以及面對(duì)新任務(wù)、后端改動(dòng)、前端改動(dòng)、模板/PDF 改動(dòng)四類典型場(chǎng)景時(shí)應(yīng)當(dāng)沿哪條文檔閱讀路徑切入。讀完本文你將獲得一張可直接對(duì)照使用的文檔地圖知道每個(gè)文檔解決什么問題、對(duì)應(yīng)哪些源碼與測(cè)試從而在 Resume Matcher 倉(cāng)庫(kù)中快速定位與安全改動(dòng)。一、為什么需要一個(gè)面向 Agent 的文檔索引大型代碼庫(kù)對(duì)人工開發(fā)者友好但對(duì) AI AgentLLM 驅(qū)動(dòng)的編碼代理并不總是如此Agent 無法依賴 IDE 的目錄樹直覺也不宜在每次任務(wù)開始時(shí)通讀全部源碼。Resume Matcher 在docs/agent/下維護(hù)了一套project-specific項(xiàng)目專屬參考文檔其定位在 docs/agent/README.md 的開篇說明中非常明確該目錄只收錄與 Resume Matcher 本身綁定的文檔通用、可復(fù)用的指南Swiss 設(shè)計(jì)系統(tǒng)、Next.js 性能優(yōu)化被拆分為portable packs可移植包存放在 docs/portable/可整體搬出倉(cāng)庫(kù)應(yīng)用到任何項(xiàng)目每個(gè)文檔用一句話標(biāo)注 Purpose用途讓 Agent 在動(dòng)手前 30 秒內(nèi)判斷該讀哪篇。這種索引頁(yè) 單主題文檔 可移植包的三層結(jié)構(gòu)本身就是一種值得借鑒的 Agent 友好文檔實(shí)踐入口文檔只做導(dǎo)航、不重復(fù)內(nèi)容分類按任務(wù)語義架構(gòu) / API / 設(shè)計(jì) / 功能 / LLM 集成而非源碼目錄一一對(duì)應(yīng)。二、文檔體系總覽五類文檔 可移植包原索引將文檔劃分為以下類別下表完整繼承其分類與用途說明并補(bǔ)充了對(duì)應(yīng)的倉(cāng)庫(kù)相對(duì)路徑核心文檔Core docs文檔用途倉(cāng)庫(kù)路徑scope-and-principles規(guī)則、范圍內(nèi)/范圍外事項(xiàng)docs/agent/scope-and-principles.mdquickstart安裝、運(yùn)行、測(cè)試命令docs/agent/quickstart.mdworkflowGit、PR、測(cè)試約定docs/agent/workflow.mdcoding-standards前端/后端編碼規(guī)范docs/agent/coding-standards.md架構(gòu)文檔Architecture文檔用途倉(cāng)庫(kù)路徑backend-architecture后端模塊、API、服務(wù)docs/agent/architecture/backend-architecture.mdbackend-guide后端逐模塊導(dǎo)覽docs/agent/architecture/backend-guide.mdfrontend-architecture組件、頁(yè)面、狀態(tài)docs/agent/architecture/frontend-architecture.mdfrontend-workflow前端用戶流程docs/agent/architecture/frontend-workflow.mdprompt-workflow-designImprover 流水線設(shè)計(jì)已廢棄保留作歷史參考docs/agent/architecture/prompt-workflow-design.mdAPI 文檔文檔用途倉(cāng)庫(kù)路徑front-end-apisAPI 契約docs/agent/apis/front-end-apis.mdapi-flow-maps請(qǐng)求/響應(yīng)流程docs/agent/apis/api-flow-maps.mdbackend-requirements后端行為需求docs/agent/apis/backend-requirements.md設(shè)計(jì)文檔Resume Matcher 專屬設(shè)計(jì)文檔用途倉(cāng)庫(kù)路徑template-system簡(jiǎn)歷模板架構(gòu)docs/agent/design/template-system.mdpdf-template-guidePDF 渲染流水線docs/agent/design/pdf-template-guide.mdprint-pdf-design-spec打印/PDF 設(shè)計(jì)規(guī)范docs/agent/design/print-pdf-design-spec.mdresume-template-design-spec簡(jiǎn)歷模板設(shè)計(jì)規(guī)范docs/agent/design/resume-template-design-spec.mdtemplates/swiss-single-spec單欄 Swiss 模板規(guī)范docs/agent/design/templates/swiss-single-spec.mdtemplates/swiss-two-column-spec雙欄 Swiss 模板規(guī)范docs/agent/design/templates/swiss-two-column-spec.md設(shè)計(jì)系統(tǒng)本身色彩、組件、反模式屬于可移植包見 docs/portable/swiss-design-system/。功能文檔Features文檔用途倉(cāng)庫(kù)路徑custom-sections動(dòng)態(tài)自定義區(qū)塊docs/agent/features/custom-sections.mdresume-templates模板類型與控制項(xiàng)docs/agent/features/resume-templates.mdadding-resume-templates如何新增模板docs/agent/features/adding-resume-templates.mdenrichmentAI 信息補(bǔ)全流程docs/agent/features/enrichment.mdjd-match職位描述匹配docs/agent/features/jd-match.mdi18n國(guó)際化docs/agent/features/i18n.mdi18n-preparationi18n 搭建筆記docs/agent/features/i18n-preparation.mdLLM 集成文檔用途倉(cāng)庫(kù)路徑llm-integration通過 LiteLLM 的多提供商 AI 接入docs/agent/llm-integration.md可移植包存放于本目錄之外包用途倉(cāng)庫(kù)路徑swiss-design-system完整 Swiss 風(fēng)格設(shè)計(jì)系統(tǒng)前端工作的必讀材料docs/portable/swiss-design-system/README.mdnextjs-performanceNext.js 15 性能優(yōu)化前端工作的必讀材料docs/portable/nextjs-performance/README.md值得注意的是docs/agent/features/application-tracker.md求職申請(qǐng)追蹤看板也存在于該目錄中與倉(cāng)庫(kù)中apps/backend/app/routers/applications.py及前端 apps/frontend/components/tracker/ 等組件對(duì)應(yīng)是功能文檔體系中未被索引表收錄但實(shí)際存在的一部分。三、項(xiàng)目結(jié)構(gòu)速覽backend 與 frontend 雙應(yīng)用原索引給出了倉(cāng)庫(kù)的頂層骨架docs/agent/README.md 的 Project Structure 一節(jié)這里完整繼承并補(bǔ)充真實(shí)目錄細(xì)節(jié)apps/ ├── backend/ # FastAPI Python │ ├── app/ │ │ ├── main.py # 入口lifespanTinyDB→SQLite 遷移、舊 key 折疊 │ │ ├── routers/ # API 端點(diǎn)health/config/resumes/jobs/applications/enrichment │ │ ├── services/ # 業(yè)務(wù)邏輯parser/improver/cover_letter/refiner │ │ ├── schemas/ # Pydantic 模型 │ │ ├── prompts/ # LLM 提示詞模板 │ │ ├── config.py # Pydantic 設(shè)置 加密 API key 讀寫 │ │ ├── crypto.py # Fernet 加密/解密 │ │ ├── database.py # 異步 SQLAlchemy/SQLite 門面返回純 dict │ │ ├── db_engine.py # SQLite 引擎/會(huì)話工廠 PRAGMA │ │ ├── llm.py # LiteLLM 多提供商封裝 │ │ └── pdf.py # Playwright PDF 渲染 │ └── data/ # 數(shù)據(jù)庫(kù)存儲(chǔ) │ └── frontend/ # Next.js React ├── app/ # 頁(yè)面(default)/、print/ ├── components/ # UI 組件ui/builder/preview/resume/tailor/tracker └── lib/ # 工具、API client、context從 apps/backend/app/ 的實(shí)際源碼看后端不止上表列出的文件還包含config_cache.py、db_engine.py、models.py、pdf.py以及scripts/migrate_tinydb_to_sqlite.py一次性 TinyDB 導(dǎo)入器prompts/目錄下除了templates.py還有enrichment.py、refinement.py、resume_wizard.py等按功能拆分的提示詞文件。前端在components/下還新增了enrichment/、resume-wizard/、tailor/、tracker/、settings/等目錄說明該索引中的結(jié)構(gòu)圖是穩(wěn)定主干具體以各架構(gòu)文檔與源碼為準(zhǔn)。四、任務(wù)驅(qū)動(dòng)的文檔閱讀路徑How to Use原索引以四類典型任務(wù)給出了閱讀順序這是整個(gè)文檔體系最實(shí)用的部分完整繼承如下并補(bǔ)充每步讀取的目的新任務(wù)New tasks先讀 scope-and-principles了解哪些事能做、哪些禁止→ quickstart掌握安裝/運(yùn)行/測(cè)試命令→ workflow遵守提交與 PR 約定。后端改動(dòng)Backend changes讀 backend-architecture模塊與 API 全貌→ front-end-apisAPI 契約→ llm-integrationLLM 調(diào)用方式。前端改動(dòng)Frontend changes讀 frontend-architecture → 可移植包 swiss-design-system → 可移植包 nextjs-performance → coding-standards。模板/PDF 改動(dòng)Template/PDF changes讀 pdf-template-guide → template-system。這套路徑的設(shè)計(jì)哲學(xué)是按任務(wù)聚類、按依賴排序后端改動(dòng)鏈把架構(gòu)怎么組織→ 契約暴露什么→ LLM 集成AI 怎么調(diào)串成一條完整鏈路前端改動(dòng)鏈則強(qiáng)制先讀可移植設(shè)計(jì)系統(tǒng)與性能規(guī)范再讀編碼規(guī)范避免 UI 改動(dòng)違反 Swiss 風(fēng)格約束。五、核心文檔深入Scope、Quickstart 與 Workflow5.1 項(xiàng)目是什么scope-and-principlesdocs/agent/scope-and-principles.md 是Agent 行為規(guī)則的權(quán)威來源Canonical source其技術(shù)棧描述與倉(cāng)庫(kù)源碼高度一致后端FastAPI Python 3.13通過 LiteLLM 支持多提供商 LLM前端Next.js React 19注意該文檔寫 Next.js 16而 frontend-architecture 寫 Next.js 15可移植包標(biāo)題為 Next.js 15 performance optimizations兩處版本表述以 apps/frontend/package.json 實(shí)際依賴為準(zhǔn)采用 Swiss International Style 設(shè)計(jì)數(shù)據(jù)庫(kù)SQLite通過異步 SQLAlchemyaiosqlite訪問PDF 生成通過 Playwright 調(diào)用無頭 Chromium。文檔還定義了不可妥協(xié)的規(guī)則Non-Negotiable Rules所有前端改動(dòng)必須遵循 Swiss 設(shè)計(jì)系統(tǒng)所有后端函數(shù)必須帶類型提示type hints提交前必須運(yùn)行npm run lint與npm run formatPrettier錯(cuò)誤處理后端在服務(wù)端記錄詳細(xì)錯(cuò)誤、向客戶端返回通用消息前端使用錯(cuò)誤邊界Error Boundary與用戶友好的錯(cuò)誤狀態(tài)安全絕不在客戶端響應(yīng)中暴露 API key 或敏感數(shù)據(jù)共享資源初始化使用asyncio.Lock()可變默認(rèn)值必須使用copy.deepcopy()。范圍外Out of Scope事項(xiàng)明確列出不得修改.github/workflows/、不得未經(jīng)明確請(qǐng)求改動(dòng) CI/CD 配置、不得改動(dòng) Docker 構(gòu)建行為、不得刪除或禁用測(cè)試。5.2 快速開始quickstartdocs/agent/quickstart.md 給出了可直接執(zhí)行的完整命令序列前置要求Node.js 22、Python 3.13、uvPython 包管理器。安裝從倉(cāng)庫(kù)根目錄執(zhí)行# 后端 cd apps/backend uv sync # 前端 cd apps/frontend npm install開發(fā)兩個(gè)終端并行# 終端 1后端 cd apps/backend uv run uvicorn app.main:app --reload --port 8000 # 終端 2前端 cd apps/frontend npm run dev質(zhì)量檢查# 在 apps/frontend 下 npm run lint # 前端 lint npm run format # Prettier 格式化后端測(cè)試cd apps/backend uv run pytest環(huán)境變量初始化# 后端 cp apps/backend/.env.example apps/backend/.env # 前端 cp apps/frontend/.env.sample apps/frontend/.env.local首次使用流程打開 http://localhost:3000/settings選擇 AI 提供商并輸入 API key點(diǎn)擊 Test Connection對(duì)應(yīng)POST /api/v1/config/llm-test端點(diǎn)上傳第一份簡(jiǎn)歷5.3 工作流約定workflowdocs/agent/workflow.md 定義了提交、PR 與測(cè)試規(guī)范提交信息使用簡(jiǎn)潔的句子式主題如Add custom funding link to FUNDING.yml若使用前綴采用祈使句type: summary格式用Fixes #123關(guān)聯(lián) issuePR 要求在描述中引用 issueschema 或 prompt 改動(dòng)必須顯式標(biāo)注以便 reviewer 對(duì)下游 Agent 做冒煙測(cè)試列出本地驗(yàn)證命令UI/API 改動(dòng)附截圖測(cè)試約定前端測(cè)試以*.test.tsx命名倉(cāng)庫(kù)中 apps/frontend/tests/ 等真實(shí)遵循此約定后端測(cè)試用test_*.py命名置于apps/backend/tests/需使用匿名化的簡(jiǎn)歷/職位 fixtures見 apps/backend/tests/conftest.pyDefinition of Done代碼可編譯、lint 通過、新功能有測(cè)試、UI 遵循 Swiss 包、schema/prompt 改動(dòng)在 PR 中標(biāo)注、UI 改動(dòng)附截圖、以 PR 中列出的命令完成本地驗(yàn)證。六、架構(gòu)文檔后端與前端的兩份地圖6.1 后端架構(gòu)backend-architecturedocs/agent/architecture/backend-architecture.md 是對(duì) apps/backend/app/ 源碼結(jié)構(gòu)的權(quán)威說明幾個(gè)關(guān)鍵設(shè)計(jì)值得展開API 端點(diǎn)一覽均掛載于/api/v1前綴類別端點(diǎn)說明健康GET /health存活探針不調(diào)用 LLM狀態(tài)GET /status完整系統(tǒng)狀態(tài)LLM 探針 DB 統(tǒng)計(jì)各檢查隔離 → 部分失敗仍返回 200 與降級(jí)狀態(tài)配置GET/PUT /config/llm-api-keyLLM 配置不再持久化 key配置POST /config/llm-test測(cè)試連接配置GET/POST/DELETE /config/api-keys按提供商加密存儲(chǔ)的 API key簡(jiǎn)歷POST /resumes/upload、GET /resumes、GET /resumes/list、POST /resumes/improve、PATCH /resumes/{id}、GET /resumes/{id}/pdf、DELETE /resumes/{id}簡(jiǎn)歷全生命周期職位POST /jobs/upload、GET /jobs/{id}職位描述應(yīng)用GET/POST /applications、GET/PATCH/DELETE /applications/{id}、PATCH /applications/bulk、POST /applications/bulk-deleteKanban 追蹤器數(shù)據(jù)庫(kù)設(shè)計(jì)SQLite 文件位于data/resume_matcher.db由database.py異步門面返回純 dict而非 ORM 行、models.py聲明式BaseResume/Job/Improvement/Application/ApiKey模型與db_engine.py引擎/會(huì)話工廠協(xié)作。數(shù)據(jù)庫(kù)有兩個(gè)引擎、一個(gè)文件模塊級(jí)異步引擎服務(wù)文檔表與applications表同步引擎服務(wù)加密的api_keys表——因?yàn)樵摫碓谕降?LLM 熱路徑get_llm_config→load_config_file→resolve_api_key上被讀取異步不必穿透到llm.py。源碼 apps/backend/app/db_engine.py 中可見兩個(gè)引擎連接時(shí)都執(zhí)行PRAGMA journal_modeWAL、PRAGMA foreign_keysON、PRAGMA busy_timeout5000。關(guān)鍵不變量與遷移單一主簡(jiǎn)歷single-master通過asyncio.Lockcreate_resume_atomic_masteris_master上的部分唯一索引保證動(dòng)態(tài)流水線字段preview_hash/preview_hashes、job_keywords、company/role存放在metadata_jsonJSON 列中讀取時(shí)扁平化Application通過UniqueConstraint在(job_id, resume_id)上去重一次性導(dǎo)入器scripts/migrate_tinydb_to_sqlite.py啟動(dòng) lifespan 時(shí)若存在舊 TinyDB 文件data/database.json且 SQLite 為空則導(dǎo)入行并重命名為database.json.migrated可回滾工件冪等——SQLite 已有數(shù)據(jù)則跳過加密 API keycrypto.py使用 Fernet 對(duì)稱加解密密鑰位于data/.secret_key自動(dòng)生成、chmod 600、gitignored、原子寫入明文只存在于內(nèi)存migrate_legacy_keys()在啟動(dòng)時(shí)將舊明文 key 折疊進(jìn)加密存儲(chǔ)冪等、不覆蓋。LLM 集成llm.py提供商為 OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter、Ollama。三個(gè)核心異步函數(shù)await check_llm_health(config) # 30s 超時(shí) await complete(prompt, ...) # 120s 超時(shí) await complete_json(prompt, ...) # 180s 超時(shí)JSON 模式 重試特性包括API key 直接傳參避免os.environ競(jìng)態(tài)受支持提供商自動(dòng)啟用 JSON 模式帶更低溫度的重試?yán)ㄌ?hào)匹配 JSON 提取。源碼 apps/backend/app/llm.py 進(jìn)一步證實(shí)了超時(shí)常量30/120/180 秒以及MAX_JSON_EXTRACTION_RECURSION 10、MAX_JSON_CONTENT_SIZE 1MB、DEFAULT_JSON_MAX_TOKENS 8192等安全上限。配置優(yōu)先級(jí)非機(jī)密配置provider/model/base/features存放在data/config.json優(yōu)先級(jí)高于環(huán)境變量API key 絕不寫入config.json只加密存于 SQLiteapi_keys表僅在讀取時(shí)注入配置字典。6.2 前端架構(gòu)與工作流frontend-architecture / frontend-workflowdocs/agent/architecture/frontend-architecture.md 與 docs/agent/architecture/frontend-workflow.md 共同勾勒了前端全貌核心用戶流Dashboard → Upload Master Resume → Tailor for Job → View/Edit → Download PDF主要頁(yè)面/dashboard主簡(jiǎn)歷卡片 定制簡(jiǎn)歷瓦片狀態(tài)機(jī)loading | pending | processing | ready | failed窗口聚焦時(shí)自動(dòng)刷新用 localStorage 的master_resume_id記錄主簡(jiǎn)歷/builder左側(cè)編輯器表單 格式控制右側(cè) WYSIWYG 分頁(yè)預(yù)覽Resume / Cover Letter / Outreach 三個(gè)標(biāo)簽頁(yè)自動(dòng)保存到 localStorage數(shù)據(jù)優(yōu)先級(jí)為 URL 參數(shù) → Context → localStorage → 默認(rèn)值/tailorJD 文本域最少 50 字符流程為POST /jobs/upload→POST /resumes/improve→ 跳轉(zhuǎn)/resumes/[new_id]/settings6 個(gè)提供商選擇、API key 輸入、系統(tǒng)狀態(tài)緩存30 分鐘刷新打印路由/print/resumes/[id]、/print/cover-letter/[id]由無頭 Chrome 為 PDF 渲染支持 template、pageSize、margins、spacing 查詢參數(shù)。狀態(tài)管理StatusCacheProvider緩存系統(tǒng)狀態(tài)30 分鐘自動(dòng)刷新 樂觀計(jì)數(shù)更新LanguageProvider管理內(nèi)容生成語言en、es、zh、ja對(duì)應(yīng)倉(cāng)庫(kù)中的 apps/frontend/lib/context/language-context.tsx 與 apps/frontend/i18n/config.ts。localStorage 鍵master_resume_id主簡(jiǎn)歷 UUID、resume_builder_draft表單自動(dòng)保存、resume_builder_settings模板偏好。分頁(yè)系統(tǒng)usePagination鉤子計(jì)算分頁(yè)斷點(diǎn)尊重.resume-item邊界、防止孤立標(biāo)題orphaned headers、150ms 防抖分頁(yè)規(guī)則為區(qū)塊可以跨頁(yè)、單個(gè)條目保持完整、頁(yè)面至少 50% 滿才斷頁(yè)、標(biāo)題永不孤立。關(guān)鍵 CSS 規(guī)則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 文檔契約與請(qǐng)求/響應(yīng)流程docs/agent/apis/api-flow-maps.md 以流程圖形式呈現(xiàn)了各端點(diǎn)的內(nèi)部調(diào)用鏈?zhǔn)桥挪閱栴}的第一手材料。以下是幾個(gè)最關(guān)鍵的流程完整繼承并適當(dāng)注解簡(jiǎn)歷上傳POST /api/v1/resumes/upload ├── 校驗(yàn)文件PDF/DOCX≤4MB ├── parse_document() → Markdown ├── db.create_resume(statusprocessing) ├── parse_resume_to_json() → LLM │ ├── 成功statusready │ └── 失敗statusfailed └── 返回 {resume_id}簡(jiǎn)歷定制ImprovementPOST /api/v1/resumes/improve ├── 從 DB 取簡(jiǎn)歷 職位 ├── 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 取簡(jiǎn)歷 ├── 構(gòu)造 URL{frontend}/print/resumes/{id}?{params} ├── Playwright 渲染等待 .resume-print └── 返回 PDF 字節(jié)系統(tǒng)狀態(tài)部分失敗仍 200GET /api/v1/status # 每項(xiàng)檢查隔離 → 200部分/降級(jí)絕不 500 ├── try: get_llm_config() │ ├── llm_configured api_key 已設(shè)置 或 provider ∈ {ollama, openai_compatible} │ └── check_llm_health() → llm_healthy # 此處失敗只降級(jí)該字段 ├── try: db.get_stats() # 失敗 → 空統(tǒng)計(jì)仍 200 └── 返回 {status, llm_configured, llm_healthy, has_master_resume, database_stats}按提供商加密的 API keyGET /api/v1/config/api-keys └── 返回 {providers: [{provider, configured, masked_key}]} # 始終掩碼 POST /api/v1/config/api-keys ├── 對(duì)每個(gè)提供的 keyFernet 加密 → upsert 進(jìn) SQLite api_keys 表 # 其他提供商 key 不受影響 └── 返回 {message, updated_providers} DELETE /api/v1/config/api-keys/{provider} # 刪除單個(gè)提供商 key DELETE /api/v1/config/api-keys?confirm... # 清空所有 key求職追蹤器Application TrackerGET /applications按 7 個(gè)狀態(tài)鍵分組返回saved / applied / no_response / response / interview / accepted / rejected手動(dòng)新增時(shí)若缺 company/role 會(huì)做一次 best-effort 的extract_job_keywords()LLM 調(diào)用PATCH /applications/{id}時(shí)服務(wù)端會(huì)重排position。值得注意的自動(dòng)創(chuàng)建邏輯POST /resumes/improve/confirm及舊版POST /resumes/improve在持久化定制簡(jiǎn)歷后會(huì)自動(dòng)創(chuàng)建一個(gè)applied卡片——這是 best-effort 行為追蹤器失敗不會(huì)破壞定制主流程company/role 復(fù)用緩存的 keyword 提取結(jié)果不產(chǎn)生額外 LLM 調(diào)用。八、設(shè)計(jì)文檔模板系統(tǒng)與 PDF 渲染8.1 模板系統(tǒng)template-systemdocs/agent/design/template-system.md 完整列出了 7 套模板倉(cāng)庫(kù)中對(duì)應(yīng)文件見 apps/frontend/components/resume/模板布局適用場(chǎng)景swiss-single全寬縱向1–2 頁(yè)簡(jiǎn)歷swiss-two-column65% 主欄 35% 側(cè)欄內(nèi)容密集modern單欄 強(qiáng)調(diào)色標(biāo)題彩色單欄modern-two-column65% 主欄 35% 側(cè)欄 強(qiáng)調(diào)色彩色密集內(nèi)容latex單欄、襯線、規(guī)則線標(biāo)題經(jīng)典/學(xué)術(shù)簡(jiǎn)歷clean單欄、極簡(jiǎn)無襯線低調(diào)現(xiàn)代簡(jiǎn)歷vivid63% 主欄 37% 側(cè)欄 強(qiáng)調(diào)色Awesome-CV 風(fēng)格彩色簡(jiǎn)歷模板設(shè)置的權(quán)威定義在 apps/frontend/lib/types/template-settings.tsTemplateSettings、DEFAULT_TEMPLATE_SETTINGS及 CSS 變量映射當(dāng)前形態(tài)包括pageSizeA4/LETTER、margins各 5–25mm、spacingsection/item/lineHeight 各 1–5 級(jí)、fontSizebase/headerScale 1–5 級(jí)headerFont/bodyFont 可選 serif/sans-serif/mono、compactMode、showContactIcons、accentColorblue/green/orange/red適用于 modern、modern-two-column、vivid。自定義區(qū)塊由AddSectionDialog支持三種類型textGenericTextForm用于 Objective、statement、itemListGenericItemForm用于 Publications、research、stringListGenericListForm用于 Hobbies、interests。間距變量通過 CSS 變量計(jì)算--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 有更詳細(xì)說明創(chuàng)建components/resume/resume-{name}.tsx實(shí)現(xiàn)TemplateProps接口從components/resume/index.ts導(dǎo)出加入FormattingControls選擇器生成預(yù)覽縮略圖。8.2 PDF 渲染流水線pdf-template-guidePDF 渲染使用 Playwright 無頭 Chromium核心函數(shù)為render_resume_pdf(url, page_size, selector.resume-print)。關(guān)鍵約束是globals.css中的打印類白名單見上文 6.2這解釋了為什么前端路由中單獨(dú)存在print/目錄打印路由是專為 PDF 渲染設(shè)計(jì)的、去交互的頁(yè)面形態(tài)。九、LLM 集成細(xì)節(jié)LiteLLM、JSON 模式與重試docs/agent/llm-integration.md 提供了多提供商接入的完整說明其中幾個(gè)關(guān)鍵實(shí)現(xiàn)值得強(qiáng)調(diào)提供商矩陣Ollama本地、免費(fèi)、OpenAIGPT-5 Nano、GPT-4o、AnthropicClaude Haiku 4.5、GeminiGemini 3 Flash、OpenRouter多模型聚合、DeepSeekDeepSeek Chat。API key 傳參方式直接傳給litellm.acompletion()的api_key參數(shù)而非os.environ——后者在異步上下文中存在競(jìng)態(tài)風(fēng)險(xiǎn)# 正確 await litellm.acompletion( modelmodel, messagesmessages, api_keyapi_key # 直接傳參 ) # 錯(cuò)誤 —— 不要在異步代碼中使用 os.environ os.environ[OPENAI_API_KEY] key # 競(jìng)態(tài)風(fēng)險(xiǎn)JSON 模式complete_json()對(duì)支持的提供商OpenAI、Anthropic、Gemini、DeepSeek、主流 OpenRouter 模型自動(dòng)啟用response_format{type: json_object}JSON 完成帶 2 次自動(dòng)重試且溫度逐次降低第 1 次 0.1、第 2 次 0.0_extract_json()使用健壯的括號(hào)匹配算法處理畸形響應(yīng)、Markdown 代碼塊、邊界情況并帶有遞歸保護(hù)源碼中MAX_JSON_EXTRACTION_RECURSION 10。超時(shí)配置源碼 apps/backend/app/llm.py 與文檔一致健康檢查 30s、普通完成 120s、JSON 操作 180s。提示詞指南新提示詞加入 apps/backend/app/prompts/templates.py使用{variable}單大括號(hào)替換結(jié)構(gòu)化輸出必須給出示例 JSON schema指令保持簡(jiǎn)潔Output ONLY the JSON object, no other text。健康檢查注意Docker 健康檢查必須使用/api/v1/health而非/health這一點(diǎn)在部署場(chǎng)景下容易被忽略。十、可移植包獨(dú)立于項(xiàng)目的最佳實(shí)踐沉淀索引特別強(qiáng)調(diào)兩個(gè)可移植包存放于 docs/portable/swiss-design-system完整 Swiss 風(fēng)格設(shè)計(jì)系統(tǒng)tokens、組件、布局、反模式前端工作的必讀材料其中的 tokens.md 與 components.md 是觸碰 UI 前的強(qiáng)制閱讀項(xiàng)見 scope-and-principles 規(guī)則第 1 條nextjs-performanceNext.js 性能優(yōu)化實(shí)踐水合瀑布、包體積、Server Actions 安全、服務(wù)端性能對(duì) apps/frontend/ 的改造工作具有直接指導(dǎo)價(jià)值。這種把通用知識(shí)做成可移植包、項(xiàng)目專屬知識(shí)留在 agent 目錄的劃分是文檔體系的關(guān)鍵設(shè)計(jì)它讓跨項(xiàng)目復(fù)用的內(nèi)容不被項(xiàng)目細(xì)節(jié)污染也讓 Agent 只需在項(xiàng)目?jī)?nèi)查找專屬約定。十一、總結(jié)如何使用這份文檔地圖對(duì)任何要在 Resume Matcher 倉(cāng)庫(kù)中工作的 Agent 或開發(fā)者推薦的實(shí)踐路徑是新任務(wù)起步scope-and-principles→quickstart→workflow先建立行為邊界、工具命令與協(xié)作約定定位問題域根據(jù)任務(wù)類型選擇架構(gòu)后端/前端、API契約/流程、設(shè)計(jì)模板/PDF或功能文檔配合 apps/backend/tests/ 與 apps/frontend/tests/ 中的測(cè)試用例驗(yàn)證行為深入實(shí)現(xiàn)通過各文檔給出的源碼相對(duì)路徑如 apps/backend/app/llm.py、apps/backend/app/db_engine.py、apps/frontend/lib/types/template-settings.ts直達(dá)底層實(shí)現(xiàn)遵循交付標(biāo)準(zhǔn)以workflow.md的 Definition of Done 為完成標(biāo)準(zhǔn)涉及 schema/prompt 改動(dòng)時(shí)在 PR 中顯式標(biāo)注。這份索引的價(jià)值在于它把代碼庫(kù)知識(shí)組織成了可檢索、可排序、按任務(wù)導(dǎo)航的結(jié)構(gòu)既服務(wù)于人類開發(fā)者也服務(wù)于需要高效定位代碼的 AI Agent——這也是它被命名為 Agent Documentation Index 的原因所在。【免費(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考