技能模式 AI Agent

技能模式(Skills Pattern)AI Agent 是一种模块化、可组合、可扩展的智能体架构。

它的核心思想只有一个:把 Agent 的能力拆成独立的"技能(Skill)"单元,每个技能封装特定领域的知识、提示词、工具和子流程,运行时再根据用户意图和上下文动态发现、加载并执行。

传统 Agent 把一切塞进一个巨型 Prompt:逻辑、工具、规则全混在一起,越堆越难维护。技能模式把它拆成”轻量内核 + 一堆自治技能”,让能力可以独立开发、独立测试、按需组合。

传统 Agent
单一巨型 Prompt
+ 工具列表
+ 逻辑混杂(全塞在一起)
Agent Core
(轻量内核)
Skill A
(代码)
Skill B
(文档)
Skill C
(搜索)

Draft v1.0

1. 概述

1.1 什么是技能模式 AI Agent

技能模式 AI Agent 是一种模块化、可组合、可扩展的智能体架构。它与传统 Agent 最大的区别,在于”能力”不再是写死在系统提示词里的一团逻辑,而是拆分成一个个自包含的技能单元。

1.2 设计目标

目标 描述
模块化 每个技能是自包含的独立单元,可独立开发、测试、发布
动态发现 Agent 根据上下文自动匹配和加载技能,无需硬编码
可组合 多个技能可链式调用或并行执行,形成复杂工作流
可扩展 第三方开发者可创建和分享自定义技能包
安全可控 技能在沙箱中运行,权限最小化,执行可审计
人机协作 在关键决策点引入人工审批,支持渐进式自主权

1.3 与传统 Agent 架构的对比

传统 Agent
单一巨型 Prompt
+ 工具列表
+ 逻辑混杂
Agent Core
(轻量内核)
Skill A(代码)
Skill B(文档)
Skill C(搜索)

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 整体架构

API Gateway
(REST + WebSocket)
Web UI
CLI Client
SDK / API
Intent Router
Skill Manager
Context Manager
Tool Executor
Skill Registry
Vector DB
(Qdrant)
Relational DB
(PostgreSQL)
Cache
(Redis)

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 技能注册与发现

技能源优先级

  1. Built-in(内置):系统自带,最高优先级
  2. Project(项目级):项目 .agent/skills/ 目录
  3. User(用户级):用户 ~/.agent/skills/ 目录
  4. Marketplace(市场):远程注册表下载
  5. Remote(远程服务):MCP 协议连接的外部技能服务

技能索引结构

# 技能注册表在内存中的索引
class SkillIndex:
    name: str                    # 唯一名称
    triggers: List[Trigger]      # 触发条件
    embedding: np.ndarray        # 描述向量,用于语义匹配
    source: SkillSource          # 来源
    priority: int                # 优先级
    enabled: bool                # 是否启用

匹配策略

User Input
Preprocess
(分词 / 实体识别)
1. 关键词精确匹配(fast path)
2. Glob Pattern 匹配
3. 语义向量相似度匹配(fallback)
4. LLM 意图分类(ambiguous cases)

4.2 技能生命周期

Registered
技能文件被扫描到
Validated
校验 schema、依赖、权限
Indexed
加入索引,可被搜索
Disabled
Loaded
Error
Running
Paused
Completed
Unloaded
会话结束或超时卸载

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)

Skill A
(代码生成)
Skill B
(代码审查)
Skill C
(格式化)

并行组合(Parallel)

Skill A
Skill B1(lint)
Skill B2(security scan)
Skill B3(test)

条件组合(Conditional)

成功路径
错误处理
Skill A
判断
Skill B
Skill C

工作流定义(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)

RECEIVE
input
MATCH
skills
LOAD
skills
COMPOSE
context
CALL LLM
EXECUTE
tool
RESPOND
to user
OBSERVE
result

循环的本质是”观察—决策—行动”

OBSERVE 把工具执行结果重新喂回循环顶部,于是 Agent 可以基于上一步的真实反馈决定下一步——这正是它能处理多步、依赖型任务的原因。

5.2 上下文窗口管理

Token 预算按以下比例在系统提示词、技能提示词、工具定义、对话、召回记忆与预留输出之间分配:

System Prompt
20%
Skill Prompt
15%
Tool Definitions
8%
Conversation
25%
Retrieved Memory
12%
Reserved/Output
20%
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 流式输出处理

LLM Streaming Response
text → SSE → Client
(逐字展示)
tool_call → 解析 → 执行 → 注入结果 → 继续生成
skill_switch → 检测 → 加载新技能 → 切换上下文

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 分层记忆架构

存储
存储
存储
存储
Layer 1
Working Memory
(当前轮次)
tool_calls / intermediate_results / errors
Layer 2
Short-term Memory
(会话级)
conversation / skill_states / user_prefs
Layer 3
Long-term Memory
(持久化)
Project / User / Knowledge
Layer 4
Episodic Memory
(经验)
Past interactions / failure patterns
进程内存
直接引用
Redis
Key-Value
PostgreSQL + pgvector
SQL + 向量搜索
ChromaDB / Qdrant
语义相似度

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 间通信

Message
Response
通信模式
Direct Call(同步)
Pub/Sub(异步广播)
Task Queue(工作分发)
Blackboard(共享状态)
Agent A
(Skill X)
Agent B
(Skill Y)

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),验证意图路由和技能加载的核心链路。