首页 > 基础资料博客日记

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

2026-04-06 22:30:01基础资料围观1次

极客资料网推荐AI 编程助手 + 基于 CLI 的 Manus 实现（Java 版本）这篇文章给大家，欢迎收藏极客资料网享受知识的乐趣

一个轻量级、自包含的 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() 方法实现反应式循环：

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

┌──────────────┐
│   用户       │
│   查询       │
└──────┬───────┘
       ▼
┌──────────────┐
│    发送给    │◄─────────────┐
│     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

文章来源:https://www.cnblogs.com/ListenCode/p/19827115
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：jacktools123@163.com进行投诉反馈，一经查实，立即删除！

标签：

上一篇："Natural-Language Agent Harnesses" 论文笔记
下一篇：【读书笔记】【CUDA编程指南】CUDA简介

首页 > 基础资料博客日记

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

目录

功能特性

快速开始

环境要求

编译构建

配置

运行

配置说明

环境变量

.env 文件

Builder API

内置工具

代码工具

基础工具

工具调用格式

自定义工具

添加自定义工具

工具注解参考

架构设计

核心组件

Agent 循环

LLM 集成

项目结构

使用示例

交互模式

单次查询模式

编程方式调用

支持的模型

常见问题

相关文章

最新发布

点击排行

本站推荐

标签云

首页 > 基础资料 博客日记

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

目录

功能特性

快速开始

环境要求

编译构建

配置

运行

配置说明

环境变量

.env 文件

Builder API

内置工具

代码工具

基础工具

工具调用格式

自定义工具

添加自定义工具

工具注解参考

架构设计

核心组件

Agent 循环

LLM 集成

项目结构

使用示例

交互模式

单次查询模式

编程方式调用

支持的模型

常见问题

相关文章

最新发布

点击排行

本站推荐

标签云

首页 > 基础资料博客日记