From 8fbb1f6fcacd7dc04482acf8a8aae6168a941313 Mon Sep 17 00:00:00 2001 From: zk Date: Thu, 23 Apr 2026 17:49:06 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8A=BD=E8=B1=A1json=E6=8F=90=E5=8F=96?= =?UTF-8?q?=E9=A3=8E=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .kiro/steering/代码开发风格文档.md | 6 ++++++ .kiro/steering/项目结构说明.md | 3 ++- app/ai/resume_diagnoser/diagnoser.py | 15 +++------------ app/ai/resume_extractor/extractor.py | 12 ++---------- app/ai/skill_gap_analyzer/analyzer.py | 20 ++++++-------------- app/tool/json_helper.py | 15 +++++++++++++++ 6 files changed, 34 insertions(+), 37 deletions(-) create mode 100644 app/tool/json_helper.py diff --git a/.kiro/steering/代码开发风格文档.md b/.kiro/steering/代码开发风格文档.md index 185ede6..f753dc2 100644 --- a/.kiro/steering/代码开发风格文档.md +++ b/.kiro/steering/代码开发风格文档.md @@ -140,6 +140,12 @@ inclusion: manual - AI 调用应做好异常捕获和容错，单次失败不应影响整体流程 - 长耗时 AI 调用考虑异步执行 +### AI 输出 JSON 解析 +- LLM 返回的 JSON 经常被 markdown 代码块（` ```json ... ``` `）包裹，**禁止**直接使用 LangChain 的 `JsonOutputParser` +- 统一使用 `app.tool.json_helper.parse_llm_json` 解析 AI 输出的 JSON 文本 +- `parse_llm_json` 会自动剥离 markdown 代码块标记，并通过 `json_repair` 做容错修复 +- **不要**在各模块中自行编写 JSON 清洗/解析逻辑，统一复用 `parse_llm_json` + ## 代码格式规范 ### 紧凑风格 diff --git a/.kiro/steering/项目结构说明.md b/.kiro/steering/项目结构说明.md index f47a607..8ba4053 100644 --- a/.kiro/steering/项目结构说明.md +++ b/.kiro/steering/项目结构说明.md @@ -64,6 +64,7 @@ offerpie_python_ai/ │ ├─ tool/ # **工具层**（无状态、无业务依赖的通用工具） │ ├─ file_parser.py # 文件解析工具（PDF/Word/TXT → 纯文本，parse_to_text 入口方法） + │ ├─ json_helper.py # AI 输出 JSON 解析工具（自动去除 markdown 代码块包裹 + json_repair 容错，parse_llm_json 入口方法） │ └─ snowflake.py # 雪花 ID 生成工具（next_id） │ ├─ schemas/ # **Schema 层**（Pydantic 请求/响应/缓存模型） @@ -84,7 +85,7 @@ offerpie_python_ai/ | **ai** | AI 模型管理 + 业务 AI 能力 | `LLM` 枚举、`resume_extractor/`（简历并行提取）、`resume_diagnoser/`（简历诊断）、`skill_gap_analyzer/`（技能差距分析 + 定制简历优化 + Agent 原子化规划 + 单条记录修改/新增） | | **api** | REST API 路由定义 | `health.py`（健康检查）、`resume.py`（简历上传解析）、`resume_diagnose.py`（简历诊断）、`skill_gap.py`（技能差距分析 + 定制简历） | | **models** | SQLAlchemy ORM 模型，与 Java 端共享同一数据库 | `FuncPermission`、`UserFuncPermissionStock`、`UserFuncUsageLog`、`UserResume`、`UserResumeEducation`/`Work`/`Internship`/`Project`/`Competition`、`ResumeDiagnosisReport`、`ResumeDiagnosisIssue`、`Job`（只读） | -| **tool** | 无状态通用工具，不依赖数据库/Redis/用户上下文 | `file_parser.py`（PDF/Word/TXT 文件解析为纯文本）、`snowflake.py`（雪花ID生成） | +| **tool** | 无状态通用工具，不依赖数据库/Redis/用户上下文 | `file_parser.py`（PDF/Word/TXT 文件解析为纯文本）、`json_helper.py`（AI 输出 JSON 解析，去 markdown 代码块 + json_repair 容错）、`snowflake.py`（雪花ID生成） | | **services** | 业务逻辑实现 | `FuncPermissionService`（功能权限校验、扣减、回退）、`ResumeParseService`（简历文件解析→AI结构化→入库）、`ResumeDiagnoseService`（简历诊断→AI并行分析→评级→入库）、`SkillGapService`（技能差距分析→定制简历生成/查询/编辑/回滚→AI对话编辑（原子化操作：delete直接删/update按记录并发/add并发生成）） | ## 3️⃣ 技术栈 diff --git a/app/ai/resume_diagnoser/diagnoser.py b/app/ai/resume_diagnoser/diagnoser.py index b70bf74..1026609 100644 --- a/app/ai/resume_diagnoser/diagnoser.py +++ b/app/ai/resume_diagnoser/diagnoser.py @@ -1,9 +1,6 @@ """简历诊断 AI 引擎：并行诊断 + 汇总评价""" import asyncio -import re - -from json_repair import repair_json from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate @@ -11,13 +8,7 @@ from langchain_core.prompts import ChatPromptTemplate from app.ai.models import LLM from app.ai.resume_diagnoser.prompts import DIAGNOSE_MODULE_PROMPT, SUMMARY_PROMPT, POLISH_PROMPT from app.core.logger import log - - -def _parse_json(text: str) -> dict: - """解析 AI 输出的 JSON，自动去除 markdown 代码块包裹，容错处理""" - cleaned = re.sub(r"^```(?:json)?\s*\n?", "", text.strip()) - cleaned = re.sub(r"\n?```\s*$", "", cleaned) - return repair_json(cleaned, return_objects=True) +from app.tool.json_helper import parse_llm_json # 诊断链（StrOutputParser 拿原始文本，再手动解析 JSON，避免 markdown 代码块导致解析失败） @@ -92,7 +83,7 @@ async def polish_content(module_type: str, reference_content: list[dict] | str | } try: raw = await _polish_chain.ainvoke(inp) - result = _parse_json(raw) + result = parse_llm_json(raw) if isinstance(result, list): return [str(item) for item in result] return [str(result)] @@ -106,7 +97,7 @@ async def _safe_invoke(task: dict) -> dict: raw = "" try: raw = await _diagnose_chain.ainvoke(task) - return _parse_json(raw) + return parse_llm_json(raw) except Exception as e: log.warning(f"AI诊断[{task.get('module_type', '')}]失败: {e}\n原始输出: {raw[:500]}") return _empty_result() diff --git a/app/ai/resume_extractor/extractor.py b/app/ai/resume_extractor/extractor.py index c05c1e5..7cadfa2 100644 --- a/app/ai/resume_extractor/extractor.py +++ b/app/ai/resume_extractor/extractor.py @@ -1,9 +1,7 @@ """简历并行提取：将完整简历文本拆分为5个AI任务并行提取""" import asyncio -import re -from json_repair import repair_json from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate @@ -13,13 +11,7 @@ from app.ai.resume_extractor.prompts import ( PROJECT_PROMPT, COMPETITION_PROMPT, ) from app.core.logger import log - - -def _parse_json(text: str) -> dict: - """解析 AI 输出的 JSON，自动去除 markdown 代码块包裹，容错处理""" - cleaned = re.sub(r"^```(?:json)?\s*\n?", "", text.strip()) - cleaned = re.sub(r"\n?```\s*$", "", cleaned) - return repair_json(cleaned, return_objects=True) +from app.tool.json_helper import parse_llm_json def _build_chain(prompt: str): @@ -65,7 +57,7 @@ async def _safe_invoke(chain, inp: dict, label: str): """单个链调用，失败返回空""" try: raw = await chain.ainvoke(inp) - return _parse_json(raw) + return parse_llm_json(raw) except Exception as e: log.warning(f"AI提取[{label}]失败: {e}") return {} if "个人信息" in label else [] diff --git a/app/ai/skill_gap_analyzer/analyzer.py b/app/ai/skill_gap_analyzer/analyzer.py index cf4f894..fc9a900 100644 --- a/app/ai/skill_gap_analyzer/analyzer.py +++ b/app/ai/skill_gap_analyzer/analyzer.py @@ -5,9 +5,7 @@ """ import asyncio -import re -from json_repair import repair_json from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate @@ -17,13 +15,7 @@ from app.ai.skill_gap_analyzer.prompts import ( AGENT_PLAN_PROMPT, AGENT_MODULE_EDIT_PROMPT, AGENT_MODULE_ADD_PROMPT, MODULE_SCHEMAS, ) from app.core.logger import log - - -def _parse_json(text: str): - """解析 AI 输出的 JSON，自动去除 markdown 代码块包裹，容错处理""" - cleaned = re.sub(r"^```(?:json)?\s*\n?", "", text.strip()) - cleaned = re.sub(r"\n?```\s*$", "", cleaned) - return repair_json(cleaned, return_objects=True) +from app.tool.json_helper import parse_llm_json # ===== 差距分析 ===== @@ -39,7 +31,7 @@ async def analyze_skill_gap(skill_tags: list[str], resume_json: str) -> list[str """分析技能差距，返回缺失技能列表""" try: raw = await _skill_gap_chain.ainvoke({"skill_tags": str(skill_tags), "resume_json": resume_json}) - result = _parse_json(raw) + result = parse_llm_json(raw) if isinstance(result, list): return [s for s in result if isinstance(s, str) and s in skill_tags] return skill_tags # 解析异常降级：全部标记缺失 @@ -85,7 +77,7 @@ async def optimize_module(job_title: str, job_description: str, module_data: str "job_title": job_title, "job_description": job_description or "", "original_module_data": module_data, }) - return _parse_json(raw) + return parse_llm_json(raw) except Exception as e: log.warning(f"AI优化经历模块失败: {e}") return None @@ -109,7 +101,7 @@ async def plan_edit(job_title: str, job_description: str, resume_json: str, "resume_json": resume_json, "chat_history": chat_history, "instruction": instruction, }) - result = _parse_json(raw) + result = parse_llm_json(raw) return result if isinstance(result, dict) else None except Exception as e: log.warning(f"AI规划失败: {e}") @@ -135,7 +127,7 @@ async def execute_record_edit(job_title: str, job_description: str, instruction: "instruction": instruction, "chat_history": chat_history, "module_schema": module_schema, "record_data": record_data, }) - return _parse_json(raw) + return parse_llm_json(raw) except Exception as e: log.warning(f"AI单条记录修改失败: {e}") return None @@ -159,7 +151,7 @@ async def execute_record_add(job_title: str, job_description: str, instruction: "instruction": instruction, "chat_history": chat_history, "module_schema": module_schema, }) - result = _parse_json(raw) + result = parse_llm_json(raw) return result if isinstance(result, dict) else None except Exception as e: log.warning(f"AI新增记录失败: {e}") diff --git a/app/tool/json_helper.py b/app/tool/json_helper.py new file mode 100644 index 0000000..1ea07f5 --- /dev/null +++ b/app/tool/json_helper.py @@ -0,0 +1,15 @@ +"""AI 输出 JSON 解析工具 + +将 LLM 返回的可能带 markdown 代码块包裹的文本解析为 Python 对象。 +""" + +import re + +from json_repair import repair_json + + +def parse_llm_json(text: str): + """解析 AI 输出的 JSON，自动去除 markdown 代码块包裹，容错处理""" + cleaned = re.sub(r"^```(?:json)?\s*\n?", "", text.strip()) + cleaned = re.sub(r"\n?```\s*$", "", cleaned) + return repair_json(cleaned, return_objects=True)