【从0到1构建一个ClaudeAgent】规划与协调-技能

2026年4月13日
| 没有评论

这里解决了 Agent 开发中的一个核心痛点：上下文窗口限制与知识广度的矛盾。

Java 实现代码

public class AgentWithSkills {
    private static final Path WORKDIR = Paths.get(System.getProperty("user.dir"));
    private static final Path SKILLS_DIR = WORKDIR.resolve("skills");  // 新增技能目录

    // --- 1. 技能管理：SkillLoader ---
    
    // 技能实体
    public static class Skill {
        public String name;
        public String description;
        public String tags;
        public String body; // 技能的具体指令内容
        public Path path;
    }

    // 管理器类
    public static class SkillLoader {
        private final Map<String, Skill> skills = new HashMap<>();

        public SkillLoader(Path skillsDir) {
            if (Files.exists(skillsDir)) {
                loadAll(skillsDir);
            }
        }

        // 扫描所有技能
        private void loadAll(Path dir) {
            try (var stream = Files.walk(dir)) {
                stream.filter(p -> p.getFileName().toString().equals("SKILL.md"))
                      .forEach(this::parseSkillFile);
            } catch (IOException e) {
                System.err.println("Error loading skills: " + e.getMessage());
            }
        }

        // 解析单个技能文件
        private void parseSkillFile(Path path) {
            try {
                String content = Files.readString(path);
                // 解析 Frontmatter (--- ... ---)
                Matcher matcher = Pattern.compile("^---\\n(.*?)\\n---\\n(.*)", Pattern.DOTALL).matcher(content);
                
                Skill skill = new Skill();
                skill.path = path;
                skill.name = path.getParent().getFileName().toString(); // 默认名称

                if (matcher.matches()) {
                    String metaBlock = matcher.group(1);
                    skill.body = matcher.group(2).trim();
                    
                    // 解析 YAML
                    for (String line : metaBlock.split("\\n")) {
                        if (line.contains(":")) {
                            String[] parts = line.split(":", 2);
                            String key = parts[0].trim();
                            String val = parts[1].trim();
                            if ("name".equals(key)) skill.name = val;
                            if ("description".equals(key)) skill.description = val;
                            if ("tags".equals(key)) skill.tags = val;
                        }
                    }
                } else {
                    skill.body = content.trim(); // 没有 frontmatter
                    skill.description = "No description";
                }
                
                skills.put(skill.name, skill);
            } catch (IOException e) {
                System.err.println("Failed to parse skill: " + path);
            }
        }

        // Layer 1: 获取简短描述列表
        public String getDescriptions() {
            if (skills.isEmpty()) return "(no skills available)";
            return skills.values().stream()
                .map(s -> String.format("  - %s: %s [%s]", s.name, s.description, s.tags != null ? s.tags : ""))
                .collect(Collectors.joining("\n"));
        }

        // Layer 2: 获取完整技能内容
        public String getContent(String name) {
            Skill skill = skills.get(name);
            if (skill == null) {
                return "Error: Unknown skill '" + name + "'. Available: " + String.join(", ", skills.keySet());
            }
            return String.format("<skill name=\"%s\">\n%s\n</skill>", skill.name, skill.body);
        }
    }

    private static final SkillLoader SKILL_LOADER = new SkillLoader(SKILLS_DIR);

    // --- 2. 工具定义与分发 ---
    public enum ToolType {
        BASH("bash"), READ_FILE("read_file"), WRITE_FILE("write_file"), 
        EDIT_FILE("edit_file"), LOAD_SKILL("load_skill");  // 新增技能加载工具
        public final String name;
        ToolType(String name) { this.name = name; }
    }

    private static final Map<String, ToolExecutor> TOOL_HANDLERS = new HashMap<>();

    static {
        // ... 省略已有的工具注册
        
        // 注册 load_skill 工具
        TOOL_HANDLERS.put(ToolType.LOAD_SKILL.name, args -> SKILL_LOADER.getContent((String) args.get("name")));
    }

    // --- 3. 核心循环 ---
    // Layer 1: 系统提示词注入技能列表
    private static final String SYSTEM_PROMPT = String.format(
        "You are a coding agent at %s.\n" +
        "Use load_skill to access specialized knowledge.\n" +
        "Skills available:\n%s",
        WORKDIR, SKILL_LOADER.getDescriptions()  // 动态注入技能列表
    );

    public static void agentLoop(List<Map<String, Object>> messages) {
        // ... 省略相同的主循环逻辑，但注意 SYSTEM_PROMPT 包含了技能列表
    }

    // 辅助方法：构建工具定义 JSON
    private static List<Map<String, Object>> getToolSpecs() {
        List<Map<String, Object>> tools = new ArrayList<>();
        // ... 添加基础工具定义
        
        // 添加 load_skill 定义
        Map<String, Object> skillTool = new HashMap<>();
        skillTool.put("name", "load_skill");
        skillTool.put("description", "Load specialized knowledge by name.");
        Map<String, Object> schema = new HashMap<>();
        schema.put("type", "object");
        schema.put("properties", Map.of("name", Map.of("type", "string", "description", "Skill name")));
        schema.put("required", Arrays.asList("name"));
        skillTool.put("input_schema", schema);
        tools.add(skillTool);
        
        return tools;
    }
}

这段代码引入了知识分层和懒加载的概念，这是解决 LLM 上下文限制（Context Window）的关键策略。

技能系统架构：SkillLoader

核心思想：引入外部知识库系统，将专业知识和经验以结构化的”技能”文件形式存储，让Agent能够动态学习和复用专业知识，实现”知识外挂”。

// 技能实体 - 知识的结构化表示
public static class Skill {
    public String name;        // 技能名称
    public String description; // 简短描述
    public String tags;        // 分类标签
    public String body;        // 技能的具体指令内容
    public Path path;          // 文件路径
    // 结构化知识：名称、描述、标签、内容四位一体
    // 文件存储：技能存储在外部文件中，易于管理和更新
}

// SkillLoader - 技能管理器
public static class SkillLoader {
    private final Map<String, Skill> skills = new HashMap<>();
    // 技能索引：内存缓存，快速查找

    public SkillLoader(Path skillsDir) {
        if (Files.exists(skillsDir)) {
            loadAll(skillsDir);
        }
    }
    // 自动扫描：启动时自动加载所有技能
    // 可插拔：技能存储在外部目录，随时可以添加/删除

    // 扫描所有技能文件
    private void loadAll(Path dir) {
        try (var stream = Files.walk(dir)) {
            stream.filter(p -> p.getFileName().toString().equals("SKILL.md"))
                  .forEach(this::parseSkillFile);
            // 约定大于配置：所有技能文件名为SKILL.md
            // 递归扫描：支持技能目录层级结构
        } catch (IOException e) {
            System.err.println("Error loading skills: " + e.getMessage());
        }
    }
}
  • 知识外化：将AI的专业知识存储在外部文件，而不是硬编码在代码中
  • 动态加载：程序启动时自动扫描技能目录
  • 约定驱动：通过文件名SKILL.md标识技能文件
  • 结构化管理：用面向对象的方式管理技能

技能文件格式与解析

// 技能文件解析
private void parseSkillFile(Path path) {
    try {
        String content = Files.readString(path);
        // 解析 Frontmatter (--- ... ---)
        Matcher matcher = Pattern.compile("^---\\n(.*?)\\n---\\n(.*)", Pattern.DOTALL).matcher(content);
        // 混合格式：YAML元数据 + Markdown内容
        // 前元数据：name, description, tags
        // 后内容：具体的技能指导
        
        Skill skill = new Skill();
        skill.path = path;
        skill.name = path.getParent().getFileName().toString(); // 默认名称
        
        if (matcher.matches()) {
            String metaBlock = matcher.group(1);
            skill.body = matcher.group(2).trim();
            // 元数据块解析
            // 内容块：技能的核心知识
            
            for (String line : metaBlock.split("\\n")) {
                if (line.contains(":")) {
                    String[] parts = line.split(":", 2);
                    String key = parts[0].trim();
                    String val = parts[1].trim();
                    if ("name".equals(key)) skill.name = val;
                    if ("description".equals(key)) skill.description = val;
                    if ("tags".equals(key)) skill.tags = val;
                }
            }
        } else {
            skill.body = content.trim(); // 没有frontmatter则全是内容
            skill.description = "No description";
        }
        
        skills.put(skill.name, skill);
    } catch (IOException e) {
        System.err.println("Failed to parse skill: " + path);
    }
}
  • 元数据+内容：YAML Frontmatter + Markdown内容的标准格式
  • 灵活兼容：支持有/无元数据的文件格式
  • 默认命名：用文件夹名作为默认技能名
  • 容错解析：解析失败不影响整体运行

双层级技能访问模式

// Layer 1: 获取简短描述列表 (用于 System Prompt)
public String getDescriptions() {
    if (skills.isEmpty()) return "(no skills available)";
    return skills.values().stream()
        .map(s -> String.format("  - %s: %s [%s]", s.name, s.description, s.tags != null ? s.tags : ""))
        .collect(Collectors.joining("\n"));
    // 简要列表：名称 + 描述 + 标签
    // 格式统一：便于LLM理解和选择
}

// Layer 2: 获取完整技能内容 (用于 Tool Result)
public String getContent(String name) {
    Skill skill = skills.get(name);
    if (skill == null) {
        return "Error: Unknown skill '" + name + "'. Available: " + String.join(", ", skills.keySet());
    }
    return String.format("<skill name=\"%s\">\n%s\n</skill>", skill.name, skill.body);
    // 完整内容：用XML标签包裹，便于LLM识别
    // 错误提示：提供可用技能列表
}
  • 摘要模式：先看目录，再决定获取哪个详情
  • 渐进式披露：避免一次性暴露所有信息污染上下文
  • 标签化：用<skill>标签标注内容来源
  • 自描述错误：未知技能时返回可用列表

技能系统集成

// 系统提示词动态注入技能列表
private static final String SYSTEM_PROMPT = String.format(
    "You are a coding agent at %s.\n" +
    "Use load_skill to access specialized knowledge.\n" +
    "Skills available:\n%s",  // 关键：将技能列表注入系统提示
    WORKDIR, SKILL_LOADER.getDescriptions()
);
// 动态提示：系统提示词包含当前可用的技能列表
// 主动引导：明确告诉LLM使用load_skill工具获取知识

// load_skill工具定义
private static List<Map<String, Object>> getToolSpecs() {
    // ... 添加基础工具
    
    // 添加 load_skill 定义
    Map<String, Object> skillTool = new HashMap<>();
    skillTool.put("name", "load_skill");
    skillTool.put("description", "Load specialized knowledge by name.");
    Map<String, Object> schema = new HashMap<>();
    schema.put("type", "object");
    schema.put("properties", Map.of("name", Map.of("type", "string", "description", "Skill name")));
    schema.put("required", Arrays.asList("name"));
    skillTool.put("input_schema", schema);
    tools.add(skillTool);
    // 专用工具：为技能系统创建专门的工具
    // 简单接口：只需要技能名一个参数
}
  • 动态上下文：系统提示词根据实际技能动态生成
  • 工具化访问：将知识获取抽象为工具调用
  • 简单接口：最小化的参数设计
  • 与基础工具并存：技能工具和操作工具在同一系统中

技能文件示例

---
name: java-refactoring
description: Best practices for refactoring Java code
tags: java, refactoring, clean-code
---

# Java代码重构最佳实践

## 1. 识别代码异味
- 过长的方法（>20行）
- 过大的类（>500行）
- 重复代码块
- 过深的嵌套（>3层）

## 2. 重构技术
- 提取方法：将重复代码提取为私有方法
- 重命名：使用清晰的变量名和方法名
- 移动方法：将方法移到更合适的类中
- 引入参数对象：减少方法参数数量

## 3. 步骤指南
1. 先写测试确保现有功能正常
2. 小步快跑，每次只做一个重构
3. 重构后立即运行测试
4. 提交到版本控制
  • 知识结构化：专业经验被系统地组织
  • 可维护：人类和AI都能理解和更新
  • 可复用：多个Agent可以共享相同的技能库
  • 渐进式完善：可以不断积累和优化技能

架构演进与价值

从 AgentWithSubAgents 到 AgentWithSkills 的升级：

维度 AgentWithSubAgents AgentWithSkills
知识来源 内置在模型权重中 外部技能文件
知识更新 重新训练模型 修改文件即可
知识复用 无法复用 跨项目共享
专业性 通用能力 领域专家知识
上下文 动态生成 静态知识库

文章摘自：https://www.cnblogs.com/sevencoding/p/19821521

Java, kettle, SpringBoot, SpringCloud