Add core database support and enhance documentation

- Introduced `MYSQL_CORE_DATABASE` in `.env.example` and `settings.py` for core database configuration. - Added `CoreReadOnlyRepository` for read-only access to the `jinrong_core` database. - Updated `AGENTS.md`, `README.md`, and various documentation files to reflect new agent onboarding processes and project structure. - Revised requirements in `requirements.txt` to include `langgraph` and `langchain-core`. - Enhanced `FLOW.md` with local bootstrap instructions for setting up the core simulation environment. - Added new scripts for database creation and seeding for the core simulation library. - Improved overall documentation for clarity on project architecture and memory management. - Updated `TODO.md` to reflect current development priorities and tasks.
2026-09-05 17:39:16 +08:00
parent 0374010b37
commit 1ddd44a6cb
34 changed files with 1848 additions and 97 deletions
@@ -1,6 +1,7 @@
 # 服务对象大环境（现状 / As-Is）

-> 来源：`docs/需求拆解/业务场景优先级清单.md`、`docs/需求拆解/用户故事/`
+> 来源：`docs/需求拆解/业务场景优先级清单.md`、`docs/需求拆解/用户故事/`  
+> **Core 说明：** 生产环境应以真实 Core 为 L0 权威；**本项目无真实 Core**，开发用 `jinrong_core` 模拟库（见 `docs/项目框架设计/Core模拟底座/`）。

 ------

@@ -13,7 +14,7 @@
 | 内部员工 | 分析、运营、合规 | 问数、报表、抽检会话、协同风控 |
 | 风控 / 合规官 | 风控专员 | 监测大额/适当性/AML；人工审核，不自动冻户 |

-**Core：** 持仓、流水、交易、正式风险等级、客户-代理人归属的权威来源。
+**L0 权威来源（本项目）：** MySQL `jinrong_core` 模拟库 — 客户、C1~C5、持仓、流水、产品、代理人-客户归属。Agent 代码经 `CoreReadOnlyRepository` **只读 SELECT**，不提供 HTTP Core API。

 ------

@@ -24,26 +25,28 @@
 - **内部分析**：SQL 或 IT 导表。
 - **风控**：事后/T+1 发现异常；适当性靠交易前规则；AML 批处理或人工。

-Agent **尚未上线**。
+Agent **尚未上线**；后端为脚手架 + 模拟数据，无生产接入。

 ------

-## 3. 主路径（现状）
+## 3. 主路径（现状 → 模拟后）

-1. 开户/测评 → Core 写 L0（C1~C5、归属代理人）
-2. 交易 → Core 流水；交易前适当性（若有）
-3. 代理人服务 → 查 Core + 口头沟通（无统一 L2 画像库）
-4. 风控 → 规则/人工台账；合规事后抽检
+1. 开户/测评 → Core（模拟：`core_customer` + `core_customer_risk`）写 L0
+2. 交易 → Core 流水（模拟：`core_trade`）；交易前适当性（R-02 待实现）
+3. 同步 → `sync_advisor_rel.py` 写入 agent 库 `customer_advisor_rel`；`sync_neo4j.py` 灌关系图
+4. 代理人服务 → 查 Core RO + 口头沟通（L2 画像表待业务实现）
+5. 风控 → 规则/人工台账；合规事后抽检

 ------

 ## 4. 环境里的关键对象

-| 名称 | 含义 |
-| --- | --- |
-| L0 正式档案 | customer_id、C1~C5、年龄、职业、advisor |
-| 持仓/流水 | 产品、份额、盈亏 |
-| 代理人-客户归属 | customer_advisor_rel（Core 同步） |
+| 名称 | 含义 | 本项目存储 |
+| --- | --- | --- |
+| L0 正式档案 | customer_id、C1~C5、年龄、职业、advisor | `jinrong_core.core_*` |
+| 持仓/流水 | 产品、份额、盈亏 | `core_holding` / `core_trade` |
+| 代理人-客户归属 | 服务关系 | Core 种子 → 同步 `jinrong_agent.customer_advisor_rel` |
+| Agent 会话/画像/审计 | 平台业务数据 | `jinrong_agent`（11 共用表 + agent 专用表） |

 ------

@@ -51,5 +54,6 @@ Agent **尚未上线**。

 ```text
 痛点：客户看不清持仓与规则；代理人多系统慢、话术易违规；问数靠 SQL；风控感知滞后
-不能动：正式 C1~C5 仅测评/人工变更；事实账以 Core 为准；监管要求审计与适当性
+不能动：正式 C1~C5 仅测评/人工变更；事实账以 Core 为准（模拟库亦只读）；监管要求审计与适当性
+模拟边界：不模拟 TA/清算/报盘；种子数据静态净值可接受；Neo4j 由同步脚本维护
 ```
@@ -5,12 +5,49 @@

 ------

-## 1. 链路总览
+## 0. 本地 bootstrap（新环境 / 新 Agent）

 ```text
-Client → Gateway(JWT/RBAC) → api/chat → agent_service → Tools → 存储 → 响应 + audit_log
+前置：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 产品 / 持仓交易种子
+
+④ Agent 共用底座（若库未建）
+   mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.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
 ```

+**尚未自动化：** agent 专用表 SQL、Milvus 建 Collection、JWT 中间件 — 见 `TODO.md`。
+
+------
+
+## 1. 链路总览（目标）
+
+```text
+Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log
+```
+
+当前：`main.py` 仅 health；全链路待 Wave 0 起逐步挂载。
+
 ------

 ## 2. 主链路 · 对话
@@ -18,19 +55,19 @@ Client → Gateway(JWT/RBAC) → api/chat → agent_service → Tools → 存储
 ```text
 输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息
 ↓
-Gateway：验签、角色准入、注入 AuthContext
+Gateway：验签、角色准入、注入 AuthContext                    【待做 T-01】
 ↓
-api/chat：SessionGuard；创建/续 agent_session
+api/chat：SessionGuard；创建/续 agent_session               【待做】
 ↓
-memory_service：Redis 读最近 N 轮；异步写 agent_message
+memory_service：Redis 读最近 N 轮；异步写 agent_message     【待做】
 ↓
-agent_service：LangChain + DeepSeek；按 Agent 类型选 Tool 集
+agent_service：LangGraph StateGraph + DeepSeek；按 Agent 类型选 Tool 节点  【待做】
 ↓
 Tool 示例：
-  - Core RO：持仓/流水（自动注入 customer_id）
-  - milvus_tool：产品规则 RAG + source_refs
-  - memory_service：读/写 L1/L2/L3（ProfileGuard）
-  - 风控 service 账号：R-02 适当性（无会话）
+  - CoreReadOnlyRepository：持仓/流水/L0（自动注入 customer_id）  【Repository 已有，Tool 未接】
+  - milvus_tool：产品规则 RAG + source_refs                   【待做】
+  - memory_service：读/写 L1/L2/L3（ProfileGuard）              【待做】
+  - 风控 service 账号：R-02 适当性（无会话）                    【待做】
 ↓
 输出：assistant 消息 + has_disclaimer（客户/对外）
 ↓
@@ -68,13 +105,15 @@ admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3)
 | 会话 | session_id | Redis ctx + MySQL session | actor_id 一致 |
 | 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 | 不可删改 |

 ------

 ## 6. 关键数据约定

- MySQL 脚本：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql`
+- 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
@@ -2,7 +2,8 @@

 > 选型详情：`docs/项目框架设计/技术选型和版本/01-技术栈与版本.md`  
 > 表设计：`docs/项目框架设计/表设计/`  
-> 鉴权：`docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md`
+> 鉴权：`docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md`  
+> Core 模拟：`docs/项目框架设计/Core模拟底座/`

 ------

@@ -11,15 +12,15 @@
 | 技术栈 | 已定（用户已同意） | 备注 |
 | --- | --- | --- |
 | 后端语言/框架 | Python 3.13.14 + FastAPI | 系统 Python |
-| Agent 编排 | langchain 1.3.18 / langchain-openai 1.6.0 | DeepSeek API |
-| 关系库 | MySQL 8.0.46 | jinrong_agent，:3306 |
+| Agent 编排 | **LangGraph** 1.2.x + langchain-core / langchain-openai 1.6.0 | DeepSeek API；StateGraph + Tool 节点 |
+| 关系库 | MySQL 8.0.46 | **双库**：`jinrong_agent` + `jinrong_core` |
 | 缓存 | Redis 8.10.1 | :6379 |
-| 图库 | Neo4j 5.26.19 Enterprise | Desktop，关系查询 |
-| 向量库 | Milvus Lite + pymilvus 3.0.1 | 本地文件；1024 维 |
+| 图库 | Neo4j 5.26.19 Enterprise | Desktop；`sync_neo4j.py` 灌图 |
+| 向量库 | Milvus Lite + pymilvus 3.0.1 | 本地 `./data/milvus.db`；1024 维 |
 | Embedding | Ollama bge-m3 | 本地，不出内网 |
 | LLM 生成 | DeepSeek API | 对话/推理 |
-| 前端 | React 19 + Vite 7 + AntD 5 + TS strict | 不用 Streamlit |
-| 对象存储 | 本地目录 data/kb/ | 不用 MinIO |
+| 前端 | React 19 + Vite 7 + AntD 5 + TS strict | 不用 Streamlit；`web/` 待 init |
+| 对象存储 | 本地目录 `data/kb/` | 不用 MinIO |
 | 部署 | Windows 原生 | Docker 仅答辩备选 |

 ```text
@@ -31,30 +32,41 @@

 ## 2. 能力模块

-| 模块 | 职责 | 依赖 |
-| --- | --- | --- |
-| Agent Gateway / Auth SDK | JWT、RBAC、归属校验 | Redis、MySQL customer_advisor_rel |
-| 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 |
-| 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus |
-| 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 |
-| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 |
-| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis |
+| 模块 | 职责 | 依赖 | 代码状态 |
+| --- | --- | --- | --- |
+| Agent Gateway / Auth SDK | JWT、RBAC、归属校验 | Redis、MySQL customer_advisor_rel | **未做**（见 JWT 手册） |
+| 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 | 空壳 service |
+| 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | 空壳 service |
+| 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | 空壳 service |
+| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | 空壳 service |
+| Core 只读层 | L0 事实查询 | `jinrong_core` | **core_ro.py 已实现** |
+| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | SQL 已定；代码未接 |
+| 同步脚本 | 归属、Neo4j | Core → agent / 图库 | **sync_*.py 已实现** |

 ------

 ## 3. 后端分层（app/）

 ```text
-api/        → 路由（chat、knowledge、admin）；薄，不含业务
-service/    → agent_service、rag_service、memory_service
-tool/       → document_parser、embedding_tool、milvus_tool
-model/      → schemas（Pydantic）、entities（ORM）
-config/     → settings、database
-utils/      → response、exceptions、logger
-main.py     → FastAPI 入口
+api/          → 路由（chat、knowledge、admin）；薄，不含业务          【空壳】
+service/      → agent_service、rag_service、memory_service           【空壳】
+tool/         → document_parser、embedding_tool、milvus_tool          【空壳】
+repository/   → core_ro（Core 只读）；后续 agent 库 Repository       【core_ro 已实现】
+model/        → schemas（Pydantic）、entities（ORM）                  【占位】
+config/       → settings、database                                     【settings 已实现】
+utils/        → response、exceptions、logger                           【占位】
+main.py       → FastAPI 入口；当前仅 /health                          【部分】

-允许：api → service → tool / model / config
-禁止：api 直连 Milvus/MySQL 写复杂逻辑；tool 写业务流程
+允许：api → service → tool / repository / model / config
+禁止：api 直连 Milvus/MySQL 写复杂逻辑；tool 写业务流程；repository 写 Core
+```
+
+**脚本（非 app 包）：**
+
+```text
+scripts/core/       → jinrong_core DDL + 种子 + reset.ps1
+scripts/sync/       → sync_advisor_rel.py、sync_neo4j.py
+scripts/dev/        → rbac-seed-reference.md（联调账号）
 ```

 ------
@@ -63,14 +75,16 @@ main.py     → FastAPI 入口

 | 层 | 存储 | 说明 |
 | --- | --- | --- |
-| L0 | Core 只读 | 正式 C1~C5、持仓 |
-| L1/L2/L3 | MySQL 画像表 | 客户/代理人/风控 enrich |
+| L0 | `jinrong_core` 只读 | 正式 C1~C5、持仓、流水（模拟） |
+| L1/L2/L3 | MySQL 画像表（agent 库） | 客户/代理人/风控 enrich |
 | 会话 | Redis + MySQL | 窗口 + 永久审计 |
-| RAG | Milvus + 本地文件 | kb_product_rules 等 |
+| RAG | Milvus + `data/kb/` | kb_product_rules 等 |
 | 关系 | Neo4j | 客户-产品-代理人（Core 同步） |

 ------

 ## 5. 骨架一句话

-Gateway 鉴权 → FastAPI api → service 编排 Agent → tool 访问 MySQL/Redis/Milvus/Neo4j/Core → 审计落库。
+Gateway 鉴权 → FastAPI api → service（LangGraph）→ tool/repository → MySQL/Redis/Milvus/Neo4j/Core → 审计落库。
+
+**记忆分层详解：** [业务记忆管理手册.md](../业务记忆管理/业务记忆管理手册.md)
@@ -5,4 +5,6 @@
 | 2026-09-05 | init 项目记忆 + app 脚手架 | 用户要求 memory kit + 目录结构 | MEMORY / ENVIRONMENT / REQUIREMENTS / FRAMEWORK / FLOW / TODO |
 | 2026-09-05 | 需求拆解四 Agent P0 场景定稿 | 用户故事归纳 | REQUIREMENTS（对照 docs/需求拆解/） |
 | 2026-09-05 | 技术栈 Windows 原生 + Milvus Lite | 本机内存限制 | FRAMEWORK |
-| 2026-09-05 | MySQL 16 表 + L0~L3 画像 + JWT 统一鉴权 | 多 Agent 共用底座 | FRAMEWORK / FLOW |
+| 2026-09-05 | Core 模拟库 jinrong_core + 扩大种子 + Neo4j 同步 | 无真实 Core | FRAMEWORK / FLOW / ENVIRONMENT |
+| 2026-09-05 | Agent 编排依赖改为 LangGraph 为主 | 状态图 + Tool 节点 | FRAMEWORK |
+| 2026-09-05 | memory 全量刷新：§0 新 Agent 交接清单 + 实现状态表 + bootstrap | 脚手架已落地，便于无上下文交接 | MEMORY / FRAMEWORK / FLOW / TODO / REQUIREMENTS / ENVIRONMENT |
@@ -1,15 +1,55 @@
 # 项目记忆（人 + Agent 共用）

-> 各阶段的**简化快照**（门闸索引）。只留基础信息，不写源文件正文。
-> 详细需求见 `docs/需求拆解/`；表设计与技术选型见 `docs/项目框架设计/`。
+> 各阶段的**简化快照**（门闸索引）。只留基础信息，不写源文件正文。  
+> **新 Agent 无上下文：先读本节 → 第 0 节交接清单 → 按需打开源文件。**
+
+------
+
+## 0. 新 Agent 交接（5 分钟）
+
+**项目是什么：** 金融四 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座；**不**互调 LLM，跨 Agent 走 L1/L2/L3 画像与预警表。
+
+**当前进度：** 需求与表设计已定 · 后端 **脚手架 + Core 模拟库脚本** 已落地 · **业务 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 只读 SELECT（jinrong_core） |
+| `app/config/settings.py` | **已实现** | 双库 `jinrong_agent` + `jinrong_core` |
+| `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子 |
+| `scripts/sync/*.py` | **已实现** | 归属同步 + Neo4j 全图 |
+| `docs/需求拆解/` | 已定 | 场景 P0、矩阵、合规原文 |
+| `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + agent 专用 SQL |
+| `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。

 ------

 ## 1. 项目简介

 - **名称：** JinRong 金融四 Agent 智能管家
- **当前阶段：** MVP（需求与底座设计已定，后端脚手架已 init）
- **当前优先级：** 交付速度（先 Wave 0 共用底座 + Wave 1 内部 Agent 闭环）
+- **当前阶段：** MVP 脚手架期（设计已定，Wave 0 开发中）
+- **当前优先级：** Wave 0 共用底座 → Wave 1 代理人/分析闭环

 ------

@@ -17,10 +57,10 @@

 | 阶段 | 当前一句话 | 源文件 |
 | --- | --- | --- |
-| 服务对象大环境 | 公募场景下四类角色各自痛点明确，数据以 Core 为准、Agent 只读事实 | `ENVIRONMENT.md` |
-| 需求目的 | 四个 Agent 服务四类人群，统一数据层交换画像与预警，合规可审计 | `REQUIREMENTS.md` |
-| 项目框架 | FastAPI 分层 app + MySQL/Redis/Milvus Lite/Neo4j + React；Windows 原生 | `FRAMEWORK.md` |
-| 实现流程 | Gateway JWT/RBAC → Agent 编排 → Tool/画像库 → 审计落库 | `FLOW.md` |
+| 服务对象大环境 | 公募四类角色；**无真实 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` |

 ------

@@ -33,7 +73,7 @@
 **禁止触碰：**

 ```text
-Core 正式 C1~C5、持仓/交易真账（Agent 只读）
+Core 正式 C1~C5、持仓/交易真账（Agent 只读；当前为模拟库）
 audit_log 等审计表（只 INSERT）
 代理人草稿自动外发客户
 风控自动冻户 / 改正式风险等级
@@ -66,22 +106,32 @@ audit_log 等审计表（只 INSERT）
 ## 4. 入口与运行

 ```text
-关键文件：app/main.py · app/config/settings.py · docs/项目框架设计/表设计/*.sql
-如何启动：MySQL/Redis/Neo4j/Ollama 就绪后 → uvicorn app.main:app --reload
-配置位置：.env（见 .env.example）
+后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py
+Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql
+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/*.md` | 见 project-memory-kit 约定 |
-| `docs/需求拆解/` | 业务场景与合规（参考） |
-| `docs/项目框架设计/` | 表结构、鉴权、技术版本 |
+| `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 权威记忆 |

-日常改代码只读本文件；验收对照 `REQUIREMENTS.md`。
+缺 `docs/memory/*` 文件：按 project-memory-kit 同名补回，**禁止空模板盖进度**。

 ------

@@ -94,8 +144,9 @@ audit_log 等审计表（只 INSERT）
 ## 7. 阅读完成门闸（Agent）

 1. 四个 Agent 服务谁、禁止什么？
-2. 改动属于 api / service / tool 哪一层？
+2. 改动属于 api / service / tool / repository 哪一层？
 3. 是否需 customer_id 归属与 JWT RBAC？
-4. 如何验证？
+4. Core 是模拟库只读还是 agent 库读写？
+5. 如何验证？（health / SQL / sync 脚本 / 对照 REQUIREMENTS 验收列）

-大任务：FRAMEWORK/FLOW 为空时先补再编码（用户确认跳过除外）。
+大任务：FRAMEWORK/FLOW 与实现状态不符时先更新 memory 再编码（用户确认跳过除外）。
@@ -20,8 +20,11 @@
 | F-01 | JWT + RBAC + 数据归属 | 越权 403 + audit；JWT 手册 §13 | 未做 | T-01 |
 | F-02 | 全量审计留痕 | trace_id 可还原 | 未做 | T-02 |
 | F-03 | 输入防护 | input_guard_log | 未做 | T-03 |
-| F-04 | Core 只读层 | 不改 Core 账 | 未做 | T-04 |
-| R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql | 未做 | T-05 |
+| F-04 | Core 只读层 | 不改 Core 账；Repository 只 SELECT | **部分** | T-04 |
+| R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql | SQL 已定；灌库待验 | T-05 |
+| R0-CORE | Core 模拟 + 同步 | reset.ps1 + sync 脚本 | **脚本已落地** | T-05 |
+
+**F-04 部分完成说明：** `app/repository/core_ro.py` + `scripts/core/*` + `settings.mysql_core_database` 已有；尚未接入 api/service Tool 与归属校验。

 ## Wave 1 · 内部 Agent P0

@@ -1,21 +1,29 @@
 # TODO

-> 大任务开始时更新；完成一步打钩并验证后再往下。
+> 大任务开始时更新；完成一步打钩并验证后再往下。  
+> **新 Agent：** 先看 `MEMORY.md` §0 交接清单，再从此处取下一项。

 ## 进行中

- [ ] Wave 0 共用底座 — 验收：F-01~F-04 + MySQL 11 表可连
+- [ ] Wave 0 共用底座 — 验收：F-01~F-03 + agent 库灌库 + JWT 可联调

-## 待办
+## 待办（推荐顺序）

- [ ] T-01 Auth SDK / JWT 中间件（对照 JWT 手册）
- [ ] T-05 执行 01-mysql-共用底座.sql + database.py 连接
+- [ ] T-01 Auth SDK / JWT 中间件（对照 `02-JWT-RBAC鉴权手册.md`）
+- [ ] T-02 audit_log 中间件 + trace_id 贯通
+- [ ] T-05 本机执行 `reset.ps1` + `01-mysql-共用底座.sql` + sync 脚本验收
+- [ ] T-06 挂载 `app.api` 路由到 `main.py`；chat 最小闭环
+- [ ] T-07 LangGraph `agent_service` StateGraph 骨架 + DeepSeek
+- [ ] T-04 Core RO 封装为 Tool 节点；A-01 归属校验
 - [ ] T-21 Milvus Lite + kb_product_rules 首批入库
- [ ] T-20 代理人 A-01 持仓 Tool + 归属校验
- [ ] 前端 React 多 Agent 入口（HashRouter）
+- [ ] 前端 React 多 Agent 入口（HashRouter，`web/` init）

 ## 已完成

- [x] 2026-09-05 init 项目记忆目录 + app/ 脚手架
+- [x] 2026-09-05 init 项目记忆目录 + `app/` 脚手架（api/service/tool/model/config/utils）
 - [x] 2026-09-05 需求拆解文档（业务场景/矩阵/合规）
 - [x] 2026-09-05 表设计 + 技术选型 + JWT 手册
+- [x] 2026-09-05 Core 模拟库 `scripts/core/*` + `reset.ps1` + 文档
+- [x] 2026-09-05 `core_ro.py` + `settings.mysql_core_database` + sync 脚本
+- [x] 2026-09-05 Agent 编排依赖改为 LangGraph（requirements.txt）
+- [x] 2026-09-05 memory 文件夹更新（新 Agent 交接清单）