 张胜宇
|
5d0becb67d
|
客服 Agent 重构收口：五出口决策链 + 知识库档位隔离 + 前端入参边界（答辩演示版本）
一、客服 Agent 智能增强（正面回应"不智能、动不动就转人工"）
- 决策链由 2 个出口扩到 5 个：E1 澄清 / E2 计算型 / E3 知识直返 / E4 证据约束生成 / E5 分级回退
- 转人工从"默认动作"降为最后一档 E5c，只保留 4 类白名单：
P0 反诈 / P1 账户与个人数据 / P2 写操作与争议 / 用户明确要求人工
- 46 条金标实测（修复前 → 修复后）：
转人工率 43.5% → 10.9%；出口准确率 45.7% → 100%；事实正确率 69.6% → 100%
禁忌违反 1 → 0；档位越权 / 无出处数字 / 误拒 四项零容忍全 0
- 安全不变量 INV-1~INV-5；零容忍规则未删，改的是挂载点
（输出侧字面黑名单 → 检索层档位隔离 + 判定层合规词表 + 输出守护）
二、知识库：档位单点化与物理隔离
- 新增 app/core/knowledge_tier.py 作为档位规则唯一落点（G-03），
knowledge_contracts.py 原定义块改为显式再导出（X as X，非副本）
- 档位过滤由 bool 默认值（fail-open）改为 tiers 必填集合（缺参即 TypeError）
- Milvus 侧四集合按 visibility 分区键物理隔离；双 schema 收敛为一套
- 新增 app/core/actor.py：访客三元组与匿名判定的唯一构造/判定点（G-01/G-01b）
- 新增 app/core/fund_fee_rules.py：费率计算纯函数
三、前端入参边界对齐（本轮 W11 新修，4 处"校验宽于存储"）
- message 加 max_length=8000（与浮窗 widget.js 的 maxlength 一致）
- session_id 加 1—64；idempotency_key 上限 128 → 64（对齐列宽 String(64)）
- feedback_type 加 max_length=32（对齐列宽 String(32)）
- 8 条路径参数补 min_length=1 + max_length=64 + 字符集正则
（{session_id} / {run_id} / {handover_id}）
- 改前超限值会落到 MySQL 才失败（500）；改后一律 422 AGENT_INPUT_INVALID + 字段级定位
- 新增 tests/unit/api/test_frontend_boundaries.py（33 例），含"端点表 ↔ OpenAPI 全量对照"
四、投顾模块整体清除（D4.4 / D4.5）
- 删除投顾相关 controller / schema / model / repository / service 及门户页面
- tools/portal_api_check.py 同步作废 AD003/AD005/AD011/A047 四条用例与 advisor_t 登录
（端点与账号均已不存在，此前稳定报 3 条假红）
五、验证（提交前实测）
- pytest -q：1856 passed / 2 skipped / 0 failed
- ruff check app tools tests：19（= 基线）；mypy app：2（= 基线）
- 前端接口契约体检 portal_api_check.py：38 项，通过 34，失败 0，跳过 4
- 全链路冒烟 e2e_smoke_test.py --read-only：31/31
- HTTP 全链路探针 http_probe.py：11/11 succeeded
- 跨文档一致性 _consistency.py：GATE PASS
- 真机边界复验 12 条：12/12 符合预期
六、纪律与文档
- 可改文件白名单 A-09（docs/46）与底座会签申请单 A-10（docs/47，组 1—组 4 全部受理）
- 零 DDL：未新增/修改任何表结构，89 张业务表与基线一致
- 证据留痕：docs/evidence/**（含 46 条金标 score、快照、清除与重建记录）
- 未提交（刻意排除，见提交说明）：仓库内 客服agent/ 与 开发文档/ 是 2026-09-16 前的
过期副本（Todolist 440 行 vs 权威 D2.1 1167 行），权威正本在仓库外；
_chunks_report.txt 是 tools/build_knowledge_chunks.py 生成的本地产物
|
2026-09-20 14:33:30 +08:00 |
|
 lzf_0626
|
06d0f9f231
|
知识库检索质量修复：「风险评估问卷怎么评分」从必然转人工 → 直接答
## 根因（两个问题叠加）
1. 灌库脚本 tools/build_knowledge_chunks.py 的 expand_table_rows() 用「第一个非分隔行」
当表头且 header 从不重置 → 同一节里第 2 张表格起**表头被当成数据行**。
《个人投资者适当性管理指南》第九条下有 16 张问卷表格 → 15 条正文逐字相同的
19 字零信息量碎片；同类共 19 条。
2. 检索层去重只按 doc_id，接不住「同一父块的兄弟子块」（POL-AST-009-07 与 -12 是
不同 doc_id、同一父块）→ 15 条碎片全留在候选里互相打平，把 top1/次优差压到 0.002，
而客服判定要求中置信必须领先 ≥0.07（MIN_GAP）→ 恒判并列转人工。
## 为什么没有重灌知识库
用 Milvus 现成向量离线复算四种做法（同一问句、同一批向量）：
现状 gap 0.002 转人工
只修 bug（=重灌全部收益） gap 0.001 仍转人工，且更糟
只加父块归并 gap 0.093 可答，但答案是 19 字碎片
两处都改 gap 0.076 可答且有内容
原因：第九条被切成 94 块，删掉 15 条表头碎片后，剩下 79 条数据行碎片依然互相打平。
重灌解决不了，却要停机 3–10 分钟并丢掉上传路径的内容（含 R1–R5 那条）。
## 改了什么
① app/service/knowledge_search_service.py：新增 _merge_sibling_subblocks()
同一父块的兄弟子块只保留最高分那条；父块自身与 FAQ/政策这类本身就是细粒度答案
的块一律不合并（它们之间打平是真的多个候选）。6 个单测守着。
被丢掉的只是同节其它细节，本节完整内容由 _parent_hits 带回的父块兜底。
② tools/build_knowledge_chunks.py：修表头识别（markdown 表格只有紧邻 |---| 之前的
那一行才是表头）+ 新增 assert_no_duplicate_contents() 自带守卫 ——
正文完全相同的块必须为 0，否则中止且不写 jsonl。该脚本是一次性灌库脚本、
原来没有单测覆盖，这正是该 bug 活下来的原因，所以守卫放在它自己的执行路径上。
块数 636 → 617；正文完全相同的组 1 组 15 块 → 0 组。
负向验证：换回旧逻辑跑，退出码 1 并报出那 15 份碎片，且未覆盖 jsonl。
③ tools/drop_table_header_vectors.py：清掉已灌进 Milvus 的 19 条历史碎片。
判定可复现：语义 id（非纯数字）且正文不在修正后产物里。只动语义 id 是因为
纯数字 id 来自上传路径、本来就不在 jsonl 里（实测冒烟 A 线的 top1 就是数字 id 179）；
不按长度判是因为短块本身是设计的一部分（「评审标准：管理人资质 15%」13 字是有效答案）。
实删 policy 16 + product 3，faq 0；dry-run 逐条核对过，全部是「标签 + 表头词」形态。
这是唯一一次绕过 Outbox 的删除：事件消费侧要回读 MySQL 行，而这批是无元数据种子向量。
## 验证
真实链路 10 问句回归 10/10 与预期一致，0 个变坏：
风险评估问卷怎么评分 0.7156 gap 0.1473 → 答（原 0.002 转人工），top1 变成真实答案行
场内基金的管理费率 0.8114 gap 0.0977 → 直接答（冒烟 A 线）
南方季季盈90天起投金额 0.8631 gap 0.3387 → 直接答（行级子块精确命中能力未受影响）
今天天气怎么样 仍正确转人工
端到端：ask_customer_service.py「风险评估问卷怎么评分」→ 直接答，返回完整评分标准；
e2e_smoke_test.py 44/44（含 A4 知识库覆盖未转人工）；
pytest tests/unit tests/contract 1506 passed / 0 failed；
对账 重复正文 15 → 0，孤儿/死向量/缺向量仍全为 0。
（冒烟首跑 42/43 的唯一失败 B6 买入下单 503 是行情过期，补刷后 44/44，与本次无关。）
## 顺带查明
Milvus 的 delete() 是标记删除，约 1 秒后才在 query/search 中不可见（隔离临时集合实测：
删完立即查仍看得到，+1s 起消失）。清理工具第一版"删完立刻复核"因此谎报 19 条残留，
已改为轮询复核并把文案改成实测依据。get_collection_stats().row_count 在删除后仍显示旧值，
这也是对账工具坚持用 query 实际行数的原因。
## 文档
新增 docs/演示用/知识库检索质量修复-2026-09-15.md（根因、四方案对比、改动、全部证据）；
并对 docs/演示用/知识库向量对账与清理-2026-09-15.md 做更正 —— 451 条短块里 429 条是
设计内的有效数据行、只有 19 条是 bug 产物；"按长度合并短块 + 重建重灌"的建议已被实测否决。
## 仍未解决（记录在案）
「高净值客户有什么权益」gap 0.0075 仍转人工：根因是不同父块之间同族内容打平
（金卡 vs 白金权益），父块归并救不了也不该救，要从内容侧或业务口径入手。
knowledge/_chunks.jsonl（新 617 块、编号连续）与 Milvus（旧编号、含 19 个空洞）目前不一致；
不重灌无影响，但下次重灌必须 drop 集合重建而不是 upsert，否则两套编号会共存。
|
2026-09-15 09:31:57 +08:00 |
|
|
qyqy
|
5f82ac5107
|
feat(knowledge): 检索字段名改为运行时探测，两套集合 schema 都能跑
评审意见 §1.3 要求的修法。背景（双方实测共同确认）：同一批集合名在两个开发环境里是两套不同 schema：
我方：knowledge_id / snippet（无 visibility），行数 106/177/73
架构师：doc_id / content / chapter / section / doc_no / visibility，行数 125/297/214
上一轮我把字段名硬编码成我方那套，在架构师环境会让 Milvus 报 field doc_id not exist
→ 三集合全失败 → 客服一律转人工（反向亦然）。硬编码任一套都会打挂另一套。
改法（采纳评审建议）：
- 新增 app/core/knowledge_schema.py：describe_collection → 逻辑名到物理名映射，按集合缓存；
缺必需字段的集合明确判为不可用并如实记 degraded，不静默零召回
- 检索服务改为逐集合探测：output_fields 只请求实际存在的字段；visibility 过滤有该字段才拼
- KnowledgeHit 对外形状不变，检索逻辑（字面召回/父子块/去重/置信判定）一行未改
测试：新增 17 个探测单测；架构师的关键词召回测试参数化为两套 schema 各跑一遍。
|
2026-09-11 18:42:42 +08:00 |
|
|
qyqy
|
395bad25b7
|
fix(knowledge): 检索服务适配现库集合 schema、发布对齐的工具白名单、免责声明只由治理层注入
合并暴露的三个真机问题（单测全绿但线上必挂）：
1. 检索服务字段名与现库集合不符 -> 静默零召回
架构师那套按 load_knowledge_milvus.py 的 schema 读 doc_id/content/chapter/section/
visibility，而现库三集合的真实字段是 knowledge_id/title/snippet/tags/version/intent。
Milvus 对不存在的字段直接报错 -> 三集合全失败 -> degraded -> 客服一律转人工。
改法：只改读取侧，用 _FIELD_ALIASES 映射；KnowledgeHit 对外形状不变（下游与测试不动）。
代价已注明：没有 visibility 字段 -> 检索层内部资料硬隔离失效（现库 356 行均为对外知识）。
2. 发布白名单与代码上限不匹配 -> AGENT_PERMISSION_DENIED
active 版本白名单是 query_knowledge，而合并后代码上限是 search_knowledge/check_suitability/
query_customer_profile -> 交集为空 -> 所有知识问题 failed。
改法：publish_customer_service_config.py 补 PROFILE_TOOL 进 faq 白名单，并让同 key 的
继承项被本次定义覆盖（旧值原样继承会被子集校验 422 拒掉整次发布）。已激活版本 216。
3. 免责声明重复出现
Agent 自己拼一句 + 治理层追加权威话术 -> 客户看到两条。改为只由治理层注入
（话术属发布配置，改文案不该改代码）。风控等内部 Agent 不注入（结构化输出不被污染）。
测试：934 passed / 1 failed（test_fund_readonly_contract 既有空集缺陷，与本线无关）
真机：知识问答两问 succeeded 且只带一条声明；画像问答 succeeded；知识库三端点全绿
|
2026-09-11 15:27:16 +08:00 |
|
|
lzf_0626
|
4c2b147793
|
feat(knowledge): 产品知识拆到表格行级，并按问句选粒度
问题（客户实测反馈）：同一会话里问「季季盈90天起投多少」和「那它风险高吗」，两次回答
**一模一样**——都是整个产品小节的表格。客户问的是风险，收到的是整张说明书，看起来像
客服没听懂问题。
根因是切分粒度：原来"一个叶子标题 = 一块"，产品手册里就是整个产品小节（表格 + 说明）
成一块。这既让两个不同的问题命中同一块，也让整节几百字的向量成了"整节的混合语义"，
与"起投多少"这种具体小问题相似度天然偏低（实测该问句向量 top1 仅 0.6291，够不到 0.75
硬门槛，只能靠与次优的差值勉强通过）。
改动三处：
1. 切分：Markdown 表格的每一行额外生成一个**自解释**的小块（"南方季季盈90天：起投金额
1万元"），挂在父块 doc_id 下（PROD-007-04），父块照旧保留。知识块 160 → 631。
效果：该问句的命中分从 0.6291 升到 0.869，命中的正是"起投金额"那一行。
2. 检索：命中行级子块时把它的整节父块一并带回（分数按 0.9 折算），供调用方按问句选粒度。
整节块保底占最后一个名额，且不参与 top1/top2 判定——实测它挤到第 2 位会把 gap 从
0.090 压到 0.076，几乎跌破 0.07 的转人工门槛。
3. 客服：命中的是行级子块时，看问句与子块标签是否真的对得上——「起投多少」对「起投金额」
对得上，用那一行；「介绍一下」对不上，换成整节。
过程中两次判据写错并已修正（都固化进了测试）：用"含连字符"认子块时，整节块自己的编号
PROD-901 被误判成子块；用"不含两位数字后缀"认整节块时，FAQ 块全被误判成整节块排到后面，
把正确答案挤出 top1、害得「基金赎回几天到账」转人工。
验证：起投/管理费等字段问法给出聚焦的单行答案；"介绍一下"给出整节；FAQ 与政策问法不受
影响（换话题、指代追问等此前修好的场景复测通过）；
ruff / mypy(113 文件) / 468 unit+contract / 29 integration 全绿。
|
2026-09-10 22:29:23 +08:00 |
|
|
lzf_0626
|
570493e71c
|
feat(knowledge): 知识检索增加产品名的字面兜底召回
问题：客户问「季季盈90天的起投金额是多少」会被引导到人工客服，而知识库里明明有答案。
实测根因不是阈值拍错了，而是专有名词在 embedding 空间里不占优势——该问句的向量 top1
只有 0.6291，够不到 0.75 硬门槛，只能靠与次优的差值勉强通过；而同一次查询用
title like "%季季盈%" 是唯一命中 PROD-007。既然客户已经说出了产品名，就不该再赌相似度。
做法（三条边界都是实测逼出来的，不是设想）：
1. 只对产品集合做字面匹配。客户问「季季盈90天的起投金额是多少」与通用 FAQ 标题
「基金起投金额是多少?」有 7 个字连续重合；把 FAQ 纳入字面匹配会让它和真正的产品块
一起拿到满分、差距归零，反而又退化成"转人工"。
2. 字面命中只在向量结果不够确定时采用。客户问「基金赎回几天到账」时向量已给出正确答案
（FAQ-0016 得 0.8060），但手册章节标题「5.2 基金赎回流程」与问句也有 4 个字连续重合，
无条件采纳会把"操作步骤"顶掉客户真正问的"到账时间"。
3. 重叠门槛取 6 字而不是 4 字："基金赎回"这类业务动作词正好 4 字，会骗过 4 字门槛；
产品名（"南方季季盈90天"）更长，6 字能同时保住产品名、挡住动作词。
未改动任何转人工判定阈值；VECTOR_CONFIDENT_SCORE 与 Agent 的 HIGH_SCORE 由单测锁定一致，
避免两处各自漂移出"谁都答不出来"的死角。
验证：季季盈类问法由"转人工"变为正确答出，基金赎回问法仍答 FAQ-0016；
ruff / mypy(113 文件) / 453 unit+contract / 29 integration 全绿。
|
2026-09-10 22:15:50 +08:00 |
|
|
lzf_0626
|
13bab7c3d0
|
feat: 客服 Agent 端到端跑通（知识直返 + 答不了引导人工客服）
按业务方确定的取向实现：金融场景确定性优先，能溯源到公司资料的才答，答不了就
引导客户拨打客服热线，绝不用模型猜答案。端到端验收 8/8 通过。
新增：
- app/service/knowledge_search_service.py：知识检索。未复用记忆的 VectorMemoryAdapter
是因为它只返回 (memory_uuid, score)，会丢掉知识块的标题与正文，而客服回答必须能把
原文与出处一起交付。检索失败一律返回 degraded 而不抛异常，由 Agent 走兜底。
- app/service/knowledge_tool.py + app/core/knowledge_contracts.py：只读工具 search_knowledge。
走 ToolExecutor 而不是让 Agent 直接持有检索服务，是为了让白名单、权限、审计、超时
都归基座统一管理；工具只读也符合 ToolRegistry 的硬约束。复用既有权限码
knowledge:reference:read（customer 角色已具备），不新增权限点。
- app/service/agent/implementations/customer_service.py：Agent 本体，刻意保持薄——
意图分发 + 四条出口（faq/产品/政策直返、闲聊走模型、其余与异常引导人工）。
直接返回知识原文而不经模型改写，答案的字面内容全部来自公司已发布资料。
- tools/publish_customer_service_config.py：发布意图工具白名单。
- tools/customer_service_check.py：端到端验收（8 个用例，含越界请求与知识库外问题）。
装配：
- bootstrap 新增 get_knowledge_search_service 工厂，注册 search_knowledge 工具与
customer_service Agent。
- runtime_config_service 新增 load_active_prompt：提示词绑定 release_id，按当前生效
版本读取，未发布时回落代码默认值。闲聊话术因此可审核、可回滚，不必改代码发版。
过程中发现并处理的三个问题：
1. 自造 source_references 被基座合规闸门拒绝。governance.review_output 只接受
「本次召回的记忆」与「本次成功调用的工具」两类引用（用于防止伪造来源），
knowledge 类型会被判非法并使整个 run 失败。处理方式是**不放开那道校验**，
而把知识出处（文件标题与内部编号）写进正文，source_references 交给基座自动附加。
2. 发布配置是整版本替换语义：新版本会清空旧版本的全部配置项。若只发客服白名单，
示例 Agent 的 fund_query_demo:fund_quote 会被静默清空。故发布脚本先读取当前生效
版本的全部配置项并原样继承，再追加新增项。
3. 验收脚本自身两处自伤：打印 emoji 触发 GBK UnicodeEncodeError、以及读错结果字段
（RunQueryService 返回的答案键是 content 不是 text）。
已知缺口（未修，已记录）：
- CoreResult.transfer_required 未持久化：conversation_message 不存该标记，
API 读不到"本次是否引导了人工"。当前靠正文里的固定话术判断。
- 知识块引用（source_type=knowledge）尚未启用，需先让 ToolExecutor 把工具返回的
doc_id 登记为本次可引用来源。
验证：ruff 通过、mypy 107 文件无错、unit+contract 447 passed；
tools/customer_service_check.py 8/8 通过（含越界请求、投诉、知识库外问题三类
必须引导人工的场景，以及 7 个零容忍负面词零命中）。
|
2026-09-10 20:22:42 +08:00 |
|