功能特性

• 代码代理：编写、编辑和管理代码文件
• 系统代理：执行 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 或兼容服务）

编译构建

1	mvn clean package

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

配置

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

cp .env.example .env

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

1 2 3

LLM_API_KEY=your_api_key_here LLM_MODEL=deepseek-chat LLM_API_BASE=https://api.deepseek.com/v1

运行

交互模式（默认）：

1	java -jar target/miniagent-1.0.0.jar

　　

单次查询模式：

1	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 文件中的值。

1 2 3 4 5

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：

1 2 3 4 5 6 7

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 使用结构化格式通信工具调用：

1 2	TOOL: <工具名称> ARGS: {"参数名": "参数值"}

　　

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

1 2 3 4 5 6 7 8 9

TOOL: calculator ARGS: {"expression": "2 + 2"} # 也支持： TOL: calculator ARGS: {"expression": "sqrt(16)"} 使用工具: calculator 参数: {"expression": "3 * 4"}

　

自定义工具

添加自定义工具

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

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 加载自定义工具：

1 2 3 4

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

项目结构

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

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 逻