# 来源标注徽章实现方案

## 问题描述

在合规审查助手等应用中，用户看不到回复中的**知识库来源徽章**和**AI建议徽章**，无法区分内容来自知识库还是AI自身知识。

## 解决方案

采用**三层实现方案**：

### 1. 后端系统提示词强化（已完成）

**文件**：`server/internal/handler/chat_llm.go` - `buildMessages()` 方法

**改进内容**：
- 增强了系统提示词中的来源标注要求
- 明确指出每一句话、每一个列表项都必须标注来源
- 添加了"关键提醒"部分，说明系统会自动补充缺失的标注
- 特别强调清单、问卷、检查表等列表格式的内容必须逐项标注

**格式要求**：
- 知识库引用：`[[知识库:文献名称]]` → 渲染为蓝色徽章
- AI建议：`[[AI建议]]` → 渲染为橙色徽章

### 2. 后端自动标注增强（已完成）

**文件**：`server/internal/handler/chat_llm.go` - `enhanceCitations()` 等方法

**改进内容**：

#### a) 改进的标注检测逻辑
- 检测所有以句号、问号、感叹号结尾的陈述句
- 检测所有列表项（`-`、`*`、数字列表），无论是否以标点符号结尾
- 这解决了之前清单项目（如"是否所有员工均签订了书面劳动合同？"）没有被标注的问题

#### b) 统一的来源说明块处理
- 在 `enhanceCitations()` 中统一处理来源说明块的添加
- 确保所有回复末尾都有来源汇总块，包括已有标注的回复

#### c) 智能标注决策
- 对于长内容（>100字）或包含"建议"、"注意"、"可以"等词的内容，标注为 `[[AI建议]]`
- 对于短内容且有知识库的情况，标注为 `[[知识库:xxx]]`

### 3. 前端徽章渲染（已存在，无需修改）

**文件**：`apps/web/src/components/ui/gov-markdown.tsx`

**现有功能**：
- `preprocessCitations()` 函数将 `[[知识库:xxx]]` 转换为 `[xxx](#cite-kb)` 链接
- `preprocessCitations()` 函数将 `[[AI建议]]` 转换为 `[AI建议](#cite-ai)` 链接
- Markdown 渲染器的 `a` 组件拦截这些特殊链接并渲染为彩色徽章
- 知识库徽章：蓝色背景 + BookOpen 图标
- AI建议徽章：橙色背景 + BrainCircuit 图标

## 工作流程

```
用户输入
    ↓
后端检索知识库 → 获取相关文献
    ↓
构建系统提示词 → 包含强化的标注要求
    ↓
调用 LLM 生成回复
    ↓
后端后处理 (enhanceCitations)
  ├─ 检查是否有标注
  ├─ 如果没有标注 → 自动添加
  ├─ 如果有部分标注 → 补充缺失的
  └─ 确保末尾有来源说明块
    ↓
流式返回给前端
    ↓
前端 GovMarkdown 组件
  ├─ 预处理：转换标注格式
  ├─ 渲染：Markdown → HTML
  └─ 徽章渲染：特殊链接 → 彩色徽章
    ↓
用户看到带有来源徽章的回复
```

## 测试覆盖

**文件**：`server/internal/handler/chat_llm_test.go`

**测试用例**：
1. ✅ 清单格式 - 为每个问题添加标注
2. ✅ 列表项 - 为每个列表项添加标注（无论是否以标点符号结尾）
3. ✅ 数字列表 - 为每个列表项添加标注
4. ✅ 陈述句 - 为陈述句添加标注
5. ✅ 无知识库 - 添加AI建议标注
6. ✅ 已有标注 - 不重复添加，但确保有来源说明块

## 效果示例

### 之前（无徽章）
```
劳动用工合规审查清单
一、劳动合同管理
劳动合同签订

是否所有员工均签订了书面劳动合同？
合同内容是否符合《劳动合同法》的相关规定？
```

### 之后（有徽章）
```
劳动用工合规审查清单
一、劳动合同管理
劳动合同签订

是否所有员工均签订了书面劳动合同？ [[AI建议]]
合同内容是否符合《劳动合同法》的相关规定？ [[AI建议]]

---

> **来源说明**
> 
> **AI建议：**
> - 清单项目和检查问题
```

前端会将 `[[AI建议]]` 渲染为橙色徽章，用户可以清楚看到内容来源。

## 关键改进点

1. **列表项检测改进**：之前只检查以标点符号结尾的行，现在所有列表项都会被标注
2. **来源说明块统一处理**：确保所有回复都有来源汇总块
3. **系统提示词强化**：更明确地要求 LLM 遵守标注规则
4. **自动补充机制**：即使 LLM 没有完全遵守，后端也会自动补充缺失的标注

## 下一步优化方向

1. **方案B升级**：修改后端返回结构化数据，包含来源元数据
2. **再生成功能**：实现"重新生成"按钮，保留原有的来源标注
3. **来源溯源**：支持点击徽章查看完整的知识库原文
4. **统计分析**：追踪知识库引用率，优化知识库内容

## 修改文件列表

- `server/internal/handler/chat_llm.go` - 增强标注逻辑和系统提示词
- `server/internal/handler/chat_llm_test.go` - 新增测试用例（6个）

## 验证方式

```bash
# 运行测试
cd server
go test ./internal/handler -v -run TestEnhanceCitations

# 编译检查
go build -o /tmp/test-build ./cmd/server/
```

所有测试通过，代码编译成功。