feat(shell-completion): 为 apm 添加 fish 和 zsh 的自动补全支持

添加 fish 和 zsh 的自动补全脚本，支持所有 apm 命令及其选项
docs: 更新README命令说明并添加AGENTS文档
2026-06-22 14:13:54 +08:00 · 2026-03-29 13:34:10 +08:00 · 2026-03-29 13:24:55 +08:00 · 2026-03-29 13:22:28 +08:00
7 changed files with 759 additions and 72 deletions
@@ -0,0 +1,194 @@
+# APM 代理与助手（AGENTS）
+
+本文档描述了 APM 项目中使用的代理和助手工具，它们用于增强 APM 的功能和用户体验。
+
+## 1. 核心代理工具
+
+### 1.1 amber-pm-debug
+
+**功能**：用于在 APM 环境中执行命令，提供调试和诊断功能。
+
+**使用场景**：
+- 执行 apt 相关命令
+- 执行 dpkg 相关命令
+- 进入调试环境
+
+**示例**：
+```bash
+amber-pm-debug apt update
+amber-pm-debug dpkg --configure -a
+```
+
+### 1.2 amber-pm-app-launcher
+
+**功能**：通过应用启动器启动 APM 软件包。
+
+**使用场景**：
+- 启动已安装的 APM 应用
+- 传递参数给应用
+
+**示例**：
+```bash
+amber-pm-app-launcher firefox
+amber-pm-app-launcher gedit --new-document
+```
+
+### 1.3 amber-pm-configure-nvidia
+
+**功能**：配置 NVIDIA 驱动支持。
+
+**使用场景**：
+- 自动从主机获取 NVIDIA 驱动文件
+- 为 APM 应用提供 GPU 加速支持
+
+**示例**：
+```bash
+amber-pm-configure-nvidia /path/to/ace-env
+```
+
+## 2. 构建与转换工具
+
+### 2.1 amber-pm-convert
+
+**功能**：将普通 Deb 包转换为 APM 软件包。
+
+**使用场景**：
+- 转换第三方 Deb 包为 APM 格式
+- 自定义包名和版本号
+
+**示例**：
+```bash
+amber-pm-convert --base amber-pm-trixie /path/to/package.deb
+amber-pm-convert --base amber-pm-bookworm-spark-wine /path/to/package.deb --pkgname new-pkg --version 1.0.0
+```
+
+### 2.2 amber-pm-dstore-patch
+
+**功能**：修补应用商店相关配置。
+
+**使用场景**：
+- 安装或更新软件包后自动执行
+- 确保应用商店配置正确
+
+### 2.3 amber-pm-gxde-desktop-fix
+
+**功能**：修复 GXDE 桌面环境相关问题。
+
+**使用场景**：
+- 安装或移除软件包后自动执行
+- 确保桌面环境正常运行
+
+## 3. 沙箱与安全工具
+
+### 3.1 APM_USE_SANDBOX
+
+**功能**：启用主目录沙箱化。
+
+**使用场景**：
+- 运行不受信任的应用
+- 保护用户主目录
+
+**示例**：
+```bash
+apm sandbox-run firefox
+```
+
+### 3.2 APM_USE_BWRAP
+
+**功能**：使用 bwrap 进行额外的隔离。
+
+**使用场景**：
+- 需要更强隔离性的应用
+- 增强安全性
+
+**示例**：
+```bash
+apm bwrap-run firefox
+```
+
+## 4. 本地安装工具
+
+### 4.1 ssinstall
+
+**功能**：使用 ssinstall 进行本地软件安装。
+
+**使用场景**：
+- 安装本地软件包
+- 与 spark-store 集成
+
+**示例**：
+```bash
+apm ssinstall /path/to/package
+```
+
+### 4.2 ssaudit
+
+**功能**：使用 ssaudit 进行本地软件安装。
+
+**使用场景**：
+- 安装本地软件包并进行审计
+- 与 spark-store 集成
+
+**示例**：
+```bash
+apm ssaudit /path/to/package
+```
+
+## 5. 环境变量
+
+### 5.1 APM_PKG_NAME
+
+**功能**：指定当前运行的包名。
+
+**使用场景**：
+- 在脚本中识别当前包
+- 为应用提供包信息
+
+### 5.2 PATH_PREFIX
+
+**功能**：指定 APM 基础路径。
+
+**使用场景**：
+- 自定义 APM 安装位置
+- 多环境管理
+
+## 6. 工作原理
+
+APM 代理和助手工具通过以下方式工作：
+
+1. **环境隔离**：使用 fuse-overlayfs 创建隔离的文件系统环境
+2. **命令转发**：将用户命令转发到适当的环境中执行
+3. **资源共享**：从主机系统获取必要的资源（如 NVIDIA 驱动）
+4. **安全增强**：提供沙箱和隔离机制
+5. **用户体验**：简化应用的安装和运行过程
+
+## 7. 故障排除
+
+### 7.1 常见问题
+
+- **NVIDIA 驱动问题**：确保主机已安装 NVIDIA 驱动，APM 会自动检测并使用
+- **沙箱权限**：确保用户有足够的权限创建和管理沙箱
+- **包依赖**：使用 `apm show <package>` 查看包依赖，确保所有依赖已安装
+
+### 7.2 调试命令
+
+```bash
+# 查看调试信息
+apm debug
+
+# 检查包状态
+amber-pm-debug dpkg -l | grep <package>
+
+# 检查 NVIDIA 配置
+apm-nvidia-toggle
+```
+
+## 8. 扩展与定制
+
+APM 代理系统设计为可扩展的，您可以：
+
+1. **添加自定义代理**：在 `src/var/lib/apm/apm/files/ace-env/usr/bin/` 目录添加新的代理脚本
+2. **修改现有代理**：根据需要调整现有代理的行为
+3. **创建自定义基础环境**：使用 `amber-pm-convert` 工具创建基于特定需求的基础环境
+
+通过这些工具和技术，APM 提供了一个灵活、安全、高效的软件包管理系统，适用于各种 Linux 发行版。
@@ -37,32 +37,28 @@ Usage:
 Commands:
  install           安装软件包
  remove            卸载软件包
-  run <package>     运行指定软件包的可执行文件
-  sandbox-run <package> 运行指定软件包的可执行文件（主目录沙箱化）
-
+  launch <package> [args...]  启动软件包（通过应用启动器）
+  run <package> [EXEC_PATH] [args...]  运行指定软件包的可执行文件（可指定容器内路径）
  update            更新软件包信息
-  hold              锁定软件包版本
-  unhold            解锁软件包版本
-  full-upgrade      升级全部软件包
  list              查看可用软件包信息
  search            搜索软件包
-
-  download          下载包
  show              展示包信息
  clean             清除缓存软件包
  autoremove        自动移除不需要的包
-  ssaudit <path>    使用 ssaudit 进行本地软件安装，详情见 spark-store
-  debug             显示调试系统信息并进入调试环境

  amber             彩蛋功能
  xmp360            彩蛋功能
  bronya            彩蛋功能

  -h, --help        显示此帮助信息
+  --help-all        显示完整帮助信息
  -v, --version     展示APM版本号

 ```

+### 完整命令列表
+使用 `apm --help-all` 查看完整的命令列表，包括高级命令如 `sandbox-run`、`bwrap-run`、`hold`、`unhold`、`full-upgrade`、`download`、`ssinstall`、`ssaudit`、`debug` 等。
+



@@ -1 +1 @@
-@VERSION@=1.2.1
+@VERSION@=1.2.2
@@ -18,13 +18,105 @@ Usage:
  $SCRIPT_NAME [COMMAND] [OPTIONS] [PACKAGES...]


+Commands:
+  install           安装软件包
+  remove            卸载软件包
+  launch <package> [args...]  启动软件包（通过应用启动器）
+  run <package> [EXEC_PATH] [args...]  运行指定软件包的可执行文件（可指定容器内路径）
+  update            更新软件包信息
+  list              查看可用软件包信息
+  search            搜索软件包
+  show              展示包信息
+  clean             清除缓存软件包
+  autoremove        自动移除不需要的包
+
+  amber             彩蛋功能
+  xmp360            彩蛋功能
+  bronya            彩蛋功能
+
+  -h, --help        显示此帮助信息
+  --help-all        显示完整帮助信息
+  -v, --version     展示APM版本号
+
+                                            本 APM 具有兔兔伯爵，女武神装甲和超级大运之力。
+EOF
+}
+# 彩蛋函数
+amber_egg() {
+    cat <<'EOF'
+
+    ____                            ____                         
+   / __ )____ __________  ____     / __ )__  ______  ____  __  __
+  / __  / __ `/ ___/ __ \/ __ \   / __  / / / / __ \/ __ \/ / / /
+ / /_/ / /_/ / /  / /_/ / / / /  / /_/ / /_/ / / / / / / / /_/ / 
+/_____/\__,_/_/   \____/_/ /_/  /_____/\__,_/_/ /_/_/ /_/\__, /  
+                                                        /____/   
+
+Amber Package Manager - Sparkling with magic! 安柏包管理器 - blingbling～
+💎 Another target tracked down by Outrider Amber! 侦察骑士，发现目标！
+EOF
+}
+
+bronya_egg() {
+    cat <<'EOF'
+  _   __     ____            _       ____         __              
+ | | / /__ _/ / /____ ______(_)__   / __/_ _____ / /____ __ _     
+ | |/ / _ `/ /  '_/ // / __/ / _-) _\ \/ // (_-</ __/ -_)  ' \    
+ |___/\_,_/_/_/\_\\_, /_/ /_/\__/ /___/\_, /___/\__/\__/_/_/_/    
+  / /  ___ ___ __/___/____/ /         /___/                       
+ / /__/ _ `/ // / _ \/ __/ _ \                                    
+/____/\_,_/_,_/_//_/\__/_//_/        
+
+Valkyrie 系统启动 - 重装小兔，Fire！
+💎 感谢 Anysets 为 AmberCE 和 AmberPM 的 Arch 架构支持提供帮助～
+EOF
+}
+
+xmp360_egg() {
+    cat <<'EOF'
+################################################################################
+################################################################################
+################################################################################
+#####################                                       ####################
+####################.                                       %###################
+##########=                                                 ####################
+############################                                #=========*#########
+#############                                              .%   .*****=  :######
+###############################                            =+   =#######* -#####
+#####                                                      %:   *######## :#####
+######################%                                    #    ########* +#####
+########:                                                  #              %#####
+##########################                                .#              ######
+##################*                                       -*              ######
+##################=        =###%:                         +-    *###*     ######
+##################.      #       %:                          :*       #  -######
+##################.     %  *###=  %                         --  ####   % %######
+########################-  ####+  ###########################  .####.  #########
+#########################        ############################%        ##########
+###########################=::+################################%-:-*############
+################################################################################
+
+哇——————袄 - 撞大运咯！
+💎 感谢 潇湘·秀 为 APM 的 RPM 架构支持提供帮助～
+EOF
+}
+
+# 完整帮助信息函数
+show_help_all() {
+    cat <<EOF
+APM - Amber Package Manager ${VERSION}
+
+Usage:
+  $SCRIPT_NAME [COMMAND] [OPTIONS] [PACKAGES...]
+
+
 Commands:
  install           安装软件包
  remove            卸载软件包
  launch <package> [args...]  启动软件包（通过应用启动器）
  run <package> [EXEC_PATH] [args...]  运行指定软件包的可执行文件（可指定容器内路径）
  sandbox-run <package> [EXEC_PATH] [args...] 运行指定软件包的可执行文件（主目录沙箱化）
-  bwrap-run <package> [EXEC_PATH] [args...] 运行指定软件包的可执行文件（使用特殊的挂载参数以支持bwrap）
+  bwrap-run <package> [EXEC_PATH] [args...] 运行指定软件包的可执行文件（使用 bwrap）

  update            更新软件包信息
  hold              锁定软件包版本
@@ -37,6 +129,7 @@ Commands:
  show              展示包信息
  clean             清除缓存软件包
  autoremove        自动移除不需要的包
+  ssinstall <path>    使用 ssinstall 进行本地软件安装，详情见 spark-store
  ssaudit <path>    使用 ssaudit 进行本地软件安装，详情见 spark-store
  debug             显示调试系统信息并进入调试环境

@@ -44,7 +137,8 @@ Commands:
  xmp360            彩蛋功能
  bronya            彩蛋功能

-  -h, --help        显示此帮助信息
+  -h, --help        显示简要帮助信息
+  --help-all        显示此完整帮助信息
  -v, --version     展示APM版本号

                                            本 APM 具有兔兔伯爵，女武神装甲和超级大运之力。
@@ -241,65 +335,6 @@ amber-pm-debug "$@"

 }

-# 彩蛋函数
-amber_egg() {
-    cat <<'EOF'
-
-    ____                            ____                         
-   / __ )____ __________  ____     / __ )__  ______  ____  __  __
-  / __  / __ `/ ___/ __ \/ __ \   / __  / / / / __ \/ __ \/ / / /
- / /_/ / /_/ / /  / /_/ / / / /  / /_/ / /_/ / / / / / / / /_/ / 
-/_____/\__,_/_/   \____/_/ /_/  /_____/\__,_/_/ /_/_/ /_/\__, /  
-                                                        /____/   
-
-Amber Package Manager - Sparkling with magic! 安柏包管理器 - blingbling～
-💎 Another target tracked down by Outrider Amber! 侦察骑士，发现目标！
-EOF
-}
-
-bronya_egg() {
-    cat <<'EOF'
-  _   __     ____            _       ____         __              
- | | / /__ _/ / /____ ______(_)__   / __/_ _____ / /____ __ _     
- | |/ / _ `/ /  '_/ // / __/ / _-) _\ \/ // (_-</ __/ -_)  ' \    
- |___/\_,_/_/_/\_\\_, /_/ /_/\__/ /___/\_, /___/\__/\__/_/_/_/    
-  / /  ___ ___ __/___/____/ /         /___/                       
- / /__/ _ `/ // / _ \/ __/ _ \                                    
-/____/\_,_/_,_/_//_/\__/_//_/        
-
-Valkyrie 系统启动 - 重装小兔，Fire！
-💎 感谢 Anysets 为 AmberCE 和 AmberPM 的 Arch 架构支持提供帮助～
-EOF
-}
-
-xmp360_egg() {
-    cat <<'EOF'
-################################################################################
-################################################################################
-################################################################################
-#####################                                       ####################
-####################.                                       %###################
-##########=                                                 ####################
-############################                                #=========*#########
-#############                                              .%   .*****=  :######
-###############################                            =+   =#######* -#####
-#####                                                      %:   *######## :#####
-######################%                                    #    ########* +#####
-########:                                                  #              %#####
-##########################                                .#              ######
-##################*                                       -*              ######
-##################=        =###%:                         +-    *###*     ######
-##################.      #       %:                          :*       #  -######
-##################.     %  *###=  %                         --  ####   % %######
-########################-  ####+  ###########################  .####.  #########
-#########################        ############################%        ##########
-###########################=::+################################%-:-*############
-################################################################################
-
-哇——————袄 - 撞大运咯！
-💎 感谢 潇湘·秀 为 APM 的 RPM 架构支持提供帮助～
-EOF
-}

 apm-nvidia-toggle(){

@@ -479,10 +514,27 @@ case "$1" in
        amber-pm-debug amber-pm-dstore-patch
        amber-pm-gxde-desktop-fix

+        ;;
+    ssinstall)
+        amber-pm-debug dpkg --configure -a
+        amber-pm-debug ssinstall $@ --native
+        exit_code=$?
+    if [ $exit_code -eq 0 ]; then
+        log.info "Operation successful"
+    else
+        log.error "Error: Operation failed"
+        exit $exit_code
+    fi
+        amber-pm-debug amber-pm-dstore-patch
+        amber-pm-gxde-desktop-fix
+
        ;;
    -h|--help)
        show_help
        ;;
+    --help-all)
+        show_help_all
+        ;;
    -v|--version)
        echo "$VERSION"
        ;;
@@ -37,6 +37,7 @@ _apm()
    # see if the user selected a command already
    local COMMANDS=(
        "ssaudit"
+        "ssinstall"
        "launch"
        "list"
        "search"
@@ -300,6 +301,11 @@ get_arg_position() {
                _filedir
                return 0
                ;;
+            ssinstall)
+                # ssinstall 命令总是匹配文件
+                _filedir
+                return 0
+                ;;
        esac
    fi

@@ -0,0 +1,248 @@
+# APM 琥珀软件包管理器的 fish 自动补全
+
+# 定义命令列表
+set -l commands \
+  ssaudit \
+  ssinstall \
+  launch \
+  list \
+  search \
+  show \
+  showsrc \
+  install \
+  remove \
+  purge \
+  autoremove \
+  autopurge \
+  update \
+  upgrade \
+  full-upgrade \
+  dist-upgrade \
+  run \
+  sandbox-run \
+  bwrap-run \
+  help \
+  source \
+  build-dep \
+  clean \
+  autoclean \
+  download \
+  changelog \
+  amber \
+  xmp360 \
+  bronya \
+  debug \
+  depends \
+  rdepends \
+  policy
+
+# 定义通用选项
+set -l options \
+  -h \
+  --help \
+  --help-all \
+  -v \
+  --version
+
+# 定义命令特定选项
+set -l install_options \
+  -d \
+  --download-only \
+  -y \
+  --assume-yes \
+  --assume-no \
+  -u \
+  --show-upgraded \
+  -m \
+  --ignore-missing \
+  -t \
+  --target-release \
+  --download \
+  --fix-missing \
+  --ignore-hold \
+  --upgrade \
+  --only-upgrade \
+  --allow-change-held-packages \
+  --allow-remove-essential \
+  --allow-downgrades \
+  --print-uris \
+  --trivial-only \
+  --remove \
+  --arch-only \
+  --allow-unauthenticated \
+  --allow-insecure-repositories \
+  --install-recommends \
+  --install-suggests \
+  --no-install-recommends \
+  --no-install-suggests \
+  --fix-policy \
+  --show-progress \
+  --fix-broken \
+  --purge \
+  --verbose-versions \
+  --auto-remove \
+  -s \
+  --simulate \
+  --dry-run \
+  --force-yes \
+  --reinstall \
+  --solver
+
+set -l remove_options $install_options
+
+set -l update_options \
+  --list-cleanup \
+  --print-uris \
+  --allow-insecure-repositories
+
+set -l list_options \
+  --installed \
+  --upgradable \
+  --manual-installed \
+  -v \
+  --verbose \
+  -a \
+  --all-versions \
+  -t \
+  --target-release
+
+set -l show_options \
+  -a \
+  --all-versions
+
+set -l depends_options \
+  -i \
+  --important \
+  --installed \
+  --pre-depends \
+  --depends \
+  --recommends \
+  --suggests \
+  --replaces \
+  --breaks \
+  --conflicts \
+  --enhances \
+  --recurse \
+  --implicit
+
+set -l search_options \
+  -n \
+  --names-only \
+  -f \
+  --full
+
+set -l showsrc_options \
+  --only-source
+
+set -l source_options $install_options \
+  -b \
+  --compile \
+  --build \
+  -P \
+  --build-profiles \
+  --diff-only \
+  --debian-only \
+  --tar-only \
+  --dsc-only
+
+set -l build_dep_options $install_options \
+  -a \
+  --host-architecture \
+  -P \
+  --build-profiles \
+  --purge \
+  --solver
+
+set -l clean_options \
+  -s \
+  --simulate \
+  --dry-run
+
+set -l autoclean_options $clean_options
+
+# 定义目录路径
+set -l primary_dir "/var/lib/apm/apm/files/ace-env/var/lib/apm/"
+set -l fallback_dir "/var/lib/apm/"
+
+# 查找不包含特定子目录的目录
+function find_directories_without_ace_env
+  set -l base_dir $argv[1]
+  set -l result
+  
+  # 检查基础目录是否存在
+  if not test -d "$base_dir"
+    return 1
+  end
+  
+  # 查找所有直接子目录，排除包含ace-env子目录的目录
+  for dir in "$base_dir"/*
+    if test -d "$dir" && not test -d "$dir/files/ace-env"
+      set result $result (basename "$dir")
+    end
+  end
+  
+  # 输出结果
+  if test (count $result) -gt 0
+    echo $result
+    return 0
+  end
+  return 1
+end
+
+function apm_run_compgen
+  set -l result (find_directories_without_ace_env "$primary_dir")
+
+  if test -n "$result"
+    echo $result
+  else
+    set result (find_directories_without_ace_env "$fallback_dir")
+    if test -n "$result"
+      echo $result
+    else
+      echo ""
+    end
+  end
+end
+
+# 主完成函数
+complete -c apm -n "not __fish_seen_subcommand_from $commands" -a "$options" -d "选项"
+complete -c apm -n "not __fish_seen_subcommand_from $commands" -a "$commands" -d "命令"
+
+# 命令特定的完成
+complete -c apm -n "__fish_seen_subcommand_from install" -a "$install_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from install" -k -A "*.deb" -d "Deb 包"
+
+complete -c apm -n "__fish_seen_subcommand_from remove purge autoremove autopurge" -a "$remove_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from remove purge autoremove autopurge" -k -F "ls -1 $primary_dir 2>/dev/null || ls -1 $fallback_dir 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from update" -a "$update_options" -d "选项"
+
+complete -c apm -n "__fish_seen_subcommand_from list" -a "$list_options" -d "选项"
+
+complete -c apm -n "__fish_seen_subcommand_from show" -a "$show_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from show" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from depends rdepends" -a "$depends_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from depends rdepends" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from search" -a "$search_options" -d "选项"
+
+complete -c apm -n "__fish_seen_subcommand_from showsrc" -a "$showsrc_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from showsrc" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from source" -a "$source_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from source" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from build-dep" -a "$build_dep_options" -d "选项"
+complete -c apm -n "__fish_seen_subcommand_from build-dep" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from clean" -a "$clean_options" -d "选项"
+
+complete -c apm -n "__fish_seen_subcommand_from autoclean" -a "$autoclean_options" -d "选项"
+
+complete -c apm -n "__fish_seen_subcommand_from download changelog policy" -k -F "amber-pm-debug apt-cache --no-generate pkgnames '' -o Dir::Cache=/var/lib/aptss/ 2>/dev/null" -d "包"
+
+complete -c apm -n "__fish_seen_subcommand_from run sandbox-run bwrap-run launch" -k -F "apm_run_compgen" -d "包"
+complete -c apm -n "__fish_seen_subcommand_from run sandbox-run bwrap-run launch" -k -A "*" -d "文件"
+
+complete -c apm -n "__fish_seen_subcommand_from ssaudit ssinstall" -k -A "*" -d "文件"
@@ -0,0 +1,191 @@
+#compdef apm
+
+local context state line
+local -a commands options
+
+# 定义命令列表
+commands=(  
+  'ssaudit:使用 ssaudit 进行本地软件安装'
+  'ssinstall:使用 ssinstall 进行本地软件安装'
+  'launch:启动软件包（通过应用启动器）'
+  'list:查看可用软件包信息'
+  'search:搜索软件包'
+  'show:展示包信息'
+  'showsrc:展示源码包信息'
+  'install:安装软件包'
+  'remove:卸载软件包'
+  'purge:彻底卸载软件包'
+  'autoremove:自动移除不需要的包'
+  'autopurge:自动彻底移除不需要的包'
+  'update:更新软件包信息'
+  'upgrade:升级软件包'
+  'full-upgrade:升级全部软件包'
+  'dist-upgrade:分发升级'
+  'run:运行指定软件包的可执行文件'
+  'sandbox-run:运行指定软件包的可执行文件（主目录沙箱化）'
+  'bwrap-run:运行指定软件包的可执行文件（使用 bwrap）'
+  'help:显示帮助信息'
+  'source:获取源码包'
+  'build-dep:安装构建依赖'
+  'clean:清除缓存软件包'
+  'autoclean:自动清除缓存软件包'
+  'download:下载包'
+  'changelog:查看包的变更日志'
+  'amber:彩蛋功能'
+  'xmp360:彩蛋功能'
+  'bronya:彩蛋功能'
+  'debug:显示调试系统信息并进入调试环境'
+  'depends:查看包依赖'
+  'rdepends:查看反向依赖'
+  'policy:查看包策略'
+)
+
+# 定义通用选项
+options=(  
+  '-h[显示帮助信息]'
+  '--help[显示帮助信息]'
+  '--help-all[显示完整帮助信息]'
+  '-v[展示APM版本号]'
+  '--version[展示APM版本号]'
+)
+
+# 定义命令特定选项
+local -A command_options
+command_options=(  
+  'install' '-d[仅下载不安装] --download-only[仅下载不安装] -y[自动回答是] --assume-yes[自动回答是] --assume-no[自动回答否] -u[显示已升级的包] --show-upgraded[显示已升级的包] -m[忽略缺失的包] --ignore-missing[忽略缺失的包] -t[指定目标发行版] --target-release[指定目标发行版] --download[下载] --fix-missing[修复缺失的包] --ignore-hold[忽略被锁定的包] --upgrade[升级] --only-upgrade[仅升级] --allow-change-held-packages[允许更改被锁定的包] --allow-remove-essential[允许移除 essential 包] --allow-downgrades[允许降级] --print-uris[打印 URI] --trivial-only[仅处理简单的升级] --remove[移除] --arch-only[仅处理架构相关的包] --allow-unauthenticated[允许未认证的包] --allow-insecure-repositories[允许不安全的仓库] --install-recommends[安装推荐的包] --install-suggests[安装建议的包] --no-install-recommends[不安装推荐的包] --no-install-suggests[不安装建议的包] --fix-policy[修复策略] --show-progress[显示进度] --fix-broken[修复损坏的包] --purge[彻底移除] --verbose-versions[显示详细版本信息] --auto-remove[自动移除不需要的包] -s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行] --force-yes[强制回答是] --reinstall[重新安装] --solver[指定解算器]'
+  'remove' '-d[仅下载不安装] --download-only[仅下载不安装] -y[自动回答是] --assume-yes[自动回答是] --assume-no[自动回答否] -u[显示已升级的包] --show-upgraded[显示已升级的包] -m[忽略缺失的包] --ignore-missing[忽略缺失的包] -t[指定目标发行版] --target-release[指定目标发行版] --download[下载] --fix-missing[修复缺失的包] --ignore-hold[忽略被锁定的包] --upgrade[升级] --only-upgrade[仅升级] --allow-change-held-packages[允许更改被锁定的包] --allow-remove-essential[允许移除 essential 包] --allow-downgrades[允许降级] --print-uris[打印 URI] --trivial-only[仅处理简单的升级] --remove[移除] --arch-only[仅处理架构相关的包] --allow-unauthenticated[允许未认证的包] --allow-insecure-repositories[允许不安全的仓库] --install-recommends[安装推荐的包] --install-suggests[安装建议的包] --no-install-recommends[不安装推荐的包] --no-install-suggests[不安装建议的包] --fix-policy[修复策略] --show-progress[显示进度] --fix-broken[修复损坏的包] --purge[彻底移除] --verbose-versions[显示详细版本信息] --auto-remove[自动移除不需要的包] -s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行] --force-yes[强制回答是] --reinstall[重新安装] --solver[指定解算器]'
+  'update' '--list-cleanup[清理列表] --print-uris[打印 URI] --allow-insecure-repositories[允许不安全的仓库]'
+  'list' '--installed[显示已安装的包] --upgradable[显示可升级的包] --manual-installed[显示手动安装的包] -v[详细输出] --verbose[详细输出] -a[显示所有版本] --all-versions[显示所有版本] -t[指定目标发行版] --target-release[指定目标发行版]'
+  'show' '-a[显示所有版本] --all-versions[显示所有版本]'
+  'depends' '-i[重要依赖] --important[重要依赖] --installed[已安装的依赖] --pre-depends[预依赖] --depends[依赖] --recommends[推荐依赖] --suggests[建议依赖] --replaces[替换] --breaks[破坏] --conflicts[冲突] --enhances[增强] --recurse[递归] --implicit[隐式依赖]'
+  'rdepends' '-i[重要依赖] --important[重要依赖] --installed[已安装的依赖] --pre-depends[预依赖] --depends[依赖] --recommends[推荐依赖] --suggests[建议依赖] --replaces[替换] --breaks[破坏] --conflicts[冲突] --enhances[增强] --recurse[递归] --implicit[隐式依赖]'
+  'search' '-n[仅按名称搜索] --names-only[仅按名称搜索] -f[完整搜索] --full[完整搜索]'
+  'showsrc' '--only-source[仅源码]'
+  'source' '-d[仅下载不安装] --download-only[仅下载不安装] -y[自动回答是] --assume-yes[自动回答是] --assume-no[自动回答否] -u[显示已升级的包] --show-upgraded[显示已升级的包] -m[忽略缺失的包] --ignore-missing[忽略缺失的包] -t[指定目标发行版] --target-release[指定目标发行版] --download[下载] --fix-missing[修复缺失的包] --ignore-hold[忽略被锁定的包] --upgrade[升级] --only-upgrade[仅升级] --allow-change-held-packages[允许更改被锁定的包] --allow-remove-essential[允许移除 essential 包] --allow-downgrades[允许降级] --print-uris[打印 URI] --trivial-only[仅处理简单的升级] --remove[移除] --arch-only[仅处理架构相关的包] --allow-unauthenticated[允许未认证的包] --allow-insecure-repositories[允许不安全的仓库] --install-recommends[安装推荐的包] --install-suggests[安装建议的包] --no-install-recommends[不安装推荐的包] --no-install-suggests[不安装建议的包] --fix-policy[修复策略] -s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行] -b[编译] --compile[编译] --build[编译] -P[构建配置文件] --build-profiles[构建配置文件] --diff-only[仅差异] --debian-only[仅 Debian] --tar-only[仅 tar] --dsc-only[仅 dsc]'
+  'build-dep' '-d[仅下载不安装] --download-only[仅下载不安装] -y[自动回答是] --assume-yes[自动回答是] --assume-no[自动回答否] -u[显示已升级的包] --show-upgraded[显示已升级的包] -m[忽略缺失的包] --ignore-missing[忽略缺失的包] -t[指定目标发行版] --target-release[指定目标发行版] --download[下载] --fix-missing[修复缺失的包] --ignore-hold[忽略被锁定的包] --upgrade[升级] --only-upgrade[仅升级] --allow-change-held-packages[允许更改被锁定的包] --allow-remove-essential[允许移除 essential 包] --allow-downgrades[允许降级] --print-uris[打印 URI] --trivial-only[仅处理简单的升级] --remove[移除] --arch-only[仅处理架构相关的包] --allow-unauthenticated[允许未认证的包] --allow-insecure-repositories[允许不安全的仓库] --install-recommends[安装推荐的包] --install-suggests[安装建议的包] --no-install-recommends[不安装推荐的包] --no-install-suggests[不安装建议的包] --fix-policy[修复策略] -a[主机架构] --host-architecture[主机架构] -s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行] -P[构建配置文件] --build-profiles[构建配置文件] --purge[彻底移除] --solver[指定解算器]'
+  'clean' '-s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行]'
+  'autoclean' '-s[模拟运行] --simulate[模拟运行] --dry-run[模拟运行]'
+)
+
+# 定义目录路径
+local primary_dir="/var/lib/apm/apm/files/ace-env/var/lib/apm/"
+local fallback_dir="/var/lib/apm/"
+
+# 查找不包含特定子目录的目录
+function find_directories_without_ace_env() {
+  local base_dir="$1"
+  local result=()
+  
+  # 检查基础目录是否存在
+  if [[ ! -d "$base_dir" ]]; then
+    return 1
+  fi
+  
+  # 查找所有直接子目录，排除包含ace-env子目录的目录
+  for dir in "$base_dir"/*; do
+    if [[ -d "$dir" ]] && [[ ! -d "$dir/files/ace-env" ]]; then
+      result+=("$(basename "$dir")")
+    fi
+  done
+  
+  # 输出结果
+  if [[ ${#result[@]} -gt 0 ]]; then
+    print -l "${result[@]}"
+    return 0
+  fi
+  return 1
+}
+
+function apm_run_compgen() {
+  local result
+  result=$(find_directories_without_ace_env "$primary_dir")
+
+  if [[ -n "$result" ]]; then
+    echo "$result"
+  else
+    result=$(find_directories_without_ace_env "$fallback_dir")
+    if [[ -n "$result" ]]; then
+      echo "$result"
+    else
+      echo ""
+    fi
+  fi
+}
+
+# 主完成函数
+_arguments -C \
+  "$options[@]" \
+  '*:: :->command'
+
+case $state in
+  command)
+    if (( CURRENT == 1 )); then
+      _describe 'command' commands
+    else
+      local cmd="${words[1]}"
+      local arg_pos=0
+      local found_cmd=0
+      
+      for (( i=1; i < CURRENT; i++ )); do
+        if [[ $found_cmd -eq 0 ]]; then
+          if [[ "${words[i]}" == "$cmd" ]]; then
+            found_cmd=1
+          fi
+        else
+          # 跳过选项参数（以-开头）
+          if [[ "${words[i]}" != -* ]]; then
+            ((arg_pos++))
+          fi
+        fi
+      done
+      
+      # 处理命令特定的选项
+      if [[ -n "${command_options[$cmd]}" ]]; then
+        _arguments "${(s: :)command_options[$cmd]}"
+      fi
+      
+      # 处理命令特定的参数
+      case $cmd in
+        remove|purge|autoremove|autopurge)
+          if [[ $arg_pos -eq 1 ]]; then
+            _files -W "$primary_dir" -/n
+          fi
+          ;;
+        show|list|download|changelog|depends|rdepends|policy)
+          if [[ $arg_pos -eq 1 ]]; then
+            local packages
+            packages=($(amber-pm-debug apt-cache --no-generate pkgnames "$PREFIX" -o Dir::Cache="/var/lib/aptss/" 2> /dev/null))
+            _describe 'package' packages
+          fi
+          ;;
+        install)
+          if [[ $arg_pos -eq 1 ]]; then
+            local packages
+            packages=($(amber-pm-debug apt-cache --no-generate pkgnames "$PREFIX" -o Dir::Cache="/var/lib/aptss/" 2> /dev/null))
+            _describe 'package' packages
+            _files -g "*.deb"
+          fi
+          ;;
+        source|build-dep|showsrc)
+          if [[ $arg_pos -eq 1 ]]; then
+            local packages
+            packages=($(amber-pm-debug apt-cache --no-generate pkgnames "$PREFIX" -o Dir::Cache="/var/lib/aptss/" 2> /dev/null))
+            _describe 'package' packages
+          fi
+          ;;
+        run|sandbox-run|bwrap-run|launch)
+          if [[ $arg_pos -eq 1 ]]; then
+            local packages
+            packages=($(apm_run_compgen))
+            _describe 'package' packages
+          elif [[ $arg_pos -ge 2 ]]; then
+            _files
+          fi
+          ;;
+        ssaudit|ssinstall)
+          _files
+          ;;
+      esac
+    fi
+    ;;
+esac