项目复盘：从 0 到 1 构建 JD 智能分析 Agent

目录
  1. 需求背景
  2. 方案设计与系统架构
  3. 关键技术决策
  4. 踩坑与解决
  5. 数据安全与脱敏

1.需求背景

在投简历的过程中发现三个高频痛点：

于是决定做一个提效的Agent：实现"JD分析 → 匹配评估 → 报告生成"全流程自动化

2.方案设计与系统架构

详细架构图：FCAgent两层架构

各层职责

另配有 Streamlit Web 界面，便于Demo演示

3.关键技术决策

决策一：输入类型判断交给 Function Call，而不是写死 if-else

早期版本用命令行参数显式指定输入类型（text/image）：image 走"先图片识别再分析"、text 直接进 JD 分析，路由写死在代码里，LLM 不参与类型判断。改造为 FCAgent 后，用户随意输入（一句话、一个图片路径均可），由 LLM 逐轮规划调用链：判断是否先调 ocr_image → 拿到文本后调 analyze_jd → 分析完成后调飞书同步工具。取舍：FC 更灵活、更接近真实 Agent 形态；代价是每串联一个工具就要多一轮模型决策调用——if-else 路由下 LLM 只做分析这一件事，FC 模式下一次图片任务的完整链路约多出 3~4 次 qwen-max 调用，带来额外的 token 成本与延迟。

决策二：知识库检索坚持代码遍历，不强行套 Function Call

匹配分析需要"拿 JD 里的每个技能去知识库逐项检索证据"。这个环节用 for 循环遍历技能清单逐个检索，而不是让 LLM 决定检索什么。原因：检索路径是固定的（每个技能都必须查），代码遍历 100% 确定性、无遗漏；交给 LLM 决策反而可能漏检。Function Call 应该用在"路径不确定"的决策点上，而不是为了用而用。

决策三：批量处理 = 并发图片识别 + 串行分析 + 串行写Excel

批量分析 N 份 JD 图片时，图片识别阶段无资源竞争可并发提速；LLM 分析阶段受 API 限流约束必须串行；写飞书 Excel 阶段若并发会产生行号冲突，也必须串行。按各环节的资源约束分段选择并发策略，而不是一刀切。

决策四：报告与归档分离，飞书表格固定覆盖写

每份 JD 生成独立的飞书云文档（无冲突，可并行），岗位汇总表则用固定范围覆盖写（URL 不变，刷新即更新），避免每次修改创建新表导致链接失效、文件冗余。

决策五：图片转文字用视觉大模型，而不是传统 OCR

决策六：图片识别只产出文本，不做 JD 的结构化

4.踩坑与解决

坑 1：RAG 检索漏检已有技能。知识库里明明记录了 4 年 SQL 经验，检索时却没有命中对应证据。
解决：分析发现是 chunk 切分策略把技能描述切断、以及单次提问式检索覆盖率不足。改为"逐技能检索"（每个技能单独一次向量检索）并优化 chunk 策略，召回率从 62% 提升到 87%。同时保留人工核对机制兜底。
坑 2：LLM 输入原始 JSON 导致输出截断。把结构化 JD 的 JSON 直接喂给模型做分析时，模型会"过度解释"字段含义，输出过长被截断，下游解析报错。
解决：先把结构化数据转成自然语言段落再输入模型，问题消失。教训：LLM 的输入形式直接影响输出行为，数据预处理是 Prompt 工程的一部分。
坑 3：LLM 供应商额度频繁耗尽。主用通道的免费额度多次在分析中途耗尽，流程直接中断。
解决：重构 LLM 配置层，支持多 Provider（注释/取消注释即切换），文本任务与视觉任务分离配置，主通道失效时秒级切换备用通道。
坑 4：批量写飞书 Excel 行号冲突。多篇报告并发写入同一张表格时，追加行号互相覆盖，数据错乱。
解决：写入阶段串行化，并改为"整表范围覆盖写"模式，彻底消除行号竞争。

5.数据安全与脱敏