group_xinghuo_jinrong/docs/memory/MEMORY.md

项目记忆（人 + Agent 共用）

各阶段的简化快照（门闸索引）。只留基础信息，不写源文件正文。
新 Agent 无上下文：先读本节 → 第 0 节交接清单 → 按需打开源文件。

---

0. 新 Agent 交接（5 分钟）

项目是什么： 金融四 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座；不互调 LLM，跨 Agent 走 L1/L2/L3 画像与预警表。

当前进度： 需求与表设计已定 · 风控 B1B9b + C4C6 + chat B/C + AL-09 合并 · 代销平台 API v0.1 · 客服 Agent S2 收尾（visitor + customer 分流 · fin_* KB · Wave 1~5 绿 · CS-C-11 迁移） · 730 passed · web/ 前端 P0 主链路已真接（ChatPanel · 游客试聊 · 四 Agent 对话 · 平台只读页 · 行情 · 风控台账处置） · npm run build/test/lint 绿（19 例 Vitest） · Redis：Docker jinrong-redis @ 127.0.0.1:6380。下一步：analytics 问数页 · 接口契约发群 · customer Chat SSE（后端未接 stream）。

工作分支： 团队开发在 merger（已 merge 风控模块）；历史开发分支 risk-control-agent 交付冻结。旧文档中「待 AL-09 合并」口径已过时。

仓库地图：

路径	状态	说明
app/main.py	已集成（AL-09）	宿主 TraceMiddleware + 模块 audit/trace + 路由（auth/platform/chat/risk/simulate）+ lifespan
app/api/auth.py	已实现（AL-09）	Mock 登录；签发走 auth_service.issue_dev_token（与模块 API 同一 issuer）
app/api/auth_adapter.py	已接线（S2）	module_auth_from_host()：宿主 AuthContext → 模块 AuthContext
app/gateway/	宿主 Wave 0（并存）	jwt_service / auth_deps / rbac / ownership；模块 API 走 deps.py，禁止模块 import gateway
app/api/risk.py simulate.py deps.py	已实现	风控 4 API + 模拟网关路由 + JWT 鉴权工厂（T-01：Bearer 全环境优先；debug 头仅 dev+无 RS256 公钥时兜底；AGENT_ACCESS_MATRIX 准入）
app/api/chat.py audit_middleware.py	已实现（T-06/T-02 + 前端接入 B/C + 客服 S2）	POST /api/chat（customer 分流 → customer_service · 其余 → agent_service）· POST /api/chat/visitor（试聊）· 前端拉侧三端点 · SSE POST /api/chat/stream
app/api/customers.py products.py advisors.py staff.py compliance.py	已实现（v0.1）	代销平台 REST；get_platform_auth_context（无 X-Agent-Type）；Service 层 app/service/platform/
app/api/knowledge.py admin.py	空壳	待审计查询台与知识库 API（T-21 拍板一期只做脚本入库，上传/重建端点不做）
app/service/platform/	已实现（v0.1）	封装 core_ro + PLATFORM_RESPONSE_DESENSITIZE 脱敏开关
app/service/embedding.py milvus_service.py rag_service.py	已实现（T21-1/2/4）	Ollama bge-m3 1024 维（失败不静默降级）/ kb_product_rules 建集合+upsert+合规过滤检索 / search_knowledge→chunks+source_refs 溯源
app/tool/kb_tools.py	已实现（T21-5）	search_knowledge 对话 Tool（skip_access_check 公开知识；仅 customer/advisor 意图开放，risk 不开放）；kb_product_rules 首批 24 块已入库（data/kb 6 产品手册，scripts/kb/build_kb.py 可重灌）
app/service/auth_service.py	已实现（T-01）	Auth SDK：JWT 验签（HS256 dev/RS256 生产）、必填 claims、jti 吊销（Redis fail-open）；签发 CLI scripts/dev/issue_dev_token.py
app/service/risk/* + service/suitability.py	已实现	RISK-001005 规则 / 预警聚合 / L3 写入 / AML / 引擎编排 / suitability（**阶段一换核：内核改调 core_ro.check_suitability，SUIT-001008 已退役**）/ locks+redis_gateway 公共原语（B7）
app/service/agent_service.py memory_service.py	已实现（T-07/T-06/T-04/C2 + 方案 C）	LangGraph StateGraph（tool→llm→guard）+ DeepSeek（无 key 降级）；T-04 tool 节点（关键词意图 customer/advisor/risk 分组 + tool_service.run_tool）；C2 tool_node 守卫放宽（requires_customer=False 允许无绑定客户，支撑 A-6 全量待审）；Redis 会话窗口 + MySQL 回源。方案 C：stream_chat 生成器（Tool 同步跑完→逐块推 LLM 文本）+ needs_disclaimer（首帧 meta 与落库尾部共用口径）
app/service/tool_service.py app/tool/core_tools.py service/risk/chat_tools.py	已实现（T-04/C1）	对话 Tool 编排（统一注册表 get_registered_tool：core+risk / 归属校验 / agent_tool_call 落库）+ Core RO 三只读 Tool（L0/持仓/流水）+ C1 风控四只读 Tool（alert_query/customer_context/suitability_check/aml_lookup，RISK_TOOL_REGISTRY）
app/repository/session_repository.py	已实现（T-06/T-04 + 前端接入 B/C）	agent_session / agent_message / agent_tool_call 读写；方案 B 增 list_sessions（分页+total）/ list_messages_page（seq 升序分页，勿与 LLM 窗口的 list_messages 混用）/ close_session（条件更新防并发）；方案 C 增 insert_turn（user+assistant 同事务落库 + 事务内取 seq，修评审 P0/P1）
app/gateway/	已实现	模拟交易网关（仅 gateway_repository 可 INSERT core_trade，B5）
app/repository/core_ro.py	已实现	Core 只读 SELECT（含风控扩展 sum_trades_on_date / list_trades_range / list_active_customers）；阶段一吸收 main：check_suitability（C×R 矩阵判定，CURDATE() 改 Python 端 _is_expired）/ list_products_for_customer / list_holdings 合并（limit=500+新列）/ list_trades / get_customer_l0 扩列版
app/repository/risk_repository.py	已实现	risk_alert / risk_suitability_log / L3 / risk_aml_list / audit_log / input_guard_log 读写
app/utils/	基本就绪	trace（trace_id+request_id 双 contextvar）/ desensitize / db（引擎工厂）/ response（统一错误体+4xx/500 handler）/ exceptions（含 ApiError）已实现；logger 占位
app/config/database.py	已实现	MySQL 双引擎 + Redis 单例（REDIS_URL · RESP2 protocol=2 兼容 Docker Redis 7 / 旧 Windows Redis 3）
app/config/settings.py	已实现	双库 + risk_* 阈值 + JWT + customer/visitor/profile 字段 + kb_root_dir
app/service/customer_service.py visitor_service.py	已实现（S2）	客服 14 节点 · 游客 9 节点 LangGraph；RAG 走 fin_ 三库*；Redis 记忆 fail-open
scripts/core/*.sql + reset.ps1	已实现	Core 模拟库 DDL + 种子
scripts/agent/ scripts/demo/ scripts/dev/	已实现	AML 种子 + 演示数据 + run_sql_file.py + start-redis.ps1（Docker Redis 优先）+ issue_dev_token
scripts/sync/*.py	已实现	归属同步 + Neo4j 全图
tests/	已实现	37+ 测试模块 730 用例 0 skipped（含客服 Wave 1~5；sqlite + 真 MySQL 集成；test_module_boundary 宿主 D 类排除）。改路由必同步 tests/test_main.py::test_all_routers_mounted
docs/需求拆解/	已定	场景 P0、矩阵、合规原文
docs/PRD/PRD-风控监测Agent.md	已冻结（v1.1）	风控 PRD v1.0 + v1.1 追加 FR-8/9/10（§4A）+ 规则表附录
docs/项目框架设计/实现方案-风控追加需求v1.1-C4C6.md	已定稿	C4~C6 编码依据（经独立 AI 评审修订闭环）；分支/进度速览另见项目根 交接文档.md
docs/项目框架设计/合并注意事项-风控模块并入main.md	AL-09 已执行（2026-09-08）	合并接线完成；接缝见《风控Agent模块边界与合并接缝标注.md》
docs/项目管理/04-从需求到公共API开发方法.md	已定（2026-09-08）	需求→矩阵→存储→Service→API→Agent 主线；Phase A 清单
docs/项目框架设计/接口契约-代销平台API-v0.1.md	已定（2026-09-08）	代销平台 REST canonical 路径、命名规范、Agent 迁移表
docs/项目框架设计/C-05-行情数据源选型对比.md	已定（2026-09-09）	C-05 净值数据源分阶段选型；禁止爬虫/前端直连第三方
docs/项目框架设计/接口契约-代销平台API-v0.2-行情扩展草案.md	草案（2026-09-09）	nav-snapshot · sync_market_nav · 前端产品行情 Phase B
docs/项目框架设计/表设计/	已定	Agent 共用 11 表 + agent 专用 SQL
docs/项目框架设计/Core模拟底座/	已定	无真实 Core 时的 L0 方案
web/	静奢智能 UI + P0 真接（2026-09-09）	ChatPanel/useChatPanel · customer 同步 Chat · risk/advisor/analyst SSE · 登录页 VisitorChatWidget · 档案/持仓/流水/行情/风控台账+处置 · web/src/api/chat.ts · 交接 docs/frontend/FRONTEND-HANDOFF.md

本地 bootstrap（首次）： 完整步骤与前置说明见 FLOW.md §0（权威），速览：

1. cp .env.example .env  → 填 MYSQL_PASSWORD、NEO4J_PASSWORD、DEEPSEEK_API_KEY
2. pip install -r requirements.txt
3. .\scripts\core\reset.ps1                        # 建 jinrong_core 模拟库 + 种子
4. mysql … < 01-mysql-共用底座.sql                  # jinrong_agent 共用 11 表
   mysql … < 02-mysql-agent专用.sql                 # 风控四表 + risk_aml_list
5. mysql … < scripts/agent/seed-aml-list.sql       # AML 名单（Windows 乱码：`python scripts/dev/fix_utf8_seed.py`）
   （风控演示：scripts/demo/prepare_risk_demo.sql，reset 后重跑）
6. python scripts/sync/sync_advisor_rel.py && python scripts/sync/sync_neo4j.py
7. `docker compose up -d redis`（或 `.\scripts\dev\start-redis.ps1`）→ **REDIS_URL=redis://127.0.0.1:6380/0**（Docker Redis 7；避开本机 Windows Redis 占 6379）
8. uvicorn app.main:app --reload → GET /health；`cd web && npm run dev`（5173 代理 8000）；python -m pytest（**730 绿**）

AL-09 合并后架构（一句话）： 宿主 gateway/ + 模块 deps.py 双栈并存；对外登录/token 统一；chat/risk 均走模块鉴权；接缝 S2 用 auth_adapter。

下一步（见 TODO）： analytics 问数页 · 接口契约发群 · customer Chat 流式（后端 /stream 未接 customer_service）· simulate 交易 UI（不做）。

Redis（2026-09-09）： 推荐 Docker jinrong-redis（redis:7-alpine）· 宿主机 6380 → 容器 6379 · .env REDIS_URL=redis://127.0.0.1:6380/0 · 客户端 RESP2（database.py / redis_gateway.py）。

前端启动（web/）： npm install → npm run dev（5173，/api 代理 8000）· 验收四 demo 账号见 docs/frontend/FRONTEND-HANDOFF.md §8 · 改 UI 后跑 npm run build && npm run test && npm run lint。

平台 API 硬规则（2026-09-08 拍板）： 路由 A · 按业务域（/api/customers 等）；与 Agent 功能重复时 以本平台 API 为准；命名见契约 §2；合并时统一改 canonical 路径。

禁止（改代码前必记）： Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM。

里程碑 tag 中文对照（tag 本体保留英文原名——git 技术标识符需跨平台/脚本稳定引用，符合「技术字面量保留英文」约定；中文名经对照表统一）：

tag	中文名	状态
risk-m1	阶段A · 适当性校验可用	已补打（2026-09-07，指向阶段 A 完成提交 3c07de6，历史归档）
risk-m2	阶段B · 事件线全链路	已打（2026-09-07，附注含验收走查记录）
risk-m3	阶段C前半 · 对话线闭环	已打（2026-09-07，指向 C1~C3 完成提交）
risk-m4	追加需求 · C4~C6（FR-8/9/10）	已打（2026-09-07，annoted tag 指向 323d98b，仅本地未 push；C4 fe4801b/C5 90d0660/C6 66ec7eb 三提交 + 文档落账 323d98b，全量 482 绿，挂账 #1~#9 核对无违规）
risk-align1（拟）	阶段一 · 对齐 main 基准	待定（AL-01~08 已完成，是否为此打 tag 由用户拍板；当前仅 AL 逐项 commit）

---

1. 项目简介

• 名称： JinRong 金融四 Agent 智能管家
• 当前阶段： 代销平台 v0.1 + AL-09 + 客服 S2 + 前端 P0 主链路真接（2026-09-09）——730 pytest 绿 · 19 Vitest 绿
• 当前优先级： analytics 问数 · 接口契约发群 · customer SSE（后端）· simulate UI（显式不做）

---

2. 阶段快照

阶段	当前一句话	源文件
服务对象大环境	公募四类角色；无真实 Core，L0 由 jinrong_core 模拟库供给	ENVIRONMENT.md
需求目的	四 Agent + 统一数据层 + 合规可审计；Wave 0~3 P0 见 REQUIREMENTS	REQUIREMENTS.md
项目框架	FastAPI 分层 + LangGraph + MySQL 双库/Redis/Milvus Lite/Neo4j + React	FRAMEWORK.md
实现流程	Gateway JWT → chat → LangGraph → Tool → 审计；bootstrap 见 FLOW §0	FLOW.md

---

3. 约束

硬阀门：技术选型

docs/项目框架设计/技术选型和版本/01-技术栈与版本.md 中已标「已定」视为用户确认；新增依赖须再确认。

禁止触碰：

Core 正式 C1~C5、持仓/交易真账（Agent 只读；当前为模拟库）
audit_log 等审计表（只 INSERT）
代理人草稿自动外发客户
风控自动冻户 / 改正式风险等级
各 Agent 自建第二套 JWT/RBAC

高风险（改前需确认）： 数据库表结构、JWT/RBAC、部署密钥、删生产数据。

开发开关：

项	YES / NO
允许新增依赖	YES（对齐技术选型文档）
允许重构	YES（最小范围）
允许改表 / schema	需确认
允许改接口协议	需确认

特殊规则：

四 Agent 不互调 LLM；跨 Agent 走 L1/L2/L3 画像与预警表
客户 Agent：无投资建议/收益承诺/自动下单
代理人：不对 C 端直发
数据分析：仅 SELECT，不处置预警
画像不得覆盖 L0 正式测评

---

4. 入口与运行

后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py
Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql · 02-mysql-agent专用.sql（含 risk_aml_list）
Core 模拟：scripts/core/reset.ps1 · 文档 docs/项目框架设计/Core模拟底座/
种子：scripts/agent/seed-aml-list.sql（AML 名单）· scripts/demo/prepare_risk_demo.sql（reset 后重跑）
依赖：requirements.txt（LangGraph + langchain-core/openai + FastAPI + SQLAlchemy）
启动：uvicorn app.main:app --reload → GET /health
Redis：`docker compose up -d redis` · `REDIS_URL=redis://127.0.0.1:6380/0` · `scripts/dev/start-redis.ps1`
测试：python -m pytest（**730 绿**；集成需本机 MySQL + `risk_aml_list` + `prepare_risk_demo.sql`）
前端：cd web && npm run dev · npm run build/test/lint（**19** Vitest）
运维/演示脚本：scripts/demo/subscribe_alerts.py（订阅推送演示）· rebuild_alerts.py TRD-xxx（引擎异常补偿重放）
JWT 联调：python scripts/dev/issue_dev_token.py --sub STAFF-30001 --roles risk_officer（+ Authorization: Bearer + X-Agent-Type）
配置：.env（见 .env.example）
RBAC 联调账号：scripts/dev/rbac-seed-reference.md

---

5. 文档资产约定

文件	何时读
docs/memory/MEMORY.md	每次任务先读（本文件）
docs/memory/REQUIREMENTS.md	对照场景 ID（F/C/A/D/R）与 Wave
docs/memory/FRAMEWORK.md	分层、选型、模块、实现状态表
docs/memory/FLOW.md	端到端链路 + 本地 bootstrap
docs/memory/ENVIRONMENT.md	As-Is 业务环境与 Core 模拟说明
docs/memory/TODO.md	当前待办与已完成
docs/PRD/PRD-风控监测Agent.md	风控 PRD v1.0（已冻结；FR-1~FR-7 + §8 验收表）
docs/PRD/附-风控规则表.md	RISK-001005 / SUIT-001008 / AML 规则权威
docs/项目框架设计/开发计划-风控模块.md	风控分阶段计划（阶段 A/B/C + 挂账登记 + B7~B9b 复审记录）风控开发必读
docs/项目框架设计/演示SOP-风控模块.md	演示/走查操作手册（重灌 + A-1~A-9 步骤 + 核查单结论）；跑集成测试前先按 §2 重灌
docs/项目框架设计/架构设计-风控模块.md	风控模块架构（§3.1 编排 / §5 service 职责）
docs/需求拆解/	业务原文（场景、矩阵、合规）
docs/项目框架设计/	表结构、JWT 手册、Core 模拟、技术版本
docs/项目管理/04-从需求到公共API开发方法.md	搭公共底座/API 前；新人 onboarding
docs/项目框架设计/接口契约-代销平台API-v0.1.md	写/Review 代销平台 REST；Agent 合并对照 canonical 路径
docs/项目框架设计/C-05-行情数据源选型对比.md	C-05 行情/净值数据源拍板与禁止项
docs/项目框架设计/接口契约-代销平台API-v0.2-行情扩展草案.md	Phase B nav-snapshot 与 sync 脚本契约（未实现）
docs/frontend/FRONTEND-HANDOFF.md	改 web/ 必读：启动/分层/设计令牌/组件边界/浏览器验收清单

缺 docs/memory/* 文件：按 project-memory-kit 同名补回，禁止空模板盖进度。

---

6. 协作口令

【大环境】→ ENVIRONMENT · 【需求讨论】→ REQUIREMENTS · 【框架讨论】→ FRAMEWORK · 【实现流程】→ FLOW · 【Plan】→ TODO

---

7. 阅读完成门闸（Agent）

1. 四个 Agent 服务谁、禁止什么？
2. 改动属于 api / service / tool / repository 哪一层？
3. 是否需 customer_id 归属与 JWT RBAC？
4. Core 是模拟库只读还是 agent 库读写？
5. 如何验证？（python -m pytest 730 绿 · docker compose up -d redis + .env 6380 · uvicorn + /health · web/ build/test · 平台 /api/customers/* · 登录页游客试聊 · 客户助手 Chat）

大任务：FRAMEWORK/FLOW 与实现状态不符时先更新 memory 再编码（用户确认跳过除外）。