huaweicloud-devkit 1.1.6-next.0 → 1.1.6-next.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.6-next.0",
+  "version": "1.1.6-next.1",
   "kooCliVersion": "7.2.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.6-next.0",
+  "version": "1.1.6-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.6-next.0",
+  "version": "1.1.6-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.6-next.0",
+  "version": "1.1.6-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.6-next.0",
+  "version": "1.1.6-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.6-next.0",
+  "version": "1.1.6-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.6-next.0",
+  "version": "1.1.6-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/skills/huawei-deployment/SKILL.md

@@ -18,8 +18,10 @@ Domain expertise for Huawei Cloud CloudDeploy. Covers application creation, depl
 
 | Trap                                                  | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Service name is `CodeArtsDeploy`                      | `hcloud CloudDeploy` returns `[USE_ERROR]不支持的服务名称`. The KooCLI service name is **CodeArtsDeploy** (product name CloudDeploy). Run `hcloud --help` to verify.                                                                                                                                                                                                                                                                                                                                                                                      |
+| Wrong operation names fail                            | The per-action names historically assumed (Start/List/Create/Delete + `Task`/`Tasks`) do NOT exist — KooCLI returns `[USE_ERROR]不支持的operation`. Use the verified names in Common Workflows.                                                                                                                                                                                                                                                                                                                                                           |
+| `project_id` is the CodeArts project ID               | Not the IAM project. If CodeArts is not enabled for the account, calls fail with `Deploy.00016902 项目不存在`.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | **Flyway SQL dialect mismatch (H2 dev → MySQL prod)** | Spring Boot apps commonly develop with H2 in-memory DB, then deploy to RDS MySQL. Flyway migrations using H2-specific syntax (e.g. `DATEADD`, `CHARACTER_LENGTH`, `BOOLEAN`) silently succeed on H2 but fail on MySQL. Before deploying, audit `V*__*.sql` migration files: replace `DATEADD` with `DATE_ADD`, `BOOLEAN` with `TINYINT(1)`, remove `characterEncoding=utf8mb4` from Spring Boot datasource URL (KooCLI RDS CreateInstance sets charset at the instance level). Use `Flyway.validate-on-migrate=true` in CI to catch dialect issues early. |
-| Service name may be `CodeArtsDeploy`                  | hcloud service name for deployment may be `CodeArtsDeploy` instead of `CloudDeploy`. Run `hcloud --help` to verify                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Deployment hosts need agent                           | Install CloudDeploy agent on target hosts first                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Task must reference application first                 | Create application before task                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Artifact source defaults to OBS                       | Most deployment tasks pull artifacts from OBS. Ensure bucket and object exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -27,22 +29,25 @@ Domain expertise for Huawei Cloud CloudDeploy. Covers application creation, depl
 
 ## Common Workflows
 
-| Task                   | Operation                                                        |
-| ---------------------- | ---------------------------------------------------------------- |
-| Create application     | `CreateApp --name=<n> --platform=<p> --cli-region=<r>`           |
-| Create deployment task | `CreateTask --name=<n> --app_id=<id> --artifact_source_type=OBS` |
-| Start deployment       | `StartTask --task_id=<id>`                                       |
-| List tasks             | `ListTasks --app_id=<id>`                                        |
-| Delete task            | `DeleteTask --task_id=<id>`                                      |
+| Task                   | Operation（省略参数用 `<placeholder>`，参数以 `hcloud CodeArtsDeploy <Op> --help` 为准）                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| List applications      | `ListAllApp --cli-region=<r> --project_id=<id> --page=1 --size=10`（`ListDeployTasks` 已由云侧于 2024-09-30 弃用，推荐本接口）                    |
+| Show app detail        | `ShowAppDetailById --cli-region=<r> --app_id=<id>`                                                                                                |
+| Create application     | `CreateApp --cli-region=<r> --name=<n> --create_type=template --project_id=<id> --is_draft=false`（`--create_type` 仅有 `template` 一个值）       |
+| Create deployment task | `CreateDeployTaskByTemplate --cli-region=<r> --template_id=<id> --task_name=<n>`（deprecated since 2024-09-30 — `--help` recommends `CreateApp`） |
+| Start deployment       | `StartDeployTask --cli-region=<r> --task_id=<id>`                                                                                                 |
+| Delete task            | `DeleteDeployTask --cli-region=<r> --task_id=<id>`（deprecated since 2024-09-30 — `--help` recommends `DeleteApplication --app_id=<id>`）         |
 
 ## Troubleshooting
 
-| Error              | Fix                                                                           |
-| ------------------ | ----------------------------------------------------------------------------- |
-| Agent offline      | Check agent service on target host, network connectivity, firewall rules      |
-| Deployment timeout | Check artifact size, increase task timeout, verify target host resources      |
-| Artifact not found | Verify OBS bucket and object path, check artifact permissions                 |
-| Permission denied  | Verify IAM roles for deployment: `CodeArtsDeploy FullAccess` or custom policy |
+| Error                                                 | Fix                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Agent offline                                         | Check agent service on target host, network connectivity, firewall rules                                                                               |
+| Deployment timeout                                    | Check artifact size, increase task timeout, verify target host resources                                                                               |
+| Artifact not found                                    | Verify OBS bucket and object path, check artifact permissions                                                                                          |
+| Permission denied                                     | Verify IAM roles for deployment: `CodeArtsDeploy FullAccess` or custom policy                                                                          |
+| `Deploy.00016902` 项目不存在                          | CodeArts not enabled or wrong project type: use the **CodeArts project ID** (found in CodeArts console), not the IAM project ID; enable CodeArts first |
+| `APIGW.0301` Incorrect IAM authentication information | Credentials lack CodeArtsDeploy access — use AK/SK with CodeArtsDeploy permissions (STS scoped credentials may be rejected)                            |
 
 ## Security
 

package/plugins/huaweicloud-core/skills/huawei-sandbox/SKILL.md

@@ -222,29 +222,84 @@ Expose a deployed web app to a public URL and return that URL to the developer.
 
 **User-facing language rule**: the tunnel mechanism below is an internal implementation detail. Never mention "DevBridge", "tunnel", or the tunnel CLI to the developer. Tell the developer only: "正在生成访问地址..." while exposing, then hand over the final URL.
 
-**Install** (internal tooling; skip if `devbridge version` already works):
+### Step 0: Ensure DevBridge CLI 0.2.x (install or upgrade in place)
+
+**Check the version first.** Sandboxes created before Sep 2026 ship devbridge 0.1.13, whose hardcoded gateway (`cn-north-4-bridge.myhuaweicloud.com`) was migrated and now serves a 「服务已迁移」 placeholder page — 0.1.x can no longer connect:
 
 ```bash
-if command -v devbridge >/dev/null 2>&1; then
-  echo "devbridge already installed"
-else
-  curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
+export PATH="$HOME/.huawei/bin:$PATH"   # PREPEND — appending lets a stale image binary in /usr/local/bin win
+devbridge version 2>/dev/null || echo "not installed"
+```
+
+- `0.2.x-release` → continue to Step 1.
+- `0.1.x-release` or not installed → upgrade in place (replaces the binary — keep NO second copy):
+
+```bash
+# Official installer (GitHub can be slow/flaky from the sandbox — force HTTP/1.1 and retry all errors)
+curl -fsSL --http1.1 --retry 3 --retry-all-errors --max-time 120 \
+  https://github.com/huaweicloud/devspace-devbridge/releases/latest/download/install.sh \
+  -o /tmp/devbridge-install.sh
+
+# Preferred: install via the GitCode mirror (domestic CDN, much faster).
+# Extract the version baked into the installer, then point -u at the matching GitCode tag.
+# Note: GitCode repo is named "devbrige" (missing 'd') — this is the actual repo name, not a typo.
+#       GitHub repo is "devspace-devbridge" (correct spelling). Do NOT "fix" the GitCode URL.
+DB_TARGET=$(grep -m1 'DEFAULT_VERSION=' /tmp/devbridge-install.sh | cut -d'"' -f2)
+if ! bash /tmp/devbridge-install.sh -s -u "https://gitcode.com/CloudDeveloperDepartment/devbrige/releases/download/${DB_TARGET}" -v "${DB_TARGET}"; then
+  bash /tmp/devbridge-install.sh -s   # fallback: GitHub (baked-in URL)
+fi
+export PATH="$HOME/.huawei/bin:$PATH"   # PREPEND (session shells do not re-source ~/.bashrc)
+devbridge version                     # must print 0.2.x-release
+
+# Remove the stale image-installed binary so only ONE version remains.
+# (Image sandboxes ship 0.1.x at /usr/local/bin/devbridge; the installer writes ~/.huawei/bin.
+#  Compare against the explicit ~/.huawei/bin path — never `command -v`, which can resolve
+#  to the stale binary itself when PATH order differs.)
+if [ -x "$HOME/.huawei/bin/devbridge" ] && [ -f /usr/local/bin/devbridge ] && [ "$(readlink -f /usr/local/bin/devbridge)" != "$(readlink -f "$HOME/.huawei/bin/devbridge")" ]; then
+  rm -f /usr/local/bin/devbridge && echo "stale /usr/local/bin/devbridge removed"
 fi
-export PATH=$PATH:$HOME/.huawei/bin   # installer only writes ~/.bashrc; session shells do not re-source it
 ```
 
-**Login** (non-interactive; credentials from `huaweicloud_sandbox_credentials` are available via `/tmp/hw_creds.sh`). If `source /tmp/hw_creds.sh` returns empty, the credentials injection has expired (sandbox session reconnection resets them) — re-run `huaweicloud_sandbox_credentials` first:
+- `-s` (silent) is **required** in the sandbox — without it the installer blocks reading `/dev/tty`.
+- **Old tunnels do not survive the upgrade**: 0.1.x-created tunnels are not registered on the s2 gateway — always rebuild the tunnel after upgrading (the expose flow below does this via pre-cleanup).
+- If `10006: quota exceeded` appears after upgrading, stale pre-upgrade tunnels still count against the quota — `devbridge delete-all` and retry.
+
+### Step 1: Authenticate with an API Key (0.2.x removed AK/SK login)
+
+devbridge 0.2.x removed `--access-key/--secret-key/--huaweicloud`. The only non-interactive auth is a DevBridge API Key. AK/SK (`/tmp/hw_creds.sh`) remains valid for hcloud, but not for devbridge.
+
+**Check, then login if the key exists** (the API Key is a long-lived account-level credential stored in its own file `/tmp/hw_api_key`, separate from the temporary AK/SK in `/tmp/hw_creds.sh` — never echo its value):
 
 ```bash
 source /tmp/hw_creds.sh 2>/dev/null
-devbridge auth login --huaweicloud --access-key "$HW_ACCESS_KEY" --secret-key "$HW_SECRET_KEY"
+source /tmp/hw_api_key 2>/dev/null
+if [ -n "$HW_API_KEY" ]; then
+  devbridge auth login --api-key "$HW_API_KEY" && devbridge auth status
+else
+  echo "NO_API_KEY"
+fi
 ```
 
-- The `--huaweicloud` flag is required for AK/SK login; without it the CLI tries an interactive browser login, which fails in the sandbox.
-- Credentials are stored in `/tmp/hw_creds.sh` (chmod 600) — source it before login, never echo the values.
-- Verify with `devbridge auth status`. If `$HW_ACCESS_KEY` is empty, ensure `huaweicloud_sandbox_credentials` was called first.
+**If `NO_API_KEY`** — STOP and guide the developer through creating one (wait for the key before continuing):
+
+1. **Why (one sentence)**: "沙箱的地址生成服务已升级到 0.2.x，新版本仅支持 API Key 登录（官方变更）。API Key 按账号管理，创建一次长期可用、所有沙箱通用。"
+2. **Where (exact steps)**: open https://devstation.connect.huaweicloud.com/space/devbridge/apikey → 登录控制台 → 选择 DevBridge 场景 → 点击"创建"。**完整值仅在创建时展示一次，立即复制**（`devbridge_` 开头）。
+3. **How to hand it over** (present both, recommend the first):
+   - **Recommended**: 在本地终端执行 `export HW_API_KEY=<粘贴Key>`（或写入 shell profile），然后告知"已设置" — Key 不经过对话记录；随后 agent 重新调用 `huaweicloud_sandbox_credentials`（本地 `HW_API_KEY` 会被自动透传注入沙箱）。
+   - **Alternative**: 直接把 Key 粘贴在对话中 — agent 通过 `huaweicloud_sandbox_credentials` 的 `api_key` 参数注入，**绝不回显、不复述、不写入日志**。
+4. **Security**: 不要提交到代码库或分享；怀疑泄露时在同页面删除并重建（1 分钟）。
 
-**Expose** (run the web server and the tunnel in the background, then read the URL from the log; the app lives in the workspace mount, e.g. `/workspace/<repo-name>`):
+**Failure paths**:
+
+| Symptom                                | Guidance                                             |
+| -------------------------------------- | ---------------------------------------------------- |
+| `auth login` returns 401/403           | Key 已被删除或禁用 — 引导在同页面删除旧 Key 重新创建 |
+| 无法访问 API Key 管理页面              | 账号无该页面权限 — 引导联系账号管理员处理            |
+| Key 带空格/换行/缺失 `devbridge_` 前缀 | 引导重新完整复制粘贴                                 |
+
+### Step 2: Expose
+
+Run the web server and the tunnel in the background, then read the URL from the log; the app lives in the workspace mount, e.g. `/workspace/<repo-name>`:
 
 ```bash
 # 0. Pre-cleanup: kill old processes and stale tunnels
@@ -273,13 +328,15 @@ else
 fi
 ```
 
-**Never return a tunnel URL without verifying it first** — a stale URL (from a killed tunnel process) will silently fail. Always curl-check before giving the URL to the developer.
+**Never return a tunnel URL without verifying it first** — a stale URL (from a killed tunnel process) will silently fail. Always curl-check before giving the URL to the developer. Note: a migrated gateway serves its placeholder page with **HTTP 200** — a bare status check is not enough when diagnosing "200 but wrong content".
 
 **Quota recovery**: if the tunnel creation fails with `10006: quota exceeded`:
 
 ```bash
 # Step A: List all tunnels (both active and stale)
-devbridge list -j
+#   0.2.x: `devbridge list` (plain table; data rows start with the 8-char tunnel ID)
+#   0.1.x (legacy): `devbridge list -j` (JSON)
+devbridge list
 # Step B: Remove all stale tunnels
 devbridge delete-all
 # Step C: Retry tunnel creation
@@ -289,10 +346,10 @@ sleep 10 && cat /tmp/host.log
 
 This eliminates the most common deployment failure — historical tunnels from previous sessions accumulating past the max=10 quota.
 
-- The public URL has the form `https://<id>-<port>.cn-north-4-bridge.myhuaweicloud.com` (from the `Tunnel URL:` line).
+- The public URL has the form `https://<id>-<port>.devbridge-s2.hwtunnel.com` (from the `Tunnel URL:` line; 8-char lowercase base32 id). The pre-migration bridge domain `cn-north-4-bridge.myhuaweicloud.com` is dead — treat any URL on it as broken and never hand one to the developer.
 - **Return this URL to the developer as the deployment result link.** Keep the host process running (do not close the session before handing over the URL).
 - Tunnel `description` (`-d`) accepts only Chinese characters, letters, and digits (0-64). Symbols such as `-`/`_`/spaces are rejected (`Invalid tunnel description`).
-- Internal docs: https://huaweicloud.github.io/devspace-devbridge/
+- Official docs: https://huaweicloud.github.io/devspace-devbridge/
 
 **No local downgrade**: if the tunnel tooling cannot be installed in the sandbox, STOP and report a generic error ("无法生成访问地址") without technical detail. Never install it on the developer's local machine — a local install would defeat the purpose of sandbox deployment.
 
@@ -446,7 +503,7 @@ For each check, parse the output: if stdout contains `MISSING:` or the tool wasn
 | pnpm         | `npm i -g pnpm`                                                                                                                                                                                                       | Same                        |
 | yarn         | `npm i -g yarn`                                                                                                                                                                                                       | Same                        |
 | Hugo         | `curl -fsSL https://github.com/gohugoio/hugo/releases/download/v0.140.0/hugo_extended_0.140.0_linux-amd64.tar.gz -o /tmp/hugo.tar.gz && sudo tar -xzf /tmp/hugo.tar.gz -C /usr/local/bin hugo && rm /tmp/hugo.tar.gz` | Same                        |
-| DevBridge    | `curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh \| bash && export PATH=$PATH:$HOME/.huawei/bin`                                                                                           | Same                        |
+| DevBridge    | Follow [Step 0 of "Expose the deployed app"](#step-0-ensure-devbridge-cli-02x-install-or-upgrade-in-place) — checks version, installs or upgrades in place via the official installer                                 | Same                        |
 
 **If Node.js is missing**, install it first — all build workflows depend on it. Stop and report to the developer if Node.js installation fails.
 
@@ -782,13 +839,15 @@ If the status code is not 2xx/3xx:
 
 ### Step 7: Expose via DevBridge [REQUIRED — deployment incomplete without this]
 
+When `deploy_check` returns `nextStep: expose_via_devbridge`, it also returns an executable `remediation` string — run those devbridge commands in the sandbox (after `source /tmp/hw_creds.sh`). Until a tunnel exists, `deploy_check` returns no `publicUrl`; do not fabricate a URL.
+
 Follow the standard [Expose the deployed app](#expose-the-deployed-app-public-url) procedure. The app is already running on the detected port — only DevBridge tunnel setup is needed.
 
 Use `exec_with_session` to background DevBridge. For SSR, DevBridge tunnels the nginx public port (not the Node port directly).
 
-**Pre-flight**: always run `devbridge delete-all` before creating a new tunnel to prevent `10006: quota exceeded` from accumulated stale tunnels. If you still get quota error, list tunnels with `devbridge list -j`, delete stale ones, and retry.
+**Pre-flight**: always run `devbridge delete-all` before creating a new tunnel to prevent `10006: quota exceeded` from accumulated stale tunnels. If you still get quota error, list tunnels with `devbridge list` (0.2.x plain table; 0.1.x legacy `-j` JSON), delete stale ones, and retry.
 
-Extract the tunnel URL from DevBridge output. The public URL has the form `https://<id>-<port>.cn-north-4-bridge.myhuaweicloud.com`. **Return this URL to the developer as the deployment result.**
+Extract the tunnel URL from DevBridge output. The public URL has the form `https://<id>-<port>.devbridge-s2.hwtunnel.com`. **Return this URL to the developer as the deployment result.**
 
 #### Cross-platform H5 QR code
 
@@ -830,8 +889,8 @@ The tool checks:
 
 - **nginx_serving** — nginx responds with 2xx/3xx on the app port
 - **output_dir** — build output directory exists and is non-empty
-- **devbridge_tunnel** — DevBridge tunnel is active
-- **tunnel_url_accessible** — tunnel URL returns 200/304
+- **devbridge_tunnel** — DevBridge tunnel is active (version-aware: 0.1.x JSON / 0.2.x table)
+- **tunnel_url_accessible** — tunnel URL returns 200/304 with real content; a gateway migration placeholder page (「服务已迁移」 with HTTP 200) counts as FAIL
 - **qr_code** (cross-platform only) — QR image exists in output dir
 
 Returns `complete: true/false`, `score`, and `nextStep` to fix missing items.
@@ -854,32 +913,36 @@ Returns `complete: true/false`, `score`, and `nextStep` to fix missing items.
 
 ## Critical Warnings
 
-| Trap                                 | Why                                                                                                                                                                                                                                     |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Target not confirmed                 | "部署到华为云" without a named target is NOT a go signal. You MUST run the Target-Selection Gate and get an explicit choice before calling any sandbox lifecycle tool. Skipping it and defaulting to the sandbox is a violation.        |
-| Agreement required first             | `sandbox_connect` fails if the agreement isn't signed; the `sandbox_check_user` preflight detects this, so surface it to the developer only when signing is needed                                                                      |
-| Real-name required                   | `sandbox_connect` fails if `realnameVerified=false`; tell the developer once and stop, don't loop on connect                                                                                                                            |
-| Never expose tunnel details          | Do not mention "DevBridge"/"tunnel"/"devbridge" to the developer — say "正在生成访问地址..." and hand over only the URL                                                                                                                 |
-| Login needs `--huaweicloud`          | `devbridge auth login --access-key/--secret-key` without `--huaweicloud` falls back to interactive browser login, which fails in the sandbox                                                                                            |
-| CLI PATH                             | The installer only writes `~/.bashrc`; run `export PATH=$PATH:$HOME/.huawei/bin` in the session before using `devbridge`                                                                                                                |
-| Never install tunnel tooling locally | If the sandbox cannot install it, report a generic error and stop — installing on the developer's machine defeats sandbox deployment                                                                                                    |
-| Return the deployment URL            | Always hand the public URL from the host log to the developer as the final result                                                                                                                                                       |
-| Deploy is not just nginx             | Configuring nginx does NOT complete the deployment. Steps 7 (DevBridge expose) and deploy_check are REQUIRED — `deploy_nginx` returns `nextStep: expose_via_devbridge` as a reminder. Do not stop after nginx.                          |
-| Call deploy_check before success     | Always call `huaweicloud_sandbox_deploy_check` before reporting deployment success. A green nginx status does not mean the tunnel is accessible — verify end-to-end with the tool.                                                      |
-| Session state persists               | `exec_with_session` preserves `cd`, env vars, aliases between calls                                                                                                                                                                     |
-| Long commands prefer one-shot        | `exec_one_shot` creates a fresh connection per call — more stable for builds, installs, and scripts >30s. See [Tool Selection Guide](#tool-selection-guide).                                                                            |
-| SSR nginx/Node ports must differ     | nginx `proxy_pass` targets `<nodePort>`, not `<port>`. `deploy_nginx` auto-defaults `nodePort` to `<port>+1` — always start the Node process with `PORT=<nodePort>` to match. Same-port = EADDRINUSE.                                   |
-| HTTP 200 ≠ correct content           | A green HTTP check does not guarantee the right project is serving — old processes from a previous session bound to the same port will still return 200. `deploy_check` verifies the deployment fingerprint to catch this.              |
-| Destructive commands blocked         | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy                                                                                                                                                                    |
-| Workspace ID = dev_stage_id          | Use `dev_stage_id` from `sandbox_connect` as `workspace_id` for terminal exec                                                                                                                                                           |
-| Projects live in `/workspace`        | Clone/install project code under `/workspace/<repo-name>` (filesystem-root workspace mount, not `$HOME/workspace`), never in `/tmp` — ephemeral locations lose the project when the sandbox session restarts                            |
-| Upload project for local code        | Use `sandbox_upload_project` to transfer local projects — packages as tar.gz, uploads via HTTP tunnel, extracts on sandbox. Much faster than base64 for multi-file projects                                                             |
-| Upload file for single files         | Use `sandbox_upload_file` for individual files — base64 chunked, reliable for small files (<1MB)                                                                                                                                        |
-| Node.js >= 22 required               | Sandbox terminal uses built-in WebSocket (globalThis.WebSocket); if Node.js is missing, install it from the Huawei Cloud mirror (see "Node.js in the sandbox")                                                                          |
-| Sandbox restart kills processes      | After sandbox restarts, all user processes (nginx, Node.js, Python servers) are stopped. Re-run startup commands and verify ports are listening before proceeding.                                                                      |
-| Cross-platform binaries incompatible | The sandbox runs Linux. Native binaries built on Windows/macOS (e.g., Prisma client, `node_modules/.prisma/`, platform-specific native addons) will not execute. Always install and build dependencies inside the sandbox, not locally. |
-| Cross-platform needs QR code         | When `detect_framework` returns `type: "cross-platform"` (Taro, uni-app), generating a QR code image is **mandatory** — the deployment is incomplete without it. Check the Deployment Completion Check table in Step 7.                 |
-| Build fails do NOT auto-fix          | When a build exits with non-zero exit code, STOP and present the error + fix options to the developer. Do not silently retry, modify configs, or change source files without explicit approval. See 4c-aux.                             |
+| Trap                                  | Why                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Target not confirmed                  | "部署到华为云" without a named target is NOT a go signal. You MUST run the Target-Selection Gate and get an explicit choice before calling any sandbox lifecycle tool. Skipping it and defaulting to the sandbox is a violation.                                                                        |
+| Agreement required first              | `sandbox_connect` fails if the agreement isn't signed; the `sandbox_check_user` preflight detects this, so surface it to the developer only when signing is needed                                                                                                                                      |
+| Real-name required                    | `sandbox_connect` fails if `realnameVerified=false`; tell the developer once and stop, don't loop on connect                                                                                                                                                                                            |
+| Never expose tunnel details           | Do not mention "DevBridge"/"tunnel"/"devbridge" to the developer — say "正在生成访问地址..." and hand over only the URL                                                                                                                                                                                 |
+| devbridge 0.2.x needs an API Key      | 0.2.x removed AK/SK login (`--access-key/--secret-key/--huaweicloud` are gone). Login with `--api-key "$HW_API_KEY"` from `/tmp/hw_api_key` (long-lived credential, stored separately from `/tmp/hw_creds.sh`). If missing, guide the developer to create one (see Step 1 of "Expose the deployed app") |
+| devbridge 0.1.x is dead               | Sandboxes created before Sep 2026 ship 0.1.13, which connects to a migrated gateway serving a 「服务已迁移」 placeholder with HTTP 200. Check `devbridge version` first and upgrade in place (Step 0) — old tunnels never survive the upgrade                                                           |
+| CLI PATH                              | The installer only writes `~/.bashrc`; run `export PATH="$HOME/.huawei/bin:$PATH"` (prepend) in the session before using `devbridge` — appending lets a stale image binary in `/usr/local/bin` win                                                                                                      |
+| Never install tunnel tooling locally  | If the sandbox cannot install it, report a generic error and stop — installing on the developer's machine defeats sandbox deployment                                                                                                                                                                    |
+| Return the deployment URL             | Always hand the public URL from the host log to the developer as the final result                                                                                                                                                                                                                       |
+| Deploy is not just nginx              | Configuring nginx does NOT complete the deployment. Steps 7 (DevBridge expose) and deploy_check are REQUIRED — `deploy_nginx` returns `nextStep: expose_via_devbridge` as a reminder. Do not stop after nginx.                                                                                          |
+| Call deploy_check before success      | Always call `huaweicloud_sandbox_deploy_check` before reporting deployment success. A green nginx status does not mean the tunnel is accessible — verify end-to-end with the tool.                                                                                                                      |
+| Session state persists                | `exec_with_session` preserves `cd`, env vars, aliases between calls                                                                                                                                                                                                                                     |
+| Long commands prefer one-shot         | `exec_one_shot` creates a fresh connection per call — more stable for builds, installs, and scripts >30s. See [Tool Selection Guide](#tool-selection-guide).                                                                                                                                            |
+| SSR nginx/Node ports must differ      | nginx `proxy_pass` targets `<nodePort>`, not `<port>`. `deploy_nginx` auto-defaults `nodePort` to `<port>+1` — always start the Node process with `PORT=<nodePort>` to match. Same-port = EADDRINUSE.                                                                                                   |
+| HTTP 200 ≠ correct content            | A green HTTP check does not guarantee the right project is serving — old processes from a previous session bound to the same port will still return 200. `deploy_check` verifies the deployment fingerprint to catch this.                                                                              |
+| Destructive commands blocked          | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy                                                                                                                                                                                                                                    |
+| Workspace ID = dev_stage_id           | Use `dev_stage_id` from `sandbox_connect` as `workspace_id` for terminal exec                                                                                                                                                                                                                           |
+| Projects live in `/workspace`         | Clone/install project code under `/workspace/<repo-name>` (filesystem-root workspace mount, not `$HOME/workspace`), never in `/tmp` — ephemeral locations lose the project when the sandbox session restarts                                                                                            |
+| Upload project for local code         | Use `sandbox_upload_project` to transfer local projects — packages as tar.gz, uploads via HTTP tunnel, extracts on sandbox. Much faster than base64 for multi-file projects                                                                                                                             |
+| Upload file for single files          | Use `sandbox_upload_file` for individual files — base64 chunked, reliable for small files (<1MB)                                                                                                                                                                                                        |
+| Node.js >= 22 required                | Sandbox terminal uses built-in WebSocket (globalThis.WebSocket); if Node.js is missing, install it from the Huawei Cloud mirror (see "Node.js in the sandbox")                                                                                                                                          |
+| Sandbox restart kills processes       | After sandbox restarts, all user processes (nginx, Node.js, Python servers) are stopped. Re-run startup commands and verify ports are listening before proceeding.                                                                                                                                      |
+| Cross-platform binaries incompatible  | The sandbox runs Linux. Native binaries built on Windows/macOS (e.g., Prisma client, `node_modules/.prisma/`, platform-specific native addons) will not execute. Always install and build dependencies inside the sandbox, not locally.                                                                 |
+| Cross-platform needs QR code          | When `detect_framework` returns `type: "cross-platform"` (Taro, uni-app), generating a QR code image is **mandatory** — the deployment is incomplete without it. Check the Deployment Completion Check table in Step 7.                                                                                 |
+| Build fails do NOT auto-fix           | When a build exits with non-zero exit code, STOP and present the error + fix options to the developer. Do not silently retry, modify configs, or change source files without explicit approval. See 4c-aux.                                                                                             |
+| Tunnel description: no spaces/hyphens | `devbridge create <name> -d 'hello world'` fails with `Invalid tunnel description: only Chinese characters, digits, letters, length 0-64`. The message is misleading — the real rule is no spaces/hyphens. Omit `-d` or use bare letters/digits.                                                        |
+| Use `host`, never `connect`           | `devbridge connect` is the sender side (for on-prem machines dialing out). For public preview it loops `Connection failed, retrying...` forever with no hint. Always use `devbridge host <tunnelId> -p <port>`.                                                                                         |
+| Port drift detaches the tunnel        | When deploy_nginx auto-increments to a free port, an existing tunnel stays bound to the old port — re-bind: `devbridge port create <tunnelId> -p <newPort> --protocol http -a` and restart `devbridge host`. deploy_nginx emits a warning when this happens.                                            |
 
 ## Node.js in the sandbox
 
@@ -896,11 +959,12 @@ node --version
 
 ## Environment Variables
 
-| Variable                | Required | Description                                                     |
-| ----------------------- | -------- | --------------------------------------------------------------- |
-| `HW_ACCESS_KEY`         | Yes      | Huawei Cloud AK                                                 |
-| `HW_SECRET_KEY`         | Yes      | Huawei Cloud SK                                                 |
-| `HW_SECURITY_TOKEN`     | No       | STS security token                                              |
-| `HW_WORKSPACE_ID`       | No       | Default workspace ID                                            |
-| `HDKITSERVICE_ENDPOINT` | No       | hdkitservice API endpoint (default: devkit.huaweicloud.com)     |
-| `HWLINK_ENDPOINT`       | No       | DevStation API endpoint (default: devstation.myhuaweicloud.com) |
+| Variable                | Required | Description                                                                                                                                                                     |
+| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HW_ACCESS_KEY`         | Yes      | Huawei Cloud AK                                                                                                                                                                 |
+| `HW_SECRET_KEY`         | Yes      | Huawei Cloud SK                                                                                                                                                                 |
+| `HW_SECURITY_TOKEN`     | No       | STS security token                                                                                                                                                              |
+| `HW_API_KEY`            | No       | DevBridge API Key (`devbridge_...`) — required for devbridge 0.2.x tunnel login; injected into the sandbox via `huaweicloud_sandbox_credentials` (`api_key` param or local env) |
+| `HW_WORKSPACE_ID`       | No       | Default workspace ID                                                                                                                                                            |
+| `HDKITSERVICE_ENDPOINT` | No       | hdkitservice API endpoint (default: devkit.huaweicloud.com)                                                                                                                     |
+| `HWLINK_ENDPOINT`       | No       | DevStation API endpoint (default: devstation.myhuaweicloud.com)                                                                                                                 |

package/plugins/huaweicloud-core/skills/huawei-sandbox/references/framework-commands.md

@@ -75,10 +75,10 @@ These tools should be available in the sandbox image. Verify with the pre-flight
 
 Tools that may need installation in the sandbox before building:
 
-| Tool      | Trigger                              | Install Command                                                                      |
-| --------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
-| yarn      | `yarn.lock` detected                 | `npm i -g yarn`                                                                      |
-| Hugo      | `hugo.toml` / `config.toml` detected | Download Hugo extended binary (see below)                                            |
-| DevBridge | Tunnel exposure step                 | `curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh \| bash` |
+| Tool      | Trigger                              | Install Command                                                                                          |
+| --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| yarn      | `yarn.lock` detected                 | `npm i -g yarn`                                                                                          |
+| Hugo      | `hugo.toml` / `config.toml` detected | Download Hugo extended binary (see below)                                                                |
+| DevBridge | Tunnel exposure step                 | Official installer with version check + in-place upgrade (see SKILL.md "Expose the deployed app" Step 0) |
 
 > Hugo download: `curl -fsSL https://github.com/gohugoio/hugo/releases/download/v0.140.0/hugo_extended_0.140.0_linux-amd64.tar.gz -o /tmp/hugo.tar.gz && sudo tar -xzf /tmp/hugo.tar.gz -C /usr/local/bin hugo && rm /tmp/hugo.tar.gz`

package/plugins/huaweicloud-core/src/mcp-protocol.mjs

@@ -59,6 +59,24 @@ export async function dispatch(method, params, opts = {}) {
   }
 
   if (method === 'tools/call') {
+    const tool = TOOL_DEFINITIONS.find((t) => t.name === params.name);
+    if (!tool) {
+      // JSON-RPC 2.0: an unknown tool name is a client-side parameter error,
+      // not a server fault (#704 D9-2).
+      const unknownToolError = new Error(`Unknown tool: ${params.name}`);
+      unknownToolError.code = -32602;
+      throw unknownToolError;
+    }
+    const missing = (tool.inputSchema?.required || []).filter(
+      (key) => !params.arguments || !Object.hasOwn(params.arguments, key),
+    );
+    if (missing.length > 0) {
+      const invalidParamsError = new Error(
+        `Invalid params: missing required field(s) ${missing.map((key) => JSON.stringify(key)).join(', ')} for tool "${params.name}".`,
+      );
+      invalidParamsError.code = -32602;
+      throw invalidParamsError;
+    }
     const result = await callTool(params.name, params.arguments || {});
     const decorated = _decorateResult(sessionId, params.name, result);
     return {

package/plugins/huaweicloud-core/src/mcp-server.mjs

@@ -128,7 +128,13 @@ function runStdioServer() {
         useContentLengthFraming = false;
         const line = buffer.subarray(0, lf).toString('utf8').trim();
         buffer = buffer.subarray(lf + 1);
-        if (line) void handleMessage(JSON.parse(line));
+        if (line) {
+          try {
+            void handleMessage(JSON.parse(line));
+          } catch {
+            writeParseError();
+          }
+        }
         continue;
       }
 
@@ -149,11 +155,21 @@ function runStdioServer() {
     if (buffer.length < bodyEnd) return false;
     const body = buffer.subarray(bodyStart, bodyEnd).toString('utf8');
     buffer = buffer.subarray(bodyEnd);
-    void handleMessage(JSON.parse(body));
+    try {
+      void handleMessage(JSON.parse(body));
+    } catch {
+      writeParseError();
+    }
     return true;
   }
 
   async function handleMessage(message) {
+    // Valid JSON that is not an object (null / array / string) is an invalid
+    // request per JSON-RPC 2.0 — reply -32600 rather than silently dropping it.
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      writeJsonRpcError(-32600, 'Invalid Request');
+      return;
+    }
     if (!Object.hasOwn(message, 'id')) {
       if (message.method === 'notifications/initialized') return;
       return;
@@ -181,4 +197,16 @@ function runStdioServer() {
       stdout.write(json + '\n');
     }
   }
+
+  function writeJsonRpcError(code, message) {
+    writeMessage({
+      jsonrpc: '2.0',
+      id: null,
+      error: { code, message },
+    });
+  }
+
+  function writeParseError() {
+    writeJsonRpcError(-32700, 'Parse error');
+  }
 }

package/plugins/huaweicloud-core/src/sandbox/session-manager.mjs

@@ -22,9 +22,18 @@ import { trackSandboxConnect, trackSandboxDisconnect } from '../telemetry/teleme
 
 const execFileAsync = promisify(execFile);
 
+// Public tunnel URL domain for the DevBridge s2 gateway. The pre-migration Huawei Cloud
+// bridge domain was retired in Sep 2026 and now serves a 「服务已迁移」 placeholder page with
+// HTTP 200 — never construct tunnel URLs from it.
+const DEVBRIDGE_TUNNEL_DOMAIN = 'devbridge-s2.hwtunnel.com';
+// Migration placeholder page marker — a tunnel URL returning this body must be treated as unreachable.
+const DEVBRIDGE_MIGRATION_MARKER = '服务已迁移';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const WS_EXEC_INDEX_URL = pathToFileURL(join(__dirname, '..', 'ws-exec', 'index.js')).href;
 
+export const TUNNEL_URL_PATTERN = /TUNNEL_URL:(https:\/\/[A-Za-z0-9_-]+-\d+\.devbridge-s2\.hwtunnel\.com)/;
+
 let currentWorkspaceId = process.env.HW_WORKSPACE_ID || null;
 
 function getCurrentWorkspaceId() {
@@ -180,6 +189,24 @@ export function splitBase64Chunks(base64, chunkSize = UPLOAD_CHUNK_SIZE) {
   return chunks;
 }
 
+export function formatPortConflictWarning(basePort, targetPort) {
+  return targetPort !== basePort ? `Port ${basePort} is in use — auto-assigned port ${targetPort}` : undefined;
+}
+
+export function formatPortDriftWarning(basePort, targetPort) {
+  if (targetPort === basePort) return undefined;
+  return `Port ${basePort} was occupied — nginx now listens on port ${targetPort}. Any DevBridge tunnel bound to port ${basePort} is detached: run "devbridge port create <tunnelId> -p ${targetPort} --protocol http -a" and restart "devbridge host" for the new port.`;
+}
+
+export function formatProxyPortWarning(basePort, targetPort) {
+  if (targetPort === basePort) return undefined;
+  return `Port ${basePort} is in use — the proxy template still listens on port ${basePort}: auto-increment does not apply to proxy configs, so nginx may fail to bind. Free the port or deploy a static/spa build instead.`;
+}
+
+export function buildExposeRemediation(port) {
+  return `In the sandbox: source /tmp/hw_creds.sh; source /tmp/hw_api_key 2>/dev/null; devbridge delete-all; devbridge create <name>; devbridge port create <tunnelId> -p ${port} --protocol http -a; nohup devbridge host <tunnelId> -p ${port} > /tmp/host.log 2>&1 & If deploy_nginx reported a different (auto-incremented) port in its "port" field, use THAT port instead of the one shown here. Full procedure in huawei-sandbox skill, Step 7 (Expose via DevBridge).`;
+}
+
 export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
   if (!existsSync(localPath)) {
     throw new Error(`sandbox upload: local file not found: ${localPath}`);
@@ -728,7 +755,6 @@ export async function deployNginx(
   const basePort = nginxType === 'proxy' ? listenPort : port;
 
   let targetPort = basePort;
-  let portWarning;
   const maxPortAttempts = 10;
   for (let offset = 0; offset < maxPortAttempts; offset += 1) {
     targetPort = basePort + offset;
@@ -740,9 +766,6 @@ export async function deployNginx(
         10000,
       );
       if (!String(portCheck.stdout || '').includes('IN_USE')) break;
-      if (offset === 0) {
-        portWarning = `Port ${basePort} is in use — auto-assigned port ${targetPort}`;
-      }
     } catch {}
     if (offset === maxPortAttempts - 1) {
       throw new Error(
@@ -840,9 +863,11 @@ fi`;
 
   let tunnelActive = false;
   try {
+    // Version-aware: devbridge 0.1.x exposes JSON via `list -j`; 0.2.x removed -j and
+    // prints a table whose data rows start with the 8-char base32 tunnel ID.
     const tunnelCheck = await execOneShot(
       workspaceId,
-      'devbridge list -j 2>/dev/null | grep -q \'"tunnelId"\' && echo "ACTIVE" || echo "INACTIVE"',
+      '(devbridge list -j 2>/dev/null | grep -q \'"tunnelId"\' || devbridge list 2>/dev/null | grep -Eq \'^[a-z2-7]{8}[[:space:]]\') && echo "ACTIVE" || echo "INACTIVE"',
       username,
       10000,
     );
@@ -860,9 +885,17 @@ fi`;
     stdout: result.stdout,
     nextStep: 'expose_via_devbridge',
     warning:
-      (!tunnelActive
-        ? 'No active DevBridge tunnel — deployment is incomplete. Proceed to Step 7 to expose the app.'
-        : portWarning) || undefined,
+      [
+        !tunnelActive
+          ? 'No active DevBridge tunnel — deployment is incomplete. Proceed to Step 7 to expose the app.'
+          : undefined,
+        nginxType === 'proxy'
+          ? formatProxyPortWarning(basePort, targetPort)
+          : formatPortConflictWarning(basePort, targetPort),
+        tunnelActive && nginxType !== 'proxy' ? formatPortDriftWarning(basePort, targetPort) : undefined,
+      ]
+        .filter(Boolean)
+        .join(' ') || undefined,
   };
 }
 
@@ -918,7 +951,13 @@ export async function deployCheck(
     `fi`,
     ``,
     `TOTAL=$((TOTAL+1))`,
+    `DB_TUNNEL_ACTIVE=0`,
     `if devbridge list -j 2>/dev/null | grep -q '"tunnelId"'; then`,
+    `  DB_TUNNEL_ACTIVE=1`,
+    `elif devbridge list 2>/dev/null | grep -Eq '^[a-z2-7]{8}[[:space:]]'; then`,
+    `  DB_TUNNEL_ACTIVE=1`,
+    `fi`,
+    `if [ "$DB_TUNNEL_ACTIVE" = "1" ]; then`,
     `  echo "devbridge_tunnel:PASS"`,
     `  PASS=$((PASS+1))`,
     `else`,
@@ -927,18 +966,29 @@ export async function deployCheck(
     ``,
     `TOTAL=$((TOTAL+1))`,
     `TUNNEL_ID=$(devbridge list -j 2>/dev/null | grep -oP '"tunnelId":\\s*"\\K[^"]+' | head -1)`,
-    `TUNNEL_URL="https://\${TUNNEL_ID}-${port}.cn-north-4-bridge.myhuaweicloud.com"`,
-    `if [ -n "$TUNNEL_ID" ] && [ -n "$TUNNEL_URL" ]; then`,
-    `  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")`,
-    `  if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "304" ]; then`,
-    `    echo "tunnel_url_accessible:PASS ($TUNNEL_URL -> $HTTP_CODE)"`,
-    `    PASS=$((PASS+1))`,
-    `  else`,
-    `    echo "tunnel_url_accessible:FAIL ($TUNNEL_URL -> HTTP $HTTP_CODE)"`,
-    `  fi`,
+    `if [ -z "$TUNNEL_ID" ]; then`,
+    `  TUNNEL_ID=$(devbridge list 2>/dev/null | grep -E '^[a-z2-7]{8}[[:space:]]' | awk '{print $1}' | head -1)`,
+    `fi`,
+    `TUNNEL_URL="https://\${TUNNEL_ID}-${port}.${DEVBRIDGE_TUNNEL_DOMAIN}"`,
+    `probe_tunnel() {`,
+    `  local url="$1" code`,
+    `  code=$(curl -s -o /tmp/.dc_tunnel_body -w "%{http_code}" --max-time 10 "$url" 2>/dev/null || echo "000")`,
+    `  [ "$code" = "000" ] && return 1`,
+    `  # A migrated gateway serves a placeholder page with HTTP 200 — treat it as unreachable.`,
+    `  if grep -q "${DEVBRIDGE_MIGRATION_MARKER}" /tmp/.dc_tunnel_body 2>/dev/null; then return 1; fi`,
+    `  rm -f /tmp/.dc_tunnel_body`,
+    `  [ "$code" = "200" ] || [ "$code" = "304" ] || return 1`,
+    `  return 0`,
+    `}`,
+    `if [ -n "$TUNNEL_ID" ] && probe_tunnel "$TUNNEL_URL"; then`,
+    `  echo "tunnel_url_accessible:PASS ($TUNNEL_URL)"`,
+    `  PASS=$((PASS+1))`,
+    `elif [ -n "$TUNNEL_ID" ]; then`,
+    `  echo "tunnel_url_accessible:FAIL ($TUNNEL_URL -> unreachable, tunnel not found, or migration placeholder page)"`,
     `else`,
-    `  echo "tunnel_url_accessible:FAIL (no tunnel URL)"`,
+    `  echo "tunnel_url_accessible:FAIL (no tunnel)"`,
     `fi`,
+    `rm -f /tmp/.dc_tunnel_body 2>/dev/null || true`,
     ``,
     `${`
 TOTAL=$((TOTAL+1))
@@ -999,7 +1049,7 @@ fi
     if (m) checks[m[1]] = { status: m[2], detail: (m[3] || '').trim() };
   }
   const scoreMatch = cleanStdout.match(/SCORE:(\d+)\/(\d+)/);
-  const tunnelMatch = cleanStdout.match(/TUNNEL_URL:(https:\/\/[^\s]+)/);
+  const tunnelMatch = cleanStdout.match(TUNNEL_URL_PATTERN);
   const complete = /VERDICT:COMPLETE/.test(cleanStdout);
 
   const missing = [];
@@ -1015,6 +1065,18 @@ fi
       ? 'Check output parsing failed — individual check results could not be extracted. See rawOutput for details.'
       : undefined;
 
+  const nextStepValue = !complete
+    ? missing.includes('devbridge_tunnel') || missing.includes('tunnel_url_accessible')
+      ? 'expose_via_devbridge'
+      : missing.includes('nginx_serving')
+        ? 'configure_nginx'
+        : missing.includes('qr_code')
+          ? 'generate_qr_code'
+          : parseWarning
+            ? 'review_raw_output'
+            : 'review_checks'
+    : 'complete';
+
   return {
     ok: true,
     complete,
@@ -1025,17 +1087,8 @@ fi
     missingSteps: missing.length > 0 ? missing.join(', ') : undefined,
     parseWarning,
     rawOutput: parseWarning ? stdout.trim() : undefined,
-    nextStep: !complete
-      ? missing.includes('devbridge_tunnel') || missing.includes('tunnel_url_accessible')
-        ? 'expose_via_devbridge'
-        : missing.includes('nginx_serving')
-          ? 'configure_nginx'
-          : missing.includes('qr_code')
-            ? 'generate_qr_code'
-            : parseWarning
-              ? 'review_raw_output'
-              : 'review_checks'
-      : 'complete',
+    nextStep: nextStepValue,
+    remediation: nextStepValue === 'expose_via_devbridge' ? buildExposeRemediation(port) : undefined,
   };
 }
 

package/plugins/huaweicloud-core/src/setup-cli.mjs

@@ -189,6 +189,10 @@ function officeaceCapabilitiesDir() {
   if (isUsableOfficeaceRoot(configRoot)) return configRoot;
   const markerRoot = readOfficeaceRootMarker();
   if (markerRoot) return markerRoot;
+  // Skip system probes (registry / Program Files) so automated environments can
+  // keep OfficeAce detection hermetic — those probes can leak a real OfficeAce
+  // install into a sandboxed/fake HOME (#654).
+  if (process.env.HUAWEICLOUD_DEVKIT_SKIP_OFFICEACE_DETECT === '1') return null;
   const regDir = readOfficeaceRegistryInstallDir();
   if (regDir) {
     const dir = join(regDir, '.office-claw');
@@ -587,7 +591,10 @@ function installRuntimeDeps(pluginsDir) {
 function removeIfExists(p) {
   if (existsSync(p)) {
     try {
-      rmSync(p, { recursive: true, force: true });
+      // Retry transient EBUSY/EPERM/ENOTEMPTY (locked files on Windows) before
+      // giving up — uninstall should not leave a skill behind just because a
+      // handle was momentarily open (#556).
+      rmSync(p, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
       return true;
     } catch (error) {
       console.log(`  \x1b[33m[WARN]\x1b[0m Could not remove ${p}: ${error.message}`);
@@ -846,8 +853,7 @@ function uninstallOpenCode() {
   if (existsSync(skills)) {
     for (const entry of readdirSync(skills, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skills, entry.name));
-        removed++;
+        if (removeIfExists(join(skills, entry.name))) removed++;
       }
     }
     console.log(`  Removed ${removed} skills`);
@@ -858,8 +864,7 @@ function uninstallOpenCode() {
   if (existsSync(commands)) {
     for (const entry of readdirSync(commands, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(commands, entry.name));
-        cmdRemoved++;
+        if (removeIfExists(join(commands, entry.name))) cmdRemoved++;
       }
     }
     if (cmdRemoved > 0) console.log(`  Removed ${cmdRemoved} commands`);
@@ -885,8 +890,7 @@ function pruneStale(targetDir, sourceDir) {
   for (const entry of readdirSync(targetDir, { withFileTypes: true })) {
     if (!entry.name.startsWith('huawei')) continue;
     if (!sourceNames.has(entry.name)) {
-      removeIfExists(join(targetDir, entry.name));
-      removed++;
+      if (removeIfExists(join(targetDir, entry.name))) removed++;
     }
   }
   return removed;
@@ -1033,8 +1037,7 @@ function uninstallOpenClaw() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     console.log(`  Removed ${removed} skills`);
@@ -1045,8 +1048,7 @@ function uninstallOpenClaw() {
   if (existsSync(cmdDir)) {
     for (const entry of readdirSync(cmdDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(cmdDir, entry.name));
-        cmdRemoved++;
+        if (removeIfExists(join(cmdDir, entry.name))) cmdRemoved++;
       }
     }
     if (cmdRemoved > 0) console.log(`  Removed ${cmdRemoved} commands`);
@@ -1192,8 +1194,7 @@ function uninstallCodexDesktop() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     console.log(`  Removed ${removed} skills`);
@@ -1204,8 +1205,7 @@ function uninstallCodexDesktop() {
   if (existsSync(cmdDir)) {
     for (const entry of readdirSync(cmdDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(cmdDir, entry.name));
-        cmdRemoved++;
+        if (removeIfExists(join(cmdDir, entry.name))) cmdRemoved++;
       }
     }
     if (cmdRemoved > 0) console.log(`  Removed ${cmdRemoved} commands`);
@@ -1349,8 +1349,7 @@ function uninstallCodeArts() {
     if (!existsSync(skillsDir)) continue;
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
   }
@@ -1510,8 +1509,7 @@ function uninstallCodeArtsWork() {
     let removed = 0;
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -1798,8 +1796,7 @@ function uninstallWorkBuddy() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -1835,9 +1832,10 @@ function uninstallWorkBuddy() {
     if (settings.hooks?.PostToolUse) {
       const before = settings.hooks.PostToolUse.length;
       settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((e) => e?.matcher !== '*');
-      if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+      const after = settings.hooks.PostToolUse.length;
+      if (after === 0) delete settings.hooks.PostToolUse;
       if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-      if (before !== settings.hooks.PostToolUse?.length) {
+      if (before !== after) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
         console.log(`  PostToolUse hook removed from ${settingsPath}`);
       }
@@ -1988,8 +1986,7 @@ function uninstallAtomCode() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -2303,8 +2300,7 @@ function uninstallDsh() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -2445,8 +2441,7 @@ function uninstallOfficeAce() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -3029,8 +3024,7 @@ function uninstallHermes() {
   if (existsSync(skillsDir)) {
     for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
       if (entry.name.startsWith('huawei')) {
-        removeIfExists(join(skillsDir, entry.name));
-        removed++;
+        if (removeIfExists(join(skillsDir, entry.name))) removed++;
       }
     }
     if (removed > 0) console.log(`  Removed ${removed} skills`);
@@ -4171,7 +4165,7 @@ async function cmdDoctor() {
     console.log('\x1b[33mFix failures above, then restart your session.\x1b[0m');
   }
   if (fail === 0 && mcpConfigured) {
-    console.log('\n\x1b[32mAll checks passed.\x1b[0m Restart your session, then describe your Huawei Cloud task');
+    console.log('\n\x1b[32mAll checks passed.\x1b[0m You can now describe your Huawei Cloud task');
   }
 
   // Detect "installed but not restarted" — check all supported agents

package/plugins/huaweicloud-core/src/tools.mjs

@@ -671,7 +671,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_deploy_nginx',
     description:
-      'Deploy an nginx configuration on the sandbox and reload. Takes nginxType, port, project, outputDir from framework detection and writes the correct template (SPA try_files, SSR reverse proxy, or static). Also fixes directory traverse permissions on the project path. Use this instead of manually constructing nginx config — it handles permissions, template selection, and reload in one call.',
+      'Deploy an nginx configuration on the sandbox and reload. Takes nginxType, port, project, outputDir from framework detection and writes the correct template (SPA try_files, SSR reverse proxy, or static). Also fixes directory traverse permissions on the project path. Use this instead of manually constructing nginx config — it handles permissions, template selection, and reload in one call. If the requested port is already in use, the actual port is auto-incremented and returned in "port" alongside a warning.',
     inputSchema: {
       type: 'object',
       required: ['nginx_type', 'port', 'project', 'output_dir'],
@@ -708,7 +708,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_deploy_check',
     description:
-      'Run a deployment completeness check on the sandbox. Verifies nginx is serving, output directory exists, DevBridge tunnel is active and accessible, and QR code exists (cross-platform). Returns a score and nextStep to fix any missing items. Call this at the end of a deployment workflow to confirm everything is working before reporting success.',
+      'Run a deployment completeness check on the sandbox. Verifies nginx is serving, output directory exists, DevBridge tunnel is active and accessible, and QR code exists (cross-platform). Returns a score, nextStep, and (when the DevBridge tunnel is missing) an executable "remediation" command string. Call this at the end of a deployment workflow to confirm everything is working before reporting success.',
     inputSchema: {
       type: 'object',
       required: ['port', 'project', 'output_dir'],
@@ -784,7 +784,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_credentials',
     description:
-      'Configure temporary AK/SK for a sandbox via hdkitservice. Validates the current AK/SK against IAM before injecting (invalid SK is rejected here instead of failing later with APIGW.0301 during exec), then injects temporary credentials into the sandbox. The sandbox must be in RUNNING state.',
+      'Configure temporary AK/SK for a sandbox via hdkitservice. Validates the current AK/SK against IAM before injecting (invalid SK is rejected here instead of failing later with APIGW.0301 during exec), then injects temporary credentials into the sandbox. Also injects an optional DevBridge API Key — required for devbridge 0.2.x tunnel exposure because 0.2.x removed AK/SK login. The API Key is a long-lived account-level credential, so it is stored in a separate file (/tmp/hw_api_key, 0600) from the temporary AK/SK (/tmp/hw_creds.sh). Source of truth: local HW_API_KEY env first, then the api_key param. The sandbox must be in RUNNING state.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -796,6 +796,11 @@ export const TOOL_DEFINITIONS = [
           description:
             'Region used for IAM credential validation and project_id resolution (defaults to the configured region)',
         },
+        api_key: {
+          type: 'string',
+          description:
+            'DevBridge API Key (devbridge_...), injected into the sandbox as HW_API_KEY for devbridge 0.2.x auth. The local HW_API_KEY environment variable takes precedence over this param (preferred delivery — keeps the long-lived key out of the conversation). Users create one at https://devstation.connect.huaweicloud.com/space/devbridge/apikey (full value shown once at creation). Required for exposing web apps via devbridge 0.2.x; if missing, guide the user through creating one.',
+        },
       },
     },
   },
@@ -1448,6 +1453,13 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const credResult = await hdkitCredentials(args.session_id, devStageId, args.enable_sts !== false);
       const sandboxWsIdCred = args.dev_stage_id || getCurrentWorkspaceId();
+      // The DevBridge API Key is a LONG-LIVED account-level credential (no expiry, manual
+      // revocation only) — unlike the temporary STS AK/SK. It is stored in its own file
+      // (/tmp/hw_api_key, 0600) so an accidental dump of /tmp/hw_creds.sh never exposes it,
+      // and the local HW_API_KEY env takes precedence over the tool param so the key can be
+      // delivered without entering the conversation.
+      const apiKey = process.env.HW_API_KEY || args.api_key || '';
+      const apiKeyFile = '/tmp/hw_api_key';
       if (sandboxWsIdCred) {
         try {
           const { ak, sk, securitytoken } = getCredentials();
@@ -1468,12 +1480,31 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
             15000,
           );
           await execWithSession(sandboxWsIdCred, `source ${credsFile} && echo "CREDS_SOURCED"`, 'root', 15000);
+          if (apiKey) {
+            await execOneShot(
+              sandboxWsIdCred,
+              `cat > ${apiKeyFile} << 'HWAPIKEY_EOF'\nexport HW_API_KEY='${apiKey}'\nHWAPIKEY_EOF\nchmod 600 ${apiKeyFile}`,
+              'root',
+              15000,
+            );
+          } else {
+            // Refresh with no key → drop any stale copy, same semantics as the creds file rewrite.
+            await execOneShot(sandboxWsIdCred, `rm -f ${apiKeyFile}`, 'root', 15000);
+          }
         } catch {}
       }
       const result = {
         ...credResult,
         credentialValidation: validation.warning ? 'passed-with-warning' : 'passed',
       };
+      if (sandboxWsIdCred) result.apiKeyInjected = Boolean(apiKey);
+      if (apiKey) {
+        result.apiKeyHint =
+          'DevBridge API Key written to /tmp/hw_api_key (0600, kept separate from the temporary AK/SK in /tmp/hw_creds.sh — it is a long-lived account-level credential). devbridge 0.2.x uses it via: source /tmp/hw_api_key && devbridge auth login --api-key "$HW_API_KEY". Never echo it into logs.';
+      } else {
+        result.apiKeyHint =
+          'No DevBridge API Key provided — devbridge 0.2.x cannot log in with AK/SK. To expose web apps, ask the user for an API Key (created at https://devstation.connect.huaweicloud.com/space/devbridge/apikey) and re-run with api_key, or set the local HW_API_KEY environment variable (preferred — keeps the key out of the conversation).';
+      }
       if (validation.projectId) result.projectId = validation.projectId;
       if (validation.warning) result.warning = validation.warning;
       if (validation.skipped) result.warning = validation.error;

package/plugins/huaweicloud-core/src/update-check.mjs

@@ -7,6 +7,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 import { fetchWithProxy } from './proxy/proxy-agent.mjs';
+import { SUPPORTED_AGENT_TARGETS } from './auth/agent-registration.mjs';
 
 const IS_WINDOWS = process.platform === 'win32';
 const NPM_BIN = IS_WINDOWS ? 'npm.cmd' : 'npm';
@@ -259,6 +260,9 @@ export function queryDistTagsSync({ timeoutMs = 15000, cwd } = {}) {
       timeout: timeoutMs,
       windowsHide: true,
       cwd,
+      // Windows + Node 22: spawning `npm.cmd` directly throws EINVAL (CVE-2024-27980
+      // mitigation); shell:true routes the .cmd through cmd.exe like other spawns (#643).
+      shell: true,
     });
     if (result.status !== 0) {
       debugLog(`queryDistTagsSync: npm view exited with status ${result.status}`);
@@ -278,6 +282,7 @@ export function queryDistTags({ timeoutMs = 15000, cwd } = {}) {
       child = spawn(NPM_BIN, ['view', 'huaweicloud-devkit', 'dist-tags', '--json'], {
         windowsHide: true,
         cwd,
+        shell: true,
       });
     } catch (error) {
       debugLog(`queryDistTags: ${error?.message || error}`);
@@ -401,6 +406,13 @@ export async function upgradePackage({ target = 'all', version = 'latest' } = {}
   if (version !== 'latest') {
     return { success: false, error: 'version 参数仅支持 latest。目标版本由插件自动判定。' };
   }
+  // The target is interpolated into an npx command spawned with shell:true;
+  // reject anything outside the known agent set + 'all' so a crafted value
+  // cannot be interpreted as shell operators (review #717).
+  const targetStr = String(target);
+  if (targetStr !== 'all' && !SUPPORTED_AGENT_TARGETS.includes(targetStr)) {
+    return { success: false, error: `不支持的升级目标：${targetStr}` };
+  }
   const { doQuery = queryDistTags, spawnFn = defaultSpawn } = options;
   // Tests inject currentVersion explicitly - the repo package.json version changes
   // between prerelease and stable lines, which must not flip the upgrade-tag logic.
@@ -431,7 +443,7 @@ export async function upgradePackage({ target = 'all', version = 'latest' } = {}
   const command = ['--yes', `huaweicloud-devkit@${tag}`, 'update', '--target', String(target)];
   let execResult;
   try {
-    execResult = spawnFn(NPX_BIN, command, { encoding: 'utf8', timeout: 300000, windowsHide: true });
+    execResult = spawnFn(NPX_BIN, command, { encoding: 'utf8', timeout: 300000, windowsHide: true, shell: true });
   } catch (error) {
     return {
       success: false,