freehire 的 on-demand LLM 岗位匹配分析:三段式提示链、五维评分与四重缓存失效机制

原创2026-10-24 22:10:401,924 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

freehire 的 on-demand LLM 岗位匹配分析:三段式提示链、五维评分与四重缓存失效机制

freehire 的岗位详情页里有一个"确定性技能匹配条",它由纯集合运算得出,快而免费,但读不懂岗位正文、公司背景与候选人真实经历。本文以仓库中的规格文档 job-fit-analysis/spec.md 为骨架,逐条拆解在此之上实现的按需 LLM 适配度分析(fit analysis):固定的三段式提示链、受控词表的五维评分、确定性锚点与硬约束封顶、四重时间戳缓存失效,以及"永不报错"的优雅降级契约,并结合 internal/candidate/matchanalysis、internal/candidate/fitanalysis 与 internal/api/handler/match_analysis.go 给出源码级证据与可直接复用的调用示例。

一、功能定位:为什么不复用确定性的技能匹配

规格开篇即把契约钉死:系统 SHALL 提供受身份认证保护的 POST /api/v1/jobs/:slug/fit,运行一条固定的三段式 LLM 提示链,比较岗位(标题 + 描述)、公司上下文与调用者已存储的 CV 文本,返回结构化适配分析。两个关键词决定了整个实现形态:

  • fixed three-stage prompt-chain:链是确定性、服务端编排的类型化调用序列,不是自主行动、自我决定步数的 agent;
  • scoped to the calling user and the job addressed by :slug:分析严格限定在"调用者 × 该岗位"这一对上,不可跨用户复用。

这条分界线在早期设计稿里讲得很清楚:确定性匹配(internal/candidate/jobmatch)是对规范化技能 slug 的纯集合运算,快且免费,但对岗位文本、公司背景、候选人真实经历是盲的,因此判断不了标题契合度与经验相关度——而这恰恰是 ATS 关键词筛选和招聘官最看重的两个信号。两者不是替代关系,而是快慢分层:确定性条恒在前,LLM 分析按需展开。

早期设计稿还记录了"为什么不用自主 agent"的取舍:自主 agent 自行决定步数与工具调用,成本、延迟、输出形状都非确定,与"可缓存、可单测、边界受控"的产品端点相悖。此处每一步的顺序已知、每段输出都是类型化 JSON、所有输入(CV、岗位、company_info、确定性锚点)在第一次调用前就已在内存里,因此没有工具可供 agent 决定调用。

命名演进提示:规格文档写的是 POST /api/v1/jobs/:slug/fit,当前实现已重命名为 /jobs/:slug/match-analysis,并把 /jobs/:slug/fit 保留为弃用别名,指向同一批 handler(见 match_analysis.go 与 docs/API.md)。同理,规格中的 internal/jobmatch 现位于 internal/candidate/jobmatch,设计稿里的 internal/jobfit 落地为 internal/candidate/matchanalysis。

二、三段式提示链:ATS 镜头 → 招聘官镜头 → 对抗审计

链只有一份实现:Analyzer.AnalyzeStream(ctx, in, emit),位于 analyzer.go;同步入口 Analyze 是一行把 emit 换成空函数的包装。这种"一条实现 + 薄包装"的写法消除了双路径漂移,也让单测可以用同一个 fake client 覆盖同步与流式两种调用。

Stage 1 — Extract & Match(ATS 镜头)

从岗位正文中抽取显式要求(技能、工具、经验、职责)以及职位标题与资历信号,并逐条对 CV 分类。规格要求这条链的第一段输出一张表,且 MUST NOT fabricate a skill the CV does not evidence:真实的缺口必须报 missing-gap,绝不允许隐藏。

受控词表(见 matchanalysis.go):

状态 含义
covered CV 中逐字出现或仅词形变化
synonym-only 概念存在,但用了不同术语
missing-have 档案能证明,但 CV 从未写明该术语
missing-gap 真实缺口:缺失且没有相近等价物

每条还带 priority(required / preferred)与 evidence(在 CV 何处出现,或为何缺失)。当前实现额外引入 evidence_strength 四级证据强度:metric(带数字/规模/可度量结果)、scope(团队、系统、地域的广度)、responsibility(以工具或方法体现的明确归属)、keyword(仅裸提及或职责式描述)。两个 missing-* 状态不带强度——没有证据,就没有强度可评。

这一级词表的价值不在"标签好看",而在它是 Stage 2 与 Stage 3 共用的判分语言。这一点在源码里有明确代价记录:evidence_rule.go 的注释写道,该规则曾只写在第三段审计的提示里,结果 2026-09-08 三个岗位中 Stage 2 给出 skills_coverage 95、100、93,审计各自拉低到 62、70、74——同方向、近同幅度、每次都发生。这不是两个模型判断不同,而是一个阶段在应用另一个阶段从未被告知的规则,还为此多付一次模型调用。现在这条规则被抽成唯一函数 evidenceStrengthRule(),同时注入 Stage 2 与 Stage 3 的提示。

Stage 1 还产出 hidden_signals(最多 5 条):从岗位自身措辞读出的未明说信号,形如 {"quote": "...", "insight": "..."}。约束同样严厉——必须基于岗位中真实存在的措辞,若岗位简短笼统、没有特征性表述,就返回空数组,绝不为了填满而编造。

此外,Stage 1 是唯一被要求"不要思考"的阶段(reasoning.go):reasoningForStage(1) 返回 llm.ReasoningNone。原因写在注释里——生产日志中该阶段每次失败都恰好是 dur=1m30.000s,一次分析两次(因为会重试一次),三分钟换来空结果;而同 alias 下 6000 字符提示词约 35 秒就能回答,说明不是网关慢,是该阶段的"深思"越过了自己的 deadline。Stage 2、3 属判断型工作,保留模型自身的思考强度。

Stage 2 — Recruiter verdict(招聘官镜头)

拿到 Stage 1 的要求匹配表后,以招聘官视角给每个维度打分并给出一句 comment,同时产出 strengths(≤6)、gaps(≤6)与 recommendation(两三段短散文,明确禁止复述逐条要求状态)。提示词里有一句关键约束:"Do NOT return an overall score — it is computed separately."

Stage 3 — Adversarial audit(对抗审计)

最后一段挑战招聘官结论:压低被夸大的维度分、删除 CV 并不支持的 strength、点出被轻描淡写的 gap,返回修正后的结论,而对外服务的那份分析就构建自它。规格给了一个硬性兜底:审计阶段失败或输出不可解析时,系统 MUST 回退到未审计的招聘官结论,而不是让请求报错。

实现里有两个容易被忽略的细节,值得单独说明。

其一,合并而非替换。 Stage 3 的 out 参数在调用前被预填为已净化的 Stage 2 结论,因此 json.Unmarshal 只覆盖 JSON 中出现的键——省略的维度保留 Stage 2 分数。注释把理由写得直白:预算模型只回显它改动过的字段时,只能"精修"结论,不可能把整份结论掏空成零。与之配套的还有 strengths / gaps 的 null 处理:显式 "strengths": null 会解成 nil 切片并覆盖 Stage 2 的列表,而"空数组"是一次有意的修剪应被保留;因此仅当解出 nil 时,才把 Stage 2 的值恢复回来。

其二,重试与超时不对称。 attempts.go 让 Stage 3 只有 1 次尝试,而 Stage 1/2 有 2 次;timeout.go 则给 Stage 3 两倍预算。两者出自同一个测量:2026-09-08 约三小时内审计失败 9 次、无一落地,每次都卡在整 90 秒,而同等判断量的 Stage 2 在 45–83 秒内答完。单次尝试的两倍预算与原先"两次尝试的常规预算"最坏情况相同,但审计这次能真正落在窗口内——它付得起等待,因为它的对象(Stage 2 结论)已经流式送达读者,慢审计延迟的只是一次精修,不是答案本身。

streamStage 还处理了一个 Go 反序列化陷阱:encoding/json 不会回滚部分解码,失败的那次尝试会留下它已走到的字段。因此每次尝试前都把 out 恢复到调用者传入时的快照(Stage 1/2 是零值,Stage 3 是 Stage 2 结论),避免后续部分成功的 JSON 静默继承未经校验的陈旧值。

三、五维评分:模型只打分,服务端算总分

规格要求的载荷结构是:五个维度各带 0–100 整数分,外加加权 overall_score、来自受控集合 {Strong Fit, Good Fit, Moderate Fit, Weak Fit, Poor Fit} 的 verdict、strengths 数组、gaps 数组和单条 recommendation。

规格同时规定:overall_score 等于五维的确定性加权平均,由服务端计算,而不是采信模型自报的总分。

当前实现是六维(新增 location_fit),权重定义在 matchanalysis.go:

维度 key 展示名 权重
title_alignment Title & role alignment 20
experience_relevance Experience relevance 25
seniority_fit Seniority fit 15
skills_coverage Skills coverage 15
company_context Company & role context 10
location_fit Location & work-mode fit 15

权重合计 100,并由单测 TestDimensionWeightsSumTo100 锁定。加权与判档逻辑本身很短:

weighted := 0.0
for _, spec := range dimensionSpecs {
    ds := scores[spec.key]
    dims = append(dims, Dimension{Key: spec.key, Label: spec.label, Score: ds.Score, Comment: ds.Comment})
    weighted += float64(ds.Score) * float64(spec.weight) / 100
}
overall := clamp(int(math.Round(weighted)))

维度切片由 dimensionSpecs 固定顺序重建,而不是照抄模型返回——因此"漏掉一个维度、打乱顺序、注入一个维度"这类输出永远到不了响应里。

verdictFor 用闭区间下界映射标签,阈值集中在 matchanalysis.go:

overall_score verdict
≥ 75 Strong Fit
≥ 60 Good Fit
≥ 45 Moderate Fit
≥ 30 Weak Fit
< 30 Poor Fit

四、确定性锚点:让模型"解释"而不是"重算"

规格的第三条要求很具体:提示词 SHALL 携带来自 internal/jobmatch 的确定性技能匹配(exact / adjacent / missing slug),使模型去解释和补充它,而不是从零重算技能;Skills coverage 维度 MUST 与确定性覆盖率保持一致。

实现由 writeAnchor 完成(analyzer.go),把覆盖率与三组 slug 直接写进 prompt:

Deterministic skills match (coverage 82%):
- has: go, postgresql
- close: typescript (via javascript)
- missing: kubernetes

锚点的语义由 jobmatch.go 定义:exact 计 1,adjacent 计 0.5,再除以岗位技能总数得到 coverage_percent。把同一个数字放进 prompt,等于同时给出"结论"和"事实来源",模型负责解释迁移性经验与隐藏匹配,而不是另造一套技能判断。

硬约束封顶:模型无法越过的天花板

除了软性锚点,还有一层硬性、纯确定性的天花板。hardconstraint.Evaluate 对六类约束(工作授权、认证、学历、经验年限、语言、地点与办公模式)做判定,未满足项带 ScoreCap:工作授权 50、认证 60、学历 65、经验 65、语言 70、地点 75;OverallCap 取所有未满足项中的最小值,无未满足项时为 100(hardconstraint.go 与 hardconstraint.go)。

这些未满足项以"已确定事实"的形式写入 prompt(writeBlockers),要求模型将其计入分数与 gap、且不得声称候选人满足;同时对外服务的副本再用 ApplyCeiling 压到该上限并重算 verdict:

func ApplyCeiling(a *Analysis, ceil int) {
    if a == nil || ceil >= a.OverallScore {
        return
    }
    a.OverallScore = ceil
    a.Verdict = verdictFor(ceil)
}

一个关键设计选择:封顶只在服务时施加,绝不写入缓存。缓存保存的是未封顶的链输出,封顶由读取方按当前字典重算,因此词典调整在下次读取即刻生效,无需任何缓存失效。

五、输出净化:所有模型输出都是不可信输入

规格要求所有模型输出在持久化或对外服务前 MUST 被净化:分数钳制、verdict 强制归入受控集合、自由文本裁剪并限长限量。实现把这条做成一个集中的净化层,默认上限定义在 matchanalysis.go:

边界 默认值 作用对象
MaxCommentRunes 240 每维 comment
MaxListItemRunes 200 每条 strength / gap
MaxRecommendRunes 1200 recommendation 自由文本
MaxReqTextRunes 200 requirement.text
MaxReqEvidenceRunes 240 requirement.evidence
MaxStrengths / MaxGaps 6 / 6 列表长度
MaxRequirements 30 要求匹配表条数
MaxSignals 5 hidden_signals 条数
MaxSignalQuoteRunes / MaxSignalInsightRunes 200 / 200 信号引文与洞察

三个净化函数的策略各不相同,值得区分:

  • sanitizeVerdict:钳制每个维度分到 0–100,逐字段裁剪自由文本,清理并限量列表。
  • sanitizeRequirements:丢弃而非改写不可信的条目——文本为空或状态不在词表内直接跳过。注释点明"绝不重贴标签,那会误报一次匹配"。priority 被归一化为 required / preferred(未识别的如 nice-to-have、空值一律落 preferred);evidence_strength 只对 covered / synonym-only 生效,未识别或空值降为最弱的 keyword,missing-* 恒为空。
  • sanitizeSignals:引文或洞察任一为空即丢弃——"没有依据的解释性主张,半成品无用",宁缺勿造。

净化同时是提示注入的防线:description 与 company_info 都是不可信输入,但模型无论被注入什么,输出都被压回受控契约与长度边界,也无法逃出 JSON 契约去触发任何动作。

上限本身也可配置:SetBounds 在进程启动时由 cmd/server 从环境变量加载(cmd/server/main.go),任何一项小于 1 会回落到该项默认值——注释的理由是"一个拼写错误不该抹掉一道天花板"。对应变量在 .env.example 中列出:

# MATCH_ANALYSIS_MAX_COMMENT_RUNES=240          # per-dimension Comment
# MATCH_ANALYSIS_MAX_LIST_ITEM_RUNES=200        # each Strengths / Gaps bullet
# MATCH_ANALYSIS_MAX_RECOMMEND_RUNES=1200       # free-text Recommendation
# MATCH_ANALYSIS_MAX_REQ_TEXT_RUNES=200         # Requirement.Text
# MATCH_ANALYSIS_MAX_REQ_EVIDENCE_RUNES=240     # Requirement.Evidence
# MATCH_ANALYSIS_MAX_STRENGTHS=6                # Strengths list length
# MATCH_ANALYSIS_MAX_GAPS=6                     # Gaps list length
# MATCH_ANALYSIS_MAX_REQUIREMENTS=30            # RequirementMatch list length
# MATCH_ANALYSIS_MAX_SIGNALS=5                  # HiddenSignals list length
# MATCH_ANALYSIS_MAX_SIGNAL_QUOTE_RUNES=200     # Signal.Quote
# MATCH_ANALYSIS_MAX_SIGNAL_INSIGHT_RUNES=200   # Signal.Insight

六、API 契约与调用示例

GET 只读缓存、永不调用 LLM;POST 跑链并 upsert;SSE 版本是同一条链的流式形态;另有一个列出"已分析岗位"的接口。路由注册见 match_analysis.go,全部走 mw.key(RequireAuthOrKey),即会话 Cookie 或 API Key。

GET /jobs/{slug}/match-analysis

返回缓存分析(CV 或岗位变化时标 stale),无缓存时 analysis 为 null,无 CV 时 has_cv 为 false。allowance 报告今日适配分析的余量,tailor_allowance 报告 CV 定制的余量。

curl "https://freehire.me/api/v1/jobs/<slug>/match-analysis" \
  -H "Authorization: Bearer $FREEHIRE_API_KEY"
{
  "data": {
    "has_cv": true,
    "stale": false,
    "analysis": {
      "overall_score": 82,
      "verdict": "Strong Fit",
      "dimensions": { "...": "..." },
      "requirement_match": [
        { "text": "5+ years Go", "priority": "required", "status": "covered", "evidence": "..." }
      ],
      "strengths": ["..."],
      "gaps": ["..."],
      "recommendation": "..."
    },
    "allowance": { "feature": "match", "used": 1, "limit": 3, "unlimited": false, "enforced": false, "resets_at": "2026-09-01T00:00:00Z" },
    "tailor_allowance": { "feature": "tailor", "used": 0, "limit": 2, "unlimited": false, "enforced": false, "resets_at": "2026-09-01T00:00:00Z" }
  }
}

响应载体是 { "data": { has_cv, stale, analysis, allowance?, tailor_allowance? } }(定义见 match_analysis.go)。allowance 只在读取路径出现,计算响应不带它——这样 SPA 能在用户点下按钮之前判断是否会被拒。

POST /jobs/{slug}/match-analysis

curl -X POST "https://freehire.me/api/v1/jobs/<slug>/match-analysis" \
  -H "Authorization: Bearer $FREEHIRE_API_KEY"

分析一个新岗位消耗当日额度,额度用尽返回 402;重算已分析过的岗位免费。analysis 为 null 表示 LLM 未配置或调用失败(仍为 200)。

GET /jobs/{slug}/match-analysis/stream

curl -N "https://freehire.me/api/v1/jobs/<slug>/match-analysis/stream" \
  -H "Authorization: Bearer $FREEHIRE_API_KEY"
data: {"kind":"stage_start","stage":1,"label":"Extracting requirements"}

data: {"kind":"requirements","requirements":[ { "...": "..." } ]}

data: {"kind":"final","analysis":{"overall_score":82,"verdict":"Strong Fit","...":"..."}}

事件种类共六种,定义在 analyzer.go:stage_start / stage_done(三步进度)、thinking(推理 token 增量,非推理模型下为空;原始 JSON token 永不外泄)、requirements(Stage 1 结果)、dimensions(Stage 2 后的中间分析)、final(审计后终稿)。流式端点还会先发一个 meta 事件告知 has_cv,并在响应头设置 X-Accel-Buffering: no 以阻止 nginx 缓冲(match_analysis_stream.go)。流式路径在完成后同样把结果写入缓存,与同步路径完全一致。

弃用别名

GET/POST /jobs/{slug}/fit 与 GET /jobs/{slug}/fit/stream 仍指向同一批 handler,仅为不打断既有 API Key 客户端与 CLI;新代码应使用 match-analysis 路径。

状态码矩阵

场景 结果
未认证 401,且绝不触发 LLM
未知 slug 404
无存储 CV 200 + has_cv: false + null analysis,不调用 LLM
LLM 未配置 / 调用失败 200 + null analysis,不写缓存
新岗位且当日额度耗尽 402(在打开 SSE 流之前就以状态码返回)
审计阶段失败 200 + Stage 2 未审计结论

七、四重缓存失效:绝不把过期结论当作当前结果

规格的缓存要求是:按 (user_id, job_id) 缓存,打上 CV 上传时间、岗位 content_hash 与产出模型的戳;GET 只有在三个戳全部等于当前值时才返回缓存,任一不同都必须报 stale 而不是当作当前结果服务。它还专门规定:content_hash 在存储戳与实时岗位两侧都缺失时视为未变,否则"永不重爬"的非 board 岗位会陷入无尽重算。

表结构见 migrations/0009_user_job_analysis.sql,主键即 (user_id, job_id),两个外键均 ON DELETE CASCADE——分析离开用户与岗位二者之一就没有意义:

CREATE TABLE public.user_job_analysis (
    user_id          bigint      NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
    job_id           bigint      NOT NULL REFERENCES public.jobs(id) ON DELETE CASCADE,
    analysis         jsonb       NOT NULL,
    model            text        NOT NULL,
    cv_uploaded_at   timestamptz,
    job_content_hash text,
    created_at       timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (user_id, job_id)
);

当前实现已扩展为四重戳:migrations/0103_user_job_analysis_language.sql 增加了 language text NOT NULL DEFAULT 'en'。理由与 CV、岗位、模型三者同构——候选人切换档案语言后,评语、strengths、gaps 与 recommendation 都写在旧语言里,若不打语言戳,就要等到 CV 或岗位文本因无关原因变化才会重算。历史行实际都是英文,因此默认值不是猜测而是事实。

判定规则只有一处实现,stamps.go:

func (live Stamps) Fresh(stored Stamps) bool {
    return stored.Model == live.Model &&
        stored.Language == live.Language &&
        sameTime(stored.CVUploadedAt, live.CVUploadedAt) &&
        sameText(stored.JobContentHash, live.JobContentHash)
}

sameText 精确实现了规格里的"两侧都缺失算未变":Valid 不一致即为变化;两侧都无效则返回 true。

规格为每种失效都给了场景,实现均能对应:

规格场景 行为
缓存新鲜(CV、岗位、模型均未变) stale: false,且不发起任何 LLM 调用
模型升级(LLM_MODEL 变更) stale: true,让更好的模型可被请求重算
重新上传 CV stale: true,SPA 提供重算入口,不当当前结果服务
岗位重新摄取、content_hash 变化 stale: true
从未分析过 200 + has_cv 反映 CV 状态 + analysis: null,不调用 LLM

CV 上传时间戳必须在链条启动之前捕获(h.cvUploadedAt),注释解释了原因:链要跑数秒,事后重读有可能把"新 CV 的时间"盖在"旧 CV 的分析"上。语言戳同理。

八、优雅降级:失败不报错,但不假装成功

规格要求功能整体 best-effort:LLM 未配置或调用失败时 MUST NOT 让请求失败,且 MUST 不影响确定性档案匹配;调用者无 CV 时必须以 has_cv: false 提示上传,而不是跑一遍模型。

在实现中,"空结果"有两个完全不同的成因,而 HasCandidateContext 这个谓词就是为了把它们区分开(analyzer.go):部署里没有配置网关,不是候选人能做什么的;CV 无法解析,只有候选人自己能修。在此之前两者都渲染成"分析不可用",于是 CV 解析失败的候选人会跑到一个显示"CV 已存在"的界面上去找一个根本不在自己这边的故障。

降级矩阵:

条件 是否调用 LLM 是否写缓存 响应
client == nil(LLM 未配置) 否 否 200,analysis: null
无存储 CV 否 否 200,has_cv: false
结构化简历无工作经历 否 否 200,analysis: null
Stage 1 / 2 失败 已调用 否 200,analysis: null
Stage 3 失败或不可解析 已调用 是(未审计结论) 200,Stage 2 结论

还有一层与隐私相关的强约束:原始 CV 文本永不发给模型。链的候选人上下文只有 resumeextract.Professional 这一"无联系方式投影"类型;去标识化是参数类型本身的性质,而不是链条执行的一个步骤——投影没有命名的字段,包括未来新增的字段,都不可能到达 prompt。若候选人没有已入库的工作经历,则不产出任何分析,且刻意不提供"回退到纯文本 CV"或"回退到结构体自带的经历副本"这两条路径:拿一份无人负责的经历去给人打分,比不打分更糟,而静默回退还会把失败的回填隐藏数月。

输入侧也有长度上限(analyzer.go):岗位描述 6000 runes、公司信息 2000 runes、结构化简历 JSON 3000 runes。注释说明了取舍——适配模型会对每个输入 token 进行推理,过大的 CV 或描述会把每段思考时间拉长到几十秒;这些上限既覆盖了 CV 与岗位的实质内容,又保住了每段的响应性。

地点维度同样优雅降级:候选人没有 location_preferences 时,只依据岗位地理信息打分,绝不报错。remoteWithinReach 是这条规则里的确定性补丁:当岗位为远程、且其 region/country 落在候选人声明的远程可达范围(remote.regions / remote.countries,global 覆盖一切)时,直接向 prompt 注入一条 NOTE,要求把 location_fit 打高、不因候选人的居住地或搬迁意愿扣分。注释点出了它防止的具体错误:模型会把远程岗位的总部城市(例如从圣多明各发布的 LATAM 远程岗)误读为搬迁要求并给出 0 分。

九、计费与并发合并

额度规则与并发治理也落在这个功能上,虽然规格主体只描述了缓存与降级,但它们是让"按需调用"在生产上可用的必要条件。

fitanalysis.Service.Reserve 做的是"先扣后算":先原子 Consume,再碰 LLM。注释记录了这个改动的由来——此前是"先查余量、算完再扣",是典型的 check-then-act,两个并发的、针对两个从未分析过岗位的运行可以同时通过一个只够付一次余量的检查,落败者的扣费会在其分析已算完、已缓存、已服务之后静默失败。把消费前置后,计数器自身的行锁就是仲裁者,第二次运行会被直接拒绝而不是白送。三条例外规则:

  • 只有"首次分析该岗位"才计费,重算永远免费;因此计量上线前就已缓存的分析重跑也不收费。
  • 计量fail open:余量读取不可达时记日志、放行且不预留。"记账不该有能力拒绝一次合法分析,一次未计费比一位被自己的会计挡住的候选人错得更轻。"
  • 运行若没有产出,会把预留归还(release);produced 与 cached 是两个不同的标志,因为"拿到分析"与"缓存写入成功"是两个问题。

并发合并在 coordinator.go 中被抽象成 leader/follower 契约:同一 (user, job) 的两个并发调用者,只有一个真正跑链(leader),另一个成为 follower,等 leader 结束后从缓存读取结果,而不是再付一次链的钱。follower 有一条纪律:先确认 leader 成功,才相信缓存。leader 失败时留下的是更旧的一行(或没有行),无条件读取会把陈旧分析伪装成这次运行的实时结果。合并的动机来自现实:Tailor 工作区的可见流与 autopilot 的冷启动填充会在同一时刻争抢同一对。

Run / Ensure / Refresh 也体现了这套包的分层理由:链有四个入口,只有一个走 HTTP——API 背后的缓存读与按需运行、Tailor 工作区的流式运行,以及 autopilot 的两个"隐形半边"(冷启动填充、运行后刷新),后者在请求结束之后从分离的 goroutine 执行、根本没有 fiber ctx。"把规则写在某个调用者恰好能碰到的地方,另外三个调用者就永远碰不到"——这正是计量、失效戳与合并为何从 Fiber handler 上移到 internal/candidate/fitanalysis 的原因。

十、前端交互:显式动作触发,过期必须提示重算

规格最后一条关于 UI 的要求很克制:Profile match 区块 SHALL 保留顶部那条快速的确定性进度条,LLM 分析渲染在由 fit 端点驱动的可展开区域里;AI 分析 MUST 只在用户显式动作后才展示(不在页面打开时自动拉取),且过期的缓存分析 MUST 提供重算入口。

当前实现已把独立分析页移除,Tailor 工作区成为唯一入口:MatchAnalysisFull.svelte 先取缓存分析,否则打开 EventSource,带三步 stepper、thinking 面板与渐进式分区;web/src/routes/match/[slug]/ 只剩一个 308 重定向到 /tailor/[slug],以便旧链接继续可用。纯 SSE 归约器 reduceMatchEvent 位于 web/src/lib/matchAnalysis.ts 并有单测;侧栏的 MatchSummary.svelte 只是指向工作区的紧凑摘要,从不在行内做计算。

组件里有一条与规格呼应的门控:只在没有任何缓存分析时自动运行。过期缓存不会静默重算——那要花三次 LLM 调用,而且还可能撞上 402;而重算一个已分析过的岗位始终免费,因此把决定权交给用户。过期时会展示提示:"Your CV or this role changed since this ran — recompute for an up-to-date read."

十一、验证与延伸阅读

想真正吃透这套实现,建议按以下顺序阅读与验证:

  1. 契约层:先读规格 spec.md,再读设计取舍 design.md——后者记录了权重校准、五维到六维的演进、以及"不用自主 agent"的完整论证。
  2. 纯函数层:internal/candidate/matchanalysis 的净化与加权是纯函数、无 I/O,单测覆盖了权重合计、阈值边界、钳制与列表限量(见 matchanalysis_test.go),是最容易单独跑通的部分。
  3. 编排层:fitanalysis 负责缓存、失效戳、计费与合并,stamps_test.go / coordinator_test.go / cache_failure_test.go 覆盖了四重戳判定与合并失败路径。
  4. 传输层:internal/api/handler/match_analysis*.go 与配套集成测试覆盖了 has_cv、stale、402、SSE 事件序列与 leader/follower 竞态。
  5. 数据层:确认 user_job_analysis 表与 language 列已在目标库中就位。注意仓库没有版本化迁移执行器,0009 的注释明确要求:在既有生产卷上,必须在部署读取该表的代码之前手工执行该语句。
  6. 配置层:.env 中确认 LLM_* 与 MATCH_ANALYSIS_*;未配置 LLM 时端点保持休眠而非报错,因此可以先上后端、后接网关。

再强调一次边界:链的步数与顺序固定、输出形状固定、文本长度固定、去标识化由类型保证、总分与标签由服务端计算、封顶由确定性字典决定。这套设计的目标不是让模型"更聪明",而是让一个不可信、非确定、会漂移的组件,落进一个可缓存、可单测、可预测的产品端点里。规格里那些"SHALL / MUST NOT"的措辞,本质都是在为同一个命题划界。

登录后查看全文
freehire