hsagent-platform 0.1.2

--- ## 为什么选择 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 ---