zhanghongyu_0626
d394686a3b
- Merged the `integrate/advisor-agent` branch into the `merger`, enhancing the advisor agent's capabilities with compliance, KYC, and script templates. - Updated the testing baseline to reflect 926 passed tests, with 65 failures concentrated in the advisor agent's `test_sprint*` cases. - Introduced new migration scripts for advisor-related database structures, ensuring smooth integration and data management. - Enhanced documentation to include the new API structure and integration details, providing clarity for future development. This update significantly advances the advisor agent's functionality while maintaining a structured approach to integration and testing.
156 lines
7.9 KiB
Markdown
156 lines
7.9 KiB
Markdown
# 实现流程
|
||
|
||
> To-Be 端到端链路；As-Is 见 `ENVIRONMENT.md`
|
||
> 画像分层见 `docs/项目框架设计/表设计/00-架构总览.md`
|
||
|
||
------
|
||
|
||
## 0. 本地 bootstrap（新环境 / 新 Agent）
|
||
|
||
```text
|
||
前置：MySQL 8、**Docker Desktop（Redis + 可选 Neo4j compose）**、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 + 客户/产品/持仓/交易 + **07 净值历史（14×365 日）**
|
||
（风控演示：`.\scripts\demo\prepare_all.ps1` 或 `prepare_risk_demo.sql` · PRD §10.2）
|
||
|
||
④b 数据分析问数（可选）
|
||
mysql … < scripts/agent/migrate-analyst-d07-d11.sql # 若未建 analyst 资产表
|
||
mysql … < scripts/agent/seed-analyst-metric-dict.sql
|
||
mysql … < scripts/agent/seed-analyst-query-templates.sql # 模板缓存演示
|
||
|
||
④ Agent 共用底座（若库未建）
|
||
mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.sql
|
||
（风控：再建 02-mysql-agent专用.sql 的 risk_aml_list + 灌 scripts/agent/seed-aml-list.sql）
|
||
|
||
⑤ 同步
|
||
python scripts/sync/sync_advisor_rel.py → customer_advisor_rel
|
||
python scripts/sync/sync_neo4j.py → 关系图（需 compose neo4j 或 Desktop）
|
||
|
||
⑤b Redis（推荐 Docker）
|
||
docker compose up -d redis
|
||
# 或 .\scripts\dev\start-redis.ps1
|
||
# .env: REDIS_URL=redis://127.0.0.1:6380/0 （避开本机 Windows Redis 占 6379）
|
||
|
||
⑥ 验证
|
||
uvicorn app.main:app --reload
|
||
GET http://127.0.0.1:8000/health → {"status":"ok"}
|
||
GET http://127.0.0.1:8000/api/ready → Redis + 路由自检（前端 DevReadyBanner）
|
||
cd web && npm run dev → 5173 代理 8000
|
||
mysql … < scripts/agent/migrate-advisor-agent-sprint1-3.sql # 投资顾问表（合并后）
|
||
python -m pytest → merger 回归 ~896 passed（不含 test_sprint*）；全量 926 passed / 65 failed（sprint）
|
||
问数答辩前：见 `docs/答辩/DEMO-SOP-答辩全流程.md` · 问数分册 `DEMO-SOP-问数.md`（`scripts/dev/seed_analyst.ps1` · battery 可选）
|
||
|
||
RBAC 联调账号：scripts/dev/rbac-seed-reference.md
|
||
```
|
||
|
||
**尚未自动化：** agent 专用表已有 `02-mysql-agent专用.sql`（手工执行，含 risk_aml_list）；Milvus 建 Collection 已随 T-21 自动化（`scripts/kb/build_kb.py` 可重灌）。JWT 中间件已完成（T-01：`app/service/auth_service.py` + `deps.py` 工厂；dev 联调签发 `scripts/dev/issue_dev_token.py`，debug 头兜底仅限 development 且未配 RS256 公钥）。
|
||
|
||
------
|
||
|
||
## 1. 链路总览（目标）
|
||
|
||
```text
|
||
Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log
|
||
```
|
||
|
||
当前：**风控全链路 + Wave 0 共用底座 + 代销平台 v0.1 + AL-09 + 客服 S2 Wave3 + 数据分析 D-06/N-03/N-07 + 前端 P0 Demo（2026-09-11，`merger`）**。**测试基线：`python -m pytest` → 825 passed 1 skipped** · **`web/` 22 Vitest 绿 · `npm run build` 绿**。
|
||
|
||
**下一步（统筹 P1）：** merger commit · 20 题 battery · 客服/风控 E2E 详测 · analyst **D-09 多轮** · **客服** L2 Redis（风控不做 L1/L2）。
|
||
|
||
**本机已就位状态（2026-09-12）：** pytest **896 绿**（不含 sprint）· 顾问 **`/api/advisor-agent/*` 已挂**（integrate 分支）· Vitest **27 绿** · 问数 **`match_phrases`** · [AN-002](tests/2026-09-12-analyst-template-phrases/TEST-LOG-2026-09-12-AN-002.md)。
|
||
|
||
**本机已知坑：** `mysql.exe` 不在 PATH；`reset.ps1` 自动化用 `MYSQL_PWD`；**6379 常被 Windows Redis 3.x 占用** → 项目 Docker 映射 **6380**；Milvus 中文路径需英文 `MILVUS_URI`；问数模板需灌 `seed-analyst-query-templates.sql` 才见蓝色「模板命中」标签；`battery_report.json` **不入库**（`.gitignore`）。
|
||
|
||
------
|
||
|
||
## 2. 主链路 · 对话
|
||
|
||
```text
|
||
输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息
|
||
↓
|
||
Gateway：验签、角色准入、注入 AuthContext 【T-01 已做】（JWT 验签/吊销 + AGENT_ACCESS_MATRIX）
|
||
↓
|
||
输入防护：限流（429）→ 注入/超长（400） 【T-03 已做】（Redis 固定窗口 30 次/分 fail-open；被拒 fail-fast 不建会话，blocked 落 input_guard_log）
|
||
↓
|
||
api/chat：SessionGuard；创建/续 agent_session 【T-06 已做】（actor/agent_type 一致校验）
|
||
↓
|
||
memory_service：Redis 读最近 N 轮；MySQL 落盘 agent_message 【T-06 已做】（窗口 TTL2h N≤20，miss 回源；同步落盘）
|
||
↓
|
||
agent_service：LangGraph StateGraph + DeepSeek；tool(意图→Tool) → llm → guard 【T-04 + C2 已做（分组关键词意图 customer/advisor/risk；risk 分支接 C1 四 Tool）】
|
||
↓
|
||
Tool（tool_service.run_tool：白名单 → 归属校验 → 执行 → agent_tool_call 落库）：
|
||
- CoreReadOnlyRepository：持仓/流水/L0（customer_id 由会话注入，不来自 LLM） 【T-04 已做 app/tool/core_tools.py 三 Tool】
|
||
- 风控四 Tool：alert_query/customer_context/suitability_check/aml_lookup 【C1 已做 chat_tools（RISK_TOOL_REGISTRY）】
|
||
- milvus_tool：产品规则 RAG + source_refs 【已做 T-21（app/tool/kb_tools.py + rag_service/milvus_service；仅 customer/advisor 意图开放）】
|
||
- memory_service：读/写 L1/L2/L3（ProfileGuard） 【窗口读写已做；画像读写待做】
|
||
↓
|
||
输出：assistant 消息 + has_disclaimer（customer/risk 固定免责，T-07 guard 节点）
|
||
↓
|
||
落库：agent_message、agent_tool_call（T-04 已接：success/blocked/error 全留痕，message_id 一期 NULL）、audit_log（http_access 已接，同 trace_id）
|
||
```
|
||
|
||
**客户线并行分支（`X-Agent-Type: customer` · 2026-09-10）：**
|
||
|
||
```text
|
||
api/chat 或 /stream → auth_adapter → customer_service.run_customer_chat（14 节点 LangGraph）
|
||
→ intent_classify（关键词优先：数据查询 > save_note > nav/匹配）
|
||
→ core_ro_tool（持仓/流水/风评/适当性/净值）或 fin_* RAG 或 reject/transfer
|
||
→ interpret/generate/chitchat → sanitize_postprocess.finalize_sanitized_reply（1B）
|
||
→ profile_maybe_extract → threshold_service.sync（C-04 摘要写 config）
|
||
→ query_holdings 末尾 build_threshold_alert（达线追加提醒 + customer_notify_log）
|
||
SSE：prepare_customer_stream 整图跑完再 _chunk_reply_text 推块
|
||
```
|
||
|
||
------
|
||
|
||
## 3. 主链路 · 知识库入库
|
||
|
||
```text
|
||
admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3)
|
||
→ milvus_tool 写入 Collection（dim=1024）
|
||
→ 元数据可选写 MySQL；原文件存 data/kb/
|
||
```
|
||
|
||
------
|
||
|
||
## 4. 分支 · 四 Agent
|
||
|
||
| X-Agent-Type | 写画像 | 特殊 |
|
||
| --- | --- | --- |
|
||
| customer | L1 | 仅本人；读 suitability 本人 |
|
||
| advisor | L2 | customer_advisor_rel 校验 |
|
||
| analyst | 无 | 仅 SELECT SQL |
|
||
| risk | L3、预警、适当性 | R-02 可 blocked |
|
||
|
||
------
|
||
|
||
## 5. 每步 I/O
|
||
|
||
| 步骤 | 输入 | 输出 | 约定 |
|
||
| --- | --- | --- | --- |
|
||
| 鉴权 | JWT | AuthContext | 失败 401/403 + audit + input_guard_log 双写（401 归 platform） |
|
||
| 会话 | session_id | Redis ctx + MySQL session | actor_id 一致（AUTH_403_SESSION_AGENT） |
|
||
| 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 | 不可删改；http_access 经 audit 中间件 |
|
||
|
||
------
|
||
|
||
## 6. 关键数据约定
|
||
|
||
- Agent 库 SQL：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql`
|
||
- Core 模拟：`scripts/core/01-ddl.sql` · **`07-seed-nav-history.sql`** · 说明 `docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md`
|
||
- Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md`
|
||
- Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维
|
||
- 禁止：Agent 覆盖 L0 正式 C1~C5
|