seed-forge devlab-ai-agent-engineering
用途
把"要做一个 AI 智能体应用"从零散试错升级为可复用的工程化方法论。回答两类问题：
- 拆分：一个 AI Agent 应用应该拆成哪几层/哪几块？各层职责与边界是什么？
- 避坑：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 | 关系 | 说明 |
|---|---|---|
| SDD framework | 邻接 | 用 requirements/design/tasks 推进本方法论产出的架构落地 |
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 方案有没有结构性坑