Document AI retrieval chunk audit requirement

ai_knowledge_base_v2/development_records/2026-07-09-record-audit-llm-retrieval-chunks.md

@@ -0,0 +1,35 @@
+# 记录审计展示 LLM 召回知识片段
+
+日期：2026-07-09
+
+## 需求背景
+
+当前“记录审计”能看到 AI 请求使用了哪些知识库 ID、命中了多少条、最终 Prompt 是什么，但看不到大模型请求前实际召回了哪些知识库片段。排查回答质量时，只能从 Prompt 或知识库 ID 反推，无法快速判断问题出在“召回范围不对”“召回内容不准”还是“模型生成不符合预期”。
+
+## 本次目标
+
+- AI 请求日志需要保存当次请求实际召回的知识片段快照。
+- 管理后台“记录审计”需要能查看这些片段。
+- 聊天详情里的关联 AI 请求，也要能查看对应片段。
+- 片段展示用于排查问题，不重新触发搜索，避免知识库更新后影响历史审计结果。
+
+## 设计决策
+
+- 后端在写入 `sys_ai_request_log` 时同步保存召回片段快照。
+- 快照字段采用 JSON 文本保存，便于兼容当前 MySQL/SQLite 开发环境，也便于后续扩展字段。
+- 单个片段保留：
+  - 知识库 ID
+  - 知识库名称
+  - 片段标题
+  - 片段正文
+  - 来源链接
+  - 序号
+- 前端列表页不直接展开大段正文，避免记录页被长文本撑乱；通过表格展开行和聊天详情折叠区查看。
+
+## 验收标准
+
+- 新产生的 AI 请求日志中应包含 `retrievedChunks`。
+- 管理后台“记录审计 > AI 请求”可以展开查看召回片段。
+- 聊天详情抽屉中，每个关联 AI 请求可以查看召回片段。
+- 没有召回片段或历史旧日志没有片段时，应显示明确空状态，不影响页面加载。
+- 不展示 API Key 等模型敏感配置。