AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
328 Commits 12 Branches 0 Tags
3134fe5dd0a5592838ce01033d01bd8f7b2f34c5
Commit Graph
328 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
lzf_0626 7635014d9e feat: 画像→图投影打通（按类型写标签，读写对齐；补删除客户端） 
第 2 步（Neo4j）主体，三件事：

1. 新增 app/service/graph_model.py：图模型的**单一来源**。
   节点标签与主属性名会被拼进 Cypher（Neo4j 的标签不能用参数占位），因此必须来自受控常量，
   绝不能是调用方传入的字符串——否则就是 Cypher 注入；同时读服务与投影侧必须就"客户节点
   长什么样"达成一致。此前两边各写各的（投影写 :Entity{entity_id}、读服务查
   :Customer{customer_id}），结果写进去的关系永远读不出来。
   另用 RELATION_SEMANTICS 补上"谁指向谁"的方向校验：底座已有关系白名单（8 种），
   但白名单只约束关系名，不约束方向，这里补上，避免把 TRADED 写成 Customer→Tag。

2. 改 app/worker/graph_projection_worker.py：按 payload 的 source_type/target_type 写具体标签，
   投影前校验关系方向。标签与属性名全部取自 graph_model，调用方传不进任意字符串。

3. 新增 app/service/profile_graph_projection_service.py：把画像事实投影成节点与关系，
   并补上此前缺失的**投影删除客户端**（销户或记忆失效时 DETACH DELETE，同时清悬挂边）。
   只投影 user_facts（与画像同源），不直接读原始记忆——否则同一件事在画像与图里会有两种说法。
   图库故障一律返回 degraded 而不抛异常：投顾推荐可以暂时没有图，但不该因为图挂了
   导致画像更新失败。

背景（核查发现）：MemorySyncOutbox 与 GraphProjectionWorker 此前是**孤儿代码**——表建了、
worker 也实现了（含幂等、重试、死信、MERGE），但没有任何代码往 outbox 写、也没有任何地方
实例化这个 worker，整条图投影链路从未接上过。这正是图中只有 Neo4j 自带 Person/Movie
示例数据的根因。本次把"画像 → 图"这条链路接通；领域事件驱动的投影仍待接入（worker 已修好可用）。

实测验证：
· 投影客户 9001 → relations=1，随后 neighbors(PREFERS) 直接读到
  {'tag_key': 'preference:risk_level=稳健型'} —— 写后读通，标签已对齐；
· delete_customer → 关系归零（degraded=False），重新投影恢复为 1，再次投影仍为 1（幂等）；
· 图中标签为 Customer/Tag、关系为 PREFERS；早先探针残留的 Entity 节点已清理；
· ruff 通过、mypy 112 文件无错。
 2026-09-10 21:43:39 +08:00
lzf_0626 75dff088d4 feat: 接通 Neo4j 图能力（驱动实现 + 装配），并实测确认图模型标签不一致 
第 2 步（图库）的地基部分。

1. 新增 app/infrastructure/graph.py：GraphDriver 协议的 neo4j 实现。
   这层此前是空的——relationship_service.py 里的 GraphDriver 只有 Protocol 声明、没有任何
   具体实现，组装层也没有装配它，因此图读服务在运行期必然降级（neo4j_unavailable）。
   这正是"Neo4j 连读适配器都没有"的根因。
   降级取向与 Milvus 侧一致：本层不吞异常（由调用方决定降级方式），但构造失败返回 None
   ——图库不可用不该让应用起不来，也不该阻塞主链路。

2. bootstrap 新增 get_relationship_service()：装配图读服务。
   该服务只读，关系类型受 ALLOWED_RELATIONSHIPS 白名单约束；写入走 GraphProjectionWorker
   （由领域事件驱动），这里不提供任意写接口——避免出现绕过事件链路的直写路径。

3. 实测确认一处既有缺陷（本次不改，方案待定）：投影 worker 写入的节点标签是
   :Entity {entity_id}（字符串属性），而 RelationshipService.neighbors 查询的是
   :Customer {customer_id}（整数属性），两侧从未对齐，写进去的关系读不出来。
   Neo4j 在执行读查询时直接给出三条警告佐证：未知标签 Customer、未知属性 customer_id、
   未知关系类型 PREFERS——这也说明业务图从未被真正投影过（库中只有 Neo4j 自带的
   Person/Movie 示例数据，共 5 个节点）。

验证：ruff 通过、mypy 110 文件无错；get_relationship_service() 返回 RelationshipService，
neighbors 与 paths 正常执行并返回空集（非降级），非法关系类型被白名单拒绝。
 2026-09-10 21:40:00 +08:00
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
zhangshy a94d5c754d feat: 迁移奶龙风控业务模块与演示文档 2026-09-10 21:03:44 +08:00
lzf_0626 20a3a2f249 feat: 客服闲聊提示词发布为可配置版本（提示词接入发布配置闭环） 
业务方选定提示词走发布配置而不是写死在代码里：改话术要经过审核并留痕，符合金融场景
对口径变更的要求。Agent 侧读取上一批已实现（runtime_config_service.load_active_prompt），
本次补上发布侧，形成闭环。

脚本处理两条路径，实测第一条被拒、自动走了第二条：
1. 直接挂到当前生效版本 → 实测 409「只能修改草稿发布版本」，生效版本不可追加；
2. 新建发布版本，先**原样继承现有全部配置项**再追加提示词。原因：config_release 是
   整版本替换语义，不继承就会把其他 Agent 的工具白名单清空（发布客服白名单时已踩过
   一次这个坑，这次直接带上了继承逻辑）。

结果：新发布版本 174 生效，含 4 条 agent_tools 白名单 + 1 条 prompt_template_version
（prompt_code=customer_service_chitchat、task_type=chat、agent_type=customer_service）。

验证：load_active_prompt 能读到该提示词（release_id=174、version=1、checksum 已生成）；
闲聊功能正常（意图 chitchat 置信 0.95，回答带免责声明）。

顺带记录一处错误码语义问题（本次不改）：对「生效版本不可追加」这种资源状态冲突，
服务端返回的错误码是 RUN_NOT_CANCELLABLE，与场景不符。原因是 docs/05 §3.6 的码表里
没有表示「资源状态不允许该操作」的码，于是被复用了语义最近的运行类错误码。
建议后续在码表里补一个状态类错误码，而不是继续复用无关的码。
 2026-09-10 20:41:09 +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 a7fd02ec44 feat: 新增客服 Agent 手工提问工具 ask_customer_service.py 
批量验收脚本（customer_service_check.py）只覆盖 8 个固定用例，手工试自己的问题时
需要自己签发 JWT、提交 run、驱动执行、解析结果，门槛太高。本工具把这条链路封成一条命令：

    python tools/ask_customer_service.py "基金赎回到账要多久"     # 单次提问
    python tools/ask_customer_service.py                          # 交互模式，同会话连续追问
    python tools/ask_customer_service.py --user 9003 "问题"        # 换身份提问

输出包含：运行状态、识别意图与置信度、处置判定（直接回答 / 引导人工客服）、回答正文、
来源引用，并在"给了答案但正文没有依据"时给出人工核对提示。

注意：脚本自己驱动这一条 run 执行（WorkerRuntime().execute），运行前需停掉常驻 Worker，
否则常驻 Worker 会从共享队列抢走任务，脚本将等不到结果。
 2026-09-10 20:24:33 +08:00
张胜宇 24f75636a0 feat: add knowledge import preflight 2026-09-10 20:22:53 +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
张胜宇 e9b3d272f0 feat: add governed customer service agent 2026-09-10 19:51:08 +08:00
张胜宇 511a8ca18f feat: add governed public knowledge retrieval 2026-09-10 18:42:44 +08:00
lzf_0626 a876e9ead7 docs: 新增四大 Agent 流程实现拆解（客服/投顾/风控/场外运营） 
对四份需求文档（智能客服方案 v1.3、基金运营流程、风控模块详细业务流程、投资顾问流程）
与现有底座逐项比对后的实现拆解，用于开工前明确边界、工作量与决策点。

核心结论：可实现。底座 52 张表与流程设计高度吻合——风控的
ack_status/is_escalated/close_reason/trigger_rule_codes、客服的 svc_handover_ticket.confidence、
投顾的 client_facing_content.review_status、biz_work_order 的双录与风险揭示字段均已在位；
客服方案的七步骨架与 BaseAgent 骨架完全一致；适当性 C1-C5/R1-R5 已实现且不接受调用方传值；
风控文档定义的 SSE 事件（start/tools/delta/replace/done）与底座现有实现完全一致。

文档内容：
1. 覆盖度总览 + 四模块逐项拆解（已就绪 / 需新写 / 必须业务补充）。
2. 指出两处真实缺口：邮件 SMTP 在 app/ 中零实现；规则引擎只有 trigger_rule_codes 字段
   而无引擎本体（风控明确要求"规则引擎产生预警、Agent 不产生"，属确定性逻辑，不能用模型代替）。
3. 指出场外运营是唯一需要新建表的模块（底座 15 张 fin_* 全为场内模拟交易，
   AGENTS.md 要求场外流程独立，不得写入场内交易表）。
4. 列出 6 个必须先决策的事项：接口形态（底座异步 + SSE vs 方案的同步 chat/customer）、
   模型与 embedding 维度（直接决定 Milvus 集合 schema）、RAG 混合判定公式（方案未给）、
   规则引擎的承载方式、场外运营排期、合规校验前置还是后置。
5. 建议开工顺序：客服 → 投顾 → 风控（规则引擎宜单独立项）→ 场外运营（缺真实单据样本）。

说明：本提交只含拆解文档，不含需求原文。需求原文的纯文本提取物位于 _flows/（未跟踪），
是否入库待定；临时提取脚本已删除。
 2026-09-10 18:35:52 +08:00
lzf_0626 2c5ef35d18 chore: 删除退役的旧 JWT 密钥，同步过时引用并记录登录接口决策 
1. 删除 config/jwt/jwt-private.pem 与 jwt-public.pem（旧密钥，配置已不再指向）。
   删除后复跑全量门禁以确认没有残留依赖：ruff 通过、unit+contract 447 passed、
   acceptance_check --production 7 PASS、demo_agent_e2e 9/9 PASS。
2. 修掉 4 处引用旧密钥路径的地方（它们会在删除密钥后直接失败或误导接入方）：
   - tests/unit/core/test_security.py 的三处硬编码路径改为单一常量 DEV_KEY_DIR，
     否则删除旧密钥后该测试会因读不到文件而失败；
   - tools/demo_agent_e2e.py 的 docstring 前置条件；
   - docs/09 的配置示例；docs/19 的手工自签说明（改为指向配置项与
     tools/generate_jwt_keys.py）。
3. docs/21 记录旧密钥已删除，并注明删除后已复跑验证无残留引用。
4. docs/19 未解决项新增第 5 条：无登录接口属于**有意识的推迟**（等业务 Agent 开发阶段
   结束后再补），写明补的时候只需动签发侧、验签侧与身份解析侧都不需要改，
   并附上当前私钥边界的实测结论（无法伪造不存在的用户、无法使用已禁用账号）。
 2026-09-10 18:18:00 +08:00
lzf_0626 c32d3dbd06 chore: 开发专用 JWT 密钥、密钥生成脚本与轮换文档 
背景：此前全环境共用一把 JWT 密钥（config/jwt/jwt-private.pem）。它相当于
"能冒充 9001/9002/9003 的万能钥匙"（实测边界：签名有效 + 用户存在且启用才通过，
伪造新用户与使用禁用账号都会被拒）。为避免同一把密钥将来又变成生产密钥，
本次引入开发专用密钥，并把签发侧收敛到配置。

改动：
1. 新增 tools/generate_jwt_keys.py：可复现地生成 RS256 密钥对（PKCS#8 / SPKI），
   打印公钥 SHA-256 指纹便于核对服务端加载的是否同一把；密钥已存在时默认拒绝
   覆盖，避免误操作导致所有已签发令牌立即失效。
2. 生成开发专用密钥到 config/jwt/dev/（该目录整体已被 .gitignore 忽略，不入库）。
3. 三个工具脚本不再硬编码私钥路径，改为读配置：acceptance_check 与 demo_agent_e2e
   走 get_settings().jwt_private_key_path，smoke_check 因刻意不依赖 app 包而读
   JWT_PRIVATE_KEY_PATH 环境变量。今后轮换密钥只需改 .env 一处。
4. .env、.env.example 与 Settings 默认值统一指向 config/jwt/dev/。
5. 新增 docs/21-JWT密钥管理与轮换.md：密钥分工（服务端只读公钥，
   JWT_PRIVATE_KEY_PATH 在 app/ 中无任何读取点，故生产机可只挂公钥）、
   克隆后必须自行生成、多人共用一个服务时必须共用同一把私钥、
   轮换的影响面与生产部署要点、安全红线。
6. 记录一处易被忽略的问题：生产环境的 JWT_ISSUER / JWT_AUDIENCE 也应与开发不同，
   否则开发环境签发的令牌在生产上依然有效——这比换密钥更容易漏。

说明：本次提交不含任何密钥文件（.env 与 config/jwt/ 均在 .gitignore 中）。
旧密钥 config/jwt/jwt-private.pem 已退役但保留未删，配置不再引用它，
用它签发的令牌会被拒绝。

验证：ruff 通过、mypy 103 文件无错、unit+contract 447 passed、integration 29 passed、
acceptance_check --production 7 PASS、demo_agent_e2e 9/9 PASS——均使用新密钥完成
签发与验签。
 2026-09-10 18:14:03 +08:00
张胜宇 ba22a2220f feat: preserve isolated visitor agent runtime 2026-09-10 17:36:39 +08:00
张胜宇 8e36a9941d merge: preserve existing business features on new foundation 2026-09-10 17:26:52 +08:00
张胜宇 a789872c79 test: record pre-migration workspace evidence 2026-09-10 17:11:52 +08:00
张胜宇 d0793355fc docs: add foundation migration implementation plan 2026-09-10 16:59:53 +08:00
张胜宇 5ebed374c4 docs: add safe foundation migration design 2026-09-10 16:36:36 +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
张胜宇 ad7172367a feat: add limited visitor tokens 2026-09-10 13:56:08 +08:00
张胜宇 c6be99078e chore: ignore local worktrees 2026-09-10 13:33:59 +08:00
yuancong_0626 5907fcd6d2 袁聪的第一次提交，包含nl2sql,行情数据,场外申购 2026-09-10 09:23:22 +08:00
lzf_0626 46fc976b24 feat: add shared fund quote capability 2026-09-09 23:40:35 +08:00
lzf_0626 ca680ca46f feat: 删除垃圾文件 2026-09-09 22:14:40 +08:00
Codex b1497fd2c6 chore: initialize project repository 2026-09-09 21:55:37 +08:00