40 张表:一个 Spring Boot 4 企业级 Agent 平台的数据模型
用户在企业微信里发一句"帮我看下这个月的报销",从点发送到看到答案,中间大概十几个动作:渠道收消息、映射身份、建会话、判断该找哪个专家、拼上下文、调模型、跑工具、过权限、必要时等人确认、写结果、记用量、留审计。
每个动作都要有地方落。BizBuddy 的 ai_* 表一共 40 张,我按动作把它们分成四组,再加一组用来管演进。下面不贴 DDL,只讲每张表为什么存在。
一、会话不是一张表
光是"一次对话",就占了 5 张:ai_session、ai_message、ai_message_attachment、ai_session_resource、ai_tool_call_log。
最常见的做法是把消息和工具调用塞进一张表,省事。但这两类数据的读法完全不同:消息要按轮次顺序读,字段越少越快,因为它最终要拼成上下文喂给模型;工具调用要按时间、按人、按工具去查,还得存入参出参的摘要,是给人做审计用的。混在一起,要么模型看到一堆自己不需要的字段白烧 token,要么审计时发现关键信息没存。
附件单独一张,因为一条消息可以带多个文件,而且附件有自己的生命周期——压缩、清理、权限校验都和消息正文不同步。
ai_session_resource 存的是会话绑定的知识库、技能、文件。它不属于任何一条消息,换一轮对话还要继续用,所以不能混进消息表。
会话表本身反而很薄:归属人、租户、状态、最后活跃时间。薄是有意的,因为它会被高频更新——每次交互都要刷活跃时间做 TTL 续期,还要抢一次互斥锁防止同一会话并发执行。把消息正文放在这张表上,等于让最热的写操作去碰最大的字段。
工具调用日志还要能串起来。一次请求可能连着调五六个工具,每个都要带上同一个追踪号,出问题时才能还原"模型先查了什么、看到什么、又决定了什么"。
二、智能体、工具、知识库,全是配置
这一组 22 张,占了一半还多。分两块看。
智能体与工具 18 张,从 ai_entry_agent、ai_expert_agent,到 ai_agent_tool、ai_tool、ai_skill、ai_subagent,再到 ai_scenario_pack 那四张。它们回答的是同一个问题:平台里的能力怎么配出来,而不是改代码改出来。
第一个设计是多对多。同一个查订单工具会被三个专家复用,如果挂在某一个专家下面,第二个专家要用就得复制一份,改一次要改三处。所以工具是独立的实体,关联靠中间表。
第二个是信任级别单独存,ai_agent_tool_trust。工具"能做什么"是能力,"允不允许写、要不要人工确认"是策略。能力跟着工具走,策略跟着客户、角色、环境变。写在一起,客户提一次要求就得改工具定义。
第三个是场景包。一套智能体加工具加技能加 MCP 连接,打包成一个包,客户现场导入就能跑。没有这四张表,实施人员要手工点几十次,还得保证顺序。
知识库四张是 ai_knowledge_base、ai_document、ai_chunk,加上前面提到的绑定关系。文档和分块必须分开,因为一份文档切几百块是常态,重切一次要能整体替换而不影响引用。
这几组里最容易混的是三对概念。入口智能体和专家智能体不是一回事:入口负责听懂意图、做路由和兜底,专家负责真正执行,两者生命周期和权限边界都不同。技能和工具也不是一回事:工具是可以被调用的接口,技能是一段提示词加若干资源文件,前者执行动作,后者改变模型怎么想。子智能体则更像一个可嵌入的执行单元,调用它的人看不到它内部的工具循环。
把这三对概念塞进一张表,字段会互相打架,最后只能靠一堆可空字段和类型标记来区分。拆开之后每张表都很窄,改一个概念不影响另一个。
三、三个容易漏的边界
路由 2 张:ai_route_run、ai_route_expert_call。路由是一次判定,判定就得能回放。客户问"为什么这句话找的是财务专家而不是人事",只能查这两张表。这里有个工程取舍:判定要求 200ms 内出结果,所以轨迹异步写,但决策结果同步落库,否则失败时连查的地方都没有。
权限 1 张:ai_permission_decision_log。每次放行或拒绝都要落一条。拦截只做在内存里,事后没人能证明当时为什么放行。无人值守场景默认拒绝、只放行白名单,本质上也是策略加判定,判定必须留下痕迹。
渠道 3 张:ai_channel、ai_channel_identity、ai_channel_thread。外部身份和内部用户不是一回事:同一个飞书 open_id 在不同租户下可能对应不同账号。渠道线程和平台会话也不是一对一:一个群聊里可以开多个会话,一个会话也能跨渠道接着聊。这三张表如果偷懒合成一张,后面每接一个渠道就要改表结构。
四、跑起来之后才需要的表
任务 2 张:ai_agent_task、ai_agent_task_run。任务定义调度规则,执行记录每一次结果。合成一张,重跑一次就把上次的证据覆盖了。
统计和观测 5 张:ai_usage_stat、ai_daily_digest、ai_trace、ai_safety_event、ai_sensitive_word。
用量必须单独聚合,会话表里查不出"这个月花了多少 token"。聚合要带维度——按模型、按专家、按租户、按天,四个维度叠加才能回答"哪个专家最烧钱"。日报要落库,因为它是一份可审计的产出,不是临时生成的一段话;它由定时任务在无人值守的情况下写入,所以还要受写工具白名单约束,默认拒绝、只放行这一个。追踪和会话分开,因为一次请求可能跨多个会话和多个工具。敏感词是配置,安全事件是记录,方向相反,不能放一张表。
五、这些表怎么演进
40 张表真正难的不是设计,是后面几年怎么改。
结构变更走 Flyway。V1 是 1.0.0 的冻结基线,之后只加 V2、V3,两个方言目录同步,靠 {vendor} 区分。PostgreSQL 和 MySQL 各一套栈,迁移历史各自独立,但内容必须等价,否则容器初始化的库和 Flyway 管理的库会分叉。
MySQL 的 DDL 不支持事务,所以增量脚本一律写成幂等——建索引先查 information_schema,用 prepare 加 execute 兜住重复执行。JSON 字段交给 Jackson 3 序列化,Long 统一转字符串,免得前端精度丢失。
顺序也有讲究。加字段可以随版本发,删字段要先停写、观察一个版本再删,改字段类型基本等于重建——所以设计阶段偷的懒,后面都要用停机窗口还。
表结构是这套系统里最难改的东西。它值得在设计阶段多花两天。
关于 BizBuddy
BizBuddy 是一个全量开源(MIT)的企业级智能体平台,Spring Boot 4.1.1 + AgentScope Java Harness,PostgreSQL 14 与 MySQL 8.0 双栈交付。上面这 40 张表的建表脚本、迁移基线和关联关系,仓库里都能直接看。