shell-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shell Integration

Shell集成

Overview

概述

Shell integration covers the APIs and patterns for building tools that extend or interact with Unix shells. This includes completion systems, prompt hooks, key bindings, terminal control, and plugin distribution across Zsh, Bash, and Fish.

When to use: Building CLI tool completions, shell plugins, prompt customizations, terminal UI, dotfile managers, installation scripts, or native binary wrappers.

When NOT to use: General-purpose scripting unrelated to shell extension (use POSIX scripting reference for standalone scripts), GUI applications, or web server development.

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

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

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

Quick Reference

快速参考

Pattern	Shell	Key Points
Completion function	Zsh	`compdef` , `compadd` , `zstyle` for matcher configuration
Completion function	Bash	`complete` , `compgen` , `COMP_WORDS` , `COMP_CWORD` , `COMPREPLY`
Completion function	Fish	`complete -c cmd -a args` , condition flags, subcommand patterns
ZLE widget	Zsh	`zle -N widget func` , `bindkey` to map keys
Prompt hook	Zsh	`precmd` , `preexec` , `chpwd` via `add-zsh-hook`
Prompt hook	Bash	`PROMPT_COMMAND` (string or array in Bash 5.1+)
Event handler	Fish	`--on-event` , `--on-variable` , `--on-signal`
Abbreviation	Fish	`abbr -a name expansion` , `--function` for dynamic
Parameter expansion	Zsh	`${(s.:.)var}` , `${var:=default}` , flags and modifiers
Terminal control	All	ANSI/CSI escape sequences, `tput` , `stty`
Signal handling	All	`trap` builtin, cleanup patterns, `EXIT` / `INT` / `TERM`
Process management	All	Job control ( `&` , `wait` , `bg` , `fg` ), subshells, coprocesses
Plugin installation	All	Sourcing strategies, version detection, `ZDOTDIR` loading order

模式	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}` 、标志与修饰符
终端控制	所有Shell	ANSI/CSI转义序列、 `tput` 、 `stty`
信号处理	所有Shell	`trap` 内置命令、清理模式、 `EXIT` / `INT` / `TERM`
进程管理	所有Shell	作业控制（ `&` 、 `wait` 、 `bg` 、 `fg` ）、子Shell、协进程
插件安装	所有Shell	源码加载策略、版本检测、 `ZDOTDIR` 加载顺序

Common Mistakes

常见错误

Mistake	Correct Pattern
Using `echo -e` for escape sequences portably	Use `printf` or `tput` for portability across shells and OSes
Modifying `PROMPT_COMMAND` with `=` in Bash	Append with `+=` to avoid overwriting other tools
Defining Fish event handlers in lazy-loaded functions	Place event handlers in config.fish or source them explicitly
Hardcoding terminal capabilities	Query via `tput` which respects `TERM` and terminfo
Missing `emulate -L zsh` in Zsh functions	Always set local options to avoid polluting caller environment
Using `$COMP_LINE` splitting instead of `COMP_WORDS`	Use `COMP_WORDS[$COMP_CWORD]` for reliable word extraction
Not quoting `$@` in wrapper scripts	Always use `"$@"` to preserve argument boundaries
Assuming `/bin/sh` is Bash	Target POSIX sh for portable scripts, test with `dash`
Using `function` keyword in POSIX scripts	Use `name() { ... }` syntax for POSIX compatibility
Ignoring `EXIT` trap for cleanup	Always set `trap cleanup EXIT` for temp files and state

错误	正确做法
可移植场景下使用 `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` 以处理临时文件和状态

Delegation

任务分工

Completion testing: Use
```
Explore
```
agent to verify completions interactively
Script review: Use
```
Task
```
agent for cross-shell compatibility audits
Code review: Delegate to
```
code-reviewer
```
agent

If the
rust
skill is available, delegate native binary compilation patterns to it. Shell wrappers often invoke Rust-compiled binaries for performance-critical operations. If the
cli-power-tools
skill is available, delegate modern CLI utility patterns to it. Many shell plugins wrap tools like
fd
,
ripgrep
, and
fzf
.

补全测试：使用
```
Explore
```
Agent交互式验证补全功能
脚本审查：使用
```
Task
```
Agent进行跨Shell兼容性审计
代码审查：委托给
```
code-reviewer
```
Agent

若
rust
技能可用，将原生二进制文件编译模式的相关工作委托给它。Shell包装器通常会调用Rust编译的二进制文件来处理性能关键型操作。若
cli-power-tools
技能可用，将现代CLI工具模式的相关工作委托给它。许多Shell插件会包装
fd
、
ripgrep
和
fzf
等工具。

References

参考资料

Zsh integration: ZLE, completions, hooks, parameter expansion
Bash integration: readline, completions, PROMPT_COMMAND, shopt
Fish integration: completions, events, abbreviations, functions
Terminal control: ANSI/CSI sequences, tput, stty, capabilities
POSIX scripting: portable patterns, signal handling, process management
Plugin distribution: installation scripts, dotfile management, version detection

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