# zx-openagent

**Repository Path**: luckSnow/zx-openagent

## Basic Information

- **Project Name**: zx-openagent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenAgent

Claude Code 风格的 Coding Agent，基于 LLM + Agent Runtime + Tool System + Context Engine 架构，支持多轮对话、代码库理解、任务分解、工具调用和自动代码修改。

## 功能特性

- **ReAct Agent Loop** — LLM 驱动的自主推理-行动循环，自动调用工具完成任务
- **双 LLM Provider** — 同时支持 OpenAI Compatible API 和 Anthropic API
- **Tool Calling** — 内置文件读写、目录浏览、代码搜索、Shell 执行等工具
- **Todo 任务规划** — 自动分解任务、跟踪进度，支持 pending/doing/done/failed 状态
- **上下文记忆** — 多轮对话记忆，超过阈值自动摘要，避免 Token 溢出
- **Web 调试界面** — FastAPI + SSE 实时推送，可视化查看 Agent 思考过程、工具调用和任务状态
- **跨平台** — 支持 Windows / macOS / Linux，代码搜索工具自动适配平台

## 项目结构

```
zx-openagent/
├── agent/
│   ├── llm/                  # LLM 客户端抽象层
│   │   ├── client.py         # OpenAI / Anthropic 双 Provider 实现
│   │   └── prompts.py        # System Prompt 与工具描述
│   ├── runtime/              # Agent 运行时
│   │   ├── agent.py          # 核心 Agent（ReAct Loop）
│   │   ├── memory.py         # 对话记忆与自动摘要
│   │   └── planner.py        # Todo 任务管理器
│   ├── tools/                # 工具系统
│   │   ├── base.py           # Tool 基类 & 注册表（单例）
│   │   ├── file_tool.py      # 文件读写 / 目录浏览
│   │   ├── search_tool.py    # 代码搜索（grep / findstr / Python 回退）
│   │   ├── shell_tool.py     # Shell 命令执行
│   │   └── todo_tool.py      # Todo 增删改查工具
│   └── web/                  # Web 调试界面
│       ├── server.py         # FastAPI + SSE 服务端
│       └── static/           # 前端页面（HTML / CSS / JS）
├── tests/                    # 测试
│   ├── test_agent.py         # Agent 集成测试
│   ├── test_tools.py         # 工具注册与执行测试
│   └── test_grep.py          # 代码搜索测试
├── main.py                   # CLI 入口
├── web_server.py             # Web 调试界面入口
├── requirements.txt          # 依赖
└── .env.example              # 环境变量模板
```

## 快速开始

### 1. 安装依赖

```bash
python -m venv venv

# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的 API Key：

```env
# 选择 Provider: openai 或 anthropic
LLM_PROVIDER=openai

# OpenAI 配置
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL=gpt-4.1

# Anthropic 配置
ANTHROPIC_API_KEY=sk-ant-xxx
ANTHROPIC_MODEL=claude-sonnet-4-20250514
```

### 3. 运行

**CLI 模式：**

```bash
python main.py
```

**Web 调试模式：**

```bash
python web_server.py
# 指定端口
python web_server.py --port 9000
```

浏览器访问 `http://localhost:8000` 即可使用 Web 调试界面。

## 内置工具

| 工具名 | 说明 |
|--------|------|
| `read_file` | 读取文件内容 |
| `write_file` | 写入/创建文件 |
| `list_dir` | 列出目录内容 |
| `grep_code` | 代码搜索（支持正则、文件类型过滤） |
| `run_shell` | 执行 Shell 命令 |
| `todo_add` | 添加任务 |
| `todo_update` | 更新任务状态 |
| `todo_list` | 查看所有任务 |

## 架构设计

```
┌─────────────┐
│   User Input │
└──────┬──────┘
       │
       ▼
┌──────────────────────────────────────┐
│            Agent (ReAct Loop)        │
│                                      │
│  ┌──────────┐    ┌───────────────┐   │
│  │   LLM    │◄──►│    Memory     │   │
│  │  Client  │    │ (auto summary)│   │
│  └────┬─────┘    └───────────────┘   │
│       │                              │
│       ▼                              │
│  ┌──────────┐    ┌───────────────┐   │
│  │  Tools   │    │    Planner    │   │
│  │ Registry │    │  (Todo List)  │   │
│  └──────────┘    └───────────────┘   │
│                                      │
└──────────────────────────────────────┘
       │
       ▼
┌─────────────┐
│  Response    │
└─────────────┘
```

**核心流程：**

1. 用户输入 → 存入 Memory
2. 构建 System Prompt + 历史消息 → 调用 LLM
3. LLM 返回 Tool Call → 执行工具 → 结果存入 Memory → 回到步骤 2
4. LLM 返回文本响应 → 输出给用户

## Web 调试界面

Web 模式通过 SSE（Server-Sent Events）实时推送 Agent 运行事件：

- **thinking** — Agent 当前迭代状态
- **tool_call** — 工具调用名称和参数
- **tool_result** — 工具执行结果
- **todo_update** — 任务列表变更
- **response** — Agent 最终回复
- **error** / **done** — 错误与完成信号

## 扩展工具

实现 `Tool` 基类并注册即可：

```python
from agent.tools.base import Tool, ToolRegistry

class MyTool(Tool):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "A custom tool"

    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "input": {"type": "string", "description": "Input text"}
            },
            "required": ["input"],
        }

    def execute(self, **kwargs):
        return f"Processed: {kwargs['input']}"

# 注册（ToolRegistry 为单例，自动注册）
MyTool()
```

## 技术栈

- **Python 3.10+**
- **OpenAI SDK** / **Anthropic SDK** — LLM 调用
- **Rich** — CLI 美化输出
- **FastAPI** + **SSE** (原生 StreamingResponse) — Web 调试服务
- **Uvicorn** — ASGI 服务器
- **python-dotenv** — 环境变量管理

## License

MIT