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

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

引言

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

项目亮点

极简而不简单

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

生产级功能支持

核心设计：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 的关键创新——搜索替换编辑，解决了传统文件编辑方式的痛点：

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=

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-...

# Ollama（本地模型）
export OPENAI_API_KEY=ollama OPENAI_BASE_URL=

扩展指南

添加自定义工具

@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 "技能执行结果";
    }
}

技术栈

为什么选择 MineCode？

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

项目资源

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

参考资料

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