@gaiaworks/gaia-cli 0.0.5 → 0.0.7

package/README.md

@@ -1,30 +1,70 @@
-# @gaiaworks/gaia-cli
+# @gaiaworks/gaia-cli
+
+这是 `gaia-cli` 的 npm 分发壳包，用于通过 `npx` 下载并运行对应版本的 Go 二进制。
+
+## 使用方式
+
+临时执行：
+
+```bash
+npx @gaiaworks/gaia-cli version
+```
+
+全局安装：
+
+```bash
+npx @gaiaworks/gaia-cli@latest install
+gaia version
+```
+
+安装模式：
+
+```bash
+npx @gaiaworks/gaia-cli@latest install
+npx @gaiaworks/gaia-cli@latest install --mode external
+npx @gaiaworks/gaia-cli@latest install --mode internal
+```
+
+未指定 `--mode` 时默认写入 `external`。安装脚本会执行 `gaia setup --mode <external|internal>`，用于初始化本地 `install_mode` 和 Agent Skills。
+
+安装时会根据 npm 包版本，从 OSS 的同版本目录下载当前平台对应的 `gaia-cli` 二进制。
 
-这是 `gaia-cli` 的 npm 分发壳包，用于通过 `npx` 下载并运行对应版本的 Go 二进制。
+升级到 npm `latest` 并保留当前安装模式：
 
-## 使用方式
+```bash
+gaia update
+```
 
-临时执行：
+仅检查或安装指定版本：
 
 ```bash
-npx @gaiaworks/gaia-cli version
+gaia update --check
+gaia update --version 0.0.7
 ```
 
-全局安装：
+更新命令拒绝降级。首个包含该命令的版本仍需通过 `npx ... install` 手工升级一次。
+
+查看脱敏后的当前有效配置，并诊断配置、端点、登录凭据及 Internal 远程授权服务：
 
 ```bash
-npx @gaiaworks/gaia-cli@latest install
-gaia version
+gaia config show
+gaia doctor
+gaia doctor --json
 ```
 
-安装模式：
+`config show` 不输出 Token 或 Client Secret 明文。未登录属于警告；配置非法、必填端点缺失或远程授权服务健康检查失败时，`doctor` 返回非零退出码。
+
+卸载全局命令和 Gaia 管理的 Agent Skills，默认保留本地配置、凭据和目标信息：
 
 ```bash
-npx @gaiaworks/gaia-cli@latest install
-npx @gaiaworks/gaia-cli@latest install --mode external
-npx @gaiaworks/gaia-cli@latest install --mode internal
+gaia uninstall
 ```
 
-未指定 `--mode` 时默认写入 `external`。安装脚本会执行 `gaia setup --mode <external|internal>`，用于初始化本地 `install_mode` 和 Agent Skills。
+需要同时删除全部本地 Gaia 数据时使用：
 
-安装时会根据 npm 包版本，从 OSS 的同版本目录下载当前平台对应的 `gaia-cli` 二进制。
+```bash
+gaia uninstall --purge
+gaia uninstall --purge --yes
+```
+
+`--purge` 删除 `GAIA_CONFIG_DIR` 指向的目录；未设置该环境变量时删除 `~/.gaia`。默认会要求确认，自动化场景可显式添加 `--yes`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaiaworks/gaia-cli",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "JavaScript launcher for gaia-cli.",
   "license": "UNLICENSED",
   "private": false,

package/scripts/install-wizard.js

@@ -1,189 +1,206 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { binaryName, install } = require('./install');
-
-const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
-const packageSpec = `${packageJson.name}@${packageJson.version}`;
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { binaryName, install } = require('./install');
+
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const packageSpec = `${packageJson.name}@${packageJson.version}`;
 const binaryPath = path.join(__dirname, '..', 'bin', binaryName());
 const shellPathMarker = '# Added by gaia-cli installer';
 
-function parseInstallArgs(args) {
-  let mode = 'external';
-  let explicitMode = false;
-  const npmArgs = [];
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === '--mode') {
-      const value = args[i + 1];
-      if (!value) {
-        throw new Error('--mode requires a value: external or internal');
-      }
-      mode = value;
-      explicitMode = true;
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith('--mode=')) {
-      mode = arg.slice('--mode='.length);
-      explicitMode = true;
-      continue;
-    }
-    npmArgs.push(arg);
-  }
-
-  if (mode !== 'external' && mode !== 'internal') {
-    throw new Error(`Unsupported mode: ${mode}. Expected external or internal.`);
-  }
-
-  return { explicitMode, mode, npmArgs };
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    stdio: options.stdio || 'inherit',
-    encoding: 'utf8',
-  });
-
-  if (result.error) {
-    console.error(`[gaia-cli] Failed to run ${command}: ${result.error.message}`);
-    process.exit(1);
-  }
-
-  if (result.status !== 0) {
-    process.exit(typeof result.status === 'number' ? result.status : 1);
+function npmInvocation(args) {
+  if (process.platform === 'win32') {
+    const npmCli = process.env.npm_execpath || path.join(
+      path.dirname(process.execPath),
+      'node_modules',
+      'npm',
+      'bin',
+      'npm-cli.js'
+    );
+    return { command: process.execPath, args: [npmCli, ...args] };
   }
+  return { command: 'npm', args };
 }
-
-function runCapture(command, args) {
-  return spawnSync(command, args, {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-}
-
+
+function parseInstallArgs(args) {
+  let mode = 'external';
+  let explicitMode = false;
+  const npmArgs = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--mode') {
+      const value = args[i + 1];
+      if (!value) {
+        throw new Error('--mode requires a value: external or internal');
+      }
+      mode = value;
+      explicitMode = true;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--mode=')) {
+      mode = arg.slice('--mode='.length);
+      explicitMode = true;
+      continue;
+    }
+    npmArgs.push(arg);
+  }
+
+  if (mode !== 'external' && mode !== 'internal') {
+    throw new Error(`Unsupported mode: ${mode}. Expected external or internal.`);
+  }
+
+  return { explicitMode, mode, npmArgs };
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: options.stdio || 'inherit',
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    console.error(`[gaia-cli] Failed to run ${command}: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(typeof result.status === 'number' ? result.status : 1);
+  }
+}
+
+function runCapture(command, args) {
+  return spawnSync(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+}
+
 function npmGlobalBinDir() {
-  const result = runCapture('npm', ['prefix', '-g']);
-  if (result.error || result.status !== 0) return null;
-  const prefix = result.stdout.trim();
-  if (!prefix) return null;
-  return process.platform === 'win32' ? prefix : path.join(prefix, 'bin');
-}
-
-function npmGlobalCommandPath(binDir, platform = process.platform) {
+  const npm = npmInvocation(['prefix', '-g']);
+  const result = runCapture(npm.command, npm.args);
+  if (result.error || result.status !== 0) return null;
+  const prefix = result.stdout.trim();
+  if (!prefix) return null;
+  return process.platform === 'win32' ? prefix : path.join(prefix, 'bin');
+}
+
+function npmGlobalCommandPath(binDir, platform = process.platform) {
+  if (!binDir) return null;
+  if (platform === 'win32') return path.win32.join(binDir, 'gaia.cmd');
+  return path.posix.join(binDir, 'gaia');
+}
+
+function pathContains(dir) {
+  if (!dir) return false;
+  const entries = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  return entries.some((entry) => path.resolve(entry) === path.resolve(dir));
+}
+
+function shellProfilePath(env = process.env) {
+  if (process.platform === 'win32') return null;
+  const home = env.HOME;
+  if (!home) return null;
+  const shell = path.basename(env.SHELL || '');
+  if (shell === 'zsh') return path.join(home, '.zshrc');
+  if (shell === 'bash') return path.join(home, '.bashrc');
+  return path.join(home, '.profile');
+}
+
+function ensureWindowsPathConfigured(binDir) {
+  if (!binDir || process.platform !== 'win32' || pathContains(binDir)) return null;
+  const command = [
+    "$dir = $args[0]",
+    "$current = [Environment]::GetEnvironmentVariable('Path', 'User')",
+    "if (-not $current) { $current = '' }",
+    "$parts = $current -split ';' | Where-Object { $_ }",
+    "if ($parts -notcontains $dir) {",
+    "  $next = (@($dir) + $parts) -join ';'",
+    "  [Environment]::SetEnvironmentVariable('Path', $next, 'User')",
+    "}",
+  ].join("; ");
+  const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command, binDir], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) {
+    const detail = result.error ? result.error.message : `${result.stdout || ""}${result.stderr || ""}`.trim();
+    throw new Error(`Failed to update user PATH: ${detail}`);
+  }
+  return "Windows user PATH";
+}
+
+function pathExportBlock(binDir) {
+  return `${shellPathMarker}\nexport PATH="${binDir}:$PATH"\n`;
+}
+
+function ensurePathConfigured(binDir, profilePath = shellProfilePath(), platform = process.platform) {
   if (!binDir) return null;
-  if (platform === 'win32') return path.win32.join(binDir, 'gaia.cmd');
-  return path.posix.join(binDir, 'gaia');
-}
-
-function pathContains(dir) {
-  if (!dir) return false;
-  const entries = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
-  return entries.some((entry) => path.resolve(entry) === path.resolve(dir));
-}
-
-function shellProfilePath(env = process.env) {
-  if (process.platform === 'win32') return null;
-  const home = env.HOME;
-  if (!home) return null;
-  const shell = path.basename(env.SHELL || '');
-  if (shell === 'zsh') return path.join(home, '.zshrc');
-  if (shell === 'bash') return path.join(home, '.bashrc');
-  return path.join(home, '.profile');
-}
-
-function ensureWindowsPathConfigured(binDir) {
-  if (!binDir || process.platform !== 'win32' || pathContains(binDir)) return null;
-  const command = [
-    "$dir = $args[0]",
-    "$current = [Environment]::GetEnvironmentVariable('Path', 'User')",
-    "if (-not $current) { $current = '' }",
-    "$parts = $current -split ';' | Where-Object { $_ }",
-    "if ($parts -notcontains $dir) {",
-    "  $next = (@($dir) + $parts) -join ';'",
-    "  [Environment]::SetEnvironmentVariable('Path', $next, 'User')",
-    "}",
-  ].join("; ");
-  const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command, binDir], {
-    stdio: ["ignore", "pipe", "pipe"],
-    encoding: "utf8",
-  });
-  if (result.error || result.status !== 0) {
-    const detail = result.error ? result.error.message : `${result.stdout || ""}${result.stderr || ""}`.trim();
-    throw new Error(`Failed to update user PATH: ${detail}`);
-  }
-  return "Windows user PATH";
-}
-
-function pathExportBlock(binDir) {
-  return `${shellPathMarker}\nexport PATH="${binDir}:$PATH"\n`;
-}
-
-function ensurePathConfigured(binDir, profilePath = shellProfilePath()) {
-  if (!binDir) return null;
-  if (process.platform === 'win32') {
+  if (platform === 'win32') {
     return ensureWindowsPathConfigured(binDir);
-  }
-  if (!profilePath || pathContains(binDir)) return null;
-  const existing = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
-  if (existing.includes(binDir) || existing.includes(shellPathMarker)) return profilePath;
-  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
-  fs.appendFileSync(profilePath, `${prefix}${pathExportBlock(binDir)}`);
-  return profilePath;
-}
-
-function ensureLocalBinary() {
-  if (fs.existsSync(binaryPath)) return;
-  install();
-}
-
-function installWizard(args) {
-  const { explicitMode, mode, npmArgs } = parseInstallArgs(args);
-  if (npmArgs.length > 0) {
-    throw new Error(`Unsupported install arguments: ${npmArgs.join(' ')}`);
+  }
+  if (!profilePath || pathContains(binDir)) return null;
+  const existing = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+  if (existing.includes(binDir) || existing.includes(shellPathMarker)) return profilePath;
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(profilePath, `${prefix}${pathExportBlock(binDir)}`);
+  return profilePath;
+}
+
+function ensureLocalBinary() {
+  if (fs.existsSync(binaryPath)) return;
+  install();
+}
+
+function installWizard(args) {
+  const { explicitMode, mode, npmArgs } = parseInstallArgs(args);
+  if (npmArgs.length > 0) {
+    throw new Error(`Unsupported install arguments: ${npmArgs.join(' ')}`);
   }
 
   ensureLocalBinary();
-  run('npm', ['install', '-g', packageSpec]);
-  const globalBinDir = npmGlobalBinDir();
-  const globalCommand = npmGlobalCommandPath(globalBinDir);
-  const setupCommand = globalCommand && fs.existsSync(globalCommand) ? globalCommand : binaryPath;
-  run(setupCommand, ['setup', '--mode', mode], { stdio: 'ignore' });
-  const profilePath = ensurePathConfigured(globalBinDir);
-  const suffix = explicitMode ? `当前模式: ${mode}。` : '';
-  if (profilePath && globalBinDir && !pathContains(globalBinDir)) {
-    console.error(`[gaia-cli] 安装完成，${suffix}已更新 PATH 配置: ${profilePath}`);
-    console.error(`[gaia-cli] 重新打开终端后可以执行: gaia version`);
-    return;
-  }
-  if (explicitMode) {
-    console.error(`[gaia-cli] 安装完成，当前模式: ${mode}。可以执行: gaia version`);
-  } else {
-    console.error('[gaia-cli] 安装完成。可以执行: gaia version');
-  }
-}
-
-if (require.main === module) {
-  try {
-    installWizard(process.argv.slice(2));
-  } catch (error) {
-    console.error(`[gaia-cli] Install failed: ${error.message}`);
-    process.exit(1);
-  }
-}
-
-module.exports = {
-  ensurePathConfigured,
-  ensureWindowsPathConfigured,
+  const npm = npmInvocation(['install', '-g', packageSpec]);
+  run(npm.command, npm.args);
+  const globalBinDir = npmGlobalBinDir();
+  const globalCommand = npmGlobalCommandPath(globalBinDir);
+  const setupCommand = globalCommand && fs.existsSync(globalCommand) ? globalCommand : binaryPath;
+  run(setupCommand, ['setup', '--mode', mode], { stdio: 'ignore' });
+  const profilePath = ensurePathConfigured(globalBinDir);
+  const suffix = explicitMode ? `当前模式: ${mode}。` : '';
+  if (profilePath && globalBinDir && !pathContains(globalBinDir)) {
+    console.error(`[gaia-cli] 安装完成，${suffix}已更新 PATH 配置: ${profilePath}`);
+    console.error(`[gaia-cli] 重新打开终端后可以执行: gaia version`);
+    return;
+  }
+  if (explicitMode) {
+    console.error(`[gaia-cli] 安装完成，当前模式: ${mode}。可以执行: gaia version`);
+  } else {
+    console.error('[gaia-cli] 安装完成。可以执行: gaia version');
+  }
+}
+
+if (require.main === module) {
+  try {
+    installWizard(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[gaia-cli] Install failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  ensurePathConfigured,
+  ensureWindowsPathConfigured,
   npmGlobalBinDir,
   npmGlobalCommandPath,
-  pathContains,
-  pathExportBlock,
-  shellProfilePath,
-  installWizard,
-  parseInstallArgs,
-};
+  npmInvocation,
+  pathContains,
+  pathExportBlock,
+  shellProfilePath,
+  installWizard,
+  parseInstallArgs,
+};

package/scripts/install.js

@@ -1,177 +1,177 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const PACKAGE_JSON = path.join(PACKAGE_ROOT, 'package.json');
-const BIN_DIR = path.join(PACKAGE_ROOT, 'bin');
-const DOWNLOAD_BASE = process.env.GAIA_CLI_DOWNLOAD_BASE || 'https://assets.gaiaworkforce.com/gaia-cli/releases';
-const ALLOWED_DOWNLOAD_HOSTS = new Set([
-  'assets.gaiaworkforce.com',
-  'gaiafe.oss-cn-shanghai.aliyuncs.com',
-]);
-
-function readPackageVersion() {
-  const content = fs.readFileSync(PACKAGE_JSON, 'utf8');
-  return JSON.parse(content).version;
-}
-
-function normalizeVersion(version) {
-  return version.startsWith('v') ? version.slice(1) : version;
-}
-
-function platformName(platform = process.platform) {
-  if (platform === 'darwin') return 'darwin';
-  if (platform === 'linux') return 'linux';
-  if (platform === 'win32') return 'windows';
-  throw new Error(`Unsupported platform: ${platform}`);
-}
-
-function archName(arch = process.arch) {
-  if (arch === 'x64') return 'amd64';
-  if (arch === 'arm64') return 'arm64';
-  throw new Error(`Unsupported architecture: ${arch}`);
-}
-
-function binaryName(platform = process.platform) {
-  return platform === 'win32' ? 'gaia-cli.exe' : 'gaia-cli';
-}
-
-function archiveName(version, platform = process.platform, arch = process.arch) {
-  const cleanVersion = normalizeVersion(version);
-  return `gaia-cli-${cleanVersion}-${platformName(platform)}-${archName(arch)}.tar.gz`;
-}
-
-function releaseTag(version) {
-  const cleanVersion = normalizeVersion(version);
-  return `v${cleanVersion}`;
-}
-
-function downloadUrl(version, platform = process.platform, arch = process.arch) {
-  return `${DOWNLOAD_BASE}/${releaseTag(version)}/${archiveName(version, platform, arch)}`;
-}
-
-function assertAllowedUrl(rawUrl) {
-  const parsed = new URL(rawUrl);
-  if (parsed.protocol !== 'https:') {
-    throw new Error(`Refusing non-HTTPS download URL: ${rawUrl}`);
-  }
-  if (!ALLOWED_DOWNLOAD_HOSTS.has(parsed.hostname)) {
-    throw new Error(`Refusing download host: ${parsed.hostname}`);
-  }
-}
-
-function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true });
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    stdio: options.stdio || 'inherit',
-    cwd: options.cwd || PACKAGE_ROOT,
-    encoding: 'utf8',
-  });
-  if (result.error) {
-    throw result.error;
-  }
-  if (result.status !== 0) {
-    throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
-  }
-  return result;
-}
-
-function downloadWithRedirects(url, destination) {
-  assertAllowedUrl(url);
-  const tmpPath = `${destination}.tmp`;
-  fs.rmSync(tmpPath, { force: true });
-
-  run('curl', [
-    '--fail',
-    '--location',
-    '--show-error',
-    '--silent',
-    '--output',
-    tmpPath,
-    url,
-  ]);
-
-  fs.renameSync(tmpPath, destination);
-}
-
-function extractArchive(archivePath, targetDir) {
-  fs.rmSync(targetDir, { recursive: true, force: true });
-  ensureDir(targetDir);
-  run('tar', ['-xzf', archivePath, '-C', targetDir]);
-}
-
-function findDownloadedBinary(targetDir, platform = process.platform) {
-  const expectedName = binaryName(platform);
-  const direct = path.join(targetDir, expectedName);
-  if (fs.existsSync(direct)) return direct;
-
-  const pending = [targetDir];
-  while (pending.length > 0) {
-    const currentDir = pending.pop();
-    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const entryPath = path.join(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        pending.push(entryPath);
-      } else if (entry.isFile() && entry.name === expectedName) {
-        return entryPath;
-      }
-    }
-  }
-  throw new Error(`Downloaded archive does not contain ${expectedName}`);
-}
-
-function install(options = {}) {
-  const version = options.version || readPackageVersion();
-  const url = options.url || downloadUrl(version);
-  const archivePath = path.join(os.tmpdir(), archiveName(version));
-  const unpackDir = path.join(os.tmpdir(), `gaia-cli-${process.pid}-${Date.now()}`);
-  const finalBinary = path.join(BIN_DIR, binaryName());
-
-  console.error(`[gaia-cli] Downloading ${url}`);
-  ensureDir(BIN_DIR);
-  downloadWithRedirects(url, archivePath);
-  extractArchive(archivePath, unpackDir);
-
-  const downloadedBinary = findDownloadedBinary(unpackDir);
-  fs.copyFileSync(downloadedBinary, finalBinary);
-  if (process.platform !== 'win32') {
-    fs.chmodSync(finalBinary, 0o755);
-  }
-
-  fs.rmSync(archivePath, { force: true });
-  fs.rmSync(unpackDir, { recursive: true, force: true });
-  console.error(`[gaia-cli] Installed ${finalBinary}`);
-}
-
-if (require.main === module) {
-  try {
-    install();
-  } catch (error) {
-    console.error(`[gaia-cli] Failed to install binary: ${error.message}`);
-    console.error('[gaia-cli] Please check network access to OSS assets or contact the administrator.');
-    process.exit(1);
-  }
-}
-
-module.exports = {
-  ALLOWED_DOWNLOAD_HOSTS,
-  archName,
-  archiveName,
-  assertAllowedUrl,
-  binaryName,
-  downloadUrl,
-  findDownloadedBinary,
-  install,
-  normalizeVersion,
-  platformName,
-  releaseTag,
-};
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const PACKAGE_JSON = path.join(PACKAGE_ROOT, 'package.json');
+const BIN_DIR = path.join(PACKAGE_ROOT, 'bin');
+const DOWNLOAD_BASE = process.env.GAIA_CLI_DOWNLOAD_BASE || 'https://assets.gaiaworkforce.com/gaia-cli/releases';
+const ALLOWED_DOWNLOAD_HOSTS = new Set([
+  'assets.gaiaworkforce.com',
+  'gaiafe.oss-cn-shanghai.aliyuncs.com',
+]);
+
+function readPackageVersion() {
+  const content = fs.readFileSync(PACKAGE_JSON, 'utf8');
+  return JSON.parse(content).version;
+}
+
+function normalizeVersion(version) {
+  return version.startsWith('v') ? version.slice(1) : version;
+}
+
+function platformName(platform = process.platform) {
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'linux') return 'linux';
+  if (platform === 'win32') return 'windows';
+  throw new Error(`Unsupported platform: ${platform}`);
+}
+
+function archName(arch = process.arch) {
+  if (arch === 'x64') return 'amd64';
+  if (arch === 'arm64') return 'arm64';
+  throw new Error(`Unsupported architecture: ${arch}`);
+}
+
+function binaryName(platform = process.platform) {
+  return platform === 'win32' ? 'gaia-cli.exe' : 'gaia-cli';
+}
+
+function archiveName(version, platform = process.platform, arch = process.arch) {
+  const cleanVersion = normalizeVersion(version);
+  return `gaia-cli-${cleanVersion}-${platformName(platform)}-${archName(arch)}.tar.gz`;
+}
+
+function releaseTag(version) {
+  const cleanVersion = normalizeVersion(version);
+  return `v${cleanVersion}`;
+}
+
+function downloadUrl(version, platform = process.platform, arch = process.arch) {
+  return `${DOWNLOAD_BASE}/${releaseTag(version)}/${archiveName(version, platform, arch)}`;
+}
+
+function assertAllowedUrl(rawUrl) {
+  const parsed = new URL(rawUrl);
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`Refusing non-HTTPS download URL: ${rawUrl}`);
+  }
+  if (!ALLOWED_DOWNLOAD_HOSTS.has(parsed.hostname)) {
+    throw new Error(`Refusing download host: ${parsed.hostname}`);
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: options.stdio || 'inherit',
+    cwd: options.cwd || PACKAGE_ROOT,
+    encoding: 'utf8',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
+  }
+  return result;
+}
+
+function downloadWithRedirects(url, destination) {
+  assertAllowedUrl(url);
+  const tmpPath = `${destination}.tmp`;
+  fs.rmSync(tmpPath, { force: true });
+
+  run('curl', [
+    '--fail',
+    '--location',
+    '--show-error',
+    '--silent',
+    '--output',
+    tmpPath,
+    url,
+  ]);
+
+  fs.renameSync(tmpPath, destination);
+}
+
+function extractArchive(archivePath, targetDir) {
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  ensureDir(targetDir);
+  run('tar', ['-xzf', archivePath, '-C', targetDir]);
+}
+
+function findDownloadedBinary(targetDir, platform = process.platform) {
+  const expectedName = binaryName(platform);
+  const direct = path.join(targetDir, expectedName);
+  if (fs.existsSync(direct)) return direct;
+
+  const pending = [targetDir];
+  while (pending.length > 0) {
+    const currentDir = pending.pop();
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(entryPath);
+      } else if (entry.isFile() && entry.name === expectedName) {
+        return entryPath;
+      }
+    }
+  }
+  throw new Error(`Downloaded archive does not contain ${expectedName}`);
+}
+
+function install(options = {}) {
+  const version = options.version || readPackageVersion();
+  const url = options.url || downloadUrl(version);
+  const archivePath = path.join(os.tmpdir(), archiveName(version));
+  const unpackDir = path.join(os.tmpdir(), `gaia-cli-${process.pid}-${Date.now()}`);
+  const finalBinary = path.join(BIN_DIR, binaryName());
+
+  console.error(`[gaia-cli] Downloading ${url}`);
+  ensureDir(BIN_DIR);
+  downloadWithRedirects(url, archivePath);
+  extractArchive(archivePath, unpackDir);
+
+  const downloadedBinary = findDownloadedBinary(unpackDir);
+  fs.copyFileSync(downloadedBinary, finalBinary);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(finalBinary, 0o755);
+  }
+
+  fs.rmSync(archivePath, { force: true });
+  fs.rmSync(unpackDir, { recursive: true, force: true });
+  console.error(`[gaia-cli] Installed ${finalBinary}`);
+}
+
+if (require.main === module) {
+  try {
+    install();
+  } catch (error) {
+    console.error(`[gaia-cli] Failed to install binary: ${error.message}`);
+    console.error('[gaia-cli] Please check network access to OSS assets or contact the administrator.');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  ALLOWED_DOWNLOAD_HOSTS,
+  archName,
+  archiveName,
+  assertAllowedUrl,
+  binaryName,
+  downloadUrl,
+  findDownloadedBinary,
+  install,
+  normalizeVersion,
+  platformName,
+  releaseTag,
+};

package/scripts/run.js

@@ -1,47 +1,67 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const { binaryName } = require('./install');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const BINARY_PATH = path.join(PACKAGE_ROOT, 'bin', binaryName());
-
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { binaryName } = require('./install');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const BINARY_PATH = path.join(PACKAGE_ROOT, 'bin', binaryName());
+
 function runInstallWizard(args) {
-  const result = spawnSync(process.execPath, [path.join(__dirname, 'install-wizard.js'), ...args], {
-    stdio: 'inherit',
-  });
-  process.exit(typeof result.status === 'number' ? result.status : 1);
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'install-wizard.js'), ...args], {
+    stdio: 'inherit',
+  });
+  process.exit(typeof result.status === 'number' ? result.status : 1);
 }
 
-function ensureBinary() {
-  if (fs.existsSync(BINARY_PATH)) return;
-  const result = spawnSync(process.execPath, [path.join(__dirname, 'install.js')], {
+function runUpdater(args) {
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'update.js'), ...args], {
     stdio: 'inherit',
   });
-  if (result.status !== 0) {
-    process.exit(typeof result.status === 'number' ? result.status : 1);
-  }
+  process.exit(typeof result.status === 'number' ? result.status : 1);
 }
 
-function runBinary(args) {
-  ensureBinary();
-  const result = spawnSync(BINARY_PATH, args, {
+function runUninstaller(args) {
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'uninstall.js'), ...args], {
     stdio: 'inherit',
   });
-  if (result.error) {
-    console.error(`[gaia-cli] Failed to run ${BINARY_PATH}: ${result.error.message}`);
-    process.exit(1);
-  }
   process.exit(typeof result.status === 'number' ? result.status : 1);
 }
-
-const args = process.argv.slice(2);
+
+function ensureBinary() {
+  if (fs.existsSync(BINARY_PATH)) return;
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'install.js')], {
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    process.exit(typeof result.status === 'number' ? result.status : 1);
+  }
+}
+
+function runBinary(args) {
+  ensureBinary();
+  const result = spawnSync(BINARY_PATH, args, {
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    console.error(`[gaia-cli] Failed to run ${BINARY_PATH}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(typeof result.status === 'number' ? result.status : 1);
+}
+
+const args = process.argv.slice(2);
 if (args[0] === 'install') {
   runInstallWizard(args.slice(1));
 }
+if (args[0] === 'update') {
+  runUpdater(args.slice(1));
+}
+if (args[0] === 'uninstall') {
+  runUninstaller(args.slice(1));
+}
 
 runBinary(args);

package/scripts/uninstall.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const readline = require('node:readline/promises');
+
+function defaultExecute(command, args) {
+  return spawnSync(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+}
+
+function npmInvocation(args, platform, env) {
+  if (platform === 'win32') {
+    const npmCli = env.npm_execpath || path.join(
+      path.dirname(process.execPath),
+      'node_modules',
+      'npm',
+      'bin',
+      'npm-cli.js'
+    );
+    return { command: process.execPath, args: [npmCli, ...args] };
+  }
+  return { command: 'npm', args };
+}
+
+function executeChecked(execute, command, args, action) {
+  const result = execute(command, args);
+  if (result.error || result.status !== 0) {
+    const detail = result.error
+      ? result.error.message
+      : `${result.stdout || ''}${result.stderr || ''}`.trim();
+    throw new Error(`${action} failed${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+async function defaultConfirm(message) {
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await prompt.question(`${message} [y/N] `);
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    prompt.close();
+  }
+}
+
+async function uninstallCli(args, options = {}) {
+  const purge = args.includes('--purge');
+  const yes = args.includes('--yes');
+  const invalidArgs = args.filter((arg) => arg !== '--purge' && arg !== '--yes');
+  if (invalidArgs.length > 0 || yes && !purge || new Set(args).size !== args.length) {
+    throw new Error(`unsupported uninstall arguments: ${args.join(' ')}`);
+  }
+
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const packageInfo = options.packageInfo || JSON.parse(
+    fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+  );
+  const execute = options.execute || defaultExecute;
+  const write = options.write || ((message) => console.error(message));
+  const confirm = options.confirm || defaultConfirm;
+  const runScript = options.runScript || path.join(__dirname, 'run.js');
+  const configDir = path.resolve(env.GAIA_CONFIG_DIR || path.join(os.homedir(), '.gaia'));
+
+  if (purge) {
+    const root = path.parse(configDir).root;
+    const protectedPaths = [root, path.resolve(os.homedir()), path.resolve(process.cwd())];
+    const normalizedConfigDir = platform === 'win32' ? configDir.toLowerCase() : configDir;
+    if (protectedPaths.some((protectedPath) => (
+      platform === 'win32' ? protectedPath.toLowerCase() : protectedPath
+    ) === normalizedConfigDir)) {
+      throw new Error(`refusing to purge unsafe Gaia configuration directory: ${configDir}`);
+    }
+    if (!yes && !await confirm(`Remove all Gaia CLI configuration and credentials at ${configDir}?`)) {
+      write('Uninstall cancelled.');
+      return { purged: false, cancelled: true, configDir };
+    }
+  }
+
+  write('Removing Gaia-managed Agent Skills...');
+  executeChecked(
+    execute,
+    process.execPath,
+    [runScript, 'skills', 'remove'],
+    'remove Gaia-managed Agent Skills'
+  );
+
+  write(`Uninstalling ${packageInfo.name}...`);
+  const uninstall = npmInvocation(['uninstall', '-g', packageInfo.name], platform, env);
+  executeChecked(execute, uninstall.command, uninstall.args, 'uninstall Gaia CLI package');
+
+  if (purge) {
+    fs.rmSync(configDir, { recursive: true, force: true });
+    write(`Gaia CLI uninstalled. Configuration removed from ${configDir}`);
+    return { purged: true, configDir };
+  }
+
+  write(`Gaia CLI uninstalled. Configuration retained at ${configDir}`);
+
+  return { purged: false, configDir };
+}
+
+if (require.main === module) {
+  uninstallCli(process.argv.slice(2)).catch((error) => {
+    console.error(`[gaia-cli] Uninstall failed: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { uninstallCli };

package/scripts/update.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const registry = 'https://registry.npmjs.org';
+
+function parseVersion(version) {
+  const match = String(version).match(
+    /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+  );
+  if (!match) throw new Error(`invalid Gaia CLI version: ${version}`);
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  for (let index = 0; index < a.core.length; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] - b.core[index];
+  }
+  if (a.prerelease.length === 0) return b.prerelease.length === 0 ? 0 : 1;
+  if (b.prerelease.length === 0) return -1;
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const aPart = a.prerelease[index];
+    const bPart = b.prerelease[index];
+    if (aPart === undefined) return -1;
+    if (bPart === undefined) return 1;
+    if (aPart === bPart) continue;
+    const aNumber = /^\d+$/.test(aPart);
+    const bNumber = /^\d+$/.test(bPart);
+    if (aNumber && bNumber) return Number(aPart) - Number(bPart);
+    if (aNumber) return -1;
+    if (bNumber) return 1;
+    return aPart.localeCompare(bPart);
+  }
+  return 0;
+}
+
+function defaultExecute(command, args) {
+  return spawnSync(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+}
+
+function npmInvocation(args, platform, env) {
+  if (platform === 'win32') {
+    const npmCli = env.npm_execpath || path.join(
+      path.dirname(process.execPath),
+      'node_modules',
+      'npm',
+      'bin',
+      'npm-cli.js'
+    );
+    return { command: process.execPath, args: [npmCli, ...args] };
+  }
+  return { command: 'npm', args };
+}
+
+function executeChecked(execute, command, args, action) {
+  const result = execute(command, args);
+  if (result.error || result.status !== 0) {
+    const detail = result.error
+      ? result.error.message
+      : `${result.stdout || ''}${result.stderr || ''}`.trim();
+    throw new Error(`${action} failed${detail ? `: ${detail}` : ''}`);
+  }
+  return result;
+}
+
+function readInstallMode(env) {
+  const configDir = env.GAIA_CONFIG_DIR || path.join(os.homedir(), '.gaia');
+  const configPath = path.join(configDir, 'config.json');
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`cannot read Gaia CLI configuration at ${configPath}: ${error.message}`);
+  }
+  if (config.install_mode !== 'internal' && config.install_mode !== 'external') {
+    throw new Error(`invalid install_mode in ${configPath}`);
+  }
+  return config.install_mode;
+}
+
+function updateCli(args, options = {}) {
+  const checkOnly = args.length === 1 && args[0] === '--check';
+  const requestedVersion = args.length === 2 && args[0] === '--version' ? args[1] : '';
+  if (args.length > 0 && !checkOnly && !requestedVersion) {
+    throw new Error(`unsupported update arguments: ${args.join(' ')}`);
+  }
+  if (requestedVersion) {
+    try {
+      parseVersion(requestedVersion);
+    } catch {
+      throw new Error(`explicit version must be a semantic version: ${requestedVersion}`);
+    }
+  }
+
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const packageInfo = options.packageInfo || JSON.parse(
+    fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+  );
+  const execute = options.execute || defaultExecute;
+  const write = options.write || ((message) => console.error(message));
+  const mode = readInstallMode(env);
+
+  const requestedSpec = requestedVersion || 'latest';
+  const view = npmInvocation([
+    'view', `${packageInfo.name}@${requestedSpec}`, 'version', '--registry', registry,
+  ], platform, env);
+  const viewResult = executeChecked(execute, view.command, view.args, 'check latest version');
+  const targetVersion = viewResult.stdout.trim();
+  if (!targetVersion) throw new Error('npm returned an empty latest version');
+  if (compareVersions(targetVersion, packageInfo.version) < 0) {
+    throw new Error(`refusing to downgrade Gaia CLI from v${packageInfo.version} to v${targetVersion}`);
+  }
+
+  if (checkOnly) {
+    const updateAvailable = targetVersion !== packageInfo.version;
+    write(updateAvailable
+      ? `Update available: v${packageInfo.version} -> v${targetVersion}`
+      : `Gaia CLI is already up to date: v${packageInfo.version}`);
+    return {
+      currentVersion: packageInfo.version,
+      targetVersion,
+      updated: false,
+      updateAvailable,
+    };
+  }
+
+  if (targetVersion === packageInfo.version) {
+    write(`Gaia CLI is already up to date: v${packageInfo.version}`);
+    return { currentVersion: packageInfo.version, targetVersion, updated: false };
+  }
+
+  write(`Updating Gaia CLI from v${packageInfo.version} to v${targetVersion}...`);
+  const prefix = npmInvocation(['prefix', '-g'], platform, env);
+  const prefixResult = executeChecked(execute, prefix.command, prefix.args, 'resolve npm global prefix');
+  const globalPrefix = prefixResult.stdout.trim();
+  if (!globalPrefix) throw new Error('npm returned an empty global prefix');
+
+  const install = npmInvocation([
+    'install', '-g', `${packageInfo.name}@${targetVersion}`, '--registry', registry,
+  ], platform, env);
+  executeChecked(execute, install.command, install.args, 'install Gaia CLI update');
+
+  let setupCommand;
+  let setupArgs;
+  if (platform === 'win32') {
+    setupCommand = process.execPath;
+    setupArgs = [
+      path.win32.join(globalPrefix, 'node_modules', ...packageInfo.name.split('/'), 'scripts', 'run.js'),
+      'setup',
+      '--mode',
+      mode,
+    ];
+  } else {
+    setupCommand = path.posix.join(globalPrefix, 'bin', 'gaia');
+    setupArgs = ['setup', '--mode', mode];
+  }
+  executeChecked(execute, setupCommand, setupArgs, 'restore Gaia CLI mode');
+
+  write(`Update completed: v${targetVersion}`);
+  write(`Install mode retained: ${mode}`);
+  return { currentVersion: packageInfo.version, targetVersion, updated: true };
+}
+
+if (require.main === module) {
+  try {
+    updateCli(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[gaia-cli] Update failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { updateCli };