AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
14 Commits 12 Branches 0 Tags
962a0a116f89cea462bbda375f0fb3fcb7ed491c
Commit Graph
8 Commits
Author SHA1 Message Date
lzf_0626 962a0a116f feat: 记忆→画像打通（事实提升 + 画像组装 + 版本快照） 
补齐"记忆系统为画像服务"的断链，按 docs/23 的分层设计实现后三层。

1. 新增 app/model/profile.py：user_facts 与 profile_snapshots 的 ORM 映射。此前这两张表
   只有结构、没有 Model，实际没有任何代码在用。两处表结构特例在 docstring 里显式标注，
   避免后续有人按直觉写入踩坑：
   · user_facts.id 无 auto_increment，主键必须由应用提供（本实现用微秒时间戳，单调递增）；
   · profile_snapshots.current_customer_id 是生成列（IF(is_current=1, customer_id, NULL)），
     故意不映射——映射了反而会在写入时与之冲突。

2. 新增 app/service/profile_assembly_service.py，三段职责：
   · 事实提升（中期→长期）：evidence_count ≥ 2 或 confidence ≥ 0.90 才从 memory_unit
     提炼进 user_facts —— 这条门槛就是"客户随口一说不能变成画像结论"的落地方式；
   · 画像组装（长期→画像）：按白名单映射进 fin_customer_profile，未列入白名单的事实
     （如 profile:family）只进 user_facts，保证画像的信噪比；
   · 版本留痕：每次重建写一条 profile_snapshots，generation_basis 逐字段记录来源，
     用于回答"当时凭什么这么判断"。

3. 新增 tools/rebuild_profile.py：手工触发入口（单客户或 --all）。画像暂无自动触发，
   这是目前唯一的重建方式，也便于排查"画像为什么没更新"。

红线由代码保证而非约定：investor_type 只从 fin_risk_assessment 最新一条读取，实现中
不存在任何记忆路径能写它。实测——客户 9001 问卷为 C2、对话自述"稳健型"，重建后
investor_type 仍为 C2，自述信息进入 risk_tags 并标注"自述:"前缀。三方不一致保持可见，
但等级判定只认问卷，客户无法靠对话改变自己的可购范围。

另一处由实测修正的设计：fin_customer_profile 的 trade_account/real_name/total_asset/
behavior_score 均为 NOT NULL，说明画像行由开户流程创建（也印证了"注册时填问卷"是开户
前置条件）。原先"首次重建时创建画像行"的做法是错的——会写出一条假的开户记录，而画像
恰恰是风控要读的数据。已改为只更新已存在的画像，未开户时返回 reason=profile_row_not_opened
并如实报告，而不是静默成功。

同时新增 docs/23-记忆分层与画像设计.md：短期/中期/长期/画像四层各自存在哪里、谁写、
提升门槛、是否进画像，以及三条路径（问卷/行为/对话）在画像层汇合的设计。

验证：ruff 通过、mypy 109 文件无错；tools/rebuild_profile.py 对客户 9001 连续两次重建
产生 version=1/2 两条快照且 is_current 正确轮转（旧版本置 0）。
 2026-09-10 21:36:23 +08:00
lzf_0626 1fa5fc7d03 refactor: 客服回答正文只保留固定免责声明 
业务方要求客户侧只看到一句固定话术（不构成投资建议），因此从回答正文移除：
1. 中置信的「（以上信息可能不完整，具体以产品说明书与公司制度为准）」提示；
2. 「（依据：…）」出处行——原先它显示的是知识块标题，FAQ 的标题就是问题本身，
   展示为「（依据：公司什么时候成立的?）」并没有可读价值。

可追溯性不受影响：本次命中哪个知识块仍由审计（agent.tool_executed 的工具调用记录）
与消息表留痕，source_references（tool 类型）也照常返回，只是不再面向客户展示。
取舍已在代码注释中标明：中置信回答此后不再向客户标注不确定性。

若将来要把出处展示给客户，应当走 source_references 的 knowledge 类型
（前提是让 ToolExecutor 把工具返回的 doc_id 登记为本次可引用来源），
而不是继续往正文里拼字符串。

同时移除因此不再使用的 INCOMPLETE_NOTICE 常量、_source_note 方法，
以及提问工具里那句"正文没有依据行"的提示。

验证：ruff 通过、mypy 107 文件无错；customer_service_check 9/9 通过；
ask_customer_service 实测回答正文为「答案 + 免责声明」两行。
 2026-09-10 20:33:13 +08:00
lzf_0626 66595ce080 fix: 客服置信判定改为「绝对阈值 + 相对间隙」混合判定 
问题（业务方实测发现）：问「我们公司叫什么名字」被引导人工，但公司名称就在知识库里
——FAQ-0001「公司全称是什么?」与 COMP-001 都稳定命中 top1。所以根因不是检索不准，
而是判定规则不完整：客服方案 §2.3 要求的是「绝对阈值 AND（相对间隙 OR 分布优势）」，
实现里只做了绝对阈值 0.60。

实测校准（qwen3.7-text-embedding-flash，COSINE）：

  库内问法                top1     top1-top2
    我们公司叫什么名字      0.592    0.100
    你们公司名称是什么      0.579    0.090
    公司全称是什么          0.671    0.098
    你们公司总部在哪        0.764    0.245
    南方科技的全称          0.855    —

  库外 / 越界             top1     top1-top2
    你们公司什么时候上市    0.500    0.046
    推荐明天肯定涨的基金    0.488    0.023
    我要投诉                0.492    0.025
    今天天气怎么样          0.416    0.035
    量子计算机退相干        0.416    0.044

两条结论：一是同为正确命中，口语问法的相似度天然偏低（0.592 vs 0.855），单用绝对阈值
必然误判；二是库内命中的 top1 领先幅度（≥0.09）显著大于库外（≤0.046），间隙是有效判别信号。

新规则：≥0.75 直接答（不再要求间隙）；≥0.55 且间隙 ≥0.07 则回答并附「信息可能不完整」
提示；其余一律引导客户致电人工客服。两侧余量：库内最低 0.579、库外最高 0.500。

验证：ruff 通过、mypy 107 文件无错；ask_customer_service 对「我们公司叫什么名字」
正确返回南方科技有限公司；customer_service_check 由 8 项扩为 9 项，全部通过，
其中「推荐明天肯定涨的基金 / 我要投诉 / 量子计算机退相干」三条必须引导人工的用例
未被放宽后的阈值误答。
 2026-09-10 20:29:12 +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
lzf_0626 d2aff7c129 feat: 建客服知识库（Milvus 三集合）并修复模型端点筛选缺陷 
一、知识库建设
- 新增 tools/build_knowledge_chunks.py：把 knowledge/ 下文档切成可检索知识块。
  采用「叶子标题」策略（其后没有更深标题的标题即切分点），同时覆盖三种真实结构：
  带子条款的按子条款切、无子条款的条款单独成块、无小节的章整章成块。
  第一版按固定标题级别切是失败的——适当性指南的条款是 ### 而没有 ####，产品手册的
  ### 1.1 又不匹配「第X条」，两条规则互相打架，导致 4 个文件一块都没切出来。
- 新增 tools/load_knowledge_milvus.py：向量化并写入 Milvus，用 upsert 保证幂等。
  schema 按方案 §4.2 统一字段，另加 chapter/section/source_file/doc_no/visibility 五个
  检索与合规必需字段；索引 IVF_FLAT + COSINE + nlist=128；向量输入取「标题+正文」，
  标题含条款号与章节名，是比正文更干净的检索信号。
- 知识内容按业务范围裁剪：反洗钱合规操作手册不入客服知识库（业务只做公募基金、
  不涉及资金划付，且该手册标注内部机密、禁止向客户透露可疑交易信息），留给后续风控；
  高净值客户服务规范只保留「客户分层标准」与「各层级专属权益」两章，
  家族信托、资产配置流程、客户经理考核、隐私应急预案等内部管理章节不入库。
- 入库现状：fin_faq_collection 61 块、fin_product_collection 26 块、
  fin_policy_collection 73 块，合计 160 块。检索自检 5/6——未命中的一条分数 0.660
  落在中置信区间，按三档兜底策略本应提示信息可能不完整，属于预期行为。

二、embedding 端点
- 新增 tools/configure_embedding_endpoint.py：走管理 API（draft→approved→active）
  配置并激活 qwen-embedding 端点，而不是直接写库。理由是状态机与审计都要留痕，
  且 DatabaseModelGateway 只认 status='active'，手工写错状态会报成与病因无关的
  「模型端点未注册或未激活」。脚本先查 endpoint_code 是否已存在，幂等可重跑。

三、修复模型端点筛选缺陷（app/service/model_gateway.py）
- 原 DatabaseModelEndpointResolver 忽略 agent_type 与 task_type、直接返回全部 active
  端点，而 ModelDispatchService 只按顺序尝试前 max_attempts（默认 2）个。两者叠加使
  「能否选到支持该任务的端点」取决于端点表顺序：实测每次 embedding 都先拿文本生成
  端点失败一次再落到向量端点（0.61s，修复后 0.42s）。
- 新增 TASK_CAPABILITY 显式映射后按能力筛选。用映射而不是同名筛选是必需的：
  memory_extraction 并不是任何端点的能力名（deepseek 声明的是 text_generation 等），
  按同名筛会得到空集、把记忆抽取打成失败关闭——这是本次修复最容易引入的回归。
- 保守兜底：未映射的 task_type、以及没有任何端点声明该能力时，都退回全部端点，
  让配置缺口表现为调用失败，而不是让上层收到「解析为空」这种与病因无关的报错。
- 验证结果：embedding→[qwen-embedding]、intent_classification→[deepseek-flash]、
  memory_extraction→[deepseek-flash]、未映射 task_type→全部；ruff 通过、
  mypy 103 文件无错、unit+contract 447 passed。

四、需求文档提取物
- 新增 _flows/：三份流程文档（智能客服 Agent 专项设计方案、投资顾问流程、基金运营流程）
  的纯文本提取，供开发期对照。原始 .docx/.html 保留在业务方目录侧。

说明：本次仅本地提交，未推送远程仓库。knowledge/ 内含公司内部制度与产品资料，
是否入远程库待确认。
 2026-09-10 20:15:09 +08:00
lzf_0626 6516ccb385 feat: 第二版——接口契约对齐 docs/05，修复静默故障与数据库基线 
相对第一版 46fc976 的完整变更。组员迁移对照表见 docs/20。

一、对外契约对齐 docs/05（破坏性，共 4 处，组员需按 docs/20 调整）
1) 配置发布端点改为文档规定的复数资源名：submit→validations、
   approve→reviews（需 body decision）、activate→activations、
   rollback→rollbacks；第一版这 4 个动词式路径 docs/05 从未定义过。
2) 错误码由 8 个笼统码改为 15 个具体语义码（FORBIDDEN→AGENT_PERMISSION_DENIED、
   UNAUTHORIZED→AUTHENTICATION_REQUIRED、CONFLICT→RESOURCE_VERSION_CONFLICT、
   RESOURCE_NOT_FOUND→RUN_NOT_FOUND/SESSION_NOT_FOUND 等），
   输入类错误状态码 400→422。
3) POST /api/v1/agent-runs 与 GET /api/v1/agent-runs/{run_id} 统一为
   {data, meta} 信封（data 内字段名与语义未变）。
4) 错误响应体统一为 {error:{code,message,retryable,field_errors}, meta:{trace_id}}，
   不再返回 FastAPI 默认的 {"detail": ...}。

二、数据库基线与约束
新增 39 张表的基线迁移（链根）与联合唯一键纠偏（4 张表、删 8 增 4，幂等收敛）；
撤下 config_release 的双人复核 CHECK（应用层已允许自审，审核节点保留，
自审如实写入 reviewer_id）；记忆 active key 生成列与唯一键；
activate 开始记录 supersedes_release_id 使版本链可追溯。
docs/00 基线未修改，未重命名或删除任何表与字段。

三、修复会静默出错或无报错的缺陷
- 跑完集成测试后平台会静默失去生效配置：清理只删自己创建的版本，却没有恢复被它
  顶成 superseded 的原生效版本，且审计一并删除因而完全无痕，表现为所有工具被拒
  但没有任何报错。已修清理逻辑并加恢复。
- Worker 单轮异常导致进程退出；记忆抽取调用方的“事务已开始”异常；
  召回缓存丢失 degraded 标记；连接时区未生效导致 created_at/updated_at 差 8 小时；
  .env 与 os.getenv 密钥来源分裂导致“没有可用的已批准模型端点”。
- 记忆信号识别漏判与跨键误命中；SSE 未带 Accept 的协商行为。

四、功能补齐
记忆链路 P1/P2/P3（抽取、受控词表、召回与缓存、生命周期级联及投影事件）、
fin_* 场内交易只读 ORM 层、agent_intent_config 状态流转并在运行期真正生效、
限流（Redis 固定窗口、故障一律放行）、游标校验、trace_id 中间件、
示例业务 Agent fund_query_demo 与一键端到端验证脚本，以及审计/指纹/迁移状态工具。

五、文档与验证
新增 docs/19（业务 Agent 接入实操）、docs/20（第一版迁移指南）与 docs/evidence 证据；
docs/01/02/06/08/09/17 同步实现现状。

验证结果：ruff 通过、mypy 103 文件无错、unit+contract 447 passed、
integration 29 passed、acceptance_check --production 7 PASS、
demo_agent_e2e 9/9 PASS（含失败关闭反证）。
 2026-09-10 15:55:54 +08:00
lzf_0626 46fc976b24 feat: add shared fund quote capability 2026-09-09 23:40:35 +08:00
Codex b1497fd2c6 chore: initialize project repository 2026-09-09 21:55:37 +08:00