我用java开发的Agent智能体：lucky_agent

陌シ未央ゞ

187人浏览 · 2026-09-04 14:50:17

陌シ未央ゞ · 2026-09-04 14:50:17 发布

github 链接：戳这里
希望大家可以多点点Star，跪谢
本地优先的单 Agent / 多 Agent 智能体编排框架

Lucky Agent 是一个运行在用户本机的 Agent 框架：它只负责 Agent 的编排、推理与执行链路（支持单 Agent 与多 Agent / 隔离子代理任务），
不托管模型、不存储用户信息、不对用户数据做任何服务端管理。

用户数据始终留在本机工作空间，平台不接触、不存储、不回传。
突出 Java 的稳定与工程严谨，融合 Agent 的创作性。

✨ 特性

本机优先（零托管）：会话、记忆、文件、配置全部存放于本机 ~/.lucky_agent，天然不接触用户内容。

REACT 主回环编排：分析 → 拆分步骤/子代理 → 执行 → 客观验证 → 达成度判定 → 记忆管理 → 再分析，全程安全阀（最大迭代/回合/token）兜底。

多 Agent 子代理（按需启用）：极高复杂任务可在 PLAN 阶段声明 subagents，框架启动隔离子代理（独立会话上下文、工具白名单、受限预算、只回摘要），结果回灌主链路继续推进进度；默认单 Agent，开关 core.subagent-enabled 开启。
客观验证链：步骤可声明 verify（文件存在/内容断言、构建/测试/命令退出码），以客观信号为准，不依赖模型自述。
硬性权限边界：执行臂强制权限级别（只读/修改/全部）+ deny > ask > allow 规则链；高危操作先 ASK 确认，重启可恢复。
记忆系统（双轨）：用户轨读写（本机 JSONL）+ 平台轨只读；召回按 ASCII 词 + 中文 bigram 相关性注入提示词。
五级上下文压缩：上下文接近阈值自动触发 FiveLevelCompactionPipeline——工具结果裁剪（Microcompact）→ 滑动窗口（Snip）→ 摘要下沉（Reactive），全程由 PreservedSegment 保全系统提示/最近 N 轮/关键结果，连续失败由熔断器（TokenCircuitBreaker）兜底；压缩前的执行结论再沉淀为长期记忆，支撑主回环多轮自纠。
工具与 Skill：文件/Shell/Skill/MCP 统一网关；Skill 按需注入（渐进披露），按扩展名自动判语言。
提示词分层：基座（LUCKY.md，可改即生效）+ 人格 + 阶段指令 + 权限约束 + 记忆召回，静态/动态分界。

📁 目录结构

lucky_agent/
├── lucky / lucky.bat / lucky.sh   # 一键启动脚本（Windows / bash）
├── LICENSE
└── web/
    ├── app/                       # 后端（Maven 多模块，Java 17 + Spring Boot 3）
    │   ├── agent-web/             # 入口：REST + SSE 事件流，托管前端
    │   ├── agent-core/            # 编排中枢：REACT 引擎、Orchestrator、子代理、压缩、验证
    │   ├── agent-model/           # 模型端点接入（OpenAI/Anthropic 兼容）、提示词、基座外置
    │   ├── agent-common/          # 公共 DTO/常量/契约
    │   ├── agent-workspace/       # 工作空间配置（唯一 owner）
    │   ├── agent-permission/      # 权限规则/审计/危险操作识别
    │   ├── agent-executor/        # 文件服务/执行臂接入
    │   ├── agent-memory/          # 记忆读写与召回
    │   ├── agent-skill/           # Skill 注册与注入
    │   ├── agent-persona/         # 人格/角色
    │   ├── agent-mcp/             # MCP 工具接入
    │   ├── agent-cache/           # 缓存
    │   └── agent-cli/             # CLI 外壳（后续）
    └── fronted/                   # 前端（Vue 3 + TypeScript + Vite + Pinia + Vue Router）

运行期数据位于 ~/.lucky_agent/（框架必备目录）：

目录	作用
`LUCKY.md`	基座提示词，改完保存即时生效
`settings.json`	全局设置（模型端点 + 推理深度）
`config/`	账号 / 工作空间注册表 / 加密密钥 / Skill 状态
`memory/`	用户轨记忆（`{userId}/mem.jsonl`）
`skills/`	全局（平台级）Skill 库
`agent/sessions/`	会话历史（JSONL + 元数据）
`logs/audit.jsonl`	操作审计日志
`rollback/` `trash/`	回滚快照 / 回收站
`workspace/`	内置默认工作空间（用户产物）

🧱 技术栈

层	选型
语言 / 框架	Java 17+ · Spring Boot 3.x · Maven 多模块
AI 编排核心	LangChain4j（Agent/工具/记忆/RAG）+ LangGraph4j（工作流/多 Agent 图，可选模式）
辅助接入	Spring AI（模型/嵌入/向量/可观测性桥接）
前端	Vue 3 · TypeScript · Vite · Pinia · Vue Router

🧭 使用说明

对话/Agent 执行：直接在聊天框描述目标；简单问题即时回答，复杂任务自动规划。
拆解方式（B 节点决策）：普通拆分→steps（同一 Agent 分步执行）；高复杂度独立子问题→subagents（隔离子代理，需开启开关）。
文件：文件页可浏览目录、语法高亮预览、行内编辑与保存。
高危操作：删除/执行等会触发确认，可在设置调整权限级别。

🖼️ 界面预览

在这里插入图片描述

⚙️ 配置速查

配置	位置	说明
模型端点 / 推理深度	`~/.lucky_agent/settings.json`	主/备端点 + 全局推理深度
基座提示词	`~/.lucky_agent/LUCKY.md`	system prompt 第一层，保存即生效
人格	`~/.lucky_agent/config/persona.json`	角色 / 语气 / 行为参数
权限规则	`~/.lucky_agent/config/`	deny > ask > allow 规则链

API Key 存于用户本机 settings.json，明文本机存储（零托管）；请勿提交到版本库。

🗺️ Agent 主链路

输入 → LLM 分析(B)
        ├─ 拆成步骤？ ─否→ 单 Agent 直接执行 → 客观验证
        ├─ 拆成步骤？ ─是→ 逐步骤执行（失败重试/超限终止）
        └─ 启动隔离子代理？─是→ TaskScheduler 隔离执行 → 摘要回灌
→ 客观验证(D) → 达成度判定(I)
        ├─ 达成 → 总结输出
        └─ 未达成(未超上限) → 记忆管理(K: 压缩+沉淀) → 回 B 再分析
安全阀(N): 最大迭代/回合/token → 强制结束并总结

🧠 上下文压缩与记忆

上下文压缩（短期记忆）与长期记忆沉淀协同支撑主回环的多轮自纠，避免「未达成 → 再分析」时上下文只增不减。

五级上下文压缩（`FiveLevelCompactionPipeline`）

当会话消息占用接近上下文阈值（model.context-threshold，默认 0.9）自动触发，按序执行：

级别	策略	作用
① 裁剪	`MicrocompactStrategy`	截断过大的工具结果文本（`…（工具结果已裁剪）`）
② 滑动窗口	`SnipStrategy`	丢弃最旧的「过程类」消息，保留 system 与最近 N 轮
③ 摘要下沉	`ReactiveCompactStrategy`	把旧工具结果/中间思考摘要为单行，保留关键前缀
保全	`PreservedSegment`	全程确保系统提示/最近 N 轮/关键结果不下沉，压缩后校验补回
熔断	`TokenCircuitBreaker`	压缩连续失败即熔断，兜底返回原消息，不无限重试