# opt_agent

**Repository Path**: xk_git_admin/opt_agent

## Basic Information

- **Project Name**: opt_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OPT-Agent - IT 运维智能体系统

面向 IT 运维领域的智能体系统，提供智能化的运维自动化解决方案。

## 核心功能

### 1. 技能管理 (Skills) 系统
- 可扩展的技能注册机制
- 动态加载运维相关技能
- 技能元数据管理
- 支持自定义技能

### 2. 运维能力
- Linux Shell 命令执行（本地/远程）
- Python 脚本自动生成与执行
- 文件操作（读/写/列表/删除）
- 命令执行沙箱机制

### 3. 交互界面
- 命令行客户端（CLI）
- TUI 终端用户界面（类似 OpenCode）
- 交互式 REPL
- 命令补全与历史记录（统一格式，支持跨客户端共享）
- 语法高亮
- REST API 接口

### 4. 安全特性
- 命令执行沙箱隔离
- 权限管理系统
- 安全审计日志
- 敏感操作确认机制

## 快速开始

### 安装依赖

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate  # Windows

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

### 配置系统

编辑 `config.yaml` 文件：

```yaml
# 系统配置
system:
  name: "OPT-Agent"
  version: "0.1.0"
  environment: "development"
  debug: true

# LLM 配置（阿里云百炼）
llm:
  provider: "openai"
  model: "qwen-plus"
  api_key: "${LLM_API_KEY}"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  temperature: 0.1
  max_tokens: 4096

# 执行器配置
executor:
  shell:
    timeout: 30
    max_output_size: 1048576
  python:
    timeout: 60
    max_memory_mb: 512
    allow_network: false

# 智能体配置
agent:
  type: "react"  # tool, react, planning, reflective, hybrid
  max_iterations: 10

# 技能配置
skills:
  install_dir: "~/.opt_agent/skills"
  auto_discover: true

# 日志配置
logging:
  level: "DEBUG"
  format: "text"
  output:
    - type: "console"
      enabled: false
    - type: "file"
      enabled: true
      path: "logs/opt-agent.log"
```

### 启动 TUI 界面（推荐）

```bash
# 启动 TUI 界面
python -m cli.tui_app

# 或使用新版 TUI
python -m cli.tui.app
```

### 启动命令行客户端

```bash
# 交互式模式
python -m cli.client

# 执行单条命令
python -m cli.client -c "检查磁盘使用情况"
```

### 启动 API 服务器

```bash
# 使用 uvicorn 启动
uvicorn api.routes:app --host 0.0.0.0 --port 8000 --reload
```

访问 API 文档：http://localhost:8000/docs

## 项目结构

```
opt_agent/
├── core/                    # 核心框架
│   ├── config.py           # 配置管理
│   ├── agent.py            # 智能体（BaseAgent, ChatAgent, ToolAgent）
│   ├── memory.py           # 对话记忆管理
│   ├── permission.py       # 权限管理
│   ├── persistent_memory.py # 持久化记忆
│   └── container.py       # 容器管理
├── skills/                  # 技能系统
│   ├── base.py             # 技能基类
│   ├── registry.py         # 技能注册中心
│   ├── adapter.py          # LangChain 工具适配器
│   ├── matcher.py          # 技能匹配器
│   ├── injector.py         # 技能注入器
│   ├── downloader.py       # 技能下载器
│   ├── python/             # Python 技能
│   │   ├── base.py
│   │   ├── adapter.py
│   │   ├── registry.py
│   │   └── builtin/       # 内置技能
│   │       ├── shell.py    # Shell 执行
│   │       ├── python_exec.py  # Python 执行
│   │       └── file_ops.py # 文件操作
│   └── markdown/           # Markdown 技能
│       ├── parser.py
│       ├── loader.py
│       └── adapter.py
├── executor/                # 执行器
│   ├── shell_executor.py   # Shell 执行器
│   ├── python_executor.py  # Python 执行器
│   ├── sandbox.py          # 沙箱隔离
│   └── security.py         # 安全审计
├── cli/                     # 命令行界面
│   ├── client.py           # CLI 客户端
│   ├── repl.py             # 交互式 REPL
│   ├── tui_app.py          # TUI 入口
│   ├── agent_factory.py    # 智能体工厂
│   └── tui/                # TUI 子模块
│       ├── app.py          # TUI 主应用
│       ├── component/      # UI 组件
│       │   ├── chat/       # 聊天组件
│       │   ├── core/       # 核心组件
│       │   └── dialog/     # 对话框组件
│       ├── themes/         # 主题系统
│       └── utils/          # 工具函数
├── api/                     # API 接口
│   ├── routes.py           # REST API
│   └── integrations/       # 外部集成
│       ├── monitoring.py   # 监控平台
│       └── ticketing.py    # 工单系统
├── utils/                   # 工具模块
│   ├── logger.py           # 日志
│   ├── exceptions.py       # 异常
│   └── validators.py       # 验证器
├── tests/                   # 测试
│   ├── unit/               # 单元测试
│   ├── integration/        # 集成测试
│   └── performance/        # 性能测试
├── config.yaml             # 主配置文件
├── permission.yaml         # 权限配置
└── requirements.txt        # 依赖清单
```

## 使用示例

### TUI 界面

```bash
# 启动 TUI
python -m cli.tui_app

# 快捷键
# ↑/↓     - 历史命令导航
# Tab     - 命令补全
# Ctrl+C  - 取消当前操作
# Ctrl+D  - 退出应用
# Ctrl+?  - 帮助对话框
# Ctrl+O  - 模型选择
# Ctrl+K  - 命令对话框

# 历史记录说明
# - 历史命令保存在 ~/.opt_agent/history
# - TUI 和 CLI 共享同一历史记录文件
# - 支持旧格式兼容（带时间戳标记）
# - 新格式：纯文本，每行一条命令
```

### Shell 命令执行

```python
from executor.shell_executor import ShellExecutor

executor = ShellExecutor()
result = await executor.execute("ls -la /home")
print(result.stdout)
```

### Python 脚本执行

```python
from skills.ops.python_exec import PythonExecuteSkill

skill = PythonExecuteSkill()
result = await skill.execute(code="print('Hello, World!')")
print(result.data["stdout"])
```

### 智能体对话

```python
from core.agent import ToolAgent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="qwen-plus")
agent = ToolAgent(name="ops_agent", llm=llm)

result = await agent.run("查看当前系统内存使用情况")
print(result.content)
```

### API 调用

```bash
# 执行 Shell 命令
curl -X POST http://localhost:8000/execute/shell \
  -H "Content-Type: application/json" \
  -d '{"command": "df -h"}'

# 执行 Python 代码
curl -X POST http://localhost:8000/execute/python \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"Hello\")"}'

# 运行智能体
curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -d '{"input": "检查系统负载"}'
```

## 安全特性

### 命令执行沙箱
- 资源限制（内存、CPU、进程数）
- 文件系统隔离
- 网络访问控制

### 权限管理
- 命令白名单/黑名单
- 危险操作检测
- 敏感操作二次确认
- 基于角色的访问控制（RBAC）

### 安全审计
- 操作审计日志
- 完整的审计追踪
- 硬编码凭证检测

## 测试

```bash
# 运行单元测试
pytest tests/unit/ -v

# 运行集成测试
pytest tests/integration/ -v

# 生成覆盖率报告
pytest --cov=opt_agent --cov-report=html
```

## 性能指标

| 指标 | 目标值 | 实测值 |
|------|--------|--------|
| 命令执行响应时间 | <500ms | ~200ms |
| Python 脚本执行时间 | <3s | ~1.5s |
| 并发处理能力 | 10+ | 15 |
| 内存占用 | <500MB | ~300MB |
| 历史记录加载 | <100ms | ~50ms |

## 开发指南

### 添加新技能

```python
from skills.base import BaseSkill, SkillResult, skill

@skill(
    name="my_skill",
    description="我的技能描述",
    tags=["custom"],
)
class MySkill(BaseSkill):
    async def execute(self, **kwargs) -> SkillResult:
        return SkillResult(success=True, data="result")
```

### 集成监控系统

```python
from api.integrations.monitoring import create_monitoring_adapter

adapter = create_monitoring_adapter(
    type="prometheus",
    url="http://localhost:9090"
)

alerts = await adapter.get_alerts()
```

## 故障排除

### 常见问题

1. **LLM 连接失败**
   - 检查 API key 配置
   - 确认网络连接
   - 查看日志：`logs/opt-agent.log`

2. **命令执行超时**
   - 增加 timeout 配置
   - 检查命令复杂度
   - 确认系统资源

3. **权限错误**
   - 检查用户权限
   - 查看命令白名单
   - 确认沙箱配置

4. **TUI 显示异常**
   - 检查终端兼容性
   - 确认 Textual 版本
   - 尝试更新依赖

5. **历史记录无法加载**
   - 检查 ~/.opt_agent/history 文件是否存在
   - 确认文件格式（支持旧格式带时间戳标记）
   - 查看日志：`logs/opt-agent.log`

## 文档

- [LLM_CONFIG.md](LLM_CONFIG.md) - LLM 配置指南
- [USER_GUIDE.md](USER_GUIDE.md) - 使用手册
- [DEPLOYMENT.md](DEPLOYMENT.md) - 部署指南
- [TUI_GUIDE.md](TUI_GUIDE.md) - TUI 使用指南
- [TUI_DEVELOPMENT.md](TUI_DEVELOPMENT.md) - TUI 开发文档
- [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - 项目总结

## 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

MIT License

## 联系方式

- 项目地址：https://gitee.com/xk_git_admin/opt_agent
- 问题反馈：https://gitee.com/xk_git_admin/opt_agent/issues

---

**OPT-Agent** - 让 IT 运维更智能、更高效、更安全