hssh-agentlisted
Install: claude install-skill hyyy-y/hssh
# hssh Agent 使用指南
hssh 是本地运行的 SSH 客户端，内置 Agent 能力。本 skill 描述 AI 如何通过接口控制 SSH 连接和终端窗口。
**前提**：Agent 只监听 `127.0.0.1`，需要在 hssh GUI 中通过 `Tools → Start Agent` 启动（勾选 "Auto-start Agent with GUI" 后自动启动），或命令行 `hssh --agent-http [--port 8222]`。
**两种会话模型，先确认用哪个**：
| 模型 | 场景 | 说明 |
|------|------|------|
| **GUI 标签页控制** | 用户在 hssh GUI 里已经开好 SSH 窗口，AI 接管它 | `/api/v1/tabs/*` 接口，直接读写终端缓冲区 |
| **Agent 托管会话** | AI 自己创建新的 SSH 连接执行命令 | `/api/v1/sessions/*` 接口（或 MCP 工具） |
---
## 一、快速开始（最常用流程）
> AI 接管用户在 GUI 里已经打开的 SSH 窗口：
```powershell
# 1. 确认 agent 在运行
Invoke-RestMethod http://127.0.0.1:8222/api/v1/status
# 2. 列出打开的终端标签（找到 SSH 标签的 index）
Invoke-RestMethod http://127.0.0.1:8222/api/v1/tabs
# 3. 发送命令到该标签（自动追加回车）
Invoke-RestMethod -Method POST http://127.0.0.1:8222/api/v1/tabs/1/send `
-ContentType "application/json" -Body '{"command":"uname -a"}'
# 4. 等待执行完成，读取终端输出
Start-Sleep -Seconds 2
Invoke-RestMethod "http://127.0.0.1:8222/api/v1/tabs/1/text?lines=50"
```
bash/curl 同理（`curl -X POST ... -d '{"command":"..."}'`）。
**关键原则**：tabs 接口是"读终端缓冲区"，不是同步 RPC——发送命令后必须等输出回来（sleep 后读 text，必要时轮询），再解析结果。
## 二、密码安全模型（必读）
**任何接口都不接受明文密码**。模型/工具只能使用密文或会话名：
| 方式 | 说明 | 适用 |
|------|------|------|
| **会话名引用** | `{"sessionName":"root"}`，hssh 用库内凭据，凭据不出进程 | **首选**，模型连密文都不用见 |
| **密文** | `passwordCipher` = `base64(RSA-OAEP-SHA256(明文))`，公钥见 `GET /api/v1/keys` | 无库存凭据的新主机 |
| 明文 `password` | **一律 400 拒绝** | — |
- 公钥获取：`GET /api/v1/keys` → `{publicKeyPem, fingerprint}`；私钥只存在 hssh 本机（GCM 加密落盘）
- 本地产密