huaweicloud-devkit 1.1.0-next.7 → 1.1.0-next.9

package/README.md

@@ -8,7 +8,7 @@
 
 Help AI coding agents use Huawei Cloud safely and accurately — a single integration that gives agents cloud knowledge, CLI tooling, and safety guardrails.
 
-Supports OpenCode, CodeArts Agent, WorkBuddy, DeepSeek Harness (DSH), OfficeAce, Hermes, OpenClaw, and AtomCode.
+Supports OpenCode, Codex, CodeArts Agent, WorkBuddy, DeepSeek Harness (DSH), OfficeAce, Hermes, OpenClaw, and AtomCode.
 
 ## Prerequisites
 
@@ -34,6 +34,23 @@ npx --yes huaweicloud-devkit uninstall --target opencode
 rm -rf ~/.npm/_npx/  # Linux/macOS only; Windows path TBD
 ```
 
+### Codex
+
+```bash
+npx --yes huaweicloud-devkit install --target codex
+```
+
+**Restart the Codex session** after installation.
+
+```bash
+npx --yes huaweicloud-devkit doctor --target codex
+npx --yes huaweicloud-devkit status --target codex
+npx --yes huaweicloud-devkit update --target codex
+npx --yes huaweicloud-devkit uninstall --target codex
+```
+
+> **Requires Codex CLI** — the `codex` command must be in PATH. If Codex is installed via WindowsApps (Microsoft Store), use `--target codex-desktop` instead. Run `codex --version` to verify CLI availability.
+
 ### CodeArts Agent
 
 ```bash
@@ -113,7 +130,9 @@ npx --yes huaweicloud-devkit update --target hermes
 npx --yes huaweicloud-devkit uninstall --target hermes
 ```
 
+> **Uninstall notes**: On Linux, run `rm -rf ~/.npm/_npx/* && npm cache clean --force` after uninstall to ensure a clean slate. On Windows, close all Hermes sessions first to release file locks, then after uninstall check `%LOCALAPPDATA%\hermes\config.yaml` for YAML corruption and manually remove `%LOCALAPPDATA%\hermes\huaweicloud-plugins` if any files remain.
 > **Safety hooks**: The installer configures Hermes shell hooks (`config.yaml` → `hooks.pre_tool_call`) to intercept unsafe terminal commands such as credential file reads, environment variable dumps, and unapproved `hcloud` write operations. Hermes shows a consent prompt the first time; approve it or set `hooks_auto_accept: true` in `config.yaml` to auto-accept.
+> **MCP Python SDK**: The installer automatically installs the `mcp` Python package required by Hermes for MCP tool discovery. If you see `[FAIL] Hermes MCP Python SDK` in `doctor`, run `pip3 install mcp` manually.
 > **Windows**: Hermes on Windows stores data under `%LOCALAPPDATA%\hermes` instead of `~/.hermes`. The installer detects this automatically.
 
 ### OpenClaw

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 帮助 AI 编码助手安全、准确地使用华为云——一站式集成云知识、CLI 工具和安全护栏。
 
-支持 OpenCode、码道（CodeArts Agent）、WorkBuddy、DeepSeek Harness（DSH）、OfficeAce、Hermes、OpenClaw、AtomCode。
+支持 OpenCode、Codex、码道（CodeArts Agent）、WorkBuddy、DeepSeek Harness（DSH）、OfficeAce、Hermes、OpenClaw、AtomCode。
 
 ## 前置条件
 
@@ -34,6 +34,23 @@ npx --yes huaweicloud-devkit uninstall --target opencode
 rm -rf ~/.npm/_npx/  # 仅 Linux/macOS；Windows 路径待确认
 ```
 
+### Codex
+
+```bash
+npx --yes huaweicloud-devkit install --target codex
+```
+
+安装后**重启 Codex 会话**。
+
+```bash
+npx --yes huaweicloud-devkit doctor --target codex
+npx --yes huaweicloud-devkit status --target codex
+npx --yes huaweicloud-devkit update --target codex
+npx --yes huaweicloud-devkit uninstall --target codex
+```
+
+> **需要 Codex CLI** — `codex` 命令必须在 PATH 中。若 Codex 通过 WindowsApps（Microsoft Store）安装，请使用 `--target codex-desktop` 替代。运行 `codex --version` 验证 CLI 可用性。
+
 ### CodeArts Agent（码道）
 
 ```bash
@@ -113,7 +130,9 @@ npx --yes huaweicloud-devkit update --target hermes
 npx --yes huaweicloud-devkit uninstall --target hermes
 ```
 
+> **卸载说明**：Linux 上卸载后执行 `rm -rf ~/.npm/_npx/* && npm cache clean --force` 确保下次全新安装。Windows 上先关闭所有 Hermes 会话（释放文件锁），卸载后检查 `%LOCALAPPDATA%\hermes\config.yaml` 是否有 YAML 损坏，如有残留文件手动删除 `%LOCALAPPDATA%\hermes\huaweicloud-plugins`。
 > **安全钩子（Safety hooks）**：安装器会在 `config.yaml` 中写入 shell hooks 配置（`hooks.pre_tool_call`），拦截不安全的终端命令，如读取凭据文件、导出环境变量、未审批的 `hcloud` 写操作。Hermes 首次使用时会弹出同意提示，可批准或设置 `hooks_auto_accept: true` 自动批准。
+> **MCP Python SDK**：安装器会自动安装 Hermes 所需的 `mcp` Python 包。如果 doctor 显示 `[FAIL] Hermes MCP Python SDK`，手动执行 `pip3 install mcp`。
 > **Windows**：Hermes 在 Windows 上数据存储在 `%LOCALAPPDATA%\hermes` 而非 `~/.hermes`，安装器会自动检测适配。
 
 ### OpenClaw

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.0-next.7",
+  "version": "1.1.0-next.9",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",
   "files": [

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.0-next.7",
+  "version": "1.1.0-next.9",
   "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.0-next.7",
+  "version": "1.1.0-next.9",
   "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.0-next.7",
+  "version": "1.1.0-next.9",
   "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.0-next.7",
+  "version": "1.1.0-next.9",
   "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.0-next.7",
+  "version": "1.1.0-next.9",
   "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.0-next.7",
+  "version": "1.1.0-next.9",
   "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-sandbox/SKILL.md

@@ -52,6 +52,8 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 | `huaweicloud_sandbox_exec_one_shot`     | One-shot execution (fresh connection; best for long/heavy commands)         |
 | `huaweicloud_sandbox_upload_file`       | Upload a local file into the sandbox (chunked base64 write + md5 verify)    |
 | `huaweicloud_sandbox_upload_project`    | Upload a local project directory to sandbox (HTTP tunnel, tar.gz + extract) |
+| `huaweicloud_sandbox_deploy_nginx`      | Deploy nginx config with permissions fix and reload in one call             |
+| `huaweicloud_sandbox_deploy_check`      | Run deployment completeness check (nginx, DevBridge, URL, QR if needed)     |
 | `huaweicloud_sandbox_close_session`     | Close a persistent terminal session                                         |
 
 ### Tool Selection Guide
@@ -63,6 +65,8 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 | `curl`, health checks, quick tests | Either — `exec_one_shot` preferred | Stateless, fast                                              |
 | Server startup (background)        | `exec_with_session`                | Need to `nohup ... &` then check output in same session      |
 | Deployment scripts                 | `exec_one_shot+shot`               | Long script, fresh connection avoids session timeouts        |
+| nginx configuration                | `deploy_nginx`                     | Auto-generates correct template + permissions + reload       |
+| Deployment completeness check      | `deploy_check`                     | Verifies nginx, DevBridge, URL, QR before reporting success  |
 | Single file upload (<1MB)          | `upload_file`                      | Base64 chunked, reliable for small files                     |
 | Project directory upload (>1MB)    | `upload_project`                   | HTTP tunnel, much faster than base64 for multi-file projects |
 
@@ -74,6 +78,12 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 **Session recovery**: if `exec_with_session` returns `session is not ready`, the WebSocket connection has dropped. Do NOT retry the same session — fall back to `exec_one_shot` for that command instead. To recover state (cd, env vars), reconstruct them explicitly in the one-shot command.
 
+**Timeout recovery**: if `exec_one_shot` returns a timeout error, check whether partial output is available before declaring failure:
+
+- For build commands: check `tail -30 /tmp/build.log` — the build may have completed but the tee pipe didn't flush before timeout
+- For long scripts: split into independent `exec_one_shot` calls (max 5 sub-commands per call, 15s timeout per call)
+- Do NOT retry the same composite command — split and retry individual steps
+
 ## Workflow
 
 Setup is a **plugin-side preflight** — the developer should be asked a question only once, when the agreement actually needs signing:
@@ -90,14 +100,22 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
 
    ```bash
    # Remove stale nginx configs from previous deployments
-   sudo rm -f /etc/nginx/conf.d/app.conf /etc/nginx/conf.d/*.conf.bak 2>/dev/null
+   sudo rm -f /etc/nginx/conf.d/*.conf /etc/nginx/conf.d/*.conf.bak 2>/dev/null
    # Remove stale DevBridge tunnels
    devbridge delete-all 2>/dev/null || true
    # Reload nginx to apply
    sudo nginx -s reload 2>/dev/null || true
    ```
 
-7. **Inject credentials** (optional): `huaweicloud_sandbox_credentials` — enables cloud API access from sandbox
+7. **Inject credentials** (optional): `huaweicloud_sandbox_credentials` — enables cloud API access from sandbox. After injection, credentials are also written to `/tmp/hw_creds.sh` for shell access:
+
+   ```bash
+   # Source credentials in any sandbox shell before using hcloud/devbridge:
+   source /tmp/hw_creds.sh 2>/dev/null && echo "Credentials loaded"
+   ```
+
+   If `source /tmp/hw_creds.sh` returns empty, the credentials injection may not have completed — re-run `huaweicloud_sandbox_credentials`.
+
 8. **Execute commands**: use `huaweicloud_sandbox_exec_with_session` for interactive work (cd, env setup), or `huaweicloud_sandbox_exec_one_shot` for long-running builds/installs. See [Tool Selection Guide](#tool-selection-guide).
 9. **Upload project** (if deploying local code): `huaweicloud_sandbox_upload_project` to transfer a local project directory into `/workspace/<name>` — uses HTTP tunnel, much faster than base64 for multi-file projects. Use `huaweicloud_sandbox_upload_file` for single files.
 10. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
@@ -184,26 +202,48 @@ fi
 export PATH=$PATH:$HOME/.huawei/bin   # installer only writes ~/.bashrc; session shells do not re-source it
 ```
 
-**Login** (non-interactive, credentials come from the developer's local agent — the vault or HW_ACCESS_KEY/HW_SECRET_KEY; never echo them):
+**Login** (non-interactive; credentials injected by `huaweicloud_sandbox_credentials` are available at `/tmp/hw_creds.sh`):
 
 ```bash
-devbridge auth login --huaweicloud --access-key "$AK" --secret-key "$SK"
+source /tmp/hw_creds.sh 2>/dev/null
+devbridge auth login --huaweicloud --access-key "$HW_ACCESS_KEY" --secret-key "$HW_SECRET_KEY"
 ```
 
 - The `--huaweicloud` flag is required for AK/SK login; without it the CLI tries an interactive browser login, which fails in the sandbox.
-- Write the AK/SK to temp files with `umask 077` (or shell vars) and delete them right after login. Verify with `devbridge auth status`.
+- 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.
 
 **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: remove stale tunnels to avoid quota exceeded
+# 0. Pre-cleanup: kill old processes and stale tunnels
+pkill -f "devbridge host" 2>/dev/null || true
+sleep 2
 devbridge delete-all 2>/dev/null || true
 
 # 1. Start tunnel
 nohup devbridge host -p <port> -e 8 > /tmp/host.log 2>&1 &
 sleep 10 && cat /tmp/host.log
+
+# 2. Extract tunnel URL and health-check before returning
+TUNNEL_URL=$(grep -oP 'Tunnel URL: \K.*' /tmp/host.log)
+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 verified: $TUNNEL_URL (HTTP $HTTP_CODE)"
+else
+  echo "WARN: Tunnel URL unreachable (HTTP $HTTP_CODE). Rebuilding tunnel..."
+  pkill -f "devbridge host" && sleep 2
+  devbridge delete-all 2>/dev/null || true
+  nohup devbridge host -p <port> -e 8 > /tmp/host.log 2>&1 &
+  sleep 10
+  TUNNEL_URL=$(grep -oP 'Tunnel URL: \K.*' /tmp/host.log)
+  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")
+  echo "Retry tunnel: $TUNNEL_URL (HTTP $HTTP_CODE)"
+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.
+
 **Quota recovery**: if the tunnel creation fails with `10006: quota exceeded`:
 
 ```bash
@@ -325,27 +365,24 @@ If nginx cannot be installed, skip to Python HTTP server fallback (see `referenc
 
 #### 3c: Verify remaining tools
 
-Before installing project dependencies, verify the sandbox has the required runtime tools. Run this pre-flight check via `exec_one_shot`:
+Before installing project dependencies, verify the sandbox has the required runtime tools. **Run each check as a separate `exec_one_shot` call with 15s timeout** — do not bundle all checks into one command. A single hung subcommand (e.g., `make --version` or `hugo version`) will timeout the entire check, blocking deployment:
 
-```bash
-# Core tools (expected pre-installed in sandbox image)
-echo "=== Checking core tools ==="
-if command -v node >/dev/null 2>&1; then node --version; else echo "MISSING: node"; fi
-if command -v npm >/dev/null 2>&1; then npm --version; else echo "MISSING: npm"; fi
-if command -v nginx >/dev/null 2>&1; then nginx -v 2>&1; else echo "MISSING: nginx"; fi
-if command -v git >/dev/null 2>&1; then git --version; else echo "MISSING: git"; fi
-if command -v python3 >/dev/null 2>&1; then python3 --version; else echo "MISSING: python3"; fi
-if command -v curl >/dev/null 2>&1; then curl --version | head -1; else echo "MISSING: curl"; fi
-if command -v wget >/dev/null 2>&1; then wget --version | head -1; else echo "MISSING: wget"; fi
-if command -v make >/dev/null 2>&1; then make --version | head -1; else echo "MISSING: make"; fi
-
-# Framework-specific tools (install on demand)
-echo "=== Checking framework tools ==="
-if command -v pnpm >/dev/null 2>&1; then pnpm --version; else echo "MISSING: pnpm"; fi
-if command -v yarn >/dev/null 2>&1; then yarn --version; else echo "MISSING: yarn"; fi
-if command -v hugo >/dev/null 2>&1; then hugo version; else echo "MISSING: hugo"; fi
-if command -v devbridge >/dev/null 2>&1; then devbridge version; else echo "MISSING: devbridge"; fi
 ```
+Check 1: node --version       (timeout: 15s)
+Check 2: npm --version         (timeout: 15s)
+Check 3: nginx -v 2>&1         (timeout: 15s)
+Check 4: git --version         (timeout: 15s)
+Check 5: python3 --version     (timeout: 15s)
+Check 6: curl --version | head -1 (timeout: 15s)
+Check 7: wget --version | head -1 (timeout: 15s)
+Check 8: make --version | head -1 (timeout: 15s)
+Check 9: pnpm --version        (timeout: 15s)
+Check 10: yarn --version       (timeout: 15s)
+Check 11: hugo version         (timeout: 15s)
+Check 12: devbridge version    (timeout: 15s)
+```
+
+For each check, parse the output: if stdout contains `MISSING:` or the tool wasn't found, install it. **Skip framework-specific tools not needed for the current project** (e.g., skip Hugo for React apps).
 
 **Install only missing tools** — parse the pre-flight output and install only tools reported as `MISSING`. Use OS-aware commands:
 
@@ -395,6 +432,18 @@ cd /workspace/<dirname> && [ -d node_modules ] && echo "SKIP: node_modules exist
 
 Wait for install to complete. For large projects on aarch64 sandboxes (1000+ packages), set `timeout_ms` to 180000 (3 min).
 
+**Node version compatibility**: if `npm install` fails with native module errors (e.g., `rollup 4`, `@esbuild`, `node-gyp`), check the Node version:
+
+```bash
+node -v
+```
+
+Node v24+ uses musl-based binaries on some sandbox images, which may break native addons built for glibc. If native modules fail:
+
+- Try `npm install --force` or `npm install --legacy-peer-deps`
+- For rollup 4 projects, consider `npm install rollup@3` as fallback
+- If webpack/rollup native addon errors persist, add `--ignore-scripts` then manually rebuild: `npm rebuild`
+
 #### 4c: Build
 
 **Timeout strategy by framework type:**
@@ -424,6 +473,20 @@ grep -r "outDir\|outputDir\|dest\|distDir" /workspace/<dirname>/.vitepress/confi
 
 If a custom outDir is found, use that instead of the framework-detected default for all subsequent checks.
 
+**Post-build output verification**: after a successful build, verify the actual `index.html` location. Framework-returned `outputDir` may be inaccurate (e.g., uni-app v3 framework: `dist`, actual: `dist/build/h5`):
+
+```bash
+# Find the real index.html after build
+REAL_INDEX=$(find /workspace/<dirname>/<outputDir> -name "index.html" -type f 2>/dev/null | head -1)
+if [ -n "$REAL_INDEX" ] && [ -f "$REAL_INDEX" ]; then
+  REAL_OUTDIR=$(dirname "$REAL_INDEX")
+  echo "Actual output dir: $REAL_OUTDIR"
+  # Use REAL_OUTDIR for nginx config instead of framework-reported outputDir
+fi
+```
+
+If `REAL_OUTDIR` differs from `<outputDir>`, use `REAL_OUTDIR` for all subsequent steps (nginx config, port check, etc.).
+
 **Post-timeout recovery**: if `exec_one_shot` returns a timeout error (Request timed out), do NOT fail immediately. First dump any captured build log, then check the output directory:
 
 ```bash
@@ -468,6 +531,62 @@ tail -5 /tmp/build.log 2>/dev/null
 - For Hugo/static sites where `installCmd` is `null`, skip install entirely.
 - For static sites where `buildCmd` is `null`, skip build entirely.
 
+#### 4c-aux: Build Failure Response
+
+Build failures fall into two categories. Handle them differently:
+
+| Failure Type            | Behavior                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Timeout** (timed out) | Check `/tmp/build.log` tail and output directory — build may have completed but `tee` pipe didn't flush. See Post-timeout recovery above.          |
+| **Non-zero exit code**  | **STOP immediately.** The build engine explicitly rejected the output. Do NOT retry, modify source, or tweak env vars. Follow the procedure below. |
+
+**When a build exits with non-zero exit code:**
+
+1. **STOP** — do NOT retry, do NOT modify source code, do NOT change environment variables
+2. **Extract the error** from `/tmp/build.log`:
+   ```bash
+   tail -30 /tmp/build.log
+   ```
+3. **Present the failure to the developer** with:
+   - The app name and build command that failed
+   - The key error message (last meaningful lines from the build log)
+   - A brief diagnosis of the likely cause
+4. **Offer fix options** (1-3 choices) and **wait for the developer to choose** before applying any fix:
+   - Never modify project source files (configs, scripts, etc.) without explicit approval
+   - If the fix requires editing source code, tell the developer what to change and where
+5. **After the developer selects a fix**, apply it, then restart only the failed build — do NOT rebuild already-succeeded apps
+
+| Rule                   | Rationale                                                      |
+| ---------------------- | -------------------------------------------------------------- |
+| No blind retry         | Retrying without diagnosis wastes time and obscures real error |
+| No silent source edits | Modifying project files without consent destroys trust         |
+| Developer decides fix  | Different projects have different fix preferences              |
+| Only rebuild failed    | Avoid redundant work in monorepo deployments                   |
+
+**Monorepo-specific**: if one sub-app build fails while others succeed, report the failure immediately — do NOT delay until all builds complete. Continue other builds in parallel if possible, but notify the developer as soon as a failure is detected.
+
+#### 4d: Fix Build Output Permissions
+
+After a successful build, fix directory traverse permissions on the build output. Build tools (webpack, vite, uni-app) may create directories with restrictive permissions that block nginx from traversing to `index.html`. **Always resolve symlinks first** — `chmod` does not follow symlinks on Linux:
+
+```bash
+# Fix directory execute permissions for nginx traverse
+REAL_OUTDIR="<outputDir>"   # use actual output dir from post-build verification
+PROJECT_ROOT="/workspace/<dirname>"
+
+# Resolve symlinks — monorepo sub-apps may be symlinked
+REAL_ROOT=$(readlink -f "$PROJECT_ROOT" 2>/dev/null || echo "$PROJECT_ROOT")
+REL_OUTDIR=$(echo "$REAL_OUTDIR" | sed "s|$PROJECT_ROOT/||")
+REAL_OUTDIR="${REAL_ROOT}/${REL_OUTDIR}"
+
+# Fix permissions on resolved real paths
+find "$REAL_ROOT" -path "*/${REAL_OUTDIR}" -prune -o -type d -exec chmod o+x {} \; 2>/dev/null || true
+chmod -R o+rX "$REAL_ROOT" 2>/dev/null || true
+chmod -R +x "$REAL_ROOT/node_modules/.bin" 2>/dev/null || true
+```
+
+This prevents the most common deployment failure: nginx 500 with `stat() ... Permission denied` caused by missing `o+x` on intermediate directories.
+
 ### Step 5: Port Availability Check
 
 **Before configuring nginx or starting the app**, verify the target ports are free. Port conflicts from previous deployments cause silent failures:
@@ -518,17 +637,33 @@ If the port cannot be freed (different user/process), increment to the next avai
 
 #### Configure Nginx
 
-Check `references/nginx-templates.md` for the correct template based on `nginxType`:
+Use `huaweicloud_sandbox_deploy_nginx` to write the correct template, fix directory permissions, and reload nginx — all in one call:
+
+```json
+{
+  "nginx_type": "<nginxType>",
+  "port": <port>,
+  "project": "<dirname>",
+  "output_dir": "<outputDir>",
+  "node_port": <nodePort>,
+  "public_port": <publicPort>
+}
+```
+
+- `nginx_type` — `spa` (SPA/SSG/cross-platform), `proxy` (SSR), or `static` (Hugo/Hexo) from `detect_framework`
+- `port` — listen port from framework detection
+- `project` — project dir name under `/workspace`
+- `output_dir` — build output dir relative to `/workspace/<project>`
+- `node_port` — Node.js app port (required only when `nginx_type=proxy`)
+- `public_port` — public listen port for SSR proxy (optional, defaults to `port`)
 
-| nginxType | Template                | When                        |
-| --------- | ----------------------- | --------------------------- |
-| `spa`     | Template 1 (try_files)  | SPA, SSG, cross-platform H5 |
-| `proxy`   | Template 2 (proxy_pass) | SSR (Next.js, Nuxt)         |
-| `static`  | Template 3 (plain root) | Hugo, Hexo, static sites    |
+The tool automatically handles:
 
-Replace `<port>`, `<project>`, `<outputDir>` (and `<nodePort>`/`<publicPort>` for SSR) with detected values.
+- Writing the correct nginx template (SPA try_files, SSR reverse proxy, or static)
+- Fixing `o+x` directory traverse permissions on the project path
+- Reloading nginx
 
-Write the config with `sudo tee`, then reload nginx. If nginx fails, fall back to Python HTTP server (see `references/nginx-templates.md`).
+If the tool returns `ok: false`, nginx may not be installed — fall back to Python HTTP server (see `references/nginx-templates.md`).
 
 **Verify nginx is serving** — curl-check the app before proceeding to DevBridge:
 
@@ -538,18 +673,18 @@ curl -s -o /dev/null -w "nginx status: %{http_code}\n" http://localhost:<port>
 
 If the status code is not 2xx/3xx:
 
-- **403** — likely file permissions: run `chmod -R o+rX /workspace/<project>/<outputDir>` and re-test
+- **403** — run `chmod -R o+rX /workspace/<project>/<outputDir>` and re-test
 - **000 (connection refused)** — nginx not listening: check `sudo nginx -t` for config errors
 - **Other** — check nginx error log: `sudo tail -20 /var/log/nginx/error.log`
 
 > If `curl` is unavailable, check port via `lsof -i :<port>` or `netstat -tlnp | grep :<port>`
 
-### Step 6: Start the App
+### Step 6: Start the App [REQUIRED]
 
 - **Static (SPA/SSG/cross-platform)**: nginx is already serving. Skip.
 - **SSR**: run `<serveCmd>` via `exec_with_session` to start the Node process in background.
 
-### Step 7: Expose via DevBridge
+### Step 7: Expose via DevBridge [REQUIRED — deployment incomplete without this]
 
 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.
 
@@ -557,29 +692,64 @@ Use `exec_with_session` to background DevBridge. For SSR, DevBridge tunnels the
 
 **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 ls --all`, delete stale ones, and retry.
 
-### Step 8: Return URL
+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 and return it to the developer.
+#### Cross-platform H5 QR code
 
-**For cross-platform H5 apps** (Taro, uni-app), also generate a QR code for mobile scanning:
+**If `detect_framework` returned `type: "cross-platform"` (Taro, uni-app)**, after exposing the tunnel, generate a QR code for mobile scanning:
 
 ```bash
 TUNNEL_URL="<extracted-tunnel-url>"
 
-# Method 1 (preferred): PNG via curl API (works on all terminals)
-curl -s "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$TUNNEL_URL")" -o /workspace/qr.png
-chmod o+r /workspace/qr.png
-echo "QR code saved. Scan QR to access on mobile."
+# Generate QR inside nginx-served output directory so it is accessible via the tunnel URL
+curl -s "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$TUNNEL_URL")" -o /workspace/<dirname>/<outputDir>/qr.png
+chmod o+r /workspace/<dirname>/<outputDir>/qr.png
+echo "QR code URL: ${TUNNEL_URL}/qr.png"
 echo "Desktop URL: $TUNNEL_URL"
+```
+
+**Do NOT use `qrencode -t ANSI256`** — terminal ANSI/ASCII QR codes have low precision and phone cameras cannot scan them. Also, never save the QR image outside the nginx root (e.g., `/workspace/qr.png`) — it must be inside the output directory so it is served by nginx alongside the app.
 
-# Method 2 (fallback): terminal ANSI QR (requires qrencode, may not render on all terminals)
-# apt-get install -y qrencode || yum install -y qrencode
-# qrencode -t ANSI256 -m 1 -s 2 "$TUNNEL_URL"
+**After generating the QR code**, return both URLs to the developer:
+
+```
+桌面访问: <tunnel-url>
+手机扫码: <tunnel-url>/qr.png
 ```
 
-If the sandbox cannot reach `api.qrserver.com`, fall back to installing `qrencode` for terminal QR output. Always `chmod o+r` the generated QR image file.
+#### Deployment Completion Check [REQUIRED]
+
+**Before reporting success, call `huaweicloud_sandbox_deploy_check`** to verify the deployment is complete:
+
+```json
+{
+  "port": <port>,
+  "project": "<dirname>",
+  "output_dir": "<outputDir>",
+  "framework_type": "<type>"
+}
+```
+
+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
+- **qr_code** (cross-platform only) — QR image exists in output dir
+
+Returns `complete: true/false`, `score`, and `nextStep` to fix missing items.
+
+**If `complete` is false, follow `nextStep` to resolve before reporting success.** Do not return a deployment URL until `complete: true`.
+
+| Framework Type              | Must Return               |
+| --------------------------- | ------------------------- |
+| `cross-platform`            | Desktop URL + QR code URL |
+| `spa` / `ssg` / `static`    | Desktop URL               |
+| `ssr`                       | Desktop URL               |
+| `monorepo` (cross-platform) | Desktop URL + QR code URL |
 
-Return both the QR code and the URL to the developer. For cross-platform apps, mention: "手机扫描二维码即可访问".
+**If the framework is cross-platform and the QR code was not generated, the deployment is incomplete — go back and generate it before reporting success.**
 
 ## References
 
@@ -597,6 +767,8 @@ Return both the QR code and the URL to the developer. For cross-platform apps, m
 | 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).                                                                            |
 | Destructive commands blocked         | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy                                                                                                                                                                    |
@@ -607,6 +779,8 @@ Return both the QR code and the URL to the developer. For cross-platform apps, m
 | 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.                             |
 
 ## Node.js in the sandbox
 

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

@@ -299,15 +299,34 @@ async function createTarGz(localDir, exclude = []) {
   mkdirSync(archiveDir, { recursive: true });
   const archivePath = join(archiveDir, archiveName);
 
-  const args = [
-    ...exclude.flatMap((p) => ['--exclude', p]),
-    '-czf',
-    archivePath,
-    '-C',
-    dirname(localDir),
-    basename(localDir),
-  ];
-  await execFileAsync('tar', args);
+  const hasGit = existsSync(join(localDir, '.git'));
+  if (hasGit) {
+    await execFileAsync('git', [
+      '-C',
+      localDir,
+      'archive',
+      '--format=tar.gz',
+      `--prefix=${basename(localDir)}/`,
+      `--output=${archivePath}`,
+      'HEAD',
+    ]);
+  } else {
+    const args = [];
+    for (const pattern of exclude) {
+      if (pattern.startsWith('**/')) {
+        const base = pattern.slice(3);
+        for (let depth = 0; depth <= 4; depth++) {
+          const prefix = depth === 0 ? '' : '*/'.repeat(depth);
+          args.push('--exclude', `${prefix}${base}`);
+        }
+      } else {
+        args.push('--exclude', pattern);
+      }
+    }
+    args.push('-czf', archivePath, '-C', dirname(localDir), basename(localDir));
+    await execFileAsync('tar', args);
+  }
+
   return archivePath;
 }
 
@@ -637,6 +656,22 @@ export async function uploadProjectWithSession(
       username,
       timeoutMs,
     );
+    try {
+      await execWithSession(
+        workspaceId,
+        [
+          `REAL_PATH=$(readlink -f "${targetParentDir}/${projectName}" 2>/dev/null || echo "${targetParentDir}/${projectName}")`,
+          `if [ ! -d "$REAL_PATH" ] && [ -d "${targetParentDir}" ]; then`,
+          `  REAL_PATH="${targetParentDir}/${projectName}"`,
+          `fi`,
+          `chmod -R o+rX "$REAL_PATH" 2>/dev/null || true`,
+          `find "$REAL_PATH" -type d -exec chmod o+x {} \\; 2>/dev/null || true`,
+          `find "$REAL_PATH" -type f -path "*/node_modules/.bin/*" -exec chmod +x {} \\; 2>/dev/null || true`,
+        ].join('\n'),
+        username,
+        15000,
+      );
+    } catch {}
   }
 
   try {
@@ -655,6 +690,236 @@ export async function uploadProjectWithSession(
   };
 }
 
+export async function deployNginx(
+  workspaceId,
+  { nginxType, port, project, outputDir, nodePort, publicPort, configName },
+  username = 'root',
+  timeoutMs = 30000,
+) {
+  if (!workspaceId) {
+    throw new Error('sandbox deploy nginx: workspace_id is required.');
+  }
+  if (!nginxType || !port || !project || !outputDir) {
+    throw new Error('sandbox deploy nginx: nginxType, port, project, and outputDir are required.');
+  }
+
+  const projectPath = `/workspace/${project}`;
+  const outputPath = outputDir.startsWith('/') ? outputDir : `${projectPath}/${outputDir}`;
+
+  const resolveScript = `REAL_PROJECT=$(readlink -f "${projectPath}" 2>/dev/null || echo "${projectPath}")
+REAL_OUTPUT="${outputPath}"
+if [ "\${REAL_PROJECT}" != "${projectPath}" ]; then
+  REL_OUTPUT=$(echo "${outputDir}" | sed "s|${projectPath}/||")
+  REAL_OUTPUT="\${REAL_PROJECT}/\${REL_OUTPUT}"
+fi`;
+
+  const templates = {
+    spa: `server {
+    listen ${port};
+    root ${outputPath};
+    index index.html;
+
+    location / {
+        try_files $uri /index.html;
+    }
+
+    location ~* \\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1h;
+        add_header Cache-Control "public, immutable";
+    }
+}`,
+    proxy: `server {
+    listen ${publicPort || port};
+    server_name _;
+
+    location / {
+        proxy_pass http://127.0.0.1:${nodePort};
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        proxy_read_timeout 60s;
+    }
+}`,
+    static: `server {
+    listen ${port};
+    root ${outputPath};
+    index index.html;
+
+    location / {
+        autoindex off;
+    }
+
+    location ~* \\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1h;
+        add_header Cache-Control "public, immutable";
+    }
+}`,
+  };
+
+  const config = templates[nginxType];
+  if (!config) {
+    throw new Error(`sandbox deploy nginx: unknown nginxType "${nginxType}". Must be one of: spa, proxy, static`);
+  }
+
+  const cmd = [
+    resolveScript,
+    `sudo mkdir -p /etc/nginx/conf.d`,
+    `sudo tee /etc/nginx/conf.d/${configName || 'app'}.conf > /dev/null << 'NGINX_EOF'`,
+    config,
+    `NGINX_EOF`,
+    `# Resolve symlinks for chmod (chmod does not follow symlinks on Linux)`,
+    `chmod -R o+rX "$REAL_PROJECT" 2>/dev/null || true`,
+    `find "$REAL_PROJECT" -type d -exec chmod o+x {} \\; 2>/dev/null || true`,
+    `find "$REAL_PROJECT" -type f -path "*/node_modules/.bin/*" -exec chmod +x {} \\; 2>/dev/null || true`,
+    `if pgrep -x nginx > /dev/null 2>&1; then sudo nginx -s reload 2>/dev/null; else sudo nginx; fi`,
+  ].join('\n');
+
+  const result = await execOneShot(workspaceId, cmd, username, timeoutMs);
+
+  let tunnelActive = false;
+  try {
+    const tunnelCheck = await execOneShot(
+      workspaceId,
+      'devbridge ls 2>/dev/null | grep -q "Tunnel URL" && echo "ACTIVE" || echo "INACTIVE"',
+      username,
+      10000,
+    );
+    tunnelActive = String(tunnelCheck.stdout || '').includes('ACTIVE');
+  } catch {}
+
+  return {
+    ok: result.exitCode === 0,
+    nginxType,
+    port: nginxType === 'proxy' ? publicPort || port : port,
+    outputPath,
+    projectPath,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    nextStep: 'expose_via_devbridge',
+    warning: !tunnelActive
+      ? 'No active DevBridge tunnel — deployment is incomplete. Proceed to Step 7 to expose the app.'
+      : undefined,
+  };
+}
+
+export async function deployCheck(
+  workspaceId,
+  { port, project, outputDir, frameworkType },
+  username = 'root',
+  timeoutMs = 30000,
+) {
+  if (!workspaceId) {
+    throw new Error('sandbox deploy check: workspace_id is required.');
+  }
+
+  const projectPath = `/workspace/${project}`;
+  const outputPath = outputDir.startsWith('/') ? outputDir : `${projectPath}/${outputDir}`;
+  const isCrossPlatform = frameworkType === 'cross-platform';
+
+  const checkScript = [
+    `echo "=== DEPLOY CHECK ==="`,
+    `PASS=0`,
+    `TOTAL=0`,
+    ``,
+    `TOTAL=$((TOTAL+1))`,
+    `if curl -s -o /dev/null -w "%{http_code}" http://localhost:${port} 2>/dev/null | grep -qE "^(2|3)"; then`,
+    `  echo "nginx_serving:PASS (port ${port})"`,
+    `  PASS=$((PASS+1))`,
+    `else`,
+    `  echo "nginx_serving:FAIL"`,
+    `fi`,
+    ``,
+    `TOTAL=$((TOTAL+1))`,
+    `if [ -d "${outputPath}" ] && ls -A "${outputPath}" 2>/dev/null | grep -q .; then`,
+    `  echo "output_dir:PASS (${outputPath})"`,
+    `  PASS=$((PASS+1))`,
+    `else`,
+    `  echo "output_dir:FAIL (${outputPath} empty or missing)"`,
+    `fi`,
+    ``,
+    `TOTAL=$((TOTAL+1))`,
+    `if devbridge ls 2>/dev/null | grep -q "Tunnel URL"; then`,
+    `  echo "devbridge_tunnel:PASS"`,
+    `  PASS=$((PASS+1))`,
+    `else`,
+    `  echo "devbridge_tunnel:FAIL"`,
+    `fi`,
+    ``,
+    `TOTAL=$((TOTAL+1))`,
+    `TUNNEL_URL=$(devbridge ls 2>/dev/null | grep -oP "Tunnel URL: \\Khttps://[^ ]+")`,
+    `if [ -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`,
+    `else`,
+    `  echo "tunnel_url_accessible:FAIL (no tunnel URL)"`,
+    `fi`,
+    ``,
+    `${
+      isCrossPlatform
+        ? `
+TOTAL=$((TOTAL+1))
+if [ -f "${outputPath}/qr.png" ]; then
+  echo "qr_code:PASS"
+  PASS=$((PASS+1))
+else
+  echo "qr_code:FAIL (cross-platform app missing QR code)"
+fi
+`
+        : ''
+    }`,
+    `echo "SCORE:\${PASS}/\${TOTAL}"`,
+    `[ "\${PASS}" = "\${TOTAL}" ] && echo "VERDICT:COMPLETE" || echo "VERDICT:INCOMPLETE"`,
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  const result = await execOneShot(workspaceId, checkScript, username, timeoutMs);
+  const stdout = String(result.stdout || '');
+  const checks = {};
+  const lines = stdout.split('\n');
+  for (const line of lines) {
+    const m = line.match(/^(\w+):(PASS|FAIL)\b(.*)/);
+    if (m) checks[m[1]] = { status: m[2], detail: (m[3] || '').trim() };
+  }
+  const scoreMatch = stdout.match(/SCORE:(\d+)\/(\d+)/);
+  const complete = /VERDICT:COMPLETE/.test(stdout);
+
+  const missing = [];
+  if (!complete) {
+    for (const [key, val] of Object.entries(checks)) {
+      if (val.status === 'FAIL') missing.push(key);
+    }
+  }
+
+  return {
+    ok: true,
+    complete,
+    checkType: isCrossPlatform ? 'cross-platform' : 'standard',
+    checks,
+    score: scoreMatch ? { pass: parseInt(scoreMatch[1], 10), total: parseInt(scoreMatch[2], 10) } : null,
+    missingSteps: missing.length > 0 ? missing.join(', ') : 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'
+            : 'review_checks'
+      : 'complete',
+  };
+}
+
 export async function closeSession(workspaceId, username) {
   const key = `${workspaceId}:${username}`;
   const session = sessions.get(key);

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

@@ -2098,6 +2098,41 @@ function removeHermesHooksConfigBlock() {
   console.log('  Hooks config cleaned');
 }
 
+function ensureHermesMcpSdk() {
+  const pythonBin = process.platform === 'win32' ? 'python' : 'python3';
+  try {
+    const r = spawnSync(pythonBin, ['-c', 'import mcp; print("ok")'], { encoding: 'utf8', timeout: 5000 });
+    if (r.status === 0 && r.stdout.trim() === 'ok') {
+      console.log('  MCP Python SDK: \x1b[32mAlready installed\x1b[0m');
+      return true;
+    }
+  } catch {}
+  console.log('  Installing Hermes MCP Python SDK...');
+  try {
+    const pip = spawnSync(pythonBin, ['-m', 'pip', 'install', 'mcp', '--quiet'], { encoding: 'utf8', timeout: 60000 });
+    if (pip.status === 0) {
+      console.log('  MCP Python SDK: \x1b[32mInstalled\x1b[0m');
+      return true;
+    }
+    console.log(`  MCP Python SDK: \x1b[33mInstall failed\x1b[0m`);
+    console.log(`  \x1b[33m  Run manually: ${pythonBin} -m pip install mcp\x1b[0m`);
+  } catch (error) {
+    console.log(`  MCP Python SDK: \x1b[33m${error.message}\x1b[0m`);
+    console.log(`  \x1b[33m  Run manually: ${pythonBin} -m pip install mcp\x1b[0m`);
+  }
+  return false;
+}
+
+function hermesMcpSdkOk() {
+  const pythonBin = process.platform === 'win32' ? 'python' : 'python3';
+  try {
+    const r = spawnSync(pythonBin, ['-c', 'import mcp; print("ok")'], { encoding: 'utf8', timeout: 5000 });
+    return r.status === 0 && r.stdout.trim() === 'ok';
+  } catch {
+    return false;
+  }
+}
+
 async function installHermes() {
   const skillsSrc = join(PLUGIN_ROOT, 'skills');
   const srcDir = join(PLUGIN_ROOT, 'src');
@@ -2121,6 +2156,7 @@ async function installHermes() {
   if (!skipMcp) ensureHermesMcpConfig();
   ensureHermesHooksConfig();
   if (!skipMcp) installRuntimeDeps(pluginDest);
+  if (!skipMcp) ensureHermesMcpSdk();
 }
 
 async function updateHermes() {
@@ -2141,6 +2177,7 @@ async function updateHermes() {
   console.log(`  Safety Hooks updated -> ${join(pluginDest, 'hooks')}`);
   ensureHermesMcpConfig();
   ensureHermesHooksConfig();
+  ensureHermesMcpSdk();
   mkdirSync(pluginDest, { recursive: true });
   writeFileSync(join(pluginDest, '.installed'), new Date().toISOString());
   installRuntimeDeps(pluginDest);
@@ -2184,6 +2221,7 @@ function hermesStatus() {
   console.log(
     `  Safety Hooks: ${existsSync(join(pluginDir, 'hooks', 'huaweicloud-safety.py')) ? '\x1b[32mInstalled\x1b[0m' : '\x1b[31mNot installed\x1b[0m'}`,
   );
+  console.log(`  MCP Python SDK: ${hermesMcpSdkOk() ? '\x1b[32mReady\x1b[0m' : '\x1b[31mMissing\x1b[0m'}`);
   let skillCount = 0;
   if (existsSync(skillsDir)) {
     skillCount = readdirSync(skillsDir, { withFileTypes: true }).filter(
@@ -2766,6 +2804,14 @@ async function cmdDoctor() {
     mcpCfgTarget ? `Found in ${mcpCfgTarget} config` : 'Run: npx huaweicloud-devkit install',
   );
 
+  // Hermes MCP Python SDK (only checked when Hermes config is found)
+  if (
+    mcpCfgTarget === 'Hermes Agent' ||
+    (existsSync(hermesConfigFile()) && readFileSync(hermesConfigFile(), 'utf8').includes('mcp_servers'))
+  ) {
+    check('Hermes MCP Python SDK', hermesMcpSdkOk(), 'Run: pip3 install mcp');
+  }
+
   // hcloud CLI
   const hcloudBin = findHcloudBin() || process.env.HCLOUD_BIN || 'hcloud';
   const hcloudCheck = spawnSync(`"${hcloudBin}" version`, [], {

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

@@ -16,6 +16,8 @@ import {
   closeSession,
   uploadFileWithSession,
   uploadProjectWithSession,
+  deployNginx,
+  deployCheck,
   getCurrentWorkspaceId,
   setWorkspaceId,
 } from './sandbox/session-manager.mjs';
@@ -27,6 +29,7 @@ import {
   hdkitVoucherStatus,
   hdkitVoucherClaim,
 } from './sandbox/hdkitservice-api.mjs';
+import { getCredentials } from './sandbox/hwlink-api.mjs';
 import { getAuthStatus, syncAuth } from './auth/service.mjs';
 import {
   readGlobalCredentials,
@@ -586,6 +589,72 @@ 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.',
+    inputSchema: {
+      type: 'object',
+      required: ['nginx_type', 'port', 'project', 'output_dir'],
+      properties: {
+        nginx_type: {
+          type: 'string',
+          description:
+            'Nginx config type from framework detection: spa (try_files fallback for SPA/SSG/cross-platform), proxy (reverse proxy for SSR), or static (plain root for Hugo/Hexo).',
+          enum: ['spa', 'proxy', 'static'],
+        },
+        port: { type: 'number', description: 'Listen port (from framework detection).' },
+        project: { type: 'string', description: 'Project directory name under /workspace, e.g. movie-ticket.' },
+        output_dir: {
+          type: 'string',
+          description: 'Build output directory relative to /workspace/<project>, e.g. dist/build/h5.',
+        },
+        node_port: { type: 'number', description: 'Node.js app port for SSR (required when nginx_type=proxy).' },
+        public_port: { type: 'number', description: 'Public listen port for SSR proxy (optional, defaults to port).' },
+        config_name: {
+          type: 'string',
+          description:
+            'Config file name (without .conf suffix). Defaults to app. Use distinct names (e.g. admin, docs) for multi-app deployments to avoid config overwrites.',
+        },
+        workspace_id: {
+          type: 'string',
+          description:
+            'Workspace ID from huaweicloud_sandbox_connect return value. Required - must be passed explicitly when HW_WORKSPACE_ID is not set.',
+        },
+        username: { type: 'string', description: 'Login username (default: root)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 30000)' },
+      },
+    },
+  },
+  {
+    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.',
+    inputSchema: {
+      type: 'object',
+      required: ['port', 'project', 'output_dir'],
+      properties: {
+        port: { type: 'number', description: 'App listen port (from framework detection).' },
+        project: { type: 'string', description: 'Project directory name under /workspace.' },
+        output_dir: {
+          type: 'string',
+          description: 'Build output directory relative to /workspace/<project>, e.g. dist/build/h5.',
+        },
+        framework_type: {
+          type: 'string',
+          description: 'Framework type from detect_framework. Set to cross-platform for QR code check.',
+          enum: ['spa', 'ssr', 'ssg', 'cross-platform', 'monorepo', 'static'],
+        },
+        workspace_id: {
+          type: 'string',
+          description:
+            'Workspace ID from huaweicloud_sandbox_connect return value. Required - must be passed explicitly when HW_WORKSPACE_ID is not set.',
+        },
+        username: { type: 'string', description: 'Login username (default: root)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 30000)' },
+      },
+    },
+  },
   {
     name: 'huaweicloud_sandbox_check_user',
     description:
@@ -824,6 +893,59 @@ export async function callTool(name, args = {}) {
         },
       );
     }
+    case 'huaweicloud_sandbox_deploy_nginx': {
+      if (!args.nginx_type || !args.port || !args.project || !args.output_dir) {
+        throw new Error('nginx_type, port, project, and output_dir are required.');
+      }
+      const sandboxWsId7 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId7) {
+        throw new Error(
+          'workspace_id is required. No sandbox connected — call huaweicloud_sandbox_connect first, ' +
+            'or set HW_WORKSPACE_ID environment variable before starting the agent.',
+        );
+      }
+      const sandboxUser7 = args.username || 'root';
+      const sandboxTimeout7 = args.timeout_ms || 30000;
+      return await deployNginx(
+        sandboxWsId7,
+        {
+          nginxType: args.nginx_type,
+          port: args.port,
+          project: args.project,
+          outputDir: args.output_dir,
+          nodePort: args.node_port,
+          publicPort: args.public_port,
+          configName: args.config_name,
+        },
+        sandboxUser7,
+        sandboxTimeout7,
+      );
+    }
+    case 'huaweicloud_sandbox_deploy_check': {
+      if (!args.port || !args.project || !args.output_dir) {
+        throw new Error('port, project, and output_dir are required.');
+      }
+      const sandboxWsId8 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId8) {
+        throw new Error(
+          'workspace_id is required. No sandbox connected — call huaweicloud_sandbox_connect first, ' +
+            'or set HW_WORKSPACE_ID environment variable before starting the agent.',
+        );
+      }
+      const sandboxUser8 = args.username || 'root';
+      const sandboxTimeout8 = args.timeout_ms || 30000;
+      return await deployCheck(
+        sandboxWsId8,
+        {
+          port: args.port,
+          project: args.project,
+          outputDir: args.output_dir,
+          frameworkType: args.framework_type,
+        },
+        sandboxUser8,
+        sandboxTimeout8,
+      );
+    }
     case 'huaweicloud_sandbox_check_user':
       return await hdkitCheckUser();
     case 'huaweicloud_sandbox_sign_agreement':
@@ -833,11 +955,37 @@ export async function callTool(name, args = {}) {
       const devStageId = connectResult?.dev_stage_id || connectResult?.devStageId;
       if (devStageId) {
         setWorkspaceId(devStageId);
+        try {
+          await execOneShot(devStageId, 'devbridge delete-all 2>/dev/null || true', 'root', 15000);
+        } catch {}
       }
       return connectResult;
     }
-    case 'huaweicloud_sandbox_credentials':
-      return await hdkitCredentials(args.session_id, args.dev_stage_id, args.enable_sts !== false);
+    case 'huaweicloud_sandbox_credentials': {
+      const credResult = await hdkitCredentials(args.session_id, args.dev_stage_id, args.enable_sts !== false);
+      const sandboxWsIdCred = args.dev_stage_id || getCurrentWorkspaceId();
+      if (sandboxWsIdCred) {
+        try {
+          const { ak, sk, securitytoken } = getCredentials();
+          const credsScript = [
+            `export HW_ACCESS_KEY='${ak}'`,
+            `export HW_SECRET_KEY='${sk}'`,
+            securitytoken ? `export HW_SECURITY_TOKEN='${securitytoken}'` : '',
+            securitytoken ? `export X_HW_SECURITY_TOKEN='${securitytoken}'` : '',
+          ]
+            .filter(Boolean)
+            .join('\n');
+          const credsFile = '/tmp/hw_creds.sh';
+          await execOneShot(
+            sandboxWsIdCred,
+            `cat > ${credsFile} << 'HWCREDS_EOF'\n${credsScript}\nHWCREDS_EOF\nchmod 600 ${credsFile}`,
+            'root',
+            15000,
+          );
+        } catch {}
+      }
+      return credResult;
+    }
     case 'huaweicloud_voucher_status':
       return await hdkitVoucherStatus(args.domain_id);
     case 'huaweicloud_voucher_claim':