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 由用户选择：

完整架构:
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: 收集输入

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

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: 四维度评估

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. 每次拒绝必须有具体理由 — 不能只说"不适合"，要说明在什么场景下会出什么问题
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      │
      │  内聚模块   │  可插拔接口│
      └───────────┼───────────┘
                  ↓
                单体进程内

判断标准：

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 化 (缺陷分析 + 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 | 接口抽象 | — |

边界条件与异常处理

约束规则

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后结束

关键外部参考资源

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

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

快速启动示例

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

回复：

📋 需求理解

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

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

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