docs: add aftersales agent llm configuration

docs/superpowers/specs/2026-07-08-enterprise-aftersales-agent-design.md

@@ -82,6 +82,89 @@ GET  /api/v1/agent/runs/{trace_id}
 GET  /health
 ```
 
+## LLM 配置
+
+LLM 运行配置归属 Python `zsElectric-agent-service`。Java `zsElectric-boot` 不直接调用大模型，Java 只作为 MCP Server 暴露受控企业工具。这样模型供应商、模型版本、prompt、RAG 参数和工具调用上限都集中在 Agent 编排层管理。
+
+首版使用显式模型配置，不依赖 SDK 默认值。默认建议：
+
+```text
+主 Agent 模型: gpt-5.5
+快速分类/意图模型: gpt-5.4-mini
+Embedding 模型: text-embedding-3-small
+Embedding 维度: 1536
+```
+
+`gpt-5.5` 用于最终建议生成、复杂售后判断和审批前说明；`gpt-5.4-mini` 用于意图分类、轻量改写、简单摘要等低成本步骤。后续如果模型升级，只改配置和评估基线，不改业务工具协议。
+
+Python `.env` 示例：
+
+```dotenv
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_DEFAULT_MODEL=gpt-5.5
+
+AGENT_MAIN_MODEL=gpt-5.5
+AGENT_FAST_MODEL=gpt-5.4-mini
+AGENT_TEMPERATURE=0.2
+AGENT_REASONING_EFFORT=medium
+AGENT_MAX_TURNS=8
+AGENT_TIMEOUT_SECONDS=60
+AGENT_TOOL_TIMEOUT_SECONDS=15
+
+EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_DIMENSIONS=1536
+RAG_TOP_K=5
+RAG_MIN_SCORE=0.75
+RAG_MAX_CONTEXT_TOKENS=3000
+
+MCP_SERVER_URL=http://localhost:8080/api/v1/agent/mcp
+MCP_CONNECT_TIMEOUT_SECONDS=5
+MCP_READ_TIMEOUT_SECONDS=30
+```
+
+Python `settings.yaml` 示例：
+
+```yaml
+llm:
+  provider: openai
+  base_url: ${OPENAI_BASE_URL}
+  default_model: ${OPENAI_DEFAULT_MODEL}
+  agents:
+    aftersales_main:
+      model: ${AGENT_MAIN_MODEL}
+      temperature: ${AGENT_TEMPERATURE}
+      reasoning_effort: ${AGENT_REASONING_EFFORT}
+      max_turns: ${AGENT_MAX_TURNS}
+      timeout_seconds: ${AGENT_TIMEOUT_SECONDS}
+    intent_classifier:
+      model: ${AGENT_FAST_MODEL}
+      temperature: 0
+      timeout_seconds: 20
+  embedding:
+    model: ${EMBEDDING_MODEL}
+    dimensions: ${EMBEDDING_DIMENSIONS}
+
+rag:
+  top_k: ${RAG_TOP_K}
+  min_score: ${RAG_MIN_SCORE}
+  max_context_tokens: ${RAG_MAX_CONTEXT_TOKENS}
+
+mcp:
+  server_url: ${MCP_SERVER_URL}
+  connect_timeout_seconds: ${MCP_CONNECT_TIMEOUT_SECONDS}
+  read_timeout_seconds: ${MCP_READ_TIMEOUT_SECONDS}
+```
+
+配置边界：
+
+- API Key 只允许放在环境变量或密钥管理系统，不写入仓库。
+- `AGENT_MAIN_MODEL`、`AGENT_FAST_MODEL`、`EMBEDDING_MODEL` 必须在启动日志中打印脱敏后的配置摘要，便于排查环境差异。
+- 每次 Agent run 要把 `model_provider`、`model_name`、`prompt_version`、`rag_top_k`、`rag_min_score`、`token_usage` 写入审计日志。
+- `EMBEDDING_DIMENSIONS` 必须与 `aftersales_policy_chunk.embedding VECTOR(...)` 一致，不一致时服务启动失败。
+- 高风险工具不允许仅靠 prompt 约束，必须由 Java MCP Server 的风险等级和审批逻辑兜底。
+- 生产环境模型变更必须跑 eval 数据集，确保意图判断、风险分级、审批触发和最终回复没有回归。
+
 ## MCP 工具
 
 首版工具清单：
@@ -294,6 +377,10 @@ CREATE TABLE agent_audit_log (
   event_type VARCHAR(64) NOT NULL COMMENT '事件类型',
   tool_name VARCHAR(128) NULL COMMENT '工具名',
   risk_level VARCHAR(16) NULL COMMENT '风险等级',
+  model_provider VARCHAR(64) NULL COMMENT '模型供应商，如openai',
+  model_name VARCHAR(128) NULL COMMENT '实际调用模型名',
+  prompt_version VARCHAR(64) NULL COMMENT 'Prompt版本',
+  token_usage_json JSON NULL COMMENT 'Token用量',
   input_json JSON NULL COMMENT '输入快照，敏感字段脱敏后保存',
   output_json JSON NULL COMMENT '输出快照，敏感字段脱敏后保存',
   status VARCHAR(32) NOT NULL COMMENT '状态: success, failed, pending, skipped',
@@ -306,11 +393,12 @@ CREATE TABLE agent_audit_log (
   KEY idx_agent_audit_approval (approval_id),
   KEY idx_agent_audit_action (pending_action_id),
   KEY idx_agent_audit_tool_time (tool_name, create_time),
+  KEY idx_agent_audit_model_time (model_name, create_time),
   KEY idx_agent_audit_status_time (status, create_time)
 ) COMMENT='Agent全链路审计日志表';
 ```
 
-审计步骤包括用户输入、意图判断、RAG 命中文档、工具调用、审批创建、审批结果、恢复执行和最终回复。
+审计步骤包括用户输入、LLM 配置快照、意图判断、RAG 命中文档、工具调用、审批创建、审批结果、恢复执行和最终回复。
 
 ### aftersales_work_order
 
@@ -504,6 +592,8 @@ Python FastAPI 测试：
 - `/resume/{approval_id}` 审批后恢复执行。
 - MCP client 工具调用失败。
 - RAG 无命中降级。
+- LLM 配置加载、默认模型、快速模型、embedding 维度一致性测试。
+- 模型变更后的 eval 数据集回归测试。
 
 集成演示：
 
@@ -521,7 +611,7 @@ Python FastAPI 测试：
 
 ### M2 Python FastAPI Agent
 
-交付 FastAPI 服务、OpenAI Agents SDK agent、MCP client、基础 RAG 检索、`/chat` 和 `/resume`。
+交付 FastAPI 服务、OpenAI Agents SDK agent、LLM 配置管理、MCP client、基础 RAG 检索、`/chat` 和 `/resume`。
 
 ### M3 售后业务闭环
 
@@ -540,4 +630,6 @@ Python FastAPI 测试：
 - 审批通过后可以按 `approval_id` 恢复执行。
 - 审批拒绝、审批过期、重复恢复、参数篡改都有确定结果。
 - 每次 Agent 运行都能通过 `trace_id` 查到完整审计链路。
+- 每次 Agent 运行都能在审计日志中看到实际模型、prompt 版本、RAG 参数和 token 用量。
+- Embedding 模型维度与 pgvector 表结构不一致时，Python 服务启动失败。
 - 项目文档能解释 RAG、MCP Tool Calling、权限、审批、状态恢复、审计和测试案例。