# 科情客服智能知识库

基于钉钉 AI 表格「科情OA知识库数据梳理」+ 钉钉知识库双数据源构建的**客服智能知识库**。
面向客服机器人 / AI Agent / 客服人员：**准确定位问题 → 引用权威答案 → 精准回答**。

## 产品形态

| 组件 | 路径 | 说明 |
|------|------|------|
| **数据层** | `knowledge/` | 3557 条结构化知识条目（单一事实源） |
| **采集层** | `scripts/` | 钉钉同步 / 清洗 / 索引脚本 |
| **Web 门户** | `portal/` | VitePress 站点（浏览器访问、搜索、分类树） |
| **API 服务** | `server/` | REST API + MCP Server（供系统与 AI Agent 调用） |
| **AI 能力(v2)** | `ai/` | LLM 清洗打标 + Embedding 向量检索 + 混合检索 RAG 问答 |
| **客服 Widget(v2)** | `widget/` | 官网悬浮客服（任意网页一行引入） |
| **CI/CD** | `.github/workflows/` | 自动构建门户并发布 GitHub Pages |

## 快速开始

### 1. 浏览门户

```bash
cd portal
pnpm install
pnpm run dev        # 本地预览 http://localhost:5173
pnpm run build      # 构建静态站点 → .vitepress/dist
```

### 2. 调用 API

```bash
cd server
npm install
npm run api         # REST API → http://localhost:8787

# 检索示例
curl "http://localhost:8787/api/search?q=U8%20登录失败&top_k=5"
curl "http://localhost:8787/api/stats"
```

### 3. 调用 MCP（供 AI Agent）

```bash
cd server
npm run mcp         # stdio MCP Server
```

客户端配置：
```json
{ "mcpServers": { "kb": { "command": "node", "args": ["<仓库路径>/server/src/mcp.mjs"] } } }
```

### 4. 命令行查询

```bash
cd scripts
python3 query.py "客户提问的问题描述"      # 全文检索 Top-5
python3 query.py --keyword "WebView2"    # 关键词检索
python3 query.py --id FX-20221130-059    # 精确获取
```

### 5. RAG 智能问答（v2，需 AI Key）

```bash
cd ai/..  # 仓库根目录
pip install -r requirements-ai.txt
cp .env.example .env                      # 填写 LLM/Embedding Key
python3 scripts/build_vectors.py          # 构建向量索引（全量约几分钟）
python3 ai/api.py --port 8800             # 启动 RAG 服务

# 客服问答（带引用）
curl -X POST http://localhost:8800/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"U8 登录失败"}'

# LLM 清洗分类打标（产出建议标签，供审核回写）
python3 scripts/llm_tag.py --limit 50
```

### 6. 官网接入客服 Widget（v2）

```html
<script>window.KBWidgetConfig = { apiBase: "http://localhost:8800" }</script>
<script src="/kb-widget.js" defer></script>
```

> 注意：项目根目录的 `启动kb服务.bat` 仅拉起 API / 门户 / 机器人，**不含 RAG(:8800) 与 控制台(:8900)**，需按本节命令另行启动。

详见 [RAG 服务部署指南](docs/rag-deployment.md)。

### 7. 知识管理后台（v2，人工收录）

成员可上传任意格式资料，系统 LLM 自动打标生成草稿，人工审核后入库并自动重建索引/门户/向量：

```bash
python3 admin/server.py --port 8900   # 需先在 .env 配置 KB_ADMIN_TOKEN
# 浏览器打开 http://localhost:8900/admin/
```

详见 [管理后台指南](docs/admin-guide.md)。

### 8. 钉钉客服机器人（v2，RAG 智能问答）

内置机器人 `小福` 已升级为 RAG 智能问答（单聊 + 群聊 @触发，附引用来源，RAG 不可用自动回退检索）：

```bash
python scripts/bot_xiaofu.py --mode both        # Windows；默认进程守护（supervisor 守护 worker，断线自动重连）
# 或统一用 启动kb服务.bat 一键拉起 API/门户/机器人
```

详见 [机器人集成指南](docs/robot-integration.md)。

## 维护流程

```bash
# 1. 从钉钉同步最新数据
bash scripts/sync_from_dingtalk.sh

# 2. 重建索引
python3 scripts/build_index.py

# 3. 重建向量索引（RAG 检索用，同步后必跑；后台入库会自动增量）
python3 scripts/build_vectors.py

# 4. 重新生成门户页面
cd portal && node scripts/generate.mjs

# 5. 构建并提交
cd portal && pnpm run build
cd .. && git add -A && git commit -m "同步最新知识" && git push
```

## 目录结构

```
kb/
├── raw/                    # 原始采集数据（只读）
├── knowledge/              # 清洗后知识库（entries + docs + tags + index + markdown + ai/）
├── scripts/                # 采集/清洗/索引/查询/打标脚本
│   ├── llm_tag.py          # LLM 清洗分类打标（v2，产建议标签）
│   └── build_vectors.py    # 向量索引构建（v2）
├── ai/                     # AI 能力（v2，Python，多服务商）
│   ├── llm.py              # LLM 客户端（OpenAI 兼容）
│   ├── embeddings.py       # Embedding 客户端
│   ├── vector_index.py     # 条目向量检索（numpy 余弦，增量构建）
│   ├── doc_index.py        # 文档切块向量检索（文档库专用）
│   ├── lexical.py          # 词法检索（移植 core.mjs 逻辑）
│   ├── rag.py              # 混合检索（条目词法/向量 + 文档词法/向量四路 RRF）+ RAG 问答编排
│   └── api.py              # RAG REST 服务（:8800）
├── admin/                  # 知识管理后台（v2，:8900）
│   ├── parse_docs.py       # 格式解析（txt/md/csv/docx/pptx/pdf/xlsx）
│   ├── doclib.py           # 文档库：上传归档 → 切块 → 向量化
│   ├── taglib.py           # 自伸缩标签词表 + 大模型标注（条目/文档/切片）
│   ├── drafts.py           # 草稿存取（上传 → LLM 打标 → 人工审核）
│   ├── ingest.py           # 上传 + LLM 结构化打标
│   ├── import_entry.py     # 审核入库 + 重建索引/向量
│   └── static/             # 后台单页前端（index.html + admin.js）
├── widget/                 # 官网客服 Widget（v2，任意页面引入）
├── config/                 # ai.json 多服务商配置（不含 Key）
├── portal/                 # VitePress Web 门户
│   ├── scripts/generate.mjs  # 知识条目 → 门户页面生成器
│   └── docs/                 # 生成的站点页面
├── server/                 # API 服务（REST + MCP）
│   └── src/
│       ├── core.mjs        # 检索核心（共享）
│       ├── api.mjs         # REST API
│       └── mcp.mjs         # MCP Server
├── docs/                   # 使用文档（机器人集成、RAG 部署、后台指南等）
└── .github/workflows/      # CI 部署
```

## 设计原则

1. **单一事实源**：钉钉端数据源是权威，本地知识库是投影
2. **双向同步**：增量拉取 → 清洗/分类/索引；本地修正可回写
3. **自进化**：每次同步自动发现新增/修改/删除，增量更新
4. **机器可读 + 人可读**：JSON 供程序消费，Markdown/门户供人阅读
5. **引用可溯源**：每条知识携带来源（钉钉文档 URL / 表格记录），回答必须引用
6. **多人协作**：Git 版本管理 + PR 审查 + 自动发布

## 详细文档

- [使用文档](docs/USAGE.md)
- [机器人集成指南](docs/robot-integration.md)
- [RAG 服务部署指南](docs/rag-deployment.md)
- [管理后台指南](docs/admin-guide.md)
- [门户使用指南](portal/docs/guide/)
- [API 文档](portal/docs/api/)
- [维护手册](portal/docs/maintain/)