IntelGrid --- 9 层工具架构的 AI Agent 框架
一句话定位
用 Kotlin 写的 Agent 框架，把 AI 需要的所有能力拆成 9 层、40 个工具，通过 ReAct 循环让 LLM 自主决策调用。
架构总览
用户输入 → Agent Loop → LLM（推理） → 工具调用 → 执行结果 → LLM（再推理） → ... → 最终回复核心思想：LLM 是大脑，工具是手脚，ToolRegistry 是中枢神经。
Agent 不直接依赖任何具体工具，只依赖 Tool 接口。LLM 看到用户需求 → 决定调哪个工具 → Registry 查找并执行 → 结果回传 LLM → 继续推理或回复。这就是 ReAct（Reasoning + Acting）循环。
9 层工具体系
| 层 | 名称 | 数量 | 职责 | 代表工具 |
|---|---|---|---|---|
| L1 | 基础设施 | 6 | Agent 生存的基础 | ExecuteCommand、CacheManager、FileWatcher |
| L2 | 本地操作 | 11 | Agent 的双手 | ReadFile、WriteFile、GitTool、TemplateEngine |
| L3 | 信息感知 | 4 | Agent 的感官 | WebSearch、WebFetch、RAGSearch |
| L4 | 用户交互 | 2 | Agent 的沟通 | AskQuestion、TodoWrite |
| L5 | 结果交付 | 4 | Agent 的表达 | PreviewUrl、ImageGen、DeliverAttachments |
| L6 | 代理能力 | 3 | Agent 的分身 | Task（子代理）、CodeExplorer、RegisterAgent |
| L7 | 团队协作 | 3 | Agent 的社交 | TeamCreate、SendMessage、TeamDelete |
| L8 | 外部接入 | 6 | Agent 的扩展 | UseSkill、McpConnect、EmailClient |
| L9 | 自动化 | 1 | Agent 的自律 | Automation（定时调度） |
设计逻辑：从底层到高层，从单兵到社会化。L1-L2 是个体生存，L3-L5 是感知与表达，L6-L7 是多 Agent 协作，L8-L9 是能力扩展与自治。
核心模块（5 个文件）
core/Config.kt --- 全局配置
单例对象，从 .env 文件加载 LLM API 地址、模型名、超时等配置。环境变量优先级：系统变量 > .env > 代码默认值。
core/Message.kt --- 消息与对话历史
定义了 4 种消息类型（system/user/assistant/tool_result）和 ChatHistory 类。ChatHistory 管理对话上下文，支持 function calling 的多轮工具结果回传。
core/Tool.kt --- 工具接口
整个框架的核心抽象。Tool 接口只有 4 个属性（name/description/params/layer）+ 1 个方法（execute）。还包含 ToolLayer 枚举（L1-L9）和 ToolParam 数据类。
core/ToolRegistry.kt --- 工具注册中心
管理所有工具实例。提供按名查找、按层过滤、批量注册（DSL 风格的 registerAll { +ReadFile() }）、生成 JSON Schema 等。
core/ToolResult.kt --- 统一返回值
密封类，三种状态：Success（成功）、Error（失败）、NeedConfirm（需用户确认）。所有工具返回同一个类型，AgentLoop 统一处理。
通信层
llm/LlmClient.kt --- LLM 客户端
基于 Ktor HTTP Client，调用 OpenAI 兼容 API。支持 function calling（工具调用的通信协议）。解析 LLM 响应为结构化的 AssistantMessage，区分纯文本回复和工具调用请求。
入口（Main.kt）
main() 函数做四件事：
- 加载配置 --- Config.loadFromFile()
- 组装组件 --- 创建 LlmClient、ToolRegistry、AgentRegistry
- 注册工具 --- 用 DSL 风格按 9 层注册全部 40 个工具
- 启动循环 --- AgentLoop.run()
AgentLoop 是 ReAct 循环的实现：外层是用户对话循环，内层是工具调用循环。每次工具执行后结果回传 LLM，直到 LLM 返回纯文本回复。
系统提示词中嵌入了执行协议：自适应身份、非必要不调用工具、复杂任务拆分为基元链条。
设计模式
| 模式 | 体现 |
|---|---|
| 注册表 | ToolRegistry 集中管理 40 个工具 |
| 策略 | Tool 接口，Agent 不依赖具体实现 |
| 依赖注入 | Task/CodeExplorer/McpConnect 通过构造函数接收 LlmClient/ToolRegistry |
| DSL | registerAll { +ReadFile() +WriteFile() } 声明式注册 |
| 适配器 | McpConnect 将 MCP 协议工具适配为 Tool 接口 |
| 密封类 | ToolResult 的 Success/Error/NeedConfirm 三态 |
技术栈
- Kotlin 2.1.20 + JVM 17
- Gradle 8.12（Kotlin DSL）
- Ktor 3.0.3（HTTP 客户端）
- kotlinx-coroutines 1.10.1（协程异步）
- kotlinx-serialization 1.8.0（JSON）
- Quartz 2.5.0（L9 定时调度）
- clikt 5.0.3（命令行解析）
- dotenv-kotlin 6.4.2（环境变量）
47 个 Kotlin 源文件分布
intelgrid/src/main/kotlin/intelgrid/
├── Main.kt ← 入口 + Agent 循环 + 系统提示词
├── core/ (5) ← 接口、注册、配置、消息、结果
├── llm/ (1) ← LLM HTTP 客户端
└── tools/
├── L1/ (6) ← 基础设施
├── L2/ (11) ← 本地操作
├── L3/ (4) ← 信息感知
├── L4/ (2) ← 用户交互
├── L5/ (4) ← 结果交付
├── L6/ (3) ← 代理能力
├── L7/ (3) ← 团队协作
├── L8/ (6) ← 外部接入
└── L9/ (1) ← 自动化每个文件都有详尽中文注释，覆盖 interface / sealed class / data class / enum / suspend fun / DSL / 依赖注入等 Kotlin 核心知识点，是一个完整的 Kotlin 学习项目。
项目定位
这是一个可用、可学、可扩展的 Agent 框架原型：
- 可用：接入任何 OpenAI 兼容 API 即可运行，9 层 40 工具覆盖从文件操作到团队协作的完整能力
- 可学：每行代码有中文注释，从简单接口到复杂协程逐步递进
- 可扩展：实现 Tool 接口就能加新工具，通过 L8 技能包/MCP 还能动态加载外部能力
IntelGrid ⚡
Intelligence Grid --- 9 层工具架构的 AI Agent 框架，用 Kotlin 构建
架构概览
用户输入 → Agent Loop → LLM（推理） → 工具调用 → 执行结果 → LLM（再推理） → ... → 最终回复9 层工具体系
| 层级 | 名称 | 工具数 | 职责 |
|---|---|---|---|
| L1 | 基础设施 | 6 | 命令执行、缓存、文件监听、依赖管理、运行时安装、云服务 |
| L2 | 本地操作 | 11 | 文件读写搜索、剪贴板、Git、Patch、模板引擎 |
| L3 | 信息感知 | 4 | 联网搜索、网页抓取、知识库检索、代码诊断 |
| L4 | 用户交互 | 2 | 任务管理、用户确认 |
| L5 | 结果交付 | 4 | 结果展示、URL 预览、附件投递、图片生成 |
| L6 | 代理能力 | 3 | 子代理注册、执行、代码分析 |
| L7 | 团队协作 | 3 | 多 Agent 团队消息、创建、解散 |
| L8 | 外部接入 | 6 | 技能包、MCP 协议、通知推送、邮件收发 |
| L9 | 自动化 | 1 | 定时/循环任务调度 |
项目结构
intelgrid/src/main/kotlin/intelgrid/
├── Main.kt # 程序入口 + Agent 主循环
├── core/ # 核心模块
│ ├── Config.kt # 全局配置管理
│ ├── Message.kt # 消息类型定义 + ChatHistory
│ ├── Tool.kt # Tool 接口 + ToolLayer 枚举
│ ├── ToolRegistry.kt # 工具注册中心
│ └── ToolResult.kt # 统一返回类型 + 扩展函数
├── llm/
│ └── LlmClient.kt # OpenAI 兼容 API 客户端
├── tools/
│ ├── L1/ # 基础设施
│ │ ├── ExecuteCommand.kt # ⭐ 执行系统命令
│ │ ├── InstallBinary.kt # ⭐⭐ 安装/管理运行时
│ │ ├── CacheManager.kt # ⭐⭐ 结构化键值缓存（内存+文件两级、LRU淘汰、TTL过期）
│ │ ├── FileWatcher.kt # ⭐⭐ 文件变化实时监听（JDK WatchService）
│ │ ├── PackageDependency.kt # ⭐⭐ 多包管理器依赖解析与管理
│ │ └── ConnectCloud.kt # ⭐⭐⭐ 云服务连接
│ ├── L2/ # 本地操作
│ │ ├── ReadFile.kt # ⭐ 读取文件内容
│ │ ├── WriteFile.kt # ⭐ 写入/创建文件
│ │ ├── ReplaceInFile.kt # ⭐ 精确替换文件内容
│ │ ├── ListDir.kt # ⭐ 列出目录结构
│ │ ├── DeleteFile.kt # ⭐ 删除文件
│ │ ├── SearchFile.kt # ⭐⭐ 按名称搜索文件
│ │ ├── SearchContent.kt # ⭐⭐ 按内容搜索文件
│ │ ├── ClipboardManager.kt # ⭐⭐ 系统剪贴板读写
│ │ ├── GitTool.kt # ⭐⭐ Git 操作语义化封装
│ │ ├── PatchApply.kt # ⭐⭐⭐ Git Diff/Patch 应用与创建
│ │ └── TemplateEngine.kt # ⭐⭐⭐ 模板文件生成（变量替换、条件、列表渲染）
│ ├── L3/ # 信息感知
│ │ ├── WebSearch.kt # ⭐⭐ 联网搜索
│ │ ├── WebFetch.kt # ⭐⭐ 抓取网页内容
│ │ ├── RAGSearch.kt # ⭐⭐ 知识库检索
│ │ └── ReadLints.kt # ⭐⭐⭐ Linter 诊断信息
│ ├── L4/ # 用户交互
│ │ ├── AskQuestion.kt # ⭐⭐⭐ 用户确认
│ │ └── TodoWrite.kt # ⭐⭐ 任务管理
│ ├── L5/ # 结果交付
│ │ ├── OpenResultView.kt # ⭐⭐ 结果展示
│ │ ├── PreviewUrl.kt # ⭐⭐⭐ URL 预览
│ │ ├── DeliverAttachments.kt # ⭐⭐ 附件投递
│ │ └── ImageGen.kt # ⭐⭐⭐ AI 图片生成
│ ├── L6/ # 代理能力
│ │ ├── RegisterAgent.kt # ⭐⭐ 注册自定义子代理
│ │ ├── Task.kt # ⭐⭐⭐ 通用子代理任务
│ │ └── CodeExplorer.kt # ⭐⭐ 深度代码分析子代理
│ ├── L7/ # 团队协作
│ │ ├── TeamCreate.kt # ⭐⭐ 创建团队
│ │ ├── SendMessage.kt # ⭐⭐⭐ 团队消息通信
│ │ └── TeamDelete.kt # ⭐⭐ 解散团队
│ ├── L8/ # 外部接入
│ │ ├── FindSkills.kt # ⭐⭐⭐ 搜索可安装技能包
│ │ ├── UseSkill.kt # ⭐⭐⭐ 加载技能包
│ │ ├── SkillCreator.kt # ⭐⭐⭐ 创建/编辑技能包
│ │ ├── McpConnect.kt # ⭐⭐⭐ MCP 协议客户端（动态工具加载）
│ │ ├── SendNotification.kt # ⭐⭐⭐ 外部通知推送（飞书/企微/Slack 等）
│ │ └── EmailClient.kt # ⭐⭐⭐ 邮件收发（SMTP/IMAP，通过 PowerShell）
│ └── L9/ # 自动化
│ └── Automation.kt # ⭐⭐⭐ 定时/循环任务调度重要性等级说明
等级 含义 数量 ⭐ 核心 Agent 运行的基石，几乎所有任务都依赖 6 ⭐⭐ 重要 高频使用，显著提升 Agent 能力 18 ⭐⭐⭐ 增强 特定场景下使用，扩展 Agent 能力边界 16
快速开始
环境要求
- JDK 17+ （推荐 Eclipse Temurin）
- Gradle 8.x（项目自带 Wrapper）
配置
bash
# 1. 复制环境变量模板
cp .env.example .env
# 2. 编辑 .env，填入你的 API Key
# 最小配置：LLM_API_KEY + LLM_BASE_URL + LLM_MODEL运行
bash
# 使用 Gradle Wrapper（推荐）
./gradlew run
# 或者打包后运行
./gradlew jar
java -jar build/libs/IntelGrid-1.0.0.jar设计模式
核心模式
| 模式 | 应用 | 说明 |
|---|---|---|
| 注册表模式 | ToolRegistry | 集中管理所有工具，按名查找、按层过滤 |
| 策略模式 | Tool 接口 | 所有工具统一接口，Agent 不依赖具体实现 |
| 依赖注入 | Task / CodeExplorer / RegisterAgent / McpConnect | LlmClient/ToolRegistry/AgentRegistry 通过构造函数传入 |
| ReAct 循环 | AgentLoop | 推理→行动→观察→推理，直到产生最终回复 |
| DSL 构建 | registerAll { } | 用 Kotlin 运算符重载实现声明式工具注册 |
关键设计决策
- 接口优先 ---
Tool接口只有 4 属性 + 1 方法，新工具实现成本低 - 层级隔离 --- 每个工具有
layer标签，便于分组、权限控制、日志过滤 - 最小权限 --- 子代理只能使用白名单中的工具，防止递归失控
- 声明式降级 --- 依赖未注入时返回描述文本，不会崩溃
- 文件系统状态 --- 消息收件箱、团队数据、自动化配置都用文件系统持久化
技术栈
| 组件 | 技术 | 用途 |
|---|---|---|
| 语言 | Kotlin 2.1 | 主开发语言 |
| 构建 | Gradle 8 (Kotlin DSL) | 编译、打包、依赖管理 |
| HTTP | Ktor Client (CIO) | 调用 LLM API、搜索 API |
| 异步 | Kotlin Coroutines | 非阻塞 I/O、Agent 循环 |
| 序列化 | kotlinx.serialization | JSON 解析、消息序列化 |
| 日志 | SLF4J + Logback | 运行日志 |
| 调度 | Quartz Scheduler | L9 定时任务 |
学习路径
本项目每个文件都有详尽的中文注释，适合 Kotlin 入门学习。
路径以 Agent 的"手脚"（工具能力）为主线，从基础操作到高级协作逐步递进：
- core/ --- 理解工具的骨架：
Tool.kt（接口 + 层级枚举）和ToolResult.kt（密封类返回值） - tools/L1/ --- Agent 的基础设施：命令执行、缓存、文件监听、依赖管理
- tools/L2/ --- Agent 的双手：文件 CRUD、搜索浏览、剪贴板、Git、模板引擎
- tools/L3-L5/ --- Agent 的感官与表达：联网感知(L3) → 用户交互(L4) → 结果交付(L5)
- llm/ --- Agent 的大脑接口：HTTP 客户端与 JSON 序列化
- Main.kt --- 看 Agent Loop 如何组装所有模块，构成完整的 ReAct 循环
- tools/L6-L9/ --- Agent 的社会化能力：子代理(L6) → 团队协作(L7) → 外部接入(L8) → 自动化(L9)
License
MIT