# Jude Agent

[![Python Version](https://img.shields.io/pypi/pyversions/jude-agent)](https://pypi.org/project/jude-agent/)
[![License](https://img.shields.io/pypi/l/jude-agent)](LICENSE) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
[![CI](https://github.com/humanleft/jude_agent/actions/workflows/ci.yml/badge.svg)](https://github.com/humanleft/jude_agent/actions)
[![Coverage](https://codecov.io/gh/humanleft/jude_agent/branch/main/graph/badge.svg)](https://codecov.io/gh/humanleft/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. 安装依赖

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

# 安装项目依赖
uv sync
```

### 2. 配置环境变量

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

从 [MiniMax 开放平台](https://platform.minimaxi.com/) 获取 API Key 并填入 `.env`。

### 3. 启动 Ollama (Embedding)

```bash
# 启动 Ollama
ollama serve

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

### 4. 初始化并运行

```bash
# 初始化知识库
uv run agent init

# 启动服务
uv run agent gateway

# 或使用 CLI
uv run agent cli
```

## 快速命令

```bash
# 安装项目（推荐）- 自动安装依赖并创建可执行命令
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
```

## 完整命令（无需安装）

```bash
# 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
```

## 文档

- [架构文档](docs/architecture.md) - 系统架构和流程图
- [API 参考](docs/api.md) - 所有 API 端点说明
- [核心概念](docs/concepts.md) - 技术原理和概念解释

## 配置

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `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 |

## 测试

```bash
# 运行测试
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 支持在运行时动态创建新工具：

```bash
# 在 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` 启用/禁用工具：

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