# GitLink 帮助中心 AI 智能助手

> 对应课程「任务五：新功能特性」的实现 —— 一个可在页面任意拖动、与用户交互、
> 回答内容**只来自帮助中心文档**的 AI 助手；与帮助中心无关的问题会回复「无关」。

---

## 一、这个 AI 工具需要 API 吗？

**需要。** 要让助手真正「听懂」自然语言、判断问题是否与帮助中心相关、并基于文档
生成自然流畅的回答，必须接入一个大语言模型（LLM）。

- 纯关键词匹配无法可靠地判断「无关」，也无法生成通顺的回答，所以本项目接入了 LLM。
- 本助手兼容任何 **OpenAI `/v1/chat/completions` 协议**的服务，例如：
  - DeepSeek（默认推荐，国内可直连、便宜）：`https://api.deepseek.com/v1`，模型 `deepseek-chat`
  - 通义千问：`https://dashscope.aliyuncs.com/compatible-mode/v1`，模型 `qwen-plus`
  - 智谱 GLM：`https://open.bigmodel.cn/api/paas/v4`，模型 `glm-4-flash`
  - Moonshot / OpenAI 等

> **API Key 安全说明（重要）**：密钥**不会写入任何代码文件、不会提交到代码仓库、不会上传到远端**。
> 你只需在助手界面的「⚙ 设置」里粘贴一次，密钥只保存在**你当前浏览器的 localStorage** 中。
> 因此 `git push` 时绝不会泄露密钥。

---

## 二、如何使用（填入你的 API Key）

1. 启动项目：
   ```bash
   npm install --legacy-peer-deps      # 安装依赖（已安装可跳过）
   npm run build:kb                     # 生成知识库 knowledge.json（文档更新后重跑）
   npm run dev                          # 开发预览：http://localhost:3000
   # 或生产构建：npm run build -- --locale zh-cn && npm run serve
   ```
2. 打开页面后，右下角会出现一个蓝色 **AI** 圆形按钮。
3. **拖拽**：按住按钮可拖到屏幕任意位置（位置会被记住）。
4. **点击**按钮打开聊天面板 → 点右上角 **⚙ 设置**。
5. 在设置里：
   - 点一个「服务厂商」快捷按钮（或手动填 Base URL / 模型名）；
   - 在 **API Key** 框粘贴你的密钥（如 DeepSeek 的 `sk-...`）；
   - 点「保存」。
6. 回到聊天框提问即可。例如：
   - 「如何创建代码仓库？」→ 基于文档回答并附 `📎 相关文档` 链接
   - 「什么是疑修？」→ 基于文档回答
   - 「今天天气怎么样？」→ 回复「无关」（与帮助中心无关）

---

## 三、工作原理（轻量 RAG）

```
用户提问
   │
   ▼
① 客户端检索 (retrieval.js, BM25)  ── 扫描 knowledge.json (来自 docs/)
   │      └─ 完全检索不到任何相关内容 → 直接回复「无关」(不调用模型，省 token)
   ▼
② 取最相关的 4 段文档作为「上下文」
   ▼
③ 调用大模型 (llm.js) + 强约束系统提示：只能依据上下文回答，无关则回「无关」
   ▼
④ 流式输出回答；若上下文含文档路径，附「📎 相关文档」可点击跳转
```

- **回答来源严格限定**：系统提示词强制模型「只能用提供的帮助中心资料回答」，
  资料外的问题一律回「无关」，从而满足「回答都来自帮助中心文档」的要求。
- **知识库**：`scripts/build-knowledge.js` 扫描 `docs/` 下全部 Markdown，按标题切分、
  去噪，生成 `knowledge.json`。文档有更新时重新执行 `npm run build:kb` 即可。

---

## 四、文件清单

| 文件 | 作用 |
|------|------|
| `src/components/AIAssistant/index.js` | 主组件：可拖拽浮动按钮 + 聊天面板 + 设置面板 |
| `src/components/AIAssistant/retrieval.js` | 客户端 BM25 检索（中文/英文分词） |
| `src/components/AIAssistant/llm.js` | OpenAI 兼容协议调用 + 强约束系统提示（流式） |
| `src/components/AIAssistant/styles.module.css` | 样式（支持亮/暗模式） |
| `src/components/AIAssistant/knowledge.json` | 知识库（由脚本生成，已纳入仓库，便于构建） |
| `scripts/build-knowledge.js` | 知识库构建脚本（`npm run build:kb`） |
| `src/theme/Layout/index.js` | 已注入 `<AIAssistant />`，全站显示 |

---

## 五、生产部署的安全建议（可选）

当前为「静态站点 + 前端直连模型」方案，密钥存在用户浏览器，适合演示/个人使用。
若要正式上线面向公众，建议改为 **后端代理**：把密钥放在服务器环境变量里，
前端只请求你自己的后端接口，由后端转发给 LLM，从而彻底隐藏密钥。
（如需此方案，可新建一个简单的 Node/Express 转发服务，本项目结构无需大改。）
