# JAgent **Repository Path**: wangxiaopeng2/jagent ## Basic Information - **Project Name**: JAgent - **Description**: No description available - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-31 - **Last Updated**: 2026-09-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: Agent, Java ## README --- AIGC: ContentProducer: '001191110102MAD55U9H0F10002' ContentPropagator: '001191110102MAD55U9H0F10002' Label: '1' ProduceID: 'fa3cfb2e-434d-4520-9bb7-0918cdf86aca' PropagateID: 'fa3cfb2e-434d-4520-9bb7-0918cdf86aca' ReservedCode1: '59903240-f34c-475e-85f0-709bf2796faf' ReservedCode2: '59903240-f34c-475e-85f0-709bf2796faf' --- # JAgent — Java 版本地 AI Agent 运行时 > 基于 miniClaude（miniClaude）架构思想，用 **Java 21** 实现的本地 AI Agent 运行时系统。 > 核心架构：守护进程 + 多前端（CLI / TUI / Web）+ 中间件（Redis / Kafka），跨进程解耦、事件外化、权限审批。 --- ## 一、项目定位 **一句话定义**：JAgent 是一个 Java 实现的本地 AI Agent 运行时，采用**守护进程 + 多前端**架构，通过中间件实现跨进程通信、事件外化与权限审批。 **与 miniClaude (Python) 的对应关系**： | miniClaude (Python) | JAgent (Java) | 说明 | |---------------------|---------------|------| | mini-core (daemon) | `jagent-core` | 守护进程，Agent 引擎 | | mini (CLI) | `jagent-cli` | 脚本化调试客户端 | | mini-tui (TUI) | `jagent-tui` (JLine3) | 终端 UI 客户端 | | — | `jagent-web` (Spring Boot) | Web 前端（新增） | | asyncio | Virtual Thread | 异步运行时 | | Pydantic v2 | Jackson + sealed interface | 消息模型 + 判别联合 | | EventBus | Redis Pub-Sub + Kafka | 事件外化 | | TCP NDJSON | HTTP/JSON-RPC + SSE + WebSocket | 通信层 | | SessionStore (文件) | Redis + 本地文件 | 会话持久化 | | PermissionManager (Future) | Redis + CompletableFuture | 跨进程权限审批 | --- ## 二、总体架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 用户交互层 │ │ ┌──────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ jagent │ │ jagent-tui │ │ jagent-web │ │ │ │ (CLI) │ │ (JLine3 TUI) │ │ (Spring Boot) │ │ │ └────┬─────┘ └──────┬───────┘ └────────┬─────────┘ │ │ │ HTTP/JSON-RPC │ WebSocket+STOMP │ HTTP REST + SSE │ ├───────┼───────────────┼──────────────────┼───────────────────────┤ │ │ 中间件层 │ │ │ ┌────▼───────────────▼──────────────────▼──────────────┐ │ │ │ Redis │ │ │ │ Session Cache │ Permission Future │ Event Stream │ │ │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Kafka (可选增强层) │ │ │ │ agent.events │ trace.records │ audit.logs │ │ │ └──────────────────────────────────────────────────────┘ │ ├──────────────────────────────────────────────────────────────────┤ │ 守护进程层 (jagent-core) │ │ CoreApp → SessionManager → AgentRunner → AgentLoop (ReAct) │ │ LLM Provider │ Tools │ Permission │ EventBus │ Session │ │ Compactor │ MCP │ Trace │ Skills │ SubAgent │ Task │ ├──────────────────────────────────────────────────────────────────┤ │ 协议与契约层 (jagent-bus) │ │ Command + Event + Envelope（Jackson sealed interface 判别联合） │ ├──────────────────────────────────────────────────────────────────┤ │ 持久化层 │ │ ~/.jagent/sessions/ policy.json traces/ runs// │ └──────────────────────────────────────────────────────────────────┘ ``` ### 三进程 + 中间件 ``` jagent-core (daemon) ← 常驻守护进程，执行所有 Agent 任务 ├─ HTTP/JSON-RPC :9081 ← CLI / Web 直连调用 ├─ 发布事件 → Redis Stream / Kafka topic: agent.events └─ 订阅权限审批 / 命令 jagent-cli / jagent-tui / jagent-web ← 三种前端，通过中间件解耦 ``` **为什么用中间件而非直连 TCP？** 接受 ~2ms 延迟，换取多实例支持、前端断线容错、水平扩展能力。单机部署时延迟差异可忽略。 --- ## 三、模块划分 ``` jagent/ ├── pom.xml # 父 POM，统一版本管理 (Java 21) ├── jagent-bus/ # 协议契约层：Command + Event + Envelope │ ├── envelope/ # JSON-RPC 2.0 信封（Request/Success/Error） │ ├── command/ # 命令定义（sealed interface 判别联合） │ ├── event/ # 事件定义（20 种事件，@JsonTypeInfo 多态） │ └── result/ # 命令返回值 ├── jagent-common/ # 公共工具：IdUtil / JsonUtil / RetryUtil / TimeUtil / JAgentConstants（全局常量） ├── jagent-core/ # 守护进程（核心引擎） │ ├── CoreApp.java # 守护进程入口 │ ├── config/ # JAgentConfig + ConfigLoader（四层优先级） │ ├── loop/ # AgentLoop — ReAct 循环引擎 │ ├── runner/ # AgentRunner — 依赖组装与执行 │ ├── llm/ # LLM Provider（OpenAI 兼容 + TracingProvider） │ ├── tools/ # 工具系统（8 个内建工具） │ ├── permission/ # 权限管理（6 层级联评估） │ ├── session/ # 会话管理（Redis + 文件双写） │ ├── context/ # 上下文压缩（Compactor + BudgetTruncator） │ ├── events/ # 进程内 EventBus + EventWriter │ ├── trace/ # 系统追踪（IPC/EventBus/LLM 三层 + Kafka） │ ├── skills/ # Skills 技能系统（S8） │ ├── subagent/ # 子 Agent（SpawnAgentTool，S8） │ ├── mcp/ # MCP 外部工具（S8） │ ├── task/ # 任务系统 │ ├── runs/ # run 目录管理 │ └── transport/ # HTTP Command + Redis 事件发布 ├── jagent-gateway/ # API 网关（Redis 命令代理 + SSE/WS 端点） ├── jagent-cli/ # CLI 客户端（picocli + HTTP + SSE） │ ├── CliMain.java # picocli 命令入口 │ ├── CoreClient.java # HTTP JSON-RPC 客户端 │ └── commands/ # ping / run / trace 子命令 ├── jagent-tui/ # TUI 客户端（JLine3 + SSE 实时渲染） └── jagent-web/ # Web 前端（Spring Boot + REST + SSE） ``` --- ## 四、技术栈 | 技术 | 用途 | |------|------| | Java 21 | 语言（Virtual Thread + sealed interface + record） | | Maven 多模块 | 工程结构（8 个模块） | | Jackson 2.17 | JSON 序列化 + 判别联合多态 | | Lettuce 6.4 | Redis 客户端（Stream / Pub-Sub / Future） | | Kafka Clients 3.7 | 事件持久化（可选增强层） | | JLine 3.26 | TUI 终端交互 | | picocli 4.7 | CLI 命令解析 | | Spring Boot 3.3 | Web 前端 | | JUnit 5 + Mockito | 测试 | --- ## 五、核心能力 ### 5.1 AgentLoop — ReAct 循环引擎 ``` plan → act → observe 循环： 1. 读取目标 (goal) → 构造上下文 2. 调用 LLM → 得到下一步动作（工具调用或回复） 3. 执行工具 → 观察结果 4. 循环直至完成 / 达到 maxSteps ``` - 支持多轮工具调用、错误恢复、上下文压缩 - 无 session 模式（`agent.run`）与会话模式（`session.send_message`） ### 5.2 工具系统 内置工具（`jagent-core/src/main/java/com/jagent/core/tools/builtin/`）： | 工具 | 说明 | |------|------| | `BashTool` | 执行 shell 命令（受权限控制） | | `ReadFileTool` / `WriteFileTool` | 读写文件 | | `ListDirTool` | 列目录 | | `NoteSaveTool` | 保存笔记 | | `TaskCreate/Update/List/Get` | 任务管理 | 扩展机制：实现 `BaseTool` → 注册到 `ToolRegistry`。 ### 5.3 权限管理（6 层级联） ``` Tier 1: deny_patterns → 硬性拒绝 Tier 2: OUTSIDE_CWD → 强制 ASK Tier 3: session always 缓存 Tier 4: persistent always 缓存 Tier 5: allow_patterns → 自动放行 Tier 6: tool default → ALLOW / DENY / ASK ``` 跨进程审批：`PermissionManager` 用 Redis + CompletableFuture 协调，前端可实时审批。 ### 5.4 事件外化 - 进程内 `EventBus`（发布-订阅） - 外发：`RedisEventPublisher` → Redis Stream + Pub-Sub - 可选：`KafkaEventPublisher` → Kafka `agent.events`（持久化回放） ### 5.5 上下文治理 - `BudgetTruncator`：tool_result 超限截断（默认 8000→4000 token） - `Compactor`：LLM 摘要式压缩（水位阈值触发 / 手动触发） ### 5.6 系统追踪（Trace） 三层追踪：**IPC**（命令/响应）→ **EventBus**（事件流）→ **LLM**（API 调用） - `TraceWriter`：异步队列 + JSONL 落盘 - `TracingProvider`：包裹 LLM Provider，记录 `api_call` / `api_response`（含 latency_ms） - `TracingEventSink`：订阅 EventBus 记录事件 - `KafkaEventPublisher`：可选，持久化到 Kafka ### 5.7 扩展边界（S8） - **Skills**：三级路径加载（`.jagent/skills` → `~/.jagent/skills` → `~/.jagent/builtin/skills`），frontmatter 元数据 + `$ARGUMENTS` 渲染 - **Subagents**：后台/前台子任务，角色白名单 + MAX_DEPTH=2 限制 - **MCP**：JSON-RPC 2.0 客户端（stdio/tcp），`tools/list` + `tools/call` --- ## 六、快速开始 ### 环境要求 - JDK 21（本机：`D:\app\Java\jdk-21.0.7+6`） - Maven 3.8+ - Redis（默认 `127.0.0.1:6379`） - Kafka（可选，`127.0.0.1:9092`） ### 构建 ```bash # 设置 JDK 21 $env:JAVA_HOME = "D:\app\Java\jdk-21.0.7+6" $env:PATH = "$env:JAVA_HOME\bin;$env:PATH" # 编译全部模块 mvn compile # 运行测试 mvn test -pl jagent-bus,jagent-common,jagent-core -am # 打包 CLI（含 fat-jar） mvn package -pl jagent-cli -am -DskipTests ``` ### 启动守护进程 ```bash # 启动 core（需先启动 Redis） mvn -pl jagent-core exec:java -Dexec.mainClass="com.jagent.core.CoreApp" # 或打包后运行 java -jar jagent-core/target/jagent-core-1.0.0.jar ``` ### CLI 使用 ```bash # 连通性测试 java -jar jagent-cli/target/jagent-cli.jar ping # 执行一次 Agent 任务 java -jar jagent-cli/target/jagent-cli.jar run --goal "读取 README.md" # 追踪回放（Trace 阶段） java -jar jagent-cli/target/jagent-cli.jar trace --run-id java -jar jagent-cli/target/jagent-cli.jar trace --layer llm --tail 20 ``` ### 配置 配置文件优先级：默认值 → `~/.jagent/config.yml` → 项目 `.jagent/config.yml` → 环境变量 ```yaml # ~/.jagent/config.yml core: host: 127.0.0.1 httpPort: 9081 llm: defaultModel: claude-sonnet-4-20250514 baseUrl: "" apiKey: "" trace: enabled: true includePayload: true kafka: # 可选增强层，默认关闭 enabled: false bootstrapServers: 127.0.0.1:9092 eventTopic: agent.events ``` ### Kafka 启动（可选） Kafka 4.3.1 已安装到 `d:\app\kafka`（KRaft 模式，无需 ZooKeeper）： ```bash d:\app\kafka\start-kafka.bat # 启动 d:\app\kafka\stop-kafka.bat # 停止 ``` 启动后创建 3 个 topic： ```bash kafka-topics --create --topic agent.events --partitions 3 --bootstrap-server localhost:9092 kafka-topics --create --topic trace.records --partitions 1 --bootstrap-server localhost:9092 kafka-topics --create --topic audit.logs --partitions 1 --bootstrap-server localhost:9092 ``` --- ## 七、开发阶段（S0 → Trace） | 阶段 | 主题 | 关键产出 | 状态 | |------|------|---------|------| | S0 | 骨架与协议 | jagent-bus + config + Redis 连通 | ✅ | | S1 | Agent 最小闭环 | AgentLoop + AgentRunner + LLMProvider | ✅ | | S2 | 事件流外化 | RedisEventPublisher + SSE 订阅 | ✅ | | S3 | TUI + 任务系统 | jagent-tui (JLine3) + TaskManager | ✅ | | S4 | Web 前端 | jagent-web + REST API | ✅ | | S5 | 会话与记忆 | SessionManager + SessionStore | ✅ | | S6 | 工具安全 | PermissionManager + 6 层评估 | ✅ | | S7 | 上下文治理 | Compactor + BudgetTruncator | ✅ | | S8 | 扩展边界 | Skills + Subagents + MCP | ✅ | | **Trace** | 系统级追踪 | TraceWriter + TracingProvider + Kafka | ✅ | ## 八、设计决策 | 决策 | 选择 | 理由 | |------|------|------| | 通信中间件 | Redis（非直连 TCP） | 多实例、断线容错、水平扩展 | | Kafka | 可选增强层 | 事件持久化回放、大数据分析；Redis Stream 覆盖 90% 场景 | | TUI 传输 | WebSocket | 双向实时交互优于 HTTP 轮询 | | 异步模型 | Virtual Thread | Java 21 原生轻量线程，避免 Reactor 复杂度 | --- ## 九、License JAgent — Java 版本地 AI Agent 运行时。基于 (miniClaude) 架构思想重构，仅供学习研究使用。 > AI生成