--- title: 每条记录都能自我说明：ai_context 序列化器 canonical: https://getcyril.com/zh/博客/每条记录都能自我说明/ published: 2026-05-20 updated: 2026-08-28 author: Cyril team language: zh-CN --- # 每条记录都能自我说明：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 导出”通道悄悄扩大影响范围——为模型提供事实依据的序列化器，同时也是限制它的边界。 ## 它为您带来什么 - [提出一个跨模块的问题](/product/)，得到的回答以已解析、带关联、最新的数据为依据——而不是模型不得不自行解读的原始数据行。 - 足够信任这个回答，敢于据此行动，因为同一条记录总是生成相同的上下文。 - 清楚知道 [AI 能看到什么](/product/ai/) 在每个实体上只在一处定义，而不是散落在各个集成里。 序列化器永远不会成为头条功能。但它是决定那些头条功能是否属实的那一层。 ## 常见问题 ### 它和 API 响应有什么不同？ API 响应是为组装界面的开发者设计的：它完整、规范，并假定调用方了解业务领域。序列化器则是为一个不了解数据结构、也无法追踪外键的读者设计的，所以它解析内容，而不是引用内容。 ### 为什么不直接在数据库上做检索？ 检索找到的是与问题相似的文本。它回答的是某个时候写下的内容，而不是一条记录当前的真实状态——而对于“本季度哪些客户有流失风险”这样的问题，当前的真实状态就是问题的全部。 ### 构建这个视图会拖慢查询吗？ 它所并入的相关状态，本来就是一个真实回答所需要的；以确定性的方式一次性收集，比让模型在多轮对话中逐一索要更省。确定性还让结果可以缓存，而原始数据行的做法做不到这一点。 ### 新增实体时会怎样？ 没有序列化器，它就不应发布。目前这是我们自我约束的规则，而不是由测试强制执行的，因为数据图谱的价值在于问题可以跨越任何边界——一个没有序列化器的实体，就是一个让智能体掉进去的坑。 --- 如果您想成为首批使用 Cyril 的人，欢迎[加入等候名单](/waitlist/)。