本文引用的文件
本文聚焦 Agent 子系统中与数据库直接相关的四类实体:
这些表共同支撑以下上层功能:
本仓库采用 Java + MyBatis-Plus + PostgreSQL(主库)+ DuckDB(从库)架构。Agent 相关数据库定义集中在 sql/ 目录下,Java 实体类位于 ai-server/src/main/java/com/zsjz/ai/module/agent/...,Insight 相关 Mapper XML 位于 resources/mappers/insight/。
graph TB
subgraph "PostgreSQL 主库"
agent["agent<br/>专家配置"]
agent_tool["agent_tool<br/>工具清单"]
chat_attachment["chat_attachment<br/>聊天附件"]
insight_session["agent_insight_session<br/>Insight 会话"]
insight_message["agent_insight_message<br/>Insight 消息"]
end
subgraph "文件系统"
file_path["原始文件路径<br/>file_path / sidecar_path"]
py_files["Python 输出图片<br/>/py/files/**"]
rag_vec["向量分块表<br/>chat_att_vec_{caseId}_d{dims}"]
end
subgraph "DuckDB 从库"
duckdb["工作空间 DuckDB<br/>execute_sql 只读"]
end
agent --> agent_tool
chat_attachment --> file_path
chat_attachment --> rag_vec
insight_session --> insight_message
insight_message --> duckdb
图表来源
章节来源
| 物理表 | Java 实体 | 主键 | 主要归属字段 | JSON/文本字段 | 状态字段 | 主要用途 |
|---|---|---|---|---|---|---|
agent |
无单独新实体,沿用已有 agent 表 |
row_id |
user_id |
skills_allow_json、tools_allow_json、tool_packs_json |
无新增业务状态列 | 专家配置、内置标记、工具/技能白名单 |
agent_tool |
AgentTool |
id |
无业务外键 | parameters(JSONB) |
status |
工具注册、分组、Schema、默认启用 |
chat_attachment |
ChatAttachment |
id |
user_id、case_id、session_id |
inline_text(TEXT)、衍生路径字段 |
index_status、status |
附件三路处理元数据 |
agent_insight_session |
AgentInsightSession |
id |
case_id |
context(JSONB)、sys_prompt(TEXT) |
status |
研判会话上下文、提示词快照、水位 |
agent_insight_message |
AgentInsightMessage |
id |
session_id、冗余 case_id |
metadata、tool_events、output_json(JSONB) |
status |
研判消息、工具调用明细、结构化产物 |
章节来源
下图展示 Agent 专家、工具、聊天附件与 Insight 数据模型之间的关联方式。其中 agent 与 agent_tool 之间不是强外键关系,而是通过“工具组白名单”和“工具包 JSON 数组”形成松耦合多对多;chat_attachment 通过 link_message_id 弱关联消息;agent_insight_* 两张表通过外键级联删除。
erDiagram
AGENT {
bigint row_id PK
bigint user_id
smallint is_builtin
text skills_allow_json
text tools_allow_json
text tool_packs_json
}
AGENT_TOOL {
bigint id PK
varchar tool_name UK
varchar tool_class
varchar tool_method
varchar group_code
varchar group_label
text group_description
integer group_sort
boolean default_active
text description
jsonb parameters
boolean read_only
varchar status
timestamp create_at
timestamp update_at
}
CHAT_ATTACHMENT {
bigint id PK
bigint user_id
bigint case_id
bigint session_id
varchar file_name
varchar file_path
varchar sidecar_path
varchar mime
varchar kind
bigint size_bytes
integer char_count
integer row_count
integer truncated
text inline_text
integer index_blocks
varchar index_status
varchar status
bigint link_message_id
varchar fail_reason
timestamp create_time
timestamp update_time
}
INSIGHT_SESSION {
bigint id PK
bigint case_id
varchar biz_type
varchar scope
bigint agent_row_id
bigint model_id
varchar title
jsonb context
varchar context_hash
text sys_prompt
int message_count
bigint last_seq
bigint total_tokens
timestamp last_message_at
boolean pinned
varchar status
timestamp create_at
timestamp update_at
}
INSIGHT_MESSAGE {
bigint id PK
bigint session_id FK
bigint case_id
bigint seq
varchar role
text content
varchar content_type
varchar message_type
jsonb metadata
jsonb tool_events
jsonb output_json
int token_count
bigint reply_to_message_id
boolean starred
varchar status
timestamp create_at
}
AGENT ||--o{ AGENT_TOOL : "按工具组与工具包间接引用"
CHAT_ATTACHMENT ||--o{ INSIGHT_MESSAGE : "link_message_id 弱关联"
INSIGHT_SESSION ||--o{ INSIGHT_MESSAGE : "外键级联删除"
图表来源
agent 表在现有基础上增加了用户隔离、内置标记以及工具/技能白名单字段。
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
row_id |
BIGINT | 是 | 主键,PostgreSQL identity 自增;存量默认专家为 1 |
user_id |
BIGINT | 否 | 创建者 ID;内置专家统一为平台管理员 ID 1 |
is_builtin |
SMALLINT | 是 | 1=内置,全局可见且不可编辑删除;0=用户自建 |
skills_allow_json |
TEXT | 否 | 技能名白名单 JSON 数组 |
tools_allow_json |
TEXT | 否 | 工具组编码白名单 JSON 数组 |
tool_packs_json |
TEXT | 否 | 工具包 ID 白名单 JSON 数组(见 Agent 数据模型文档) |
业务规则:
is_builtin=1、user_id=1,全局可见、不可编辑、不可删除。is_builtin=0,仅创建者可见、可编辑、可删除。row_id=1 非内置行,并补齐主键约束。章节来源
agent_tool 是代码镜像表,应用启动时反射扫描 module/agent/tools 下的 @Tool 方法,生成工具名、类、方法、分组、参数 Schema、默认启用等元数据,并按工具名 upsert。
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
id |
BIGINT | 是 | 雪花 ID,应用侧生成 |
tool_name |
VARCHAR(128) | 是 | 工具名,全表唯一,模型调用标识 |
tool_class |
VARCHAR(255) | 否 | 声明工具方法的类名 |
tool_method |
VARCHAR(128) | 否 | 方法名 |
group_code |
VARCHAR(32) | 否 | 工具组编码:call/trans/track/graph/person/file/base |
group_label |
VARCHAR(64) | 否 | 工具组中文名 |
group_description |
TEXT | 否 | 写给模型的分组描述 |
group_sort |
INTEGER | 否 | 分组排序位 |
default_active |
BOOLEAN | 否 | 新会话默认装备 |
description |
TEXT | 否 | 工具描述 |
parameters |
JSONB | 否 | 入参 JSON Schema |
read_only |
BOOLEAN | 否 | 是否只读工具 |
status |
VARCHAR(16) | 否 | ACTIVE 或 DELETED |
create_at |
TIMESTAMP | 否 | 创建时间 |
update_at |
TIMESTAMP | 否 | 更新时间 |
约束与索引:
id。uk_agent_tool_name(tool_name)。Java 映射:
AgentTool 使用 MyBatis-Plus ASSIGN_ID 作为主键;parameters 通过 JsonbTypeHandler 以 JSONB 形式读写;status 对应 ACTIVE/DELETED,删除工具不删行,只标记为已删除。章节来源
chat_attachment 记录一次输入框上传的文件,承担附件问答三条路径的统一登记点。
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
id |
BIGINT | 是 | 主键 |
user_id |
BIGINT | 是 | 归属用户,加载时校验 |
case_id |
BIGINT | 是 | 归属案件,加载时校验 |
session_id |
BIGINT | 是 | 归属会话,加载校验与 RAG 过滤 |
file_name |
VARCHAR(500) | 是 | 原始文件名 |
file_path |
VARCHAR(1000) | 是 | 原件落盘路径 |
sidecar_path |
VARCHAR(1000) | 否 | 衍生全文路径,如 .txt 或 xlsx→csv |
mime |
VARCHAR(100) | 否 | Tika 探测 MIME |
kind |
VARCHAR(20) | 是 | DOCUMENT / TABLE / UNSUPPORTED |
size_bytes |
BIGINT | 否 | 文件大小 |
char_count |
INTEGER | 否 | 提取文本字符数 |
row_count |
INTEGER | 否 | 数据行数,不含表头 |
truncated |
INTEGER | 否 | 1=内容已截断 |
inline_text |
TEXT | 否 | 路径 A 的小文本内联全文 |
index_blocks |
INTEGER | 否 | 已向量化块数 |
index_status |
VARCHAR(20) | 否 | NONE / READY / FAILED |
status |
VARCHAR(20) | 是 | READY / FAILED |
link_message_id |
BIGINT | 否 | 发出后回填的消息 ID |
fail_reason |
VARCHAR(1000) | 否 | 失败原因 |
create_time |
TIMESTAMP | 否 | 创建时间 |
update_time |
TIMESTAMP | 否 | 更新时间 |
三路处理逻辑:
inline_text 直接进消息。execute_python 读取 file_path 或 sidecar_path。chat_att_vec_{caseId}_d{dims},并通过 index_blocks、index_status 跟踪索引进度。索引:
idx_chat_att_session(session_id):会话维度查找。idx_chat_att_status(status, link_message_id):孤儿附件清理与状态查询。章节来源
Insight 会话表与通用 Agent 会话表物理隔离,所有查询强制携带 case_id。
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
id |
BIGINT | 是 | 应用侧生成,随机非单调 |
case_id |
BIGINT | 是 | 案件级硬隔离边界 |
biz_type |
VARCHAR(32) | 是 | 研判场景,本期恒 GRAPH_RELATION |
scope |
VARCHAR(16) | 是 | BATCH 或 PAIR |
agent_row_id |
BIGINT | 否 | 使用的专家配置行 |
model_id |
BIGINT | 是 | 会话默认模型 |
title |
VARCHAR(128) | 否 | 会话标题 |
context |
JSONB | 是 | 查询条件与结果快照 |
context_hash |
VARCHAR(64) | 是 | context 的 sha256 |
sys_prompt |
TEXT | 是 | 实际系统提示词,会话内不可变 |
message_count |
INT | 是 | 消息条数缓存 |
last_seq |
BIGINT | 是 | 会话内消息序号水位 |
total_tokens |
BIGINT | 是 | 累计 Token 数 |
last_message_at |
TIMESTAMP | 否 | 最后活动时间 |
pinned |
BOOLEAN | 是 | 是否置顶 |
status |
VARCHAR(16) | 是 | ACTIVE / STREAMING / ARCHIVED |
create_at |
TIMESTAMP | 是 | 创建时间 |
update_at |
TIMESTAMP | 是 | 更新时间 |
关键约束:
idx_ais_case_list(case_id, biz_type, last_message_at DESC)。idx_ais_ctx_hash(case_id, context_hash)。status=STREAMING 配合 Mapper 中的 acquireStreamLock、releaseStreamLock。章节来源
Insight 消息表冗余 case_id,保证越权查询在 SQL 层面无法绕过案件过滤。
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
id |
BIGINT | 是 | 主键 |
session_id |
BIGINT | 是 | 所属 Insight 会话 |
case_id |
BIGINT | 是 | 冗余案件 ID |
seq |
BIGINT | 是 | 会话内递增序号 |
role |
VARCHAR(16) | 是 | user / assistant / system |
content |
TEXT | 否 | 正文 |
content_type |
VARCHAR(16) | 是 | text / insight |
message_type |
VARCHAR(16) | 是 | chat / first_round / followup |
metadata |
JSONB | 否 | 轻量元数据 |
tool_events |
JSONB | 否 | 工具调用明细 |
output_json |
JSONB | 否 | 结构化产物 |
token_count |
INT | 是 | Token 计数 |
reply_to_message_id |
BIGINT | 否 | 追问指向的首轮消息 |
starred |
BOOLEAN | 是 | 是否收藏 |
status |
VARCHAR(16) | 是 | DONE / INTERRUPTED |
create_at |
TIMESTAMP | 是 | 创建时间 |
关键约束:
uk_aim_session_seq(session_id, seq)。fk_aim_session(session_id) REFERENCES agent_insight_session(id) ON DELETE CASCADE。idx_aim_output(case_id, create_at DESC) WHERE output_json IS NOT NULL。章节来源
专家最终可用工具来自两部分:
tools_allow_json 中的工具组编码;tool_packs_json 中的工具包,再由工具包解析出具体 tool_name。典型流程:
参考实现位置:
flowchart TD
Start["上传附件"] --> Detect["探测 MIME 与规模"]
Detect --> Kind{"kind 判定"}
Kind -->|DOCUMENT 小| Inline["写入 inline_text"]
Kind -->|TABLE 小| Inline
Kind -->|TABLE 大| PythonPath["记录 file_path/sidecar_path<br/>等待 execute_python 读取"]
Kind -->|DOCUMENT 大| VectorPath["写入 sidecar_path<br/>分块向量化"]
Inline --> Ready["status=READY"]
PythonPath --> Ready
VectorPath --> Indexing["更新 index_blocks/index_status"]
Indexing --> Ready
Ready --> LinkMsg["发出消息后回填 link_message_id"]
LinkMsg --> End["附件完成生命周期"]
图表来源
Insight 写入要求:
case_id;INSERT ... SELECT,源表带 case_id 归属校验;seq 通过 UPDATE ... RETURNING last_seq 原子分配;列表分页严格按 seq DESC 排序。
sequenceDiagram
participant Client as "客户端"
participant Service as "InsightService"
participant SessionMapper as "AgentInsightSessionMapper"
participant MessageMapper as "AgentInsightMessageMapper"
participant DB as "PostgreSQL"
Client->>Service: "发起研判"
Service->>SessionMapper: "nextSeq(sessionId)"
SessionMapper->>DB: "UPDATE last_seq RETURNING last_seq"
DB-->>SessionMapper: "返回 seq"
Service->>MessageMapper: "insertMessage(message)"
MessageMapper->>DB: "INSERT ... SELECT FROM agent_insight_session WHERE case_id=? AND id=?"
DB-->>MessageMapper: "影响行数 1 或 0"
MessageMapper->>SessionMapper: "bumpAfterMessage(sessionId)"
SessionMapper->>DB: "更新 message_count、last_message_at"
Service-->>Client: "返回消息或错误"
图表来源
以下为意图说明,不直接给出完整语句:
case_id 和 biz_type 筛选,按 pinned DESC, last_message_at DESC 排序。session_id 与 case_id 双条件,按 seq DESC 分页。context、context_hash,不查 sys_prompt。idx_aim_output 部分索引,只取 output_json。session_id 与 user_id/case_id 三重归属校验。| 阶段 | 行为 | 关键字段 |
|---|---|---|
| 上传 | 登记 file_path、mime、kind、size_bytes |
kind、status |
| 小文本内联 | 写入 inline_text |
inline_text、char_count |
| 大表格 Python 直读 | 不写 inline_text,留给 execute_python 读文件 |
file_path、sidecar_path |
| 大文档向量化 | 生成 sidecar 全文,写入向量分块表 | sidecar_path、index_blocks、index_status |
| 发送成功 | 回填 link_message_id |
link_message_id |
| 失败 | 保留 fail_reason、status=FAILED |
fail_reason、status |
| 清理 | 按 status 与 link_message_id 清理孤儿附件 |
idx_chat_att_status |
风险点:
inline_text 应限制大小,防止消息体积膨胀。chat_att_vec_{caseId}_d{dims} 需要随会话或案件生命周期清理。章节来源
| 阶段 | 行为 | 关键字段 |
|---|---|---|
| 创建会话 | 写入 context、context_hash、sys_prompt、last_seq=0 |
context、context_hash、last_seq |
| 开始流式分析 | 抢占 status=STREAMING |
status |
| 写入消息 | 原子分配 seq,更新 message_count、last_message_at |
seq、message_count |
| 首轮分析 | 写入 output_json |
output_json |
| 用户中止 | 设置 status=INTERRUPTED |
status |
| 结束分析 | 恢复 status=ACTIVE,或归档为 ARCHIVED |
status |
| 删除会话 | 级联删除消息 | fk_aim_session |
注意事项:
context 可能较大,列表接口应只查 context_hash,详情再拉 context。sys_prompt 是运维追溯字段,不应通过普通接口下发。tool_events 可达数百 KB,列表查询必须排除,仅追踪详情按需读取。章节来源
| 对象 | 生命周期行为 |
|---|---|
| 工具 | 代码上线时反射生成;代码下线时置 status=DELETED,不删行;历史可追溯 |
| 工具包 | 保存时校验工具名存在;删除时摘除所有方案绑定并驱逐实例池 |
| 专家 | 内置专家全局可见不可改;自建专家仅创建者可管理;改配置后驱逐池化实例 |
| 工具装配 | 启动或配置变更后重新解析工具组与工具包,构建工具级白名单 |
章节来源
| 表 | 索引 | 目的 |
|---|---|---|
agent |
idx_agent_user_id(user_id) |
用户维度专家查询 |
agent_tool |
uk_agent_tool_name(tool_name) |
工具名唯一性与装配查找 |
chat_attachment |
idx_chat_att_session(session_id) |
会话附件快速定位 |
chat_attachment |
idx_chat_att_status(status, link_message_id) |
孤儿清理与状态扫描 |
agent_insight_session |
idx_ais_case_list(case_id, biz_type, last_message_at DESC) |
案件列表分页 |
agent_insight_session |
idx_ais_ctx_hash(case_id, context_hash) |
同条件复用与去重 |
agent_insight_message |
idx_aim_output(case_id, create_at DESC) WHERE output_json IS NOT NULL |
线索聚合部分索引 |
context、sys_prompt;tool_events、output_json;inline_text 仅用于小文本路径;章节来源
现象:selectById 报找到多行。
原因:存量显式插入的 row_id=1 未走 identity 序列,且表缺少主键约束。
处理:脚本会删除非内置重复行、对齐序列、补加主键。
章节来源
现象:并发写入后出现相同 seq。
防护:
UPDATE last_seq + 1 RETURNING last_seq;uk_aim_session_seq(session_id, seq) 做第二道保险;insight_agent_tables_align.sql 补齐约束。章节来源
现象:会话状态卡在 STREAMING,后续请求无法抢占。
原因:流式结束或异常后未释放锁。
处理:确保 finally 分支执行 releaseStreamLock,将 status 重置为 ACTIVE。
章节来源
现象:消息已发送但附件未关联消息,或消息删除后残留附件。
处理:
link_message_id;status 与 link_message_id 扫描,清理未关联或超出生命周期的附件;chat_att_vec_{caseId}_d{dims} 向量分块表。章节来源
现象:消息写入到不属于当前案件的会话。
防护:
insertMessage 使用 INSERT ... SELECT FROM agent_insight_session WHERE id=? AND case_id=?;session_id + case_id,忽略外部排序参数。章节来源
这五张表构成了 Agent 子系统的核心数据骨架:
agent 扩展字段提供专家的用户隔离与工具/技能白名单;agent_tool 将代码中的工具能力稳定映射到数据库,支持工具组与工具包装配;chat_attachment 统一管理附件的三类处理路径,连接文件、Python 执行器与 RAG 向量索引;agent_insight_session 与 agent_insight_message 提供独立的研判会话与消息存储,具备案件级硬隔离、会话内原子序号和结构化产物能力。在实际使用中,应避免把大附件、大 JSON 和长文本混放在同一查询中;对聊天附件、向量分块表和 Insight 消息,都应建立明确的清理策略,以保证主库容量、查询性能和数据安全。