huaweicloud-devkit 1.1.0-next.4 → 1.1.0-next.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.0-next.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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.4",
+  "version": "1.1.0-next.6",
   "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

@@ -102,14 +102,27 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
   "local_dir": "/path/to/local/project",
   "remote_dir": "/workspace",
   "extract": true,
-  "exclude": ["node_modules", ".git", "__pycache__"]
+  "exclude": [
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".turbo",
+    ".cache",
+    ".swc",
+    "dist",
+    "coverage",
+    "*.pyc"
+  ]
 }
 ```
 
 - `local_dir` (required): local project directory
 - `remote_dir` (optional, default `/workspace`): parent directory on sandbox
 - `extract` (optional, default `true`): extract tar.gz after upload
-- `exclude` (optional): patterns to exclude from archive
+- `exclude` (optional): patterns to exclude from archive. **For web apps, always exclude dependency directories** (`node_modules`, `.next`, `.nuxt`, `.output`, `.turbo`, `.cache`) — these will be re-installed/built in the sandbox.
 - Result includes `md5` and `md5Verified` for integrity check
 
 ### upload_file (for single files)
@@ -170,11 +183,28 @@ devbridge auth login --huaweicloud --access-key "$AK" --secret-key "$SK"
 **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
-cd /workspace/<repo-name> && nohup python3 -m http.server 8080 > /tmp/http.log 2>&1 &
-nohup devbridge host -p 8080 -e 8 > /tmp/host.log 2>&1 &
+# 0. Pre-cleanup: remove stale tunnels to avoid quota exceeded
+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
 ```
 
+**Quota recovery**: if the tunnel creation fails with `10006: quota exceeded`:
+
+```bash
+# Step A: List all tunnels (both active and stale)
+devbridge ls --all
+# Step B: Remove all stale tunnels
+devbridge delete-all
+# Step C: Retry tunnel creation
+nohup devbridge host -p <port> -e 8 > /tmp/host.log 2>&1 &
+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).
 - **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).
 - Internal docs: https://huaweicloud.github.io/devspace-devbridge/
@@ -208,14 +238,80 @@ Follow the standard [Workflow](#workflow) steps 1-6 to connect to the sandbox, t
 ```json
 {
   "local_dir": "<projectPath>",
-  "remote_dir": "/workspace"
+  "remote_dir": "/workspace",
+  "exclude": [
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".turbo",
+    ".cache",
+    ".swc",
+    "dist",
+    "coverage",
+    "*.pyc"
+  ]
 }
 ```
 
-The project will be extracted to `/workspace/<dirname>/`.
+**Always exclude build artifacts and dependency directories** — they will be re-installed/built inside the sandbox:
+
+| Pattern        | Why excluded                                   |
+| -------------- | ---------------------------------------------- |
+| `node_modules` | Dependencies — reinstall in sandbox            |
+| `.git`         | Version control — not needed for deployment    |
+| `__pycache__`  | Python bytecode cache                          |
+| `.next`        | Next.js build output — rebuild in sandbox      |
+| `.nuxt`        | Nuxt build cache — rebuild in sandbox          |
+| `.output`      | Nuxt production output — rebuild in sandbox    |
+| `.turbo`       | Turborepo cache — re-run in sandbox            |
+| `.cache`       | Generic tool cache (Parcel, Storybook, etc.)   |
+| `.swc`         | Taro/Webpack SWC cache — regenerate in sandbox |
+| `dist`         | Build output — rebuild in sandbox              |
+| `coverage`     | Test coverage reports — not needed for deploy  |
+| `*.pyc`        | Python compiled files                          |
+
+**Post-upload permission fix**: after `upload_project` extracts the project, fix file permissions lost during transfer (native binaries from other platforms, .bin symlinks):
+
+```bash
+# Fix executable permissions on node_modules/.bin (lost during cross-platform transfer)
+chmod -R +x /workspace/<dirname>/node_modules/.bin 2>/dev/null || true
+# Fix world-read on all files (sandbox default umask may restrict)
+chmod -R o+rX /workspace/<dirname> 2>/dev/null || true
+```
 
 ### Step 3: Sandbox Environment Readiness
 
+Install OS-level dependencies **before** uploading the project (independent of project code, can run in parallel if desired).
+
+#### 3a: Detect OS and package manager
+
+```bash
+source /etc/os-release 2>/dev/null
+echo "OS_DETECTED=${ID:-unknown}|${ID_LIKE:-}"
+if command -v apt-get >/dev/null 2>&1; then echo "PKG_MGR=apt"; elif command -v yum >/dev/null 2>&1; then echo "PKG_MGR=yum"; elif command -v dnf >/dev/null 2>&1; then echo "PKG_MGR=dnf"; elif command -v apk >/dev/null 2>&1; then echo "PKG_MGR=apk"; else echo "PKG_MGR=unknown"; fi
+```
+
+Use the detected `PKG_MGR` for all package installations below.
+
+#### 3b: Install nginx (before project upload)
+
+```bash
+# Use the detected PKG_MGR from step 3a
+case "$PKG_MGR" in
+  apt) sudo apt-get update -qq && sudo apt-get install -y -qq nginx ;;
+  yum) sudo yum install -y nginx ;;
+  dnf) sudo dnf install -y nginx ;;
+esac
+sudo nginx -t && echo "nginx: ready"
+```
+
+If nginx cannot be installed, skip to Python HTTP server fallback (see `references/nginx-templates.md`).
+
+#### 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`:
 
 ```bash
@@ -228,7 +324,6 @@ if command -v git >/dev/null 2>&1; then git --version; else echo "MISSING: git";
 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 dpkg -l build-essential >/dev/null 2>&1; then echo "build-essential: found"; else echo "MISSING: build-essential"; 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)
@@ -239,41 +334,113 @@ if command -v hugo >/dev/null 2>&1; then hugo version; else echo "MISSING: hugo"
 if command -v devbridge >/dev/null 2>&1; then devbridge version; else echo "MISSING: devbridge"; fi
 ```
 
-**Install only missing tools** — parse the pre-flight output and install only tools reported as `MISSING`. Skip tools already present:
+**Install only missing tools** — parse the pre-flight output and install only tools reported as `MISSING`. Use OS-aware commands:
 
-| Missing Tool    | Install Command                                                                                                                                                                                                       |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Node.js         | Follow [Node.js in the sandbox](#nodejs-in-the-sandbox)                                                                                                                                                               |
-| nginx           | `sudo apt-get update -qq && sudo apt-get install -y -qq nginx`                                                                                                                                                        |
-| curl            | `sudo apt-get update -qq && sudo apt-get install -y -qq curl`                                                                                                                                                         |
-| wget            | `sudo apt-get update -qq && sudo apt-get install -y -qq wget`                                                                                                                                                         |
-| build-essential | `sudo apt-get update -qq && sudo apt-get install -y -qq build-essential`                                                                                                                                              |
-| make            | `sudo apt-get update -qq && sudo apt-get install -y -qq make`                                                                                                                                                         |
-| pnpm            | `npm i -g pnpm`                                                                                                                                                                                                       |
-| yarn            | `npm i -g yarn`                                                                                                                                                                                                       |
-| 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` |
-| DevBridge       | `curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh \| bash && export PATH=$PATH:$HOME/.huawei/bin`                                                                                           |
-
-**If nginx cannot be installed**, skip to Python HTTP server fallback (see `references/nginx-templates.md`).
+| Missing Tool | Install Command (apt)                                                                                                                                                                                                 | Install Command (yum/dnf)   |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Node.js      | Follow [Node.js in the sandbox](#nodejs-in-the-sandbox)                                                                                                                                                               | Same                        |
+| nginx        | `sudo apt-get update -qq && sudo apt-get install -y -qq nginx`                                                                                                                                                        | `sudo yum install -y nginx` |
+| curl         | `sudo apt-get update -qq && sudo apt-get install -y -qq curl`                                                                                                                                                         | `sudo yum install -y curl`  |
+| wget         | `sudo apt-get update -qq && sudo apt-get install -y -qq wget`                                                                                                                                                         | `sudo yum install -y wget`  |
+| make         | `sudo apt-get update -qq && sudo apt-get install -y -qq make`                                                                                                                                                         | `sudo yum install -y make`  |
+| 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                        |
 
 **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.
 
 ### Step 4: Install and Build
 
-Use `exec_one_shot` for the build pipeline (long-running, more stable).
+#### 4a: Inject Environment Variables
+
+Before any project commands, parse `.env*` files and inject them into the shell environment. Prisma, Drizzle, and other ORM/database tools do NOT auto-read framework-level env files:
 
-**Install dependencies** — skip if `node_modules` already exists:
+```bash
+cd /workspace/<dirname>
+# Load env files if present (most specific first)
+for f in .env.local .env.development.local .env.development .env; do
+  if [ -f "$f" ]; then
+    set -a && source "$f" 2>/dev/null; set +a
+    echo "Loaded env: $f"
+  fi
+done
+# Verify key variables for common tools
+echo "DATABASE_URL=${DATABASE_URL:-<NOT SET>}"
+echo "NODE_ENV=${NODE_ENV:-development}"
+```
+
+This must run via `exec_with_session` so the exported variables persist for subsequent build commands in the same session.
+
+#### 4b: Install Dependencies
+
+Use `exec_one_shot` for install (no shared state needed). Skip if `node_modules` already exists:
 
 ```bash
 cd /workspace/<dirname> && [ -d node_modules ] && echo "SKIP: node_modules exists" || <installCmd>
 ```
 
-Wait for install to complete, then:
+Wait for install to complete. For large projects on aarch64 sandboxes (1000+ packages), set `timeout_ms` to 180000 (3 min).
+
+#### 4c: Build
+
+**Timeout strategy by framework type:**
+
+| Type                           | timeout_ms      | Rationale                             |
+| ------------------------------ | --------------- | ------------------------------------- |
+| SPA / SSG                      | 300000 (5 min)  | Vite/Webpack builds typically < 3 min |
+| Cross-platform (Taro, uni-app) | 900000 (15 min) | Webpack5 H5 slow on aarch64, 7-8 min  |
+| SSR (Next.js, Nuxt)            | 600000 (10 min) | Full-stack compilation + SSG pages    |
+| Monorepo                       | 600000 (10 min) | Multiple apps, shared packages        |
+| `null` (no build)              | N/A             | Skip                                  |
 
-**Build** — only if build output doesn't already exist:
+**Build with `exec_one_shot`:**
 
 ```bash
-cd /workspace/<dirname> && [ -d <outputDir> ] && echo "SKIP: <outputDir> exists" || (umask 022 && <buildCmd>)
+cd /workspace/<dirname> && [ -d <outputDir> ] && echo "SKIP: <outputDir> exists" || (umask 022 && <buildCmd> 2>&1 | tee /tmp/build.log)
+```
+
+Always pipe build output through `tee /tmp/build.log` — captures stderr+stdout so diagnostics are available even if the command times out.
+
+**OutDir verification**: before building for the first time, check the project's actual output directory (not just the default from framework detection). Projects can override outDir in config (e.g., VitePress `outDir: '../dist'`):
+
+```bash
+# Check for custom outDir in common config files
+grep -r "outDir\|outputDir\|dest\|distDir" /workspace/<dirname>/.vitepress/config.* 2>/dev/null || true
+```
+
+If a custom outDir is found, use that instead of the framework-detected default for all subsequent checks.
+
+**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
+# If timeout occurred, show captured output and verify build
+if timeout_error; then
+  echo "=== Build log (tail) ==="
+  tail -30 /tmp/build.log 2>/dev/null
+  echo "=== Checking output ==="
+  if [ -d <outputDir> ] && [ "$(ls -A <outputDir> 2>/dev/null)" ]; then
+    echo "Build output detected despite timeout — continuing with deployment"
+  else
+    echo "ERROR: Build did not complete. Output directory empty or missing."
+    echo "Full log: /tmp/build.log"
+    exit 1
+  fi
+fi
+```
+
+For SSR frameworks, also verify the server entry point exists: `test -f <outputDir>/server.js || test -f node_modules/next/dist/server/next-server.js`.
+
+**Build progress visibility**: for very large builds, touch a marker file before starting and use `exec_with_session` to poll intermediate logs:
+
+```bash
+# Before build:
+touch /tmp/build-start && echo "Build started at $(date)"
+
+# During build via exec_with_session (separate call for polling):
+cat .next/trace 2>/dev/null | tail -5  # Next.js build trace
+# or
+tail -5 /tmp/build.log 2>/dev/null
 ```
 
 - `cd /workspace/<dirname>/<subAppPath>` for Monorepo sub-apps.
@@ -281,11 +448,55 @@ cd /workspace/<dirname> && [ -d <outputDir> ] && echo "SKIP: <outputDir> exists"
 - For Hugo/static sites where `installCmd` is `null`, skip install entirely.
 - For static sites where `buildCmd` is `null`, skip build entirely.
 
-**Real-time logging**: each `exec_one_shot` call returns stdout. Show build progress to the developer as it arrives.
+### 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:
+
+```bash
+# Check ports from framework detection
+check_port() {
+  PORT=$1
+  # Prefer lsof (most portable), fallback to netstat, then ss
+  if command -v lsof >/dev/null 2>&1; then
+    PID=$(lsof -ti :$PORT 2>/dev/null)
+    if [ -n "$PID" ]; then
+      echo "PORT_IN_USE:$PORT (PID=$PID)"
+      kill -9 $PID 2>/dev/null && echo "Killed PID $PID on port $PORT"
+    else
+      echo "PORT_FREE:$PORT"
+    fi
+  elif command -v netstat >/dev/null 2>&1; then
+    PID=$(netstat -tlnp 2>/dev/null | grep ":$PORT " | awk '{print $NF}' | sed 's|/.*||')
+    if [ -n "$PID" ] && [ "$PID" != "-" ]; then
+      echo "PORT_IN_USE:$PORT (PID=$PID)"
+      kill -9 $PID 2>/dev/null && echo "Killed PID $PID on port $PORT"
+    else
+      echo "PORT_FREE:$PORT"
+    fi
+  else
+    # Last resort: ss (iproute2)
+    PID=$(ss -tlnp 2>/dev/null | grep ":$PORT " | sed -n 's/.*pid=\([0-9]*\).*/\1/p' | head -1)
+    if [ -n "$PID" ]; then
+      echo "PORT_IN_USE:$PORT (PID=$PID)"
+      kill -9 $PID 2>/dev/null && echo "Killed PID $PID on port $PORT"
+    else
+      echo "PORT_FREE:$PORT"
+    fi
+  fi
+}
+check_port <port>
+# For SSR, also check the Node port
+check_port <nodePort>
+```
+
+| Scenario               | Port                                 | Action if occupied                     |
+| ---------------------- | ------------------------------------ | -------------------------------------- |
+| SPA/SSG/Cross-platform | nginx port (from `framework.detect`) | Kill old process, then configure nginx |
+| SSR                    | nginx public port + Node app port    | Kill old processes on both ports       |
 
-**Timeout**: for large projects, set `timeout_ms` to 300000 (5 min) or higher.
+If the port cannot be freed (different user/process), increment to the next available port: `<port>+1`, update all subsequent nginx config and DevBridge references accordingly.
 
-### Step 5: Configure Nginx
+#### Configure Nginx
 
 Check `references/nginx-templates.md` for the correct template based on `nginxType`:
 
@@ -311,7 +522,7 @@ If the status code is not 2xx/3xx:
 - **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 listening via `/proc`: `cat /proc/net/tcp | awk '{print $2}' | grep -q "$(printf '%04X' <port>)" && echo "port <port> listening" || echo "port <port> NOT listening"`
+> If `curl` is unavailable, check port via `lsof -i :<port>` or `netstat -tlnp | grep :<port>`
 
 ### Step 6: Start the App
 
@@ -324,9 +535,31 @@ Follow the standard [Expose the deployed app](#expose-the-deployed-app-public-ur
 
 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 ls --all`, delete stale ones, and retry.
+
 ### Step 8: Return URL
 
-Extract the tunnel URL from DevBridge output and return it to the developer. For cross-platform H5 apps, also mention QR code scanning on mobile.
+Extract the tunnel URL from DevBridge output and return it to the developer.
+
+**For cross-platform H5 apps** (Taro, uni-app), also 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."
+echo "Desktop URL: $TUNNEL_URL"
+
+# 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"
+```
+
+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.
+
+Return both the QR code and the URL to the developer. For cross-platform apps, mention: "手机扫描二维码即可访问".
 
 ## References
 
@@ -335,23 +568,25 @@ Extract the tunnel URL from DevBridge output and return it to the developer. For
 
 ## Critical Warnings
 
-| Trap                                 | Why                                                                                                                                                                                                          |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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                                                                                                                            |
-| 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                                                                                                                                         |
-| 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")                                               |
+| Trap                                 | Why                                                                                                                                                                                                                                     |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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                                                                                                                                                       |
+| 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                                                                                                                                                                    |
+| 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. |
 
 ## Node.js in the sandbox
 

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

@@ -0,0 +1,52 @@
+---
+name: huawei-voucher
+description: '查询和领取华为云激励代金券（一人一次）。当用户询问插件能力、首次使用，或提到"领券/代金券/优惠券/激励金/领取"等话题时，先查询领取状态：未领取（claimed=false）则主动提示可领取，已领取（claimed=true）则不打扰。Triggers: voucher, coupon, incentive, 领券, 代金券, 优惠券, 激励金, 领取. NOT for: 账单/费用查询（用 huawei-billing）。'
+version: 1
+---
+
+# 华为云激励代金券
+
+## 主动提示准则（核心）
+
+此能力仅在用户尚未领取时才有价值，需避免已领取用户被反复打扰：
+
+1. 当用户**询问插件能力 / 首次使用 / 提到福利领取类话题**时，先调用 `huaweicloud_voucher_status` 查询领取状态。
+2. 若 `claimed=false` → 主动告知"可领取华为云代金券（一人一次）"，并询问是否现在领取。
+3. 若 `claimed=true` → 静默处理，不再提及代金券，不打扰用户。
+
+## 流程
+
+### 1. 查询状态
+
+调用 `huaweicloud_voucher_status`（生产环境无需 `domain_id`，测试环境需传 `domain_id`）。
+
+返回 `{ claimed, message }`：
+
+- `claimed=true` + `message="已领取"` → 已领取，告知结果即可，不再引导
+- `claimed=false` + `message="未领取"` → 未领取，可引导领取
+
+### 2. 领取代金券
+
+调用 `huaweicloud_voucher_claim`（生产环境无需 `domain_id`）。
+
+返回 `{ claimed, voucherId, amount, message }`。
+
+### 3. 结果解读（错误码 UX）
+
+| 返回 message 关键特征                        | 含义                        | 对用户表述           |
+| -------------------------------------------- | --------------------------- | -------------------- |
+| `领取成功`                                   | 发券成功                    | 告知券已到账         |
+| `已领取过` / `已领取`                        | 该账号已领过                | 告知已领取，不打扰   |
+| `本月代金券总额度已用完，所有账号均无法领取` | 全局额度用尽（HD.60630042） | 告知下月再试         |
+| `请先完成实名认证`                           | 账号未实名（HD.60630022）   | 引导去控制台实名认证 |
+| `发券失败: <原文>`                           | 其他错误                    | 原样转达，不展开     |
+
+## 环境注意
+
+- 生产环境：`voucher_status` / `voucher_claim` 无需传 `domain_id`，后端从 IAM 自动解析账号。
+- 测试环境：需传 `domain_id`（华为云账号 ID）；未传时返回 `测试环境需提供 domain_id`，此时可用 `hcloud IAM KeystoneListAuthDomains` 查询账号 ID 后补传。
+
+## 注意事项
+
+- 每个账号（domain_id）仅可领取一次，重复调用返回已领取。
+- 领取结果以激励服务返回为准，不要凭本地认知猜测。

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

@@ -43,6 +43,7 @@ Do not rely on training data for facts. Huawei Cloud services, pricing, quotas,
 | troubleshoot  | Troubleshooting Routing | error, bug, failed, AccessDenied, quota                                              | Handoff to huaweicloud-troubleshooting                                                                                                                                                   |
 | api-sdk       | API/SDK Routing         | API call, SDK, REST, integration, code example                                       | Handoff to huaweicloud-api-and-sdk                                                                                                                                                       |
 | report-issue  | Issue Reporting         | wrong service, you picked wrong, incorrect                                           | Read references/report-issue.md                                                                                                                                                          |
+| voucher       | Voucher Routing         | 领券, 代金券, 优惠券, 激励金, 领取, voucher, coupon, incentive                       | Handoff to huawei-voucher                                                                                                                                                                |
 
 ## Service Map
 
@@ -70,6 +71,7 @@ Do not rely on training data for facts. Huawei Cloud services, pricing, quotas,
 | CI/CD pipeline                                   | CloudDeploy          | huawei-deployment        |
 | Temporary runtime / web app preview              | Sandbox (DevStation) | huawei-sandbox           |
 | Getting started                                  | Account setup        | huaweicloud-cli-and-auth |
+| Incentive voucher                                | Voucher              | huawei-voucher           |
 
 **Web app scenario layering**: for "deploy a web app", prefer `huawei-sandbox` for free/quick try (hello world, prototype, demo, temporary preview — temporary runtime + public URL, ~8h validity, zero billed resources); route to `huawei-functiongraph` / `huawei-ecs` (or `huawei-cce`) for production / long-term / custom-domain / high-availability hosting.
 

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

@@ -155,7 +155,9 @@ export async function execWithSession(workspaceId, command, username, timeoutMs)
 
 export const UPLOAD_CHUNK_SIZE = 30000;
 
-export const UPLOAD_BATCH_SIZE = 5;
+export const UPLOAD_BATCH_SIZE = 2;
+
+export const UPLOAD_MAX_RETRIES = 3;
 
 export function splitBase64Chunks(base64, chunkSize = UPLOAD_CHUNK_SIZE) {
   const chunks = [];
@@ -189,11 +191,21 @@ export async function uploadFileWithSession(workspaceId, localPath, remotePath,
     const batchNum = Math.floor(batchStart / UPLOAD_BATCH_SIZE) + 1;
     const totalBatches = Math.ceil(chunks.length / UPLOAD_BATCH_SIZE);
     const cmd = `printf '%s' '${combinedChunk}' >> "${tmp}"`;
-    const res = await execWithSession(workspaceId, cmd, username, timeoutMs);
-    if (res.exitCode !== 0) {
-      throw new Error(
-        `sandbox upload: failed writing batch ${batchNum}/${totalBatches}: ${res.stdout || res.error || res.exitCode}`,
-      );
+
+    let batchOk = false;
+    let lastError;
+    for (let retry = 0; retry < UPLOAD_MAX_RETRIES; retry++) {
+      const res = await execWithSession(workspaceId, cmd, username, timeoutMs);
+      if (res.exitCode === 0) {
+        batchOk = true;
+        break;
+      }
+      lastError = res.stdout || res.error || res.exitCode;
+      console.error(`  upload retry ${retry + 1}/${UPLOAD_MAX_RETRIES} for batch ${batchNum}/${totalBatches}`);
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+    if (!batchOk) {
+      throw new Error(`sandbox upload: failed writing batch ${batchNum}/${totalBatches}: ${lastError}`);
     }
     if (batchNum % 10 === 0 || batchNum === totalBatches) {
       console.error(`  upload progress: batch ${batchNum}/${totalBatches}`);
@@ -556,14 +568,25 @@ export async function uploadProjectWithSession(
   uploadLog(`uploadProject: ${localDir} -> ${archiveRemotePath} (archive=${archiveSize} bytes, md5=${expectedMd5})`);
 
   let result;
-  try {
-    result = await uploadViaHttpTunnel(workspaceId, archivePath, archiveRemotePath, username, timeoutMs, options);
-  } catch (tunnelError) {
-    uploadLog(`uploadProject: HTTP tunnel upload failed: ${tunnelError.message}`);
+  let tunnelError;
+  for (let attempt = 0; attempt < UPLOAD_MAX_RETRIES; attempt++) {
+    try {
+      await cleanupFileServer(workspaceId, username).catch(() => {});
+      result = await uploadViaHttpTunnel(workspaceId, archivePath, archiveRemotePath, username, timeoutMs, options);
+      tunnelError = null;
+      break;
+    } catch (error) {
+      tunnelError = error;
+      uploadLog(`uploadProject: attempt ${attempt + 1}/${UPLOAD_MAX_RETRIES} failed: ${error.message}`);
+      await new Promise((r) => setTimeout(r, 5000));
+    }
+  }
+  if (tunnelError) {
+    uploadLog(`uploadProject: all ${UPLOAD_MAX_RETRIES} attempts failed: ${tunnelError.message}`);
     uploadLog(`uploadProject: NOT falling back to base64 (removed). Rethrowing with diagnostics.`);
     cleanupLocalArchive(archivePath);
     throw new Error(
-      `sandbox upload failed: HTTP tunnel could not transfer the project archive. ` +
+      `sandbox upload failed after ${UPLOAD_MAX_RETRIES} attempts: HTTP tunnel could not transfer the project archive. ` +
         `Archive size: ${(archiveSize / 1024).toFixed(1)}KB. ` +
         `Root cause: ${tunnelError.message}. ` +
         `Diagnostic log: ${UPLOAD_LOG_PATH}`,

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

@@ -648,21 +648,27 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_voucher_status',
-    description: '查询激励金代金券领取状态。',
+    description: '查询代金券领取状态。',
     inputSchema: {
       type: 'object',
       properties: {
-        domain_id: { type: 'string' },
+        domain_id: {
+          type: 'string',
+          description: 'Optional. Leave empty in production — account is resolved from IAM automatically.',
+        },
       },
     },
   },
   {
     name: 'huaweicloud_voucher_claim',
-    description: '领取激励金代金券。领取前会自动检查是否已领取。',
+    description: '领取代金券（一人一次）。重复领取会返回已领取。',
     inputSchema: {
       type: 'object',
       properties: {
-        domain_id: { type: 'string' },
+        domain_id: {
+          type: 'string',
+          description: 'Optional. Leave empty in production — account is resolved from IAM automatically.',
+        },
       },
     },
   },
@@ -1184,6 +1190,11 @@ function serviceCatalog(intent = '') {
       skills: ['huawei-dds-dcs'],
       services: ['DDS', 'DCS'],
     },
+    {
+      keywords: ['voucher', 'coupon', 'incentive', 'credit', '领券', '代金券', '优惠券', '激励金', '领取'],
+      skills: ['huawei-voucher'],
+      services: ['Incentive Voucher'],
+    },
   ];
   const matched = [];
   const tokens = new Set(it.split(/[\s,./-]+/).filter((t) => t.length > 0));