zsh-setup

用途

zsh-setup 用于在 macOS 上以现代方式配置 zsh（macOS 默认 shell）。它通过 Homebrew 安装独立插件（自动建议、语法高亮），配置 Starship 提示符，并建立保持快速和可调试的启动文件结构，无需框架。该技能负责 ~/.zshrc 的结构；其他技能追加受保护的片段，~/.zprofile 的 brew 行属于 homebrew-setup。

不适用场景

终端模拟器安装（Ghostty/iTerm2/Warp）→ mac-dev-apps
fzf/zoxide/eza 等 CLI 工具本身 → dev-cli-tools（它们的初始化行会进入 .zshrc，但工具选择在那里）
在仓库中对配置进行版本控制 → dotfiles-setup
编写 shell 脚本 → 不是配置任务

安全护栏

重构前备份，带时间戳，确保重复运行不会覆盖上一个良好备份：cp ~/.zshrc ~/.zshrc.bak.$(date +%Y%m%d%H%M%S)（.zprofile 同理）。
只保留一个提示符。如果 Powerlevel10k 或其他提示符处于活动状态，在启用 Starship 的同一次更改中禁用它——两个提示符初始化会冲突并破坏渲染。
幂等追加：grep -q '<marker>' ~/.zshrc || echo ... >> ~/.zshrc。

工作流程

1. 检测现有内容

grep -iE 'oh-my-zsh|powerlevel|starship' ~/.zshrc 2>/dev/null
[ -d ~/.oh-my-zsh ] && echo "OMZ present"

全新机器 → 按步骤 2–4 执行。
已有 Oh My Zsh → 保留它（其插件继续工作）；只需让 Starship 成为提示符：在 .zshrc 中设置 ZSH_THEME=""，并在 source $ZSH/oh-my-zsh.sh 之后添加 Starship 初始化行。不要同时安装 brew 插件副本——OMZ 的插件数组已经加载它们。
已有 Powerlevel10k → 它仍可用但仅维护（作者称“无新功能，大多数 bug 不会修复”）。建议切换：移除/清空 ZSH_THEME="powerlevel10k/powerlevel10k" 及其 ~/.p10k.zsh source 行，然后安装 Starship。如果用户坚持保留或安装 p10k，旧步骤在 references/zsh-structure.md 中——尊重选择，只保留一个提示符。

2. 插件（通过 Homebrew，无框架）

brew install zsh-autosuggestions zsh-syntax-highlighting

在 ~/.zshrc 中通过 $HOMEBREW_PREFIX 加载它们（由 brew shellenv 导出——不要每次启动都运行 $(brew --prefix)，那会消耗真实毫秒），语法高亮放在两者最后：

source "$HOMEBREW_PREFIX/share/zsh-autosuggestions/zsh-autosuggestions.zsh"
source "$HOMEBREW_PREFIX/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"

3. Starship 提示符 + Nerd Font

brew install starship
grep -q 'starship init' ~/.zshrc || echo 'eval "$(starship init zsh)"' >> ~/.zshrc  # near the end
brew install --cask font-jetbrains-mono-nerd-font   # or font-meslo-lg-nerd-font; no tap needed

提醒用户：在终端应用的配置中选择字体——仅安装不会应用。提示符中出现方框/问号 = 字体未选择，不是主题损坏。可选预设：starship preset nerd-font-symbols -o ~/.config/starship.toml。

4. 启动文件结构

~/.zprofile = 登录时环境（brew shellenv——由 homebrew-setup 拥有；PATH 添加；typeset -U path 去重）。
~/.zshrc = 仅交互式，按此顺序：

# 1. History
HISTSIZE=50000; SAVEHIST=50000
setopt SHARE_HISTORY HIST_IGNORE_ALL_DUPS HIST_IGNORE_SPACE INTERACTIVE_COMMENTS AUTO_CD
# 2. Completions
autoload -Uz compinit && compinit
# 3. Plugins (autosuggestions, then syntax-highlighting LAST of the plugins)
# 4. Tool inits (fzf, zoxide, mise, direnv...) - other skills append here or
#    at end-of-file; appended inits landing after the prompt init are fine
# 5. Prompt init near the end:  eval "$(starship init zsh)"
# 6. Aliases

唯一的硬性顺序规则是 zsh-syntax-highlighting 在插件中最后（它必须包装之前定义的 widget）；之后追加的工具初始化不会破坏它。完整注释模板和 macOS path_helper 怪癖（为什么在 .zshenv 中设置的 PATH 会被重新排序）：references/zsh-structure.md。

5. 慢启动诊断（被要求时）

先测量：在 .zshrc 第 1 行添加 zmodload zsh/zprof，最后一行添加 zprof，打开新 shell，读取表格，然后移除两者。常见问题：繁重的框架插件列表、急切的 nvm 初始化（参见 language-runtimes 的 mise 替代方案）、每个提示符运行 brew/网络命令、双重 compinit。从结构上修复；重新测量；报告前后对比。

6. 验证

新终端：Starship 提示符渲染图标，输入时显示灰色自动建议，有效命令绿色/无效红色，starship --version 打印。

输出规范

完成意味着：插件在新 shell 中无错误加载，恰好一个提示符（除非用户明确保留其他，否则为 Starship）正确渲染，任何被替换文件的备份存在，用户知道必须在其终端配置中选择字体。

注意事项

两个提示符初始化（Starship + 遗留的 p10k 主题）= 提示符乱码；检测步骤正是为了防止这种情况。
zsh-syntax-highlighting 不在最后 = 高亮会错过后续插件添加的 widget。
$HOMEBREW_PREFIX 仅在 homebrew-setup 的 shellenv 行运行后才设置——这是本技能的前提。
macOS 自 Catalina 起默认提供 zsh——chsh -s /bin/zsh 仅适用于 Catalina 之前的账户。
从 OMZ 过来且启动变慢？框架不是问题——其插件列表才是；在放弃它之前先精简 plugins=(...)。