Metadata-Version: 2.4
Name: hsagent-platform
Version: 0.1.2
Summary: 面向 AI 智能体的服务器集群 MCP 工具包 (Bridge + Relay)
Author: HSAgent Contributors
License: Apache-2.0
Project-URL: Homepage, https://gitcode.com/ZhaXionghui/hsagent-platform
Project-URL: Repository, https://gitcode.com/ZhaXionghui/hsagent-platform
Keywords: mcp,agent,ssh,hpc,slurm,cluster,controlmaster
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0; sys_platform != "win32"
Requires-Dist: fastmcp[cli,fastapi,httpx]>=2.0; sys_platform == "win32"
Requires-Dist: paramiko>=3.0
Requires-Dist: uvicorn>=0.30
Dynamic: license-file

<div align="center">

# 🚀 HSAgent Platform

**面向 AI 智能体的服务器集群 MCP 工具包**

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-Apache-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
[![MCP](https://img.shields.io/badge/Protocol-MCP-ff6b35.svg)](https://modelcontextprotocol.io)
[![pip](https://img.shields.io/badge/pip-installable-9cf.svg)](https://pypi.org)

**一次 `pip install`，任意 智能体，任意服务器集群。**

[快速开始](#-快速开始) · [功能特性](#-功能特性) · [文档](#-文档) · [路线图](#-路线图) · [架构](#-架构)

</div>

---

## 为什么选择 HSAgent？

一些服务器无法直接安装 AI Agent, 若是要操作服务器集群更是麻烦。
对**已配置 SSH 公钥**的服务器，HSAgent **优先使用密钥认证**、免去密码/OTP 输入；对只支持密码/OTP 的服务器，则走原有的密码流程。
用 HSAgent 可以解决这个问题，通过 AI 助手直接调用工具，完成指定任务。他是智能体时代的智能体友好的 MCP 工具包。**让 Agent 可以在任意服务器上执行命令**，**无需在服务器上安装插件或依赖**。


- 🔌 **一条命令连接 HPC** — SSH ControlMaster 自动复用，不再重复输入密码
- 🛠️ **完整 MCP 工具套件** — 连接、执行、上传、下载、提交作业、查看状态，全部通过 AI 助手完成
- 🖥️ **多 IDE 支持** — Claude Code、Cursor、Trae、Windsurf，相同配置，相同工具
- 📊 **内置遥测与追踪** — 每次工具调用都被记录，失败自动分析，生成改进建议

> 💡 **设计理念**：HSAgent 是一个 *MCP 服务*，而非 SDK。你不需要写 Python 代码来使用它——你的 AI 助手直接调用工具即可。

---

## ✨ 功能特性

| 功能 | 说明 | 状态 |
|------|------|------|
| 🔐 服务器/集群登录 | SSH ControlMaster 会话管理（注册/登录/状态/登出），支持任意主机别名 | ✅ |
| 💻 远程执行 | 通过 SSH 在任意服务器上执行命令 | ✅ |
| 📤 文件上传/下载 | 基于 SCP 的服务器文件双向传输（目录自动打包） | ✅ |
| 📋 作业提交与追踪 | Slurm sbatch 作业提交，自动生成脚本，可查状态/取消 | ✅ |
| 📊 集群监控 | 节点状态、队列、作业与性能报告（sinfo/squeue/节点健康检查） | ✅ |
| 🔗 Bridge-Relay 架构 | 本地 Bridge（stdio）+ 远端 Relay（HTTP）双层架构 | ✅ |
| 📈 遥测 | 工具级别成功/失败追踪 | ✅ |
| 🔍 会话追踪 | 完整任务轨迹记录，自动脱敏 | ✅ |
| 🧠 失败分析 | 自动检测失败模式并生成修复建议 | ✅ |
| 🛡️ 权限层 | 读/写/破坏性操作分类与校验 | ✅ |
| 📦 技能包 | IDE 无关的 SKILL 文档管理 | ✅ |
| 🖥️ 多 IDE 支持 | Claude Code、Cursor、Trae、Windsurf 支持 | ✅ |

---

## 🏗️ 架构

```
┌──────────────────────────────────────────────────────────────┐
│                     你的 AI 助手                               │
│   Claude Code  ·  Cursor  ·  Trae  ·  Windsurf               │
└────────────────────────┬─────────────────────────────────────┘
                         │ stdio（MCP 协议）
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                   HSAgent-Bridge（本地）                       │
│                                                              │
│   • 向 IDE 暴露 stdio MCP 接口                                │
│   • 管理本地 SSH 会话与密钥                                    │
│   • 记录遥测与追踪数据                                        │
│   • 在可用时路由至 Relay                                      │
└────────────────────────┬─────────────────────────────────────┘
                         │ HTTP（JSON-RPC）
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                   HSAgent-Relay（服务端）                      │
│                                                              │
│   • 技能包管理                                                 │
│   • 遥测聚合与失败分析                                         │
└──────────────────────────────────────────────────────────────┘
```

> **核心设计**：Bridge 将 SSH 会话和密钥保留在**本地**，Relay 在**服务端**处理技能包管理与遥测分析。两者协同但完全独立——没有 Relay，Bridge 也能独立运行。

---

## ⚡ 快速开始
> **注意**：
> 1. HSAgent 并不支持在 Windows 上运行。请在 WSL2 上安装。
> 2. Python 3.11 或更高版本。

### 1. 安装
项目链接：https://pypi.org/project/hsagent-platform/
```bash
pip install hsagent-platform
```

### 2. 连接你的服务器

```bash
hsagent-bridge hpc login --cluster my-cluster --host login.example.com --user zxh --port 22
```

### 3. 配置你的 IDE

查看 `hsagent-bridge` 路径：

```bash
whereis hsagent-bridge
# /home/zxh/.local/bin/hsagent-bridge
```

添加到项目的 `.mcp.json`：

```json
{
  "mcpServers": {
    "hsagent": {
      "command": "wsl",
      "args": [
        "/home/zxh/.local/bin/hsagent-bridge",
        "serve"
      ],
      "env": {
        "HSAGENT_HPC_BACKEND": "wsl",
        "HSAGENT_RELAY_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

```

### 4. 让 AI 帮你做剩下的事

直接告诉你的 AI 助手：

> *"连接我的服务器 'my-server'，查看队列状态，然后完成我的作业。"*

你的 AI 将使用 HSAgent 的 MCP 工具完成所有操作——无需手动 SSH，无需复制粘贴命令。

📖 **[完整入门指南 →](docs/getting-started.md)**

---

## 📖 文档

| 文档 | 说明 |
|------|------|
| [🚀 快速入门](docs/getting-started.md) | 从安装到提交第一个作业的 6 步指引 |
| [📦 安装](docs/installation.md) | pip / uvx / 离线 wheel 安装方式 |
| [🔐 服务器 连接](docs/connection.md) | SSH ControlMaster、多后端、注册/登录/状态/登出 |
| [💻 服务器 操作](docs/server-operations.md) | 执行命令、上传/下载文件、提交作业、监控与作业追踪 |
| [🖥️ IDE 集成](docs/ide-integration.md) | Claude Code、Cursor、Trae、Windsurf 配置 |

---

## 🛠️ MCP 工具参考

### Bridge 工具（本地——所有 IDE 可用）

| 工具 | 说明 |
|------|------|
| `host_register` | 注册连接目标（别名 → host/user/port），持久化 |
| `host_list` | 列出所有已注册连接目标 |
| `host_login` | 建立/验证到服务器或集群的 SSH 会话 |
| `host_status` | 检查 SSH 会话是否活跃 |
| `host_logout` | 关闭 SSH 会话并清理 |
| `host_exec` | 通过 SSH 在服务器上执行 Shell 命令 |
| `host_upload` | 通过 SCP 上传本地文件/目录到服务器 |
| `host_download` | 通过 SCP 从服务器下载文件/目录到本地 |
| `submit_host_job` | 提交 Slurm 批处理作业，自动生成 sbatch 脚本，返回 job_id |
| `host_job_status` | 查询已提交 Slurm 作业状态（squeue） |
| `host_job_cancel` | 取消已提交的 Slurm 作业（scancel） |
| `host_monitor` | 集群监控：节点/队列/作业概览（sinfo/squeue/健康检查） |
| `relay_status` | 检查 Bridge-Relay 连接状态 |
| `relay_list_bundle_skills` | 列出 Relay 技能包中的技能 |
| `trace_begin_session` | 启动追踪会话以跟踪任务执行 |
| `trace_finish_session` | 结束追踪会话并上报至 Relay |
| `trace_flush_cached` | 刷新离线缓存的追踪数据至 Relay |

> 旧的 `hpc_*` / `execute_hpc_command` / `upload_hpc_file` / `submit_hpc_job` 等名称作为
> **向后兼容别名**保留（标记为 `[DEPRECATED]`），新代码请使用 `host_*` 系列。

### Relay 工具（服务端——需要 Relay 部署）

| 工具 | 说明 |
|------|------|
| `get_bundle_info` | 获取技能包清单和技能列表 |
| `list_bundle_skills` | 列出技能包中的所有技能 |
| `get_bundle_skill` | 读取指定 SKILL 文档 |
| `export_bundle_to_roo` | 将技能包导出为 Roo-Code 格式 |
| `report_tool_telemetry` | 上报工具调用遥测数据 |
| `get_failure_patterns` | 查询工具级别失败模式 |
| `report_session_trace` | 上报完整会话追踪 |
| `get_session_traces` | 按条件查询会话追踪 |
| `get_trace_stats` | 获取追踪存储统计 |
| `get_failure_insights` | 获取失败分析洞察 |
| `analyze_recent_failures` | 触发实时失败分析 |

---

## 🗺️ 路线图

### v0.1 — 基础能力 ✅（当前版本）

- [x] Bridge MCP 服务器，完整服务器/集群工具套件（host_* 命名）
- [x] SSH ControlMaster 会话管理（native/gitbash/wsl 后端）+ 多目标注册（host_register）
- [x] Relay MCP 服务器，技能包管理
- [x] Bridge-Relay 双层架构（stdio + HTTP）
- [x] 工具级别遥测采集
- [x] 会话级别追踪，自动敏感数据脱敏
- [x] FailureAnalyzer 结构化洞察
- [x] 多 IDE 支持（Claude Code、Cursor、Trae、Windsurf）
- [x] pip 可安装包
- [x] Windows 平台测试（Trae IDE 验证通过）

### v0.2 — 加固 🔧

- [x] 权限层（读/写/破坏性操作分类）
- [x] 作业生命周期追踪（host_job_status / host_job_cancel / host_list_jobs + 本地作业库）
- [x] 集群监控（host_monitor：summary/nodes/jobs）
- [x] 多文件/目录上传，自动 tar 打包
- [ ] OTP 续期工作流指引
- [ ] macOS 和 Linux 平台测试

### v0.3 — 智能化 🧠

- [ ] 留出集部署策略
- [ ] 跨会话记忆（情景 + 语义）
- [ ] SKILL 版本差异与谱系查看器

### v0.4 — 生态 🌐

- [ ] Prometheus + Grafana 服务器 监控面板
- [ ] 自愈流水线（19 种故障 → 11 种自动修复动作）
- [ ] VS Code 扩展，编辑器内 服务器 管理
- [ ] 社区技能插件注册中心

---

## 🔑 核心概念

### Bridge-Relay 分离

HSAgent 将**执行**（Bridge）与**分析**（Relay）分离：

- **Bridge** 在本地运行，连接你的 HPC 集群，执行命令，保护你的 SSH 会话和密钥安全
- **Relay** 在服务端运行，管理技能包，收集遥测数据，聚合失败分析

你可以单独使用 Bridge——没有 Relay 也能完美工作。当你需要技能包管理与跨用户分析时，再添加 Relay。

### ControlMaster SSH 会话

HSAgent 使用 SSH ControlMaster 维持持久 SSH 会话，这意味着：

- 一次登录（输入密码 + OTP）→ 后续所有命令复用该会话
- 密码不存储在任何地方——由操作系统级 SSH socket 处理认证
- 会话在 `ControlPersist` 秒数后自动过期（默认：900 秒 / 15 分钟）

### 技能包

技能包是一组 IDE 无关的 SKILL 文档集合，教会你的 AI 助手正确使用 HSAgent 工具：

```
agent-bundle/
├── manifest.json
├── prompts/system.md
├── skills/
│   ├── connect-to-hpc/SKILL.md
│   └── submit-hpc-job/SKILL.md
└── policies/routing.yaml
```

技能使用带 YAML frontmatter 的 Markdown 编写——无需代码，无需编译，只是 AI 读取并遵循的自然语言指令。

---

## 🤝 兼容性

| IDE | 连接方式 | 状态 |
|-----|---------|------|
| Claude Code | `.mcp.json` → stdio | ✅ 已支持（自动识别 client_id） |
| Cursor | `.cursor/mcp.json` → stdio | ✅ 已支持（自动识别 client_id） |
| Trae | Trae MCP 设置 → stdio | ✅ Windows 已验证 |
| Windsurf | MCP 配置 → stdio | ✅ 已支持（自动识别 client_id） |
| VS Code | `.vscode/mcp.json` → stdio | ✅ 已支持（自动识别 client_id） |

---

## 📄 许可证

MIT License

---

<div align="center">

**用 ❤️ 为 HPC + AI 社区构建**

[报告问题](../../issues) · [功能建议](../../issues) · [阅读文档](docs/getting-started.md)

</div>
