From 0cf0dd61b9f01453a3559ee4e3380bb69d5a5439 Mon Sep 17 00:00:00 2001
From: Odboy <tianjun@odboy.cn>
Date: Tue, 3 Nov 2026 19:42:54 +0800
Subject: [PATCH] =?UTF-8?q?feature:=20=E6=96=B0=E5=A2=9E=E5=91=BD=E4=BB=A4?=
 =?UTF-8?q?=E8=A1=A5=E5=85=A8=E8=84=9A=E6=9C=AC=E7=94=A8=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.completion.md | 133 +++++++++++++++++++++++++++++++++++++++++++
 README.md            |   2 +
 2 files changed, 135 insertions(+)
 create mode 100644 README.completion.md

diff --git a/README.completion.md b/README.completion.md
new file mode 100644
index 0000000..1775869
--- /dev/null
+++ b/README.completion.md
@@ -0,0 +1,133 @@
+# Shell 自动补全（`kopsc completion`）
+
+> 返回 [README.md](README.md)
+
+为 bash、zsh、fish 或 powershell 生成命令补全脚本，配置后可通过 Tab 键自动补全命令、子命令和选项。
+
+```bash
+kopsc completion bash        # 生成 bash 补全脚本
+kopsc completion zsh         # 生成 zsh 补全脚本
+kopsc completion fish        # 生成 fish 补全脚本
+kopsc completion powershell  # 生成 powershell 补全脚本
+```
+
+## 配置方法
+
+### Bash（Linux）
+
+**临时生效（当前会话）：**
+
+```bash
+source <(kopsc completion bash)
+```
+
+**永久生效：**
+
+```bash
+# 将补全脚本添加到 /etc/bash_completion.d/
+kopsc completion bash | sudo tee /etc/bash_completion.d/kopsc > /dev/null
+
+# 重新加载配置
+source ~/.bashrc
+```
+
+### Zsh（macOS / Linux）
+
+**临时生效（当前会话）：**
+
+```zsh
+source <(kopsc completion zsh)
+```
+
+**永久生效：**
+
+```zsh
+# 将补全脚本添加到 ~/.zshrc
+echo 'source <(kopsc completion zsh)' >> ~/.zshrc
+
+# 重新加载配置
+source ~/.zshrc
+```
+
+或者使用更规范的方式：
+
+```zsh
+# 创建补全目录
+mkdir -p ~/.zsh/completions
+
+# 生成补全脚本
+kopsc completion zsh > ~/.zsh/completions/_kopsc
+
+# 在 ~/.zshrc 中添加（如果还没有）
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+echo 'autoload -U compinit && compinit' >> ~/.zshrc
+
+# 重新加载配置
+source ~/.zshrc
+```
+
+### Fish
+
+**临时生效（当前会话）：**
+
+```fish
+kopsc completion fish | source
+```
+
+**永久生效：**
+
+```fish
+# 将补全脚本添加到 ~/.config/fish/completions/
+kopsc completion fish > ~/.config/fish/completions/kopsc.fish
+
+# 重新加载配置（或重启 fish）
+source ~/.config/fish/config.fish
+```
+
+### PowerShell（Windows）
+
+**临时生效（当前会话）：**
+
+```powershell
+kopsc completion powershell | Out-String | Invoke-Expression
+```
+
+**永久生效：**
+
+```powershell
+# 生成补全脚本到文件
+kopsc completion powershell > "$env:USERPROFILE\Documents\WindowsPowerShell\kopsc_completion.ps1"
+
+# 在 PowerShell 配置文件中添加（用 notepad $PROFILE 编辑）
+Add-Content -Path $PROFILE -Value ". $env:USERPROFILE\Documents\WindowsPowerShell\kopsc_completion.ps1"
+
+# 重新加载配置
+. $PROFILE
+```
+
+如果 `$PROFILE` 文件不存在，先创建：
+
+```powershell
+New-Item -Type File -Force $PROFILE
+```
+
+## 验证配置
+
+配置完成后，尝试以下操作：
+
+```bash
+# 输入 kopsc 后按 Tab，应显示所有分组
+kopsc <Tab>
+
+# 输入 kopsc docker 后按 Tab，应显示 docker 子命令
+kopsc docker <Tab>
+
+# 输入 kopsc file findbig -- 后按 Tab，应显示选项
+kopsc file findbig --<Tab>
+```
+
+## 注意事项
+
+- 补全脚本会列出所有已注册的命令和选项
+- 如果新增命令后补全不生效，重新执行上述配置步骤即可
+- PowerShell 可能需要调整执行策略：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
diff --git a/README.md b/README.md
index 40a8089..2aa62ed 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,7 @@ kopsc 的命令按用途分组，每组的完整说明（命令表、选项、
 | `kopsc explain <命令>` | 解释为什么选中某条底层命令，列出全部候选与被排除的原因；支持 `docker.clearsafe` 与 `docker clearsafe` 两种写法，也支持分组名（`kopsc explain docker`） |
 | `kopsc platform` | 显示探测到的 OS/ARCH/发行版/运行时 |
 | `kopsc version` | kopsc 自身版本与平台 |
+| `kopsc completion <shell>` | 生成 shell 补全脚本（bash/zsh/fish/powershell），详见 [README.completion.md](README.completion.md) |
 | `kopsc <命令> -h` | 任意命令的说明、当前平台命中结果与选项 |
 
 ### 各模块入口速查
@@ -273,6 +274,7 @@ kopsc 的命令按用途分组，每组的完整说明（命令表、选项、
 | sys | [`README.sys.md`](README.sys.md) |
 | log | [`README.log.md`](README.log.md) |
 | fw | [`README.fw.md`](README.fw.md) |
+| completion | [`README.completion.md`](README.completion.md) |
 
 新分组需要新建 `README.<分组>.md`，并在本文件「命令一览」的表格里加一行链接。
 每条命令至少要写清：**作用**、**实际执行什么**、**示例**；有独有选项时补选项表。