得物小摊是一个从 0 到 1 孵化的创新业务。在一段时间里，我需要同时负责 H5、运营后台、Node 网关和 Go 服务的设计、实现、联调和交付。

随着业务推进和协作范围扩大，一次需求常常要穿过多个工程与运行时。我开始让 AI 并行参与这些模块的开发。代码产出速度明显提高，一个人也像拥有了一支"虚拟全栈团队"。

AI 参与多模块协作后，一个人的有效工程半径得到扩展。

Codex 基于近期任务记录给出的开发能力评价。

但工程半径扩大以后，新的问题随之出现：怎样保证同一条业务规则跨过不同运行时后仍不变形，改动不越界，验证、验收和发布仍然可追溯？为了解决它，我把工作重点从“写出更聪明的 Prompt”转向探索一套面向单人全栈交付的 Harness。

在这条链路里，AI 可以检索、实现、补测试、整理报告，甚至同时推动多个模块；但每一次状态跃迁都必须有合同和证据支撑：需求是否读对，改动是否越界，业务不变量是否跨运行时成立，产品是否在真实设备确认，生产发布是否留下可追溯锚点。

我把这套系统叫做 Delivery Harness。它把一个人的工程判断固化成四个可复用组件：Version Contract 锁定事实，Execution Boundary 限制改动半径，Evidence Gate 控制状态跃迁，Repair Loop 把真实反馈变成下一次默认生效的规则。它不替代工程判断，而是把判断发生的时机、输入和结果留在可复查的链路里。即使由一个人推进，后续评审者也能看清为什么这样做、凭什么继续走。下面这篇复盘，讲的是它为什么出现、已经接住了什么，以及下一步还要继续建设什么。

真正让我警惕的第一个语义分叉很小：拼团页面里一个看似普通的进度数字，目标人数究竟取最低成团数，还是当前可售库存？

两个数字都在系统里，也都能解释得通。最低成团数表达“达到什么条件才成团”，库存表达“最多还能卖多少”。公式很简单，危险的是如果我在这里猜错，错误会顺着接口、页面、分享海报和验收用例一路传下去。

最初输入只是一段讨论。产品关心用户看到的进度是否合理，研发关心字段从哪里取，测试关心怎样构造可复现的状态。如果直接选一个“看起来更合理”的值开始写代码，后面的设计、实现和测试都会在错误前提上自洽。

这里的核心是一条业务语义分叉。AI 未必更容易猜错，却能用极高速度把一次猜测扩散成接口、页面、海报和测试里的共同前提。

我随后把失真链拆成五个控制点：输入偏差、执行越界、验证缺位、缺陷逃逸和反馈断裂。它们会级联放大：输入漏掉一条规则，设计里便没有对应分支；测试再锚定已有实现，最终，一个不存在的业务路径可能带着“已验证”的标签进入验收。

Delivery Harness 的第一目标很直接：让错误在最便宜、最靠前的位置暴露，并阻止未经证明的状态继续向后传播。

这套 Harness 包裹在模型之外，接管四件事：任务读取哪份事实、可以修改多大范围、结果怎样被证明、什么条件下必须停止。模型负责生成与判断，Harness 负责边界与状态。

Prompt 继续承载意图和上下文；权限、发布与证据门禁则交给确定性系统。路径、分支、文档登记、仓库范围和发布锚点一旦有客观答案，就不该让模型在每次任务里重新猜。

我会先区分两类问题：

• 路径、分支、文件范围、接口是否经过统一网关、发布记录是否完整，这些有明确答案，适合脚本和门禁。

• 产品口径、架构取舍、真实体验、跨文件语义，这些需要理解上下文，可以由受约束的 Agent 提出判断，但最终仍要有人负责。

四个组件共同形成一条闭环：Version Contract 给出事实；Execution Boundary 约束执行；Evidence Gate 决定是否推进；Repair Loop 再把真实反馈写回合同。

Version Contract 与 Execution Boundary 共同解决两个最容易失控的问题：本次交付究竟以什么为准，以及 Agent 到底被允许做什么。

“应该看什么”不是把所有资料一次性塞进上下文。事实应放在最接近它的位置：确认后的产品口径留在产品文档；影响范围和技术方案留在规格变更里；版本与交付仓库进入版本合同；验收结果进入统一报告；真实缺陷进入 Repair Case。任务开始时只加载本轮判断需要的部分。

这样做有一条硬边界：临时推断不能自动变成长期事实。只有被文档、代码或验证结果确认后，它才可以进入后续任务的默认上下文。

“允许做什么”则落到仓库和环境规则里。一次需求使用独立工作区和分支；跨仓改动要逐仓声明；客户端不能绕过统一请求层直连业务服务；测试环境的特殊入口不能顺手扩展到预发或生产；涉及外部写入、发布和消息发送时，没有明确授权就停止。

在这个项目里，worktree 不是一个 Git 使用技巧，而是 Execution Boundary 的第一层实现。每个新的产品需求、缺陷或独立技术需求，在首次写入前都要从已核对的稳定基线创建专属 worktree；纯只读分析不创建。已确认版本按版本与主题命名；未排期原型按日期与主题命名；开发分支使用统一命名空间。

同一需求从开发、UI 与接口联动、联调修复、验收整改到发布收口，全程复用第一次创建的 worktree 和分支。涉及多个代码仓时，每个仓库各保留一个工作现场。因此这里的隔离单位可以写成一句公式：一个需求 × 一个仓库 = 一个 worktree。多个仓库通过同一份版本合同关联，却不会共享未提交文件、分支状态和依赖现场。

Worktree 生命周期：只读任务不建树；首次写入先核对基线，再按仓库隔离工作现场；开发到发布收口持续复用，生产证据完整后才能安全清理。

清理也属于交付合同。只有生产发布记录成功、所有需保留提交已推送、发布记录完整且证据已经持久化，才允许从另一棵已注册工作树执行 git worktree remove，再执行 git worktree prune；禁止直接删除目录、禁止强制移除、也不会自动删除分支。这些约束进入版本合同和交付检查。

下面是一份经过抽象的版本合同结构示意：多份需求与技术文档进入同一版本，不同代码仓分别声明交付范围；测试、预发、统一验收与生产发布分别记录状态，未完成项保持 pending。图中只展示结构，不对应真实版本、仓库或发布数据。

Evidence Gate 不接受一句“代码完成”。编译、单测、接口验证、真实设备验收、生产发布和稳定分支合入，是六个不同状态；每一步都要拿出与结论匹配的证据。

每次交付必须回答四个问题：本版本登记了哪些需求与仓库；每条产品规则对应哪个用例；用例产生了什么可复查证据；哪些体验判断仍必须由产品责任人完成。答不全，状态就停在原地。

统一验收报告是一张“文档—需求—用例—证据”映射，而不是一段完成宣言。任何人都应能沿着它找到命令结果、真机截图、运行记录和未覆盖项。文档读取失败、规则没有用例、跨模块没有回执，状态统一保持 pending。

这里最容易混淆的是交付状态。它们之间不能画等号：

代码完成
≠ 研发验证通过
≠ 具备产品验收条件
≠ 产品真实环境验收通过
≠ 已生产发布
≠ 已合入稳定分支

自动化适合检查接口、状态、边界和页面元素。真实设备里的操作是否别扭，文案是否容易误解，容器和网络条件下的体验是否符合预期，仍需要产品责任人判断。AI 可以整理证据，不能替责任人签字。

下一阶段计划引入独立评估视角：由另一个评估 Agent 只读取需求、diff 和测试证据，再独立判断是否允许进入验收。生成与评估进一步分离后，证据门禁会更稳定。

Repair Loop 处理的是系统记忆。对跨模块、跨环境或容易复发的问题，只记录“最后改了什么”没有价值；原始反馈、定位过程、失败基线、候选结果与回归结果必须落在同一个 Repair Case 里。

我给 Repair Case 设置了一个较严格的完成条件：在不同提交上，基线检查必须失败；候选修复必须通过；回归检查也必须通过。客观上无法建立 red/green 对照时，Case 停在较早阶段并说明限制。环境恢复不能写成代码修复；偶现问题也不能因为暂时没复现就宣布解决。

一条反馈只有改变了下一次任务的默认行为，才算真正被系统吸收：能写成测试的进入测试；能固化为权限边界的进入门禁；能成为版本不变量的进入合同。Repair Loop 的终点不是复盘文档，而是下一次同类错误更早失败。

这套 Harness 第一次完整经受跨运行时考验，是一次多 SKU 履约改造。

一笔订单从用户端出发，经过管理端、Node 服务和 Go 服务，随后进入下游系统。任何一层把“订单”误解成“SKU”，都会制造局部正确、整体错误：前端显示完整，后台只处理一部分；接口返回成功，下游却生成多条互不关联的履约记录。

我们先把唯一不能被拆散的业务不变量写进合同：订单是履约原子单位。多个 SKU 共享同一次履约决策，要么整单接受，要么整单失败；外部回执必须依靠持久化的稳定标识回到原订单，不能靠当前请求临时猜关联关系。

多 SKU 履约的跨运行时链路。用户端、管理端、Node 服务与 Go 服务分属不同运行时，但必须共同保持订单级原子性。

Delivery Harness 在这里做了一件关键的事：把“订单级原子性”从一句产品口径变成跨运行时不变量。产品文档定义语义；接口合同约束输入输出；服务端校验资源与状态；测试主动构造部分失败的反例；验收报告记录跨服务结果；相关代码仓分别保留分支、提交与发布证据。

这套系统已经可以运行，但还不是一张可以宣布"大功告成"的架构图。目前还有三个方面需要继续建设。

• 第一：统一本地与持续集成的检查入口，让同一套规则覆盖真实提交与远端流水线。

• 第二：把完整的版本合同与交付合同接入流水线，使本地验证与远端门禁采用一致标准。

• 第三：统一稳定分支与版本合同的语义，让系统可以可靠判断版本是否已经进入稳定主线。

下一阶段的目标：让独立评估 Agent 只读取需求、diff 与证据作出第二判断；把完整合同检查接入 CI；再用运行观测把线上反馈自动送回 Repair Loop。

Delivery Harness 会让一次任务多出几步：核对事实源、确认边界、运行合同检查、整理证据、等待真实环境验收。只看生成瞬间，它更慢；放到完整交付周期里，它是在提前偿还返工、越权、误报和不可复现的成本。

它真正放大的是一个人的有效工程半径：我可以让 AI 同时进入四个运行时，却不必把所有质量判断留在自己的记忆里。合同负责守边界；证据负责推状态；真实反馈负责升级系统。

AI Native 交付的终局，是让模型承担越来越多执行工作，同时让每一个交付结论都能被检查、被复验、被追责。速度可以由模型放大，质量秩序必须由系统托底。

也正因为如此，我越来越确定，AI Native 改变的不会只是研发效率，也不会停在“产品写 PRD、研发拿 PRD 让 AI 生成代码”。当需求、版本、实现和证据开始由同一套 Harness 贯通，产研协作的基本单元会从文档交接变成可验证假设：产品定义业务不变量和真实体验标准；研发把它们翻译成接口合同、状态机、门禁与观测；AI 在两者之间持续补全方案、生成实现、构造反例并回放证据。

产品不必等到开发完成才第一次验收，研发也不必等到 PRD 看起来“百分之百完整”才开始工作。双方可以围绕同一事实源并行推进，但状态跃迁仍只有一套标准：假设是否被确认；边界是否被执行；证据是否足以支撑下一步。AI 负责扩大探索与执行速度，人负责业务判断、工程取舍和最终签字。

如果你对这个从 0 到 1 的创新业务感兴趣，也欢迎在得物搜索“娃衣开团”，看看这套交付方式最终承载的真实产品体验。

文 / 正飞

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

每年都有一批校招生走进得物技术部，他们大多都一样：有点紧张，有点期待，心里没底。

五年后，他们怎么样了？

这期我们找到了两位司龄5年的校招生——海狸和骅征，跟大家一起分享他们的故事。

海狸(Hayley)，2021年通过校招进入得物，

目前在交易平台做后端开发。

海狸（Hayley）目前在交易平台从事后端开发。

她给自己取“海狸”这个花名，是因为海狸擅长筑坝、修渠、搭巢，会主动改造自己的栖息环境。

“我觉得这和技术人的工作很像。不是只靠一时灵感做出一个漂亮的东西，而是通过持续建设，让系统和环境一点点变得更好。”

进入得物后，海狸从后端开发做起。参与AI导购项目后，她开始面对一类与过去不同的问题：需求并不总是清晰，答案也不一定只有一个。

项目需要AI相关的生产和分发导购内容。相比传统的接口开发，内容生产涉及用户理解、业务判断和效果验证，很多事情无法在一开始就被完整定义。

项目推进过程中，方案经历了多次调整。每一次变化，背后都对应着新的问题：如何让AI更稳定地完成任务，如何让系统能够持续运行，如何让方案真正适应业务场景。

“那段时间，每次升级，都像把之前搭好的积木推倒重来。”

海狸应对反复试错的方法，是把过程完整记录下来。每次架构调整、问题现象、决策原因和复盘结论，她都会及时留下记录。

“知道哪些坑踩过了、哪些路走不通，后面遇到类似问题时，就不用重新摸索。”

这段经历也让她开始承担更多连接技术与业务的工作。除了原有的开发任务，她还需要参与业务对接、需求挖掘和方案落地。

更大的变化在于，她不能只等待业务提出需求。业务同学未必能一开始就准确描述问题，而她需要进入具体场景，理解目标背后的真实痛点，再判断AI能否提供合适的解决方案。

“不能只是别人说什么我做什么。很多时候，要先把问题找出来，再去想技术怎么解决。”

这个过程并不轻松。技术、业务和项目推进之间不断切换，也让她重新认识了技术工作的边界：写出代码只是开始，真正重要的是让方案在真实环境中运转起来，并持续产生价值。

从后端开发到参与复杂的业务和AI项目，从相对明确的技术任务到开放性的问题，海狸逐渐形成了自己的工作方法。

“短期可能靠小聪明，但长期真正重要的，是把一件事持续做对的能力。”

她也强调，要把自己当成系统的第一个用户。只有亲自进入流程、体验工具、观察问题，才能判断一个产品究竟只是“做出来了”，还是确实解决了问题。

对海狸来说，技术工作的价值，不只是写出一段正确的代码，也包括在事情还没有答案的时候，先把问题拆开、把方案做起来，再在一次次实践中找到更好的方向。

“技术会过时，但解决问题的能力不会。没有答案的时候，先把事情做起来。”

骅征(huazheng)，2021年通过校招进入得物，

目前在国际技术做后端开发。

作为国际业务的研发，骅征入职后就参与了香港仓寄售项目，后面又参与了日本开仓、美国自建站搭建、全球买卖项目、BBMAX项目、韩国用户项目、三方开店项目。入职5年以来，经历了得物国际业务从香港进口、亚太扩张、美国建站（全球买卖雏型）、BBMAX+韩国（全球买卖一体化）到现在的海外用户+开店贸易的所有阶段。参与了国际业务几乎所有的大型项目。

但问他有没有自己的高光时刻，他反而不觉得有什么特别的瞬间。

“其实没有太多的高光时刻，善战者无赫赫之功。功夫都花在平时，把每一个小的需求做好，就不会有太多需要力挽狂澜的高光时刻。”

比如国际火山云的多云迁移。

交易的链路是核心域，牵扯个卖、企卖、保税、出海多个业务场景，数据一致性要求极高，C端要求低延时。上下游又依赖了支付、履约、库存、风控，同时还涉及MQ跨集群同步、DTS数据同步、内网域名修改等非代码的改造。

这类复杂而高风险的项目，往往不能当作一场孤注一掷的仗来打。它没有“发布一个炫酷新功能”那样的高光时刻——它的目标，就是让一切意外“不发生”。

“越是复杂的事情，越需要梳理出详尽的细节，否则一个小问题的遗漏，可能就会导致严重的后果。”骅征说。

把复杂的事拆成几十个小任务项，梳理所有涉及的改动点，再反复“压榨”AI继续找遗漏，把之前没想到的迁移项也一个个揪出来，按类整理。真正切换的时候，一个环节一个环节确认；灰度阶段，盯着报错日志一遍遍排查。

最终，整个迁移过程中RT只上涨了10-13毫秒，用户完全无感知，实现平稳迁移，并且显著降低了资源成本。

“没有高光时刻，就是最好的高光时刻。”他说。

业余时间，骅征和国际团队的小伙伴们还一起开发了一个AI工作伙伴——DewuSmartClaw。没有产品提需求，他们自己跑到产运和开发同学那里，一个个搜集工作里对AI应用的痛点。针对AI Coding带来的稳定性挑战，他们还在DewuSmartClaw中内置了名为Dev zone的编程工具。通过OpenSpec流程驱动，覆盖需求探索、方案设计、代码实现、自动验证、知识归档、代码审查、缺陷修复七个阶段，并通过Harness组件进行约束限制。在运用AI提高效率的同时，保证了代码质量。

“我们把自己逼成'半个产品经理'去琢磨用户体验，逼成'半个设计师'去打磨交互细节，又逼成'半个架构师'去守住系统稳定。”

骅征有一个小本子，记了好几年。“记的都是当时觉得重要、以后可能用得上的东西，翻起来会想起很多事，也能看到自己在不同阶段关注的东西不一样了。”

回看加入得物5年以来自己最大的变化：“之前是‘把事情做完’就结束了，现在会问自己有没有‘把事情做明白’。想清楚一件事，比快速做完一件事要难得多，也重要得多。”

“不管这件事有没有人看见，都得把它做成自己拿得出手的样子。”

在 MultiAgent 平台中，Agent 一次请求可能同时经过模型、MCP/A2A 工具、RAG、Workflow 和 Sandbox，还要在多轮对话和跨会话协作中记住用户偏好、任务进展与协作约定。因此记忆模块不是独立外挂，而是 Agent 执行链路的一部分。

在本项目中，记忆不是把全部历史简单拼到 Prompt，而是分别承接会话上下文、跨会话信息和上下文关联：

• 会话延续：短期历史无法支持指代消解和任务延续。

• 跨会话复用：跨会话无法复用用户偏好和稳定事实。

• 上下文关联：新增消息无法与已有上下文建立关联。

选型 MemOS：在 1540 个问题、10 个测试用户的评测中，综合得分 74.33%，单跳与多跳表现均达标（评测仅作选型参考，不代表生产 SLA）。

整体架构：后端基于 Spring Boot 3 和 Java 17，Agent 编排采用 AgentScope。新建 Agent 默认将 longMemoryProvider 设为 MEMOS，但 openLongMemory 默认关闭；开启后，请求开始时短期会话历史和长期记忆并行加载，会话结束后由 onSessionEndAsync 异步完成筛选、去重和长期沉淀。短期记忆以 MySQL 为持久化底座、Redis 为热点缓存，长期记忆以 MemOS 为主路径，同时保留 MySQL/Mem0 路由作为兼容路径。

本文只展开记忆模块的实现：包括四层记忆模型、短期历史的读取与写入、MemOS 的按 scope 检索，以及会话结束后的异步沉淀。

四层分别对应不同的生命周期：Working Memory 只服务当前一步推理；Session Memory 保存会话内的消息历史；User Memory 记录跨 Agent 共享的偏好和稳定事实，对应 MemOS 的 user_profile；Agent Memory 保存某个 Agent 的任务经验和协作约定，对应 agent_{agentId}。会话结束后，新增消息经过判断和去重，再从 Session 层沉淀到 User 或 Agent 层。

Agent 四层记忆模型：Working、Session、User 与 Agent Memory 的读取、作用域和异步沉淀链路。

四层模型与 MemOS 类型是两套分类维度：四层模型描述信息的生命周期和作用域；MemOS 的 text_mem、pref_mem、skill_mem、tool_mem 描述记忆内容形态，不能直接与四层一一对应。

当前路由行为：longMemoryProvider 未配置、Agent 不存在或读取配置异常时，MemoryRpcServiceImpl 选择 MySQL；明确配置为 MEMOS 或 Mem0 时才进入对应 Provider。MemOS 查询异常由 Provider 自身记录日志并返回空结果，当前不会自动切换到 MySQL。

一次请求的记忆路径可以概括为：AgentExecutor#execute 解析上下文参数后，在 memoryLoadExecutor 中并行启动短期记忆和长期记忆 Future。短期链路读取 ConversationMemory；长期链路调用 queryMemory，由 MemoryRpcServiceImpl 按 Agent 配置选择 MEMOS、Mem0 或 MySQL。

• 长期记忆检索返回后，平台按 user_profile 与 agent 分组，过滤敏感或低相关内容，并限制每个 scope 的条数。

• 随后以固定 tokens 为默认预算，优先满足用户画像，再把剩余预算分配给 Agent 专属记忆。

• 最终结果写入 AgentContext，与短期消息一起参与后续模型调用；会话结束后再异步触发长期记忆沉淀和上下文摘要。 

实现边界：平台的 ConversationMemory 负责会话历史读取和窗口裁剪；AgentScope Harness 的 state store 负责会话状态持久化，有 Sandbox 时使用共享工作区文件存储，没有 Sandbox 时回退到内存存储。当前 ModelInvoker 主链路构造 Harness 消息时，以本轮 userMsg 为入口，因此不能简单理解为 Redis/MySQL 历史会被无条件直接拼进每一次 AgentScope Prompt。

短期记忆（Session Memory）保存当前会话中按时间排列的对话历史，是指代消解和多轮推理的直接上下文。实现重点是读取时延、Redis/MySQL 回退以及 Token 窗口控制。

加载流程图

调用链说明：

• AgentExecutor 从 AgentContext 获取 AgentConfig → ModelBindConfigDto → contextRounds。

• AgentExecutor 调用 chatMemory.get(conversationId, contextRounds * 3)。

• chatMemory 是 ConversationMemory 接口，由 ConversationApplicationServiceImpl 实现。

• 实现类优先从 Redis 读取，失败则从 MySQL 回退。

完整实现还包括消息类型转换、system 消息拆分及工具调用信息处理。下面只保留“读取 → 交替校验 → Token 窗口判断”的主路径，便于理解短期记忆如何形成模型上下文。

Redis 优先读取，类说明：ConversationApplicationServiceImpl#getMessagesFromCache 先读取 Redis List，命中后把 JSON 转为 ChatMessageDto，并翻转为 oldest-first；未命中或读取异常则查询 MySQL，再按倒序 leftPush 回写，设置 CACHE_TTL_SECONDS，并用 rightPop 按 MAX_CACHED_MESSAGES 淘汰最旧消息。逐条解析和异常日志属于防御性代码，这里不展开。

使用 leftPush 写入，最新消息在 index 0；当前实现使用 range(0, Long.MAX_VALUE) 读取 Redis 列表，再在应用层做窗口裁剪；使用 rightPop 移除最旧消息 需要注意，ConversationMemory#get(String, int) 的 lastN 参数当前未参与 Redis 的 range 边界计算；实际读取范围由 Redis 列表内容和后续 Token 窗口共同决定。Redis 只承担热点缓存，MySQL 仍是冷启动回源和持久化兜底。

写入时序图

双写的意义——MySQL ：持久化兜底防止数据丢失。Redis： 高性能读取支撑实时对话。回退机制： Redis 失败时仍可从 MySQL 回退读取。

短期消息写入后，onSessionEndAsync 还会检查会话摘要：当未被摘要覆盖的消息达到 20 条才触发摘要生成，摘要注入预算约 2000 tokens，并在 Redis 缓存 1 小时。这样做把高频对话写入与低频摘要合并拆开，避免每轮都调用摘要模型。

加载时序图

在 Agent 执行入口 AgentExecutor#execute 中，我们采用 CompletableFuture 实现短期记忆和长期记忆的并行加载：

final int finalContextRounds = contextRounds;
CompletableFuture<List<Message>> contextMessagesFuture = CompletableFuture.supplyAsync(() -> {
    // contextRounds=0 是合法配置，直接跳过短期历史读取。
    if (finalContextRounds <= 0) {
        return new ArrayList<Message>();
    }
    return new ArrayList<>(
        chatMemory.get(agentContext.getConversationId(), finalContextRounds * 3));
}, memoryLoadExecutor);


CompletableFuture<Map<String, String>> longMemoryFuture = CompletableFuture.supplyAsync(() -> {
    if (agentContext.getAgentConfig().getOpenLongMemory() != AgentConfig.OpenStatus.Open) {
        return Collections.emptyMap();
    }
    try {
        AgentComponentConfigDto modelComponentConfig =
            agentContext.getAgentConfig().getModelComponentConfig();
        // queryMemory 需要绑定模型的 targetId，未绑定时不发起长期检索。
        if (modelComponentConfig == null || modelComponentConfig.getTargetId() == null) {
            return Collections.emptyMap();
        }
        boolean justKeywordMatch = resolveJustKeywordMatch(agentContext);
        // originalMessage 是主查询词；此处 context 为空，短期历史不会反向增强本次 query。
        return conversationApplicationService.queryMemory(
            agentContext.getUser().getTenantId(), agentContext.getUser().getId(),
            agentContext.getAgentConfig().getId(), modelComponentConfig.getTargetId(),
            agentContext.getOriginalMessage(), "", justKeywordMatch,
            agentContext.isFilterSensitive());
    } catch (Exception e) {
        // 长期记忆是增强能力，查询失败时让主对话继续。
        log.warn("查询长期记忆失败", e);
        return Collections.emptyMap();
    }
}, memoryLoadExecutor);


// 这里才是并行结果的汇合点，主流程等待两条记忆链路都完成。
agentContext.setContextMessages(contextMessagesFuture.join());
Map<String, String> longMemoryMap = longMemoryFuture.join();

设计要点：使用专用线程池 memoryLoadExecutor，避免 ForkJoinPool.commonPool 争抢；长期记忆不阻塞短期记忆，用空 context 先行查询。

边界与降级：关闭 openLongMemory 时长期 Future 直接返回空 Map；Agent 未绑定模型时跳过长期检索；查询异常也会记录 warning 并返回空结果，主对话继续执行。当前长期查询以 originalMessage 作为主检索词，和短期记忆的读取互不等待，因此并行带来的是执行重叠，不是"短期历史已注入后再增强查询"。

MemOS Search 请求保留以下参数；context 非空时，平台只取前 200 个字符拼到 userMessage 后作为 query。调用链虽然携带 justKeywordSearch，但当前 MemosMemoryApplicationService 未据此切换检索模式，仍固定调用 MemOS Search。

List<String> readableCubeIds = new ArrayList<>();
readableCubeIds.add("user_profile");
if (agentId != null) {
    readableCubeIds.add("agent_" + agentId);
}


MemOSClient.SearchRequest searchRequest = new MemOSClient.SearchRequest();
// 一次 Search 同时覆盖用户画像和当前 Agent 的记忆 cube。
searchRequest.setQuery(buildSearchQuery(userMessage, context));
searchRequest.setUserId(memOSUserId);
searchRequest.setTopK(DEFAULT_TOP_K);
searchRequest.setMode("fast");
searchRequest.setRelativity(0.45);
searchRequest.setDedup("mmr");
searchRequest.setReadableCubeIds(readableCubeIds);
searchRequest.setIncludePreference(true);
searchRequest.setPrefTopK(6);


List<MemOSMemory> searchResults =
    memOSClient.searchMemory(searchRequest).getMemories();
// 转换阶段会过滤低分结果、截断单条内容，再按 score 降序返回。
result.addAll(convertToMemoryUnitDTOs(searchResults, tenantId, userId, agentId));
result.sort((a, b) -> {
    if (a.getScore() == null && b.getScore() == null) return 0;
    if (a.getScore() == null) return 1;
    if (b.getScore() == null) return -1;
    return Double.compare(b.getScore(), a.getScore());
});

readableCubeIds 当前包含 user_profile 和 agent_{agentId}；同时开启 preference 检索，prefTopK=6 用于补充用户偏好。检索结果随后还会经过 score < 0.3 过滤和单条 1000 字符截断，避免低相关或过长内容挤占上下文。

以下片段承接 5.2 的检索结果，userProfileRaw 与 agentMemoryRaw 分别是按 scope 汇总后的文本。为防止记忆撑爆 Agent 上下文，我们设计了 Token Budget 分配机制。

int budget = DEFAULT_LONG_MEMORY_TOKEN_BUDGET; // 4000 tokens
int userProfileRawTokens =
    TikTokensUtil.tikTokensCount(userProfileRaw != null ? userProfileRaw : "");


// user_profile 最多占 60%；实际未用满时，剩余预算让给 Agent 记忆。
if (userProfileRawTokens <= budget * 0.6) {
    userProfile = userProfileRaw;
    agentMemory = truncateLongMemory(agentMemoryRaw, budget - userProfileRawTokens);
} else {
    userProfile = truncateLongMemory(userProfileRaw, (int) (budget * 0.6));
    // 重新计算截断后的 token 数，避免把截断前的估算带入剩余预算。
    int userProfileTokens =
        TikTokensUtil.tikTokensCount(userProfile != null ? userProfile : "");
    agentMemory = truncateLongMemory(agentMemoryRaw, budget - userProfileTokens);
}

截断算法采用按行截断，保留完整语义：

String[] lines = longMemory.split("\n", -1);
for (String line : lines) {
    // 按行累计 token，尽量保留一条记忆的完整内容。
    int lineTokens = TikTokensUtil.tikTokensCount(line + "\n");
    if (currentTokens + lineTokens > budget) {
        break;
    }
    truncated.append(line);
    currentTokens += lineTokens;
}

user_profile 最多占 60% 预算；如果实际占用更少，剩余空间分给 Agent 记忆。两类内容都按行累加 token，达到预算后停止追加，避免拆散单条记忆。

写入时序图

会话结束时，系统触发记忆写入流程，首先使用 Redis Set 记录已处理消息的 hash 并做去重。

类说明：MemoryRpcServiceImpl 负责会话结束后的写入编排，onSessionEndAsync 先获取会话级 Redis 锁，再由 processSessionEnd 按消息 hash 过滤本次新增内容并提前记录已处理 hash，随后根据 Agent 配置选择 provider：MemOS 路径先进行 LLM 记忆判断，再交给 MemoryPersistenceServiceImpl 持久化；MySQL、Mem0 路径则组装完整上下文和最新 user 输入后调用 createMemory。记忆处理完成后，同一异步线程继续检查是否需要生成上下文摘要。

设计要点：

• 分布式锁防止并发处理同一会话。

• MD5(role:content) 生成消息唯一标识。

• TTL 7 天自动清理过期记录。

onSessionEndAsync 使用 10 分钟的会话锁，已处理消息 hash 的 TTL 为 7 天。hash 会在 LLM 判断和 MemOS 持久化之前写入，用来挡住重复结束事件。但这一层属于 best-effort：Redis 读取失败时，当前实现会把整段会话作为新增内容继续处理；hash 写入失败也只记录日志。外部服务失败后没有自动回放，因此运行侧需要同时关注重复写入和处理未完成两类异常。

完整 Prompt 定义了记忆类别、scope、importance 和 JSON 输出约束，下面只保留新增消息标记与模型调用主线。judge 会先调用 LLM；调用异常或返回为空时，降级到仅基于新增消息的规则判断。LLM 返回不为空时，还会统一补齐缺省字段、过滤空内容，并将单条记忆截断到 200 字符。

private MemoryJudgeResult judgeByLLM(Long tenantId, Long modelId,
        List<MemoryMessage> fullContext, List<MemoryMessage> newMessages) {
    Set<String> newMessageKeys = newMessages.stream()
        .map(m -> (m.getRole() != null ? m.getRole() : "user")
            + ":" + (m.getContent() != null ? m.getContent() : ""))
        .collect(Collectors.toSet());


    StringBuilder content = new StringBuilder("## 完整对话上下文\n\n");
for (MemoryMessage message : fullContext) {
        String role = message.getRole() != null ? message.getRole() : "user";
        String text = message.getContent() != null ? message.getContent() : "";
        content.append(newMessageKeys.contains(role + ":" + text)
                ? "[[NEW] " : "[")
            .append(role).append("]: ").append(text).append("\n");
    }


    MemoryJudgeResult result = iModelRpcService.call(
        tenantId, modelId, JUDGE_SYSTEM_PROMPT, content.toString(),
new ParameterizedTypeReference<MemoryJudgeResult>() {});
return result == null ? null : validateAndFixResult(result);
}

判断要点：

• 按 role:content 生成消息 key 并标记重点内容，相同内容的历史消息也可能一并命中。

• 按 5 类信息定义 importance 区间（1-10）。

• 明确 scope 归属规则。

在持久化前进行本地相似度去重，减少不必要的写入：类说明：MemoryPersistenceServiceImpl#calculateSimilarity 按 exact、contains、字符级 Jaccard（阈值 0.7）和短文本 Levenshtein（阈值 0.8）依次判断，相似即标记为重复；空值或未达到阈值则返回 none。它只负责同批次的本地预去重，跨历史记忆的冲突仍交给后续冲突服务处理。

batchPersist 完成本地去重后，先按 memCubeId 分组，再调用 batchDetectConflict 获取每条候选记忆的冲突结果。下面只保留逐条决定"写入新记忆、跳过，或记录待失效旧记忆"的核心循环：

for (int i = 0; i < memoryList.size(); i++) {
    MemoryToSave memory = memoryList.get(i);
    MemoryConflictResult conflict = i < conflictResults.size()
        ? conflictResults.get(i) : MemoryConflictResult.noConflict();


    if (!conflict.isHasConflict()) {
        messagesToStore.add(createMessage(memory.getContent()));
        continue;
    }


    ConflictResolutionResult resolution =
        memoryConflictService.resolveConflict(
            tenantId, memOSUserId, memCubeId,
            memory.getContent(), conflict, modelId);
    if (resolution.isShouldStoreNew()) {
        messagesToStore.add(createMessage(memory.getContent()));
        if (CollectionUtils.isNotEmpty(resolution.getMemoryIdsToExpire())) {
            memoryIdsToDelete.addAll(resolution.getMemoryIdsToExpire());
        }
    }
}

这里的“批量”主要指按 memCubeId 分组、复用一批待写入内容；冲突服务的批量方法在实现内部仍逐条调用检测接口，再逐条决定保留新记忆、跳过或标记旧记忆。因此它减少了分组和编排开销，但不能等同于一次网络请求完成全部冲突判断。

为避免数据丢失，采用"先写新记忆，后删旧记忆"策略。

类说明：MemoryPersistenceServiceImpl#batchPersist 按 memCubeId 组装 MemOS 的 AddMemoryRequest，写入 userId、writableCubeIds 和 messages，并以 async、fine 模式调用 addMemory。只有返回结果中包含新增记忆时，才把冲突旧记忆 ID 交给 deleteMemories；删除异常只记录 warning，已经写入的新记忆继续保留。

这是一种"写入优先"的风险控制，而不是事务级一致性：MemOS 是外部 HTTP 服务，平台无法用本地事务同时包住新增和删除。当前删除失败只记录 warning，属于 best-effort；旧记忆可能暂时保留，后续检索或下一次冲突处理再进行清理。

这套实现把记忆处理拆成两条独立链路：请求前并行加载短期历史和长期记忆，会话结束后异步完成筛选、去重和持久化。核心策略集中在四点：

• 并行加载：短期记忆和长期记忆提交到同一个专用线程池，主流程在 join 处汇合。

• 新增消息标记：使用 [[NEW]] 标记本次新增消息，让 LLM 借助完整上下文提取新信息。

• 预算控制：短期历史采用滑动窗口并预留摘要空间，长期记忆按 scope 分组后分配固定 tokens。

• 可靠写入：Redis 锁和 hash 负责幂等，MemOS 侧先写新记忆、再尽力删除冲突旧记忆。

运行观测能力：系统提供运行概览、记忆类型分布、时间趋势、Top Agents 和 Cube 明细等查询能力，可用于了解记忆数据的规模、分类、来源及变化趋势，并支持按时间范围查看长期记忆搜索趋势，适合日常巡检、数据分布分析和异常定位。

短期记忆负责把当前会话带入下一轮，长期记忆负责把经过筛选的用户事实和 Agent 经验带到后续会话。两条链路在请求前并行读取，在会话结束后通过异步任务衔接；长期记忆再按 scope 和 Token Budget 控制注入内容。

当前方案已覆盖 Redis/MySQL 回退、MemOS 语义检索、LLM 判断、本地去重、冲突处理和先写后删。仍需补齐生产流量下的延迟与失败率观测，以及外部记忆服务失败后的补偿机制。

文 / 偶啦

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

直接在本地使用 AI Coding 工具，短期看，很方便，但团队化之后会暴露出几个缺口。

• Prompt 没有 Review

代码有 Code Review，prompt 没有。Agent 指令写得好不好、有没有歧义、有没有安全风险、能不能复用，往往只靠个人判断。

• 经验无法沉淀

日志排查步骤、部署检查方式、开发提示词通常只留在个人本地文件里，下一个人还要重新摸索。

• 过程缺少可见性

谁在用哪个 Agent？用了什么模型和 runtime？成功率、耗时、token 花费是多少？没有平台化就很难进入团队管理。

• 研发链路没有闭环

Agent 写完代码不是结束。代码审查、推送、部署、提测、CR 反馈、BUG 回流和日志巡检如果仍靠人手动接力，价值就停在局部提效。

EP-Harness 的核心价值，就是把这些缺口从个人习惯问题变成平台能力。

EP-Harness 可以理解为一个 Managed Agents 平台。它把 Agent 当成团队里的工作成员来管理：Agent 有身份、有任务、有状态、有执行记录、有可见性、有权限边界，也有自己的 instructions、skills、runtime 和历史产出。

技术基座：EP-Harness 是基于开源项目 Multica 的二次开发。Multica 官方定位是 open-source managed agents platform，核心思路是把 coding agents 作为可分配任务、可跟踪进度、可沉淀技能的真实队友来管理；EP-Harness 在这个基座上，进一步贴合公司研发流程和内部系统。

从架构上看，Multica 由 server、daemon 和 AI 编程工具三部分协作：server 管理工作区、Issue、成员和任务队列，并承担实时更新；daemon 运行在开发者本机，领取任务并调用本地 AI 编程 CLI；实际的代码执行发生在本地工具链和工作目录中。

在 EP-Harness 里，任务不是散落在聊天窗口里，而是进入 Issue。Issue 可以关联项目、需求、应用分支、工作流、评论、执行日志、文件变更和后续反馈。

• 当 Agent 的任务进入 Issue，团队就可以追踪它。

• 当 Agent 的规则进入 Instructions 和 Workflow，团队就可以审查它。

• 当 Agent 的经验进入 Skills，团队就可以复用它。

• 当 Agent 的执行进入 Runtime 和日志，团队就可以复盘它。

• 当 Agent 的结果进入部署、评审和反馈链路，团队就可以让它持续闭环。

EP-Harness 在 server/pkg/agent/agent.go 中以 Backend.Execute(ctx, prompt, ExecOptions) 作为各 Agent Runtime 的统一入口。agent.New 根据 agentType 和 Config 选择具体 Provider Backend；Claude、Codex、OpenCode、ACP 等实现可以保留各自的参数、进程和传输协议，但对上层暴露一致的执行生命周期。

AI Coding 的使用方式正在经历四层变化。它们不是互相替代，而是逐层外扩：从"怎么问"，走向"喂什么材料"，再走向"如何执行和约束"，最终走向"如何持续闭环"。

个人 AI Coding 工具通常解决前两层。EP-Harness 还解决后两层，并把四层能力放进团队研发流程。

通用 AI Coding 工具并不了解公司的研发体系。它不知道需求结构，不知道内部飞书文档权限，不知道应用分支如何创建，不知道代码管理和发布平台的实际流程，也不知道每个团队沉淀过哪些 Skills。

EP-Harness 的价值，就是把这些内部系统接进 Agent 的工作环境里。它要解决的不是"模型有没有能力写代码"，而是"模型能不能在我们的研发流程里正确工作"。

外部工具能给你一个 Agent，EP-Harness 要给团队一个 Agent 可以工作的组织环境。

很多团队刚开始用 AI 时，会把重点放在 prompt 技巧上。但用得久了会发现，更重要的是把 prompt 变成可维护的规程。

Agent 做不好，很多时候不是模型不够强，而是上下文不对。需求背景、设计文档、验收标准、关联代码仓库、目标分支、历史讨论、失败记录和内部系统调用方式，不应该靠用户每次手动复制粘贴。

• Issue：任务目标、评论、状态和历史记录。

• 需求：业务背景、需求文档和迭代信息。

• 项目：业务边界和仓库资源。

• Workflow：阶段目标和交付要求。

• Skills：团队沉淀的方法和工具说明。

• Runtime：真实执行环境。

• 飞书集成：通知、讨论和文档读取能力。

• 运行记录：执行过程、产出和失败信息。

这样 Agent 不再只拿到一段文字描述，而是进入一个由 Issue、项目、文档、分支、评论和运行记录组成的工作现场。

Context Engineering 的重点不是把上下文塞满，而是让正确上下文在正确时机进入 Agent。

一个裸模型没有工作目录，不会天然知道当前项目怎么测试，也不会自动遵守团队规范，更不会自己接入需求管理、代码管理、发布平台、飞书和日志平台。Harness 的价值，就是在模型外面补齐这些工程能力。

这让 Agent 从"一个能说话的模型"变成"一个可管理的执行单元"。对团队来说，更重要的不是 Agent 某次回答得多漂亮，而是它能否长期稳定地在工程约束里工作。

Loop Engineering 不是让 Agent 一直跑，也不是无限自动化。有价值的 Loop，需要包含发现、派发、执行、验证、记录和下一步决策。

• 上游版本更新分析

自动化定时检查外部 release。 判断是否已有分析 Issue。 发现新版本后创建分析任务。 Agent 分析影响、风险、迁移建议和验证项。 需要落地时继续拆成迁移子任务。

• 线上日志巡检

自动化按时间窗口拉取异常。 聚合错误 fingerprint、影响范围和样本。 Agent 分析可能根因。 生成修复建议和验证建议。 必要时创建后续修复 Issue。

这些场景的关键不是"Agent 自动跑了"，而是每一轮都有记录、判断、产出和后续动作。Loop 的价值在闭环，不在循环本身。

需求交付完成后，可依托 Issue 中沉淀的决策记录、实现说明，快速还原当时的实现背景和关键取舍。

案例结论：通过将交付流程拆分为提议、开发、评审、归档等阶段，并引入多 Agent 协作机制，形成从需求澄清、实现落地、质量评审到经验沉淀的闭环，持续提升代码质量。

治理成效：累计自动化修复 100+ 个异常日志问题，异常日志从高频暴露逐步收敛，问题识别、归类和修复效率明显提升。典型高频问题由治理前每 4 小时 2400+ 条，降低到治理后的个位数。

AI Coding 的第一阶段，是个人把 Agent 当工具。下一阶段，是团队把 Agent 当协作成员。当 Agent 开始接触真实需求、真实代码、真实部署和真实反馈时，单纯依赖聊天窗口和本地 prompt 已经不够。团队需要一个平台，把 Agent 的任务、上下文、规则、执行、审查、反馈和度量都组织起来。当这套机制跑起来，Agent 才能从一个个人电脑里的助手，慢慢变成团队研发流程里可管理、可复用、可持续优化的生产力。

文 / 方舟

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

知识问答的核心挑战是准确率和质量。一个回答要准确，需要：查得全（召回率），查得准（精准度），理解得对（多模态），看得对（权限隔离）。这些能力不是堆功能就能实现的，需要一个强大的 Agent 运行时来支撑。

我们选择 AgentScope 2.0，核心原因是它的 HarnessAgent 架构——这是面向生产环境的 Agent 实现，内置了长期运行 Agent 必备的工程能力。

HarnessAgent 提供了丰富的能力（ReAct 循环、Middleware、长期记忆、子 Agent 编排、沙箱隔离等），我们重点使用了三个与复合检索直接相关的能力：

• ReAct 循环：Agent 不是一次性检索然后回答，而是在「推理→行动→观察→再推理→再行动……」的循环中反复迭代，实现"搜索→评估→精读→再搜索"的复杂流程。

• 中间件（Middleware）：在 Agent 执行流程的关键位置插入自定义逻辑，不侵入核心代码。我们在 onActing 钩子中实现三阶段质量过滤，对 Agent 完全透明。

• 并行工具调用：当 Agent 决定调用多个工具时，框架自动并行执行，而非串行等待。这让"多工具 + 多变体"并行检索成为可能。

流程概览：Agent 通过 ReAct 循环实现多轮自主决策，每一轮都是"搜索 → 评估 → 决策"的闭环。

• 多源并行检索：Agent 同时调用知识库、飞书文档、飞书消息、飞书妙记等多个工具，每个工具用不同的查询变体并行调用。

• 自主评估与挖掘：Agent 评估检索结果的相关性、完整性和时效性，不够充分时触发补充检索或精读全文。

• 质量过滤：检索结果经过三阶段质量 Pipeline（FastPass → Reranker → LLM Grading）过滤。

• 信息整合：Agent 根据来源权威性优先级排序，多源信息交叉验证，生成有判断力的回答。

核心：Agent 的自主决策权——Agent 决定用哪些工具、搜几次、是否需要精读、什么时候停止。用户不需要告诉 Agent"你去查飞书文档"，Agent 自己知道什么时候该查。

当前产品的定位是两条线并行：

• 知识库线：企业知识库——产品文档、流程规范、FAQ 等，按业务领域或部门划分，由管理员统一维护。

• 个人线：飞书生态数据——用户勾选飞书消息、飞书文档、飞书妙记时，Agent 检索的是该用户个人可见的数据，由飞书自身的权限体系控制。

两条线在同一轮对话中可以同时激活——用户问"SSO 接入流程"，Agent 可能从知识库拿官方文档、从用户所在技术群拿最新讨论、从团队周会妙记拿相关决策。知识库提供权威性和结构化的知识基座，个人数据提供实时性和上下文关联的补全——这是产品最核心的价值差异。

Agent 可用的工具覆盖知识库数据源 + 三类个人飞书数据源，全部根据用户的前端勾选和权限动态激活。Agent 自主判断何时调用哪个工具，整个过程对用户透明：

权限隔离的两个层面：知识库层按业务领域或部门划分，不同用户拥有不同的可访问知识库列表；飞书生态层通过 UserCallContext 注入用户的飞书 openId，API 按当前用户的身份返回数据。同一个问题，不同用户看到的结果是不同的。

并行调用的技术实现：当 Agent 在一次推理中决定调用多个工具时，框架自动并行执行，由 AgentScope 的 Toolkit.parallel(true) + Java 21 Virtual Thread 支撑。工具调用是 I/O 密集型的（HTTP 请求到知识管理平台和飞书 API），虚拟线程在 I/O 阻塞时自动释放底层平台线程。

传统 RAG 的流程是单向的：用户提问 → 向量检索 → 拼接上下文 → 生成回答。Agent 在这个流程里是被动的——检索到什么就用什么，无法判断信息是否充分，也不会主动补充检索。 

我们的流程完全不同，核心在于两个关键决策点：判断Agent 如何评估检索结果是否充分？

Agent 拿到第一轮检索结果后，会基于结构化提示词中的策略进行多维度评估：

• 相关性判断：检索结果是否直接回答了用户问题？还是只是"词像但意思不对"？

• 完整性判断：关键信息是否齐全？比如用户问"SSO 接入流程"，是否包含了配置步骤、权限申请、测试方法等必要环节？

• 时效性判断：文档是否是最新版本？是否有更新的版本在其他数据源中？ 

如果评估结果是"信息不足"，Agent 不会盲目重试，而是根据判断结果选择下一步策略。

挖掘：Agent 如何决定深挖方向？

基于判断结果，Agent 有三种挖掘策略：

• 精读全文：如果搜索结果中有高价值文档的片段，但信息不完整，Agent 会调用 get_document_content 工具拉取完整文档。比如从知识库检索到"SSO 接入指南"的摘要，但缺少具体的配置参数，Agent 会精读全文获取完整信息。

• 补充检索：如果当前数据源的信息不够，Agent 会调整查询策略，尝试其他数据源。比如知识库没有最新讨论，Agent 会转向飞书消息或妙记搜索。

• 交叉验证：如果多个数据源返回了冲突信息，Agent 会根据来源权威性进行优先级排序——官方文档 > 飞书文档 > 消息/妙记，并在回答中明确指出冲突和建议采信的来源。

这个流程的核心是 Agent 的决策权——每一轮都是"搜索 → 评估 → 决策"，而不是预设的固定路径。Agent 决定用哪些工具、搜几次、是否需要精读、什么时候停止。

Agent 做决策的依据来自我们精心设计的结构化提示词中的策略引导——"知识库权威性更高，优先使用"、"飞书文档检索范围更广，权威性一般"——这些是优先级提示，帮助 Agent 判断不同来源的特性。但最终选哪些工具、怎么组合、哪一轮做什么，由 LLM 在提示词的策略框架内自主决定。用户不需要告诉 Agent"你去查飞书文档"，Agent 自己知道什么时候该查。

我们在 AGENTS.md 中设计了一套结构化的 Agent 提示词，它不是简单的指令列表，而是一个完整的决策流程图：

这套提示词的设计精髓在于：它不是告诉 Agent 怎么做，而是告诉 Agent 做什么和为什么。Agent 在 ReAct 循环中自主决定具体的执行细节——用哪些工具、搜几次、是否需要精读、什么时候停止。

同时，HarnessAgent 的中间件机制允许在 ReAct 循环的关键时机插入自定义逻辑。我们在 onActing 钩子中实现三阶段质量过滤（FastPass → Reranker → LLM Grading），当知识库检索工具执行完成、结果即将返回给大模型时，中间件拦截结果进行过滤。这个过程对 Agent 完全透明——Agent 看到的始终是过滤后的高质量结果。

这种设计的优势在于：关注点分离。结构化提示词负责"做什么"（策略框架），Middleware 负责"做得好"（质量保障），ReAct 循环负责"怎么做"（执行流程）。三者各司其职，互不侵入。

我们没有修改 AgentScope 的 ReAct 循环代码，而是通过结构化提示词和中间件，在循环的关键节点注入了我们的业务逻辑。

当 Agent 自主选择多个数据源并行检索后，它拿到的不是零散的片段，而是一张信息拼图。这张拼图的价值体现在三个递进的层面：

第一层：多角度并行搜索，最大化召回。Agent 发现知识库结果中有一份标记为"废弃"的旧版文档，同时飞书文档搜索找到了同文档的最新版本——它自动优先采用新版，标注旧版已废弃。

第二层：从搜索到精读，深挖关键文档。Agent 不是"搜到什么就用什么"。它从搜索结果中识别出最关键的文档，进一步调用精读工具拉取全文——因为向量检索只返回最相似的那几个片段，完整的上下文藏在同一篇文档的其他段落里。

第三层：多源交叉验证，有判断力的信息整合。Agent 拿到多源信息后，会根据来源权威性进行优先级排序——官方文档最高优先级，会议纪要作为背景补充。这不是"多搜几个地方然后拼起来"，而是有判断力的信息整合。

实现要点：结构化提示词中明确规定了来源优先级（企业知识库 > 飞书文档 > 消息/妙记），并要求冲突时明确指出并建议用户以哪个为准。SourceCollector 组件按 sourceId 跨工具去重，每条关键信息在最终回答中标注 [src:sourceId]，可追溯到来源。

RAG 系统的质量由两个指标决定：召回率——有没有把相关文档找出来；精准度——找出来的文档是不是真的相关。召回靠查询扩展，精准靠三阶段质量 Pipeline。

向量检索本身我们没有重复造轮子——知识库的文档解析、Chunk 切分、向量化、混合检索，全部由公司已有的知识管理平台提供。我们做的是"在知识管理平台之上构建智能检索层"。

在发起检索之前，第一件事是查询扩展——将用户的原始问题转化为更适合检索的查询语句。这不是简单的关键词提取，而是生成语义等价的完整自然语言句子。

为什么是自然语言而非关键词？Embedding 模型是在海量自然语言文本上训练的——完整的句子、段落、文档。模型对"一句话"的语义编码远比"一串词"精准。例如用户问"怎么申请加薪"，关键词方式「加薪 申请 流程 条件」缺乏语法结构，而自然语言变体「得物内部员工申请薪资调整的流程是什么」有完整的主谓宾结构，能生成更精准的语义向量。 

更关键的是，Agent 会生成多个不同角度的变体，并行发起检索。这些变体彼此互补——有的侧重流程描述，有的侧重政策条款，有的侧重申请入口——共同覆盖用户意图的各个侧面。

查询扩展提升了召回率，但并不保证召回来的都是真正有用的。向量检索用余弦相似度比较 query 和 document 的 Embedding 向量，这个机制适合"找看起来像的"，但容易被高频词汇干扰。 

例如用户问「得物 App 的退货流程是什么」，向量检索返回 5 条结果中只有 2 条真正相关，噪声比例 60%。直接把这些喂给大模型，回答质量必然受影响。

我们不是在向量检索结果上只做一次过滤，而是构建了一个三阶段 Pipeline，每个阶段解决不同层面的问题：

三阶段 Pipeline 通过 AgentScope 的 Middleware 机制接入，在 onActing 钩子中拦截 knowledge_search 工具结果。核心逻辑：

• 识别 knowledge_search 工具调用。

• 调用原始工具获取结果。

• 按 toolCallId 分组独立处理：FastPass → Reranker → LLM Grading。

• 重建事件流，用过滤后的结果替换原始工具输出。

关注点分离：Agent 的推理逻辑和检索质量策略完全解耦。调整阈值、切换 Reranker 模型、开关 LLM Grading，都只需修改配置或 Middleware，不影响 Agent 核心代码。

Middleware 入口 — onActing 拦截 knowledge_search 结果：

// 实现 MiddlewareBase 接口，在工具执行前后注入过滤逻辑
Flux<AgentEvent> onActing(Agent agent, ActingInput input, next){
    if (!config.isEnabled()) return next.apply(input);            // 未启用，直接透传


    // 1. 识别本轮是否包含 knowledge_search 工具调用
    targetToolCalls = input.toolCalls()
        .filter(tc -> tc.name == "knowledge_search");
    if (targetToolCalls.isEmpty()) return next.apply(input);      // 无目标工具，透传


    // 2. 先让工具执行，收集所有事件后再统一处理
    events = next.apply(input).collectList();
    return processEvents(events, targetToolCalls);                // 进入三阶段过滤
}

List<RetrievedItem> filter(String query, List<RetrievedItem> items){
    // ── Stage 0: FastPass ──
    // 条件：结果数 ≤ 2 且全部原始 score ≥ 0.7
    if (items.size() <= 2 && items.allMatch(i -> i.originalScore >= 0.7)) {
        return items;  // 高置信度，跳过过滤，零额外延迟
    }


    // ── Stage 1: Reranker 粗筛 ──
    // 调用交叉编码器模型重新打分，过滤"词像但意思不对"的结果
    if (config.rerankerEnabled) {
        scores = rerankerService.rerank(query, items.snippets);   // 调用 gte-rerank-v2 模型
        items = items
            .filter(i -> scores[i.index] >= 0.3)                  // 阈值 0.3，过滤低相关
            .sortByDescending(i -> i.rerankerScore)
            .limit(8);                                            // 取 Top-8
    }


    // ── Stage 2: LLM Grading 精评 ──
    // 用大模型逐条打分（0.1~1.0 四级），过滤"主题对但不够直接"的结果
    if (config.llmGradeEnabled && !items.isEmpty()) {
        graded = llmScoringService.gradeInBatch(query, items);    // 最多 10 条，30s 超时
        items = graded
            .filter(g -> g.score >= 0.5)                          // 阈值 0.5，过滤不够直接的结果
            .sortByDescending(i -> i.relevanceScore);
    }


    return items;  // 过滤后的结果重建为文本，替换原始工具输出，对 Agent 透明
}

设计要点：

在实际使用中，用户遇到问题时往往第一反应是截图——报错信息、界面异常、配置页面，一张图比千言万语更直观。支持图片输入，让"截图即提问"成为可能，大幅降低了用户的表达成本。

用户上传图片后，系统检测到上下文包含图片，自动判断模型策略：

• 未指定模型 → 自动切换到视觉语言模型。

• 指定了视觉模型 → 正常执行。

• 指定了纯文本模型 → 拒绝并提示，防止调用失败。

这个校验不仅检查本轮上传的图片，还检查历史对话中是否有图片。因为大模型无状态，历史图片也需要每轮重新发送——即使本轮没传新图，只要历史中有，同样强制使用视觉模型。

从上传到在回答中展示，图片经历了完整的生命周期：

• 上传阶段：拖拽/粘贴/点击，最多 6 张，校验类型和大小。

• 发送阶段：从对象存储内网读取图片字节，Base64 编码，与文本一起构造多模态消息。

• 历史回放：多轮对话中，历史图片按消息聚合回放，按用户归属过滤，总大小受预算控制。

• 回答嵌入：Agent 可以在回答中插入检索到的图片辅助说明，图片和文字引用统一编号。

SSE 断点续传的需求，不止来自"服务器宕机"这种极端情况。实际上，高频触发断点续传的是用户的正常操作：

• 页面切到后台太久，浏览器断开了 SSE 连接。

• 刷新页面（F5），前端重新挂载，需要重建 SSE 流。

• 关闭标签页后重新打开，用户期望回到刚才的对话。

• 移动端切换网络（Wi-Fi → 5G），IP 变了，连接中断。

我们的方案是多实例 SSE 断点续传：无论因为什么断开——服务器宕机、页面刷新、网络切换——浏览器自动重连，从断开的地方继续接收，完全看不到中断痕迹。

系统同时支持三种恢复路径，按优先级自动选择：

路径一：同实例恢复（最常见——页面刷新、切后台、网络闪断）用户断开后重连，请求打到同一个实例。本地内存中仍有 Agent 的运行状态，直接发送一个完整快照恢复历史，然后续传后续内容。零延迟、零 Redis 开销。

路径二：跨实例转发（负载均衡调度、网络切换导致 IP 变化）用户重连时被负载均衡分到了另一个实例。新实例通过 Redis 路由表查到原实例的地址，内部转发请求。原实例像对待本地客户端一样直接推送 SSE 流，新实例透传。

路径三：快照重建兜底（原实例宕机或不可达）如果原实例确实不可达，系统从 Redis 中重建完整会话，已产生的所有内容可以完整恢复，用户不会丢失任何信息。

以下为三种恢复路径的对比图：

为什么用快照一帧恢复而不是逐条重放？

早期的方案是"把所有历史事件按顺序重新发送一遍"。在一个典型的多轮 Agent 对话中可能意味着几百个事件——如果逐条重放，前端 React 组件接收到密集的批量更新，浏览器渲染引擎会把这些更新合并成"一段一段"的跳变。快照方案把所有这些事件折叠成一个完整的"当前状态"——就像游戏存档，一帧恢复。 

为什么用路由表 + 内部转发，而不是 Redis Pub/Sub？

一个更"直觉"的多实例方案是：每个实例的事件写入 Redis Pub/Sub，其他实例订阅。但 Pub/Sub 有一个致命问题——订阅生效有延迟。新订阅者连上 Pub/Sub 时，可能已经错过了前面几条消息。我们的方案核心思路是：Redis 只存路由信息，不参与事件推送。

 心跳保活：工具调用期间可能长时间无新事件，系统通过定期发送 SSE 注释行（心跳，每 10 秒）保持连接活跃，对业务逻辑完全透明。

 分布式锁：用户快速双击发送按钮，可能导致同一会话产生两个并发请求。系统通过 Redis 的原子 SETNX 操作实现分布式锁，锁带 TTL 自动过期，防止死锁。

大模型服务偶尔波动。当主模型出现可重试错误时（5xx 服务端错误、限流、超时、网络异常），自动切换到备用版本继续服务，用户无感知。4xx 客户端错误不触发切换，直接返回错误让用户修正。

回到最初的问题。我们的答案不在某一个算法或某一项技术上，而在系统设计的整体思路。以下是与"标准 RAG 套壳"的六个关键差异：

复合检索不是"多搜几个地方"——大多数多源 RAG 的做法是"各搜各的然后拼起来"。我们的做法是 Agent 根据问题自主选择最合适的来源组合，搜索和精读交替推进，交叉验证、分层整合。

质量 Pipeline 不只是 Reranker——很多系统在向量检索后只加一个 Reranker。我们做了三级：FastPass 快速通道、Reranker 粗筛、LLM Grading 精评，每一级解决不同层面的问题。

SSE 断点续传不靠 Pub/Sub——我们用了路由表 + 内部转发的方案，Redis 只存路由信息不参与推送，跨实例重连时直接 HTTP 转发到原实例。

当前产品已经实现了复合检索 Agent 的核心能力：四源融合检索、三阶段质量过滤、多模态支持、以及生产级的 SSE 断点续传。基于这些能力，未来的演进可以分为两个层次。

短期优化：精细化检索与总结策略 

当前系统对飞书文档、会议、消息等数据源采用统一的总结逻辑，但实际上不同数据源的信息特征差异很大。例如：

• 飞书文档：通常是结构化的流程说明或技术规范，需要提取关键步骤和配置参数

• 飞书消息：包含大量日常讨论噪声，需要识别关键决策点和时间线

• 飞书妙记：会议记录包含结论、待办、责任人等多维度信息，需要根据会议类型（技术评审、项目周会、需求讨论）采用不同的总结侧重点

未来可以针对这些数据源特性，设计差异化的总结策略，进一步提升回答的精准度和实用性。同时，评测体系也会持续完善，覆盖更多业务场景和边界情况。

长期愿景：个人知识助手

当前产品打通了"公共知识 + 个人数据"的双通道，但每次对话仍然是独立的。未来的方向是让 Agent 具备长期记忆能力——记住用户的身份、职责、偏好，主动关联相关信息和过往对话，实现"公共知识 + 个人数据 + 长期记忆"三重叠加的检索优势。

AgentScope 框架已内置长期记忆、对话压缩、技能系统、子代理编排等能力，当前处于"已禁用但可激活"状态，后续功能可直接迭代优化，不需要推倒重来。

基于不同业务维度的三组评测集（覆盖知识库、飞书文档、飞书消息、飞书妙记四类数据源），全量人工标注，评测结果如下：

另外在技术选型阶段，我们将 AgentScope 2.0 与 Java 生态的主流 AI 框架进行了详细对比：

文 /莲舟

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

从 24 年冬天开始，各类 coding agent 层出不穷——从 Gemini CLI 的起步，到 Claude Code 的尝试，再到如今 Codex、OpenCode、PI、Qoder 等百花齐放。

短短一年多的时间，agent 从大模型的一个附属品，逐渐演变成模型能力的放大器，成为 AI 工程化的关键载体。市面上各类业务 agent——客服、数据分析、工作流编排等——追根溯源，基本都是 coding agent 的泛化变种。

理解了 coding agent 的构建原理，也就掌握了理解其他 agent 的一把钥匙。笔者对每天都在使用的 agent 原理很感兴趣，于是决定自己写一个：violin。

虽然有点丑，但是基本的功能（多模态、skill、插件）已经完备了。

Violin 的架构设计深度借鉴了 Pi 的设计理念。Pi 作为一个 TypeScript 实现的 AI coding agent，其最突出的特点是简洁而可扩展的架构——三层分离（模型适配层 / 内核层 / 产品层）、EventBus 事件驱动、工具注册表和插件系统，每个模块各司其职且松耦合。

更难得的是，Pi 的代码完全开源，这不仅让 Violin 有了一个扎实的参考蓝本，也让它本身成为一个极佳的 Agent 工程学习范本：代码结构清晰、注释详尽、每层职责明确。想要学习 Pi 架构的，强烈推荐这个项目：how-pi-agent-works。

可以说，读懂了 Pi 的架构，就理解了现代 AI coding agent 的核心设计模式。Violin 在保持这一架构精髓的同时，用 Zig 替换了 TypeScript，在内存安全和性能上做了进一步的探索。

Violin agent 的架构如下：

Why Zig?

Violin 的架构设计深度借鉴了 Pi 的三层分离和 EventBus 方案，但在实现语言上做了完全不同的选择。既然每一层通过接口（或网络协议）解耦，那么不同层用不同语言实现是完全可行的——不需要也不可能「全部用一种语言写完」。

Violin 的分工是：Agent Loop、模型适配、会话管理等底层引擎用 Zig 实现，追求极致的性能和内存可控性；而 Client 端用 Python 实现，利用 Python 的生态快速搭建终端交互 UI。

两者通过 TCP + JSON line 协议通信，Server 不关心 Client 用什么语言写的。笔者的技术栈恰好是 Zig + Python，不会 JS、不熟悉 Rust，但这个组合正好覆盖了「引擎」和「界面」两端，分工清楚，各取所长。

不同模型 API 对工具调用、推理内容、缓存、错误、OAuth、流式协议的表达都不同。Violin 把这些差异统一成 Message、Tool、AssistantMessageEvent 和 streamSimple()。

这样上层 Agent Loop 不需要知道「这是 Anthropic 的 tool_use，还是 OpenAI Responses 的 function call」。它只关心统一后的 toolCall 内容块。

写一个 Agent Loop 不难，难的是把它变成每天能用的开发工具。产品层负责这些「麻烦但关键」的事情：

为了让客户端实现与语言无关，我们需要将 agent 能力包装为一套通信协议 + 一个 TCPServer。TCPServer 流式通信 + 全双工，天生适合这个场景。

Agent Loop 是什么？一个 while 循环，在「问模型」和「执行工具」之间来回切换，直到模型给出最终答案。它不关心模型是 OpenAI 还是 Anthropic，不关心工具是读文件还是跑命令，只关心两件事：模型要不要调工具？如果要，调完继续问；如果不要，结束。

这是 Agent Loop 的核心代码（简化后）：

while (turn < max_turns) : (turn += 1) {
   // 1. 调模型
   const assistant = try model.complete(.{
       .messages = messages.items,
       .tools = tool_registry.definitions(),
   });


   // 2. 检查是否有工具调用
   const has_tool_calls = assistant.toolCalls().len > 0;


   // 3. 没有 → 结束；有 → 逐个执行工具
   if (!has_tool_calls) break;


   for (assistant.content) |block| {
       if (block == .tool_call) {
           const result = tool_registry.execute(tc.name, tc.args);
           messages.append(result);  // 回写给模型
       }
   }
}

这里需要注意：

• 为什么要有 max_turns — 模型可能陷入无限工具循环，上限是安全阀。

• 为什么工具结果要 append 回 messages — 模型需要看到结果才能决定下一步。

• 为什么 tools 定义要传进 complete() — 模型要提前知道有哪些工具可用。

当然不管是 LLM 调用还是工具调用，都有失败的可能，所以我们需要在 AgentLoop 这一层加入重试机制。首先我们需要区分错误种类，是不是一个可以重试的错误，Violin 中做了简单分类：

Agent Loop 只关心「循环」，不关心消息从哪里来、执行结果存到哪里。这些「循环之外」的事——会话历史的加载和保存、上下文压缩后的重试、Arena 内存管理——由上一层产品层（product/agent.zig）封装。

agent.zig 调用 loop.run() 时传入历史消息，loop 返回后它负责把新消息持久化到 Session，并在 ContextOverflow 时截断上下文重试。

模型适配层的职责只有一句话：把不同 LLM Provider 的 API 差异封装在一个 Model.complete() 接口后面。Agent Loop 只认这个接口，不关心背后是 OpenAI 还是 Anthropic。

简化后的核心逻辑（伪代码）：

interface ModelAdapter {
    complete(input: CompleteInput) -> AssistantMessage
    name() -> string
}


// 每个 Provider 实现这个接口：
// OpenAIAdapter      — 调用 /chat/completions
// AnthropicAdapter   — 调用 /v1/messages


struct CompleteInput {
    system_prompt: string,
    messages: Message[],
    tools: ToolDefinition[],
    max_tokens: int,
    temperature: float,
    stream_callback: optional callback,  // 流式输出
}

实际 Zig 实现使用函数指针表（Zig 没有 trait 和虚函数，用函数指针实现多态），每个适配器提供三个函数指针（complete、name、deinit），通过统一接口调用。适配器内部状态（如 base_url/api_key）通过类型擦除的指针在回调中还原。

Violin 适配了目前最流行的 2 种 LLM 协议：

两个适配器代码量差不多（531 vs 558 行），因为它们各自要处理 JSON 序列化、HTTP 请求、SSE 流式解析、错误映射。差异主要在：请求体格式不同（OpenAI 用 messages[]，Anthropic 用 content[]）。工具调用的结构不同（OpenAI 是 tool_calls[]，Anthropic 是 content[] 中的 tool_use block）。流式协议不同（OpenAI 用 data: 行，Anthropic 用 event: 行）。

LLM 生成一个回答可能需要几秒甚至十几秒。如果等全部生成完再返回，用户只能干等。为了客户端体验的流畅，目前主流 Agent 都采用了流式输出，这个问题的解决方案是流式（SSE）。

// 模型适配器在收到 SSE 的每个 chunk 时，调用 stream_callback
// Agent Loop 收到回调后，立即通过 EventBus 发射 message_update 事件
// Client 收到事件后，实时追加到终端显示


pub const StreamCallback = *constfn (ctx, chunk: StreamChunk) bool;

Violin 没有内置任何模型，全部从 ~/.violin/agent/models.json 中加载模型配置，再由客户端决定使用哪个模型：

{
"providers": {
   "openai": {
     "base_url": "https://api.openai.com/v1",
     "api": "openai-completions",
     "api_key": "$OPENAI_API_KEY",
     "models": [
       { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000 }
     ]
   }
 }
}

模型适配层让 Agent Loop 可以调任何模型，工具系统让 Agent Loop 可以做任何事。

工具的定义：

pub const Tool = struct {
  name: []const u8,
  description: []const u8,
  parameters: []const u8,  // JSON Schema
  execute: ToolExecuteFn,
};

Violin 内置了 6 个基本工具，和 Pi 的设计保持一致：

为了方便管理这些 tools，Violin 中实现了一个工具注册表（伪代码）：实际 Zig 实现使用 HashMap 存储工具，按名称快速查找。definitions() 将工具列表编码为模型可识别的 JSON Schema 格式。

// 简化后的工具注册表逻辑：
classToolRegistry:
    tools: Map<string, Tool>


    funcregister(name, description, execute_fn):
        tools[name] = Tool(name, description, execute_fn)


    func get(name) -> Tool:
        return tools[name]


    func definitions() -> ToolDefinition[]:
        // 返回所有工具定义，发送给模型
        return [t.definition() for t in tools.values()]


    func execute(name, args) -> ToolResult:
        tool = tools[name]
        return tool.execute(args)

product/agent.zig 只有 123 行，却是把整个项目「粘起来」的那层。它做的事情很简单：

• 从 Session 加载历史消息。

• 传给 loop.run () 执行。

• loop 返回后，把所有新消息保存到 Session。

• 如果 loop 抛了 ContextOverflow，调用 compaction 压缩后重试。

展示核心逻辑（简化）：

// 简化后的 agent.run() 逻辑：
func run(config, user_input) -> AgentResult:
    history = load_history(config.session)


    while True:
        loop_result = loop.run(
            model=config.model,
            initial_messages=history,
            input=user_input
        )


        if loop_result == ContextOverflow:
            compact_session()     // 压缩历史，保留关键信息
            continue              // 压缩后重试


        // 保存新消息到会话
        for msg in loop_result.new_messages:
            session.appendMessage(msg)


        return AgentResult(text=loop_result.final_text)

没有 Session，Agent 每次对话都是「失忆」的。存储格式：JSONL，每行一个独立 JSON 对象。第一行是会话头（id, created_at, cwd），后续每行是一条消息。

{"id":"sess_001","created_at":1717234567,"cwd":"/project","model":"gpt-4o"}
{"id":1,"parent_id":null,"timestamp":1,"role":"user","content":"帮我读 README.md"}
{"id":2,"parent_id":1,"timestamp":2,"role":"assistant","content":"我来帮你读..."}

violin 为了管理 Session，添加一个 SessionStore 的数据结构

// 简化后的 SessionStore 数据结构：
classSessionStore:
    file_path: string          // JSONL 文件路径
    entries: Map<id, Entry>    // 消息索引，支持随机访问
    leaf_id: int | null        // 当前叶子节点（最新消息）
    next_id: int               // 自增 ID，用于生成新消息 ID
    header: SessionHeader      // 会话头信息

实际 Zig 实现使用 ArenaAllocator 统一管理内存（所有分配来自 arena，deinit 时一次性释放），省去逐条 free 的麻烦。

核心方法如下：

• 消息持久化 writeEntry 的核心逻辑（伪代码）：

// 简化后的消息持久化逻辑：
func writeEntry(entry):
    json_line = serialize_to_json(entry) + "\n"
    // 写入临时文件，然后追加到会话文件
    // 用临时文件方式，避免处理特殊字符的麻烦
    write_temp_file(json_line)
    append_to_session_file(temp_file)

// 简化后的追加消息逻辑：
func appendMessage(message) -> entry_id:
    id = next_id++
    entry = Entry(
        id: id,
        parent_id: current_leaf_id,  // 挂在当前消息后面
        timestamp: now(),
        message: message
    )
    entries[id] = entry
    leaf_id = id                     // 新消息成为最新消息
    writeEntry(entry)                // 持久化到 JSONL 文件
    return id

• session 从文件恢复（伪代码）：

// 简化后的会话恢复逻辑：
func load():
    if not file_exists(file_path):
        createSession()       // 文件不存在，新建会话
        return


    for each line in read_lines(file_path):
        if is_first_line:
            header = parse_header(line)  // 首行 = 会话头
            is_first_line = false
        else:
            entry = parse_entry(line)    // 后续行 = 消息
            if entry is valid:
                entries[entry.id] = entry
            else:
                log_warn("跳过损坏的消息")  // 损坏行跳过，不崩

与 Pi 的对比：Pi 的 Session 也是 JSONL + 树结构，支持了树形对话结构，支持分支 fork 和回滚，Violin 继承了这些能力。

当 token 超过阈值时，把旧消息压缩成一条摘要，保留最近 N 条消息。Agent 层的重试循环会检查压缩结果并重新执行 loop。

LLM 有上下文窗口限制，一个 Coding Agent 的对话可能持续几十轮，累积数千 token。如果不做处理，早期消息会被窗口截断，模型「忘记」了之前的上下文。当 token 超过阈值时，把旧消息压缩成一条摘要，保留最近的消息不变。

压缩前:
[消息1] [消息2] [消息3] ... [消息N-10] [消息N-9] ... [消息N]


压缩后:
[摘要: 之前讨论的要点] [消息N-9] [消息N-8] ... [消息N]

核心设计：

• Token 预算

// 不引入 tokenizer，用 字符数/4 近似。够用就行——压缩决策不需要精确到个位数。
pub fn estimateTokens(text: []const u8) usize {
   return text.len / 4;
}

funcneedsCompaction(messages, config) -> bool:
    return estimateMessagesTokens(messages) > config.max_tokens

默认阈值 100K token，保留最近 10 条消息，摘要目标长度 500 token。

把旧消息拼接成文本，调用模型生成摘要：
[user]: 帮我写一个 HTTP 服务器
[assistant]: 可以用 Zig 的 std.http...
[tool_call]: write_file("server.zig", ...)
[tool_result]: 文件已写入


--->
用户要求编写 HTTP 服务器，助手使用 Zig 标准库创建了 server.zig，实现了基本的请求处理。

violin 的压缩系统分成了 2 层：

Resources 从文件系统加载项目规则（AGENTS.md）和技能（SKILL.md），解析 frontmatter，格式化为 system prompt 注入给 LLM，让模型知道它有哪些工具和能力可用。ResourceLoader 负责从文件系统加载三类资源，格式化为 system prompt 供 LLM 使用：

• 项目规则 — AGENTS.md/ CLAUDE.md。

• 技能 — .agent/skills/ 下的 SKILL.md 文件。

数据结构（伪代码）如下：

// 简化后的数据结构：
struct Skill {
    name: string           // 技能名称
    description: string    // 技能描述
    filePath: string       // SKILL.md 文件路径
    source: enum           // "global" 或 "project"
    content: string        // SKILL.md 原文
}


struct Resources {
    rules: ProjectRules
    skills: Skill[]
    cwd: string
}

资源的搜索路径如下：

项目规则（优先级从高到低）:
 {cwd}/AGENTS.md
 {cwd}/CLAUDE.md
 ~/.violin/agent/AGENTS.md
 ~/.violin/agent/CLAUDE.md


技能（项目先，全局后，同名冲突时项目赢）:
 {cwd}/.agent/skills/*/SKILL.md
 {cwd}/.agents/skills/*/SKILL.md
 ~/.violin/agent/skills/*/SKILL.md


loadAll()
 ├─ loadProjectRules()
 │   ├─ 尝试 {cwd}/AGENTS.md
 │   ├─ 尝试 {cwd}/CLAUDE.md
 │   ├─ 尝试 ~/.violin/agent/AGENTS.md
 │   └─ 尝试 ~/.violin/agent/CLAUDE.md
 │
 └─ loadSkills()
     ├─ 扫描 {cwd}/.agent/skills/*/SKILL.md
     ├─ 扫描 {cwd}/.agents/skills/*/SKILL.md
     └─ 扫描 ~/.violin/agent/skills/*/SKILL.md
         └─ 同名冲突时报告 diagnostic，跳过

SKILL.md 文件都会携带一个 YAML frontmatter，violin 会解析这部分内容，并构建成一个 XML 数据，最终会注入到系统提示词中：

<available_skills>
    <skill>
      <name>basedpyright</name>
      <description>Python static type checking</description>
      <location>/path/to/skill/SKILL.md</location>
    </skill>
</available_skills>

Agent Loop 在跑，但外界怎么知道它跑到了哪一步？—— 事件系统就是答案。Agent Loop 每做一件事（开始一轮、生成一个 token、调一个工具），就往 EventBus 上发一个事件。谁关心这个事件，谁就注册回调。

插件的优势在于即插即用、动态加载，刚开始考虑有如下的方案：

最终我选了 Lua。不是因为 Lua 是最好的语言，而是因为它是最小的对的那一个。500KB 的运行时，20 年 proven 的嵌入场景（从 WoW 到 Redis 到 Nginx），一 C 函数就能调 — 对 Zig 项目来说，这是路径最短的选择。

插件系统的架构如下：

核心机制非常简单：EventBus 有三个回调槽（agent /session/compaction），install () 把原回调保存下来，换成自己的 dispatch 包装函数。先执行原回调（写 socket 流式返回给客户端），再遍历所有已注册的 Lua 插件，逐个调用对应的 hook 函数。

插件长什么样子？

-- ~/.violin/plugins/bash-guard.lua
return {
    name = "bash-guard",
    version = "0.2.0",
    description = "拦截危险 bash 命令，自动加安全前缀",


    -- tool_start：执行工具前拦截
    on_tool_start = function(event)if event.tool_name == "bash" then-- 阻止危险命令if event.arguments:find("rm -rf", 1, true) thenreturn { action = "block", reason = "危险命令已阻止" }
            end-- 修改命令（加安全前缀）return { action = "modify", arguments = "set -e; " .. event.arguments }
        end-- 不 return = allowend,


    -- tool_end：修改工具执行结果
    on_tool_end = function(event)if event.tool_name == "bash" and event.is_error thenreturn { action = "modify", content = "错误已自动处理", is_error = false }
        endend,


    -- context：在 LLM 调用前注入系统指令
    on_context = function(event)return { action = "modify", inject_text = "使用 bash 时注意安全", inject_role = "system" }
    end,


    -- agent_start：阻止 agent 启动
    on_agent_start = function(event)-- 在某些条件下阻止 agent 启动-- return { action = "block", reason = "当前不允许执行" }end,


    -- session_before_compact：阻止手动压缩
    on_session_before_compact = function(event)if event.reason == "manual" thenreturn { action = "block", reason = "禁止手动压缩" }
        endend,
}

网络层定义了 Violin 客户端与服务端之间如何通信 —— 客户端发一条消息，服务端把思考过程、工具调用、最终回答一条条推送给客户端，就像看一个人边想边做边说的直播。

为什么是 C/S 架构？大多数 Coding Agent 是一体式的 ——Agent 引擎直接嵌入编辑器或 CLI 工具里，启动、加载模型、执行工具、管理会话都在一个进程里完成。

Violin 选择了前后端分离：

一体式:  [agent + UI + 会话]  — 一个进程，跑在本地


Violin:  [Zig 服务端 (daemon)]  ←TCP/JSON-lines→  [Python TUI 客户端]
                               也可以接其他客户端

这个设计选择也是受到了 ACP 协议的启发，ACP 协议复杂度较高，而且 zig 没有很好的 ACP 实现依赖，violin 作为一个 toy 项目，选择了最小最容易的方式 ——TCP + JSON LINES。

我在项目中维护了一个详细的通信协议说明，如果用户想用其他语言实现客户端，只需要把通信协议交给 AI 即可 vibe 出一个新的客户端。

受到篇幅限制，我只简单介绍几个核心协议：

客户端 → 服务端:
{"type":"handshake","cwd":"/home/user/project/violin"}


服务端 → 客户端:
{"type":"models_result","models":[...],"default":"deepseek-v4-flash"}
{"type":"skills_result","global_skills":[...],"project_skills":[...]}

cwd 用于加载项目技能 {cwd}/.agent/skills/ 和注入系统提示词。

客户端 → 服务端:
{"type":"chat","content":"列出目录下文件","model":"deepseek-v4-flash"}

可选字段：session_id、temperature、max_tokens、system_prompt、images。

服务端处理 chat 请求时，流式推送事件。Violin 设计了 8 个事件类型来完善对话需求：

完整事件流示例：

// Client 发送
→ {"type":"chat","content":"帮我读 README.md"}// Server 开始流式返回
← {"type":"turn_start","session_id":"sess_001","model":{"id":"gpt-4o","provider":"openai","label":"GPT-4o"},"context":{"tokens":5400,"window":128000,"usage_pct":4.2}}


← {"type":"delta","text":"我来"}
← {"type":"delta","text":"帮你"}
← {"type":"delta","text":"读"}


← {"type":"tool_start","name":"read_file","args":{"path":"README.md"}}// ... 等待工具执行 ...
← {"type":"tool_end","name":"read_file","ok":true,"output":"# Violin\n..."}


← {"type":"delta","text":"文件"}
← {"type":"delta","text":"内容是："}
← {"type":"delta","text":"Violin是一个AI助手"}


← {"type":"turn_end","turn":0,"usage":{"input_tokens":5400,"output_tokens":18,"cost_usd":0.0115}}


← {"type":"result","text":"我来帮你读...","turns":1,"aborted":false,"session_id":"sess_001","usage_total":{"input_tokens":5400,"output_tokens":18,"cost_usd":0.0115}}

有了上一节网络协议的铺垫，我们可以写一个简单的 Violin Python 客户端。Python Client 的核心是一个 async TCP 连接 + 事件分发器：

classViolinClient:
"""Async Violin protocol client (no UI, just I/O)."""


def__init__(self, host="127.0.0.1", port=9877):
        self.reader = None
        self.writer = None
        self.models = []
        self.session_id = ""


# 回调——UI 层注册这些，实现与展示分离
        self.on_delta = None
        self.on_tool_start = None
        self.on_tool_end = None
        self.on_result = None
        ...


asyncdefconnect(self, retries=3):
"""TCP 连接 → handshake → 收 models_result + skills_result"""
for i inrange(retries):
try:
                r, w = await asyncio.open_connection(*self.addr)
                self.reader = r
                self.writer = w
await self._send({"type": "handshake", "cwd": os.getcwd()})
                msg = await self._read_msg()
if msg and msg.get("type") == "models_result":
                    self.models = msg.get("models", [])
returnTrue
except ConnectionRefusedError:
await asyncio.sleep(0.5 * (2 ** i))
returnFalse


asyncdefhandle_messages(self, state):
"""事件分发——读 socket → 按 type 调用对应回调"""
whileTrue:
            msg = await self._read_msg()
            mt = msg.get("type", "")
if mt == "delta":
                state["full_text"] += msg.get("text", "")
if self.on_delta:
                    self.on_delta(msg["text"])
elif mt == "tool_start":
if self.on_tool_start:
                    self.on_tool_start(msg["name"], msg["args"])
elif mt == "result":
                self.session_id = msg.get("session_id", self.session_id)
if self.on_result:
                    self.on_result(msg["text"], msg.get("usage_total", {}))
return msg["text"]
elif mt == "error":
if self.on_error:
                    self.on_error(msg["msg"])
return""
elif mt == "ping":
await self._send({"type": "pong"})
return state["full_text"]

整个项目做下来，最大的感受是：coding agent 的核心没有什么魔法。剥开各种花哨的 UI 和功能，底层就是一个 while 循环 —— 问模型、拿结果、要不要调工具、调完再问。Violin 的每一层都是在给这个循环打补丁：

• 模型适配层解决 "问谁"。

• 工具系统解决 "能干嘛"。

• 资源层解决 "记不记得住、SKILL 在哪"。

• 插件解决 "能力扩充"。

这个玩具距离一个成熟的 Coding Agent 还有一堆没填的坑：buildJson 里 tools 参数还没序列化，模型根本收不到工具定义。插件没有权限隔离，Lua 能干任何事。ACP 协议也没接，暂时只能自己跟自己玩。

但作为一个从零搭起来的 toy agent，这个项目的目的从来不是交付一个商用产品，而是验证一个判断：理解了 coding agent 的构建原理，也就掌握了理解其他 agent 的一把钥匙。

这个判断在构建过程中不断被验证 —— 模型的统一适配、工具的注册与调度、会话的持久化与恢复、上下文的压缩与保留、插件的注入与拦截，这些看似各不相干的问题，底层都收敛到同一个循环：问模型、调工具、再问。客服 agent 的会话管理、数据分析 agent 的工具链编排、工作流 agent 的状态机设计 —— 追根溯源，都是这个循环在不同场景下的变形。

剩下那些没填的坑，既是项目当前的边界，也是下一段探索的起点。把一个 toy 项目一路补到能真正落地，过程本身就是最好的学习方式。

文 / 酒米

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

订单系统是交易链路的核心命脉，直接承载用户所有下单与支付行为，其稳定性直接决定业务盈亏。为此，我们耗时一年多，完成了订单系统由外而内的三阶段改造。

• 第一阶段筑牢稳定底线：以 SLA 99.99%、杜绝跌单为目标，梳理下游依赖、搭建三级保障规范，规避下游抖动拖累主链路。

• 第二阶段剥离核心链路：以支付节点为分界，将订单创建、支付回调等核心能力从老旧应用中独立拆分并专属保障。

• 第三阶段模块化重构链路：按业务语义重构执行序列，实现各环节模块化分层并配齐全链路埋点。

三阶段改造落地后，订单系统实现了稳定性兜底、核心链路隔离、架构模块化、链路可观测的全面升级。但 AI Coding 的普及，给核心系统研发带来了全新的挑战。

前三阶段的改造为系统打下了稳定性、可扩展性和模块化的基础，但当前仍面临以下挑战：AI 让代码产出又快又多（人均增加近 3 倍），但质量并不会因生成速度提升而自动提升。约束不够强、知识不够全，AI 就会"又快又稳地把错的东西复制一千份"。具体挑战归纳为：

• 错误模式迁移：从"个人手误"转向"系统性偏差"，AI 倾向复用历史模式，错误容易批量复制。

• 知识结构化压力：约束规约散落各处时，AI 等同于"看不见"团队积累。

• 代码量与审查力失衡：变更量是之前的数倍，但 CR 资源不同步增加，缺陷逃逸风险被放大。

• 故障回溯难：人 + AI 协同完成的代码，事后难定位根因（知识库/skill/规约/prompt 哪里出错）。

• 单点提效，链路熵增：编码变快但前后步骤没变快，阶段间信息折损变大，整条链路熵在增加而非减少。

问题不在 AI 不会写代码，而在旧流程没有给 AI 准备可执行的输入和可验证的出口——旧流程是为"人理解人"设计的，要重新设计的不是 AI，而是它工作的流水线。本文分享：如何将适配传统人工研发的旧流程，重构为适配 AI 编码的五道标准化关口——需求澄清、技术方案、TDD 实施、门禁卡控、全流程埋点监控。

第一章的五个挑战背后其实是同一件事：旧流程是给"人理解人"设计的。治理思路就是把研发流水线重构成五道关口，让每个痛点在源头就被接住。

定位：一个 Claude Code 的 Spec-Driven 开发插件，把"需求澄清→技术方案→执行计划→TDD 实施→准入准出"串成一条带用户确认门控的工作流。

整体采用五层自底向上的架构设计：

• 基础设施层：统一埋点定义和阶段性产出规范，双层采集通道（Hook 自动层 + SKILL 显式层）实现全链路数据采集。

• Agent 系统层：设计 Agent、意图工程、上下文工程，通过"链式调用→并行协作→反馈修正→结果汇总"编排。

• 开发流程层：定义五阶段核心研发流程。

• 度量层：全链路可观测，量化数据采集、分析、报告与可视化。

• 治理层：顶层保障，将核心治理能力（spec/code/arch/BDD 四维并行审查）内嵌到前四层。

工作流的第一阶段是需求澄清。在这一步，我们不产出任何代码，甚至不讨论代码——只做一件事：让业务意图被精确地、结构化地记录下来。

拿贯穿全文的案例说：出海下单支持礼品卡，礼品卡金额 = 礼品卡面值 + 出海服务费。算错是资损，且有一个跨环节约束——确认订单和创建订单两处都要算礼品卡金额，漏一处就会出现确认时和下单时金额对不上。在需求澄清关口，我们要钉死的是"算什么、什么情况算错了要阻断"。

落到出海礼品卡上，Gherkin 场景这样写：

• 正常路径：Given 出海下单选礼品卡支付，面值 100 元 + 出海服务费 10 元，When 用户确认订单，Then 礼品卡金额 = 110 元。

• 异常边界：Given 礼品卡面值 + 服务费计算后金额异常，When 下单，Then 阻断并提示，不创建异常金额订单。

• 优先级标定：礼品卡金额一致性场景标 P0，必须通过才能发布。

后续的 BDD-acceptance agent 会把每条 Gherkin 场景一对一映射到 TDD 用例，逐条验收——需求、测试、实现三者一一对齐。传统流程中 PRD 是"给人看的文章"，AI 读完后"猜"要做什么、测试再"猜"要测什么，两次传递两次折损；我们强制在需求阶段产出 Gherkin 场景（Given-When-Then）作为需求与测试之间的"硬契约"，让验收标准从一开始就是机器可读、可执行的。

Spec 固定六节：①文档基本信息 ②业务目标与用户价值 ③核心业务流程 ④边界条件与异常场景 ⑤业务规则与协作边界 ⑥优先级与验收方法。每节强制业务语言，技术术语一律屏蔽：

字段类型、表结构、接口签名、上下游系统名一律不写（tech-design 阶段的事）。模板由独立子 Agent 渲染、不注入主会话上下文，保证产出格式稳定一致。

需求澄清开始前，自定义插件会自动触发获取对应知识库信息，传入 PRD 中的业务场景关键词，从知识库 + 代码现状中拉取一份"现状分析报告"。这份报告是需求澄清的事实底座，作用是：

• 避免凭印象描述现状：AI 不会"觉得"某个功能现在是怎么工作的，而是基于代码和文档的事实。

• 避免新增能力与已有逻辑撞车：写新需求前先知道"这块之前是怎么设计的"。

• 澄清过程可回溯：每个判断都能溯源到知识库或代码，而不是拍脑袋。

按"该问 / 不该问 / 可跳过"三类管理提问：

需求澄清关口核心：BDD 钉死验收、模板屏蔽技术语言、知识库兜住现状、提问管理该问不该问——让"做什么"和"怎么算做完"在起点就被精确记录。

承接上一关口：需求澄清把"算什么"（What）钉死，技术方案这一关口要回答"怎么改"（How）和"算错了怎么兜"（Fallback）。核心思想一句话——不让 AI 在编码时临场发挥，所有设计决策在编码前就被锁定。

拿到需求 Spec 后，tech-design 阶段不会直接跳进代码细节。先做自上而下的模块拆解：

• 第一步：解析服务清单。从需求规格的"整体架构/跨服务总览"章节解析本次涉及的服务清单。

• 第二步：逐服务拆到模块粒度。每个涉及的服务按场景拆解，每个场景下固定五个子部分：

▎ 场景详细设计（每个场景固定五部分）
├── 模块详情（五段式结构）
│   ├── 目标：这个模块要达成什么
│   ├── 变更位置：改哪个类、哪个方法
│   ├── 字段/配置变更：加什么字段、改什么配置
│   ├── 构建/处理逻辑：核心处理流程
│   └── 阻断/兜底行为：异常时怎么处理
├── 异常与边界：边界条件清单
├── 新增清单：新增的类/方法/配置
└── 上下游协作（表格形式）
    ├── 上游依赖项
    ├── 下游影响项
    ├── 是否需要对方改动
    └── 联合设计状态

落到出海礼品卡上，五段式是这样写的：

出海礼品卡需求拉取时，会命中一条关键跨环节不变约束："确认订单要算礼品卡金额（含出海服务费）""创建订单也要算——两处算法必须一致"。命中的约束逐条让用户选"纳入"还是"明确排除"——排除必须填理由，理由在门禁阶段会被强制复查，防止有人为图省事把关键约束排除了。纳入的约束作为场景详细设计的输入，方案从一开始就"长"在规约上，并像影子跟到编码和门禁阶段，"入口拉了哪些规约，出口就查哪些规约"，形成完整证据链。CLI 不可用时降级跳过并在产物中明确标注，不静默漏过。

所有技术方案走统一模板，五大核心章节固定顺序：一、业务用例分析 → 二、整体架构 → 三、场景详细设计 → 四、数据结构设计 → 五、稳定性设计。

层面一：模块详情层的"阻断/兜底行为"——每个模块必须明确具体动作（阻断/降级/默认值），不能只写模糊的"兜底处理"。

层面二：稳定性设计层（第五章）——按可灰度 / 可监控 / 可回滚三维度展开，弱依赖模块在这里补全熔断、降级链路：

承接上一关口：技术方案把"怎么算"锁死后，编码就变纯粹——照方案"翻译"成代码，再用 TDD 卡住"做完没"。

技术方案被拆解为可独立验证的任务列表，每个任务有三个硬约束：

• 足够小，可独立完成——一个任务的产物应该是可独立 review 的最小单元。

• 有明确的 RED/GREEN 验证点——先写测试（RED），再写实现（GREEN），没有例外。

• 可独立回退——任务失败时可以单独回退，不影响其他任务。

这样拆解的目的是：把"写一段大代码"这件事，变成"完成 N 个小任务"。每个小任务都有明确的入口（失败的测试）和出口（通过的测试）。AI 不再有"自由发挥"的空间——想写代码，先证明你想清楚了它该怎么测。

编码前，架构检测先卡一次：

• 分层是否越界——比如 Controller 层直接调 DAO 层，跳过了 Service 层。

• 依赖方向是否反转——比如领域层反向依赖了基础设施层。

• 模块边界是否穿透——比如订单模块直接调用了支付模块的内部类。

这一步的设计意图是：避免实现跑偏后再返工——方向错了，代码写得再快也没用。架构预检是"事前防"，比"事后查"成本低得多。

TDD 的三步循环：

放到出海礼品卡上，三步循环是这样跑的：

• RED：先写"礼品卡面值 100 + 出海服务费 10 = 110 元"的测试，预期礼品卡金额 = 110 元。

• GREEN：实现 GiftCardCalculator.calcAmount 让测试通过。

• REFACTOR：把"面值 + 服务费"的算法抽成公共方法，确认订单和创建订单复用同一份。

TDD 确保每行代码都有对应测试，测试又对应到需求澄清的 Gherkin 场景——需求→方案→计划→测试→代码，一条完整可追溯链。

为什么 TDD 在 AI 时代格外重要？AI 写代码最大的问题不是写不出来，是它太自信了。它会在没有测试的情况下，写一段看起来很合理的实现，然后自信地告诉你"完成了"。TDD 的价值在于，先有一个失败的测试摆在那里，AI 必须让这个测试通过——这是一个客观的、不可糊弄的锚点。没有 TDD，AI 的"完成"是主观判断；有了 TDD，AI 的"完成"是测试通过——客观、可验证、不可糊弄。

承接上一关口：编码过了 TDD，最后一道关口是门禁——但"审核"不只发生在 gate-check，每个阶段产物落地都有对应审核，gate-check 是最终汇总。门禁的设计遵循四个核心原则：

• 机器判定为主：每个审核 Agent 输出结构化 JSON，门禁读 JSON 判 PASS/FAIL，不靠 LLM 主观总结。

• 人工决策为辅：只有关键决策点（如回退方向、排除规约的理由）才需要人确认。

• 所有结论落本地磁盘，数据可回溯：每一步都有结构化证据，不是"凭印象觉得没问题"。

• 失败必须回退到具体阶段：门禁 FAIL 不是简单打回重来，而是定位到具体阶段、具体问题。

审核机制贯穿全流程，每个阶段产物落地时都有对应的审核 Agent，gate-check 只是最终汇总：

放到出海礼品卡需求上看门禁怎么查：

• invariant-reviewer：技术方案阶段"纳入"的"确认订单和创建订单都要算礼品卡金额"约束，两处调用点是否都同步改了——只改一处就 FAIL。

• delta-guard：新增的出海服务费查询外部调用是否登记、是否有降级——命中"外部调用"检查项，没降级就高亮提醒。

• bdd-acceptance：需求 Spec 里"礼品卡 = 110 元""金额 ≤ 0 阻断"两条 Gherkin 场景，必须有对应测试且全部通过。

增量代码检测是"代码准入检查"的工具，主要用于合并代码前的自动审查和开发者本地自查。它会用 9 个维度扫描本次改动的代码——比如有没有引入新的外部调用、新的线程池、错误码是否重复、关键调用链上有没有动到不该动的节点等——然后把结果整理成一份飞书报告，直接发到项目组的知识库下。

• 可扩展：每条规则是独立小目录，一个配置 + 一个扫描脚本，新增规则不动其他地方，预留大模型判断扩展位。

• 可复用：解析代码差异、查代码作者、生成飞书文档等基础动作下沉为共用工具，代码差异只解析一次，9 条规则读同一份数据。

• 轻量级：纯文本扫描 60 秒超时、秒级返回，流水线三级兜底，单条规则挂了不拖累其他，飞书发不出也留本地文件。

承接上一关口：前四道关口是"闸门"，这一道是"仪表盘"——告诉你改进到底有没有效果。

埋点监控把研发过程变成数据：这次需求花了多少人力成本、哪个阶段最耗时、知识库调用成功率高吗、门禁通过率在变好还是变差、回退了两次根因是需求没写清还是方案设计漏了。让改进有据可依。

把看板上的指标按"问什么问题"归类：

场景一：知识库补充——从用户问答里挖"该补什么" 

信号组合：知识库调用成功率低 + 引用知识条目少 + 用户问答多 → 知识库要么内容少、要么命中率低。高频问题清单就是知识库该补充的内容清单。

场景二：流程优化——从耗时和对话轮数里找"哪里设计得不好"

核心判断标准：耗时高不一定是问题，但耗时高 + 对话轮数异常高一定是流程设计问题，不是模型慢。

场景三：子代理与工具调用收敛——从"谁在白干"里找"哪里该收敛"

AI Coding 走到下一阶段，比拼的不再是谁的模型更强，而是：谁能把 AI 的产出，变成可验证、可度量、可负责的研发生产方式。这五个字——可验证、可度量、可负责——才是 AI Native 研发范式的核心。模型能力是变量，流程设计是常数。变量决定上限，常数决定底线。交易核心系统的底线，不能交给变量。

文 / 行亦

关注得物技术，每周三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

本文是得物技术专家在 AICon 上海演讲整理的技术实录。AICon上海2026_全球人工智能开发与应用大会暨大模型应用生态展_InfoQ技术大会

「得物推荐 AI Harness 工程化实践系列」的末篇内容，本系列共三篇连载。本篇（末篇）详解得物推荐评测平台的完整技术体系：从主观体验量化到大模型自动化评测流水线，涵盖多维度指标设计、人机协作提示词校验闭环、分布式任务调度与成本精控等核心工程实现，以及单周百万级审计需求下实现 91% 资源成本优化的工业级落地实战细节。

在推荐系统中，CTR 和 CVR 等硬性指标往往容易通过实时数据进行观测，但新颖性、相关性等评价维度由于主观性强、反馈周期长，长期处于量化黑盒状态。本文将介绍得物自动化评测平台的建设方案。该平台通过引入大模型评测能力，将评测反馈周期从周级缩短至小时级，并在支撑单周百万级审计需求的背景下，实现了 91% 的资源成本优化。

在得物推荐评测平台建设前，推荐产研团队在优化用户体验和长尾策略时，面临以下核心痛点：

• 主观指标难以定量：判断一个商品是否属于算法针对用户潜在兴趣的合理推荐，过去高度依赖人工审计，缺乏统一且可连续对比的数据标准。

• 反馈周期严重滞后：策略上线后，通常需要等待一周的大盘例行数据才能得出综合评估，无法满足策略高频迭代的需求。

• 审计成本居高不下：面对百万级别的全量对比和竞品评测需求，依靠传统人工评估模式需要投入巨大的人力资源，难以形成常态化的日常诊断。

为了打破这一基建瓶颈，得物推荐评测平台应运而生，旨在通过自动化流水线将主观的发现性指标转化为可实时监控、可精确对比的结构化数据。

得物推荐评测平台通过任务流自动化和指标多维可视化，构建了完整的全自动评测空间。

在评测任务管理中心，产研同学可以一键拉起不同类型的评测任务。

• 任务承载：上线初期，平台已稳定支撑大量实验任务、1 组例行大盘以及多场友商对比评测。

• 吞吐能力：依托异步底座，单周评测数据处理量已达到百万级别。

评测空间是针对具体 case 进行深度拆解的场所。平台支持结合用户的多维画像特征进行全自动化洞察：

• 智能辅助评估：平台引入了 AI 辅助模式，从相关性、新颖性等维度对推荐结果进行 1 到 5 分的动态打分，并输出具体的判定依据。

• 多维特征关联：评测员或算法同学可以通过双列视图直观看到商品详情，快速定位异常推荐结果。

评测工作界面

在数据报表模块，得物推荐评测平台实现了全层级指标的实时监控与下钻分析：

• 核心 KPI 提炼：报表实时输出有效发现率、精准推荐率以及无效推荐率。

• 分级下钻：评测记录被精细化划分为 L0 到 L4 等不同层级，产研可在小时级内清晰掌握实验组与基线的水位差，彻底告别直觉判断。

数据报表

在得物推荐评测平台中，评测提示词的设计与评估一致性的对齐，并非通过硬编码锁死，而是交由产品与业务专家基于实际场景进行敏捷迭代。为了支撑业务同学能够独立、高效地完成提示词的调试与人工校验，平台在底层构建了一套完善的工程化配置与校验基建：

动态提示词（Prompt）版本管理：平台将评测提示词抽象为独立的配置资产。产品同学可以针对相关性、新颖性等不同评测维度，在后台可视化界面中独立调优 Prompt。平台支持 Prompt 的版本控制与热更新，确保策略调整后，评测标准能够秒级同步，无需经历繁琐的代码发布流程。

低门槛的评测员配置矩阵： 平台底层解耦了具体的模型供应商，提供了统一的接入协议。业务同学可以自由选择 Qwen3-Max 等不同量级的模型作为评测员，并在系统配置中实时观测其并发能力、当前版本的准确率以及与人工结论的一致性水位。

系统配置与评测大模型管理

人机协作的在线校验流：为解决大模型在复杂电商场景下的理解偏差，平台构建了高效的样本校验工作流。产品同学在调整 Prompt 后，可一键抓取历史真实 case 进行小规模盲测。通过平台提供的双列视图，人工专家可以对 AI 的打分和文本解释进行实时审计与修正。