diff --git a/ai_knowledge_base_v2/development_records/2026-07-08-user-chat-agent-alignment.md b/ai_knowledge_base_v2/development_records/2026-07-08-user-chat-agent-alignment.md
new file mode 100644
index 0000000..e194d84
--- /dev/null
+++ b/ai_knowledge_base_v2/development_records/2026-07-08-user-chat-agent-alignment.md
@@ -0,0 +1,28 @@
+# 用户端问答与后台 Agent 调试链路对齐
+
+## 问题现象
+
+用户端 H5 提问后，返回内容只是把已开放知识库中的片段直接拼接输出，缺少模型加工和 Agent 风格回答；后台 Agent 调试页面则能按模型、Prompt 和知识库进行调试回答。
+
+## 根因
+
+用户端问答链路 `ModelClientService.complete` 仍然读取部署环境变量 `MOCK_MODEL_ENABLED`，没有读取后台“系统设置”中的 `mock_model_enabled`。
+
+因此即使后台系统设置已经保存，用户端仍可能继续走 mock 分支。mock 分支当前会直接拼接检索片段，这会造成“像是把完整知识库原样输出”的体验。
+
+另外，用户端问答只会使用“模型管理”中已启用的模型；后台 Agent 调试可以临时选择任意模型进行测试。两者需要在产品口径上区分：
+
+- 后台 Agent 调试：用于配置、验证和调参。
+- 用户端 H5 问答：使用当前已启用模型和当前生效 Prompt 对外回答。
+
+## 调整决定
+
+1. 用户端问答的模型 mock 开关改为优先读取 `sys_system_config.mock_model_enabled`。
+2. 如果系统设置关闭 mock，但模型管理中没有启用模型，则用户端返回明确错误，提示管理员启用模型。
+3. 用户端真实回答继续使用已启用模型、当前 Prompt 和已开放知识库检索结果，保证与后台 Agent 调试的正式模型调用方式一致。
+
+## 验收口径
+
+- 后台系统配置将“使用 mock 大模型”关闭后，用户端不再输出 mock 拼接内容。
+- 模型管理中启用一个模型后，用户端提问应调用该模型生成回答。
+- 如果未启用模型，用户端应显示明确配置错误，而不是输出知识库原文。