数据模型参考

本页不是 ER 图替代品，而是帮助读者快速建立“哪些对象是一组、哪些状态必须一起看”的模型地图。

当前主要模型簇

模型簇	关键文件	负责什么
Agent 与版本	`agents.py` `agent_api_keys.py`	Agent 主体、version、public access mode、API key inventory、成本快照、请求租约
Session 与对话观测	`sessions.py`	session、message、conversation turn、takeover、checkpoint、memory
RAG 知识链路	`knowledge.py` `documents.py` `knowledge_corrections.py`	source、mount、document、chunk、ingestion、manual inspection、correction
MCP 控制面	`mcp.py`	server、credential、agent mount、call audit
Skill 控制面	`skills.py`	skill、version、agent link
Evaluation	`evaluations.py`	dataset、dataset item、run、result
Fusion Runtime	`fusion.py`	definition、version、run、run input、run output
Scheduled Tasks	`scheduled_tasks.py`	task、task run、调度状态

一个 Agent 当前会关联：

所以很多“为什么这个 Agent 行为变了”的问题，根本不是看 agents 一张表就够。

sessions.py 当前不只包含消息，还包含：

也就是说，聊天运行时的可观察性和人工接管历史都已经是数据模型的一部分。

当前 RAG 相关模型实际至少包含：

模型	作用
`KnowledgeSource`	知识源
`AgentKnowledgeLink`	Agent 与 source 的挂载关系
`Document`	原始文档与向量健康状态
`DocumentParseSnapshot`	解析快照
`DocumentChunk`	chunk 元数据
`IngestionJob`	ingest 过程
`ManualInspectionRun` / `ManualInspectionResult`	inspect 过程与结果
knowledge correction 相关模型	managed correction 的发布链路

这解释了为什么 RAG 问题往往要同时看 source、document、job、snapshot、inspection result。

MCP 当前不是配置文件式集成，而是完整数据模型：

Skill 也一样：

这意味着它们现在是“可治理资产”，不是轻量插件列表。

Evaluation 不是静态 benchmark 表：

Fusion 也不是只存 definition：

字段	含义
`ConversationTurn.trace_id`	turn 与 MCP / Skill 审计关联键
`ConversationTurn.token_usage_*`	token 消耗观测
`RuntimeCheckpoint.status`	审批 / 挂起状态

字段	含义
`FusionDefinition.latest_version_number`	最新 version
`published_version_id`	当前生效 version
`FusionRun.status`	run 状态
`FusionRun.attempt_count`	worker 已尝试执行次数
`FusionRun.lease_token`	当前 worker claim / lease
`FusionRun.last_attempt_started_at`	最近一次 claim 的开始时间
`FusionRun.worker_heartbeat_at`	当前执行心跳
`governance_context_json`	capability 治理上下文