huaweicloud-devkit 1.1.1 → 1.1.2-next.1

package/README.md

@@ -249,10 +249,13 @@ npx --yes huaweicloud-devkit install --target all
 ### Update All Agents
 
 ```bash
-npx --yes huaweicloud-devkit update --target all
+npx huaweicloud-devkit version
+npx --yes huaweicloud-devkit@latest update --target all
 ```
 
-`update` is incremental — it refreshes installed files without touching your config.
+`update` is incremental — it refreshes installed files without touching your
+config. Always keep `@latest` so npm fetches the newest version instead of a
+locally cached older one.
 
 ## What It Does
 

package/README.zh-CN.md

@@ -249,10 +249,11 @@ npx --yes huaweicloud-devkit install --target all
 ### 更新所有 Agent
 
 ```bash
-npx --yes huaweicloud-devkit update --target all
+npx huaweicloud-devkit version
+npx --yes huaweicloud-devkit@latest update --target all
 ```
 
-`update` 是增量更新——只刷新已安装的文件，不动配置文件。
+`update` 是增量更新——只刷新已安装的文件，不动配置文件。请务必保留 `@latest`，确保 npm 获取最新版本而非本地缓存的旧版本。
 
 ## 功能特性
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.1",
+  "version": "1.1.2-next.1",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",
   "files": [

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

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.1",
+  "version": "1.1.2-next.1",
   "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.1",
+  "version": "1.1.2-next.1",
   "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.1",
+  "version": "1.1.2-next.1",
   "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.1",
+  "version": "1.1.2-next.1",
   "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.1",
+  "version": "1.1.2-next.1",
   "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.1",
+  "version": "1.1.2-next.1",
   "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/huaweicloud-core/SKILL.md

@@ -10,6 +10,14 @@ version: 1
 
 Huawei Cloud comprises 200+ services. This skill is the entry point for ANY action or question related to Huawei Cloud. It matches a workload to the right service, then hands off to a service-specific skill for operational questions.
 
+## 会话启动
+
+首次操作前必须先调用 `huaweicloud_check_update` 检查插件版本：
+
+1. 如果 `updateAvailable == true` 且 `dismissed == false`，先询问用户是否升级
+2. 用户同意 → 调用 `huaweicloud_upgrade`，完成后提示重启会话
+3. 用户拒绝 → 调用 `huaweicloud_check_update` 传 `dismiss: true`
+
 ## How This Skill Works
 
 1. Match user intent against the Sub-skill registry below

package/plugins/huaweicloud-core/src/mcp-server.mjs

@@ -6,6 +6,7 @@ import { platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 import { TOOL_DEFINITIONS, callTool } from './tools.mjs';
+import { getCachedUpdateInfo, readInstalledVersion, peekCachedUpdateInfo, applyUpdateHint } from './update-check.mjs';
 import { initTelemetry } from './telemetry/telemetry.mjs';
 import { detectAgent } from './telemetry/agent-detect.mjs';
 
@@ -73,6 +74,27 @@ let useContentLengthFraming = true;
 // shutdown signal — exit cleanly so the host does not see CLOSE_TIMEOUT.
 const { harness } = detectAgent();
 const NEEDS_KEEPALIVE = harness === 'hermes' && platform() === 'win32';
+
+// 版本升级检测预热：异步、非阻塞；失败静默（离线/超时不影响会话）。
+process.nextTick(() => {
+  getCachedUpdateInfo(readInstalledVersion() || '0.0.0').catch(() => {});
+});
+
+// 会话内首个非 check/upgrade 工具调用附加 _updateInfo，只消费一次。
+let hintConsumed = false;
+function decorateResult(name, result) {
+  if (hintConsumed) return result;
+  try {
+    const hint = peekCachedUpdateInfo();
+    if (!hint) return result;
+    const decorated = applyUpdateHint(result, name, hint);
+    if (decorated !== result) hintConsumed = true;
+    return decorated;
+  } catch {
+    return result; // 兜底装饰失败绝不影响工具调用
+  }
+}
+
 let keepAlive = null;
 function onStdinClose() {
   if (keepAlive) return;
@@ -191,11 +213,12 @@ async function dispatch(method, params) {
 
   if (method === 'tools/call') {
     const result = await callTool(params.name, params.arguments || {});
+    const decorated = decorateResult(params.name, result);
     return {
       content: [
         {
           type: 'text',
-          text: JSON.stringify(result, null, 2),
+          text: JSON.stringify(decorated, null, 2),
         },
       ],
       isError: false,

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

@@ -35,6 +35,7 @@ import {
   getProxySettings,
 } from './proxy/proxy-config.mjs';
 import { removeKooCli, removeObsConfig } from './sandbox/uninstall-cleanup.mjs';
+import { queryDistTagsSync, determineTarget, semverCompare } from './update-check.mjs';
 
 const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
 
@@ -3056,20 +3057,12 @@ function parseTarget() {
 
 function checkForUpdate() {
   if (pkgVersion === '0.0.0') return;
-  const tag = /-next\.\d+/.test(pkgVersion) ? 'next' : 'latest';
-  let latest = null;
-  try {
-    const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const r = spawnSync(npmBin, ['view', `huaweicloud-devkit@${tag}`, 'version'], {
-      encoding: 'utf8',
-      timeout: 5000,
-      windowsHide: true,
-    });
-    if (r.status === 0) latest = (r.stdout || '').trim().split('\n').pop().trim();
-  } catch {}
-  if (latest && latest !== pkgVersion) {
+  const distTags = queryDistTagsSync({ timeoutMs: 5000 });
+  const target = determineTarget(pkgVersion, distTags ?? {});
+  if (target && semverCompare(target, pkgVersion) > 0) {
+    const tag = distTags.next && semverCompare(target, distTags.next) === 0 ? 'next' : 'latest';
     console.log(
-      `\n\x1b[33mℹ️ 检测到新版本：${latest}（当前 ${pkgVersion}，${tag} 频道）。建议运行 \`npx huaweicloud-devkit@${tag} update\` 更新。\x1b[0m`,
+      `\n\x1b[33mℹ️ 检测到新版本：${target}（当前 ${pkgVersion}，${tag} 频道）。建议运行 \`npx --yes huaweicloud-devkit@${tag} update\` 更新。\x1b[0m`,
     );
   }
 }

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

@@ -46,6 +46,17 @@ import {
 } from './auth/credentials.mjs';
 import { trackToolInvoke, trackSkillRetrieve } from './telemetry/telemetry.mjs';
 import { fingerprint, runHcloudConfigure, resolveManagedProfile } from './auth/reconcile.mjs';
+import {
+  getCachedUpdateInfo,
+  getUpdateDistTags,
+  invalidateUpdateCache,
+  judgeUpdate,
+  determineTarget,
+  readInstalledVersion,
+  writeSkipState,
+  resolveSkipFilePath,
+  upgradePackage,
+} from './update-check.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_ROOT_DEV = join(__dirname, '..', 'skills');
@@ -795,6 +806,36 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  {
+    name: 'huaweicloud_check_update',
+    description:
+      '检查 huaweicloud-devkit 插件是否有新版本。结果含 currentVersion / latestStable / latestNext / targetVersion / updateAvailable / dismissExpiresAt / result。支持 dismiss:true 记录用户拒绝（3 天冷却，新版本会重新提醒）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dismiss: { type: 'boolean', description: '用户拒绝升级时传 true，记录冷却状态。' },
+        dismissVersion: {
+          type: 'string',
+          description: '与 dismiss:true 搭配，用户拒绝的版本号。缺省时用当前检测到的 targetVersion。',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_upgrade',
+    description:
+      '升级 huaweicloud-devkit 到最新版本。执行前必须先征得用户同意。version 仅支持 "latest"。完成后需重启会话生效。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        version: { type: 'string', description: '仅支持 "latest"（默认）。' },
+        target: {
+          type: 'string',
+          description: 'agent 目标（opencode/codex/codearts/.../all）。缺省时用 all（仅更新已安装的）。',
+        },
+      },
+    },
+  },
 ];
 
 function toolInvokeValue(name, args) {
@@ -1284,11 +1325,46 @@ export async function callTool(name, args = {}) {
       return await hdkitVoucherStatus(args.domain_id);
     case 'huaweicloud_voucher_claim':
       return await hdkitVoucherClaim(args.domain_id);
+    case 'huaweicloud_check_update':
+      return await handleCheckUpdate(args);
+    case 'huaweicloud_upgrade':
+      return await handleUpgrade(args);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
 }
 
+async function handleCheckUpdate(args = {}) {
+  const current = readInstalledVersion() || '0.0.0';
+  if (args.dismiss === true) {
+    const distTags = await getUpdateDistTags(current);
+    const target = determineTarget(current, distTags);
+    const dismissedVersion =
+      typeof args.dismissVersion === 'string' && args.dismissVersion ? args.dismissVersion : target || current;
+    const state = writeSkipState(resolveSkipFilePath(), dismissedVersion);
+    invalidateUpdateCache();
+    return judgeUpdate(current, distTags, state);
+  }
+  return getCachedUpdateInfo(current);
+}
+
+async function handleUpgrade(args = {}) {
+  const target = typeof args.target === 'string' && args.target ? args.target : 'all';
+  const version = typeof args.version === 'string' && args.version ? args.version : 'latest';
+  const current = readInstalledVersion() || '0.0.0';
+  const info = await getCachedUpdateInfo(current);
+  if (info && info.result === 'up_to_date') {
+    return {
+      success: false,
+      requiresRestart: false,
+      message: '已是最新版本，无需升级。',
+      currentVersion: info.currentVersion,
+      targetVersion: info.targetVersion,
+    };
+  }
+  return upgradePackage({ target, version });
+}
+
 function hookResult(result) {
   return {
     ok: result.decision !== 'deny',

package/plugins/huaweicloud-core/src/update-check.mjs

@@ -0,0 +1,383 @@
+// Version-update detection & auto-upgrade for huaweicloud-devkit (session-level).
+// Spec: docs/superpowers/specs/2026-09-07-version-upgrade-design.md (internal, not committed).
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, rmSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const IS_WINDOWS = process.platform === 'win32';
+const NPM_BIN = IS_WINDOWS ? 'npm.cmd' : 'npm';
+const NPX_BIN = IS_WINDOWS ? 'npx.cmd' : 'npx';
+const TTL_MS = 60 * 60 * 1000;
+const FAIL_THROTTLE_MS = 5 * 60 * 1000;
+const COOLDOWN_DAYS = 3;
+
+export function semverParse(input) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(input).trim());
+  if (!m) return null;
+  const pre = m[4] ? m[4].split('.') : null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre, raw: String(input).trim() };
+}
+
+function comparePre(a, b) {
+  if (a === null && b === null) return 0;
+  if (a === null) return 1; // 无 prerelease（正式版）更大
+  if (b === null) return -1;
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xNum = /^\d+$/.test(x);
+    const yNum = /^\d+$/.test(y);
+    if (xNum && yNum) {
+      const dx = Number(x);
+      const dy = Number(y);
+      if (dx !== dy) return dx < dy ? -1 : 1;
+    } else if (xNum) {
+      return -1; // 数字标识符 < 字母标识符
+    } else if (yNum) {
+      return 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+export function semverCompare(a, b) {
+  const A = semverParse(a);
+  const B = semverParse(b);
+  if (!A || !B) {
+    const sa = String(a);
+    const sb = String(b);
+    return sa === sb ? 0 : sa < sb ? -1 : 1;
+  }
+  if (A.major !== B.major) return A.major < B.major ? -1 : 1;
+  if (A.minor !== B.minor) return A.minor < B.minor ? -1 : 1;
+  if (A.patch !== B.patch) return A.patch < B.patch ? -1 : 1;
+  return comparePre(A.pre, B.pre);
+}
+
+export function hasPrerelease(v) {
+  const parsed = semverParse(v);
+  return Boolean(parsed && parsed.pre);
+}
+
+export function determineTarget(current, distTags = {}) {
+  const isPre = hasPrerelease(current);
+  const candidates = [];
+  if (distTags.latest) candidates.push(distTags.latest);
+  if (isPre && distTags.next) candidates.push(distTags.next);
+  if (!candidates.length) return null;
+  return candidates.slice().sort(semverCompare).pop();
+}
+
+export function parseDistTagsOutput(stdout) {
+  try {
+    const text = String(stdout || '').trim();
+    if (!text) return null; // 空输出视为 npm view 失败
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return {
+      latest: typeof parsed.latest === 'string' ? parsed.latest : null,
+      next: typeof parsed.next === 'string' ? parsed.next : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function buildResult(current, distTags, extra = {}) {
+  const result = {
+    currentVersion: current,
+    latestStable: distTags?.latest ?? null,
+    latestNext: distTags?.next ?? null,
+    targetVersion: extra.target ?? null,
+    updateAvailable: extra.result === 'update_available',
+    dismissed: extra.result === 'dismissed',
+    dismissExpiresAt: extra.dismissExpiresAt ?? null,
+    result: extra.result ?? 'up_to_date',
+  };
+  if (extra.note) result.note = extra.note;
+  return result;
+}
+
+export function judgeUpdate(current, distTags, skipState, now = Date.now()) {
+  if (process.env.HUAWEICLOUD_DEVKIT_SKIP_UPDATE === '1') {
+    return buildResult(current, distTags ?? null);
+  }
+  if (!distTags) {
+    return buildResult(current, null, { result: 'check_failed', note: '检测失败，不影响使用' });
+  }
+  const target = determineTarget(current, distTags);
+  if (!target || semverCompare(target, current) <= 0) {
+    return buildResult(current, distTags, { result: 'up_to_date', target: target ?? null });
+  }
+  const expiresAt = skipState?.expireAt ? new Date(skipState.expireAt).getTime() : 0;
+  const inCooldown =
+    Boolean(skipState) && now < expiresAt && semverCompare(target, String(skipState.dismissedVersion)) <= 0;
+  if (inCooldown) {
+    return buildResult(current, distTags, { result: 'dismissed', target, dismissExpiresAt: skipState.expireAt });
+  }
+  return buildResult(current, distTags, { result: 'update_available', target });
+}
+
+function selfDir() {
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+export function readInstalledVersion() {
+  const pluginRoot = resolve(selfDir(), '..');
+  const packageRoot = resolve(pluginRoot, '..', '..');
+  for (const base of [pluginRoot, packageRoot]) {
+    try {
+      const version = JSON.parse(readFileSync(join(base, 'package.json'), 'utf8')).version;
+      if (typeof version === 'string' && version) return version;
+    } catch {}
+  }
+  return null;
+}
+
+export function skipFilePath() {
+  return join(resolve(selfDir(), '..'), '.update-skip.json');
+}
+
+export function fallbackSkipFilePath() {
+  const base = process.env.HUAWEICLOUD_HOME || homedir();
+  return join(base, '.config', 'huaweicloud', 'devkit-skip.json');
+}
+
+// A1 定稿: 标准 agent 用插件目录副本(有 package.json); codex 等无副本时回退共享文件
+export function resolveSkipFilePath() {
+  try {
+    if (existsSync(join(dirname(skipFilePath()), 'package.json'))) return skipFilePath();
+  } catch {}
+  return fallbackSkipFilePath();
+}
+
+export function readSkipState(file) {
+  if (!existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed.dismissedVersion !== 'string' || !parsed.dismissedAt || !parsed.expireAt) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSkipState(file, dismissedVersion, { at = Date.now(), days = COOLDOWN_DAYS } = {}) {
+  const state = {
+    dismissedVersion: String(dismissedVersion),
+    dismissedAt: new Date(at).toISOString(),
+    expireAt: new Date(at + days * 24 * 60 * 60 * 1000).toISOString(),
+  };
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  try {
+    renameSync(tmp, file);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+  return state;
+}
+
+export function queryDistTagsSync({ timeoutMs = 5000, cwd } = {}) {
+  try {
+    const result = spawnSync(NPM_BIN, ['view', 'huaweicloud-devkit', 'dist-tags', '--json'], {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      windowsHide: true,
+      cwd,
+    });
+    if (result.status !== 0) return null;
+    return parseDistTagsOutput(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+export function queryDistTags({ timeoutMs = 5000, cwd } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(NPM_BIN, ['view', 'huaweicloud-devkit', 'dist-tags', '--json'], {
+        windowsHide: true,
+        cwd,
+      });
+    } catch {
+      resolve(null);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill();
+      } catch {}
+      resolve(null);
+    }, timeoutMs);
+    let stdout = '';
+    child.stdout.on('data', (d) => {
+      stdout += String(d);
+    });
+    child.on('error', () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(parseDistTagsOutput(stdout));
+      else resolve(null);
+    });
+  });
+}
+
+let cachedDistTags = null;
+let cachedAt = 0;
+let failedAt = 0;
+let inflightQuery = null;
+let lastHint = null;
+
+export function invalidateUpdateCache() {
+  cachedDistTags = null;
+  cachedAt = 0;
+  failedAt = 0;
+  inflightQuery = null;
+  lastHint = null;
+}
+
+function cacheValid() {
+  return Boolean(cachedDistTags) && Date.now() - cachedAt <= TTL_MS;
+}
+
+export async function getCachedUpdateInfo(current, { doQuery = queryDistTags } = {}) {
+  if (process.env.HUAWEICLOUD_DEVKIT_SKIP_UPDATE === '1') {
+    lastHint = judgeUpdate(current, null);
+    return lastHint;
+  }
+  const skipState = readSkipState(resolveSkipFilePath());
+  if (!cacheValid()) {
+    if (!cachedDistTags && Date.now() - failedAt < FAIL_THROTTLE_MS) {
+      lastHint = judgeUpdate(current, null, skipState);
+      return lastHint;
+    }
+    if (!inflightQuery) {
+      inflightQuery = doQuery()
+        .then((distTags) => {
+          if (distTags) {
+            cachedDistTags = distTags;
+            cachedAt = Date.now();
+          } else {
+            failedAt = Date.now();
+          }
+          return distTags;
+        })
+        .finally(() => {
+          inflightQuery = null;
+        });
+    }
+    const distTags = await inflightQuery;
+    lastHint = judgeUpdate(current, distTags, skipState);
+    return lastHint;
+  }
+  lastHint = judgeUpdate(current, cachedDistTags, skipState);
+  return lastHint;
+}
+
+export function peekCachedUpdateInfo() {
+  return lastHint && lastHint.updateAvailable && lastHint.targetVersion ? lastHint : null;
+}
+
+export async function getUpdateDistTags(current) {
+  const result = await getCachedUpdateInfo(current);
+  if (!result) return null;
+  return { latest: result.latestStable ?? null, next: result.latestNext ?? null };
+}
+
+export function applyUpdateHint(result, name, hint) {
+  if (!hint || !hint.updateAvailable || !hint.targetVersion) return result;
+  if (name === 'huaweicloud_check_update' || name === 'huaweicloud_upgrade') return result;
+  return {
+    ...result,
+    _updateInfo: { currentVersion: hint.currentVersion, latestVersion: hint.targetVersion },
+  };
+}
+
+function defaultSpawn(command, args, options) {
+  return spawnSync(command, args, options);
+}
+
+function restartMessage(target) {
+  if (target === 'officeace') {
+    return '升级完成，请打开连接器 → 我的连接器 → huaweicloud-devkit → 重新连接后使用新版本。';
+  }
+  return '升级完成，请重启当前会话使新版本生效。';
+}
+
+export async function upgradePackage({ target = 'all', version = 'latest' } = {}, options = {}) {
+  if (version !== 'latest') {
+    return { success: false, error: 'version 参数仅支持 latest。目标版本由插件自动判定。' };
+  }
+  const { doQuery = queryDistTags, spawnFn = defaultSpawn } = options;
+  const previousVersion = readInstalledVersion();
+  let distTags;
+  try {
+    distTags = await doQuery();
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || '无法确认最新版本（registry 查询失败）。',
+      manual: `npx --yes huaweicloud-devkit@latest update --target ${target}`,
+    };
+  }
+  const targetVersion = determineTarget(previousVersion, distTags ?? {});
+  if (distTags === null) {
+    return {
+      success: false,
+      error: '无法确认最新版本（registry 查询失败）。',
+      manual: `npx --yes huaweicloud-devkit@latest update --target ${target}`,
+    };
+  }
+  if (!targetVersion) {
+    return { success: false, message: '已是最新版本，无需升级。', requiresRestart: false };
+  }
+  const isNextTarget = Boolean(distTags.next && semverCompare(targetVersion, distTags.next) === 0);
+  const tag = isNextTarget ? 'next' : 'latest';
+  const command = ['--yes', `huaweicloud-devkit@${tag}`, 'update', '--target', String(target)];
+  let execResult;
+  try {
+    execResult = spawnFn(NPX_BIN, command, { encoding: 'utf8', timeout: 300000, windowsHide: true });
+  } catch (error) {
+    return {
+      success: false,
+      error: error?.message || '升级命令执行失败。',
+      manual: `npx --yes huaweicloud-devkit@${tag} update --target ${target}`,
+    };
+  }
+  if (execResult.status === 0) {
+    invalidateUpdateCache();
+    return {
+      success: true,
+      previousVersion,
+      installedVersion: targetVersion,
+      requiresRestart: true,
+      message: restartMessage(target),
+    };
+  }
+  const errObj = execResult.error;
+  const stderr = String(execResult.stderr || '').trim();
+  const reason = errObj?.message
+    ? errObj.message
+    : stderr
+      ? stderr.split(/\r?\n/).filter(Boolean).slice(-2).join(' ')
+      : `exit ${execResult.status}`;
+  return {
+    success: false,
+    error: reason,
+    manual: `npx --yes huaweicloud-devkit@${tag} update --target ${target}`,
+  };
+}