# Agent Architecture Designer

> Design production-grade Agent-native architecture. Analyzes existing system, judges if Agent-ification helps, designs full tech stack (framework/model/tools/memory/safety/orchestration/observability) with detailed rejection rationale per choice, produces layered architecture with module boundaries (Service/Module/Plugin/SPI), catalogs mature OSS libraries, and adds completeness (testing/CI-CD/cost/resilience/compliance/migration/ops). Triggers: 技术方案, 技术栈, 架构设计, agent架构, Agent技术选型, architecture design, tech stack, 系统重构, architecture review.

- Skill: `oliverpanda/agent-architecture-designer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oliverpanda/agent-architecture-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oliverpanda/agent-architecture-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: OliverPanda (https://skillmd.com/u/oliverpanda)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oliverpanda/agent-architecture-designer

---


# Agent 架构设计师

为任意软件系统设计生产级的 Agent-Native 技术架构。核心理念：**每个决策都有可追溯的理由，每个被拒绝的方案都有明确的原因，架构文档可交付给工程团队直接实施。**

---

## 设计哲学

> "Architecture is the decisions you wish you could get right early in a project." — Ralph Johnson

本 skill 遵循四条原则：
1. **决策可追溯** — 每个选型附带「为什么选 A」和「为什么不选 B/C/D」，数据支撑而非主观偏好
2. **完备性优先** — 不只画架构图，必须覆盖测试/CI-CD/成本/韧性/合规/迁移/运维七个维度
3. **模块边界清晰** — 每个组件明确归属于 Service(独立部署) / Module(内聚模块) / Plugin(外挂) / SPI(可插拔)
4. **库即代码** — 每个复杂模块推荐具体的成熟开源库(含版本号、成熟度评级、备选)

---

## 工作流总览

本 skill 支持两种模式，在 Phase 1 由用户选择：

| 模式 | 适用场景 | 输出 |
|------|---------|------|
| **完整架构** (默认) | 系统重构、技术评审、正式立项 | 完整架构文档(24章) + PRD更新 + 对照表 |
| **快速评估** (轻量) | 快速判断、技术选型咨询、原型阶段 | Phase 1-3 精简输出(技术栈选型+拒绝理由+一句话建议) |

```
完整架构:
Phase 1: 需求理解    →  阅读输入文档 → 识别当前架构模式 → 选择模式 → **唯一暂停点**
Phase 2: 架构判断    →  Agent-ification 必要性分析 → 直接进 Phase 3
Phase 3: 技术栈设计  →  逐维度选型 + 拒绝理由 → [快速模式在此结束] → 直接进 Phase 4
Phase 4: 分层设计    →  模块边界四象限 + 部署拓扑 → 直接进 Phase 5
Phase 5: 完备性补充  →  测试/CI-CD/成本/韧性/合规/迁移/运维 → 直接进 Phase 6
Phase 6: 文档整理    →  ⚠️写入前确认 → 输出架构文档 + 更新PRD + 生成对照表
```

**Phase 1 是唯一暂停点**。Phase 6 写入旧文档前有二次确认（安全关卡）。

---

## Phase 1: 需求理解

### Step 1: 收集输入

识别用户提供的所有输入材料：

| 输入类型 | 典型文件 | 提取信息 |
|---------|---------|---------|
| PPT/演示文稿 | `*.pptx`, PPT脚本 Markdown | 业务场景、目标用户、核心功能 |
| 知识大纲 | 知识大纲 Markdown | 领域知识结构 |
| 案例集 | 案例 Markdown | 真实使用场景、痛点 |
| PRD | PRD Markdown | 功能需求、现有技术栈、API 定义 |
| 架构文档 | 架构设计 Markdown | 当前架构模式、组件关系、技术选型 |
| 代码仓库 | `src/` 目录 | 实际实现细节 |

### Step 2: 识别当前架构

从文档中提取当前架构的关键特征：

```
当前架构诊断清单:
☐ 架构范式: Pipeline? Rules Engine? Microservices? Monolith? Event-Driven?
☐ AI 角色: 核心决策者? 末位兜底? 辅助工具? 未使用?
☐ 状态管理: 有状态? 无状态? 如何持久化?
☐ 扩展性: 如何添加新功能? 需要改多少地方?
☐ 安全边界: 安全策略在哪里执行? 是否统一?
☐ 可观测性: 是否可追踪单次请求的完整链路?
```

### Step 3: 选择模式 + 确认理解 (唯一暂停点)

先让用户选择完整架构还是快速评估，再确认理解：

```
📋 需求确认

| 维度 | 我的理解 |
|------|---------|
| 系统定位 | {一句话描述} |
| 当前架构 | {架构范式 + 核心缺陷(如有)} |
| 核心痛点 | {当前最主要的问题} |

⚡ 请选择输出深度：
  A. 完整架构 — 全量24章架构文档+PRD更新+对照表（适合正式评审）
  B. 快速评估 — Phase 1-3精简输出：技术栈选型+拒绝理由+一句话建议（适合快速决策）

基于以上理解，我将进入 Phase 2。
有需要纠正的地方请告诉我。
```

---

## Phase 2: 架构判断 — Agent-ification 必要性

### Step 1: 四维度评估

| 评估维度 | 判断标准 | Agent 化收益 |
|---------|---------|:--:|
| **复合意图处理** | 当前系统能否处理「同时包含 A+B+C」的复合场景? | 规则引擎需 N² 条规则，Agent 自主分解 |
| **上下文连续性** | 当前系统是否有状态? 能否追踪多轮交互的上下文? | 规则引擎无状态，Agent 有 checkpoint |
| **行为不可预测性** | 当前行为模式是否固定? 是否容易被反作弊检测? | 确定性系统=可预测=可检测 |
| **策略灵活性** | 当前决策能否根据实时数据动态调整? | 预设策略 vs Agent 自主推理 |

### Step 2: 输出判断

```
🔍 Agent-ification 必要性分析

✅ / ⚠️ / ❌ 建议 {Agent 化 / 暂缓 / 不需要} — 原因:
  1. {具体缺陷1 — 附真实场景举例}
  2. {具体缺陷2 — 附真实场景举例}
  3. {具体缺陷3 — 附真实场景举例}

当前架构根本矛盾: {一句话总结}
→ [快速模式在此输出结论后结束]
→ [完整模式自动进入 Phase 3 技术栈设计...]
```

### 快速模式结束模板

如果用户选了快速评估，Phase 2 输出判断后不进入 Phase 3，直接给轻量结论：

```
⚡ 快速评估结论

**建议方案**:
| 维度 | 推荐 | 一句话理由 |
|------|------|-----------|
| Agent 框架 | {X} | {理由} |
| 模型 | {X} | {理由} |
| 工具协议 | {X} | {理由} |
| 记忆 | {X} | {理由} |
| 安全 | {X} | {理由} |

**关键风险**: {1-2个最大的技术风险}
**下一步**: {一句话行动建议}
**如需完整架构文档**: 回复"展开完整架构"即可
```

---

## Phase 3: 技术栈设计

这是本 skill 的核心 —— 逐个维度做技术选型，**每个选型必须附带「为什么不选其他方案」**。

### 必选维度（9个）

每个维度按以下模板输出：

```
### {维度名称}

**选定**: {方案名}
**一句话理由**: {为什么}

**候选方案对比**:
| 维度 | 选定方案 | 候选A | 候选B | 候选C |
|------|:------:|:----:|:----:|:----:|
| {关键指标1} | ✅/⚠️/❌ | ... | ... | ... |
| ... | | | | |

**为什么不选其他方案**:

✗ **{候选A}** — {最关键的1个拒绝原因，附数据或场景}
✗ **{候选B}** — {最关键的1个拒绝原因}
✗ **{候选C}** — {最关键的1个拒绝原因}
```

### 9 个必选维度

| # | 维度 | 关键考量 | 典型选型 |
|---|------|---------|---------|
| 1 | **Agent 框架** | StateGraph? Checkpoint? Human-in-the-Loop? | LangGraph / CrewAI / AutoGen / Dify |
| 2 | **模型层** | 是否需要分级路由? Tool-use 准确率? 中文质量? | Claude Sonnet / GPT-4o / qwen / DeepSeek |
| 3 | **工具协议** | 标准化? 模型无关? 动态发现? | MCP / OpenAI FC / A2A / 自研 |
| 4 | **记忆系统** | 向量+关系混合查询? 运维复杂度? | PG+pgvector / Chroma / Milvus / Redis-only |
| 5 | **安全约束** | 语义级检测? 延迟要求? 假阳性率? | Guardrails-AI / NeMo / 纯规则 / LLM-as-Judge |
| 6 | **Agent 编排** | 条件路由? 循环支持? 流式输出? | LangGraph StateGraph / Temporal / Celery Canvas |
| 7 | **可观测性** | LLM 链路追踪? 自部署? 国内可用? | LangFuse / LangSmith / 纯 Prometheus |
| 8 | **任务队列** | 复杂工作流? Windows 兼容? 性能? | Celery / Dramatiq / RQ |
| 9 | **浏览器自动化** | 反检测生态? Async 原生? | Playwright / Selenium / Puppeteer |

### 选型原则

1. **每次拒绝必须有具体理由** — 不能只说"不适合"，要说明在什么场景下会出什么问题
2. **数据优先** — 有 benchmark 数据就引 benchmark (如 BFCL 的 Tool-use 准确率)
3. **场景约束** — 选型理由要绑定具体场景 (如「对于需要黄金5分钟回复的客服场景，X 的延迟不可接受」)

---

## Phase 4: 分层架构与模块边界设计

### Step 1: 确定分层

```
标准分层 (从上到下):
┌──────────────┐
│   接入层      │  HTTP/WS 路由、认证鉴权
├──────────────┤
│   Agent 编排层│  图编排、状态管理、推理决策
├──────────────┤
│   工具层      │  MCP Protocol, 标准化 Tool
├──────────────┤
│   安全约束层  │  硬约束(正则+频率) + 软约束(语义)
├──────────────┤
│   记忆层      │  短期(Redis) + 长期(pgvector)
├──────────────┤
│   基础设施层  │  PG/Redis/Celery/Playwright/LiteLLM
├──────────────┤
│   可观测性    │  LLM 追踪 + 系统监控 (横切)
└──────────────┘
```

### Step 2: 模块边界四象限

将每个组件归入四个象限之一：

```
                独立部署
                  ↑
      ┌───────────┼───────────┐
      │  Service   │  Plugin   │
      │  独立服务   │  外挂插件  │
进程内─┼───────────┼───────────┼─→ 进程外
      │  Module    │  SPI      │
      │  内聚模块   │  可插拔接口│
      └───────────┼───────────┘
                  ↓
                单体进程内
```

**判断标准**：

| 象限 | 判断条件 |
|------|---------|
| **Service** | 有独立扩缩需求 / 独立故障域 / 独立团队 ownership |
| **Module** | 与核心流程强耦合 / 拆出去增加延迟 / 同进程目录级隔离 |
| **Plugin** | 独立进程但非核心 / 可选部署 / 失败不影响核心 |
| **SPI** | 有多个可替换实现 / 需在不改代码的情况下切换 |

### Step 3: 输出边界决策表 + 部署拓扑图

参见下方输出模板。

---

## Phase 5: 完备性补充

设计完成不等于架构完成。必须补充以下 7 个维度。每项输出应达到的深度：

### 5.1 测试策略

**目的**: Agent 不能用传统 assertEquals 测试,需要新的测试方法论。

最少产出:
- 四层测试金字塔 (Unit → Component → E2E → A/B),每层说明测什么、用什么工具
- 统计性断言示例 (如「意图分类准确率 > 95%」「高风险 False Negative = 0」)
- 对话剧本格式 (YAML: scenario → turns → assertions)
- Eval Gate 设计 (CI 中阻塞性检查: 安全评分/准确性/自然度)

### 5.2 Prompt 管理

**目的**: Prompt 是 Agent 的「源代码」,必须像代码一样管理。

最少产出:
- 目录结构 (prompts/{agent}/system_prompt_v{N}.txt + CHANGELOG.md)
- 变更流水线 (Review → Eval Suite → Staging 1% → Canary 10% → Full)
- A/B 分流方案 (一致性哈希,同 account 始终同版本)
- 回滚方式 (切换 prompt version, 5 分钟内生效)

### 5.3 CI/CD 流水线

**目的**: 不同类型的变更(Prompt/Tool/Graph/Infra)风险不同,需要不同的部署策略。

最少产出:
- 变更检测→策略分派表 (4种变更类型×部署策略)
- Feature Flag 清单 (含默认值和回滚方式)
- 部署策略矩阵 (Stage观察/Canary比例/全量观察/回滚方式)

### 5.4 Token 经济与成本

**目的**: Agent 的主要运营成本不是服务器,是 LLM API 调用。

最少产出:
- 逐场景成本模型 (简单/复杂/高风险,各自 input/output token + 单价 = 单次成本)
- 月度成本估算 (日活 × 日均对话 × 单次成本)
- 三级预算管控 (账号级→系统级→异常检测)
- 成本优化策略表 (语义缓存/压缩/蒸馏/夜间降级,各标注预期节省%)

### 5.5 韧性工程

**目的**: Agent 在 LLM 超时/Tool 失败/平台限流时不能「死掉」。

最少产出:
- 多层熔断机制 (LLM API / Tool 执行 / Agent 自身,各独立熔断)
- 优雅降级链路 (Level 0→5,从最优到最差,每级标注损失)
- 幂等性代码示例 (Redis SETNX 防止重复执行)
- 消息去重方案

### 5.6 数据合规

**目的**: 处理真实用户的聊天/订单/地址数据,必须满足《个人信息保护法》。

最少产出:
- 数据分级表 (L0公开→L3最高敏感,每级标注存储方式和保护要求)
- 关键合规点对照 (最小必要/知情同意/删除权/可携带/跨境/泄露上报)
- 审计日志表 DDL (Append-Only, REVOKE DELETE+UPDATE)

### 5.7 迁移策略 + 运维手册

**目的**: 从旧系统到 Agent 必须分阶段、可回滚。上线后必须有人值班。

最少产出:
- 四阶段迁移路线 (Shadow→试点→灰度→全量,每阶段有退出条件)
- 回滚 SOP (触发条件 + 5分钟内操作步骤)
- 告警分级 (P0-P3,含条件+响应时间+通知范围)
- 至少 3 个关键 Runbook (越狱/LLM全部宕机/Token暴增)

---

## Phase 6: 文档整理与输出

### ⚠️ 安全关卡 (写入前确认)

在覆盖/创建任何文件之前，必须先展示将要执行的操作并获得确认：

```
📝 即将执行以下写入操作:

| # | 操作 | 文件 | 风险 |
|---|------|------|:--:|
| 1 | 新建 | {系统名}-Agent架构设计.md | 🟢 低 |
| 2 | 修改 | {系统名}-PRD.md | 🟡 中 |
| 3 | 新建 | 技术栈变更对照表.md | 🟢 低 |
| 4 | 修改 | {旧架构文档}(添加弃用声明) | 🟡 中 |

确认以上操作？(回复 "确认" 或 "跳过某文件")
```

**绝不静默覆盖已有文件。** 如果目标文件已存在，必须额外提示「文件已存在，将覆盖」。

### 输出文件

| # | 文件 | 内容 |
|---|------|------|
| 1 | `{系统名}-Agent架构设计.md` | 完整的 Agent 架构设计 (Phase 2-5 全部内容) |
| 2 | `{系统名}-PRD.md` (更新) | 更新 PRD 的技术选型、模块概述、依赖关系，增加文档导航 |
| 3 | `技术栈变更对照表.md` | 旧 vs 新 技术栈一页速查 + 选型理由速查 |
| 4 | 旧架构文档 (如有) | 顶部添加弃用声明 + 指向新文档的链接 |

### 架构文档的章节结构

```
1. 为什么必须 Agent 化 (缺陷分析 + Agent 优势)
2. 架构决策总览 (核心决策一览表)
3-9. 技术栈选型 (9维度 × 候选对比 × 拒绝理由)
10. 基础设施层 (保留/升级/替换/新增)
11. 分层架构与模块边界 (四象限 + 部署拓扑 + 通信契约)
12. 核心 Agent 详细设计 (Chat/Ops/Content + StateGraph 图)
13. Agent 安全架构 (三层防线 + 行为拟人化)
14. 部署与运维 (Docker Compose + K8s 扩缩策略)
15. 技术风险与缓解
16. ADR 决策记录
17. 测试策略
18. Prompt 管理
19. CI/CD
20. Token 经济
21. 韧性工程
22. 数据合规
23. 迁移策略
24. 运维手册
附录B: 全模块成熟开源库对照表 (16类别 × 100+ 库)
```

### PRD 更新清单

```
☐ 文档头: 版本号升级 + 关联文档链接
☐ 新增: 文档导航表 (读者在不同文档间导航)
☐ §1.4 技术选型: 更新为 Agent-Native 技术栈
☐ §2 系统架构: 增加 PRD模块→Agent组件 映射表
☐ 受影响的模块概述: 增加 🏗️ 实现架构说明 (M2→Chat Agent, M6→Ops Agent, M8→Content Agent, M10→Guardrails)
☐ 受影响的模块依赖: 增加 "Agent 实现" 行
```

---

## 输出交付物模板

### 架构决策总览表示例

```
| 决策维度 | 选定方案 | 一句话理由 |
|---------|---------|-----------|
| Agent 框架 | LangGraph | 原生StateGraph+Checkpoint+HITL,三者缺一不可 |
| 主模型 | Claude Sonnet (复杂) + qwen-turbo (简单) | 分级路由,70%请求<0.3s |
| 工具协议 | MCP | 标准化tool schema,模型无关,动态发现 |
| ... | ... | ... |
```

### 选型对比表示例 (每个维度)

```
| 维度 | 选定方案 | 候选A | 候选B | 候选C |
|------|:------:|:----:|:----:|:----:|
| 有状态图编排 | ✅ StateGraph原生 | ❌ 线性Pipeline | ⚠️ 有限 | ⚠️ 可视化 |
| Checkpoint | ✅ PG内置 | ❌ | ❌ | ❌ |
| Human-in-the-Loop | ✅ interrupt() | ❌ | ⚠️ 自实现 | ❌ |
| 生产就绪度 | ✅ LangSmith生态 | ⚠️ 早期 | ⚠️ 研究项目 | ❌ SaaS锁定 |

**为什么不选其他方案**:
✗ **CrewAI** — 无状态管理,多轮对话状态丢失;砍价场景Step3 LLM失败需从Step1重跑
✗ **AutoGen** — Agent互相"聊天"增加延迟(2-3x),客服场景不可接受
✗ **Dify/Coze** — 无法深度集成Playwright/WebSocket等基础设施
```

### 模块边界决策表示例

```
| 组件 | 边界类型 | 部署模式 | 扩缩策略 |
|------|:------:|------|------|
| agent-service | Service | 独立Pod,HPA | 并发图执行数+CPU |
| mcp-server | Service | 独立Pod,HPA | QPS |
| Chat Agent | Module | agent-service内 | — |
| Playwright Browser | Plugin | Sidecar容器 | 固定池 |
| LLMProvider | SPI | 接口抽象 | — |
```

---

## 边界条件与异常处理

| 场景 | 处理方式 |
|------|---------|
| 用户只提供了 PPT/PRD 没有旧架构文档 | 从 PRD 的功能描述和 API 设计中推断当前架构模式；标注「基于文档推断，可能与实际有偏差」 |
| 用户跳过了 Phase 1 确认 | 不跳过，回复：「为了保证架构质量，我需要先确认对系统的理解是否准确」 |
| 某维度没有明显的「最佳选择」 | 列出两个可行方案 + 各自的 tradeoff，标注「⚠️ 需人工决策」，继续推进其他维度 |
| 系统规模太小(单服务/个人项目) | 自动推荐快速评估模式；如需完整架构，简化 Phase 4(不画 K8s 拓扑) |
| 用户已有偏好的技术栈 | 评估偏好方案是否满足架构需求；如果不满足，给出数据驱动的反对理由；如果满足，尊重偏好并在文档中记录 |
| 生成内容过长(>3000行) | 分文件输出：核心架构文档 + 附录独立文件；在核心文档中写「详见附录X」 |
| 用户系统已经是 Agent-Native | 告知「当前已是 Agent 架构」→ 转为架构审查/优化模式，跳过 Phase 2 判断 |
| LLM API 不可用(国内网络) | 技术栈默认推荐国内可用的模型(通义千问)；标注 Claude Sonnet 需要 API 代理 |
| 目标文件已存在 | Phase 6 安全关卡中额外提示「⚠️ 文件已存在，将覆盖」，必须用户确认后才写入 |
| 用户要求只改某个模块 | 将 Phase 3-5 限定到该模块范围，但仍然输出该模块的完整架构建议 |

---

## 约束规则

1. **拒绝理由必须具体** — 每个「不选 X」必须有场景+数据支撑，不接受「不适合」「生态差」等模糊理由
2. **分级路由默认推荐** — Agent 系统默认走分级路由(简单→轻量模型,复杂→强模型)，除非用户明确要求统一模型
3. **安全双层必含** — 硬约束(正则+频率,100%召回) + 软约束(语义,低假阳性) 缺一不可
4. **日志不可删** — 审计日志表必须 Append-Only，架构文档必须写明
5. **废弃标注** — 更新旧架构文档时必须在顶部添加弃用声明，保留历史参考
6. **库带版本号** — 推荐的每个开源库必须写明最低版本要求
7. **成本模型必含** — Token 经济的成本估算必须给具体数字，不能用「较低」「可控」等定性词
8. **回滚方案必含** — 迁移策略必须有明确的回滚触发条件和操作 SOP
9. **一口气到底** — Phase 1 确认后，Phase 2→6 自动连续执行。Phase 6 写入前有安全关卡。快速模式在Phase 3后结束

---

## 关键外部参考资源

在做技术选型决策时，优先引用以下权威数据源：

| 决策维度 | 参考资源 | 用途 |
|---------|---------|------|
| Tool-use 准确率 | **BFCL** (Berkeley Function Calling Leaderboard) | 比较 Claude/GPT/qwen 的 tool-use 能力 |
| 模型中文质量 | **SuperCLUE** / **C-Eval** | 中文理解和生成能力排名 |
| Agent 框架对比 | **LangGraph** / **CrewAI** / **AutoGen** GitHub stars + 生产案例 | 框架成熟度和社区活跃度 |
| MCP 协议 | **modelcontextprotocol.io** (Anthropic 官方) | MCP 规范、SDK、社区 Server 列表 |
| LLM 成本 | **LiteLLM** cost tracker / 各厂商定价页 | 实时 API 价格对比 |
| 向量数据库 | **ann-benchmarks.com** | pgvector vs Milvus vs Chroma 性能对比 |
| 反检测 | **playwright-stealth** / **nodriver** GitHub | 浏览器指纹隐藏最新进展 |
| 国内合规 | **《个人信息保护法》** / **《数据安全法》** | 数据分类、存储、删除要求 |

选型时引用以上数据源的具体数字，而非主观感受。例如：「BFCL 2025: Claude Sonnet tool-use AST 匹配 93.2% vs GPT-4o 90.1%」。

---

## 快速启动示例

用户说：「帮我看看这个系统的技术架构，能不能 Agent 化」

回复：

```
📋 需求理解

我注意到你提到了 {系统名/文件}。在开始架构分析之前，请确认以下几点：

| 维度 | 待确认 |
|------|--------|
| 系统范围 | 是完整分析还是聚焦某个模块(如客服/运营/内容)? |
| 现有文档 | 是否有 PRD/架构文档/代码仓库可以阅读? |
| 关注重点 | 更关注技术选型? 还是部署/安全/成本? |
| 团队背景 | Python? Node.js? 对 LangGraph/LLM 的熟悉度? |

另外，我会读取你提供的所有文档进行深度分析。
```