铃阅
❌

普通视图

AI专栏 | 让知识库不只是“写过”:一份面向 AI 的知识工程实践

2026年11月16日 17:00

原创 Snow 2026-11-16 17:00 上海

把 AI 文档变成一份工程契约

作者简介

Snow,携程后端开发专家,关注前沿AI发展,对知识工程感兴趣。喜欢从底层机制理解技术取舍,探索可维护、可复用的工程实践。

团队热招岗位:AI Agent 开发工程师

「全文约 6,600 字,阅读约 16 分钟」

导读:一份写得完整、格式规整的知识库,有时反而比没有更让人不放心:过期内容会被当成确定答案,AI 还会把它组织得更有理有据。过去一段时间,作者参与了团队知识库的建设,一边把散落的 PDF、Word 手册迁移为可校验的 Wiki,一边沉淀出一套内容标准:知识与入口分离、写入时记录生成与确认、指标定义可编译成看板与告警、检索采用混合召回加两阶段重排。如果你正在建团队知识库,或在思考 AI 时代的知识治理该怎么做,这篇值得一读。

一、先把知识和入口分开

二、写得像真的,不等于是真的

三、知识还可以成为可编译的契约

四、没查到,未必是没写过

五、事实也会“脏读”

六、做减法,也有代价

一份写得完整、格式规整的知识库,有时反而比没有知识库更让人不放心。没有的时候,我们知道要去查代码、找负责人;有了以后,一段两个月前完全正确的说明,今天仍可能被当成确定的答案。现在再加上 AI,它还可以把这段说明组织得有条有理,顺便附上引用。

引用确实存在,只是引用的内容已经过期了。

最近一段时间,我参与了团队知识库的建设。我们一边整理散落的 PDF、Word 手册,一边从头建立团队 Wiki,把系统概念、业务规则和排障经验逐步沉淀下来。做着做着,关注点也从“怎样让 AI 帮忙写文档”,变成了“写下来的知识,怎样才值得继续使用”。谨以此文记录一些实践,以及我对这件事逐渐形成的理解。

这里不打算介绍某款知识库产品,也不展开各种 Agent 框架,主要聊我们怎么做、为什么这么取舍,以及哪些地方还没有做完。

一、先把知识和入口分开

我们通常把“知识库”当成一个整体,实际可以先拆成两件事:里面的知识,以及访问这些知识的工具。

工具负责编辑、搜索、展示,知识负责说明一个概念是什么、某条规则为什么存在、遇到问题该怎么查。工具升级换代很快,但这些内容不应该每次都跟着重新装修。对于团队来说,几年后能否继续理解和使用今天的积累,比当前页面是否足够漂亮更重要。

因此,我们选择先做内容标准,再做入口。

这个选择也来自我对平台和标准寿命的一点思考。平台常常在竞争中更替,而被广泛兼容的公共契约,往往能活得更久。POSIX 保留了不同 Unix 实现之间可复用的接口约定;OCI 沉淀了容器镜像与运行时规范,Kubernetes 则通过 CRI 对接不同运行时,更换实现并不意味着必须放弃已有镜像。OpenTelemetry 也让遥测采集与观测后端解耦,和 HTTP 一样,工具和形态可以变,共同的接口与协议仍可沿用。

到了 Agent 时代,很难不让我联想到当年的 Unix 竞争:MCP、A2A 也许会成为类似的公共契约,但这仍是我的判断,还没有经过长期验证。标准不是更能预测变化,而是更能吸收变化;我想留下的,是实现更替之后仍能复用的积累。就像 Docker 死了,但它构建的镜像们活了下来。

我借鉴了 LLM Wiki 的思路:让 AI 不只在查询时临时拼接原始资料,而是参与维护一份持久化的 Wiki,把摘要、概念关系、分析结果和来源整理成可以持续积累的内容。人负责提供来源、确定方向和作判断,机器承担整理、交叉引用、更新索引等结构化工作。当然,这不意味着检索不再需要,只是检索之前,先把值得检索的知识组织起来。

内容格式采用 Open Knowledge Format,简称 OKF。它的底座很简单:一个 Markdown 目录,加上 YAML 元数据。规范的最小必填项只有概念类型 type,并不要求所有团队采用同一套目录,也没有规定必须使用某个平台。我们在这个基础上增加了来源、确认记录和校验等团队约束,这是在 OKF 的基础上建设的类似代码管理的一套团队约束。

在我们的实现里,一份知识集合称为一个 bundle。下面是简化后的目录示意,描述文件用于本地识别和注册:

knowledge/
├── okf-bundle.yaml
├── index.md
├── log.md
├── concepts/
└── procedures/

其中,index.md 提供导航,log.md 记录变更,其他目录由 LLM 根据内容自己组织。同一份 Markdown 可以在本地编辑器里阅读,也可以生成文档站点,或者交给 Agent 消费。换入口时不用重写内容。

多个 bundle 也不必倒进同一个大仓库。团队手册、业务知识、工具说明可以各自维护,由不同的工作区选择需要的组合,这就是这里所说的“联邦”。它首先解决的是知识集合的自治、注册和引用,而不是宣布已经有了跨团队的统一搜索平台。截至撰稿时,跨库联合检索和权限治理仍是后续工作。

知识、工作区与可替换入口的分层关系

知识集合各自维护,组合由工作区决定,入口可以替换。

我认为现阶段 AI 的发展仍然没有逃脱《人月神话》中关于复杂度的论述框架,所以做知识库积累这件事还是有价值的。同样的,标准既不是“银弹”,也不能保证迁移完全没有成本。它只是让内容和工具少一些绑定,给以后的选择多留一点余地。

二、写得像真的,不等于是真的

能够搬走,接下来才轮到可信的问题。

一篇由 AI 整理的说明,往往看起来很完整。但“谁整理的”和“谁核对过”,是两件不同的事;“有来源”和“来源支持这个结论”,同样不是一回事。只靠读者在使用时自己判断,既费力,也很难让机器遵循一致的规则。

我们把这些信息写进了文档结构。

信息

对应字段

回答的问题

生成记录

generated

谁在什么时候产出了内容?

确认记录

verified

谁在什么时候核对过内容?

来源

sources

依据来自哪些材料,能否回到原处检查?

生命周期

status

、stale_after

是否仍建议使用,何时应该重新复核?

OKF 可以根据确认记录区分未确认、机器确认和人工审核三个档位。它记录的是客观信号,不是给文档盖一个“正确率百分之百”的章。人工审核过的内容也可能因为后续变更失效,文档过期了也不代表一定无效。

所以这里刻意使用“可核验”,而不是“保证为真”:有依据、有记录,人与机器才有路径去检查。内容发生变化后,旧的确认记录也不能自动当成新内容的背书。

生成、确认、来源与生命周期的客观信号

确认档位表示记录状态,不是永久正确的保证,也不是必须逐级完成的审批流程。

接下来是把约定落到检查里。来源是否缺失、链接是否断裂、元数据格式是否符合要求,这些尽量由程序确定性校验;概念之间是否矛盾、一次代码变更是否影响了排障说明,则需要结合上下文分析,不能都伪装成简单的格式检查。

我们将检查放在不同位置:写入时尽早发现基础问题——Hook,持续集成检查结构与引用——CI,合入审核负责确认变更是否合理——CR。由于本地 Hook 依赖宿主 Agent 支持,不能把它当成唯一防线,所以我们设计了多层检查关卡保障,以保障知识库的健康状态,最后还有定期巡检来兜底。

一个小插曲,曾经巡检结果先由子 Agent 产出,再交给主 Agent 转述。文字看起来没什么变化,群里的 @ 却失效了,因为转述过程改坏了结构化标签。后来我们把巡检编排收回主执行流程,减少这一次额外转述。原先采用子 Agent 有它的上下文隔离和成本考虑,设计之初还没有 DeepSeek V4 flash 这类高性价比模型。也是这次经历也提醒我们,需要原样传递的数据,不应该因为“再帮我整理一下”而多经过一次自由改写。知识的内容需要理解,结构化凭据则需要保真,两者的处理方式不必相同。

三、知识还可以成为可编译的契约

说到这里,知识库似乎还是一些带了元数据的文档。下面用一个指标的例子,说明它还能往前走一步。

比如“请求成功率”,看起来大家都认识,但分母统计哪些请求,主动取消算不算失败,时间窗口怎么取,数据来自哪里,都可能有不同理解。如果文档、看板和告警各写一份定义,三份在当时都对,几轮修改后也可能各执一词。

我们的做法是先在指标页里写清口径、来源和可执行查询,给查询一个稳定标识。注册表只引用这个标识,并描述它如何被看板或告警消费,不再重复保存另一份查询。

引用大致如下,路径和名称均为虚构示意,不对应内部指标:

query_ref: metrics/request-success.md#success-rate

随后,校验程序检查来源信息、查询引用和生成所需的配置是否完整,再由编译程序生成目标产物。

指标页到看板与告警配置的编译流程
原始流程图源码

图 1:一份指标定义被多种产物消费的抽象示意。

这里真正有价值的,不是生成了多少面板,而是同一份定义同时有三个用途:人能阅读,机器能检查,下游能据此生成配置。它不再只是一段介绍,开始具备契约的性质。

不过,编译成功不等于统计口径正确。编译器能发现引用不存在,却不能替业务判断“接口A的请求量指标是否关键”。哪些指标值得长期维护,也仍需要人的判断。我们没有从头自动梳理所有候选指标,而是基于已有人工积累继续治理。

另一点是,看板和告警只是并列的消费方,不是所有看板指标都需要告警,也不是所有告警都必须先出现在看板上。共享事实定义,不等于共享所有使用方式。

至于将生成的配置发布到真实系统,是单独的操作,需要单独授权,不能因为文件编译通过,就顺手替人上线。但我们通过 Browser Use 能力做到一键发布。

四、没查到,未必是没写过

写入有了约束,读取也会遇到另一类问题:知识在库里,Agent 却没有找到。

我们在检索评测中碰到过这样的题目:询问某个平台的应用标识,答案就在总览页的表格里,但推荐返回范围没有命中,放宽返回范围后才能找到。这个例子不是“加上向量就解决了”的简单叙事。

排查时,我们考虑了提问术语、字段写法、分块边界等因素。比如用户说“应用标识”,文档可能写“应用 ID”;用户使用平台简称,正文采用正式名称。这些都是合理的归因方向,但如果没有单题对照验证,就不能把猜测写成已经确认的根因。

从方法上说,文本检索和向量检索各有长处。BM25 擅长保留表名、字段名、标识符等字面线索,向量召回擅长处理“换了个说法”。我们将两路候选通过 RRF 融合,再做重排。RRF 主要按排名合并结果,避免直接比较两路并不一致的分数尺度;重排再结合查询与候选内容判断相关性。

这条链路也有一些外部佐证。2026 年 4 月公开的 T²-RAGBench 检索研究,在两万余条金融数值问答上比较了多种策略,文档同时包含文本和表格。下面截取其主结果表中的几项,Recall@5 衡量前五个结果对目标文档的召回情况,数字来自论文,不是我们的实测:

方法(同一主结果表)

Recall@5

BM25

0.644

混合召回(BM25+向量,RRF)

0.695

上下文增强的混合召回

0.717

混合召回+神经重排(两阶段)

0.816

两阶段检索主链路与论文 Recall@5 对照

四项数字来自同一论文主结果表,仅作外部架构佐证,不代表我们的实测或预期收益。

在该研究所比较的策略中,两阶段方法取得了最高的 Recall@5。论文把重排称为“单项影响最大的组件”,并推荐将它放在混合召回之后。这和 QMD 的架构设计相近,也给我们继续投入召回与重排提供了方向依据。

在该研究的 Recall@5 对照中,上下文增强的混合召回(Contextual Hybrid)仅次于两阶段方法,说明上下文增强仍有增益。我们现阶段优先完善已采用的混合召回与重排,再评估上下文增强。这是工程投入顺序的取舍。

另外,QMD 的架构还有首尾两个关键节点:Query Expansion(词扩展) 和 Position-Aware Blend(位置感知融合)。对此我们也做了一些 Tradeoff,由于现代 Agentic Search 通常会自行扩展 Query 同时并行 Tool Call,所以我们认为在 MCP 里做 Query Expansion 是冗余工作,而 Position-Aware Blend 仍然有用,它可以避免 Reranker 根据语义相关性轻易推翻 BM25 传统检索已经找到的精确匹配结果,通过调节权重起到兜底作用。

借助于 Markdown 标准格式的结构化语法,也可以做到语义相关性更好的 Chunking。标题层级提供上下文,表格和代码块尽量保持完整,每个片段保留标题路径。否则答案虽然在某一行里,脱离表头后也可能不再是答案。

检索返回原始片段及来源路径,同时提供读取原文的能力。组织答案仍交给调用方 Agent:需要少量证据时不用把整篇文章搬进上下文,需要核对前提时又能继续下钻。

小规模本地对照中,这种方式相比当时整篇盲读的基线,减少了上下文读取量和查询耗时。现在也已在线上试运行,后续还要整理真实环境的量化数据。

五、事实也会“脏读”

文档可以被找到,也有过确认记录,今天还有效吗?

做了一段时间后,我更愿意把 Wiki 理解成一层“事实缓存”。代码、配置、原始材料和口口相传是来源,Wiki 保存的是对它们的整理与解释。我们复用这层结果,不必每次遇到问题都从头分析,但来源已经变化、页面没有更新时,也就发生了类似脏读的事情。

这是一个架构比喻,不是说知识库已经具备了数据库级的一致性保证。

要减少这类问题,我们需要两种反馈。一种来自来源变化,比如代码变更和部分遥测信号变化,用来提示哪些页面可能需要复核;另一种来自真实使用,看看用户为什么没有得到需要的帮助。更多配置、数据等来源的漂移检测,也需要逐步接入,不能因为元数据能记录某种来源,就认为已经能够自动监听它的所有变化。

使用反馈尤其不能简单归因。比如用户在排障时知道要查某张表,却不清楚需要看哪个字段。这场排障没有完成,可能是文档缺步骤,也可能是工具调用失败,或者内容本来齐全,只是没有被检索到。把这些情况一律处理成“让 AI 再写一篇”,很容易越补越乱。

因此,我们先判断有没有问题,再判断该由哪一层解决。如果归属知识库,还要继续区分:内容不存在、内容不正确、已有内容没有被找到,或者不同页面互相冲突。用户多问了几轮,也只能作为候选信号,不能直接视为一次失败。

分析以完整会话为单位,分桶后再核对对应页面,产出带定位依据的修正提案。对于能明确定位的交叉引用缺失,可以生成局部修正,但提交的变更仍走审核流程。发现重复问题则按类型和定位做去重,在同类问题下跟进,避免每次巡检都重新制造一份待办。

来源变化与使用反馈驱动的事实缓存维护

来源变化与使用反馈经过归因、提案、审核和回归验收,形成知识维护路径(架构比喻)。

不过,“发现问题并改了文档”还不是终点。改动究竟有没有用,有没有顺便改坏其他场景,需要评测。

我们将题目模板与具体数据分开:Case 描述问题以及必须取得的证据,Instance 绑定一次具体场景和数据。能固定依赖的场景用快照或 Mock 做回归,需要实时查询的场景保留真实执行。

我们的评分约定也不只看最后一句答案像不像正确答案,而是看必要证据是否获得,推导是否成立。对于允许保留不确定性的案例,明确指出尚未验证的依赖可以是合格行为;没有证据却强行给确定结论,反而应该失败。这不等于可以省略题目要求的必要取证。对排障来说,知道哪里还不能下结论,比猜中一个答案更值得保留。

评测集本身也需要复核。我们的检索标注集规模还小,而且当时没有“库里根本没有答案”的负样本。一个很高的命中成绩,只说明已有题目答得不错,测不出遇到知识边界时会不会硬编。先补齐这类样本,再讨论几个小数点的提升,更有意义。

目前,发现问题、提出修正和回归验收已经有了各自的机制,也经历了几轮闭环迭代。

六、做减法,也有代价

前面讲了不少治理,最后还是回到人怎么使用。

我们提供了轻量阅读站点,也建设了面向特定手册的薄编辑入口。我还自测过一种在浏览器里运行 Obsidian 的兼容方案,主题、图谱和插件看起来都很不错,但没有解决团队多人并行编辑的冲突。调研完成后,我们暂时不投入这条路线。

做团队知识库的第一性原理是赌上“未来的文档即现在的代码”的个人判断,所以我不追求做一个重型在线协作文档平台,跟现在管理代码的方式一样,协作主要沿用 Git、变更请求和人工审核。入口可以改进,但内容格式与检查规则尽量不绑在编辑器里。

从起步结果看,两条工作都已经有了可用产物:存量手册被迁移成独立的 Wiki bundle,团队 Wiki 则从零积累了百余篇知识页,日常提交有同事,也有机器人。两类内容分属不同的 bundle,各自维护,但都在验证同一套内容组织与变更机制。对我来说,更有价值的是把迁移、阅读、写入和检查实际跑通,并开始进入团队的日常使用。

当然,标准化治理不是免费的。补来源、确认口径、处理冲突和复核变更,都要花时间和精力。对一次临时交流来说,直接发段文字更方便;对需要多年复用的团队知识来说,留下依据和维护路径才更值得。我们只是把成本从“每次使用时重新猜”,挪了一部分到“写入和变更时认真检查”,并没有让维护凭空消失。

临时交流与长期知识复用的维护代价对比

维护成本没有消失,只是从使用时部分前移到写入与变更时。

下一步,我们要做的是持续扩大来源变化的检测范围,发掘更多消费知识的场景,量化知识库在实际问题中的作用,降低整套运转机制的推广接入成本。至于上下文增强、更炫的编辑器和更多自动化,可以等这些基础问题做扎实后再看。

知识库不必越来越像一个庞大的产品,但里面的每一份长期知识,最好越来越像一份有人维护的工程:有来源、有检查,变化时知道该找谁,使用时知道哪里还不能确定。

至少下次遇到同一个问题时,不必全靠那个最了解情况的人恰好在线。

【参考资料】

  1. LLM Wiki:持久化知识维护的设计笔记

  2. Open Knowledge Format v0.2 规范

  3. QMD:Markdown 文档检索工具

  4. From BM25 to Corrective RAG:文本与表格文档检索策略对照研究(arXiv:2604.01733v1,2026-04)

【推荐阅读】

 “携程技术”公众号

  分享,交流,成长

跳转微信打开

干货 | 告别轮询!携程机票 APP 基于 SSE 的全栈流式通信实战与性能优化

2026年10月29日 17:00

原创 Haitao 2026-10-29 17:00 上海

用最小的改造成本,获得最广泛的业务收益

作者简介

Haitao,携程资深前端开发经理,关注前端性能优化相关与AI应用落地。

导读:面对移动端传统轮询带来的延迟与高功耗痛点,携程机票前端团队完成了Server-Sent Events(SSE)从Web到APP(Native+RN)的全栈落地。本文深度拆解了全链路改造的踩坑经验,以及预建连、预请求、Brotli压缩等硬核优化手段。数据显示,其列表多批次加载总耗时平均提升11.8%。此外,文章还探讨了如何利用SSE“异构分批”解决前端渲染与API粒度设计的矛盾,并为AI Agent流式改造铺平道路。如果你正苦恼于复杂列表的串行请求与首屏体验,这篇全栈级实战干货不容错过。

一、前言

二、SSE在Web上的应用

三、SSE在APP上卖现方案

四、SSE在APP上优化效果

五、其他适用的业务场景

六、小结

一、前言

SSE(Server-Sent Events)是一种允许服务器通过HTTP协议向客户端(通常是浏览器)单向推送实时更新的技术。它是HTML5标准的一部分,主要用于需要从服务器持续接收数据更新的应用场景。 

在SSE中,客户端通过创建一个 EventSource 对象来连接到服务器的SSE端点。服务器则通过一个持久的HTTP连接不断向客户端发送数据流。数据通常以纯文本格式发送,客户端可以通过JavaScript监听这些数据并进行处理。SSE的典型应用场景包括实时通知、新闻推送、股票行情更新等,适合那些需要服务器主动向客户端推送数据的场合。与WebSocket不同,SSE是单向的,只能从服务器向客户端发送数据。

同时随着 AI 应用相关的推进,结合业务场景完成 SSE 在 APP 上的落地应用,同时可完成相关 Agent 相关业务场景的基建。

二、SSE在Web上的应用

去年携程机票团队首先在Web Online业务上进行落地使用,《干货 | 携程机票前端Web流式通信SSE全链路应用实践》技术方案主要采用:

  • 前端侧,SSE使用工具库fetch-event-source,

  • 服务侧,业务的流量链路并不是客户端—服务端直达,完全落地SSE,需要全链路支持SSE。

同时在服务侧需要注意处理以下问题:

  • 中间存在多个7层代理需注意处理,包括:

    • 7层加速节点(akamai/aws)

    • 流量接入层(slb)

    • 中间转发节点(虫洞)

    • sidecar(envoy/nginx)

  • 分块传输,本质上需要传输数据碎片,但中间层各自实现并不遵从统一标准,例如nginx,默认配置上会缓存response

  • 对于nginx 链路上所有Nginx,需主动关闭报文缓存,透传相关header:proxy_pass_header X-Accel-Buffering;

  • 需开启数据压缩

三、SSE在APP上实现方案

3.1 方案对比

在 APP 中使用 SSE(Server-Sent Events)相比其他实时通信方案(如轮询、WebSocket)

  • 移动平台适配友好,可通过原生网络库实现

  • 跨平台一致性,同一套 SSE 服务可同时支持移动端 APP、网页端 H5,避免为不同端开发多套实时通信方案,降低维护成本。

  • 低功耗与后台适配,相比 WebSocket 的双向通信,SSE 单向推送的连接维护成本更低,对移动设备的 CPU 和内存消耗更小,在弱网或网络切换时,SSE 的重连逻辑可更灵活地适配网络状态

3.2 实现方案

SSE在机票Web online上成功落地使用后,随即开始APP上针对SSE进行使用验证。对于APP的实现方式基于text/event-stream 类型的响应体持续推送数据,通过Event来处理数据。业务上基于携程公共框架团队实现SSE基础能力之上进行,框架团队提供了相关接口给业务使用。从实现上分为三层包括云端, native层和RN业务层,大致的关系如下:

  • React Native Plugin - Native 框架侧

    同时由于机票业务采用的RN跨平台方案,因此还需同时支持Native以及RN的使用,增加相应的RN Plugin,需要分别处理:

    onOpen:建立连接

    onMessage:服务端向客户端推送批次数据

    onClosed:请求完成

    onError: 请求报错

    业务接入实现的大致结构如下:

另外在完成功能链路外,针对 SSE 相关的数据指标也做了一些优化手段包括:

  • 预建连:优化onOpen阶段的耗时

    1)在实际需要发送请求前,提前建立好网络连接,以减少后续请求的响应延迟。

    2)目标 host 相同的多个请求,在协议一致且连接空闲可用的情况下,网络层会自动进行进行连接复用,减少网络开销,提升通信效率。

    3)针对host连接复用,多个不同请求间共享,时机可在业务入口初始化时触发。

    ssePreConnect = (serviceCode: string): boolean => {

        const host = host;

        if (host && EventSource.preConnect) {

            EventSource.preConnect?.(host);

            return true;

        }

        .....;


    • 预请求:相比于预建连为host维度,预请求针对单一request进行链路复用,提升业务请求响应性能

      1)在实际业务的前序流程中提前请求数据,加速业务加载。

      export const createSSEPreload = (options: TSSEServerParam) => {

          const { params, sseInstance } = createSSEInstance(options);

          const sseEventMananger = new SSEEventManager({params});

          sseInstance.preload?.();

          return () => {

              sseEventMananger.onUnsubscribe?.();

              sseInstance.removeAllEventListeners();

              sseInstance.close();

          };

      };


      • 请求缓存:服务于预请求

        1)请求命中时,复用缓存数据或者复用请求链路。

        2)请求会标记不同的状态标识复用情况,状态枚举如下:

      缓存实现通过父子任务进行真实请求与在途管理,父任务用于管理真实请求即 network 类型,子任务即标识挂载到父任务下的相同 cachekey的在途请求,在途请求发生时会创建子任务挂载到父任务下,同步管理实时数据接收,不同类型的大致流程图如下:

      • 报文压缩

      针对报文压缩相关进行了两项优化包括:

      1)请求命中时,复用缓存数据或者复用请求链路开启报文压缩:网络请求性能,尤其在P90指标上,报文size与网络链路耗时呈现显著正相关关系,需注意开启报文压缩,降低报文size。

      2)更换压缩编码从 Gzip 更换为 Broti。

      切换为 SSE 后带来的一个问题是报文压缩上的差异:压缩算法从 ZSTD 变更为 Gzip,导致 SSE 版本的报文 size 显著上升,压缩后的size,反映到体验上是加载完成耗时提升正向收益之外,带来了少量首次数据耗时的负向影响,通过进一步压缩报文 size 进行优化。

      四、SSE在APP上优化效果

      4.1 SSE的性能提升数据

      通过引入 SSE 方式,相比于原有的轮询方式存在以下优势:

      • 减少网络链路请求次数,提升查询性能

        • 减少网络交互

        • RN与Native的通信次数

        • 串行查询时的处理及等待耗时

      • 简化各端代码结构,减少串行请求的回调监听,时序控制

      • 简化前端预搜索多批处理逻辑,对比串行查询机制,仅需处理一次预搜索即可完成所有批次的数据预请求

      • 轻量灵活便于下沉,多端复用,灵活调整业务查询流程,便于引入更丰富的查询机制

      数据上,APP接入SSE除了在业务逻辑简化等业务收益外,同时在查询性能上也有所体现,通过我们的实际业务数据对照效果,列表页多批次加载完成的总耗时对比如下:

      针对验证数据进行分析:

      • 性能提升体现在数据加载完成的耗时,对于首批数据的耗时没有明显的差异

      • 同时分析对比链路请求差异,SSE能够减少RN与Native的通信时间(数十毫秒),以及减少一次请求,同时能够避免在服务数据已经ready,但是需要前端请求到达才能下发的情况。相比于Web,这种情况,由于APP用户的网络波动更高,尤其对于查询性能高的航线,叠加用户的网络波动和预请求的因素,效果更为显著。

      APP接入SSE后的注意事项:

      • APP在使用SSE前使用TCP连接,使用SSE后变更为HTTP连接,HTTP由于SSL Pinning机制的存在,会导致部分使用VPN等网络环境不安全的用户无法访问。

      • 业务上存在上云,海外访问等情况,存在远距离数据传输的问题,需要关注所有链路均支持SSE,关注各地区数据,避免出现部分地区SSE分批失效的情况,数据上表现为,多批次数据同一时间到达,需要进行降级处理,同时与相关服务商反馈报障。

      • 自动重连,业务实际使用中虽然原生支持,但是暂未启用失败重连特性。若需使用需要注意防范重连风暴风险,避免极端场景大量用户重连,导致服务端负载压力过大。

      4.2 报文压缩的数据指标

      整体的优化中有专门针对报文压缩编码进行优化,并进行了相关数据对比主要的观测指标分类客户端和服务端分别进行检测。

      客户端性能指标如下:

      • 压缩率Br 与 ZSTD 基本一致

      • 平均报文 size 上 Br 比 Gzip 减少约 20%, 超长报文size Br 可比 Gzip 减少约 30%

      • 耗时SSE-Br 相比 SSE-Gzip 可提升 20ms 左右的性能

      服务端指标如下:

      • 压缩率比值

      • 内存开销 无显著差异

      • CPU开销 无明显差异

      • 服务端压缩耗时,小报文无影响,平均报文压缩耗时下降 30%,但因基数小对总体均值影响较小,主要用于证明对服务侧无负向收益

      另外针对选择 Br 的优势

      • 标准HTTP 编码,框架层接入成本相对较低,同时能够适用于不同的客户端

      五、其他适用的业务场景

      针对SSE的应用场景,上述业务中的例子是针对轮询场景下的业务应用,该场景下每一批次均为同一业务的数据,数据结构也为同构数据。

      除此之外,在前端的日常开发过程中, 经常出现服务接口的粒度设计上,存在视图导向和资源导向之间的矛盾,细粒度 API 与后端的资源模型一一对应,而前端视图的需求可能与后端资源划分不一致。很多接口粒度以资源为导向,前端在处理时需要设计复杂度更高的方案去兼容各个接口间的请求时序、渲染时序、不同API间的逻辑PK关系等等。

      因此,我们可以考虑将不同功能的接口,包装为异构的多批数据请求聚合在同一个SSE请求中,分批下发,用以解决服务API设计原则上产生的粒度过细与页面渲染实际使用间的矛盾问题。能够达到:

      • 逻辑下沉,简化前端复杂度,通过SSE由服务聚合控制是否分批、如何分批,提升业务灵活性

      • 简化时序边缘场景控制,更灵活地控制页面子元素分批渲染

      • 多端复用生效

      • 相关预请求以及缓存实现的复杂度显著降低

      不同的实现方案在此场景下 SSE 相比 BFF 聚合和 GraphQL 的横向对比如下:

      同时当前,查询 agent 的应用日益广泛。SSE 在携程业务的落地,不仅在当下完成了相关业务实现的基础,同时对查询列表的流式改造也为后续 UI 列表加载与 agent 的结合预留了改造基础——既解决眼前的实时性与分批渲染诉求,也为未来的能力扩展留出空间。

      六、小结

      SSE 在查询上的应用价值不是为了比 WebSocket 等其他方式更快,而在于用标准 HTTP 的最小代价,获得服务端主动推送、全链路复用以及原生重连异常处理的组合能力,通过最小的改造成本获得最广泛的业务收益。当业务的需求场景是服务端持续吐数据给客户端时,SSE往往是更务实的选择。

      【推荐阅读】

       “携程技术”公众号

        分享,交流,成长

      跳转微信打开

      AI专栏 | AI写代码加速后,如何保障高质量交付?拆解携程 DevMaster 的企业级研发实践

      2026年10月19日 17:00

      原创 市场 2026-10-19 17:00 上海

      一套连接需求分析、项目拆分、规格驱动开发和测试反馈的研发方法与工程体系

        作者简介

      Minglei Jia,携程前端开发专家,持续探索 AI Agent 驱动的研发体系重塑与工程效能提升;

      Zhaosheng Wei,携程资深后端开发工程师,关注AI Agent构建与应用落地;

      Gang Dong,携程资深后端开发工程师,关注后端工程化与AI Agent实践;

      Joan Zhou,资深后端开发工程师,专注探索大模型在测试领域的落地应用。

      导读:AI 编程工具正在快速改变软件开发方式。代码生成变得更快,开发者可以用自然语言完成页面搭建、接口实现和测试补充。但在企业研发中,代码写得快并不等于需求交付得快。需求是否清楚、多个项目如何协作、生成结果如何验证、测试问题如何回到开发环节,仍然决定着最终的交付质量。

      过去一段时间,我们围绕这些问题建设了 DevMaster。它并不是一个单独的代码生成工具,而是一套连接需求分析、项目拆分、规格驱动开发和测试反馈的研发方法与工程体系。本文介绍我们为什么要建设这套体系、如何设计关键环节,以及实践中得到的经验。

      一、AI 范式下的需求交付问题

      二、自然语言需求的结构化与标准化

      三、完整需求的应用级拆分

      四、Harness驱动的SDD开发与质量保障

      五、TestPilot:测试用例的生成与管理

      六、工作方式的变化与结语

      一、AI 范式下的需求交付问题

      早期使用 AI 编程工具时,我们最关注的是生成速度和代码可用率。随着使用范围扩大,我们发现,影响交付结果的主要因素往往发生在代码生成之前和之后。

      1.1 需求信息不适合直接交给 AI

      真实需求通常分散在产品文档、原型、会议纪要和即时沟通中,容易出现信息不一致、边界缺失和版本不同步。开发者可以通过沟通补齐上下文,但 AI 只能依据当前输入判断;一旦信息不完整或变化未同步,生成结果就可能偏离目标并扩大返工。

      1.2 一个需求通常涉及多个项目

      中大型需求通常涉及前端、多个服务端应用和测试团队,需要共同确认接口、数据流、异常处理与验收标准。应用拆分依赖资深工程师对系统结构和隐性约定的理解,这类经验难以稳定复用,项目越复杂,遗漏和误解越容易发生。

      1.3 AI 能写代码,不等于代码能够进入生产

      生成可运行代码并不难,但生产级代码还必须符合团队规范和技术设计,覆盖需求场景,并通过编译、构建和测试验证。因此,需要将这些要求转化为生成前约束和生成后检查,关键结论仍由人确认。

      1.4 前端、服务端与测试之间信息割裂

      前端、服务端和测试往往分别理解需求,信息沉淀在各自的文档、沟通和经验中。差异通常到联调或测试阶段才暴露,表现为接口字段、状态流转或异常场景不一致,因此三方需要基于共享规格协作。

      1.5 小结:从单点工具转向完整交付链路

      DevMaster 的核心思路是以结构化规格为纽带,让同一份需求信息在分析、设计、开发和测试之间持续流动。整个链路可以概括为四个阶段:需求结构化、应用级拆分、规格驱动开发和测试反馈。

      核心产物关系:原始需求经过结构化形成 TRD(跨应用的技术需求规格);TRD 按应用边界拆分为 ATRD(单应用技术需求规格);ATRD 进一步生成设计、任务和增量 Spec,最终约束代码实现与测试验证。

      这套设计遵循三个原则。

      • 规格是共同依据。产品、开发和测试使用同一组结构化信息,减少各自重新解释需求带来的偏差。

      • 关键节点由人确认。AI 负责提取、分析和生成,人负责确认需求边界、技术决策和验收结果。

      • 过程可以度量。系统记录规格覆盖、代码匹配、测试覆盖和修复过程,用数据发现问题,而不是只凭主观感受判断效果。

      二、自然语言需求的结构化与标准化

      2.1 自然语言需求为什么不能直接进入 AI 开发

      原始需求往往来自文档、原型与沟通记录,信息缺失或版本不一致会使 AI 偏离真实目标;需求变化也难以及时传递到设计、代码和测试。因此,在进入开发前,需要先将自然语言需求转化为结构稳定、可追踪、可增量更新的规格。

      2.2 结构化需求的设计目标

      为解决这些问题,我们设计了技术需求文档 TRD(Technical Requirement Document)。它不是对产品文档的简单改写,而是将分散信息整理为可以被人和 AI 共同使用的规格。设计时重点关注四个目标:

      • 结构统一:用稳定格式描述触发条件、参与者、业务行为、异常分支和预期结果。

      • 来源可追溯:每条规则都能回到原始需求或经过确认的澄清记录。

      • 变化可管理:保留需求版本和差异,识别变化对规格及下游产物的影响。

      • 结论可审核:AI 负责提取、整理和提出问题,业务决定仍由产品、开发和测试负责人确认。

      2.3 核心设计

      整个过程可以概括为四步:聚合需求上下文、生成结构化规则、完成歧义澄清、根据需求变化持续更新。四个步骤共享同一份来源和版本信息,避免每个环节重新解释需求。

      2.3.1 聚合多来源上下文

      系统首先汇总产品文档、评审记录、业务知识和历史澄清结果,并保留每段信息的来源。不同来源发生冲突时,优先采用当前需求中经过确认的结论,其次是本项目的有效规则,历史经验只作为参考。无法确定的信息不会被自动补全,而是进入待澄清列表。

      经过人工确认的通用知识和澄清经验可以沉淀到知识库中,在后续需求中复用。知识条目同时保留适用范围和来源,避免历史结论脱离场景后被直接套用。

      2.3.2 用 EARS 表达可验证的需求规则

      结构化规则采用 EARS(Easy Approach to Requirements Syntax)的基本思想,将自然语言拆分为条件、动作和结果。例如:“当用户满足指定条件并提交申请时,系统应完成校验并返回处理结果;如果校验失败,则保持原状态并说明原因。”

      这种表达方式不要求删除所有自然语言,而是把最容易产生分歧的条件、边界和结果显式写出。统一结构既方便开发者阅读,也便于后续生成设计、代码和测试用例,并支持逐条检查需求是否得到实现。

      2.3.3 通过人机协同完成需求澄清

      系统根据缺失条件、规则冲突和边界不完整等情况生成澄清问题,同时给出问题来源、生成原因和可能影响。对于能够从会议记录、业务知识或历史结论中找到的信息,系统提供候选答案;负责人确认后,答案才会进入正式规格。

      这一机制的重点不是让 AI 代替需求评审,而是把分散、重复的检查转成清晰的问题列表。人工主要判断业务规则和例外情况,系统负责整理证据、记录结论并将有效经验沉淀为后续可复用的澄清标准。

      2.3.4 检测需求变化并增量更新

      需求重新导入后,系统比较新旧版本,定位新增、删除和修改的内容,并判断哪些结构化规则受到影响。对于未变化且已经确认的内容,系统继续保留;对于变化部分,重新生成澄清问题并提示负责人审核。

      增量更新避免了每次变更都重新生成整份文档,也保留了需求、澄清记录和 TRD 之间的版本关系。下游系统可以据此判断设计、代码和测试是否需要重新检查。

      2.4 实践效果与局限

      目前,该方法已覆盖百余个需求,并沉淀数百条经人工审核的澄清标准。实践表明,结构化需求能提升澄清完整性,并为代码和测试用例生成提供更稳定的输入;但其效果仍受原始材料、知识库时效和人工审核质量影响,复杂业务与高风险边界仍需负责人确认。

      三、完整需求的应用级拆分

      3.1 架构师视角的需求拆分

      上一章解决了需求如何被完整、准确地表达,但结构化需求仍不能直接转化为代码任务。进入开发阶段后,还需要完成一次关键的技术拆分:把业务需求映射到具体应用,明确每个应用的职责和协作边界。

      业务边界明确,不等于应用边界明确

      在现有研发流程中,业务澄清、PRD 输出和优先级确认通常在开发前完成。此时明确的主要是业务目标与需求范围,但研发团队仍需要结合实际系统结构,判断这次需求会影响哪些应用。

      开发真正需要回答的是:

      • 需求涉及哪些应用?

      • 每个应用分别需要完成什么改动?

      • 前后端及上下游之间存在哪些依赖?

      • 跨应用、跨团队的协作契约如何确定?

      这些判断本质上是架构师的结构性决策

      应用边界不能只根据 PRD 中的功能描述推断,还需要同时理解现有代码组织、服务依赖、数据流路径和历史技术约束。只有把需求信息与项目结构放在一起分析,才能形成可执行的应用拆分方案。

      依赖个人经验的方式难以规模化

      随着项目数量、调用链路和协作团队增加,建立上述认知的成本会快速上升。相关知识往往分散在代码、文档和个人经验中;一旦人员变化,新的负责人就需要重新理解系统,拆分效率和准确性都难以稳定。

      DevMaster 的目标,是填补“需求到应用边界”的认知鸿沟

      DevMaster 通过持续建立项目结构认知,结合代码关系、服务依赖和历史数据流,辅助工程师识别受影响的应用,明确各应用的职责、改动范围与交互契约。完成边界划分后,系统会为每个应用分别生成需求概要设计(ATRD),作为后续 SDD 编码的输入。

      下一节将具体说明,每个应用最终会拿到什么样的交付物。

      3.2 用户最终拿到的是什么?

      完成应用边界划分后,DevMaster 会面向每个涉及的应用分别生成一份需求概要设计(ATRD),作为后续 SDD 编码的输入。

      需求概要设计不是需求文档的复述,也不是代码注释的堆砌。它从单个应用的视角重新组织需求,把全局方案转换成该应用可以直接执行的工程输入。

      一份完整的应用级需求概要设计,重点回答四个问题:

      • 背景——为什么要改?说明应用参与本次需求的原因、在整体方案中的角色,以及与上下游的关系。

      • 协作触点——和谁协作?明确对外接口、上游依赖、异步消息和数据共享边界,形成前后端及上下游共同遵守的交互契约。

      • 改动范围——具体改什么?明确需要新增的能力、调整的逻辑和废弃的路径,让 AI 编码知道从哪里入手,也让 Code Review 知道应重点关注哪些模块。

      • 验收标准——怎样算完成?用“给定输入—执行路径—预期输出”描述可验证结果,使其能够继续转化为测试用例和接口自动化测试的输入。

        这份产物的核心价值,是让每个应用独立推进,而不是重复对齐。

        每个应用拿到自己的 ATRD 后,就能明确职责边界、协作契约、改动范围和验收标准,并据此独立进入 AI 辅助编码流程。跨团队协作也从反复开会确认,转变为基于明确契约并行推进。

        这些应用级需求概要设计并非依靠静态模板直接生成,而是在项目探索过程中,通过架构地图、代码检索和交互澄清逐步形成。下一节将说明一次完整探索的具体流程。

        3.3 一次完整探索的流程

        从输入一个需求,到拿到分应用概要设计,大概经历这几步:   

        1)选择需求、技术栈、相关仓库启动探索。

        2)召回或者建立架构地图,追踪数据流,找到相关代码逻辑。

        3)选择题式互动澄清,帮你最大程度的“偷懒”。

        4)方案 Review,确认应用边界划分、协作契约、改动范围是否准确。

        5)确认并交付下游。

        3.4 团队记忆与自进化

        理念

        让每次探索产生的认知,沉淀为团队可复用的资产

        两层沉淀

        • 项目级记忆:每次探索结束后,AI 把关键认知写回知识库——模块边界、数据流路径、踩过的理解误区。下次同项目探索时自动注入,不从零开始。

        • 团队级知识:跨需求、跨项目积累的经验形成团队级知识——某类需求的影响范围规律、中间件使用约定、历史反复出现的理解偏差。这些不再是个人的隐性知识,而是每次探索时 AI 都会读取的"集体经验"。

        三个反哺方向

        • 探索更准:带着已有认知进入,直接在已知骨架上定位变化点,更快速准确。

        • 设计更可靠:历史同类需求的结论作参照,减少重复犯同样的判断错误。

        • 编码少返工:团队沉淀的约束和规范,避免后续再次违反"不成文规定"。

        3.5 总结

        需求理解不是 AI 编程的准备工作,它本身就是 AI 编程最难的那一步,分应用级需求的拆解和概要设计,是本阶段的核心产物,它是后续每一行 AI 生成代码的出发点,也是让 AI 编码从"写出来"到"写对了"的前提。

        四、Harness 驱动的 SDD 开发与质量保障

        Spec 能够说明要实现什么,但不能保证开发过程始终遵守规格。要让 SDD 从个人使用方式变成工程体系,还需要解决三个问题:Spec 如何生成,开发时如何执行,需求变化后如何持续维护。

        为此,我们在 SDD 工作流中引入 Harness,并通过桌面应用 CodingMaster App 承载这套改造后的工作流。Harness 不负责替代 AI 编码,而是通过约束和检测,让规格真正参与设计、实现、验证和归档;CodingMaster App 则让开发者不需要直接面对命令行,就能使用这套能力。

        4.1 整体方案

        整体方案可以归纳为四部分:

        • 方案来源:参考 OpenSpec 的开源规范管理方案,沿用 Proposal—Apply—Archive 的增量变更思路。

        • 流程改造:增加 Init 项目初始化,重构 design、task 和 spec 模板,并补充任务依赖与并行管理。

        • 质量增强:加入 Validate、Lint / Build、Verify、Coverage 等质量门禁,以及经验沉淀和持续偏离检测。

        • 系统分工:DevMaster 管理需求和项目资产,CodingMaster App 承载改造后的 SDD 流程,Harness 负责约束与检测。

        OpenSpec 提供规范管理基础,Harness 和相关工程能力是结合团队研发要求完成的扩展。

        图:DevMaster、CodingMaster 与 Harness 的整体关系

        4.2 Harness 如何约束和检测开发过程

        改造后的 SDD 工作流仍按 Init、Proposal、Apply、Archive 四个阶段推进,但每个阶段都增加了明确的约束和检测,避免只管理流程、不控制产出质量。

        4.2.1 Init:建立可信的项目基线

        约束:

        • 用结构化项目描述记录目标、技术栈、编码与架构规范、测试方式、业务领域和外部依赖。

        • 基线 Spec 统一格式,用 Requirement、Scenario 和 SHALL / MUST 表达需求与场景,不接受无法解析的自由描述。

        检测:

        • 扫描现有代码,生成基线Spec

        • 检查格式能否被正确识别。

        • 逐项核对 Spec 是否准确覆盖已有代码行为。

        产出:结构化项目说明和可机器解析的基线 Spec,为后续增量变更提供起点。

        4.2.2 Proposal:形成可执行的设计与任务

        约束:

        • 前后端分离的 design 模板,要求明确数据流、接口、异常处理、变更文件和依赖。

        • tasks 改为结构化元数据,包含唯一编号、状态、Do / Don’t、完成标准、修改文件和前置依赖。

        • 契约类前置变更单独拆入 pre_tasks;Spec 增量严格使用 Delta 格式。

        检测:

        • 检查任务依赖是否存在环或悬空引用。

        • 检查同一并行批次中的修改文件是否冲突。

        • Proposal 完成后执行严格校验,检查 Delta 格式、Scenario、Requirement 重名以及跨区冲突。

        产出:设计文档、结构化任务计划和 Spec 增量;只有依赖已满足且修改文件不冲突的任务才允许并行。

        4.2.3 Apply:在编码过程中执行质量门禁

        约束:

        • 编码前读取历史踩坑经验,避免重复历史错误。

        • 按照 tasks 中的依赖顺序和文件范围执行。

        • 加载项目 Skill 中的代码风格、命名和异常处理规则。

        检测:

        • 编码会话结束时在Stop Hook中自动触发:前端执行格式和静态规则检查,服务端按项目条件增加编译构建。

        • 必要时执行基于 Skill 规则的代码审查。

        • 实现完成后检查需求场景是否得到实现、代码是否偏离 Spec,以及是否存在无关变更。

        产出:通过基础工程检查和 Spec 一致性检查的代码,以及对应的验证报告;检查失败会返回当前任务修复,不能直接进入归档。

        4.2.4 Archive:完成归档、覆盖率和经验闭环

        约束:

        • 归档前必须先通过实现验证和测试覆盖检查,确认后的 Delta 才能合并回主 Spec。

        • 提交前再次检查归档是否完成,确保先归档、再提交。

        检测:

        • 测试场景分为 PASS、WARN、FAIL,判断是否存在明确实现证据。

        • 从开发对话中提取并过滤有价值的踩坑经验。

        • 记录代码变化、场景匹配、测试覆盖和变更追溯等过程指标。

        产出:更新后的主 Spec、验证报告、可复用的踩坑经验和过程度量;沉淀的经验会在下一轮 Apply 前重新加载,形成跨轮次闭环。

        图:Harness 在 Init、Proposal、Apply、Archive 中的作用

        4.2.5 归档后的持续检测:巡检 Agent

        Archive 完成后,代码仍可能在后续迭代中被修改,导致已归档的 Spec 与实际代码再次产生偏离;这种偏离往往是渐进式的,人工定期核对成本高、频率低。因此,我们引入了持续运行的巡检 Agent,作为 Harness 在归档之后的延伸。

        约束:

        • 已归档的 Spec 不允许被静静修改:任何导致偏离的代码变更均需被发现。

        • 修复只能以 PR 形式提出,涉及 Spec 变化的 PR 必须经过 Code Review,不能全自动合入。

        检测:

        • 定期或在关键代码变更时自动比对 Spec 与代码。

        • 发现偏离后自动生成修复建议。

        • 持续上报偏离趋势数据。

        产出:Spec–Code 对齐从“一次性归档验收”升级为“持续保障”,偏离能在早期被发现和拦截。

        4.3 为什么需要 CodingMaster App

        痛点:

        • 早期 SDD 工作流主要通过 CLI 交付,开发者需要记住初始化、提案、实现、验证和归档等命令。

        • 还需要理解目录结构和各阶段产物;流程本身能够运行,但学习成本影响了团队采用。

        定位:CodingMaster App 因此出现。它不是新的代码生成工具,而是 SDD 和 Harness 的图形化入口。

        三种模式:

        • Spec 模式:面向正式需求,完整走 SDD 流程。

        • 快速开发模式:面向小范围修改。

        • 对话模式:用于方案讨论和问题排查,不绑定 SDD 流程。

        Spec 模式如何使用:

        • 按步骤展示规格、设计、任务、代码差异和终端结果。

        • 开发者通过“下一步”推进流程,不需要记忆底层命令。

        • 关键产物仍需人工审核。

        图:CodingMaster App 的需求入口与过程预览

        4.4 检验与修复自循环:让测试问题回到原开发会话

        痛点:

        • 传统流程中,开发完成、提测、测试提 bug、开发定位、修复、通知验收,每个环节都靠人工衔接。

        • 信息在环节之间断裂,开发常常需要重新回忆需求当时是怎么实现的。

        方案:CodingMaster 与测试平台打通后,形成检验与修复的自循环:测试发现的问题自动关联到开发会话,自动发起修复,修复完成自动通知验收,循环直至用例全部通过。

        机制:

        • CodingMaster 保留需求对应的开发会话,包含 Spec、设计、任务、历史经验和代码变更。

        • 测试发现问题后携带需求信息,系统据此定位到原会话继续修复,避免重新解释需求和设计背景。

        • 相比冷启动只能看到问题描述和当前代码,复用原会话能看到完整的设计决策和已规避的踩坑,修复更贴合原有约束。

        闭环:修复完成后,结果再次进入测试验收;未通过则继续返回原会话,直到相关用例通过。这个闭环把 Harness 从代码检查延伸到测试结果验证。

        图:测试反馈与修复闭环

        4.5 效果与总结

        Harness 的价值不是生成更多代码,而是让规格得到执行、问题更早暴露、失败原因能够定位。CodingMaster App 则降低了这套流程的使用门槛。

        系统投入使用以来,已经完成了超过数百个需求,输出了数十万行代码,随着迭代深入,代码贡献率、SDD 新增行数呈稳步增长——团队对 AI 辅助开发的依赖度和信任度在持续上升。

        这些数据体现了三个方面:

        • 质量可保障:Harness 将检查前移,测试覆盖率由不足三成提升到接近七成。

        • 过程可度量:通过匹配度、覆盖率、迭代轮次和贡献率定位改进方向。

        • 结果可追溯:Spec 关联需求、代码和测试用例,巡检 Agent 持续发现偏离

        五、TestPilot:测试用例的生成与管理

        需求结构化之后,测试环节也需要同样的规范和自动化程度。长期以来,测试用例主要依赖人工编写和个人经验积累,格式不统一、检索效率低、新旧规则混杂,逐渐成为交付链路中最容易脱节的一环。

        5.1 测试环节面临的问题

        • 用例标准不统一:不同团队的用例格式、层级和写法差异较大,跨团队协作时需要反复对齐,历史用例难以直接复用。

        • 编写与执行分散:用例编写、任务分配、结果统计分散在多个工具中,环节多、易出错,进度和缺陷关联难以实时查看。

        • 业务知识依赖个人经验:历史逻辑和测试方法主要靠口头传承,新人上手成本高;原始需求文档非结构化、跨迭代分散,通用检索效率低。

        • 用例库随迭代膨胀:废弃用例和相互冲突的预期长期并存,同一测试点可能有多条矛盾用例,难以确定当前生效的规则。

        • 测试与开发脱节:双方主要靠人工沟通对齐,一旦需求或实现变更,另一方往往无法及时感知,同一问题需要反复确认。

        5.2 核心设计

        5.2.1 统一用例规范

        为解决格式不统一、难以复用的问题,规范体系覆盖五个维度:

        • 模板:前端和服务端使用不同的层级模板,明确各自需要填写的字段,也支持按业务线自定义。

        • 术语:统一维护页面和模块的名称与关系,避免同一功能在不同用例里叫法不一致。

        • 节点:用标准节点树约束用例的层级结构,并做必填项和格式校验,保证用例结构完整、可被机器解析。

        • 组件:把常见场景封装成可复用组件,例如多分支实验、多端一致性检查、执行结果标记等,编写时直接引用。

        • 标签:通过标签管理测试类型、优先级和自动化关联,方便筛选和统计。

        在统一规范之上,平台支持按模板逐层展开的手工编写方式,编写过程中可以直接引用标准术语和可复用组件,并实时校验结构完整性。除了手工编写,还提供三类辅助能力:

        • 历史用例搜索:用于新增功能场景,按需求、页面或测试点检索相似历史用例,减少重复编写。

        • 召回用例推荐:用于需求不变、技术方案调整的场景,按影响范围召回相关历史用例,快速组成回归集合。

        • AI 联想补全:输入部分用例内容后,自动联想并补全其余相关用例,提升编写效率和覆盖完整度。

        图:从需求到预期结果的结构化用例链路

        5.2.2 多来源 AI 生成用例

        规范建立后,系统支持从多种输入生成用例,覆盖不同研发阶段:

        • 从产品需求文档生成需求用例:适用于全部产线,输出结构化的需求覆盖用例。

        • 从前端技术需求生成前端用例:适用于已完成需求结构化的产线,输出结构化前端用例。

        • 从技术设计和接口约定生成服务端用例:适用于已完成结构化设计的产线,输出覆盖参数组合、边界和异常场景的用例。

        三类输入均经过解析清洗、需求点提取、历史用例对齐、用例生成和覆盖检查;结构化服务端场景还会增加质量门禁,在覆盖不足时自动修复,并支持多应用并发生成后汇总。

        5.2.3 任务管理与执行

        平台将用例组织为包含负责人和周期的执行任务,并支持任务创建、自动分配、进度统计和报告推送。

        5.2.4 有效用例治理

        有效用例树是当前版本下、覆盖全部功能的有效用例集合,用来回答“当前业务逻辑是什么”,而不是历史用例的简单汇总。它的目标是识别重复、冲突和过时的用例,收敛出统一口径,同时为用例生成和知识问答提供现行有效逻辑的对照基准。

        治理不是一次性动作,而是跨迭代比对、模型分析和人工确认相结合的持续过程:

        • 整合比对:以已确认有效的用例为基准,将新增用例按页面、模块和测试点分组,形成新旧用例的比对集合。

        • 模型分析:对每组用例判断关系——属于重复的保留较优版本,属于冲突的保留更合理的版本并说明理由。

        • 结果写回:为每条用例标记有效、已废弃或未扫描的状态,废弃用例指向被保留的有效用例。

        • 人工复核:测试人员对模型给出的结论做最终确认,可以调整保留、废弃或部分保留。

        判断重复和冲突时,主要依据文本相似度、逻辑矛盾、跨迭代重复和时间顺序,版本较新的结论通常优先保留。

        5.2.5 业务知识问答

        业务逻辑和历史决策容易分散在个人经验和零散文档中,通用问答工具面对非结构化、跨迭代的内容时,容易遗漏或给出不准确的答案,原因主要在于三点:原始文档结构松散、难以稳定提取;同一功能的信息横跨多个迭代和文档,检索时不集中;答案缺少明确出处,难以核实。相比之下,治理后的用例本身具备清晰的页面—模块—测试点结构,天然适合作为问答的知识底座,也能展示具体依据。

        早期问答主要依靠规则编排:先用固定规则识别意图,再执行一次检索并直接拼接结果,问法一旦变化就容易走错路径,答案也缺乏校验。现在的架构升级为模型自主规划检索路径:模型先理解问题、拆解成具体的检索计划,再按需调用不同的工具取数——统计类问题走统计工具,业务逻辑类问题走用例检索;取数完成后先进行结果校验,再以“思考—取数—结论”的方式流式呈现,使答案可以对应到具体用例,而不是一段无法核实的总结。

        图:问答 Agent 的思考过程示例

        图:问答结果可追溯到具体用例

        5.3 与开发侧的质量闭环

        测试用例治理和生成能力与开发侧质量闭环的衔接,见 4.4“检验与修复自循环”。

        5.4 实践效果与局限

        目前,这套方法已在数十条业务线落地,沉淀数万条测试用例,AI 生成占比超过一半。实践表明,基于结构化设计生成的用例,其准确率和覆盖率明显高于直接使用原始需求;业务问答升级为模型自主规划后,回答质量也有明显提升,有效用例治理已在部分产线灰度运行。

        体系效果仍依赖上游规格质量;用例冲突判断可能误判,高风险场景需要人工复核,业务问答也不能完全替代人工判断。

        六、工作方式的变化与结语

        6.1 引入系统后的工作方式变化

        过去,产品、开发和测试分别理解需求,质量检查集中在开发完成后,缺陷也依赖人工传递。DevMaster 以共享规格连接需求、设计、代码和测试,使工作方式发生以下变化:

        • 需求先结构化:产品需求经过澄清和人工确认,形成统一的验收规则。

        • 协作边界先对齐:完整需求拆分到相关应用,前端、服务端和测试共享接口约定与验收标准。

        • 规格驱动开发与测试:应用级规格继续生成设计、任务和测试用例,减少三方重复理解。

        • 质量检查前移:编码过程中持续检查团队规范、编译结果、设计一致性、需求覆盖和测试覆盖。

        • 问题回到原上下文:测试失败后,问题关联原需求、设计和开发记录,修复完成后重新验收。

        工作方式变化示意

        下面三幅图分别展示完整交付链路、系统整体关系以及引入系统后的研发流程。

        6.2 展望

        6.2.1 云端 SDD 开发流程落地

        未来将在云端完成代码生成、运行、调试和验证,减少本地环境准备,开发者主要负责关键方案与结果审批。

        6.2.2 自动化测试验证的接入

        未来将引入自动化测试工具完成业务功能验证,并接入开发闭环;未通过的用例自动触发修复和重新执行,人工介入高风险或结果存疑的场景。

        附录:

        术语表

        参考资料

        1. Alistair Mavin、Philip Wilkinson、Adrian Harwood、Mark Novak:《Easy Approach to Requirements Syntax (EARS)》,IEEE International. Requirements Engineering Conference,2009。DOI:10.1109/RE.2009.9

        2. Fission-AI:OpenSpec 项目。官方网站;GitHub 仓库.

        【推荐阅读】

         “携程技术”公众号

          分享,交流,成长

        跳转微信打开

        AI专栏 | 单点模型越堆越乱?携程酒店多模态平台如何让内容资产可治理

        2026年10月8日 16:30

        原创 Franky Yang 2026-10-08 16:30 上海

        拆解一套可评测、可灰度、可回滚的内容 AI 底座

        作者简介

        Franky Yang,携程技术专家,关注多模态与 AI 系统工程,尤其是知识与检索底座、平台架构以及系统的可靠性和持续进化能力。

        团队热招岗位:高级/资深Java开发工程师、算法专家-企业知识库方向、AI Agent工程师

        导读:随着酒店图片、视频等内容资产持续增长,图搜、首图精选、图片质检、视频理解等场景不断扩展,单点模型和独立链路逐渐难以支撑复杂的业务需求——重复计算、版本不一致、效果难以复现和回滚等问题,也开始成为多模态能力规模化落地的工程瓶颈。

        为此,我们建设了一套面向酒店内容场景的多模态理解平台,将数据接入、模型编排、向量检索、内容理解、评测灰度和治理回流串成完整闭环,让图片、视频和文本等内容资产能够被稳定理解、检索、复用和持续迭代。

        如果你正关注多模态 AI 工程化、向量检索、模型评测治理,或 AI 基础设施的平台化建设,希望这篇分享能带给你一些启发。

        一、背景信息

        二、从单点能力到平台化基建

        三、总体架构:数据、模型、检索与治理闭环

        四、数据底座:把模型结果变成可治理资产

        五、向量链路:面向大规模内容的检索中枢

        六、内容理解:从图片扩展到视频

        七、评测、灰度与可观测:让模型迭代可控

        八、阶段性效果与工程沉淀

        九、总结:可复用的工程经验

        一、背景信息

        酒店首图

        酒店相册

        酒店视频

        图搜酒店

        当用户预订酒店时,图片和视频往往比文字更先影响决策:房间是否宽敞、窗外视野如何、早餐区是否干净、泳池和健身房是否真实可用,这些信息都藏在海量内容资产里。

        但对工程系统来说,酒店图片和视频并不只是“展示素材”。它们需要被理解、检索、精选、质检和复用:用户想用一张图找到相似房型,运营希望从素材库中快速挑出适合首图的图片,平台需要持续识别低质、水印、拼接或误导性内容,视频也需要被拆解成可搜索、可审核、可摘要的结构化信息。

        随着内容规模持续增长,单点模型很难支撑这些复杂场景。图片分类、图文检索、质量检测、首图评分、视频摘要看似是不同问题,但底层都依赖同一件事:如何把多模态内容转化为稳定、可复用、可评测、可治理的数据资产。

        围绕酒店内容场景,我们建设的不是单点模型服务,而是一套面向图片、视频和文本资产的多模态理解平台。平台将数据接入、模型编排、向量检索、评测灰度和治理回流串成闭环,让图搜、首图精选、图片质检巡检、视频理解等场景可以在同一套底座上组合能力、复用资产、持续迭代。

        在真实业务环境中,平台面对的复杂度不只是“多跑几个模型”,而是大规模内容资产的长期治理:存量图片与视频、日新增素材、标签结果、质量分、风险识别结果、Embedding 特征和索引版本会共同形成多层衍生数据。内容规模越大,重复计算、版本不一致、效果不可复现和回滚困难就越容易变成系统性问题。

        二、从单点能力到平台化基建

        多模态项目早期往往从具体问题出发:图片分类、风险识别、图文检索、视频摘要等能力可以分别上线。但随着场景增多,如果每个需求都独立接模型、建数据链路、做评测和上线治理,系统复杂度会快速放大。我们希望建设的不是一批孤立能力,而是一个可以持续装配业务场景的内容 AI 平台。

        平台化之后,业务场景不再从零建设链路,而是按需组合能力模块:图片标签、质量分、Embedding、风险识别、向量召回、重排策略、人工反馈和评测集都可以像积木一样被复用。不同场景的差异,主要体现在积木的组合方式、阈值策略和业务约束,而不是底层链路的重复建设。

        三、总体架构:数据、模型、检索与治理闭环

        整体架构可以理解为一个面向酒店内容的多模态理解平台:底层接入图片、视频、文本和用户反馈,中间沉淀标签、质量分、风险结果、Embedding 和索引版本,上层通过模型编排、向量检索、任务调度、评测灰度和可观测能力对外服务。各层之间通过标准化协议和版本治理连接,避免模型、存储和业务逻辑深度绑定。

        在线链路面向低时延请求,优先读取已有资产;缺失时按策略触发计算,并通过降级、缓存和超时控制保证稳定性。离线链路面向增量回填、存量刷新和大规模索引构建,通过异步编排、批量调度和资源隔离提升吞吐。

        这套架构的关键不是引入某一个模型或某一个引擎,而是让每个组件都可以被替换、评测、灰度和回滚。模型在变化,数据规模在变化,业务诉求也会变化,基础设施必须先具备稳定演进的能力。

        3.1 典型场景如何在架构里跑起来

        不同场景使用的模型和阈值不同,但底层路径是相通的:先把内容资产标准化,再形成可复用的模型结果,最后通过检索、排序、治理或生产工具对外提供能力。

        3.2 链路实战:一次图搜请求如何跑起来

        以图搜 / 文搜图为例,用户或运营同学提交一张图片、一段文本描述或一组筛选条件后,系统并不会直接调用单个模型返回结果,而是经过“资产读取、特征生产、向量召回、结构化过滤、重排治理、反馈回流”几个阶段。每个阶段都对应前面提到的平台能力,也都可以独立评测、灰度和回滚。 

        这条链路的重点不是“多调用几个模型”,而是让每次模型升级、索引重建或排序策略调整都有明确的版本边界、评测口径和回滚路径。只有链路可治理,图搜能力才能从一次项目交付变成长期可迭代的基础能力。

        四、数据底座:把模型结果变成可治理资产

        多模态系统的第一层能力是数据底座。过去,模型输出常常只是一次接口调用的返回值;在平台化体系中,它需要被注册、存储、查询、评测和复用。

        • Schema 注册:为不同类型的算法结果建立统一描述,支持多版本演进、跨介质存储、压缩策略和降级策略。

        • 模型管理:将垂域模型、Embedding 模型和多模态大模型纳入统一注册体系,模型版本与数据 Schema 显式绑定。

        • 查算分离:优先查询已有版本化结果,缺失时再触发计算,减少重复推理并提升资源利用率。

        • 资源编排:在线请求走低时延同步通道,批量刷新和存量任务走异步通道,并通过优先级和集群隔离削峰填谷。

        • 中间结果缓存:支持多模型流水线编排、断点续跑、失败重试,让复杂任务具备工程可恢复性。

        数据底座的价值不只在节省算力,更重要的是把“模型结果”沉淀为组织可复用的工程资产。后续模型替换、场景扩展、效果回溯,都可以基于同一套资产体系完成。

        从量级上看,平台需要同时处理“原始内容规模”和“衍生结果规模”:一张图片或一个视频片段可能对应多类标签、多个模型版本、不同维度的质量/风险结果,以及多套 Embedding 和索引版本。随着存量回填、日常增量和模型升级持续发生,元数据平台承担的是长期可追踪、可回放、可复算的资产治理能力。

        把内容理解结果资产化:不只负责调用模型,还要把不同模型、不同版本、不同任务产出的结果统一写入元数据平台,供检索、精选、巡检和视频理解复用。

        五、向量链路:面向大规模内容的检索中枢

        多模态理解不仅要能“看懂”,还要能“找得到”。在酒店内容场景里,图搜和文搜图是最典型的检索能力:用户或运营同学可以用一张图片、一段文本描述、一个标签组合,找到语义相近、风格相似或满足筛选条件的图片与视频片段。向量链路承担的是高吞吐、低延迟、可扩展的召回底座。

        5.1 引擎可插拔

        我们在向量服务层屏蔽底层搜索引擎差异,将 Elasticsearch、Milvus、Zilliz 等能力抽象成统一接口。上层业务不直接依赖具体引擎,下层可以根据规模、延迟、召回效果和运维成本独立选型。

        5.2 索引全生命周期管理

        索引构建不是一次性任务,而是持续演进的工程系统。平台支持全量重建、增量回填、批量刷新、快速回滚和索引版本追踪,让模型升级、特征变更和数据扩容都有明确的发布路径。

        5.3 Embedding 统一评测

        Embedding 模型决定了跨模态召回的上限。我们将模型接入、评测集、离线 Benchmark、线上灰度和回滚串联起来,用统一口径比较不同模型在相关性、细节感知、延迟和资源成本上的表现。

        在部分检索链路中,通过引擎升级和索引结构优化,平均延迟和尾延迟都有明显下降,吞吐能力获得倍数级提升。更重要的是,这些优化被沉淀成可复用的接入基线,而不是只服务于单个项目。

        5.4 图搜链路的数据流

        以图搜和文搜图为例,系统不会把检索做成单一接口,而是拆成内容入库、特征生产、索引构建、在线召回和效果评测几段。这样 Embedding 模型、向量引擎、索引结构和重排策略都可以独立升级。

        六、内容理解:从图片扩展到视频

        内容理解层采用“垂域模型、Embedding 模型、多模态大模型”协同的方式。垂域模型负责稳定的结构化识别,Embedding 模型负责语义召回,多模态大模型负责更复杂的主观语义理解和泛化判断。

        6.1 图片理解的几类典型用法

        图片理解并不是单一“识别图片里有什么”的问题。落到酒店内容里,它通常会拆成质量、语义、风险和吸引力几类信号,再按不同场景组合使用。

        6.2 质检巡检闭环:从问题发现到样本回流

        质检巡检面对的是持续变化的问题空间:低质、遮挡、水印、拼接、误导性、合成内容等问题并不会一次性被穷尽。平台将离线巡检、在线抽验、人工确认和样本回流串成闭环,让新问题可以持续进入评测集和模型迭代流程。

        首图精选、图搜、质检巡检并不是三套彼此割裂的系统。它们共享图片标签、质量分、Embedding、风险结果和人工反馈,只是在不同场景里采用不同的组合方式。

        图片理解链路将检测、打标、语义理解和检索结果统一沉淀到元数据平台。这样做的好处是,下游不需要反复调用不同模型,而是按版本读取稳定结果;当模型升级时,也可以通过评测和灰度机制验证后再逐步替换。

        视频理解则采用“复用优先”的路线:先进行镜头分割和关键帧抽取,再复用已有图片理解能力完成分类、检测、打标和向量化,最后结合多模态大模型生成摘要、主题和可检索语义。这样可以把视频能力建设从重工程投入转为在既有图片能力上的薄层扩展。

        七、评测、灰度与可观测:让模型迭代可控

        多模态能力的难点不只是模型效果,还包括如何证明效果、如何稳定上线、如何在问题出现时快速回滚。因此,评测与实验能力必须内建到基础设施中。

        • Benchmark 套件:沉淀标准评测集,覆盖常见检测、检索、理解和生成类任务。

        • 自动化评测:模型提交后触发预跑、指标计算和准入判断,减少临时脚本和人工对齐成本。

        • 人工抽验:对主观语义、复杂风险和边界样本保留人工校验入口,形成模型迭代样本池。

        • 灰度与回滚:按模型版本、数据版本、索引版本和算子版本切流,出现异常时可快速回退。

        • 全链路监控:覆盖任务队列、计算资源、索引更新、检索延迟、模型命中和结果分布等核心指标。

        多模态模型的上线不应只看单次离线指标。更稳妥的方式是把离线评测、线上灰度、人工抽验和结果回流组合起来,让系统持续学习,同时保证发布过程可解释、可观测、可回滚。

        八、阶段性效果与工程沉淀

        经过平台化建设,多模态能力从“项目内能力”逐步沉淀为“跨场景基础设施”。图搜、首图精选、图片质检巡检、视频理解等场景可以复用同一套数据资产、模型注册、任务编排、向量检索和评测灰度能力;重复计算显著下降,模型接入周期由周级缩短到天级,检索延迟和离线资源利用率也获得明显优化。

        对工程团队来说,最大的变化是交付模式的变化:过去每个新需求都需要重新拼接数据、模型、脚本和评测;现在可以基于统一平台完成配置、接入、验证和发布。能力复用让团队把更多精力放在模型效果和产品体验上,而不是重复建设底层链路;新场景也可以通过组合已有能力快速试错、灰度和放量。

        九、一些可复用的工程经验

        先做资产化,再谈智能化。如果模型结果无法被查询、追踪和复用,智能能力越多,系统复杂度越高。

        模型要可替换,数据协议要稳定。多模态模型会持续演进,工程系统需要把模型变化限制在可控边界内。

        评测要平台化,而不是脚本化。只有评测集、指标、人工抽验和灰度流程沉淀下来,模型迭代才不会依赖个人经验。

        视频能力优先复用图片能力。通过关键帧和片段级建模,可以在较低成本下获得可用的视频理解链路。

        可观测和回滚是 AI 基建的一部分。模型上线后的分布漂移、延迟抖动和边界样本问题都需要工程化兜底。

        多模态 AI 的价值不只来自模型本身,更来自模型背后的工程系统。只有当数据可治理、模型可替换、计算可编排、检索可扩展、效果可评测时,多模态能力才能从一次次项目交付,真正变成长期复用的技术底座。

         “携程技术”公众号

          分享,交流,成长

        跳转微信打开

        AI 专栏 | 代码改了,文档却“死”了?携程机票“代码即文档”实践,让隐性知识随代码共同生长

        2026年8月28日 12:00

        原创 Sheila/舟遥 2026-08-28 12:00 上海

        破解知识熵增,让AI替你写“活文档”

        作者简介

        Sheila,携程资深研发经理,关注前端性能优化与 AI Agent 驱动的研发效能建设。

        舟遥,携程资深前端开发工程师,专注前端工程化与AI应用落地

        团队热招岗位:高级前端开发工程师

        导读:在敏捷开发的浪潮下,代码与文档的割裂几乎是每一支研发团队的“灵魂之痛”。携程机票前端团队主动向这一顽疾“宣战”,提出了“代码即文档”的理念,并自研了 Lumos 平台。通过将 CI/CD 流水线与 Dify 工作流深度融合,不仅实现了代码改动触发文档的自动生成与更新,更构建了覆盖 74 个业务仓库的智能知识库。这套体系将人工维护文档的时间压缩了 80% 以上,让“信息孤岛”连成一片,真正实现了隐性知识的显性化与组织资产的沉淀。

        一、背景

        二、问题分析

        2.1 信息分散与检索困难

        2.2 文档更新滞后

        2.3 代码改动影响难以追踪

        三、解决方案

        四、技术实现

        4.1 AI驱动的“代码即文档”模式

        4.2 知识库整合与智能检索

        4.3 代码改动追踪体系

        五、实践与应用

        5.1 自动化文档生成

        5.2 模块文档总结

        5.3 代码改动影响分析

        5.4 智能问答与实时协作

        5.5 实践效果

        六、下一步规划

        七、结语

        一、背景

        随着携程机票业务的快速发展,项目复杂度持续攀升,信息分散、文档更新滞后等问题日渐凸显。项目相关信息散布在多个异构系统中,开发者在进行代码修改时,难以快速追踪改动对业务逻辑的具体影响,导致开发效率显著下降。

        在传统开发模式下,文档维护高度依赖人工操作,往往在项目压力下被边缘化。开发者需要在多个平台间切换以获取完整的业务背景,而文档与代码的不同步进一步加剧了团队协作的复杂性。当功能逻辑发生变更时,相关文档可能仍停留在旧版本状态,造成团队成员对业务理解的偏差。

        为解决这一系列问题,携程机票前端团队提出了"代码即文档"(Code as Docs)的理念,并基于此构建了 Lumos 平台。通过持续集成流水线、Dify 工作流和智能问答系统的深度整合,实现代码改动与文档生成的自动化联动,确保文档与代码的实时同步。本文将详细阐述机票前端团队在这一自动化文档与代码分析体系上的构建过程与实践经验。

        二、问题分析 

        在携程机票前端团队的开发实践中,以下问题尤为突出,成为制约项目推进效率的主要瓶颈:

        2.1 信息分散与检索困难

        在大型软件项目的生命周期中,知识与信息的有效管理是确保开发效率和协同质量的关键。然而,在现有研发体系中,缺乏统一的知识管理工具,项目相关信息分散在多个异构系统中,直接导致了信息检索效率低下与上下文获取困难。项目信息,包括但不限于产品需求文档、技术设计方案、会议纪要、代码实现、合并请求记录以及线上问题复盘,分别存储在项目管理平台、文档知识库、代码托管仓库和企业 IM 等多个独立的系统中。这些系统在数据结构、存储方式和访问接口上各不相同,形成了一个个“信息孤岛”。

        这种分散化的状态,为开发者的日常工作带来了具体且可量化的挑战,主要体现在以下三个方面:

        认知负荷的增加:当开发者需要对某个模块进行修改或排查问题时,必须构建一个完整的“心理上下文模型”。这意味着他们需要在多个系统之间频繁跳转,拼凑零散的信息。例如,为了全面理解某个功能的背景,开发者可能需要追溯一条繁琐的链条:“原始需求文档 → 技术设计文档 → 代码的多次迭代历史 → 企业即时通讯群聊中的相关讨论”。这一过程不仅耗时费力,还容易因信息遗漏而导致对业务逻辑的片面理解,从而影响决策的准确性。

        检索效率的瓶颈:当前的检索机制大多依赖于基于关键词全文搜索。然而,这种方式在处理海量、异构数据时显得力不从心。开发者常常面临搜索结果“噪音”过多的问题,难以精准定位到核心信息点。更为棘手的是,许多关键的设计决策和逻辑演变过程,往往隐藏在非结构化的讨论记录或已归档的文档版本中,常规检索手段几乎无法触及。这种低效的信息获取方式进一步加剧了开发者的负担。

        信息一致性的风险:由于缺乏统一的数据源和同步机制,各系统之间的文档状态常常不一致。例如,某个在文档平台上已被标记为“废弃”的设计方案,可能仍然被新成员误认为是有效信息;某个在代码中已被重构的接口,其对应的文档可能仍停留在旧版本。这种不一致性不仅容易导致开发决策失误,还可能引入潜在的缺陷,成为项目质量的隐患。

        综上所述,这种分散化的状态不仅增加了开发者的认知负担,还显著降低了信息检索的效率,并带来了信息一致性方面的风险。这些问题若得不到有效解决,将对开发效率和项目质量产生深远的负面影响。

        2.2 文档更新滞后

        在敏捷开发和持续交付的背景下,代码迭代速度远超传统文档的维护能力,导致文档与代码实现之间的脱节成为普遍且棘手的问题。携程机票前端团队同样面临这一挑战,其根源在于现有流程高度依赖人工维护,缺乏自动化同步机制。文档滞后性主要体现在以下方面:

        维护优先级低:在紧张的项目排期和交付压力下,开发者将主要精力集中在功能实现与代码质量上,文档更新被视为“非紧急”任务,优先级被人为降低。新功能上线或代码重构后,文档更新常被延误甚至遗忘,导致“技术债务”不断累积,进一步削弱文档的实用性。

        静态内容的局限性:传统文档本质上是静态的,无法动态反映代码库的真实状态。例如,接口的请求参数或返回结构发生变化时,若 API 文档未能同步更新,将直接误导调用方,引发集成错误。这种静态性使文档在代码持续演进中迅速失去参考价值。

        缺乏与代码的上下文关联:文档与代码存储在不同系统中,缺乏原生的双向关联。开发者阅读代码时无法一键跳转到对应的设计文档,阅读文档时也无法快速定位到具体代码片段。这种上下文缺失不仅增加了理解成本,也使 Code Review 过程中评审者难以基于最新设计意图评估代码的合理性。

        文档更新滞后问题若得不到解决,将严重影响开发效率和代码质量,亟需通过流程优化和技术手段加以改进。

        2.3 代码改动影响难以追踪

        在大型、长生命周期的项目中,任何代码改动都可能引发连锁反应,准确评估和追踪这些影响是保障软件质量和系统稳定性的关键。然而,在携程机票前端团队的现有研发流程中,由于缺乏自动化影响分析工具,这一过程高度依赖人工,导致效率低下且风险增加。这一挑战主要体现在以下两方面:

        2.3.1 对业务逻辑的隐性影响

        在高度耦合的系统中,模块间的依赖关系复杂,一次看似局部的代码修改可能波及远超预期的范围。开发者在提交改动前,通常依赖“代码搜索”和“个人经验”判断影响范围。这种方式对显性的函数调用关系尚可应对,但对于通过事件总线、配置文件或动态调用等方式建立的隐性依赖,则几乎无能为力。

        此外,由于无法全面识别受影响的业务场景,回归测试的范围难以精确界定。这不仅增加了测试成本,还显著提高了线上问题的发生概率,为系统稳定性埋下隐患。

        2.3.2 对非功能性指标的影响

        代码改动不仅影响功能正确性,还直接关系到用户体验和技术健康度。以页面加载时间为例,当某次改动导致性能下降时,开发者通常需要手动对比修改前后的数据,逐步排查问题根源。这种方式不仅耗时费力,还容易因人为疏忽遗漏关键细节,影响诊断准确性。

        因此,引入自动化工具实时监控代码改动的影响并生成分析报告,不仅可以显著提升开发效率,还能帮助团队快速响应潜在问题,确保代码质量和性能始终处于可控状态。

        三、解决方案

        为应对传统开发模式中的信息分散、文档更新滞后和影响追踪困难等痛点,携程机票前端团队提出了“代码即文档”的核心理念,并通过三大策略来实现这一目标:统一知识库、自动化同步和智能分析。

        统一知识库策略通过将代码与需求描述整合到同一平台,团队落地了“代码即文档”的理念。利用 Git 进行版本控制与同步,确保文档与代码的统一存储和版本管理。每次修改都被精确记录,支持追溯历史版本,解决了代码与文档脱节的问题。所有文档变更通过 Pull Request 或 Merge Request 机制进行,集中存储于统一的代码仓库,打造单一可信的知识中心,降低协作成本,帮助新成员快速上手。

        自动化同步策略团队设计了一套事件驱动的自动化机制,确保任何代码改动都能被系统捕捉,并自动生成和更新相关文档。这种机制不仅解放了开发者的手动维护工作,还确保文档与代码保持实时一致,杜绝因信息过时引发的误解与决策风险。

        智能分析策略引入即时、量化、数据驱动的影响评估机制,自动评估代码修改对业务逻辑、系统性能、代码规范性等多个维度的影响。分析结果以结构化报告呈现,帮助开发者迅速洞察改动的潜在后果,优化决策,降低风险。

        三大策略协同配合,从信息整合、流程自动化和智能决策三个层面全面提升研发效能。

        四、技术实现

        为了支撑携程机票前端团队在文档管理中的解决方案,我们设计了一套完整的系统架构,涵盖信息分散与检索、文档更新滞后、代码改动影响追踪等核心问题的解决。以下是整体系统架构图,展示了各个技术模块的组成及其交互关系:

        基于该架构,我们将从以下三个核心问题出发,分别设计针对性的技术模块:信息分散与检索困难、文档更新滞后、代码改动影响难以追踪。每个模块通过自动化工具、智能分析和知识库整合,确保文档与代码的高度一致性,提升团队协作效率。

        4.1 AI 驱动的“代码即文档”模式

        在技术实现层面,AI 驱动的“代码即文档”模式通过智能代码分析、自动文档生成和动态更新机制,具体解决了文档与代码脱节的问题。以下是每个环节的技术细节和实现方法:

        4.1.1 智能分析:解析结构与依赖

        智能代码分析是"代码即文档"模式的基础环节,其核心在于通过 AI 模型解析代码结构、注释和函数签名,识别模块间的依赖关系、功能逻辑和接口定义。具体实现如下:

        1)从项目入口文件(如 index.js 或 main.ts)开始,利用静态代码分析工具提取模块间的依赖关系。

        2)分析入口文件中的 import 语句,构建模块依赖图,明确各模块间的调用关系。

        3)深入挖掘代码的语义信息,结合代码注释生成详细的功能描述。

        4)基于分析结果,生成包含功能描述、输入输出定义以及依赖关系的文档。

        5)结合历史版本信息,补充版本历史和改动说明。

        这一过程将代码中的隐性知识显性化,形成对项目模块分区和核心逻辑的清晰描述。系统实现了从代码到知识的自动化转化,为开发者提供直观的项目概览,同时为后续的代码维护和协作奠定基础。

        4.1.2 动态机制:变更触发文档更新

        为解决文档更新滞后的问题,团队通过 CI/CD 流水线与 Dify 服务 API 的结合,构建了一套自动化文档生成机制,确保每次代码改动都能实时更新文档。具体实现如下:

        CI/CD 流水线触发:每当有新的合并请求(MR)时,CI/CD 流水线会自动触发 Dify 服务 API,启动代码改动分析流程。这种机制确保文档更新与代码改动同步进行,避免了传统文档管理中的人工干预和滞后问题。

        Dify 工作流分析:Dify 工作流根据 MR 的 IID(合并请求 ID)进行内容分析,生成包含以下内容的 Markdown 格式文档:

          • 产品需求描述:从 MR 描述中提取需求背景和目标。例如,通过分析 MR 描述中的需求任务链接或标准化字段,提取需求的背景和目标。

          • 开发逻辑梳理:分析代码改动对业务逻辑的影响,生成业务逻辑的详细描述。

          • 代码分析:生成代码改动的详细分析,包括新增、修改和删除的代码片段。

          • 改动影响评估:结合性能指标(如 TTI、代码大小、ESLint 规则评分等),评估代码改动对系统的影响。例如,通过分析代码改动对页面加载时间的影响,生成性能指标的变化报告。

        标准化 MR 描述:为 MR 定义完整的标准格式(如包含需求背景、改动范围、性能指标等),帮助 AI 更准确地评估和总结本次改动内容。标准化的 MR 描述不仅提升了自动化分析的准确性,还为团队协作提供了统一的规范。

        文档存储与整合:生成的代码改动总结以 Markdown 格式存储,并整合到向量知识库中,支持后续检索和复用。团队成员可以通过知识库快速查询某次代码改动的详细分析和影响评估,显著提升信息获取效率。

        通过上述机制,实现了文档与代码的实时联动更新,确保了信息的准确性和一致性,同时大幅提升了团队协作效率。

        4.1.3 文档优化:实时与准确的平衡

        在自动化文档生成的基础上,团队通过结合手工调整机制,确保文档的实时性与准确性之间的平衡:

        自动化保障实时性:自动化生成文档是核心手段,通过 CI/CD 流水线触发 Dify 服务 API,确保每次代码改动都能实时更新文档。这种机制显著减少了文档更新的延迟,提升了团队协作效率。

        手工调整保障准确性:尽管自动化生成文档能够满足大部分需求,但文档平台也支持手工调整,团队成员可以根据实际需求对自动生成的文档进行修改和优化,确保最终内容的准确性。例如,当自动化生成的文档未能完全反映复杂业务逻辑时,团队成员可以通过手工调整补充细节。

        标准化与灵活性的统一:通过标准化 MR 描述提升自动化分析的准确性,同时保留手工调整的灵活性,满足不同场景的需求。这种结合方式既保证了文档的实时性,又确保了最终内容的高质量。

        4.2 知识库整合与智能检索

        生成的文档以 Markdown 格式存储,并通过向量化处理整合至知识库中,从而实现高效的检索与信息定位。向量化存储技术使团队成员能够通过自然语言查询快速获取目标信息,例如模块功能描述、依赖关系分析以及代码改动的影响评估。这种技术不仅显著提升了检索的准确性与效率,还支持复杂语义理解,满足多样化查询需求。

        智能问答系统基于向量化知识库,能够处理自然语言查询并结合上下文语义分析,返回精准结果。例如,团队成员可通过提问“XX 模块的功能是什么”获取相关技术细节;针对模块改动对系统性能的影响,系统可综合历史版本数据与性能测试结果,生成详细分析报告。此外,智能问答系统与团队日常协作工具深度集成,通过企业群聊机器人实现实时信息共享。当团队成员在群聊中提出技术问题时,机器人可即时从知识库中提取相关信息并返回结果,同时附带相关文档链接,便于进一步查阅。

        通过仓库管理系统与 AI 技术的结合,团队实现了文档与代码的同步更新,解决了信息分散与检索困难的问题。智能问答系统与实时协作工具的集成显著提升了团队沟通效率与问题解决速度,同时支持多维度查询与复杂语义分析。这种体系不仅优化了文档生成与检索的智能化水平,还为团队协作与项目推进提供了强有力的技术支撑,确保信息的高效流转与利用。

        4.3 代码改动追踪体系

        代码改动影响追踪体系旨在全面评估代码变更对系统的影响,包括性能指标分析、代码质量评估及多维度分析。通过与内部性能监控平台的指标关联,可以实现以下功能:

        性能指标分析:实时监控关键指标,如首次内容绘制时间(First Contentful Paint, FCP)、可交互时间(Time to Interactive, TTI)、累积布局偏移(Cumulative Layout Shift, CLS)以及 JavaScript 包大小变化。结合 AI 生成的性能分析报告,可快速定位性能瓶颈并提供优化建议。这种机制有助于提高问题排查效率,确保代码改动对系统性能的正面影响。

        代码质量评估:通过静态代码分析工具(如 ESLint、SonarQube 等)与 AI 助手的结合,全面评估代码改动对圈复杂度(Cyclomatic Complexity)、代码重复率(Code Duplication)、潜在漏洞(Potential Vulnerabilities)及代码异味(Code Smells)的影响。AI 助手可基于分析结果生成代码质量报告,帮助快速发现并修复问题,提升代码的可维护性。

        多维度分析:围绕用户行为埋点分析、A/B 测试评估及综合影响分析等方面,可以开发多种 AI 辅助工具。这些工具采用模块化设计,具备强大的数据整合能力,可关联分析性能指标(如服务器响应时间、API 调用频率)、用户体验指标(如用户停留时间、转化率)以及系统健康指标(如 CPU 使用率、内存占用),为未来拓展更多分析维度奠定基础。

        通过这种体系,可以实现对代码改动影响的全面追踪,为智能化支持的进一步拓展提供灵活的技术框架。它有潜力显著提升开发效率、代码质量和系统稳定性,同时为持续集成/持续部署(CI/CD)流程中的自动化决策提供数据支持。

        五、实践与应用

        5.1 自动化文档生成

        通过将 CI/CD 流水线与 Dify 工作流相结合,实现了代码改动的自动化文档生成。这一实践大幅提升了文档更新的效率,确保文档始终与代码保持同步,减少了手动维护的工作量。

        5.2 模块文档总结

        借助模块化代码解析 AI Agent,团队从入口文件自动生成模块文档总结,全面梳理了仓库中所有模块的功能描述与依赖关系。这一能力帮助开发者快速掌握模块的核心逻辑,降低了新成员的学习成本,同时为跨团队协作提供了清晰的参考。

        5.3 代码改动影响分析

        通过自动追踪代码改动对业务逻辑和性能指标的影响,团队能够生成详细的性能分析报告。这些报告涵盖关键指标,如可交互时间(Time to Interactive, TTI)以及代码包大小变化(Bundle Size Change),帮助开发者快速评估改动的潜在影响,确保系统性能和稳定性。

        5.4 智能问答与实时协作

        携程机票前端团队接入了智能问答系统和企业群聊机器人,实现了信息的实时共享与问题的快速解决。这一实践显著提升了团队的协作效率,减少了沟通成本,同时为开发者提供了即时的技术支持。

        5.5 实践效果

        5.5.1 规模化落地:从机票前端走向全研发体系

        Lumos 平台由机票前端团队自主研发,目前已从最初的前端场景验证走向跨团队规模化落地。当前已接入  74 个业务仓库,覆盖 7 个事业群/业务线,累计生成 1063 篇业务与变更文档,实现了知识库的跨团队、跨技术栈统一覆盖。

        5.5.2 知识库质量:从"有文档"到"可用文档"

        文档不仅是数量的积累,更是质量的迭代。Lumos 产出的文档分为两大类:

        • 业务文档:模块分析、技术实现、需求设计等,共 989 篇

        • 变更文档:CI/CD 流水线自动生成的代码改动分析,共 74 篇

        头部仓库的文档深度已达实用级别——最高单仓库累计 126 篇文档,4 个仓库文档总量超过 50 篇,为 AI Code Review 和新人 onboarding 提供了充足的上下文支撑。

        向量知识库覆盖:51 个仓库已同步至向量知识库,每个仓库拥有独立的数据集,支持基于语义的精准检索。检索阶段使用平台侧预配置的 Embedding 模型,在检索精准度与响应速度之间保持平衡。

        全局 AI 问答能力:5 个核心仓库已开通全局 AI 问答,开发者可通过自然语言直接查询仓库级业务知识。其中 2 个高频仓库还配备了专属对话机器人入口,提供仓库级别的深度对话体验。

        5.5.3 技术架构:Lumos-Skill 的检索增强管线

        Lumos 的知识库检索能力已产品化为 Lumos-Skill,可直接集成至 AI Code Review 流水线,实现"业务上下文 + 代码变更"的联合审查——通过让 AI Reviewer 在审查时自动查询业务知识库,弥补了单纯代码审查缺少业务视角的问题。

        5.5.4 效能提升:从人工到自动化的范式转变

        Lumos 的核心价值在于将开发者的"信息获取成本"趋近于零,具体体现在:

        • 文档维护成本:传统模式下,开发者需在功能开发之外额外投入 20-30% 的时间维护文档;Lumos 通过 CI/CD 自动触发工作流,MR 合并即生成文档,人工维护时间下降 80%+。

        • 新人 onboarding:新成员加入项目时,通过 Lumos 知识库可在 1-2 天内建立完整的模块认知,相比传统的"读代码 + 问老员工"模式,上手周期缩短 60%+。

        • Code Review 质量:通过 Lumos-Skill 为 AI Reviewer 提供业务上下文后,review 意见的"业务逻辑正确性"维度检出率显著提升——Reviewer 不再仅关注代码风格,而是能基于业务背景判断改动的合理性与风险点。

        • 知识沉淀:散落在个人头脑中的隐性知识,通过 Lumos 的系统化采集、向量化存储,转化为团队共享的组织资产,实现从"人走知识丢"到"知识随代码生长"的转变。

        六、下一步规划

        基于当前平台的能力,机票前端团队在代码改动影响追踪方面已经取得了显著成效,未来将沿此路径持续深耕,并进一步将前端侧的实践经验推广至更广泛的集团研发场景:

        • 知识库从检索到推理的能力升级

        在现有通过代码反推业务需求的基础上,逐步引入图谱化关联,将代码实体、推导出的业务规则与变更历史形成结构化语义网络。目标是让 AI 不仅能还原单点需求,还能理解需求之间的依赖与演进脉络,在影响分析时提供更完整的业务上下文。

        • AI Code Review 与业务语义的深度结合

        在现有代码审查辅助的基础上,融合代码所承载的业务语义进行审查——不仅检测代码层面的缺陷,还能识别改动是否与既有业务规则产生冲突。逐步覆盖安全合规、性能风险、跨模块业务一致性等场景,使审查建议从"代码规范提示"演进为"业务风险诊断"。

        • Harness 范式下的产出校验与效果度量

        重点建设 AI 输出质量的量化评估体系,包括需求还原文档的准确率(precision)与覆盖率(recall),以及 Code Review 的发现率与误报率等核心指标。通过与人工审查结果的交叉验证,形成度量反馈闭环,驱动模型持续迭代,确保 AI 产出稳定满足工程质量标准。

        七、结语

        通过自动化工具与智能技术的深度结合,携程机票前端团队初步践行了"代码即文档"的理念,在代码改动影响追踪与逆向需求还原方面取得了阶段性成效。从最初解决前端团队自身的文档痛点,到如今 Lumos 平台服务于多个事业群的研发体系,机票前端团队以工程实践证明了"代码即文档"理念的可行性与可推广性。

        下一步,我们的重心将从"能力建设"转向"质量收敛"——在 Harness 范式下建立系统化的输出校验机制,量化评估需求还原文档的准确率与完整性,持续度量 AI Code Review 的检出率与误报率。

        我们相信,只有将评测体系做扎实,才能让 AI 辅助研发从"可用"走向"可信赖",真正成为团队日常工作流中稳定可靠的一环。

        【推荐阅读】

         “携程技术”公众号

          分享,交流,成长

        跳转微信打开

        AI专栏 | 让Agent学会“不贰过”:从一次纠偏,到采纳率翻倍的工程实践

        2026年8月20日 17:00

        原创 Li Yi 2026-08-20 17:00 上海

        人工对 AI 的结果做高质量决策

        作者简介

        Li Yi,携程资深后端开发工程师。关注 AI Agent 进入真实环境后如何继续获得经验,把经验沉淀为可复用的认知,并从用户视角持续拓展它能解决的问题。

        团队热招岗位:高级/资深Java开发工程师、AI Agent工程师、AI Infra 研发工程师、大模型算法工程师

        导读:Agent 答错后,人补一句正确答案并不难。真正困难的是:下一次遇到相似问题时,它能不能自己用上这次纠正;业务发生变化后,过去有效的做法能不能被重新检查;又怎样证明这次修改真的让 Agent 变得更好,而不是碰巧答对,或者修好这一类却让别的问题变差。

        我们为此建立了一条从生产反馈出发的改进链路。系统保留 Agent 回答问题时的完整过程,找出错误从哪一步开始,把专家判断整理成候选知识,在隔离环境中重跑历史问题,经维护者审核后写回。修改后的 Agent 继续处理真实问题,新记录再回到同一条链路中。

        这套机制已经用于多个业务 Agent。在与携程酒店技术支持团队的共建中,两类明确接入该流程的 Agent,一线采纳率分别从约 20% 提升到 40% 以上、从约 40% 提升到 60% 左右。这里的“采纳率”,指一线人员认为 Agent 回答可以直接采用的比例。本文从一个具体错误开始,说明一次人工判断怎样变成 Agent 后续会持续使用的能力,以及这条链路为什么仍然需要验证和人工治理。

        一、为什么“库存不足”仍不是完整答案

        二、怎样让一次纠正影响下一次答案

        三、系统怎样判断Agent错在哪里

        四、一项修改为什么值得被保留

        五、怎样让一条经验帮助更多同类问题

        六、人和基础设施各自负责什么

        七、怎样判断这套方法是否产生价值

        一、为什么“库存不足”仍不是完整答案

        一位用户很早创建了一笔需要企业审批的酒店订单。订单创建时尚有房间,但系统不会立即向商户确认订单并锁定房间,而要等审批通过后才真正执行。等审批完成,房间已经被其他订单订走了。

        排障 Agent 查到执行时没有库存,于是回答“库存不足”。这句话描述了失败发生时的状态,却没有回答用户真正关心的问题:为什么很早创建的订单,最后仍然没有订到房?

        问题出在时间线上。Agent 看到了执行失败时的最终状态,却漏掉了创建与执行之间的审批过程。订单创建时间和房间真正被锁定的时间不同;等待期间发生的状态变化,才把“很早提交”和“最后失败”连成完整的因果链。

        图 1:最终状态只能说明失败时发生了什么;完整原因还要包含提交与真正生效之间的过程。

        这类问题并不只存在于酒店业务。申请提交后等待审核、任务创建后等待调度、支付发起后等待清算,都存在“已经提交”和“真正生效”之间的间隔。如果 Agent 只看最后一刻的状态,就容易把结果当成原因。

        传统做法通常有两种:业务人员直接改对当前答案,或者补一条“遇到某类订单就检查审批”的规则。前一种做法只关闭了这次问题;后一种做法依赖具体名称和触发词。用户换一种说法,或者同样的机制出现在另一个场景,Agent 仍可能重复犯错。

        真正值得留下的不是这次答案,而是一条可以迁移的业务知识:请求提交不等于操作真正生效;存在中间流程时,解释最终失败前要先检查等待期间发生了什么。

        二、怎样让一次纠正影响下一次回答

        要让这条知识影响下一次问题,系统不能只保存问题和最终答案,还要保留 Agent 当时怎样得到答案:调用了哪些工具、传入什么参数、拿到哪些结果,又依据这些信息作出什么判断。

        改进系统随后检查这条执行过程,找出错误从哪里开始:是缺少必要信息,已经拿到字段却理解错了,还是信息足够但没有完成推理。专家提供的判断会先被整理成候选知识,去掉订单号、活动名和一次性返回值,保留适用条件和判断原则。

        候选知识不会直接进入生产。系统先把它写入测试版本,在历史问题上重新运行,确认它确实被 Agent 使用、结果变化能够解释,而且没有让原本能正确处理的问题变差。通过验证并经维护者审核后,它才会写入 Agent 下一次运行时加载的工具说明、业务规则或提示词。

        图 2:改对当前答案只能关闭一个问题;只有候选知识经过验证、审核和写回,才影响下一次回答。

        本文把这条持续链路称为受人工治理的 Agent 自进化。业务 Agent 仍然负责回答用户问题;另一套改进系统读取它留下的执行记录,分析错误、提出修改并回放历史案例。维护者决定哪些修改能够进入生产,新版 Agent 则继续运行并产生下一轮反馈。

        一次变化要构成这样的自进化,需要同时满足四个条件:反馈来自 Agent 自己的真实运行;系统能根据反馈修改 Agent 后续仍会使用的内容;修改经过验证和人工选择;修改后的 Agent 继续产生新反馈。少了其中任何一环,都更接近一次普通优化,而不是持续循环。

        三、系统怎样判断 Agent 错在哪里

        生产记录和标准评测集不同。它通常没有一份稳定、干净的标准答案:失败问题原来的结论可能就是错的;成功回答也可能只是碰巧命中,实际推理并不成立;同一种知识缺失,在不同执行记录中还可能表现为调错工具、传错参数、漏看字段或最终判断错误。

        因此,系统不能只把问题文本和最终答案攒起来做分类。它需要读取从问题输入、工具调用、中间结果到最终回答的完整过程,逐步检查 Agent 还缺什么信息、哪个字段被误解,以及哪项已经取得的信息没有进入最终判断。

        常见错误大致有三类:

        信息已经足够,但推理没有走完。前面的订单案例就属于这一类:Agent 已经查到执行时没有库存,却没有把审批和时间差加入因果链。

        字段已经拿到,但不知道它在业务上意味着什么。例如某项优惠无法使用,真正的判断依据可能是请求来源。这个字段早已存在于工具返回中,Agent 却不知道它与使用资格有关。此时不需要增加数据源,只需要把字段含义写清楚。

        现有工具确实拿不到必要信息。系统会先确认已有工具是否能够补足证据;仍然缺失时,再提出需要增加什么查询,并在只能读取、不能修改生产数据的隔离环境中验证。未经维护者审核,新的查询能力不会进入生产。如果根因属于业务系统缺陷,或者所需信息根本不存在,系统会停止继续尝试,把已经排除的方向和最接近的线索交给人。

        人工反馈也要按可信程度分别使用。专家有时给出明确结论,有时只提供排查方向,也可能暂时没有答案。

        仍以前面的订单为例。假设专家已经判断“审批造成的时间差才是真因”,如果分析模型一开始就拿到完整结论,它可能沿着答案拼出一条看似合理的解释,即使执行记录里没有足够证据。因此,分析阶段只得到“检查审批流程”这样的方向,并先从执行记录中寻找依据;完成分析后,另一道评估再检查分析结果是否与专家判断一致,以及记录中的证据能否支撑这一结论。

        这一阶段的产物不是“这条订单应该回答什么”,而是换一个订单、换一种表达仍然成立的候选知识。只有当它说明了适用条件和判断原则,并通过后续验证,才值得被长期保留。

        四、一项修改为什么值得被保留

        自动提出修改并不等于已经学会。答案发生变化,可能是新知识真的起作用了,也可能只是下游数据已经不同,或者 Agent 偶然走到了另一条路径。

        判断一项修改能否保留,需要同时回答三个彼此独立的问题。它们不是依次发生的三步,而是并列的三个条件。

        生效性:修改真的被 Agent 使用了吗?

        知识已经写入测试版本,不代表它一定进入了执行。系统需要从执行记录确认新版内容已经加载,并真正影响了工具调用或判断。如果改了但没有用上,就不能继续把答案变化归因于这项修改。

        可归因性:答案变化来自修改,还是外部数据变化?

        历史问题发生后,库存、订单和审批状态仍会变化。如果回放时重新查询今天的数据,修改后的运行与原始记录面对的就不是同一组事实。例如,事后有人取消订单,今天查到的库存可能已经恢复;这时答案发生变化,未必是因为 Agent 学会了新的知识。反过来,如果禁止 Agent 发起历史记录中没有出现过的新查询,它又无法尝试新的排查路径,例如补查审批完成时间。

        因此,历史记录中已经出现过的同名、同参数调用,回放时优先返回当时保存的结果。修改前后的 Agent 先面对同一份基础事实,判断差异才可能来自新加入的知识。

        如果修改后的 Agent 开始查询审批时间,而历史记录没有保存这次调用,系统可以让它在只读环境中发起一次实时查询,并明确标记结果来自今天。这类查询验证的是:Agent 是否学会了主动查询这项信息,以及当前接口是否可用。它不用于还原几个月前的业务现场,也不能据此判断当时查询会得到什么。

        如果只想比较新旧 Agent 的判断方式,系统会关闭所有新增查询,让两者完全基于当时保存的数据重新回答。我们把这种方式称为完全冻结回放。

        安全性:修好当前问题,有没有伤害其他问题?

        验证不能只盯住当前错误,还要重跑一批原本能正确处理的历史问题。即使当前问题变好,只要新知识让其他问题变差,也不能进入生产。

        图 3:生效性、可归因性和安全性是三个并列判断;缺少任何一项,都不足以把候选修改带回生产。

        证据是否充分、执行路径是否改变、最终结论是否改善,也由不同角色分别判断,而不是让同一个模型先下结论,再为自己的判断寻找理由。在内部评估中,由单一模型同时分析和裁判时,无效修改被误判为有效的比例曾在三成左右;拆分职责并增加“修改必须实际生效”的条件后,这一比例下降到个位数百分比。

        自动检查完成后,候选修改只有三种出口:证据充分则提交维护者采纳;信息不足则返回继续分析;无效或伤害其他问题则拒绝。系统负责提出候选并整理证据,维护者负责决定哪些变化值得被长期保留。

        五、怎样让一条经验帮助更多同类问题

        一条执行记录已经足以发现新的业务知识,这对低频、长尾问题尤其重要。但当同一种错误反复出现时,每次都从头分析并不经济。随着经过验证的问题逐渐积累,系统会进一步对照同类问题的成功和失败过程,寻找能够复用的共同做法。

        它不会简单汇总每条问题的最终答案。答案相同,不代表推理过程正确;问题文本相似,也不代表错误原因相同。

        假设后来又积累了十条“很早提交却最终失败”的问题。Agent 回答正确的记录通常都会检查提交时间、审批完成时间和房间状态变化;回答错误的记录往往只检查最后的库存。两组记录一对照,系统就能发现:失败最常发生在没有检查中间流程这一步。

        “存在延迟生效流程时,要检查等待期间的状态变化”由此成为一条候选通用做法。系统还会过滤活动名、渠道名、订单号等只属于个案的信息,避免把一次特殊处理误写成共享规则。候选做法随后要在这批问题上共同回放,确认它确实帮助了同类问题,也没有伤害其他场景。

        图 4:单条记录用于发现新事实,同类记录用于提炼共同做法;两种结果都要经过验证和人工审核。

        通过审核的内容会进入可信经验库,并保存它来自哪些生产记录、经过什么验证、适用于什么条件以及属于哪个版本。未经验证的结论不会入库,已经入库的经验也不是无需检查的标准答案,每次仍要结合当前证据使用。

        目前,经验库主要由改进系统使用:当下一条错误记录进入分析时,系统会先查找过去有没有类似经验,以减少重复排查。

        尚未完全打通的是业务 Agent 的前置使用。当用户刚提出一个新问题时,业务 Agent 还不能稳定地在回答前自动找到并采用已有经验。因此,系统已经能够加快“错误发生后的改进”,但还不能保证在错误再次发生前就阻止它。

        六、人和基础设施各自负责什么

        “自进化”容易让人联想到系统不再需要人。生产环境中的实际情况恰好相反:机器适合承担可以重复、可以批量验证的工作,人则保留对业务真因和生产发布的责任。

        业务专家最有价值的输入,通常不是重新写一整份规则文档,而是指出真正原因的一句话。例如:“创建时有房,不代表审批完成时仍有房。”过去,这句话可能只用于关闭当前问题;现在,系统可以据此查找相关执行记录、提出候选修改、批量回放历史问题并整理证据。专家不必亲自完成每一步,但仍要判断证据是否成立、适用范围是否过宽,以及修改能否进入生产。

        人的位置因此发生了变化:从逐条搜索和手工改写,转向提供准确的判断和排查方向、审核证据,并治理生产变化。一次经过验证的判断,可以影响后续一类问题,而不只影响当前一条记录。

        权限也要随着任务阶段分开。分析系统只读取历史记录的副本,因此不需要修改生产;需要重新调用工具时,任务进入只能查询、不能写入生产数据的隔离环境;只有修改通过验证和人工审核后,专门的发布流程才取得写入权限,并记录修改人、版本和回滚点。这样,即使分析系统提出了错误建议,也不能绕过审核直接改变生产 Agent。

        并不是所有 Agent 都能直接接入这套机制。至少要满足三件事:

        看得见。系统除了最终答案,还要能看到 Agent 调用了哪些工具、传入什么参数、拿到什么结果,以及怎样作出判断。否则只能知道它答错了,不知道错误从哪一步开始。

        改得动。Agent 后续使用的工具说明、业务规则和提示词需要能够单独更新、比较版本和回滚。否则即使找到了问题,也没有一个安全的位置承接修改。

        有人负责。必须明确由谁审核、谁批准发布,以及出现问题后谁负责回滚。系统可以提出修改并提供验证结果,最终是否进入生产,仍由对应 Agent 的维护团队决定。

        七、怎样判断这套方法是否产生价值

        接入了多少 Agent、生成了多少候选、采纳了多少修改,只能说明系统在运行。真正需要回答的是:一线是否愿意采用新版 Agent 的回答,处理问题是否更快,最终用户是否感受到改善。

        酒店技术支持团队提供了一个较完整的观察样本。这个团队每月处理上万条问题,其中大量场景低频、信息不完整,固定规则很难持续覆盖。

        在两类 Agent 上,接入前后的变化最为直接。负责排查房价、库存和售卖状态的 Agent,采纳率从约 20% 提升到 40% 以上;负责促销问题的 Agent,采纳率从约 40% 提升到 60% 左右。前者每周覆盖一百余条问题,后者每周覆盖两百余条问题,并非少量孤立样本。

        把范围扩大到整个协作体系,总采纳率由 25.9% 提升到 51.7%。2026 年 6 月,AI 有效覆盖率达到 48.08%。这个指标的含义是:在技术支持团队经手的全部问题中,由系统自动转移且没有回流、由系统自动解决,或者 Agent 诊断结论被一线采纳的三类问题,合计占 48.08%。

        对于 Agent 确实提供有效帮助的问题,相比纯人工处理,解决时长中位数缩短约 40%;在业务量和处理人力基本相当的情况下,及时解决率同比提升约 4.9 个百分点。

        这些整体结果不能全部归因于自进化系统。同期还进行了工具与业务知识整理、已有 Agent 复用、问题自动分流和部分场景自动处理。更准确的结论是:自进化补上了“从真实错误中持续发现 Agent 不会的地方,并形成经过验证的修改”这一环;最终业务结果来自工具、Agent、平台和一线团队共同形成的协作链路。

        系统内部还要单独判断每次修改的净收益:有多少原本答错的问题在修改后真正答对,又有多少原本答对的问题被新知识带坏。前者增加而后者接近零,才说明这次变化值得保留。业务指标用于判断这条方向是否值得继续投入;历史回放则用于确保每次具体修改不会以伤害其他问题为代价。

        还有两项能力需要继续完善。其一,历史问题集需要覆盖更多类别,避免验证只围绕当前问题;其二,业务事实会变化,系统仍需要更完整地识别哪些经验已经过时,并重新验证。明确这些边界,比把一次阶段性提升误认为永久能力更重要。

        结语

        Agent 自进化不是让系统在没有约束的情况下随意修改自己。它是一套具体的工程过程:从真实运行中取得完整反馈,找出错误从哪一步开始,把专家判断整理成候选知识,通过历史回放和人工审核决定是否保留,再让新版 Agent 回到生产继续接受新反馈。

        模型会继续变强,业务事实也会继续变化,低频问题不会因为一次升级而消失。真正困难的不是让 Agent 把当前答案再说一遍,而是让一次错误留下可以复用、可以验证,也可以在过期后重新检查的知识。

        过去,专家的一次判断往往只关闭一个问题;在这条链路中,一次经过验证的业务判断,有机会改变 Agent 之后处理一类问题的方式。被持续放大的不是某一句答案,而是人对真实业务的理解。人原来逐条救火,现在只在真需要判断的地方出手。在这个体系中,人工要做的不再是逐条看工单的体力活,而是要对 AI 的结果做高质量决策。

        【推荐阅读】

         “携程技术”公众号

          分享,交流,成长

        跳转微信打开

        AI专栏 | 每天被 oncall 打断到无法写代码?携程机票前端用这套方法把重复问题解决了2/3

        2026年8月6日 17:00

        原创 Sheila 2026-08-06 17:00 上海

        让研发从“救火”回到“建设”

        作者简介

        Sheila,携程资深研发经理,关注前端性能优化与 AI Agent 驱动的研发效能建设。

        团队热招岗位:AI Agent开发工程师

        导读:每天被拉群、被私聊、被问同样的问题——携程机票前端团队的oncall曾一度占据研发大量精力。过去6个月1000+条事件统计显示,近一半是“接口参数确认”“业务逻辑解释”这类高重复问题。团队用一套“飞书多维表格+知识问答+机器人”的组合方案,把重复劳动从40%打到15%,单次处理时长从100+分钟压缩至40分钟。怎么做到的?本文拆解完整落地路径。

        一、背景介绍

        1.1 提效场景介绍

        1.2 痛点分析

        1.3 提效目标

        二、解决方案

        2.1 使用的飞书工具和方案亮点

        2.2 提效的实现路径和步骤

        三、业务价值

        3.1 提效情况和前后对比

        3.2 应用成果分享

        3.3 后续规划

        本文分享的 oncall 体系由携程机票前端团队搭建并落地实践,聚焦机票业务场景下的研发 oncall 痛点,以前端视角切入,打造知识驱动型研发支持体系。

        一、背景介绍

        1.1 提效场景介绍

        在业务高速增长、系统复杂度不断提升的背景下,携程机票前端研发团队的 oncall 已从偶发支持演变为高频、刚性的日常工作。大量精力被消耗在排障、业务逻辑解释、接口参数确认等事务性工作上,持续挤压了团队在架构优化和产品创新上的投入。

        传统 oncall 依赖零散的 IM 私聊、电话、邮件等非结构化渠道,缺乏统一入口和可追溯记录;问题处理状态不透明,责任边界模糊;解决方案沉淀严重不足,同类问题反复出现、重复解答,既影响研发体验,也拉低整体研发效能。在此背景下,机票前端团队开始系统性思考:如何通过"知识库 + 流程"重构研发 oncall 体系——这正是本文希望回答的核心问题。

        1.2 痛点分析

        1.2.1 Oncall 定义与范畴

        研发 oncall 是研发团队在约定时段内处理与业务系统相关的突发技术事件或高优先级咨询的机制。典型场景包括:

        • TS 排障与工单升级

        • 产品逻辑与业务规则问询

        • 接口字段、参数、返回值确认

        • 特定活动/版本的配置与风控规则解释

        参与角色横跨 TS、产品、运营、研发、运维等多个职能,是连接业务与技术的“最后一道防线”。

        1.2.2 Oncall 来源与占比

        基于携程机票前端团队对过去 6 个月、1,000+ 条研发 oncall 事件的脱敏统计,我们得到以下结构性结论:

        • 按发起方

          • 技术支持:约 1/3

          • 产品经理:约 1/4

          • 运营:约 1/5

          • 测试 & 研发/运维:其余约 1/5

        说明 oncall 已成为多角色、多团队的交汇点,问题来源分散。

        • 按问题类型

          • 业务逻辑咨询:约 26%,重复率 ~64%

          • 接口参数/字段确认:约 21%,重复率 ~70%

          • 系统异常排查:约 17%,重复率相对较低(~28%)

        前两类“解释型”问题合计接近一半,且高重复、高可标准化。

        • 按处理结果

          • 仅为简单确认/解释:约 43%

          • 小修改/配置调整即可解决:约 29%

        说明相当比例的 oncall 并非“技术难题”,而是信息获取与知识暴露问题。

        以“接口参数确认类问题”为例:单次平均处理耗时约 0.4 小时,同一问题在 6 个月内重复出现 20+ 次,累计浪费数十小时研发人力;同时还伴随上下游沟通协调成本。

        1.2.3 问题分析:来源杂乱、状态不清、无知识沉淀

        结合定性访谈与数据分析,机票前端团队识别出当前研发 oncall 面临至少三类系统性问题:

        • 来源杂乱,缺乏统一登记

          • 问题入口分散在飞书私聊、群聊、电话、邮件等多个渠道

          • 事件往往缺乏“工单化”记录,无法准确统计 oncall 真实负载

          • 值班人员接收信息零散,排期难以掌控,容易“漏接”与“重复接”

        • 处理状态不透明,协作效率低

          • 提交方难以获知当前处理进度与负责人

          • 相同问题在不同渠道多次被提起,进一步放大负载

          • 事件优先级与升级规则不清晰,紧急任务易被信息噪音淹没

        • 缺乏知识沉淀,重复劳动严重

          • 解决方案散落在聊天记录、个人笔记和过往经验中

          • 缺少结构化的知识条目与统一检索入口

          • 新人或外部团队很难快速自助获取答案,只能继续“问人”

        结论:当前模式本质上是“事件驱动 + 人肉协作”的即时通信体系,缺少标准化 SOP 和知识闭环,导致 oncall 事件“越处理越多”,形成恶性循环。

        1.3 提效目标

        核心问题:减轻 oncall 工作量,而不是取消 oncall。

        oncall 本质上是保障业务连续性和用户体验的必要机制,无法也不应被简单取消。需要解决的,不是“要不要 oncall”,而是“哪些 oncall 必须由人来做、哪些可以交给系统”和“在人必须介入时,如何把每次的处理成本打到最低”:

        • 将尽可能多的高频、标准化问题,从“必须人工处理”转变为“优先由系统自动解决”;

        • 在必须人工介入的场景下,通过流程与工具优化,显著降低单次处理成本。

        因此,携程机票前端团队将本项目目标定为:在不牺牲业务稳定性的前提下,系统性减少 30%~50% 的 oncall 事件量与人力投入,使研发从"被动救火"回到"主动建设",具体体现在:

        • 统一入口与流程,形成可统计、可追踪的工单体系;

        • 知识优先匹配,能自动解决的尽量自动解决;

        • 强制知识沉淀,形成“越用越聪明”的正向循环。

        二、解决方案

        2.1 使用的飞书工具和方案亮点

        围绕上述痛点,携程机票前端团队提出“知识驱动型研发 oncall 体系”,核心理念是:

        让“知识”和“流程”成为 oncall 的第一责任人,让“人”更多处理边界与例外。

        具体目标包括:

        统一入口与流程:所有 oncall 通过标准化提需入口进入多维表格工作台,形成可统计、可追踪、可分派的工单。

        知识优先匹配:每个新 oncall 先自动匹配知识库与历史记录,能自动解决的尽量自动解决。

        标准化 SOP 流程:从提需、分派、处理到闭环确认,每一步都有明确责任人与状态。

        强制知识沉淀:每一个完成的 oncall 事件,都对应一条结构化的知识资产,形成“越用越聪明”的正向循环。

        基于飞书生态,我们构建了一套“多维表格 oncall 工作台 + 知识问答 + 机器人 + 话题群”的组合方案,在不引入新系统的前提下完成改造。

        2.1.1 Oncall SOP:从提需到闭环的标准流程

        流程概览 -标准化 SOP 被抽象为四个阶段:

        1)提需:

          • 统一从飞书“提需入口”提交 oncall 需求(应用 / 消息卡片 / 多维表格表单)

          • 强制填写关键信息:业务线、问题类型、优先级、影响范围、相关链接等

        2)智能分派:

          • 按业务线、模块与问题类型自动路由到对应值班组

          • 支持按轮值规则与负载情况自动指定责任人

        3)机器人 oncall(知识优先):

          • 机器人自动拉起话题群,抓取提问内容与结构化字段

          • 调用飞书知识问答与历史 oncall 记录,返回候选解决方案

          • 对高匹配度问题(如接口参数说明),可直接给出答案并请求发起人确认

        4)人工 oncall 与闭环沉淀:

          • 对复杂或低匹配问题,由值班研发接手处理

          • 处理完成后,在工作台一键闭环,并自动触发知识条目创建与补充流程

        关键机制
        • 自动提醒与升级:

          • 提交后超 2 小时未响应,自动提醒责任人

          • 超 24 小时未解决,自动升级给负责人或 higher-level 值班

        • 状态全程可见:

          • 提交方与处理方在同一 oncall 话题群与工作台视图中共享状态

          • 支持按业务线 / 人员 / 状态维度实时统计与追踪

        2.1.2 方案设计:飞书生态下的知识驱动 oncall 体系

        核心组件 - 围绕 SOP,我们在飞书上搭建了四大组件:

        1)多维表格 oncall 工作台

          • 作为 oncall 的中枢系统,承载问题登记、分派、状态流转、统计分析

          • 通过约 10~15 个结构化字段保证信息完整性(业务线、模块、类型、优先级、影响范围、处理人、SLA 等)

        2)飞书知识问答与知识库

          • 承载业务规则、接口文档、故障排查手册等结构化知识

          • 通过关键词 + 语义检索,为 oncall 自动给出候选答案

          • 支持按“业务线 / 模块 / 标签”组织知识,便于维护

        3)智能 oncall 机器人

          • 负责在话题群中自动响应、拉取上下文、调用知识问答

          • 在工单创建、分派、处理、升级、关闭各节点自动发消息同步状态

          • 将话题群中的关键信息回写到多维表格与知识库

        4)按业务线划分的 oncall 话题群

          • 将问题讨论集中在线程化话题中,避免信息被沉没在大群

          • 配合机器人和知识库,形成“边沟通边沉淀”的工作方式

        与飞书生态的集成方式 - 整个方案基于飞书现有能力实现,无需自研复杂平台:

        • 多维表格作为“数据中台”

        • 知识库 + 知识问答作为“知识中台”

        • 机器人作为“流程中台”与“交互入口”

        • 话题群作为“协作中台”

        这种“基于平台、融入平台”的策略,使 oncall 流程自然嵌入团队日常协作,降低学习成本与推广阻力。

        2.1.3 知识沉淀机制:让每次 oncall 都变成资产

        在本方案中,“知识沉淀”不再是可选项,而是 oncall 流程的必经步骤。

        知识运营与质量保障

        为避免“建而不用”或“越用越乱”,我们配套设计了简易但有效的知识运营机制:

        • 条目责任人制:每条知识明确业务 / 技术负责人

        • 双人审核机制:关键条目需要业务和技术双重确认

        • 有效期与复审:超期条目自动标记“待复核”

        • 使用反馈与权重:基于点击量、解决率和用户反馈定期优化条目

        2.2 提效的实现路径和步骤

        机票前端团队的方案落地主要围绕几个关键节点展开:业务知识库初始化、oncall 流程编排、多维表格 / 工单应用配置、机器人与知识沉淀机制。以下步骤可结合实际配置截图按序实现。

        2.2.1 前置条件:业务知识库初始化(飞书知识问答 + 飞书 aily 机器人)

        1)基于飞书知识库梳理首批业务与排障知识

        基于飞书知识库梳理并录入首批业务知识与排障知识,按业务线 / 模块建立目录与标签。首先需要一个初始版本的知识库来进行问答查询,建立规则可参考:

        知识库空间创建:

        打开飞书aily开发者后台,创建一个知识空间,配置参考如下:

        直接选择父节点的文档即可导入所有内容,文档内有更新会在30分钟内进行自动同步。确保了我们可以一次选用知识库后,后续可以无需改动即可连接到新知识。

        2)使用飞书 aily 创建问答助手,绑定知识库实现语义检索

        使用飞书 aily 创建一个问答助手,并将其与知识问答能力绑定,使其能够基于企业知识库进行语义检索与在线对话问答。

        打开飞书aily开发者后台,创建一个工作流,默认工作流修改如下,关联第一步的知识库空间即可:

        3)发布该工作流,完成该步骤后,将产出一个可在群聊 / 私聊中直接 @ 的 aily 问答助手,作为后续 oncall 机器人的基础能力。

        2.2.2 Step 1:搭建 oncall 工作台

        整体链路为:飞书机器人接收 oncall 提问 → 写入多维表格 / 工单底表 → 处理结束后触发知识库沉淀。

        你可以直接复制本文对应的工单模版,快速搭建一套属于自己的 oncall 应用;如果场景相对简单,也可以只使用飞书新版多维表格完成底表搭建与自动化配置。

        选择一:简单场景(多维表格 + 自动化)

        适合 oncall 逻辑相对简单、参与角色较少的团队:

        • 搭建一个新版多维表格作为 oncall 底表:包含基础字段(问题描述、业务线、优先级、处理人、状态、结束时间等)。

        • 使用多维表格「自动化」能力,在“新增记录”“状态变更”等节点触发机器人通知和知识沉淀动作。

        • 通过视图和筛选即可完成简单的统计与复盘。

        选择二:复杂场景(工单应用 + 多维表格)

        适合 oncall 流程复杂、需要长期复盘与精细化运营的团队:

        • 复制本文示例的 oncall 工单应用模版,即可快速搭建一套完整的 oncall 工单系统。

        • 相比直接使用多维表格,工单应用提供更友好的操作界面、响应时长等关键指标的可视化能力,更适合做长期趋势分析与复盘。

        • 自动化规则仍然配置在底层多维表格中,可参考“选择一”的自动化方案进行配置。

        2.2.3 Step 2:配置 oncall 机器人与智能分派

        • 在 oncall 话题群中,研发 / TS / 产品等同学通过 @ oncall 机器人发起问题。

        • 机器人根据预设规则(如业务线、模块、问题类型)结合“熟悉业务范围 + 过往 oncall 处理总数”等指标进行智能分派,将工单指派给合适的值班同学。

        • 在分派和处理过程中,机器人优先调用前置配置好的 aily 问答助手和知识库,为发起人返回候选解决方案;若命中度不足,再引导转人工处理。

        2.2.4 Step 3:构建知识驱动循环

        • 每个 SP(服务周期 / 值班周期)结束后,由对应 oncall 同学对本周期高价值问题进行知识总结,补充到业务知识库和排障知识库中。

        在此步骤直接使用“飞书知识问答”进行群聊上下文总结。

        • 实践中,可以在工单应用或多维表格视图中增加一个“沉淀知识”按钮:点击后自动拉起指定群聊 / 话题,@ 相关处理人,并附带本次 oncall 的关键信息,引导完成结构化总结。

        • 通过自动化将“沉淀知识”按钮与知识条目创建流程打通,实现:点击按钮 → 拉群讨论补充 → 一键提交为知识条目 → 进入飞书知识问答索引。

        • 随着每个 SP 的结束,知识库不断扩充,形成“问题处理 → 知识沉淀 → 下次优先由知识解决”的良性循环。

        三、业务价值

        3.1 提效情况和前后对比

        携程机票前端团队在完成体系改造后,关键指标对比如下:

        • 响应速度:平均响应时间从约 120 分钟缩短至 40 分钟左右。

        • 重复劳动:重复问题占比从约 40% 降至 15% 左右。

        • 处理效率:单次 oncall 处理时长从 100+ 分钟压缩至 40 分钟左右。

        • 知识资产:知识沉淀率从不足 10% 提升至接近 80%。

        3.2 应用成果分享

        3.2.1 研发体验与业务满意度

        • 研发人员 oncall 相关满意度显著提升,主观“被打断感”明显下降

        • 业务方对 oncall 响应及时性与方案清晰度均有满意度上升

        • 跨部门协作成本下降,产品需求与技术实现的一致性显著提升

        3.2.2 知识资产与可持续价值

        • 知识库条目数与使用频次呈稳健增长,高频场景覆盖率接近全部高发问题

        • 接口确认与业务逻辑类问题的自动解决率达到 60%~75%

        • 新人培训与交接周期缩短,oncall 相关“问人”场景明显减少

        • 方案可平移到运维 oncall、客服支持、合规咨询等其他知识密集型场景

        3.3 后续规划

        • 持续运营:将“知识贡献”纳入日常任务,建立双人审核与定期复审机制,保障知识质量。

        • 场景扩展:将该模式复制到运维 oncall、客服支持、合规咨询等其他知识密集型场景。

        • 前置主动:打通发布流程与监控告警,让 oncall 更加前置与主动,进一步降低“救火”需求。

        【推荐阅读】

         “携程技术”公众号

          分享,交流,成长

        跳转微信打开

        AI专栏 | 别再手动造数据了!LLM 与 CTGAN 组合拳破解测试数据难题

        2026年7月23日 17:00

        原创 Flint/Aquawer 2026-07-23 17:00 上海

        合成数据新范式:CTGAN负责“量”,LLM负责“质”

        作者简介

        Flint Liu,携程测试开发总监,对于测试用例生成、基于模型的测试、质量领域体系建设以及AI Test有一定的理论和实践积累。

        Aquawer,携程高级测试开发工程师,专注于软件测试与质量保障领域,持续探索大模型在测试领域的应用。

        团队热招岗位:测试开发工程师

        导读:测试人员44%的时间耗在数据构造上——合成数据本是“解药”,但市面方案总缺一角:CTGAN丰富度高却学不会字段逻辑,LLM语义强但输出不可控且低效。本文提出CTGAN+LLM的工程化方案,让二者各司其职,实验证明字段间关系大幅提升,覆盖率接近100%。如果你正苦于测试数据质量与效率,这篇实战复盘值得一读。

        一、背景

        二、合成数据模型调研

        三、LLM-CTGAN数据生成方案

        四、总结与展望

        一、背景

        在软件测试过程中,构造测试数据是一项基础而关键的工作,其目的在于确保软件产品在多种条件下的功能正确性、性能稳定性和兼容性。随着软件系统发展,业务系统的复杂度大幅提升,测试数据的构造也面临高效性、安全性和充分性的挑战。Capgemini与Sogeti的一项联合研究表明,测试人员通常需要耗费44%的测试时间用于测试数据的生成与管理,这是制约企业将产品快速推向市场以保持竞争力的一个关键因素。

        常见的测试数据构造方式主要有两种方式,即手动创建测试数据或从线上数据库中同步可用数据。但前者通常成本较高,且受限于测试人员对于业务的理解程度;后者将会带来一定的隐私合规风险,且数据形态受限于现有业务场景,可能无法覆盖极端测试用例。

        为了弥补上述两种方式在特定场景下的劣势,一些公司和研究机构提出一种新的概念,合成数据(Synthetic Data)。合成数据是指通过统计、深度学习、大语言模型等方式,将模型拟合到真实数据集,然后使用该模型生成不包含任何敏感信息的高度逼真的模拟数据,使得测试数据管理变得更快、更轻松。这种生成过程是随机的,也就意味着模型每次都会产生不同的合成数据集,从而充分模拟生产环境中不同的数据分布、模式和异常,生成涵盖广泛用例的样本数据。这种方式能够高效地降低测试人员数据构造的成本,验证系统是否稳健,并确保更全面的测试覆盖范围。

        注:合成数据可能是多模态的,比如数据、音频以及视频等,本文只对表格数据(Tabular Data)进行讨论。

        在合成数据构造中,模型的选取非常重要。只有生成的测试数据与真实数据非常相似,且能保持足够的多样性,才能有效地模拟各种测试场景并挖掘潜在问题。但当前的常用数据合成模型通常只能满足上述需求的一部分。本文评估了当前业界常用的几种模型,包括高斯分布、时序变分自编码器(Time-series Variational Autoencoder-based,TVAE)、条件式生成对抗模型(Conditional Tabular Generative Adversaial Network,CTGAN),以及大语言模型(Large Language Model,LLM)。

        通过实践案例,比较了不同方案间的优缺点,并最终提出了一种CTGAN与LLM相结合的数据生成方案。这种方式结合了CTGAN与LLM在生成数据时的优势,能够生成既与真实数据相似,又具有较高丰富度的合成数据。本文通过真实案例论证了方法的有效性,并设计了一套完整的工程方案以实现测试数据的生成、修复、监控与管理,使其能够有效地应用于工程化的测试场景中。

        二、合成数据模型调研

        合成数据通常需要为模型提供一个由真实数据组成的训练集。模型通过对训练集的字段特征进行建模,学习其字段的生成规律,包括字段类型、字段格式、字段取值等,最终使用该模型生成与原始数据相似的合成数据集,因此选择合适的模型决定了最终数据生成的质量和成本。

        在工程化的场景中,我们优先追求合成数据有效性、真实性与丰富度三个维度的质量。前两者保障数据的可用性,后者保障合成数据的丰富性。

        • 数据的有效性:即合成数据中是否生成训练集范围之外的无效的取值。如果生成真实场景之外的无效取值,可能导致测试系统异常崩溃、测试人员消耗大量精力在排查无效的测试数据导致的问题中,产生大量的"脏数据",影响数据的可用性。

        • 数据的真实性:合成数据的真实性指其模拟真实数据关键特性的能力,包括统计分布、字段间关系及数据内在逻辑的一致性。在测试数据生成的场景中,并不要求数据与真实数据保持一致的统计分布,相反,希望数据能够均匀地取值,以保证各类单据测试数据数量。而字段间关系与数据内在逻辑一致性可能会直接影响系统处理数据的结果,错误的字段分布和组合可能引起系统判断错误,导致在测试环境验证成功的场景,在真实环境中暴露错误,同样影响数据的可用性。因此,下文从字段间关系以及数据内在逻辑讨论数据的真实性。

        • 数据的丰富度:数据丰富度可以从数据的取值覆盖率、字段间组合、场景覆盖等多方面评估。高丰富度的测试数据能够避免系统反复处理相同的数据,使测试人员能够小成本地覆盖足够的测试场景。从目前业务的高优诉求、数据生成本身的特性以及实现成本考虑,本文将数据的丰富度简化为数据中枚举字段对真实数据覆盖率的问题,即单据的类型、状态取值是否足够丰富,下文所述的数据丰富度均为此定义。

        生成效率同样也是衡量合成数据模型表现的一个关键指标。但由于实际场景中,我们倾向于在每周以定时任务的形式提前准备数据以供测试人员使用,对于实时性的诉求不高,因此对于生成效率指标可适当放宽,生成速度在10s每条以内即可接受。基于上述目标,对现有的模型调研如下。

        2.1 高斯模型

        基于高斯模型的数据生成使用统计学对原始数据的分布进行建模,能够快速地学习数据的分布特征并生成数据。

        模型假设被学习的数据服从正态分布,利用均值向量和协方差矩阵描述数据分布特征,使得生成的数据能与真实数据保持相似的字段取值分布。其优势在于计算高效、有坚实的数据理论基础且参数可解释性强,尤其适合低维、近似正态分布的场景。但受限于严格的正态性假设,模型存在以下缺点:

        • 复杂关系识别能力差:仅能捕捉变量间的线性相关性,无法建模复杂的非线性关系;

        • 长尾分布建模能力弱:由于模型严格按照原始数据的取值分布进行建模,在原始数据中出现概率较低的取值在数据生成时将会丢失,影响生成数据的丰富度。

        2.2 TVAE模型

        基于TVAE的数据生成利用变分自编码器(Variational Autoencoder,VAE)的生成能力,增加了对时序依赖的建模,将表格的每一行视为一个序列,能够在训练过程中学习字段的时序关系。

        模型首先通过编码器,根据字段的数值、类别、文本等特征,将每一行输入数据压缩为一个固定长度的特征向量,再通过一个解码器将特征向量解码为全新的模拟数据。这种方式能够有效学习连续类型变量的数据特征,在一定程度上捕捉字段间的非线性关系,但其数据生成存在以下局限:

        • 模型规则可解释性差:TVAE模型虽然能够在一定程度上捕捉字段间的非线性关系,但其潜在变量缺少明确的语义解释;

        • 高维混合型数据学习效果差:TVAE对于分类变量的拟合效果较差,当变量列数多、或分类基数大时,甚至可能产生训练集中未出现过的异常取值;

        • 长尾分布建模能力弱:TVAE对于低频类别数据的生成质量下降,会损失较多分类字段的取值,丰富度较差。

        2.3 CTGAN

        基于CTGAN的数据生成是一种针对结构化表格数据设计的生成对抗网络。其核心原理是通过条件生成机制解决混合数据类型(连续型、分类型)的生成难题。

        CTGAN模型由一个生成器和一个判别器组成。模型首先根据表格字段的取值类型,将各行数据归一化编码为机器可识别的特征向量。生成器(Generator)接收随机噪声和条件向量作为输入,生成合成的数据向量;判别器(Discriminator)对Generator的输出与真实数据向量进行真伪判别,通过对抗训练的机制优化判别准确率。Generator在对抗过程中学习生成更逼真的数据以“欺骗”判别器,Discriminator则持续提升其判别能力。

        CTGAN的条件生成模式能够有效地处理类别不平衡问题,使原始数据的取值在合成数据中完整且均匀地出现,生成数据的质量较高。但受限于模型的架构设计和参数量,基于CTGAN的本质是通过深度学习隐式捕捉变量间统计关联性生成数据,无法有效且显式地捕捉数据间多字段的联合约束(如城市code、机场code间的级联关系),且无法学习到字段间的隐含逻辑(如订单人数等于各类人员总和等),模型生成结果的可解释性差、字段间关系捕捉不足。

        2.4 LLM

        随着ChatGPT、DeepSeek等LLM在自然语言处理领域的突破,越来越多的研究者尝试利用LLM的语义理解能力构造某些特定领域的数据集,对真实数据进行扩容,这和我们的测试数据合成场景异曲同工。LLM的语义理解能力和模型推理能力使其能够从数据训练集中获取神经网络学习不到的额外信息——即通过字段名称和建表信息推测字段间的语义联接。因此对于诸如多字段联合约束、字段间隐含的计算逻辑,LLM可以轻易地根据字段名称推断字段间的关联,并在字段中隐式验证规则正确性,进而通过链式推理自动计算字段结果,保证生成数据的逻辑一致性。下表是两个LLM对于关联关系学习的示例:

        关系类型

        场景示例

        LLM生成结果

        语义关联关系识别

        以机票大系统政策为例,出发/到达城市code和出发/到达机场code通常具备关联关系,一个airportcode只对应一个citycode。

        LLM生成的数据能够保持与原数据完全一致的关联关系。但是生成的数据只覆盖了部分取值,丢失了一些取值信息。

        机器学习效果:

        大模型效果:

        逻辑关联关系识别

        以机票订单为例,订单表的人数、成人人数、儿童人数、婴儿人数字段间具备逻辑上的计算关系,即人数=成人人数+儿童人数+婴儿人数。

        LLM在数据生成时能够维持字段间的计算关系,生成的数据符合数学计算的结果。

        机器学习效果

        大模型效果

        从上述示例可得,LLM能够在数据生成时获取字段间存在的隐式关联关系,使得生成的数据更具备可用性。但同时也存在其局限性:

        数据丰富度损失:LLM的注意力机制使其仅能关注到最重要的信息,因此在输入数据token较多的情况下,LLM在数据生成时会损失一定的数据丰富度;

        输出可控性差:与传统的统计模型不同,LLM的内部决策过程复杂,微小的输入区别都会导致其输出的多样性,输出的可控性较差,因此对于prompt的要求较高;

        复杂场景稳定性不足:在输入表格字段多、模式复杂的情况下,LLM无法将注意力集中在存在关联关系的字段间,生成的数据往往会:

        • 缺少部分列

        • 不满足输出格式

        • 产生异常取值

        • 数据生成异常终止

        因此,如何合理地应用LLM,使其稳定可控地生成有效、具有真实关联关系且尽可能丰富的数据是使用LLM生成数据面临的挑战。

        2.5 综合分析

        我们分别在三个库表中,用一个小样本的训练集,简单且直观地验证了各个模型对于字段取值覆盖率、字段间关系以及数据有效性的生成效果。字段取值覆盖率、字段间关系以及数据有效性指标的计算方式如下:

        训练集从真实的库表中获取,共200条,分别使用每个模型生成20条合成数据。其中:

        • 高斯模型、TVAE模型、CTGAN各训练300个Epoch,模型均达到收敛;

        • LLM每轮训练30条数据,生成10条数据,并将生成的数据追加到下一批中,最终生成20条数据。

        各模型生成效果如下:

        由上表可得:

        • 对于数据有效性指标,四种模型均能达到较高的有效性水平(>0.95),确保生成的数据具备基本的可用性;

        • 对于字段间关系指标,LLM凭借强大的语义理解能力,显著优于高斯、TVAE及CTGAN模型,合成数据的字段间关联性最接近真实分布;

        • 对于枚举字段覆盖率,高斯、TVAE以及LLM表现相似,均损失约30%的枚举字段取值,而CTGAN模型凭借条件生成对抗的训练机制,枚举字段覆盖率显著优于其他实验模型,在训练集上达到了100%的字段覆盖率;

        • 对于模型生成速度,高斯、TVAE模型的生成速度较快(<1s/条),CTGAN生成速度有所降低,但在可接受范围内(<10s/条),而LLM的生成速度达到了43s/条,数据生成的成本显著上升,在大批量生成数据时可能存在性能局限。

        综上,LLM与CTGAN能够分别满足我们对于合成数据真实性与丰富度的诉求,LLM能够学习到更多其他模型无法学习到的字段间关联,而CTGAN能够生成与真实数据具有几乎一致丰富度的合成数据。但二者均存在一定的局限性。

        对于CTGAN,其受限于模型架构,难以学习显式的逻辑规则(如数学公式、字段映射),且模型学习特征的可解释性较差;对于LLM,其生成数据的字段丰富度较低,且其数据生成的效率较其他模型显著降低。

        基于上述特性,本文提出将CTGAN模型与LLM结合,使其各自生成各自擅长的字段数据,从而生成既能保证丰富度,又更接近真实数据特征的合成数据。该方案既可集成CTGAN的高丰富度能力,又能通过LLM学习复杂逻辑规则,最终输出兼具丰富度与业务逻辑的合成数据。此外,通过一些工程化的技巧提升使用CTGAN与LLM生成数据的效率,降低成本消耗。

        三、LLM-CTGAN数据生成方案

        在本章节中,将详细论述基于LLM-CTGAN的数据生成方案。方案包括关联关系识别、数据生成、指标监控以及数据修复四个模块。在这个整体的方案中,我们利用LLM的语义识别能力指导数据生成的模型选型,使得CTGAN和LLM能够充分地在其擅长的数据类型中发挥优势。

        在关联关系识别模块,我们为LLM提供少量数据样本和库表建表信息,使其能够根据语义信息将库表字段分类为存在相关性的字段和关系独立的字段两部分,用于指导各字段在生成时使用的模型。

        在数据生成模块,我们使用CTGAN进行无关联关系字段的数据生成,使用LLM分别对每个存在关联关系的组进行数据生成。对于CTGAN,我们选择直接从线上获取10000条真实数据作为训练集,并保存训练得到的模型参数,以减少后续模型训练的时间。对于LLM,考虑到其上下文限制,我们使用一个压缩算法对上述训练集进行了精简,使其能够在缩小规模的同时尽可能地保持丰富度。

        在指标监控模块,我们从字段列和数据行两个维度对数据生成的效果进行监控。对于合成数据每一列质量,我们采用字段间关系、数据有效性以及覆盖率三个指标进行衡量。对于合成数据每一行的指标,我们复用了CTGAN模型在判别器参数,对每一行进行打分,以确定每一行数据的置信度。此外,我们还形式化LLM在数据生成过程中学习到的规则,在真实数据上验证这些规则的真实性。这一操作不仅能够验证LLM对语义的理解能力,还使得数据生成这一过程具备可解释性。最后将指标整合为报告推送给使用者,使其能够对数据生成质量有清晰的认知。

        在数据修复模块,后置对模型生成的数据进行检查,检查其与原始数据集丰富度的差异及有效性,对于丰富度缺失的列,额外补充丰富度;对于异常数据,将其剔除。

        3.1 关联关系识别

        在数据生成中,我们对于表格中各字段的生成诉求通常是不同的。例如,对于一些单据标识字段,我们通常不关心它的取值;对于一些枚举类型字段,我们希望它在生成中保持与输入同样丰富的取值;而对于一些业务字段,我们希望它们能维持字段间的逻辑关系。库表字段根据其合成数据时的特征可以分为如下几类:

        根据上述分析,需要生成的字段可以分为两部分:

        • 无需保证字段间的关联关系,但需要保持丰富度的字段,适用于CTGAN生成;

        • 需要保证字段间的关联关系,可以接受牺牲一些字段的丰富度的字段,适用于LLM生成。

        因此,如果可以识别字段类型,即可使用CTGAN用于前者的生成,LLM用于后者的生成,满足两种字段的数据生成诉求。对CTGAN而言,这种方式最大化了其取值丰富度的优势;对于LLM而言,该方式避免了无关字段占用模型输入,从而避免了不必要的计算和存储开销。

        人工完成这一识别任务需要分类人员具备深入的业务知识且实施成本较高,而LLM凭借丰富的语义理解能力,能够比人工更为高效的完成此任务。

        为LLM提供库表的少量样本行S,及建表语句T,我们希望LLM能够识别库表中可能存在关联关系的字段,并将其分为若干个具备关联关系且不重叠的组(G₁,G₂,...,Gₙ)。划分字段组的原因是:字段间关系通常存在于特定的字段子集中,与其他字段无关。使LLM分别学习这些分组对应的数据,可以使其最大程度上排除无关的信息的干扰。我们将这个任务拆分为三步:

        1)直接使LLM将字段分为若干个取值上有相关关系的组;

        2)使LLM对生成的结果进行批评和修复,以[["category1","category2",...],[["category3",...]]格式,结构化地输出识别的结果;

        3)根据预设规则修复LLM的输出,如过滤输出中字段名中包含state、type、version的字段、过滤只有一个字段的分组。

        通过上述工作,即可获取到库表中存在关联关系的字段组(G₁,G₂,...,Gₙ)用于指导数据的生成。整体的工作流程如下:

        1)首先要求LLM对样本及建表语句进行分析,识别出可能存在关系的分组。提示词(Prompt)如下:

          接下来我将为你提供一个表格的表头和5条真实数据,表格中字段间可能存在一定的逻辑关联关系。请帮我过滤掉这些字段中,在生成合成数据时通常不需要保持原有的关联关系或取值随机性较高的字段。其余的字段细分为若干个取值上有相关关系的组。注意:每个组之间不要出现重复的字段。

          2)随后再次使用LLM对上一步的输出进行评价,评价其分组是否合理,对不合理的部分进行修正后,将结果输出为json列表格式。Prompt如下:

            请检查下面的分组中是否存在错误,修正并将修正后的分组以列表的形式输出,例如[["category1","category2",...],["category3",...]],不要使用任何额外解释,直接给出结果即可。

            3)为了避免LLM无法很好地过滤不具备关联关系的枚举字段,采用另一个Prompt,提示模型识别与status、state、type、version等内容相关的字段,并在最终结果中过滤这些字段。

              接下来我将为你提供一个表格的建表语句,请帮我识别其中字段名中包含status、state、type、version的枚举字段。返回格式为一个列表,格式为|'column1','column2',...|,不要返回其他内容。

              3.2 LLM-CTGAN模型实现

              在这一模块中,我们首先使用CTGAN模型对原始数据集D-original进行建模,得到合成数据D-independent。再由LLM对一个由D-original压缩而来的D-compressed进行学习,得到合成数据D-related。最终合并两种方式得到的数据,生成最终的测试数据。与单独使用CTGAN或单独使用LLM相比,这种方式存在以下优势:

              • 端到端流程整合:将关系识别、模型适配与数据生成整合为一个端到端的自动化管道,显著降低人工配置成本;

              • 语义-统计协同建模:该方式融合了LLM的语义理解与CTGAN的统计建模优势,使得生成的数据能够兼顾字段级别的高丰富度与跨字段关联一致性。

              • 计算效率与样本规模兼顾:与直接采用LLM生成数据相比,该框架分组学习的方法使LLM能够单次处理更多规模的数据,减少LLM的计算负载。

              3.2.1 CTGAN模型实现

              我们使用开源的SDV库搭建CTGAN模型。以一个从线上获取的10000条真实数据的表格作为训练集。考虑到CTGAN在单次训练过多数据时会出现内存崩溃,本文采用了一种高效的训练方式实现数据生成,如下图所示。

              训练集被拆分为若干个大小相同的批次(batch),每个batch通过CTGAN训练一个Epoch后,生成一个小样本数据,追加到下一个batch中进行下一轮的训练。在最后一轮的训练中,将CTGAN训练的模型参数保存到云端。在后续的每次生成中,只需加载库表对应的生成模型,即可实现高效的数据生成。每一次训练相当于一次蒸馏,提取数据集中最重要的部分,在保障了生成数据丰富度的同时减少了训练成本,解决了CTGAN内存消耗大、训练速度慢的问题。

              数据集构建

              数据集是模型训练的基础,构造数据集的目标是希望数据集能够覆盖尽可能多的字段真实取值。获取数据集的方式有三种:人工构造数据集、从测试环境中获取数据集、从线上环境中获取数据集。人工构造数据集虽然能够更加针对性地设计数据分布,但需要投入较多人力成本;从测试环境中获取数据集可能由于Mock、异常插入等原因,导致数据失真,带来脏数据;而从线上环境获取数据集具有最真实的用户行为特征和自然数据分布,与人工构造相比数据获取成本低,与测试数据相比数据真实性高。因此,选择直接从线上环境获取库表数据构建数据集。

              由于某些线上库表数据量较大(10w+),获取全量数据作为训练集是不现实的。本文比较了在限制获取10000条数据情况下,不同的SQL排序写法对于数据集枚举丰富度的影响,分别为按id倒序获取、按创建时间(create_at)倒序获取以及按修改时间(change_at)倒序获取,实验结果如下表所示。其中,按id倒序获取到的枚举值更完整,取值覆盖率达到了全量数据的85%。且由于几乎所有库表都存在id字段,但不是所有库表都存在create_at/change_at字段,因此,选用按照id倒序的方式获取线上数据,构建训练集。

              Metadata生成

              Metadata是对要合成的数据集的描述,包括列的名称、每列的数据类型,其核心作用在于指导生成模型进行差异化的特征编码与生成策略选择。当前业界标准将基础数据类型划分为boolean、categorical、datetime、numerical四类。开源的SDV库提供了一种根据DataFrame的sdtype识别的Metadata生成方式。但这种方式在实践中经常出现识别错误导致生成错误的问题,需要通过异常处理机制并错误的列全部覆写为categorical类型,这可能影响数据的生成质量与后续的指标度量。

              鉴于字段类型通常与数据库模式定义存在严格映射关系,采用LLM解析数据库建表语句(DDL),可实现更精确的元数据自动化构建。生成Metadata所使用的Prompt如下:

                你是一个数据专家。接下来我讲为你提供一个数据库表的若干条数据。请为我生成这个库表可用于sdv生成的metadata。输入:一个数据库表的若干条数据以及这个库表的建表语句。输出:这个表的metadata。metadata对字段的类型进行分类,包括boolean、categorical、datetime、numerical四类。一个示例如下:

                { 

                    "columns": { 

                        "age": { 

                            "sdtype": "numerical" 

                        }, 

                        "tier": { 

                            "sdtype": "categorical" 

                        }, 

                        "active": { 

                            "sdtype": "boolean" 

                        }, 

                        "paid_amt": { 

                            "sdtype": "numerical" 

                        }, 

                        "renew_date": { 

                            "sdtype": "datetime" ,

                            "datetime_format": "%Y-%m-%d" 

                        }

                    } 

                }


                数据分批训练

                在数据训练时,为了降低训练成本的同时,还能使合成数据具有与真实数据一致的丰富度,本文采用了一种分批训练的方式实现数据生成。

                首先将训练集拆分为若干个大小为100条数据的batch,每批数据在训练10个Epoch后生成100条数据,将生成数据追加入下一批数据中。这一步骤的目的是将200条数据的取值浓缩到100条数据中。当某个字段在200条数据中的唯一取值超过100个时,这个过程可能会损失一些取值。但由于我们的目标是保持"分类字段的取值丰富",而分类字段的取值通常不会多于100,因此,这种方式能够成功地将分类字段的取值压缩。

                当训练至最后一个batch时,模型训练300个Epoch,并将模型参数上传至云端文件管理系统。在下一次生成数据时,首先查询是否存在对应库表的模型参数,若存在,则直接生成数据,反之,则从线上获取数据后训练模型。

                我们分别在6张库表中单独使用CTGAN对10000条数据构成的训练集进行了训练,比对生成1000条数据后,合成数据与真实数据的枚举字段取值。在所实验的库表中,CTGAN均能保持与训练集完全一致的枚举字段覆盖率。当首次训练模型生成数据时,生成速度约1.99s/条;使用预保存的模型参数生成数据时,生成速度进一步提升至0.16s/条,与上文实验中以200条训练集直接训练的9.84s/条相比,生成数据的时间消耗缩短至1/60。

                3.2.2 LLM数据生成

                对于LLM,我们以一个由上述10000条真实数据的表格压缩而来的1000条数据的表格作为训练集。首先根据关联关系识别模块得到的字段分组,将数据集纵向划分为若干个分组。与CTGAN的训练策略相似,对于每个分组,分批次训练后,将生成的一个小样本数据集追加到下一个批次中形成新的训练集。最终将各分组的结果合并。与直接使LLM训练1000条数据相比,这种分批次的生成方式可以使LLM专注于每批次的数据,避免过大数据量导致的注意力不均衡和信息损失。

                模型选用

                由于测试数据生成涉及对线上真实数据的学习,因此需要模型支持数据外发,且具有较强的推理能力。综合考量模型特征及成本,我们选用自部署的开源Deepseek-R1-Friday(全参671B)用于LLM数据生成。

                数据集压缩

                由于LLM天然的Token数量及注意力机制限制,LLM并不能像CTGAN一样学习万级别的训练数据。而事实上,关联关系的识别也并不需要如此庞大的数据量。因此,我们需要对原始数据集进行压缩操作。

                一种简单的方式是直接切片获取原始数据集的前1000条数据。但对于某些分布不均匀的字段来说,直接切片操作可能导致损失过多取值信息。如某字段的前1000条数据均为NaN,这显然是不可接受的。

                想要对一个库表的几十个字段抽样压缩,并保障其丰富度和分布均匀是一件有挑战性的工作。

                我们采用了一种分类+按行评分的方式来实现这一需求,具体抽样流程如下图所示:

                1)首先将各字段分为单一值列、极端偏态列、随机值列、可数离散值列、其他共五类;

                2)对极端偏态和可数的列按值出现的概率之和进行评分采样;

                3)按得分倒序排列,取前900条数据纳入样本数据集,剩余数据均分为4个区间,分别随机抽样25条,最终构成1000条样本数据集。这样抽样得到的数据能够保持各列分布相对均匀,使得出现频率较低的列也能被采样到,避免出现一整列抽样均为单一值的情况。

                比较直接顺序切片、随机抽样、以及我们所使用的差异化抽样可得,差异化抽样方式的各列平均相对熵比、枚举字段覆盖率均有所提升,与直接切片相比,平均相对熵比提升约15%,枚举字段覆盖率提升32.3%。

                Prompt优化

                吴恩达《提示工程》课程中提出,要对每一个子任务构造清晰而具体的提示,可遵循以下策略:

                • 少样本提示:将一系列成功执行所需任务的案例与要查询的问题连接在一起,形成带有提示的模型输入,通过少量的标注引导模型预测。

                • 要求结构化的输出:即指定模型输出的格式,如JSON格式;

                • 使用分隔符:即使用分隔符使模型清晰地确定需要用于分析的文本;

                本文借鉴这一思想,为LLM数据生成设计了精心优化的提示词。

                首先是样本的提供。在每次训练中,我们将为LLM提供100条真实数据作为样本,并指导模型生成20条数据,并合并入下一批数据,作为下一次训练的训练集。样本的数量不宜过多,过多样本会引发LLM上下文长度溢出,以及削弱模型对每个个体示例的注意力。

                在选择结构化的输入输出时,本文选择Markdown格式的表格作为LLM的输入和输出。这是由于Markdown格式的表格数据结构清晰,可读性高。对于LLM来说,清晰的格式可能使其更容易理解数据结构。在训练前,我们将excel表格数据转换为Markdown格式的文本提供给LLM,并从LLM的输出中提取符合Markdown表格格式的输出,转换为excel存储。

                此外,我们在提示词中充分使用了诸如序号、换行符等分隔符,采用定义角色、定义输入输出、定义约束的三段式描述方式,使得Prompt能够被LLM清晰地解析。

                以下是我们使用的几种提示词的优缺点分析:

                版本1:

                  你是一个对业务非常了解,且精通数据库,推理能力很强的数据分析人员。接下来我将为你提供一张数据表的若干数据,我希望你能在保持数据特征、丰富度以及列间关系的情况下,帮我生成更多这样的数据。

                  你需要遵循以下策略和规则:

                  1. 输入输出

                  1.1 输入格式:输入是一个有若干行的 Markdown 表格格式的表格,包含表头与表单项。

                  1.2 输出格式:输出是一个有 20 条数据的 Markdown 表格格式的表格。

                  2. 约束

                  2.1 输出必须保持与输入完全一致的丰富度,不要出现输入中没有出现过的数值。

                  2.2 对于可能有关联的字段,请保持给他们之间的关联关系。

                  2.3 生成的数据分布需要均匀,不需要和输入保持相似的分布。


                  分析:Prompt的约束要求LLM需要与输入保持完全一致的丰富度、保持关联关系,且保持数据分布均匀。这使得LLM在处理非分类字段时,由于约束,也会倾向于生成与该字段完全一致的取值,且在生成致据中使这些取值保持均匀,而由于非分类宇段通常具有较多不同的取值,在生成数据中保持取值均匀和维持关联关系变得十分困难,因此LLM的生成效率会大大降低,甚至因为思考长度超长无法生成数据。

                  版本2:

                    你是一个对业务非常了解,且精通数据库,推理能力很强的数据分析人员。接下来我将为你提供一张数据表的若干数据,我希望你能在保持数据特征、丰富度以及列间关系的情况下,帮我生成更多这样的数据。你需要遵循以下策略和规则:

                    1. 输入输出

                    1.1 输入格式: 输入是一个有若干行的Markdown表格格式的表格,包含表头与表单项。

                    1.2 输出格式: 输出是一个有20条数据的Markdown表格格式的表格。局6

                    2.约束(请重点关注!!!)

                    2.1 除了时间类型,其他所有字段的输出必须保持与输入完全一致的丰富度,不要出现输入中没有出现过的数值。

                    2.2 对于可能有关联关系的字段,生成时请保持它们之间的关系,使其符合常识。


                    分析:Prompt的约束去掉了对于数据分布均匀的要求,便这项数据生成的任务变得更加简单。此外,与上述Prompt相比,这一版本使LLM不必关注时间类型的丰富度,但其他的非分类字段仍然存在上还问题。

                    版本3(最终版):

                      你是一个对业务非常了解,且精通数据库,推理能力很强的数据分析人员。接下来我将为你提供一张数据表的若干数据,我希望你能在保持数据特征、丰富度以及列间关系的情况下,帮我生成更多这样的数据。你需要遵循以下策略和规则:

                      1. 输入输出

                      1.1 输入格式: 输入是一个有若干行的Markdown表格格式的表格,包含表头与表单项。

                      1.2 输出格式: 输出是一个有10条数据的Markdown表格格式的表格。

                      2. 约束

                      2.1 对于枚举类型、分类类型的字段;输出必须保持与输入完全一致的丰富度,不要出现输入中没有出现过的数值。

                      2.2 对于连续致值、时间类型的字段:输出必须保持与输入完全一致的数据范围与格式,在数据范国内可以生成随机的数据。

                      2.3 对于可能有关联关系的字段,请保持它们之间的关系。


                      分析:这一版本的Prompt强调了LLM对于不同类型的字段可以采取不同的丰富度保持的方式,生成异常数据的几率大大降低,LLM能够较为稳定地生成合成数据。

                      3.3 实验验证

                      我们在两个特征不同的场景中试验我们方法的有效性,前者涉及的三张表中,数值类型字段偏多,字段间计算逻辑关系较多。后者涉及的三张表中,分类类型的字段较多,字段间多为映射关联关系。

                      3.3.1 指标设置

                      本文采用字段列和数据行两种维度的指标衡量合成数据的质量。

                      字段列指标指的是上文所述的枚举字段覆盖率、字段间关系、数据有效性指标,这些指标关注字段本身或字段与其他某个字段二元关联关系,能够较为直观地反映合成数据是否与真实数据具有相似的统计学特征。但仅使用这些指标,不足以反映合成数据是否学习到了与真实数据一致的字段间关联——基于相关系数的字段间关系指标只能反映字段间两两间的线性趋势,无法度量复杂的字段间关系。

                      数据行指标包括判别器得分与规则有效性两种,从整体数据表现入手,反映合成数据是否真正学习到了字段间的隐含关系。其中,判别器得分指标利用CTGAN的模型判别器,使其反过来对合成的新数据进行判别打分。规则有效性指标使LLM将其生成数据时所用的规则形式化,反过来验证规则是否在合成数据中有效,这一过程使数据生成变得可解释。

                      数据的行列指标结合,使我们能够更全面地评估合成数据的质量。

                      字段列指标

                      数据行指标

                      • Discriminator Score

                      作用:判定每一行的数据置信度

                      计算方式:CTGAN的判别器loss能达到比较低的水平,即整体判别正确率较高,因此,使用CTGAN的判别器对最终生成的数据每一行进行评分,整体评判合成数据的整体质量。

                      由于CTGAN原有判别器采用一个linear层作为输出,并没有进行归一化处理,无法直接用于衡量数据置信度。我们首先使用一个sigmoid层,对Discriminator的数据进行归一化,再以判别器对真实数据的评分对合成数据的评分进行放缩,衡量行数据的质量。

                        1. 对于每一个生成的数据行i,将其向量化为t_i

                        2. Discriminator计算T的预测得分p_i

                        3. 使用sigmoid将pi归一化,得到得分d_1

                        4. 使用上述方法计算真实数据的平均得分D_real=(d_1+d_2+...+d_i)/i

                        5. 使用上述方法计算合成数据的平均得分Dsyn=(d_1+d_2+..-+d_i)/i

                        6. 则合成数据的最终得分Q=D_syn/D_real


                        • Rule Validity
                        作用:模型规则验证

                        计算方式:形式化输出LLM生成数据时所依赖的规则,并使用这些规则在真实数据中进行验证,证明其可行性。若在真实数据有效性达到100%,即所有训练集的数据行均条件成立,则证明该规则真实存在。进而使用规则在生成数据中进行验证。

                        规则有效性=规则成立的行/数据集的所有行

                        你是一个对业务非常了解,且精通数据库,推理能力很强的数据分析人员。接下来我将为你提供一张数据表的若干数据,我希望你能找出这些数据中存在的关联关系。
                        你需要遵循以下策略和规则:
                        1.输入格式: 
                        输入是一个有若干行的Markdown表格格式的表格,包含表头与表单项.
                        2.输出格式: 
                        输出是一系列你发现的关联关系,以字符串列表格式表示,不需要输出其他信息,也不要生成除了下面提供的三种关系类型以外的关系。
                        2.1 如果字段间存在一对一的映射关系,则字符串为列表格式,如"
                        a->b
                        ",表示一个a唯一确定一个b值;
                        2.2 如果字段间为计算关系,则输出他们的计算关系,如"
                        a=b+c
                        ";
                        2.3 如果字段间为大小关系,则输出他们的大小关系,如
                        "a>b+c"
                        、
                        "a<100"
                        等。
                        3.示例
                        ["a->b","a=b+c","a<100"]

                        3.3.2 实验验证

                        在一个10000条数据的原始训练集上,我们验证了我们所提出的方法的有效性。每次训练生成1000条数据、执行10次后求平均值计算指标得分。

                        本文重点对比了CTGAN基线方法与LLM_CTGAN增强方案的生成性能。实验设计未纳入直接使用LLM生成的对比组。这是由于随着训练迭代次数增加,直接使用LLM生成数据的多样性严重下降,所有字段取值趋向于某个出现概率较高的固定值,且接口调用生成错误结构的数据概率也增加,导致使用1000条数据训练时,生成流程的失败率已经超过90%,生成数据所需时间超过60s/条,不适用于大数据量的数据生成任务。数据生成结果如下表所示:

                        行间指标:

                        列间指标:

                        3.4 数据整合与修复

                        在上文中,我们使用LLM_CTGAN实现了数据的生成,生成的结果需进行后置检查修复操作,检查生成的数据中是否保持了数据的丰富度,以及是否存在取值异常的情况,使最终输出的数据更加丰富和可用。

                        数据丰富度修复旨在解决生成数据中潜在的分布偏差问题。尽管在数据预处理阶段我们通过压缩算法调整了训练集分布,但生成过程中仍可能因模型注意力偏好导致特定字段出现极端分布偏态,导致LLM在训练过程中丢失一些字段的取值,进而导致生成数据的取值过于单一。因此,我们通过后置补充丰富度规避这一情况,即后置检查各列的取值分布。对于生成数据中枚举字段取值与原始数据不一致的列,通过对LLM增加约束条件,使其再补充一些指定取值。

                        生成指定取值数据的Prompt如下:

                          你是一个对业务非常了解,且精通数据库,推理能力很强的数据分析人员。接下来我将为你提供一张数据表的若干数据,我希望你能在保持数据特征、丰富度以及列间关系的情况下,帮我生成更多这样的数据。

                          你需要遵循以下策略和规则:

                          1. 输入输出 

                          1.1 输入: 输入是一个有若干行的Markdown表格格式的表格,包含表头与表单项。

                          1.2 输出: 输出是一个有{batch_generate_size}条数据的Markdown表格格式的表格。

                          2.约束

                          2.1 对于枚举类型、分类类型的字段:输出必须保持与输入完全一致的丰富度,不要出现输入中没有出现过的数值。

                          2.2 对于连续数值、时间类型的字段:输出必须保持与输入完全一致的数据范围与格式,在数据范围内可以生成随机的数据。

                          2.3 对于可能有关联关系的字段,请保持它们之间的关系。

                          2.4 生成的致据分布需要均匀,不需要和输入保持相似的分布。

                          2.5 字段{col}的值为{unique val}


                          取值异常修复旨在在解决字段取值异常及关系异常两种异常的致据情况。检查方式与修复方式如下:

                          • 异常取值:对于“枚举字段”,即Metadala字段分类为categorical,且训练集中唯一值<20的字段,后置检查判断这类字段与原始数据值域的差异,剔除其中没有在原始数据中出现过的值。

                          • 异常组合:对于LLM识别出的规则,校验其在真实数据中的有效性,进而使用在真实数据中被验证有效的规则反过来验证其在测试数据中是否成立。对于在测试数据中有效性>90%的规则(即LLM在学习过程中使用了该条规则),过滤不符合规则的数据。

                          四、总结与展望

                          我们提出的基于AI增强的自动化数据生成方式能够有效地提升传统的基于统计模型生成数据的效果,使生成的测试数据具有更接近真实业务数据的字段间关系,且能够保持基于统计模型的丰富度优势,这个方法使得LLM和CTGAN能够“各展所长”,生成他们更擅长的字段类型的数据,使成的测试数据更加有意义。

                          在未来的工作中,我们将在以下方向持续迭代:

                          • 复杂表间关系识别:探究如何识别库表间的复杂关系,进一步降低数据生成的配置成本;

                          • 效率提升与成本优化:探究能否通过离线推理等方式提升LLM的数据生成速度;

                          • 通用平台建设:完善数据生成系统能力,建设通用的测试数据生成平台。

                          【推荐阅读】

                           “携程技术”公众号

                            分享,交流,成长

                          跳转微信打开

                          AI专栏 | Demo 跑通了,上线就翻车?Java Agent 生产的那些坑,我们帮你填了

                          2026年7月17日 11:50

                          原创 Cris/小蜗牛 2026-07-17 11:50 上海

                          一个 Harness,把 Java Agent 从 Demo 拉到生产

                          作者简介

                          Cris Yang,携程资深后端开发工程师,关注AI原理探索与Agent构建。

                          奋斗的小蜗牛,开源项目 SnailJob / SnailAi 作者。专注于系统架构、分布式设计、高性能系统与 AI Agent 技术探索。

                          导读:Java 团队做 Agent,不缺模型接入方案,缺的是让 Agent 稳定跑在生产里的运行时能力。记忆漂移、大报文击穿上下文、推理不可复盘、工具变更要发版——这些问题现有框架不兜底。Spring-Ai-Trip 在 Spring AI 上叠加了一层 Harness,用渐进压缩、Spill 溢出保护、认知可观测等机制,填平 Demo 到生产之间的鸿沟。如果你也在 Java 侧做 Agent,也在被这些“Demo 跑通了,上线就翻车”的问题反复折磨,这篇文章或许能帮你少踩几个坑。

                          一、Java 侧做 Agent,我们到底缺什么

                          二、设计哲学:我们如何看待 Agent 运行时

                          三、系统架构:Spring-Ai-Trip 的全景视图

                          四、短期记忆:渐进式压缩

                          五、可观测性:Span + Event 树

                          六、Spill:大结果的溢出保护

                          七、能力供给:填平 Skill 的空白 + MCP 热插拔

                          八、并行工具调用:能同时做的事,别排队

                          九、端到端实战:一次排障会话,把所有机制串起来

                          十、Roadmap:我们还在往哪走

                          一、Java 侧做 Agent,我们到底缺什么

                          过去两年,Agent 生态的语言分布很偏——Python、TS 那边百花齐放,Java 这边一直不温不火。LangChain4j 和 Spring AI 把接入大模型这件事做得挺到位,后来的 Spring AI Alibaba、AgentScope Java 又在编排和多 Agent 协作方向补上了部分能力。但真正在生产里做过 Java 侧 Agent 的团队,大概率都踩过下面这三个问题:

                          • 技术栈错配:国内后端团队的技术栈基本以 Java 为主,用 Python 独立搭建服务会带来跨语言 RPC 调用,同时需要维护两套可观测体系、两套配置中心,让整队人转去写 Python 也不现实。他们要的不是能用 Python 跑的 Agent,而是"能用 Java 写、能长在现有业务代码旁边"的 Agent。

                          • 企业级治理断层:多数开源框架只做到能跑起来:调通模型、跑通工具。至于链路追踪、配置中心、限流熔断、审计合规、灰度发布——大多要业务方自己接。

                          • 运行时空白:即便选了 Java 方案,现有框架也基本只做到能调通大模型。而生产化真正的难点在运行时:短期记忆怎么管、单次工具返回的 5 万字报文怎么处理、错误结论的推理过程怎么回溯、工具怎么在不重启的情况下加减、并发工具调用怎么保证一致性——这些几乎没有框架给你兜。

                          会调大模型,只是拿到了入场券;让 Agent 稳定、可控、可解释地跑在生产里,才是真正难的部分。

                          现有 Java 方案审视

                          Spring AI把接入大模型这件事做得很轻,统一的模型抽象、Advisor 拦截链、Tool Calling 注解对 Java 工程师很友好。但也就到接入这一步:ChatMemory 只有滑动窗口这类基础实现,工具返回值直接进上下文、没有溢出保护,Observation 只覆盖到"调用发生了"这一层,工具注册是启动期静态的,会话生命周期没有作用域概念。

                          Spring AI 是模型抽象层,不是Agent 运行时。它给你一辆能开的车,但生产化需要的变速箱、ABS、行车电脑,得自己造。

                          Spring AI Alibaba走得更远,Graph 编排、Nacos 集成、DashScope 生态、Studio 工具链。我们没选它:一来我们已经在用 QConfig、CAT、内部 MCP 网关,换 Nacos 这套等于把现有基建全部替掉;二来它的重点在编排,我们头疼的是单个 Agent 内部怎么更稳定的运行。

                          AgentScope Java出现得晚,但布局铺得比较全:不可变消息、@Tool 注解、A2A / MCP 双协议、Reactor 非阻塞,适合新起项目。它和我们的场景不一样:它是一站式开发平台,我们是往已有 Spring Boot 服务里嵌的一层。后文会把它拿来做对照。

                          Spring AI 之外这块空白,大到值得单独做一层。我们将该中间层叫做 Spring-Ai-Trip,作为挂载在 Spring AI 与业务 Agent 之间的Harness。

                          二、设计哲学:我们如何看待 Agent 运行时

                          在讲机制之前,先把心法交代清楚,后面所有具体设计,都是这四条原则的推论。

                          2.1 叠加,而不是替代(Additive over Replacement)

                          不重造 Spring AI 的轮子,所有能力以 Advisor / ToolCallback / Observation 的方式挂到它上面。业务方随时可以只用 Spring AI 原生能力,也随时可以按需开启我们的能力项。

                          2.2 读写分离,把复杂度推后(Lazy Compaction)

                          写入路径永远简单快速——毫秒级落库,零加工。所有 Agent 决策(压缩、预算判断、锚定、修复)都推迟到注入模型的那一刻再做。原始数据永远完整保留在库里,复盘、审计、回放随时可查。

                          2.3 信息不丢弃,只降级(Progressive Degradation)

                          面对上下文压力,信息从高精度原文渐进降级到高密度摘要,而不是断崖式截断,也不是被打散成检索碎片。我们要的是斜坡,即保留连续的、可读的、只是密度不同的一份历史。

                          2.4 默认安全,业务无感(Safe by Default)

                          异常路径的清理、并发下的一致性、工具下线的安全窗口、进程重启后的会话续接,这些脏活都由框架在业务背后处理干净。

                          三、系统架构:Spring-Ai-Trip 的全景视图

                          3.1 整体架构图

                          3.2 核心数据流

                          一次 agent调用穿过 Harness 的完整路径,大致是这样:

                          四、短期记忆:渐进式压缩

                          Agent 的短期记忆决定了它是能连续作战的助手,还是每轮从零开始的无状态函数。没有记忆的 Agent 本质上是 f(当前输入) → 输出,会在三个层面断裂:

                          • 对话连续性断裂:第 1 轮说"处理订单 ORD-2024-001",第 5 轮问"进展怎样了"——Agent 已经不记得订单号

                          • 决策链断裂:中间环节丢失,无法基于已有结论继续推进

                          • 行动链断裂:早期工具返回消失,可能重复调用或跳过步骤

                          记忆不是 Agent 的附加功能,而是 Agent 区别于 API wrapper 的本质特征。

                          4.1 通行做法的结构性缺陷

                          上下文窗口是固定的,对话越长越满,必须淘汰一些内容。核心问题是淘汰标准:按什么规则丢、丢完之后关键信息还在不在。

                          滑动窗口——Spring AI 的 MessageWindowChatMemory、LangChain 的 ConversationBufferWindowMemory 都是这个路子:保留最近 N 条消息,超出从队头丢。它用位置作为唯一淘汰标准,可信息的价值根本不由时间决定——用户第 1 轮说的"帮我处理订单 ORD-2024-001 的退款",可能比第 19 轮那句"嗯"重要一万倍。到第 21 轮,窗口一滑,最初的目标被无声丢弃,于是 Agent 开始目标漂移:越聊越偏,或者每一轮都在重新猜用户到底想要啥。

                          RAG 检索——把历史向量化,用时再捞。它擅长跨文档知识检索,但用作会话记忆有个硬伤:它按语义相似度捞相关片段,却感知不到时序,也拼不出对话的整体画像——Agent 知道自己某次查过订单,却不知道整个任务进展到哪一步了。

                          看清了这些,我们的设计哲学其实就一句话:

                          永远不丢弃任何信息;注入模型时,按信息价值的衰减曲线,渐进地压缩。

                          "渐进"是关键词。信息不是在某个边界突然消失,也不是被打散成碎片,而是连续、分级地从高精度原文过渡到高密度摘要。

                          在思考这套渐进压缩具体怎么做时,Claude Code 的四层上下文管理机制给了我们很大启发——我们借鉴了其中三条核心思想:信息不应被断崖式截断、摘要应该结构化而不是"总结一下"、压缩之后需要显式恢复。但不能直接照搬:Claude Code 是单机 CLI,单进程持有会话状态、SM 文件写本地磁盘;我们是分布式服务端,多实例无粘性会话、要跨实例续接、要接多家模型厂商——这些差异决定了我们最终落地的形态和它不同。

                          4.2 三层防御体系

                          第一层:完整持久化。所有消息逐条落库,只追加、不删除。

                          这一层还带来一个容易被忽视、却极其关键的设计——读写分离。写入永远只是简单的一次落库,毫秒级,零压缩开销;所有压缩都只发生在读取、注入模型的那一刻。原始数据一条都不少地躺在库里,复盘、审计、回放随时可查。这一步还顺带解决了服务端才需要面对的跨实例会话续接:任何实例接过 sessionId,都能从库里拿到完整历史 + 摘要,不依赖任何本地状态。

                          第二层:工具结果微压缩。这是一个纯内存计算、完全不调用大模型的轻量回收。它的核心洞察是:一次工具调用的返回值,价值衰减得极快。一个 3000 token 的订单查询结果,在 Agent 已经据此告诉用户"订单已发货"之后,那 3000 token 的原始 JSON 就不再需要了——留下"我查过了,已发货"这个事实就够了。

                            压缩前(约 3000 tokens):

                              [工具] query_order → {"status":200,"body":{"orderId":"...","items":[...大量数据...]}}




                            压缩后(约 10 tokens):

                              [工具] query_order → "[旧工具结果已清理,可按 evidence-id=e7f3a 回查]"


                            一些打磨得比较细的点: 以完结轮次为原子单位——工具调用链可能横跨好几条消息,只有当整轮真正结束了其中的结果才有资格被回收,绝不切断正在进行的调用链;按工具分策略——不同工具挂不同压缩规则,关键操作永不压缩、查询结果过期即清

                            替换文本带证据指针——清理后的占位符里带一个指向持久化层的 evidence-id,排障时需要还原当时看到了什么,直接按指针回查即可,和后面讲的可观测性打通,原始工具返回并没有真的消失,只是从注入模型的上下文里退场。一次 20 轮工具调用的对话,光微压缩就能释放约 5 万 token。

                            第三层:LLM 结构化摘要。 当微压缩之后仍然超预算,才动用大模型,把早期对话折叠成一份结构化摘要。注意,这不是让模型随便总结一下,而是按一个固定的九段式模板来写,并且给每一段排了优先级:

                            这个设计直接命中前面说的目标漂移:User Intent 和 Current State 被显式地、结构化地锚定在摘要里,无论压缩多少轮,Agent 始终清楚"用户要什么"和"我做到哪了"。token 实在不够时,先从 P3 往下砍,P0 段落死保。摘要以 <system-reminder> 标签包住、作为一条历史消息注入,插在近期原文之前,既压缩了信息量,又最大限度保住了会话连贯。

                            对话再长呢?摘要之上还能再做摘要。当已有一份摘要、又积累了一批新对话,框架会以合并更新的方式做增量摘要——在旧摘要基础上更新各段,而不是从头重写。于是摘要的质量随对话深度线性提升,而不是反复推倒重来。

                            顺带对照一下 AgentScope Java 的思路:它的短期记忆走标准的消息容器

                            ( InMemoryMemory ),长期记忆则通过 LongTermMemory 接口委托给 ReMe / Mem0 /阿里百炼等外部服务——重心是"记忆服务的对接"。回到"单会话内不忘事"这个问题上,它的重心不在这里;我们更像在做"记忆的注入形态"。两种取向没有对错,解决的是不同层次的问题,甚至可以叠加。

                            4.3 悬空调用修复:服务端才会踩到的坑

                            还有一个真实生产才会踩到的坑:服务中断。假如一轮工具调用刚发出、结果还没回来,进程就重启了,库里就留下了一个悬空的工具调用——这违反了大模型 API 的消息协议,下次直接报错。框架在加载历史时会自动检测并修复这种残缺,把违规的悬空消息剔除干净,让会话能安全地接着跑。这类"脏活",正是分布式 Harness 该替业务扛下来的。

                            4.4 动态预算:为什么固定配额会翻车

                            那么,超不超预算这条线,到底谁来划?

                            给历史消息分配固定配额(比如窗口的 80% 留给历史)这个想法,建立在一个错误假设上——prompt 里除历史之外的部分是稳定的。它一点都不稳定:系统提示词(从几十到三千多 token)、工具 Schema(20 个工具轻松过万)、当前用户输入(一句"好"是 1 token,粘贴一份日志是几千 token)——固定比例要么太保守、要么一遇工具增多就溢出。

                            正确的算法不是"取窗口的某个比例",而是"窗口减去所有已知固定开销之后,剩下多少给历史"

                              有效窗口   = 上下文窗口 − 预留输出(默认 8000) − 安全缓冲(默认 3000)

                              固定开销   = 系统提示词 + 工具 Schema + 当前输入

                              历史预算   = 有效窗口 − 固定开销

                              预估总量   = 固定开销 + 摘要 tokens + 历史 tokens

                              触发压缩   ⇔  预估总量 > 有效窗口 × 阈值(默认 0.90)


                              关键在"先扣后算":不可压缩的输出预留和安全余量先扣掉,固定开销再扣掉,剩下的才是历史的真实空间;判断是否压缩时,摘要本身也占地方,必须算进去。所有 token 数由一个本地近似估算器算出——英文约 4 字符 1 token、中文约 2 字符 1 token、JSON 上浮 15%——不调用远程 tokenizer,靠 10% 的阈值余量兜住估算误差。

                              五、可观测性:Span + Event 树

                              Agent 的故障模式和传统服务根本不同:没有异常堆栈,没有错误码,服务运行一切正常——只是推理方向偏了。传统 APM 能覆盖调用链路和耗时分布,但覆盖不到推理层:模型在哪一步、基于什么证据、做出了什么判断,这些信息在现有监控体系里是缺失的。

                              5.1 一个真实的排障案例

                              用户问:"帮我看看为什么昨天下午订单转化率跌了。"Agent 调了几个工具,最后回答:"经查,是支付网关超时率上升导致的转化率下跌,建议排查支付链路。"

                              结论有零有整,业务方信了,排查支付链路一整天,结果发现支付一切正常。

                              问题到底出在哪?如果没有可观测性,你只能靠猜。而当你能把这次会话完整回放出来,真相一目了然:

                              真相浮出水面:那个查超时率的工具,数据只覆盖到中午 12 点,而下跌发生在下午两点后。模型拿到的是一份残缺数据,却把"上午的上升趋势"错误外推成了"下午的根因"。

                              错误不在模型笨,而在于它拿到的证据本身有问题,且没人能看见这个断裂。有了完整的 Span + Event 回放,你一眼就能锁定:不是模型的锅,是那个工具的数据覆盖范围有问题,去修工具,而不是去调提示词。

                              5.2 认知可观测 vs 传统监控

                              这就是认知可观测性和传统监控的根本区别:它记录的不只是调用发生了,而是模型基于什么证据、做出了什么推理、得到了什么结论。

                              我们把一次 Agent 执行,建模成一棵由Span和 Event 组成的树:

                              • Span 是有始有终、可嵌套的执行区间:一次会话套着多轮对话,每轮里有模型调用和工具调用。它天然还原了 Agent "思考—行动—再思考"的递归结构。

                              • Event是 Span 内部的关键瞬间:模型的思维链、最终回复、工具的入参与出参、以及错误。

                              尤其是 Thinking 事件——模型的思维链被显式捕获下来。上面那个例子里,正是第 3 轮那句"有上升趋势 → 大概率是它导致的",暴露了模型的推理跳跃。没有它,你永远只能对着一个错误结论干瞪眼。

                              5.3 可观测性后台

                              那么,如何让这些认知层的可观测事件——思维链、证据链、工具入参出参、token 消耗、错误现场——被开发者直观地感受到呢?一个好用的可视化后台同样必不可少。为此,我们把整棵 Span + Event 树做成了一个专门服务于 Agent 开发的可视化平台。

                              通过它,开发者可以按会话回放 Agent 的每一次执行,把模型看到的"有效上下文""每一步的思维链""工具的入参与出参""token 与耗时的分布""异常事件的现场"一并摊在同一个视图里。最终答案只是结果,Trace 才是调优入口——写完一版提示词、加了一个工具、换了一个模型之后,改动到底让 Agent 变好了还是变差了,不再靠肉眼比对输出去猜,而是能落到一条条可对照的证据上

                              六、Spill:大结果的溢出保护

                              短期记忆管的是随时间累积的膨胀,但还有一类膨胀是瞬间的——单次工具调用就能返回 5 万字。我们踩过这个坑:一个 BAT 生态的 MCP 工具,某次调用甩回将近 5 万字的报文。这份报文一旦原样进入上下文,三件事同时发生:

                                预算瞬间击穿——单条消息就吃掉大半个窗口,其它历史被迫大规模压缩甚至丢弃;

                                注意力被稀释——模型淹没在海量它根本不关心的字段里,真正该看的那几行反而被忽略,输出质量肉眼可见地下滑;

                                成本被引爆——这份报文会跟着后续每一轮对话反复重新发送,token 一次次翻倍计费。

                                而模型绝大多数时候只需要其中某个字段,或者只需要知道这个接口调通了、数据拿到了。

                                6.1 思路:类比操作系统的内存交换

                                我们的应对,叫 Spill(溢出保护)。思路和操作系统的内存交换如出一辙:内存(上下文)放不下的大块数据,落到磁盘去,在内存里只留一个指针。

                                具体来说,任何工具的返回值,一旦超过阈值(默认 32000 字符),框架会自动接管:

                                • 把完整原文落盘持久化,一个字节都不丢;

                                • 给模型的上下文里,只留一段预览(默认前 2048 字符)+ 一句明确的说明 + 一个可回读的路径。

                                模型看到的,从一堵 5 万字的墙变成了这样:

                                  [工具结果过大,已溢出到磁盘]

                                  预览(前 2048 字符):

                                  {"code":0,"data":{"list":[{"id":"...","name":"..."} ...

                                  完整内容已保存至:spill://order-assistant/conv-abc/tool-7f3a.json

                                  如需完整数据,可使用读取工具按该路径获取。


                                  这个设计的巧妙之处在于,它把要不要看全文的决策权,交还给了模型自己。绝大多数情况下,预览里的信息已经足够它继续推理;万一真需要全文里的某个细节,它可以主动拿着路径去回读——甚至只读其中一段。

                                  信息一点没少,但它从"强行灌进大脑"变成了"需要时再查阅的档案"。

                                  6.2 几个我们打磨过的细节

                                  按 tool 粒度可配置。哪些工具触发、阈值多少、预览多长、要不要落盘,都能挂到策略上按工具定制。有些工具的输出天然结构化(比如 JSON List),可以在预览时智能截取前若干项 + 计数摘要;有些工具的输出是纯文本报告,直接截前 N 个字符就够了。

                                  回读工具支持范围读取。回读接口不是要么给你全文、要么什么都没有,而是允许按字节区间、按 JSON path、按分页游标读取——避免回读又把上下文爆一次。模型看到一个 5 万字的 spill 文件路径时,它可以只回读第 3 到第 5 条 list 项,而不是被迫拿全文。

                                  命名空间和会话生命周期绑定。Spill 文件按 agentName/sessionId/toolId 组织,天然属于一次会话的资源。会话结束(无论成功、失败、取消、超时),这批文件跟着会话作用域一起被清理,不会在磁盘上留下孤儿。

                                  并发一致性。多个工具在同一轮里并发返回、并发触发 Spill 时,文件命名要不冲突、回注消息要顺序对齐、可观测 Span 要各挂各的——这些一致性细节在虚拟线程环境下都经过了针对性测试。

                                  "大工具返回值该往哪放"这个问题,不是我们独家看到的坑。Spring AI 目前还没有这一层的原生抽象,工具返回值直接进上下文;LangChain 一侧靠调用方手动 truncate——信息就直接丢了。有意思的对照来自 AgentScope Java,它的 ToolResultEvictionMiddleware 思路和我们的 Spill 几乎撞在一起:超过阈值自动接管、原文落盘、上下文里换成预览占位符、模型按需回读。它甚至在设计文档里明确区分了两件事——eviction 解决"上下文的宽度"(单条消息太大)、compaction 解决"上下文的深度"(消息太多),和我们把 Spill 与短期记忆压缩分成两层的思路完全一致。不同团队独立收敛到相近的方案,这本身就说明"大工具返回值该落盘 + 预留回读入口"是这类问题现阶段的合理解。差异更多在细节和归属——阈值、预览方式、挂载层次、命名空间——来自各自场景的具体约束,而不是设计思路的分歧。

                                  七、能力供给:填平 Skill 的空白 + MCP 热插拔

                                  Agent 的能力边界,由它手里的工具决定。这里有一对天生的矛盾:

                                  • 工具给少了——Agent 啥也干不成;

                                  • 工具给多了——每个工具的名字、描述、参数 Schema 都要塞进上下文,20 个工具轻松吃掉上万 token,不但烧钱,还稀释模型注意力。

                                  更别提工具还会变:今天上线一个新数据源,明天下线一个旧接口。难道每次都要改代码、发版?

                                  7.1 拆解一:填平 Spring AI 在 Skill 上的空白

                                  Skill 按需加载的思路早已是业界共识:上下文里只放技能清单(name + description),模型判断需要时,再调工具捞正文。这一层机制本身不新——新的是 Spring AI 在这件事上是一片空白,业务方要么自己拼加载器,要么把指令全塞进 system prompt。

                                  我们把 Skill 作为一等公民补齐,做了两个来源的实现:

                                  • 内置 Skill(classpath 加载):团队沉淀的通用能力——日志排查、大工具输出处理、ClickHouse 查询等——以 jar 内置形式随框架下发,引依赖即得。

                                  • DB 动态 Skill(后台可配):每次 spawn() 拉取当前 (appId, agentName) 绑定的技能清单,后台上架、编辑、绑定,下一次 spawn 即生效——不改代码、不发版。

                                  同名 DB Skill 覆盖内置 Skill。平台方提供默认能力池,业务方按需扩展或覆盖。

                                  7.2 拆解二:让工具能"热插拔"——MCP 动态工具注册

                                  工具集本身可由配置中心(如 QConfig)驱动、运行时热更新:改一份配置即时生效,全程不重启、不发版。

                                  热更新的难点在"安全":更新的瞬间,可能正有请求在用旧工具。两个机制兜底:

                                  • 差量刷新:只动真正变化的部分,避免"配置一变就全量重连"的雪崩。

                                  • 引用计数 + 延迟关闭:要下线的工具连接,等它身上所有在途调用都结束才真正释放——绝不会在请求执行到一半时把连接抽走。

                                  7.3 内置原子工具

                                  框架还内置了一批开箱即用的原子工具:文件读写、命令执行、任务清单、HTTP 调用等——都是我们在多个业务场景里反复用到、抽象出来的最小可复用能力集。

                                  八、并行工具调用:能同时做的事,别排队

                                  还有一个体感极强的痛点:慢。

                                  模型常常一次性决定调好几个相互独立的工具——查订单、查物流、查用户等级。串行执行意味着耗时累加,但这几个调用之间根本没有依赖,没必要排队。

                                  8.1 虚拟线程:契合"大部分时间在等网络"的场景

                                  框架的做法很直接:当模型在一轮里请求了多个独立的工具调用,用Java 虚拟线程把它们并发执行——总耗时从各段相加变成取最长的那段。虚拟线程极其轻量,成百上千个并发的 IO 等待也扛得住,契合工具调用这种"大部分时间在等网络"的场景。

                                  8.2 并发了,但不能乱

                                  • 结果顺序对齐:并发返回的工具结果回注 Prompt 时,要和模型请求顺序严格对齐——不能因为查物流比查订单快 200ms 就颠倒。

                                  • 观测 Span 不串味:每个工具调用挂在自己那条 Span 子树上,Thinking / ToolInput / ToolOutput 归属不错乱。

                                  • Spill 和微压缩在并发下照常工作:多工具并发触发 Spill 时文件命名不冲突;微压缩"完结轮次"的判定依然正确。

                                  这些一致性细节,框架都在底层处理干净——业务侧感知不到并发的复杂,只感知到变快了。

                                  九、端到端实战:一次排障会话,把所有机制串起来

                                  单看每个机制,都像一个独立的补丁。但它们真正的威力,在于协同。我们用一个贯穿始终的场景,把它们串成一条线。

                                  用户:"帮我排查下为什么订单 ORD-2024-0117 一直卡在'支付中'。"

                                  第 1 步——技能与工具就位。 收到问题,Agent 扫一眼上下文里的技能清单,判断这是支付排障,用内置工具把"支付状态机排查"这份技能的正文加载进来。同时,配置中心早已把这个环境该有的查询工具热插拔就绪。

                                  第 2 步——并行取证。 模型一次性决定:查订单主表、查支付流水、查网关回调日志。三个调用互不依赖,框架用虚拟线程并发执行,耗时取最长的一段,而不是三段相加。

                                  第 3 步——大报文不炸场。 网关回调日志甩回来一份 4 万字的报文。它没有污染上下文——超过阈值的部分被自动落盘,模型只拿到预览和一个回读路径。模型瞄一眼预览,发现关键信息不在里头,于是拿着路径只回读了它需要的那一段。上面这几步,都发生在响应这同一个问题的过程里,即模型内部"思考—取证—再思考"地递归推进,整个过程被记录成一棵 Span/Event 树。

                                  聊到后面几轮——记忆不漂移。 排障很少一问一答就结束:给出初步结论后,用户往往接着追问——"那网关重试过没有""换昨天同一时段再看看"。这样一来一回,就成了多轮对话。压缩正是在这里发挥作用:它不发生在某一轮的内部推理中,而是当新一轮对话到来、框架把历史加载进来准备注入模型的那一刻才触发。此时,前几轮里那些完整的工具返回值,被微压缩成"查过了、结果如何"的事实条目;更早的几轮被折叠成结构化摘要,而"用户要排查 ORD-2024-0117 的支付卡单"这个目标,始终被稳稳锚定在摘要的 P0 段落里——哪怕聊到第 20 轮,Agent 依然清楚自己在查什么。

                                  结论给出后——一切可回放。 整个过程被完整记录成一棵 Span + Event 树。万一结论有问题,你能一眼看到模型在哪一步、基于哪份证据、想岔了。

                                  会话结束——干净收场。 无论这次是顺利结案还是中途被取消,会话谢幕的那一刻,spill 文件、内存缓存、临时工具连接被成套释放,不留一点残渣。

                                  而这一整套协同,业务方几乎一行都不用写。 你只管把对话喂进去,把业务工具接上去;压缩、预算、锚定、修复、观测、清理,全在后台悄悄运转。业务代码里,剩下的就是那件你本该专注的事:把这个领域的问题解决好。

                                  十、Roadmap:我们还在往哪走

                                  Spring-Ai-Trip 解决的,是"让 Agent 稳稳跑在生产里"这一层的问题。往前看,还有更大的图景:

                                  • 更强的 Agentic Loop: 让 Agent 的自主规划、反思、纠错能力更成熟,并支持Plan Mode、Sub Agent,从"能完成任务"走向"能把任务完成得更好"。

                                  • 长期记忆: 短期记忆解决一次会话内不忘事,长期记忆要解决跨会话地积累经验、认识用户。

                                  • 自愈与容错: 把"悬空调用修复"这类点状能力,扩展成一套系统化的故障自恢复机制。

                                  • 提示词治理: 让提示词像代码一样,可版本化、可评测、可灰度。

                                  写在最后

                                  回头看,Spring-Ai-Trip 做的所有事情,其实都围绕一句话:

                                  把"会调大模型"和"能在生产里跑好一个 Agent"之间那道鸿沟,用一层 Harness 填掉。

                                  它不替代 Spring AI,而是叠在上面;它也不去和 Spring AI Alibaba、AgentScope 抢编排层的位置,而是专心把单个 Agent 内部怎么活下去这件事做好——记忆、Spill、可观测、能力供给、并行工具调用,每一层都是我们在业务里被问题绊过一次之后,补上的一块。它们对业务方大多只是一行配置,但每一行背后,都是从 Demo 到生产之间必须过的一道坎。

                                  如果你也在 Java 这边做 Agent,也在被这些问题反复折磨,希望文章里的思路对你有用。

                                  【推荐阅读】

                                   “携程技术”公众号

                                    分享,交流,成长

                                  跳转微信打开

                                  干货 | 200G内存尖峰、数十万Pod迁移:携程Karmada规模化治理实录

                                  2026年7月10日 12:00

                                  原创 扎克 2026-07-10 12:00 上海

                                  用联邦层承载全局治理,用成员集群保留本地自治

                                  作者简介

                                  扎克,携程资深云原生研发工程师。长期关注 Kubernetes 多集群、弹性调度与控制面稳定性建设,深耕复杂基础设施系统在真实业务流量下的落地与演进。

                                  导读:多集群治理并不只是把应用分发到多个 Kubernetes 集群这么简单。

                                  在大型在线业务场景下,基础设施平台既要统一分发资源,又要在容量变化、集群拆分、故障切换和基础组件交付过程中保持足够稳定。尤其是交易型业务,对弹性、可用性和变更平滑度都有很高要求:联邦控制面不能成为运行时强依赖,也不能在规模扩大后成为新的性能瓶颈。

                                  携程很早就开始了 Kubernetes 集群联邦实践。早期,我们主要使用 Kubefed 解决跨集群资源同步和统一管理问题。随着业务规模增长,多集群逐步从“资源分发”走向“生产调度与规模化治理”,平台侧需要更主动地控制应用跨集群分布,并在容量变化或异常场景下完成平滑调整。

                                  在这个过程中,我们逐步引入 Karmada,并将其作为新一代多集群联邦控制面的基础。如今,Karmada 已在携程用于多集群高可用、跨集群迁移以及基础组件统一交付等场景:累计完成数十万个 Pod 迁移,并将新集群 baseline 组件的初始化时间从数天缩短到数小时。

                                  本文会围绕三个层面展开:

                                  • 架构演进:为什么从 Kubefed 走向 Karmada,原有联邦模型在哪些生产场景下遇到边界;

                                  • 生产落地:如何支撑多集群高可用、跨集群平滑迁移和新集群基线组件初始化;

                                  • 规模化治理:几十万级资源规模下,如何优化控制面状态同步、启动成本、内存压力和策略权限边界。

                                  一、为什么从 Kubefed 走向 Karmada

                                  二、Karmada 在携程的生产落地

                                  三、规模化使用中的问题与优化

                                  四、后续方向

                                  一、为什么从 Kubefed 走向 Karmada

                                  在携程早期的集群联邦实践中,Kubefed 承担了部分资源联邦分发和多集群管理职责。它当时主要承担跨集群资源同步和统一管理的工作,也支撑了早期联邦能力建设。

                                  但随着多集群场景从简单资源分发扩展到容量调度、应用迁移和弹性治理,平台侧对联邦能力的要求发生了变化。Kubefed 的模型开始暴露出一些局限。

                                  1.1 资源模型引入额外适配成本

                                  Kubefed 通过 FederatedDeployment、FederatedConfigMap 等 federated 对象描述联邦资源。原生 Kubernetes 资源需要被转换成对应的 federated 资源后,才能参与多集群分发。

                                  这会带来额外的模型适配成本。原有围绕 Kubernetes 原生对象构建的发布、审计、运维链路,以及平台侧基于原生资源扩展的增强能力,都需要做相应改造。对于已经沉淀了大量 Kubernetes 原生能力的平台来说,这类改造成本并不低。

                                  1.2 平台策略与业务配置耦合

                                  在 Kubefed 模型中,业务资源定义、分发策略和集群差异配置往往集中在同一个 federated 对象中。

                                  当平台侧需要调整调度策略时,通常只能通过修改 federated workload 实现,而这类对象又通常由业务侧维护。这会增加变更成本,也不利于平台侧统一治理。随着多团队、多集群共用同一套联邦能力,这种耦合会进一步放大协作复杂度。

                                  1.3 缺少控制实例分布的上游入口

                                  在携程的联邦 HPA 场景中,成员集群必须保留本地扩缩容能力。扩缩容是高频核心链路,不能强依赖联邦控制面;否则一旦联邦控制面不可用,业务应用的自动扩缩容也会受到影响。因此,我们将实时扩缩容保留在成员集群内,由各成员集群 HPA 根据本地指标独立完成;联邦层则用于表达资源分发策略和跨集群调度意图。

                                  在携程旧有的 Kubefed 体系中,各成员集群可以独立扩缩容,但联邦层只能把当前副本结果记录回 federated workload。这能反映现状,却不方便表达平台侧的分布目标。比如管理员希望应用实例在两个集群中的比例按 3:7 分布时,Kubefed 缺少类似 weight 的配置入口。

                                  基于以上原因,我们开始采用 Karmada 作为新一代多集群联邦控制面的基础。

                                  与 Kubefed 不同,Karmada 并不是通过为每类资源重新定义 federated 对象来完成分发,而是尽量保持原生 Kubernetes 资源不变,并将业务对象、平台策略和调度结果拆开管理。

                                  业务资源仍以 Deployment、Service、ConfigMap、HPA 等原生 Kubernetes 对象存在;平台侧通过 PropagationPolicy、OverridePolicy 等策略对象描述分发范围、分布权重和集群差异配置。这样,业务对象不需要为了联邦分发改变形态,平台侧也可以在业务对象之外独立表达调度策略。

                                  对于携程需要控制实例分布、进行跨集群 Rebalance 的业务场景,Karmada 也提供了更明确的策略入口,例如通过 weight 描述应用在不同集群之间的目标分布。

                                  二、Karmada 在携程的生产落地

                                  引入 Karmada 之后,它最早承担的是资源分发入口,后来逐渐覆盖到多集群高可用、跨集群迁移和基础组件交付等场景。

                                  我们在架构设计中始终坚持一个核心原则:

                                  低频、全局、跨集群的能力放在联邦层;高频、局部、运行时强依赖的能力保留在成员集群内。

                                  这条边界决定了 Karmada 在携程生产环境中的角色:它负责全局策略、资源分发、状态聚合和跨集群调度意图,但不直接接管实时流量决策和成员集群内的实时扩缩容链路。

                                  2.1 韧性优先的多集群高可用架构

                                  携程有大量交易型业务,流量高峰明显,容量需求也具有很强的弹性。对这类业务来说,多集群架构不能只解决“资源分发到哪里”的问题,还必须保证故障发生时业务可以快速恢复。

                                  具体来说,我们会将无状态应用部署到多个成员集群中,每个成员集群都运行独立的 HPA 组件。正常情况下,各集群根据本地指标独立完成扩缩容。当某个承载线上流量的成员集群发生故障时,流量侧会基于实例健康状态摘除故障集群中的实例,并自动切换到其他健康集群;同时,健康集群中的 HPA 被触发扩容,完成自愈过程。

                                  在这个架构中,Karmada 负责分发应用资源和 HPA 对象,联邦层控制器负责状态聚合和 Rebalance 计算,但不直接接管实时流量决策和成员集群内的实时扩缩容。即使 Karmada 控制面短时间不可用,也只会影响应用更新和自动 Rebalance,不会影响已经运行服务的流量切换和本地 HPA 扩缩容能力。

                                  这也是我们在生产中非常看重的一点:联邦层需要足够可靠,但核心运行链路不应该把它作为实时强依赖。当前内部设计允许联邦控制面达到小时级别不可用,因为核心服务运行、流量切换和成员集群内扩缩容都不依赖联邦层的实时可用。

                                  这样的架构让故障影响面可以被限制在单个成员集群内,也让核心服务具备更强的高可用和容灾能力。

                                  2.2 权重驱动的平滑跨集群迁移

                                  随着业务规模快速增长,我们的部分 Kubernetes 集群曾经达到 5000 个节点以上。单集群规模继续扩大后,容量、运维和故障隔离都会遇到边界。因此,我们经常需要拆分集群,把应用逐步迁移到新的集群中。

                                  过去,这类迁移缺少管理员侧的统一能力,往往需要业务负责人通过重新发布应用来触发迁移。这个过程既耗时,也会增加业务侧的理解和操作成本。

                                  在 Karmada 体系下,我们在联邦层引入自研 fed-hpa-controller 和 Rebalance 状态机,用于聚合各成员集群的副本状态,并在迁移过程中按灰度批次推进实例分布调整。

                                  管理员可以通过 PropagationPolicy 中的 weight 声明应用在不同集群之间的目标分布比例,状态机会根据目标权重自动推进迁移。在生产操作中,目标权重也可以按阶段设置,用于控制整体迁移节奏。

                                  对于使用 HPA 的 workload,fed-hpa-controller 会结合 PropagationPolicy 中的 weight、各成员集群的实际副本数,以及 HPA 的扩缩容约束,驱动状态机计算每一批 Rebalance 的目标。

                                  执行时,状态机会优先扩容目标集群,使整体副本数在短时间内高于实际负载需求;随后源集群实例的平均负载就会下降,并由源集群本地 HPA 按缩容策略自然缩容。迁移节奏会与 HPA 的缩容稳定窗口对齐,避免副本数在集群之间来回抖动。

                                  对于不具备 HPA 的 workload,我们也在内部版本的 resourcebinding-controller 中补充了灰度控制逻辑,由控制器按固定步进自动推进副本分布调整。这样,跨集群平滑迁移能力不再局限于 HPA 场景。

                                  如果迁移过程中需要回退,也可以通过恢复上一版本 weight 触发反向 Rebalance,或者中止 Rebalance 后将期望状态重新对齐当前实际分布。

                                  目前,这套机制已经支撑我们在多个集群之间完成了大规模迁移,累计涉及超过数十万个 Pod。

                                  2.3 基础组件统一分发:从数天到数小时

                                  在多集群体系中,新集群创建完成并不意味着可以立刻承载业务。一个 Kubernetes 集群真正进入可用状态之前,还需要完成一组 baseline 组件的安装和初始化,包括网络、监控、日志、RBAC、Operator、平台插件以及其他支撑资源。

                                  这些组件数量多、来源分散,并且存在明确的依赖关系:有些组件必须先就绪,后续组件才能继续安装。

                                  在引入 Karmada 之前,这部分工作通常需要多个团队分别处理。不同团队维护各自的配置和发布流程,初始化过程中既要关注安装顺序,也要反复确认配置一致性。一次新集群交付往往需要持续数天。

                                  引入 Karmada 后,我们将基础组件分发收敛到统一入口。管理员只需要在控制面声明目标集群和分发策略,后续组件分发过程就可以自动推进。

                                  具体来说,组件之间的依赖和安装顺序由上层的 Trip Cluster Components Controller 负责编排。当前置组件就绪后,上层控制器再将后置组件纳入 Karmada 的分发范围,并通过 PropagationPolicy 下发到目标集群。Karmada 负责资源分发和状态保持,资源下发到成员集群后,继续按照 Kubernetes 原生方式运行。

                                  目前,这套能力已经覆盖数十个集群,新集群 baseline 初始化时间也从原来的数天缩短到数小时内,这让新集群从创建完成到具备业务承载能力的周期大幅缩短,也减少了扩容高峰期对多个团队串行配合的依赖。

                                  三、规模化使用中的问题与优化

                                  随着 Karmada 覆盖的集群和资源数量不断增加,我们遇到的问题也从“能力是否可用”逐渐转向“控制面能否在更大规模下稳定运行”。

                                  这些问题主要集中在三个方面:控制面高频状态同步、控制器启动成本、单实例内存压力。此外,多团队共用控制面后,策略权限边界也需要额外治理。

                                  3.1 高频状态同步带来的控制面压力

                                  Karmada 标准分发链路中,Work 是面向成员集群的资源载体,与成员集群对象存在 1:1 的映射关系;早期我们的 fed-hpa-controller 也沿用了 Work 进行分发。

                                  在 HPA 场景中,成员集群中的副本数、HPA status、ready pod 数量等状态会持续频繁变化。如果这些运行时状态都沿着联邦链路同步回 Karmada 控制面,Work 就会从资源分发载体变成高频更新对象。

                                  在生产中,这类高频更新曾经带来明显的控制面压力。部分场景下,Karmada 控制面中对应 Work 资源的更新频率可以达到每秒数百次。频繁读写会推动 etcd db size 增长,进而引发写入延迟劣化;Work 更新过快也会导致 karmada-controller-manager 的 informer cache 长时间滞后,进而出现大量 409 冲突。冲突后的重试又会继续放大整体负载,形成正反馈。

                                  针对这类问题,我们的优化思路是缩短高频链路,减少不必要的控制面写入:

                                  • 在内部版本 Karmada 中,弃用 Work 资源,将 Work 相关逻辑折叠进 resourcebinding-controller 和 fed-hpa-controller,避免每一次运行时状态变化都转化为 Work 更新;

                                  • 降低 HPA status 更新频率,减少联邦控制面的状态写入频率;

                                  • 对 watch event 做 batch 和去重,例如在短时间窗口内合并同一个对象的多次事件,减少 reconciliation 触发;

                                  • 升级 etcd 到 3.4,降低 db size 增长后对写入性能的影响。

                                  3.2 启动成本随资源规模放大

                                  karmada-controller-manager 启动时,需要先通过 List/Watch 建立控制面对象和成员集群对象的 informer cache。资源规模越大,首次 List 进行 cache 同步和存量对象入队处理的耗时就越长。在滚动发布或重启 controller 时,这部分启动成本会直接传导为业务用户感知到的发布延迟。

                                  这里的延迟主要来自三部分。

                                  第一,List 本身会随着对象数量增长而变慢,informer cache 同步时间随之变长,会延长 controller 新实例就绪所需时间。

                                  第二,如果 List 时间超过 kube-apiserver watch cache 能覆盖的时间窗口,后续 Watch 就容易出现 too old resource version,触发重新 List,并伴随 409 冲突和重试,进一步放大同步成本。

                                  第三,存量对象进入队列后仍然需要 controller 逐个处理。worker 并发、client QPS 和单次 reconcile 成本都不可能随资源量无限增长,因此资源量上来后,存量队列清空本身也会成为发布链路中的耗时点。

                                  对此,我们主要做了几类优化:

                                  • 启动阶段预加载 informer,等待 cache 同步完成后再上报 ready 并参与选主,从而在滚动更新过程中保留旧实例继续处理事件,降低新旧实例切换时的感知影响;

                                  • 调整 kube-apiserver watch cache 时间窗口,避免 too old resource version 错误。(在社区版本 v1.33 起可通过 --request-timeout 参数调整)

                                  • 对存量对象对账和新增变更事件区分优先级,引入优先级队列,优先处理新增和变更事件,将存量对象对账放到最后,降低业务用户的可感知延迟;

                                  • 写入前增加 deepEqual check,跳过无变化对象,减少无效 update 对 HTTP 请求 QPS 的占用,加快存量对账速度。

                                  3.3 karmada-controller-manager 内存压力

                                  随着纳管资源数量增加,karmada-controller-manager 的内存压力也会变得明显。内存占用主要来自几类对象和过程:

                                  • 需要 Karmada 进行分发的资源;

                                  • Karmada 控制面资源,例如 Work、ResourceBinding、PropagationPolicy、OverridePolicy;

                                  • 成员集群被纳管对象的 informer cache,且不仅包括被纳管对象,还包括该类别在成员集群的所有资源;

                                  • List/Watch 过程中的对象反序列化。

                                  在大规模下,启动或 cache 重建阶段的瞬时内存峰值会明显高于常态。尤其是在 dynamic informer 和 unstructured 对象路径中,数据从 JSON 字节流反序列化为 unstructured 对象进入 informer cache,会带来较高的对象化成本。

                                  当前线上较大规模下,Karmada 纳管资源量已经达到几十万级,karmada-controller-manager 在控制面启动时内存尖峰可达 200G。压测也表明,资源规模继续翻倍甚至数倍增长后,单实例内存会成为更明确的容量边界。

                                  当前可优先利用 watch list 相关能力。我们在基于 Kubernetes 1.36 的环境中验证后,观察到该能力可将启动时内存尖峰降低约 15%。

                                  此外,还有一些方向后续会继续评估:

                                  • 使用 CBORServingAndStorage feature gate,进一步降低传输以及编解码开销;

                                  • 对成员集群 informer 中冷数据使用 metadata informer,减少完整对象缓存;

                                  • 对类型固定、字段访问稳定的对象使用 typed informer,降低 unstructured 带来的编解码和内存开销;

                                  • 对部分大对象链路探索 bytes cache,减少不必要的编解码和 unstructured 对象化成本;

                                  • controller 分片,避免单进程承载过多对象。

                                  3.4 策略权限边界问题

                                  除了性能问题,策略权限边界也是深化使用后需要关注的点。PropagationPolicy 和 ClusterPropagationPolicy 通过 resourceSelectors 选择需要分发的资源。在多团队共用同一个 Karmada 控制面的情况下,如果缺少额外约束,就可能出现策略选择范围超过预期、不同团队策略互相冲突的问题。

                                  原生 Kubernetes RBAC 很难在统一资源类别内做细粒度约束。因此,我们在部分场景中引入 OPA 作为准入控制层,对 PP/CPP 的创建者、目标资源的 label、resourceSelectors 的匹配范围这几类信息做额外校验,避免策略越权选择其他团队的资源。

                                  这类问题本质上是多团队共享联邦控制面后必然会出现的治理问题。Karmada 提供了策略入口,平台侧还需要围绕这些入口补齐权限、审计和准入控制能力。

                                  四、后续方向

                                  后续,我们会继续推进历史 Kubefed 体系下线,并将更多基础设施治理能力收敛到 Karmada,减少两套联邦体系并存带来的维护成本,提升多集群交付和运维效率。

                                  同时,我们也会持续优化大规模场景下的控制面稳定性,减少资源规模增长对数据同步、缓存和控制器处理链路带来的压力。重点方向包括降低高频状态写入、优化启动阶段 cache 构建成本、控制单实例内存边界,以及探索 controller 分片等能力。

                                  回看整个演进过程,我们最核心的经验是:联邦控制面不应该接管所有事情,而应该明确自己的职责边界。低频、全局、跨集群的能力适合放在联邦层,例如资源分发、策略表达、跨集群迁移和基础设施治理;高频、局部、运行时强依赖的能力则应该保留在成员集群内,例如实时扩缩容、流量切换和本地故障自愈。

                                  换句话说,用联邦层承载全局治理,用成员集群保留本地自治。这条边界如果划不清,联邦控制面很容易从治理入口变成新的运行时风险点;划清之后,它才能真正承担全局治理的价值。

                                  【推荐阅读】

                                   “携程技术”公众号

                                    分享,交流,成长

                                  跳转微信打开

                                  AI专栏 | 上下文越多,Agent 越笨?开源框架 Flow2Spec 给出另一种答案

                                  2026年6月25日 17:00

                                  原创 Lands 2026-06-25 17:00 上海

                                  让项目在开发中自然长出知识图谱

                                  作者简介

                                  Lands,携程高级前端开发工程师。专注工程化实践、性能调优与底层架构设计。拥抱 AI 浪潮,推动 AI 辅助编码与 D2C 全链路落地,用前沿技术极致提升开发效率,重塑研发生产力。

                                  一、前言

                                  二、只做“记忆”为什么不够

                                  三、Flow2Spec的关键差异:开发过程生成知识图谱

                                  四、知识库接口:不是一个大文档,而是一套路由协议

                                  五、渐进式读取:AI 每次只拿该拿的知识

                                  六、多依赖能力:不让 Agent 只读到一半规则

                                  七、知识库正确性:不是写了 topic 就算完

                                  八、意图识别:不是所有话都应该自动进流程

                                  九、一个更真实的开发闭环

                                  十、它不只管知识,也管开发闭环

                                  十一、和普通知识库最大的区别

                                  十二、几个常见问题

                                  十三、适合什么项目+快速体验

                                  一、前言

                                  最近一年,很多 AI 编程工具都在解决同一个问题:让 Agent 记住项目上下文。

                                  这件事当然重要。但现在只说"项目记忆""上下文管理""规则文件",已经不够了。

                                  因为很多开源项目都在做类似的事:写一个 AGENTS.md/ CLAUDE.md,加一组 rules,建一个 docs 目录,让 Agent 先读项目说明,或者接入向量库做检索。

                                  这些方案能缓解问题,但我真正想解决的不是"启动时塞给 AI 一堆上下文"。我想解决的是:

                                  在真实开发过程中,项目知识能不能被持续沉淀、自动路由、持续验证,并且随着代码一起演进。

                                  这就是 Flow2Spec。一句话介绍:Flow2Spec 是一个让项目在开发过程中自然长出知识图谱的 Agent 工程框架。

                                  二、只做“记忆”为什么不够

                                  很多项目接入 AI 后,会很快遇到一个悖论:你希望 AI 多了解项目,但你给它的上下文越多,它越容易读不完、读偏、忘掉重点。

                                  于是大家不断加规则:先读这个文件,再读那个目录,这个模块不能改,那个接口有历史兼容,改完记得更新文档……最后上下文变成另一种负担。它看起来像知识库,实际上更像一个不断膨胀的说明书。

                                  Flow2Spec 的判断是:项目知识不能只靠"写下来",还要能被路由、被组合、被校验、被持续更新。

                                  三、Flow2Spec 的关键差异:开发过程生成知识图谱

                                  Flow2Spec 不是要求你先做一场大规模文档工程。它更推荐的方式是:

                                  1. 先 flow2spec init 初始化一个空骨架

                                  2. 用 f2s-doc-arch 生成项目架构说明,沉淀进知识库

                                  3. 真实需求来了,Agent 先按现有知识路由

                                  4. 功能实现后,用 f2s-kb-sync 把本轮确认的事实同步回知识库

                                  5. 下一次类似需求,再从这份知识中渐进读取

                                  知识不是一次性建设出来的。它是在需求澄清、技术方案、代码实现、修复问题、知识同步、提交代码的过程中逐步长出来的。

                                  这也是 Flow2Spec 和普通"项目记忆文件"的区别:普通方案更像给 Agent 一份说明书;Flow2Spec 更像给项目维护一张可演进的知识图谱——落在仓库里的 .Knowledge/ 中,能 diff、能 review、能随代码提交。

                                  四、知识库接口:不是一个大文档,而是一套路由协议

                                  Flow2Spec 的知识库有一个明确的接口结构:

                                    .Knowledge/
                                      manifest-routing.json   # 机读路由清单
                                      matchers/               # 关键词分片
                                      topics/                 # 主题摘要
                                      stock-docs/             # 已落地能力长文档
                                      req-docs/               # 需求 / 技术方案文档

                                    Agent 的读取顺序不是自由发挥,而是按协议走:

                                      manifest-routing.json
                                        -> matcher 分片
                                        -> topic 摘要
                                        -> topicDependencies
                                        -> stock-docs / req-docs
                                        -> 源码兜底

                                      这套结构的价值在于:知识库对 Agent 暴露的不是"文件",而是"怎么找到正确知识"的接口。

                                      manifest-routing.json告诉 Agent 有哪些主题;matchers/*.json告诉 Agent 这个需求可能命中哪些主题;topics/*.md给 Agent 短摘要和硬约束;topicDependencies告诉 Agent 哪些前置规则必须一起读;stock-docs/和 req-docs/只在需要时下钻。

                                      五、渐进式读取:AI 每次只拿该拿的知识

                                      Flow2Spec 的读取模型可以概括成四步:match → expand → verify → act

                                      match:Agent 先读 manifest-routing.json,再按任务读取对应 matcher 分片。不遍历整个知识库,先缩小候选范围。

                                      expand:命中主主题后,通过 topicDependencies继续读取依赖主题,避免只看到局部规则。比如一个功能可能同时依赖公共配置规则、鉴权规则、某个业务模块的约束。

                                      verify:命中 topic 不代表知识一定够。Flow2Spec 要求 Agent 在执行前检查:当前主题是否真的覆盖用户问题,是否缺关键依赖,是否需要读长文档,是否需要先反问用户。这一步把"看起来命中了"变成"确认可以执行"。

                                      act:只有在知识覆盖足够、边界清楚时,Agent 才进入实现、修改或提交。如果置信度不足,就先澄清,而不是硬改。

                                      六、多依赖能力:不让 Agent 只读到一半规则

                                      真实项目里,很多错误不是因为 AI 完全没读知识,而是它只读了一个局部知识,漏掉了前置约束:

                                      • 改功能时读了业务 topic,但没读提交规则

                                      • 生成技术方案时读了需求文档,但没读 req-docs / stock-docs 的边界规则

                                      • 修改配置时读了模块说明,但没读配置开关默认值

                                      Flow2Spec 把这些依赖显式放进路由层。一个 topic 可以声明它依赖哪些 topic,Agent 命中主主题时会先展开依赖。这不是简单的"多读几个文件",而是把项目知识从扁平文档变成有边的图:

                                        需求实现
                                          -> 文档路由规则
                                          -> 技术方案规则
                                          -> 任务追踪规则
                                          -> Git 提交规则

                                        这让 Agent 每次读取的不是孤立片段,而是一组经过声明的上下文组合。

                                        七、知识库正确性:不是写了 topic 就算完

                                        知识库最怕两件事:过期和写错。Flow2Spec 没有假设知识库永远正确,它把"验证"放进了开发流程。

                                        典型场景:用户问一个业务细节,Agent 先查知识库,发现 topic 有覆盖但不够细,继续读源码得到更准确的事实。这时 Flow2Spec 不应该只回答完就结束,还要判断:

                                        • 这个事实是否已经写进 topic

                                        • 如果没写或不够细,是否应该提示用 f2s-kb-distill 把本轮问答提取入库

                                        • 如果知识看起来已覆盖,是否能证明覆盖来源;不能证明就不能静默

                                        这就是"知识库补充建议收口"。它让 AI 从源码里找到的每次新知识,都不只留在本次聊天里,而是反哺回知识库。

                                        八、意图识别:不是所有话都应该自动进流程

                                        用户说一句话,Agent 到底应该回答、讨论、澄清,还是直接进开发流程?

                                        • "这个方案可行吗?" → 应该是讨论,不应该自动开始写代码

                                        • "修一下这个 bug" → 应该进入 fix 流程

                                        • "我想做一个新能力,先帮我把需求问清楚" → 应该进入需求澄清,而不是直接实现

                                        Flow2Spec 里有 intentRecognition开关,开启后 Agent 会按意图识别规则做辅助判断:高置信新增能力进入 feat 流程,高置信修复问题进入 fix 流程,需求不清楚进入 req-clarify,只是询问/讨论则保持普通对话。

                                        经过一段时间真实项目验证,意图识别已经比较稳定,建议默认开启,让 Agent 在大多数场景下自动分流;当然你也可以随时显式输入 f2s-req-clarify、f2s-kb-feat、f2s-kb-fix 等命令,覆盖自动判断结果。建议多显式使用 f2s skill**,熟悉这些技能的用法,可以更高效地使用 Flow2Spec。

                                        九、一个更真实的开发闭环

                                        使用 Flow2Spec 后,一个需求可能是这样流动的:

                                          用户提出需求
                                            -> 显式 f2s-* skill / intentRecognition 辅助判断
                                            -> f2s-req-clarify 反问到无歧义
                                            -> f2s-req-tech 生成技术方案
                                            -> Agent 按知识库渐进读取
                                            -> 实现代码
                                            -> changeTracking 记录任务进度
                                            -> f2s-kb-sync 同步新知识
                                            -> f2s-git-commit 提交前检查

                                          这条链路里,每一步都会留下可追踪的资产:需求文档在 req-docs/,已落地知识在 stock-docs/,主题摘要在 topics/,路由关系在 manifest-routing.json,任务进度在 .task/。

                                          Flow2Spec 做的不是"让 AI 单次回答更好",而是在把一次次开发过程转化为项目知识图谱的增量更新。

                                          十、它不只管知识,也管开发闭环

                                          任务进度落盘:开启 changeTracking后,Agent 执行功能开发或方案实现时,会把任务 checklist 写到 .task/。新会话继续做时,不需要重新问"上次做到哪",直接从磁盘任务接上。

                                          技术方案不硬套模板:f2s-req-tech会根据当前需求选择合适的技术方案结构,而不是把所有章节机械套一遍,避免前端改造也生成一堆数据库章节。

                                          多 Agent 编排与校验:复杂任务可以通过 subAgent拆给子 Agent 处理。如果开启 switchAgentVerification,还可以让写入方和验证方分离,降低单个 Agent 自己写、自己验、自己放过的风险。

                                          提交前知识覆盖检查:f2s-git-commit会在提交前检查 diff、冲突标记、暂存范围,也会检查本轮变更是否需要同步知识库,让"改代码后忘记更新知识"在提交前能被发现。

                                          模板与路由升级检测:Flow2Spec 启动时会检测 .Knowledge/结构版本,如果落后于 npm 包版本,Agent 会提示执行 f2s-kb-upgrade,确保项目知识结构与工具版本保持同步。

                                          十一、和普通知识库最大的区别

                                          如果只用一句话概括差异:普通知识库是给 Agent 查的;Flow2Spec 的知识库是给 Agent 参与维护的。

                                          普通知识库关注:文档放在哪里、怎么检索、怎么总结。

                                          Flow2Spec 更关注:需求来了该读哪个主题、主题之间有什么依赖、当前知识是否足够执行、源码兜底后是否要反哺、用户意图是否应该触发流程、改代码后知识是否一起更新、提交前是否检查过知识覆盖。

                                          这也是为什么 Flow2Spec 会同时包含 .Knowledge/、.task/、f2s-* skills、Agent rules 和 flow2spec.config.json——它们不是散件,而是一套围绕开发闭环组织起来的协议。

                                          十二、几个常见问题

                                          Q:改动一个能力后,怎么保证对应主题都能更新?

                                          Flow2Spec 通过五层机制提高覆盖率:

                                          • 路由层 matcher 找主 topic;

                                          • topicDependencies展开依赖 topic;

                                          • f2s-kb-sync先给出更新大纲让用户确认;

                                          • 普通问答下钻源码后提示补充;

                                          • f2s-git-commit提交前做知识覆盖检查。

                                          Q:Flow2Spec 怎么解决 Agent 遗忘规则的问题?

                                          分两侧看。

                                          • 使用侧:规则不塞进一个大文件,而是拆成可路由、可依赖的结构——入口规则写进各端配置、业务知识放进 topics、匹配词放进 matchers、依赖关系放进 topicDependencies、长文档放进 stock-docs / req-docs。Agent 每次不靠记忆,而是按 match → expand → verify → act 重新取规则。

                                          • 设计侧:五层约束分阶段拦截"规则写了但不遵守"的情况:

                                          • 入口层:声明读取顺序和禁止项

                                          • 配置层:执行任何技能前必须先读配置开关

                                          • 路由层:所有任务先读 manifest,不直接全仓搜索

                                          • 技能层:每个技能定义前置检查、确认点和收口方式

                                          • 门禁层:在多个节点分别设门禁——任务归档前检查 checklist、知识落盘前确认大纲、问答下钻源码后强制收口自检、代码提交前检查 diff 与知识覆盖

                                          两个典型场景说明这五层如何生效:一是防止意图误判(用户还在澄清阶段,Agent 不能跳去实现);二是防止源码答完后知识不反哺(必须判断是否需要 f2s-kb-distill 把本轮问答提取入库,不允许静默跳过)。

                                          Flow2Spec 的目标不是完全消除遗忘,而是让"绕过规则"在每个阶段都更难发生。

                                          Q:单个主题文件过大怎么办?

                                          topic 的定位是"路由摘要",记触发词、边界、关键约束和下一步指针,不承载所有细节。大功能拆成多个 focused topic,再用 topicDependencies串起来。Agent 先读概览判断相关性,再按需下钻具体子主题。

                                          Q:如果知识库没有覆盖当前模块怎么办?

                                          Flow2Spec 提供三个互补命令,按触发方式与粒度区分:

                                          f2s-kb-distill 由 Agent 自动提示:在一次问答中下钻源码找到答案后,把本轮问答提取入库;技能内部会按下钻深度与命中主题,自动判新建主题或补充既有主题。

                                          f2s-kb-add <路径或能力描述> 由用户主动触发:想把一个整体模块 / 历史能力一次性解析入库时使用,输入路径或多文件聚合,适合从未入库的整块代码。

                                          f2s-kb-sync 由用户主动触发:用于已实现能力的全局 / 批量同步,可零输入推断,先输出更新大纲再落盘,适合阶段性体检式补强。

                                          简言之:单次问答 → distill(Agent 自动),新模块整体入库 → add,多个已落地能力一次性同步 → sync。

                                          每次「从源码里找答案」,都可能变成一次知识库补强。

                                          十三、适合什么项目+快速体验

                                          最适合:中大型业务项目、长期维护的代码仓库、多人协作规则很多的项目、经常使用 Cursor / Claude Code / Codex 的团队、希望 AI 不只是"看文档"而是参与维护项目知识的场景。

                                          可能不适合:一次性脚本或非常小的个人项目(< 5000 行,一份 README 够用)。

                                          5 分钟快速体验:

                                            npx @double-codeing/flow2spec@latest init

                                            开始使用时建议优先显式输入f2s-* skill,熟悉这些技能的用法,可以更高效地使用 Flow2Spec。默认开启 intentRecognition 即可让 Agent 在常见任务下自动分流。

                                            常用流程:

                                              /f2s-req-clarify   需求澄清
                                              /f2s-req-tech      生成技术方案
                                              /f2s-kb-feat       新增能力并同步知识
                                              /f2s-kb-fix        修复问题并修正知识
                                              /f2s-kb-add <路径>  解析已有模块入库
                                              /f2s-kb-sync       全局/批量同步已落地能力到知识库
                                              /f2s-kb-distill    把本轮问答提取入库(自动判新主题或补充既有主题)
                                              /f2s-git-commit    提交前检查并生成提交信息

                                              目前已支持 Cursor、Claude Code、Codex 三端初始化,也支持中文 / 英文模板。

                                              结语

                                              AI 编程的终点不是"写更多代码"。真正难的是:让 AI 在长期项目里持续理解上下文,并且把每次开发产生的新知识沉淀下来。

                                              Flow2Spec 把项目知识从静态文档变成可路由、可依赖、可验证、可反哺的知识图谱。它让 Agent 不只是消费上下文,也参与维护上下文。

                                              如果你的项目已经出现"每次都要给 AI 解释同一套业务规则"、"AI 经常漏读前置约束"、"文档和代码越来越不同步"这类问题,可以试一下:

                                                npx @double-codeing/flow2spec@latest init

                                                开源地址:https://github.com/Lands-1203/Flow2Spec

                                                PPT演示:https://lands-1203.github.io/Flow2Spec/

                                                延伸阅读

                                                • Flow2Spec 官方文档:

                                                https://github.com/Lands-1203/Flow2Spec/tree/main/docs

                                                项目体系与原理、使用说明、命令详解的完整文档,包含多端配置差异说明。

                                                • Building Effective Agents — Anthropic:

                                                https://www.anthropic.com/research/building-effective-agents

                                                Agent 工程的权威指南,包含工具使用、上下文管理和多 Agent 协作的设计原则,是理解 Flow2Spec 规则环/技能环设计的重要参考。

                                                • Memory for Agents — LangChain:

                                                https://www.langchain.com/blog/memory-for-agents

                                                对 AI Agent 记忆机制的系统性分析,涵盖程序性/语义性/情节性三类记忆分层,以及热路径更新与后台异步更新两种实现方式,与 Flow2Spec 的 Memory Coding 理念形成对照。

                                                【推荐阅读】

                                                 “携程技术”公众号

                                                  分享,交流,成长

                                                跳转微信打开

                                                ❌