host-execution-mcp 1.0.0 → 2.0.0

package/docs/USER_GUIDE.zh-CN.md

@@ -1,93 +1,62 @@
 # host-execution-mcp 使用教程
 
-**本机 Cursor → SSH（ACCESS / 帕拉迪网关）→ 落点 HostExecutionContext → kubectl / docker / shell**（笔记本不直连 Pod）。
+配置、`ACCESS_KIND`、怎么跟 Agent 说话，以 [GUIDE.md](./GUIDE.md) 为准（MCP Resource `host-execution://guides/user`）。本文只补 Codex 接法、旧包迁移和场景示例。
 
-工具名：`access_check` / `shell_exec` / `context_*` / `k8s_*` / `docker_*` / `remote_*`。在 `ACCESS_KIND=ssh` 时落点是 ACCESS；在 `paradi-gateway` 时落点是 **TARGET**（不是网关机）。详见 [AGENT_GUIDE.md](AGENT_GUIDE.md) / [CONFIGURATION.md](CONFIGURATION.md)。
+建议配套 [k8s-multi-node-deploy](../../../skill/env/k8s-multi-node-deploy/) skill。
 
----
+帕拉迪网关长什么样（先连网关，再选手选资产 / 账号）：
 
-## 1. 安装 Node.js
+![帕拉迪网关：先连网关，再选资产与账号，才能进入目标机](./paradi-gateway-interactive.png)
 
-需要 **Node.js >= 18**。官网 [nodejs.org](https://nodejs.org) 下载 LTS，安装后验证：
+## Codex
 
-```bash
-node -v
-```
-
----
-
-## 2. MCP 配置（Cursor）
-
-配置文件：`.cursor/mcp.json`，或 Cursor → Settings → MCP → Edit Config。
-
-```json
-{
-  "mcpServers": {
-    "host-execution": {
-      "command": "npx",
-      "args": ["-y", "host-execution-mcp@latest"],
-      "env": {
-        "ACCESS_HOST": "10.121.120.7",
-        "ACCESS_USER": "your-user"
-      }
-    }
-  }
-}
-```
-
-`ACCESS_HOST` + `ACCESS_USER` 填你**本机能 SSH 直连的入口机**（跳板或目标机）即可。可选 `TARGET_HOST` / `TARGET_USER` / `TARGET_PASSWORD` 作为默认第二跳（见 CONFIGURATION.md）。
-
-保存后重启 MCP 服务。验证连通：
-
-> 先用 host-execution 跑 `access_check`。若要做 Kubernetes 相关操作，通过后再跑 `kubectl cluster-info --request-timeout=5s`（纯 ACCESS/主机 SSH 任务不必跑 cluster-info）。
+把 GUIDE §2 的 `env` 配进 Codex。不要把密码写进仓库或对话。
 
-若提示 `ACCESS_UNAVAILABLE` / 无法连接：先检查本机 VPN 与 `ACCESS_HOST`，不要反复重试其他工具。
+也可把 GUIDE 里的 JSON 交给 Codex，让它按 GUIDE 配。`~/.codex/config.toml` 示意：
 
----
+```toml
+[mcp_servers.host-execution]
+command = "npx"
+args = ["-y", "host-execution-mcp@latest"]
 
-## 3. 怎么用
-
-对 Agent **用自然语言**说清：**命名空间、负载/Pod 名、文件路径**；需要时加「只读，不要改」。
-
-| 你想做的事 | 告诉 Agent |
-|-----------|-----------|
-| 找 Pod | 命名空间 + Deployment/负载名 |
-| 看日志 | Pod 名 + 日志**文件路径**（训练日志多在挂载盘，不是 stdout） |
-| 拷到本地 | 远程路径 + 本地目录（Agent 读取后写入本机） |
-| 排查故障 | 日志 / dmesg / core 路径 + 「只读分析」 |
-
-输出太大被截断时，让 Agent 用 `grep`、`tail` 缩小范围。
-
----
-
-## 4. 示例话术
+[mcp_servers.host-execution.env]
+ACCESS_KIND = "ssh"
+ACCESS_HOST = "<入口机 IP>"
+ACCESS_USER = "<入口机用户>"
+ACCESS_PASSWORD = "<入口机密码>"
+ACCESS_PORT = "22"
+```
 
-**查负载**
+> 使用时整个 vscode 窗口只能当作一个类似 Codex 桌面版 app，建议配合 terminal 使用。
 
-> `his-test` 命名空间，列出 `jd-joyvideo-test` 的 Pod 状态和 IP。
+## 与旧包对照（迁移）
 
-**看训练日志**
+| 旧（bastion-k8s-mcp） | 新（host-execution-mcp） |
+| --- | --- |
+| `bastion-k8s-mcp@3.x` | `host-execution-mcp@1.0.0` |
+| `BASTION_HOST` / `USER` / `PASSWORD` / `PORT` | `ACCESS_HOST` / `USER` / `PASSWORD` / `PORT` |
+| `REMOTE_SSH_USER` / `PASSWORD` | `TARGET_USER` / `TARGET_PASSWORD` |
+| `bastion_check` / `bastion_exec` | `access_check` / `shell_exec` |
+| — | `ACCESS_KIND=paradi-gateway` + `TARGET_*`（帕拉迪） |
 
-> Pod `jd-joyvideo-test-xxx`，tail `/mnt/code/.../log.65.10.121.33.74` 最后 200 行，看有没有 Killed 或 MUSA error。只读。
+## 场景示例
 
-**拷 log 到本地**
+1. MCP + SKILL → 让从零重新创建一个负载，然后拉 128 个节点
 
-> 把 Pod `jd-joyvideo-test-xxx` 上的 `/path/to/log` 和 `/path/to/core.mudmp` 拷到本地 `jd-joyvideo-logs/`，不要改远程文件。
+   ![d36c358b1c6ee6cc73b978f300978c27.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/8045491c-9f79-49bb-9ee8-63e90c726336.png)
 
-**分析训练失败**
+2. 帮进行多机 mccl-test 测试（替换新 mccl 测试）
 
-> 只读分析 Pod 上的 mudmp 和训练 log，启动脚本 `/mnt/code/0407/cluster/dist_run_fsdp8.sh`，说明失败原因。
+   （上下文信息已经有了对应 16 机信息）
 
-**批量检查**
+   ![a24515a4bcdf008990bcf01b899b89d9.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/c6dbb6fb-bfe1-4f25-b351-fa670f2523dd.png)
 
-> 对 `his-test` 里所有 Running 的 `jd-joyvideo-test` Pod 跑 `mthreads-gmi -q | grep Bios`，汇总版本。
+3. 批量配置 128 机环境，并帮拉起训练做对比验证
 
----
+   ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/bc0d5e32-fc06-41d2-8387-0cfbe101f46d.png)
 
-## 常见问题
+4. 负载任务
 
-- **MCP 起不来**：检查 `node -v`、堡垒机地址账号、本机能否 `ssh user@10.121.120.7`
-- **k8s_logs 为空**：容器日志流（stdout+stderr）可能为空；日志在文件里时让 Agent 读挂载路径，不要只用 `k8s_logs`
-- **多个节点都 Killed**：先找第一个报 MUSA/SIGABRT 的 rank，其余可能是连锁退出
+   ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/4f8dc2c2-6445-44f8-b1d9-8aaf27d37ccc.png)
 
-更多配置见 [CONFIGURATION.md](./CONFIGURATION.md)。
+常见问题见 [GUIDE.md](./GUIDE.md)。更多环境变量见 [CONFIGURATION.md](./CONFIGURATION.md)。

package/docs/host-execution.yaml

@@ -0,0 +1,92 @@
+# host-execution 名册（对照 docs/GUIDE.md §2）
+# 路径写死：
+#   Linux/mac  ~/.agents/host-execution.yaml
+#   Windows    %USERPROFILE%\.agents\host-execution.yaml
+#
+# 一条链路 = GUIDE 里一份 mcp.json env。description 必填且唯一，写清场景用途（谁、干什么、哪台），不要只写「本机直连 + IP」。
+# 追加：在 links 下复制下面某一段示例，去掉行首 #，改 description 与账号。
+# 对话里出现新的 user+IP（新跳板/网关/账号，或同一 IP 换用户）→ 追加一条，不要只记在对话里。
+# 同一 ACCESS 且同一 TARGET_USER、只是多了一个目标 IP → 往该条 TARGET_HOSTS 加一项。
+# 同一 IP、不同用户（root vs mccxadmin）是两条链路，不要写进同一条 TARGET_HOSTS。
+# description 不准（场景变了、或「本机/跳板/生产」说错）→ 当场改名，随后按新名精确选用；不要把旧名当不可改主键。
+# 本轮对话一直指向某一条 → 一直用那条，不要因为本文件有多条（含同 IP 另一用户）就换。
+# 选用时 description 必须精确相等。不要 CIDR / 通配。
+# 帕拉迪：不要手写 USER/HOST/OSUSER 或 密码@##@… ，由 MCP 编码。
+
+links: []
+
+# --- GUIDE §2.1 最少：只上入口机 ---
+# - description: 入口机本机作业
+#   ACCESS_KIND: ssh                 # 可省，默认 ssh
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   ACCESS_PORT: 22                  # 可省
+
+# --- GUIDE §2.1 密钥代替密码 ---
+# - description: 入口机密钥登录
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PRIVATE_KEY_PATH: "<密钥路径>"
+
+# --- GUIDE §2.1 限制 kubectl 命名空间 ---
+#   ALLOWED_NAMESPACES: "his-test"
+
+# --- GUIDE §2.1 跳板 + 一台默认第二跳 ---
+# - description: 跳板再上训练机
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.1 跳板 + 多台已知 IP（同一账号）---
+# - description: 跳板再上多台训练机
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.1 只留账号，对话里说 IP ---
+# - description: 跳板账号已配，目标 IP 对话指定
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.2 帕拉迪 ---
+# - description: 经网关上业务机
+#   ACCESS_KIND: paradi-gateway
+#   ACCESS_HOST: "<网关 IP>"
+#   ACCESS_PORT: 22
+#   ACCESS_USER: "<网关用户>"
+#   ACCESS_PASSWORD: "<网关密码>"
+#   ACCESS_PARADI_AUTH: auto         # auto | slash | compound
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机系统用户>"
+
+# --- 同一 IP、不同用户：两条链路 ---
+# - description: 业务机 mccxadmin
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "mccxadmin"
+#   TARGET_PASSWORD: "<该用户密码>"
+# - description: 业务机 root
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "root"
+#   TARGET_PASSWORD: "<该用户密码>"

package/package.json

@@ -1,65 +1,67 @@
-{
-  "name": "host-execution-mcp",
-  "version": "1.0.0",
-  "description": "Access -> HostExecutionContext -> Runtime MCP for remote shell/docker/kubectl (SSH jump or Paradi gateway)",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "host-execution-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "docs"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsc && node dist/index.js",
-    "test": "node --import tsx --test tests/*.test.ts",
-    "lint": "eslint src tests",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "mcp",
-    "host-execution",
-    "kubernetes",
-    "kubectl",
-    "ssh",
-    "paradi"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/your-org/host-execution-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/your-org/host-execution-mcp/issues"
-  },
-  "homepage": "https://github.com/your-org/host-execution-mcp#readme",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "ssh2": "^1.16.0",
-    "ssh2-sftp-client": "^12.1.1",
-    "zod": "^3.24.2"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.23.0",
-    "@types/node": "^22.13.10",
-    "@types/ssh2": "^1.15.4",
-    "@types/ssh2-sftp-client": "^9.0.6",
-    "eslint": "^9.23.0",
-    "prettier": "^3.5.3",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.28.0"
-  }
-}
+{
+  "name": "host-execution-mcp",
+  "version": "2.0.0",
+  "description": "Access -> HostExecutionContext -> Runtime MCP for remote shell/docker/kubectl (SSH jump or Paradi gateway)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "host-execution-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "lint": "eslint src tests",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "host-execution",
+    "kubernetes",
+    "kubectl",
+    "ssh",
+    "paradi"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/host-execution-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/host-execution-mcp/issues"
+  },
+  "homepage": "https://github.com/your-org/host-execution-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "js-yaml": "^5.4.2",
+    "ssh2": "^1.16.0",
+    "ssh2-sftp-client": "^12.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "@types/ssh2": "^1.15.4",
+    "@types/ssh2-sftp-client": "^9.0.6",
+    "eslint": "^9.23.0",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0"
+  }
+}

package/dist/ssh/bastion-client.d.ts

@@ -1,60 +0,0 @@
-import type { AppConfig } from "../config.js";
-import { type SftpCopyOptions, type SftpTransferResult } from "../utils/copy-transfer.js";
-import { type AccessCheckResult } from "./bastion-errors.js";
-export interface ExecOutput {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    durationMs: number;
-}
-export declare class BastionClient {
-    private client;
-    private connecting;
-    /** Serializes ensureBastionReady / check cache updates. */
-    private gate;
-    private readonly config;
-    private readyUntil;
-    private unavailableUntil;
-    private lastUnavailable;
-    constructor(config: AppConfig);
-    /**
-     * Ensure bastion is reachable (TTL-cached). Uses an ephemeral SSH probe ?
-     * never disconnects an in-flight shared exec session on success.
-     */
-    ensureBastionReady(): Promise<void>;
-    /**
-     * Short-timeout Local to ACCESS probe (ephemeral client; <=10s worst case).
-     * Respects negative TTL (returns cached failure). Does not sever shared exec SSH.
-     */
-    check(): Promise<AccessCheckResult>;
-    exec(command: string, timeoutMs?: number, cwd?: string, signal?: AbortSignal): Promise<ExecOutput>;
-    disconnect(): void;
-    /**
-     * Upload local path (file or directory) ? bastion via independent Hop1 SFTP.
-     * Transfer-phase errors are not reclassified into ACCESS_UNAVAILABLE.
-     */
-    uploadPath(localPath: string, remotePath: string, options?: SftpCopyOptions): Promise<SftpTransferResult>;
-    /**
-     * Download bastion path (file or directory) ? local via independent Hop1 SFTP.
-     */
-    downloadPath(remotePath: string, localPath: string, options?: SftpCopyOptions): Promise<SftpTransferResult>;
-    private withGate;
-    private markReady;
-    /**
-     * Record a connect-phase failure. Negative TTL only for classified causes
-     * (not UNKNOWN), so transient unknowns are not blackholed for 15s.
-     */
-    private markConnectUnavailable;
-    /** Ephemeral SSH + shell probe; never assigns or disconnects `this.client`. */
-    private probeEphemeral;
-    private remoteSha256;
-    private ensureConnected;
-    private ensureConnectedUnlocked;
-    private requireClient;
-    /**
-     * Open a dedicated ssh2 Client with readyTimeout + hard deadline
-     * (covers TCP blackhole where ssh2 readyTimeout alone is insufficient).
-     */
-    private openSshClient;
-    private execOnClient;
-}