SmartCLI · Java Agent CLI

面向 Java 项目的本地命令行编程 Agent，支持自然语言驱动代码检索、任务规划、代码修改与自动诊断，从 0 到 1 实现「需求分析 → 代码交付」的自动化开发流程。

SmartCLI 是一个用纯 Java 从零实现的 本地 CLI 编程 Agent，对标 Claude Code / Cursor 这类 AI 编程助手，但完全运行在本地终端。它不只是一个「套壳 LLM 的聊天框」，而是完整实现了 ReAct 推理、Plan-and-Execute 规划、Multi-Agent 协作、三层记忆系统、代码库 RAG 检索、MCP 工具协议与 HITL 人工审批等 Agent 核心能力。

---

技术栈

• 语言：Java 17
• Agent 范式：ReAct · Plan-and-Execute · Multi-Agent
• 工具协议：MCP（stdio + Streamable HTTP）
• 代码解析：JavaParser（AST 分析）
• 持久化：SQLite（向量 / 关系图谱 / 长期记忆）
• 分词：Jieba 分词（中文检索）
• HTTP：OkHttp
• 终端交互：JLine 3（TUI、补全、历史）
• 检索：BM25 + 余弦相似度混合检索
• 测试：JUnit 5

---

核心能力

1. ReAct 推理 + 动态 Token 预算 + 上下文压缩

基于 ReAct（Reasoning + Acting）范式实现 Agent 的「思考-行动-观察」循环：

• 并行执行：同一轮 LLM 返回多个 tool_calls 时，工具层并行执行；
• 动态 Token 预算：AgentBudget 按当前模型动态计算预算（默认 80% * maxContextWindow），支持 DeepSeek 1M、GLM 200k 等不同窗口；
• 上下文压缩：当上下文占用达到 90% 时自动触发 Map-Reduce 压缩——先把长对话按语义分段（Map）逐段摘要，再合并成连贯摘要（Reduce），在压缩体积的同时保障上下文连贯性。

2. 三层记忆系统

层	职责	实现
短期记忆	管理当前对话与工具结果	ConversationMemory
长期记忆	跨会话持久化关键事实	SQLite 持久化 LongTermMemory
边界感知压缩	对话接近预算时的上下文压缩	ConversationHistoryCompactor / ContextCompressor

长期记忆检索采用 BM25 + 余弦相似度混合检索，既支持关键词精确命中，也支持语义模糊回忆。通过 /save <事实> 或用户明确说「记一下 / 记住」即可保存跨会话知识。

3. Plan-and-Execute + Multi-Agent 架构

• Planner 将复杂任务拆解为 DAG（有向无环图），表达任务间的依赖关系；
• Worker 按依赖批次并行执行独立任务，最大并行 4 线程；
• Reviewer 审核产出质量，未通过时自动重试（带反馈，最多 2 次），冲突自动解决；
• 编排器（Orchestrator）协调多个子代理（SubAgent），形成主从协作架构。

        ┌──────────┐
        │ 用户需求  │
        └────┬─────┘
             ▼
        ┌──────────┐     拆解为 DAG
        │ Planner  │ ──────────────────┐
        └────┬─────┘                   │
             │                         ▼
        ┌────▼─────┐           ┌──────────────┐
        │Orchestrator│         │ Task DAG      │
        └────┬─────┘           │  A → B → D    │
             │                 │   ↘ C ↗       │
      ┌──────┼──────┐          └──────┬───────┘
      ▼      ▼      ▼                 │ 并行调度
   Worker  Worker  Worker ◄───────────┘
      │      │      │
      └──────┼──────┘
             ▼
        ┌──────────┐     审核 + 自动重试
        │ Reviewer │
        └──────────┘

4. RAG 检索封装为 search_code 工具

把 RAG 能力封装为 search_code 工具注册到 Agent 工具集，通过 LLM 系统提示词引导其在需要时自动触发检索：

• 代码向量化：Embedding 支持本地 Ollama 与远程 API；
• 代码分块：文件 / 类 / 方法粒度，配合 JavaParser 做 AST 解析；
• 代码关系图谱：抽取 extends / implements / imports / calls / contains 关系；
• 双模式适配：ReAct 与 Plan-and-Execute 两种执行范式都支持代码库理解；
• 精确代码定位仍默认走 glob_files / grep_code / read_file 现用现查，语义检索作为辅助增强。

5. HITL 人工审批（高风险操作护栏）

针对文件修改、Shell 执行等高风险 Tool 增加 Human-in-the-Loop 人工审批，限制 Agent 的自主操作范围：

• 危险操作静态识别：write_file、execute_command、create_project、revert_turn；
• 三级危险等级：高危（execute_command）、中危（write_file / create_project）；
• 审批决策：批准 / 全部放行 / 拒绝 / 跳过 / 修改参数后执行；
• 默认关闭，通过 /hitl on 启用；审计参数自动脱敏 token / key / password 等凭证。

6. MCP 工具协议（可扩展工具生态）

内置完整的 MCP（Model Context Protocol）客户端，支持 stdio 子进程 server 与 Streamable HTTP 远程 server，可动态接入任意 MCP 工具（如浏览器自动化 Chrome DevTools MCP），工具自动注册为 mcp__{server}__{tool} 供 Agent 调用。

---

项目结构

src/main/java/com/hechengyi/smartcli
├── agent/               # ReAct / Plan-and-Execute / Multi-Agent 编排
├── cli/                 # CLI 入口、命令解析、补全、历史
├── llm/                 # 多模型客户端（DeepSeek/GLM/Step/Kimi...）
├── context/             # 上下文模式与 Token 预算
├── memory/              # 三层记忆系统
├── plan/                # Planner / Task / ExecutionPlan（DAG）
├── rag/                 # 代码向量化 / 分块 / AST 分析 / 检索
├── mcp/                 # MCP 协议核心（jsonrpc / transport / resources）
├── hitl/                # 人工审批流
├── tool/                # 工具注册表与代码搜索引擎
└── tui/                 # 终端界面（pane / highlight / history）

---

快速开始

构建

mvn clean package
# 默认跳过测试，产出可手工验收的 jar

运行

java -jar target/smartcli-1.0.0.jar

常用命令

命令	说明
/plan	进入 Plan-and-Execute 规划模式
/team	进入 Multi-Agent 协作模式
/memory	查看 / 管理长期记忆
/save <事实>	保存跨会话事实
/index /search /graph	代码索引 / 检索 / 关系图谱
/hitl on	开启高风险操作人工审批
/mcp	管理 MCP 工具服务
/model <provider>	切换 LLM 模型

---

作者

• 贺程义 (HeChengyi0109) · hechengyi2002@163.com
• 项目主页：https://github.com/HeChengyi0109/SmartCLI

License

Apache License 2.0