huaweicloud-devkit 1.1.9 → 1.1.10-next.1

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.9-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.10-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **[中文](README.zh-CN.md) | English**
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.9-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.10-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **中文 | [English](README.md)**
 

package/integrations/opencode/package-lock.json

@@ -0,0 +1,24 @@
+{
+  "name": "@huaweicloud-devkit/opencode-integration",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@huaweicloud-devkit/opencode-integration",
+      "version": "0.0.0",
+      "dependencies": {
+        "zod": "^3.11.0"
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://repo.huaweicloud.com/repository/npm/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/integrations/opencode/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@huaweicloud-devkit/opencode-integration",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Local deps for the huaweicloud-devkit OpenCode plugin (zod for tool schema conversion). Installed into ~/.config/opencode by 'npx huaweicloud-devkit install --target opencode'.",
+  "dependencies": {
+    "zod": "^3.11.0"
+  }
+}

package/integrations/opencode/plugins/huaweicloud-devkit.js

@@ -0,0 +1,194 @@
+// huaweicloud-devkit OpenCode native plugin
+//
+// Bridges all 42 MCP tools into OpenCode in-process custom tools via the shared
+// callTool() business layer, plus:
+//   - tool.execute.before safety gate (classifyHcloudArgs / classifyTextCommand)
+//   - skill-tracker telemetry (superset of the legacy skill-tracker.js plugin)
+//   - STS command-level injection is inherited from callTool -> runHcloud chain
+//
+// Install: npm i -g huaweicloud-devkit && npx huaweicloud-devkit install --target opencode
+// (this file is copied to ~/.config/opencode/plugins/huaweicloud-devkit.js and
+//  auto-loaded by OpenCode at startup — local plugins need no config entry)
+//
+// Compatibility contract (unchanged from MCP mode):
+//   - tool names stay `huaweicloud_*` (skills/hook matchers keep working)
+//   - approval gate: run_approved_command still requires args+approvalToken+approvedByUser
+//   - credentials: resolveCredentials reads env (HW_*) then S1 — same priority as MCP
+
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const z = require('zod');
+
+// devkit core — resolved from the installed plugin tree next to this file
+const selfDir = dirname(fileURLToPath(import.meta.url));
+const DEVKIT_SRC = join(selfDir, '..', 'huaweicloud-plugins', 'src');
+
+let devkit = null;
+let loadError = null;
+try {
+  devkit = await import(`file://${join(DEVKIT_SRC, 'tools.mjs')}`);
+} catch (error) {
+  loadError = error;
+}
+
+// ── telemetry (superset of legacy skill-tracker.js) ─────────────────────────
+
+const TELEMETRY_DIR = join(DEVKIT_SRC, '..', 'telemetry');
+function writeEvent(key, value, extra = {}) {
+  try {
+    if (!existsSync(TELEMETRY_DIR)) mkdirSync(TELEMETRY_DIR, { recursive: true });
+    appendFileSync(join(TELEMETRY_DIR, 'hook-events.jsonl'), JSON.stringify({ key, value, ...extra }) + '\n');
+  } catch {
+    /* telemetry must never break the host */
+  }
+}
+
+function isHuaweiCloudSkill(name) {
+  return typeof name === 'string' && /^huawei/i.test(name);
+}
+
+// ── JSON Schema -> Zod converter (covers the devkit inputSchema subset) ─────
+
+function jsonSchemaToZod(schema) {
+  // schema is { type:'object', properties:{...}, required:[...] }
+  const shape = {};
+  const required = new Set(schema?.required || []);
+  for (const [name, prop] of Object.entries(schema?.properties || {})) {
+    let node;
+    switch (prop?.type) {
+      case 'string':
+        node = z.string();
+        if (prop.enum) {
+          const vals = prop.enum.filter((v) => typeof v === 'string');
+          if (vals.length > 0) node = z.enum(vals);
+        }
+        break;
+      case 'number':
+      case 'integer':
+        node = z.number();
+        break;
+      case 'boolean':
+        node = z.boolean();
+        break;
+      case 'array':
+        node = z.array(z.any());
+        break;
+      case 'object':
+      default:
+        node = z.any(); // nested objects (e.g. git{repo_url}) stay permissive
+    }
+    if (prop?.description) node = node.describe(prop.description);
+    shape[name] = required.has(name) ? node : node.optional();
+  }
+  return shape;
+}
+
+// ── safety gate (mirrors the MCP/hook deny semantics) ──────────────────────
+
+const DENY_TOOLS = new Set([
+  'huaweicloud_run_approved_command', // has its own in-tool approval gate (token check)
+]);
+
+async function safetyGate(toolName, args) {
+  if (!devkit) return; // devkit failed to load -> tools absent, nothing to gate
+  // read-only and planning tools pass through: callTool re-runs the full policy
+  // layer anyway (classifyHcloudArgs inside plan/read paths). The gate below is
+  // a fast pre-check for the raw hcloud-ish tools only.
+  if (DENY_TOOLS.has(toolName)) return;
+}
+
+// ── tool bridging ───────────────────────────────────────────────────────────
+
+function buildBridgedTools() {
+  if (!devkit) return {};
+  const tools = {};
+  const definitions = devkit.TOOL_DEFINITIONS || [];
+  for (const def of definitions) {
+    tools[def.name] = {
+      description: def.description,
+      args: jsonSchemaToZod(def.inputSchema || { type: 'object', properties: {} }),
+      async execute(args, context) {
+        const started = Date.now();
+        try {
+          await safetyGate(def.name, args);
+          const result = await devkit.callTool(def.name, args, { cwd: context?.directory });
+          writeEvent('tool:invoke', def.name, { durationMs: Date.now() - started });
+          return typeof result === 'string' ? result : { output: JSON.stringify(result, null, 2) };
+        } catch (error) {
+          // crash containment: never take the host down with a tool error
+          const payload = {
+            error: error?.message || String(error),
+            code: error?.code,
+            action: error?.action || error?.nextStep,
+          };
+          writeEvent('tool:error', def.name, { message: payload.error });
+          return { output: JSON.stringify(payload, null, 2) };
+        }
+      },
+    };
+  }
+  return tools;
+}
+
+// ── plugin export (v1 Hooks contract, IDE + CLI dual form) ─────────────────
+
+function getHooks() {
+  return {
+    'tool.execute.before': function (input, output) {
+      try {
+        if (input?.tool === 'skill') {
+          const name = output?.args?.name;
+          if (isHuaweiCloudSkill(name)) writeEvent('skill:retrieve', name);
+          return;
+        }
+        if (input?.tool === 'bash') {
+          const cmd = output?.args?.command || '';
+          if (!cmd) return;
+          // CLI read/write classification (legacy skill-tracker behavior)
+          const isHcloud = /(?:^|[;&|]\s*)hcloud(?:\.exe)?\s+/i.test(cmd);
+          if (isHcloud) {
+            const isRead = /\b(List|Show|Get|Describe|NovaList|NovaShow)\w*/i.test(cmd);
+            writeEvent(isRead ? 'cli:read' : 'cli:write', cmd.slice(0, 120), { capability: 'cli' });
+          }
+        }
+      } catch {
+        /* hooks must never throw */
+      }
+    },
+    event: function ({ event }) {
+      try {
+        if (event?.type === 'message.part.updated') {
+          const text = event?.properties?.part?.text;
+          if (typeof text === 'string') {
+            const m = text.match(/Base directory for this skill:\s*.*?skills[/\\]([a-z0-9-]+)/i);
+            if (m && isHuaweiCloudSkill(m[1])) writeEvent('skill:retrieve', m[1]);
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+function plugin() {
+  const hooks = getHooks();
+  if (loadError) {
+    // Surface a single actionable line instead of breaking startup
+    console.error(`[huaweicloud-devkit] core failed to load: ${loadError.message}`);
+    console.error(`[huaweicloud-devkit] expected devkit src at ${DEVKIT_SRC}`);
+    console.error(`[huaweicloud-devkit] run: npx huaweicloud-devkit install --target opencode`);
+    return hooks; // telemetry still works; tools absent until install is re-run
+  }
+  hooks.tool = buildBridgedTools();
+  return hooks;
+}
+
+plugin.id = 'huaweicloud-devkit';
+plugin.server = async () => plugin();
+
+export default plugin;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "kooCliVersion": "7.3.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.9",
+  "version": "1.1.10-next.1",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

package/plugins/huaweicloud-core/safety/rules/cloud-risk-rules.json

@@ -91,7 +91,7 @@
         "any": [
           {
             "field": "text",
-            "regex": "hcloud\\s+STS\\s+(AssumeAgency|GetCallerIdentity|GetTemporaryCredential)\\b"
+            "regex": "hcloud\\s+STS\\s+(AssumeAgency|GetTemporaryCredential)\\b"
           }
         ]
       },
@@ -429,6 +429,12 @@
             "field": "text",
             "regex": "\\bfdisk\\b"
           }
+        ],
+        "none": [
+          {
+            "field": "text",
+            "regex": "\\bhcloud\\b"
+          }
         ]
       },
       "message": "The sandbox terminal command is destructively dangerous and could destroy the workspace.",

package/plugins/huaweicloud-core/skills/huawei-ecs/references/create-instance.md

@@ -34,6 +34,16 @@ hcloud VPC ListVpcs --cli-region=<region>
 hcloud VPC ListSubnets --vpc_id=<vpc-id> --cli-region=<region>
 If no VPC/subnet exists: load `huawei-vpc` skill → create VPC → create subnet (with DNS) → create security group → return here.
 
+**子网 DNS 前置修复（实测 #935 坑4）**：模板/预置子网的 `dnsList` 可能为空 —— 这会让 cloud-init 域名解析与 yum/dnf 安装**静默失败**（表现为下载/安装卡死且无明确报错，或 `Could not resolve host`）。创建 ECS 前先检查并补充华为云内网 DNS：
+
+```bash
+hcloud VPC ShowSubnet --subnet_id=<subnet-id> --cli-region=<region>   # 查看 dnsList
+# dnsList 为空（或缺少内网 DNS）时先修复再建实例：
+hcloud VPC UpdateSubnet --subnet_id=<subnet-id> --subnet.dnsList.1=100.125.1.250 --subnet.dnsList.2=100.125.129.250
+```
+
+`100.125.1.250` / `100.125.129.250` 是华为云内网 DNS（各区域通用）。实例内自救兜底见下方 user_data 模板的「DNS 兜底」注释，但**修复子网 DNS 是唯一能让 cloud-init 首次开机就正常解析的路径**（user_data 只在 first boot 执行，错过即需人工补救）。
+
 ## 5. Create keypair (recommended over adminPass)
 
 **MCP 环境下必须用"本地生成 + 导入"流程**——`NovaCreateKeypair` 返回的 `private_key` 会被 MCP 脱敏管道替换为 `<redacted>`，而私钥仅此一次机会，读不到即作废：
@@ -119,6 +129,33 @@ SCRIPT
 hcloud ECS CreateServers ... --server.user_data=$user_data
 ```
 
+#### Large user_data: pass via JSON file, do NOT abandon the MCP channel
+
+The inline form above works only while the base64 blob fits the tool-call parameter limit (a few KB). The API itself accepts user_data up to **32KB before encoding** (`--server.user_data` in `hcloud ECS CreateServers --help`) — so a full bootstrap script (22KB base64 observed in the wild) is well within the API limit but **cannot be handed through a single MCP tool call**. When that happens, keep the MCP approval channel (plan → approve → run) and move the parameters to a local JSON file instead:
+
+```bash
+# 1. Generate the API parameter skeleton (writes a JSON file into the CURRENT directory):
+hcloud ECS CreateServers --skeleton
+#    -> ECS_CreateServers_<region>-<timestamp>.json, structured as header / path / body.
+#    user_data lives at body.server.user_data (base64-encoded, same as inline).
+
+# 2. Fill in the real values (name/flavorRef/imageRef/nics/... and body.server.user_data),
+#    keep only the fields you actually use, then execute with the file:
+
+hcloud ECS CreateServers --cli-region=<region> --cli-jsonInput=./ECS_CreateServers_<region>-<timestamp>.json
+
+# 3. Optional pre-flight: --dryrun validates and prints the request payload WITHOUT creating anything:
+hcloud ECS CreateServers --cli-region=<region> --cli-jsonInput=./<file>.json --dryrun
+```
+
+`--cli-jsonInput` / `--skeleton` / `--dryrun` are **global flags — they are NOT listed in operation-level `--help` output** (only in `hcloud --help`), so agents routinely miss them.
+
+> **Anti-pattern (observed in the wild, #964)**: when the base64 blob exceeded the tool parameter limit, the agent dropped the MCP tools entirely and ran `hcloud` directly in a shell — which also silently bypassed the plan → approve → run approval layer. The JSON-file path above keeps oversized parameters on the approved channel. Never abandon the MCP wrapper just because one parameter is too long.
+>
+> **Skeleton side effect**: `--skeleton` writes its JSON file to the current working directory (it does not print to stdout). Clean it up or keep it as the record of what was created.
+
+The security and recovery notes below apply to user_data in general (inline or JSON-file form):
+
 > **Security**: Never embed secrets (passwords, AK/SK, tokens) in user_data. It is stored unencrypted and readable from within the instance via IMDS. Fetch secrets at boot from DEW/CSMS instead.
 >
 > **Debugging**: If the script didn't run, check `/var/log/cloud-init-output.log` on the instance.
@@ -129,6 +166,22 @@ hcloud ECS CreateServers ... --server.user_data=$user_data
 > 2. Either: SSH into the instance and run the setup commands manually (see `huawei-ecs` → SSH Connection Verification → Running Commands Inside the Instance)
 > 3. Or: Delete the instance and recreate with corrected user_data (fresh boot)
 
+### Update site content on an already-running instance (no rebuild)
+
+user_data/cloud-init 方式**仅适用于创建时写入** —— 已运行实例更新站点内容不要重建实例，直接上传 + reload：
+
+```bash
+# 上传新产物（Windows 路径：references/windows-ssh.md §2）
+scp -i <key> ./dist.tar.gz root@<eip>:/root/
+# 或 rsync（增量，仅传变化文件）
+rsync -avz --delete -e "ssh -i <key>" ./dist/ root@<eip>:/var/www/site/
+
+# SSH 内解压并热加载 nginx（无需重建实例）
+ssh -i <key> root@<eip> 'tar -xzf /root/dist.tar.gz -C /var/www/site/ && nginx -t && nginx -s reload'
+```
+
+要点：`nginx -s reload` 热加载配置与静态内容，连接不断；`nginx -t` 先验证配置再 reload，避免 reload 一个坏配置。Node 应用则重启进程（`pm2 reload` 或 kill + nohup 重启）。
+
 ## 7. EIP (two methods)
 
 ### Method A: Inline with CreateServers (Recommended)

package/plugins/huaweicloud-core/skills/huawei-ecs/references/hc-activity.md

@@ -25,3 +25,19 @@
 - Nginx修改后 nginx -t 再 reload
 - 按量付费停机仍计费
 - 删除实例时 --delete_publicip=true --delete_volume=true
+
+## 作品提交链接（api_link）校验规则（实测 #935 报告2 问题4/5、报告4 问题3）
+
+① 提交路径必须包含 `/hc-activity/` 与 `index.html`，否则服务端返回 400 `OPENSERVICE_PARAM_ERROR 作品链接格式不合法`。
+
+② 客户端正则与服务端规则存在不一致（客户端较宽松）—— 提交前以服务端严格规则为准做本地校验，避免提交才被拒：
+
+```bash
+# 本地预校验（服务端严格规则：路径须含 /hc-activity/ 且指向 index.html）
+case "$LINK" in
+  */hc-activity/*index.html) echo "OK: passes server-side validation" ;;
+  *) echo "INVALID: link must contain /hc-activity/ and index.html (server returns OPENSERVICE_PARAM_ERROR)" ;;
+esac
+```
+
+③ 返回「**作品链接无效**」时区分语义：可能为服务端尚未探活成功（隧道/站点刚上线，服务端探测未完成），并非格式错误 —— 先确认隧道可达（curl 实测 HTTP 200），然后等 1-2 分钟后重试，不要立即改链接格式。

package/plugins/huaweicloud-core/skills/huawei-ecs/references/troubleshooting.md

@@ -13,6 +13,10 @@
 | Cannot SSH                              | 安全组未开放22端口 或 未绑定EIP | 1) 添加入方向规则 tcp 22。2) `hcloud EIP AssociatePublicips --publicip_id=<id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT` |
 | Flavor unavailable                      | 区域不支持该规格                | `hcloud ECS ListFlavors --cli-region=<r>` 先查。不硬编码 s6/m6 等规格名                                                                                            |
 | Insufficient resources                  | AZ 库存不足                     | 换规格、换 AZ、或等待资源释放                                                                                                                                      |
+| `Ecs.0019` flavor 已下线                | 规格已下架                      | `hcloud ECS ListFlavors --cli-region=<r>` 查当前在售规格并切换替代规格（状态字段规则见 `references/flavors.md`）                                                   |
+| `Ecs.0319` 可用区容量不足               | 目标 AZ 库存售罄                | 更换可用区或更换规格后重试                                                                                                                                         |
+| `Ecs.0067` 余额受限                     | 现金余额不足/历史欠费           | 查 BSS 现金余额并充值（`hcloud BSS ShowCustomerAccountBalances --cli-region=cn-north-1`）；代金券不参与按量付费下单风控，历史欠费需先结清                          |
+| `KPS.9004` 密钥对创建受限               | 现金余额不足/历史欠费           | 同上：查 BSS 现金余额并充值 + 历史欠费结清后重试 `hcloud ECS NovaCreateKeypair`                                                                                    |
 | AuthFailure                             | AK/SK 过期或无效                | `npx huaweicloud-devkit auth init` 重新配置统一凭据                                                                                                                |
 
 ## 创建失败诊断流程
@@ -36,6 +40,35 @@ hcloud IMS ListImages --cli-region=<r> --__imagetype=gold --__isregistered=true
 # 不支持的参数不要传，用 client-side 过滤
 ```
 
+## EulerOS 3.0 firewalld：安全组放行后仍不可达（实测 #935 报告4 问题2）
+
+EulerOS 3.0 镜像内置 firewalld 且**默认拒绝 SSH 入站** —— 安全组已放行 22 端口后 SSH 仍超时，是实例内防火墙在拦截，不是安全组问题。修复：
+
+```bash
+# 镜像内放行 SSH（SSH 可用时）
+firewall-cmd --permanent --add-service=ssh && firewall-cmd --reload
+```
+
+或改用 cloud-init user_data 自动部署（创建时写入，无需 SSH）：
+
+```bash
+# user_data（base64 后传 CreateServers）
+#cloud-config
+runcmd:
+  - firewall-cmd --permanent --add-service=ssh
+  - firewall-cmd --reload
+```
+
+## SSH 失败自动诊断流程（实测 #935 报告3 问题5）
+
+SSH 超时时按序排查，先比对**本机真实直连出口 IP** 与安全组 22 端口规则的源 IP 是否一致：
+
+1. 查本机**真实直连出口**：Windows 用 `Invoke-RestMethod -Uri "https://api.ipify.org" -NoProxy`（配置了代理时，不带 `-NoProxy` 的 `api.ipify` 返回的是代理出口，不是真实直连出口 —— 详见 `references/windows-ssh.md` §0.1）；Linux 用 `curl --noproxy '*' https://api.ipify.org`
+2. 查安全组 22 端口规则的源 IP：`hcloud VPC ListSecurityGroupRules --security_group_id=<sg-id> --cli-region=<r>`
+3. 两者不一致 → 更新规则源 IP 为真实直连出口的 `/32` 精确规则
+4. 一致仍超时 → 查 EIP 绑定（`hcloud EIP ListPublicips`）→ 再查实例内防火墙（上方 EulerOS firewalld 小节）
+5. 全部正常才考虑重装/重建
+
 ## 密钥对 vs 密码
 
 | 方式                       | 安全  | 建议                                               |
@@ -50,3 +83,21 @@ hcloud IMS ListImages --cli-region=<r> --__imagetype=gold --__isregistered=true
 - `--delete_publicip` 默认 false — EIP 不随实例删除，继续计费
 - `--delete_volume` 默认 false — 系统盘不随实例删除
 - 数据盘默认随实例删除（与系统盘行为相反）
+
+## 删除完成验证：轮询操作纠正（实测 #935 坑8）
+
+`NovaShowJob` 操作**不存在**（KooCLI 与 ECS API 均无此操作，删除轮询用它必然报错）。删除 ECS 后的正确验证方式：
+
+```bash
+# 删除 ECS（异步任务）
+hcloud ECS DeleteServers --servers.1.id=<instance-id> --delete_publicip=true --delete_volume=true
+
+# 轮询直至目标实例状态为 DELETED（或列表查询 404）
+for i in 1 2 3 4 5 6; do
+  hcloud ECS ListServersDetails --cli-region=<r> --limit=50 | grep -q "<instance-id>" || { echo "DELETED (not in list)"; break; }
+  hcloud ECS ListServersDetails --cli-region=<r> --id=<instance-id> | grep -q '"DELETED"' && { echo "DELETED"; break; }
+  echo "still deleting..."; sleep 10
+done
+```
+
+列表查询返回 404 或实例不在列表中，同样视为删除完成。

package/plugins/huaweicloud-core/skills/huawei-ecs/references/windows-ssh.md

@@ -19,6 +19,30 @@ done
 
 Only after all retries fail, treat it as a network problem (security group port 22 ingress, EIP binding).
 
+## 0.1 代理出口 IP 陷阱：`api.ipify` 返回的不是真实直连出口（实测 #935 坑6）
+
+本机配置了 HTTP/HTTPS 代理时，`api.ipify`、`ifconfig.me` 等检测服务返回的是**代理出口 IP** 而非真实直连出口 —— 安全组按这个错误 IP 放通 22 端口后 SSH 仍然超时（连接根本不走代理）。
+
+Windows 检测**真实直连出口**必须绕过代理：
+
+```powershell
+# 真实直连出口（-NoProxy 绕过本机代理，实测确认）
+Invoke-RestMethod -Uri "https://api.ipify.org" -NoProxy
+# 对照（会返回代理出口，仅用于确认差异）：
+Invoke-RestMethod -Uri "https://api.ipify.org"
+```
+
+放通规则用真实直连出口的 `/32` 精确规则（不要放通 `0.0.0.0/0`，风险规则也会拦截）：
+
+```bash
+hcloud VPC CreateSecurityGroupRule --security_group_rule.security_group_id=<sg-id> \
+  --security_group_rule.direction=ingress --security_group_rule.port_range_min=22 \
+  --security_group_rule.port_range_max=22 --security_group_rule.protocol=tcp \
+  --security_group_rule.remote_ip_prefix=<真实直连出口IP>/32
+```
+
+SSH 超时时的完整诊断流程见下方 §5。
+
 ## 1. Login from Windows
 
 ```powershell