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

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 中。

推荐触发方式

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seed-forge
• Source: seed-forge/harness-ai-kit
• License: Apache-2.0
• Homepage: https://pypi.org/project/harness-ai-kit/

Install and usage instructions live in the source repository linked above.