192 lines
16 KiB
Markdown
192 lines
16 KiB
Markdown
# 项目记忆（人 + 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 落库 + `utils/authz.py` 公共鉴权留痕，**321 测试绿（首评+复审双闭环）**。风控阶段 C 已完成（2026-09-07，345 绿，tag `risk-m3`，A-6 对话线验收通过，独立 AI 评审 PASS P0=0）。T-03 输入防护已完成（2026-09-07，378 绿，独立 AI 评审 PASS with findings P0=0）：app/service/input_guard.py 注入词表 42 条纯函数检测 + oversize 4000 + actor 级 Redis 固定窗口限流 30 次/分（fail-open）；chat 链路顺序 = 鉴权→准入→空白→限流 429→注入/超长 400→归属→会话，被拒 fail-fast 不建会话，blocked 落 input_guard_log（ENUM 四值已用满）。**阶段一「对齐 main 基准」AL-01~AL-08 已完成（2026-09-07，逐项独立 commit bb244f4~b5fd52e）：适当性判定换核为 main 的 core_ro.check_suitability（C×R 矩阵表数据驱动，match_result 五值/JR-AST-012/FM-01/FM-03/JR-AST-PRO 契约，SUIT-001~008 退役）；risk_suitability_log 重建 21 列；Core 表加 is_hnw/风评七新列（expires_at）；种子 33 客户/14 产品；全量 406 passed 0 failed 0 skipped + uvicorn 冒烟三端点通过；risk-m1 已补打（指向 3c07de6）**。**下一步：阶段一验收门（用户浏览器目视确认）→ AL-09 合并 main → AL-10 PRD v1.2 → AL-11 docx 登记 → 阶段二 C4~C6（实现方案已定稿并经独立 AI 评审修订闭环）/ 前端 React 多 Agent 入口（HashRouter `web/` init）。****开发在分支 `risk-control-agent`（与 main 已分叉：领先 75 提交 / main 独有 4 提交；旧文档中的 `feature/risk` 为过时口径）。**
|
||
|
||
**仓库地图：**
|
||
|
||
| 路径 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `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` | 空壳 | 待审计查询台与知识库 API（T-21 拍板一期只做脚本入库，上传/重建端点不做） |
|
||
| `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-001~005 规则 / 预警聚合 / L3 写入 / AML / 引擎编排 / suitability（**阶段一换核：内核改调 core_ro.check_suitability，SUIT-001~008 已退役**）/ locks+redis_gateway 公共原语（B7） |
|
||
| `app/service/agent_service.py` `memory_service.py` | **已实现（T-07/T-06/T-04/C2）** | 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 回源 |
|
||
| `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）** | 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）；**阶段一吸收 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/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/` | **已实现** | 30 个测试模块 406 用例（sqlite 隔离；DDL 单一事实源 `_ddl.py`；`test_integration_risk.py` 走真 MySQL + TRD-TEST- 前缀隔离；pytest 依赖装在系统 Python 3.13.14；阶段一 test_suitability 按 main 契约重写后基线 425→406） |
|
||
| `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/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + agent 专用 SQL |
|
||
| `docs/项目框架设计/Core模拟底座/` | 已定 | 无真实 Core 时的 L0 方案 |
|
||
| `web/` | **不存在** | 前端 React 待 init |
|
||
|
||
**本地 bootstrap（首次）：** 完整步骤与前置说明见 `FLOW.md` §0（权威），速览：
|
||
|
||
```text
|
||
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（406 用例，系统 Python 3.13.14）
|
||
```
|
||
|
||
> **本机 ①~⑤已执行、`.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）：** 阶段一验收门（用户浏览器目视确认，pytest 406 绿 + 冒烟已通过）→ AL-09 合并 main → AL-10 PRD v1.2 → AL-11 docx 登记 → 阶段二 C4~C6 追加需求编码（FR-8/9/10 已并入 PRD v1.1 · 实现方案《docs/项目框架设计/实现方案-风控追加需求v1.1-C4C6.md》定稿，AL-05 换核后 SuitabilityResult 字段名需同步核对）/ 前端 React 多 Agent 入口。演示走查按 `docs/项目框架设计/演示SOP-风控模块.md`（debug 头通道仍有效；JWT 通道签发用 `scripts/dev/issue_dev_token.py`；**演示库已按 AL-08 expires_at 新口径重灌**）。知识库入库：`python scripts/kb/build_kb.py`（先启 Ollama；**Milvus 数据路径必须纯英文**——faiss 不支持中文路径，本机 .env 已配 C:/Users/YUAN/.jinrong/milvus/）。
|
||
|
||
**禁止（改代码前必记）：** 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） | 拟（完成后打，名待拍板） |
|
||
| `risk-align1`（拟） | 阶段一 · 对齐 main 基准 | 待定（AL-01~08 已完成，是否为此打 tag 由用户拍板；当前仅 AL 逐项 commit） |
|
||
|
||
------
|
||
|
||
## 1. 项目简介
|
||
|
||
- **名称：** JinRong 金融四 Agent 智能管家
|
||
- **当前阶段：** **阶段一「对齐 main 基准」AL-01~AL-08 已完成（2026-09-07，commit bb244f4~b5fd52e，406 绿 + 冒烟通过，待用户目视确认验收门）**；T-21 知识库入库已完成并评审闭环（2026-09-07，425 绿基线，commit 9cc2e59）；风控阶段 C 完成（M3 tag risk-m3，345 绿）；T-03 输入防护完成（378 绿，评审 PASS with findings P0=0）；追加需求 FR-8/9/10 已并入 PRD v1.1，实现方案（C4~C6）已定稿并经独立 AI 评审修订闭环，编码未开始
|
||
- **当前优先级：** 阶段一验收门（用户目视确认）→ AL-09/10/11 → 阶段二 C4~C6 → 前端 React 入口
|
||
|
||
------
|
||
|
||
## 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：无投资建议/收益承诺/自动下单
|
||
代理人：不对 C 端直发
|
||
数据分析：仅 SELECT，不处置预警
|
||
画像不得覆盖 L0 正式测评
|
||
```
|
||
|
||
------
|
||
|
||
## 4. 入口与运行
|
||
|
||
```text
|
||
后端入口：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（321 用例；集成测试需本机演示数据，未灌库时自动 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-001~005 / SUIT-001~008 / 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` 全量（当前 321 绿）· uvicorn 启动 + /health · SQL / sync 脚本 · 对照 REQUIREMENTS 验收列）
|
||
|
||
大任务：FRAMEWORK/FLOW 与实现状态不符时先更新 memory 再编码（用户确认跳过除外）。
|