⚡

Shell自动补全生成器Skill shell-completion-generator

Shell自动补全生成器是一个用于为命令行工具（CLI）创建智能自动补全脚本的工具。它支持bash、zsh和fish三种主流shell，能够根据命令定义自动生成包含参数建议、文件补全和动态值的补全脚本。该工具特别适用于开发人员为自定义CLI工具添加用户体验友好的自动补全功能，提高命令行操作效率。关键词：shell自动补全、CLI工具、bash补全、zsh补全、fish补全、命令行工具、开发工具、自动补全脚本、智能补全、命令行界面。

DevOps 0 次安装 0 次浏览 更新于 2/23/2026

name: shell-completion-generator description: 从CLI命令定义生成bash、zsh和fish的shell自动补全脚本。创建智能补全，包括参数建议、文件补全和动态值。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Shell自动补全生成器

从CLI命令定义生成bash、zsh和fish shell的全面自动补全脚本。

能力

  • 生成bash自动补全脚本
  • 生成带描述的zsh自动补全
  • 生成fish自动补全脚本
  • 支持子命令和嵌套命令
  • 参数的动态补全
  • 文件/目录路径补全
  • 自定义补全函数

使用场景

当您需要时调用此技能：

  • 为CLI应用程序添加shell自动补全
  • 从命令模式生成自动补全
  • 创建自定义补全逻辑
  • 支持多种shell

输入参数

参数 类型 是否必需 描述
cliName 字符串 是 CLI可执行文件的名称
commands 数组 是 带选项的命令定义
shells 数组 否 目标shell（默认：全部）
outputDir 字符串 否 脚本输出目录
dynamic 对象 否 动态补全配置

命令定义结构

{
  "commands": [
    {
      "name": "deploy",
      "description": "将应用程序部署到环境",
      "options": [
        {
          "flags": ["-e", "--env"],
          "description": "目标环境",
          "type": "choice",
          "choices": ["dev", "staging", "prod"]
        },
        {
          "flags": ["-c", "--config"],
          "description": "配置文件路径",
          "type": "file",
          "extensions": [".json", ".yaml", ".yml"]
        }
      ],
      "arguments": [
        {
          "name": "service",
          "description": "要部署的服务",
          "type": "dynamic",
          "source": "services-list"
        }
      ],
      "subcommands": [
        {
          "name": "status",
          "description": "检查部署状态"
        }
      ]
    }
  ]
}

输出结构

completions/
├── bash/
│   └── <cliName>.bash       # Bash自动补全脚本
├── zsh/
│   └── _<cliName>           # Zsh自动补全函数
├── fish/
│   └── <cliName>.fish       # Fish自动补全脚本
└── install.sh               # 安装帮助脚本

生成的代码模式

Bash自动补全脚本

#!/bin/bash
# mycli的自动补全脚本

_mycli_completions() {
    local cur prev words cword
    _init_completion || return

    local commands="deploy rollback status config"

    case "${prev}" in
        mycli)
            COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
            return
            ;;
        deploy)
            COMPREPLY=($(compgen -W "--env --config --dry-run" -- "${cur}"))
            return
            ;;
        --env|-e)
            COMPREPLY=($(compgen -W "dev staging prod" -- "${cur}"))
            return
            ;;
        --config|-c)
            _filedir '@(json|yaml|yml)'
            return
            ;;
    esac

    # 处理子命令
    if [[ ${words[1]} == "deploy" ]]; then
        case "${prev}" in
            status)
                # 服务的动态补全
                local services=$(_mycli_get_services)
                COMPREPLY=($(compgen -W "${services}" -- "${cur}"))
                return
                ;;
        esac
    fi

    COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
}

# 动态补全辅助函数
_mycli_get_services() {
    mycli services list --quiet 2>/dev/null
}

complete -F _mycli_completions mycli

Zsh自动补全脚本

#compdef mycli

_mycli() {
    local -a commands
    commands=(
        'deploy:将应用程序部署到环境'
        'rollback:回滚到先前版本'
        'status:检查部署状态'
        'config:管理配置'
    )

    local -a deploy_options
    deploy_options=(
        '(-e --env)'{-e,--env}'[目标环境]:environment:(dev staging prod)'
        '(-c --config)'{-c,--config}'[配置文件路径]:config file:_files -g "*.{json,yaml,yml}"'
        '--dry-run[预览更改而不应用]'
    )

    _arguments -C \
        '1: :->command' \
        '*:: :->args'

    case $state in
        command)
            _describe -t commands 'mycli命令' commands
            ;;
        args)
            case $words[1] in
                deploy)
                    _arguments $deploy_options \
                        '1:service:_mycli_services'
                    ;;
                rollback)
                    _arguments \
                        '(-v --version)'{-v,--version}'[要回滚的版本]:version:_mycli_versions'
                    ;;
            esac
            ;;
    esac
}

# 服务的动态补全
_mycli_services() {
    local -a services
    services=(${(f)"$(mycli services list --quiet 2>/dev/null)"})
    _describe -t services '服务' services
}

_mycli "$@"

Fish自动补全脚本

# mycli的自动补全

# 默认禁用文件补全
complete -c mycli -f

# 主命令
complete -c mycli -n __fish_use_subcommand -a deploy -d '将应用程序部署到环境'
complete -c mycli -n __fish_use_subcommand -a rollback -d '回滚到先前版本'
complete -c mycli -n __fish_use_subcommand -a status -d '检查部署状态'
complete -c mycli -n __fish_use_subcommand -a config -d '管理配置'

# 部署选项
complete -c mycli -n '__fish_seen_subcommand_from deploy' -s e -l env -d '目标环境' -xa 'dev staging prod'
complete -c mycli -n '__fish_seen_subcommand_from deploy' -s c -l config -d '配置文件路径' -r -F
complete -c mycli -n '__fish_seen_subcommand_from deploy' -l dry-run -d '预览更改'

# 部署子命令
complete -c mycli -n '__fish_seen_subcommand_from deploy' -a status -d '检查部署状态'

# 动态服务补全
function __mycli_services
    mycli services list --quiet 2>/dev/null
end

complete -c mycli -n '__fish_seen_subcommand_from deploy; and not __fish_seen_subcommand_from status' -a '(__mycli_services)' -d '服务'

补全类型

类型 描述 示例
choice 固定值列表 环境、格式
file 文件路径补全 配置文件
directory 目录路径补全 输出路径
dynamic 运行时生成的值 服务、分支
command 子命令补全 嵌套命令
none 无补全 自由格式文本

动态补全源

{
  "dynamic": {
    "services-list": {
      "command": "mycli services list --quiet",
      "cache": 60
    },
    "git-branches": {
      "command": "git branch --format='%(refname:short)'",
      "cache": 10
    },
    "docker-images": {
      "command": "docker images --format '{{.Repository}}:{{.Tag}}'",
      "cache": 30
    }
  }
}

安装脚本

#!/bin/bash
# install.sh - 为mycli安装shell自动补全

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

install_bash() {
    local dest="${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/bash/mycli.bash" "$dest/mycli"
    echo "已将bash自动补全安装到 $dest/mycli"
}

install_zsh() {
    local dest="${ZDOTDIR:-$HOME}/.zfunc"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/zsh/_mycli" "$dest/_mycli"
    echo "如果未在.zshrc中添加，请添加 'fpath=(~/.zfunc \$fpath)'"
    echo "已将zsh自动补全安装到 $dest/_mycli"
}

install_fish() {
    local dest="${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions"
    mkdir -p "$dest"
    cp "$SCRIPT_DIR/fish/mycli.fish" "$dest/mycli.fish"
    echo "已将fish自动补全安装到 $dest/mycli.fish"
}

case "$1" in
    bash) install_bash ;;
    zsh) install_zsh ;;
    fish) install_fish ;;
    all|"")
        install_bash
        install_zsh
        install_fish
        ;;
    *)
        echo "用法: $0 [bash|zsh|fish|all]"
        exit 1
        ;;
esac

工作流程

  1. 解析命令定义 - 提取命令、选项、参数
  2. 识别补全类型 - 将类型映射到shell补全方法
  3. 生成bash脚本 - 创建基于complete函数的脚本
  4. 生成zsh脚本 - 创建带描述的_compdef函数
  5. 生成fish脚本 - 创建complete命令
  6. 创建安装脚本 - 用户安装的帮助程序

应用的最佳实践

  • zsh补全中的描述
  • 文件扩展名过滤
  • 动态补全的缓存
  • 子命令处理
  • 选项分组（-e|–env）
  • 上下文感知补全

参考资料

目标流程

  • shell自动补全脚本
  • cli文档生成
  • cli应用程序引导