jude-agent 0.3.0

智能 Agent，支持多渠道对话和 RAG 能力

Jude Agent

一个智能 Agent 项目，支持多渠道（CLI、HTTP Gateway、飞书）对话，具备 RAG（检索增强生成）能力。

技术栈

• LLM: MiniMax Anthropic API (MiniMax-M2.5)
• Embedding: Ollama (nomic-embed-text, 本地运行)
• 向量数据库: Chroma
• 框架: LangChain v1 (含 Agent 框架 + Middleware 动态工具加载)
• 项目管理/打包: uv (uv_build 后端)
• HTTP 框架: Flask
• 事件系统: 自研同步事件总线

快速开始

1. 安装依赖

# 安装 uv (如果没有)
brew install uv

# 安装项目依赖
uv sync

2. 配置环境变量

# 复制配置模板
cp .env.example .env

从 MiniMax 开放平台 获取 API Key 并填入 .env。

3. 启动 Ollama (Embedding)

# 启动 Ollama
ollama serve

# 下载 Embedding 模型
ollama pull nomic-embed-text

4. 初始化并运行

# 初始化知识库
uv run agent init

# 启动服务
uv run agent gateway

# 或使用 CLI
uv run agent cli

快速命令

# 安装项目（推荐）- 自动安装依赖并创建可执行命令
uv pip install -e .

# 或使用 uv run（无需安装）
uv sync

# 启动服务
agent gateway              # 默认端口 8080
agent gateway --port 9000 # 指定端口

# CLI 客户端
agent cli                 # 交互式对话
agent cli ask "问题"      # 单次问答
agent cli --no-rag ask "问题"  # 禁用 RAG

# 飞书通道
agent feishu

完整命令（无需安装）

# HTTP 服务
uv run agent gateway              # 默认端口 8080
uv run agent gateway --port 9000 # 指定端口

# CLI 客户端
uv run agent cli                 # 交互式对话
uv run agent cli ask "问题"      # 单次问答
uv run agent cli --no-rag ask "问题"  # 禁用 RAG

# 飞书通道
uv run agent feishu

文档

• 架构文档 - 系统架构和流程图
• API 参考 - 所有 API 端点说明
• 核心概念 - 技术原理和概念解释

配置

环境变量

变量	说明	默认值
ANTHROPIC_API_KEY	MiniMax API Key	(必填)
ANTHROPIC_BASE_URL	API 端点	https://api.minimaxi.com/anthropic
LLM_MODEL	LLM 模型	MiniMax-M2.5
EMBEDDING_MODEL	Embedding 模型	nomic-embed-text
CHUNK_SIZE	文本分块大小	500
TOP_K	检索返回数	3
AGENT_MODEL	Agent 模型	MiniMax-M2.5
AGENT_SERVER_PORT	服务端口	8080

记忆配置

变量	说明	默认值
AGENT_MEMORY_MAX_MESSAGES	最多保留消息数	20
AGENT_MEMORY_SUMMARY_THRESHOLD	触发摘要的消息数	10

测试

# 运行测试
uv run pytest tests/ -v

# 代码检查
ruff check .
uv run mypy src/

文件说明

目录/文件	说明
src/config/	统一配置模块
src/core/	核心组件（LLM、Agent、Memory、Middleware）
src/events/	事件系统
src/gateway/	Flask HTTP 网关
src/rag/	RAG 核心模块
src/agent/	Agent 模块
src/agent/tools/	工具系统（插件式架构）
data/	测试文档目录
chroma_db/	向量数据库
~/.local/share/jude_agent/plugins/	本地插件目录
docs/	详细文档

动态工具创建

Agent 支持在运行时动态创建新工具：

# 在 CLI 中告诉 Agent 创建新工具
uv run agent cli
# 然后输入: "请创建一个问候工具，输入名字返回 Hello xxx!"

工作流程

1. Agent 判断需要新工具
2. 调用 create_tool 工具
3. 自动生成 Python 代码并保存到插件目录
4. 代码验证（语法 + 结构）
5. 热加载到当前 Agent 实例
6. 新工具立即可用

LangChain v1 Middleware 架构

项目使用 LangChain v1 原生支持的 Middleware 架构实现动态工具加载：

LLM 调用 ──► DynamicToolMiddleware.wrap_model_call()
                │
                ▼
        获取最新工具列表 ──► 动态更新请求
                │
                ▼
        执行 LLM 调用
                │
                ▼
        wrap_tool_call()（处理动态工具执行）

内置工具

工具	功能
calculator	数学计算
search_documents	搜索知识库文档
create_tool	动态创建新工具
list_plugins	列出已安装的插件

工具配置

编辑 tools.yaml 启用/禁用工具：

tools:
  calculator: true
  search_documents: true
  create_tool: true
  list_plugins: true
  delete_plugin: false