技术架构设计
Agent MCP Container 从前端到 LLM 的完整技术架构
一、问题和背景
这套技术架构重点要解决两个问题：
- 技能复用——每个 SKILL.md 定义的不只是一段 Prompt，而是一个完整的技能流程（阶段划分、输入约束、输出规格、知识检索策略）。同一个技能可以被不同的 AI Agent 工具调用，也可以被同一个工具的不同项目复用。MCP 协议屏蔽了客户端差异，让技能"写一次，到处用"。
- 技能组织资产化——随着 BA/SA/PM 三个 Agent（未来会持续扩充更多Agent） 的 15 项技能逐步成熟，它们不再只是"AI 对话的辅助"，而是形成了一套可管理的知识资产。新的项目启动时，可以直接加载已有技能包，而不是每次从零写 Prompt。技能的版本管理、热加载、按 Agent 类型隔离，使得这套资产可以持续积累和演进。
二、整体架构
Agent MCP Container 是一个基于 MCP（Model Context Protocol）协议的智能代理容器系统。它将 BA（业务分析师）、SA（系统架构师）、PM（项目经理）三大角色的专家能力封装为独立的 MCP Server，通过 Streamable HTTP 传输协议对外提供工具（Tools）与资源（Resources）。
系统采用"共享模块 + 多 Agent 服务 + 技能定义"的分层架构。每个 Agent 独立进程、独立端口，通过 Nginx 反向代理统一对外暴露。客户端（OpenClaw / Cursor / Qoder 等 AI Agent 工具）通过 MCP 协议接入，发起技能调用。
graph TB
subgraph FRONT["客户端"]
C["AI Agent 工具
OpenClaw / Cursor / Qoder
（MCP Streamable HTTP）"] end subgraph EDGE["接入层"] NGINX["Nginx 反向代理
mcp.smartmoves.com.cn"] end subgraph AGENTS["Agent 服务层（独立进程）"] BA["BA Server
业务分析师
6 项需求分析技能"] SA["SA Server
系统架构师
4 项架构设计技能"] PM["PM Server
项目经理
5 项项目管理技能"] end subgraph SHARED["共享模块 shared/"] AC["AgentCore 引擎
四层 Prompt 组装
流式 LLM 调用"] SR["SkillRegistry
技能注册中心
SKILL.md 解析与 Schema 生成"] SM["SessionManager
Redis 会话管理
分布式锁 / 历史压缩"] end subgraph INFRA["基础设施"] REDIS["Redis
会话存储"] QD["Qdrant 向量数据库
知识检索"] LLM["LLM API
（兼容 OpenAI 格式）"] EMBED["Embedding 模型
bge-small-zh-v1.5"] end C --> NGINX NGINX --> BA NGINX --> SA NGINX --> PM BA & SA & PM --> AC BA & SA & PM --> SR BA & SA & PM --> SM AC --> REDIS AC --> QD AC --> LLM SM --> REDIS QD --> EMBED
OpenClaw / Cursor / Qoder
（MCP Streamable HTTP）"] end subgraph EDGE["接入层"] NGINX["Nginx 反向代理
mcp.smartmoves.com.cn"] end subgraph AGENTS["Agent 服务层（独立进程）"] BA["BA Server
业务分析师
6 项需求分析技能"] SA["SA Server
系统架构师
4 项架构设计技能"] PM["PM Server
项目经理
5 项项目管理技能"] end subgraph SHARED["共享模块 shared/"] AC["AgentCore 引擎
四层 Prompt 组装
流式 LLM 调用"] SR["SkillRegistry
技能注册中心
SKILL.md 解析与 Schema 生成"] SM["SessionManager
Redis 会话管理
分布式锁 / 历史压缩"] end subgraph INFRA["基础设施"] REDIS["Redis
会话存储"] QD["Qdrant 向量数据库
知识检索"] LLM["LLM API
（兼容 OpenAI 格式）"] EMBED["Embedding 模型
bge-small-zh-v1.5"] end C --> NGINX NGINX --> BA NGINX --> SA NGINX --> PM BA & SA & PM --> AC BA & SA & PM --> SR BA & SA & PM --> SM AC --> REDIS AC --> QD AC --> LLM SM --> REDIS QD --> EMBED
三、请求处理全链路
当用户在 AI Agent 工具中触发 Agent 技能时，一次完整的请求处理链路如下：
sequenceDiagram
participant C as 客户端
participant N as Nginx
participant S as MCP Server
participant SM as SessionManager
participant SR as SkillRegistry
participant Q as QdrantRetriever
participant AC as AgentCore
participant LLM as LLM API
C->>N: POST /{agent}/mcp
N->>S: 按端口转发
S->>SM: 获取/创建 Redis 会话
SM-->>S: 返回会话上下文 + CCID
S->>SR: 查找技能定义
SR-->>S: 返回 Skill 对象（参数 Schema）
S->>AC: 执行技能（message + session）
AC->>SM: 获取历史对话
AC->>Q: 按技能检索知识
Q-->>AC: 返回向量检索结果
AC->>AC: 四层 Prompt 组装
AC->>LLM: 流式 HTTP 请求
LLM-->>AC: SSE 流式 token
AC-->>S: 实时流式输出
S-->>C: 流式响应 + [DOC] 标记
AC->>SM: 更新会话历史
四、MCP Server 层
每个 Agent 是一个独立的 FastMCP 实例，负责：
- 技能动态注册：启动时扫描 skills/{agent}/ 目录，通过 SkillRegistry 将每个 SKILL.md 注册为一个 MCP Tool
- 协议消息处理：响应 Initialize、tools/list、tools/call 等 MCP 协议消息
- 流式响应：LLM 输出通过 SSE（Server-Sent Events）实时推送给客户端
- 会话管理：每个请求关联独立的 Conversation ID（CCID），客户端后续调用回传该 ID 以延续会话上下文
- 健康检查：每个 Agent 暴露 /health 端点，可查看服务状态、活跃会话数、已加载技能列表
五、AgentCore 引擎
AgentCore 是每个 Agent 的核心执行引擎，采用统一的四层 Prompt 组装机制：
| 层级 | 内容 | 来源 |
|---|---|---|
| 角色层 | Agent 的身份定义、行为约束、职责边界 | Agent 定义文件（ba-master/pm-master/sa-master.md） |
| 技能层 | 当前技能的完整 SKILL.md：执行步骤、约束规则、阶段流程 | SkillRegistry 解析的 SKILL.md |
| 知识层 | 从工程知识库检索的相关领域知识（项目管理方法论/业务规则/技术架构模式等） | QdrantRetriever 向量检索 |
| 历史层 | 当前会话的对话历史摘要（超过阈值时自动压缩） | SessionManager |
LLM 调用采用流式输出 + 指数退避重试策略。流式 token 通过 SSE 逐条推送给客户端。
六、技能注册中心（SkillRegistry）
SkillRegistry 扫描 skills/{agent}/ 目录下的 SKILL.md，解析 YAML Frontmatter 与正文，动态生成 MCP Tool 的 JSON Schema。Agent 启动时自动加载全部技能，无需手动配置。
- 参数映射：SKILL.md 中定义的参数自动映射为 MCP Tool 的 inputSchema
- 多 Agent 隔离：每个 Agent 只加载自己目录下的技能，BA 的技能 SA 不可见，反之亦然
- 热加载支持：修改 SKILL.md 后重启对应 Agent 即可生效
七、会话管理（SessionManager）
基于 Redis 的会话生命周期管理，核心设计：
- CCID 协议：服务端首次响应返回 Conversation-ID，客户端后续调用回传该 ID。同 CCID 的请求在同一会话内串行处理，跨客户端支持的是一种"逻辑续接"而非共享状态
- 分布式锁：同一会话同一时间只允许一个请求执行，避免并发写入冲突
- 历史压缩：对话历史超过阈值时自动将最早批次压缩为摘要，控制上下文窗口
- TTL 管理：每个会话有过期时间，定期清理无效会话
八、Qdrant 知识检索
系统内置 Qdrant 向量数据库，为每个 Agent 提供 RAG（检索增强生成）能力：
- 嵌入模型：bge-small-zh-v1.5（约 90MB），首次启动时自动下载
- 知识集合：按领域分类，如 pm-pure-project-management（项目管理方法论）、sa-architecture-patterns（架构模式）、ba-business-rules（业务规则）等
- 检索策略：根据当前技能类型定向检索对应的 Collection，支持多集合并行查询与结果去重
- 结果注入：检索到的知识片段注入到四层 Prompt 的知识层，供 LLM 参考
九、部署拓扑
| 服务 | 路径 | 协议 |
|---|---|---|
| BA Agent | /ba/mcp | Streamable HTTP |
| SA Agent | /sa/mcp | Streamable HTTP |
| PM Agent | /pm/mcp | Streamable HTTP |
| Redis | — | RESP |
| Qdrant | — | gRPC / REST |