项目二|NL2SQL 多 Agent 数据分析平台(CodeArts 场景)
状态 v0.2:业务层(§1-2)已立;结构与事实层(§3-5)、演进(§6)、个人贡献(§7)待填,填写清单见 §8。 源码:公司环境,本机不可得 ⇒ 本文所有事实必须来自 AI 回报或你本人确认,不许推测填充。 用途:它同时是三样东西——简历素材的唯一来源、面试底稿、被追问时的退守依据。
〇、这份文档的七节骨架,以及三条纪律
一份"准确"的模块总结必须回答七个问题,缺任何一个都会被追问打穿:
| # | 问题 | 谁提供 |
|---|---|---|
| 一 | 为什么需要它(业务理由) | 你(已立) |
| 二 | 它负责什么、明确不负责什么 | 你(已立) |
| 三 | 里面分成哪几块、按什么顺序跑 | AI 回报事实 + 你确认 |
| 四 | 关键决策为什么这么选(3-5 个) | 你(AI 只能给选项,给不了理由) |
| 五 | 哪里会坏、坏了怎么办 | AI 回报事实 + 你确认 |
| 六 | 怎么变成现在这样(演进) | 只有你 |
| 七 | 哪部分是你定的,哪部分是你接的 | 只有你 |
三条纪律:
- 事实与判断分开写。 每节都标出处:
[AI 回报]/[我确认]/[推测,未验证]。混在一起就会在面试中把推测当事实讲。 - 答不出的节留空,不要编。 空着可以临场说"这块我记不清",编了就没有退路。
- 每次拿到新信息,先回来改这份文档,再改简历。 简历是它的压缩版,不是独立创作。
一、存在的理由(业务视角)
1.1 一句话
给用 CodeArts 的研发和运维用的一套「问一句就够了」的排障助手——把「我想查一下某条流水线为什么变慢」这类问题,从"提需求等排期"变成一次对话。
参考:CodeArts 是一站式 DevOps 平台,覆盖需求 → 代码托管 → 代码检查 → 编译构建 → 测试 → 部署 → 制品仓库 → 效能洞察(https://codearts.huaweicloud.com/ )。
1.2 场景还原(最该背下来的一段)
一个人在 CodeArts 里遇到问题,通常是这几种:
| 问题 | 他要的答案 | 答案在哪 |
|---|---|---|
| 这条流水线平时 40 分钟,今天 90 分钟 | 哪个阶段变慢了,从哪天开始 | ClickHouse 里的阶段耗时指标 |
| 构建挂了,日志两万行 | 错在哪一步、哪一行 | 构建日志 + 报错聚类 |
| 代码检查报了一堆问题 | 哪些是这次提交引入的 | 检查结果 + 代码变更 |
| 某个项目构建排队很久 | 是配额不够还是资源池被占 | 资源池指标 + 队列数据 |
| 告警老是半夜响,其实没事 | 规则该怎么改 | 告警配置 + 历史触发记录 |
| 这个配置项为什么填错了 | 正确写法是什么 | 文档 / 历史工单 |
这些数据散在 ClickHouse(指标、日志)、DWS(数仓聚合)、业务元数据(项目 / 租户 / 流水线定义)、知识库(文档与工单)里,表名和口径都很专业。
1.3 以前怎么办,为什么不行
| 方式 | 代价 |
|---|---|
| 提需求给数据开发写 SQL | 排期按天算,一次排障等三天 |
| 自己拖 BI | 得先知道查哪张表、字段什么含义 |
| 找熟手问 | 不可规模化,且答案不留痕 |
1.4 平台的解法
自然语言进来 → 判断该找哪个分析模块 → 各自取数 → 合成一份带结论的答案,边算边推给前端。
它不只是"查数",还要"教怎么用"。 问题分两类,这是理解模块为什么这么分的钥匙:
- 诊断类(为什么慢 / 为什么挂 / 谁受影响)→ 查指标与日志,按数据域切
- 操作类(该怎么配 / 这个配置错在哪)→ 查文档与历史,按任务切
- 通用(临时查数 / 查资料)→ 取数模块、知识模块
⚠️ 「按问题类型 × 数据域正交切分」是推断,用来解释为什么是多个专职模块而不是一个大模块。需你确认,它是编排层设计合理性的第一依据。
二、责任边界(做什么 / 不做什么)
这一节比技术描述重要,因为它回答的是"没有它会怎样"。
| 模块 | 没有它会怎样 | 所以它实际在做的是 |
|---|---|---|
| 统一编排层 | 十个分析模块就是十个孤岛:用户得自己在五个入口之间跳,还得自己把几份答案拼起来 | 让"跨模块的连续追问"变成一次对话 |
| 取数 Agent | 预设的分析逻辑只能覆盖常见问题,遇到"这次事故很特殊"就查不了,只能回去排队 | 兜住长尾,同时用中间层把"乱查"约束住 |
2.1 编排层:分析天然是追问式的
"这条流水线今天特别慢"
→ 哪个阶段慢? (性能)
→ 这次构建的链路哪一跳卡了? (链路追踪)
→ 是某类任务集中提交导致的吗? (用户行为 / 会话)
→ 要不要加个告警盯着? (告警配置)四个问题属于四个不同模块。 孤岛式产品把这个串联动作交给用户;编排层把它交给系统。所以它真正解决的问题是「一次提问会命中多个异构模块,而这些模块的实现方式还不一样」——不只是"调度"两个字。
编排层交付的三件东西,对应三个问题:
| 解决什么 | 一句话 |
|---|---|
| 怎么接 | 三种不同实现的模块(自主决策 / 状态图 / 单次调用)适配成统一签名 |
| 怎么合 | 一次问涉及多个模块时并行跑,结果合成一份答案(不是三份报告) |
| 怎么扩 | 输出收敛成一套流式事件协议,加新模块不用改前端 |
最后一条是平台化的分水岭:没有统一协议,十个模块就是十个 demo。
2.2 取数 Agent:长尾无法穷举,而临时查数最危险
预设逻辑永远覆盖不住"这次事故很特殊"。但临时查数恰恰是全系统最危险的动作:越权读别的租户、全表扫打爆库、模型幻觉出不存在的字段名。
所以它的设计重心不是"让模型写 SQL",而是 "让模型没机会写错 SQL":
模型只说:要哪个指标 / 按什么维度分 / 什么时间范围
↓(中间表示,不是 SQL)
确定性代码:映射到物理表 → 生成抽象语法树 → 按方言渲染
↓
最后一道:只放读、强制带租户与过滤条件换来三件事,都是能讲成判断的:
- 模型只管"取什么",不管"怎么写" —— 方言差异、字段拼写交给代码;
- 校验点前移 —— 能在编译前判"这个指标不存在""这个维度不能和这个指标组合";
- 权限在最后一道,不靠模型自觉 —— 多租户隔离是查询层的硬约束,不是 prompt 里的叮嘱。
⚠️ 待确认:中间表示这一层是你设计的,还是语义层那边定的?
- 你设计 → 写"我把模型能力约束在选指标/维度/过滤上"
- 别人设计你接入 → 写"按中间表示契约接入:缺参先问、生成后校验、方言与字段由语义层渲染"
两种都成立,但追问方向完全不同。
2.3 三层归属:只为你签字的那层负责
| 层 | 内容 | 你的关系 | 怎么写 |
|---|---|---|---|
| 你签字的 | 统一编排层、取数 Agent | 亲手写 | 越具体越好 |
| 你消费的 | 指标字典、方言渲染、工具执行器 | 接入方 | 写成"平台已有约束",不写成"我设计的" |
| 与你无关的 | 各业务线专属分析逻辑、向量化、监控埋点 | 无 | 一个字都不写 |
句式差别只有一行:
- ❌「设计了 242 个指标的语义层」→ 必须能答"第 137 个指标为什么这么定义"
- ✅「数据侧已把指标沉淀成字典,编排层要求模块产出的不是裸 SQL,而是一个指向这些指标的中间表示」→ 只需答"为什么不让模型直接写 SQL"
三、内部结构(待填)
这一节要回答:一条提问进来,到结果出去,中间到底分成几块、按什么顺序跑。
合格标准:能在白板上画出这条链,且每一块都能说出"它不做会怎样"。画不出就别写"我负责编排层"。
3.1 待填项
| 需要知道 | 从哪来 | 判据 |
|---|---|---|
| 完整调用链(A → B → C) | AI 回报 | 能说出每块的输入输出 |
| 模块总数与分类(几类实现方式、各几个) | AI 回报 | 与"多个专职模块"的说法一致 |
| 每个模块负责的问题类型(一句 10 字内) | AI 回报 | 能对上 §1.2 的场景表 |
| 事件协议的类数与用途 | AI 回报 | 能解释为什么需要分类,而不是一个 text 流 |
| 记忆/会话存在哪、跨模块怎么续 | AI 回报 | 能解释"切模块时上下文为什么不丢" |
3.2 画图要求(面试现场要能画)
用户一句话
→ [路由] 判断该找谁(一个 / 几个)
→ [并行执行] 各模块取数(走中间表示 → 查询)
→ [合成] 冲突/重复怎么处理
→ [流式输出] 统一事件序列这张图必须自己画三遍,画不出来的地方就是 §3.1 还没填的地方。
四、关键决策(为什么这么选)
面试官不关心"你用了什么",只关心"你为什么不用另一个"。这一节是全篇最值钱的部分。
4.1 已经能确定的判断
| 决策 | 备选 | 为什么选它 | 代价(必须主动说) |
|---|---|---|---|
| 不让模型直接产 SQL,先产中间表示 | 模型直接写 SQL | 方言/字段名不可靠;校验点能前移 | 表达能力受限,复杂查询要扩中间表示 |
| 权限放查询层,不放 prompt | 提示词里叮嘱"只查本租户" | 不依赖模型自觉 | 需要维护租户字段映射 |
| 输出统一事件协议 | 每个模块自己定格式 | 加模块不改前端 | 协议演进要考虑兼容 |
4.2 待补决策(模板)
每补一条,按这四格填满;填不满就不算决策,只是描述。
| 决策 | 备选方案 | 为什么选它(当时的约束) | 代价 / 后悔的地方 |
|---|---|---|---|
| ? | ? | ? | ? |
优先补这几条(都是必问题):
- 为什么拆成多个专职模块,而不是一个通用模块?
- 为什么三种编排方式并存,不统一成一种?
- 多个模块结论冲突时为什么这么合并?
- 为什么限制只能读、不能执行代码?(对比:同类系统有的能跑代码)
- 中间层为什么是这一层,不是更上层/更下层?
五、失败与边界(哪里会坏)
这一节是「做过 vs 抄的」分水岭。 讲不出失败细节的人,一看就没接管过线上。
5.1 待填项
| 需要知道 | 合格标准 |
|---|---|
| 非法查询拦在哪一步、怎么回到模型 | 能说出拦截点 + 重试策略 |
| 只读约束的实现在哪、有没有绕过路径 | 能主动承认一条绕过路径(加分项) |
| 某模块失败时:整体失败还是部分返回 | 能说出判定逻辑 |
| 取消后结果晚到怎么处理 | 能说出"为什么不能直接丢弃"这类细节 |
| 参数缺失是猜还是追问 | 能说出追问的成本(多一轮交互) |
| 已知短板(你自己认为最脆的地方) | 能说一个具体的、不体面的坑 |
5.2 必须准备的一句话
「这个系统里我最不放心的是 ___,因为 ___。当时的处理是 ___,如果重做我会 ___。」
这三空填好,比任何架构描述都可信。
六、演进(怎么变成现在这样)★ 最容易被忽略、也最值钱
这一节在我前面所有文档里都是缺的,而它恰恰是只有你能提供、且最难编的部分。
为什么值钱:面试官问「这个系统有什么不足」,答现状是静态的;答演进说明你在时间里做过修正——后者是「有判断力」的直接证据。
填法:三段时间线(不需要精确日期,只要能说清因果):
| 阶段 | 最早的版本长什么样 | 撞到了什么墙 | 改成什么样 |
|---|---|---|---|
| 第一版 | ? | ? | ? |
| 第二版 | ? | ? | ? |
| 现在 | ? | ? | —— |
示例填法(仅示范句式,内容待你替换):
最早的版本是每个分析场景各写一套入口,前端要对接好几套格式。撞的墙是"加一个新场景就要改前端",于是把输出收敛成统一事件;后来发现单模块答不了跨域问题,才加了路由和合成。
注意:AI 只能给你 commit 时间线(骨架),给不了"撞墙"的原因——后者是你脑子里的东西,也是这一节唯一的价值。
七、我个人的贡献(我定的 vs 我接的)
这一节决定面试的可信度。 说"这个模块是我做的"和说"这个目录 800 行里我写了 620 行,路由和合成是我从零建的",差一个量级。
7.1 待填项
| 需要知道 | 从哪来 |
|---|---|
| 编排层里我写的行数占比 | AI 跑 blame |
| 哪些文件是我创建的(从零建) | AI 跑 blame |
| 哪些是接手的、哪些只改了几行 | AI 跑 blame |
| 哪些设计是我拍板的(不只是我写的) | 只有你 |
7.2 边界表述法(三种情况,三种说法)
| 情况 | 怎么说 |
|---|---|
| 我从零建的 | 「这块是我从零设计的,包括 ___ 和 ___」 |
| 我接手改造的 | 「这块原来有,我改的是 ___,因为 ___」 |
| 我只接入的 | 「这块不是我做的,我按它给的契约接入,接入时我处理的是 ___」 |
第三种最容易被低估。 诚实说"我只接入",然后讲清接入时你解决了什么问题,比含糊说"我负责"安全得多,也常常更有内容。
八、填写清单:每节谁能答
| 节 | 谁能答 | 现在有吗 |
|---|---|---|
| 一、存在的理由 | 你(已立) | ✅ |
| 二、责任边界 | 你(已立) | ✅ |
| 三、内部结构 | AI 回报事实 → 你确认 | ❌ |
| 四、关键决策 | 只有你(AI 只给选项) | 🟡 3 条已知,5 条待补 |
| 五、失败与边界 | AI 回报事实 → 你确认 | ❌ |
| 六、演进 | 只有你 | ❌ |
| 七、个人贡献 | AI 跑 blame + 你确认设计归属 | ❌ |
顺序:先要 §3 和 §5 的事实(AI 一批给),再补 §4、§6、§7(只有你能写)。不要反过来——先写判断再找事实,一定会写出没有依据的漂亮话。
九、话术三版本
9.1 给非技术的人(30 秒)
像医院导诊台。你只说"我不舒服",导诊台判断你该去哪个科;如果一个症状涉及几个科,就同时叫几个医生看,最后给你一份统一的诊断意见——而不是三张各说各的纸条。
我们做的是那个导诊台,以及其中一个"什么都能查一下"的科室。
9.2 给技术面试官(60 秒)
这是一个 NL2SQL 的多 Agent 数据分析平台,服务对象是 CodeArts 上做研发和运维的人——他流水线变慢了、构建挂了、告警老误报,想查清原因。
它要解决两件事:一次提问往往得几个不同分析模块一起回答,以及总有问题落在预设逻辑之外。
我负责统一编排层和其中的取数 Agent。编排层把三种不同实现的模块适配成统一签名,做意图路由、多模块并行、结果合成,并把输出收敛成一套流式事件协议,加新模块不用改前端。取数 Agent 走的是"中间表示再编译":不让模型直接产 SQL,它只说取什么指标、按什么维度分,方言和字段交给确定性代码,权限在查询层兜底。
9.3 给朋友(10 秒)
就是让不会写 SQL 的人,用大白话问数据库,背后的 AI 自己决定该查哪张表、该怎么算。
十、数字纪律
| 能写 | 不能写 |
|---|---|
| 结构性事实:三种实现范式、统一事件协议、两条取数路径 | 242 个指标、RECURSION_LIMIT=300、10 个 Agent 这类具体数 |
| "接入多个分析模块"(不给数字) | "我设计了 N 个 Agent" |
| 设计判断(为什么不让模型直接写 SQL) | 任何你无法解释来源的常数 |
理由:自家描述文档标题写"8 个 Agent"、正文实际列 10 个——数字自己对不齐,就更不该写进简历。这条在 fundmate 上已经吃过一次亏("这三个数是量出来的"是编的),不能重犯。
十一、退守顺序(被问住时)
- 先讲业务问题——"这个模块存在是因为某类问题原来要排队三天"
- 再讲设计判断——"所以我不让模型直接写 SQL,而是让它只说取什么"
- 最后才讲实现——"具体是先生成中间表示,再编译成方言 SQL"
反过来(先讲实现)有两个坏处:听者不知道这东西为什么值得做;而你一旦被追问实现细节,就没有退路了。
保命句:这块的具体实现不在我负责的范围里,我接入时按的是 ___ 契约。 —— 比硬编安全一个数量级。
十二、与旧项目二的关系(待你定,先别删文件)
旧项目二(05-data-agent.md)是「模型写 Python、在容器里跑」的执行型 Agent,本平台是「只读出数」的查询型 Agent。两者不重复,但撞同一个岗位叙事(都是"自然语言 → 数据分析")。
| 方案 | 做法 | 代价 |
|---|---|---|
| A 替换(建议) | 本文占项目二位;旧项目二压成一句话进自我评价 | 需要把旧项目二最硬的能力用一句话保住 |
| B 并存 | 两个都写 | 3710 → 4260 字,"三年五个 Agent 平台"密度超标 |
选 A 时必须保留的一句话(删项目可以,删能力不行):
不可信代码与不可逆操作:AST 作用域符号表拦截别名/反射/魔法属性/容器索引等 9 类逃逸写法(37 例单测)+ 容器六项约束兜底 + 审批前硬中断。
这句占用不到 60 字,但「让模型写代码在你机器上跑,怎么防止它把机器搞坏」这类经验的稀缺性远超编排。
