huaweicloud-devkit 1.0.3-dev.0 → 1.1.0-next.0

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

@@ -1,15 +1,31 @@
-import { planHcloudCommand, runHcloud } from './hcloud-cli.mjs';
-import { classifyTextCommand, redactSecrets } from './safety-policy.mjs';
-import { evaluateArtifacts, evaluateCommandRisk, evaluateDeployPlan } from './risk-rule-engine.mjs';
-import { readFileSync, readdirSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+import { evaluateArtifacts, evaluateCommandRisk, evaluateDeployPlan } from './risk-rule-engine.mjs';
+import { classifyTextCommand, redactSecrets } from './safety-policy.mjs';
+import { planHcloudCommand, runHcloud } from './hcloud-cli.mjs';
 import { searchMarketplace } from './search-market.mjs';
-import { execWithSession, closeSession, DEFAULT_WORKSPACE_ID } from './sandbox/session-manager.mjs';
+import { getServiceIcon } from './icon-library.mjs';
+import {
+  execWithSession,
+  execOneShot,
+  closeSession,
+  uploadFileWithSession,
+  uploadProjectWithSession,
+  getCurrentWorkspaceId,
+  setWorkspaceId,
+} from './sandbox/session-manager.mjs';
 import { hdkitCheckUser, hdkitSignAgreement, hdkitConnect, hdkitCredentials } from './sandbox/hdkitservice-api.mjs';
 import { getAuthStatus, syncAuth } from './auth/service.mjs';
-import { readGlobalCredentials, writeObsConfig as writeObsConfigFile } from './auth/credentials.mjs';
+import {
+  readGlobalCredentials,
+  writeObsConfig as writeObsConfigFile,
+  setRuntimeCredentials,
+  clearRuntimeCredentials,
+} from './auth/credentials.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_ROOT_DEV = join(__dirname, '..', 'skills');
@@ -25,12 +41,86 @@ function workbuddySkillsDir() {
   const home = homedir();
   return join(home, '.workbuddy', 'skills');
 }
+function dshSkillsDir() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh');
+  return join(home, 'skills');
+}
+function readOfficeaceRegistryInstallDir() {
+  if (process.platform !== 'win32') return null;
+  try {
+    const r = spawnSync('reg', ['query', 'HKCU\\SOFTWARE\\OfficeAce\\OfficeAce', '/v', 'InstallDir'], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 5000,
+    });
+    if (r.status === 0) {
+      const m = r.stdout.match(/InstallDir\s+REG_SZ\s+(.+)/);
+      if (m) return m[1].trim();
+    }
+  } catch {}
+  return null;
+}
+
+function officeaceSkillsRoot() {
+  const configRoot = process.env.OFFICE_CLAW_CONFIG_ROOT;
+  if (configRoot && existsSync(join(configRoot, 'capabilities.json'))) return join(configRoot, 'skills');
+  const regDir = readOfficeaceRegistryInstallDir();
+  if (regDir) {
+    const dir = join(regDir, '.office-claw', 'skills');
+    if (existsSync(dir)) return dir;
+  }
+  if (process.platform === 'win32') {
+    const bases = [process.env.ProgramFiles, 'C:\\Program Files', 'D:\\Program Files'];
+    if (process.env.LOCALAPPDATA) bases.push(join(process.env.LOCALAPPDATA, 'Programs'));
+    for (const base of bases) {
+      if (!base) continue;
+      const dir = join(base, 'OfficeAce', '.office-claw', 'skills');
+      if (existsSync(dir)) return dir;
+    }
+  }
+  return null;
+}
+
+function hermesSkillsDir() {
+  if (process.env.HERMES_HOME) return join(process.env.HERMES_HOME, 'skills');
+  // Hermes on Windows stores under LOCALAPPDATA, not ~/.hermes
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    return join(process.env.LOCALAPPDATA, 'hermes', 'skills');
+  }
+  const home = homedir();
+  return join(home, '.hermes', 'skills');
+}
+
+export function listSkillDirs(root) {
+  if (!existsSync(root)) return [];
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((d) => (d.isDirectory() || d.isSymbolicLink()) && existsSync(join(root, d.name, 'SKILL.md')))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+export function findSkillsRoot(candidates) {
+  for (const dir of candidates) {
+    if (listSkillDirs(dir).length > 0) return dir;
+  }
+  return null;
+}
+
 function resolveSkillsRoot() {
-  if (existsSync(SKILLS_ROOT_DEV)) return SKILLS_ROOT_DEV;
-  if (existsSync(codeartsSkillsDir())) return codeartsSkillsDir();
-  if (existsSync(opencodeSkillsDir())) return opencodeSkillsDir();
-  if (existsSync(workbuddySkillsDir())) return workbuddySkillsDir();
-  return SKILLS_ROOT_DEV;
+  return (
+    findSkillsRoot([
+      SKILLS_ROOT_DEV,
+      dshSkillsDir(),
+      codeartsSkillsDir(),
+      opencodeSkillsDir(),
+      workbuddySkillsDir(),
+      officeaceSkillsRoot(),
+      hermesSkillsDir(),
+    ]) || SKILLS_ROOT_DEV
+  );
 }
 const SKILLS_ROOT = resolveSkillsRoot();
 
@@ -90,7 +180,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_list_operations',
-    description: 'List KooCLI operations for a Huawei Cloud service by running local/read-only hcloud <Service> --help.',
+    description:
+      'List KooCLI operations for a Huawei Cloud service by running local/read-only hcloud <Service> --help.',
     inputSchema: {
       type: 'object',
       required: ['service'],
@@ -108,7 +199,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_run_approved_command',
-    description: 'Run a write-capable hcloud command only after the exact command has been shown and explicitly approved by the user.',
+    description:
+      'Run a write-capable hcloud command only after the exact command has been shown and explicitly approved by the user.',
     inputSchema: {
       type: 'object',
       required: ['args', 'approvedCommand', 'approvedByUser'],
@@ -188,7 +280,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_hook_check_deploy_plan',
-    description: 'Check a structured or textual deployment plan for Huawei Cloud sandbox, exposure, IAM, and cost risks.',
+    description:
+      'Check a structured or textual deployment plan for Huawei Cloud sandbox, exposure, IAM, and cost risks.',
     inputSchema: {
       type: 'object',
       required: ['plan'],
@@ -227,19 +320,24 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_search_docs',
-    description: 'Search across Huawei Cloud SKILL.md files and local documentation. Returns top 10 relevant results with source, name, snippet, and relevance score. Use when the agent needs to discover which skill covers a topic, or when uncertain about API parameters, quotas, or limitations.',
+    description:
+      'Search across Huawei Cloud SKILL.md files and local documentation. Returns top 10 relevant results with source, name, snippet, and relevance score. Use when the agent needs to discover which skill covers a topic, or when uncertain about API parameters, quotas, or limitations.',
     inputSchema: {
       type: 'object',
       required: ['query'],
       properties: {
         query: { type: 'string', description: 'Search query across skill descriptions and documentation.' },
-        topic: { type: 'string', description: 'Optional filter: all | ecs | obs | vpc | iam | rds | cce | modelarts | dew. Defaults to all.' },
+        topic: {
+          type: 'string',
+          description: 'Optional filter: all | ecs | obs | vpc | iam | rds | cce | modelarts | dew. Defaults to all.',
+        },
       },
     },
   },
   {
     name: 'huaweicloud_retrieve_skill',
-    description: 'Retrieve a full SKILL.md by skill name. Returns the complete skill content plus list of reference files. Use when the agent has identified which skill to load and needs the full procedure.',
+    description:
+      'Retrieve a full SKILL.md by skill name. Returns the complete skill content plus list of reference files. Use when the agent has identified which skill to load and needs the full procedure.',
     inputSchema: {
       type: 'object',
       required: ['name'],
@@ -250,7 +348,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_list_regions',
-    description: 'List available Huawei Cloud regions. Returns region IDs, display names, and endpoints. Use when the agent needs to discover available regions before creating resources.',
+    description:
+      'List available Huawei Cloud regions. Returns region IDs, display names, and endpoints. Use when the agent needs to discover available regions before creating resources.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -258,30 +357,58 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_get_regional_availability',
-    description: 'Check if a specific Huawei Cloud service is available in a target region. Use before creating resources to prevent failures from regional unavailability.',
+    description:
+      'Check if a specific Huawei Cloud service is available in a target region. Use before creating resources to prevent failures from regional unavailability.',
     inputSchema: {
       type: 'object',
       required: ['service', 'region'],
       properties: {
-        service: { type: 'string', description: 'Service name: ecs, obs, rds, gaussdb, cce, modelarts, functiongraph, etc.' },
+        service: {
+          type: 'string',
+          description: 'Service name: ecs, obs, rds, gaussdb, cce, modelarts, functiongraph, etc.',
+        },
         region: { type: 'string', description: 'Region ID: cn-south-1, cn-north-4, ap-southeast-3, etc.' },
       },
     },
   },
   {
     name: 'huaweicloud_search_marketplace',
-    description: 'Search the Huawei Cloud agent skill marketplace for available skills. Returns scored results with names, categories, and descriptions. Use when built-in skills are insufficient or the user asks what skills exist.',
+    description:
+      'Search the Huawei Cloud agent skill marketplace for available skills. Returns scored results with names, categories, and descriptions. Use when built-in skills are insufficient or the user asks what skills exist.',
     inputSchema: {
       type: 'object',
       properties: {
         query: { type: 'string', description: 'Search query across skill name, description, triggers, and service.' },
-        category: { type: 'string', description: 'Optional category filter: computing, storage, network, security, devtools, monitoring, etc.' },
+        category: {
+          type: 'string',
+          description: 'Optional category filter: computing, storage, network, security, devtools, monitoring, etc.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_get_service_icon',
+    description:
+      'Find the official Huawei Cloud service logo from the Huawei Cloud Icons library (open.huaweicloud.com/openplatform/icons.html). Returns top 5 matches with CDN logo URLs, local paths, category, aliases, and product page links. Provide service (e.g. ecs, obs, modelarts, 对象存储) or category (e.g. 计算, 存储, 人工智能) to browse. Use when generating PPT, architecture diagrams (draw.io), or frontend pages that need official Huawei Cloud service logos.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        service: {
+          type: 'string',
+          description:
+            'Service name, alias, or Chinese name, e.g. ecs, obs, modelarts, 对象存储, 虚拟私有云. Omit to browse by category only.',
+        },
+        category: {
+          type: 'string',
+          description: 'Optional category filter, e.g. 计算, 存储, 网络, 人工智能, 数据库, 安全, 企业应用.',
+        },
       },
     },
   },
   {
     name: 'huaweicloud_setup_obs_config',
-    description: 'Synchronize KooCLI credentials to OBS config (~/.obsutilconfig). KooCLI and OBS use separate credential stores — hcloud commands work fine but OBS commands fail with "Please set ak, sk" unless this sync is done. Run this once to enable OBS operations; re-run after changing hcloud credentials.',
+    description:
+      'Synchronize KooCLI credentials to OBS config (~/.obsutilconfig). KooCLI and OBS use separate credential stores — hcloud commands work fine but OBS commands fail with "Please set ak, sk" unless this sync is done. Run this once to enable OBS operations; re-run after changing hcloud credentials.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -291,35 +418,83 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_auth_status',
-    description: 'Check unified Huawei Cloud authentication status across the global credential vault, OBS, KooCLI, and all supported agent MCP registrations. Returns only redacted/status information, never credentials.',
+    description:
+      'Check unified Huawei Cloud authentication status across the global credential vault, OBS, KooCLI, and all supported agent MCP registrations. Returns only redacted/status information, never credentials.',
     inputSchema: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: 'Agent target to check: opencode, codex, codex-desktop, codearts, workbuddy, or all (default).' },
+        target: {
+          type: 'string',
+          description:
+            'Agent target to check: opencode, codex, codex-desktop, codearts, workbuddy, dsh, officeace, hermes, openclaw, atomcode, or all (default).',
+        },
       },
     },
   },
   {
     name: 'huaweicloud_auth_sync',
-    description: 'Synchronize credentials from the global Huawei Cloud credential vault to OBS and report agent registration status. Does not write secrets into any agent config.',
+    description:
+      'Synchronize credentials from the global Huawei Cloud credential vault to OBS and report agent registration status. Does not write secrets into any agent config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description:
+            'Agent target to report after sync: opencode, codex, codex-desktop, codearts, workbuddy, dsh, officeace, hermes, or all (default).',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_auth_init',
+    description:
+      'Set or clear runtime Huawei Cloud credentials (AK/SK) for this MCP session. Runtime credentials take highest priority over environment variables and config files for all subsequent API calls. Use when switching accounts within the same Agent session — call with AK/SK to switch, or with clear=true to fall back to env/file credentials.',
     inputSchema: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: 'Agent target to report after sync: opencode, codex, codex-desktop, codearts, workbuddy, or all (default).' },
+        ak: { type: 'string', description: 'Huawei Cloud Access Key (required unless clear=true)' },
+        sk: { type: 'string', description: 'Huawei Cloud Secret Key (required unless clear=true)' },
+        region: { type: 'string', description: 'Default region (optional)' },
+        clear: { type: 'boolean', description: 'Set to true to clear runtime credentials and revert to env/file' },
       },
     },
   },
   {
     name: 'huaweicloud_sandbox_exec_with_session',
-    description: 'Execute a command on a workspace terminal with session reuse (state persists across calls). Shell state (cd, env vars, aliases) carries over between calls.',
+    description:
+      'Execute a command on a workspace terminal with session reuse (state persists across calls). Shell state (cd, env vars, aliases) carries over between calls. Use for interactive work and command sequences that need shared state. NOT for long-running commands (>30s) — prefer exec_one_shot for those.',
     inputSchema: {
       type: 'object',
       required: ['command'],
       properties: {
         command: { type: 'string', description: 'The shell command to execute on the remote workspace' },
-        workspace_id: { type: 'string', description: 'The workspace ID' },
+        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 for the remote terminal (default: root)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 120000)' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_sandbox_exec_one_shot',
+    description:
+      'Execute a command on a workspace terminal with a fresh connection per call (no session state carries over). Each invocation opens a new WebSocket connection, executes one command, then disconnects. Use for long-running build/deploy/install commands (>30s) that do not need shell state persistence between calls. More stable than session-based execution for heavy workloads.',
+    inputSchema: {
+      type: 'object',
+      required: ['command'],
+      properties: {
+        command: { type: 'string', description: 'The shell command to execute on the remote workspace' },
+        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 for the remote terminal (default: root)' },
-        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 30000)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 120000)' },
       },
     },
   },
@@ -329,14 +504,72 @@ export const TOOL_DEFINITIONS = [
     inputSchema: {
       type: 'object',
       properties: {
-        workspace_id: { type: 'string', description: 'The workspace ID' },
+        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)' },
       },
     },
   },
+  {
+    name: 'huaweicloud_sandbox_upload_file',
+    description:
+      'Upload a local file into the sandbox workspace. Base64-encodes the file, writes it in small chunks through the terminal session (the exec channel is fragile for large single commands), then decodes and verifies the md5 checksum. Use this instead of embedding large file content directly in a command.',
+    inputSchema: {
+      type: 'object',
+      required: ['local_path', 'remote_path'],
+      properties: {
+        local_path: { type: 'string', description: 'Absolute path to the local file to upload.' },
+        remote_path: { type: 'string', description: 'Target path in the sandbox, e.g. /workspace/<repo>/index.html.' },
+        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: 'Per-command execution timeout in milliseconds (default: 120000)' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_sandbox_upload_project',
+    description:
+      'Package a local project directory and upload it to a sandbox workspace via HTTP tunnel. Falls back to base64 chunking if tunnel fails. Creates a tar.gz archive, uploads it, and extracts it on the sandbox by default.',
+    inputSchema: {
+      type: 'object',
+      required: ['local_dir'],
+      properties: {
+        local_dir: { type: 'string', description: 'Local project directory to upload.' },
+        remote_dir: {
+          type: 'string',
+          description:
+            'Remote parent directory where project will be extracted (default: /workspace). Final layout: <remote_dir>/<dirname>/',
+        },
+        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)' },
+        exclude: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Patterns to exclude from archive (default: .git, node_modules, __pycache__, .venv)',
+        },
+        extract: {
+          type: 'boolean',
+          description: 'Extract tar.gz on sandbox after upload (default: true)',
+        },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 300000)' },
+      },
+    },
+  },
   {
     name: 'huaweicloud_sandbox_check_user',
-    description: 'Check if the current user has completed real-name verification and signed the required agreements. Returns realname_verified and agreement_signed status.',
+    description:
+      'Check if the current user has completed real-name verification and signed the required agreements. Returns 200 {realnameVerified, agreementSigned} when all good; throws 403 HDKIT_NOT_REALNAME / HDKIT_NOT_AGREEMENT / HDKIT_NOT_REALNAME_AND_AGREEMENT to indicate what is missing. Never signs anything itself.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -344,7 +577,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_sandbox_sign_agreement',
-    description: 'Sign all unsigned or outdated agreements for the current user. Required before huaweicloud_sandbox_connect if check-user returns agreement_signed=false.',
+    description:
+      "Sign all unsigned or outdated agreements for the current user. Required before huaweicloud_sandbox_connect if check-user returns agreementSigned=false. CRITICAL: only call after the user explicitly consents to signing — never sign agreements on the user's behalf without their explicit request.",
     inputSchema: {
       type: 'object',
       properties: {},
@@ -352,11 +586,16 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_sandbox_connect',
-    description: 'Connect to a sandbox via hdkitservice. One user one instance - reuses existing sandbox if available, otherwise creates a new one. Returns session_id, dev_stage_id, connection_id, and connection_address.',
+    description:
+      'Connect to a sandbox via hdkitservice. One user one instance - reuses existing sandbox if available, otherwise creates a new one. Returns session_id, dev_stage_id, connection_id, and connection_address.',
     inputSchema: {
       type: 'object',
       properties: {
-        source: { type: 'string', description: 'Source identifier (default: WEB). Options: VSCODE, CLI, WEB, WEBVNC, WEBPTY, WEBIDE, CURSOR, etc.' },
+        source: {
+          type: 'string',
+          description:
+            'Source identifier (default: WEB). Options: VSCODE, CLI, WEB, WEBVNC, WEBPTY, WEBIDE, CURSOR, etc.',
+        },
         template_id: { type: 'string', description: 'Template ID; overrides server default (only for new sandbox)' },
         flavor_id: { type: 'string', description: 'Flavor ID; overrides server default (only for new sandbox)' },
         env: { type: 'object', description: 'Environment variables to set in the sandbox (only for new sandbox)' },
@@ -376,7 +615,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_sandbox_credentials',
-    description: 'Configure temporary AK/SK for a sandbox via hdkitservice. Injects temporary credentials into the sandbox. The sandbox must be in RUNNING state.',
+    description:
+      'Configure temporary AK/SK for a sandbox via hdkitservice. Injects temporary credentials into the sandbox. The sandbox must be in RUNNING state.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -386,7 +626,6 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
-
 ];
 
 export async function callTool(name, args = {}) {
@@ -424,35 +663,124 @@ export async function callTool(name, args = {}) {
       return listRegions();
     case 'huaweicloud_get_regional_availability':
       return getRegionalAvailability(args.service || '', args.region || '');
-        case 'huaweicloud_explain_error':
+    case 'huaweicloud_explain_error':
       return explainError(args);
     case 'huaweicloud_search_marketplace':
       return searchMarketplace(args.query || '', args.category || '');
+    case 'huaweicloud_get_service_icon':
+      return getServiceIcon(args.service || '', args.category || '');
     case 'huaweicloud_setup_obs_config':
       return setupObsConfig(args.profile);
     case 'huaweicloud_auth_status':
       return getAuthStatus(args.target || 'all');
     case 'huaweicloud_auth_sync':
       return syncAuth(args.target || 'all');
+    case 'huaweicloud_auth_init':
+      if (args.clear) {
+        clearRuntimeCredentials();
+        return { status: 'cleared', message: 'Runtime credentials cleared. Fallback to env/file.' };
+      }
+      if (!args.ak || !args.sk) {
+        throw new Error('ak and sk are required. Set clear=true to clear runtime credentials.');
+      }
+      setRuntimeCredentials(args.ak, args.sk, undefined, args.region);
+      return { status: 'ok', message: 'Runtime credentials set for this MCP session.' };
     case 'huaweicloud_sandbox_exec_with_session': {
-      const sandboxWsId2 = args.workspace_id || DEFAULT_WORKSPACE_ID;
+      const sandboxWsId2 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId2) {
+        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 sandboxUser2 = args.username || 'root';
-      const sandboxTimeout2 = args.timeout_ms || 30000;
+      const sandboxTimeout2 = args.timeout_ms || 120000;
       const sandboxResult2 = await execWithSession(sandboxWsId2, args.command, sandboxUser2, sandboxTimeout2);
       return { stdout: sandboxResult2.stdout, exitCode: sandboxResult2.exitCode };
     }
-    case 'huaweicloud_sandbox_close_session': {
-      const sandboxWsId3 = args.workspace_id || DEFAULT_WORKSPACE_ID;
+    case 'huaweicloud_sandbox_exec_one_shot': {
+      const sandboxWsId3 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId3) {
+        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 sandboxUser3 = args.username || 'root';
-      const closed = await closeSession(sandboxWsId3, sandboxUser3);
+      const sandboxTimeout3 = args.timeout_ms || 120000;
+      const sandboxResult3 = await execOneShot(sandboxWsId3, args.command, sandboxUser3, sandboxTimeout3);
+      return { stdout: sandboxResult3.stdout, exitCode: sandboxResult3.exitCode };
+    }
+    case 'huaweicloud_sandbox_close_session': {
+      const sandboxWsId4 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId4) {
+        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 sandboxUser4 = args.username || 'root';
+      const closed = await closeSession(sandboxWsId4, sandboxUser4);
       return closed ? 'ok' : 'not_connected';
     }
+    case 'huaweicloud_sandbox_upload_file': {
+      if (!args.local_path || !args.remote_path) {
+        throw new Error('local_path and remote_path are required.');
+      }
+      const sandboxWsId5 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId5) {
+        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 sandboxUser5 = args.username || 'root';
+      const sandboxTimeout5 = args.timeout_ms || 120000;
+      return await uploadFileWithSession(
+        sandboxWsId5,
+        args.local_path,
+        args.remote_path,
+        sandboxUser5,
+        sandboxTimeout5,
+      );
+    }
+    case 'huaweicloud_sandbox_upload_project': {
+      if (!args.local_dir) {
+        throw new Error('local_dir is required.');
+      }
+      const sandboxWsId6 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId6) {
+        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 sandboxUser6 = args.username || 'root';
+      const sandboxTimeout6 = args.timeout_ms || 120000;
+      return await uploadProjectWithSession(
+        sandboxWsId6,
+        args.local_dir,
+        args.remote_dir,
+        sandboxUser6,
+        sandboxTimeout6,
+        {
+          exclude: args.exclude,
+          extract: args.extract,
+        },
+      );
+    }
     case 'huaweicloud_sandbox_check_user':
       return await hdkitCheckUser();
     case 'huaweicloud_sandbox_sign_agreement':
       return await hdkitSignAgreement();
-    case 'huaweicloud_sandbox_connect':
-      return await hdkitConnect(args);
+    case 'huaweicloud_sandbox_connect': {
+      const connectResult = await hdkitConnect(args);
+      const devStageId = connectResult?.dev_stage_id || connectResult?.devStageId;
+      if (devStageId) {
+        setWorkspaceId(devStageId);
+      }
+      return connectResult;
+    }
     case 'huaweicloud_sandbox_credentials':
       return await hdkitCredentials(args.session_id, args.dev_stage_id, args.enable_sts !== false);
     default:
@@ -465,11 +793,12 @@ function hookResult(result) {
     ok: result.decision !== 'deny',
     decision: result.decision,
     findings: result.findings,
-    nextStep: result.decision === 'deny'
-      ? 'Revise the command, artifact, or deployment plan before execution.'
-      : result.decision === 'warn'
-        ? 'Review the warnings with the user before proceeding.'
-        : 'No Huawei Cloud hook risk rule matched.',
+    nextStep:
+      result.decision === 'deny'
+        ? 'Revise the command, artifact, or deployment plan before execution.'
+        : result.decision === 'warn'
+          ? 'Review the warnings with the user before proceeding.'
+          : 'No Huawei Cloud hook risk rule matched.',
   };
 }
 
@@ -490,7 +819,8 @@ export async function runVersionCheck(options = {}) {
       : isSpawnError
         ? 'hcloud executable not found. Set HCLOUD_BIN to the full hcloud path, or install KooCLI: npx huaweicloud-devkit install-hcloud. Then restart the agent.'
         : 'Install Huawei Cloud KooCLI: npx huaweicloud-devkit install-hcloud. Configure credentials outside the agent conversation.',
-    authHint: 'If hcloud is installed but commands fail with "配置文件中不存在配置项", run `hcloud configure set --cli-access-key=<AK> --cli-secret-key=<SK> --cli-region=<region>` outside agent chat to configure credentials.',
+    authHint:
+      'If hcloud is installed but commands fail with "配置文件中不存在配置项", run `hcloud configure set --cli-access-key=<AK> --cli-secret-key=<SK> --cli-region=<region>` outside agent chat to configure credentials.',
   };
 }
 
@@ -509,7 +839,8 @@ async function showProfileRedacted(profile) {
       ok: false,
       blockedByPolicy: true,
       reason: result.reason,
-      safeAlternative: 'Use huaweicloud_show_profile_redacted so profile output is returned through the redaction pipeline.',
+      safeAlternative:
+        'Use huaweicloud_show_profile_redacted so profile output is returned through the redaction pipeline.',
     };
   }
   return {
@@ -551,7 +882,12 @@ async function setupObsConfig(profile) {
 async function setupObsConfigFromHcloud(profile) {
   const obsConfigPath = join(homedir(), '.obsutilconfig');
   if (existsSync(obsConfigPath)) {
-    return { ok: true, existed: true, path: obsConfigPath, note: 'OBS config already exists. Delete ~/.obsutilconfig first if you need to re-sync.' };
+    return {
+      ok: true,
+      existed: true,
+      path: obsConfigPath,
+      note: 'OBS config already exists. Delete ~/.obsutilconfig first if you need to re-sync.',
+    };
   }
 
   const args = ['configure', 'show'];
@@ -567,9 +903,9 @@ async function setupObsConfigFromHcloud(profile) {
     };
   }
 
-  let accessKeyId = '';
-  let secretAccessKey = '';
-  let region = '';
+  let accessKeyId;
+  let secretAccessKey;
+  let region;
 
   try {
     const parsed = typeof result.stdout === 'string' ? JSON.parse(result.stdout) : result.stdout;
@@ -607,11 +943,11 @@ async function setupObsConfigFromHcloud(profile) {
 
   try {
     writeFileSync(obsConfigPath, configContent, { encoding: 'utf8', mode: 0o600 });
-  } catch (e) {
+  } catch (error) {
     return {
       ok: false,
       error: 'Failed to write OBS config file.',
-      detail: e.message,
+      detail: error.message,
       path: obsConfigPath,
     };
   }
@@ -630,12 +966,16 @@ async function setupObsConfigFromHcloud(profile) {
 const SERVICE_EXAMPLES = {
   ECS: { list: 'ECS ListServersDetails', create: 'ECS CreateServers', show: 'IMS GlanceShowImage' },
   VPC: { list: 'VPC ListVpcs', create: 'VPC CreateVpc', show: 'VPC ShowVpc' },
-  FunctionGraph: { list: 'FunctionGraph ListFunctions', create: 'FunctionGraph CreateFunction', show: 'FunctionGraph ShowFunctionConfig' },
+  FUNCTIONGRAPH: {
+    list: 'FunctionGraph ListFunctions',
+    create: 'FunctionGraph CreateFunction',
+    show: 'FunctionGraph ShowFunctionConfig',
+  },
   APIG: { list: 'APIG ListInstancesV2', create: 'APIG CreateInstanceV2', show: 'APIG ShowDetailsOfInstanceV2' },
   OBS: { list: 'OBS ls', create: 'OBS mb obs://<bucket>', show: 'OBS stat obs://<bucket>/<key>' },
   RDS: { list: 'RDS ListInstances', create: 'RDS CreateInstance', show: 'RDS ShowInstance' },
   CES: { list: 'CES ListAlarms', create: 'CES CreateAlarm', show: 'CES ListMetrics' },
-  GaussDB: { list: 'GaussDB ListInstances', create: 'GaussDB CreateInstance', show: 'GaussDB ShowInstance' },
+  GAUSSDB: { list: 'GaussDB ListInstances', create: 'GaussDB CreateInstance', show: 'GaussDB ShowInstance' },
   DDS: { list: 'DDS ListInstances', create: 'DDS CreateInstance', show: 'DDS ShowInstance' },
   DCS: { list: 'DCS ListInstances', create: 'DCS CreateInstance', show: 'DCS ShowInstance' },
 };
@@ -662,7 +1002,9 @@ async function listOperations(service, options = {}) {
     service: serviceName,
     command: isObs ? 'hcloud obs help' : `hcloud ${svc} --help`,
     selectionRule: 'Use this help text to select the exact KooCLI operation name before planning any service command.',
-    examples: SERVICE_EXAMPLES[serviceName.toUpperCase()] || { note: `No cached examples for ${serviceName}. Use the help text above to discover available operations.` },
+    examples: SERVICE_EXAMPLES[serviceName.toUpperCase()] || {
+      note: `No cached examples for ${serviceName}. Use the help text above to discover available operations.`,
+    },
     result,
   };
 }
@@ -691,41 +1033,131 @@ async function runApprovedCommand(args = {}) {
 function serviceCatalog(intent = '') {
   const it = String(intent).toLowerCase();
   const routeMap = [
-    { keywords: ['ecs', 'server', 'vm', 'instance', 'compute', 'flavor', 'image'], skills: ['huawei-ecs'], services: ['ECS'] },
-    { keywords: ['vpc', 'subnet', 'network', 'security group', 'eip', 'nat', 'vpn', 'bandwidth'], skills: ['huawei-vpc'], services: ['VPC', 'EIP'] },
-    { keywords: ['obs', 'bucket', 'storage', 'object', 'static website', 'static site', 'hosting'], skills: ['huawei-obs'], services: ['OBS'] },
-    { keywords: ['functiongraph', 'serverless', 'function', 'lambda', 'trigger', 'faas'], skills: ['huawei-functiongraph'], services: ['FunctionGraph'] },
-    { keywords: ['cce', 'kubernetes', 'k8s', 'container', 'cluster', 'node pool', 'swr', 'docker', 'image registry'], skills: ['huawei-cce'], services: ['CCE', 'SWR'] },
+    {
+      keywords: ['ecs', 'server', 'vm', 'instance', 'compute', 'flavor', 'image'],
+      skills: ['huawei-ecs'],
+      services: ['ECS'],
+    },
+    {
+      keywords: ['vpc', 'subnet', 'network', 'security group', 'eip', 'nat', 'vpn', 'bandwidth'],
+      skills: ['huawei-vpc'],
+      services: ['VPC', 'EIP'],
+    },
+    {
+      keywords: ['obs', 'bucket', 'storage', 'object', 'static website', 'static site', 'hosting'],
+      skills: ['huawei-obs'],
+      services: ['OBS'],
+    },
+    {
+      keywords: ['functiongraph', 'serverless', 'function', 'lambda', 'trigger', 'faas'],
+      skills: ['huawei-functiongraph'],
+      services: ['FunctionGraph'],
+    },
+    {
+      keywords: ['cce', 'kubernetes', 'k8s', 'container', 'cluster', 'node pool', 'swr', 'docker', 'image registry'],
+      skills: ['huawei-cce'],
+      services: ['CCE', 'SWR'],
+    },
     { keywords: ['apig', 'api gateway', 'publish', 'throttle'], skills: ['huawei-apig'], services: ['APIG'] },
     { keywords: ['rds', 'mysql', 'postgresql', 'database', 'db'], skills: ['huawei-rds'], services: ['RDS'] },
-    { keywords: ['gaussdb', 'distributed', 'sharding', 'opengauss'], skills: ['huawei-gaussdb'], services: ['GaussDB'] },
-    { keywords: ['iam', 'permission', 'policy', 'role', 'user', 'ak/sk', 'access key', 'agency'], skills: ['huawei-iam'], services: ['IAM'] },
-    { keywords: ['dew', 'secret', 'kms', 'encrypt', 'decrypt', 'certificate', 'csms'], skills: ['huawei-dew'], services: ['CSMS', 'KMS'] },
-    { keywords: ['modelarts', 'ai', 'model', 'training', 'inference', 'machine learning'], skills: ['huawei-modelarts'], services: ['ModelArts'] },
-    { keywords: ['billing', 'cost', 'bill', 'budget', 'expense', 'bss'], skills: ['huawei-billing'], services: ['BSS'] },
-    { keywords: ['waf', 'aad', 'ddos', 'firewall', 'web protection'], skills: ['huawei-waf-aad'], services: ['WAF', 'AAD'] },
-    { keywords: ['smn', 'dms', 'notification', 'message', 'kafka', 'rabbitmq'], skills: ['huawei-smn-dms'], services: ['SMN', 'DMS'] },
-    { keywords: ['ces', 'monitor', 'alarm', 'metric', 'dashboard', 'cloud eye'], skills: ['huawei-cloud-eye'], services: ['CES'] },
+    {
+      keywords: ['gaussdb', 'distributed', 'sharding', 'opengauss'],
+      skills: ['huawei-gaussdb'],
+      services: ['GaussDB'],
+    },
+    {
+      keywords: ['iam', 'permission', 'policy', 'role', 'user', 'ak/sk', 'access key', 'agency'],
+      skills: ['huawei-iam'],
+      services: ['IAM'],
+    },
+    {
+      keywords: ['dew', 'secret', 'kms', 'encrypt', 'decrypt', 'certificate', 'csms'],
+      skills: ['huawei-dew'],
+      services: ['CSMS', 'KMS'],
+    },
+    {
+      keywords: ['modelarts', 'ai', 'model', 'training', 'inference', 'machine learning'],
+      skills: ['huawei-modelarts'],
+      services: ['ModelArts'],
+    },
+    {
+      keywords: ['billing', 'cost', 'bill', 'budget', 'expense', 'bss'],
+      skills: ['huawei-billing'],
+      services: ['BSS'],
+    },
+    {
+      keywords: ['waf', 'aad', 'ddos', 'firewall', 'web protection'],
+      skills: ['huawei-waf-aad'],
+      services: ['WAF', 'AAD'],
+    },
+    {
+      keywords: ['smn', 'dms', 'notification', 'message', 'kafka', 'rabbitmq'],
+      skills: ['huawei-smn-dms'],
+      services: ['SMN', 'DMS'],
+    },
+    {
+      keywords: ['ces', 'monitor', 'alarm', 'metric', 'dashboard', 'cloud eye'],
+      skills: ['huawei-cloud-eye'],
+      services: ['CES'],
+    },
     { keywords: ['cts', 'audit', 'trace', 'tracker'], skills: ['huawei-cts'], services: ['CTS'] },
     { keywords: ['cbr', 'backup', 'restore', 'vault', 'snapshot'], skills: ['huawei-cbr'], services: ['CBR'] },
-    { keywords: ['deployment', 'deploy', 'ci/cd', 'pipeline', 'release'], skills: ['huawei-deployment'], services: ['CloudDeploy'] },
-    { keywords: ['sandbox', 'devstation', 'workspace', 'terminal', 'preview', 'hwlink'], skills: ['huawei-sandbox'], services: ['Sandbox', 'DevStation'] },
-    { keywords: ['dds', 'dcs', 'mongodb', 'redis', 'memcached', 'cache', 'document db'], skills: ['huawei-dds-dcs'], services: ['DDS', 'DCS'] },
-];
+    {
+      keywords: ['deployment', 'deploy', 'ci/cd', 'pipeline', 'release'],
+      skills: ['huawei-deployment'],
+      services: ['CloudDeploy'],
+    },
+    {
+      keywords: [
+        'sandbox',
+        'devstation',
+        'workspace',
+        'terminal',
+        'preview',
+        'hwlink',
+        'website',
+        'web app',
+        'webapp',
+        'hosting',
+        '网站',
+        '网页',
+        '静态',
+      ],
+      skills: ['huawei-sandbox'],
+      services: ['Sandbox', 'DevStation'],
+    },
+    {
+      keywords: ['dds', 'dcs', 'mongodb', 'redis', 'memcached', 'cache', 'document db'],
+      skills: ['huawei-dds-dcs'],
+      services: ['DDS', 'DCS'],
+    },
+  ];
   const matched = [];
-  const tokens = it.split(/[\s,./-]+/).filter((t) => t.length > 0);
+  const tokens = new Set(it.split(/[\s,./-]+/).filter((t) => t.length > 0));
+  const cjk = /[\u4e00-\u9fff]/;
   for (const route of routeMap) {
-    if (route.keywords.some((kw) => tokens.includes(kw))) {
+    if (route.keywords.some((kw) => (kw.includes(' ') || cjk.test(kw) ? it.includes(kw) : tokens.has(kw)))) {
       matched.push(route);
     }
   }
   const recommendedSkills = [...new Set(matched.flatMap((r) => r.skills))];
   const recommendedServices = [...new Set(matched.flatMap((r) => r.services))].slice(0, 5);
 
+  // Deployment intent (deploy/host/publish a web app or static website) must never
+  // default to a storage/other service — recommend the sandbox first.
+  const deploymentIntent = /deploy|host|hosting|publish|website|web app|preview|部署|托管|发布|网站|网页/.test(it);
+  if (deploymentIntent && recommendedSkills.includes('huawei-sandbox')) {
+    const idx = recommendedSkills.indexOf('huawei-sandbox');
+    recommendedSkills.splice(idx, 1);
+    recommendedSkills.unshift('huawei-sandbox');
+  }
+
   return {
     intent,
     recommendedSkills: recommendedSkills.length ? recommendedSkills : ['Use huaweicloud-core to route intent.'],
-    recommendedServices: recommendedServices.length ? recommendedServices : ['Run hcloud --help to list available services.'],
+    recommendedServices: recommendedServices.length
+      ? recommendedServices
+      : ['Run hcloud --help to list available services.'],
     capabilityOrder: [
       'Huawei Cloud Skills for task-specific workflows and examples',
       'KooCLI hcloud for local authenticated operations and quick inspection',
@@ -751,32 +1183,38 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
   const svc = String(service).toLowerCase();
 
   const SERVICE_ALIASES = {
-    'functiongraph': 'FSS',
-    'fgs': 'FSS',
+    functiongraph: 'FSS',
+    fgs: 'FSS',
   };
   const patternKey = SERVICE_ALIASES[svc] || service;
 
   const hwErrorPatterns = {
     OBS: {
-      'InvalidAccessKeyId': 'OBS uses AK/SK directly (not IAM tokens). Verify AK/SK validity, OBS endpoint, and OBS permissions.',
-      'UserRestricted': 'This IAM user is restricted from OBS operations (403). Check IAM console → Users → Permissions: grant OBS bucket/object actions, or use an unrestricted account. If the account is a sub-account, the main account may have imposed restrictions.',
+      InvalidAccessKeyId:
+        'OBS uses AK/SK directly (not IAM tokens). Verify AK/SK validity, OBS endpoint, and OBS permissions.',
+      UserRestricted:
+        'This IAM user is restricted from OBS operations (403). Check IAM console → Users → Permissions: grant OBS bucket/object actions, or use an unrestricted account. If the account is a sub-account, the main account may have imposed restrictions.',
     },
     APIG: {
       'APIC.7241': 'The enterprise_project_id is required for enterprise accounts. Add --enterprise_project_id=0.',
-      'APIC.7242': 'The EIP binding method depends on loadbalancer_provider. Use AddIngressEipV2 for elb, AddEipV2 for lvs.',
+      'APIC.7242':
+        'The EIP binding method depends on loadbalancer_provider. Use AddIngressEipV2 for elb, AddEipV2 for lvs.',
       'APIC.7256': 'Bandwidth minimum is 5 Mbps. Use --bandwidth_size=5 or higher.',
       'APIC.7310': 'available_zone_ids must use AZ codes (e.g. ap-southeast-3a), NOT UUIDs from ListAvailableZonesV2.',
     },
     FSS: {
-      'FSS.0403': 'Missing FunctionGraph IAM permissions. Attach FunctionGraph FullAccess role or grant specific actions.',
+      'FSS.0403':
+        'Missing FunctionGraph IAM permissions. Attach FunctionGraph FullAccess role or grant specific actions.',
       'FSS.1078': '--code_filename is filename-only (no path). cd to the file directory before running the command.',
-      'FSS.1417': 'event_data field validation failed. Check parameter format: use dotted key=value, verify required hidden-optional fields.',
+      'FSS.1417':
+        'event_data field validation failed. Check parameter format: use dotted key=value, verify required hidden-optional fields.',
     },
     VPC: {
       'VPC.0301': 'Bandwidth name is required for PER type EIPs, even though --help marks it optional.',
     },
     APIGW: {
-      'APIGW.0802': 'The current IAM user has no permissions in the requested region. Go to IAM console → Users → Permissions → add the target region, or switch to a different region.',
+      'APIGW.0802':
+        'The current IAM user has no permissions in the requested region. Go to IAM console → Users → Permissions → add the target region, or switch to a different region.',
     },
   };
   if (hwErrorPatterns[patternKey] && hwErrorPatterns[patternKey][errorCode]) {
@@ -791,19 +1229,30 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
 
   if (/auth|token|credential|ak|sk|401|403|unauthorized|forbidden|Incorrect IAM/i.test(combined)) {
     if (svc === 'obs') {
-      suggestions.push('OBS uses AK/SK directly, not IAM tokens. Verify AK/SK validity and OBS bucket permissions via hcloud configure list or the Huawei Cloud console.');
+      suggestions.push(
+        'OBS uses AK/SK directly, not IAM tokens. Verify AK/SK validity and OBS bucket permissions via hcloud configure list or the Huawei Cloud console.',
+      );
     } else {
       suggestions.push('Check KooCLI profile, region, project_id, and IAM permissions without printing secrets.');
     }
   }
   if (/APIGW\.(\d+)/i.test(errorCode)) {
-    suggestions.push('APIGW.' + (errorCode.match(/APIGW\.(\d+)/i) || [])[1] + ': API Gateway layer error. ' + (errorCode === 'APIGW.0802' ? 'IAM user has no region permissions — check IAM console → User → Permissions → add target region.' : 'Verify the API request, region endpoint, and IAM permissions.'));
+    suggestions.push(
+      'APIGW.' +
+        (errorCode.match(/APIGW\.(\d+)/i) || [])[1] +
+        ': API Gateway layer error. ' +
+        (errorCode === 'APIGW.0802'
+          ? 'IAM user has no region permissions — check IAM console → User → Permissions → add target region.'
+          : 'Verify the API request, region endpoint, and IAM permissions.'),
+    );
   }
   if (/region|endpoint|project/i.test(combined)) {
     suggestions.push('Confirm the service endpoint, region, and project_id match the target resource.');
   }
   if (/quota|limit|insufficient|reach the limit/i.test(combined)) {
-    suggestions.push('Check quota and resource limits before retrying a create or scale operation. Consider switching accounts or requesting a quota increase.');
+    suggestions.push(
+      'Check quota and resource limits before retrying a create or scale operation. Consider switching accounts or requesting a quota increase.',
+    );
   }
   if (/not.?found|404/i.test(combined)) {
     if (/list.?regions/i.test(svc)) {
@@ -813,7 +1262,9 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
     }
   }
   if (!suggestions.length) {
-    suggestions.push('Collect service name, operation, region, project_id, request_id, and the full redacted error message.');
+    suggestions.push(
+      'Collect service name, operation, region, project_id, request_id, and the full redacted error message.',
+    );
   }
 
   if (requestId) {
@@ -821,8 +1272,7 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
   }
 
   const uniqueSuggestions = suggestions.filter((s, i, arr) => {
-    return !arr.slice(0, i).some((prev) =>
-      prev.substring(0, 50).toLowerCase() === s.substring(0, 50).toLowerCase());
+    return !arr.slice(0, i).some((prev) => prev.substring(0, 50).toLowerCase() === s.substring(0, 50).toLowerCase());
   });
 
   return {
@@ -839,9 +1289,7 @@ async function searchDocs(query, topic = 'all') {
   const results = [];
   try {
     if (existsSync(SKILLS_ROOT)) {
-      const dirs = readdirSync(SKILLS_ROOT, { withFileTypes: true })
-        .filter((d) => d.isDirectory())
-        .map((d) => d.name);
+      const dirs = listSkillDirs(SKILLS_ROOT);
       for (const dir of dirs) {
         const skillPath = join(SKILLS_ROOT, dir, 'SKILL.md');
         if (!existsSync(skillPath)) continue;
@@ -864,11 +1312,16 @@ async function searchDocs(query, topic = 'all') {
         const nameLower = name.toLowerCase();
         const contentLower = content.toLowerCase();
         const relevance = tokens.reduce((score, token) => {
-          return score + (descLower.includes(token) ? 3 : 0) + (nameLower.includes(token) ? 2 : 0) + (contentLower.includes(token) ? 1 : 0);
+          return (
+            score +
+            (descLower.includes(token) ? 3 : 0) +
+            (nameLower.includes(token) ? 2 : 0) +
+            (contentLower.includes(token) ? 1 : 0)
+          );
         }, 0);
         if (relevance > 0) {
           results.push({
-            source: "skills/" + dir + "/SKILL.md",
+            source: 'skills/' + dir + '/SKILL.md',
             name,
             snippet: description.substring(0, 200),
             relevance,
@@ -876,8 +1329,8 @@ async function searchDocs(query, topic = 'all') {
         }
       }
     }
-  } catch (err) {
-    return { ok: false, error: err.message, results: [] };
+  } catch (error) {
+    return { ok: false, error: error.message, results: [] };
   }
   results.sort((a, b) => b.relevance - a.relevance);
   return { ok: true, query: q, topic, count: results.length, results: results.slice(0, 10) };
@@ -888,9 +1341,7 @@ async function retrieveSkill(name) {
   if (!skillName) return { ok: false, error: 'Skill name is required.' };
   const skillPath = join(SKILLS_ROOT, skillName, 'SKILL.md');
   if (!existsSync(skillPath)) {
-    const dirs = existsSync(SKILLS_ROOT)
-      ? readdirSync(SKILLS_ROOT, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
-      : [];
+    const dirs = listSkillDirs(SKILLS_ROOT);
     return { ok: false, error: 'Skill "' + skillName + '" not found. Available: ' + dirs.join(', ') };
   }
   const content = readFileSync(skillPath, 'utf8');
@@ -903,7 +1354,8 @@ async function retrieveSkill(name) {
     });
   }
   const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  let version = 1, description = '';
+  let version = 1,
+    description = '';
   if (frontmatter) {
     const fm = frontmatter[1];
     const vm = fm.match(/^version:\s*(.+)$/m);
@@ -915,8 +1367,12 @@ async function retrieveSkill(name) {
 }
 
 async function listRegions() {
-  const result = await runHcloud(['IAM', 'KeystoneListRegions'], { timeoutMs: 30000, maxRetries: 0 })
-    .catch((err) => ({ ok: false, error: err.message }));
+  const result = await runHcloud(['IAM', 'KeystoneListRegions'], { timeoutMs: 30000, maxRetries: 0 }).catch(
+    (error) => ({
+      ok: false,
+      error: error.message,
+    }),
+  );
   if (!result.ok) {
     return {
       ok: false,
@@ -936,7 +1392,7 @@ async function listRegions() {
       note: 'hcloud unavailable. Showing static region list. For the complete list, visit the fallback URL.',
     };
   }
-  let regions = [];
+  let regions;
   try {
     const parsed = typeof result.stdout === 'string' ? JSON.parse(result.stdout) : result.stdout;
     const rawRegions = parsed.regions || [];
@@ -954,37 +1410,128 @@ async function listRegions() {
 }
 
 async function getRegionalAvailability(service, region) {
-  const svc = String(service || '').toLowerCase().trim();
-  const reg = String(region || '').toLowerCase().trim();
+  const svc = String(service || '')
+    .toLowerCase()
+    .trim();
+  const reg = String(region || '')
+    .toLowerCase()
+    .trim();
   if (!svc || !reg) return { ok: false, error: 'Both service and region are required.' };
   const known = {
-    ecs: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','ap-southeast-4','af-south-1','tr-west-1','sa-brazil-1','la-north-2','na-mexico-1','me-east-1'],
-    obs: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','af-south-1'],
-    vpc: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','ap-southeast-4','af-south-1','tr-west-1','sa-brazil-1','la-north-2','me-east-1'],
+    ecs: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+      'ap-southeast-4',
+      'af-south-1',
+      'tr-west-1',
+      'sa-brazil-1',
+      'la-north-2',
+      'na-mexico-1',
+      'me-east-1',
+    ],
+    obs: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+      'af-south-1',
+    ],
+    vpc: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+      'ap-southeast-4',
+      'af-south-1',
+      'tr-west-1',
+      'sa-brazil-1',
+      'la-north-2',
+      'me-east-1',
+    ],
     iam: ['global'],
-    rds: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
-    gaussdb: ['cn-south-1','cn-north-4','cn-east-3'],
-    cce: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
-    modelarts: ['cn-south-1','cn-north-4','cn-east-3'],
-    functiongraph: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
-    dew: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    smn: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    ces: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    cts: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    apig: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    cbr: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    dds: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
-    dcs: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    rds: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+    ],
+    gaussdb: ['cn-south-1', 'cn-north-4', 'cn-east-3'],
+    cce: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+    ],
+    modelarts: ['cn-south-1', 'cn-north-4', 'cn-east-3'],
+    functiongraph: [
+      'cn-south-1',
+      'cn-north-4',
+      'cn-north-1',
+      'cn-east-3',
+      'cn-east-2',
+      'ap-southeast-3',
+      'ap-southeast-2',
+      'ap-southeast-1',
+    ],
+    dew: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    smn: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    ces: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    cts: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    apig: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    cbr: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    dds: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
+    dcs: ['cn-south-1', 'cn-north-4', 'cn-east-3', 'ap-southeast-3'],
   };
-  if (!known[svc]) return { ok: false, service: svc, region: reg, available: false, note: 'Service ' + svc + ' is not in the regional availability cache. Run hcloud ' + svc.toUpperCase() + ' --help to verify, or check https://developer.huaweicloud.com/endpoint.' };
+  if (!known[svc])
+    return {
+      ok: false,
+      service: svc,
+      region: reg,
+      available: false,
+      note:
+        'Service ' +
+        svc +
+        ' is not in the regional availability cache. Run hcloud ' +
+        svc.toUpperCase() +
+        ' --help to verify, or check https://developer.huaweicloud.com/endpoint.',
+    };
   const available = known[svc].includes(reg) || known[svc].includes('global');
   return {
-    ok: true, service: svc, region: reg, available,
+    ok: true,
+    service: svc,
+    region: reg,
+    available,
     note: available
       ? svc + ' is available in ' + reg + '.'
-      : svc + ' availability in ' + reg + ' could not be confirmed. Verify at https://developer.huaweicloud.com/endpoint.',
+      : svc +
+        ' availability in ' +
+        reg +
+        ' could not be confirmed. Verify at https://developer.huaweicloud.com/endpoint.',
     sourcedFrom: 'static cache, update via npm package upgrade',
-    disclaimer: 'This result reflects service-level availability only. It does NOT guarantee that your IAM user has permissions in this region. Account-level restrictions (e.g., APIGW.0802) may block actual API calls even when the service is available.',
+    disclaimer:
+      'This result reflects service-level availability only. It does NOT guarantee that your IAM user has permissions in this region. Account-level restrictions (e.g., APIGW.0802) may block actual API calls even when the service is available.',
   };
 }