@ziniao-open/cli 1.0.6 → 1.0.8

package/README.md

@@ -10,6 +10,43 @@
 npm install -g @ziniao-open/cli
 ```
 
+紫鸟客户端自带的 `ziniao` CLI 需要同步到 AppCache 并加入 PATH。执行 `npm install -g @ziniao-open/cli` 时会自动尝试同步；安装紫鸟客户端后，也可以手动执行以下命令：
+
+```bash
+source "$(npm root -g)/@ziniao-open/cli/scripts/setup-ziniao-cli.sh"
+```
+
+Windows PowerShell 执行：
+
+```powershell
+. "$(npm root -g)\@ziniao-open\cli\scripts\setup-ziniao-cli.ps1"
+```
+
+也可以在安装后手动修复：
+
+```bash
+ziniao-cli doctor fix-path
+```
+
+遍历当前 PATH 清理旧的 `ziniao` shim，并清理 Unix 端的 `ziniaobrowser/cli` 缓存目录（默认只预览）：
+
+```powershell
+& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1"
+& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1" -Apply
+```
+
+macOS/Linux：
+
+```bash
+"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh"
+"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh" --apply
+```
+
+脚本只探测 `ziniao.app` / `ziniao` 的安装目录；Windows 会优先查询卸载注册表中 `DisplayIcon` 包含 `ziniao.exe` 的条目，再从本体目录的 `resources/app.asar.unpacked/envkit/cli` 查找 CLI。Windows 使用 `%APPDATA%\ziniaobrowser\cli`，macOS 使用 `~/Library/Application Support/ziniaobrowser/cli`，Linux 使用 `${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/cli`，在目标目录缺少 CLI 或文件内容发生变化时同步最新文件，并注册当前用户 PATH。找不到源文件时只提示并继续，不阻断 PATH 配置。若安装目录无法自动探测，可设置 `ZINIAO_INSTALL_DIR`；若目标位置不同，可设置 `ZINIAO_APP_CACHE_DIR`。
+Windows 同时会把找到的紫鸟本体绝对路径写入 `%APPDATA%\ziniaobrowser\gui-path`，供 CLI 定位桌面客户端。
+macOS/Linux 也会在找到桌面本体时写入对应的 `gui-path`（macOS 为 `~/Library/Application Support/ziniaobrowser/gui-path`，Linux 为 `${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/gui-path`）。
+macOS/Linux 还会在 `~/.local/bin/ziniao` 创建固定 shim，避免向随机 PATH 目录写入文件。
+
 安装时会自动下载当前平台对应的预编译二进制（支持 macOS / Linux / Windows × amd64 / arm64），并做 SHA-256 校验。
 
 ## 快速开始
@@ -46,14 +83,49 @@ ziniao-cli --help
 
 完整列表见 `ziniao-cli --help`。
 
+## 本地 dev/prod 打包与切换
+
+在仓库根目录执行以下命令，可分别生成本地测试环境包和本地正式环境包：
+
+```bash
+make package-dev
+make package-prod
+```
+
+两个命令都会生成本地多平台 snapshot 包。版本基于最近的发布 tag，并使用本机递增计数器：最近 tag 为 `v1.0.7` 时，依次生成 `1.0.7-dev-1`、`1.0.7-dev-2`、`1.0.7-dev-3`。
+
+计数器保存在 `~/.ziniao-cli/dev-build-counter`；当最近 tag 变化时计数从 `1` 重新开始。可通过 `ZINIAO_CLI_DEV_COUNTER_FILE` 指定其他计数器路径，便于 CI 或测试隔离。产物写入 `dist/`，该命令只打包，不发布。
+
+`package-dev` 内置测试环境 `https://test-sbappstoreapi.ziniao.com` 与 `https://test-open.ziniao.com`，默认使用独立配置目录 `~/.ziniao-cli-dev/`，本地二进制写入 `~/.ziniao-cli-dev/bin/ziniao-cli`。
+
+`package-prod` 内置正式环境 `https://sbappstoreapi.ziniao.com` 与 `https://open.ziniao.com`，默认使用独立配置目录 `~/.ziniao-cli-prod/`，本地二进制写入 `~/.ziniao-cli-prod/bin/ziniao-cli`。
+
+仓库内的 `scripts/ziniao-cli-use` 提供统一切换入口；如果你已将该脚本加入 PATH，可直接执行：
+
+```bash
+ziniao-cli-use dev
+ziniao-cli-use prod
+ziniao-cli-use online
+```
+
+- `ziniao-cli-use dev`：切换到 `~/.ziniao-cli-dev/bin/ziniao-cli`
+- `ziniao-cli-use prod`：切换到 `~/.ziniao-cli-prod/bin/ziniao-cli`
+- `ziniao-cli-use online`：切换回 npm 安装的线上版 `ziniao-cli`，继续使用默认线上配置目录 `~/.ziniao-cli/`
+
+`make package-dev` 与 `make package-prod` 只会更新各自隔离的本地输出路径，不会改写仓库根目录的 `./ziniao-cli`。如果你需要仓库根目录的开发测试二进制，继续使用 `make build`。
+
+dev、本地 prod、online 三套 CLI 默认分别使用 `~/.ziniao-cli-dev/`、`~/.ziniao-cli-prod/`、`~/.ziniao-cli/`，API Key 和配置互不读取。首次运行某个本地环境前，执行 `ziniao-cli config init` 即可在对应目录完成初始化。
+
 ## AI Agent Skills
 
-仓库提供 13 个开箱即用的 AI Agent Skill，包括员工、店铺、角色、部门、设备、访问策略管理，以及批量授权、店铺巡检等编排工作流。
+仓库提供 12 个开箱即用的 AI Agent Skill：访问策略、账号、部门、设备、OpenAPI 探索、页面、角色、共享基础、Skill 创建、员工、店铺和批量账号授权。
 
 安装 Skill：
 
 ```bash
-npx skills add ziniao-open/skills -y -g
+ziniao-cli skills install
 ```
 
+备选：`npx skills add ziniao-open/skills -y -g`
+
 详见 [ziniao-skills](https://github.com/ziniao-open/skills)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziniao-open/cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "紫鸟开放平台命令行工具，为开发者和 AI Agent 提供统一的接口调用入口。",
   "license": "UNLICENSED",
   "bin": {
@@ -12,7 +12,11 @@
   },
   "files": [
     "scripts/install.js",
-    "scripts/run.js"
+    "scripts/run.js",
+    "scripts/setup-ziniao-cli.sh",
+    "scripts/setup-ziniao-cli.ps1",
+    "scripts/remove-ziniao-cli-shims.ps1",
+    "scripts/remove-ziniao-cli-shims.sh"
   ],
   "engines": {
     "node": ">=18"

package/scripts/install.js

@@ -197,6 +197,31 @@ function findBinaryIn(dir, name) {
   return null;
 }
 
+function runDesktopCliSetup() {
+  const scriptName = IS_WIN ? "setup-ziniao-cli.ps1" : "setup-ziniao-cli.sh";
+  const scriptPath = join(__dirname, scriptName);
+  if (!existsSync(scriptPath)) {
+    warn(`desktop CLI PATH setup script is missing: ${scriptPath}`);
+    return;
+  }
+
+  const result = IS_WIN
+    ? spawnSync("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        scriptPath,
+      ], { stdio: "inherit" })
+    : spawnSync("sh", [scriptPath], { stdio: "inherit" });
+  if (result.error) {
+    warn(`desktop CLI PATH setup skipped: ${result.error.message}`);
+  } else if (result.status !== 0) {
+    warn(`desktop CLI PATH setup exited with code ${result.status}`);
+  }
+}
+
 async function downloadAndInstall() {
   const version = PKG.version;
   if (!DOWNLOAD_BASE) {
@@ -266,18 +291,16 @@ async function main() {
   if (PKG.version === "0.0.0") {
     warn("package.json version is 0.0.0; skipping binary install (developer mode).");
     warn("Set ZINIAO_CLI_BINARY=/path/to/binary or run `make build` to use a local build.");
-    return;
-  }
-
-  if (existsSync(TARGET_PATH)) {
+  } else if (existsSync(TARGET_PATH)) {
     makeExecutable(TARGET_PATH);
     log(`binary already present at ${TARGET_PATH}, skipping download`);
-    return;
+  } else if (copyFromEnv()) {
+    // Local binary installed.
+  } else {
+    await downloadAndInstall();
   }
 
-  if (copyFromEnv()) return;
-
-  await downloadAndInstall();
+  runDesktopCliSetup();
 }
 
 main().catch((err) => fail(err.stack || err.message || String(err)));

package/scripts/remove-ziniao-cli-shims.ps1

@@ -0,0 +1,43 @@
+# Find and optionally remove ziniao.exe shims created in PATH directories.
+# Run without -Apply first to preview the files that would be removed.
+
+[CmdletBinding(SupportsShouldProcess)]
+param(
+  [switch]$Apply
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Log([string]$Message) {
+  Write-Output "[ziniao-cli-shims] $Message"
+}
+
+$targetDir = Join-Path $env:APPDATA "ziniaobrowser\cli"
+$candidates = @()
+foreach ($pathEntry in @($env:Path -split ";" | Where-Object { $_ })) {
+  $directory = $pathEntry.TrimEnd('\')
+  if (-not $directory -or $directory -ieq $targetDir.TrimEnd('\')) { continue }
+  $shimPath = Join-Path $directory "ziniao.exe"
+  if (-not (Test-Path -LiteralPath $shimPath -PathType Leaf)) { continue }
+  $candidates += $shimPath
+}
+
+if (-not $candidates) {
+  Write-Log "No ziniao.exe shims found in PATH directories."
+  exit 0
+}
+
+foreach ($candidate in ($candidates | Select-Object -Unique)) {
+  if (-not $Apply) {
+    Write-Log "Would remove: $candidate"
+    continue
+  }
+  if ($PSCmdlet.ShouldProcess($candidate, "Remove CLI shim")) {
+    Remove-Item -LiteralPath $candidate -Force
+    Write-Log "Removed: $candidate"
+  }
+}
+
+if (-not $Apply) {
+  Write-Log "Preview only. Re-run with -Apply to remove these files."
+}

package/scripts/remove-ziniao-cli-shims.sh

@@ -0,0 +1,82 @@
+#!/bin/sh
+# Find and optionally remove ziniao shims created in PATH directories.
+# Run without --apply first to preview the files that would be removed.
+
+apply=0
+if [ "${1:-}" = "--apply" ]; then
+  apply=1
+elif [ -n "${1:-}" ]; then
+  printf '%s\n' "[ziniao-cli-shims] ERROR: unsupported option: $1" >&2
+  exit 2
+fi
+
+log() { printf '%s\n' "[ziniao-cli-shims] $*"; }
+
+home_dir="${HOME:?HOME is not set}"
+platform="$(uname -s 2>/dev/null || printf 'unknown')"
+case "$platform" in
+  Darwin) default_dir="$home_dir/Library/Application Support/ziniaobrowser/cli" ;;
+  Linux) default_dir="${XDG_CONFIG_HOME:-$home_dir/.config}/ziniaobrowser/cli" ;;
+  *)
+    log "ERROR: unsupported operating system: $platform"
+    exit 1
+    ;;
+esac
+
+target_dir="${ZINIAO_APP_CACHE_DIR:-${default_dir%/cli}}/cli"
+found=0
+old_ifs="$IFS"
+IFS=:
+for path_entry in ${PATH:-}; do
+  IFS="$old_ifs"
+  directory="${path_entry%/}"
+  [ -n "$directory" ] || continue
+  [ "$directory" = "${target_dir%/}" ] && continue
+  shim_path="$directory/ziniao"
+  [ -e "$shim_path" ] || [ -L "$shim_path" ] || continue
+  found=1
+  if [ "$apply" -eq 1 ]; then
+    rm -f -- "$shim_path"
+    log "Removed: $shim_path"
+  else
+    log "Would remove: $shim_path"
+  fi
+  IFS=:
+done
+IFS="$old_ifs"
+
+stable_shim="$home_dir/.local/bin/ziniao"
+if [ -e "$stable_shim" ] || [ -L "$stable_shim" ]; then
+  if [ "$stable_shim" != "$target_dir/ziniao" ]; then
+    found=1
+    if [ "$apply" -eq 1 ]; then
+      rm -f -- "$stable_shim"
+      log "Removed: $stable_shim"
+    else
+      log "Would remove: $stable_shim"
+    fi
+  fi
+fi
+
+cache_found=0
+if [ -d "$target_dir" ]; then
+  cache_found=1
+  if [ "$apply" -eq 1 ]; then
+    if [ -f "$target_dir/ziniao" ] || [ -L "$target_dir/ziniao" ]; then
+      rm -f -- "$target_dir/ziniao"
+    fi
+    if rmdir "$target_dir" 2>/dev/null; then
+      log "Removed CLI cache directory: $target_dir"
+    else
+      log "WARN: CLI cache directory is not empty; keeping it: $target_dir"
+    fi
+  else
+    log "Would remove CLI cache directory: $target_dir"
+  fi
+fi
+
+if [ "$found" -eq 0 ] && [ "$cache_found" -eq 0 ]; then
+  log "No ziniao shims found in PATH directories."
+elif [ "$apply" -eq 0 ]; then
+  log "Preview only. Re-run with --apply to remove these files."
+fi

package/scripts/setup-ziniao-cli.ps1

@@ -0,0 +1,179 @@
+# Synchronize the Ziniao desktop CLI into the per-user AppCache and register
+# that directory in the current user's PATH.
+#
+# Use `. .\scripts\setup-ziniao-cli.ps1` to refresh the current PowerShell.
+# A normal invocation persists PATH but cannot modify its parent PowerShell.
+
+$ErrorActionPreference = "Stop"
+$isDotSourced = $MyInvocation.InvocationName -eq "."
+
+function Write-Log([string]$Message) {
+  Write-Output "[ziniao-cli-path] $Message"
+}
+
+$arch = if ([Environment]::Is64BitOperatingSystem) {
+  if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE }
+} else { $env:PROCESSOR_ARCHITECTURE }
+switch ($arch.ToLowerInvariant()) {
+  "amd64" { $archDir = "x64" }
+  "x86_64" { $archDir = "x64" }
+  "arm64" { $archDir = "arm64" }
+  default { throw "Unsupported CPU architecture: $arch" }
+}
+
+$sourceName = "ziniao.exe"
+$sourceRelative = Join-Path "envkit\cli\win32\$archDir" $sourceName
+$resourceRoot = "resources\app.asar.unpacked"
+
+$sourcePath = $null
+$guiExecutablePath = $null
+$checkedSourcePaths = @()
+if ($env:ZINIAO_CLI_SOURCE -and (Test-Path -LiteralPath $env:ZINIAO_CLI_SOURCE -PathType Leaf)) {
+  $sourcePath = $env:ZINIAO_CLI_SOURCE
+}
+if (-not $sourcePath -and $env:ZINIAO_INSTALL_DIR) {
+  $candidate = Join-Path $env:ZINIAO_INSTALL_DIR "$resourceRoot\$sourceRelative"
+  $checkedSourcePaths += $candidate
+  if (Test-Path -LiteralPath $candidate -PathType Leaf) {
+    $sourcePath = $candidate
+  }
+}
+if (-not $sourcePath) {
+  $uninstallKeys = @(
+    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*",
+    "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*",
+    "HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
+  )
+  $uninstallEntries = Get-ItemProperty $uninstallKeys -ErrorAction SilentlyContinue |
+    Where-Object { $_.DisplayIcon -and $_.DisplayIcon -match "ziniao\.exe" }
+  foreach ($entry in $uninstallEntries) {
+    $displayIcon = ([string]$entry.DisplayIcon).Trim()
+    if ($displayIcon -match '^\s*"([^"]+\.exe)"') {
+      $executablePath = $matches[1]
+    } elseif ($displayIcon -match '^\s*(.*?\.exe)(?:,\d+)?(?:\s|$)') {
+      $executablePath = $matches[1]
+    } else {
+      continue
+    }
+    if (-not (Test-Path -LiteralPath $executablePath -PathType Leaf)) { continue }
+    $guiExecutablePath = $executablePath
+    $installDir = Split-Path -Parent $executablePath
+    $candidate = Join-Path $installDir "$resourceRoot\$sourceRelative"
+    $checkedSourcePaths += $candidate
+    if (Test-Path -LiteralPath $candidate -PathType Leaf) {
+      $sourcePath = $candidate
+      Write-Log "Found the Ziniao installation from the uninstall registry: $installDir"
+      break
+    }
+  }
+}
+if ($env:ZINIAO_APP_CACHE_DIR) {
+  $appCacheDir = $env:ZINIAO_APP_CACHE_DIR
+} else {
+  # The Windows GUI installs its CLI under %APPDATA%\ziniaobrowser\cli.
+  $appCacheDir = Join-Path $env:APPDATA "ziniaobrowser"
+}
+
+$targetDir = Join-Path $appCacheDir "cli"
+$targetPath = Join-Path $targetDir $sourceName
+New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+
+if ($guiExecutablePath) {
+  $guiPathFile = Join-Path $env:APPDATA "ziniaobrowser\gui-path"
+  try {
+    New-Item -ItemType Directory -Path (Split-Path -Parent $guiPathFile) -Force | Out-Null
+    [System.IO.File]::WriteAllText(
+      $guiPathFile,
+      "$guiExecutablePath$([Environment]::NewLine)",
+      [System.Text.Encoding]::ASCII
+    )
+    Write-Log "Wrote GUI path hint: $guiPathFile"
+  } catch {
+    Write-Log "WARN: Could not write GUI path hint: $($_.Exception.Message)"
+  }
+}
+
+function Get-FileSha256([string]$Path) {
+  $sha256 = [System.Security.Cryptography.SHA256]::Create()
+  $stream = [System.IO.File]::OpenRead($Path)
+  try {
+    return ([BitConverter]::ToString($sha256.ComputeHash($stream))).Replace("-", "")
+  } finally {
+    $stream.Dispose()
+    $sha256.Dispose()
+  }
+}
+
+if (-not $sourcePath) {
+  foreach ($checkedPath in ($checkedSourcePaths | Select-Object -Unique)) {
+    Write-Log "Checked CLI source path: $checkedPath"
+  }
+  if (Test-Path -LiteralPath $targetPath -PathType Leaf) {
+    Write-Log "CLI source was not found in the install directory; keeping the existing AppCache CLI: $targetPath"
+  } else {
+    Write-Log "WARN: ${sourceName} was not found in the install directory; skipping copy. Set `$env:ZINIAO_INSTALL_DIR or `$env:ZINIAO_CLI_SOURCE to override."
+  }
+} else {
+  $needsCopy = -not (Test-Path -LiteralPath $targetPath -PathType Leaf)
+  if (-not $needsCopy) {
+    $needsCopy = (Get-FileSha256 $sourcePath) -ne (Get-FileSha256 $targetPath)
+  }
+  if ($needsCopy) {
+    Copy-Item -LiteralPath $sourcePath -Destination $targetPath -Force
+    Write-Log "Synced CLI: $sourcePath -> $targetPath"
+  } else {
+    Write-Log "AppCache CLI is up to date: $targetPath"
+  }
+}
+
+function Install-PathShim {
+  if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) { return }
+  $windowsAppsDir = Join-Path $env:LOCALAPPDATA "Microsoft\WindowsApps"
+  foreach ($pathEntry in @($env:Path -split ";" | Where-Object { $_ })) {
+    $normalizedPath = $pathEntry.TrimEnd('\')
+    if ($normalizedPath -ieq $windowsAppsDir.TrimEnd('\') -and (Test-Path -LiteralPath $windowsAppsDir -PathType Container)) {
+      $shimPath = Join-Path $windowsAppsDir $sourceName
+      if (-not (Test-Path -LiteralPath $shimPath)) {
+        try {
+          Copy-Item -LiteralPath $targetPath -Destination $shimPath -ErrorAction Stop
+          $script:shimInstalled = $true
+          Write-Log "Created the CLI shim in WindowsApps: $shimPath"
+        } catch {
+          Write-Log "WARN: Could not create the CLI shim in WindowsApps: $($_.Exception.Message)"
+        }
+      } else {
+        Write-Log "WindowsApps already contains a file named $sourceName; leaving it unchanged"
+      }
+      return
+    }
+    if ($normalizedPath -ieq $targetDir.TrimEnd('\')) {
+      $script:shimInstalled = $true
+      Write-Log "The current PATH already contains the AppCache CLI directory: $targetDir"
+      return
+    }
+  }
+  Write-Log "The AppCache CLI directory is not on the current PATH; no shim was created in another directory."
+}
+
+$shimInstalled = $false
+Install-PathShim
+
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+$entries = @($userPath -split ";" | Where-Object { $_ })
+if (-not ($entries | Where-Object { $_.TrimEnd('\') -ieq $targetDir.TrimEnd('\') })) {
+  [Environment]::SetEnvironmentVariable("Path", (($entries + $targetDir) -join ";"), "User")
+  Write-Log "Added to the user PATH: $targetDir"
+}
+
+$currentEntries = @($env:Path -split ";" | Where-Object { $_ })
+if (-not ($currentEntries | Where-Object { $_.TrimEnd('\') -ieq $targetDir.TrimEnd('\') })) {
+  $env:Path = "$targetDir;$env:Path"
+}
+if ($shimInstalled) {
+  Write-Log "The CLI is already available on the current PATH; this PowerShell session needs no PATH refresh"
+} elseif ($isDotSourced) {
+  Write-Log "The current PowerShell PATH was refreshed"
+} else {
+  Write-Log "The current process PATH was refreshed; dot-source this script in the parent PowerShell or reopen the terminal"
+}
+Write-Log "Verification command: Get-Command ziniao"

package/scripts/setup-ziniao-cli.sh

@@ -0,0 +1,232 @@
+#!/bin/sh
+# Synchronize the Ziniao desktop CLI into the per-user AppCache and register
+# that directory in the current user's shell PATH.
+#
+# Use `source scripts/setup-ziniao-cli.sh` when the current shell should be
+# refreshed immediately. A normal execution can persist PATH but cannot modify
+# its parent shell.
+
+log() { printf '%s\n' "[ziniao-cli-path] $*"; }
+fail() { printf '%s\n' "[ziniao-cli-path] ERROR: $*" >&2; return 1 2>/dev/null || exit 1; }
+
+is_sourced=0
+if [ -n "${BASH_VERSION:-}" ]; then
+  [ "${BASH_SOURCE[0]:-$0}" != "$0" ] && is_sourced=1
+elif [ -n "${ZSH_EVAL_CONTEXT:-}" ]; then
+  case "$ZSH_EVAL_CONTEXT" in
+    *:file) is_sourced=1 ;;
+  esac
+fi
+
+if [ "$is_sourced" -eq 0 ]; then
+  set -eu
+fi
+
+platform="$(uname -s 2>/dev/null || printf 'unknown')"
+machine="$(uname -m 2>/dev/null || printf 'unknown')"
+
+case "$platform" in
+  Darwin) platform_dir="darwin"; source_name="ziniao"; ;;
+  Linux) platform_dir="linux"; source_name="ziniao"; ;;
+  MINGW*|MSYS*|CYGWIN*)
+    fail "Windows shell detected; use PowerShell: scripts/setup-ziniao-cli.ps1"
+    return 1 2>/dev/null || exit 1
+    ;;
+  *) fail "Unsupported operating system: $platform"; return 1 2>/dev/null || exit 1 ;;
+esac
+
+case "$machine" in
+  arm64|aarch64) arch_dir="arm64" ;;
+  x86_64|amd64) arch_dir="x64" ;;
+  *) fail "Unsupported CPU architecture: $machine"; return 1 2>/dev/null || exit 1 ;;
+esac
+
+home_dir="${HOME:?HOME is not set}"
+
+find_source() {
+  if [ -n "${ZINIAO_CLI_SOURCE:-}" ] && [ -f "$ZINIAO_CLI_SOURCE" ]; then
+    printf '%s\n' "$ZINIAO_CLI_SOURCE"
+    return 0
+  fi
+
+  for candidate_arch in "$arch_dir" x64 arm64; do
+    source_rel="envkit/cli/$platform_dir/$candidate_arch/$source_name"
+    if [ -n "${ZINIAO_INSTALL_DIR:-}" ]; then
+      candidate="$ZINIAO_INSTALL_DIR/$source_rel"
+      if [ -f "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+
+    for install_root in \
+      "/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Library/Application Support/ziniaobrowser/app.asar.unpacked" \
+      "/opt/ziniao/resources/app.asar.unpacked"; do
+      candidate="$install_root/$source_rel"
+      if [ -f "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    done
+  done
+  return 1
+}
+
+log_source_candidates() {
+  [ -n "${ZINIAO_CLI_SOURCE:-}" ] && log "Checked CLI source path: $ZINIAO_CLI_SOURCE"
+  for candidate_arch in "$arch_dir" x64 arm64; do
+    source_rel="envkit/cli/$platform_dir/$candidate_arch/$source_name"
+    [ -n "${ZINIAO_INSTALL_DIR:-}" ] && log "Checked CLI source path: $ZINIAO_INSTALL_DIR/$source_rel"
+    for install_root in \
+      "/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Library/Application Support/ziniaobrowser/app.asar.unpacked" \
+      "/opt/ziniao/resources/app.asar.unpacked"; do
+      log "Checked CLI source path: $install_root/$source_rel"
+    done
+  done
+}
+
+find_gui_executable() {
+  case "$platform_dir" in
+    darwin)
+      for candidate in \
+        "/Applications/ziniao.app/Contents/MacOS/ziniaobrowser" \
+        "/Applications/ziniao.app/Contents/MacOS/ziniao" \
+        "$home_dir/Applications/ziniao.app/Contents/MacOS/ziniaobrowser" \
+        "$home_dir/Applications/ziniao.app/Contents/MacOS/ziniao"; do
+        [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+      done
+      ;;
+    linux)
+      for candidate in \
+        "/opt/ziniao/ziniaobrowser" \
+        "/opt/ziniao/ziniao" \
+        "/usr/lib/ziniaobrowser/ziniaobrowser" \
+        "/usr/lib/ziniaobrowser/ziniao"; do
+        [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+      done
+      ;;
+  esac
+  return 1
+}
+
+if [ -n "${ZINIAO_APP_CACHE_DIR:-}" ]; then
+  target_dir="$ZINIAO_APP_CACHE_DIR/cli"
+else
+  case "$platform_dir" in
+    darwin) target_dir="$home_dir/Library/Application Support/ziniaobrowser/cli" ;;
+    *) target_dir="${XDG_CONFIG_HOME:-$home_dir/.config}/ziniaobrowser/cli" ;;
+  esac
+fi
+
+source_path="$(find_source || true)"
+gui_executable_path="$(find_gui_executable || true)"
+target_path="$target_dir/$source_name"
+mkdir -p "$target_dir"
+
+if [ -n "$source_path" ]; then
+  log "CLI source path: $source_path"
+else
+  log_source_candidates
+fi
+
+if [ -n "$gui_executable_path" ]; then
+  case "$platform_dir" in
+    darwin) gui_path_file="$home_dir/Library/Application Support/ziniaobrowser/gui-path" ;;
+    *)
+      xdg_config_home="${XDG_CONFIG_HOME:-$home_dir/.config}"
+      gui_path_file="$xdg_config_home/ziniaobrowser/gui-path"
+      ;;
+  esac
+  if mkdir -p "$(dirname "$gui_path_file")" && printf '%s\n' "$gui_executable_path" > "$gui_path_file"; then
+    log "Wrote GUI path hint: $gui_path_file"
+  else
+    log "WARN: Could not write GUI path hint: $gui_path_file"
+  fi
+fi
+if [ -z "$source_path" ]; then
+  if [ -f "$target_path" ]; then
+    log "CLI source was not found in the install directory; keeping the existing AppCache CLI: $target_path"
+  else
+    log "WARN: ${source_name} was not found in the install directory; skipping copy. Set ZINIAO_INSTALL_DIR or ZINIAO_CLI_SOURCE to override."
+  fi
+elif [ ! -f "$target_path" ] || ! cmp -s "$source_path" "$target_path"; then
+  cp "$source_path" "$target_path"
+  chmod 755 "$target_path"
+  log "Synced CLI: $source_path -> $target_path"
+else
+  log "AppCache CLI is up to date: $target_path"
+fi
+
+shim_installed=0
+install_path_shim() {
+  [ -f "$target_path" ] || return 0
+  shim_dir="$home_dir/.local/bin"
+  shim_path="$shim_dir/$source_name"
+  mkdir -p "$shim_dir"
+  if [ -L "$shim_path" ] && [ "$(readlink "$shim_path" 2>/dev/null || true)" = "$target_path" ]; then
+    shim_installed=1
+    log "The CLI shim already points to the AppCache CLI: $shim_path"
+  elif [ ! -e "$shim_path" ]; then
+    if ln -s "$target_path" "$shim_path" 2>/dev/null; then
+      shim_installed=1
+      log "Created the CLI shim: $shim_path"
+    else
+      log "WARN: Could not create the CLI shim: $shim_path"
+    fi
+  else
+    log "A file already exists at the CLI shim path; leaving it unchanged: $shim_path"
+  fi
+  case ":${PATH:-}:" in
+    *:"$target_dir":*)
+      shim_installed=1
+      log "The current PATH already contains the AppCache CLI directory: $target_dir"
+      ;;
+    *:"$shim_dir":*)
+      [ "$shim_installed" -eq 1 ] && log "The current PATH contains the CLI shim directory: $shim_dir"
+      ;;
+    *)
+      log "The AppCache CLI directory is not on the current PATH; no shim will be created elsewhere: $target_dir"
+      ;;
+  esac
+}
+
+install_path_shim
+
+shim_dir="$home_dir/.local/bin"
+export PATH="$target_dir:$shim_dir${PATH:+:$PATH}"
+
+profile=""
+case "${SHELL:-}" in
+  */zsh) profile="$home_dir/.zshrc" ;;
+  */bash) profile="$home_dir/.bashrc" ;;
+esac
+if [ -z "$profile" ]; then
+  case "$platform_dir" in
+    darwin) profile="$home_dir/.zshrc" ;;
+    *) profile="$home_dir/.profile" ;;
+  esac
+fi
+
+marker="# ziniao-cli: AppCache CLI PATH"
+path_line="export PATH=\"$target_dir:$shim_dir:\$PATH\""
+if ! grep -Fqx "$marker" "$profile" 2>/dev/null; then
+  mkdir -p "$(dirname "$profile")"
+  printf '\n%s\n' "$marker" >> "$profile"
+  log "Added to shell profile: $profile"
+fi
+if ! grep -Fqx "$path_line" "$profile" 2>/dev/null; then
+  printf '%s\n' "$path_line" >> "$profile"
+fi
+
+if [ "$shim_installed" -eq 1 ]; then
+  log "The CLI is already on the current PATH; this terminal needs no PATH refresh"
+elif [ "$is_sourced" -eq 1 ]; then
+  log "The current shell PATH was refreshed"
+else
+  log "The current process PATH was refreshed; source \"$profile\" in the parent terminal"
+fi
+log "Verification command: command -v $source_name"