Agent、专家、工具与聊天附件表.md 29 KB

Agent、专家、工具与聊天附件表

本文引用的文件

  • agent_expert.sql
  • agent_tool.sql
  • chat_attachment.sql
  • insight_agent_tables.sql
  • insight_agent_tables_align.sql
  • AgentTool.java
  • ChatAttachment.java
  • AgentInsightSession.java
  • AgentInsightMessage.java
  • AgentInsightSessionMapper.xml
  • AgentInsightMessageMapper.xml
  • agent-data-model.md

目录

  1. 引言
  2. 项目结构与范围
  3. 核心数据模型总览
  4. 架构关系图
  5. 表级详细设计
  6. 典型插入与查询示例
  7. 生命周期管理与清理策略
  8. 性能与索引设计
  9. 故障排查要点
  10. 结论

引言

本文聚焦 Agent 子系统中与数据库直接相关的四类实体:

  • Agent 专家(agent 表扩展):承载专家配置、内置标记、用户隔离以及允许的工具/技能白名单。
  • Agent 工具清单(agent_tool):由代码反射扫描生成的工具元数据,是模型调用工具的权威清单。
  • 聊天附件(chat_attachment):一次对话上传文件的元数据,支撑小文本内联、大表格 Python 直读、大文档 RAG 向量化三条路径。
  • Insight 研判会话与消息(agent_insight_session、agent_insight_message):独立于通用 Agent 对话的研判业务存储,具备案件级硬隔离、会话内原子序号和结构化产物能力。

这些表共同支撑以下上层功能:

  • Agent 对话中的专家选择、工具装配与权限控制;
  • RAG Schema 与向量检索元数据;
  • Workspace Catalog 中可查表的元数据描述;
  • Artifact 与 Python 执行器通过文件路径读取工作空间产出;
  • Insight 分析结果的结构化归档与线索聚合。

项目结构与范围

本仓库采用 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

图表来源

  • agent_expert.sql:1-47
  • agent_tool.sql:1-52
  • chat_attachment.sql:1-39
  • insight_agent_tables.sql:1-107

章节来源

  • AI_AGENT.md:1-200

核心数据模型总览

物理表 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_expert.sql:1-47
  • agent_tool.sql:1-52
  • chat_attachment.sql:1-39
  • insight_agent_tables.sql:1-107
  • AgentTool.java:1-80
  • ChatAttachment.java:1-105
  • AgentInsightSession.java:1-90
  • AgentInsightMessage.java:1-85

架构关系图

下图展示 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_expert.sql:1-47
  • agent_tool.sql:1-52
  • chat_attachment.sql:1-39
  • insight_agent_tables.sql:1-107
  • agent-data-model.md:1-85

表级详细设计

专家表扩展:agent

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_expert.sql:1-47
  • agent-data-model.md:1-85

工具清单表:agent_tool

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,删除工具不删行,只标记为已删除。

章节来源

  • agent_tool.sql:1-52
  • AgentTool.java:1-80

聊天附件表:chat_attachment

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 否 更新时间

三路处理逻辑:

  • 路径 A:小文档或小表格 → inline_text 直接进消息。
  • 路径 B:大表格 → 不物化全文,Agent 用 execute_python 读取 file_path 或 sidecar_path。
  • 路径 C:大文档 → sidecar 全文 + 分块向量化,写入 chat_att_vec_{caseId}_d{dims},并通过 index_blocks、index_status 跟踪索引进度。

索引:

  • idx_chat_att_session(session_id):会话维度查找。
  • idx_chat_att_status(status, link_message_id):孤儿附件清理与状态查询。

章节来源

  • chat_attachment.sql:1-39
  • ChatAttachment.java:1-105

Insight 会话表:agent_insight_session

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_agent_tables.sql:1-107
  • AgentInsightSession.java:1-90
  • AgentInsightSessionMapper.xml:1-89

Insight 消息表:agent_insight_message

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。

章节来源

  • insight_agent_tables.sql:1-107
  • insight_agent_tables_align.sql:1-88
  • AgentInsightMessage.java:1-85
  • AgentInsightMessageMapper.xml:1-83

典型插入与查询示例

专家与工具装配

专家最终可用工具来自两部分:

  1. tools_allow_json 中的工具组编码;
  2. tool_packs_json 中的工具包,再由工具包解析出具体 tool_name。

典型流程:

  • 保存专家时校验所选工具包是否存在且属于当前用户或内置;
  • 装配对话时解析工具包,合并工具组白名单,得到工具级白名单;
  • 白名单外的业务工具被真实注销;
  • 改专家配置后驱逐该专家实例池,避免旧工具面继续生效。

参考实现位置:

  • agent-data-model.md:1-85

聊天附件三路处理

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["附件完成生命周期"]

图表来源

  • chat_attachment.sql:1-39
  • ChatAttachment.java:1-105

Insight 会话与消息写入

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: "返回消息或错误"
    

图表来源

  • AgentInsightSessionMapper.xml:1-89
  • AgentInsightMessageMapper.xml:1-83
  • insight_agent_tables.sql:1-107

典型 SQL 意图示例

以下为意图说明,不直接给出完整语句:

  • 查询某案件下某个 Insight 会话的列表:按 case_id 和 biz_type 筛选,按 pinned DESC, last_message_at DESC 排序。
  • 查询某 Insight 会话的消息分页:按 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

风险点:

  • 大附件优先走文件路径而非数据库 TEXT,避免把二进制或超大文本塞进主库。
  • inline_text 应限制大小,防止消息体积膨胀。
  • 向量分块表 chat_att_vec_{caseId}_d{dims} 需要随会话或案件生命周期清理。

章节来源

  • chat_attachment.sql:1-39
  • ChatAttachment.java:1-105

Insight 数据生命周期

阶段 行为 关键字段
创建会话 写入 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,列表查询必须排除,仅追踪详情按需读取。

章节来源

  • insight_agent_tables.sql:1-107
  • AgentInsightSessionMapper.xml:1-89
  • AgentInsightMessageMapper.xml:1-83

专家与工具生命周期

对象 生命周期行为
工具 代码上线时反射生成;代码下线时置 status=DELETED,不删行;历史可追溯
工具包 保存时校验工具名存在;删除时摘除所有方案绑定并驱逐实例池
专家 内置专家全局可见不可改;自建专家仅创建者可管理;改配置后驱逐池化实例
工具装配 启动或配置变更后重新解析工具组与工具包,构建工具级白名单

章节来源

  • agent_tool.sql:1-52
  • agent-data-model.md:1-85

性能与索引设计

索引策略

表 索引 目的
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 线索聚合部分索引

大字段访问纪律

  • Insight 会话列表不查 context、sys_prompt;
  • Insight 消息列表不查 tool_events、output_json;
  • 聊天附件 inline_text 仅用于小文本路径;
  • 向量检索元数据与文件路径分离,避免主库负载过大。

章节来源

  • agent_expert.sql:1-47
  • agent_tool.sql:1-52
  • chat_attachment.sql:1-39
  • insight_agent_tables.sql:1-107
  • AgentInsightSessionMapper.xml:1-89
  • AgentInsightMessageMapper.xml:1-83

故障排查要点

专家主键重复

现象:selectById 报找到多行。
原因:存量显式插入的 row_id=1 未走 identity 序列,且表缺少主键约束。
处理:脚本会删除非内置重复行、对齐序列、补加主键。

章节来源

  • agent_expert.sql:1-47

Insight 消息序号重复

现象:并发写入后出现相同 seq。
防护:

  • 应用层使用 UPDATE last_seq + 1 RETURNING last_seq;
  • 数据库层 uk_aim_session_seq(session_id, seq) 做第二道保险;
  • 旧库需执行 insight_agent_tables_align.sql 补齐约束。

章节来源

  • insight_agent_tables.sql:1-107
  • insight_agent_tables_align.sql:1-88

Insight 会话永久处于 STREAMING

现象:会话状态卡在 STREAMING,后续请求无法抢占。
原因:流式结束或异常后未释放锁。
处理:确保 finally 分支执行 releaseStreamLock,将 status 重置为 ACTIVE。

章节来源

  • AgentInsightSessionMapper.xml:1-89

聊天附件孤儿文件

现象:消息已发送但附件未关联消息,或消息删除后残留附件。
处理:

  • 成功发送后回填 link_message_id;
  • 清理任务按 status 与 link_message_id 扫描,清理未关联或超出生命周期的附件;
  • 同时清理 chat_att_vec_{caseId}_d{dims} 向量分块表。

章节来源

  • chat_attachment.sql:1-39
  • ChatAttachment.java:1-105

Insight 越权写入

现象:消息写入到不属于当前案件的会话。
防护:

  • insertMessage 使用 INSERT ... SELECT FROM agent_insight_session WHERE id=? AND case_id=?;
  • 归属不匹配时影响行数为 0,服务层抛 403;
  • 列表查询强制 session_id + case_id,忽略外部排序参数。

章节来源

  • AgentInsightMessageMapper.xml:1-83

结论

这五张表构成了 Agent 子系统的核心数据骨架:

  • agent 扩展字段提供专家的用户隔离与工具/技能白名单;
  • agent_tool 将代码中的工具能力稳定映射到数据库,支持工具组与工具包装配;
  • chat_attachment 统一管理附件的三类处理路径,连接文件、Python 执行器与 RAG 向量索引;
  • agent_insight_session 与 agent_insight_message 提供独立的研判会话与消息存储,具备案件级硬隔离、会话内原子序号和结构化产物能力。

在实际使用中,应避免把大附件、大 JSON 和长文本混放在同一查询中;对聊天附件、向量分块表和 Insight 消息,都应建立明确的清理策略,以保证主库容量、查询性能和数据安全。