huaweicloud-devkit 1.1.0-next.3 → 1.1.0-next.5

package/package.json

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

@@ -221,24 +221,22 @@ Before installing project dependencies, verify the sandbox has the required runt
 ```bash
 # Core tools (expected pre-installed in sandbox image)
 echo "=== Checking core tools ==="
-command -v node && node --version || echo "MISSING: node"
-command -v npm && npm --version || echo "MISSING: npm"
-command -v nginx && nginx -v 2>&1 || echo "MISSING: nginx"
-command -v git && git --version || echo "MISSING: git"
-command -v python3 && python3 --version || echo "MISSING: python3"
-command -v curl && curl --version | head -1 || echo "MISSING: curl"
-command -v wget && wget --version | head -1 || echo "MISSING: wget"
-dpkg -l build-essential >/dev/null 2>&1 && echo "build-essential: found" || echo "MISSING: build-essential"
-command -v lsof && lsof -v 2>&1 | head -1 || echo "MISSING: lsof"
-command -v netstat && netstat --version 2>&1 | head -1 || echo "MISSING: net-tools"
-command -v make && make --version | head -1 || echo "MISSING: make"
+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 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)
 echo "=== Checking framework tools ==="
-command -v pnpm && pnpm --version || echo "MISSING: pnpm"
-command -v yarn && yarn --version || echo "MISSING: yarn"
-command -v hugo && hugo version || echo "MISSING: hugo"
-command -v devbridge && devbridge version || echo "MISSING: devbridge"
+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
 ```
 
 **Install only missing tools** — parse the pre-flight output and install only tools reported as `MISSING`. Skip tools already present:
@@ -250,8 +248,6 @@ command -v devbridge && devbridge version || echo "MISSING: devbridge"
 | 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`                                                                                                                                              |
-| lsof            | `sudo apt-get update -qq && sudo apt-get install -y -qq lsof`                                                                                                                                                         |
-| net-tools       | `sudo apt-get update -qq && sudo apt-get install -y -qq net-tools`                                                                                                                                                    |
 | make            | `sudo apt-get update -qq && sudo apt-get install -y -qq make`                                                                                                                                                         |
 | pnpm            | `npm i -g pnpm`                                                                                                                                                                                                       |
 | yarn            | `npm i -g yarn`                                                                                                                                                                                                       |
@@ -277,7 +273,7 @@ Wait for install to complete, then:
 **Build** — only if build output doesn't already exist:
 
 ```bash
-cd /workspace/<dirname> && [ -d <outputDir> ] && echo "SKIP: <outputDir> exists" || <buildCmd>
+cd /workspace/<dirname> && [ -d <outputDir> ] && echo "SKIP: <outputDir> exists" || (umask 022 && <buildCmd>)
 ```
 
 - `cd /workspace/<dirname>/<subAppPath>` for Monorepo sub-apps.
@@ -303,6 +299,20 @@ Replace `<port>`, `<project>`, `<outputDir>` (and `<nodePort>`/`<publicPort>` fo
 
 Write the config with `sudo tee`, then reload nginx. If nginx fails, fall back to Python HTTP server (see `references/nginx-templates.md`).
 
+**Verify nginx is serving** — curl-check the app before proceeding to DevBridge:
+
+```bash
+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
+- **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"`
+
 ### Step 6: Start the App
 
 - **Static (SPA/SSG/cross-platform)**: nginx is already serving. Skip.
@@ -325,23 +335,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-sandbox/references/framework-commands.md

@@ -50,7 +50,6 @@ These tools should be available in the sandbox image. Verify with the pre-flight
 | curl            | 8.x         | Tool downloads, health checks |
 | build-essential | -           | Native module compilation     |
 | pnpm            | 10.x        | Monorepo / workspace installs |
-| lsof            | 4.95.x      | Port conflict detection       |
 
 ### Install on Demand
 

package/plugins/huaweicloud-core/skills/huawei-sandbox/references/nginx-templates.md

@@ -6,7 +6,7 @@ Nginx is the primary serving mechanism for web apps deployed to the sandbox. Pyt
 
 ```bash
 sudo apt-get update -qq && sudo apt-get install -y -qq nginx 2>/dev/null || true
-sudo mkdir -p /etc/nginx/sites-enabled
+sudo mkdir -p /etc/nginx/conf.d
 ```
 
 ## Template 1: SPA (with try_files fallback)
@@ -14,7 +14,7 @@ sudo mkdir -p /etc/nginx/sites-enabled
 Use for: Vite, CRA, Vue CLI, Angular, VitePress, Docusaurus, Taro H5, uni-app H5
 
 ```bash
-sudo tee /etc/nginx/sites-enabled/app.conf > /dev/null << 'NGINX_EOF'
+sudo tee /etc/nginx/conf.d/app.conf > /dev/null << 'NGINX_EOF'
 server {
     listen <port>;
     root /workspace/<project>/<outputDir>;
@@ -38,7 +38,7 @@ sudo nginx -s reload 2>/dev/null || sudo nginx
 Use for: Next.js, Nuxt
 
 ```bash
-sudo tee /etc/nginx/sites-enabled/app.conf > /dev/null << 'NGINX_EOF'
+sudo tee /etc/nginx/conf.d/app.conf > /dev/null << 'NGINX_EOF'
 server {
     listen <publicPort>;
     server_name _;
@@ -65,7 +65,7 @@ sudo nginx -s reload 2>/dev/null || sudo nginx
 Use for: Hugo, Hexo, plain static HTML
 
 ```bash
-sudo tee /etc/nginx/sites-enabled/app.conf > /dev/null << 'NGINX_EOF'
+sudo tee /etc/nginx/conf.d/app.conf > /dev/null << 'NGINX_EOF'
 server {
     listen <port>;
     root /workspace/<project>/<outputDir>;

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: 'Query the Huawei Cloud incentive voucher claim status.',
     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: 'Claim the Huawei Cloud incentive voucher. Automatically checks if already claimed.',
     inputSchema: {
       type: 'object',
       properties: {
-        domain_id: { type: 'string' },
+        domain_id: {
+          type: 'string',
+          description: 'Optional. Leave empty in production — account is resolved from IAM automatically.',
+        },
       },
     },
   },