每条记录都能自我说明：ai_context 序列化器

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

这一点做错了，后面所有的演示都是建在沙子上。做对了，智能体就不再需要猜。

原始数据行是错误的输入

数据库行是为数据库而建的。它有外键、状态枚举、可为空的列、内部标志位，以及 UTC 时间戳。把这些交给模型，等于让它同时做两件事：先还原这条记录的含义，再基于它进行推理。

第一件事它会做得很糟。status: 3 离开查找表就毫无意义。closed_at 里的一个 null，可能表示“尚未关闭”，也可能表示“从未记录”。外键是一个模型无法追踪的数字。于是模型会自信地编造出它需要的含义——而这个错误会贯穿之后的每一步，越滚越大。

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

ai_context 序列化器是什么

在 Cyril 中，核心记录——客户、联系人、商机、项目、工单、发票、文档和产品——都各自提供一个 ai_context 序列化器。它是一个方法，返回该记录的一个确定性、理解数据结构的视图，专为 AI 的事实锚定而构建。

这个视图替模型完成了本不该由模型来做的解读：

• 枚举被解析为人能读懂的含义——status: 3 变成 "stage: negotiation"。
• 相关的统计数被并入——一个客户会带上其待处理工单数、进行中项目的状态和未付发票的情况，因为关于这个客户的问题会需要这些。
• 仅供内部使用的字段被剥离——模型永远看不到行 ID、软删除标志或租户底层字段。
• 结构是稳定的——同一条记录每次都生成相同的上下文，因此提示词可以缓存，行为可以复现。

它刻意既不是 API 响应，也不是数据库行，而是第三种表示形式，唯一的读者是模型。

为什么覆盖面才是关键

为一次上线演示会用到的那三个实体写 ai_context 序列化器很容易，而这恰恰是陷阱。同一张数据图谱的价值在于，一个问题可以跨越任何边界——“哪些有风险的客户同时还有延期的项目和未付的发票？”只有在客户、项目和发票都以同样方式自我说明时才能回答。

所以在 Cyril 中，序列化器是一项要求，而不是一个功能。核心记录目前都已具备；任务、费用、工时记录和人力资源记录仍在陆续加入，目前也还没有自动化测试来检查每个新实体是否都有序列化器。这种纪律并不光鲜，却正是它让智能体能在整个平台中穿行，而不会碰到一条读不懂的记录。

确定性也是一种安全特性

由于序列化器是唯一面向 AI 的视图，它也是我们控制数据暴露的地方。关于智能体能看到哪些字段的决定，在每个实体上只存在于一个可审计的位置，并且像所有其他查询一样限定在 org_id 范围内。不存在一条另外的“AI 导出”通道悄悄扩大影响范围——为模型提供事实依据的序列化器，同时也是限制它的边界。

它为您带来什么

• 提出一个跨模块的问题，得到的回答以已解析、带关联、最新的数据为依据——而不是模型不得不自行解读的原始数据行。
• 足够信任这个回答，敢于据此行动，因为同一条记录总是生成相同的上下文。
• 清楚知道 AI 能看到什么 在每个实体上只在一处定义，而不是散落在各个集成里。

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