实现流程

To-Be 端到端链路；As-Is 见 ENVIRONMENT.md
画像分层见 docs/项目框架设计/表设计/00-架构总览.md

0. 本地 bootstrap（新环境 / 新 Agent）

前置：MySQL 8、Redis、Neo4j Desktop、Ollama(bge-m3) 已安装并启动

① 配置
   cp .env.example .env
   必填：MYSQL_PASSWORD、NEO4J_PASSWORD、DEEPSEEK_API_KEY（对话阶段）

② 依赖
   pip install -r requirements.txt

③ Core 模拟库（L0）
   .\scripts\core\reset.ps1
   → 创建 jinrong_core + 28 客户 / 12 产品 / 持仓交易种子
   （风控演示：再执行 scripts/demo/prepare_risk_demo.sql 刷新测评日期 · PRD §10.2）

④ Agent 共用底座（若库未建）
   mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.sql
   （风控：再建 02-mysql-agent专用.sql 的 risk_aml_list + 灌 scripts/agent/seed-aml-list.sql）

⑤ 同步
   python scripts/sync/sync_advisor_rel.py   → customer_advisor_rel
   python scripts/sync/sync_neo4j.py         → 关系图

⑥ 验证
   uvicorn app.main:app --reload
   GET http://127.0.0.1:8000/health  → {"status":"ok"}
   （可选）Python 调 CoreReadOnlyRepository.get_customer_l0("CUST-10001")

RBAC 联调账号：scripts/dev/rbac-seed-reference.md

尚未自动化： Milvus 建 Collection（T-21）；agent 专用表已有 02-mysql-agent专用.sql（手工执行，含 risk_aml_list）。JWT 中间件已完成（T-01：app/service/auth_service.py + deps.py 工厂；dev 联调签发 scripts/dev/issue_dev_token.py，debug 头兜底仅限 development 且未配 RS256 公钥）。

1. 链路总览（目标）

Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log

当前：风控事件线 + Wave 0 共用底座 + T-04 Tool 节点完成（交易网关 → 规则引擎 → 预警/AML/L3 → 4 API，main.py 路由挂载 + trace 中间件（X-Trace-Id/X-Request-Id + 500 兜底）+ audit 中间件（http_access）+ lifespan 完成，B1~B8；T-01 JWT 鉴权（Bearer 全环境 + dev debug 头兜底 + X-Agent-Type 准入矩阵）/ T-02 审计与 input_guard_log 双写 / T-06 chat 最小闭环（POST /api/chat 会话+窗口+落盘）/ T-07 LangGraph 骨架+DeepSeek（无 key 降级）均于 2026-09-07 完成并经独立 AI 评审闭环；M2 tag risk-m2 + M4 复核闭环；T-04 Core RO Tool 节点（customer/advisor 意图触发 + 归属校验 + agent_tool_call 落库 + 公共鉴权双写 utils/authz.py + 入参白名单，2026-09-07，两轮评审闭环）；321 测试绿）；阶段 B 完结；对话链路已含只读查数（chat → LangGraph(tool→llm→guard) → 免责声明 → 落库），风控四 Tool 与 RAG 待 C1/T-21、输入防护待 T-03。

本机已就位状态（2026-09-07 更新 · 已完成上述 ①~⑤，无需重做）： .env 已配置（学习项目，MYSQL_PASSWORD=123456；NEO4J/DEEPSEEK 留空——DEEPSEEK_API_KEY 空时 chat 走降级回复，不阻塞演示；.env 无 JWT 项，签发走默认 JWT_DEV_SECRET，启动时出现默认密钥 warning 属预期，生产形态须配 JWT_PUBLIC_KEY_PATH）；jinrong_core + jinrong_agent 已灌库（28 客户 / AML 名单 8 条 / 演示测评已刷新 / 归属同步 28 行）；python -m pytest 321 用例全绿（集成测试真连本机 MySQL，未灌库的机器自动 skip 集成模块）；演示库已重灌并清理冒烟数据（2026-09-07），全量测试可直接跑，下次演示/走查后再按 SOP §2 重灌；本机 Redis 服务在跑（redis://127.0.0.1:6379/0，B9a 订阅脚本已验证）。

本机已知坑： mysql.exe 不在 PATH（位于 C:\Program Files\MySQL\MySQL Server 8.0\bin）；reset.ps1 的交互式 -p 在自动化执行时会卡死——脚本化重灌用 MYSQL_PWD 环境变量传密码（交互执行不受影响，不把密码写进仓库脚本）；redis 与 python-jose[cryptography] 包均出现过 requirements 有而环境漏装（B9a 补装 redis、Wave 0 补装 jose，2026-09-07），重装环境后先 python -c "import jose, redis" 自检。

2. 主链路 · 对话

输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息
↓
Gateway：验签、角色准入、注入 AuthContext                    【T-01 已做】（JWT 验签/吊销 + AGENT_ACCESS_MATRIX）
↓
api/chat：SessionGuard；创建/续 agent_session               【T-06 已做】（actor/agent_type 一致校验）
↓
memory_service：Redis 读最近 N 轮；MySQL 落盘 agent_message   【T-06 已做】（窗口 TTL2h N≤20，miss 回源；同步落盘）
↓
agent_service：LangGraph StateGraph + DeepSeek；tool(意图→Tool) → llm → guard  【T-04 已做（tool 节点：关键词意图仅 customer/advisor；risk/analyst 空转）；LLM intent 归 C2】
↓
Tool（tool_service.run_tool：白名单 → 归属校验 → 执行 → agent_tool_call 落库）：
  - CoreReadOnlyRepository：持仓/流水/L0（customer_id 由会话注入，不来自 LLM）  【T-04 已做 app/tool/core_tools.py 三 Tool】
  - 风控四 Tool：alert_query/customer_context/suitability_check/aml_lookup     【待做 C1 chat_tools，复用 run_tool】
  - milvus_tool：产品规则 RAG + source_refs                   【待做 T-21】
  - memory_service：读/写 L1/L2/L3（ProfileGuard）              【窗口读写已做；画像读写待做】
↓
输出：assistant 消息 + has_disclaimer（customer/risk 固定免责，T-07 guard 节点）
↓
落库：agent_message、agent_tool_call（T-04 已接：success/blocked/error 全留痕，message_id 一期 NULL）、audit_log（http_access 已接，同 trace_id）

3. 主链路 · 知识库入库

admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3)
→ milvus_tool 写入 Collection（dim=1024）
→ 元数据可选写 MySQL；原文件存 data/kb/

4. 分支 · 四 Agent

X-Agent-Type	写画像	特殊
customer	L1	仅本人；读 suitability 本人
advisor	L2	customer_advisor_rel 校验
analyst	无	仅 SELECT SQL
risk	L3、预警、适当性	R-02 可 blocked

5. 每步 I/O

步骤	输入	输出	约定
鉴权	JWT	AuthContext	失败 401/403 + audit + input_guard_log 双写（401 归 platform）
会话	session_id	Redis ctx + MySQL session	actor_id 一致（AUTH_403_SESSION_AGENT）
RAG	question + product_id?	chunks + source_doc_id	必须溯源
画像读	customer_id	L1/L2/L3 JSON	RBAC 矩阵 §8
Core RO	customer_id	L0/持仓/流水	只读 jinrong_core
审计	任意判定	audit_log INSERT	不可删改；http_access 经 audit 中间件

6. 关键数据约定

Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql、02-mysql-agent专用.sql
Core 模拟：scripts/core/01-ddl.sql · 说明 docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md
Redis Key：docs/项目框架设计/表设计/02-redis-keys.md
Milvus：kb_product_rules、kb_business_ops；向量 1024 维
禁止：Agent 覆盖 L0 正式 C1~C5

7.2 KiB Raw Blame History Unescape Escape