huaweicloud-devkit 1.1.4-next.0 → 1.1.4-next.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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.4-next.0",
+  "version": "1.1.4-next.2",
   "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-billing/SKILL.md

@@ -16,14 +16,14 @@ Domain expertise for billing queries (BSS). Covers cost tracking, bill details,
 
 ## Critical Warnings
 
-| Trap                                      | Why                                                                                                                                                                                                                                                                                                                     |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Bills delayed ~24h                        | Yesterday's costs may not appear until the next day                                                                                                                                                                                                                                                                     |
-| BSS Admin role needed                     | IAM user must have BSS Administrator or Finance role                                                                                                                                                                                                                                                                    |
-| Currency conversion varies                | Cross-region costs use daily exchange rates                                                                                                                                                                                                                                                                             |
-| Region fixed to cn-north-1                | BSS operations only support `--cli-region=cn-north-1` in KooCLI. This is a KooCLI metadata limitation — the billing data itself covers all regions.                                                                                                                                                                     |
-| English catalog missing BSS               | `Unsupported service: BSS` under the default `en` language is a KooCLI catalog gap, not a missing service. devkit auto-injects `--cli-lang=cn`; manual fallback: add `--cli-lang=cn` or `hcloud configure set --cli-lang=cn` — prefer `--cli-lang=cn` on the command itself so the global output language is untouched. |
-| `缺少必填参数 cli-domain-id` / APIGW.0301 | Invalid credentials — KooCLI can't resolve the account-id                                                                                                                                                                                                                                                               | Re-run `npx huaweicloud-devkit auth init` |
+| Trap                                      | Why                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bills delayed ~24h                        | Yesterday's costs may not appear until the next day                                                                                                                                                                                                                                                                                                           |
+| BSS Admin role needed                     | IAM user must have BSS Administrator or Finance role                                                                                                                                                                                                                                                                                                          |
+| Currency conversion varies                | Cross-region costs use daily exchange rates                                                                                                                                                                                                                                                                                                                   |
+| Region fixed to cn-north-1                | BSS operations only support `--cli-region=cn-north-1` in KooCLI. This is a KooCLI metadata limitation — the billing data itself covers all regions.                                                                                                                                                                                                           |
+| English catalog missing BSS               | `Unsupported service: BSS` under the default `en` language is a KooCLI catalog gap, not a missing service. devkit detects it and advises the supported fix `hcloud configure set --cli-lang=cn` (switch is global-only; KooCLI has no per-command `--cli-lang` flag). Running with Chinese mode from the start (see Prerequisites) avoids the issue entirely. |
+| `缺少必填参数 cli-domain-id` / APIGW.0301 | Invalid credentials — KooCLI can't resolve the account-id                                                                                                                                                                                                                                                                                                     | Re-run `npx huaweicloud-devkit auth init` |
 
 ## Common Workflows
 

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

@@ -58,7 +58,7 @@ Flavor families are **region-dependent**. Always run `hcloud ECS ListFlavors --c
 | Create instance     | hcloud ECS CreateServers --server.name=<n> --server.flavorRef=<id> --server.imageRef=<id> --server.nics.1.subnet_id=<id> --server.availability_zone=<az> | references/create-instance.md                                                            |
 | Find by name        | See "How to search for instances" below                                                                                                                  |                                                                                          |
 | Bind EIP            | hcloud EIP AssociatePublicips --publicip_id=<id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT                      | Get port ID from `hcloud ECS ListServersDetails --server_id=<id>` → `OS-EXT-IPS:port_id` |
-| Security group rule | hcloud VPC CreateSecurityGroupRule --security_group_id=<id> --direction=<direction> --protocol=<protocol>                                                | references/sg.md                                                                         |
+| Security group rule | hcloud VPC CreateSecurityGroupRule --security_group_id=<id> --direction=<direction> --protocol=<protocol>                                                | see huawei-vpc                                                                           |
 | Attach disk         | hcloud ECS AttachServerVolume --server_id=<id> --volumeAttachment.volumeId=<id>                                                                          | references/evs.md                                                                        |
 | Delete instance     | hcloud ECS DeleteServers --servers.1.id=<id> --delete_publicip=true --delete_volume=true                                                                 | references/create-instance.md                                                            |
 | Reboot instance     | hcloud ECS BatchRebootServers --reboot.servers.1.id=<id> --reboot.type=SOFT                                                                              | NOT `RebootServer` — that operation does not exist                                       |

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

@@ -45,12 +45,12 @@ Domain expertise for Huawei Cloud Identity and Access Management (IAM). Covers u
 
 | Task                     | Command                                                                                                                     | Steps                         |
 | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| List users               | hcloud IAM KeystoneListUsers --cli-region=<r>                                                                               | references/iam-ops.md         |
-| Create group             | hcloud IAM CreateGroupV5 --group_name=<name>                                                                                | references/iam-ops.md         |
+| List users               | hcloud IAM KeystoneListUsers --cli-region=<r>                                                                               | references/quick-ref.md       |
+| Create group             | hcloud IAM CreateGroupV5 --group_name=<name>                                                                                | references/quick-ref.md       |
 | Create custom policy     | hcloud IAM CreateCloudServiceCustomPolicy --role.display_name=<n> --role.type=<type> --role.policy.Statement.1.Effect=Allow | references/policy-examples.md |
-| Create agency            | hcloud IAM CreateAgency --agency.name=<n> --agency.domain_id=<id> --agency.trust_domain_name=<domain>                       | references/agency.md          |
-| Get temporary credential | hcloud STS AssumeAgency --agency_urn=<urn> --agency_session_name=<n> --duration_seconds=3600                                | references/sts.md             |
-| Attach policy to group   | hcloud IAM AttachGroupPolicyV5 --group_id=<id> --policy_id=<id>                                                             | references/iam-ops.md         |
+| Create agency            | hcloud IAM CreateAgency --agency.name=<n> --agency.domain_id=<id> --agency.trust_domain_name=<domain>                       | references/quick-ref.md       |
+| Get temporary credential | hcloud STS AssumeAgency --agency_urn=<urn> --agency_session_name=<n> --duration_seconds=3600                                | references/quick-ref.md       |
+| Attach policy to group   | hcloud IAM AttachGroupPolicyV5 --group_id=<id> --policy_id=<id>                                                             | references/quick-ref.md       |
 
 ## Policy Examples (Least Privilege)
 
@@ -109,4 +109,4 @@ Common roles for FunctionGraph: VPC Administrator, RDS Administrator, DCS Admini
 
 - IAM Docs: https://support.huaweicloud.com/iam/
 - Policy examples: references/policy-examples.md
-- Agency setup: references/agency.md
+- Agency setup: references/quick-ref.md

package/plugins/huaweicloud-core/skills/huawei-iam/references/quick-ref.md

@@ -7,11 +7,46 @@ hcloud IAM KeystoneListProjects                  # list projects
 hcloud IAM KeystoneListUsers                     # list users
 hcloud IAM KeystoneListGroups                    # list groups
 hcloud IAM ListCustomPolicies                    # list custom policies
-hcloud IAM ListAgencies                          # list agencies
+hcloud IAM ListAgencies --domain_id=<domain-id>  # list agencies
 hcloud IAM KeystoneListAuthDomains               # list domains
 hcloud IAM KeystoneShowUser                      # show user detail
 ```
 
+> **Group lifecycle uses the V5 API, not Keystone.** `CreateGroupV5` / `AttachGroupPolicyV5` take `group_id`/`policy_id`; `KeystoneListGroups` is the older read API. The V5 group `description` forbids `@ # % & < > \ $ ^ *`.
+
+```bash
+hcloud IAM CreateGroupV5 --group_name=<name>
+hcloud IAM AttachGroupPolicyV5 --group_id=<id> --policy_id=<id>
+```
+
+## Agencies & Temporary Credentials (STS)
+
+An agency + `STS AssumeAgency` is the only safe way to mint temporary credentials (never store long-term AK/SK):
+
+1. Create the delegation:
+
+   ```bash
+   hcloud IAM CreateAgency --agency.name=<name> --agency.domain_id=<domain-id> --agency.trust_domain_name=<trust-domain>
+   ```
+
+   `--agency.trust_domain_name` and `--agency.trust_domain_id` are two ways to name the entrusted account — provide at least one; when both are present, `trust_domain_name` wins validation.
+
+2. Grant a role to the agency (optional):
+
+   ```bash
+   hcloud IAM AssociateAgencyWithDomainPermission --agency_id=<id> --role_id=<role-id>
+   ```
+
+3. Exchange for temporary credentials:
+
+   ```bash
+   hcloud STS AssumeAgency --agency_urn=<urn> --agency_session_name=<name> --duration_seconds=3600
+   ```
+
+   - `--agency_urn` is the agency **URN**, not its name or id — query it with `hcloud IAM ListAgencies --domain_id=<domain-id>` first.
+   - `--duration_seconds` range is `[900, 43200]`; it must not exceed the agency's own session duration, and is capped at `3600` when `--X-Security-Token` is present.
+   - The returned credential includes a `security_token` — pass it as `--X-Security-Token` for subsequent calls.
+
 ## Credential Management
 
 ```bash

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

@@ -131,4 +131,3 @@ See `references/single-file-share.md` for the full workflow to host one file and
 - Static website: references/static-website.md
 - Single-file share: references/single-file-share.md
 - Lifecycle: references/bucket-lifecycle.md
-- Replication: references/replication.md

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

@@ -43,8 +43,8 @@ Domain expertise for Huawei Cloud Virtual Private Cloud (VPC). Covers VPC/subnet
 | SG rule         | hcloud VPC CreateSecurityGroupRule --security_group_rule.security_group_id=<id> --security_group_rule.direction=<direction> --security_group_rule.protocol=<protocol> --security_group_rule.multiport=<port> --security_group_rule.remote_ip_prefix=<cidr> | references/security-group.md                                                                                         |
 | Create EIP      | hcloud EIP CreatePublicip --publicip.type=<type> --bandwidth.size=<size> --bandwidth.share_type=<share-type> --bandwidth.name=<name>                                                                                                                       | Run `hcloud EIP CreatePublicip --help` to confirm valid type values per region                                       |
 | Bind EIP to ECS | hcloud EIP AssociatePublicips --publicip_id=<id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT                                                                                                                        | Get port ID from `hcloud ECS ListServersDetails --server_id=<id>` → `OS-EXT-IPS:port_id`                             |
-| Unbind EIP      | hcloud EIP DisassociatePublicips --publicip_id=<id>                                                                                                                                                                                                        | references/eip.md                                                                                                    |
-| Delete EIP      | hcloud EIP DeletePublicip --publicip_id=<id>                                                                                                                                                                                                               | references/eip.md                                                                                                    |
+| Unbind EIP      | hcloud EIP DisassociatePublicips --publicip_id=<id>                                                                                                                                                                                                        | references/network.md                                                                                                |
+| Delete EIP      | hcloud EIP DeletePublicip --publicip_id=<id>                                                                                                                                                                                                               | references/network.md                                                                                                |
 | List EIPs       | hcloud EIP ListPublicips                                                                                                                                                                                                                                   |                                                                                                                      |
 | NAT gateway     | hcloud NAT CreateNatGateway --nat.name=<name> --nat.spec=<spec> --router_id=<vpc-id> --internal_network_id=<subnet-id>                                                                                                                                     | Run `hcloud NAT CreateNatGateway --help` for available spec values                                                   |
 

package/plugins/huaweicloud-core/skills/huaweicloud-cli-and-auth/SKILL.md

@@ -109,8 +109,8 @@ If a command needs an `adminPass` or other password field, do not leave plaintex
 ## Language / Service Catalog Trap
 
 - KooCLI loads the service list from a per-language catalog: `~/.hcloud/metaRepo/services_{cn,en}.json`. The **English catalog is incomplete** (149 services vs 220 in Chinese; ~70 services — BSS, DevStar, CloudTable, FRS, ASM, ... — are missing). A command against a service that only exists in the Chinese catalog fails with a misleading `Unsupported service: X`.
-- `huaweicloud-devkit` auto-injects `--cli-lang=cn` (proactive when the catalog shows `X ∈ cn ∧ X ∉ en`, reactive once if `Unsupported service` still appears) for read and write commands; approved write commands keep their approved argument list (injection happens inside the runner).
-- Manual fallback (do not rely on the auto path alone): append `--cli-lang=cn` to the failing command, or set globally with `hcloud configure set --cli-lang=cn` (this changes ALL CLI output language).
+- KooCLI has **no per-command `--cli-lang` flag** — appending `--cli-lang=cn` is rejected as `不正确的参数:cli-lang`. The language switch is **global only**: `hcloud configure set --cli-lang=cn` (changes ALL CLI output language).
+- `huaweicloud-devkit` detects `Unsupported service: X` and, when the cause is the en-catalog gap, returns an actionable hint to run `hcloud configure set --cli-lang=cn` (or to check the service name / refresh metadata for genuinely unknown services). It never mutates your command.
 - Distinguish from **region** metadata limits (e.g., BSS only supports `cn-north-1`): a region error is NOT solved by switching language.
 
 ## Output Formatting

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

@@ -57,10 +57,13 @@ export function syncAuth(target = 'all') {
   try {
     obs = writeObsConfig(credentials);
   } catch (error) {
+    const missingRegion = !String(credentials?.region || '').trim();
     return {
       ok: false,
       error: error.message,
-      nextStep: 'Run "npx huaweicloud-devkit auth init" to refresh credentials and region.',
+      nextStep: missingRegion
+        ? 'Credential region is missing — run huaweicloud_auth_switch action=persist with --region, or add "region" to creds-import.json and re-import.'
+        : 'Run "npx huaweicloud-devkit auth init" to refresh credentials and region.',
     };
   }
 

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

@@ -196,24 +196,6 @@ function obsWriteHint(args) {
   return 'OBS write operations are obsutil-style and always write-class. Before executing, present the full resource manifest (bucket/object list) to the user for ONE batch approval, then run each command through plan → approve (see huawei-iac skill, Provisioning Rules).';
 }
 
-const OBS_SUBCOMMANDS = new Set([
-  'help',
-  'ls',
-  'mb',
-  'cp',
-  'mv',
-  'rm',
-  'chattri',
-  'config',
-  'cors',
-  'lifecycle',
-  'policy',
-  'share',
-  'sync',
-  'url',
-  'sign',
-]);
-
 const CATALOG_TTL_MS = 5 * 60 * 1000;
 let _catalogCache = { dir: null, t: 0, cn: new Set(), en: new Set() };
 
@@ -252,19 +234,9 @@ export function classifyUnsupported(service, metaDir) {
   }
   // One or both catalog files are missing locally — we cannot distinguish
   // "service missing from the en catalog" from "en catalog not downloaded".
-  // Only the reactive fallback may attempt --cli-lang=cn for this case.
   return 'unknown';
 }
 
-export function shouldInjectLang(args, metaDir) {
-  const arr = Array.isArray(args) ? args.map(String) : [];
-  if (arr.some((a) => /^--cli-lang=/.test(a))) return false;
-  const s = (arr[0] || '').toUpperCase();
-  if (!s) return false;
-  if (s === 'OBS' && OBS_SUBCOMMANDS.has((arr[1] || '').toLowerCase())) return false;
-  return classifyUnsupported(s, metaDir) === 'lang-missing';
-}
-
 export function planHcloudCommand(args, options = {}) {
   const normalizedArgs = Array.isArray(args) ? args.map(String) : [];
   const classification = classifyHcloudArgs(normalizedArgs, options);
@@ -301,7 +273,8 @@ const UNSUPPORTED_SERVICE_RE = /Unsupported service:\s*([A-Za-z0-9_-]+)/i;
 function appendLangHint(result, service, metaDir) {
   const cause = classifyUnsupported(service, metaDir);
   if (cause === 'lang-missing' || cause === 'unknown') {
-    const nextStep = 'Re-run with --cli-lang=cn, or set hcloud configure set --cli-lang=cn.';
+    const nextStep =
+      'KooCLI switches language only via global config: hcloud configure set --cli-lang=cn (changes CLI output language; BSS requires Chinese mode).';
     return {
       ...result,
       langCause: cause,
@@ -318,16 +291,6 @@ function appendLangHint(result, service, metaDir) {
   };
 }
 
-function isObsUtilStyle(args) {
-  const s = String(args[0] || '').toUpperCase();
-  return s === 'OBS' && OBS_SUBCOMMANDS.has(String(args[1] || '').toLowerCase());
-}
-
-function canRetryLang(service, metaDir) {
-  const cause = classifyUnsupported(service, metaDir);
-  return cause === 'lang-missing' || cause === 'unknown';
-}
-
 export async function runHcloud(args, options = {}) {
   const normalizedArgs = Array.isArray(args) ? args.map(String) : [];
   const plan = {
@@ -337,44 +300,13 @@ export async function runHcloud(args, options = {}) {
   assertAllowed(plan.classification);
 
   const metaDir = options.metaDir;
-  const langGiven = normalizedArgs.some((a) => /^--cli-lang=/.test(a));
-  const injectedArgs =
-    !langGiven && shouldInjectLang(normalizedArgs, metaDir) ? [...normalizedArgs, '--cli-lang=cn'] : null;
-
-  if (injectedArgs) {
-    const result = await runHcloudOnceWithRetries(
-      {
-        ...plan,
-        rawArgs: injectedArgs,
-      },
-      options,
-    );
-    const tagged = {
-      ...result,
-      autoRetried: true,
-      injection: 'proactive',
-      injectedLang: 'cn',
-    };
-    if (tagged.ok) return tagged;
-    const match = `${result.stderr || ''}\n${result.stdout || ''}`.match(UNSUPPORTED_SERVICE_RE);
-    return match ? appendLangHint(tagged, match[1], metaDir) : tagged;
-  }
 
+  // KooCLI only switches language globally (`hcloud configure set --cli-lang=cn`); there is no
+  // per-command `--cli-lang` flag (it is rejected as "不正确的参数:cli-lang"). So we never mutate
+  // the command — we run it as-is and annotate `Unsupported service` with an actionable cause.
   const result = await runHcloudOnceWithRetries(plan, options);
   const text = `${result.stderr || ''}\n${result.stdout || ''}`;
   const match = text.match(UNSUPPORTED_SERVICE_RE);
-  if (match && !langGiven && !result.ok && canRetryLang(match[1], metaDir) && !isObsUtilStyle(normalizedArgs)) {
-    const retry = await runHcloudOnceWithRetries(
-      {
-        ...plan,
-        rawArgs: [...normalizedArgs, '--cli-lang=cn'],
-      },
-      options,
-    );
-    return retry.ok
-      ? { ...retry, autoRetried: true, reactiveFallback: true, injection: 'reactive', injectedLang: 'cn' }
-      : appendLangHint(retry, match[1], metaDir);
-  }
   if (match && !result.ok) {
     return appendLangHint(result, match[1], metaDir);
   }

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

@@ -961,9 +961,23 @@ function readImportFile() {
       region: String(data.region || ''),
     };
   } catch {
+    // Malformed/undecodable import file is un-replayable — wipe it. A VALID
+    // file is kept so a rejected persist can be replayed (see #502).
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      // ignore
+    }
     return null;
-  } finally {
+  }
+}
+
+function clearImportFile() {
+  const path = join(dirname(globalCredentialsPath()), 'creds-import.json');
+  try {
     rmSync(path, { force: true });
+  } catch {
+    // best-effort: an absent or locked file is not an error
   }
 }
 
@@ -996,7 +1010,7 @@ function persistCredentials(ak, sk, securityToken, region) {
     writeLastSync({ kooCliProfile: profile, s1Fingerprint: fingerprint(ak, sk) });
   }
   return {
-    status: 'ok',
+    status: obs.ok && hcloud.ok ? 'ok' : 'partial',
     scope: 'persist',
     backedUp: Boolean(before),
     obs: obs.ok ? { configured: true } : { configured: false, error: obs.error },
@@ -1124,10 +1138,14 @@ export async function callTool(name, rawArgs = {}) {
       let securityToken = args.securityToken || '';
       let region = args.region || '';
       const sourceChannel = args.mode || 'memory';
+      let importedFromFile = false;
 
       if (sourceChannel === 'import' && (!ak || !sk)) {
         const imported = readImportFile();
-        if (imported) ({ ak, sk, securityToken, region } = imported);
+        if (imported) {
+          ({ ak, sk, securityToken, region } = imported);
+          importedFromFile = true;
+        }
       }
       if (sourceChannel === 'mcp-config' && (!ak || !sk)) {
         const cc = readCodeArtsCredentials();
@@ -1143,9 +1161,19 @@ export async function callTool(name, rawArgs = {}) {
         throw new Error('ak and sk are required (or provide creds-import.json for mode=import).');
       }
 
+      if (action === 'persist' && !String(region || '').trim()) {
+        return {
+          status: 'error',
+          scope: 'invalid_region',
+          error:
+            'region is required to persist credentials. Pass --region, or include "region" in creds-import.json (mode=import).',
+        };
+      }
+
       if (action === 'temporary') {
         setRuntimeCredentials(ak, sk, securityToken || undefined, region);
         refreshUserHashAfterAuthChange();
+        if (importedFromFile) clearImportFile();
         return {
           status: 'ok',
           scope: 'temporary',
@@ -1166,6 +1194,7 @@ export async function callTool(name, rawArgs = {}) {
           newRegion: region,
           oldFingerprint: fingerprint(prev.ak, prev.sk),
           newFingerprint: fingerprint(ak, sk),
+          fromImport: importedFromFile,
         });
         return {
           status: 'needs_confirmation',
@@ -1178,6 +1207,10 @@ export async function callTool(name, rawArgs = {}) {
       }
 
       const persisted = persistCredentials(ak, sk, securityToken, region);
+      // Clear the import file for non-replayable outcomes (success, or an
+      // unfixable rejection such as STS R3). Keep it only for a retryable
+      // 'partial' (S1 written but a mirror failed).
+      if (importedFromFile && persisted.status !== 'partial') clearImportFile();
       refreshUserHashAfterAuthChange();
       return persisted;
     }
@@ -1189,6 +1222,7 @@ export async function callTool(name, rawArgs = {}) {
         return { status: 'ok', outcome: 'aborted', message: '保持 S1 现有账号，未覆盖。' };
       }
       const confirmed = persistCredentials(pending.newAk, pending.newSk, pending.newSecurityToken, pending.newRegion);
+      if (pending.fromImport && confirmed.status !== 'partial') clearImportFile();
       refreshUserHashAfterAuthChange();
       return confirmed;
     }