shell-integration

Shell 集成

概述

Shell 集成涵盖用于构建扩展或交互 Unix Shell 的工具的 API 和模式。这包括 Zsh、Bash 和 Fish 的补全系统、提示符钩子、按键绑定、终端控制和插件分发。

适用场景： 构建 CLI 工具补全、Shell 插件、提示符自定义、终端 UI、点文件管理器、安装脚本或原生二进制文件包装器。

不适用场景： 与扩展 Shell 无关的通用脚本（独立脚本请参考 POSIX 脚本参考）、GUI 应用或 Web 服务开发。

快速参考

模式	Shell	要点
补全函数	Zsh	使用 compdef、compadd 和 zstyle 配置匹配器
补全函数	Bash	complete、compgen、COMP_WORDS、COMP_CWORD、COMPREPLY
补全函数	Fish	complete -c cmd -a args、条件标志、子命令模式
ZLE 小组件	Zsh	zle -N widget func，使用 bindkey 映射按键
提示符钩子	Zsh	通过 add-zsh-hook 使用 precmd、preexec、chpwd
提示符钩子	Bash	PROMPT_COMMAND（Bash 5.1+ 中为字符串或数组）
事件处理程序	Fish	--on-event、--on-variable、--on-signal
缩写	Fish	abbr -a name expansion，使用 --function 实现动态缩写
参数展开	Zsh	${(s.:.)var}、${var:=default}、标志和修饰符
终端控制	所有	ANSI/CSI 转义序列、tput、stty
信号处理	所有	trap 内置命令、清理模式、EXIT/INT/TERM
进程管理	所有	作业控制（&、wait、bg、fg）、子 Shell、协程
插件安装	所有	加载策略、版本检测、ZDOTDIR 加载顺序

常见错误

错误	正确做法
使用 echo -e 以便跨平台输出转义序列	使用 printf 或 tput，以确保在不同 Shell 和操作系统间的可移植性
在 Bash 中使用 = 修改 PROMPT_COMMAND	使用 += 追加，避免覆盖其他工具设置的内容
在延迟加载的函数中定义 Fish 事件处理程序	将事件处理程序放在 config.fish 中，或显式加载它们
将终端功能硬编码	通过 tput 查询，它会遵循 TERM 和 terminfo
Zsh 函数中缺少 emulate -L zsh	始终设置本地选项，避免污染调用方环境
使用拆分 $COMP_LINE 而非 COMP_WORDS	使用 COMP_WORDS[$COMP_CWORD] 可靠地提取单词
包装脚本中的 $@ 未加引号	始终使用 "$@" 保留参数边界
假设 /bin/sh 是 Bash	以 POSIX sh 为目标编写可移植脚本，并使用 dash 测试
在 POSIX 脚本中使用 function 关键字	使用 name() { ... } 语法以兼容 POSIX
忽略用于清理的 EXIT 陷阱	始终设置 trap cleanup EXIT 来清理临时文件和状态

委派

• 完成情况测试：使用 Explore Agent 交互式验证完成情况
• 脚本审查：使用 Task Agent 审核跨 Shell 兼容性
• 代码审查：委派给 code-reviewer Agent

如果有 rust 技能，请委派原生二进制编译模式相关工作。Shell 包装器通常会调用 Rust 编译的二进制文件，以执行性能关键型操作。 如果有 cli-power-tools 技能，请委派现代 CLI 实用工具模式相关工作。许多 Shell 插件会包装 fd、ripgrep 和 fzf 等工具。

参考资料

• Zsh 集成：ZLE、补全、钩子、参数展开
• Bash 集成：readline、补全、PROMPT_COMMAND、shopt
• Fish 集成：补全、事件、缩写、函数
• 终端控制：ANSI/CSI 序列、tput、stty、功能
• POSIX 脚本：可移植模式、信号处理、进程管理
• 插件分发：安装脚本、点文件管理、版本检测