title: 云原生自主编码 Agent 架构
description: 面试与技术分享版,介绍一个从用户任务到代码 PR 的云端 Agent 平台如何设计。

云原生自主编码 Agent 架构

适用场景:系统设计面试、AI Agent 平台介绍、云原生架构分享。

60 秒摘要

这是一个面向软件工程任务的云端自主 Agent 平台。用户用自然语言提交需求,控制面完成身份认证、权限检查、知识检索、任务持久化和调度;执行面为每个任务创建隔离的 Runner Pod,Agent 在 Pod 中读取代码、调用工具、运行测试并创建 Pull Request。任务进度和执行 Trace 通过消息总线异步回传,Portal 实时展示结果,并允许用户中途调整或终止任务。

用户

Web Portal

业务控制面

PostgreSQL

消息总线

Runner Manager

隔离 Runner Pod

编码 Agent

代码仓库

Pull Request

核心思想不是“让大模型直接操作生产系统”,而是把模型放进一个有明确边界、可观测、可中断、可回收的执行环境。

1. 为什么需要平台,而不是直接使用聊天模型

一次性 LLM 调用只能生成文本,而工程任务需要持续观察真实世界:

  • 代码仓库结构未知,需要搜索和阅读。
  • 修改后可能编译失败,需要运行测试并修复。
  • 用户可能中途改变需求。
  • Git、CI、PR 和浏览器验证都有外部状态。
  • 长任务必须有成本、超时、权限和失败恢复边界。

用户需求

模型分析

调用工具

读取真实结果

任务完成?

构建与审查

创建 PR

这类系统的本质是一个受控状态机,而不是一个更长的聊天窗口。

2. 控制面与执行面

系统被拆成两个主要平面。

控制面

控制面负责稳定、长期、面向用户的业务状态:

  • Entra ID 用户和服务身份认证。
  • 项目与仓库权限检查。
  • Task、Session、Trace 持久化。
  • 任务协作者、所有权和可见性。
  • 知识检索与执行计划。
  • 消息发布、进度订阅和实时推送。

执行面

执行面负责动态、资源密集、可能失败的工作:

  • 创建和删除 Runner Pod。
  • 分配 CPU、内存、磁盘和镜像。
  • 克隆仓库并启动 Agent。
  • 执行文件、Shell、Git、浏览器和 DevOps 工具。
  • 上报上下文、Trace、心跳和最终状态。

执行面

控制面

API Service

Task / Session / Trace

Message Bus

Runner Manager

Runner Pod A

Runner Pod B

为什么不合成一个服务

如果 API Service 直接管理 Kubernetes 并执行代码,它会同时承担用户请求、数据库事务、Pod 生命周期和不可信代码执行。一旦某个任务耗尽内存或阻塞线程,用户 API 也可能受到影响。

拆分后,两侧可以独立扩缩容、部署和授权:控制面保持稳定,执行面允许任务级失败。

3. 一次任务的端到端流程

Runner AgentRunner ManagerMessage BusKnowledge ServiceAPI ServicePortal用户Runner AgentRunner ManagerMessage BusKnowledge ServiceAPI ServicePortal用户提交自然语言任务创建任务认证、授权、写 Task检索知识并生成 PlanKnowledge + Plan写 Session发布 Session New投递任务创建隔离 Pod搜索、修改、测试、创建 PRProgress + Trace更新状态SSE 实时推送

任务创建接口快速返回,实际执行异步进行。这样用户不需要保持一个几分钟甚至几小时的 HTTP 请求。

4. Task、Session 与 Trace

Task: 长期业务目标

Session 1: 首次执行

Session 2: 用户调整

Session 3: 失败重试

Trace: 模型消息

Trace: 工具调用

Trace: 测试结果

  • Task 表示长期目标和最终 PR。
  • Session 表示一次独立执行或后续调整。
  • Trace 表示一次模型回复、工具调用、测试或状态事件。

为什么后续调整不创建新 Task?因为用户仍在推进同一个业务目标。Session 既保留历史,又允许使用新的 Pod 和新的执行上下文。

5. 为什么使用消息总线

跨服务命令和进度通过消息总线传递,而不是要求同步 HTTP 一直成功。

Session New

Progress / Trace

API

Message Bus

Manager

与同步 HTTP 对比

同步 HTTP消息总线
调用方等待执行结果发送后即可返回
下游不可用会立即失败消息可以缓冲和重试
调试链路较简单需要处理重复、延迟和最终一致性
适合短操作适合长任务和跨网络边界

代价是状态不会在每个瞬间完全一致。因此消息需要幂等,Trace 使用 nonce 去重,状态更新必须容忍重复投递。

6. 为什么每个任务一个 Pod

任务 A

Pod A / Repo A

任务 B

Pod B / Repo B

任务 C

Pod C / Repo C

Pod 级隔离提供:

  • 独立文件系统和 Git 工作区。
  • 独立 CPU、内存和临时磁盘边界。
  • 任务完成后整体回收。
  • Linux/Windows 节点池按需选择。
  • 一个 Agent 崩溃不会污染其他任务。

与“单机运行多个 Agent 进程”相比,Pod 成本更高、启动更慢,但隔离、安全和可运维性更适合多用户平台。

7. Agent 内部结构

Task + Session + Knowledge + Plan

Agent Core

LLM Adapter

MCP Tool Server

Safety / Quality Hooks

File Tools

Shell

Git / PR

Browser

context.json + traces.jsonl

模型只负责选择下一步,工具才真正修改外部世界。工具调用前后经过确定性 Hook:权限开关、Git 分支保护、PR 规则、命令检查和结束前 Review。

为什么不只依赖 System Prompt?Prompt 是概率性约束;Hook 可以在危险操作真正执行前确定性拒绝。

8. 文件通信与可观测性

Agent 不直接连接业务数据库,而是在 Pod 内输出:

output/
├── context.json
└── traces.jsonl

原子替换

追加

Agent

context.json

traces.jsonl

Runner Bridge

平台服务

context.json 保存任务状态、当前步骤、当前工具和心跳;traces.jsonl 保存可增量消费的事件。先写临时文件再原子替换,避免监督进程读到半个 JSON。

这种设计比 Agent 直接调用远程 API 更容易本地测试,也把网络重试、认证和上报职责集中到 Bridge。

9. 安全与人工控制

用户

任务级能力开关

写文件

运行命令

创建或更新 PR

浏览器访问

中途 Steering

终止任务

平台采用“任务级能力授权 + 运行中可调整/终止”,而不是每个工具动作都弹窗审批。这样保持异步自主性,同时给用户明确监督权。

10. 失败模型

故障处理方式
模型暂时失败有界重试或模型降级
工具失败把错误作为 Observation 返回模型
Agent 重复循环卡住检测和策略 Nudge
达到最大步数标记失败并生成短期记忆
Pod 崩溃Runner Manager 棴测并清理
消息重复幂等更新和 Trace nonce 去重
用户终止协作式中断、保存上下文后退出

11. 设计取舍

为什么是 App Service + AKS,而不是全放 AKS

稳定 HTTP 控制面适合托管 Web 平台;动态、资源密集、需要 Windows/Linux 混合节点的 Runner 更适合 AKS。全放 AKS 可以统一平台,但会增加控制面运维复杂度。

为什么是 PostgreSQL,而不是纯文档数据库

Task、Session、用户、协作者和 Trace 有明确关系,需要事务、分页和统计。JSONB 用于保存可扩展上下文,关系模型用于保持核心一致性。

为什么是 SSE,而不是 WebSocket

Portal 主要接收单向进度流,用户命令可通过普通 POST 发送。SSE 基于 HTTP、重连简单;WebSocket 更适合高频双向协作。

12. 当前限制与演进方向

  • 部分进程内异步状态不适合无限水平扩展,可迁移到 Redis 或数据库。
  • DB 写入与消息发布不是单一事务,可引入 Transactional Outbox。
  • Pod 启动存在冷启动,可通过镜像预拉取和温池改善。
  • Agent 自主性越高,越需要更强的工具权限、审计和评测。
  • 文档知识可能过时,应引入 Owner、版本和自动回归评测。

13. 面试表达建议

建议按以下顺序讲:

  1. 先讲业务目标:自然语言任务到 Review-ready PR。
  2. 再讲核心难点:长任务、隔离、状态、权限和可观测性。
  3. 画控制面/执行面分离图。
  4. 展开一次任务的消息链路。
  5. 重点解释一个取舍,例如消息总线或 Pod-per-task。
  6. 主动说出限制和下一步演进。

常见追问

如何避免一个任务重复创建两个 Pod?

通过消息幂等键、数据库状态检查和 Kubernetes Lease 分布式锁,使多个 Manager 副本只允许一个成为创建者。

为什么 Runner Manager 可以多副本?

权威状态位于 PostgreSQL、Kubernetes API、PVC 和 Lease,Manager 实例尽量不保存不可恢复的本地状态。

如何证明 Agent 真做了工作?

平台保存工具调用、测试输出、Git Diff、PR 地址和实时 Trace,而不是只展示模型的自然语言声明。

最大的工程挑战是什么?

不是接入模型,而是把不确定的模型行为包裹在确定性的状态、权限、工具、消息、评测和恢复机制中。



title: 超大代码仓库的上下文组织与 Agentic RAG
description: 面试与技术分享版,介绍几 GB 代码仓库如何被压缩为模型可用的上下文。

超大代码仓库的上下文组织与 Agentic RAG

适用场景:RAG、代码智能、大模型上下文工程、超大仓库理解相关面试。

60 秒摘要

几 GB 代码仓库不会直接进入模型上下文。完整仓库保留在磁盘,系统通过三层漏斗组织信息:DevBrain 提供长期项目知识,Task/Plan/Skill 组成任务级上下文,Agent 再用 Search/Read 工具按需获取当前代码证据。CodeTravel 将跨文件流程压缩成结构化 Codemap,长对话通过摘要压缩。当前 DevBrain 主路径属于 Agentic 文档 RAG:LLM 根据文档目录和 Front Matter 摘要选择相关文档,再读取正文组装 Knowledge;它不是经典的向量数据库 Top-K RAG。

几 GB 完整仓库

按需搜索

候选片段

精确行读取

有限模型上下文

项目知识库

Agentic RAG

编码 Agent

1. 核心问题:磁盘容量与 Context Window 不同

一个仓库可以有数万个文件、数百万行代码,但模型一次只能接收有限 Token。真正的问题不是“如何把仓库全部塞进去”,而是:

对当前问题,怎样用最少上下文保留足够证据?

完整代码仓库

全部放进 Prompt?

超过上下文上限

无关代码干扰

延迟与成本过高

检索、读取、压缩

问题相关证据

仓库是外部可查询记忆,Context Window 是当前工作记忆。

2. 三层上下文模型

长期知识层

任务上下文层

即时证据层

Agent 决策

长期知识层

长期知识保存不容易从代码直接推断的内容:

  • 项目架构和领域术语。
  • 开发、测试、发布和 PR 流程。
  • Feature Flag、Staging 和团队约定。
  • 常见模块、代码入口和历史经验。
  • 结构化 Codemap。

任务上下文层

任务创建时注入:

  • 用户需求。
  • DevBrain Knowledge。
  • 执行 Plan。
  • AGENTS.md 强制规则。
  • Skill 名称、描述和路径。
  • Workspace、任务类型和权限。

即时证据层

Agent 在执行过程中按需获取:

  • 搜索命中片段。
  • 某个函数附近的行范围。
  • 调用方和被调用方。
  • Git Diff、测试错误和 Pipeline 输出。
  • PR 评论和浏览器结果。

3. 当前 RAG 怎样工作

RAG 可拆成:

RAG=Retrieval+Augmentation+Generation RAG = Retrieval + Augmentation + Generation RAG=Retrieval+Augmentation+Generation

任务描述

选择相关文档

Markdown Knowledge Base

读取并拼接正文

Knowledge Context

生成计划

指导执行

当前 DevBrain 主路径不依赖 FAISS、Chroma、pgvector 或图数据库。检索过程是:

  1. 扫描对应 Workspace 的 Markdown 文档。
  2. 提取路径、分类和 Front Matter summary
  3. 将结构化 TOC 与任务交给检索 Agent。
  4. Agent 返回文档路径和相关度。
  5. 验证路径必须位于 Workspace 内。
  6. 按优先级和相关度排序。
  7. 读取完整正文,去除 Front Matter。
  8. 使用分隔符拼成最终 Knowledge。
Markdown FilesRetrieval AgentDocument TOCDevBrainAPI ServiceMarkdown FilesRetrieval AgentDocument TOCDevBrainAPI Serviceworkspace + task扫描路径、摘要和分类候选 TOCreferences + relevance校验并读取正文Markdown contentknowledge + references + plan

4. 为什么不用纯向量 RAG

Agentic 文档 RAG向量 RAG
理解路径、摘要和文档类型根据向量距离快速检索
易加入 How-to 优先等业务规则适合海量 Chunk
无需维护向量索引检索成本和延迟更低
每次选择需要 LLM 调用复杂流程关系可能召回不足
可解释选了哪些文档相似度不一定可解释

当前知识库结构清晰、规模可控,而且业务规则很重要,例如:

  • How-to Guide 最多选择一篇最相关文档。
  • How-to 的引用文档可自动加入一层。
  • How-to 优先级高于普通 Reference。
  • 带实验标记的文档只有对应 Exp 开启才可使用。

这些规则使用纯 Top-K 向量相似度很难表达。

合理的下一步不是完全替换,而是混合检索:

Query

Keyword / BM25

Vector Search

TOC Agent

Codemap Search

Candidate Fusion

LLM Rerank

5. 搜索工具怎样控制上下文

大仓搜索采用漏斗式限制:

数万文件

路径/扩展名过滤

有限候选文件

快速文本搜索

有限结果数

每文件少量片段

小规模 Observation

典型限制包括:

  • 限制候选文件数量,避免全仓无限扫描。
  • 一次返回有限结果。
  • 每个文件只返回少量命中片段。
  • 限制总输出字符数和单行长度。
  • 搜索不完整时明确标记,要求 Agent 缩小条件继续查找。

这比“搜索后把全部匹配结果给模型”更稳定,因为模型最容易被大量相似命中淹没。

6. 文件读取采用渐进披露

文件工具支持指定行范围,并设置最大字符和行数限制。

搜索命中 1800 行

读取 1770-1850

发现调用符号

查找定义/引用

读取另一个窄区间

模型只看到当前调用链需要的局部代码。若输出被截断,它必须继续读取更窄范围,而不是把截断内容误认为完整文件。

7. CodeTravel 如何理解跨文件流程

CodeTravel 使用 ReAct 循环主动探索:

代码问题

判断需要什么证据

搜索符号/关键词

观察命中

读取关键实现

更新 Codemap Draft

证据充分?

输出 Codemap

它不是预先索引整个仓库,而是针对问题逐步建立调用链。默认探索有最大步数,避免无限搜索。

8. Codemap 是问题相关的上下文压缩

Codemap 保存:

  • 逻辑 Trace。
  • 精确文件路径和行区间。
  • 位置标题与说明。
  • Trace Diagram。
  • Motivation 和 Details Guide。
  • 模型、耗时、Token 和成本元数据。

几 GB 源码

问题驱动探索

几十 KB Codemap

人类导航

后续 Codemap 检索

这是一种有损压缩:舍弃与问题无关的代码,保留关键位置和关系。

9. 外部草稿如何降低模型记忆压力

Agent 将 Codemap 保存为渐进式 JSON Draft:

建立骨架

code-1.json

补充位置

code-2.json

补充解释

code-3.json

Schema 校验

codemap.json

草稿充当外部工作记忆。模型不需要每轮在对话中重新输出整个 JSON,修改也可以被精确验证和追踪。

10. 长 Session 如何压缩

编码 Agent 会在消息数或 Token 达到阈值时压缩历史:

长消息历史

合并 Tool Call 与 Result

LLM 摘要

短期记忆

最新 Steering

压缩后追加

需要保留:任务目标、关键决定、文件/符号、Branch/PR、失败原因、未完成步骤。可以丢弃:重复搜索、过长原始输出和已经不影响后续的临时过程。

最新用户指令必须在压缩后追加,避免刚到达的 Steering 被摘要掉。

11. 为什么 Knowledge 不能替代实时代码搜索

文档知识

告诉 Agent 去哪里、遵守什么

实时源码

确认当前实现是什么

最终决策

文档擅长保存动机、流程和隐含规则,但可能过时;源码最新,却不一定解释为什么。二者结合优于任何单一来源。

12. 安全与隔离

  • Knowledge 按 Workspace 选择,避免跨项目误用。
  • 文档路径必须规范化并限制在 Workspace 根目录内。
  • 原始 Knowledge 不直接返回浏览器,而是使用短期 opaque reference。
  • Task 创建时服务端解引用,再写入 Session。
  • Agent Prompt 明确规定 Knowledge 低于系统安全规则和用户最新指令。

Raw Knowledge

服务端短期存储

Opaque Knowledge Ref

Portal

创建任务

服务端解引用

Session

13. 典型失败与对策

失败模式对策
搜索结果太多路径过滤、分页、结果上限
漏掉关键符号多轮 Query Reformulation
文档召回过多Precision/Recall 评测和 Rerank
文档过时Owner、版本、更新时间和代码验证
长上下文爆炸外部草稿、摘要压缩、窄读取
Codemap 行号过期绑定 Commit Hash
Knowledge Ref 丢失后续迁移到共享缓存/数据库

14. 面试表达建议

可以用一句话开场:

我们不把大仓库放进模型,而是把仓库当作可查询外部记忆,通过长期知识、任务上下文和即时证据三层漏斗动态构建 Prompt。

然后重点展开:

  1. 为什么仓库大小与 Context Window 是两个问题。
  2. Agentic RAG 与向量 RAG 的取舍。
  3. Search/Read 工具如何限制输出。
  4. Codemap 和 Draft 如何充当外部记忆。
  5. 如何评测检索和定位质量。

常见追问

几 GB 仓库第一次搜索不会很慢吗?

本地 Ripgrep 和路径过滤负责第一轮快速缩小范围;预生成知识和 Codemap 提供搜索方向。若规模继续增长,可以增加预索引、BM25 或向量候选召回。

如何避免模型只看文档,不检查代码?

Prompt 和工具流程要求把 Knowledge 视为指导,并使用当前代码、测试和 Git 状态验证。Codemap 还必须给出真实路径与行号。

为什么 RAG 结果直接拼整篇文档?

它保留完整流程和团队约定,适合当前文档规模;代价是 Precision 偏低、Token 较多。未来可升级为 Section-level Hybrid Retrieval。

如何知道上下文组织是有效的?

分别评测文档检索的 Precision/Recall、代码定位的 REGION 指标、语义解释的 RUBRIC 分数,以及 Token、成本和延迟。



title: AI Coding Agent 的评测与质量保障体系
description: 面试与技术分享版,介绍如何同时评测检索、代码定位、语义解释、成本和端到端质量。

AI Coding Agent 的评测与质量保障体系

适用场景:AI Evaluation、LLM-as-a-Judge、Agent 可靠性、质量平台相关面试。

60 秒摘要

Agent 评测不能只看“最终回答像不像对的”。这个体系将质量拆成三层:DevBrain Evaluation 检查 RAG 是否找对知识文档;CodeTravel Benchmark 用 REGION 确定性指标检查是否定位到正确代码,用 RUBRIC LLM Judge 检查是否解释完整;生产侧再观察构建、测试、PR 合并、用户追加 Session、延迟和成本。Benchmark 固定 repo@commit Docker 快照,保存完整 Artifact,使不同模型和 Prompt 版本可公平比较、可诊断和可回归。

Agent Quality

RAG Retrieval

Code Localization

Semantic Explanation

End-to-End Delivery

Cost / Latency / Tokens

1. 为什么传统单元测试不够

单元测试擅长判断确定性函数,但 Agent 输出具有开放性:

  • 可以使用不同但正确的代码路径。
  • 解释文字没有唯一标准答案。
  • 同一模型重复运行可能有差异。
  • 找到文件不代表解释正确。
  • 解释流畅不代表代码位置真实。
  • 质量提升可能伴随不可接受的成本。
渲染错误: Mermaid 渲染失败: Lexical error on line 3. Unrecognized text. ...e 代码理解质量 x-axis 定位错误 --> 定位正确 y- ----------------------^

因此评测必须拆维度,而不是只给一个“感觉不错”的总分。

2. 评测全景

Evaluation System

DevBrain Retrieval Eval

CodeTravel Benchmark

Production Metrics

Precision / Recall / F1

REGION Metrics

RUBRIC Judge

Token / Cost / Latency

Build / Test / PR Merge

3. Benchmark Case 怎样定义

每个 CodeTravel Case 固定:

  • Repository URL。
  • Commit SHA。
  • 用户问题。
  • Core/Optional 代码区间。
  • 分层、带权重的 Rubric。
  • 语言和来源 PR。
{
  "id": "settings-search-history-focus",
  "repo": "https://github.com/example/repo",
  "commit": "<fixed-sha>",
  "question": "How does search history and focus navigation work?",
  "ground_truth": {
    "core_regions": [],
    "optional_regions": []
  },
  "rubrics": []
}

问题来自真实 PR 所涉及的功能和代码路径,而不是只使用玩具算法题。

4. 为什么必须固定 repo@commit

渲染错误: Mermaid 渲染失败: Lexical error on line 4. Unrecognized text. ...Snapshot[/testbed 快照] Snapshot --> V -----------------------^

如果代码每天变化,行号、文件和实现都会改变,分数不再可比。Benchmark 离线构建 repo@commit 镜像,运行时校验镜像中的 Git HEAD 必须等于 Case Commit。

同一 Commit 的多个问题共享一次 Workspace 提取,减少几 GB 仓库反复复制的 I/O 成本。

5. 端到端评测流程

加载 Case

按 repo + commit 分组

从 Docker 提取 Workspace

校验 Commit

运行当前 CodeTravel

解析和 Schema 校验

REGION 评分

RUBRIC 评分

报告与 Artifact

默认可以并行生成多个 Case;调试时设为单 Worker,以获得可重复的执行顺序和清晰日志。

6. REGION:代码定位的确定性评测

Ground Truth 分为:

  • Core Regions:回答问题必须覆盖的关键代码。
  • Optional Regions:合理辅助上下文,不是必需答案。

Ground Truth

Core Regions

Optional Regions

Codemap Locations

区间比较

Region Recall

应该找到的关键区间中,有多少被至少一个预测区间覆盖:

RegionRecall=HitCoreRegionsAllCoreRegions RegionRecall = \frac{HitCoreRegions}{AllCoreRegions} RegionRecall=AllCoreRegionsHitCoreRegions

它衡量是否漏掉关键逻辑。

Region Precision

预测的代码区间中,有多少与 Core Region 相交:

RegionPrecision=PredictionsOverlappingCoreAllPredictions RegionPrecision = \frac{PredictionsOverlappingCore}{AllPredictions} RegionPrecision=AllPredictionsPredictionsOverlappingCore

它衡量是否带回太多无关位置。

Region Line Recall

Core Region 总行数中,有多少行被预测区间覆盖:

LineRecall=CoveredCoreLinesAllCoreLines LineRecall = \frac{CoveredCoreLines}{AllCoreLines} LineRecall=AllCoreLinesCoveredCoreLines

它区分“只碰到函数入口”和“真正覆盖关键实现”。重叠预测先取并集,避免重复计分。

Region Line Precision

预测区间总行数中,有多少行位于 Core Region:

LinePrecision=PredictedLinesInsideCoreAllPredictedLines LinePrecision = \frac{PredictedLinesInsideCore}{AllPredictedLines} LinePrecision=AllPredictedLinesPredictedLinesInsideCore

File Recall / Precision

文件级指标对行号轻微偏差更宽容,用于判断方向是否正确。

Context Efficiency

Optional Region 是合理上下文,因此:

ContextEfficiency=PredictionsInCoreOrOptionalAllPredictions ContextEfficiency = \frac{PredictionsInCoreOrOptional}{AllPredictions} ContextEfficiency=AllPredictionsPredictionsInCoreOrOptional

这个指标直接衡量上下文是否精简。

7. RUBRIC:语义解释质量

仅找对位置不代表讲清楚机制。Rubric 使用带权重的要求树:

Search UI Behavior

History / weight 3

Focus / weight 3

输入框保存历史

Previous/Next 遍历

命令和快捷键

搜索框与结果间移动

Down Arrow 决策

每个叶子 Requirement 单独交给 Judge:

Judge ModelScorerJudge ModelScorerQuestion + 单个 Criterion + Codemapscore 0/1 + reasoning + evidence按权重自底向上汇总

叶子采用二元分数:覆盖为 1,未覆盖为 0。要求 Judge 给出 Codemap 中的具体 Evidence,减少仅凭文风打分。

8. Rubric 分数怎样汇总

若三个叶子权重分别为 3、3、2,得分为 1、1、0:

ParentScore=3×1+3×1+2×03+3+2=0.75 ParentScore = \frac{3\times1 + 3\times1 + 2\times0}{3+3+2} = 0.75 ParentScore=3+3+23×1+3×1+2×0=0.75

系统报告:

  • rubric_overall_score
  • rubric_average_leaf_score
  • rubric_coverage
  • 各顶层类别分数
  • 每个叶子的 reasoning 和 evidence

9. 为什么 Region 与 Rubric 必须同时存在

REGIONRUBRIC结论
找对代码且解释清楚
定位正确但理解不完整
文字合理但缺少真实代码证据
整体失败

REGION 是确定性的,RUBRIC 能覆盖开放语义;二者互补。

10. LLM-as-a-Judge 的可靠性设计

Judge 不是绝对真理,因此系统增加约束:

  • 一次只评一个叶子 Criterion。
  • 只允许输出固定 JSON。
  • Score 只能是 0 或 1。
  • 必须给 Reasoning 和 Evidence。
  • 非法 JSON 最多重试一次。
  • Judge API 错误标记为 judge_error,不能当成质量分 0。
  • 支持多个 Judge Model,最终求平均。
  • 保存原始 Judge 响应供审查。

Codemap

Judge A

Judge B

Judge C

平均指标

11. DevBrain RAG 的评测

DevBrain 使用人工审核的 Qrels:

固定知识问题

DevBrain 检索

文档路径集合

人工相关性标注

比较

Precision

Recall

F1

相关等级达到阈值的文档视为正确答案。

Precision=RelevantRetrievedAllRetrieved Precision = \frac{RelevantRetrieved}{AllRetrieved} Precision=AllRetrievedRelevantRetrieved

Recall=RelevantRetrievedAllRelevant Recall = \frac{RelevantRetrieved}{AllRelevant} Recall=AllRelevantRelevantRetrieved

F1=2PRP+R F_1 = \frac{2PR}{P+R} F1=P+R2PR

还检查无效路径、Candidate Error、延迟和新旧引用集合的 Jaccard 相似度。

12. 为什么 PR CI 不直接运行在线模型评测

在线模型评测存在:成本、凭据、延迟、限流和随机性。当前流程是开发者本地运行并提交审核后的 Baseline,CI 比较 main 与 PR 的 Baseline。

本地运行模型评测

更新 baseline.json

PR

CI Baseline Guard

指标下降超过阈值?

Fail

Pass

优点是 CI 快且稳定;代价是 Baseline 更新需要人工诚信和 Review。更成熟的方案可以增加受控 Nightly 在线评测。

13. 成本与延迟评测

每个 Case 分别统计 Codemap Generation 和 Rubric Judge:

  • Prompt Tokens。
  • Cached Prompt Tokens。
  • Uncached Prompt Tokens。
  • Completion Tokens。
  • 调用次数。
  • 模型成本。
  • 生成耗时。
  • 总成本。

质量

模型/Prompt 选择

成本

延迟

稳定性

只追求分数可能让 Agent 无限搜索。工程目标是在质量、成本和延迟之间找到 Pareto 最优点。

14. Artifact 设计

runs/<run-id>/
├── run_config.json
├── summary.json
├── cases/<repo-commit>/<case>/
│   ├── question.txt
│   ├── codemap.json
│   ├── normalized_codemap.json
│   ├── codemap.log
│   └── test_result.json
└── reports/cases/<repo-commit>/<case>/
    ├── metrics.json
    ├── region_details.json
    ├── rubric_details.json
    └── score.log

为什么保存这么多中间产物?总分下降时,需要判断到底是搜索错误、行号错误、解释遗漏、JSON 失败、Judge 故障还是成本异常。可诊断性比单一排行榜更重要。

15. 生产质量保障不止离线 Benchmark

离线评测

合并前质量

编辑后 Micro Review

运行中质量

Build / Test

Browser Validation

PR Review / Merge

线上结果

用户追加 Session

线上还应观察:

  • Build/Test 成功率。
  • PR 创建率和合并率。
  • Reviewer 修改量。
  • 首次通过率。
  • 用户追加 Session 次数。
  • 从创建任务到 PR Ready 的时长。
  • 失败和终止原因。

离线指标适合快速比较版本,线上结果检验真实业务价值。

16. 当前局限

  • Dataset 主要是公开 VS Code Case,不能完全代表内部超大仓库。
  • Ground Truth 的代码区间和 Rubric 维护成本高。
  • LLM Judge 仍存在模型偏差和波动。
  • 行号对 Commit 变化敏感,因此不能跨版本直接复用。
  • Benchmark 问题比真实用户请求更清晰,无法覆盖所有交互噪声。
  • 单次运行无法衡量方差,需要重复实验。

17. 推荐的演进路线

Evaluation Suites

PR Smoke: 少量快速 Case

Nightly: 完整公开 Case

Release: 内部大仓 Case

Production: 业务指标

建议增加:

  1. 同一 Case 重复运行,报告均值、最低分和标准差。
  2. 公开仓与内部大仓双 Dataset。
  3. Prompt、模型、工具变更的分项消融实验。
  4. Retrieval、Localization、Generation 和 Delivery 分层 Dashboard。
  5. 人工盲评校准 LLM Judge。
  6. 将成本和延迟加入发布 Gate,而不是只看质量分。

18. 面试表达建议

推荐用下面这句话开场:

我们把 Agent 质量拆成“找对知识、找对代码、讲清机制、完成交付、控制成本”五个维度,分别使用确定性指标、LLM Rubric 和生产业务指标评测。

然后展示一个真实 Case 的结构,重点讲:

  1. 为什么固定 repo@commit。
  2. 为什么 Core/Optional Region 分开。
  3. 为什么 REGION 与 RUBRIC 双评分。
  4. 如何控制 LLM Judge 的不确定性。
  5. 为什么保存可诊断 Artifact。
  6. 当前局限和下一步方案。

常见追问

为什么不用 Exact Match?

代码理解没有唯一文本答案。不同文件或解释方式都可能正确,因此需要 Region 区间与语义 Rubric。

LLM Judge 会不会自己胡说?

会,所以它只负责语义维度,并受到单 Criterion、固定 JSON、二元分数、Evidence、多模型平均和原始响应审查约束。代码定位仍由确定性指标计算。

怎样防止 Benchmark 过拟合?

使用多个仓库和 Commit,保留隐藏 Case,增加 Nightly 重复运行,并同时观察生产指标。不要只针对已知 Rubric 调 Prompt。

一个分数下降后怎样定位原因?

先看 REGION 判断搜索和定位,再看 RUBRIC 叶子判断解释遗漏,然后查看 Codemap、搜索日志、Judge Evidence、Token 与耗时 Artifact。

最重要的质量原则是什么?

Agent 的自然语言自信不能作为正确性证据。必须要求可验证的代码位置、工具输出、测试结果和可追踪 Artifact。

Logo

Agent 垂直技术社区,欢迎活跃、内容共建。

更多推荐