第 7 章：`lib/` 标准库 —— 默认体验从哪里来¶

lib/ 是 Oh My Zsh 每次启动都会遍历的运行时层。它不是一个有统一 API 的库，而是一组会产生全局副作用的 zsh 文件。理解它们的分工，比记住某个 alias 更重要。

7.1 模块地图¶

模块	主要职责	代表性机制
`async_prompt.zsh`	异步 prompt handler	后台任务、结果表、prompt hook
`bzr.zsh` / `nvm.zsh`	prompt 信息 helper	`bzr_prompt_info`、`nvm_prompt_info`
`cli.zsh`	`omz` 命令入口	update、reload、diagnostics 等子命令
`clipboard.zsh`	跨平台剪贴板探测	macOS、Linux、WSL、Termux 分支
`compfix.zsh`	补全目录安全提示	权限检查、修复建议
`completion.zsh`	补全默认策略	matcher、cache、menu、颜色
`correction.zsh`	命令纠错	`ENABLE_CORRECTION`、拼写建议
`diagnostics.zsh`	诊断信息收集	`omz_diagnostic_dump`
`directories.zsh`	目录导航	`auto_cd`、`pushd`、`d`、`...`
`functions.zsh`	通用 helper	`take`、`env_default`、卸载、URL 编解码
`git.zsh`	Git prompt/helper	dirty、branch、ahead/behind、async
`grep.zsh`	grep 默认行为	平台兼容 alias/选项
`history.zsh`	历史策略	`HIST_STAMPS`、history option
`key-bindings.zsh`	ZLE 快捷键	emacs/vi map、方向键和编辑命令
`misc.zsh`	杂项默认设置	magic functions、pager、`_` alias
`prompt_info_functions.zsh`	空实现与 Ruby prompt	避免主题调用时报 command not found
`spectrum.zsh`	256 色 helper	`FG`/`BG`/`FX` 映射、色板展示
`termsupport.zsh`	终端集成	title、OSC 7 当前目录、precmd/preexec
`theme-and-appearance.zsh`	外观默认值	colors、prompt 常量、ls 颜色
`vcs_info.zsh`	zsh vcs_info 修补	prompt 字段 `%` 转义

7.2 默认 option 是“隐形 API”¶

lib/directories.zsh 设置：

setopt auto_cd
setopt auto_pushd
setopt pushd_ignore_dups
setopt pushdminus

因此用户可以直接输入目录名执行 cd，并且目录切换形成 stack。...、.... 等 global alias 进一步把路径跳转变成命令行快捷方式。

lib/misc.zsh 则启用 multios、long_list_jobs、interactivecomments。这些不是 alias，而是改变 zsh 解析/执行语义的 option，影响范围更大。

7.3 `functions.zsh` 的通用 helper¶

几个很值得学习的函数：

env_default(name, value)：只有环境变量未设置时才提供默认值，避免覆盖用户选择；
default(name, value)：为 shell 变量提供默认值；
take(path)：创建目录并进入；
takegit(url)：下载仓库并进入；
alias_value(name)：读取 alias 展开内容；
omz_urlencode/omz_urldecode：供终端 title 和 OSC 7 使用。

这些 helper 体现了 shell 代码的防御性写法：尽量使用 command 绕过 alias，使用 emulate -L zsh 限定 option 污染，并在跨平台边界处理 locale。

7.4 终端集成：两个 hook¶

lib/termsupport.zsh 注册：

precmd：显示 prompt 前设置窗口/Tab 标题，并通过 OSC 7 更新终端当前工作目录；
preexec：命令执行前把命令名和命令行写入窗口标题。

它根据 $TERM、$TERM_PROGRAM、Emacs/vterm、SSH 等条件选择行为。设置：

DISABLE_AUTO_TITLE=true

可以关闭标题更新。对于 prompt 类功能，hook 的好处是不会把每次变化都硬编码到 .zshrc；代价是排查时需要查看 precmd_functions 和 preexec_functions。

7.5 prompt helper 的“空实现”技巧¶

lib/prompt_info_functions.zsh 为 chruby_prompt_info、rbenv_prompt_info、pyenv_prompt_info、conda_prompt_info 等定义返回失败的 dummy function。

这样主题可以安全地写：

$(pyenv_prompt_info)

而不用给每个函数写 (( $+commands[pyenv] )) 条件。真正插件加载后可以覆盖 dummy implementation。这是一个很实用的 shell 多态模式：先提供不做事的默认接口，再由插件注入真实实现。

7.6 `vcs_info.zsh` 的安全补丁¶

zsh 的 vcs_info 会把 branch、base、revision 等字段传给 hook 和 prompt。Oh My Zsh 在加载时用 regexp-replace 改写 VCS_INFO_formats，对可能包含 % 的字段先进行转义，并用唯一 ID 避免重复 patch。

这类代码看起来“离业务很远”，但它处在所有主题共享的输出边界上：一次 prompt 字符串拼接错误会影响所有 VCS 主题，所以选择在 lib 层集中修复。

7.7 `lib/` 的维护规则¶

因为所有用户都会加载 lib，新代码应遵守：

不要无条件启动网络请求；
外部命令不可用时静默降级；
尽量把昂贵逻辑推迟到真正需要的 hook 或函数调用；
变量命名保持 ZSH_/OMZ_ 前缀，避免覆盖用户变量；
对 prompt 文本做 % 转义；
用 zstyle 提供细粒度开关；
改动后运行 zsh -n 和启动性能测试。

下一章把工具脚本单独拿出来，因为安装和更新不是 shell 初始化的普通模块，而是会修改文件系统和 Git 工作树的运维流程。

第 7 章：lib/ 标准库 —— 默认体验从哪里来¶