Agent Skill目录结构设计指南：从新手入门到生产级实践

15次阅读

没有评论

共计 2528 个字符，预计需要花费 7 分钟才能阅读完成。

刚接触 Agent Skill 开发时，很多新手会直接把所有代码塞进一个文件夹。这种看似简单的做法很快就会带来问题：

功能混杂 ：业务逻辑、第三方接口调用、配置管理全部挤在一起，修改一个功能可能影响其他完全不相关的部分
依赖混乱 ：文件之间相互引用形成蜘蛛网，简单的重命名都可能引发连锁报错
协作困难 ：多个开发者同时修改同一文件时，Git 冲突频发

我曾维护过一个早期项目，核心业务逻辑里混杂着微信消息模板和数据库连接字符串。当需要更换消息平台时，不得不冒着风险修改了 200 多行看似无关的代码。这就是糟糕的目录结构带来的技术债务。

把 Skill 想象成乐高玩具：

每个功能模块应该是独立的积木块（如自然语言处理、API 调用、状态管理）
通过标准接口（插槽）相互连接
可以单独替换 / 升级某个模块而不影响整体

推荐采用经典的三层结构：

Core 层 ：纯业务逻辑（如对话状态机、意图识别）
Adapters 层 ：对接外部平台（微信、Slack 等）的适配器
Services 层 ：基础设施（数据库、缓存、消息队列）

这种分层比扁平化结构多 10%-20% 的初始工作量，但能让后期维护成本降低 50% 以上。

my_skill/
├── core/               # 核心业务逻辑
│   ├── intents/        # 意图识别处理
│   ├── dialog/         # 对话状态管理
│   └── skills/         # 具体技能实现
├── adapters/           # 平台适配层
│   ├── wechat/         # 微信机器人适配
│   ├── slack/          # Slack 适配
│   └── web/            # HTTP 接口
├── services/           # 基础设施服务
│   ├── database/       # 数据持久化
│   ├── cache/          # Redis 缓存
│   └── config/         # 配置管理
├── tests/              # 分层测试
└── main.py             # 应用入口

core/skills：实现具体的技能逻辑，比如天气查询、日程提醒等。每个技能应该是一个独立的 Python 模块
adapters/wechat：处理微信特定的消息格式转换、签名验证等平台相关逻辑
services/config：集中管理所有配置项，支持环境变量覆盖和热加载

# services/config/loader.py
import os
from dotenv import load_dotenv

class Config:
    """支持多环境配置的加载器"""
    def __init__(self):
        load_dotenv()  # 加载.env 文件

        # 分层配置：默认值 < 环境变量 < 运行时覆盖
        self.wechat_token = os.getenv('WECHAT_TOKEN', 'dev_token')
        self.db_url = os.getenv('DATABASE_URL', 'sqlite:///local.db')

    def reload(self):
        """热重载配置（适合长期运行的 Agent）"""
        self.__init__()

# main.py
from adapters import wechat, slack

class SkillApplication:
    def __init__(self):
        self.adapters = {'wechat': wechat.WeChatAdapter(),
            'slack': slack.SlackAdapter()}

    def get_adapter(self, platform: str):
        """通过统一接口获取适配器实例"""
        if platform not in self.adapters:
            raise ValueError(f'Unsupported platform: {platform}')
        return self.adapters[platform]

错误现象 ：

# core/dialog/manager.py
from core.skills.weather import WeatherSkill

# core/skills/weather.py
from core.dialog.manager import DialogManager

解决方案 ：
– 使用依赖注入（DI）传递实例
– 或将公共逻辑提取到新模块

反模式 ：

# adapters/wechat/client.py
def send_message(user_id, content):
    token = "abcdef123456"  # 直接写在代码里
    ...

正确做法 ：
– 所有配置集中管理
– 敏感信息通过环境变量注入

问题代码 ：

class BaseSkill:
    # 20 个抽象方法...

class WeatherSkill(BaseSkill, Loggable, Cacheable):
    # 多重继承导致难以维护

改进方案 ：
– 优先使用组合而非继承
– 通过接口定义行为契约

当业务复杂度上升时，可以考虑：

领域驱动设计（DDD）：
按业务域拆分模块（如 payment/notifications）
使用明确的界限上下文
依赖注入容器 ：
使用 wire/inject 等库管理复杂依赖

示例：

# 使用 dependency-injector 库
from dependency_injector import containers, providers

class AdaptersContainer(containers.DeclarativeContainer):
    wechat = providers.Singleton(WeChatAdapter)
    slack = providers.Factory(SlackAdapter)