# my_agent_framework

**Repository Path**: lanhe-green/test

## Basic Information

- **Project Name**: my_agent_framework
- **Description**: 我在进行测试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent Framework

多功能 AI 编程助手框架，支持 Web 界面、CLI 和 TUI 三种交互模式。提供 SSH 集群直连管理、RAG 知识库、多 LLM 提供商、MCP 协议扩展、文件操作沙箱等企业级能力。

## 功能特性

### 核心能力
- **多交互模式** — Web 聊天界面 / CLI 命令行 / TUI 终端界面
- **多 LLM 提供商** — OpenAI / Ollama / DeepSeek / 兼容 OpenAI API 的通用提供商
- **RAG 知识库** — ChromaDB 向量检索 + BM25 混合检索 + 知识库问答 + 文件导入
- **MCP 协议支持** — 通过 MCP 服务器接入第三方工具（自动排除与内置工具同名的 MCP 工具），后台持久事件循环
- **工具系统** — 40+ 内置工具：文件操作（沙箱隔离）、Shell 执行（命令白名单）、代码执行、Git 只读操作、文档解析、OCR、Excel 读/分析、日报填写
- **Excel 直接读取** — `read_excel` 工具将 .xlsx/.xls 转为 Markdown 表格，支持全量/摘要双模式
- **文件下载 API** — AI 生成的文件自动识别路径并生成下载按钮（仅 sandbox / uploads 白名单内可下载）
- **计划模式** — AI 自动拆解复杂目标为多步计划并逐步执行
- **会话管理** — 多会话持久化、上下文管理、分支管理

### SSH 集群管理（无需节点装 Agent）
- **SSH 直连** — 通过 paramiko 直接 SSH 远程工站，不需要在节点上安装任何软件
- **节点配置** — YAML 文件管理节点清单，支持手动添加/移除
- **批量操作** — 并发 SSH 执行命令，Semaphore 控制并发，默认 5 台一批
- **文件传输** — SFTP 上传/下载/远程读取脚本、日志、测试结果
- **密码认证** — 启动时手动输入统一密码，仅存内存，连接复用减少握手（5 分钟 TTL）

### 工站状态与异常检测
- **按需检查** — 问的时候才查，不设后台定时巡检
- **异常模式识别** — 自动检测进程崩溃(CRASH)、磁盘爆满(DISK_FULL)、批量失败(BATCH_FAIL)、超时(TIMEOUT)
- **FAIL 分析** — SSH grep 搜索日志，可选拉取完整 record 文件到本地深度分析
- **结果缓存** — 2 分钟内重复查询返回缓存，避免反复 SSH

### 审批与审计
- **审批流程** — 高风险操作（杀进程、批量执行）需人工确认
- **审计日志** — SHA256 签名，不可篡改
- **告警系统** — P0-P3 四级告警，自动聚合，WebSocket 实时推送

### 系统与安全
- **安全机制** — 沙箱路径隔离、Shell 元字符检测、文件上传 MIME 校验、Bearer Token 认证、速率限制
- **会话锁超时** — 300s 自动释放死锁，防止请求永久挂起
- **SSE 流式超时** — 空闲 30s 发送心跳，300s 总体超时强制终止
- **内置监控** — Prometheus 指标端点、系统资源监控、健康检查

## 快速开始

### 前置要求

- Python 3.10+
- （可选）Ollama — 使用本地模型

### 安装

```bash
# 1. 克隆仓库
git clone <repo-url> && cd AI_project

# 2. 安装依赖
pip install -r my_agent_framework/requirements.txt

# 3. 配置环境变量（可选）
cp .env.example .env
# 编辑 .env，至少设置 OPENAI_API_KEY
```

### 启动

```bash
# Web 界面（推荐）
python -m my_agent_framework serve

# 访问 http://localhost:8000
# API 文档 http://localhost:8000/docs
```

```bash
# CLI 模式
python -m my_agent_framework

# 单次对话
python -m my_agent_framework "你好"
```

```bash
# 环境检查
python -m my_agent_framework preflight
```

## 配置

通过 `.env` 文件或环境变量配置：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | API 密钥 | — |
| `MODEL_NAME` | 模型名称 | `deepseek-chat` |
| `PROVIDER_TYPE` | 提供商类型 (`openai`/`ollama`/`generic`) | `generic` |
| `BASE_URL` | API 基础 URL | — |
| `MAX_TOKENS` | 最大响应 token | `4096` |
| `TEMPERATURE` | 生成温度 | `0.7` |
| `USE_TOOLS_API` | 使用 API tools 参数传递 | `true` |
| `MEMORY_MAX_TOKENS` | 对话历史 token 上限（0=自动推算） | `0` |
| `COMPRESS_THRESHOLD` | 触发智能压缩的 token 阈值（0=自动） | `0` |
| `AUTO_DETECT_MODEL` | 自动检测模型上下文窗口 | `false` |
| `HOST` | Web 服务监听地址 | `127.0.0.1` |
| `PORT` | Web 服务端口 | `8000` |
| `ALLOWED_ORIGINS` | CORS 允许的域名（逗号分隔） | `*` |
| `API_AUTH_TOKEN` | API 认证令牌（留空则不认证） | — |
| `MAX_SESSIONS` | 最大并行会话数 | `100` |
| `SESSION_TTL_MINUTES` | 会话过期时间（分钟） | `60` |
| `AGENT_TOOL_MODE` | 工具权限模式 (`readonly`/`safe`/`full`) | `readonly` |
| `RATE_LIMIT_REQUESTS` | 限流窗口内最大请求数 | `60` |
| `RATE_LIMIT_WINDOW` | 限流窗口（秒） | `60` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `GRACEFUL_SHUTDOWN_TIMEOUT` | 优雅关闭超时（秒） | `30` |
| `MAX_REQUEST_BODY_MB` | 最大请求体大小（MB） | `50` |
| `DATA_DIR` | 数据存储根目录 | `./data` |
| `UPLOADS_DIR` | 文件上传存储目录 | `./data/uploads` |
| `SANDBOX_ROOT` | 文件操作沙箱根目录 | `./data/sandbox` |
| `AUDIT_LOG_DIR` | 审计日志存储目录 | `./logs` |
| `AUDIT_LOG_MAX_MB` | 审计日志单文件大小上限（MB） | `50` |
| `CHROMA_PERSIST_DIR` | ChromaDB 持久化目录 | `./data/chroma` |
| `LLAMA_MODEL_PATH` | 本地 GGUF 模型路径（OCR/嵌入） | — |
| `LLAMA_N_CTX` | 本地模型上下文窗口 | `4096` |
| `OCR_ENABLED` | 启用 OCR 功能 | `false` |
| `OLLAMA_HOST` | Ollama 服务地址 | `http://localhost:11434` |
| `CLUSTER_BACKEND` | 集群后端 (`mock`/`ssh`) | `mock` |
| `MAX_UPLOAD_SIZE` | 单文件上传上限（字节） | `52428800` |

## 集群管理快速开始

### 依赖安装

```bash
pip install paramiko   # SSH 集群管理需要
```

### 配置节点

编辑 `data/cluster_nodes.yaml` 或通过 AI 工具添加：

```bash
# 通过 AI 添加节点（在聊天界面或 CLI 中说）：
"帮我加 station-01，IP 192.168.1.101，标签 产线A"
```

### 使用方式

```bash
# SSH 直连模式启动
python -m my_agent_framework serve
```

启动后 AI 能帮你做的事：

| 你说 | AI 做什么 |
|------|-----------|
| "所有工站的磁盘情况报一下" | 并发 SSH 执行 df，汇总返回 |
| "把 deploy.sh 分发给 station-01~10" | SFTP 上传 + 分批执行 |
| "现在工站什么状态" | 检查每个工站的测试进程、最近FAIL、异常 |
| "station-03 的 log 有什么异常" | SSH grep 日志、检测异常模式 |
| "拉取 station-07 的 record 文件" | SFTP 下载到本地分析 |

## 部署

### Docker（推荐）

```bash
# 构建并启动
docker compose up -d

# 查看日志
docker compose logs -f
```

### 手动部署（生产环境）

```bash
# 安装生产依赖
pip install -r my_agent_framework/requirements.txt

# 配置环境变量（生产环境必须设置）
export API_AUTH_TOKEN="your-secure-token"
export ALLOWED_ORIGINS="https://your-domain.com"
export RATE_LIMIT_REQUESTS=120

# 启动（建议使用 systemd / supervisor 管理进程）
python -m my_agent_framework serve --host 0.0.0.0 --port 8000
```

### 反向代理示例（nginx）

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}
```

### 水平扩展

- 应用层无状态（会话持久化到磁盘），可部署多实例
- 使用 Redis + Celery 替换内置 Worker 池以支持分布式任务（进阶）

## 项目结构

```
my_agent_framework/
├── agent/           # Agent 核心（LLM 调用、对话管理、记忆）
│   ├── core.py      # Agent 主循环（流式/Function Calling）
│   ├── config.py    # 配置管理
│   └── providers/   # LLM 提供商适配层
├── _server/         # Web 服务器（FastAPI + SSE/WS）
│   ├── routes/      # API 路由（chat/cluster/approval/audit/files...）
│   │   ├── files.py       # 文件下载 API（路径安全白名单校验）
│   │   └── ...
│   ├── sse.py       # SSE 流式响应（超时 + 心跳 + 会话锁）
│   ├── shared.py    # 公共依赖（Agent 工厂、工具注册）
│   └── ...
├── cluster/         # 集群管理
│   ├── ssh_backend.py   # SSH 连接池（paramiko + SFTP 直连）
│   ├── node_manager.py  # 节点配置管理（YAML）
│   ├── status_service.py # 工站状态检查 + 异常检测
│   ├── alert_manager.py # 告警分级/聚合/通知路由
│   └── tools/           # 集群工具
├── coordinator/     # 多 Agent 协调 & 任务编排
├── cli/             # CLI & TUI 界面
├── tools/           # 40+ 内置工具（文件/Shell/代码/Git/OCR/Excel...）
├── rag/             # RAG 知识库（向量/BM25/混合检索）
├── frontend/        # Web 前端（SPA — 单页应用）
│   ├── ts/          # TypeScript 源码（esbuild 编译）
│   │   ├── pages/   # 7 个页面模块（hash 路由）
│   │   ├── router.ts  # SPA 路由管理器
│   │   └── app.ts     # 应用入口
│   ├── js/          # 编译输出
│   └── index.html   # SPA 唯一入口
├── tests/           # 900+ 测试用例
│   ├── test_files_download.py    # 文件下载测试（20 测）
│   ├── test_critical_paths.py    # 核心路径 + 孤立 tool 清理
│   └── ...
├── Dockerfile       # 生产容器镜像
├── server.py        # 服务入口
└── data/            # 运行时数据
    └── cluster_nodes.yaml  # 集群节点配置
```

## 开发

```bash
# 安装开发依赖
pip install -r my_agent_framework/requirements-dev.txt

# 运行测试
cd my_agent_framework && python -m pytest -v

# 带覆盖率
cd my_agent_framework && python -m pytest --cov=. --cov-report=term

# 代码检查
ruff check my_agent_framework/
black --check my_agent_framework/
```

## 更新日志

### 2026-07-03 — 全栈修复与优化

#### 崩溃修复
- **工具 Schema 格式错误** — `Agent.register_tool()` 不再传递裸 JSON Schema，改用 `_build_json_schema()` 包装为正确的 `{"type": "function", "function": {...}}` 格式，DeepSeek/OpenAI API 工具调用恢复正常
- **MCP Manager** — 添加缺失的 `import time as _time`，修复 `_time.time()` 抛 `NameError`
- **PlanExecutor** — `_execute_tool` → `ToolRegistry.execute()`，修复 `AttributeError`
- **DAG 执行器** — 统一转为 JSON 字符串，修复 `json.loads(dict)` 抛 `TypeError`
- **CLI events.py** — 添加缺失的 `Path` 和 `os` 导入

#### 功能修复
- **HTTP 代理超时** — 注释掉不可达的办公代理，直连 DeepSeek API
- **审批配置 ID** — HTML 中 `approvalToggles` → `approvalSettings`，审批 UI 恢复正常
- **WebSocket 认证** — `/ws/` 路径加入免认证前缀（浏览器 WS 无法发送自定义 Header）
- **Session 恢复** — `node_id=0` 因 `if 0` 被跳过，改为 `is not None` 检查
- **消息编辑** — 先隐藏旧消息而非立即删除，网络失败时可恢复

#### RAG / 知识库
- **上下文窗口** — `deepseek-v4-pro`/`deepseek-v4-flash` 从 8192 修正为 **65536**
- **`ingest_to_knowledge_base` 错误信息** — 区分文件不存在/路径是目录/文件过大/空文件/权限不足
- **`ingest_text_to_knowledge_base` 校验** — 空 source/text 时返回明确错误

#### 新增工具
- **`read_excel`** — 读取 .xlsx/.xls 返回 Markdown 表格，支持全量/摘要双模式
- **摘要模式** — `summary="true"` 时输出行列数、数值列 sum/avg 统计

#### MCP 改进
- **后台事件循环** — 持久 `_get_mcp_loop()` 替代每次 `asyncio.run()`，MCP 工具调用更稳定

#### 稳定性
- **工具执行超时** — `_execute_with_progress` 新增 `tool_timeout`（默认 300s）硬截止
- **防死循环** — Agent 主循环连续 3 轮工具调用无文本输出时强制终止
- **双重重试** — 移除 `_stream_llm_with_retry` 外层 retry loop，仅用 `@_retry` 装饰器
- **日志时间戳** — `%H:%M:%S` → `%m-%d %H:%M:%S`，支持跨天日志关联
- **`BadRequestError` 区分** — 工具 Schema 错误不再被误判为 `stream_options` 不支持

## 测试

```bash
# 运行全部测试
python -m pytest my_agent_framework/tests/ -v

# 仅运行文件下载测试
python -m pytest my_agent_framework/tests/test_files_download.py -v

# 仅运行核心路径测试
python -m pytest my_agent_framework/tests/test_critical_paths.py -v
```

测试覆盖：核心 Agent 内存管理、文件下载 API 安全校验、路径穿越防御、会话锁机制、知识库初始化。

## 技术栈

- **后端**: Python 3.10+ / FastAPI / Uvicorn
- **AI**: OpenAI SDK / DeepSeek API / llama-cpp-python
- **SSH 集群**: paramiko (SSH 直连) / SFTP (文件传输)
- **向量库**: ChromaDB / BM25 混合检索 / ONNX 或 GGUF Embedding
- **前端**: TypeScript（SPA 单页应用） / esbuild / marked.js / highlight.js / WebSocket / SSE
- **监控**: Prometheus 文本格式 / psutil
- **工具协议**: MCP (Model Context Protocol) 后台持久事件循环

## 许可证

MIT