Go程序需通过shell调用获取补全候选值，主流做法是用cobra生成bash/zsh补全脚本并写入配置；zsh脚本须命名为_cmd、放入fpath且末尾加compdef _cmd cmd；动态补全需注册回调函数，避免耗时操作；PowerShell需单独实现__complete子命令输出JSON；跨平台不可复用脚本。
bash/zsh 补全脚本怎么生成
Go 程序本身不内置补全逻辑，得靠 shell 解析命令结构并调用你的程序获取候选值。主流做法是让 CLI 工具（比如用 cobra）在运行时输出补全脚本，再由用户写入 shell 配置中。
如果你用 cobra，直接调用 rootCmd.GenBashCompletionFile 或 GenZshCompletionFile 即可生成对应脚本。注意路径权限：生成的文件需有可读权限，且不能放在临时目录里——shell 启动时会直接 source 它。
-
cobrav1.7+ 默认启用 zsh 补全，但旧版本需手动注册cmd.RegisterFlagCompletionFunc才能支持子命令/参数级补全 - zsh 脚本必须以
_yourcommand命名（开头下划线），否则compinit不识别 - bash 补全依赖
bash-completion包，macOS 上用brew install bash-completion，Linux 通常自带，但得确认/etc/bash_completion被 sourced
如何让自定义参数支持动态补全
静态命令补全（比如子命令名）cobra 自动处理；但像文件路径、API 资源名、配置项这类动态值，得自己实现补全回调函数。
关键点在于：补全函数返回的是字符串切片，shell 拿到后直接拼接进当前行，不经过你的主逻辑。所以别在里面做耗时操作（比如 HTTP 请求），否则 tab 会卡住。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 用
cmd.RegisterFlagCompletionFunc("flagname", func(...)绑定标志位补全 - 对位置参数（如
mytool deploy <env></env>），改用cmd.ValidArgsFunction = func(...) - 补全函数里拿到的
toComplete是用户已输入的部分，不是完整参数值，要按前缀匹配，别用==全等判断 - 返回结果里不要带空格或引号，shell 会自己处理转义
为什么补全在 zsh 下不生效
zsh 补全比 bash 更严格，常见失效原因是加载顺序或函数命名不对。它不会报错，只是静默跳过。
典型现象：输入 mytool <tab></tab> 没反应，或只补出文件名（说明 fallback 到默认补全了）。这时候先确认 zsh 是否已初始化补全系统：type compinit 应该返回函数定义，否则要手动执行 compinit。
- 生成的 zsh 脚本必须放在
fpath目录下（如~/zsh/completion），且文件名是_mytool（不是mytool.zsh） - 脚本末尾必须有
compdef _mytool mytool这行，把函数和命令名绑定 - 如果用了 oh-my-zsh，别把补全脚本放进
plugins/目录——它只加载特定命名的插件，普通脚本得走fpath方式 - 修改后要执行
rm ~/.zcompdump*; compinit清缓存，否则旧定义一直生效
跨平台补全兼容性要注意什么
Windows 的 PowerShell 补全机制和 Unix shell 完全不同，不能复用 bash/zsh 脚本。PowerShell 使用 Register-ArgumentCompleter 注册脚本块，且要求 Go 程序输出 JSON 格式的候选列表（而非纯文本）。
这意味着：同一套补全逻辑，在不同平台得走不同路径。别指望一个 gen-completion 命令打天下。
- PowerShell 补全脚本里，调用的是
mytool __complete <args></args>，这个子命令必须由你实现，输出格式为["val1","val2"]的 JSON 数组 - PowerShell 5.0+ 才支持原生补全，老版本只能靠第三方模块（如
PSReadLine），但体验差很多 - Windows Terminal 和 ConEmu 对补全支持不一致，建议优先测试默认的 Windows Terminal
- macOS 上 zsh 是默认 shell，但部分用户仍用 bash —— 如果只生成 zsh 脚本，bash 用户就完全没补全
echo 到临时文件里捞线索。 
