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

KDLM79pz1

354人浏览 · 2026-04-07 13:22:47

KDLM79pz1 · 2026-04-07 13:22:47 发布

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

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

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

1 2	`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 命令查看已加载的工具列表。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

零售销量预测为何选LightGBM

该零售销量预测 API 基于模型构建。具体而言，作者阳明山水在博文中明确提到，其解决方案是基于真实零售数据训练了“两个高性能模型（LightGBM）”，并将它们封装成简单易用的 API 供开发者调用。LightGBM 是一种基于梯度提升决策树（Gradient Boosting Decision Tree, GBDT）的高效机器学习框架，由微软公司开发并开源。

AtomGit开源社区

磨针AI获客和SEO优化哪个效果好？5大维度实测数据对比，90%的企业主选错了

如果你急需客户、预算有限、产品面向C端或B端中小客户：请毫不犹豫地选择磨针AI获客。它在“见效速度”和“获客成本”上，对传统SEO形成了碾压式优势。根据【2024年企业获客效率调研】，使用AI获客工具的企业，平均获客周期缩短约70%，成本降低约60%。如果你是大品牌、预算充裕、目标在于长期品牌建设：可以继续保留SEO团队，但强烈建议引入磨针AI获客作为“弹药库”，为SEO团队提供精准的用户需求洞察

AtomGit开源社区

磨针AI获客 vs 谷歌SEO：2026外贸企业如何选对“流量引擎”？

如果你是“生存型”企业首选磨针AI获客。它能让你在1-2周内看到效果，快速回血。如果你是“发展型”企业磨针AI获客 + 谷歌SEO双轮驱动。先用AI拿订单，再用SEO建品牌。如果你是“土豪型”企业谷歌SEO为主，AI获客为辅。在2024年这个AI席卷一切的时代，你还在用“农耕时代”的谷歌SEO苦苦等待，还是愿意尝试“AI时代”的磨针AI获客，主动出击？不妨在评论区分享你的获客故事，我们一起探讨。-