group_fqcd_jr/docs/客服Agent一期远程整合测试手册.md

客服 Agent 一期远程整合测试手册

版本：v1.0 适用分支：develop 及其候选分支 适用范围：访客、已登录用户、公开 FAQ/产品/政策知识检索

一、当前本地基线

• 代码最新提交：c76b763 feat: configure local customer service knowledge runtime。
• 一期公开知识：52 条，FAQ 15 条、产品 26 条、政策 11 条。
• 知识权威状态：MySQL published + active；Milvus 仅保存召回投影。
• Embedding：Qwen text-embedding-v3，要求 1024 维；密钥只通过 env:QWEN_API_KEY 引用。
• 本地开发向量库：Milvus Lite；团队/生产环境应使用受管 Milvus。
• 一期客服白名单：仅 query_knowledge，不开放账户、订单、持仓、收益、银行卡、定投、风险测评或投诉进度工具。

二、干净环境初始化顺序

1. 安装项目依赖：

   python -m pip install -e ".[dev]"
   

2. 配置 .env。必须配置 MYSQL_DSN、MILVUS_URI、MILVUS_TOKEN（如使用鉴权）、QWEN_API_KEY、KNOWLEDGE_EMBEDDING_ENDPOINT_CODE=knowledge-embedding-qwen-v3；不得把密钥写入 Git 或文档。

3. 执行完整数据库迁移：

   python -m alembic upgrade heads
   

4. 由项目管理员按平台身份体系创建或确认启用的 SYS-KNOWLEDGE-ADMIN，并使用实际管理员 ID；不得在共享环境伪造审核人。

5. 在管理员配置面登记并审核 knowledge-embedding-qwen-v3：

   • provider：qwen
   • model：text-embedding-v3
   • base URL：Qwen OpenAI-compatible /v1
   • capabilities：仅 embedding
   • allowed_data_levels：仅 public
   • secret_ref：env:QWEN_API_KEY
   • 返回维度：1024

6. 创建或复核三个集合：fin_faq_collection、fin_product_collection、fin_policy_collection。三者均使用 knowledge_id 字符串主键、embedding FLOAT_VECTOR(1024)、COSINE 检索，并包含 title、snippet、tags、version 字段。

7. 使用管理员受控发布工具导入预检清单：

   python tools/publish_customer_service_knowledge.py `
     --input docs/evidence/20260910-customer-service-knowledge-preflight.json `
     --reviewer-id <真实管理员ID> `
     --apply `
     --confirm-count 52
   

8. 激活一期客服配置版本，只给四个公开知识意图配置 query_knowledge。

三、整合测试门禁

先运行只读环境门禁：

python tools/verify_customer_service_phase1.py

预期输出中 failures 为空，且公开记录总数为 52。该脚本不会创建、更新或删除任何数据。

然后运行代码质量检查：

python -m pytest tests/unit tests/contract -q -p no:cacheprovider
python -m ruff check app tests tools alembic
python -m mypy app

四、必须执行的业务场景

场景	预期
访客问公司名称、客服电话、开户/赎回公开规则	命中对应公开集合并返回自包含答案
已登录用户问同样的公开信息	与访客相同，不读取个人数据
任一角色问持仓、收益、订单、银行卡或投诉进度	只引导“我的账户”或转人工，不调用知识工具查询个人数据
要求推荐具体基金、承诺收益、代客交易	合规拒答并转人工
验证码泄露、疑似诈骗、盗号	安全提示并转人工
明确要求人工服务或投诉纠纷	展示受控人工联系方式，并产生后台可见转接事件
连续闲聊超过三条	第四条自然引导业务；不重复诱导
停止 Milvus 或制造 Embedding 故障	只对已发布知识走 MySQL 关键词降级；无匹配则转人工

五、推送与合并策略

1. 从当前 develop 创建候选分支，例如 feature/customer-service-phase1-rc。
2. 在候选分支运行本手册第三节的门禁和第四节的业务场景。
3. 远程环境通过后，再发起合并请求或快进合并到共享 develop。
4. 不把 .env、Milvus Lite 数据文件、测试账号、个人数据或模型密钥推送到远程仓库。
5. 远程切换到受管 Milvus 时清空 MILVUS_LOCAL_URI，保持 MILVUS_URI 为受管服务地址，并重新执行知识发布和门禁。

六、失败处理

• 数据库迁移失败：停止整合，不修改历史迁移文件。
• Embedding 维度不是 1024：停止发布，保留知识为不可见状态。
• Milvus 写入失败：发布工具会禁用暂存 MySQL 记录并尝试清理向量；修复后重新执行。
• 业务边界测试失败：禁止合并，优先修复路由或白名单，不通过扩大客服 Agent 权限解决。