精选案例 · 工程接入与部署 / Agent 自动化

HSAgent 服务器集群 MCP 工具包实践

标题由系统整理

作者： zxh

原题：🚀 HSAgent Platform

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

案例速读

README 标题「🚀 HSAgent Platform」下已经出现运行/配置路径、脚本或接口线索、结果证据，正文重点集中在「为什么选择 HSAgent？」「✨ 功能特性」，比纯概念介绍更适合进入精选阅读流。建议从「🚀 HSAgent Platform」、「为什么选择 HSAgent？」、「✨ 功能特性」、「🏗️ 架构」进入正文，先确认真实任务和模型辅助过程。

重点看可参考其中的运行与配置路径、包含可迁移的命令、脚本或接口线索、已有结果或观测证据可用于判断复用价值。结合工程接入与部署 / Agent 自动化 / Agent / 实践案例和「任务驱动用户、AI 实践者」，它更适合作为任务检索后的精读材料。
正文目录和原始材料仍然是判断依据；导读只帮助你更快定位阅读重点。

首读入口: 为什么选择 HSAgent？
读者: 任务驱动用户、AI 实践者
复用: 可参考其中的运行与配置路径
结构: 12 个目录入口

原文内容

🚀 HSAgent Platform

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

图片暂时无法显示：Python 图片暂时无法显示：License 图片暂时无法显示：Platform 图片暂时无法显示：MCP 图片暂时无法显示：pip

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

快速开始 · 功能特性 · 文档 · 路线图 · 架构

为什么选择 HSAgent？

一些服务器无法直接安装 AI Agent, 若是要操作服务器集群更是麻烦。部分服务器可能没有提供密钥对，导致无法通过 SSH 登录。无法使用 AI Agent 在这些服务器上执行命令。完成指定任务需要手动操作。用 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 作业提交，自动生成脚本	✅
📊 集群监控	节点状态、告警、性能报告	TODO
🔗 Bridge-Relay 架构	本地 Bridge（stdio）+ 远端 Relay（HTTP）双层架构	TODO
📈 遥测	工具级别成功/失败追踪	✅
🔍 会话追踪	完整任务轨迹记录，自动脱敏	TODO
🧠 失败分析	自动检测失败模式并生成修复建议	✅
🧬 自主进化	引擎自动完成基准测试 → 变异 → 门控 → 晋升/回滚	TODO
📦 技能包	IDE 无关的 SKILL 文档管理	TODO
🖥️ 多 IDE 支持	Claude Code、Cursor、Trae、Windsurf 支持	TODO

🏗️ 架构

┌──────────────────────────────────────────────────────────────┐
│                     你的 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 可用）

工具	说明
`hpc_login`	建立/验证到 HPC 集群的 SSH 会话
`hpc_status`	检查 SSH 会话是否活跃
`hpc_logout`	关闭 SSH 会话并清理
`execute_hpc_command`	通过 SSH 在 HPC 上执行 Shell 命令
`upload_hpc_file`	通过 SCP 上传本地文件到 HPC
`download_hpc_file`	通过 SCP 从 HPC 下载文件到本地
`submit_hpc_job`	提交 Slurm 批处理作业，自动生成 sbatch 脚本
`relay_status`	检查 Bridge-Relay 连接状态
`relay_list_bundle_skills`	列出 Relay 技能包中的技能
`trace_begin_session`	启动追踪会话以跟踪任务执行
`trace_finish_session`	结束追踪会话并上报至 Relay
`trace_flush_cached`	刷新离线缓存的追踪数据至 Relay

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`	触发实时失败分析
`benchmark_bundle`	对当前技能包运行基准测试
`hsagent_self_improve_bundle`	运行自主进化循环

🗺️ 路线图

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

[x] Bridge MCP 服务器，完整 HPC 工具套件
[x] SSH ControlMaster 会话管理（native/gitbash/wsl 后端）
[ ] Relay MCP 服务器，技能包管理
[x] Bridge-Relay 双层架构（stdio + HTTP）
[x] 工具级别遥测采集
[ ] 会话级别追踪，自动敏感数据脱敏
[ ] FailureAnalyzer 结构化洞察
[ ] A-Evolve 自主进化（基准测试 → 变异 → 门控 → 晋升/回滚）
[ ] 多 IDE 支持（Claude Code、Cursor、Trae、Windsurf）
[x] pip 可安装包
[x] Windows 平台测试（Trae IDE 验证通过）

v0.2 — 加固 🔧

[ ] 权限层（读/写/破坏性操作分类）
[ ] 工具注册表，懒加载
[ ] 增强作业监控，TaskStore 追踪作业生命周期
[ ] 多文件/目录上传，自动 tar 打包
[ ] OTP 续期工作流指引
[ ] macOS 和 Linux 平台测试

v0.3 — 智能化 🧠

[ ] LLM 驱动的技能变异（大模型提供商支持）
[ ] 留出集部署策略
[ ] 实时失败驱动进化触发
[ ] 跨会话记忆（情景 + 语义）
[ ] SKILL 版本差异与谱系查看器

v0.4 — 生态 🌐

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

v0.5 — 自主进化 🔮

[ ] 完整 A-Evolve 自主进化闭环
[ ] 多技能包并发进化
[ ] SWE-bench / terminal 基准测试集成

🔑 核心概念

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	未测试
Cursor	`.cursor/mcp.json` → stdio	未测试
Trae	Trae MCP 设置 → stdio	✅ Windows 已验证
Windsurf	MCP 配置 → stdio	未测试

📄 许可证

MIT License

用 ❤️ 为 HPC + AI 社区构建

报告问题 · 功能建议 · 阅读文档

返回顶部