name: llm-agent-dev metadata: version: 0.1.2 description: 'LLM Agent engineering: pattern selection (12-mode matrix), data simulation, convergence iteration.

Covers intent routing, function calling, ReAct, MCP, prompt chaining, guardrails, evaluation.

'

LLM Agent 全栈工程技能 — Tri-Pillar Protocol v3

三支柱: 设计范式 · 数据模拟 · 收敛迭代 目标: 在任意场景下产出业界一流的 Agent 系统

0) Scope and Boundaries

In scope

• Agent 架构模式选择与组合（12 种模式）
• 意图、对话、上下文工程
• 工具/MCP 集成设计
• Guardrails、安全、HITL
• 记忆/RAG 架构
• 可观测性与追踪
• 性能评估（模型基线 TTFT/TPS + Agent 管道延迟剖析）
• 评估策略与质量门禁
• 合成数据生成（Agent 自主调 LLM API 批量生成）
• 收敛迭代优化（多版本竞争 + LLM-as-Judge 择优）

Out of scope

• 仓库分支治理 / CI/CD 平台策略
• 自主编码编排协议
• 多 Agent 头脑风暴辩论

1) Working Mode — Five Phases

触发后按序执行以下五个阶段。每个阶段有明确的输入/输出契约。

Phase A — 战略锚定 (Strategic Framing)

提取最小决策上下文:

关键输入缺失时声明假设并标注。

Phase B — 模式选择 (Pattern Stack Selection)

从 12 模式矩阵中选择模式栈（非单一标签），产出:

• 推荐栈 + 理由
• 被拒替代方案 + 理由
• 模式组合拓扑

加载对应模式参考:

• 模式矩阵: references/paradigms/pattern-matrix.md
• 决策树: references/paradigms/decision-tree.md
• 独立模式: references/patterns/{nn}-{name}.md

Phase C — 实现合同 (Implementation Contracts)

产出五份合同（可交付给工程团队）:

1. Intent Contract — 意图注册表 + 参数定义
2. State Contract — 会话状态 + 记忆模型
3. Tool Contract — 工具/MCP 定义 + 调用约束
4. Guardrail Contract — 5 层安全架构
5. Handoff Contract — 升级/委托触发条件

横切面参考按需加载:

• references/paradigms/context-engineering.md
• references/paradigms/prompt-patterns.md
• references/paradigms/memory-architecture.md
• references/paradigms/tool-design.md
• references/paradigms/safety-guardrails.md
• references/paradigms/observability.md
• references/paradigms/performance-benchmarking.md

Phase D — 评估与数据 (Evaluation & Data)

产出评估计划 + 数据生成策略:

1. 评估计划

   • 离线测试集分类与覆盖目标
   • 在线 KPI 定义
   • 质量门禁阈值
   • 回滚条件

2. 性能评估计划（详见 performance-benchmarking.md）

   • Layer 1: 模型基线（TTFT/TPS/缓存/上下文长度）
   • Layer 2: Agent 管道逐环节延迟剖析
   • 性能 SLO 与回归门禁

3. 数据模拟生成（Pillar II — 详见 §3）

   • 合成数据集生成策略
   • 分维度 LLM 批量生成
   • 质量验证标准

评估参考:

• references/eval-loop.md
• references/simulation/data-generation.md

Phase E — 收敛迭代 (Convergence Iteration)

产出迭代优化策略（Pillar III — 详见 §4）:

1. 版本竞争方案 — 多版本 prompt/架构并行测试
2. 判定标准 — LLM-as-Judge 评分维度与权重
3. 收敛规则 — 何时停止迭代、择优逻辑
4. 执行计划 — Agent 自主串行/并行调 LLM API 执行

收敛参考:

• references/convergence/iteration-protocol.md

2) Pattern Matrix — 12 Agent Modes

Selection Rules (Deterministic)

1. 延迟 < 1s → 优先 ①② + 缓存，禁用 ⑤⑪⑫
2. 步骤固定 → ④ Workflow 或 ⑨ Prompt Chaining
3. 步骤动态 → ⑤ ReAct 或 ⑪ Orchestrator-Worker
4. 输出需要质量迭代 → ⑫ Evaluator-Optimizer
5. 多领域意图歧义 → ⑥ Router-Expert + ⑧ Handoff
6. 可并行子任务 → ⑩ Parallelizing
7. 仅当单 Agent 无法满足成本/延迟 → 多 Agent (⑥⑧⑪)
8. 需要外部知识 → Agentic RAG (⑤ + 检索工具)

3) Pillar II — 数据模拟生成

目的: 通过 LLM API 批量调用自动生成高质量评估数据集

触发条件

当 Agent 设计完成但缺少评估数据时，主动触发数据模拟生成。

工作流

┌─────────────────────────────────────────────────────────────┐
│                  数据模拟生成 Pipeline                        │
│                                                              │
│  Agent 设计合同 (Phase C)                                    │
│       │                                                      │
│       ▼                                                      │
│  [生成 Task Specs] ← 按维度拆分:                             │
│       │                                                      │
│       ├── T1: happy_path (正常路径, 60%)                     │
│       ├── T2: edge_case (边界情况, 20%)                      │
│       ├── T3: adversarial (对抗测试, 10%)                    │
│       ├── T4: multi_turn (多轮对话, 10%)                     │
│       └── T5: i18n_variant (语言变体, 可选)                   │
│       │                                                      │
│       ▼                                                      │
│  [Agent 自主并行调 LLM API] → 分维度批量生成                  │
│       │                                                      │
│       ▼                                                      │
│  [汇总] → [去重] → [质量检查 LLM-as-Judge] → 数据集         │
└─────────────────────────────────────────────────────────────┘

Task Spec 模板

每个数据生成任务的 Task Spec 格式:

## T{N} · {dimension} 数据生成

- **Engine**: codex 或 claude
- **范围**: 生成 {count} 条评估用例
- **输入**:
  - Agent 意图注册表 (IntentSchema)
  - SkillResponse 协议定义
  - 场景上下文描述
- **交付物**: `eval/generated/{dimension}.json`
- **格式**: EvalCase[] (见 eval-loop.md §评估数据集)
- **质量要求**:
  - [ ] 每条用例有唯一 id
  - [ ] input 真实自然（含口语化/错别字/方言变体）
  - [ ] expected 字段完整（intent + params + responseType）
  - [ ] 无重复/高度相似用例
  - [ ] adversarial 类必须包含注入攻击变体
- **依赖**: 无
- **预估**: S (< 30min)

数据质量验证

生成后使用强模型进行质量检查:

interface DataQualityCheck {
  uniqueness: number;      // 去重后保留比例 ≥ 90%
  naturalness: number;     // LLM 评分 ≥ 4.0/5.0
  completeness: number;    // 字段完整率 100%
  diversity: number;       // 意图覆盖率 ≥ 95%
  adversarialRigor: number; // 对抗强度 ≥ 3.5/5.0
}

执行方式

Agent 自主执行数据生成（技能内自洽，不依赖外部技能）:

1. 串行方式: Agent 逐个维度调用 LLM API 生成数据，每完成一个维度做质量检查
2. 并行方式: Agent 用 Promise.all 并发调多个 LLM API 请求，按维度分组生成
3. 分批方式: 大量数据拆分为多批次，避免 rate limit

// Agent 自主执行数据生成的伪代码
const dimensions = ['happy_path', 'edge_case', 'adversarial', 'multi_turn'];
const results = await Promise.all(
  dimensions.map(dim => generateEvalData(dim, intentSchema, agentContext))
);
const merged = deduplicateAndValidate(results.flat());
await writeFile('eval/dataset.json', JSON.stringify(merged, null, 2));

4) Pillar III — 收敛迭代

目的: 通过多版本并行测试 + LLM-as-Judge 评估实现 Prompt/架构的自动择优收敛

触发条件

当存在以下情况时触发:

• 多个候选 System Prompt 需要择优
• 多种模式组合需要对比
• Prompt 迭代需要量化验证
• 新版本上线前需要回归对比

工作流

┌─────────────────────────────────────────────────────────────┐
│                  收敛迭代 Pipeline                            │
│                                                              │
│  候选版本集合 (V1, V2, V3, ...)                              │
│       │                                                      │
│       ▼                                                      │
│  [生成 Task Specs] ← 每个版本一个测试任务:                    │
│       │                                                      │
│       ├── T1: V1 → 跑全量 eval 数据集 → 输出评分             │
│       ├── T2: V2 → 跑全量 eval 数据集 → 输出评分             │
│       └── T3: V3 → 跑全量 eval 数据集 → 输出评分             │
│       │                                                      │
│       ▼                                                      │
│  [Agent 自主并行运行各版本测试] → 收集评分                    │
│       │                                                      │
│       ▼                                                      │
│  [收集评分结果]                                               │
│       │                                                      │
│       ▼                                                      │
│  [LLM-as-Judge 跨版本比较]                                   │
│       │                                                      │
│       ├── 明确胜出 → 选择最优 → 更新 baseline                │
│       ├── 差异不显著 → 选择成本/延迟更优的                    │
│       └── 全部不达标 → 诊断 → 生成新候选 → 下一轮            │
│       │                                                      │
│       ▼                                                      │
│  [收敛判定] → 最优版本 + 分析报告                            │
└─────────────────────────────────────────────────────────────┘

版本竞争 Task Spec 模板

## T{N} · V{M} 收敛测试

- **Engine**: codex 或 claude（推荐使用高智能模型做评估）
- **范围**: 对版本 V{M} 运行完整评估数据集
- **输入**:
  - V{M} 的 System Prompt / 配置
  - Agent 完整代码（或可运行的分支/commit）
  - 评估数据集 `eval/dataset.json`
- **交付物**: `convergence/results/v{M}-scores.json`
- **评估执行**:
  - Layer 1: 确定性断言（意图准确率等）
  - Layer 2: LLM-as-Judge 多维评分
  - Layer 3: 端到端多轮对话评估（如适用）
- **验收**:
  - [ ] 所有 eval case 有评分结果
  - [ ] 输出格式符合 ConvergenceResult schema
  - [ ] 包含分维度明细 + 总分
- **依赖**: 评估数据集存在
- **预估**: M (30-60min)

收敛判定规则

interface ConvergenceDecision {
  // 评分维度与权重
  dimensions: {
    intentAccuracy: { weight: 0.30, threshold: 0.95 };
    paramExtraction: { weight: 0.15, threshold: 0.90 };
    responseQuality: { weight: 0.25, threshold: 4.0 };
    safety: { weight: 0.15, threshold: 4.5 };
    latency: { weight: 0.15, threshold: 2000 };
  };

  // 收敛条件
  convergenceCriteria: {
    minVersions: 2;              // 至少 2 个版本参与比较
    significanceThreshold: 0.05; // 版本间差异 > 5% 才认为显著
    maxIterations: 5;            // 最多迭代 5 轮
    regressionBuffer: 0.02;      // 允许 2% 的指标波动
  };
}

跨版本比较 Prompt

你是 Agent 系统评估专家。现在有 {N} 个版本的测试结果，请进行跨版本比较。

## 版本评分
{{#each versions}}
### V{{this.id}}
- 意图准确率: {{this.intentAccuracy}}
- 参数提取率: {{this.paramExtraction}}
- 回复质量均分: {{this.responseQuality}}
- 安全性均分: {{this.safety}}
- P95 延迟: {{this.latency}}ms
- 总分: {{this.overall}}
{{/each}}

## 评判标准
1. 加权总分最高的版本为初步推荐
2. 如果总分差异 < 5%，推荐延迟/成本更低的版本
3. 安全性得分低于 4.5 的版本一票否决
4. 意图准确率低于 95% 的版本一票否决

## 输出格式（仅 JSON）
{
  "winner": "V{id}",
  "confidence": 0.92,
  "reasoning": "V2 在意图准确率和回复质量上显著优于其他版本...",
  "improvements": ["V2 的退款意图识别仍有 3% 误分类，建议增加训练样例"],
  "shouldContinue": false,
  "nextAction": "deploy" | "iterate" | "manual_review"
}

5) Output Contract

每次响应生成必须包含以下段落：

A. Recommended Stack

• 主模式栈（有序）
• 适配理由 + 约束匹配
• 被拒替代方案

B. Runtime Architecture

• 请求路径（input → classify → route/plan → act → respond）
• 状态模型（session/slots/workflow/memory）
• 工具调用边界
• 上下文工程策略

C. Safety and Escalation

• 5 层 Guardrail 架构
• 策略违规处理
• HITL 升级触发条件

D. Evaluation Plan

• 离线测试集分类 + 覆盖目标
• 在线 KPI
• 质量门禁阈值
• 回滚条件

E. Performance Baseline

• Layer 1: 模型基线 TTFT/TPS 数据
• Layer 2: Agent 管道逐环节延迟预算
• 性能优化策略与 SLO

F. Data & Iteration Strategy

• 数据模拟生成计划（若需要）
• 收敛迭代计划（若需要）
• Agent 自主执行步骤（LLM API 调用策略）

缺少任何段落 → 响应不完整。

6) Scenario Router

场景明确时加载对应蓝图:

横切面参考:

7) Reference Loading Policy

保持上下文精简:

1. 仅加载选定栈/场景所需文件
2. 避免批量加载所有参考
3. 优先: 模式文件 + 1 个横切面文件
4. 仅在受阻时加载额外文件
5. 数据模拟/收敛迭代参考仅在触发时加载

8) Delivery Quality Bar

交付前检查:

• 架构内部一致，无自相矛盾
• 延迟/成本/安全 tradeoff 显式标注
• 合同可被工程团队直接实施
• 评估计划可量化、可自动化
• 性能基线已建立或有明确的测量计划
• 数据模拟方案可由 Agent 自主执行（内部自洽）
• 收敛迭代方案有明确的停止条件

不通过 → 修订后再返回。