AI_AGENT.md 35 KB

AI Agent 协作指南 · zsjz-ai(清鉴)

本文件是仓库级约定,供 AI 编码助手(WorkBuddy / Claude Code / Cursor / Copilot 等)在本仓库内改代码时遵守。

⚠️ 别和下面两个文件搞混 —— 它们是产品运行时的 AI 人格提示词,不是给编码助手看的:

  • ai-server/src/main/resources/prompts/AGENTS.md
  • QingJian/agent/AGENTS.md

改那两个文件 = 改产品里 AI 研判专家的人设与话术;改本文件 = 改编码助手的行为约定。


1. 项目一句话定位

清鉴(QingJian) —— 面向纪检监察 / 经侦机关的智能资金数据研判平台。

业务闭环:

多源异构数据导入(话单 CDR / 银行账单 / 第三方支付 / 基站轨迹 / 外部库表)
   → 清洗治理(dm 模块)
   → 建模分析(通话·资金·轨迹·人物画像·图谱)
   → 可视化(ECharts / G6 关系图 / 离线栅格地图)
   → AI 对话式研判(AgentScope Agent + RAG + SQL 工具)

领域术语(写注释/命名时沿用它,不要自创): 资金回流、闭环交易、快进快出、通联异常、时空伴随、白手套、攻守同盟。


2. 仓库结构

zsjz-ai/
├─ pom.xml                    # 父 POM(packaging=pom),Spring Boot 3.5.16,聚合 ai-server + ai-gateway
├─ ai-server/                 # 后端:Spring Boot 3 + MyBatis-Plus + AgentScope
├─ ai-gateway/                # 网关:Spring Cloud Gateway(WebFlux),按用户粘性路由到多台 ai-server
├─ ai-frontend/               # 前端:Vue3 + Vite7 + TS + Ant Design Vue(JeeSite 脚手架血统)
├─ sql/                       # 建表 / 初始化脚本(*.sql,含网关 gateway.sql)
├─ qingjian/                  # 运行期目录:system/(程序资产)+ data/(业务数据,按案件隔离)
├─ cmd/  lib/  pmtiles.exe    # 本机工具(regInfo.exe 授权、mbtiles→pmtiles 转换等)
└─ enc.md  readme.md

qingjian/ 不是源码目录:system/ 放 conf、模板库、license、RocksDB、模型与原生库; data/ 放案件库、导入原件、EDS 材料、对话附件、AI 产物(备份只备 data/)。 完整布局见 docs/design/storage-layout.md。


3. 技术栈

后端(ai-server)

项 值
JDK 25
框架 Spring Boot 3.5.16
持久层 MyBatis-Plus 3.5.17 + dynamic-datasource 4.5.0
主库 PostgreSQL + pgvector(master)
分析库 DuckDB(slave,按工作空间切换)
缓存 Redis
图库 Neo4j(配置存在,非全链路强依赖)
鉴权 Sa-Token 1.46
Agent AgentScope 2.1.0-SNAPSHOT(本地安装 main 分支;harness + dashscope/ollama/openai + mem0 + rag-simple + redis + jdbc 技能仓库)
检索 Elasticsearch 8.18(spring-boot-starter-data-elasticsearch,单索引+caseId 隔离)
其他 fesod-sheet(Excel)、Hutool、Guava、MapStruct 1.6.3、commons-compress、JNA
启动类 com.zsjz.ai.App
端口 8980

ai-server/src/main/resources/app.yml 是 Solon 时代遗留配置,已不生效,只作历史参考,不要照它改。 生效配置是 application.yaml + application-dev.yaml。

前端(ai-frontend)

  • Vue 3.5 + TypeScript 5.9 + Vite 7 + pnpm 10(preinstall: only-allow pnpm,禁止 npm/yarn)
  • Ant Design Vue 4.2.6、Pinia 2.3、vue-i18n 11、UnoCSS 66
  • 图可视化:G6 5、X6、@relation-graph/vue;图表 ECharts 6
  • 地图:maplibre-gl + pmtiles(离线栅格底图)
  • Markdown:vditor、streamdown-vue、markdown-it
  • Node 要求:>=20.19 || >=22.12

接口前缀 /js,开发环境由 .env.development 代理到 http://127.0.0.1:8980:

VITE_PROXY = [["/js","http://127.0.0.1:8980/js",false]]
VITE_GLOB_API_URL_PREFIX = /js
VITE_GLOB_ADMIN_PATH = /a

请求最终落到 /js/a/...(urlPrefix(/js) + adminPath(/a)), 与后端 server.servlet.context-path: /js/a 严格对应 —— 两者必须同步改。 调接口时用 url: adminPath + '/xxx'(defHttp 会自动补 /js); 不走 defHttp 的场景(fetch / <img src>)用 glob.apiUrl + glob.urlPrefix + glob.adminPath + path。


4. 后端分层与落位约定

包根:com.zsjz.ai

com.zsjz.ai
├─ App.java                      启动类
├─ common/                       跨模块复用
│  ├─ config/                    Result、WebConfig、MybatisPlusConfig、LicenseFilter、
│  │                             DuckdbUnpooledDataSource、BigDecimal 序列化器
│  ├─ base/                      Query、TreeNode、BasicColumn、Cleaned、ErrorEnum
│  ├─ enums/  constants/  utils/
│  └─ model/<domain>/{dto,entity,query,vo}/     ★ DTO / 实体统一放这里
└─ module/<domain>/
   ├─ controller/                仅收参 + 调 service
   ├─ service/  service/impl/
   └─ mapper/   (XML 在 resources/mappers/<domain>/*.xml)

<domain> 固定取值:agent call dm external govern graph otg person plat track trans

配套资源:

ai-server/src/main/resources/mappers/<domain>/<Xxx>Mapper.xml

命名规范

  • 查询入参 → common.model.<domain>.query.XxxQuery
  • 出参 DTO → common.model.<domain>.dto.XxxDTO
  • 数据库实体 → common.model.<domain>.entity.Xxx
  • Service 接口 XxxService,实现 XxxServiceImpl
  • 类名后缀:Controller / Service / Mapper / DTO / VO / Entity / Query / Enum / Const

编码规则

  1. Controller 不写业务逻辑,只做参数校验 + 转调 service。
  2. 分页统一用 MyBatis-Plus Page<T>(PaginationInnerInterceptor(DbType.DUCKDB) 已注册)。
  3. 统一返回 Result<T>:Result.succeed(data) / Result.failure(msg)。 > 存量 Controller(如 CallNightController)有直接返回裸对象的历史写法;新增代码一律用 Result,存量代码按需渐进改造。
  4. 金额/比率用 BigDecimal(已配 BigDecimalSerializer / BigDecimalDeserializer),禁用 double。
  5. 鉴权取当前用户:StpUtil.getLoginIdAsLong()。会话、消息、模型配置等用户级资源必须带 userId 做归属校验,不能只按 id 查。
  6. 跨库访问用 @DS("slave")(参考 SqlAnalysisTool 依赖的 SqlQueryMapper);不标注则走 master。
  7. 注释用中文,Javadoc 写清「做什么 + 为什么」,不写废话。
  8. 新增枚举尽量实现 HasInnerEnum,与存量保持一致。

5. 数据层要点

数据源 用途
master(PostgreSQL + pgvector) 平台元数据、table_info/table_field、Agent 会话/消息、模型与 Provider 配置、技能(agentscope_skills/agentscope_skill_resources,按 namespace=用户ID 隔离 + 启停表 agent_skill_state)、RAG 索引状态、向量检索
slave(DuckDB) 按工作空间切换的案情库;Agent 的 execute_sql 只在这里跑
Redis Sa-Token 登录态、业务缓存(qing_jian_ai*)、mem0、Agent 会话状态(qing_jian:agent:{agentscope}:session:*,由 RedisAgentStateStore 存对话历史)
Neo4j 图谱(配置在 application-dev.yaml)
  • 表/字段元数据三表链路:meta_raw_sheet → table_info → table_field
  • 建表脚本放 sql/,新增表结构务必同步补脚本 和 元数据三表
  • mapUnderscoreToCamelCase 已开启

⚠️ 环境配置

application-dev.yaml 内含本机数据库密码 / 内网 IP,属于开发便利配置。

  • 不要把真实凭证提交到公开仓库
  • 不要在生产 profile 复用 dev 配置

6. Agent 子系统(module/agent)★ 核心

架构

AgentScope HarnessAgent + Toolkit + 中间件:

controller/   AgentChatController(REST + SSE,裸返回)
              AgentModelController(模型/厂商 CRUD,Result 包装)
              AgentResultController(execute_sql 结果集分页,裸返回)
              AgentPythonFileController(Python 产出图片文件服务)
service/      AgentChatService、AgentModelService、AgentModelProviderService
tools/        SqlAnalysisTool、RagSchemaSearchTool、PythonAnalysisTool、
              WorkspaceInfoTool、GovernTableTool、各业务域 *AnalysisTool
intent/       意图识别(IntentService / IntentMiddleware / IntentEnum)
followup/     追问生成(FollowupService / FollowupMiddleware)
rag/          RagSchemaService、EmbeddingProvider(本地/在线向量模型路由)、
              EmbeddingModelFactory、RagProperties
python/       PythonExecutor(沙箱执行)
sql/          SqlResultStore(结果集缓存,供前端分页;按登录用户归属)
prompt/       PromptLoader、PromptHelper
scaffold/     WorkspaceScaffolder(工作空间初始化)
mapper/       Agent*Mapper、SqlQueryMapper、RagVectorMapper
entity/       AgentChatSession、AgentMessage、AgentModel、AgentModelProvider、RagIndexStatus

工具清单(@Tool 注解)

工具 说明
execute_sql 在当前工作空间 DuckDB 上执行只读 SQL,返回 resultId + 列定义 + 当前页 + 总行数
list_tables 列出已登记的可查表(table_info + ai_clean_template 含 AI 动态表 + wa_mforensics_ 取证表结构文件):物理表名/中文名/字段(物理列名、类型、中文注释、必填)。不扫描 DuckDB(业务约定:先登记元数据才可查);取证表只含 vectorize=true 的表,wa_mforensics_ext_* 不进清单
search_table_schema 基于 pgvector 的模板元数据语义检索(AiCleanTemplateVectorIndex):返回物理表名 + 字段,供生成 SQL;同一份向量索引也用于 AI 模板匹配召回
render_chart 校验并返回 ECharts 图表配置(禁止用于关系图)
execute_python 在沙箱中执行 Python 脚本分析,产出图片经 /py/files/** 访问;任意表/字段的关系图用沙箱内置 emit_relation_graph(nodes, edges, title) 输出 relation_graph.json,后端转成 relationGraph 交给前端通用关系图组件
get_current_workspace / get_user_selected_workspace 读取当前/用户所选工作空间信息
get_call_records 通话原始明细(CallRecordService#getCallRecord)
stat_call_night_summary / stat_call_night_detail 夜间通话一/二层(CallNightService)
stat_call_continuous_summary / stat_call_continuous_detail 持续联系一/二层(CallContinuousService)
stat_call_sensitive_summary / stat_call_sensitive_detail 敏感日期联系一/二层(CallSensitiveService)

业务域工具分组(AgentToolRegistry,当前实际注册 67 个)

只读 service 由 AgentToolRegistry 统一注册为 6 个工具组,默认只装备 person 组, 其余组由模型调用 reset_equipped_tools 按需切换 —— 避免每轮把全部 JSON Schema 塞进上下文。

组名 数量 覆盖能力 工具类 / 入参类
person(默认装备) 24 人员枚举与分组、通话/交易画像、常联系/常交易 TOP、汇总、运营商归属、银行卡、交易趋势、9 类亲密度行为 PersonAnalysisTool / PersonToolSpecs
call 7 通话明细、夜间/连续/敏感通话的汇总与明细 CallAnalysisTool / CallToolSpecs
trans 16 交易明细、大额、共同/相互交易、代持卡、现金流、连续交易、快速资金流转、理财、定期存款、频次、敏感交易 TransAnalysisTool / TransToolSpecs
track 16 基站轨迹、境外本地昼夜活动、快递、碰面、同住、同行出行 TrackAnalysisTool / TrackToolSpecs
graph 1 关系图谱取数(get_case_graph) GraphAnalysisTool / GraphToolSpecs
file 3 非表格材料档案:清单检索、分类统计、读正文样本 FileAnalysisTool / FileToolSpecs

⚠️ 上表是当前实际值,不是设计稿:otg(全文检索,OtgAnalysisTool)未注册 (OTG_TOOLS 为空、createGroup 整段注释),trans 的 TRANS_TOOLS 清单也还没补全, graph 的明细类工具同样没实现。改动工具清单时同步更新 AgentToolRegistryTest#TOTAL_BUSINESS_TOOLS 的数量下限。

工具描述与参数规范(新增 / 修改工具必读)

工具 description 和每个 @ToolParam.description 直接决定模型是否会选对工具、是否会漏传参数,按「面向 Agent 的 UX」对待:

  • 工具 description:一句话写清用途;再写「何时使用 / 何时不要用 / 与其他相似工具的边界」;涉及结果形态时写清返回结构(如 nodeList/edgeList、CSV 产物)。优先用短句和 ★ 标记关键边界,避免大段无结构说明。
  • 每个参数必须有 description:写清类型、格式、枚举取值、单位、默认值、是否必填。日期统一 yyyy-MM-dd,金额按元,比较符枚举使用描述中的原值。
  • 语义必填字段必须 required = true,并在 description 里写「必填 / 必传」;条件必填(如「lx=2/3 时必传」)或「建议必传」不要硬标 required,改为工具内可读校验 + description 说明。
  • 不要暴露 orderKey / sort / tableName 这类会被拼进 SQL 的内部字段;入参只保留真正参与业务条件的字段。
  • 错误信息要能指导重试:缺参时给出期望结构和示例(参考 get_case_graph 的 personNames 报错),不要只抛「参数错误」。
  • schema 契约测试:ToolSpecRequiredFieldContractTest 会扫描所有 *ToolSpecs,校验「description 写必填 ⇒ required=true」以及「required=true ⇒ description 写明必填」;新增参数会自动纳入检查。
  • 参考行业实践:Anthropic 的 Define tools(描述即 Agent UX、写清边界与示例)、OpenAI 的 Function calling(strict schema / required)、LangChain 的 Tools(参数 docstring)、以及社区整理的 Tool Calling Schema Standards(每个参数都写 description、schema 尽量扁平)。

分组机制要点(AgentToolRegistry 注释里有完整说明):

  • 组必须是 ToolGroupScope.META,否则 reset_equipped_tools 会拒绝("not manageable by this tool") 且组名不会出现在该工具 to_activate 的 enum 里;
  • 未激活组里的工具不进 getToolSchemas(activeGroups),模型完全看不到;
  • 新会话的初始激活组 = ReActAgent 在 build 时捕获的 toolkit.getActiveGroups(), 所以「默认装备哪一组」只由 AgentToolRegistry#DEFAULT_ACTIVE_GROUPS 决定;
  • reset_equipped_tools 是全量替换语义(不在 to_activate 里的组一律卸载), AgentService#appendRenderPrompt 里已提醒模型「把还要用的组一并列出,用完切回」。
  • 已知限制:ReActAgent 在会话恢复/结束时用共享 Toolkit 的全局 activeGroups 做 set/get, 同一 agent 实例的并发会话理论上可能互相覆盖全局状态(每轮实际按会话状态过滤,影响有限)。

通话分析 7 件套由 CallAnalysisTool 包装 module/call 的既有 service,只做适配不改业务, 保证「页面上的结论」与「AI 的结论」同口径;返回形态与 execute_sql 一致 (resultId + columns/rows/totalRows,前端 DataTableBlock 直接渲染可翻页表格), 单次取数上限 10,000 行(比 execute_sql 收紧,因 SqlResultStore 是 LRU 50 的共享缓存), 超限返回可读报错而不是静默截断。入参是专用 POJO(CallToolSpecs), 不暴露 orderKey/sort/tableName(Mapper XML 里是 ${} 拼接,属注入面)。 其余 5 个域同构:入参 *ToolSpecs、出参 ToolResultTable、上限 10,000 行。

唯一例外:get_case_graph 返回 {nodeList, edgeList} 结构化 JSON(不表格化,前端直接按它 自动渲染关系图),且边数超过 500 时按权重降序截断并附 truncated / totalEdges / note,防止 1 万条边的 JSON(约 30 万 token)冲爆上下文。

硬约束(不要放宽)

  • 结果集上限 100,000 行,超出要求模型加 LIMIT / WHERE
  • page_size 默认 50,上限 500
  • 单元格字符串截断 500 字符
  • 只读白名单首词:select / with / pragma / describe / show / explain,禁止多语句(含分号)
  • render_chart 会硬拦截 series.type == "graph",引导改用 get_case_graph(前端自动渲染关系图)

SSE 流式协议

POST /chat/stream,事件按序:tool_call → tool_input → tool_result → token(多次) → done / error

payload 结构:

{ type, data?, toolCallId?, toolName?, toolInput?, toolResult?, error?, sessionKey? }

前端消费方:ai-frontend/src/ai/api/(chatApi.ts / types.ts)。改动协议必须前后端同步。

子代理(subagent.enabled=true,默认开启):主 agent 通过 agent_spawn(task, subagent_type?, tools?, timeout_seconds?) 自行创建,每次新建一次性实例。 能力由档案决定:classpath:subagents/*.md 内置 + 工作区 cases/{caseId}/ai/agents/{agentRowId}/{userId}/subagents/*.md 同名覆盖;文件名即 subagent_type, frontmatter 支持 description / tools / skills,正文是系统提示词,不支持 model。 工具只能从基础工具(search_table_schema / list_tables / query_table_data / execute_python / render_chart / get_current_workspace)里选,且创建时只能收窄档案范围。子代理不继承父专家能力, 不带业务工具、知识库与 Intent/Followup。报告超过 subagent.max-inline-result-chars 时落盘到 runs/subagent-*.md 并返回 <persisted-output> 路径。task_* 与后台交付由 InMemorySubagentTaskRepository + SubagentDeliveryMiddleware 提供。SSE 额外下发 subagent_start / subagent_update / subagent_end(带 source = 父会话ID/档案名,不含子代理正文), 后台任务另发 task_update 并用 GET /chat/tasks?sessionId= 2 秒轮询;运行态只在内存,不落库、 刷新不恢复。父消息 tool_events 对 agent_spawn 只存 alias/status/durationMs/summary。

提示词

  • 运行时系统提示词:ai-server/src/main/resources/prompts/AGENTS.md
  • 未经明确要求,不要重写人格设定与输出格式(【异常概览】/【资金链路分析】/【通联行为画像】/【时空碰撞结果】/【研判结论与建议】),那是产品行为的一部分。

前端渲染管线(ai-frontend/src/ai/)

后端 AgentService#appendRenderPrompt 强制的输出契约 → 前端块的映射:

AI 输出形式 前端块 组件
裸 JSON 混在 markdown 正文(execute_sql 结果,禁止围栏) table blocks/DataTableBlock.vue(按 resultId 调 /chat/results/{id} 翻页)
`echarts 围栏(ECharts option JSON) echarts blocks/EChartsBlock.vue
get_case_graph 工具结果({nodeList, edgeList} 原样 JSON,无需围栏) 聊天图谱块 ai/components/graph/GraphAnalysisBlock.vue(独立 G6 简版:查找/过滤/明细查询,不复用对象关系分析页面组件)
execute_python 结果里的 relationGraph(Python 调 emit_relation_graph 产出) 通用关系图块 ai/components/relation/RelationGraphBlock.vue(独立 G6 基础渲染:缩放/拖拽/适配/全屏 + 类型图例,不复用案件图谱组件)
`html 围栏 / 裸 <html>·<svg> html blocks/HtmlBlock.vue(sandbox iframe)
其余代码围栏 / markdown 正文 code / markdown blocks/CodeBlock.vue / blocks/MarkdownBlock.vue

旧会话里的 `graph 围栏不再由后端产出,前端仍由 BlockRenderer 交给 GraphAnalysisBlock 只读兼容;

render_graph 工具已下线:案件对象关系走 get_case_graph,任意表/字段关系走 Python 的 relationGraph 契约, 前端分别自动渲染,不要再手写 graph 围栏或 ECharts graph series。

通用关系图输出契约(Python,不是新工具)

任意业务表/字段的关系图(人物管理、社交关系、亲属/同事、交易、通话、同住、快递等)不新增专用工具: 模型用 execute_python 自己查 DuckDB、自己决定节点与边口径,然后调用沙箱内置模块:

```python from zgraph import emit_relation_graph

emit_relation_graph(nodes=[...], edges=[...], title="人物社交关系")


- `nodes` / `edges` 支持 `list[dict]` 或 pandas DataFrame。
- node:`{id, label, type, value}`;edge:`{source, target, relation, weight, directed}`,
  可选 `sourceLabel/targetLabel/sourceType/targetType`;`source/target` 对应 `node.id`。
- `type` 建议 `person/phone/card/org/place/vehicle/account/other`。
- 调用后写沙箱当前目录的 `relation_graph.json`;`PythonExecutor` 读取后由
  `RelationGraphPayload`(`module/agent/render`)做结构校验/去重/裁剪(500 节点 / 300 边 / 60k 字符),
  `PythonAnalysisTool` 以 `relationGraph` 字段返回;前端按工具步骤自动渲染。
- 边界:`get_case_graph` 只覆盖预置 `rel_edge` 的案件对象关系;其他表不要硬套,统一走本契约。
- Python 代码可以直接用 `open` / `pathlib` 读写沙箱当前目录(关系图 HTML、CSV 报告等);
  生成的文件由 `collectGeneratedFiles` 自动收进产物栏。`zgraph.py` 只是关系图的便捷序列化入口。
- Python 代码不做内容拦截,拥有完整文件/进程/网络权限;只保留空代码校验、执行超时和输出截断。
  生产环境必须用容器/受限 OS 用户隔离,或只挂载当前案件目录。

**关键实现约束**:因为表格是裸 JSON 而非围栏,`utils/scanner.ts` 必须做**字符级花括号配平扫描**
(字符串/转义感知)并按载荷形态校验,不能只按围栏切分。流式期间的增量策略是
「已完成块冻结(尾部 8KB 窗口外)+ 只重扫尾部 + 尾部块按 key 复用对象」,
块 key 用 `kind:start`(内容只追加 → key 稳定,避免图表实例重建、表格分页被重置)。

改渲染契约(`appendRenderPrompt`)时必须同步改前端 `scanner.ts` 与对应块组件。

---

## 7. 数据清洗 / 治理(`module/dm`)

dm/ ├─ pre/ PreTask、PreDataListener、DateNumberConverter、Str2NullConverter ├─ clean/ │ ├─ DataCleaner(接口)、CleanResult、CleanCache、DirtyDataHandler、StrategyType │ ├─ impl/cleaner/ 各数据源清洗器(Call/Trans/Track/External/...) │ ├─ impl/loader/ 数据装载器 │ └─ func/ 可复用清洗函数:FunAbs/FunRadix/FunReplace/FunTime/FunMultiplier/... ├─ ai/ 非表格文件的 Tika 抽样本 + 大模型识别 │ (FileSampleExtractor / FileRecognitionService / FileAiProfileService) └─ mapper/ CleanErrorLogMapper、DmMapper、PersonRelEdgeMapper、EdgeConfMapper、

       FileInfoMapper、FileAiProfileMapper

- 新增一种数据源导入 = 新增一对 `Loader` + `Cleaner`(命名对齐 `XxxDataLoader` / `XxxDataCleaner`)
- 清洗错误必须落 `CleanErrorLog`,不要静默吞掉
- 可复用变换优先写成 `func/Fun*` 而不是在 Cleaner 里硬编码
- **非 xls / xlsx / csv 的文件不落盘**:只登记 `file_info`(`FILE_UNSUPPORTED_FAIL`)+
  `file_ai_profile`(Tika 文本样本 + 大模型识别的分类/摘要/关键词,供后续数据分析工具按 `category` 分流)。
  识别链路 3 路并发、其余排队(`zsjz.file-ai.*` 可调),**全程 fail-open** ——
  抽样本失败/模型报错只落 SKIP/FAIL,绝不能让上传接口失败。抽样本必须在**请求线程内**做
  (multipart 临时文件在请求结束被清理)。详见 `ai-server/src/main/java/com/zsjz/ai/module/dm/ai/`
- **`file_ai_profile` 带 `caseId`(绑定到案件上)**:建档时从 `CaseContextHolder` 读一次,
  写进档案,同时把同一个值传给 `FileRecognitionService#submit` —— 分两次读万一中间上下文变了,
  会落出「档案说 A 案、识别写回 B 案」的脏数据。**查询不按 caseId 过滤**:
  案件范围由 `CaseRoutingDataSource` 按上下文自动限定,再叠一层只会制造「两边不一致就查不到」的假故障。
- **改 `file_ai_profile` 的列要动 4 处**:实体 `FileAiProfile`、`CaseDataSourceRegistry#AI_PROFILE_DDL`(新库)、
  `CaseDataSourceRegistry#AI_PROFILE_MIGRATIONS`(老库补列)、`sql/case_table_1.sql`。
  ★ **`CREATE TABLE IF NOT EXISTS` 对已存在的表是空操作** —— 老案件库里表已建好,
  光改建表语句**永远加不上新列**,表现是「新环境好好的,老案件一识别就报 Column not found」。
  所以新列必须同时写进建表语句和补列清单。`FileAiProfileSchemaTest` 会按生产顺序跑
  DDL + 补列并比对实体注解,漏改一处就红;另有 `legacyTableGetsCaseIdColumn` 专门模拟
  「已有旧版表的老库」验证补列路径。
- **AI 识别只认文本类文件(后缀白名单)**:唯一事实来源是
  `FileTypeConstants.AI_RECOGNIZABLE_SUFFIXES`,判定走 `FileTypeConstants.isAiRecognizable(fileType)`。
  白名单 ≈ pdf / doc / docx / ppt / pptx / rtf / odt / ods / odp / wps / wpt / dps / dpt / eml /
  txt / text / md / markdown / log / xml / json / html / htm / sql / tsv / yaml / yml / properties / ini / conf / cfg。
  压缩包、图片、音视频、可执行文件、数据库文件、**无后缀文件(`fileType = "unknown"`)一律不识别**。
  ★ 三条硬约定:**用白名单不用黑名单**(后缀无穷无尽,黑名单漏一个 = 默认识别,白名单漏一个只是
  「该识别的没识别」,代价可控);**`csv / xls / xlsx` 绝不加进白名单**(它们走表格解析流水线,
  根本到不了这条路);**守卫放在 `FileAiProfileService#register` 入口**,不是调用方 `DmService` ——
  绕过是静默的(只是多花钱、识别不出东西),不报错就发现不了,只有放在唯一入口才拦得住后续新增的调用点。
  加后缀时同步改 `FileTypeConstantsTest`(`whitelistEntriesAreNormalized` 会拦住「大写」和「带点号」的条目)
- 同一批档案还给 AI 用:`file` 工具组(`FileAnalysisTool`)提供
  `list_file_profiles`(清单检索)/ `stat_file_profiles_by_category`(分类统计)/
  `get_file_sample`(读某份材料的正文样本,≤4000 字)。
  ★ 三条硬约定:**正文绝不进列表**(单条样本 4000 字,50 行就是 20 万字,会冲爆上下文,
  正文只能按需单份取);**命中超 5000 条报错而非截断**(截断会让模型以为材料就这么多);
  **分类/状态认不出必须报错**(`FileCategoryEnum.parse` 认不出会落 `OTHER`,
  直接用它会让「过滤笔录」静默变成「过滤其他」)。

---

## 8. 前端约定

目录按业务域划分,与后端 `<domain>` 基本对齐:

ai-frontend/src/ ├─ core/ 脚手架通用层:components/、layouts/、api/、hooks/、store/、router ├─ ai/ AI 数据分析应用(api/、utils/、store/、styles/、components/、views/) ├─ case/ 案件:数据导入/清洗/治理/人物画像/线索推送 ├─ call/ 话单分析(night、continuous、sensitive...) ├─ trans/ 资金分析 ├─ track/ 轨迹分析 ├─ person/ 人员 ├─ plat/ 平台/模板 ├─ dm/ 清洗类型定义 └─ graph/ 图谱(G6 编辑器、力导向布局 worker、资金流向图)


每个业务域内:`api/`(请求 + `types/dto.ts`、`types/query.ts`)、`views/`、`components/`、`hooks/`、`types/`。

### 规则
1. **优先复用 `src/core/components/*`**(BasicTable / BasicForm / BasicModal / Description / AnalysisPagination 等),不要新造轮子。
2. 组件用 `<script setup lang="ts">`,`defineProps` / `defineEmits` 显式类型化。
3. 新增接口先写 `src/<domain>/api/types/{dto,query}.ts` 的 TS 类型,**与后端 DTO 字段保持一致**(改后端字段时同步改这里)。
4. 样式:UnoCSS 原子类 + Less(组件内 `<style lang="less" scoped>`)。
5. 只能用 pnpm。

### ⚠️ 新增页面 / 菜单的四个坑

1. **菜单图标必须进 UnoCSS 白名单**:`uno.config.ts` 的 `content.pipeline.include` 只扫
   `**/*.{vue,tsx,ts}`,**`menu.json` 不在扫描范围内**;而 `Icon` 组件是运行时拼
   `i-<collection>:<name>` 类名的。所以在 `menu.json` 里配的图标不会生成 CSS。
   新增图标时同步把 `i-` 前缀的完整类名加入 `uno.config.ts` 的 `safelist`
   (`menu.json` 里可直接写 `"icon": "i-mdi:history"`,Icon 见到 `i-` 前缀会原样使用)。
2. **路由建议走显式映射**:`src/core/router/helper/routeHelper.ts` 的 `explicitDynamicViewMap`
   加一条 `'/name/index': () => import('@/<domain>/views/<name>/index.vue')`。
   默认的 `import.meta.glob('**/views/**')` 会命中 `node_modules` 里的同名 views。
3. **全高页面**:布局内容容器 `.jeesite-layout-content` 有确定像素高度,页面根用
   `height: 100%` 即可撑满;要全出血再配 `width: calc(100% + 24px); margin: 0 -12px;`
   (容器 `padding: 12px 12px 0`)。
4. **两套响应形态**:`module/agent` 的 `/chat/**`(含 `/chat/results/**`)是**裸返回**,
   `defHttp` 默认 transform 会把非 `code===200` 的结构当错误抛,所以必须传
   `{ isTransformResponse: false }`;`/models/**` 是 `Result<T>` 包装,用默认 transform。
   鉴权靠 **Sa-Token,token 走 `x-token` 请求头**(后端 `sa-token.is-read-cookie=false`,
   **仅 Header 模式**)。`defHttp` 的请求拦截器会自动注入;不走 `defHttp` 的场景
   (`fetch` / `EventSource`)必须手动带上 `'x-token': getToken()`。
   ⚠️ 原生 `EventSource` **无法自定义请求头**,SSE 一律用 `fetch` + `body.getReader()` 读增量。
   未登录时后端返回 **HTTP 200 + `body.code=401`**(不是 HTTP 401),前端据此跳登录页。

---

## 9. 常用命令

### 后端

bash

编译

mvn -pl ai-server -am clean compile

打包(跳过测试)

mvn -pl ai-server -am clean package -DskipTests

运行

mvn -pl ai-server spring-boot:run

只跑 ai-server 的测试

mvn -pl ai-server test

启动后:`http://localhost:8980`

### 前端

bash cd ai-frontend pnpm install # = pnpm bootstrap pnpm dev # 开发服务器 pnpm type:check # vue-tsc --noEmit pnpm lint:eslint pnpm lint:prettier pnpm lint:stylelint pnpm lint:all # 全量(含 install) pnpm build # 生产构建 pnpm preview:dist # 预览 :3100 ```

依赖服务

PostgreSQL(需装 pgvector 扩展)、Redis、Neo4j(按需)。


10. 硬性规则:Do / Don't

✅ Do

  • 新业务按 module/<domain>/{controller,service,mapper} + common/model/<domain>/{dto,entity,query,vo} 落位
  • 改 SQL 同步改 resources/mappers/**/*.xml
  • 改后端 DTO 字段 → 同步前端 src/<domain>/api/types/*.ts
  • 改表结构 → 补 sql/ 脚本 + table_info / table_field 元数据
  • 新增 Agent 工具 → 写清 @Tool(description=...) 与 @ToolParam,返回结构化 JSON + 中文说明
  • 大查询一律带 LIMIT / WHERE,分页返回
  • 提交前跑通后端 compile 与前端 type:check

❌ Don't

  • 不要动 ai-server/src/main/resources/app.yml(Solon 遗留,已失效)
  • 不要把密钥 / 真实库密码 / 内网地址硬编码进提交
  • 不要在 Java 里拼接 SQL 字符串(用 MyBatis XML 或 LambdaQueryWrapper)
  • 不要放宽 execute_sql 的只读白名单、行数上限、单元格截断
  • 不要让 render_chart 渲染关系图
  • 不要绕过 Sa-Token 的用户归属校验
  • 不要在仓库里存放原始敏感案情数据
  • 未经要求不要改写 prompts/AGENTS.md / QingJian/agent/AGENTS.md 的人格与输出格式
  • 不要用 npm / yarn 装前端依赖

11. 已知待清理项(改到就顺手修)

  1. common/config/Result.java 顶部有 import io.milvus.param.R; —— 未被使用且 pom 中无 milvus 依赖,属遗留脏引用,建议直接删除。
  2. Result 的 SUCCEED_CODE / FAILURE_CODE 是非 final 的 public static 字段,可被外部篡改,建议改 final 或换成常量/枚举。
  3. common/config/WebConfig.java 与 application.yaml 的 context-path: "!/js/a/" 写法源自 Solon 语法,在 Spring Boot 下语义可疑 —— 已实证并修复(2026-09-15): AbstractServletWebServerFactory.checkContextPath() 会拒绝不合法的 context path。 实测 new TomcatServletWebServerFactory().setContextPath(v)(Spring Boot 3.5.16): !/js/a/ → 抛 IllegalArgumentException;/js/a/ → 同样被拒(尾部斜杠非法);/js/a → 通过。 即原配置会让 ai-server 完全无法启动。已改为 context-path: /js/a, 与前端 ctxPath(/js) + adminPath(/a) 及 defHttp 约定一致。
  4. ai-server 未声明 @MapperScan,确认 mapper 是靠 @Mapper 注解还是 XML 绑定注册;新增 Mapper 时跟随现有写法。
  5. pom.xml 中 testcontainers 等依赖已声明但未见到对应测试,可评估是否裁剪。
  6. src/main/resources/mappers/**/*.xml 全是 com.qingjian.* 命名空间 —— 已修(2026-09-15): Java 侧 0 处引用 com.qingjian,但有 85 个 com.zsjz.* Mapper 接口与 85 个 XML 一一对应, 属包名迁移时漏改 XML,导致 MyBatis 启动即炸 (Failed to parse mapping resource: mappers/ai/SkillMapper.xml → 无法解析 resultType), ai-server 在本仓库根本无法启动。 处理:删除 mappers/ai/(8 个文件,QingJian 旧 AI 模块,现 AI 能力在 module/agent 用 BaseMapper); 其余 77 个文件、160 处 com.qingjian → com.zsjz.ai。 新增 / 迁移 Mapper XML 时务必确认 namespace 与 resultType 用的是 com.zsjz.ai.*。
  7. application.yaml 的 mybatis-plus.type-aliases-package: com.qingjian.ai.server.model.*.entity.* 仍指向不存在的包(当前无实际影响:XML 全用全限定名)。 若要启用别名,先确认 com.zsjz.ai.common.model.*.entity 下无重名简单类名,否则 MyBatis 会因别名冲突启动失败。
  8. AppLoadEndEventListener(CommandLineRunner)依赖平台库结构(table_info / table_field) 与客户端运行时资产(RocksDB 目录、基站库文件)。当前开发库 zsjz-ai 缺平台库结构 (平台表在 etl-2,两个库不重合),故裸跑仓库目录会在启动后置任务阶段失败: PSQLException: 关系 "table_info" 不存在。 完整本地运行需先补齐库结构与客户端资产(见 PathConst)。

12. 提交前检查清单

  • 后端 mvn -pl ai-server -am clean compile 通过
  • 前端 pnpm type:check + pnpm lint:eslint 无错
  • 接口字段变更 → 后端 DTO/VO 与前端 TS 类型同步
  • 表结构变更 → sql/ 补脚本 + 元数据三表同步
  • 新增/修改 Agent 工具 → description 更新,必要时同步提示词
  • 用户级资源接口 → 带 StpUtil.getLoginIdAsLong() 归属校验
  • 无密钥 / 密码 / 敏感数据入库
  • 中文注释齐全,无调试 System.out.println 残留