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

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

• 功能特性
  
• 快速开始
  
  
  
  • 环境要求
    
  • 编译构建
    
  • 配置
    
  • 运行
    
  
  
• 配置说明
  
  
  
  • 环境变量
    
  • .env 文件
    
  • Builder API
    
  
  
• 内置工具
  
  
  
  • 代码工具
    
  • 基础工具
    
  • 工具调用格式
    
  
  
• 自定义工具
  
  
  
  • 添加自定义工具
    
  • 工具注解参考
    
  
  
• 架构设计
  
  
  
  • 核心组件
    
  • Agent 循环
    
  • LLM 集成
    
  • 项目结构
    
  
  
• 使用示例
  
  
  
  • 交互模式
    
  • 单次查询模式
    
  • 编程方式调用
    
  
  
• 支持的模型
  
• 常见问题
  
• 许可证
  

功能特性

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

1. cp .env.example .env

复制代码

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

1. LLM_API_KEY=your_api_key_here
2. LLM_MODEL=deepseek-chat
3. 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/v1API 基础地址LLM_TEMPERATURE否0.7采样温度（0.0-2.0）LLM_MAX_ITERATIONS否10最大 Agent 循环迭代次数.env 文件

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

1. LLM_API_KEY=sk-xxxxx
2. LLM_MODEL=deepseek-chat
3. LLM_API_BASE=https://api.deepseek.com/v1
4. LLM_TEMPERATURE=0.7
5. LLM_MAX_ITERATIONS=10

复制代码

　　
 Builder API

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

1. MiniAgent agent = MiniAgent.builder()
2.     .model("deepseek-chat")
3.     .apiKey("your-api-key")
4.     .baseUrl("https://api.deepseek.com/v1")
5.     .temperature(0.7)
6.     .maxIterations(10)
7.     .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生成搜索 URLquery（必填）http_request发起 HTTP GET 请求url（必填）clipboard_copy复制文本到剪贴板text（必填）工具调用格式

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

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

复制代码

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

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

复制代码

　
自定义工具

添加自定义工具

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

1. public class MyTools {
3.     @Tool(
4.         name = "my_tool",
5.         description = "我的工具的功能描述",
6.         paramDesc = "param1: 第一个参数\nparam2: 第二个参数"
7.     )
8.     public String myTool(String param1, int param2) {
9.         return "结果: " + param1 + param2;
10.     }
12.     @Tool(name = "file_exists", description = "检查文件是否存在")
13.     public boolean fileExists(String path) {
14.         return java.nio.file.Files.exists(java.nio.file.Paths.get(path));
15.     }
16. }

复制代码

　　
 通过 Builder 加载自定义工具：

1. MiniAgent agent = MiniAgent.builder()
2.     .apiKey("your-api-key")
3.     .build()
4.     .loadTools(new CodeTools(), new BasicTools(), new MyTools());

复制代码

　　
 工具注解参考

字段类型必填说明nameString否工具名称（默认为方法名）descriptionString是人类可读的描述paramDescString否参数描述（每行一个）架构设计

核心组件

1. ┌─────────────────────────────────────────────────────────────┐
2. │                          Main                               │
3. │                     （入口程序）                              │
4. └──────────────────────────┬──────────────────────────────────┘
5.                            │
6.                            ▼
7. ┌─────────────────────────────────────────────────────────────┐
8. │                      Config                                 │
9. │           （.env + 环境变量配置）                              │
10. └──────────────────────────┬──────────────────────────────────┘
11.                            │
12.                            ▼
13. ┌─────────────────────────────────────────────────────────────┐
14. │                    MiniAgent                                │
15. │                  （核心 Agent 逻辑）                          │
16. │  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
17. │  │ 工具解析器   │  │ 工具执行器    │  │ LLM 客户端       │   │
18. │  └─────────────┘  └──────────────┘  └──────────────────┘   │
19. └──────────────────────────┬──────────────────────────────────┘
20.                            │
21.          ┌─────────────────┼─────────────────┐
22.          ▼                 ▼                 ▼
23. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
24. │  ToolRegistry  │ │   LLMClient    │ │     CLI         │
25. │  （工具注册表） │ │ （LLM 客户端） │ │ （交互界面）    │
26. └─────────────────┘ └─────────────────┘ └─────────────────┘
27.          │
28.          ▼
29. ┌─────────────────────────────────────────────────────────────┐
30. │                      Tools                                   │
31. │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
32. │  │  CodeTools   │  │ BasicTools   │  │  Custom Tools    │   │
33. │  │  （内置）     │  │  （内置）     │  │  （用户自定义）  │   │
34. │  └──────────────┘  └──────────────┘  └──────────────────┘   │
35. └─────────────────────────────────────────────────────────────┘

复制代码

 Agent 循环

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

• 系统提示词 - 加载默认提示词并追加可用工具列表
  
• 发送给 LLM - 调用 LLM API，传入查询和对话历史
  
• 解析响应 - 使用正则表达式从 LLM 输出中提取工具调用
  
• 执行工具 - 调用已注册的工具并捕获结果
  
• 反馈循环 - 将工具结果反馈给 LLM 进行下一次迭代
  
• 重复 - 继续直到达到最大迭代次数或收到最终答案
  

1. ┌──────────────┐
2. │   用户       │
3. │   查询       │
4. └──────┬───────┘
5.        ▼
6. ┌──────────────┐
7. │    发送给    │◄─────────────┐
8. │     LLM      │             │
9. └──────┬───────┘             │
10.        ▼                     │
11. ┌──────────────┐    ┌─────────┴─────────┐
12. │  解析 LLM   │───►│ 发现工具调用？       │
13. │  响应       │    └─────────┬───────────┘
14. └──────────────┘              │
15.        │              ┌───────┴───────┐
16.        │              │               │
17.        ▼              ▼               ▼
18. ┌──────────────┐ ┌──────────┐ ┌─────────────┐
19. │   返回      │ │  执行     │ │  将工具结果 │
20. │ 最终答案    │ │  工具     │ │  反馈给 LLM │
21. └──────────────┘ └────┬─────┘ └─────────────┘
22.                       │
23.                       ▼
24.                ┌──────────────┐
25.                │   达到最大   │
26.                │   迭代次数？ │
27.                └──────┬───────┘
28.                       │ 否
29.                       ▼
30.                ┌──────────────┐
31.                │   下一轮    │
32.                │   迭代      │
33.                └──────────────┘

复制代码

 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. miniagent-java/
2. ├── pom.xml                                          # Maven 构建配置
3. ├── .env.example                                     # 环境变量示例文件
4. ├── .env                                             # 你的环境变量文件（已被 gitignore）
5. ├── README.md                                        # 英文文档
6. ├── README_zh.md                                     # 中文文档
7. └── src/main/java/com/example/miniagent/
8.     ├── Main.java                                    # 入口程序
9.     ├── MiniAgent.java                               # 核心 Agent 逻辑（约 285 行）
10.     ├── Tool.java                                    # @Tool 注解定义
11.     ├── ToolRegistry.java                            # 全局工具注册表
12.     ├── ToolCall.java                                # 工具调用数据类
13.     ├── config/
14.     │   └── Config.java                              # 配置加载器
15.     ├── cli/
16.     │   └── CLI.java                                 # 交互式 CLI 接口
17.     ├── llm/
18.     │   ├── LLMClient.java                          # LLM 客户端接口
19.     │   └── OpenAICompatibleClient.java             # LLM API HTTP 客户端
20.     └── tools/
21.         ├── CodeTools.java                           # 文件/代码操作工具
22.         └── BasicTools.java                          # 基础工具

复制代码

　　
 使用示例

交互模式

1. $ java -jar target/miniagent-1.0.0.jar
3. ╔══════════════════════════════════════════════════════╗
4. ║                    MiniAgent                         ║
5. ║              AI 编程助手（Java 版本）                   ║
6. ╚══════════════════════════════════════════════════════╝
8. Available Tools:
9. ================
10.   • read - 读取文件内容（带行号）
11.   • write - 写入文件内容
12.   • edit - 通过字符串替换编辑文件
13.   • glob - 查找匹配模式的文件
14.   • grep - 在文件中搜索模式
15.   • bash - 执行 Shell 命令
16.   • calculator - 计算数学表达式
17.   ...
19. Commands:
20.   help  - 显示帮助信息
21.   tools - 列出可用工具
22.   exit  - 退出程序
24. you: 创建一个 hello.py 文件
26. Assistant: TOOL: write
27. ARGS: {"path": "hello.py", "content": "print('Hello, World!')"}
29. [Tool Result] ok
31. 文件 hello.py 已成功创建。

复制代码

　　
 单次查询模式

1. $ java -jar target/miniagent-1.0.0.jar "现在几点了？"
3. Query: 现在几点了？
4. ==================================================
5. [Iteration 1/10] 思考中...
6. [Assistant Response]
7. TOOL: get_current_time
8. ARGS: {"format": "yyyy-MM-dd HH:mm:ss"}
10. [Executing Tool] get_current_time
11. [Tool Result] 2026-04-06 12:34:56
13. 现在是 2026-04-06 12:34:56。

复制代码

　　
 编程方式调用

1. import com.example.miniagent.*;
3. public class Example {
4.     public static void main(String[] args) {
5.         // 构建 Agent
6.         MiniAgent agent = MiniAgent.builder()
7.             .model("deepseek-chat")
8.             .apiKey(System.getenv("LLM_API_KEY"))
9.             .temperature(0.7)
10.             .maxIterations(5)
11.             .build();
13.         // 加载内置工具和自定义工具
14.         agent.loadTools(new CodeTools(), new BasicTools());
16.         // 执行单次查询
17.         String result = agent.run("创建一个 config.json 文件，包含基本配置");
18.         System.out.println(result);
20.         // 或使用交互式 CLI
21.         CLI.interactive(agent);
22.     }
23. }

复制代码

　　
 支持的模型

提供商模型API 基础地址DeepSeekdeepseek-chathttps://api.deepseek.com/v1OpenAIgpt-4, gpt-4-turbo, gpt-3.5-turbohttps://api.openai.com/v1AzureAzure OpenAI 端点你的 Azure 端点本地模型任何 Ollama 或 LocalAI 模型http://localhost:11434/v1使用 Ollama 本地模型：

1. LLM_API_KEY=ollama  # 不使用但必填
2. LLM_MODEL=llama3
3. 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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！