devlab-ai-agent-engineering

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 不可用/超时时有确定性兜底或明确的失败语义，不能静默丢结果。