group_xinghuo_jinrong/docs/项目框架设计/客服Agent-合并说明.md

# 客服 Agent · 从 `customer-service-agent` 合并说明

> 日期：2026-09-09  
> 原则：**只增不盖**；与 `merger` 同路径文件冲突时 **以 merger 为准**（未覆盖 `main.py` / `chat.py` / `agent_service.py` 等）。

---

## 1. 合并了什么

从远程分支 `xinghuo/customer-service-agent` 迁入 **客服 Agent Wave 1~5** 代码与文档（新增文件）：

| 类别 | 路径 | 作用（白话） |
| --- | --- | --- |
| 游客入口 | `app/api/visitor.py` | 未登录访客试聊 API |
| 画像槽位 | `app/config/profile_slots.py` | L1 画像字段定义 |
| 仓储 | `app/repository/profile_repository.py` `note_repository.py` | 画像 / 客户备注读写 |
| 编排 | `app/service/customer_service.py` | 客户 Agent 专用 LangGraph（14 节点） |
| 服务 | `profile_service.py` `note_service.py` `visitor_service.py` | 画像、备注、游客 |
| 提示词 | `customer_prompts.py` `visitor_prompts.py` | 各场景 system/user 模板 |
| 工具 | `app/tool/core_ro_tool.py` | 查持仓/流水等只读 Tool（客服线） |
| 合规 | `compliance_guard.py` `data_masker.py` | 话术合规 / 脱敏 |
| 脚本 | `scripts/bootstrap.ps1` `init_agent_db.py` `scripts/kb/*` | 客服线建库 / Milvus 集合 |
| 测试 | `tests/test_wave1_*` ~ `test_wave5_*` | Wave 1~5 单测与 E2E |
| 文档 | `表设计/02-mysql-agent 专用表设计总结.md` | Agent 专用表说明 |

**未迁入（冲突 · 保留 merger）：**

- `app/main.py`、`app/api/chat.py`、`app/service/agent_service.py` — 宿主对话线已集成 AL-09
- `docs/项目框架设计/表设计/02-mysql-agent专用.sql` — 保留 merger 版（含 `risk_aml_list` 等风控表）
- `docs/memory/*`、前端 `web/`、平台 API、风控模块 — 全部保留 merger

**根目录 `01-客户.docx`：** 与 `docs/需求拆解/用户故事/01-客户.docx` 内容相同，**不重复复制到根目录**。

---

## 2. 新增数据库表（需手工执行）

客服线新增两张表，已单独成迁移脚本（不修改 canonical DDL 文件）：

```text
scripts/agent/migrate-customer-agent-cs-c11.sql
  → conversation_archive   会话结束写摘要
  → customer_notes         用户说「帮我记住…」
```

在 `jinrong_agent` 库、共用底座表已存在后执行。

---

## 3. S2 接缝（2026-09-09 已接线）

**并行分流**（不替换 `agent_service.py`）：

| 入口 | 行为 |
| --- | --- |
| `POST /api/chat/visitor` | `main.py` 挂载 `visitor_router` · 免登录试聊 |
| `POST /api/chat` + `X-Agent-Type: customer` | `chat.py` 分流 → `customer_service.run_customer_chat`（14 节点 LangGraph） |
| `POST /api/chat/stream` + `X-Agent-Type: customer` | `chat.py` 分流 → `prepare_customer_stream`（图跑完后分块 SSE） |
| 其余 Agent | 仍走 `agent_service.chat` |

**接缝文件：**

- `app/api/auth_adapter.py` → `host_auth_for_customer_service()`（模块 `deps.AuthContext` → 宿主同形 `_HostAuthShim`）
- `app/service/memory_service.py` → `VisitorMemoryService`（游客 Redis 窗口）
- `app/service/rag_service.py` → `VisitorRagService`（包装 T-21 `search_knowledge`）
- `app/config/settings.py` → `customer_*` / `visitor_*` / `profile_*` / `archive_*` / `note_*` 字段

**仍待手工：**

- 本机真跑服务：`docker compose up -d redis`（游客/客服短期记忆与限流；无 Redis 时客服/游客对话可降级，但无跨轮记忆）

**RAG 双轨（2026-09-09）：**

| 链路 | Milvus | 灌库 |
| --- | --- | --- |
| 客服/游客 RAG | `fin_faq` / `fin_product` / `fin_policy` | `scripts/kb/build_collections.py` · 原料 `data/kb_collections/` |
| 宿主 Tool | `kb_product_rules` | `scripts/kb/build_kb.py` · 原料 `data/kb/` |

---

## 4. 测试预期

- 基线 `python -m pytest` → **730 passed**（Wave 1~5 客服测试已全部解禁）
- `tests/conftest.py` `collect_ignore` 已清空
- 新增 `pytest.ini`：`testpaths = tests`（避免 `scripts/kb/test_*.py` 被误收集）
- 客服线全量：`pytest tests/test_wave1_data_masker.py … test_wave5_notes.py`

---

## 5. 修订记录

| 日期 | 说明 |
| --- | --- |
| 2026-09-09 | Wave 1~5 解禁 · 迁移 SQL 已执行 · pytest **730 passed** · Scope B 冒烟（customer 200 · visitor Redis 降级） |
| 2026-09-09 | S2 接缝接线：visitor 路由 + customer 分流 + wave3 测试绿 · pytest 554 passed |