Skill Compose 是一个开源的 Agent 构建与运行时平台，基于 FastAPI + Next.js + PostgreSQL 三大件搭建，让你无需工作流画布、无需 CLI，就能通过"技能（Skill）"组合出可自主进化的 AI Agent。本文将从分层视角拆解它的整体架构：FastAPI 负责编排与 API 网关，Next.js 提供 Web 管理台，PostgreSQL（含 pgvector）承载技能注册表与向量记忆，外加一组隔离的 Executor 容器安全执行代码。

一、整体架构：五层分离的运行时

Skill Compose 的部署拓扑定义在 docker/docker-compose.yaml，核心服务有五个：

各服务通过健康检查（healthcheck）级联启动：数据库就绪后 API 才启动，API 就绪后 Web 才启动，生产环境再叠加一层 Nginx 反向代理（可选 profile）。

如上图所示，每个 Agent 运行时（容器 / K8s Pod）由四部分组成：系统提示词 + agent.md、允许使用的技能、允许的 MCP 服务器与工具、独立的虚拟文件系统与依赖包。多个 Agent 共享底层分布式文件系统中的skills、resources、memories等目录——这正是"Skill 组合 Agent"的核心设计：能力可插拔、环境可隔离、数据可共享。

二、FastAPI 后端：Agent 的大脑与总调度

后端入口是 app/main.py，一个看似简单却暗藏生产级细节的 FastAPI 应用：

• JWT 全局认证中间件（AuthMiddleware）：所有/api/v1请求必须携带Bearertoken，仅健康检查、文档页、登录/刷新、已发布的公开 Agent 等白名单路径可匿名访问；
• 启动生命周期管理（lifespan）：初始化数据库、清理孤儿 trace 与过期工作区、预热各 worker 的数据库连接池；
• 单节点选举：多 worker 部署时用文件锁（fcntl.flock）选出唯一"服务领导者"，只有它启动定时任务调度器（app/services/scheduler.py）和渠道管理器（app/services/channel_manager.py），避免重复连接外部平台。

API 路由按领域拆分为独立模块，注册在 app/api/v1/router.py 下：技能管理（skills.py）、Agent 编排（agents.py）、执行引擎（execute.py）、MCP 集成（mcp.py）、记忆（memory.py）、会话与追踪（sessions.py/traces.py）等十余个子路由，职责边界非常清晰。

多 LLM 供应商支持是后端另一亮点。app/llm/provider.py 用一个统一客户端封装了 Anthropic Claude、OpenAI、Google Gemini、DeepSeek、Kimi（Moonshot）、OpenRouter 等供应商——非 OpenAI 协议的服务通过 OpenAI 兼容端点接入，换模型只需改一个环境变量。

三、PostgreSQL 数据层：不止是关系表

数据模型定义在 app/db/models.py，选型的精妙之处在于：

1. pgvector 扩展：镜像直接使用pgvector/pgvector:pg16，memory_entries表内嵌向量列（Vector类型），Agent 的长期记忆检索无需额外部署向量数据库——嵌入服务（app/services/embedding_service.py）调用 text-embedding 模型生成向量后直接入库；
2. JSONB 灵活字段：技能标签、配置等半结构化数据用JSONB存储，既保留关系约束又避免频繁改表；
3. 完整的技能版本体系：skills、skill_versions、skill_files、skill_tests、skill_changelogs五张表协同，支撑技能的导入导出、回归测试与变更审计（见 app/repositories/skill_repo.py）。

连接层采用 SQLAlchemy 2.0 异步 ORM +asyncpg驱动，与 FastAPI 的异步模型完全对齐。

四、Next.js 前端：Web 化的 Agent 工作台

前端位于 web/src/，技术选型见 web/package.json：Next.js 14（App Router）+ React 18 + Tailwind CSS + Radix UI 组件库，状态管理用 Zustand，数据请求用 React Query。

管理台覆盖 Agent 全生命周期：

• 技能市场：Find Skills（从 skills.sh 发现）、Import Skill（文件/GitHub 导入）、Create Skill（AI 辅助生成）；
• Agent 构建器：web/src/components/agents/agent-builder-chat.tsx 让你通过聊天方式配置 Agent 的技能组合、MCP 服务器与工具权限；
• 会话与追踪：web/src/app/traces/ 可视化每次执行的工具调用链，"Evolve Skills"功能直接从执行 trace 中学习、改进技能；
• 内置终端：基于 xterm.js + 后端 app/terminal/pty_manager.py 的 PTY 管理，浏览器里直接操作容器；
• 渠道接入：web/src/app/channels/ 支持把 Agent 发布到 Telegram、飞书等平台（对应后端 app/channels/）。

五、Executor 容器群：把代码执行关进沙箱

Agent 要"动手"就得执行代码，Skill Compose 的答案是每个执行环境一个独立容器。每个 executor 运行同一个 FastAPI 服务（docker/executor/executor_server.py），暴露/execute/python、/execute/bash等端点：

• Python 执行基于持久化 IPython kernel——同一 workspace 内变量、导入和状态跨调用保留，天然适合多轮数据分析；kernel 不可用时自动降级为 subprocess；
• 每次执行都落在按 workspace 隔离的目录中，输出截断在 100KB 防止内存爆炸；
• API 侧通过 app/services/executor_client.py 这个异步 HTTP 客户端按名路由到目标容器。

预置执行环境在 config/executors.json 中声明：

需要 GPU 的场景用--profile gpu按需拉起，其余环境零成本闲置不占资源。

六、Agent 执行循环：技能驱动的自主推理

真正的"运行时"核心在 app/agent/agent.py，一个标准的 ReAct 式异步循环：

1. 接收用户请求；
2. LLM 依据系统提示词 + agent.md 决策下一步；
3. 调用工具（list_skills、get_skill、execute_code等，工具注册在 app/core/tools_registry.py）；
4. 循环直至任务完成，全程通过事件流（app/agent/event_stream.py）向 Web 端推送进度。

两个工程细节值得一提：上下文压缩——当输入 token 超过模型上下文上限的 70% 时，自动把早期对话摘要成结构化总结（保留用户原始意图、文件变更、待办任务）；记忆冲刷——压缩前插入一轮"静默回合"，让 Agent 把值得长期保留的事实写入MEMORY.md、SOUL.md等记忆文件，落盘到 PostgreSQL 后再参与向量检索。

七、五分钟上手：部署与验证

cd docker cp .env.example .env # 填入 ANTHROPIC_API_KEY 等 docker compose up -d

启动后访问http://localhost:62600打开 Web 控制台，API 文档在http://localhost:62610/docs（路由与鉴权逻辑见 app/api/v1/）。需要单机资源更省的开发者模式，可改用 docker/docker-compose.dev.yaml；测试入口在 tests/，涵盖 API 单测与真实 Agent 的 E2E 场景。

总结：为什么这套架构值得借鉴

• 职责分层：FastAPI 只做编排与调度，重计算全部下沉到 Executor 容器，API 进程永远轻量；
• 存储复用：PostgreSQL 一身三职——关系表、JSONB 配置、向量记忆，小团队部署零额外组件；
• 能力即数据：技能是带版本的文件包而非硬编码，Agent 能力组合、演进、审计全走数据流；
• 前端即运维台：Next.js 管理台把技能市场、trace 调试、终端、渠道发布收敛进浏览器，真正做到"无 CLI"。

想深入了解，推荐阅读 docs/docs/concepts/ 下的架构概念文档（executors.md、skills.md）以及快速上手指南 docs/docs/quickstart.md。