host-execution-mcp 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-16
+
+### Changed
+
+- Soften absolute agent wording: this MCP's tool path is ACCESS→host (`do not retry these tools`), not a ban on laptop SSH.
+- Example MCP configs (`GUIDE.md`, `mcp.example.json`, USER_GUIDE) use `host-execution-mcp@latest` so copy-paste snippets do not need a version bump.
+
 ## [1.0.0] - 2026-07-27
 
 First public release of **`host-execution-mcp`** (new npm package name; continues the Access → HostExecutionContext → Runtime line formerly developed as `bastion-k8s-mcp`).

package/README.md

@@ -55,7 +55,7 @@ Requires Node.js >= 18 only.
 }
 ```
 
-Pin a version for stability: `"args": ["-y", "host-execution-mcp@6.0.0"]`
+生产环境若要钉死版本，把 `@latest` 换成具体版本号即可。
 
 ### Option B — 本地开发
 

package/dist/instructions.js

@@ -1,66 +1,66 @@
 function buildSshBaseInstructions() {
-    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP.
-
-Execution model:
-  Access:  MCP client → AccessTransport → HostExecutionContext (landing)
-  Runtime: selected Context → shell / docker / k8s / copy (SessionPool; Runtime never creates SSH)
-  Derive:  context_derive → contextKey (ACCESS_KIND=ssh only). NOT SSH from the laptop.
-
-Context vs shell:
-- context_derive — create a derived HostExecutionContext; returns contextKey (does not probe reachability)
-- shell_exec — shell on a Context; never creates Context (omit contextKey = AccessTransport landing)
-- ssh_exec — shortcut for context_derive + shell_exec; returns reusable contextKey. Prefer for derive+shell in one call; reuse the key for follow-up docker_*/remote_*/shell_exec
-
-docker_* / context_probe: Runtime on selected Context.
-Omit contextKey = AccessTransport landing (ACCESS under ssh; TARGET under paradi-gateway).
-
-remote_* target=context = HostExecutionContext by contextKey (from context_derive / ssh_exec).
-
-Tool selection:
-- access_check — Local→ACCESS connectivity (≤10s; NOT kubectl). First session / after ACCESS_UNAVAILABLE
-- shell_exec — landing or derived shell (contextKey)
-- context_derive — need a contextKey without running a command yet
-- ssh_exec — one-shot derive+shell (returns contextKey)
-- docker_* — Docker on landing or contextKey
-- k8s_* — kubectl on landing only (by design). kubectl on a derived host: shell_exec(contextKey, "kubectl …")
-- remote_* target=landing|pod|context — files/ps/copy
-- remote_copy_file vs remote_copy_start — sync vs async; never auto-promote; prefer start when size>256MB or ETA>2min
-
-Hard rules:
-- access_check.reachable=false or code=ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST); do not retry other tools
-- SSH success ≠ docker/kubectl; unknown ≠ true — never invent true; never reuse capabilities across Contexts
-- Before pkill/kill/rm: remote_ps or user confirmation
-- Never assume namespace/paths; never reuse ACCESS_USER as TARGET_USER / derive user
-- success=false: read stdout (stderr merged). truncated → more lines / remote_copy_*
-- Multi-container pods: pass container name
+    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP.
+
+Execution model:
+  Access:  MCP client → AccessTransport → HostExecutionContext (landing)
+  Runtime: selected Context → shell / docker / k8s / copy (SessionPool; Runtime never creates SSH)
+  Derive:  context_derive → contextKey (ACCESS_KIND=ssh only). This tool path is ACCESS→host, not laptop SSH.
+
+Context vs shell:
+- context_derive — create a derived HostExecutionContext; returns contextKey (does not probe reachability)
+- shell_exec — shell on a Context; never creates Context (omit contextKey = AccessTransport landing)
+- ssh_exec — shortcut for context_derive + shell_exec; returns reusable contextKey. Prefer for derive+shell in one call; reuse the key for follow-up docker_*/remote_*/shell_exec
+
+docker_* / context_probe: Runtime on selected Context.
+Omit contextKey = AccessTransport landing (ACCESS under ssh; TARGET under paradi-gateway).
+
+remote_* target=context = HostExecutionContext by contextKey (from context_derive / ssh_exec).
+
+Tool selection:
+- access_check — Local→ACCESS connectivity (≤10s; NOT kubectl). First session / after ACCESS_UNAVAILABLE
+- shell_exec — landing or derived shell (contextKey)
+- context_derive — need a contextKey without running a command yet
+- ssh_exec — one-shot derive+shell (returns contextKey)
+- docker_* — Docker on landing or contextKey
+- k8s_* — kubectl on landing only (by design). kubectl on a derived host: shell_exec(contextKey, "kubectl …")
+- remote_* target=landing|pod|context — files/ps/copy
+- remote_copy_file vs remote_copy_start — sync vs async; never auto-promote; prefer start when size>256MB or ETA>2min
+
+Hard rules:
+- access_check.reachable=false or code=ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST); do not retry these tools
+- SSH success ≠ docker/kubectl; unknown ≠ true — never invent true; never reuse capabilities across Contexts
+- Before pkill/kill/rm: remote_ps or user confirmation
+- Never assume namespace/paths; never reuse ACCESS_USER as TARGET_USER / derive user
+- success=false: read stdout (stderr merged). truncated → more lines / remote_copy_*
+- Multi-container pods: pass container name
 - Operational cookbook (shell quoting, CRLF, docker login quirks, registry probes): see docs/AGENT_GUIDE.md`;
 }
 function buildParadiBaseInstructions(config) {
     const target = config.targetHost?.trim() || "<TARGET_HOST>";
-    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP (ACCESS_KIND=paradi-gateway).
-
-Landing endpoint is TARGET (${target}) — not the gateway OS. Runtime does not know gateway details; never creates SSH.
-
-Derive / context_derive / ssh_exec / remote_* target=context / contextKey: unsupported by current Paradi AccessTransport (landing is already TARGET). Handlers throw if called — omit contextKey; use target=landing|pod|local.
-
-Default workflow:
-- Shell: shell_exec or remote_* target=landing
-- Docker / context_probe: omit contextKey (landing = TARGET)
-- Pods: k8s_* / remote_* target=pod (kubectl on landing)
-- Copy: local↔landing or pod/local; SFTP degraded — prefer remote_copy_start for large files
-
-Hard rules:
-- access_check.reachable=false or ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST)
-- unknown ≠ true; SSH success ≠ docker/kubectl; never reuse capabilities across Contexts
-- Before pkill/kill/rm: remote_ps or user confirmation
-- Never assume namespace/paths
+    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP (ACCESS_KIND=paradi-gateway).
+
+Landing endpoint is TARGET (${target}) — not the gateway OS. Runtime does not know gateway details; never creates SSH.
+
+Derive / context_derive / ssh_exec / remote_* target=context / contextKey: unsupported by current Paradi AccessTransport (landing is already TARGET). Handlers throw if called — omit contextKey; use target=landing|pod|local.
+
+Default workflow:
+- Shell: shell_exec or remote_* target=landing
+- Docker / context_probe: omit contextKey (landing = TARGET)
+- Pods: k8s_* / remote_* target=pod (kubectl on landing)
+- Copy: local↔landing or pod/local; SFTP degraded — prefer remote_copy_start for large files
+
+Hard rules:
+- access_check.reachable=false or ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST)
+- unknown ≠ true; SSH success ≠ docker/kubectl; never reuse capabilities across Contexts
+- Before pkill/kill/rm: remote_ps or user confirmation
+- Never assume namespace/paths
 - Operational cookbook: docs/AGENT_GUIDE.md`;
 }
 /** TARGET_* default derive auth so agents omit configured defaults instead of asking the human. */
 export function buildDerivedHostAuthGuidance(config) {
     if (config.accessKind === "paradi-gateway") {
         const host = config.targetHost?.trim();
-        return `
+        return `
 Paradi landing: Context endpoint is TARGET${host ? ` (${host})` : ""}. Derive unsupported by current Paradi AccessTransport — omit contextKey; context_derive / ssh_exec / target=context throw if called. Use shell_exec, docker_*, k8s_*, target=landing|pod|local.`;
     }
     const user = config.targetUser?.trim();
@@ -70,18 +70,18 @@ Paradi landing: Context endpoint is TARGET${host ? ` (${host})` : ""}. Derive un
     const noAccessUserFallback = " Never reuse ACCESS_USER as TARGET_USER / derive user — pass TARGET_USER (or tool user) explicitly.";
     const shortcutHint = " ssh_exec = context_derive + shell_exec shortcut (returns reusable contextKey).";
     if (!user && !passwordSet) {
-        return `
+        return `
 Derive host auth: TARGET_* unset — pass user (password if no key).${hostHint}${noAccessUserFallback}${shortcutHint} Do not invent defaults.`;
     }
     if (user && passwordSet) {
-        return `
+        return `
 Derive host auth: TARGET_* active (user=${user}, password=set)${hostHint} — omit user/password on context_derive / ssh_exec; do not ask the human. Override only for a different account.${noAccessUserFallback}${shortcutHint}`;
     }
     if (user) {
-        return `
+        return `
 Derive host auth: TARGET_USER=${user}${hostHint} — omit user on context_derive / ssh_exec; pass password only if no key.${noAccessUserFallback}${shortcutHint}`;
     }
-    return `
+    return `
 Derive host auth: TARGET_PASSWORD set${hostHint} — omit password on context_derive / ssh_exec; still pass user (TARGET_USER unset). Do not invent a username.${noAccessUserFallback}${shortcutHint}`;
 }
 export function buildServerInstructions(config) {

package/docs/AGENT_GUIDE.md

@@ -15,7 +15,7 @@ User config is `ACCESS_*` / `TARGET_*` only. Async copy root: `ACCESS_COPY_JOB_R
 
 ## Architecture (read this first)
 
-**There is no direct connection from the user's laptop to pods or cluster nodes.**
+**On this MCP path**, there is no laptop SSH to pods or cluster nodes.
 
 ### Shape A — ACCESS_KIND=ssh
 

package/docs/CONFIGURATION.md

@@ -123,7 +123,15 @@ Default `ACCESS_PARADI_AUTH=auto` (may omit):
 2. On AUTH_FAILED only, try **compound** username `ACCESS_USER` + `ACCESS_PASSWORD@##@TARGET_HOST:SSH:22:TARGET_USER`
 3. Pin the winner for this MCP process (restart MCP to clear / re-probe)
 
-Ops override: set `ACCESS_PARADI_AUTH=slash` or `compound` to force one encoding. `access_check` may report `paradiAuth` after success.
+Ops may force `ACCESS_PARADI_AUTH=auto|slash|compound` (customers usually keep **`auto`**). One table:
+
+| Mode | Username | Password | Fit | Example (manual SSH equivalent) |
+| --- | --- | --- | --- | --- |
+| **auto** (default) | Try slash first; on AUTH_FAILED try compound; pin winner for this process | same as winners | Unknown which gateway capability is enabled | No manual pick; `access_check` may show `paradiAuth` |
+| **slash** | `USER/HOST/OSUSER` | gateway password | Gateway selects asset via slash username | `ssh zhangyimingzgc/10.121.35.68/mccuseradmin@10.121.61.3` (password = gateway password; gateway `10.121.61.3` → `10.121.35.68` / `mccuseradmin`) |
+| **compound** | `USER` | `password@##@HOST:SSH:22:OSUSER` | Gateway has program penetration | `ssh ellazj@10.121.61.10` (password = `gatewayPassword@##@10.121.35.74:SSH:22:mccuseradmin`; gateway `10.121.61.10` → `10.121.35.74` / `mccuseradmin`) |
+
+Do not put slash usernames or `@##@` strings in mcp.json — the server encodes them.
 
 Landing Context is already TARGET: use `shell_exec` / `docker_*` (omit contextKey).
 

package/docs/USER_GUIDE.zh-CN.md

@@ -1,25 +1,48 @@
 # host-execution-mcp 使用教程
 
-**本机 Cursor → SSH（ACCESS / 帕拉迪网关）→ 落点 HostExecutionContext → kubectl / docker / shell**（笔记本不直连 Pod）。
+**使用场景：本地可以直连入口机（跳板 / 帕拉迪网关），再进入 K8s 集群或目标主机，AI 辅助分析代码、文件传输等等。**
 
-工具名：`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)。
+**本机 Cursor → SSH（ACCESS）→ 落点 HostExecutionContext → kubectl / docker / shell / 再跳目标机**（这条路径上笔记本不直连 Pod）。
 
----
+> 包名已由 `bastion-k8s-mcp` 升级为 **`host-execution-mcp`**。环境变量统一为 `ACCESS_*` / `TARGET_*`（不再使用 `BASTION_*` / `REMOTE_SSH_*`）。
+
+:::
+建议配套 [**k8s-multi-node-deploy**](https://sh-code.mthreads.com/andy.wang/agent-compose/-/tree/master/skill/env/k8s-multi-node-deploy?ref_type=heads) skill 效果更佳~~~，无法访问联系我 $\color{#0089FF}{@Andy Wang}$
+:::
 
 ## 1. 安装 Node.js
 
-需要 **Node.js >= 18**。官网 [nodejs.org](https://nodejs.org) 下载 LTS，安装后验证：
+MCP 需要运行在 Node.js 环境上，**Node.js >= 18**。官网 [nodejs.org](https://nodejs.org) 下载 LTS，安装后验证：
 
 ```bash
 node -v
 ```
 
----
-
-## 2. MCP 配置（Cursor）
+## 2. MCP 配置（Cursor 为例）
 
 配置文件：`.cursor/mcp.json`，或 Cursor → Settings → MCP → Edit Config。
 
+先问自己一句：**本机能不能用普通 `ssh user@ip` 直接登到要用的那台机器（或跳板）？** 答案决定 `ACCESS_KIND`。
+
+| `ACCESS_KIND` | 你的实际情况 | 一句话 |
+| --- | --- | --- |
+| **`ssh`**（默认） | 本机（通常开 VPN）能**正常 SSH** 到入口机 / 目标机，连上就是 bash，没有「选资产 / 选账号」菜单 | 普通 SSH 场景 |
+| **`paradi-gateway`** | **不能**对目标机直接 `ssh`；只能先连帕拉迪网关，再在网关里交互选资产、选登录账号，才能落到业务机 | 网关菜单穿透场景（见下图） |
+
+**`ssh` 长什么样：** 本机执行例如 `ssh mccxadmin@10.121.120.7`，输密码后直接进系统 shell —— 配 `ACCESS_KIND=ssh`（§2.1）。
+
+**`paradi-gateway` 长什么样：** 本机只能先 `ssh 网关账号@网关IP`，连上后出现「目标资产列表 / 登录帐号列表」，要手选数字才能进机器 —— **MCP 替你省掉这份交互**，用编码账号/密码直接落到目标机（§2.2）。真实终端示意：
+
+![帕拉迪网关：先连网关，再选资产与账号，才能进入目标机](./paradi-gateway-interactive.png)
+
+选好模式后，抄下面对应小节的 `env`。
+
+### 2.1 `ACCESS_KIND=ssh`：本机能正常 SSH（跳板 / K8s）
+
+:::
+**需要先验证本地机器通过 VPN 能登录到 `10.121.120.7` 才行（找四季青运维）**
+:::
+
 ```json
 {
   "mcpServers": {
@@ -27,67 +50,160 @@ node -v
       "command": "npx",
       "args": ["-y", "host-execution-mcp@latest"],
       "env": {
+        "ACCESS_KIND": "ssh",
         "ACCESS_HOST": "10.121.120.7",
-        "ACCESS_USER": "your-user"
+        "ACCESS_USER": "mccxadmin",
+        "ACCESS_PASSWORD": "mccxadminjd",
+        "ACCESS_PORT": "22",
+        "ALLOWED_NAMESPACES": "his-test"
+      }
+    }
+  }
+}
+```
+
+`ACCESS_HOST` + `ACCESS_USER` 填你**本机能 SSH 直连的入口机**地址和账号即可（MCP 会用同样的方式登录）。
+
+可选：若常从跳板再 SSH 到某台目标机，可加默认第二跳：
+
+```json
+"TARGET_HOST": "10.121.32.69",
+"TARGET_USER": "mccxadmin",
+"TARGET_PASSWORD": "mccxadmin"
+```
+
+### 2.2 `ACCESS_KIND=paradi-gateway`：不能直连目标机，经帕拉迪网关
+
+本机**无法**对业务机普通 SSH；只能连网关。客户只需配**网关账号** + **目标机 IP/系统用户**；**不要**手写三段用户名或 `@##@` 密码串（MCP 内部编码，效果等价于你在菜单里选好资产与账号）。默认 `ACCESS_PARADI_AUTH=auto`：先试 slash，失败再试 compound，成功后进程内钉死。
+
+```json
+{
+  "mcpServers": {
+    "host-execution-paradi": {
+      "command": "npx",
+      "args": ["-y", "host-execution-mcp@latest"],
+      "env": {
+        "ACCESS_KIND": "paradi-gateway",
+        "ACCESS_HOST": "10.121.61.10",
+        "ACCESS_PORT": "22",
+        "ACCESS_USER": "ellazj",
+        "ACCESS_PASSWORD": "<网关密码>",
+        "ACCESS_PARADI_AUTH": "auto",
+        "TARGET_HOST": "10.121.35.74",
+        "TARGET_USER": "mccuseradmin"
       }
     }
   }
 }
 ```
 
-`ACCESS_HOST` + `ACCESS_USER` 填你**本机能 SSH 直连的入口机**（跳板或目标机）即可。可选 `TARGET_HOST` / `TARGET_USER` / `TARGET_PASSWORD` 作为默认第二跳（见 CONFIGURATION.md）。
+运维可强制：`ACCESS_PARADI_AUTH` = `auto` | `slash` | `compound`（一般客户保持 **`auto`** 即可）。对照表：
+
+| 模式 | 用户名 | 密码 | 适合 | 实际场景（手动 SSH 等价） |
+| --- | --- | --- | --- | --- |
+| **auto**（默认） | 先按 slash，AUTH_FAILED 再按 compound；成功后进程内钉死赢家 | 同上 | 不确定网关开了哪种能力时 | 无需手选；`access_check` 可看 `paradiAuth` |
+| **slash** | `USER/HOST/OSUSER` | 网关密码 | 网关按三段用户名选资产 | `ssh zhangyimingzgc/10.121.35.68/mccuseradmin@10.121.61.3`，密码填网关密码（网关 `10.121.61.3` → `10.121.35.68` / `mccuseradmin`） |
+| **compound** | `USER` | `密码@##@HOST:SSH:22:OSUSER` | 网关已开程序穿透 | `ssh ellazj@10.121.61.10`，密码填 `网关密码@##@10.121.35.74:SSH:22:mccuseradmin`（网关 `10.121.61.10` → `10.121.35.74` / `mccuseradmin`） |
+
+mcp.json **不要**手写三段用户名或 `@##@` 串，由 MCP 按上表编码。
 
 保存后重启 MCP 服务。验证连通：
 
-> 先用 host-execution 跑 `access_check`。若要做 Kubernetes 相关操作，通过后再跑 `kubectl cluster-info --request-timeout=5s`（纯 ACCESS/主机 SSH 任务不必跑 cluster-info）。
+> 用 host-execution 跑 `access_check`；若要做 K8s，再让 Agent 执行 `kubectl cluster-info --request-timeout=5s`
 
-若提示 `ACCESS_UNAVAILABLE` / 无法连接：先检查本机 VPN 与 `ACCESS_HOST`，不要反复重试其他工具。
+若提示 `ACCESS_UNAVAILABLE`：先查 VPN / `ACCESS_HOST`，不要反复重试本 MCP 的其他工具。
 
 ---
 
 ## 3. 怎么用
 
-对 Agent **用自然语言**说清：**命名空间、负载/Pod 名、文件路径**；需要时加「只读，不要改」。
+对 Agent **用自然语言**说清：**命名空间、负载/Pod 名、文件路径**；**需要时加「只读，不要改」**，可减少 AI 操作带来的不确定性风险（尤其破坏性操作）。
 
 | 你想做的事 | 告诉 Agent |
-|-----------|-----------|
+| --- | --- |
 | 找 Pod | 命名空间 + Deployment/负载名 |
 | 看日志 | Pod 名 + 日志**文件路径**（训练日志多在挂载盘，不是 stdout） |
 | 拷到本地 | 远程路径 + 本地目录（Agent 读取后写入本机） |
 | 排查故障 | 日志 / dmesg / core 路径 + 「只读分析」 |
+| 上目标机 | 目标 IP + 用户（有 `TARGET_*` 时可省略，让 Agent `context_derive` / 跳板执行） |
+| 帕拉迪落点 | 已在目标机：直接 `shell_exec` / `docker_*`，不要再 derive |
 
 输出太大被截断时，让 Agent 用 `grep`、`tail` 缩小范围。
 
----
+常用工具（Agent 侧）：`access_check`、`shell_exec`、`context_derive`、`k8s_*`、`docker_*`、`remote_*` / `remote_copy_*`。
 
-## 4. 示例话术
+---
 
-**查负载**
+## 4. 示例
 
-> `his-test` 命名空间，列出 `jd-joyvideo-test` 的 Pod 状态和 IP。
+1. MCP + SKILL → 让从零重新创建一个负载，然后拉 128 个节点
 
-**看训练日志**
+   ![d36c358b1c6ee6cc73b978f300978c27.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/8045491c-9f79-49bb-9ee8-63e90c726336.png)
 
-> Pod `jd-joyvideo-test-xxx`，tail `/mnt/code/.../log.65.10.121.33.74` 最后 200 行，看有没有 Killed 或 MUSA error。只读。
+2. 帮进行多机 mccl-test 测试（替换新 mccl 测试）
 
-**拷 log 到本地**
+   （上下文信息已经有了对应 16 机信息）
 
-> 把 Pod `jd-joyvideo-test-xxx` 上的 `/path/to/log` 和 `/path/to/core.mudmp` 拷到本地 `jd-joyvideo-logs/`，不要改远程文件。
+   ![a24515a4bcdf008990bcf01b899b89d9.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/c6dbb6fb-bfe1-4f25-b351-fa670f2523dd.png)
 
-**分析训练失败**
+3. 批量配置 128 机环境，并帮拉起训练做对比验证
 
-> 只读分析 Pod 上的 mudmp 和训练 log，启动脚本 `/mnt/code/0407/cluster/dist_run_fsdp8.sh`，说明失败原因。
+   ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/bc0d5e32-fc06-41d2-8387-0cfbe101f46d.png)
 
-**批量检查**
+4. 负载任务
 
-> 对 `his-test` 里所有 Running 的 `jd-joyvideo-test` Pod 跑 `mthreads-gmi -q | grep Bios`，汇总版本。
+   ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/4f8dc2c2-6445-44f8-b1d9-8aaf27d37ccc.png)
 
 ---
 
 ## 常见问题
 
-- **MCP 起不来**：检查 `node -v`、堡垒机地址账号、本机能否 `ssh user@10.121.120.7`
-- **k8s_logs 为空**：容器日志流（stdout+stderr）可能为空；日志在文件里时让 Agent 读挂载路径，不要只用 `k8s_logs`
-- **多个节点都 Killed**：先找第一个报 MUSA/SIGABRT 的 rank，其余可能是连锁退出
+* **MCP 起不来**：检查 `node -v`、入口机地址账号、本机能否 `ssh user@10.121.120.7`；确认 env 已改成 `ACCESS_*`（旧 `BASTION_*` 会被拒绝）
+* **仍配置 BASTION_***：会报错并提示改名；按上文 JSON 换成 `ACCESS_HOST` / `ACCESS_USER` / `ACCESS_PASSWORD`
+* **k8s_logs 为空**：日志在文件里，让 Agent 读挂载路径，不要只用 container stdout
+* **多个节点都 Killed**：先找第一个报 MUSA/SIGABRT 的 rank，其余可能是连锁退出
+* **帕拉迪连不上**：确认网关开了程序穿透（或 slash 可用）；可设 `ACCESS_PARADI_AUTH=compound` / `slash` 强制一种；`access_check` 成功后会带 `paradiAuth`
 
 更多配置见 [CONFIGURATION.md](./CONFIGURATION.md)。
+
+---
+
+# 补充：
+
+## Codex 使用
+
+本地 vscode + codex 也可用。
+
+将上述《host-execution-mcp 使用教程》的配置拷贝给 codex 插件，直接让其根据该配置，自动本地配好 MCP server。
+
+配置好后大概如下：
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/4286d40d-ca12-4bbd-94bf-beff93baefa7.png)
+
+也可以打开 `~/.codex/config.toml`（或本机 Codex 配置）增加配置如下：
+
+```toml
+[mcp_servers.host-execution]
+command = "npx"
+args = ["-y", "host-execution-mcp@latest"]
+
+[mcp_servers.host-execution.env]
+ALLOWED_NAMESPACES = "his-test"
+ACCESS_KIND = "ssh"
+ACCESS_HOST = "10.121.120.7"
+ACCESS_PASSWORD = "mccxadminjd"
+ACCESS_PORT = "22"
+ACCESS_USER = "mccxadmin"
+```
+
+> 使用时整个 vscode 窗口只能当作一个类似 Codex 桌面版 app，建议配合 terminal 使用。
+
+## 与旧包对照（迁移）
+
+| 旧（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_*`（帕拉迪） |

package/package.json

@@ -1,65 +1,65 @@
-{
-  "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": "1.0.1",
+  "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"
+  }
+}

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;
-}