zhanghongyu_0626
0fb7d34d7a
- Enhanced the `AnalystAgent` class to include an `_audit_terminal` method for logging query denials, clarifications, and errors, ensuring compliance and traceability. - Updated error handling paths to call the new audit method, capturing relevant details such as question, user authentication, and SQL context. - Introduced new validation checks in `sql_guard.py` to enforce ownership filters for sensitive queries, improving security measures. - Added unit tests to verify the correct logging behavior and ownership filter enforcement, ensuring robust functionality. This update significantly strengthens the auditing capabilities of the analyst agent, enhancing security and compliance in query handling.
154 lines
7.5 KiB
Markdown
154 lines
7.5 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 + 28 客户 / 12 产品 / 持仓交易种子
|
||
（风控演示：`.\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"}
|
||
cd web && npm run dev → 5173 代理 8000
|
||
python -m pytest → 816 passed 1 skipped
|
||
问数答辩前：见 `docs/答辩/DEMO-SOP-问数.md`（灌 metric+template 种子 · 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 + 前端 P0 Demo（2026-09-10，`merger`）**。**测试基线：`python -m pytest` → 804 passed 1 skipped** · **`web/` 19 Vitest 绿 · `npm run build` 绿**。
|
||
|
||
**下一步（统筹 P1）：** merger commit · 20 题 battery · 客服验收 · analyst D-09/N-03/N-07 · **客服** L1/L2 Redis（风控不做 L1/L2）。
|
||
|
||
**本机已就位状态（2026-09-10）：** `.env` 含 `REDIS_URL=redis://127.0.0.1:6380/0`；pytest **804 绿**；问数 D-06 结果+模板缓存已接；前端四角色 Demo 可 walkthrough。
|
||
|
||
**本机已知坑：** `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` · 说明 `docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md`
|
||
- Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md`
|
||
- Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维
|
||
- 禁止：Agent 覆盖 L0 正式 C1~C5
|