filepath.Walk不适合路径补全，因其深度遍历全部子目录，而补全只需读取当前层目录内容；应改用os.ReadDir或filepath.Glob配合tilde展开与排序去重，并通过CLI框架集成shell补全协议。
为什么 filepath.Walk 不适合做路径补全
因为 filepath.Walk 是深度遍历，会递归进入所有子目录，哪怕用户只输入了 ./a 想补全 ./abc/ 或 ./app.go，它也会扫描整个 ./a/ 下所有层级——既慢又没必要。路径补全只需要查一层目录内容，用 os.ReadDir（Go 1.16+）或 ioutil.ReadDir（旧版）更直接、可控。
常见错误现象：补全延迟明显、终端卡顿、甚至因权限问题 panic（比如遇到 /proc 下不可读目录）。这时候不是逻辑错了，是选错了 API。
- 只补全当前层级：用
os.ReadDir(dir)获取dir下所有条目，再按前缀过滤 - 注意区分文件和目录：补全时通常要保留结尾斜杠（如
docs/），需检查entry.IsDir() - 忽略隐藏文件？默认不忽略，但 CLI 用户常期望跳过
.git、.env等，得手动过滤
如何让 Tab 补全支持通配符和 tilde 展开
用户输入 ~/do<tab></tab> 或 src/*.go<tab></tab> 时，补全逻辑必须先做路径预处理，否则直接传给 os.ReadDir 会失败。
~/ 需展开为 $HOME，而 * 不能靠文件系统匹配——得用 filepath.Glob，它返回符合 glob 模式的绝对路径列表，再逐个提取 basename 用于显示。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- tilde 展开：用
os.UserHomeDir()获取主目录，再用strings.Replace替换开头的~ - glob 处理：调用
filepath.Glob(pattern)，注意它返回的是完整路径，补全建议应取filepath.Base(path) - 混合情况如
~/src/*.md：先展开 tilde，再 glob，顺序不能反，否则~/src被当字面量处理
怎么避免补全结果重复或顺序混乱
补全建议没排序、大小写混杂、目录和文件穿插，会让用户难以快速定位目标项。Go 标准库不保证 os.ReadDir 返回顺序，filepath.Glob 也不排序，必须显式处理。
典型表现：输入 go 后补全出现 go.mod、Gopkg.lock、GOOS 杂乱排列，而非按字母升序、目录优先排列。
- 统一转小写排序？不行——文件系统区分大小写，Linux 下
Readme.md和README.md是不同文件 - 正确做法：收集所有候选名后，用
sort.Slice自定义排序：目录排前面（加斜杠标识）、其余按字符串自然序 - 去重关键点：同一路径可能因软链接、大小写不同被多次命中，建议用
filepath.EvalSymlinks归一化后再比对
CLI 补全集成到 shell 的实际约束
Go 程序本身不提供 shell 补全 hook，真正生效靠的是外部 shell 脚本（如 bash 的 complete -F _mycmd mycmd）。你的 Go 程序只需暴露一个子命令（如 mycmd __complete foo）输出补全候选，由 shell 脚本调用并解析。
容易被忽略的细节：shell 传入的参数含空格、引号、未转义特殊字符，Go 程序必须原样接收并处理，不能依赖 os.Args 简单切分。
- 推荐用
github.com/spf13/cobra：它的Command.RegisterFlagCompletionFunc和内置__complete子命令已处理好 shell 交互协议 - 手动实现时，务必从
os.Stdin读取当前行（bash 提供COMP_LINE）、当前词位置（COMP_POINT），而不是只看os.Args - 输出格式必须是每行一个候选，末尾不能有空行，否则 zsh 会截断
最麻烦的其实是跨 shell 兼容：bash 用 COMP_WORDBREAKS 控制分词，zsh 用 compdef，fish 用 complete -f。别自己硬写，用成熟 CLI 框架生成对应脚本更稳。
