XingHuo/docs/memory/MEMORY.md

项目记忆（人 + Agent 共用）

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

---

0. 新 Agent 交接（5 分钟）

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

当前进度： 需求与表设计已定 · 风控模块 B1~B9b 全部完成（M2 tag risk-m2），M4 复核已闭环（2026-09-07），风控阶段 B 正式完结 · Wave 0 已完成（2026-09-07，经独立 AI 评审闭环）：T-01 JWT 鉴权（auth_service Auth SDK + deps 工厂替换 + X-Agent-Type 准入矩阵）/ T-02 审计中间件（http_access + 独立 request_id + 4xx/500 统一错误体 + input_guard_log 双写）/ T-06 chat 最小闭环（POST /api/chat + 会话落库 + Redis 窗口）/ T-07 LangGraph StateGraph 骨架 + DeepSeek（无 key 降级）· T-04 Core RO Tool 节点已完成（2026-09-07）：app/tool/core_tools.py 三只读 Tool + tool_service（意图/归属校验/run_tool）+ 图 tool 节点 + agent_tool_call 落库，297 测试绿。下一步：T-21 Milvus / T-03 输入防护 / 风控阶段 C（C0~C3，A-6 对话验收，C1 复用 run_tool）。开发在分支 feature/risk（未合入 main）。

仓库地图：

路径	状态	说明
app/main.py	已集成	路由挂载 + trace 中间件（X-Trace-Id/X-Request-Id 贯通 + 500 兜底错误体）+ audit 中间件（T-02 http_access）+ lifespan（jwt_ready 校验 · Redis 网关注册 · 引擎 dispose）
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）	POST /api/chat（SessionGuard+归属+窗口+落盘）· http_access 访问审计
app/api/knowledge.py admin.py	空壳	待 T-21（Milvus/RAG）与审计查询台
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 / 引擎编排 / SUIT-001008 / locks+redis_gateway 公共原语（B7）
app/service/agent_service.py memory_service.py	已实现（T-07/T-06/T-04）	LangGraph StateGraph（tool→llm→guard）+ DeepSeek（无 key 降级）；T-04 tool 节点（关键词意图 customer/advisor + tool_service.run_tool）；Redis 会话窗口 + MySQL 回源
app/service/tool_service.py app/tool/core_tools.py	已实现（T-04）	对话 Tool 编排（白名单/归属校验/agent_tool_call 落库）+ Core RO 三只读 Tool（L0/持仓/流水）；风控四 Tool 归 C1 复用 run_tool
app/repository/session_repository.py	已实现（T-06/T-04）	agent_session / agent_message / agent_tool_call 读写
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）
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/settings.py	已实现	双库 + risk_* 阈值 + JWT 配置（jwt_public_key_path/jwt_dev_secret/jwt_issuer/jwt_audience）
scripts/core/*.sql + reset.ps1	已实现	Core 模拟库 DDL + 种子
scripts/agent/ scripts/demo/ scripts/dev/	已实现	AML 名单种子 + 风控演示数据 + subscribe_alerts/rebuild_alerts + issue_dev_token（JWT 签发）
scripts/sync/*.py	已实现	归属同步 + Neo4j 全图
tests/	已实现	22 个测试文件 297 用例（sqlite 隔离；DDL 单一事实源 _ddl.py；test_integration_risk.py 走真 MySQL + TRD-TEST- 前缀隔离）
docs/需求拆解/	已定	场景 P0、矩阵、合规原文
docs/PRD/PRD-风控监测Agent.md	已冻结	风控 PRD v1.0 + 规则表附录
docs/项目框架设计/表设计/	已定	Agent 共用 11 表 + agent 专用 SQL
docs/项目框架设计/Core模拟底座/	已定	无真实 Core 时的 L0 方案
web/	不存在	前端 React 待 init

本地 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 名单种子
   （风控演示：scripts/demo/prepare_risk_demo.sql，reset 后重跑）
6. python scripts/sync/sync_advisor_rel.py && python scripts/sync/sync_neo4j.py
7. uvicorn app.main:app --reload → GET /health；python -m pytest（297 绿）

本机 ①~⑤已执行、.env 已配置，勿重做；本机状态与已知坑（mysql.exe 路径 / reset.ps1 交互式 -p / redis、python-jose 包漏装已补）见 FLOW.md §0 尾注。 演示库状态（2026-09-07）：已按演示 SOP §2 重灌并清理冒烟数据（alerts 0 / AML 8 / 会话 0），pytest 全量可直接跑；下次演示/走查后再按 SOP §2 重灌（核查单⑥前置断言会对走查残留显式 fail，属防护行为）。

下一步开发（见 TODO）： T-21 Milvus / T-03 输入防护 / 风控阶段 C（C0~C3，A-6 对话验收；C1 风控四 Tool 复用 T-04 run_tool）。演示走查按 docs/项目框架设计/演示SOP-风控模块.md（debug 头通道仍有效；JWT 通道签发用 scripts/dev/issue_dev_token.py）。

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

---

1. 项目简介

• 名称： JinRong 金融四 Agent 智能管家
• 当前阶段： T-04 Core RO Tool 节点完成（2026-09-07：tool 节点+归属校验+agent_tool_call 落库，297 绿）；Wave 0 共用底座完成（T-01 JWT / T-02 审计中间件 / T-06 / T-07 LangGraph）；风控模块 B1~B9b 完成（M2 tag risk-m2）+ M4 复核闭环，阶段 B 完结；下一批 = T-21/T-03 + 风控阶段 C（A-6 对话线验收）
• 当前优先级： T-21 / T-03 → 风控阶段 C（A-6）→ Wave 1

---

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
测试：python -m pytest（297 用例；集成测试需本机演示数据，未灌库时自动 skip）
运维/演示脚本：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/业务记忆管理/	Redis 短期 vs MySQL/Milvus/Neo4j 权威记忆

缺 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 全量（当前 297 绿）· uvicorn 启动 + /health · SQL / sync 脚本 · 对照 REQUIREMENTS 验收列）

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