技能模式(Skills Pattern)AI Agent 是一种模块化、可组合、可扩展的智能体架构。
它的核心思想只有一个:把 Agent 的能力拆成独立的"技能(Skill)"单元,每个技能封装特定领域的知识、提示词、工具和子流程,运行时再根据用户意图和上下文动态发现、加载并执行。
传统 Agent 把一切塞进一个巨型 Prompt:逻辑、工具、规则全混在一起,越堆越难维护。技能模式把它拆成”轻量内核 + 一堆自治技能”,让能力可以独立开发、独立测试、按需组合。
Draft v1.0
1. 概述
1.1 什么是技能模式 AI Agent
技能模式 AI Agent 是一种模块化、可组合、可扩展的智能体架构。它与传统 Agent 最大的区别,在于”能力”不再是写死在系统提示词里的一团逻辑,而是拆分成一个个自包含的技能单元。
1.2 设计目标
| 目标 | 描述 |
|---|---|
| 模块化 | 每个技能是自包含的独立单元,可独立开发、测试、发布 |
| 动态发现 | Agent 根据上下文自动匹配和加载技能,无需硬编码 |
| 可组合 | 多个技能可链式调用或并行执行,形成复杂工作流 |
| 可扩展 | 第三方开发者可创建和分享自定义技能包 |
| 安全可控 | 技能在沙箱中运行,权限最小化,执行可审计 |
| 人机协作 | 在关键决策点引入人工审批,支持渐进式自主权 |
1.3 与传统 Agent 架构的对比
2. 核心概念
2.1 技能(Skill)
技能是 Agent 能力的原子单元,由元数据、提示词模板、工具、子技能、权限和生命周期钩子共同组成:
- Metadata(元数据)
name:唯一标识符(kebab-case)description:一句话描述version:语义化版本author:作者信息triggers:触发条件列表
- Prompt Template(提示词模板)
system:系统提示词context:上下文注入规则examples:Few-shot 示例
- Tools(工具定义)
built-in:内置工具引用custom:自定义工具实现
- Sub-skills(子技能引用)
dependencies:依赖的其他技能
- Permissions(权限声明)
capabilities:所需权限列表
- Hooks(生命周期钩子)
on_load:技能加载时on_execute:执行前/后on_error:错误处理
技能定义示例(skill.yaml)
name: code-review
description: Review code changes for bugs, security issues, and style violations
version: 1.2.0
author: team-platypus
triggers:
- keywords: ["review", "code review", "检查代码", "审查"]
- patterns: ["*.diff", "*.patch", "git diff"]
- context: ["pull_request", "code_change"]
tools:
- built-in: [Glob, Grep, Read]
- custom: [report_findings]
permissions:
- read_filesystem
- git_diff
hooks:
on_load: load_review_checklist
on_error: fallback_to_lint
2.2 Agent 核心(Agent Core)
Agent Core 是最小化的运行时内核,负责把”用户输入”翻译成”该调用哪个技能、怎么调”:
- 意图路由(Intent Routing):解析用户输入,匹配技能
- 技能编排(Skill Orchestration):加载、执行、卸载技能
- 上下文管理(Context Management):维护对话历史和技能状态
- 工具调度(Tool Dispatch):安全地执行工具调用
- 记忆管理(Memory Management):短期/长期记忆的读写
2.3 工具(Tool)
工具是技能与外部世界交互的接口,按风险分级管理:
- ReadOnly Tools(只读安全):
file_read、search、api_get - SideEffect Tools(需审批):
file_write、api_post、git_commit - Dangerous Tools(需显式授权):
shell_exec、db_migrate、deploy
2.4 记忆(Memory)
分层记忆架构让”临时上下文”和”长期知识”各归其位:
| 记忆层 | 保留期 | 用途 |
|---|---|---|
| Working Memory | 单次会话 | 当前对话上下文 |
| Short-term Memory | 会话期间 | 技能状态、中间结果 |
| Long-term Memory | 持久化 | 用户偏好、项目知识 |
| Episodic Memory | 索引化 | 历史交互经验 |
| Semantic Memory | 向量化 | 知识库、文档 |
3. 系统架构
3.1 整体架构
3.2 组件职责
| 组件 | 职责 | 技术选型 |
|---|---|---|
| API Gateway | 请求路由、认证、限流、协议转换 | Nginx / Envoy |
| Intent Router | NLP 意图识别、技能匹配、歧义消解 | 基于 LLM + 规则引擎 |
| Skill Manager | 技能注册、发现、加载、生命周期 | 自研 |
| Context Manager | 对话窗口管理、token 预算、上下文压缩 | LangChain / 自研 |
| Tool Executor | 工具校验、沙箱执行、结果序列化 | Docker / WASM 沙箱 |
| Memory Store | 多层级记忆的 CRUD | ChromaDB / PostgreSQL |
| Permission Manager | 基于能力的访问控制 (CBAC) | OPA / Casbin |
| Event Bus | Agent 间异步通信、事件驱动编排 | Redis Pub/Sub / NATS |
4. 技能系统设计
4.1 技能注册与发现
技能源优先级
- Built-in(内置):系统自带,最高优先级
- Project(项目级):项目
.agent/skills/目录 - User(用户级):用户
~/.agent/skills/目录 - Marketplace(市场):远程注册表下载
- Remote(远程服务):MCP 协议连接的外部技能服务
技能索引结构
# 技能注册表在内存中的索引
class SkillIndex:
name: str # 唯一名称
triggers: List[Trigger] # 触发条件
embedding: np.ndarray # 描述向量,用于语义匹配
source: SkillSource # 来源
priority: int # 优先级
enabled: bool # 是否启用
匹配策略
4.2 技能生命周期
4.3 技能执行模型
# 技能执行的伪代码
async def execute_skill(
skill: Skill,
context: AgentContext,
user_input: str
) -> SkillResult:
# 1. 权限检查
await permission_manager.check(skill.required_permissions)
# 2. 上下文注入
enriched_context = await context_manager.inject(
base_context=context,
skill_context=skill.prompt_template,
memory=await memory_store.retrieve_relevant(user_input)
)
# 3. 工具绑定
bound_tools = await tool_registry.bind(
skill.tools,
sandbox=skill.sandbox_config
)
# 4. 执行循环
async with skill_session(skill, enriched_context) as session:
result = await session.run(
input=user_input,
tools=bound_tools,
hooks=skill.hooks,
on_permission_required=request_user_approval
)
# 5. 结果持久化
await memory_store.save(skill.name, result)
return result
一次技能执行做了五件事
权限先于一切、上下文按需注入、工具按沙箱绑定、执行循环内可请求人工审批、结果最后落库。任何一步缺位,技能就只是”提示词”,而不是”可控的能力”。
4.4 技能组合模式
技能之间可以像函数一样组合,构成更复杂的工作流。
链式组合(Pipeline)
并行组合(Parallel)
条件组合(Conditional)
工作流定义(YAML DSL)
workflow: deploy-review
steps:
- name: lint
skill: code-lint
on_error: abort
- name: review
parallel:
- skill: security-review
- skill: code-review
args: { level: high }
on_complete: aggregate_results
- name: decide
condition: all_passed
then:
- skill: deploy
args: { env: staging }
requires_approval: true
else:
- skill: notify
args: { channel: slack, status: failed }
5. Agent 运行时
5.1 主循环(Agent Loop)
循环的本质是”观察—决策—行动”
OBSERVE 把工具执行结果重新喂回循环顶部,于是 Agent 可以基于上一步的真实反馈决定下一步——这正是它能处理多步、依赖型任务的原因。
5.2 上下文窗口管理
Token 预算按以下比例在系统提示词、技能提示词、工具定义、对话、召回记忆与预留输出之间分配:
class ContextManager:
async def compose_context(
self,
system_prompt: str,
skill_prompts: List[str],
conversation: List[Message],
memory: List[Memory],
token_budget: int
) -> ComposeResult:
# 1. 计算各部分 token 预算
# 2. 压缩超出的对话历史(摘要/裁剪)
# 3. 按优先级排序检索到的记忆
# 4. 组装最终上下文
pass
5.3 流式输出处理
6. 工具系统
6.1 工具定义标准
采用与 OpenAI Function Calling / Anthropic Tool Use 兼容的 JSON Schema:
{
"name": "web_search",
"description": "Search the web for current information",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
},
"max_results": {
"type": "integer",
"default": 10,
"minimum": 1,
"maximum": 50
}
},
"required": ["query"]
},
"permissions": ["network_outbound"],
"sandbox": "none",
"cache": {
"ttl": 300,
"strategy": "url-based"
}
}
6.2 工具执行沙箱
Permission Level Execution Context
─────────────────────────────────────────
Level 0 (Trusted) 进程内直接调用
Level 1 (ReadOnly) 只读文件系统视图
Level 2 (Sandboxed) Docker/WASM 隔离
Level 3 (Approved) 需用户审批 + Level 2
6.3 MCP 协议集成
支持通过 Model Context Protocol (MCP) 连接外部工具服务:
Agent Core ←→ MCP Client ←→ MCP Server (remote tools)
├── Database tools
├── API integrations
└── Custom services
7. 记忆与上下文管理
7.1 分层记忆架构
7.2 记忆存储后端
| 记忆层级 | 存储后端 | 检索方式 |
|---|---|---|
| Working Memory | 进程内存 | 直接引用 |
| Short-term | Redis | Key-Value |
| Long-term | PostgreSQL + pgvector | SQL + 向量搜索 |
| Episodic | ChromaDB / Qdrant | 语义相似度 |
7.3 记忆召回策略
class MemoryRetrieval:
async def retrieve(self, query: str, layers: List[str]) -> List[Memory]:
results = []
if "working" in layers:
results += self._get_working_memory()
if "short_term" in layers:
results += await self._redis_search(query)
if "long_term" in layers:
# 混合检索: 关键词 + 语义向量
keyword_results = await self._pg_search(query)
semantic_results = await self._vector_search(query)
results += self._reciprocal_rank_fusion(
keyword_results, semantic_results
)
if "episodic" in layers:
results += await self._episodic_search(
query, top_k=5, recency_weight=0.3
)
return self._deduplicate_and_rank(results)
8. 通信模式
8.1 Agent 间通信
8.2 人机协作模式
Autonomy Level Behavior
───────────────────────────────────────────
L0: Full Manual 每步都需用户确认
L1: Suggest 建议行动,等待确认
L2: Auto-execute 自动执行可逆操作
L3: Auto-approve 自动执行(事后通知)
L4: Full Auto 完全自主(限定域)
9. 技术栈选型
9.1 推荐的技术栈
| 层级 | 技术 | 理由 |
|---|---|---|
| 语言 | Python 3.12+ | 最成熟的 AI/ML 生态;async/await 原生支持;与 LLM SDK 最佳兼容 |
| LLM | Anthropic Claude API (Opus 5.5) | 最强的推理和工具使用能力;原生支持 tool_use;超长上下文窗口 |
| Agent 框架 | LangGraph + 自研 | LangGraph 提供状态机编排;自研部分处理技能特有逻辑 |
| Web 框架 | FastAPI | 高性能 async;原生 OpenAPI;Pydantic 集成 |
| 数据库 | PostgreSQL + pgvector | 关系型 + 向量搜索二合一;成熟稳定 |
| 缓存 | Redis | 高性能 KV;Pub/Sub;支持多种数据结构 |
| 向量搜索 | pgvector / Qdrant | pgvector 适合中规模;Qdrant 适合大规模高性能场景 |
| 消息队列 | NATS / Redis Streams | 轻量;支持 Pub/Sub 和 Request/Reply |
| 沙箱 | Docker / Firecracker (microVM) | 隔离性强;启动快;资源可控 |
| MCP 协议 | mcp (Python SDK) | 标准化的工具/资源/提示词协议 |
| 监控 | OpenTelemetry + Grafana | 可观测性标准;LLM 调用追踪 |
| 配置 | YAML + Pydantic Settings | 人类可读;类型安全 |
9.2 备选方案对比
Agent 框架选择
| 框架 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| LangGraph | 状态机模型清晰;流式支持好;社区活跃 | 抽象层级较高;调试困难 | 复杂多步工作流 |
| CrewAI | 简单易用;角色扮演模型 | 灵活性有限;不适合复杂编排 | 简单多 Agent 协作 |
| AutoGen | 微软支持;对话驱动 | 与 Azure 绑定紧;学习曲线 | 企业微软生态 |
| 自研 | 完全可控;最小开销 | 开发成本高;需持续维护 | 深度定制需求 |
推荐:LangGraph + 自研技能管理层。LangGraph 处理通用 Agent 状态机,自研部分聚焦技能特有的注册/发现/生命周期。
为什么选择 Claude API 作为主要 LLM
| 能力 | Claude Opus 5.5 | GPT-4o | 意义 |
|---|---|---|---|
| 工具使用准确率 | ★★★★★ | ★★★★ | 减少工具调用重试 |
| 指令遵循 | ★★★★★ | ★★★★ | 技能 prompt 执行力 |
| 代码生成 | ★★★★★ | ★★★★ | 代码类技能质量 |
| 长上下文 | 200K tokens | 128K tokens | 更多对话和技能上下文 |
| 多语言 | ★★★★★ | ★★★★ | 中文场景友好 |
| 安全性 | ★★★★★ | ★★★ | 技能执行更安全可控 |
9.3 部署架构
# docker-compose.yml 核心服务
services:
agent-server:
build: .
ports: ["8000:8000"]
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- DATABASE_URL=postgresql://...
- REDIS_URL=redis://...
depends_on: [postgres, redis]
postgres:
image: pgvector/pgvector:pg16
volumes: [pgdata:/var/lib/postgresql/data]
redis:
image: redis:7-alpine
sandbox:
image: agent-sandbox:latest
privileged: false # 安全: 非特权容器
nginx:
image: nginx:alpine
ports: ["443:443"]
volumes: [./nginx.conf:/etc/nginx/nginx.conf]
10. 实现路线图
Phase 1:核心基础(4–6 周)
- Skill schema 定义与验证
- Skill registry 实现
- Agent Core 最小化运行时
- Tool 系统(内置 10+ 工具)
- LLM 集成(Claude API)
- 基础 CLI 接口
Phase 2:技能系统(4–6 周)
- 技能发现与自动加载
- 意图路由与技能匹配
- 技能链式/并行执行
- 上下文窗口管理
- 基础权限系统
- WebSocket 流式输出
Phase 3:记忆与扩展(4–6 周)
- 分层记忆系统
- 向量数据库集成
- MCP 协议客户端
- 沙箱执行环境
- 第三方技能市场
- Web UI 基础版
Phase 4:生产化(4–6 周)
- 多租户支持
- 审计日志
- 性能优化与缓存
- 水平扩展
- 监控告警
- 文档与示例
11. 附录
A. 技能开发快速示例
# skills/code_review/skill.py
from agent_core import Skill, tool, hook
class CodeReviewSkill(Skill):
name = "code-review"
description = "Review code changes for bugs and style issues"
triggers = [
{"keywords": ["review", "审查"]},
{"patterns": ["*.diff", "*.patch"]}
]
# 技能专属工具
@tool
async def report_findings(self, findings: list[dict]) -> str:
"""Report review findings in structured format"""
return self.format_report(findings)
# 生命周期钩子
@hook("on_load")
async def load_checklist(self):
self.checklist = await self.fetch_review_checklist()
@hook("on_execute")
async def enrich_context(self, context):
context["review_standards"] = self.checklist
return context
# 注册技能
registry.register(CodeReviewSkill())
B. 与 Claude Code Skill 系统的关系
本设计受 Claude Code 的 Skill 系统启发,但进行了泛化和扩展:
| 特性 | Claude Code Skills | 本设计 |
|---|---|---|
| 技能作用域 | CLI 会话内 | 多 Agent 共享 |
| 触发方式 | 用户显式调用或自动匹配 | 意图路由自动匹配 |
| 技能组合 | 单技能执行 | Pipeline/Parallel |
| 记忆持久化 | 文件系统 | 多层向量数据库 |
| 工具扩展 | MCP/内置 | MCP + 自定义工具 SDK |
| 部署模式 | 本地 CLI | 服务端 + 客户端 |
C. 关键设计决策记录(ADR)
| ID | 决策 | 理由 | 权衡 |
|---|---|---|---|
| ADR-001 | 使用 YAML 定义技能 | 人类可读写,工具链成熟 | 不如 JSON Schema 严格 |
| ADR-002 | Agent 有状态 | 支持长对话和多步工作流 | 增加了状态管理复杂度 |
| ADR-003 | 技能无状态 | 简化技能开发,易于横向扩展 | 状态需外部存储(记忆系统) |
| ADR-004 | Python 为主语言 | AI 生态最丰富 | 性能不如 Go/Rust |
| ADR-005 | 向量 + 关键词混合检索 | 兼顾语义理解和精确匹配 | 实现复杂度增加 |
下一步:基于本文档进行技术原型验证(PoC),验证意图路由和技能加载的核心链路。