huaweicloud-devkit 1.1.8-next.3 → 1.1.9-next.0

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.8-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.9-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **[中文](README.zh-CN.md) | English**
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![CI](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml/badge.svg)](https://github.com/huaweicloud/huaweicloud-devkit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/huaweicloud-devkit)](https://www.npmjs.com/package/huaweicloud-devkit)
-[![Beta](https://img.shields.io/badge/beta-v1.1.8-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
+[![Beta](https://img.shields.io/badge/beta-v1.1.9-orange)](https://github.com/huaweicloud/huaweicloud-devkit)
 
 **中文 | [English](README.md)**
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.8-next.3",
+  "version": "1.1.9-next.0",
   "kooCliVersion": "7.2.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.8-next.3",
+  "version": "1.1.9-next.0",
   "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.8-next.3",
+  "version": "1.1.9-next.0",
   "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.8-next.3",
+  "version": "1.1.9-next.0",
   "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.8-next.3",
+  "version": "1.1.9-next.0",
   "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.8-next.3",
+  "version": "1.1.9-next.0",
   "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.8-next.3",
+  "version": "1.1.9-next.0",
   "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-obs/references/common-pitfalls.md

@@ -54,10 +54,37 @@ hcloud OBS config -i
 
 KooCLI OBS **不支持** `SetBucketWebsite` 命令。配置静态网站托管需要：
 
-1. **REST API**: `PUT /?website` 到桶的 endpoint
-2. **控制台**: OBS 控制台 → 桶 → 静态网站托管 → 开启
+1. **MCP 工具**: `huaweicloud_obs_set_website_config`（插件内置，AWS4 签名处理，action=set/get/delete，实测可用）
+2. **REST API**: `PUT /?website` 到桶的 endpoint
+3. **控制台**: OBS 控制台 → 桶 → 静态网站托管 → 开启
 
-插件只能完成"上传文件 + 设置 ACL"，静态托管开关需用户手动完成。
+## Content-Disposition 强制下载陷阱（2022-01-01 后创建的桶）
+
+**实测发现（2026-10，cn-north-4）**：2022 年 1 月 1 日之后创建的 OBS 桶，对象 **GET 响应被 OBS 强制注入 `Content-Disposition: attachment`**——浏览器访问 HTML 一律下载而不是渲染，静态网站托管端点（`<bucket>.obs-website.<region>.myhuaweicloud.com`）也不例外，与对象元数据无关。
+
+| 请求方式                | 返回的 Content-Disposition   | 说明                       |
+| ----------------------- | ---------------------------- | -------------------------- |
+| GET（浏览器、在线预览） | `attachment`（OBS 强制注入） | 网页被下载，无法渲染       |
+| HEAD                    | 元数据中的值（如 inline）    | 会误导诊断，不是浏览器行为 |
+
+**避坑方法**：
+
+1. **验证网页行为必须用 GET 直连**（`curl -s -D - -o NUL <url>` 或浏览器）——HEAD 和代理层会给出假象
+2. **官方解法**：绑定自定义域名接入 **CDN**，在"CDN 控制台 > 域名管理 > 高级设置 > HTTP header 配置"设置 `Content-Disposition: inline`（参见华为云 CDN 文档《如何在浏览器中在线预览 OBS 中的对象？》）
+3. 跨云对照：阿里云 OSS 同样策略（Bucket 域名访问 HTML 强制下载，绑定自定义域名即可在线预览）
+
+**对静态托管的结论**：2022 年后创建的桶，裸 OBS（含 obs-website 端点）**无法交付可渲染的 web 站点**；自定义域名 + CDN（+ header 配置 inline）是**必要条件**，不是增强项。
+
+## obsutil 元数据大小写陷阱
+
+`cp -meta=content-disposition:inline`（小写）会被存为用户自定义元数据 `x-amz-meta-content-disposition`，**不命中标准头**；标准 HTTP 头（Content-Type、Content-Disposition、Cache-Control 等）必须按标准大小写书写：
+
+```bash
+# 错误：存为 x-amz-meta-content-disposition，浏览器不识别
+hcloud OBS cp index.html obs://<bucket>/ -meta=content-disposition:inline
+# 正确：命中标准 Content-Disposition 头
+hcloud OBS cp index.html obs://<bucket>/ -meta=Content-Disposition:inline
+```
 
 ## 权限模型（三层）
 

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

@@ -74,6 +74,7 @@ version: 2
 | `code=HDKIT_NOT_SIGNED_UP`（您尚未报名…）                               | 未报名该赛事                | 告知需先完成赛事报名后再来领取    |
 | `已领取过` / `已领取`                                                   | 该账号已领过赛事券          | 告知已领取，不打扰                |
 | `code=HDKIT_COMPETITION_NOT_FOUND`（赛事不存在或已下线）                | 赛事配置异常                | 告知赛事暂不可用，稍后再试        |
+| `code=HDKIT_COMPETITION_NOT_CONFIGURED`（赛事代金券服务配置缺失…）      | 服务端活动参数未配置        | 告知赛事代金券暂未开放，稍后再试  |
 | `本月代金券总额度已用完，所有账号均无法领取`                            | 全局额度用尽（HD.60630042） | 告知下月再试                      |
 | `请先完成实名认证`                                                      | 账号未实名（HD.60630022）   | 引导去控制台实名认证              |
 | `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK          |

package/plugins/huaweicloud-core/src/auth/credential-validator.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
 
 import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
+import { errorFromTable } from './guidance.mjs';
 
 function iamBaseUrl() {
   return process.env.HW_IAM_ENDPOINT || 'https://iam.myhuaweicloud.com';
@@ -81,15 +82,28 @@ function projectForRegion(projects, region) {
  * SDK-HMAC-SHA256 request signing. A wrong SK produces an invalid signature,
  * which IAM rejects with HTTP 401 before any project data is returned.
  *
- * Returns { valid, projectId, error, warning }:
+ * Returns { valid, projectId, error, warning, code, messageZh, action, nextStep }:
  * - valid: true when IAM verified the signature (or the rejection is not
  *   authentication-related), false when the credentials are unusable.
  * - projectId: first project matching `region`, else the first visible project.
  * - warning: set when credentials passed but project discovery was denied.
+ * - code/messageZh/action/nextStep: unified #900 shape from the shared
+ *   ERROR_TABLE (guidance.mjs). The English `error`/`warning` detail text is
+ *   intentionally kept — existing consumers (tools.mjs sandbox_credentials,
+ *   external string-matching tests) rely on it.
  */
 export async function validateIamCredentials({ ak, sk, securityToken, region, timeoutMs = 15000 } = {}) {
   if (!ak || !sk) {
-    return { valid: false, projectId: null, error: 'AK and SK are both required for credential validation.' };
+    const e = errorFromTable('HDKIT_CRED_MISSING');
+    return {
+      valid: false,
+      projectId: null,
+      error: 'AK and SK are both required for credential validation.',
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
+    };
   }
 
   const base = iamBaseUrl();
@@ -115,11 +129,16 @@ export async function validateIamCredentials({ ak, sk, securityToken, region, ti
       resp = await fetch(url, fetchOpts);
     }
   } catch (error) {
+    const e = errorFromTable('HDKIT_CRED_UNEXPECTED', error.message);
     return {
       valid: false,
       projectId: null,
       skipped: true,
       error: `IAM validation request failed (treating credentials as unverified): ${error.message}`,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
     };
   } finally {
     clearTimeout(timer);
@@ -138,26 +157,42 @@ export async function validateIamCredentials({ ak, sk, securityToken, region, ti
 
   if (resp.status === 401) {
     const msg = data?.error?.message || text.slice(0, 200);
+    const e = errorFromTable('HDKIT_CRED_INVALID', `HTTP 401: ${msg}`);
     return {
       valid: false,
       projectId: null,
       error: `IAM rejected the credentials (HTTP 401: ${msg}). The AK/SK is invalid - check the SK for typos or expired security tokens.`,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
     };
   }
 
   if (resp.status === 403) {
+    const msg = data?.error?.message || text.slice(0, 200);
+    const e = errorFromTable('HDKIT_CRED_FORBIDDEN', `HTTP 403: ${msg}`);
     return {
       valid: true,
       projectId: null,
       error: null,
       warning: `Credentials signed successfully but project listing was denied (HTTP 403). Continuing without project_id.`,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
     };
   }
 
+  const e = errorFromTable('HDKIT_CRED_UNEXPECTED', `HTTP ${resp.status}`);
   return {
     valid: false,
     projectId: null,
     skipped: true,
     error: `Unexpected IAM response (HTTP ${resp.status}): ${text.slice(0, 200)}`,
+    code: e.code,
+    messageZh: e.messageZh,
+    action: e.action,
+    nextStep: e.nextStep,
   };
 }

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

@@ -11,6 +11,8 @@ import {
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
+import { buildOnboardingSteps, makeError } from './guidance.mjs';
+
 // Verify a credential file ended up with 0600. On Windows-mounted drives inside WSL
 // (drvfs/9p) chmod is silently ignored, so the file can be world-readable (0777).
 // Native Windows has no POSIX modes (statSync always reports 0666), so skip the check there.
@@ -203,7 +205,8 @@ export function writeObsConfig(credentials = {}) {
   const sk = String(credentials.sk || '');
   const securityToken = String(credentials.securityToken || '');
   if (!region || !ak || !sk) {
-    throw new Error('region, ak, and sk are required to write OBS config');
+    // #900: unified error shape from the shared ERROR_TABLE.
+    throw makeError('HDKIT_CRED_REGION_MISSING');
   }
   const path = obsConfigPath();
   const endpoint = credentials.endpoint || `https://obs.${region}.myhuaweicloud.com`;
@@ -263,43 +266,25 @@ export function resolveCredentials(options = {}) {
 
   if (!ak || !sk) {
     if (options.allowMissing) return null;
-    const err = new Error(
-      'Huawei Cloud credentials are not configured. Run "npx huaweicloud-devkit auth init" or set HW_ACCESS_KEY/HW_SECRET_KEY.',
-    );
-    err.code = 'HDKIT_CRED_MISSING';
-    // Lightweight onboarding hint. HDKIT_CRED_MISSING fires when no credential
-    // resolved: with env empty/masked and S1 absent, the scenario is 3 by
-    // default. Scenario 4 (import a config-provided account) is only reachable
-    // in the narrow case where CodeArts S4 offers real creds that the resolver
-    // still couldn't adopt (e.g. CODEARTS_PROJECT_DIR set but the marker dir is
-    // absent). Full guidance comes from getAuthStatus(); keep this branch cheap.
+    // #900: unified guidance — one steps builder shared with computeOnboarding,
+    // and the error shape from the single ERROR_TABLE. Zero IO beyond the
+    // readCodeArtsCredentials() probe we already did above for scenario routing.
     const codeartsCreds = readCodeArtsCredentials();
     const injectedAvailable = present(codeartsCreds?.ak) && present(codeartsCreds?.sk);
+    const codearts = isCodeArtsContext();
+    const err = makeError('HDKIT_CRED_MISSING');
     err.onboarding = injectedAvailable
       ? {
           scenario: 4,
           reason: 'import-injected',
           message: '检测到配置中已有有效账号,可导入为正式凭证。',
-          steps: isCodeArtsContext()
-            ? [{ action: 'auth_switch', args: { mode: 'mcp-config', action: 'persist' }, label: '导入配置中的账号' }]
-            : [
-                {
-                  action: 'auth_switch',
-                  args: { mode: 'import', action: 'persist' },
-                  label: '通过 creds-import.json 导入',
-                },
-              ],
+          steps: buildOnboardingSteps(4, { codearts }),
         }
       : {
           scenario: 3,
           reason: 's1-missing',
           message: '未配置华为云凭证,需要完成登录后才能使用云能力。',
-          steps: isCodeArtsContext()
-            ? [
-                { action: 'write-import', target: join(homedir(), '.config', 'huaweicloud', 'creds-import.json') },
-                { action: 'auth_switch', args: { mode: 'import', action: 'persist' } },
-              ]
-            : [{ action: 'auth-init', args: {} }],
+          steps: buildOnboardingSteps(3, { codearts }),
         };
     throw err;
   }
@@ -320,7 +305,9 @@ export function getParentCwd() {
   }
 }
 
-function isCodeArtsContext() {
+// Exported for tests: the failure path and the tests must agree on which
+// onboarding variant (codearts vs plain) the current environment selects.
+export function isCodeArtsContext() {
   return (
     existsSync(join(process.cwd(), '.codeartsdoer')) ||
     existsSync(join(homedir(), '.codeartsdoer')) ||

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

@@ -0,0 +1,112 @@
+// plugins/huaweicloud-core/src/auth/guidance.mjs
+// Single Source of Truth for onboarding guidance steps and the error surface.
+// Leaf module: imports NOTHING from auth/ siblings. Zero IO — pure builders.
+// Callers: credentials.mjs (failure path), service.mjs (computeOnboarding),
+// credential-validator / reconcile / hcloud-probe (error shapes).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function buildOnboardingSteps(scenario, { codearts = false } = {}) {
+  switch (scenario) {
+    case 3: {
+      const base = [{ order: 1, action: 'obtain-aksk', target: 'console', label: '获取 AK/SK(华为云控制台)' }];
+      if (codearts) {
+        return [
+          ...base,
+          {
+            order: 2,
+            action: 'write-import',
+            target: join(homedir(), '.config', 'huaweicloud', 'creds-import.json'),
+            label: '把 AK/SK 写入 creds-import.json',
+          },
+          {
+            order: 3,
+            action: 'auth_switch',
+            // QA #905 Required: scenario-3 codearts flow writes creds-import.json
+            // in step 2, so the import must READ that file (mode:'import').
+            // mode:'mcp-config' reads the CodeArts injected environment, which
+            // is empty/placeholder in scenario 3 — the channel would not close.
+            args: { mode: 'import', action: 'persist' },
+            label: '执行导入完成配置',
+          },
+        ];
+      }
+      return [...base, { order: 2, action: 'auth-init', args: {}, label: '运行 npx huaweicloud-devkit auth init' }];
+    }
+    case 4:
+      return [
+        {
+          order: 1,
+          action: 'auth_switch',
+          args: { mode: codearts ? 'mcp-config' : 'import', action: 'persist' },
+          label: '导入该账号',
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+// #900 error contract table. messageZh: Chinese, human-readable, no English
+// sentences, no internal codenames. action: directly executable. nextStep is
+// kept as a derived compatibility field for existing consumers.
+export const ERROR_TABLE = {
+  HDKIT_CRED_MISSING: {
+    messageZh: '未配置华为云凭证,需要先完成登录。',
+    action: 'npx huaweicloud-devkit auth init',
+  },
+  HDKIT_CRED_INVALID: {
+    messageZh: '凭证已被华为云拒绝(AK/SK 无效或已过期),请重新生成。',
+    action: 'npx huaweicloud-devkit auth status',
+  },
+  HDKIT_CRED_FORBIDDEN: {
+    messageZh: '凭证有效但无权限列出项目,请检查账号授权。',
+    action: 'hcloud IAM KeystoneListProjects --cli-region=<region>',
+  },
+  HDKIT_CRED_REGION_MISSING: {
+    messageZh: '缺少 region(区域),登录配置不完整。',
+    action: 'hcloud configure set --cli-region=<region>',
+  },
+  HDKIT_KOOCLI_NOT_READY: {
+    messageZh: 'KooCLI(hcloud)未安装或未就绪。',
+    action: 'npx huaweicloud-devkit install-hcloud',
+  },
+  HDKIT_PROJECT_ID_MISSING: {
+    messageZh: 'KooCLI 配置缺少 project_id,导致同步失败。',
+    action: 'hcloud configure set --cli-project-id=<id>',
+  },
+  // Runtime credentials (in-process, set via auth_init/auth_switch) suppress
+  // auto-sync (rule R10). No `auth sync --force` flag exists; the real unblock
+  // is clearing the runtime store first, then re-running the sync.
+  HDKIT_SYNC_SKIPPED_RUNTIME: {
+    messageZh: '运行时凭证生效,自动同步已跳过。',
+    action: 'huaweicloud_auth_switch action=clear',
+  },
+  // IAM returned something other than 200/401/403 (or the request itself
+  // failed). The canonical debug hint lives in the cli-and-auth skill.
+  HDKIT_CRED_UNEXPECTED: {
+    messageZh: '凭证校验遇到异常响应,请开启调试排查。',
+    action: 'hcloud <Service> <Op> --cli-debug=true',
+  },
+};
+
+export function errorFromTable(code, detail) {
+  const e = ERROR_TABLE[code];
+  if (!e) return { code, messageZh: detail || String(code), action: '', nextStep: detail || '' };
+  return {
+    code,
+    messageZh: detail ? `${e.messageZh}(${detail})` : e.messageZh,
+    action: e.action,
+    nextStep: e.action,
+  };
+}
+
+export function makeError(code, detail) {
+  const shape = errorFromTable(code, detail);
+  const err = new Error(shape.messageZh);
+  err.code = shape.code;
+  err.action = shape.action;
+  err.nextStep = shape.nextStep;
+  err.messageZh = shape.messageZh;
+  return err;
+}

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

@@ -12,6 +12,7 @@ import {
   readLastSync,
   resolveCredentialsWithRuntime,
 } from './credentials.mjs';
+import { errorFromTable } from './guidance.mjs';
 import { resolveHcloudCommand } from '../hcloud-probe.mjs';
 import { redactSecrets } from '../safety-policy.mjs';
 
@@ -43,7 +44,12 @@ export function isManualModified(path) {
 
 export function readKooCliProfiles() {
   const configPath = kooCliConfigPath();
-  if (!existsSync(configPath)) return { error: 'KooCLI config not found' };
+  if (!existsSync(configPath)) {
+    // #900: bare string replaced by the unified ERROR_TABLE shape; the old
+    // English text survives only as the distinguishing detail argument.
+    const e = errorFromTable('HDKIT_KOOCLI_NOT_READY', 'KooCLI config not found');
+    return { error: e.messageZh, code: e.code, messageZh: e.messageZh, action: e.action, nextStep: e.nextStep };
+  }
   try {
     const raw = JSON.parse(readFileSync(configPath, 'utf8'));
     const current = String(raw.current || 'default');
@@ -72,7 +78,9 @@ export function readKooCliProfiles() {
       ),
     };
   } catch {
-    return { error: 'KooCLI config parse failed' };
+    // #900: bare string replaced by the unified ERROR_TABLE shape.
+    const e = errorFromTable('HDKIT_KOOCLI_NOT_READY', 'KooCLI config parse failed');
+    return { error: e.messageZh, code: e.code, messageZh: e.messageZh, action: e.action, nextStep: e.nextStep };
   }
 }
 

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

@@ -1,11 +1,10 @@
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 
 import { getAgentRegistrationStatuses } from './agent-registration.mjs';
 import { resolveAndApplyProjectId } from './project-id.mjs';
 import {
   globalCredentialsPath,
+  isCodeArtsContext,
   isPlaceholder,
   obsConfigPath,
   parseStsExpiry,
@@ -15,6 +14,7 @@ import {
   writeLastSync,
   writeObsConfig,
 } from './credentials.mjs';
+import { buildOnboardingSteps, errorFromTable } from './guidance.mjs';
 import {
   fingerprint,
   exportStateForStatus,
@@ -22,15 +22,7 @@ import {
   resolveManagedProfile,
   runHcloudConfigure,
 } from './reconcile.mjs';
-import { hcloudProbeNextStep, probeHcloud } from '../hcloud-probe.mjs';
-
-function isCodeArtsHome() {
-  return (
-    existsSync(join(process.cwd(), '.codeartsdoer')) ||
-    existsSync(join(homedir(), '.codeartsdoer')) ||
-    existsSync(join(homedir(), '.codeartswork'))
-  );
-}
+import { hcloudProbeNextStep, hcloudProbeRaw, probeHcloud } from '../hcloud-probe.mjs';
 
 function envHasRealTriplet() {
   return (
@@ -57,7 +49,9 @@ export function computeOnboarding({ credentials, reconciled } = {}) {
   const envRealAk = !isPlaceholder(process.env.HW_ACCESS_KEY) && Boolean(process.env.HW_ACCESS_KEY);
   const envRealSk = !isPlaceholder(process.env.HW_SECRET_KEY) && Boolean(process.env.HW_SECRET_KEY);
   const envHasCreds = envRealAk && envRealSk;
-  const codeArts = isCodeArtsHome();
+  // Same context detector the resolveCredentials failure path uses (#900): the
+  // codearts flag must select the identical builder variant on both paths.
+  const codeArts = isCodeArtsContext();
   const accountHint = s1Has ? fingerprint(creds.ak, creds.sk) : null;
 
   let scenario;
@@ -133,32 +127,12 @@ export function computeOnboarding({ credentials, reconciled } = {}) {
     scenario = 4;
     reason = 'import-injected';
     message = '检测到配置中已有有效账号,可导入为正式凭证。';
-    steps = [
-      {
-        order: 1,
-        action: 'switch-persist',
-        args: { mode: codeArts ? 'mcp-config' : 'import', action: 'persist' },
-        label: '导入该账号',
-      },
-    ];
+    steps = buildOnboardingSteps(4, { codearts: codeArts });
   } else {
     scenario = 3;
     reason = 's1-missing';
     message = '未配置华为云凭证,需要完成登录后才能使用云能力。';
-    steps = [
-      { order: 1, action: 'obtain-aksk', target: 'console', label: '获取 AK/SK(华为云控制台)' },
-      ...(codeArts
-        ? [
-            {
-              order: 2,
-              action: 'write-import',
-              target: join(homedir(), '.config', 'huaweicloud', 'creds-import.json'),
-              label: '把 AK/SK 写入 creds-import.json',
-            },
-            { order: 3, action: 'auth_switch', args: { mode: 'import', action: 'persist' }, label: '执行导入完成配置' },
-          ]
-        : [{ order: 2, action: 'auth-init', args: {}, label: '运行 npx huaweicloud-devkit auth init' }]),
-    ];
+    steps = buildOnboardingSteps(3, { codearts: codeArts });
   }
 
   return { needsSetup: true, scenario, reason, message, steps, accountHint };
@@ -215,6 +189,7 @@ export function getAuthStatus(target = 'all') {
     kooCliInstalled: hcloud.installed,
     kooCliStatus: hcloud.status,
     kooCliNextStep: hcloudProbeNextStep(hcloud),
+    kooCliRaw: hcloudProbeRaw(hcloud),
     reconciled,
     onboarding,
     agents: getAgentRegistrationStatuses(target).agents,
@@ -224,17 +199,28 @@ export function getAuthStatus(target = 'all') {
 export function syncAuth(target = 'all') {
   const credentials = readGlobalCredentials();
   if (!credentials?.ak || !credentials?.sk) {
+    // #900: unified error shape from the shared ERROR_TABLE.
+    const e = errorFromTable('HDKIT_CRED_MISSING');
     return {
       ok: false,
-      error: 'Global credentials are not configured.',
-      nextStep: 'Run "npx huaweicloud-devkit auth init" first.',
+      error: e.messageZh,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
     };
   }
   if (hasRuntimeCredentials()) {
+    // R10: runtime credentials suppress auto-sync. The codename stays in code
+    // comments only, never in user-facing strings (#900).
+    const e = errorFromTable('HDKIT_SYNC_SKIPPED_RUNTIME');
     return {
       ok: false,
-      error: 'Runtime credentials are active; auto-sync suppressed (R10).',
-      nextStep: 'Run huaweicloud_auth_switch action=clear or action=persist first.',
+      error: e.messageZh,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: e.nextStep,
     };
   }
 
@@ -264,25 +250,47 @@ export function syncAuth(target = 'all') {
 
   const hcloud = probeHcloud();
   if (!hcloud.ok) {
+    // #900: three probe states share the table code; the detail distinguishes.
+    const detail =
+      hcloud.status === 'sandbox_home_failure'
+        ? '无法解析用户主目录'
+        : hcloud.status === 'privacy_pending'
+          ? '隐私协议待同意'
+          : '';
+    const e = errorFromTable('HDKIT_KOOCLI_NOT_READY', detail);
     return {
       ok: false,
-      error:
-        hcloud.status === 'sandbox_home_failure'
-          ? 'KooCLI detected but cannot resolve the user home directory in this agent sandbox.'
-          : hcloud.status === 'privacy_pending'
-            ? 'KooCLI privacy agreement is pending.'
-            : 'KooCLI not ready.',
+      error: e.messageZh,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      // #900 issue comment: nextStep is the executable table action; the
+      // verbose English guidance survives only in the `raw` side-channel.
       nextStep: hcloudProbeNextStep(hcloud),
+      raw: hcloudProbeRaw(hcloud),
       obs: { configured: true, path: obs.path, endpoint: obs.endpoint },
     };
   }
 
   const { ok, error } = runHcloudConfigure(profile, credentials.ak, credentials.sk, credentials.region);
   if (!ok) {
+    // #900: `hcloud configure set` failures are usually a missing/invalid
+    // project_id for the target region; anything else keeps the raw (already
+    // redacted) stderr as the detail argument.
+    const detail = String(error || '').trim();
+    const projectIdCause = /project[_\s-]?id/i.test(detail);
+    const e = projectIdCause
+      ? errorFromTable('HDKIT_PROJECT_ID_MISSING', detail)
+      : errorFromTable('HDKIT_KOOCLI_NOT_READY', detail || 'KooCLI 配置同步失败');
     return {
       ok: false,
-      error: error || 'KooCLI config sync failed',
-      nextStep: 'Run "npx huaweicloud-devkit auth init" in a real terminal to refresh the KooCLI config.',
+      error: e.messageZh,
+      code: e.code,
+      messageZh: e.messageZh,
+      action: e.action,
+      nextStep: projectIdCause
+        ? e.nextStep
+        : 'Run "npx huaweicloud-devkit auth init" in a real terminal to refresh the KooCLI config.',
       obs: { configured: true, path: obs.path, endpoint: obs.endpoint },
     };
   }

package/plugins/huaweicloud-core/src/hcloud-probe.mjs

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { errorFromTable } from './auth/guidance.mjs';
 import { compareVersion, getKooCliVersion, parseHcloudVersion } from './koocli-version.mjs';
 import { kooCliInstallLogPath } from './preflight.mjs';
 import { redactSecrets } from './safety-policy.mjs';
@@ -140,19 +141,24 @@ export function probeHcloud(options = {}) {
   };
 }
 
-export function hcloudProbeNextStep(probe) {
-  if (probe.status === 'ok')
+// #900 (issue comment Required 1): every not-ready probe state routes through
+// the shared ERROR_TABLE.HDKIT_KOOCLI_NOT_READY so nextStep is always a
+// directly executable command (d11-41-nextstep-actionable). The verbose
+// English guidance is preserved verbatim in hcloudProbeRaw() — a docs/debug
+// side-channel — and must never leak back into the top-level nextStep.
+export function hcloudProbeRaw(probe) {
+  if (probe?.status === 'ok')
     return 'Use huaweicloud_show_profile_redacted to inspect the active KooCLI profile safely.';
-  if (probe.status === 'version_mismatch') {
+  if (probe?.status === 'version_mismatch') {
     return `KooCLI version mismatch: installed ${probe.installedVersion}, this plugin is paired with ${probe.requiredVersion}. Reinstall the pinned version (see huaweicloud-cli-and-auth skill) and restart the agent.`;
   }
-  if (probe.status === 'sandbox_home_failure') {
+  if (probe?.status === 'sandbox_home_failure') {
     return 'KooCLI was found, but this agent sandbox cannot resolve the Windows user home directory. Set HCLOUD_BIN to the full hcloud path, restart Codex, or verify from a normal terminal.';
   }
-  if (probe.status === 'privacy_pending') {
+  if (probe?.status === 'privacy_pending') {
     return 'KooCLI requires accepting its one-time privacy agreement. Run hcloud version in a real terminal and accept the prompt, then restart the agent.';
   }
-  if (probe.status === 'not_found') {
+  if (probe?.status === 'not_found') {
     return (
       'KooCLI is not installed yet. Background auto-install may be running — please retry shortly instead of assuming failure. To install now: npx huaweicloud-devkit install-hcloud. DevKit picks up the binary from its fixed install dirs (~/.local/bin on Linux, /usr/local/bin on macOS, ~/hcloud on Windows) or HCLOUD_BIN on the next call — no agent restart needed. Install progress: ' +
       kooCliInstallLogPath()
@@ -160,3 +166,17 @@ export function hcloudProbeNextStep(probe) {
   }
   return 'Install Huawei Cloud KooCLI: npx huaweicloud-devkit install-hcloud. Configure credentials outside the agent conversation.';
 }
+
+export function hcloudProbeNextStep(probe) {
+  if (probe?.status === 'ok') return 'huaweicloud_show_profile_redacted';
+  const detail =
+    probe?.status === 'version_mismatch'
+      ? `版本不匹配(已装 ${probe?.installedVersion ?? '未知'},插件配套 ${probe?.requiredVersion ?? '未知'})`
+      : probe?.status === 'sandbox_home_failure'
+        ? '无法解析用户主目录'
+        : probe?.status === 'privacy_pending'
+          ? '隐私协议待同意'
+          : '';
+  const e = errorFromTable('HDKIT_KOOCLI_NOT_READY', detail);
+  return e.nextStep;
+}

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

@@ -65,7 +65,7 @@ import {
   resolveSkipFilePath,
   upgradePackage,
 } from './update-check.mjs';
-import { hcloudProbeNextStep, probeHcloud } from './hcloud-probe.mjs';
+import { hcloudProbeNextStep, hcloudProbeRaw, probeHcloud } from './hcloud-probe.mjs';
 import { isUsableOfficeaceRoot, readOfficeaceRootMarker } from './officeace-paths.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1662,6 +1662,7 @@ export async function runVersionCheck(options = {}) {
     installedVersion: result.installedVersion || undefined,
     versionMismatch: Boolean(result.versionMismatch),
     nextStep: hcloudProbeNextStep(result),
+    raw: hcloudProbeRaw(result),
     authHint:
       'If hcloud is installed but commands fail with "配置文件中不存在配置项", run `npx huaweicloud-devkit auth init` outside agent chat to configure credentials.',
   };