# AI Agent Demo

**Repository Path**: yanglinghui/ai-agent-demo

## Basic Information

- **Project Name**: AI Agent Demo
- **Description**: 基于 LangChain + Ollama 的企业级 AI Agent，提供代码助手和文档生成能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent Demo

基于 LangChain + Ollama 的企业级 AI Agent，提供代码助手和文档生成能力。

## 功能特性

- **代码助手** - 代码格式化、解释、重构、单元测试生成
- **文档生成** - API 文档、README、文档字符串自动生成
- **知识库** - 支持 GitLab 仓库、本地文档、Web 文档的向量检索

## 快速开始

### 1. 安装 uv

```bash
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. 克隆并进入项目

```bash
git clone <repo-url>
cd ai-agent-demo
```

### 3. 创建虚拟环境并安装依赖

```bash
# 创建虚拟环境
uv venv

# 激活环境
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安装依赖
uv pip install -r requirements.txt
```

### 4. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，填写你的配置
```

### 5. 启动 Ollama

确保本地已安装 Ollama 并拉取了模型：

```bash
ollama pull qwen2.5:14b
ollama serve
```

### 6. 运行 Demo

```bash
cd src
python main.py
```

## 实现机制

### 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                         Main                                │
│                    (Entry Point)                            │
└──────────────────────┬────────────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ CodeAssistant│ │  DocWriter  │ │KnowledgeBase│
│  (代码助手)   │ │  (文档生成)  │ │  (知识库)    │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
       │               │               │
       ▼               ▼               ▼
┌───────────────────────────────────────────────┐
│              Ollama LLM                       │
│         (Local Language Model)                │
└───────────────────────────────────────────────┘
```

### 核心组件

#### 1. CodeAssistant (代码助手)

基于 AST (抽象语法树) 实现代码分析：

```python
# 代码格式化
autopep8.fix_code(code)

# AST 分析
tree = ast.parse(code)
for node in ast.walk(tree):
    if isinstance(node, ast.FunctionDef):
        # 分析函数定义
        analyze_function(node)
```

**功能模块：**
- `_handle_code_format`: 使用 autopep8 格式化代码
- `_handle_code_explanation`: AST 解析生成代码解释
- `_handle_code_refactor`: 基于 AST 的重构建议
- `_generate_unit_test`: 根据函数签名生成测试模板

#### 2. DocWriter (文档生成)

使用模板引擎生成标准化文档：

```python
TEMPLATES = {
    "api": "...",      # API 文档模板
    "readme": "...",   # README 模板
}

def _generate_api_doc(query):
    # 检索知识库中的相关文档
    relevant_docs = kb.get_relevant_docs(query)
    # 填充模板
    return TEMPLATES["api"].format(**template_args)
```

#### 3. KnowledgeBase (知识库)

向量检索架构：

```
┌─────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Document       │────▶│  Text Splitter   │────▶│  Embeddings  │
│  Loaders        │     │  (Chunking)      │     │  (Vectorize) │
└─────────────────┘     └──────────────────┘     └──────┬───────┘
                                                        │
                                                        ▼
                                              ┌─────────────────┐
                                              │  ChromaDB       │
                                              │  (Vector Store) │
                                              └────────┬────────┘
                                                       │
                                                       │ Similarity Search
                                                       ▼
                                              ┌─────────────────┐
                                              │  Results        │
                                              └─────────────────┘
```

**技术栈：**
- **Embeddings**: HuggingFace (`moka-ai/m3e-base` 中文支持)
- **Vector Store**: ChromaDB (持久化存储)
- **Text Splitter**: RecursiveCharacterTextSplitter (1000 chars, 200 overlap)
- **Document Loaders**: GitLoader, DirectoryLoader, WebBaseLoader

**数据源支持：**
```python
# GitLab 仓库
kb.load_gitlab_repos(url, token, group_ids, project_ids)

# 本地文档
kb.load_doc_center({"local": [...], "web": [...], "git": [...]})
```

### Agent 架构

使用 LangChain 的 ReAct Agent：

```python
from langchain.agents import initialize_agent, AgentType

agent = initialize_agent(
    tools=[CodeAssistant(kb), DocWriter(kb)],
    llm=OllamaLLM(model="qwen2.5:14b"),
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)
```

**执行流程：**
1. 用户输入 → Agent 分析意图
2. 选择 Tool (CodeAssistant / DocWriter)
3. Tool 调用知识库检索上下文
4. 生成结果 → 返回给用户

## 配置说明

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `OLLAMA_MODEL` | 使用的 Ollama 模型 | `qwen2.5:14b` |
| `OLLAMA_HOST` | Ollama 服务地址 | `http://localhost:11434` |
| `GITLAB_URL` | GitLab 地址 | - |
| `GITLAB_TOKEN` | GitLab 访问令牌 | - |
| `GITLAB_GROUPS` | 要加载的组 ID，逗号分隔 | - |
| `GITLAB_PROJECTS` | 要加载的项目 ID，逗号分隔 | - |
| `DOC_LOCAL_PATHS` | 本地文档路径，逗号分隔 | - |
| `DOC_WEB_URLS` | Web 文档 URL，逗号分隔 | - |

## 项目结构

```
.
├── src/
│   ├── main.py                 # 入口文件
│   └── tools/
│       ├── code_assistant.py   # 代码助手
│       ├── doc_writer.py       # 文档生成
│       └── knowledge_base.py   # 知识库
├── tests/                      # 测试用例
├── requirements.txt            # 依赖
├── .env.example                # 环境变量模板
└── README.md                   # 本文件
```

## 运行测试

```bash
pytest tests/ -v
```

## 许可证

MIT License