统一抽象 封装 模型配置配置管理

.kiro/steering/代码开发风格文档.md

@@ -135,11 +135,32 @@ inclusion: manual
 
 ## AI 调用规范
 
-- 通过 `LLM` 枚举创建模型实例：`LLM.DEEPSEEK_V3.create(temperature=0)`
-- kwargs 透传给 LangChain `ChatOpenAI`（temperature、max_tokens 等）
+- 业务代码**不直接使用** `LLM` 枚举，而是从 `app.ai.model_config` 中引用对应模块的场景配置类
+- `model_config.py` 中每个模块一个 class，每个场景一个类属性，属性值为预创建的 `ChatOpenAI` 实例
+- 修改模型或调整参数只需改 `model_config.py` 一个文件，业务代码不动
 - AI 调用应做好异常捕获和容错，单次失败不应影响整体流程
 - 长耗时 AI 调用考虑异步执行
 
+### 模型引用示例
+```python
+from app.ai.model_config import SkillGapModel
+
+# chain 中直接使用配置类属性（已经是 ChatOpenAI 实例）
+_plan_chain = (
+    ChatPromptTemplate.from_messages([...])
+    | SkillGapModel.AGENT_PLAN
+    | StrOutputParser()
+)
+
+# 非 chain 场景直接 await 调用
+result = await JobAgentModel.CHAT.ainvoke(messages)
+```
+
+### 新增 AI 场景步骤
+1. 在 `app/ai/model_config.py` 对应模块的 class 中新增一个类属性，指定模型和参数
+2. 在业务代码中 `from app.ai.model_config import XxxModel`，引用该属性
+3. 如需新增模块，在 `model_config.py` 中新建一个 class
+
 ### AI 输出 JSON 解析
 - LLM 返回的 JSON 经常被 markdown 代码块（` ```json ... ``` `）包裹，**禁止**直接使用 LangChain 的 `JsonOutputParser`
 - 统一使用 `app.tool.json_helper.parse_llm_json` 解析 AI 输出的 JSON 文本