【从0到1构建一个ClaudeAgent】规划与协调-技能
<p>这里解决了 Agent 开发中的一个核心痛点：<strong>上下文窗口限制与知识广度的矛盾</strong>。</p><h2 id="java-实现代码">Java 实现代码</h2>
<pre><code class="language-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.trim();
String val = parts.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;
}
}
</code></pre>
<p>这段代码引入了<strong>知识分层</strong>和<strong>懒加载</strong>的概念，这是解决 LLM 上下文限制（Context Window）的关键策略。</p>
<h2 id="技能系统架构skillloader">技能系统架构：SkillLoader</h2>
<p><strong>核心思想</strong>：引入<strong>外部知识库系统</strong>，将专业知识和经验以结构化的"技能"文件形式存储，让Agent能够<strong>动态学习和复用专业知识</strong>，实现"知识外挂"。</p>
<pre><code class="language-java">// 技能实体 - 知识的结构化表示
public static class Skill {
public String name; // 技能名称
public String description; // 简短描述
public String tags; // 分类标签
public String body; // 技能的具体指令内容
public Path path; // 文件路径
// 结构化知识：名称、描述、标签、内容四位一体
// 文件存储：技能存储在外部文件中，易于管理和更新
}
</code></pre>
<pre><code class="language-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());
}
}
}
</code></pre>
<ul>
<li><strong>知识外化</strong>：将AI的专业知识存储在外部文件，而不是硬编码在代码中</li>
<li><strong>动态加载</strong>：程序启动时自动扫描技能目录</li>
<li><strong>约定驱动</strong>：通过文件名<code>SKILL.md</code>标识技能文件</li>
<li><strong>结构化管理</strong>：用面向对象的方式管理技能</li>
</ul>
<h2 id="技能文件格式与解析">技能文件格式与解析</h2>
<pre><code class="language-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.trim();
String val = parts.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);
}
}
</code></pre>
<ul>
<li><strong>元数据+内容</strong>：YAML Frontmatter + Markdown内容的标准格式</li>
<li><strong>灵活兼容</strong>：支持有/无元数据的文件格式</li>
<li><strong>默认命名</strong>：用文件夹名作为默认技能名</li>
<li><strong>容错解析</strong>：解析失败不影响整体运行</li>
</ul>
<h2 id="双层级技能访问模式">双层级技能访问模式</h2>
<pre><code class="language-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识别
// 错误提示：提供可用技能列表
}
</code></pre>
<ul>
<li><strong>摘要模式</strong>：先看目录，再决定获取哪个详情</li>
<li><strong>渐进式披露</strong>：避免一次性暴露所有信息污染上下文</li>
<li><strong>标签化</strong>：用<code><skill></code>标签标注内容来源</li>
<li><strong>自描述错误</strong>：未知技能时返回可用列表</li>
</ul>
<h2 id="技能系统集成">技能系统集成</h2>
<pre><code class="language-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);
// 专用工具：为技能系统创建专门的工具
// 简单接口：只需要技能名一个参数
}
</code></pre>
<ul>
<li><strong>动态上下文</strong>：系统提示词根据实际技能动态生成</li>
<li><strong>工具化访问</strong>：将知识获取抽象为工具调用</li>
<li><strong>简单接口</strong>：最小化的参数设计</li>
<li><strong>与基础工具并存</strong>：技能工具和操作工具在同一系统中</li>
</ul>
<h2 id="技能文件示例">技能文件示例</h2>
<pre><code class="language-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. 提交到版本控制
</code></pre>
<ul>
<li><strong>知识结构化</strong>：专业经验被系统地组织</li>
<li><strong>可维护</strong>：人类和AI都能理解和更新</li>
<li><strong>可复用</strong>：多个Agent可以共享相同的技能库</li>
<li><strong>渐进式完善</strong>：可以不断积累和优化技能</li>
</ul>
<h2 id="架构演进与价值">架构演进与价值</h2>
<p><strong>从 AgentWithSubAgents 到 AgentWithSkills 的升级</strong>：</p>
<table>
<thead>
<tr>
<th>维度</th>
<th>AgentWithSubAgents</th>
<th>AgentWithSkills</th>
</tr>
</thead>
<tbody>
<tr>
<td>知识来源</td>
<td>内置在模型权重中</td>
<td>外部技能文件</td>
</tr>
<tr>
<td>知识更新</td>
<td>重新训练模型</td>
<td>修改文件即可</td>
</tr>
<tr>
<td>知识复用</td>
<td>无法复用</td>
<td>跨项目共享</td>
</tr>
<tr>
<td>专业性</td>
<td>通用能力</td>
<td>领域专家知识</td>
</tr>
<tr>
<td>上下文</td>
<td>动态生成</td>
<td>静态知识库</td>
</tr>
</tbody>
</table>
</div>
<div id="MySignature" role="contentinfo">
<p>本文来自在线网站：seven的菜鸟成长之路，作者：seven，转载请注明原文链接：www.seven97.top</p><br><br>
来源：https://www.cnblogs.com/sevencoding/p/19821521
頁:
[1]