项目概览

本文引用的文件

readme.md
AI_AGENT.md
pom.xml
ai-gateway/pom.xml
GatewayApplication.java
StickyRouteFilter.java
TokenResolver.java
StickyUnavailableException.java
GatewayErrorHandler.java
App.java
AiCleanController.java
AiSmartCleanController.java
DmController.java
GraphController.java
AgentChatController.java
InsightController.java
main.ts
package.json

简介

清鉴是一个面向纪检监察、经侦机关及风控调查场景的智能数据研判工具。它围绕“多源异构数据导入 → 清洗治理 → 建模分析 → 可视化 → Agent 对话式研判”的闭环展开，目标是在公安、审计、风控等强监管环境中，把话单、银行账单、第三方支付、基站轨迹、外部库表等业务数据，转化为可查询、可图谱化、可由 AI 辅助推理的调查线索。

从用户视角看，它是一个桌面客户端；从系统视角看，它是 Electron 桌面端 + Spring Cloud Gateway + Spring Boot 多模块后端 + PostgreSQL/pgvector + Redis + DuckDB 的组合。仓库中的术语强调“资金回流”“闭环交易”“快进快出”“通联异常”“时空伴随”“白手套”“攻守同盟”等调查业务概念，而不是泛化的数据分析平台。

章节来源

AI_AGENT.md:1-200

项目结构

仓库是 Maven 聚合工程，父 POM 打包类型为 pom，包含两个主要子模块：

模块	角色	关键技术
`ai-server`	业务后端	Spring Boot 3、MyBatis-Plus、dynamic-datasource、AgentScope、pgvector、Redis、Elasticsearch、Neo4j（可选）
`ai-gateway`	用户粘性路由网关	Spring Cloud Gateway、WebFlux、Sa-Token、PostgreSQL、Redis
`ai-electron`	桌面客户端外壳	Electron、ElectronEgg、前端构建脚本
`ai-frontend`	前端界面	Vue 3、TypeScript、Vite、Ant Design Vue、G6、ECharts、MapLibre + pmtiles
`sql`	数据库脚本	建表、初始化、网关 DDL、Agent/清洗/外部表相关 SQL
`QingJian`	运行时工作空间素材	Agent 提示词、Skills、配置、许可证、模板
`cmd` / `lib`	本机工具	授权工具、地图瓦片转换工具等

graph TB
    subgraph "客户端"
        EE["Electron 进程<br/>electron/main.ts"]
        FE["Vue 前端<br/>Vite + Ant Design Vue"]
    end

    subgraph "网关层"
        GW["Spring Cloud Gateway<br/>StickyRouteFilter"]
    end

    subgraph "业务后端"
        AS["ai-server<br/>Spring Boot 应用"]
        AG["agent 模块"]
        AC["aiclean 模块"]
        DM["dm 模块"]
        GR["graph 模块"]
        PS["person 模块"]
        CL["call 模块"]
        TR["trans 模块"]
        TK["track 模块"]
        GV["govern 模块"]
        EX["external 模块"]
        OT["otg 模块"]
        KN["knowledge 模块"]
    end

    subgraph "数据层"
        PG["PostgreSQL + pgvector"]
        RD["Redis"]
        DD["DuckDB"]
        ES["Elasticsearch"]
        N4["Neo4j（可选）"]
    end

    FE --> EE
    EE --> GW
    GW --> AS
    AS --> AG
    AS --> AC
    AS --> DM
    AS --> GR
    AS --> PS
    AS --> CL
    AS --> TR
    AS --> TK
    AS --> GV
    AS --> EX
    AS --> OT
    AS --> KN
    AS --> PG
    AS --> RD
    AS --> DD
    AS --> ES
    AS --> N4

图表来源

main.ts:1-19
GatewayApplication.java:1-23
App.java
AI_AGENT.md:1-200

章节来源

pom.xml:1-23
AI_AGENT.md:1-200

核心组件

组件	职责	关键入口或类型
Electron 客户端	启动桌面窗口、加载前端、调用本地能力、转发请求到网关	`electron/main.ts`、`package.json`
前端	登录、案件与工作空间管理、数据导入、清洗、图谱、Agent 对话、业务查询	Vue 3 + TypeScript 前端工程
网关	按用户解析 token、选择固定 ai-server 节点、流式转发 SSE/上传/下载	`StickyRouteFilter`、`TokenResolver`
后端主应用	加载业务模块、持久层、Agent 子系统、RAG、知识库、权限与系统服务	`com.zsjz.ai.App`
agent 模块	AgentScope Harness、模型管理、意图识别、追问、RAG、工具注册、SQL 执行、Python 沙箱	`AgentChatController`、`InsightController`
aiclean 模块	智能清洗、模板匹配、向量索引、规则校验、清洗任务状态	`AiCleanController`、`AiSmartCleanController`
dm 模块	数据管理、文件元数据、清洗前置处理、表字段元数据	`DmController`
graph 模块	图谱查询与展示	`GraphController`
person/call/trans/track/govern/external/otg/knowledge	人物、通话、资金、轨迹、治理、外部表、OTG、知识检索等业务域	对应 Controller/Service/Mapper
数据层	PostgreSQL/pgvector（主库）、DuckDB（按工作空间切换）、Redis、Elasticsearch、Neo4j	dynamic-datasource、pgvector、Spring Data Elasticsearch

章节来源

AI_AGENT.md:1-200
AiCleanController.java
AiSmartCleanController.java
DmController.java
GraphController.java
AgentChatController.java
InsightController.java

架构总览

清鉴的整体边界可以理解为三层：

客户端层：Electron 提供桌面进程，运行 Vue 前端页面。前端通过约定前缀 /js 和后端上下文路径 /js/a 对齐接口。
网关层：Spring Cloud Gateway 不复制业务逻辑，只做“用户粘性路由”。同一个用户的请求始终落到同一台 ai-server，避免会话、附件、工作空间切片分散。

后端层：Spring Boot 单体聚合应用按业务域拆包，但部署时通常以单个 ai-server 实例或多实例集群形式存在；网关负责把用户绑定到具体实例。

sequenceDiagram
participant User as "调查员"
participant Client as "Electron 客户端"
participant Frontend as "Vue 前端"
participant Gateway as "Spring Cloud Gateway"
participant Server as "ai-server 实例"
participant DB as "PostgreSQL/pgvector"
participant Cache as "Redis"
participant Duck as "DuckDB"

User->>Client: 打开清鉴桌面客户端
Client->>Frontend: 加载前端页面
Frontend->>Gateway: 发起登录或业务请求
Gateway->>Cache: 解析 token 得到 userId
Gateway->>Server: 转发到该用户绑定的 ai-server
Server->>DB: 读写平台元数据、Agent 会话、RAG 索引
Server->>Duck: 在工作空间 DuckDB 中执行只读 SQL
Server-->>Frontend: 返回 Result 或 SSE 流

图表来源

main.ts:1-19
GatewayApplication.java:1-23
AI_AGENT.md:1-200

章节来源

AI_AGENT.md:1-200
ai-gateway/pom.xml:1-148

关键业务流程

流程一：从启动客户端到发起 Agent 对话

flowchart TD
    Start(["启动客户端"]) --> LoadFE["Electron 加载 Vue 前端"]
    LoadFE --> Login["前端调用登录接口"]
    Login --> GWLogin["网关解析 token 并路由到后端"]
    GWLogin --> Auth["后端 Sa-Token 验证并建立会话"]
    Auth --> Workspace["选择工作空间/案件"]
    Workspace --> ChatAPI["前端发起 Agent 对话"]
    ChatAPI --> AgentCore["agent 模块构造 Agent 会话"]
    AgentCore --> Tools["调用工具：execute_sql、RagSchemaSearchTool、业务分析工具"]
    Tools --> DuckDB["DuckDB 查询工作空间数据"]
    Tools --> Vector["pgvector 语义检索模板/知识"]
    AgentCore --> SSE["SSE 流式返回对话结果"]
    SSE --> End(["调查员看到研判结论"])

关键点：

Agent 使用 AgentScope Harness，结合 LLM、中间件、工具集。
execute_sql 只在 DuckDB 上执行只读 SQL，物理表必须先在模板元数据中登记。
RAG 既用于模板元数据语义检索，也用于知识库文档检索。
前端通过 SSE 接收流式消息，适合长耗时调查分析。

图表来源

AgentChatController.java
InsightController.java
AI_AGENT.md:1-200

流程二：导入与清洗数据

flowchart TD
    ImportStart["导入话单/账单/轨迹/外部表文件"] --> FileMeta["dm 模块记录文件元数据"]
    FileMeta --> TemplateMatch["aiclean 模板匹配与列名映射"]
    TemplateMatch --> SmartClean["智能清洗：类型推断、规则校验、拒绝记录"]
    SmartClean --> CleanResult{"清洗是否通过？"}
    CleanResult -->|否| Reject["查看拒绝原因与修正规则"]
    CleanResult -->|是| DuckCreate["写入工作空间 DuckDB 临时表"]
    DuckCreate --> MetaSync["同步 table_info/table_field 元数据"]
    MetaSync --> Ready["数据可用于 Agent SQL、图谱、业务查询"]

关键点：

数据先由 dm 模块管理文件与元数据。
aiclean 模块负责模板匹配、智能清洗、向量索引与规则验证。
清洗后数据进入 DuckDB，供 Agent 的 execute_sql 和业务查询使用。
模板与字段的向量索引用于 AI 自动匹配表结构。

图表来源

DmController.java
AiCleanController.java
AiSmartCleanController.java
AI_AGENT.md:1-200

流程三：查看图谱与业务查询

flowchart TD
    QueryStart["在图谱或业务页面发起查询"] --> DomainAPI["对应领域 Controller"]
    DomainAPI --> Service["Service 组合查询：PostgreSQL、DuckDB、Redis、Neo4j"]
    Service --> Graph["图谱查询：人物/通话/资金/轨迹关系"]
    Service --> Business["业务查询：夜间通话、持续联系、敏感日期、资金流水等"]
    Graph --> Front["前端渲染 G6/ECharts/地图"]
    Business --> Front
    Front --> Analyst["调查员导出或继续向 Agent 提问"]

关键点：

图谱、人物、通话、资金、轨迹、治理、外部数据各自有独立 Controller。
查询可能跨 PostgreSQL、DuckDB、Redis、Neo4j。
图谱结果常用于辅助 Agent 生成更精确的分析结论。

图表来源

GraphController.java
AI_AGENT.md:1-200

详细组件分析

网关：用户粘性路由

网关的核心目标是“一个用户始终访问同一台 ai-server”。它不负责业务鉴权细节，只复用 Sa-Token 提供的 token → loginId 能力，并把 loginId 映射到已绑定的服务节点。

flowchart TD
    Req["网关收到请求"] --> Token["TokenResolver 解析 token"]
    Token --> UserId{"得到 userId？"}
    UserId -->|否| FailToken["返回认证失败"]
    UserId -->|是| RouteKey["计算 routeKey：userId/serviceId"]
    RouteKey --> CacheCheck["检查 Redis 中缓存的 ai-server 地址"]
    CacheCheck --> Found{"找到绑定节点？"}
    Found -->|是| Forward["重写 URL 并转发"]
    Found -->|否| CheckHealth["查询健康节点并绑定"]
    CheckHealth --> Healthy{"有可用节点？"}
    Healthy -->|否| Unavailable["抛出 StickyUnavailableException"]
    Healthy -->|是| BindNode["写入 Redis 绑定"]
    BindNode --> Forward

设计约束：

绑定节点不可用时明确失败，不自动切换到其他节点，因为案件数据、附件、工作空间属于特定实例。
token 解析走 Redis 缓存，未命中时回退到 Sa-Token。
错误分类包括：粘性路由不可用、无匹配路由、上游连接失败。

图表来源

StickyRouteFilter.java
TokenResolver.java
StickyUnavailableException.java
GatewayErrorHandler.java

章节来源

GatewayApplication.java:1-23
ai-gateway/pom.xml:1-148
StickyRouteFilter.java
TokenResolver.java
StickyUnavailableException.java
GatewayErrorHandler.java

后端主应用与模块边界

后端主应用是 Spring Boot 入口，业务按 module/<domain> 组织。根据代码库中的包和注释，领域取值包括：agent、call、dm、external、govern、graph、otg、person、plat、track、trans。aiclean、knowledge、embedding 作为支撑能力，贯穿多个业务域。

graph LR
    App["App.java<br/>后端主应用"] --> Common["common 公共层"]
    App --> Agent["module/agent"]
    App --> Aiclean["module/aiclean"]
    App --> Knowledge["module/knowledge"]
    App --> Embedding["module/embedding"]
    App --> Call["module/call"]
    App --> Trans["module/trans"]
    App --> Track["module/track"]
    App --> Person["module/person"]
    App --> Graph["module/graph"]
    App --> Govern["module/govern"]
    App --> External["module/external"]
    App --> Otg["module/otg"]
    App --> Plat["module/plat"]
    App --> Dm["module/dm"]

图表来源

App.java
AI_AGENT.md:1-200

章节来源

App.java
AI_AGENT.md:1-200

Agent 子系统

Agent 子系统是清鉴的 AI 研判中枢。它不是简单聊天机器人，而是把 LLM、工具、中间件、RAG、工作空间、Python 沙箱、图与业务查询能力整合在一起。

核心点：

对外暴露 Agent 对话、模型管理、工具包、能力检测、产物文件等接口。
工具包括 execute_sql、list_tables、search_table_schema、render_chart、execute_python，以及通话、资金、轨迹、人物、图谱、文件、治理表等业务工具。
RAG 使用 pgvector 做模板元数据和知识库的语义检索。
SQL 执行限制为 DuckDB 只读，并通过 resultId 分页返回结果集。

意图识别和追问中间件让对话更贴近调查场景。

classDiagram
class AgentChatController {
    +"处理 Agent 对话请求"
    +"SSE 流式返回"
}
class InsightController {
    +"深度洞察/分析"
    +"结构化结果输出"
}
class AgentService {
    +"组装 Agent 会话"
    +"调度工具与中间件"
}
class SqlAnalysisTool {
    +"execute_sql"
    +"DuckDB 只读查询"
}
class RagSchemaSearchTool {
    +"search_table_schema"
    +"pgvector 语义检索"
}
class PythonAnalysisTool {
    +"execute_python"
    +"沙箱执行"
}

AgentChatController --> AgentService : "调用"
InsightController --> AgentService : "调用"
AgentService --> SqlAnalysisTool : "使用"
AgentService --> RagSchemaSearchTool : "使用"
AgentService --> PythonAnalysisTool : "使用"

图表来源

AgentChatController.java
InsightController.java
AI_AGENT.md:1-200

章节来源

AI_AGENT.md:1-200
AgentChatController.java
InsightController.java

数据清洗与模板体系

清洗链路的关键是“模板 + 规则 + 向量索引”：

模板描述表结构、字段映射、中文名、必填项。
智能清洗负责类型推断、值转换、规则校验、拒绝收集。
模板向量索引用于 AI 自动匹配新导入文件的表结构。

清洗完成后，数据进入 DuckDB，同时维护 table_info、table_field 元数据。

flowchart TD
File["导入文件"] --> Probe["探测列统计与指纹"]
Probe --> Candidate["加载候选模板"]
Candidate --> Match["AI 模板匹配 + 向量检索"]
Match --> Plan["生成清洗计划"]
Plan --> Execute["执行清洗、转换、校验"]
Execute --> Store["写入 DuckDB + 元数据"]
Store --> Index["更新模板向量索引"]

图表来源

AiCleanController.java
AiSmartCleanController.java
AI_AGENT.md:1-200

章节来源

AiCleanController.java
AiSmartCleanController.java
AI_AGENT.md:1-200

依赖关系分析

模块间依赖

agent 依赖 dm、call、trans、track、person、graph、govern 的业务能力，将其封装为工具。
aiclean 依赖 dm 的文件与元数据，并向 agent 提供模板向量索引。
knowledge 与 embedding 为 RAG 提供知识库文档、向量模型与索引能力。
plat 提供系统、用户、会话、工作空间、健康检查等公共平台能力。

graph、call、trans、track、otg、external 是业务查询域，共同依赖 PostgreSQL、DuckDB、Redis、Neo4j。

graph TB
Agent["agent"] --> Call["call"]
Agent --> Trans["trans"]
Agent --> Track["track"]
Agent --> Person["person"]
Agent --> Graph["graph"]
Agent --> Govern["govern"]
Agent --> Dm["dm"]
Aiclean["aiclean"] --> Dm
Aiclean --> Agent
Knowledge["knowledge"] --> Agent
Embedding["embedding"] --> Knowledge

图表来源

AI_AGENT.md:1-200

外部依赖

依赖	用途	注意事项
PostgreSQL + pgvector	平台元数据、Agent 会话、RAG 向量索引	主库
DuckDB	工作空间案情库，Agent SQL 只读查询	按工作空间切换
Redis	Sa-Token、会话、缓存、mem0、网关路由缓存	与网关共享
Elasticsearch	搜索与索引（例如知识库、附件索引）	单索引 + caseId 隔离
Neo4j	图谱（配置存在）	非全链路强依赖
AgentScope	LLM 编排、工具、中间件、RAG	支持 dashscope/ollama/openai
Sa-Token	鉴权与会话	网关与后端需一致

章节来源

AI_AGENT.md:1-200
ai-gateway/pom.xml:1-148

性能与扩展性

网关使用 WebFlux，适合流式转发 SSE、分片下载和大文件上传。
后端分页统一基于 MyBatis-Plus，DuckDB 分页拦截器已注册。
DuckDB 作为工作空间分析库，适合离线、大表、一次性分析，避免对 PostgreSQL 造成过大压力。
粘性路由保证用户会话、附件、工作空间切片的局部性，减少跨实例一致性成本。
Agent 的 SQL 结果通过 resultId 分页缓存，避免一次拉取超大结果集。
扩展点主要集中在：
- 新增业务域 Controller/Service/Mapper。
- 新增 @Tool 工具类接入 Agent。
- 新增清洗模板、规则、同义词。
- 新增知识库文档与向量索引。
- 新增图谱关系与查询视图。

[本节为通用指导，不直接分析具体源码]

故障排查

常见定位方向：

现象	可能原因	排查建议
登录后频繁被踢或数据不一致	网关粘性路由失效，请求落到不同 ai-server	检查 Redis 中 `gateway:route:*` 和用户绑定
粘性路由返回不可用	绑定节点停用、DOWN、无健康节点	检查 `StickyUnavailableException` 和节点健康状态
Agent 无法查表	DuckDB 中没有表或元数据未登记	检查 dm 模块文件导入、aiclean 清洗完成、`table_info`
SQL 查询无结果	当前工作空间 DuckDB 与 Agent 选错	检查工作空间切换与会话归属
清洗大量拒绝	模板不匹配、字段映射错误、规则过严	查看拒绝记录、调整模板或规则
图谱为空	数据未入库或图谱关系未构建	检查原始数据、清洗结果、图谱服务
许可证无效或过期	本机授权文件与机器码不匹配	使用仓库说明中的 `regInfo.exe` 校验

章节来源

StickyUnavailableException.java
GatewayErrorHandler.java
readme.md

结论

清鉴不是一个普通的数据看板，而是一个面向调查业务的 AI 辅助平台。它的价值在于：

用 Electron 提供稳定、可控的桌面体验。
用粘性路由网关保证调查会话和数据局部性。
用多模块后端划分 agent、aiclean、knowledge、graph、person、call、trans、track、govern、external、otg 等业务边界。
用 PostgreSQL/pgvector、Redis、DuckDB 区分平台元数据、缓存、工作空间分析。
用 Agent + RAG + SQL/Python/图谱工具，把原始数据转化为调查线索。

对于初学者，理解“Agent、RAG、pgvector、粘性路由、许可证”五个概念即可上手；对于开发者，重点应放在模块边界、工具扩展点、清洗模板体系和数据流向。

[本节为总结性内容，不直接分析具体源码]

项目概览.md 25 KB

Түүх Анхны өгөгдөл

项目概览

目录

简介

项目结构

核心组件

架构总览

关键业务流程

流程一：从启动客户端到发起 Agent 对话

流程二：导入与清洗数据

流程三：查看图谱与业务查询

详细组件分析

网关：用户粘性路由

后端主应用与模块边界

Agent 子系统

数据清洗与模板体系

依赖关系分析

模块间依赖

外部依赖

性能与扩展性

故障排查

结论

项目概览.md 25 KB Түүх Анхны өгөгдөл

项目概览

目录

简介

项目结构

核心组件

架构总览

关键业务流程

流程一：从启动客户端到发起 Agent 对话

流程二：导入与清洗数据

流程三：查看图谱与业务查询

详细组件分析

网关：用户粘性路由

后端主应用与模块边界

Agent 子系统

数据清洗与模板体系

依赖关系分析

模块间依赖

外部依赖

性能与扩展性

故障排查

结论

项目概览.md 25 KB

Түүх Анхны өгөгдөл