flag包不支持自动补全，因其仅负责参数解析，不参与shell交互；补全需由shell（如bash/zsh）通过注册的补全函数实现，依赖手动或工具（如cobra）生成对应脚本。
为什么 flag 包本身不支持自动补全
Go 标准库的 flag 包只负责解析命令行参数，不介入 shell 层交互，所以它压根不处理 Tab 补全。补全行为由 shell（bash/zsh/fish）在用户按下 Tab 时触发，需要你提前注册补全脚本或函数。换句话说：flag 解析什么、怎么解析，和「按 Tab 能列出哪些选项」是两件事，不能指望它自动生成补全逻辑。
zsh/bash 下实现补全的关键：提供 shell 函数 + 注册
主流做法是让 CLI 程序自己输出补全定义（shell 函数），再由用户 source 到 shell 配置中。比如 spf13/cobra 的 cobra.GenZshCompletion 就是干这个的。但如果你没用 cobra，而是直接用 flag 或 kingpin，就得手动构造输出：
- 补全函数名必须是
_<your-binary-name></your-binary-name>（zsh）或_<your-binary-name>_completion</your-binary-name>（bash） - 函数内部要读取
COMP_WORDS/words、COMP_CWORD/cword等变量判断当前上下文 - 最终通过
COMPREPLY=(...)（bash）或reply=(...)（zsh）返回候选字符串数组 - zsh 还需在函数末尾加
compdef _your-binary-name your-binary-name
示例片段（zsh）：
_mytool() {
local words=("${(@)words}")
local cword=$CURRENT
local candidates=()
if [[ $cword -eq 2 ]]; then
candidates=("serve" "build" "list")
elif [[ ${words[2]} == "build" && $cword -eq 3 ]]; then
candidates=("--output" "--debug" "--env")
fi
reply=($candidates)
}
compdef _mytool mytool
用 spf13/cobra 是最省事的选择，但要注意生成时机
Cobra 内置了完整的补全支持，调用 cmd.GenZshCompletion 或 cmd.GenBashCompletion 即可输出对应脚本。但注意两点：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 生成的脚本依赖于
cmd的结构（比如Args: cobra.ExactArgs(1)会影响子命令补全层级），所以必须确保命令树在生成前已完全构建好 - zsh 补全要求函数名与二进制名严格一致；如果用户用 alias 启动（如
alias mt=mytool），补全会失效——得额外注册compdef _mytool mt - fish 补全需单独调用
cmd.GenFishCompletion，且 fish 不认 bash/zsh 的补全脚本
常见错误：在 init() 里就调用 GenZshCompletion，此时子命令可能还没被 rootCmd.AddCommand(...) 注册，导致补全列表为空。
补全内容不是越全越好：别把敏感参数或动态值暴露出去
自动补全本质是把程序内部信息“广播”给 shell，容易引发问题：
- 如果补全逻辑里调用了
os.ReadDir("/etc/secrets")，每次 Tab 都会执行，存在权限和性能风险 - 补全建议不应包含密码、token、临时文件路径等敏感内容；
--password这类 flag 最好禁用补全（设置DisableFlagParsing: true或在补全函数中跳过） - 动态数据（如远程 API 返回的项目名列表）不适合做补全源——延迟高、不可靠、难缓存；更适合做成子命令（如
mytool projects list）
真正该补全的，是稳定、有限、本地可判定的集合：子命令名、枚举型 flag 值（--format=json,yaml,toml）、配置文件路径（--config ./config.yaml 可补全当前目录下的 .yaml 文件）。
