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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.10-next.3",
+  "version": "1.1.10-next.5",
   "kooCliVersion": "7.3.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.10-next.3",
+  "version": "1.1.10-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.10-next.3",
+  "version": "1.1.10-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.10-next.3",
+  "version": "1.1.10-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.10-next.3",
+  "version": "1.1.10-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.10-next.3",
+  "version": "1.1.10-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.10-next.3",
+  "version": "1.1.10-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/src/account-type.mjs

@@ -112,7 +112,16 @@ export async function checkAccountType({ region } = {}) {
   }
   const identity = parseCallerIdentity(identityResult.stdout);
   if (!identity.ok) {
-    return { ok: false, error: identity.error };
+    // hcloud ran but stdout was not the expected JSON — usually a credentials
+    // problem surfacing as free-text error output, not a parser bug.
+    const snippet = String(identityResult.stdout || '')
+      .slice(0, 200)
+      .replace(/\s+/g, ' ');
+    return {
+      ok: false,
+      error: identity.error + (snippet ? ` (raw: ${snippet})` : ''),
+      hint: 'GetCallerIdentity 未返回 JSON，通常是凭据未就绪：请确认已运行 auth init、或平台已注入可用 STS（先用 huaweicloud_auth_status 查看 usableCredentials/credentialPanel）。',
+    };
   }
 
   const domainsResult = await runHcloud(['IAM', 'KeystoneListAuthDomains'], {

package/plugins/huaweicloud-core/src/auth/agent-registration.mjs

@@ -31,7 +31,7 @@ function opencodeConfigFile() {
 function readJsonSafe(path) {
   if (!existsSync(path)) return null;
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''));
   } catch {
     return null;
   }

package/plugins/huaweicloud-core/src/auth/credentials.mjs

@@ -50,11 +50,18 @@ export function obsConfigPath() {
   return process.env.HCLOUD_OBS_CONFIG_PATH || join(homedir(), '.obsutilconfig');
 }
 
+// Read a JSON file, stripping a leading UTF-8 BOM (U+FEFF) if present. CodeArts
+// writes mcp_settings.json with a BOM on Windows; plain JSON.parse would throw.
+export function readJsonFile(path) {
+  const text = readFileSync(path, 'utf8');
+  return JSON.parse(text.replace(/^\uFEFF/, ''));
+}
+
 export function readGlobalCredentials() {
   const path = globalCredentialsPath();
   if (!existsSync(path)) return null;
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    return readJsonFile(path);
   } catch {
     return null;
   }
@@ -325,7 +332,7 @@ export function readCodeArtsCredentials() {
     const path = join(dir, '.codeartsdoer', 'mcp', 'mcp_settings.json');
     try {
       if (!existsSync(path)) continue;
-      const config = JSON.parse(readFileSync(path, 'utf8'));
+      const config = readJsonFile(path);
       const server = pickDevkitMcpServer(config?.mcpServers);
       if (!server?.env) continue;
 
@@ -355,7 +362,7 @@ export function readCodeArtsCredentials() {
   for (const path of workPaths) {
     try {
       if (!existsSync(path)) continue;
-      const config = JSON.parse(readFileSync(path, 'utf8'));
+      const config = readJsonFile(path);
       const entry = readWorkEnvironmentEntry(config);
       if (entry) return entry;
     } catch {
@@ -404,7 +411,7 @@ export function resolveXAuthToken() {
     const path = join(dir, '.codeartsdoer', 'mcp', 'mcp_settings.json');
     try {
       if (!existsSync(path)) continue;
-      const config = JSON.parse(readFileSync(path, 'utf8'));
+      const config = readJsonFile(path);
       const server = pickDevkitMcpServer(config?.mcpServers);
       const token = server?.env?.HW_X_AUTH_TOKEN;
       if (present(token)) return token;
@@ -418,7 +425,7 @@ export function resolveXAuthToken() {
   for (const path of workPaths) {
     try {
       if (!existsSync(path)) continue;
-      const config = JSON.parse(readFileSync(path, 'utf8'));
+      const config = readJsonFile(path);
       const server = pickDevkitMcpServer(config?.mcp);
       const token = server?.environment?.HW_X_AUTH_TOKEN;
       if (present(token)) return token;
@@ -482,7 +489,7 @@ export function readLastSync() {
   const path = lastSyncPath();
   if (!existsSync(path)) return null;
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    return readJsonFile(path);
   } catch {
     return null;
   }

package/plugins/huaweicloud-core/src/auth/service.mjs

@@ -85,7 +85,8 @@ export function computeOnboarding({ credentials, reconciled } = {}) {
     // devkit exchanges it for temporary AK/SK on demand, so no manual setup.
     scenario = 0;
     reason = 'token-auth';
-    message = '已使用 X-Auth-Token 认证,MCP 工具可直接使用,无需配置 AK/SK。';
+    message =
+      '已使用 X-Auth-Token 认证。管理面与数据面(沙箱部署/exec)都会在需要时用 token 自动换取临时 AK/SK;请确保可访问 IAM 端点。';
     return { needsSetup: false, scenario, reason, message, steps: [], accountHint };
   }
   if (s1Has && !envHasCreds) {
@@ -189,6 +190,17 @@ export function getAuthStatus(target = 'all') {
   };
   return {
     target,
+    // usableCredentials: any credential source that makes the MCP/backend path
+    // actually work right now (S1, CodeArts settings, platform STS triplet,
+    // X-Auth-Token, or runtime creds) — supersedes the misleading
+    // credentialsConfigured/onboarding split (#P4).
+    usableCredentials: Boolean(
+      (credentials?.ak && credentials?.sk) ||
+      (s4Creds?.ak && s4Creds?.sk) ||
+      envHasRealTriplet() ||
+      tokenAuth ||
+      hasRuntimeCredentials(),
+    ),
     credentialsConfigured: Boolean(credentials?.ak && credentials?.sk) || Boolean(tokenAuth),
     credentialsPath: globalCredentialsPath(),
     mcpSettingsConfigured: Boolean(s4Creds?.ak && s4Creds?.sk),

package/plugins/huaweicloud-core/src/koocli-install.mjs

@@ -0,0 +1,57 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { getKooCliVersion, kooCliDownloadBase } from './koocli-version.mjs';
+
+// Programmatic KooCLI (hcloud) install — downloadable from inside the MCP server
+// process via Node (fetch + tar via child_process), so it does NOT depend on the
+// agent's bash tool (which is unavailable in CodeArts with OPENCODE_CONFIG
+// unset — experience-report #3.5). Returns a structured result for the
+// `huaweicloud_install_hcloud` MCP tool.
+export async function installKooCli(options = {}) {
+  const os = process.platform;
+  const arch = process.arch;
+
+  // Windows auto-install needs PowerShell specifics — keep it on the CLI path.
+  if (os === 'win32') {
+    return { ok: false, error: 'Windows 环境请使用 CLI: npx huaweicloud-devkit install-hcloud' };
+  }
+  if (os !== 'linux' && os !== 'darwin') {
+    return { ok: false, error: `不支持的操作系统: ${os}` };
+  }
+
+  const installDir = options.binDir || (os === 'linux' ? join(homedir(), '.local', 'bin') : '/usr/local/bin');
+  const pkg =
+    os === 'linux' ? (arch === 'arm64' ? 'linux-arm64' : 'linux-amd64') : arch === 'arm64' ? 'mac-arm64' : 'mac-amd64';
+  const url = `${kooCliDownloadBase()}/huaweicloud-cli-${pkg}.tar.gz`;
+  const binPath = join(installDir, 'hcloud');
+
+  try {
+    mkdirSync(installDir, { recursive: true });
+
+    const tmpTar = join(installDir, `huaweicloud-cli-${pkg}.tar.gz`);
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      return { ok: false, error: `下载失败 (HTTP ${resp.status}): ${url}` };
+    }
+    const buf = Buffer.from(await resp.arrayBuffer());
+    writeFileSync(tmpTar, buf);
+
+    const ex = spawnSync('tar', ['-xzf', tmpTar, '-C', installDir], { stdio: 'pipe', timeout: 60000 });
+    rmSync(tmpTar, { force: true });
+    if (ex.status !== 0) {
+      return { ok: false, error: `解压失败 (tar exit ${ex.status}): ${(ex.stderr || '').toString().slice(0, 200)}` };
+    }
+
+    if (!existsSync(binPath)) {
+      return { ok: false, error: `hcloud 二进制未生成于 ${binPath}` };
+    }
+    chmodSync(binPath, 0o755);
+
+    return { ok: true, binPath, version: getKooCliVersion() };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  }
+}

package/plugins/huaweicloud-core/src/sandbox/hdkitservice-api.mjs

@@ -1,20 +1,42 @@
-import { getCredentials } from './hwlink-api.mjs';
 import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
 import { cacheUserHash } from '../telemetry/telemetry.mjs';
 import { readInstalledVersion } from '../update-check.mjs';
+import { resolveCredentialsWithRuntime, resolveXAuthToken } from '../auth/credentials.mjs';
+import { getTokenCredentials } from '../auth/token-exchange.mjs';
+import { makeError } from '../auth/guidance.mjs';
 
 function getHdkitBaseUrl() {
   return process.env.HDKITSERVICE_ENDPOINT || 'https://devkit.huaweicloud.com/rest/developer/server/hdkitservice/';
 }
 
+// Backend (hdkitservice/voucher) credentials: prefer AK/SK, else fall back to
+// X-Auth-Token → temporary AK/SK exchange, so token-auth users are not blocked.
+async function resolveBackendCredentials() {
+  try {
+    const creds = resolveCredentialsWithRuntime({ allowMissing: true });
+    if (creds && creds.ak && creds.sk) return creds;
+  } catch {
+    // no AK/SK — fall through to token
+  }
+  const token = resolveXAuthToken();
+  if (!token) return null;
+  try {
+    return await getTokenCredentials(token);
+  } catch {
+    return null;
+  }
+}
+
 async function hdkitRequest(method, path, body, timeoutMs = 300000) {
-  const { ak, sk, securitytoken } = getCredentials();
+  const creds = await resolveBackendCredentials();
+  const ak = creds?.ak;
+  const sk = creds?.sk;
+  const securitytoken = creds?.securityToken || '';
 
   if (!ak || !sk) {
-    throw new Error(
-      'Huawei Cloud credentials are not configured. ' +
-        'Run "npx huaweicloud-devkit auth init" or set HW_ACCESS_KEY/HW_SECRET_KEY.',
-    );
+    const err = makeError('HDKIT_CRED_MISSING');
+    err.detail = 'Run "npx huaweicloud-devkit auth init" or set HW_ACCESS_KEY/HW_SECRET_KEY/HW_X_AUTH_TOKEN.';
+    throw err;
   }
   const headers = {
     'Content-Type': 'application/json',

package/plugins/huaweicloud-core/src/sandbox/hwlink-api.mjs

@@ -1,6 +1,8 @@
 import crypto from 'node:crypto';
 
-import { resolveCredentialsWithRuntime } from '../auth/credentials.mjs';
+import { resolveCredentialsWithRuntime, resolveXAuthToken } from '../auth/credentials.mjs';
+import { getTokenCredentials } from '../auth/token-exchange.mjs';
+import { makeError } from '../auth/guidance.mjs';
 import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
 
 const BASE_URL = process.env.HWLINK_ENDPOINT || 'https://devstation.myhuaweicloud.com';
@@ -82,6 +84,33 @@ export function getCredentials() {
   return { ak: credentials.ak, sk: credentials.sk, securitytoken: credentials.securityToken };
 }
 
+// Data-plane (sandbox exec/upload/tunnel) credentials: prefer AK/SK, else fall
+// back to X-Auth-Token → temporary AK/SK, so token-auth users can drive the data
+// plane without a permanent AK/SK (experience-report #3.3/#3.7 dead-loop fix).
+export async function resolveBackendCredentials() {
+  try {
+    const creds = resolveCredentialsWithRuntime({ allowMissing: true });
+    if (creds && creds.ak && creds.sk) return creds;
+  } catch {
+    // no AK/SK — fall through to token
+  }
+  const token = resolveXAuthToken();
+  if (token) {
+    try {
+      return await getTokenCredentials(token);
+    } catch (error) {
+      // Distinguish "token exchange failed" from "no credential at all" (#3.4).
+      const err = makeError('HDKIT_CRED_MISSING');
+      err.code = error?.code || 'TOKEN_EXCHANGE_FAILED';
+      err.messageZh =
+        `X-Auth-Token 换取临时 AK/SK 失败(${err.code}):` +
+        `${error?.message || '网络异常或 token 无效'},请检查网络连通性与 token 有效性。`;
+      throw err;
+    }
+  }
+  throw makeError('HDKIT_CRED_MISSING');
+}
+
 async function apiGet(path, query, ak, sk, securitytoken) {
   query = query || {};
   const qs = sortedQs(query);

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

@@ -16,7 +16,7 @@ import { join, dirname, basename } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { createConnection, getCredentials } from './hwlink-api.mjs';
+import { createConnection, resolveBackendCredentials } from './hwlink-api.mjs';
 import { getWebSocketImpl } from '../proxy/proxy-agent.mjs';
 import { trackSandboxConnect, trackSandboxDisconnect } from '../telemetry/telemetry.mjs';
 
@@ -107,7 +107,7 @@ async function getSession(workspaceId, username, timeoutMs) {
   const key = `${workspaceId}:${username}`;
   if (sessions.has(key)) return sessions.get(key);
 
-  const { ak, sk, securitytoken } = getCredentials();
+  const { ak, sk, securitytoken } = await resolveBackendCredentials();
   const { wsUrl, source } = await createConnection(workspaceId, ak, sk, securitytoken);
 
   const WebSocketImpl = await getWebSocketImpl(wsUrl);
@@ -126,7 +126,7 @@ async function getSession(workspaceId, username, timeoutMs) {
 }
 
 async function createTunnelSession(workspaceId, username, timeoutMs = 30000) {
-  const { ak, sk, securitytoken } = getCredentials();
+  const { ak, sk, securitytoken } = await resolveBackendCredentials();
   const { wsUrl, source } = await createConnection(workspaceId, ak, sk, securitytoken);
   const WebSocketImpl = await getWebSocketImpl(wsUrl);
 
@@ -165,7 +165,7 @@ async function createTunnelSession(workspaceId, username, timeoutMs = 30000) {
 }
 
 export async function execOneShot(workspaceId, command, username, timeoutMs) {
-  const { ak, sk, securitytoken } = getCredentials();
+  const { ak, sk, securitytoken } = await resolveBackendCredentials();
   const { wsUrl, source } = await createConnection(workspaceId, ak, sk, securitytoken);
 
   const WebSocketImpl = await getWebSocketImpl(wsUrl);

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

@@ -25,6 +25,9 @@ import { redactSecrets } from './safety-policy.mjs';
 import {
   globalCredentialsPath,
   readGlobalCredentials,
+  readJsonFile,
+  resolveCredentialsWithRuntime,
+  resolveXAuthToken,
   writeGlobalCredentials,
   writeLastSync,
   writeObsConfig,
@@ -53,8 +56,6 @@ import { queryDistTagsFetch, determineTarget, semverCompare } from './update-che
 import { getKooCliVersion, compareVersion, kooCliDownloadBase, KOO_CLI_BASE } from './koocli-version.mjs';
 import { findHcloudBin, hcloudProbeNextStep, probeHcloud } from './hcloud-probe.mjs';
 
-const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
-
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLUGIN_ROOT = resolve(__dirname, '..');
 const PACKAGE_ROOT = resolve(PLUGIN_ROOT, '..', '..');
@@ -244,6 +245,9 @@ function officeaceSqlitePath() {
 }
 
 function openOfficeaceDb() {
+  // Lazy-require node:sqlite (experimental on Node 22.x) so CLI commands that
+  // don't touch OfficeAce (version/doctor/install) run without the flag.
+  const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
   return new DatabaseSync(officeaceSqlitePath());
 }
 
@@ -1584,7 +1588,7 @@ function codeartsStatus() {
   );
   if (existsSync(codeartsMcpSettingsFile())) {
     try {
-      const config = JSON.parse(readFileSync(codeartsMcpSettingsFile(), 'utf8'));
+      const config = readJsonFile(codeartsMcpSettingsFile());
       console.log(
         `  MCP config: ${config.mcpServers?.['huaweicloud-devkit'] ? '\x1b[32mConfigured\x1b[0m' : '\x1b[31mNot configured\x1b[0m'}`,
       );
@@ -1745,7 +1749,7 @@ function codeartsWorkStatus() {
   );
   if (existsSync(codeartsWorkMcpSettingsFile())) {
     try {
-      const config = JSON.parse(readFileSync(codeartsWorkMcpSettingsFile(), 'utf8'));
+      const config = readJsonFile(codeartsWorkMcpSettingsFile());
       console.log(
         `  MCP config: ${config.mcp?.['huaweicloud-devkit'] ? '\x1b[32mConfigured\x1b[0m' : '\x1b[31mNot configured\x1b[0m'}`,
       );
@@ -4310,7 +4314,27 @@ async function cmdDoctor() {
       timeout: 5000,
     });
     const hasAuth = authCheck.status === 0 && /access.?key/i.test(authCheck.stdout.toString());
-    check('hcloud credentials configured', hasAuth, 'Run: npx huaweicloud-devkit auth init');
+    if (hasAuth) {
+      check('hcloud credentials configured', true, '');
+    } else {
+      // In CodeArts, platform-injected STS / X-Auth-Token reach only the MCP
+      // server process, not this bash tool process — so `hcloud configure list`
+      // shows no profile even though the backend API path is usable. Degrade to
+      // a warning instead of a hard fail in that case (#P3 of CodeArts test).
+      let platformCredsActive = false;
+      try {
+        const c = resolveCredentialsWithRuntime({ allowMissing: true });
+        platformCredsActive = Boolean((c && c.ak && c.sk && c.securityToken) || resolveXAuthToken());
+      } catch {}
+      if (platformCredsActive) {
+        console.log(
+          `  \x1b[33m[WARN]\x1b[0m hcloud credentials configured — KooCLI 无 profile，但检测到平台凭证(MCP 通道可用);仅 KooCLI 直接调用需 auth init`,
+        );
+        warn++;
+      } else {
+        check('hcloud credentials configured', false, 'Run: npx huaweicloud-devkit auth init');
+      }
+    }
   }
 
   // Skills

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

@@ -13,6 +13,7 @@ import { checkAccountType } from './account-type.mjs';
 import { searchMarketplace } from './search-market.mjs';
 import { getServiceIcon } from './icon-library.mjs';
 import { detectFramework } from './detect-framework.mjs';
+import { installKooCli } from './koocli-install.mjs';
 import {
   execWithSession,
   execOneShot,
@@ -35,7 +36,7 @@ import {
   hdkitCompetitionVoucherClaim,
   hdkitGenerateUserHash,
 } from './sandbox/hdkitservice-api.mjs';
-import { getCredentials } from './sandbox/hwlink-api.mjs';
+import { resolveBackendCredentials } from './sandbox/hwlink-api.mjs';
 import { getAuthStatus, syncAuth } from './auth/service.mjs';
 import { validateIamCredentials } from './auth/credential-validator.mjs';
 import {
@@ -199,6 +200,15 @@ export const TOOL_DEFINITIONS = [
       properties: {},
     },
   },
+  {
+    name: 'huaweicloud_install_hcloud',
+    description:
+      'Install KooCLI (hcloud) from inside the MCP server process via Node (no agent bash tool required). Downloads and extracts the pinned hcloud binary to ~/.local/bin/hcloud. Use when huaweicloud_check_cli reports HCLOUD_NOT_FOUND and the agent bash tool is unavailable (e.g. CodeArts with OPENCODE_CONFIG unset).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
   {
     name: 'huaweicloud_plan_cli_command',
     description: 'Classify and plan a Huawei Cloud hcloud command without executing it.',
@@ -1180,6 +1190,8 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
   switch (name) {
     case 'huaweicloud_check_cli':
       return runVersionCheck();
+    case 'huaweicloud_install_hcloud':
+      return installKooCli();
     case 'huaweicloud_plan_cli_command':
       return planHcloudCommand(args.args || [], { allowWrites: args.allowWrites === true });
     case 'huaweicloud_run_readonly_command':
@@ -1572,7 +1584,7 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       const apiKeyFile = '/tmp/hw_api_key';
       if (sandboxWsIdCred) {
         try {
-          const { ak, sk, securitytoken } = getCredentials();
+          const { ak, sk, securitytoken } = await resolveBackendCredentials();
           const credsScript = [
             `export HW_ACCESS_KEY='${ak}'`,
             `export HW_SECRET_KEY='${sk}'`,
@@ -2318,6 +2330,26 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
   }
   const patternKey = SERVICE_ALIASES[svc] || resolvedService;
 
+  // devkit internal credential/environment error codes (experience-report #3.9)
+  // — these come from devkit's own guidance/credential layer, not Huawei Cloud API.
+  const devkitErrorPatterns = {
+    HDKIT_CRED_MISSING:
+      '未配置华为云凭证。运行 npx huaweicloud-devkit auth init 配置 AK/SK,或注入 HW_X_AUTH_TOKEN(devkit 会自动用 token 换取临时 AK/SK)。',
+    HDKIT_CRED_INVALID: '凭证已被华为云拒绝(AK/SK 无效或已过期)。重新生成 AK/SK 后 auth init。',
+    HDKIT_CRED_FORBIDDEN: '凭证有效但无权限列出项目。检查 IAM 授权(可用 huaweicloud_check_account_type 判断账号类型)。',
+    HDKIT_CRED_REGION_MISSING: '缺少 region 配置。运行 hcloud configure set --cli-region=<region>。',
+    HDKIT_KOOCLI_NOT_READY: 'KooCLI(hcloud)未安装或未就绪。运行 npx huaweicloud-devkit install-hcloud。',
+    HDKIT_PROJECT_ID_MISSING: '缺少 project_id。运行 npx huaweicloud-devkit auth init 自动配置。',
+    TOKEN_INVALID: 'X-Auth-Token 无效或已过期。重新注入有效的 HW_X_AUTH_TOKEN。',
+    TOKEN_EXPIRED: 'X-Auth-Token 已过期。重启进程重新注入凭证。',
+    TOKEN_EXCHANGE_FAILED:
+      'X-Auth-Token 换取临时 AK/SK 失败,通常是网络无法访问 IAM 端点。检查网络连通性与 token 有效性。',
+    HDKIT_SUB_ACCOUNT_RESTRICTED: '沙箱使用限制:当前子账号无法使用沙箱。切换主账号认证(auth_init)后重试。',
+  };
+  if (devkitErrorPatterns[errorCode]) {
+    suggestions.push(`${errorCode}: ${devkitErrorPatterns[errorCode]}`);
+  }
+
   const hwErrorPatterns = {
     OBS: {
       InvalidAccessKeyId: