XingHuo/docs/memory/MEMORY.md

# 项目记忆（人 + Agent 共用）

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

------

## 0. 新 Agent 交接（5 分钟）

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

**当前进度：** 需求与表设计已定 · **Core 模拟库 + L0 KYC/适当性矩阵 + R-02 计算与 log 契约** 已落地 · **业务 API / JWT / LangGraph 图尚未实现**（多为空壳模块）。

**仓库地图：**

| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `app/main.py` | 可跑 | 仅 `/health`；路由未挂载 |
| `app/api/*.py` | 空壳 | chat / knowledge / admin 待实现 |
| `app/service/*.py` | 空壳 | agent / rag / memory 待实现 |
| `app/repository/core_ro.py` | **已实现** | Core 只读 + `check_suitability`（R-02 计算） |
| `app/model/suitability.py` | **已实现** | R-02 → `risk_suitability_log` 行映射 |
| `app/config/settings.py` | **已实现** | 双库 `jinrong_agent` + `jinrong_core` |
| `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子（33 客户 / 14 产品） |
| `scripts/sync/*.py` | **已实现** | 归属同步 + Neo4j 全图 |
| `docs/需求拆解/` | 已定 | 场景 P0、矩阵、合规原文 |
| `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + 画像/适当性说明 06/07 |
| `docs/项目框架设计/Core模拟底座/` | 已定 | 无真实 Core 时的 L0 方案 |
| `web/` | **不存在** | 前端 React 待 init |

**本地 bootstrap（首次）：**

```text
1. cp .env.example .env  → 填 MYSQL_PASSWORD、NEO4J、DEEPSEEK_API_KEY
2. pip install -r requirements.txt
3. .\scripts\core\reset.ps1          # 建 jinrong_core + 种子
4. mysql … < 表设计/01-mysql-共用底座.sql   # jinrong_agent（若未建）
5. python scripts/sync/sync_advisor_rel.py
6. python scripts/sync/sync_neo4j.py
7. uvicorn app.main:app --reload     # GET /health
```

**下一步开发（见 TODO）：** T-01 JWT 中间件 → 挂载 api → LangGraph agent_service → Wave 0 验收。

**禁止（改代码前必记）：** Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM · **客户 Agent 可做适当性匹配说明，禁止营销式推荐/买卖指导**。

------

## 1. 项目简介

- **名称：** JinRong 金融四 Agent 智能管家
- **当前阶段：** MVP 脚手架期（设计已定，Wave 0 开发中）
- **当前优先级：** Wave 0 共用底座 → 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` 中已标「已定」视为用户确认；新增依赖须再确认。

**禁止触碰：**

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

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

**开发开关：**

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

**特殊规则：**

```text
四 Agent 不互调 LLM；跨 Agent 走 L1/L2/L3 画像与预警表
客户 Agent：允许按 C1~C5 与产品 R 等级做「是否匹配」说明（C-07/C-11，联动 R-02）；禁止营销推荐、买卖指导、收益承诺、自动下单
代理人：不对 C 端直发；禁止对比优劣、推荐产品（A-02）
数据分析：仅 SELECT，不处置预警
画像不得覆盖 L0 正式测评
```

------

## 4. 入口与运行

```text
后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py · 适当性映射 app/model/suitability.py
Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql
画像/适当性：表设计/06-用户画像L1-L3设计.md · 表设计/07-risk_suitability_log说明.md
Core 模拟：scripts/core/reset.ps1 · 文档 docs/项目框架设计/Core模拟底座/
依赖：requirements.txt（LangGraph + langchain-core/openai + FastAPI + SQLAlchemy）
启动：uvicorn app.main:app --reload → GET /health
配置：.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/需求拆解/` | 业务原文（场景、矩阵、合规） |
| `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. 如何验证？（health / SQL / sync 脚本 / 对照 REQUIREMENTS 验收列）

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