MineCode：一个极简的 Java AI 代码代理

MineCode：用 Java 17 打造极简 AI 代码代理

从 Claude Code 和 AgentScope 中汲取灵感，用 14,000 行代码诠释 AI Agent 的核心设计模式

---

引言

MineCode 是一个用 Java 17 实现的 AI 代码代理框架。项目的初衷很简单：把 Claude Code 的设计模式和 AgentScope 的架构思想提炼出来，写成一个清晰、易懂的代码库。如果你对 AI Agent 的实现原理感兴趣，或者想在 Java 项目中集成代码代理能力，可以试试这个项目。

项目亮点

极简而不简单

• 14,155 行核心代码，清晰展示 AI Agent 的完整架构
• 85 个 Java 源文件，模块化设计，易于理解
• 零外部依赖臃肿，仅依赖 JDK 内置 HttpClient 和 Jackson

生产级功能支持

模块	能力
ReAct 循环	持续对话直至任务完成
工具系统	7 个内置工具，支持 @Tool 注解扩展
Hook 系统	9 种事件、6 个内置 Hook，Sealed Class 类型安全
上下文管理	3 层智能压缩，支持长对话场景
任务规划	PlanNotebook + LLM 自动分解
多模型支持	OpenAI / Claude / DeepSeek / Ollama 一键切换

---

核心设计：ReAct 循环

MineCode 采用经典的 Reasoning + Acting 循环架构：

用户输入 → LLM 推理 → 工具调用 → 执行结果 → 继续推理 → ... → 最终答案

核心代码仅需几行：

public String chat(String userInput) {
    messages.add(userMessage);

    for (int round = 0; round < maxRounds; round++) {
        LLMResponse response = llm.chat(messages, tools);

        // 无工具调用 → LLM 认为任务完成
        if (!response.hasToolCalls()) {
            return response.content();
        }

        // 执行工具并继续循环
        for (ToolCall tc : response.toolCalls()) {
            String result = executeTool(tc);
            addToolResult(tc, result);
        }
    }
    return "(达到最大轮数)";
}

---

创新特性：搜索替换编辑

Claude Code 的关键创新——搜索替换编辑，解决了传统文件编辑方式的痛点：

方式	问题
整体重写	Token 消耗大，不精确
行号编辑	行号易变化，不稳定
diff 补丁	解析复杂，易出错

MineCode 实现了这一创新：LLM 指定精确的子字符串及其替换，必须唯一匹配才能执行，既精确又安全。

---

Hook 系统：事件驱动的扩展能力

Java 17 的 Sealed Class + Switch 模式匹配 让 Hook 系统如虎添翼：

HookEvent result = switch (event) {
    case PreReasoningEvent e -> handlePreReasoning(e);
    case PostReasoningEvent e -> handlePostReasoning(e);
    case PreActingEvent e -> handlePreActing(e);
    case PostActingEvent e -> handlePostActing(e);
    case InterruptedEvent e -> handleInterrupt(e);
    default -> event;
};

内置 6 个实用 Hook：

• LoggingHook - 执行日志
• TokenStatsHook - Token 统计
• TimingHook - 执行时间统计
• HumanInTheLoopHook - 人工介入确认
• LoopDetectionHook - 无限循环检测
• RetryHook - 错误自动重试

---

快速上手

环境要求

• Java 17+
• Maven 3.6+

一键运行

# 配置 API Key
export OPENAI_API_KEY=sk-...

# 编译运行
mvn clean package -DskipTests
java -jar target/minecode-1.0.0.jar

代码示例

// 1. 创建 LLM 客户端
LLMClient llm = LLMClient.builder()
    .fromEnv()
    .model("gpt-4o")
    .build();

// 2. 创建 Agent
Agent agent = Agent.builder()
    .llm(llm)
    .hook(new BuiltinHooks.LoggingHook(true))
    .hook(new BuiltinHooks.TokenStatsHook())
    .maxRounds(30)
    .build();

// 3. 开始对话
String response = agent.chat("帮我写一个快速排序算法");
System.out.println(response);

---

多模型支持

轻松切换不同的 LLM 后端：

# OpenAI
export OPENAI_API_KEY=sk-...

# DeepSeek
export OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-...

# Ollama（本地模型）
export OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1

---

扩展指南

添加自定义工具

@Tool(name = "my_tool", description = "工具描述")
public String myMethod(
    @ToolParam(name = "arg1", description = "参数1") String arg1) {
    return "执行结果";
}

添加自定义技能

public class MySkill implements Skill {
    @Override
    public String name() { return "my"; }

    @Override
    public String execute(SkillContext context, String args) {
        return "技能执行结果";
    }
}

---

技术栈

组件	技术选型	理由
HTTP Client	Java HttpClient	JDK 内置，支持 SSE
JSON	Jackson	生态成熟
CLI	Picocli + JLine	REPL 支持
日志	SLF4J + Logback	行业标准
并发	CompletableFuture	并行工具执行
Java 版本	Java 17	sealed class、switch 模式匹配

---

为什么选择 MineCode？

1. 教育价值 - 清晰的代码结构，适合学习 AI Agent 架构
2. 生产可用 - 完整的功能集，支持实际项目开发
3. 易于扩展 - 清晰的接口设计，快速添加自定义能力
4. Java 生态 - 无缝融入现有 Java 项目

---

项目资源

• GitHub: MineCode
• 架构文档: ARCHITECTURE.md
• License: MIT

---

参考资料

• NanoCoder - Claude Code 极简实现
• AgentScope - 阿里巴巴多智能体框架
• Claude Code 源码分析

---

MineCode —— 用最少的代码，诠释最纯粹的 AI Agent 设计。