用户可通过 AI 助手直接操作服务器集群，无需手动 SSH 或安装依赖。提供 SSH 会话管理、远程命令执行、文件传输、作业提交等功能，支持多 IDE，具备遥测追踪与失败分析能力。【此简介由AI生成】
为什么选择 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 也能独立运行。
⚡ 快速开始
注意：
- HSAgent 并不支持在 Windows 上运行。请在 WSL2 上安装。
- Python 3.11 或更高版本。
1. 安装
项目链接：https://pypi.org/project/hsagent-platform/
pip install hsagent-platform
2. 连接你的服务器
hsagent-bridge hpc login --cluster my-cluster --host login.example.com --user zxh --port 22
3. 配置你的 IDE
查看 hsagent-bridge 路径：
whereis hsagent-bridge
# /home/zxh/.local/bin/hsagent-bridge
添加到项目的 .mcp.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，无需复制粘贴命令。
📖 完整入门指南 →
📖 文档
| 文档 | 说明 |
|---|---|
| 🚀 快速入门 | 从安装到提交第一个作业的 6 步指引 |
| 📦 安装 | pip / uvx / 离线 wheel 安装方式 |
| 🔐 服务器 连接 | SSH ControlMaster、多后端、注册/登录/状态/登出 |
| 💻 服务器 操作 | 执行命令、上传/下载文件、提交作业、监控与作业追踪 |
| 🖥️ IDE 集成 | 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 — 基础能力 ✅（当前版本）
v0.2 — 加固 🔧
v0.3 — 智能化 🧠
v0.4 — 生态 🌐
🔑 核心概念
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） |
📄 许可证
Apache License 2.0