项目复盘：从 0 到 1 构建 JD 智能分析 Agent
本篇按"实验报告"的形式，完整记录这个项目的需求背景、方案设计、关键决策、踩坑与迭代过程。
1.需求背景
2026 年下半年启动跳槽，目标岗位为 AI 产品经理。在投递过程中发现三个高频痛点：
- 信息过载：招聘平台上海量 JD，人工逐条阅读、筛选效率极低；
- 匹配模糊：凭感觉判断"合不合适"，缺少结构化的差距分析，简历优化无从下手；
- 过程失控：投过哪些公司、什么岗位、进展到哪一步，靠脑子记不全。
于是决定把这个问题当作一个真实的产品需求来做：做一个 Agent，把"JD分析 → 匹配评估 → 报告生成 → 投递归档"全流程自动化。它首先是我自己每天要用的工具，其次才是展示作品。
2.方案设计与系统架构
系统采用 FCAgent 两层架构：上层是由大模型驱动的决策循环，下层是注册给模型调用的工具集。LLM 不直接生成答案，而是通过 Function Calling 自主选择并调用工具，多轮迭代直至任务完成。
各层职责
- 输入层：支持文本 JD、图片 JD（招聘截图）、批量图片三种输入形态；
- 决策层：FCAgent 主循环（qwen-max），根据用户输入自主决定调用哪个工具、以什么顺序调用，并设有系统边界——仅处理 JD 分析类请求，无关问题礼貌拒绝；
- 工具层：4 个核心工具——ocr_image（视觉模型识别图片）、analyze_jd（JD解析+RAG匹配+报告生成）、upload_report（同步飞书云文档）、write_to_excel（写入飞书岗位梯队表）；
- 支撑层：Chroma 向量知识库（个人简历/技能/项目经历向量化）、Prompt 版本化管理（YAML 配置）、效果评测、成本追踪、多 Provider LLM 配置；
- 输出层：Markdown 匹配度报告 + 飞书云文档归档 + 飞书表格投递策略沉淀。
另配有 Streamlit Web 界面，支持本地上传图片、查看分析进度与报告。
3.关键技术决策
决策一：输入类型判断交给 Function Call，而不是写死 if-else
早期版本用命令行参数路由（text/image 参数）。改造为 FCAgent 后，用户可以用自然语言表达（"帮我分析这张图里的JD"），由 LLM 自主决定是否调用 ocr_image 工具。取舍：FC 更灵活、更接近真实 Agent 形态，代价是多一次模型决策调用。
决策二：知识库检索坚持代码遍历，不强行套 Function Call
匹配分析需要"拿 JD 里的每个技能去知识库逐项检索证据"。这个环节用 for 循环遍历技能清单逐个检索，而不是让 LLM 决定检索什么。原因：检索路径是固定的（每个技能都必须查），代码遍历 100% 确定性、无遗漏；交给 LLM 决策反而可能漏检。Function Call 应该用在"路径不确定"的决策点上，而不是为了用而用。
决策三：批量处理 = 并发OCR + 串行分析 + 串行写Excel
批量分析 N 份 JD 图片时，OCR 阶段无资源竞争可并发提速；LLM 分析阶段受 API 限流约束必须串行；写飞书 Excel 阶段若并发会产生行号冲突，也必须串行。按各环节的资源约束分段选择并发策略，而不是一刀切。
决策四：报告与归档分离，飞书表格固定覆盖写
每份 JD 生成独立的飞书云文档（无冲突，可并行），岗位汇总表则用固定范围覆盖写（URL 不变，刷新即更新），避免每次修改创建新表导致链接失效、文件冗余。
4.踩坑与解决
解决：分析发现是 chunk 切分策略把技能描述切断、以及单次提问式检索覆盖率不足。改为"逐技能检索"（每个技能单独一次向量检索）并优化 chunk 策略，召回率从 62% 提升到 87%。同时保留人工核对机制兜底。
解决：先把结构化数据转成自然语言段落再输入模型，问题消失。教训：LLM 的输入形式直接影响输出行为，数据预处理是 Prompt 工程的一部分。
解决：重构 LLM 配置层，支持多 Provider（注释/取消注释即切换），文本任务与视觉任务分离配置，主通道失效时秒级切换备用通道。
解决：写入阶段串行化，并改为"整表范围覆盖写"模式，彻底消除行号竞争。
5.评测体系与成本控制
效果评测（evaluator 模块）
- JD 解析质量：用标注样本计算 F1，Prompt 每迭代一版跑一轮评测（0.71 → 0.89）；
- 检索召回率：统计 JD 技能在知识库中的证据命中率，指导 chunk 策略与检索方式优化（62% → 87%）。
核心思路：所有优化必须有量化依据，改 Prompt、改检索策略之前先跑基线，改完看指标变化，不靠感觉。
成本追踪（cost_tracker 模块）
- 每次分析按模型、按 Token 记录消耗与费用，单次 JD 分析成本可精确核算到分；
- 分析耗时三段式追踪（OCR / LLM分析+报告 / 全流程），性能瓶颈一目了然。
多 Provider 容灾
- LLM 配置层支持多供应商（注释/取消注释即切换），文本任务与视觉任务分离配置；
- 主通道额度耗尽时可秒级切换备用通道，保证分析流程不中断。
这些模块的共同目标：让项目从"能跑的Demo"变成"可度量、可控成本的工程化系统"。
6.数据安全与脱敏
- 知识库本地化：个人简历、技能、项目经历等敏感数据仅存储在本地 Chroma 向量库，数据目录已通过 .gitignore 排除，不进入任何远程仓库；
- 密钥管理：所有 API Key 统一存放在本地 .env 文件，代码与配置文件中无明文密钥；
- 对外脱敏：本站展示的所有报告均已脱敏——真实姓名替换为化名、雇主名称泛化、薪资预期删除。JD 公司名保留真实（属公开招聘信息），以保证分析过程的真实性可验证。
7.成果与迭代方向
当前成果
- 全流程跑通：JD 截图 → 1-2 分钟 → 7 章节匹配度报告 → 自动归档飞书；
- 已对多家真实招聘岗位完成分析（样例见成果页），直接指导了简历优化与投递策略；
- 形成可复用的工程范式：FCAgent 架构、Prompt 版本管理、评测驱动迭代、成本追踪。
下一步迭代方向
- 知识库证据可视化的进一步加强，缩小机检与人工核对的差距；
- 投递漏斗追踪：从"分析"延伸到"投递→面试→Offer"的全流程数据沉淀；
- 基于共性分析模块，挖掘目标岗位族群的技能需求趋势，反向指导学习计划。