装闭 RenoPit 源码解析（07）：装修闭坑知识库与AI Prompt构建

装闭 RenoPit 并不是只把装修图片交给大模型自由发挥。它会先把本地装修坑位、消费者立场和 JSON 输出格式写入系统 Prompt，再附上用户说明和文档内容。相关源码位于开源仓库 fthux/RenoPit，本篇分析这套 Prompt 是怎样拼装出来的。

一、知识库独立于 Python 代码

装修知识保存在 backend/app/data/pitfalls.json，prompt_builder.py 只负责读取和格式化。设计分析主要使用五类检查项：

cleaning_blindspots：卫生死角；
space_oppression：空间压迫；
pseudo_needs：实用性伪需求；
hidden_costs：隐性成本；
safety_health：安全与健康。

合同分析另外读取 billing_traps、contract_clauses 和 extra_item_patterns。知识内容与 Prompt 模板分离后，同一份 JSON 可以被设计分析、合同分析和增项预测重复使用。

二、PitfallsLoader 如何加载数据

PitfallsLoader 接收一个可选路径，默认指向项目内的 pitfalls.json。第一次调用 load() 时执行 json.load()，结果缓存在实例的 _data 中，后续读取不再重复打开文件。

get_category_items() 把类别下的 items 转换成项目符号文本：

python 复制代码

lines = []
for item in items:
    lines.append(f"- {item['description']}")
return "\n".join(lines)

如果类别不存在或没有条目，则返回"无数据"占位。Prompt 模板因此总能获得字符串，不需要在模板层判断空值。

三、系统 Prompt 如何确定 AI 角色

SYSTEM_PROMPT_TEMPLATE 首先把模型定义为站在消费者一方的家装监理，要求它主动揭露增加预算、降低实用性或隐藏长期成本的设计。随后插入五类本地检查清单，并规定分析步骤和输出结构。

build_system_prompt() 负责取得每类文本并格式化模板：

python 复制代码

return SYSTEM_PROMPT_TEMPLATE.format(
    cleaning_blindspots=cleaning_blindspots,
    space_oppression=space_oppression,
    pseudo_needs=pseudo_needs,
    hidden_costs=hidden_costs,
    safety_health=safety_health,
    web_search_section=web_search_section,
)

这里不仅告诉模型"检查装修问题"，还要求返回 summary、problems 等固定 JSON 字段。每个问题需要包含标题、位置、批判说明、套路解释、替代方案和可选坐标。后端的 JSON 校验器正是按照这份契约接收结果。

四、联网搜索如何进入 Prompt

ENABLE_WEB_SEARCH 由环境变量控制。开启后，build_system_prompt() 会在模板中加入 WEB_SEARCH_SECTION，要求模型针对新材料、新工艺和最新装修套路补充检索结果。

Prompt 指令和 API 工具是两层机制：系统 Prompt 可以向所有 OpenAI 兼容模型表达检索要求；真正的 web_search_preview 工具只会在 LLM 服务判断当前地址为 OpenAI 官方 API 时加入请求。其他兼容端点不会收到不支持的 tools 参数。

五、用户消息如何组合

图片不会写入字符串，而是在 LLM 服务中作为多模态内容发送。build_user_message() 只负责文本部分，输入来源有两类：

input_text：用户在项目中填写的装修需求；
extracted_texts：从合同、报价单、TXT 或 PDF 中提取的文本。

用户说明会被限制在 MAX_INPUT_TEXT_LENGTH 内。文档文本则按照真实文件名分段：

text 复制代码

## 用户描述
主卧需要衣帽间，厨房计划增加岛台......

## 上传文件内容（装修报价单.pdf）
......

当没有任何文本时，函数生成一条默认指令，让模型根据已上传图片逐项检查知识库。

六、不同任务使用不同 Prompt

设计图、合同和报价单并不共用同一个输出模板：

build_system_prompt()：输出综合装修问题；
build_document_analysis_prompt()：输出报价陷阱、合同条款和增项风险；
build_extra_prediction_prompt()：把报价单分析结果再次注入，预测后续增项；
build_cross_check_prompt()：组合多份文档摘要，要求找出相互矛盾之处。

它们共用 PitfallsLoader，但分别规定任务角色、输入信息和 JSON Schema。这样后端可以为不同结果使用不同校验函数和数据库字段。

七、Prompt 构建链路小结

RenoPit 的 Prompt 由"消费者立场、任务步骤、本地知识库、联网搜索说明、输出 JSON 契约、用户真实素材"共同构成。大模型看到的不是一句宽泛问题，而是一份带检查清单和交付格式的分析任务书。

完整模板和知识库可以在 fthux/RenoPit 中查看。下一篇将继续追踪这些 Prompt 如何被转换成 OpenAI 兼容请求，以及多模态调用失败后如何重试并降级到纯文本路径。