omniAgent：全本地部署的开源 AI Agent，让大模型真正帮你写代码

> 全知全能，本地运行，为系统性思考的开发者而生。

---

最近一年，AI Agent 的概念从科幻走进现实。Cline、Claude Code、Cursor 等工具让我们看到了 AI 辅助编程的潜力，但它们要么是闭源 SaaS 服务，要么数据必须经过云端，要么无法深度定制。

如果你和我一样，**既想要 Agent 的自动化能力，又不想让代码和数据离开本地**，那么这个项目或许正是你需要的。

**omniAgent** —— 一个基于 **Java 21 + Spring Boot 3 + Spring AI 1.0** 的全本地 AI Agent，已在 GitHub 开源。

🔗 https://github.com/LainXXX/omniAgent

---

为什么自己做 Agent？

市面上不缺 AI 编程工具，但我的需求很明确：

• **全本地部署**：代码、对话历史、向量数据全部留在本地，不经过任何第三方云端
• **深度可控**：工具注册、Advisor 编排、技能注入全部在 Java 代码层完成，想改哪里改哪里
• **多厂商自由切换**：不绑定单一模型厂商，DeepSeek、MiniMax、Claude 按需切换
• **代码理解能力**：不是 ChatBot，是真正能读写代码、跑命令的 Engineer

• 抱着这个想法，我用 Spring AI 的 Advisor 链式管道从零搭建了一个 Agent 框架。断断续续写了几个月，现在已经具备了比较完整的能力体系。

  ---

  六大核心能力

  ① Agentic RAG：查→评→补的自省检索闭环

  RAG 的痛点是：召回不准 → 生成胡说 → 你都不知道它有没有瞎编。

  omniAgent 的 RAG 链路做了三件事：

  
  向量召回 → Rerank 重排 → Parent Chunk 回扫

  第一轮向量检索找潜在相关片段 → Rerank 模型重新打分排序 → 如果置信度不足，自动将细粒度 Chunk 回扫到父级段落补全上下文。

  更关键的是支持 **ReadChunks 物理坐标级补读**。如果 Agent 发现某段内容不完整，可以直接按坐标精准补读，而不是整篇文章重新塞进去。

  这套 **"查→评→补" 的自省闭环** 让 RAG 不再是碰运气。

  数据层面双库并行：**MySQL 存对话历史**，**PostgreSQL + pgvector 存向量嵌入**，各司其职。

  ---

  ② 链表式消息记忆：会话永不"断代"

  大多数 Agent 的消息存储是平铺的 —— conversation_id 一把捞，按时间排序。这在连续多轮工具调用后很容易乱序。

  omniAgent 用 **parent_id 构建单向链表**，每条消息只记录它的前驱。加载历史时通过 **MySQL 递归 CTE** 自底向上回溯重建，保证会话绝对正序。

  
  消息 A (parent_id = null)
    └→ 消息 B (parent_id = A)
         └→ 消息 C (parent_id = B)
              └→ ...

  无论中间经历了多少次工具调用、子代理分支、用户打断重试，历史记录永不乱序。

  ---

  ③ 上下文消息装配：物理隔离的系统注入层

  Agent 的 Prompt 组装是一个容易被低估的复杂度来源。系统指令、工具定义、技能注入、历史消息、用户输入混在一起，既容易注意力稀释，也容易出现注入攻击。

  omniAgent 的 **MessageFormatAdvisor** 在请求前置阶段按固定拓扑编排消息栈：

  
  System → Tools → Skills → CWD → History → Input

  关键设计：**OMNI_INJECTED 标识**。系统注入层（System Prompt、Skill 指令）和工具输出层带有独立标识，与用户输入物理隔离，既保证模型能区分"谁说了什么"，也防止工具输出污染系统指令空间。

  ---

  ④ 多层记忆压缩：对抗上下文窗口天花板

  大模型的上下文窗口再大也是有限的。连续几十轮工具调用后，历史堆积会让 Token 消耗爆炸。

  omniAgent 的 **ContextCompressionAdvisor** 实现了四层压缩流水线：

  
  去重剪裁 → 时间衰减 → LLM 摘要 → 结构化注入

  1. **去重剪裁**：移除完全重复的用户/助手消息，截断超长工具输出

  2. **时间衰减**：超过一定时间的旧工具结果自动清除，只保留最近 N 条

  3. **LLM 摘要**：对中间段历史进行语义摘要，保留高熵信息

  4. **结构化注入**：将摘要以结构化格式注入，最大化降低 Token 损耗

  这套流水线在请求到达 LLM 之前前置拦截，确保每一轮对话的 Token 消耗在可控范围内。

  ---

  ⑤ Multi-SubAgent + Worktree 隔离：并行任务的工程化方案

  Agent 不能只有一个线程在跑。复杂任务需要拆分、并行、互不干扰。

  omniAgent 支持**动态 Fork 子 Agent**，每个子 Agent 拥有：

• 独立会话（可回溯、可 Resume）
• 独立工具权限（按 AgentType 过滤允许的工具集）
• 独立工作目录

• 最硬核的是 **Git Worktree 级别的文件沙箱**。当子 Agent 需要操作文件系统时，系统自动创建 Git Worktree 作为隔离沙箱，修改完后合并回主工作区。这从根本上解决了多 Agent 并发写文件的冲突问题。

  
  SubAgent Fork
    ├── AgentType: EXPLORE (One-Shot, 只读工具)
    ├── AgentType: PLAN (One-Shot, 只读工具)
    ├── AgentType: GENERAL (全工具, Worktree 隔离)
    └── AgentType: CODE_REVIEWER (One-Shot, 只读工具)

  Agent 类型分为 One-Shot（单次调用，不迭代）和 General（完整迭代循环），按场景精确控制资源消耗。

  ---

  ⑥ 动态指令注入（Skill）：YAML 声明式技能框架

  传统的 Agent Prompt 是"把所有技能的所有描述塞进 System Prompt"——又长又糊，模型根本记不住。

  omniAgent 的 Skill 系统是**元数据驱动的延迟加载框架**：

  1. 在 ~/.omni/skills/<name>/SKILL.md 中声明技能（YAML frontmatter + Markdown 描述）

  2. 运行时自动扫描发现

  3. 按需注入到 MessageFormatAdvisor 的消息栈中

  ---
  name: my-skill
  description: Handle specific task
  ---
  
  Say "hello world" when user asks.

  只有需要时才加载，避免注意力稀释。同时遵循**最小特权原则**——技能只能访问自己被授予的工具和上下文。

  ---

  ⑦ 代码理解：完整的 IDE 级原语

  Agent 如果能读写代码，体验会上一个台阶。omniAgent 实现了完整的代码操作原语集：

  | 原语 | 能力 |

  |------|------|

  | **Read** | 文件读取，支持行范围 |

  | **Write** | 文件写入 |

  | **Edit** | 精确字符串替换（Diff 式修改） |

  | **Grep** | 正则搜索文件内容 |

  | **Glob** | 文件名模式匹配 |

  | **Bash** | Shell 命令执行（带安全验证） |

  **Delta Edit** 是关键能力——不是整个文件重写，而是通过 Edit 原语做精确的代码差分修改，保留文件其余部分不变。这对大型项目的增量修改至关重要。

  Bash 工具内置了多层安全防护：危险命令模式检测、自杀命令检测（rm -rf /、fork bomb 等）、命令审批流程、进程树清理。

  ---

  ⑧ 任务进度管理：阻断 LLM 死循环

  大模型在工具调用循环中很容易卡死——同一个错误反复重试、无意义地来回切换工具、陷入逻辑死胡同。

  omniAgent 内置了 **Task 状态机**，包含两个关键防护机制：

• **活性检测 & 超时 Nag 探测**：Agent 在某个步骤停留太久时触发提醒
• **生命周期硬性步数上限（Max Steps）**：达到上限后强制终止，避免 Token 无限消耗

• 配合 AskUserQuestionTool，Agent 在不确定时可以暂停执行、向用户提问，然后继续。执行链路全程可干预、可打断。

  ---

  技术栈速览

  | 层级 | 技术 |

  |------|------|

  | 后端框架 | Spring Boot 3.5.10 + Spring AI 1.1.3 |

  | 语言 | Java 21 |

  | 前端 | React 18 + TypeScript + Vite + Tailwind v4 |

  | 聊天历史 | MySQL 8.0 |

  | 向量存储 | PostgreSQL 15+ + pgvector |

  | 嵌入模型 | BAAI/bge-m3 (1024d) |

  | 重排序 | BAAI/bge-reranker-v2-m3 |

  | LLM 厂商 | DeepSeek / MiniMax M2.7 / Anthropic Claude |

  | 文档解析 | Apache Tika + POI |

  | Token 计数 | JTokkit |

  ---

  快速上手

  # 1. 克隆项目
  git clone https://github.com/LainXXX/omniAgent.git
  cd omniAgent
  
  # 2. 创建数据库
  # MySQL: 创建 rem-agent 数据库
  # PostgreSQL: 创建 springai 数据库并安装 pgvector 扩展
  
  # 3. 配置 AI 提供商（编辑 application-dev.yml）
  
  # 4. 启动后端（端口 9090）
  ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
  
  # 5. 启动前端（端口 9500）
  cd frontend
  npm install
  npm run dev

  打开 http://localhost:9500 即可开始对话。

  ---

  写在最后

  omniAgent 是一个偏工程化的 AI Agent 项目。它的核心设计理念是：

  > **数据不出本地，能力深度可控，架构足够灵活**

  如果你也是 Java 生态的开发者，对 AI Agent 感兴趣、希望有一个可以随意修改和扩展的本地 Agent 框架，欢迎来 GitHub 看看。Issues、PR、Star 都是一种支持。

  🔗 https://github.com/LainXXX/omniAgent

  ---

  *MIT License © 2025-2026 LainXXX*