---
name: devlab-ai-agent-engineering
description: AI Agent / LLM 应用工程化方法论。指导如何把一个 AI 智能体应用"拆成哪几块 + 如何避免重走老路"：分层管道、规则优先+LLM兜底、多模型触点路由、Prompt 统一治理、超时/缓存/降级、评测闭环、多厂商 SDK 适配。Triggers on "AI agent 架构", "LLM 应用怎么拆", "规则还是大模型", "prompt 管理", "agent 工程化", "ai agent methodology", "llm app architecture".
---

# devlab-ai-agent-engineering

## 用途

把"要做一个 AI 智能体应用"从零散试错升级为**可复用的工程化方法论**。回答两类问题：

1. **拆分**：一个 AI Agent 应用应该拆成哪几层/哪几块？各层职责与边界是什么？
2. **避坑**：LLM/Agent 工程里反复踩的坑，如何在设计期就规避（不是给某个具体 bug 的补丁，而是给方法论原则）。

> 本技能是**方法论层**（讲原则与结构），具体某个技术栈的落地细节交由 AI Agent 结合项目给出选项/建议；各业务领域的落地范例见 `references/`。

## 适用场景

- 新建 NL2SQL / Text2SQL、RPA、语音数字人、RAG 问答等任意 LLM 驱动应用，需要先定架构。
- 现有 Agent 应用"越改越乱"、规则与 LLM 边界混乱、Prompt 散落、模型成本失控，需要重新梳理分层。
- 评审一个 AI 应用设计方案是否踩了已知的结构性坑。

## 不适用场景

- 纯粹的模型微调/训练（本技能聚焦**应用工程**，非模型训练）。
- 具体某框架的 API 用法（交由 `-usage` 类技能或 AI 现场给建议）。
- 非 AI 的普通后端/前端架构（用对应 devlab-srv-* / devlab-web-* 技能）。

## 输入

- 业务目标与输入/输出形态（自然语言查询？桌面操作？语音对话？）。
- 现有代码/架构现状（可选，用于重构场景）。
- 约束：延迟预算、成本预算、可解释性/审计要求、私有化程度。

## 输出

- Agent 分层架构方案（各层职责 + 边界 + 数据流）。
- 规则 vs LLM 的分工决策 + 兜底/超时/缓存策略。
- 多模型触点路由表（每个触点的 primary/fallback 模型与选型理由）。
- Prompt 治理方案（统一注册/版本/复用）。
- 结构性风险清单（对照"已知坑方法论"）。

## 核心方法论

### 1. 分层管道（Layered Pipeline）
把 Agent 拆成**单向、可独立测试**的阶段，每阶段有明确输入/输出契约：

```
输入理解 → 信息抽取 → 策略决策 → 执行/编译 → 结果验证 → 输出
  │            │           │          │           │
意图识别     槽位/条件    按类型选策略  调用/生成   正确性校验
知识增强检索  metric抽取   strategy-    (SQL/动作/  (schema/
             实体消歧      per-type      TTS)        断言)
```

- **中间表示解耦**：在"理解"与"执行"之间引入中间表示（如 DSL），让 NLP 层与工程实现层解耦，便于多目标复用（如一份 DSL 编译到多种 SQL 方言）。
- **按类型分策略**：先做**请求分类**（如明细/指标/排名/对比），再路由到 strategy-per-type，避免一个巨型分支处理所有情况。
- **每层可独立评测**：每个阶段都能单独喂输入、断言输出，是后续评测闭环的基础。

### 2. 规则优先 + LLM 兜底（Hybrid）
- 默认 **rule_first**：规则/检索能确定的走确定性路径（快、稳、可解释、零成本）。
- 规则**置信度低于阈值**或产出不足时，才触发 LLM 兜底（慢路径）。
- 策略可配：`rule_first` / `llm_first` / `parallel` / `adaptive`。
- ⚠️ **兜底触发阈值必须语义正确**：典型坑是"最小条件数=0"导致"0 条件也算充足"→ 兜底永不触发。阈值要表达"何时判定规则不足"，而非形式化默认值。

### 3. 多模型触点路由（Touchpoint Routing）
- 每个 LLM 触点独立配置 `primary_model` + `fallback_models`。
- **按难度分配模型**：简单触点用便宜/快模型，复杂触点（如复杂条件抽取）用强模型。
- 路由集中在配置，不在代码里散落硬编码模型名。

### 4. Prompt 统一注册治理
- 所有 prompt 集中注册管理（统一命名/版本/复用），**禁止散落在各处字符串**。
- 新增触点的 prompt 必须遵循已有注册规范与配置结构，保持一致性。

### 5. 韧性三件套：超时 / 缓存 / 降级
- **超时**：LLM 调用必设超时；超时值要匹配真实耗时（典型坑：默认 5s 太短，返回 200 但未完成即 timeout）。
- **缓存**：可缓存的触点开启缓存，降本增稳。
- **降级**：LLM 不可用/超时时有确定性兜底或明确的失败语义，不能静默丢结果。

### 6. 多厂商 SDK 适配器
- 用适配器隔离厂商差异（ASR/TTS/渲染/LLM 各厂商 SDK），新增厂商=新增一个 adapter，不改上层。
- 上层只依赖统一接口，"新增一个 tech 模式"成为可插拔动作。

### 7. 评测闭环（详见 `devlab-eval-driven-agent`）
- 从第一天就建评测集 + 自动评测脚本，改动后可回归；本技能负责"架构可被评测"，评测体系本身见 eval 技能。

## 工作流

```
Phase 1: 目标与约束澄清
  → 明确输入/输出形态、延迟/成本/可解释性/私有化约束
  → ⛔ Gate G1：形态与约束是否清晰

Phase 2: 分层设计
  → 套用"分层管道"，定义每层职责/边界/契约 + 是否需要中间表示
  → 定请求分类维度与 strategy-per-type
  → ⛔ Gate G2：分层与契约是否闭合

Phase 3: 规则/LLM 分工 + 触点路由
  → 逐触点决策 rule/LLM、阈值、超时、缓存、降级
  → 产出多模型路由表 + Prompt 治理方案
  → ⛔ Gate G3：混合策略与路由确认

Phase 4: 结构性风险自查
  → 对照 references/ 各域已知坑（方法论化）逐条核对
  → 产出风险清单 + 规避设计

Phase 5: 交接
  → 输出架构方案；实施交 code-developer / devlab-*，评测交 devlab-eval-driven-agent
```

## 领域 reference（各域落地范例）

| Reference | 领域 | 用途 |
|-----------|------|------|
| `references/REFERENCE-NL2SQL.md` | NL2SQL / Text2SQL | 分层管道、字段检索、条件抽取、多表推理、SQL 正确性的落地范例与坑 |
| `references/REFERENCE-RPA.md` | 桌面 RPA / GUI 自动化 | 感知-决策-执行环、DPI/焦点/剪贴板/去重等 GUI 自动化坑 |
| `references/REFERENCE-DIGITALHUMAN.md` | 语音数字人前端 | ASR/TTS/VAD 时序、音视频同步、打断、浏览器音频策略坑 |

> reference 只沉淀"方法论原则 + 典型坑规避"，不绑死具体版本/厂商；实操由 AI 结合项目给选项。

## 与其他 devlab-* Skill 的关系

| Skill | 关系 | 说明 |
|-------|------|------|
| `devlab-spec-driven-dev` | **上游** | 用 spec 驱动方式推进本方法论产出的架构落地 |
| `devlab-eval-driven-agent` | **并行** | 提供评测闭环，验证本架构的正确率/回归 |
| `devlab-srv-reliability-ops` | **下游** | 运行期故障只读诊断（Observe→Diagnose→Fix→Re-verify） |
| `devlab-solution-architecture` | **邻接** | 多工具组合选型时引用 |
| `devlab-middleware-expert` | **知识源** | 数据源/中间件连接细节 |

## 约束

- 只讲方法论与结构决策，**不硬编码具体框架 API、模型名、URL、端口、凭据**（这些是配置或现场决策）。
- 分层不超过合理粒度，避免过度设计；"能用规则确定的不要交给 LLM"。
- 每条"坑"必须写成**可迁移的方法论原则**（去掉项目/文件/变量名后仍成立），而非一次性 bug 修复。
- sensitive 配置（密钥等）不得出现在本技能或 references 中。

## 推荐触发方式

```text
帮我设计这个 AI agent 应用的分层架构，规则和大模型怎么分工？
```

```text
用 devlab-ai-agent-engineering 评审下我这个 NL2SQL 方案有没有结构性坑
```