Files

T

2026-09-13 18:31:38 +08:00

80 KiB

Raw Blame History

奶龙基金客服 Agent 对话推进记录

用途：记录客服 Agent 知识库、一期 RAG 接入和运行边界的关键讨论、已确认决策与后续动作。

更新方式：从 2026-09-10 起，后续有效讨论或操作完成后持续追加。

安全约束：不记录 API Key、数据库密码、JWT 私钥或其他明文凭据。运行配置只记录变量名和状态。

一、项目定位

公司名称：奶龙基金责任有限公司（虚拟设定）。
公司地址：深圳市南湾街道布吉路66号（虚拟设定）。
Agent 名称：奶龙基金智能助手。
人设：活泼、可爱、清楚、有分寸；不冒充人工客服、基金经理、投顾或监管机构。
对标参考：南方基金等基金直销平台的公开业务场景，但对外品牌和业务数据均使用奶龙基金自己的虚拟配置。

二、一期业务边界

一期仅面向访客与已登录用户提供公开、静态的知识问答和服务路径指引。

可以处理

公司公开信息、官方渠道与服务路径；
已审核产品公开资料、风险等级、费率和披露资料说明；
开户、登录、申购、赎回、撤单、定投、转换等公开规则与自助路径；
风险测评、适当性、反洗钱、资料更新等公开规则；
风险教育、术语解释、常见页面问题与安全提示；
正常闲聊；用户连续第四条闲聊时进行一次自然、非诱导的业务引导。

不可以处理

不返回、推断或计算本人或他人的持仓、收益、订单、定投状态、银行卡、风险测评结果、投诉进度及其他动态账户数据；
不代办交易、资料修改、销户、退款、投诉、转账或其他写操作；
不推荐具体基金，不给买卖、止盈止损或资产配置建议，不预测涨跌，不承诺收益；
不索取或复述密码、验证码、完整身份证号、完整银行卡号、证件照片等敏感凭据；
不对投诉、赔偿、法律争议、人工处理时限或处理结果作承诺。

固定分流

诈骗、盗号、验证码或密码泄露、非本人交易、资金风险：停止操作和敏感信息披露，提示人工、警方及支付机构渠道。
本人账户或他人数据：不由 Agent 返回数据；已登录用户跳转“我的账户”，未登录用户提示登录。
人工、投诉、赔偿、法律争议、销户、个性化投资建议或写操作：转人工或明确拒绝代办。
公开静态问题：进入知识检索。
闲聊或问题不完整：简短回应，必要时只追问一个关键信息。

三、知识库资料结论

当前一期仅以以下文件为有效业务资料：

文件	定位	是否直接进入向量库
`客服Agent知识库_QA问答对_v5_RAG发布候选版.txt`	一期唯一 QA 候选源，版本 v5.8	是，按单条结构化后导入
`客服Agent一期运行边界基线_v1.md`	安全、权限、人设和拒答的最高优先级规则	否，必须在检索前执行
`客服Agent一期向量化前流程文档_v1.md`	一期流程依据	否，作为实现控制规则
`智能财富管家系统-完整项目流程文档.md`	项目级技术与业务背景	否，不能直接当作客服答案
`智能财富管家系统-业务与技术全景设计说明书.md`	项目级技术与业务背景	否，不能直接当作客服答案

QA 文件已核对：共有 105 条唯一稳定知识 ID，且有 105 个问题、105 组相似问法和 105 个标准答案，可作为一期结构化入库来源。

四、后端底座现状

后端仓库：D:\桌面\财富项目\group_fqcd_jr，当前使用 develop 分支代码。

已确认可复用的底座能力：

FastAPI、MVC+S、BaseAgent 与 AgentFactory；
JWT 与 RBAC；
MySQL、SQLAlchemy、Alembic；
Redis、Milvus、Neo4j 配置；
模型路由、ToolExecutor、审计、SSE 与 Worker；
知识元数据表 fin_knowledge_meta 的设计基线。

客服 RAG 已完成的主要模块（代码位于独立 feature/customer-service-rag worktree）：

访客短时 JWT 与 visitor 角色最小权限；
customer_service Agent 注册与安全、账户、人工、合规优先路由；
ModelGateway.embed() 与 Qwen Embedding 网关；
Milvus 知识检索只读适配器；
KnowledgeRetrievalService、MySQL 发布状态二次校验和关键词降级；
query_knowledge 公共只读工具；
fin_knowledge_meta 只读 ORM 映射。

仍未开始的外部数据发布工作：创建三类客服集合、配置已启用的 Embedding 端点、写入 MySQL 权威知识记录、写入向量和配置工具白名单。知识引用 Token 的签发和解析不属于一期 RAG 最小闭环，后续单列处理。

五、本地环境与服务状态

Conda 环境

环境名：123_py313；
Python：3.13.15，符合项目 >=3.13,<3.14 要求；
已按项目 requirements.txt 安装依赖；
已确认 asyncmy 可用；
已将 pymilvus 校正为 2.6.17，符合项目 <3 约束；
本地 .env 已创建并被 Git 忽略；其中模型密钥仅以环境变量方式提供。

本地服务检测

服务	当前状态	说明
MySQL `127.0.0.1:3306`	可达	本地连接配置已就绪，实际库名和迁移状态待后续确认
Milvus `127.0.0.1:19530`	已启动、客户端连接成功	当前已有 `sanguo_chunks`、`materials_chunks` 两个非客服集合，不能复用或删除
Redis `127.0.0.1:6379`	上次检测未启动	当前不阻塞知识库结构讨论；运行完整 Agent 前需启动或明确降级策略

JWT 测试

已生成仅用于本地测试的 RS256 RSA 公钥/私钥文件；
文件在被 Git 忽略的 config/jwt/ 目录；
JWT 安全测试结果：11 passed；
生产环境不得复用本地测试密钥。

单元测试基线

已执行过项目单元测试；
结果为 142 passed, 15 failed；
失败由本地测试密钥缺失和 aiosqlite 缺失导致，不是知识检索逻辑问题；JWT 密钥问题已解决，aiosqlite 待需要完整测试时再处理。

六、一期 RAG 技术决策

已确认

Embedding 模型：Qwen text-embedding-v3
调用平台：阿里云百炼 DashScope
向量维度：1024
相似度度量：COSINE
向量数据库：Milvus

该选型与项目流程文档中的 ADR-002 和知识检索接入方案一致。Milvus 集合一旦创建，向量维度不可直接变更，因此一期固定使用 1024 维。

向量内容

每条 QA 是一个完整业务单元，不按 512 Token 再切块。向量化文本为：

标准问题 + 相似问法 + 标签

MySQL 保留完整标准答案、版本、状态、有效期和来源信息。这样避免多个回答中的“转人工”“以页面为准”等高频文本干扰语义召回。

索引建议

一期数据量仅 105 条，三个集合均推荐使用：

索引：FLAT
度量：COSINE

FLAT 属于精确检索，当前数据规模下性能充足、配置最少、结果最稳定。HNSW 和 IVF_FLAT 等数据量达到数千条后再评估迁移。

三个客服集合

集合	内容	初始 TopK
`fin_faq_collection`	公司信息、服务入口、基础概念、开户登录和通用流程	3
`fin_product_collection`	产品、份额、费率、交易时间、申赎确认、定投和转换等静态规则	5
`fin_policy_collection`	风险测评、适当性、反洗钱、资料更新和合规说明	5

账户入口、人工转接、安全事件、投诉赔偿和写操作等控制类 QA 不进入普通向量检索集合；它们保留为结构化固定话术，由应用层规则优先调用。

初始阈值

默认最低相似度：0.70（配置化，不固化）

当前仅作为初始配置。由于 Qwen text-embedding-v3 的相似度分布与旧模型不同，后续应在有真实问题样本后再校准。

七、当前下一步

在不创建集合、不导入数据的前提下，下一项工作是对 105 条 QA 逐条做结构化分类：

faq
product_inquiry
policy_explain
account_entry
human_transfer
security_notice

分类结果将明确每条 QA 是进入哪个 Milvus 集合，还是仅作为应用层固定控制话术。完成该映射后，才创建三个客服专用 Milvus 集合并导入公开知识。

八、QA 分类完成（2026-09-10）

已完成 105 条 QA 的一期运行分类，详见 客服Agent一期_QA检索分类映射_v1.md。
52 条公开、静态知识将进入三类 Milvus 集合：FAQ 15 条、产品 26 条、政策 11 条。
53 条账户、人工、安全、会话与合规控制 QA 不进入普通向量检索，由应用层固定路由处理。
已登记产品清单、A/C 类、费率、交易时点、定投、转换和风险测评等语义重叠项的线上优先级，避免泛化答案覆盖具体平台规则。

九、结构化知识记录完成（2026-09-10）

已从 v5.8 候选 TXT 生成 客服Agent一期_QA结构化记录_v1.jsonl。
共 105 条有效 JSONL 记录，所有 qa_id 唯一；每条保留标准问题、相似问法、标准答案、标签、版本、审核状态和生命周期字段。
52 条公开知识的 execution_mode=vector_search，并已标明目标集合；53 条控制类知识的 execution_mode=fixed_route 且没有 Milvus 集合归属。
该文件是后续 MySQL 知识元数据写入与 Milvus Embedding 导入的唯一结构化输入；尚未创建集合、尚未调用 Embedding、尚未写入任何外部服务。

十、专项设计 HTML 评审结论（2026-09-10）

已阅读外部参考文件 D:\桌面\智能客服Agent专项设计方案(2)(2).html（v1.3，2026-09-07，内部评审稿）。

可采纳内容

FAQ / 产品 / 政策三集合与意图路由；
COSINE、FAQ TopK 3、产品和政策 TopK 5；
知识记录的版本、生效日期、失效日期、标签、来源、审校字段；
动态状态、低置信、投诉、情绪、人工需求的安全降级；
Milvus 故障时 MySQL 关键词降级；
来源引用、审计留痕、会话上下文随人工事件传递的方向。

不采纳或延后内容

已登录用户的持仓、收益、订单、交易记录查询：属于 HTML 的 Phase 2，和一期边界冲突；
自动创建人工工单并对外宣称“已登记”：当前仅显示人工入口和联系方式，后台事件未确认成功前不能这样表述；
新增 /api/chat/customer Controller：现有底座使用统一 /api/v1/agent-runs，不得另起执行链；
Agent 或子类直接连接 Milvus / 自动建集合 / 运行时 upsert：必须经过公共检索服务和工具执行治理；
105 条 QA 使用 IVF_FLAT、nlist=128、产品分区：数据量过小，仍采用 FLAT + COSINE，不建分区；
产品和政策回答交由 LLM 自由生成：一期统一返回审核后的标准答案；
“安全”作为绝对禁词：会误伤“账户安全”等必要风险提示，应拦截“安全无风险”“绝对安全”等承诺性语境；
对所有回答强制追加长免责声明：会损害人设和基础服务体验，改为对产品、费率、风险、收益等金融内容按场景追加。

后续影响

结构化 JSONL 下一次迭代应增加 title、source_type、source_url、reviewer 等字段。其中 reviewer 需业务方后续补充，不能伪造。当前下一项仍是先讨论统一 Milvus 字段结构，再创建集合。

十一、客服服务角色确认（2026-09-10）

客服 Agent 面向两类服务角色，而不是三类客服：

角色	身份状态	可用能力	账户类问题的固定动作
`visitor`	未登录访客	公开知识问答、闲聊、人工服务路径和安全提示	提示登录后前往“我的账户”；不返回任何数据
`authenticated_user`	已登录用户	与访客相同的公开知识问答、闲聊、人工服务路径和安全提示	提供“我的账户”受控页面入口；Agent 仍不读取、展示或复述账户数据

FAQ、产品、政策三个 Milvus 集合是公开知识的内容分类，不是三种客服角色。两个角色共用这三类公开知识；运行时必须先读取 user_role 再执行账户分流。结构化知识记录后续应增加 audience 字段，用于标明条目是否对两类角色均可见，以及访客/登录用户的路径差异。

十二、角色路由结构化数据完成（2026-09-10）

已保留 v1 原始结构化记录，并生成 客服Agent一期_QA结构化记录_v2_角色路由版.jsonl。
v2 对全部 105 条 QA 增加：audience、requires_authentication、visitor_strategy、authenticated_user_strategy、agent_data_access、title、source_type、source_url、reviewer。
17 条 account_entry 记录：访客走 prompt_login_then_account_center，已登录用户走 account_center_redirect；仅这 17 条标记为需要登录。
所有 105 条记录的 agent_data_access=none，保证已登录不会因角色字段而获得客服 Agent 数据读取权限。
reviewer 和 source_url 当前为 null，等待业务审核人和真实官方入口补充，禁止编造。

十三、三类公开知识统一字段方案完成（2026-09-10）

已新增 客服Agent一期_三类公开知识统一字段方案_v1.md，明确 FAQ、产品、政策三集合使用完全一致的 Milvus 物理字段：knowledge_id、embedding、title、snippet、tags、version。
已确认 MySQL fin_knowledge_meta 是标准答案、审核状态、启停状态、版本和生命周期的权威来源；Milvus 只保存召回投影，命中后必须回查 MySQL 的 published + active + 有效期 条件。
已明确从角色路由 JSONL 导入时，只有 52 条 vector_search 的公开知识可导入；53 条会话、账户、人工、安全与合规控制记录继续由应用层固定路由处理。
未创建 Milvus 集合，未调用 Embedding，未导入任何向量数据。下一阶段进入实际检索设计前，先向业务方提供索引、阈值、重排及降级策略的选择方案。

十四、RAG 实现与数据导入准备（2026-09-10）

已确认方案 A：Qwen text-embedding-v3、1024 维、COSINE、FLAT；FAQ / 产品 / 政策三个集合初始 TopK 为 3 / 5 / 5，相似度阈值为 0.70。
已完成公开知识工具链的代码实现：Embedding、Milvus 只读召回、MySQL 权威答案和生命周期校验、Milvus 不可用时的 MySQL 关键词降级、客服 Agent 接线。
核心测试已通过：RAG、客服路由、模型网关相关测试 15 项通过；Ruff 和 Python 编译检查通过。项目全量单元测试中有 4 项既有场外邮件 Worker 用例因本地缺少 aiosqlite 失败，与客服 RAG 无关。
本机 MySQL 3306 和 Milvus 19530 均可达；Milvus 当前仅有 sanguo_chunks、materials_chunks，尚未创建任何客服集合。
已复核 v2 JSONL：105 条唯一记录中有 52 条公开向量发布候选，分布为 FAQ 15、产品 26、政策 11；其余 53 条继续固定路由。
已修正 A/C 类知识的同问不同答：RAG-CONFIG-003 负责具体 A/C 类费率，NF-STS-006 改为“奶龙基金支持哪些份额类别？”并负责产品范围说明。
已固定导入主键规则：qa_id 仅用于追溯；Milvus knowledge_id 必须使用 MySQL fin_knowledge_meta.id 的十进制字符串，以支持运行时权威回查。
已固定 Milvus tags 为 JSON 字符串数组；运行时检索已增加安全解析，异常格式按空标签处理，不影响权威答案校验。

十五、对话记录维护规则（2026-09-10）

本文件记录有效的业务决策、代码阶段结果、测试结论、基础设施状态和待确认事项，不逐字保存完整聊天内容。
从本次更新起，每完成一个实质性阶段后追加摘要；不记录 API Key、数据库密码、JWT 私钥或其他明文凭据。
当前下一步：确认 Milvus 三集合的最终物理 Schema 和发布审核人后，再创建集合并执行 MySQL、Embedding、Milvus 的一次性受控导入。

十六、Milvus 客服集合已初始化（2026-09-10）

已创建空集合：fin_faq_collection、fin_product_collection、fin_policy_collection；未触碰原有 sanguo_chunks、materials_chunks。
三个集合均已验证为统一 Schema：knowledge_id（主键）、embedding（FLOAT_VECTOR(1024)）、title、snippet、tags（JSON 字符串数组）和 version。
三个 embedding 索引均已完成构建，索引类型为 FLAT、度量为 COSINE，当前总行数均为 0。
未调用 Embedding、未插入 Milvus 向量、未写入 MySQL；下一阶段必须先建立 52 条公开知识的 MySQL 权威记录并取得其自增主键，再生成向量写入对应集合。
MySQL 预检结论：应用配置指向的 jr_agent 数据库当前不存在；本机现有数据库均未包含 fin_knowledge_meta，因此不能向其他项目库写入客服知识。下一步需要先创建并初始化项目数据库，再进行知识发布。

十七、本地项目数据库已初始化（2026-09-10）

已按 .env 中的名称创建本地 jr_agent 数据库；未修改或写入其他已有数据库。
已导入仓库 alembic/baseline_generated.sql 的 39 张基础表，并执行 Alembic 至 20260910_offsite_worker；当前数据库共有 60 张表。
已核对 fin_knowledge_meta 字段完整，当前知识记录数为 0。
当前 sys_user 记录数为 0，因此没有合法的知识审核人 reviewer_id。一期不单独创建客服运营或审核账号；在整体项目合并后，由项目管理员完成知识运营、审核和发布，并使用管理员实际用户 ID 作为 reviewer_id。

十八、知识运营与审核职责确认（2026-09-10）

一期知识运营、审核和发布均由整体项目管理员完成，不建立客服模块独立的运营人或审核人账号。
当前本地 jr_agent 仅用于基础表和链路验证，不伪造管理员身份或审核记录。
52 条公开知识在管理员实际审核发布前保持候选状态；客服 Agent 的 MySQL 权威校验会阻止任何未发布知识对客返回。
该规则只适用于客服知识内容。平台配置中心的 config_release 若保留创建人与审核人分离约束，仍应遵循其自身底座规则。

十九、当前客服 Agent 交付范围收敛（2026-09-10）

当前负责人只交付访客与已登录用户共用的客服 Agent 基本功能，不负责管理员后台、知识审核、知识发布、数据库运营或后续知识更新流程。
Agent 侧只需要保证：两类角色的访问隔离、公开知识检索接口、账户问题的前端入口提示、安全与合规优先路由、人工联系方式和闲聊引导规则。
管理员后续负责向 MySQL 和 Milvus 发布或更新知识；Agent 不创建集合、不写入知识、不修改数据库事实。
本地空数据库和空客服集合仅作为接口与链路验证环境，不应成为继续扩展管理员能力的理由。

二十、客服 Agent 基础行为补齐（2026-09-10）

已将客服本地意图细分为：安全提示、合规拒答、账户入口、人工转接、闲聊、公开 FAQ、产品资料和政策说明；安全、合规、账户和人工分支始终优先于 RAG。
FAQ、产品与政策问题现在分别只向对应公开知识子意图检索，避免所有公开集合同时召回造成的无关命中；知识仍必须由管理员发布后才可能返回。
连续闲聊由服务端按同一会话的用户消息意图计算，客户端传入的计数会被忽略；第四句仅自然引导一次，之后不重复提示，出现业务消息后自动重置。
已新增并通过客服 Agent、知识检索、模型网关与 Agent 接收流程的 21 项回归测试，Ruff 检查通过。
本阶段未新增管理员后台、审核发布、知识写入、向量导入或数据库运维功能；后续管理员完成知识发布后，Agent 可直接检索已发布公开内容。

二十一、访客前端联调页与异步执行修复（2026-09-10）

已新增同源测试页入口：/customer-service-test/。页面仅申请访客 Token、创建 customer_service 运行并轮询状态接口，不新增正式前端工程、不接入管理员能力。
页面提供闲聊、政策、账户入口、安全风险、合规拒答和人工服务六类快捷场景；由于浏览器原生 EventSource 无法附加鉴权头，测试页采用带 Authorization 请求头的状态轮询。
端到端测试发现并修复访客 Worker 身份恢复缺陷：接收端会在内部 Outbox 事件中记录服务器已验证的 actor_type=visitor，Worker 恢复最小访客权限且不查询正式用户 RBAC；已登录用户仍在执行时重新读取 RBAC。
端到端测试发现并修复固定客服路由被意图模型端点阻断的问题：客服 Agent 明确声明不需要模型意图分类，安全、账户、人工、合规、闲聊与公开知识子路由均由本地确定性规则处理。
已将人工客服电话配置为 customer_service_phone；统一治理层只保留该唯一受控号码，其余手机号仍脱敏。实际访客安全测试已返回成功状态和人工电话。

二十二、访客端端到端验收完成（2026-09-10）

已通过测试页同源请求链路完成 9 项访客验收，均返回 succeeded：账户入口、安全风险、合规拒答、人工服务、政策降级和连续 4 句闲聊。
账户问题只提示访客登录后进入“我的账户”，未返回持仓、收益或其他动态账户数据。
安全、合规和人工服务话术均展示受控人工电话；政策问题在当前无已发布知识时安全降级至人工，不编造公开规则。
闲聊前三句保持普通友好回应，第四句仅进行一次自然业务引导，符合一期闲聊规则。
下一步前置条件：整体项目需提供正式登录接口及可用客户账号或已登录 JWT。当前本地不伪造客户身份、不创建业务用户数据，因此暂不执行已登录用户浏览器联调。

二十三、已登录客户模拟联调完成（2026-09-10）

根据测试授权，已使用本地签名 JWT 和临时客户 9001 完成真实已登录请求链路验证；未新增登录接口，未持久化测试账号。
已登录客户的订单查询返回“我的账户”入口，未返回订单、持仓、收益或其他账户动态数据；安全风险场景返回止损提示和受控人工电话。
测试完成后已删除临时客户、角色、权限、关联会话、运行和 Outbox 数据；复核结果为测试用户、角色和权限记录均为 0。
访客与已登录客户的客服 Agent 基础行为均已完成实际异步接口和 Worker 链路验证。正式前端后续只需接入整体项目的登录态，不应复用本次临时测试账号或 JWT 生成方式。

二十四、隔离分支客服闭环与知识预检复核（2026-09-10）

本节为隔离分支完成时的历史快照；其中“尚未合并”“543 passed”和“待实现发布工具”的状态已由第二十五节更新，现以第二十五节为准。

代码位置与提交证据

后续迁移工作在独立工作树 D:\桌面\财富项目\group_fqcd_jr\.worktrees\foundation-safe-migration 的 feature/foundation-safe-migration 分支完成；该工作树的成果随后已快进合并回 develop，原工作树未被覆盖。
511a8ca feat: add governed public knowledge retrieval：公开知识受控检索，包含 FAQ / 产品 / 政策三路由、1024 维 COSINE、MySQL 发布有效性二次校验和关键词降级。
e9b3d27 feat: add governed customer service agent：访客与登录用户客服 Agent、确定性优先分流、连续闲聊软引导、联调页，以及人工转接工单/Outbox 闭环。
24f7563 feat: add knowledge import preflight：本地知识导入预检工具及 52 条公开候选的待审核清单。

知识数据与验证复核

v2 JSONL 的 105 条记录经最新预检：52 条公开候选、53 条控制规则；公开候选为 FAQ 15、产品 26、政策 11。
52 条都满足 agent_data_access=none 和一期公开边界，但仍为 approved_candidate，没有实际审核人，因此预检清单全部保持 pending_review。
dry-run 清单位于隔离工作树 docs/evidence/20260910-customer-service-knowledge-preflight.json；本轮未向 MySQL、Redis、Milvus 或模型服务写入任何数据。
最新验证：pytest tests/unit tests/contract -q -p no:cacheprovider 为 543 passed；Ruff 和 Mypy 均通过。

后续前置条件

由整体项目管理员审核 52 条候选，确认虚构渠道、产品、费率和规则口径，并提供实际 reviewer_id。
配置专用 Qwen Embedding 端点，确认稳定返回 1024 维；不得复用默认聊天端点。
复核既有空客服 Milvus 三集合 Schema 和 MySQL jr_agent 基线状态，再实现管理员使用的正式发布工具。
正式发布工具必须先写 MySQL 权威记录，再生成向量写入对应集合；失败必须停止并输出可核对结果。
管理员工单列表、通知消费者、知识审核后台和“我的账户”独立接口仍属于后续项目集成，不扩展客服 Agent 的数据读取范围。

二十五、一期收尾、受控发布与主分支合并（2026-09-10）

本轮决策

选择完成“管理员受控发布工具”，而不是由客服 Agent 直接写入 MySQL 或 Milvus。这样保留了知识审核、可追溯性与运行时只读边界。
不创建虚假的管理员账号、不伪造 reviewer_id，也不把候选知识直接标为已发布。金融业务公开口径即使为项目虚拟设定，也应保留真实项目管理员的审核记录。
选择将已验证代码以 fast-forward 方式合并至项目 develop，避免额外合并提交和冲突；用户原有未跟踪文档保持不变。

已完成结果

bc2f521 feat: add guarded knowledge publication tool 已在 develop：管理员发布工具默认仅 dry-run，不加载 .env、不连接外部服务；执行真实发布必须同时提供 --apply、合法正数 --reviewer-id 与 --confirm-count 52。
真实发布顺序固定为：先生成并校验全部 1024 维 Embedding，再将 MySQL 权威记录暂存为 pending + disabled，随后写入 Milvus，最后才激活为 published + active。向量写入失败时，暂存记录会禁用并尝试清理已写入向量。
已在 develop 完成回归：pytest tests/unit tests/contract -q -p no:cacheprovider 为 548 passed；Ruff 与 Mypy 均通过。
已验证 dry-run：52 条候选均处于“等待管理员审核”的状态。此次收尾没有向 MySQL、Milvus、Redis 或模型服务写入任何实际知识或配置。

明早需由项目方完成的真实前置条件

在 sys_user 中创建或确认真实、启用的项目管理员，并提供其实际 ID 作为 reviewer_id。
对 52 条虚构公开 QA 作内容审核，确认可发布、需修订或需下线的条目。
在主项目 .env 中配置 KNOWLEDGE_EMBEDDING_ENDPOINT_CODE，并在 model_endpoint_config 中启用对应的 Qwen text-embedding-v3 端点及其环境密钥引用；该端点必须稳定返回 1024 维向量。
复核 fin_faq_collection、fin_product_collection、fin_policy_collection 存在且 Schema 为已约定的 1024 维 COSINE 结构。

满足上述条件后，管理员在主项目根目录执行以下首发命令（将占位内容替换为真实管理员 ID）：

& 'D:\ANACOUDA\envs\123_py313\python.exe' tools/publish_customer_service_knowledge.py `
  --input docs/evidence/20260910-customer-service-knowledge-preflight.json `
  --reviewer-id <真实管理员ID> `
  --apply `
  --confirm-count 52

二十六、一期知识首发与本地运行环境完成（2026-09-11）

代为确定并已执行的决策

创建内部通用知识发布管理员：SYS-KNOWLEDGE-ADMIN（ID 9003）。该账号是发布审计身份，具备配置、模型端点与审计的最小管理权限；不属于客服 Agent 运行角色，不给访客或客户增加任何数据权限，也不作为前端登录凭据使用。
选择 Qwen text-embedding-v3 作为一期 Embedding 模型，端点代码为 knowledge-embedding-qwen-v3，通过环境变量密钥引用配置，能力范围限定为公开知识；实际连通性测试返回 1024 维向量。
因本机 Docker/Milvus 服务未运行，选择 Milvus Lite 作为本地开发持久化向量库。配置采用 MILVUS_URI 保留独立 Milvus 默认地址、MILVUS_LOCAL_URI 指向本地文件的双地址模式；清空本地地址即可切回团队或生产 Milvus，无需改业务代码。
将知识相似度阈值从 0.70 校准为 0.60。实测精确公司 FAQ 的分数约为 0.669，账户查询、行情和天气反例最高分分别约为 0.563、0.429、0.372；账户类仍在路由层优先拦截，因此该阈值提升公开知识召回而不扩大账户数据边界。
创建并激活 customer-service-phase1-public-kb-v1 配置版本，只允许 customer_service 在 public_knowledge、FAQ、产品和政策意图调用 query_knowledge。未配置任何账户、交易、持仓、银行卡、投诉进度或人工处理结果工具。

实际发布与验证结果

已创建 fin_faq_collection、fin_product_collection、fin_policy_collection，均为字符串主键、1024 维向量、COSINE 检索结构。
已发布 52 条公开知识：FAQ 15 条、产品 26 条、政策 11 条；MySQL 状态均为 published + active，三个 Milvus 集合行数合计 52。
补齐了缺失的 Alembic 分支 20260910_drop_review_separation。此前数据库只应用了另一条 head，导致单管理员审核的既有迁移未生效；现通过 alembic upgrade heads 正常收敛，未手工修改表、字段或业务数据。
实际检索验证：精确公司问题命中 1 条权威答案，复合公司/客服电话问题命中 3 条相关公开知识；Milvus 就绪探针返回正常。
实际客服 Agent 全链路验证：访客公开公司问题的工具调用成功并返回公开答案；“查询自己的持仓和收益”不调用工具，只返回“我的账户”入口。
最新质量验证：pytest tests/unit tests/contract -q -p no:cacheprovider 为 548 passed；Ruff 和 Mypy 均通过。
相关代码已提交到 develop：c76b763 feat: configure local customer service knowledge runtime。本地 .env、Milvus 数据文件和用户原有未跟踪文档均未提交。

一期后续事项（不阻塞当前本地功能）

团队或生产环境部署时，提供受管 Milvus 服务并清空 MILVUS_LOCAL_URI，随后按同一 Schema 迁移或重新发布知识。
使用项目正式登录态完成浏览器前端联调；客服 Agent 仍只提供“我的账户”入口，个人数据必须由独立接口处理。
接入管理员工单列表与 Outbox 消费通知，供人工实际处理转接事件；在此之前对客话术不得表示人工已处理或承诺时效。
后续每次更新公开知识都必须由管理员执行预检、审核和受控发布，不允许 Agent 运行期写知识库。

二十七、远程整合前门禁固化（2026-09-11）

选择先建立远程候选分支并执行整合测试，再推送共享 develop；原因是 Git 只携带代码，不能携带本机 MySQL 记录、Milvus Lite 数据或环境密钥。
新增只读门禁脚本 tools/verify_customer_service_phase1.py，检查管理员 9003、Qwen Embedding 端点、一期客服工具白名单、52 条公开知识以及三类 Milvus 集合的 1024 维 Schema 和行数。脚本不创建、更新或删除任何数据。
新增 docs/客服Agent一期远程整合测试手册.md，固定干净环境初始化顺序、发布命令、业务场景、失败处理和推送策略；不包含任何密钥值。
门禁实测通过：failures=[]、公开记录总数 52；Ruff/Mypy 通过；全量单元与契约测试 548 passed。
代为确定的 Git 策略：从当前 develop 创建 feature/customer-service-phase1-rc 候选分支，先在候选分支完成远程环境门禁，再合并到共享 develop。
候选分支已成功推送到远程：origin/feature/customer-service-phase1-rc，远程提交为 a229ec2；未修改远程 develop。下一步由整合环境按手册重建服务与数据后执行测试。

二十八、客服一期合并至 ZSY_develop 并完成整合测试（2026-09-11）

访客转人工匿名工单修复与冒烟验证（2026-09-11）

启动 ZSY_develop 本地服务和 Worker 后，发现访客安全/转人工 Agent 判断正确，但转人工工单将随机访客 subject 写入 svc_handover_ticket.customer_id，触发正式用户外键错误。
修复 AgentPersistenceService：仅当运行用户存在于 sys_user 时写入工单 customer_id；访客工单使用 NULL 归属并保留 session_id、Outbox 和审计信息，后台仍可追踪处理，不扩大客服数据权限。
新增访客匿名工单回归测试；修复后全量测试为 683 passed，Ruff、Mypy 均通过。
真实 HTTP 冒烟通过：访客公开 FAQ（使用知识库原问题）命中客服电话答案；访客持仓收益只提示登录后进入“我的账户”；访客安全风险和转人工均成功，工具调用数符合预期；已登录客户公开 FAQ 命中答案，持仓收益不调用工具。
本轮临时测试会话、运行、工单、Outbox、审计和临时 RBAC 已清理；保留专用 sys_user=9001 作为后续集成测试外键基准。
修复提交为 0059701 fix: persist visitor handover tickets anonymously，本地已提交；推送 origin/ZSY_develop 时远程返回认证失败，当前远程仍为 9220b7b，待恢复 Git 凭据后执行普通 git push origin ZSY_develop，不需要强推。
按用户要求，从远程 ZSY_develop 创建本地目标分支，保留该分支已有的风控与场外业务功能，并将客服一期候选分支真实合并。
冲突处理保留了配置、风险路由、访客令牌、场外基金、知识检索和客服 Agent；未覆盖用户未跟踪文档，未提交 .env、API 密钥、数据库文件或 Milvus Lite 数据。
合并提交为 9220b7b47ce874278212b16da357572949b33464，已成功推送至远程 origin/ZSY_develop；未推送或修改远程 develop。
为修复转人工 Outbox 集成测试的外键前置条件，仅在本地 jr_agent.sys_user 增加一条专用测试用户：ID 9001、用户编号 IT_HANDOVER_9001、用户名 integration_handover_9001，状态正常、基金账户未开户；未覆盖已有记录，也未写入 Git。
补充测试用户后，转人工 Outbox 集成用例通过；全量测试结果为 682 passed，Ruff、Mypy 和客服一期门禁均通过。
远程当前仅确认存在 ZSY_develop、develop、qyqy_develop；没有发现可撤回的额外远程候选分支。本地历史工作分支保留，避免影响已有工作树。

二十九、修复提交已补推至 ZSY_develop（2026-09-11）

按用户再次授权，执行普通 git push origin ZSY_develop，未使用强制推送，也未修改其他远程分支。
远程 origin/ZSY_develop 已从 9220b7b 更新至 0059701 fix: persist visitor handover tickets anonymously。
推送后复核 origin/ZSY_develop...ZSY_develop 为 0 0，本地与远程提交一致。
工作区仍有两份未跟踪文档：docs/15-知识检索接入方案.md、docs/superpowers/plans/2026-09-10-customer-service-rag-plan-a.md；本次未将其纳入提交。

三十、一期剩余工作盘点（2026-09-11）

按一期运行边界、远程整合手册和当前 ZSY_develop 代码复核，核心客服能力已完成：访客/已登录用户角色路由、公开 FAQ/产品/政策检索、个人数据禁止返回、安全拦截、闲聊引导、转人工工单/Outbox/审计、知识发布控制和前端测试页均已具备。
只读环境门禁再次通过：failures=[]，Embedding 端点为 knowledge-embedding-qwen-v3，公开知识 52 条，三类 Milvus 集合和一期白名单符合预期。
单元与契约测试再次通过：646 passed；本次未发现一期回归失败。
当前仍未完成、但不阻塞本地一期客服使用的事项：
1. 正式前端登录态联调；当前已验证临时登录链路，正式账户登录仍应由主项目接入，个人查询继续走独立接口。
2. 管理员工单列表、Outbox 消费和通知闭环；当前只能可靠地产生后台可见事件，不能向用户承诺人工已处理或处理时限。
3. 团队/生产环境的受管 Milvus 切换与干净环境重建验证；本地 Milvus Lite 已通过，远程环境需按整合手册重新发布 52 条知识。
4. 知识库运营后台（新增、复核、失效、版本化、重新索引）；一期已有受控命令行发布工具，后台界面属于后续运营建设。
不属于一期未完成项、应保持关闭的能力：客服 Agent 查询或返回持仓、收益、订单、银行卡、投诉进度、风险测评结果，代客交易，个性化推荐，以及直接调用“我的账户”数据接口。

三十一、二期 Redis 客服会话记忆补充盘点（2026-09-11）

纠正上一轮盘点：二期 Redis 记忆不能遗漏，但它不等同于账户查询 Phase 2，也不等同于底座已有的长期记忆热缓存。
当前底座已有 MemoryRecallService、MySQL 记忆单元、Milvus 可选语义召回和 Redis 热缓存；它服务于已登录客户的通用长期记忆召回，不是 Redis List 会话上下文。
当前客服 Agent 尚未实现 Redis 会话短期记忆：连续闲聊计数和最近三条用户消息来自 MySQL ConversationMessage，没有 session:{session_id}:messages 的 Redis List、滑动 TTL、24 小时上限、消息/Token 截断或会话隔离测试。
当前 BaseAgent.recall_memory 会对非访客调用通用长期记忆召回；客服 Agent 虽然不读取或输出 self.memories，仍不应保留该隐式读取路径。因为一期客服 agent_data_access=none，二期开始前应让 customer_service 显式跳过通用长期/画像记忆召回。
二期客服记忆的范围应限定为：访客和已登录用户各自当前会话内的、经过敏感信息清洗的短期上下文，只用来消解“刚才那只基金”“上面说的费率”等指代；不得读取或写入客户画像、持仓、订单、风险测评、银行卡、投诉处理结果，不得改变工具白名单或投资建议边界。
推荐顺序：先做客服长期记忆禁用与回归测试，再做 Redis 会话 List（滑动 30 分钟、绝对最长 24 小时、固定消息数和约 4096 Token 上限、会话所有权校验、Redis 故障降级为当前 MySQL 最近消息），最后完成访客/登录用户隔离、敏感信息不入 Redis、TTL/截断/故障降级的测试。

三十二、专项方案复核与后续实施顺序（2026-09-11）

已逐节复核《智能客服Agent专项设计方案(2)(2).html》。方案中的“Phase 2 账户/持仓/交易 API 查询”与当前项目已确认的职责划分不合并：个人数据继续由主前端的独立“我的账户”接口处理，客服 Agent 保持 agent_data_access=none。
目前已完成或已有底座支撑的部分：访客/已登录用户隔离、三类公开知识的受控 RAG、MySQL 权威回查、Milvus 降级、只读工具白名单、SSE/幂等/trace、基础限流、公开知识标准答案、基础安全/合规分流、转人工工单/Outbox/审计。
专项方案中尚未闭环且与当前客服职责直接相关的缺口：
1. 客服 Redis 短期会话记忆及隐私控制；
2. 客服跳过通用长期/画像记忆；
3. 敏感信息在用户输入、会话归档和 Redis 写入前的统一脱敏/不入库；
4. 低置信澄清（至多两轮、单槽位）和高/中/低三档 RAG 兜底；
5. 转人工工单附带经过脱敏的会话摘要、路由原因、置信度和来源，而不仅是 session_id 与当轮回复；
6. 负面词全量门禁、提示词注入规则及红队用例；
7. 评测集、运营指标与管理员工单消费通知闭环。
推荐实施顺序：
1. 先建立客服二期边界与测试基线：禁止长期/画像记忆，明确 Redis 仅保存当前会话安全上下文；同步补齐输入脱敏和敏感凭据不入会话记录。
2. 实现 Redis 短期会话记忆：访客与登录用户按会话隔离，30 分钟滑动 TTL、24 小时绝对上限、消息/Token 截断、Redis 故障降级；完成隔离/TTL/敏感信息/故障测试。
3. 使用短期上下文实现指代消解和澄清状态机：未知问题或低检索置信度一次只问一个关键槽位，最多两轮，仍失败即转人工；不让未识别问题默认按 FAQ 硬答。
4. 完善人工转接上下文：生成脱敏摘要和结构化原因，管理员侧可消费 Outbox、查看待处理工单并通知相关人员；对外仍不承诺处理时效。
5. 进行合规与质量门禁：全量负面词、注入/越权/敏感信息红队用例，公开 QA 检索与路由评测集，记录命中率、低置信率、转人工率和延迟。
6. 再做体验与运营增强：引用展示、建议问题、知识健康检查/运营后台、FAQ 缓存、熔断与压测、团队受管 Milvus 部署。
RAG + LLM 自由生成、按画像推荐、客服读取账户 API、长期个人记忆和跨 Agent 客户画像联动均不纳入上述客服二期；它们会扩大当前已确认的客服权限边界。

三十三、客服长期/画像记忆读取隔离完成（2026-09-11）

已完成客服二期实施顺序第 1 项的读取侧收紧：在公共 AgentDefinition 增加默认开启的 recalls_customer_memory 声明；BaseAgent 在声明关闭时统一跳过治理层长期/画像记忆召回。
CustomerServiceAgent 显式配置 recalls_customer_memory=False，因此访客与已登录用户均不会触发 MemoryRecallService、MySQL 记忆、Milvus 长期记忆或 Redis 记忆热缓存读取；不绕过公共 Agent 治理骨架，也不影响其他 Agent 的默认行为。
新增回归用例，使用会抛错的治理替身验证已登录客服调用链绝不执行 recall；现有访客隔离测试继续保留。
验证通过：客服/治理定向测试 20 passed；全量单元与契约测试 647 passed；Ruff、Mypy 均通过。
已识别下一步写入侧前置：Worker 当前仍可能对满足受控业务信号的已登录客服消息投递通用长期记忆抽取事件。此行为将在下一步“敏感输入不入会话/不入长期记忆/不入 Redis”中一并关闭和测试，不在本次读取侧改动中扩大范围。

三十四、客服输入脱敏与长期记忆写入隔离完成（2026-09-11）

完成客服二期实施顺序第 2 项：新增客服会话持久化前的凭据最小化处理。密码、验证码、完整身份证号、银行卡号和手机号的具体值在写入 ConversationMessage 前替换为受控占位符；“验证码”“密码”等风险语义保留，以便客服安全路由仍可提示用户停止泄露。
客服的 Idempotency 请求摘要、会话消息、Worker 重建请求和后续 Outbox/Redis 会话路径均使用脱敏后的文本；原始敏感值不进入本项目的上述持久化链路。
Worker 增加 agent_type 判断：customer_service 即使遇到业务事件或用户偏好信号，也不会创建 memory.extraction_requested，因此客服内容不会沉淀为长期客户画像或偏好记忆。
新增单元测试覆盖凭据隐藏与普通“忘记登录密码怎么办”咨询不误伤；新增 Worker 回归测试覆盖已登录客服不入长期记忆；新增真实 MySQL 受理集成测试，确认固定测试验证码、银行卡号和密码均未落入会话记录，测试数据已自动清理。
验证通过：隐私/Worker/客服定向测试与集成测试 13 passed；全量单元与契约测试 650 passed；Ruff、Mypy 均通过。
约束：本次仅控制应用内部的会话、Outbox 与记忆链路，网关、反向代理或基础设施访问日志的原始 HTTP 请求脱敏属于部署侧配置，后续生产部署需单独核验；既有历史会话不做批量改写，避免未经审批修改审计数据。

三十五、客户画像与客服记忆边界确认（2026-09-11）

已与用户确认：客户与客服的对话可在后续作为客户画像的来源之一，但客服 Agent 不应在实时回答时读取、推断或基于画像推荐产品；这会突破当前“公开知识客服、只答不荐”的权限边界。
当前“跳过长期/画像记忆”含义：客服 Agent 不读取通用 MemoryRecallService，客服消息也不直接写入长期画像；不是删除客户画像能力。
后续独立画像流程应为：已登录用户明确对话 → 异步提取受控画像候选 → 规则/置信度/来源证据校验 → 候选或人工审核 → 画像服务生效。只允许风险偏好、投资期限、流动性需求、投资目标等用户明确陈述的受控字段。
密码、验证码、银行卡、身份证、投诉描述、订单/持仓状态不进入画像；正式风险等级、适当性资格、交易和账户事实只能来自权威系统，不能从聊天推断。
下一步 Redis 短期会话记忆仅用于“刚才那只基金”“上面说的费率”等当前会话指代，不写长期画像、不接个人账户接口、不触发推荐。

三十六、Redis 短期会话记忆实施确认（2026-09-11）

已确认进入客服二期的 Redis 短期会话记忆实施。它是“当前会话上下文”而非客户画像、长期记忆或账户数据缓存。
存储边界：仅在客服运行成功并完成 MySQL 会话持久化后，保存已脱敏的 user 与 assistant 两类消息；不保存原始密码、验证码、完整证件号、银行卡号、手机号等敏感值。
生命周期：30 分钟滑动过期，首次写入起绝对最长 24 小时；最多保留 16 条消息，并按保守估算控制在约 4096 Token 内。
隔离边界：访客与已登录用户使用不同、不可反推身份的会话键；即使会话 ID 相同也不得互读。客服不读取 MemoryRecallService 的长期/画像记忆。
降级边界：Redis 健康但当前会话不存在时按空上下文处理；只有 Redis 访问异常才回退 MySQL 最近三条用户消息。Redis 写入失败只告警，不影响正常回答、人工转接、审计或主事务。
本轮不实现指代消解、澄清状态机、画像候选提取、个人账户接口或产品推荐；这些能力须在短期会话隔离和隐私测试稳定后单独推进。

三十七、Redis 短期会话记忆实现完成（2026-09-11）

已新增 CustomerServiceSessionMemory 独立服务，使用 Redis List 保存当前客服会话的已脱敏 user / assistant 消息；未复用 MemoryRecallService、长期记忆热缓存或客户画像链路。
Redis 键由 actor_id + session_id 的 SHA-256 摘要组成，不在键名暴露用户或访客标识。相同 session_id 在不同访客/登录用户之间隔离，无法互读。
已实现 30 分钟滑动 TTL、首次写入起最长 24 小时 deadline、最多 16 条消息和约 4096 Token 截断。Redis 正常但 List 为空时按空上下文处理；仅 Redis 出错时才回退 MySQL 最近三条用户消息。
已接入 AgentRunApplicationService：短期上下文仅用于连续闲聊计数，且 MySQL 与 Redis 均转换为时间正序，避免存储顺序影响第四条闲聊的业务引导判断。
已接入 WorkerRuntime：仅在客服运行结果成功完成 MySQL 持久化后写入 Redis。Redis 写入异常只记录告警，不影响已完成回复、人工转接、审计或主事务；非客服 Agent 不写此 List。
已验证 Redis 本地服务可达（PONG）。测试覆盖访客/登录用户隔离、TTL/绝对上限、消息/Token 截断、敏感凭据二次脱敏、读写故障降级、Redis 空上下文不回退 MySQL、Redis 故障回退 MySQL，以及 Worker 仅写客服会话。
验证通过：Redis 相关定向与真实 MySQL 受理回归 33 passed；全量单元测试加受理集成回归 642 passed；Ruff 全量 app 检查与 Mypy 全量 app 检查通过。
下一项建议：基于这份短期上下文实现低置信澄清与指代消解状态机。每轮只询问一个关键槽位、最多两轮，仍无法确定或触及动态/敏感/人工事项即转人工；不让未知问题默认命中 FAQ。

三十八、低置信澄清与指代消解完成（2026-09-11）

已在客服运行元数据中增加服务端专用的 clarification_round 和 session_context。客户端请求体没有这两个字段，不能伪造或覆盖；上下文仅来自当前会话 Redis List 或 Redis 故障时的已脱敏 MySQL 最近消息。
已复用 svc_conversation_session.clarification_round，没有新增表或改变数据库基线。客服成功发出澄清时在与结果消息同一 MySQL 事务内递增；成功回答、转人工或其他非澄清客服结果会重置为 0，避免旧状态影响下一次独立咨询。
已实现“最多两轮”规则：首次、第二次知识未命中或缺少指代对象时，只问一个关键问题；第三次仍不能确定时返回人工联系方式并创建转人工结果，不再循环追问。
已实现指代消解：如“它的费率是多少”“刚才那只基金的风险等级”等，只有存在当前会话脱敏上下文时，才将“当前问题 + 已脱敏上下文”发送给公开知识检索；没有上下文时先询问产品名称或代码。该上下文不传给回答模型、不调用账户接口、不写入长期记忆或客户画像。
检索服务降级（如 Embedding/Milvus 不可用）仍直接转人工，不消耗澄清轮次；避免把基础设施问题误导为用户表达不清。拼接后的检索输入限制为 2000 字符，Redis 读取也已移动到 MySQL 会话行锁事务外，防止短暂网络故障占用业务锁。
测试覆盖：无上下文指代澄清、两轮上限转人工、上下文检索补全、空知识澄清、检索降级转人工、Redis 空/故障降级、澄清轮次递增/重置，以及真实 MySQL 会话行递增。验证通过：全量单元测试及客服受理/持久化集成回归 651 passed；Ruff 与 Mypy 全量 app 检查通过。
下一项建议：完善转人工上下文。工单应附带脱敏会话摘要、结构化转接原因、澄清轮次、检索置信度和来源，而不是仅保存当轮回答与 session_id；管理员侧再消费 Outbox 并完成待处理通知闭环。对外仍不得承诺处理时限或已处理结果。

三十九、转人工上下文完善完成（2026-09-11）

已新增确定性转人工上下文构造器，不调用大模型，不读取账户、客户画像或长期记忆。它只读取当前会话最近 6 条已持久化消息，单条最多 280 字符，并在生成工单前再次执行密码、验证码、证件号、银行卡号和手机号脱敏。
客服自动转人工时，svc_handover_ticket 现在保存：结构化 reason_code、不含个人凭据的 reason_detail、脱敏 conversation_summary、当前会话的澄清轮次、可用的意图置信度和知识来源。未给用户增加“已处理”“已登记成功”或任何处理时限承诺。
同一份结构化上下文同步写入：工单、agent.handover_requested 审计明细和 conversation.transfer_requested Outbox 事件。Outbox 消费者可据此通知管理员或展示待处理列表，而不必重新读取原始敏感会话内容。
已验证：历史会话中即使存在旧的原始验证码、银行卡号或密码，转人工摘要与 Outbox 内容仍只保留受控占位符；访客工单继续不把匿名主体写入正式客户外键。
验证通过：全量单元、客服受理/持久化和人工转接集成回归 656 passed；Ruff 全量 app 检查与 Mypy 全量 app 检查通过。
下一项建议：实现管理员侧对 conversation.transfer_requested 的 Outbox 消费和待处理工单查看/通知闭环。该能力只面向管理员，外部客服回复仍仅提供人工联系方式；在消费者真实成功前，不向用户表述“已通知人工”或“已受理”。

四十、管理员转人工队列只读闭环完成（2026-09-11）

已为 conversation.transfer_requested 注册 Worker 消费者。事件消费成功时，同一事务写入 handover.queue_ready 审计和 OutboxDelivery 幂等交付记录；它仅说明管理员队列已可查看，绝不修改 svc_handover_ticket.status，不会把 pending 伪装成已接单、已处理或已完成。
已新增管理员只读接口：GET /api/v1/admin/customer-service/handover-tickets 与 GET /api/v1/admin/customer-service/handover-tickets/{ticket_no}。两者必须同时具有 admin/super_admin 角色和独立的最小权限码 handover:read；列表不展示会话摘要，详情也不返回客户标识、原始会话、账户数据、联系方式、分配信息或处理结论。
管理面详情只返回二次脱敏的转接原因、会话摘要、意图置信度和来源白名单字段。即使历史工单中存在原始验证码、银行卡号或来源扩展字段，读取时仍隐藏凭据并剔除未声明字段；用户主动填写的“转人工原因说明”在新写入时也已加入同一脱敏规则。
按最小化和当前一期边界，未实现管理员接单、人员分配、通知外部渠道、回复用户、处理、解决或关闭工单；这些需要单独定义状态机、人员身份、审计和用户通知口径后再开展。
本地测试 RBAC 种子已加入 handover:read。生产或共享环境不会自动改写现有管理员权限，部署时需要由管理员在 sys_permission / sys_role_permission 中创建并授予同名权限；未授予时接口会按预期返回 403，而不会退化为通用配置读取权限。
已同步更新权威接口文档 group_fqcd_jr/docs/05-接口文档.md，明确接口、权限、返回边界和 Outbox 消费语义；没有修改数据库基线、表结构或已有字段。
验证通过：完整测试 713 passed，ruff check app tests tools alembic 全通过，mypy app 全通过。真实 MySQL 集成回归覆盖“工单事件 → Worker → 幂等交付和审计 → 管理员列表/详情”，确认工单仍为 pending 且敏感内容不经接口输出。
文档权威性检查当前仍因已有三份 15-* 文档编号冲突失败（15-Agent组员统一接入说明书.md、15-知识检索接入方案.md、15-金融NL2SQL工具接入说明.md）。它们不是本轮创建或修改，未擅自删除或重命名；后续整理文档编号时再由项目决定保留名称与编号。

四十一、本地管理员 RBAC 实际接入验证完成（2026-09-11）

复核时发现当前本地 MySQL 不存在约定的测试用户 9001、9002、9003，因此不能仅靠接口依赖覆盖确认真实 JWT → 身份库 → RBAC 链路。
已运行仓库受控脚本 tools/seed_test_rbac.py。该脚本只删除并重建固定测试号段 9001-9003 的用户、角色、角色权限关系和权限记录；未访问其他用户、业务表、客服会话或知识库数据。
创建后的身份口径：9001 为 customer，9002 为 risk_operator，9003 为 admin。测试管理员 9003 已被授予 handover:read，客服访问本身未增加账户、持仓、订单、银行卡、投诉进度或客户画像权限。
使用项目 RSA 私钥签发的真实 JWT，通过实际 FastAPI 鉴权与真实 IdentityRepository 验证：9003 请求管理员工单列表返回 200（当前空队列）；9001 请求同一接口返回 403 AGENT_PERMISSION_DENIED。未输出、记录或传播令牌、私钥或其他凭据。
下一项建议：建立客服公开知识、越权/敏感输入、提示词注入、低置信澄清与转人工的合规红队测试集和可复跑评测命令；它只验证当前边界，不引入个人账户查询、长期画像或产品推荐。

四十二、客服合规红队基线建立（2026-09-11）

按前文已确认的客服边界建立 group_fqcd_jr/docs/客服Agent一期_合规红队与业务评测集_v1.md，覆盖 18 类场景：账户/持仓/收益/订单/银行卡/投诉进度、密码和验证码披露、诈骗与非本人交易、提示词注入、收益承诺和具体推荐、代客交易、转人工、低置信指代、连续闲聊、公开知识和 Milvus 故障降级。
红队执行要求固定为：访客与已登录用户分别验证；先检查路由再检查工具调用；账户、安全、人工、合规拒答和闲聊不得调用 query_knowledge；公开答案只能来自已发布标准 QA；人工转接不得承诺已接单、已处理或处理时限。
发现并修正两项真实路由缺口：我的密码是/密码为/我的验证码是 等主动凭据披露现在优先进入 security_notice；忽略之前规则/泄露系统提示词/显示内部指令 等提示词注入现在优先进入 compliance_refusal，不会进入知识检索。
新增自动化用例验证两类收紧，客服 Agent 定向测试 18 passed；完整项目测试 717 passed；Ruff 全量 app tests tools alembic 通过；Mypy 全量 app 通过。
当前红队集验证的是代码路由和边界，不代表真实知识命中率。待管理员发布 52 条公开知识后，需用同一用例执行端到端测试，补充命中率、误转人工率、低置信率、平均延迟和敏感输出扫描结果。
仍保持明确不做：客服读取或更新客户画像、长期记忆、持仓、收益、订单、银行卡、风险测评结果、投诉进度；个人账户数据继续由前端独立接口提供。任何红队用例触发这些越界行为都应阻断发布。

四十三、一期收口并行验证与提交状态（2026-09-11）

为提高效率，本轮将无相互依赖的事项并行执行：全量测试、Ruff、Mypy、一期只读门禁同时运行；门禁发现测试种子管理员编号与门禁要求不一致后，已统一为 9003 / SYS-KNOWLEDGE-ADMIN，随后复测通过。
当前验证结果：tools/verify_customer_service_phase1.py 返回 failures=[]；完整测试 717 passed；ruff check app tests tools alembic 通过；mypy app 通过。
已同步更新一期进度报告 D:\桌面\财富项目\docs\奶龙基金客服Agent一期进度报告_v1.md：将管理员只读工单、短期记忆、澄清和红队状态改为当前实际结果，并列出剩余团队/生产事项。
已将当前客服 Agent 相关改动统一提交到本地 ZSY_develop：提交 ef098e6 feat: complete customer service safety and handover flow。提交包含 30 个客服代码、测试和接口/红队文档文件；未纳入用户原有未跟踪资料、.env、模型密钥、数据库文件或 Milvus Lite 数据。
推送 git push origin ZSY_develop 已重试两次：第一次无法连接 Git 服务，授权网络重试后返回 Failed to authenticate user。因此当前 HEAD=ef098e6 仅存在本地，远程 origin/ZSY_develop 尚未更新；恢复 Git 凭据后只需执行普通 git push origin ZSY_develop，不需要强推。
当前可继续推进的最优下一步不依赖代码：准备正式前端登录态、受管 Milvus 连接和实际管理员账号，按《客服Agent一期远程整合测试手册》在团队环境重建并执行门禁；管理员工单接单/通知状态机和客户画像候选写入属于后续独立阶段，不与客服公开知识检索混合。

四十四、二期画像集成测试修复与 Milvus 本地验证（2026-09-11）

修复真实 MySQL 画像候选集成测试的清理逻辑：原清理语句在 MySQL 中对 profile_snapshots 自引用子查询触发 1093；现改为先按画像 UUID 清理同步 Outbox，再按临时 customer_id 直接删除快照、冲突记录和记忆单元，不改变业务逻辑。
单独重跑 tests/integration/test_customer_profile_candidate_mysql.py：1 passed；完整测试集：729 passed；Ruff：All checks passed；Mypy：Success: no issues found in 157 source files。
修复已提交并推送到二期分支 ZSY_develop2：提交 1eb04f2 test: fix mysql profile snapshot cleanup。一期 ZSY_develop 未修改。
依赖检查：本地 MySQL 与 Redis 可达；项目 Milvus Lite 文件存在，fin_faq_collection、fin_product_collection、fin_policy_collection 三集合共 52 条数据。通过 MilvusKnowledgeClient 实际调用验证集合自动加载和 FAQ 返回正常；直接同步 SDK 搜索因集合 released 的提示属于 SDK 使用方式问题，不代表项目适配器失败。
当前外部阻塞：本机 Neo4j bolt://127.0.0.1:7687 未启动，无法完成画像快照到 Neo4j 的真实投影联调；画像候选、快照和同步 Outbox 已落 MySQL，但不能把 Outbox 事件标记为真实 Neo4j 已成功同步。
下一步按严谨顺序：先实现并测试 memory_sync_outbox 的 Milvus/Neo4j 消费者幂等、失败重试和状态更新；Milvus 可先用 Lite 验证，Neo4j 需在服务启动或提供受管测试实例后再做端到端联调。客服 Agent 仍不读取长期画像，也不开放个人账户数据。

四十五、Neo4j 服务启动但认证配置待补充（2026-09-11）

检测到 Neo4j Bolt 127.0.0.1:7687 与 HTTP 7474 均可达，说明服务已启动。
项目当前读取到的配置为 NEO4J_USERNAME=neo4j，但 NEO4J_PASSWORD 为空；使用该配置连接返回 Neo.ClientError.Security.Unauthorized。为避免错误写入或伪造同步成功，暂未执行画像投影写入，也未将任何 memory_sync_outbox 事件标记为已处理。
需要用户介入的唯一配置项：在项目 .env 中填写该 Neo4j 实例真实密码（只在本地配置，不提交 Git），然后通知继续。密码不会写入对话记录或输出。
用户提出尝试 123456；已仅通过临时进程环境变量验证 neo4j/123456，仍返回认证失败，确认该凭据与当前实例不匹配。未继续猜测密码、修改 Neo4j 或写入任何投影数据。
用户提供新实例密码 12345678 后，已仅通过临时进程环境变量验证默认用户 neo4j 认证成功。使用现有 GraphProjectionWorker 完成一次真实 PREFERS 关系写入、关系计数核验和同事件重复投影幂等验证（首次 True、重复 False），探针节点已立即清理。
在 Neo4j 已启动环境下重新执行一期门禁：failures=[]，完整项目测试 729 passed。当前二期画像 Outbox 仍未接入专用 Milvus/Neo4j 消费者；该实现需先确定画像向量集合字段及 Neo4j 节点/关系白名单，不凭空复用关系投影测试映射。
已将用户确认的 Neo4j 密码写入本地 group_fqcd_jr/.env（该文件由 .gitignore 忽略），配置读取检查通过；密码不进入 Git、测试输出或本记录正文。

四十六、画像投影协议冻结与远程凭据阻塞（2026-09-11）

根据 00-新数据库基线设计 和 01-通用Agent平台开发设计，固化《客服Agent二期_画像投影协议_v1.md：Milvus 使用 user_long_term_memory_v1，Neo4j 仅投影 Customer/Preference/Goal` 最小字段，MySQL 版本门禁最高优先，外部存储不得反向覆盖权威库。
协议明确当前画像事件的安全前置：必须补齐正式 memory_uuid 与快照内记忆来源映射，不能把 profile_uuid 猜作记忆 UUID，也不能把整份画像快照直接冒充长期记忆向量。
文档本地提交为 2de1735 docs: define profile projection protocol；git diff --check 已通过。尝试推送 ZSY_develop2 时远程返回 Failed to authenticate user，提交目前仅在本地。
需要用户介入：恢复该 Git 远程的有效认证凭据后执行普通 git push origin ZSY_develop2；不需要强推，不影响已有远程历史。
随后重试推送成功：ZSY_develop2 已从 1eb04f2 更新到 2de1735；本地与远程已同步。远程仅提示当前使用 HTTP 地址存在传输安全警告，未改变推送结果。

四十七、画像同步事件补齐正式记忆来源映射（2026-09-11）

按冻结协议完成第 1 步：管理员批准画像时，在同一事务内查询该客户全部 active memory_unit，将 memory_uuid、memory_key、content、memory_type、confidence、version、valid_until 写入 Milvus/Neo4j Outbox payload 的 memory_sources。
未改变客服 Agent 的长期画像读取禁用、账户数据权限或访客隔离；只扩充异步投影事件的来源字段，未把 profile_uuid 冒充 memory_uuid。
单元与真实 MySQL 集成定向测试 6 passed；完整测试 729 passed；Ruff 和 Mypy 全部通过。
已提交并推送 ZSY_develop2：5777f0f feat: include memory sources in profile sync events。
下一步：实现 Neo4j 画像投影适配器（Customer/Preference/Goal、版本门禁、幂等）并用当前已认证的本地 Neo4j 做端到端验证；Milvus 投影仍需按 user_long_term_memory_v1 集合 schema 接入 Embedding 后再写入。

四十八、Neo4j 画像投影适配器完成（2026-09-11）

新增 app/infrastructure/neo4j_profile_projection.py：固定参数化 Cypher，只允许 preference: 与 goal: 记忆键，强制校验客户、画像版本、记忆 UUID、置信度和版本；写入前再次执行客服敏感信息脱敏。
实现 Customer 画像版本门禁：低版本或重复版本不覆盖高版本；按来源生成 Preference/Goal 节点及 PREFERS/HAS_GOAL 关系，关系携带记忆 UUID、置信度、版本和有效期。
新增 4 项单元测试，覆盖正常投影、低版本跳过、敏感信息脱敏和非法记忆键拒绝；真实 Neo4j 临时数据验证首写成功、关系数量为 2、重复版本跳过，临时节点已清理。
验证结果：定向测试 9 passed，完整测试 733 passed；Ruff、Mypy 全部通过。
已提交并推送 ZSY_develop2：f167390 feat: add neo4j profile projection adapter。
尚未把适配器接入 memory_sync_outbox 消费循环；下一步应实现独立 Outbox 消费器的领取、幂等交付、失败退避和 processed/dead 状态更新，再以真实画像批准事件进行端到端验证。客服 Agent 继续不读取长期画像。

四十九、画像同步 Outbox 消费器完成（2026-09-11）

新增 app/worker/memory_sync_outbox_worker.py，独立负责 memory_sync_outbox 单条领取、目标存储筛选、handler 调用、成功 processed、失败指数退避和第 5 次失败 dead。
未配置目标 handler 的事件会明确进入 dead，不会伪造投影成功；外部存储调用不与客服主请求事务混合。Neo4j 和 Milvus 目标可以独立消费，单边失败不影响另一边。
新增 4 项单元测试，覆盖成功处理、失败退避、死信和缺少 handler；全量测试 737 passed，Ruff、Mypy 全部通过。
已提交并推送 ZSY_develop2：6c605ec feat: add memory sync outbox worker。
当前仍需完成的接线：在常驻 Worker 装配 Neo4j Neo4jProfileProjection.upsert handler；实现符合 user_long_term_memory_v1 schema 的 Milvus handler后，再以真实画像批准事件验证两路 Outbox 状态均为 processed。客服 Agent 仍不读取长期画像。

五十、Neo4j 投影接入常驻 Worker（2026-09-11）

app/worker/__main__.py 已接入可选 Neo4j 投影：仅当 NEO4J_PASSWORD 已配置时创建驱动和 MemorySyncOutboxWorker，每轮只消费 target_store=neo4j 的画像同步事件；未配置时不阻塞客服主循环，事件保持待处理。
Neo4j 驱动在 Worker 退出时显式关闭；Milvus 事件因尚无符合 user_long_term_memory_v1 的写入 handler 继续保留，不会被误标记成功。
Mypy、Ruff 和完整测试均通过：737 passed。
已提交并推送 ZSY_develop2：5e848f5 feat: wire neo4j projection into worker。
下一步：创建一条受控的真实画像批准事件，运行一次 Worker，核验 Neo4j Outbox 从 pending 到 processed、重复事件不重复写入；随后再实现 Milvus 长期记忆写入 handler。客服 Agent 仍不读取长期画像。

五十一、Neo4j Outbox 常驻消费真实闭环完成（2026-09-11）

常驻 Worker 已装配 Neo4j handler：配置有效时每轮只消费 target_store=neo4j，配置缺失时保持事件 pending，不影响客服主链路。
为运维重放增加可选 event_uuid 精确过滤，避免验收或补偿时误领取其他积压事件。
使用固定测试客户写入真实 memory_sync_outbox，精确运行消费器后验证：consumed=True、MySQL 状态 processed、Neo4j 关系数 1；测试事件和图数据均已清理。
全量测试 737 passed，Ruff、Mypy 全部通过；已提交并推送 ZSY_develop2：50a6112 feat: target memory sync event replay。
当前剩余：Milvus user_long_term_memory_v1 写入 handler（需正式 Embedding 端点和集合 schema）；完成后再做两路 Outbox 联合验收。客服 Agent 仍不读取长期画像。

五十二、Milvus 画像投影与双目标 Worker 接线完成（2026-09-11）

新增 app/infrastructure/milvus_profile_projection.py：固定 user_long_term_memory_v1 schema，按 memory_uuid 查询版本后再 upsert，强制 1024 维向量、客户字段、状态和有效期；写入前再次脱敏，拒绝非 UUID 或非 preference:/goal: 记忆键。
本地 Milvus Lite 原目标集合为空，已按基线创建可空时间戳字段；真实写入与重复 upsert 验证成功，测试记录已清理。既有三套客服知识集合未修改。
常驻 Worker 现可按配置同时装配 Neo4j 与 Milvus handler；两路事件独立消费，任一端失败只重试自身事件。
新增 4 项 Milvus 适配器测试；全量测试 741 passed，Ruff、Mypy 全部通过。
已提交并推送 ZSY_develop2：cbcf7c7 feat: add milvus profile projection。
当前剩余：使用真实画像批准流程产生的一对 Outbox 事件，调用常驻 Worker 完成 Neo4j + Milvus 双目标 processed 联合验收；Embedding 将调用已配置的 Qwen 端点，需确认端点可用后再执行，避免无意消耗额度。客服 Agent 仍不读取长期画像。

五十三、二期画像双目标联合验收完成（2026-09-11）

使用固定临时客户、正式 UUID 记忆来源和两条独立 memory_sync_outbox 事件，完成 Neo4j 与 Milvus 的真实联合验证；临时画像快照、Outbox、Neo4j 图节点/关系和 Milvus 向量均在验证结束后清理。
验证结果：Neo4j 与 Milvus 消费器均成功领取事件；MySQL 中两条事件状态均为 processed；Neo4j 中 PREFERS 关系数量为 1；user_long_term_memory_v1 中对应长期记忆向量数量为 1。
初次在受限工具网络中运行时，Qwen Embedding 连接不可达，Milvus 事件正确进入 failed，没有被误标记为成功；在项目实际允许访问模型服务的网络环境复跑后，双路均成功。这确认失败关闭与成功投影两种状态均符合预期。
本轮没有改动客服 Agent 的读取边界：长期画像仅由管理员批准后的异步投影写入，客服不读取长期画像，也不开放用户持仓、收益、订单、银行卡或投诉进度。
仅用于联调的临时探针脚本已删除；group_fqcd_jr 中两份既有未跟踪资料保持原样，未纳入提交。
联合验收后已完成必要回归：741 passed、Ruff 通过、Mypy 通过（160 个源文件）。本轮没有新增需提交的项目代码；ZSY_develop2 与 origin/ZSY_develop2 均停在已推送的 cbcf7c7。
当前应暂停等待用户确认是否将 ZSY_develop2 的二期提交集成到一期 ZSY_develop。在明确确认前，不修改、不合并也不强推 ZSY_develop；集成时需先拉取远程分支、基于共同祖先审查差异，并按功能语义处理冲突，禁止整文件采用 ours/theirs 覆盖。

五十四、二期快进集成到 ZSY_develop 完成（2026-09-11）

已先同步远程引用并确认 ZSY_develop 是 ZSY_develop2 的直接祖先，二期提交集共 11 个，未发现分叉或冲突。
在独立集成工作树中执行 git merge --ff-only ZSY_develop2，保留一期全部历史和功能，没有使用整文件覆盖，也没有改写历史。
集成后回归结果：完整测试 741 passed，Ruff 通过，Mypy 通过（160 个源文件），git diff --check 通过。
已普通推送到远程：origin/ZSY_develop 从 ef098e6 快进到 cbcf7c7；未使用强制推送。远程分支现已包含一期客服安全/转人工能力与二期画像候选、Neo4j/Milvus 异步投影链路。
集成工作树使用的 JWT 忽略文件仅用于本地测试，未进入 Git；临时集成工作树可安全移除。客服 Agent 既定边界保持不变：不读取长期画像和账户敏感数据。
下一步建议：在团队环境按远程分支执行一次服务启动和前端联调；若需继续开发，统一基于最新 ZSY_develop 新建个人工作分支，避免直接在共享分支上开发。

五十五、qyqy_develop 集成结果及推送记录（2026-09-12）

按用户要求，在独立工作树 group_fqcd_jr/.worktrees/qyqy-integration 中基于最新 origin/qyqy_develop 完成本地集成，并保留用户 ZSY_develop 的主体功能。
冲突处理结论：客服主体采用同事版本的完整实现；保留用户侧访客/已登录用户边界、敏感信息拦截、转人工、Redis 短期会话、画像候选、Neo4j/Milvus 投影及管理员接口；重复客服 Agent 通过兼容导出保留旧引用路径，不重复注册业务实现。
修复了合并后的重复 ORM 表定义、知识检索新旧接口兼容、访客路由恢复和画像快照生成列映射问题；客服 Agent 已关闭长期画像隐式召回。
本地合并提交为 ef701c8 merge: integrate ZSY customer service and profile capabilities，该提交为双父合并提交，父提交分别为 qyqy_develop 最新提交和 ZSY_develop 原提交。
验证结果：核心单元回归 1249 passed, 3 skipped；Ruff 全部通过。跳过项为当前环境未安装的可选文档/绘图依赖相关测试。Mypy 剩余提示来自当前环境缺少 python-docx、python-pptx、Pillow、matplotlib 等包，并非 Git 冲突。
用户要求将集成结果推送到 ZSY_develop。推送命令使用 git push origin qyqy-integration:ZSY_develop，未使用强制推送；首次因独立工作树所有权安全检查被阻止，临时声明安全目录后再次执行，远程返回 Failed to authenticate user，因此本轮没有成功更新远程分支。
当前状态：集成提交已在本地工作树保存，远程 origin/ZSY_develop 是否更新需在恢复 Git 认证后复核；认证恢复后执行普通推送即可，不应使用 --force。

五十六、对话记录归档（2026-09-12）

已将本轮关于 qyqy_develop 与 ZSY_develop 合并、测试、依赖说明、推送尝试及认证失败的讨论追加到本文件。
记录中未写入模型密钥、数据库密码、Neo4j 密码或 JWT 私钥；合并提交和错误信息仅保留必要的排障信息。

五十七、qyqy_develop 增量合并至 ZSY_develop 并推送完成（2026-09-12）

合并前的仓库事实

远程 qyqy_develop 已从上次集成的基线 bbf623a 前进到 c4a73b7，且 bbf623a 是 c4a73b7 的祖先。新增内容为 7 个非合并提交加 1 个合并提交，共 18 个文件、约 2063 行，全部为新增。
新增内容为：账号密码登录接口 POST /api/v1/auth/tokens、RBAC 只读查询接口 4 个（挂在 /api/v1/admin 下）、限流依赖、登录测试台、sys_user 认证现状探查与建人/改密工具。
当时 ZSY_develop 为 cbcf7c7，与远程一致；该分支只有 10 个 controller，qyqy 侧有 18 个，差异来自更早的 foundation 迁移。

冲突预演与路径选择

直接用 ZSY_develop(cbcf7c7) 合并 c4a73b7：公共祖先为 c2178a9，git merge-tree 预演出 18 个冲突文件。其中 app/model/knowledge.py、app/service/knowledge_retrieval_service.py、tests/unit/service/test_customer_service_agent.py、app/core/knowledge_contracts.py 等为 add/add 冲突，即昨天已经处理过的那一批。
在昨天的集成分支 ef701c8 之上增量合并 c4a73b7：公共祖先为 bbf623a，git merge-tree 预演为无冲突。
结论：采用增量合并，复用昨天已完成的语义冲突解决，避免重复处理 add/add 冲突；不建议再从 cbcf7c7 重新裸合并。

执行结果

合并提交 e85989b，双父为 ef701c8 与 c4a73b7；合并引入的文件恰好是 qyqy 的 18 个文件，ZSY 侧文件未被改动。
合并未破坏 ZSY 侧的直接证据：git diff ef701c8 HEAD 的变更集合恰好等于这 18 个文件；全文扫描无冲突标记；git diff --check 通过。
三个双方都改过的文件均为纯新增且两侧改动全部保留：app/main.py 同时注册 auth_router、rbac_router、visitor_tokens_router 与 /customer-service-test 静态页；requirements.txt 同时含 milvus-lite 与 bcrypt；pyproject.toml 同样两者都有。
路由核查：应用可正常导入，OpenAPI 共 115 条路径，无重复 path+method；qyqy 的 /api/v1/auth/tokens、/api/v1/admin/roles 系列与 ZSY 的 /api/v1/visitor-tokens、/api/v1/admin/customer-service/handover-tickets 并存。
ZSY_develop 由 cbcf7c7 快进到 e85989b，已用普通推送（未强推）更新远程：origin/ZSY_develop 现为 e85989b，本地与远程一致。

验证结果

pytest tests/unit tests/contract -q -p no:cacheprovider：1282 passed, 2 skipped, 0 failed。
ruff check app tests tools alembic：All checks passed；mypy app：no issues found in 246 source files。
首次运行时出现 4 个失败，已定位为本地环境缺包（matplotlib、openpyxl、Pillow、python-pptx、alibabacloud_docmind_api20220711），与本次合并无关：相关文件在 ef701c8..e85989b 之间没有任何改动。按合并后 requirements.txt 声明补齐依赖后全部转绿。

本地环境补充

已在 123_py313 按合并后 requirements.txt 补齐：bcrypt、Pillow(<12)、python-pptx、openpyxl、matplotlib、python-docx、alibabacloud_docmind_api20220711 及其配套包。
已修复本地两个远程跟踪引用（origin/ZSY_develop、origin/ZSY_develop2）中少写一位的 SHA；origin/qyqy_develop 已更新为 c4a73b7。
本地 .env、Milvus Lite 数据、JWT 密钥和原有未跟踪文档均未进入提交；合并工作仍在独立工作树 group_fqcd_jr/.worktrees/qyqy-integration 中完成。

后续建议

团队环境拉取最新 ZSY_develop 后需执行一次 pip install -r requirements.txt，新增的登录接口依赖 bcrypt。
启动服务后重点验证 POST /api/v1/auth/tokens 与 GET /api/v1/admin/roles 系列接口，以及客服 Agent 与转人工工单是否仍保持原有边界。
后续继续开发请基于最新 ZSY_develop 新建个人工作分支，避免直接在共享分支提交。

80 KiB Raw Blame History Unescape Escape