AI 编程助手 + 基于 CLI 的 Manus 实现（Java 版本）

ThisIsTest2026-04-06 22:31

一个轻量级、自包含的 Agent 框架，可连接 LLM API（DeepSeek、GPT-4 等），通过基于反射的工具系统完成任务，支持交互式 CLI 和单次查询两种模式。

目录

功能特性

  • 代码代理：编写、编辑和管理代码文件
  • 系统代理：执行 Shell 命令、管理文件和目录
  • 交互式 CLI：自然对话界面，支持工具执行
  • 单次查询模式：通过命令行参数执行一次性任务
  • 多模型支持：DeepSeek、OpenAI GPT-4/3.5 及任何兼容 OpenAI 的 API
  • 可扩展工具系统：通过 @Tool 注解和反射机制添加自定义工具
  • 最小依赖：仅使用 Gson 进行 JSON 解析；基于 Java 17 标准库构建
  • 跨平台：支持 Windows、macOS 和 Linux

快速开始

环境要求

  • Java 17 或更高版本
  • Maven 3.6+
  • LLM API 密钥（DeepSeek、OpenAI 或兼容服务）

编译构建

复制代码 
mvn clean package

构建完成后，uber JAR 文件位于 target/miniagent-1.0.0.jar，包含所有依赖。

配置

在项目根目录创建 .env 文件：

复制代码 
cp .env.example .env

编辑 .env，填入你的 API 凭证：

复制代码 
LLM_API_KEY=your_api_key_here
LLM_MODEL=deepseek-chat
LLM_API_BASE=https://api.deepseek.com/v1

运行

交互模式（默认）：

复制代码 
java -jar target/miniagent-1.0.0.jar

单次查询模式：

复制代码 
java -jar target/miniagent-1.0.0.jar "创建一个 hello.py 文件，输出 Hello World"

配置说明

环境变量

变量 必填 默认值 说明
LLM_API_KEY 是 - LLM 提供商的 API 密钥
LLM_MODEL 否 deepseek-chat 模型标识符
LLM_API_BASE 否 https://api.deepseek.com/v1 API 基础地址
LLM_TEMPERATURE 否 0.7 采样温度（0.0-2.0）
LLM_MAX_ITERATIONS 否 10 最大 Agent 循环迭代次数

.env 文件

配置从当前目录的 .env 文件加载。环境变量优先级高于 .env 文件中的值。

复制代码 
LLM_API_KEY=sk-xxxxx
LLM_MODEL=deepseek-chat
LLM_API_BASE=https://api.deepseek.com/v1
LLM_TEMPERATURE=0.7
LLM_MAX_ITERATIONS=10

Builder API

编程方式调用时，使用 Builder 模式构建 Agent：

复制代码 
MiniAgent agent = MiniAgent.builder()
    .model("deepseek-chat")
    .apiKey("your-api-key")
    .baseUrl("https://api.deepseek.com/v1")
    .temperature(0.7)
    .maxIterations(10)
    .build();

内置工具

代码工具

工具 说明 参数
read 读取文件内容（带行号） path（必填）, offset（默认 1）, limit（默认 200）
write 写入文件内容（不存在则创建） path（必填）, content（必填）
edit 通过字符串替换编辑文件 path（必填）, old（必填）, newContent（必填）
glob 查找匹配 glob 模式的文件 pattern（必填）, path（默认 "."）
grep 在文件中搜索正则表达式 pattern（必填）, path（必填）
bash 执行 Shell 命令 cmd（必填）

基础工具

工具 说明 参数
calculator 计算数学表达式 expression（必填）
get_current_time 获取当前日期和时间 format（可选，默认 yyyy-MM-dd HH:mm:ss）
system_info 获取系统信息 （无）
file_stats 获取文件或目录统计信息 path（必填）
web_search 生成搜索 URL query（必填）
http_request 发起 HTTP GET 请求 url（必填）
clipboard_copy 复制文本到剪贴板 text（必填）

工具调用格式

Agent 使用结构化格式通信工具调用：

复制代码 
TOOL: <工具名称>
ARGS: {"参数名": "参数值"}

支持多种模式以提高 LLM 灵活性：

复制代码 
TOOL: calculator
ARGS: {"expression": "2 + 2"}

# 也支持：
TOL: calculator
ARGS: {"expression": "sqrt(16)"}

使用工具: calculator
参数: {"expression": "3 * 4"}

自定义工具

添加自定义工具

创建带有 @Tool 注解方法的类：

复制代码 
public class MyTools {

    @Tool(
        name = "my_tool",
        description = "我的工具的功能描述",
        paramDesc = "param1: 第一个参数\nparam2: 第二个参数"
    )
    public String myTool(String param1, int param2) {
        return "结果: " + param1 + param2;
    }

    @Tool(name = "file_exists", description = "检查文件是否存在")
    public boolean fileExists(String path) {
        return java.nio.file.Files.exists(java.nio.file.Paths.get(path));
    }
}

通过 Builder 加载自定义工具：

复制代码 
MiniAgent agent = MiniAgent.builder()
    .apiKey("your-api-key")
    .build()
    .loadTools(new CodeTools(), new BasicTools(), new MyTools());

工具注解参考

字段 类型 必填 说明
name String 否 工具名称（默认为方法名）
description String 是 人类可读的描述
paramDesc String 否 参数描述（每行一个）

架构设计

核心组件

复制代码 
┌─────────────────────────────────────────────────────────────┐
│                          Main                               │
│                     （入口程序）                              │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      Config                                 │
│           （.env + 环境变量配置）                              │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    MiniAgent                                │
│                  （核心 Agent 逻辑）                          │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ 工具解析器   │  │ 工具执行器    │  │ LLM 客户端       │   │
│  └─────────────┘  └──────────────┘  └──────────────────┘   │
└──────────────────────────┬──────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  ToolRegistry  │ │   LLMClient    │ │     CLI         │
│  （工具注册表） │ │ （LLM 客户端） │ │ （交互界面）    │
└─────────────────┘ └─────────────────┘ └─────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                      Tools                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  CodeTools   │  │ BasicTools   │  │  Custom Tools    │   │
│  │  （内置）     │  │  （内置）     │  │  （用户自定义）  │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Agent 循环

MiniAgent.run() 方法实现反应式循环：

  1. 系统提示词 - 加载默认提示词并追加可用工具列表

  2. 发送给 LLM - 调用 LLM API，传入查询和对话历史

  3. 解析响应 - 使用正则表达式从 LLM 输出中提取工具调用

  4. 执行工具 - 调用已注册的工具并捕获结果

  5. 反馈循环 - 将工具结果反馈给 LLM 进行下一次迭代

  6. 重复 - 继续直到达到最大迭代次数或收到最终答案

    ┌──────────────┐
    │ 用户 │
    │ 查询 │
    └──────┬───────┘
    ▼
    ┌──────────────┐
    │ 发送给 │◄─────────────┐
    │ LLM │ │
    └──────┬───────┘ │
    ▼ │
    ┌──────────────┐ ┌─────────┴─────────┐
    │ 解析 LLM │───►│ 发现工具调用？ │
    │ 响应 │ └─────────┬───────────┘
    └──────────────┘ │
    │ ┌───────┴───────┐
    │ │ │
    ▼ ▼ ▼
    ┌──────────────┐ ┌──────────┐ ┌─────────────┐
    │ 返回 │ │ 执行 │ │ 将工具结果 │
    │ 最终答案 │ │ 工具 │ │ 反馈给 LLM │
    └──────────────┘ └────┬─────┘ └─────────────┘
    │
    ▼
    ┌──────────────┐
    │ 达到最大 │
    │ 迭代次数？ │
    └──────┬───────┘
    │ 否
    ▼
    ┌──────────────┐
    │ 下一轮 │
    │ 迭代 │
    └──────────────┘

LLM 集成

  • 接口：LLMClient 定义聊天协议
  • 实现：OpenAICompatibleClient 使用 Java 11+ HttpClient
  • 协议：OpenAI Chat Completions API（/v1/chat/completions）
  • 认证：Authorization 头中的 Bearer Token
  • 模型：DeepSeek、GPT-4、GPT-3.5 及任何兼容 OpenAI 的 API

项目结构

复制代码 
miniagent-java/
├── pom.xml                                          # Maven 构建配置
├── .env.example                                     # 环境变量示例文件
├── .env                                             # 你的环境变量文件（已被 gitignore）
├── README.md                                        # 英文文档
├── README_zh.md                                     # 中文文档
└── src/main/java/com/example/miniagent/
    ├── Main.java                                    # 入口程序
    ├── MiniAgent.java                               # 核心 Agent 逻辑（约 285 行）
    ├── Tool.java                                    # @Tool 注解定义
    ├── ToolRegistry.java                            # 全局工具注册表
    ├── ToolCall.java                                # 工具调用数据类
    ├── config/
    │   └── Config.java                              # 配置加载器
    ├── cli/
    │   └── CLI.java                                 # 交互式 CLI 接口
    ├── llm/
    │   ├── LLMClient.java                          # LLM 客户端接口
    │   └── OpenAICompatibleClient.java             # LLM API HTTP 客户端
    └── tools/
        ├── CodeTools.java                           # 文件/代码操作工具
        └── BasicTools.java                          # 基础工具

使用示例

交互模式

复制代码 
$ java -jar target/miniagent-1.0.0.jar

╔══════════════════════════════════════════════════════╗
║                    MiniAgent                         ║
║              AI 编程助手（Java 版本）                   ║
╚══════════════════════════════════════════════════════╝

Available Tools:
================
  • read - 读取文件内容（带行号）
  • write - 写入文件内容
  • edit - 通过字符串替换编辑文件
  • glob - 查找匹配模式的文件
  • grep - 在文件中搜索模式
  • bash - 执行 Shell 命令
  • calculator - 计算数学表达式
  ...

Commands:
  help  - 显示帮助信息
  tools - 列出可用工具
  exit  - 退出程序

you: 创建一个 hello.py 文件

Assistant: TOOL: write
ARGS: {"path": "hello.py", "content": "print('Hello, World!')"}

[Tool Result] ok

文件 hello.py 已成功创建。

单次查询模式

复制代码 
$ java -jar target/miniagent-1.0.0.jar "现在几点了？"

Query: 现在几点了？
==================================================
[Iteration 1/10] 思考中...
[Assistant Response]
TOOL: get_current_time
ARGS: {"format": "yyyy-MM-dd HH:mm:ss"}

[Executing Tool] get_current_time
[Tool Result] 2026-04-06 12:34:56

现在是 2026-04-06 12:34:56。

编程方式调用

复制代码 
import com.example.miniagent.*;

public class Example {
    public static void main(String[] args) {
        // 构建 Agent
        MiniAgent agent = MiniAgent.builder()
            .model("deepseek-chat")
            .apiKey(System.getenv("LLM_API_KEY"))
            .temperature(0.7)
            .maxIterations(5)
            .build();

        // 加载内置工具和自定义工具
        agent.loadTools(new CodeTools(), new BasicTools());

        // 执行单次查询
        String result = agent.run("创建一个 config.json 文件，包含基本配置");
        System.out.println(result);

        // 或使用交互式 CLI
        CLI.interactive(agent);
    }
}

支持的模型

提供商 模型 API 基础地址
DeepSeek deepseek-chat https://api.deepseek.com/v1
OpenAI gpt-4, gpt-4-turbo, gpt-3.5-turbo https://api.openai.com/v1
Azure Azure OpenAI 端点 你的 Azure 端点
本地模型 任何 Ollama 或 LocalAI 模型 http://localhost:11434/v1

使用 Ollama 本地模型：

复制代码 
LLM_API_KEY=ollama  # 不使用但必填
LLM_MODEL=llama3
LLM_API_BASE=http://localhost:11434/v1

常见问题

"API key is required" 错误

确保 .env 文件存在且 LLM_API_KEY 已设置，或设置 LLM_API_KEY 环境变量。

工具未找到错误

检查工具类是否通过 agent.loadTools() 加载。交互模式下可使用 tools 命令查看已加载的工具列表。

LLM API 错误

  • 验证 API 密钥是否有效
  • 检查 LLM_API_BASE 是否与你的提供商匹配
  • 确保网络可以访问 API 端点

github 地址 : https://github.com/TensorCode666/miniagent-java

欢迎提issue

热门推荐
01GitHub 镜像站点02OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程03Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）04VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）05【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线06最新更新版本，OpenClaw v2026.4.2 深度解读剖析：Task Flow 重磅回归与安全架构的全面硬化07Claude Code 未登录 使用第三方模型08AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南09纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！10UV安装并设置国内源