每条记录都能自我解释：ai_context 序列化器

人工智能原生软件里令人兴奋的部分，是智能体真的做成了某件有用的事。而真正让它成立的那部分很枯燥：一条记录如何向模型描述自己。

这一步做错，下游的每一场演示都建在沙上。做对了，智能体就不再靠猜。

原始数据表行是错误的输入

数据表的一行是为数据库而生的。它有外键、状态枚举、可空列、内部标志位，还有以 UTC 记录的时间戳。把这样一行丢给模型，等于要求它同时干两件事：先还原这条记录意味着什么，再对它进行推理。

第一件事它会干得很糟。离开查找表，status: 3 什么也不是。closed_at 里的一个 null，可能表示「仍未关闭」，也可能表示「从来没跟踪过」。外键只是一个数字，模型顺着它走不下去。于是模型自行发明它需要的含义——而且说得斩钉截铁——这个错误再顺着后续的每一步不断放大。

解法不是换一个更大的模型，而是给模型正确的输入。

ai_context 序列化器是什么

在 Cyril 里，每个实体——客户、商机、项目、工单、发票——都暴露一个 ai_context 序列化器。它是单个方法，返回这条记录的一份确定性的、理解自身模式的视图，专为给人工智能提供事实依据而构建。

这份视图替模型完成了本不该由它做的解释工作：

• 枚举被还原为人能读懂的含义——status: 3 变成 "stage: negotiation"。
• 关联状态被折叠进来——一个客户会带上它的未结工单数、在途项目状态和未清发票情况，因为关于这个客户的问题正需要这些。
• 仅供内部使用的字段被剥离——模型永远看不到行 ID、软删除标志或多租户管道。
• 形状是稳定的——同一条记录每次产出同一份上下文，因此提示词可以缓存，行为可以复现。

它被刻意设计成既不是 API 响应，也不是数据库行。这是第三种表示，唯一的读者是模型。

「每个实体都强制」才是关键所在

只给发布演示会碰到的那三个实体写 ai_context 序列化器，是很容易的事。这正是陷阱。单一数据图谱的价值，在于一个问题可以跨越任意边界——「哪些高风险客户同时还有延期项目和未付发票？」这个问题能成立的前提，是客户、项目和发票都用同一种方式自我解释。

所以在 Cyril 里，序列化器是一项要求，而不是一个特性。新实体没有它就不算做完，测试模式会逐一检查。这种纪律毫不起眼，却恰恰是智能体能够遍历整个平台、而不会撞上一条读不懂的记录的原因。

确定性同时也是一项安全属性

因为序列化器是唯一面向人工智能的视图，它同时也是我们控制暴露面的地方。关于智能体可以看到哪些字段的决定，集中在每个实体唯一一处可审计的位置，并且和其他所有查询一样按 org_id 限定作用域。不存在另一条悄悄扩大影响范围的「人工智能导出」通道——为模型提供事实依据的那个序列化器，同时就是限制它的那道边界。

它带来了什么

• 提出一个跨模块的问题，得到的答案建立在已还原、已关联、当下为真的数据之上，而不是模型不得不自行解码的原始数据行。
• 答案可信到足以据此行动，因为同一条记录永远产出同一份上下文。
• 你清楚人工智能能看到什么，而这件事在每个实体上只定义一次，不会散落在各个集成里。

序列化器永远不会成为头条功能。它是决定那些头条功能是否属实的那一层。

常见问题

它和 API 响应有什么不同？

API 响应是为正在拼装界面的开发者塑形的：它完整、规范化，并且默认调用方懂这套领域模型。序列化器则是为一个不了解模式、也没法顺着外键走下去的读者塑形的，所以它做的是还原，而不是引用。

为什么不直接对数据库做检索？

检索找到的是与问题相似的文本。它回答的是某个时刻被写下来的内容，而不是这条记录当下为真的内容——而对于「本季度哪些客户存在风险」，当下为真恰恰就是问题的全部。

构建这份视图会拖慢查询吗？

它折叠进来的关联状态，本来就是一个像样的答案必然需要的；一次性、确定性地取齐，比让模型分好几轮来回索要更省。确定性还让结果可以缓存，而原始数据行那条路做不到。

新增一个实体时会怎样？

没有序列化器，它就不算做完。这一点由测试模式强制，而不是靠人记住，因为图谱的价值就在于一个问题可以跨越任意边界——一个没有序列化器的实体，就是智能体会掉进去的一个洞。

---

如果你希望成为最早使用 Cyril 的用户，加入等候名单。