# OpenAgent

**Repository Path**: zhangmf9773/open-agent

## Basic Information

- **Project Name**: OpenAgent
- **Description**: Open_Agent是一个专注于开发开放智能代理系统的团队，支持多平台应用，涵盖自动化决策、数据处理等场景，致力于为开发者提供高效灵活的解决方案。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="assets/logo.svg" alt="OpenAgent Logo" width="720">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-blue?logo=python" alt="Python">
  <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/Version-1.0.0-brightgreen" alt="Version">
  <img src="https://img.shields.io/badge/Models-12-orange" alt="Models">
  <img src="https://img.shields.io/badge/Tools-13-purple" alt="Tools">
  <img src="https://img.shields.io/badge/Skills-21-red" alt="Skills">
  <img src="https://img.shields.io/badge/Commands-33-yellow" alt="Commands">
</p>

---

# OpenAgent

> 一个 Python 原生的全功能 AI Agent 平台。终端里跑，浏览器里聊，代码随便改。

OpenAgent 将 LLM 的推理能力与真实世界的工具连接起来——Shell 命令、文件操作、网页搜索、代码执行——全部开箱即用。支持 12 个模型提供商、三层记忆系统、21 个内置技能，以及一个暗色主题的 Web UI。

---

## 目录

- [快速开始](#快速开始)
- [核心能力](#核心能力)
- [配置指南](#配置指南)
- [命令系统](#命令系统)
- [记忆系统](#记忆系统)
- [技能系统](#技能系统)
- [Web UI](#web-ui)
- [架构总览](#架构总览)
- [扩展开发](#扩展开发)
- [更新日志](#更新日志)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

---

## 快速开始

```bash
# 克隆仓库
git clone https://gitee.com/zhangmf9773/open-agent.git
cd open-agent

# 安装
pip install -e .

# 启动 CLI
openagent

# 或在 CLI 中输入 /web 打开浏览器界面
```

API Key 自动从 `~/.openagent/.env` 或 `~/.hermes/.env` 加载，无需额外配置即可使用。

---

## 核心能力

| 能力              | 说明                                                   |
|-----------------|------------------------------------------------------|
| 🤖 **Agent 循环** | LLM → 工具调用 → 结果注入 → 继续推理，全程流式输出                      |
| 🔧 **工具执行**     | Shell、文件读写、网页搜索、HTTP 请求、Python 代码执行                  |
| 🧠 **持久记忆**     | 用户画像 + 角色灵魂 + 环境记忆，跨会话保留                             |
| 📦 **技能加载**     | 21 个 Markdown 技能，覆盖开发、运维、AI、安全等领域                    |
| 🌐 **Web UI**   | Flask + SSE 流式聊天，暗色主题，工具调用可视化                        |
| 💬 **命令系统**     | 33 个 slash 命令管理会话、模型、记忆、技能                           |
| 📡 **多模型**      | DeepSeek / OpenAI / Claude / Qwen / Ollama 等 12 个提供商 |
| 🛡️ **容错机制**    | 连续工具失败自动降级文本回答，API 自动重试 3 次                          |

---

## 配置指南

### 环境变量

在 `~/.openagent/.env` 中设置 API Key：

```bash
DEEPSEEK_API_KEY=your_key_here       # DeepSeek（推荐，性价比高）
OPENAI_API_KEY=your_key_herex        # OpenAI
ANTHROPIC_API_KEY=your               # Claude
DASHSCOPE_API_KEY=your_key_here      # 通义千问
MINIMAX_API_KEY=your_key_here        # MiniMax
TENCENT_API_KEY=your_key_here        # 腾讯混元
```

### config.yaml

```yaml
llm:
  default: deepseek            # 默认模型

agent:
  system_prompt: "..."         # 系统提示词
  max_tool_rounds: 6           # 最大工具调用轮数

tools:
  terminal:
    allowed_commands: []       # 空 = 允许所有
    blocked_commands: []       # 空 = 不阻止任何
    timeout: 300               # 命令超时（秒）
  web:
    timeout: 30
```

### 添加新模型

一行配置即可接入任何 OpenAI 兼容的 API：

```yaml
llm:
  providers:
    my_provider:
      type: openai_compatible
      base_url: https://api.example.com/v1
      api_key: ${MY_API_KEY}
      model: my-model
```

---

## 命令系统

CLI 中所有操作通过 `/` 命令完成，共 33 个：

### 会话管理 (5个)

| 命令             | 说明       | 命令             | 说明           |
|----------------|----------|----------------|--------------|
| `/new`         | 新建会话     | `/resume`      | 恢复最近会话       |
| `/sessions`    | 历史会话列表   | `/load <id>`   | 加载指定会话       |
| `/history [n]` | 查看对话历史   | `/undo`        | 撤销最后一轮       |
| `/retry`       | 重试上一条    | `/save [path]` | 导出为 Markdown |
| `/clear`       | 清屏 + 新会话 | `/title <名称>`  | 设置会话标题       |

### 模型与配置 (5个)

| 命令              | 说明               |
|-----------------|------------------|
| `/model [名称]`   | 切换或查看当前模型        |
| `/config [key]` | 查看配置项            |
| `/system [文本]`  | 查看或修改系统提示词       |
| `/verbose`      | 切换详细模式（显示工具返回详情） |
| `/yolo`         | 切换自动执行模式（跳过确认）   |

### 记忆管理(6个)

| 命令                    | 说明     |
|-----------------------|--------|
| `/user add/del/clear` | 管理用户画像 |
| `/soul add/del/clear` | 管理角色灵魂 |
| `/memory`             | 查看环境记忆 |
| `/memory-add <类型:内容>` | 添加记忆   |
| `/memory-del <id>`    | 删除记忆   |
| `/memory-clear`       | 清空记忆   |

### 其他(8个)

| 命令                   | 说明           |
|----------------------|--------------|
| `/web [start/stop]`  | 启动或停止 Web UI |
| `/skills`            | 列出所有技能       |
| `/skill <名称>`        | 切换技能开关       |
| `/tools`             | 列出可用工具       |
| `/status`            | 查看当前状态       |
| `/usage`             | 查看 Token 用量  |
| `/help [命令]`         | 查看帮助         |
| `/quit` `/exit` `/q` | 退出           |

---

## 内置工具(15个)

| 工具              | 功能                  | 典型用法                        |
|-----------------|---------------------|-----------------------------|
| `terminal`      | Shell 交互            | `git log`、`npm run build`   |
| `read_file`     | 读取文件（带行号）           | 查代码、配置文件                    |
| `write_file`    | 创建/覆盖文件             | 生成脚本、修改配置                   |
| `search_files`  | 正则搜索文件内容            | 定位函数定义、错误信息                 |
| `list_files`    | 目录浏览                | 了解项目结构                      |
| `download_file` | 文件下载                | 下载文件、资源                     |
| `web_request`   | HTTP 请求 + HTML 提取   | 调用 API、抓取网页                 |
| `web_search`    | Bing 搜索引擎           | 查最新文档、技术资讯                  |
| `web_browse`    | 网页浏览                | 浏览网页、查看信息                   |
| `code_exec`     | Python 子进程执行        | 数据处理、跑测试                    |
| `edit_file`     | 文件编辑                | 数据处理、跑测试                    |
| `python_exec`   | Python 运行时执行        | 数据处理、跑测试                    |
| `memory`        | 记忆管理                | 添加、删除、清空记忆                  |
| `process`       | 进程管理                | 进程管理、任务调度                   |
| `todo`          | 规划计划                | 规划计划、任务管理                   |

|
---

## 记忆系统

OpenAgent 拥有三层结构化记忆，所有记忆跨会话持久化并自动注入 System Prompt：

```
┌─────────────────────────────────────┐
│  👤 用户画像    你是谁、偏好、项目      │
│  ✨ 灵魂        角色设定、语气风格      │
│  📋 环境记忆    路径、配置、Bug 修复    │
└─────────────────────────────────────┘
```

### 使用示例

```bash
/soul add 你是一个简洁犀利的代码助手，不说废话
/user add 我在开发一个 Flask 项目，路径 ~/myapp
/memory-add 上次的 Bug 是因为 SQLAlchemy 连接池没配置
```

### 记忆操作

| 命令    |        画像        |        灵魂        |          环境           |
|-------|:----------------:|:----------------:|:---------------------:|
| 查看    |     `/user`      |     `/soul`      |       `/memory`       |
| 添加    | `/user add <内容>` | `/soul add <内容>` | `/memory-add <类型:内容>` |
| 删除    | `/user del <id>` | `/soul del <id>` |  `/memory-del <id>`   |
| 清空    |  `/user clear`   |  `/soul clear`   |    `/memory-clear`    |

---

## 技能系统

技能是独立的 Markdown 文件，Agent 加载后获得对应领域的专业指令。21 个内置技能覆盖以下领域：

| 类别           | 技能                                                                                             |
|--------------|------------------------------------------------------------------------------------------------|
| 🔧 **开发**    | `python-dev` `git-workflow` `api-design` `database-design` `web-dev` `documentation` `testing` |
| 🚀 **运维**    | `docker` `docker-compose` `linux` `cicd` `monitoring` `shell-scripting`                        |
| 🤖 **AI/数据** | `machine-learning-basics` `data-analysis` `prompt-engineering`                                 |
| 🛡️ **质量**   | `security` `performance-optimization` `debugging`                                              |
| 📦 **通用**    | `example-dev` `practical-assistant`                                                            |

### 使用示例
```bash
/skills          # 查看所有技能及状态
/skill docker    # 切换 docker 技能开关
```

技能文件放在 `~/.openagent/.trae/skills/`，自定义技能只需一个 Markdown 文件。

---

## Web UI

```
/web              # CLI 中一键启动
# → 自动打开浏览器 http://127.0.0.1:5555
```

- **Flask + SSE** — 流式聊天，逐字渲染
- **暗色主题** — GitHub 风格配色
- **工具调用可视化** — 实时显示 Agent 在执行什么工具
- **CLI 不中断** — 后台线程运行，CLI 继续可用

---

## 架构总览

```
openagent/
├── openagent/
│   ├── cli.py                    # prompt_toolkit 交互 CLI
│   ├── agent.py                  # Agent 循环核心（工具调用 → 结果注入）
│   ├── commands.py               # 命令注册表（/ 命令系统）
│   ├── config.py                 # YAML 配置 + 环境变量加载
│   ├── session.py                # 会话持久化
│   ├── memory.py                 # 三层记忆引擎
│   ├── skills.py                 # Markdown 技能加载器
│   ├── intent.py                 # 意图识别
│   ├── web.py                    # Flask Web 服务
│   ├── llm/                      # LLM 适配层
│   │   ├── base.py               # 抽象接口
│   │   ├── openai_compatible.py  # OpenAI 兼容（覆盖 11 个模型）
│   │   └── anthropic.py          # Claude SDK
│   └── tools/                    # 工具层
│       ├── base.py               # 工具基类 + 注册中心
│       ├── builtin/              # 8 个内置工具
│       └── anthropic/            # Claude 技能
│── tests/                        # 测试文件
├── assets/                       # 静态资源
├── .trae/skills                  # 技能文件
├── config.yaml                   # 配置文件
├── pyproject.toml                # 项目依赖
├── README.md                     # 说明文档
├── LICENSE                       # 许可协议
├── requirements.txt              # 项目依赖
├── verify_integration.py         # 集成测试
└── assets/logo.svg               # logo
```

---

## 扩展开发

### 添加工具（3 步）

```python
# 1. 创建 openagent/tools/builtin/my_tool.py
from openagent.tools.base import Tool

class MyTool(Tool):
    name = "my_tool"
    description = "描述这个工具的作用"

    parameters = {
        "type": "object",
        "properties": {
            "input": {"type": "string", "description": "输入参数"}
        },
        "required": ["input"],
    }

    async def execute(self, input: str = "") -> str:
        # 工具逻辑
        return f"处理结果: {input}"

# 2. 在 register_defaults() 中注册
# 3. 在 __init__.py 中导出
```

### 添加技能（1 个文件）

```bash
# 在 ~/.openagent/skills/ 下创建 my-skill.md

---
name: my-skill
description: 自定义技能描述
version: 1.0
tags: [示例]
---

# 我的技能

## 规则
- 规则 1：...
- 规则 2：...

## 最佳实践
- ...
```

---

## 更新日志

### v1.0.0 (2026-05-31)

- 🌐 新增 `/web` 命令，CLI 中一键启动 Web UI
- 🎨 全新 SVG Logo
- ✨ 意图识别模块
- 📝 重构 README，更专业清晰
- 🐛 Web 服务后台运行不阻塞 CLI

### v0.4.0 (2026-05-30)

- ✨ 新增 14 个技能（Docker、数据库、API、测试、安全、ML 等）
- 🤖 技能自动加载
- 🔐 最高权限配置
- 📝 重写文档

---

## 贡献指南

欢迎 Issue、PR 和 Star ⭐

1. Fork 本仓库
2. 创建分支 `git checkout -b feature/my-feature`
3. 提交 `git commit -m "feat: add my feature"`
4. 推送 `git push origin feature/my-feature`
5. 创建 Pull Request

**规范：** Python 3.10+ · 类型注解 · PEP 8 · 提交信息用中文或 Conventional Commits

---

## 许可证

MIT License © 2026 [zhangmf9773](https://gitee.com/zhangmf9773)

---

<p style="text-align: center;">
  <strong>OpenAgent</strong> — 让 AI Agent 更简单、更强大
</p>
<p align="center">
  <a href="https://gitee.com/zhangmf9773/open-agent">Gitee 项目地址</a>
</p>