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

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

Java 实现代码

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能够动态学习和复用专业知识，实现"知识外挂"。

java

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

java

// 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标识技能文件
• 结构化管理：用面向对象的方式管理技能

技能文件格式与解析

java

// 技能文件解析 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内容的标准格式
• 灵活兼容：支持有/无元数据的文件格式
• 默认命名：用文件夹名作为默认技能名
• 容错解析：解析失败不影响整体运行

双层级技能访问模式

java

// 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>标签标注内容来源
• 自描述错误：未知技能时返回可用列表

技能系统集成

java

// 系统提示词动态注入技能列表 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); // 专用工具：为技能系统创建专门的工具 // 简单接口：只需要技能名一个参数 }

• 动态上下文：系统提示词根据实际技能动态生成
• 工具化访问：将知识获取抽象为工具调用
• 简单接口：最小化的参数设计
• 与基础工具并存：技能工具和操作工具在同一系统中

技能文件示例

markdown

--- 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 的升级：