自訂別名與 Shell 函式¶
editorcfg（status/list/use/reset/doctor）與 dotfiles-editor 是受管 executable；09_editor.sh 設定 EDITOR／VISUAL。v 仍直接使用 Neovim。見 編輯器選擇。
本 dotfiles repo 中所定義的自訂別名 (alias) 與 shell 函式 (function) 的快速參考。
Terminology rule (zh-TW pages)
技術名詞首次出現以「中文 (English original)」格式呈現，例：依賴注入
(dependency injection)。不自創翻譯——若無公認譯名直接保留英文
（如 embedding、tokenizer）。代碼、API 名、CLI flag、套件名、檔名一律不翻。
維護規則（鏡像於
CLAUDE.md）：每當你新增、修改或刪除自訂別名或 shell 函式時，請更新此表格 —— 包含類型（alias或function）、來源檔案（相對於 repo 根目錄）以及一行描述。
目錄¶
- Editor
- File Listing
- Navigation
- Git
- Tools Picker
- Session Management
- Worktree Management
- GitHub / GitLab
- AI Usage Tracking
- Task Queue
- Networking
- Log Viewers
- Media / AV
- Shell Utilities
- Tmux Integration
- AI Capture
- Summarize
- Claude Code
- Package Managers & Runtime
Editor¶
| Command | Type | Source File | Description |
|---|---|---|---|
v |
alias | dot_config/shell/10_aliases.sh |
開啟 Neovim (nvim) |
File Listing¶
由
eza（現代化的ls替代品）提供。僅在已安裝eza時生效。
| Command | Type | Source File | Description |
|---|---|---|---|
ls |
alias | dot_config/shell/26_eza.sh |
緊湊列表，含圖示、顏色、git 狀態 |
la |
alias | dot_config/shell/26_eza.sh |
長列表，含隱藏檔，目錄優先排序 |
ll |
alias | dot_config/shell/26_eza.sh |
長列表，目錄優先排序（不含隱藏檔） |
lt |
alias | dot_config/shell/26_eza.sh |
樹狀檢視，2 層深 |
llt |
alias | dot_config/shell/26_eza.sh |
長樹狀檢視，3 層深 |
Navigation¶
cd僅在已安裝zoxide時被取代。
| Command | Type | Source File | Description |
|---|---|---|---|
cd |
alias | dot_config/shell/20_zoxide.sh |
透過 zoxide (z) 智慧 cd，採用 frecency 配對 |
Git¶
自訂（本 repo）¶
| Command | Type | Source File | Description |
|---|---|---|---|
gcam-amend |
function | dot_config/shell/10_aliases.sh |
git commit --amend -m "<msg>"（取代訊息） |
gundo |
function | dot_config/shell/10_aliases.sh |
還原最後一次 commit → 回到 staged；印出已還原的 commit 訊息 |
lg |
alias | dot_config/shell/37_lazygit.sh |
開啟 lazygit TUI。Ctrl+O（複製到剪貼簿）透過 ~/.config/lazygit/config.yml 的 os.copyToClipboardCmd 改走 x copy — 本機與 SSH 都可用（clipboard） |
oh-my-zsh git 外掛¶
來源：oh-my-zsh git plugin。當
git外掛啟用時自動載入。請勿在自訂設定中重新定義這些。
函式
| Command | Description | |---------|-------------| | `git_main_branch` | 偵測預設分支（`main`、`master`、`trunk` 等） | | `git_develop_branch` | 偵測開發分支（`dev`、`devel`、`develop` 等） | | `grename別名 — Basic
| Command | Command Expanded | |---------|-----------------| | `g` | `git` | | `grt` | `cd "$(git rev-parse --show-toplevel)"` | | `ghh` | `git help` | | `gcf` | `git config --list` | | `gst` | `git status` | | `gss` | `git status --short` | | `gsb` | `git status --short --branch` |別名 — Add & Apply
| Command | Command Expanded | |---------|-----------------| | `ga` | `git add` | | `gaa` | `git add --all` | | `gapa` | `git add --patch` | | `gau` | `git add --update` | | `gav` | `git add --verbose` | | `gap` | `git apply` | | `gapt` | `git apply --3way` |別名 — Branch
| Command | Command Expanded | |---------|-----------------| | `gb` | `git branch` | | `gba` | `git branch --all` | | `gbd` | `git branch --delete` | | `gbD` | `git branch --delete --force` | | `gbm` | `git branch --move` | | `gbnm` | `git branch --no-merged` | | `gbr` | `git branch --remote` | | `gbg` | 顯示 upstream 已消失 (gone) 的分支 | | `gbgd` | 刪除 upstream 已消失的分支 | | `gbgD` | 強制刪除 upstream 已消失的分支 | | `ggsup` | `git branch --set-upstream-to=origin/別名 — Checkout & Switch
| Command | Command Expanded | |---------|-----------------| | `gco` | `git checkout` | | `gcor` | `git checkout --recurse-submodules` | | `gcb` | `git checkout -b` | | `gcB` | `git checkout -B` | | `gcm` | `git checkout $(git_main_branch)` | | `gcd` | `git checkout $(git_develop_branch)` | | `gsw` | `git switch` | | `gswc` | `git switch --create` | | `gswm` | `git switch $(git_main_branch)` | | `gswd` | `git switch $(git_develop_branch)` |別名 — Commit
| Command | Command Expanded | |---------|-----------------| | `gc` | `git commit --verbose` | | `gcn` | `git commit --verbose --no-edit` | | `gc!` | `git commit --verbose --amend` | | `gcn!` | `git commit --verbose --no-edit --amend` | | `gca` | `git commit --verbose --all` | | `gca!` | `git commit --verbose --all --amend` | | `gcan!` | `git commit --verbose --all --no-edit --amend` | | `gcans!` | `git commit --verbose --all --signoff --no-edit --amend` | | `gcann!` | `git commit --verbose --all --date=now --no-edit --amend` | | `gcam` | `git commit --all --message` | | `gcmsg` | `git commit --message` | | `gcsm` | `git commit --signoff --message` | | `gcas` | `git commit --all --signoff` | | `gcasm` | `git commit --all --signoff --message` | | `gcs` | `git commit --gpg-sign` | | `gcss` | `git commit --gpg-sign --signoff` | | `gcssm` | `git commit --gpg-sign --signoff --message` | | `gcfu` | `git commit --fixup` |別名 — Diff
| Command | Command Expanded | |---------|-----------------| | `gd` | `git diff` | | `gdca` | `git diff --cached` | | `gdcw` | `git diff --cached --word-diff` | | `gds` | `git diff --staged` | | `gdw` | `git diff --word-diff` | | `gdup` | `git diff @{upstream}` | | `gdt` | `git diff-tree --no-commit-id --name-only -r` |別名 — Fetch & Pull
| Command | Command Expanded | |---------|-----------------| | `gf` | `git fetch` | | `gfa` | `git fetch --all --tags --prune --jobs=10` | | `gfo` | `git fetch origin` | | `gl` | `git pull` | | `gpr` | `git pull --rebase` | | `gprv` | `git pull --rebase -v` | | `gpra` | `git pull --rebase --autostash` | | `gprav` | `git pull --rebase --autostash -v` | | `gprom` | `git pull --rebase origin $(git_main_branch)` | | `gprum` | `git pull --rebase upstream $(git_main_branch)` | | `ggpull` | `git pull origin別名 — Push
| Command | Command Expanded | |---------|-----------------| | `gp` | `git push` | | `gpd` | `git push --dry-run` | | `gpv` | `git push --verbose` | | `gpf` | `git push --force-with-lease` | | `gpf!` | `git push --force` | | `gpsup` | `git push --set-upstream origin別名 — Rebase
| Command | Command Expanded | |---------|-----------------| | `grb` | `git rebase` | | `grba` | `git rebase --abort` | | `grbc` | `git rebase --continue` | | `grbi` | `git rebase --interactive` | | `grbo` | `git rebase --onto` | | `grbs` | `git rebase --skip` | | `grbm` | `git rebase $(git_main_branch)` | | `grbd` | `git rebase $(git_develop_branch)` | | `grbom` | `git rebase origin/$(git_main_branch)` | | `grbum` | `git rebase upstream/$(git_main_branch)` |別名 — Reset & Restore
| Command | Command Expanded | |---------|-----------------| | `grh` | `git reset` | | `gru` | `git reset --` | | `grhh` | `git reset --hard` | | `grhk` | `git reset --keep` | | `grhs` | `git reset --soft` | | `groh` | `git reset origin/別名 — Log
| Command | Command Expanded | |---------|-----------------| | `glo` | `git log --oneline --decorate` | | `glog` | `git log --oneline --decorate --graph` | | `gloga` | `git log --oneline --decorate --graph --all` | | `glg` | `git log --stat` | | `glgp` | `git log --stat --patch` | | `glgg` | `git log --graph` | | `glgga` | `git log --graph --decorate --all` | | `glgm` | `git log --graph --max-count=10` | | `glol` | `git log --graph --pretty`（簡短格式，含作者 + 相對日期） | | `glols` | 同 `glol` 加 `--stat` | | `glola` | 同 `glol` 加 `--all` | | `glod` | 同 `glol` 改絕對日期 | | `glods` | 同 `glod` 加 `--date=short` | | `glp` | `git log --pretty=別名 — Merge
| Command | Command Expanded | |---------|-----------------| | `gm` | `git merge` | | `gma` | `git merge --abort` | | `gmc` | `git merge --continue` | | `gms` | `git merge --squash` | | `gmff` | `git merge --ff-only` | | `gmom` | `git merge origin/$(git_main_branch)` | | `gmum` | `git merge upstream/$(git_main_branch)` | | `gmtl` | `git mergetool --no-prompt` | | `gmtlvim` | `git mergetool --no-prompt --tool=vimdiff` |別名 — Cherry-pick, Revert, Blame
| Command | Command Expanded | |---------|-----------------| | `gcp` | `git cherry-pick` | | `gcpa` | `git cherry-pick --abort` | | `gcpc` | `git cherry-pick --continue` | | `grev` | `git revert` | | `greva` | `git revert --abort` | | `grevc` | `git revert --continue` | | `gbl` | `git blame -w` |別名 — Remote
| Command | Command Expanded | |---------|-----------------| | `gr` | `git remote` | | `grv` | `git remote --verbose` | | `gra` | `git remote add` | | `grrm` | `git remote remove` | | `grmv` | `git remote rename` | | `grset` | `git remote set-url` | | `grup` | `git remote update` |別名 — Stash
| Command | Command Expanded | |---------|-----------------| | `gsta` | `git stash push` | | `gstaa` | `git stash apply` | | `gstc` | `git stash clear` | | `gstd` | `git stash drop` | | `gstl` | `git stash list` | | `gstp` | `git stash pop` | | `gsts` | `git stash show --patch` | | `gstall` | `git stash --all` | | `gstu` | `git stash --include-untracked` |別名 — Tag, Worktree, Submodule, Bisect 與其他
| Command | Command Expanded | |---------|-----------------| | `gta` | `git tag --annotate` | | `gts` | `git tag --sign` | | `gtv` | `git tag \| sort -V` | | `gtl` | `git tag --sort=-v:refname -n --list "Tools Picker¶
需要
fzf。資料檔案 (~/.config/docs/tools/cli-tools.md) 必須透過chezmoi apply部署。
| Command | Type | Source File | Description |
|---|---|---|---|
tools-picker |
function | dot_config/zsh/tools/11_tools_picker.zsh |
已安裝 CLI 工具的 fzf picker；Enter 將呼叫貼到緩衝區 (buffer)，Ctrl+E 執行（綁定為 Alt+T） |
tv tools |
tv channel | dot_config/television/cable/tools.toml |
CLI 工具的 Television picker；Enter 執行，Ctrl+T 顯示 tldrf 頁面 |
tv aliases |
tv channel | dot_config/television/cable/aliases.toml |
所有執行期 (runtime) 別名與函式的 Television picker；Enter 執行，Ctrl+Y 複製名稱（綁定為 Alt+A） |
tv files |
tv ZLE | dot_config/zsh/tools/12_television.zsh |
Television 檔案 picker（綁定為 Alt+P） |
tv history |
tv ZLE | dot_config/zsh/tools/12_television.zsh |
Television shell 歷史搜尋（綁定為 Alt+R） |
tv git-log |
tv ZLE | dot_config/zsh/tools/12_television.zsh |
Television git log 瀏覽器（綁定為 Alt+G） |
tv env |
tv ZLE | dot_config/zsh/tools/12_television.zsh |
Television 環境變數 picker（綁定為 Alt+E） |
tv ssh-config |
tv channel | dot_config/television/cable/ssh-config.toml |
SSH host picker，支援 Include config.d/*；Enter 連線 |
tv ports |
tv channel | dot_config/television/cable/ports.toml |
含 PID 的監聽埠 (listening ports) picker；Ctrl+K 終止程序、Ctrl+D 強制終止 |
tv kill-process |
tv channel | dot_config/television/cable/kill-process.toml |
Raycast 風格的 process killer：依名稱模糊搜尋、CPU/MEM 統計 |
Session Management¶
sesh-*需要sesh+tmux；tsesh還需要try-cliRuby gem。mrun/tmrun/zjrun只需 tmux 或 zellij（取決於選擇的後端 (backend)） —— 不依賴 sesh。
| Command | Type | Source File | Description |
|---|---|---|---|
sesh-sessions |
function | dot_config/zsh/tools/22_sesh.zsh |
所有 sesh sessions 的 fzf 彈出 picker（也綁定為 Alt+S） |
sesh-here / shere |
function / alias | dot_config/zsh/tools/22_sesh.zsh |
輕量：在 $PWD 的純 shell session（無 nvim、無專案 layout）。傳入 args 或 -c CMD 覆寫 |
sesh-root / sroot |
function / alias | dot_config/zsh/tools/22_sesh.zsh |
將 sesh 連到目前的 git 根目錄（退回 $PWD）；遵循 sesh.toml 萬用模式/預設值 |
sesh-code / scode |
function / alias | dot_config/zsh/tools/22_sesh.zsh |
以 repo 為範圍的 coding-agent layout：nvim 75% | specstory run [agent] 25%，外加 btop 視窗。Session 命名為 coding-agent/<repo>（防衝突）。在 git repo 之外會拒絕。Flags：--on-exit shell\|kill\|restart、--no-specstory |
sesh-vibe / svibe |
function / alias | dot_config/zsh/tools/22_sesh.zsh |
參數化的多 agent layout：svibe [N] [CLI]（同質）或 svibe --agents claude,codex,opencode,…（異質）。N 個平鋪 (tiled) agent panes + lazygit 視窗 + nvim 視窗。Session 命名為 vibe/<repo>。--on-exit / --no-specstory flags 同 scode |
herdr-vibe / hvibe |
function / alias | dot_config/shell/24_herdr.sh |
herdr 版的 svibe（需要 herdr server + jq）。hvibe [N] [CLI] 或 hvibe --agents claude,codex,opencode。建立 workspace vibe/<repo>：agents tab 含 N 個等寬 agent panes（--tab-per-agent → 每個 agent 一個 tab）+ git + edit tab。重用 svibe 的 specstory/on-exit/git-root 邏輯。每 repo 冪等。從 herdr 外部跑會 attach（在內部則只聚焦）。--on-exit / --no-specstory / --min-width flags，外加 --session NAME（鎖定某個正在跑的 herdr session；預設為當前/default） |
herdr-code / hcode |
function / alias | dot_config/shell/24_herdr.sh |
herdr 版的 scode（需要 herdr + jq）。建立 workspace coding-agent/<repo>：editor tab（nvim 75% | agent 25%）+ monitor tab（btop）。在 git repo 之外會拒絕。從 herdr 外部跑會 attach。Flags：--on-exit、--no-specstory、-a/--agent、--session NAME |
try-sesh / tsesh |
function / alias | dot_config/zsh/tools/32_try.zsh |
開啟一個 try 短暫 (ephemeral) 工作空間，並立即透過 sesh 連線 |
mrun |
function | dot_config/zsh/tools/23_mrun.zsh |
設定即忘 (fire-and-forget)：在 $PWD 跑 CMD 的脫離 (detached) tmux/zellij session，立即返回。mrun [-b tmux\|zellij] [-n NAME] [-d DIR] [-f] [--on-exit shell\|kill\|restart] [-k] [--] CMD [ARGS...]。預設 --on-exit shell 在 CMD 退出後保留 session（掉到登入 shell，可透過 history-Up 重跑）；-k 還原 fire-and-forget 的終止語意。後端預設為 tmux（透過 $MRUN_BACKEND 覆寫）。對 TUI 命令會軟性警告。將 attach 提示印至 stderr |
tmrun |
function | dot_config/zsh/tools/23_mrun.zsh |
mrun -b tmux。執行 CMD 的脫離 tmux session；以 tmux attach -t NAME 附加 (attach) |
zjrun |
function | dot_config/zsh/tools/23_mrun.zsh |
mrun -b zellij。在 $TMPDIR/mrun-layout-* 下產生短暫 KDL（含 default_tab_template，恢復標準 tab-bar / status-bar 外掛），生成脫離的 zellij session；以 zellij attach NAME 附加 |
Worktree Management¶
需要
dev-cli(dev) 與／或worktrunk(wt)。wtcd還需要jq+fzf。Worktrunk 自身的別名（
wt sw、wt ls、wt rm、wt cc、wt oc）定義在dot_config/worktrunk/config.toml中，不在 zsh 中 —— 它們在任何 shell 與互動式 picker 中皆可使用。
| Command | Type | Source File | Description |
|---|---|---|---|
dev |
function | dot_config/shell/39_dev.sh |
dev binary 的包裝器；保留真實 TTY，並透過 child-only file descriptor 將目錄切換交回父 shell。bash/zsh 內容由 dev shell-init 產生 |
wt |
function | dot_config/zsh/tools/37_worktrunk.zsh |
wt 二進位檔的包裝器，會擷取 cd/exec 指令以便 wt switch 真正改變父 shell 的 $PWD（從 wt config shell init zsh eval 而來） |
wtcd |
function | dot_config/zsh/tools/37_worktrunk.zsh |
對 wt list --format=json 路徑的 fzf-tmux picker；cd 進入所選 worktree 但不切換 tmux/sesh session —— 適合偷看姊妹 worktree |
GitHub / GitLab¶
| Command | Type | Source File | Description |
|---|---|---|---|
ghget |
function | dot_config/shell/41_github.sh |
從 GitHub tree URL 下載一個子目錄 |
ghrepo |
function | dot_config/shell/41_github.sh |
模糊搜尋你的 GitHub repos（fzf）→ 預覽 README，然後 clone 後 cd／開啟／複製 URL。Enter clone 到 ${GHREPO_ROOT:-$PWD}。孿生：tv github-repos |
glcreate |
function | dot_config/shell/42_gitlab.sh |
在某 group 下建立私有 GitLab repo、設定 origin 並 push |
glcreate-ai |
function | dot_config/shell/42_gitlab.sh |
同 glcreate，但使用 AI agent 自動產生描述 |
glrepo |
function | dot_config/shell/42_gitlab.sh |
模糊搜尋你的 GitLab repos（fzf）→ 預覽，然後 clone 後 cd／開啟／複製 URL。孿生：tv gitlab-repos。自架：GITLAB_HOST=… |
AI Usage Tracking¶
cbu/cbc/cbca需要codexbar。ccusage需要bun。
| Command | Type | Source File | Description |
|---|---|---|---|
cbu |
alias | dot_config/shell/40_codexbar.sh |
Claude Code 使用統計 (codexbar usage --provider claude) |
cbc |
alias | dot_config/shell/40_codexbar.sh |
Claude Code 成本明細 (codexbar cost --provider claude) |
cbca |
alias | dot_config/shell/40_codexbar.sh |
跨所有 provider 的成本明細 (codexbar cost) |
ccusage |
alias | dot_config/shell/07_bunx_cli.sh |
透過 bunx ccusage 的 Claude Code 用量追蹤 |
Task Queue¶
需要
pueue與jq。
| Command | Type | Source File | Description |
|---|---|---|---|
pqsum |
function | dot_config/zsh/tools/36_pueue.zsh |
摘要 pueue 佇列狀態：整體進度、ETA、各 group 細分 |
Networking¶
條件式別名 —— 僅在對應工具已安裝時定義。
| Command | Type | Source File | Description |
|---|---|---|---|
ports |
alias | dot_config/zsh/tools/50_networking.zsh |
列出所有監聽埠 (lsof -i -P -n \| grep LISTEN) |
myip |
alias | dot_config/zsh/tools/50_networking.zsh |
顯示公開 IP 位址 |
localip |
alias | dot_config/zsh/tools/50_networking.zsh |
顯示本機 IP 位址（依平台調整） |
pingsweep |
function | dot_config/zsh/tools/50_networking.zsh |
透過 nmap -sn 對本機 /24 子網段進行 ping sweep (需要 nmap) |
arpscan |
alias | dot_config/zsh/tools/50_networking.zsh |
對本機網路進行 ARP 掃描 (sudo arp-scan -l) (需要 arp-scan) |
dns |
alias | dot_config/zsh/tools/50_networking.zsh |
透過 doggo 進行 DNS 查詢（DoH/DoT/DoQ） (需要 doggo) |
bw-net |
alias | dot_config/zsh/tools/50_networking.zsh |
即時頻寬監看 (sudo bandwhich) (需要 bandwhich) |
portscan |
alias | dot_config/zsh/tools/50_networking.zsh |
透過 rustscan 的快速 port 掃描 (需要 rustscan) |
lanscan |
alias | dot_config/zsh/tools/50_networking.zsh |
對 LAN 完整掃描裝置 + port，輸出至 ~/.cache/tv/（餵給 tv lan-devices） |
tv-lan |
alias | dot_config/zsh/tools/50_networking.zsh |
開啟 lan-devices Television 頻道 |
ssh-setup-remote |
function | dot_config/shell/96_ssh_setup.sh |
互動式精靈：選擇／建立 SSH 金鑰（若私鑰旁邊缺 .pub 會自動修復）、把公鑰裝到遠端（POSIX 遠端用 ssh-copy-id；Windows sshd 遠端則走對應的 PowerShell 路徑，管理員帳號會寫入 administrators_authorized_keys），再把金鑰接進本機 ~/.ssh/config —— 若別名已設定過就就地編輯既有 Host 區塊（會遞迴沿 Include config.d/* 找到正確檔案），否則附加新別名並可補上缺漏的 Include。會先解析目標完整的 ProxyJump 鏈，由外而內對每一跳都重跑一次整套流程——以前透過跳板連線時，只有最後一跳會設成免密碼。bash／zsh 的 gum 選單若失敗或取消，會停止目前步驟，不會自動採用預設選項。在有終端機且已安裝 gum 時，提示會用 gum（方向鍵操作、金鑰以清單挑選），否則退回 bash read -e / zsh vared，再退回單純的 read。環境變數：SSH_SETUP_ASSUME_YES=1（每個提示都取預設值）、SSH_SETUP_KEY=<path>（跳過金鑰選擇）、SSH_SETUP_NO_MUX=1（停用每次執行的 ControlMaster）、SSH_SETUP_NO_GUM=1（即使有 gum 也用純文字提示）。就地編輯需 python3，否則退回僅附加。 |
Proxy 輔助¶
可攜的 loopback proxy 輔助函式。遵循
$LOCAL_PROXY_URL（可選$LOCAL_PROXY_SOCKS_URL用於分離的 Clashsocks-port:設定）。偵測順序：環境變數 → macOS System Proxy（HTTPEnable 且 loopback 埠在聽 —— Clash Verge / CFW「系統代理」寫入處）→ Clash Verge / mihomo / CFW 設定檔（宣告的埠必須真的在聽）→ 探測7897/7890/7891/17890/1087/8118/8080。優先 System Proxy 可避免舊的~/.config/clash蓋過正在跑的 Verge7897。偵測結果按 shell 快取；proxy-off/proxy-refresh會清除。設定$LOCAL_PROXY_AUTO_ACTIVATE=1可在啟動時自動匯出。完整指南：docs/tools/web-reader.md。Copilot 的 Node 客戶端需另外帶HTTPS_PROXY/--proxy-env——見 docs/tools/copilot-claude-proxy.md。
| Command | Type | Source File | Description |
|---|---|---|---|
withproxy |
function | dot_config/zsh/tools/50_networking.zsh |
執行單一命令，僅將 proxy 環境變數匯出到子程序（例如 withproxy curl ...） |
try_direct_then_proxy |
function | dot_config/zsh/tools/50_networking.zsh |
直連執行命令；失敗則透過 withproxy 重試。reader 函式預設使用此。 |
proxy-on |
function | dot_config/zsh/tools/50_networking.zsh |
在當前 shell 匯出 http_proxy/https_proxy/HTTP_PROXY/HTTPS_PROXY/ALL_PROXY |
proxy-off |
function | dot_config/zsh/tools/50_networking.zsh |
在當前 shell 取消所有 proxy 環境變數 |
proxy-status |
function | dot_config/zsh/tools/50_networking.zsh |
回報狀態：active（已匯出）、available（已偵測到）或 unavailable |
proxy-test |
function | dot_config/zsh/tools/50_networking.zsh |
以 curl https://www.google.com/generate_204 測試已偵測 proxy 是否可出網（HTTP，不是 ICMP ping） |
proxy-refresh |
function | dot_config/zsh/tools/50_networking.zsh |
清除快取的偵測結果、重新探測、印出狀態（在切換 proxy 後使用） |
Docker registry 出口（docker-net）¶
docker pull是在 daemon 裡執行的，所以你 shell 的 proxy 環境變數和~/.docker/config.json的proxies.default都影響不到它 —— 後者只在docker run/docker build時注入到 container 裡。docker-net管的是 daemon 這一層：用和proxy-status同一個__net_detect_proxy解析本機 proxy、寫入daemon.json的proxieskey（Engine ≥ 23），並為 mirror 沒有的 image 提供逐次 pull 的降級階梯。完整指南：docs/tools/docker-net.md。mirror 策略與四種安裝變體：docs/tools/containers.md。macOS：除了on/off之外都能用 —— 那兩個會拒絕，因為 Docker Desktop / OrbStack 把 daemon 跑在 VM 裡（127.0.0.1是 VM 的 loopback 不是你 Mac 的），proxy 要在它們的 UI 設。
| Command | Type | Source File | Description |
|---|---|---|---|
docker-net status |
function | dot_config/shell/51_docker_net.sh |
一屏現況：安裝形態、daemon proxy、生效中的 mirror、偵測到的本機 proxy、TUN 攔截、死設定警告 |
docker-net doctor |
function | dot_config/shell/51_docker_net.sh |
九段診斷。--deep 會額外從 daemon 那一側探測 ghcr/gcr/quay/registry.k8s.io（不會下載任何東西） |
docker-net on |
function | dot_config/shell/51_docker_net.sh |
用偵測到的 proxy 寫入 daemon.json 的 proxies 並重啟 daemon（會先確認 —— 重啟會殺掉執行中的 container） |
docker-net off |
function | dot_config/shell/51_docker_net.sh |
移除該區塊並重啟 |
docker-net mirrors |
function | dot_config/shell/51_docker_net.sh |
只測 mirror 健康度 —— 分類出 DNS 消失 / 403 / 502 / TLS reset / timeout |
docker-net pull |
function | dot_config/shell/51_docker_net.sh |
以降級階梯拉取：一般 pull → 明確指定 mirror 前綴再 retag → skopeo copy 走 shell 的 proxy（不必重啟 daemon） |
Web reader¶
在終端機中將網頁渲染為 markdown。所有函式都使用
try_direct_then_proxy，因此非 GFW'd 的 URL 不會付出 proxy 開銷。依函式名稱挑選擷取器 (extractor)。完整指南：docs/tools/web-reader.md。
| Command | Type | Source File | Description |
|---|---|---|---|
readurl |
function | dot_config/zsh/tools/55_web_reader.zsh |
透過 jina.ai Reader + glow 閱讀文章（遠端，本地除 glow 外無依賴） |
readlocal |
function | dot_config/zsh/tools/55_web_reader.zsh |
透過 trafilatura + glow 閱讀文章（本地、離線） (需要 trafilatura) |
readnode |
function | dot_config/zsh/tools/55_web_reader.zsh |
透過 readability-cli (readable) + glow 閱讀文章（Mozilla Readability） (需要 readable) |
readraw |
function | dot_config/zsh/tools/55_web_reader.zsh |
渲染整頁：curl | pandoc -f html -t gfm | glow -（無文章擷取） (需要 pandoc) |
Log Viewers¶
對
tailspin(tspin) 與ccze的薄包裝，用以著色任意 log 檔案。完整指南：docs/tools/log-tools.md。
| Command | Type | Source File | Description |
|---|---|---|---|
catl |
function | dot_config/zsh/tools/29_log_tools.zsh |
透過 tspin --print 對 log 檔上色的 cat（stdout 模式；可乾淨地管線） (需要 tspin) |
lessl |
function | dot_config/zsh/tools/29_log_tools.zsh |
透過 ccze -A \| less -RSFX 顯示 ANSI 著色 log 的 pager (需要 ccze) |
logtail |
function | dot_config/zsh/tools/29_log_tools.zsh |
即時 tailspin 高亮的 tail -f（優先 tspin --follow，退回 tail -F \| tspin --print） |
svclog |
function | dot_config/zsh/tools/29_log_tools.zsh |
跨平台服務 log 跟隨器 —— Linux 用 journalctl -fu、macOS 用 tail -F StdoutPath / log stream --predicate，皆透過 tailspin 管線。接受 --user 用於使用者範圍。用法：svclog [--user] <service>。見 services.md |
svcstat |
function | dot_config/zsh/tools/29_log_tools.zsh |
跨平台服務狀態 —— Linux 用 systemctl status、macOS 用 launchctl print DOMAIN/LABEL。接受 --user。用法：svcstat [--user] <service> |
Media / AV¶
影音由
ffmpeg提供、圖片由ImageMagick提供。只要任何一個媒體工具在$PATH上就會載入（通常透過installMediaTools=true）。每個 function 自行檢查需要的工具。底層工具見 docs/tools/ffmpeg.md 與 docs/tools/imagemagick.md。
| Command | Type | Source File | Description |
|---|---|---|---|
compress-video <input> |
function | dot_config/zsh/tools/29_media.zsh |
用 x264 CRF 28 重編碼 → <name>_compressed.mp4（更小；想換畫質直接改 CRF） |
extract-audio <input> |
function | dot_config/zsh/tools/29_media.zsh |
去掉影像、複製音訊 stream → <name>.m4a（不重新編碼） |
to-wav16k <input> |
function | dot_config/zsh/tools/29_media.zsh |
Resample 成 16 kHz 單聲道 WAV → <name>_16k.wav（Whisper / faster-whisper 輸入格式） |
compress-image <input> [<mb>=1] |
function | dot_config/zsh/tools/29_media.zsh |
重編碼成體積在目標 MB 以下的 JPEG → <name>_<mb>mb.jpg；使用 ImageMagick -define jpeg:extent=NMB（內部自動迭代品質，不用手動二分搜）。Alpha 會被攤平成白色。 |
resize-image <input> <width_px> |
function | dot_config/zsh/tools/29_media.zsh |
縮放到寬度 = <width_px>，保持比例 → <name>_<width>w.<ext>；輸出延用原本格式 |
media-pick |
function | dot_config/zsh/tools/29_media.zsh |
互動式入口：gum file 選檔 → 動作選單 →（必要時）參數輸入。把上面所有 helper 串起來；只有在 gum 已在 $PATH 時才載入。 |
Shell Utilities¶
| Command | Type | Source File | Description |
|---|---|---|---|
zsh-profile |
alias | dot_config/zsh/10_aliases.zsh |
對 zsh 啟動時間做效能剖析 (ZSH_PROF=1 zsh -i -c exit) |
ghostty-ssh-terminfo |
function | dot_config/shell/10_aliases.sh |
透過 SSH 在遠端主機上安裝 xterm-ghostty terminfo（無需特權） |
nvtop |
function | dot_config/shell/10_aliases.sh |
讓 Snap 版從持久化的 common 目錄讀取 Ghostty terminfo；其他版本照常執行 |
source-rc |
function | dot_config/shell/10_aliases.sh |
就地重新載入目前 shell 的 rc（~/.zshrc 或 ~/.bashrc，依 $ZSH_VERSION/$BASH_VERSION 自動偵測）—— chezmoi apply 後不必開新 login shell 就能吃到新的 alias/function。是 exec 型 cas/cau 的輕量版本；與手動 source ~/.zshrc 有相同的注意事項 |
reload |
alias | dot_config/shell/10_aliases.sh |
source-rc 的簡短別名。現已跨 shell（先前僅 bash 的 . ~/.bashrc） |
tldrf |
function | dot_config/zsh/tools/28_tldr.zsh |
帶語言退回的 tldr：zh_TW → zh → en (需要 tldr) |
Tmux Integration¶
需要 tmux + pane scrollback 中的 OSC 133 標記（由
02_shell_integration.zsh發出 —— 若缺少，執行exec zsh重新載入）。三個函式都會輸出至 stdout（可管線：cpout | grep ERROR），並透過 tmux 的 OSC 52 橋接複製到系統剪貼簿。對應於prefix + M-y/M-itmux 綁定的 shell 層版本 —— 見 docs/tools/tmux/README.md → OSC 133。
| Command | Type | Source File | Description |
|---|---|---|---|
cpout [N] |
function | dot_config/zsh/tools/03_tmux_capture.zsh |
印出 + 複製第 N 個最近命令的輸出（預設 N=1）。接受位置整數 (positional integer) 作為回看 |
cpcmd [N] |
function | dot_config/zsh/tools/03_tmux_capture.zsh |
印出 + 複製第 N 個最近命令的輸入行（預設 N=1）。讀取 zsh 歷史，因此在 tmux 之外也能用 |
cpblock [N] |
function | dot_config/zsh/tools/03_tmux_capture.zsh |
印出 + 複製第 N 個最近命令的完整區塊（prompt + input + output）。預設 N=1 |
AI Capture¶
一次性管線：擷取過去的區塊（透過
cpblock N），並以非互動式 / 顧問模式傳給 coding-agent CLI（claude / opencode / codex / cursor-agent）。Agent 依列出順序自動偵測；以-a AGENT覆寫。Prompt 以-p PROMPT覆寫。Agent 回覆送至 stdout（可管線：aifix | tee /tmp/advice.md），狀態行送至 stderr。
| Command | Type | Source File | Description |
|---|---|---|---|
aifix [N] [-a AGENT] [-p PROMPT] |
function | dot_config/zsh/tools/04_ai_capture.zsh |
擷取第 N 個區塊（tmux），請 agent 診斷 + 建議修復 |
aiexplain [N] [-a AGENT] [-p PROMPT] |
function | dot_config/zsh/tools/04_ai_capture.zsh |
擷取第 N 個區塊（tmux），請 agent 解釋發生什麼事 |
aifix-stdin [-a AGENT] [-p PROMPT] |
function | dot_config/zsh/tools/04_ai_capture.zsh |
非 tmux：將 stdin 作為 context 讀取，請 agent（tail -100 log \| aifix-stdin） |
aifix-run -- CMD [ARG...] |
function | dot_config/zsh/tools/04_ai_capture.zsh |
非 tmux：執行 CMD 並 tee stdout+stderr，餵給 agent |
aifix-rerun [-y] |
function | dot_config/zsh/tools/04_ai_capture.zsh |
非 tmux：thefuck 風格地重新執行最後一個命令（除非 -y 否則會確認；副作用警告） |
aiblock |
function | dot_config/zsh/tools/04_ai_capture.zsh |
啟動 scripts/aiblock.py TUI：從歷史挑選命令、編輯 prompt、挑選動作（print / copy / 生成新 agent 視窗）。透過 uv run --script 解析依賴 |
Summarize¶
summarize包裝函式 (installSummarize)。輸出語言與長度來自受管的~/.summarize/config.jsonoverlay，所以每個包裝函式本來就回繁體中文；~/.config/summarize/prompts/底下的 presets 只改變結構。加上--cli claude|codex|gemini可沿用已登入的 coding CLI 而非 API key，或用--language en單次覆蓋語言。
| 指令 | 類型 | 來源檔案 | 說明 |
|---|---|---|---|
ytsum <url> |
function | dot_config/shell/32_summarize.sh |
影片型摘要：TL;DR → 主要論點 → 值得注意的細節 → 重要時間點 → 值不值得完整觀看。使用 prompts/youtube-zhtw.md |
sumq <url\|file> |
function | dot_config/shell/32_summarize.sh |
任何來源的 30 秒分流 (--length short + prompts/quickscan-zhtw.md)：一句話結論、三個重點、要讀還是跳過 |
suml <url\|file> |
function | dot_config/shell/32_summarize.sh |
summarize --length long——使用上游內建結構，不覆寫 prompt |
sumj <url\|file> |
function | dot_config/shell/32_summarize.sh |
summarize --json——給 jq 或 agent 用的機器可讀 envelope |
Claude Code¶
專案區域 (project-local) 的 Claude Code 設定輔助。僅在 merge 路徑（目標檔案已存在時）需要
jq。
| Command | Type | Source File | Description |
|---|---|---|---|
claude-plans-here [-f] [-y] |
function | dot_config/shell/10_aliases.sh |
建構/更新 ./.claude/settings.json，使 Claude Code 的 /plan 檔案落在 ./.claude/plans/（在 repo 內）。同時 mkdir -p .claude/plans/ 並提供匯入「孤兒」(orphan) plans 的選項 —— 也就是先前寫在全域 ~/.claude/plans/ 中、屬於本 cwd 或 git-root 的 plans。偵測會解析 ~/.claude/projects/<encoded-path>/*.jsonl 中的權威寫入/結果欄位（Write/Edit/MultiEdit 路徑、toolUseResult.filePath、ExitPlanMode.planFilePath），不採計聊天提及。-f 自動同意 settings 合併提示；-y 自動同意孤兒複製提示。~/.claude/plans/ 中的原始檔案會保留 |
Copilot agent gateway¶
用 GitHub Copilot served 的模型驅動 Claude Code 與 Codex，透過只安裝一次、版本釘選的 copilot-api 維護 fork。Claude Code 優先可選的 Claude model，否則依 live catalog 建立 main/Terra/Luna 角色 profile；Codex 優先 native Responses OpenAI model。完整指南、ToS / rate-limit 風險與設定分層：docs/tools/copilot-claude-proxy.md。首次需執行
copilot-proxy auth；launcher 不碰 committed project settings 或 chezmoi-managed user settings。
| Command | Type | Source File | Description |
|---|---|---|---|
copilot-proxy [start\|stop\|status\|stats\|events\|limiter\|logs\|quota\|bench\|update\|rollback\|doctor\|…] |
function | dot_config/shell/43_copilot_proxy.sh |
管理並量測釘選 proxy。Exact update 直接安裝已驗證的 archive；離線 rollback 還原套件與 transport 設定，保留目前憑證與用量。:4142 shim 以不含內容的 metrics 追蹤完成、draining 及 unknown 工作，配對 restart 只在兩個 process 都退出後清除保留的 admission。自適應並行仍為 4→8；limiter status/set/reset 即時調整，COPILOT_SHIM_MIN/MAX 保留跨 restart 預設。支援 logs [-f]、stats/events --json 與有上限但消耗 quota 的 bench。completion：61_copilot_proxy_completion.{zsh,bash}。 |
claude-copilot [--fast] [--specstory-mode MODE] [args...] |
function | dot_config/shell/43_copilot_proxy.sh |
單次 CLI --settings 注入；與 -once 相同。支援 --specstory-mode run/exit/off，預設 run；exit 在退出後同步。先合併使用者 JSON／檔案，既有 pin 不改寫。 |
claude-copilot-once [args...] |
function | dot_config/shell/43_copilot_proxy.sh |
建議的日常入口；與 claude-copilot 相同，不暫寫專案 pin。 |
codex-copilot [--specstory-mode MODE] [args...] / codex-copilot-once |
function | dot_config/shell/43_copilot_proxy.sh |
單次 Responses provider 與 metadata 注入；兩個名稱相同。--specstory-mode run/exit/off 預設 run，run/exit 保留 SpecStory command。明確 model／permission 優先；不改 Codex config。 |
copilot-run <cmd...> |
function | dot_config/shell/43_copilot_proxy.sh |
泛用積木：自動啟動代理，然後帶著代理 env 執行 任意 指令（例如 copilot-run specstory run claude、copilot-run claude --resume） |
copilot-here [claude] [on [MODEL] [--yes]\|off\|status] |
function | dot_config/shell/43_copilot_proxy.sh |
明確的持久 Claude pin。新建、相同不動；已有差異顯示預覽並詢問，預設保留，--yes 供腳本更新。拒絕 tracked 檔，透過 Git 查詢本機 exclude；off 還原未再被手動修改的受管理欄位。Codex 0.156.1 不支援 project provider pin。 |
copilot-model [<id>\|-l\|-L\|-c\|--auto [--why]\|--why\|--json] |
function | dot_config/shell/43_copilot_proxy.sh |
切換 main 並產生完整 Claude Code role profile。--auto 會排除 disabled／hidden／embedding／-fast entries，依 catalog capability tier 排序，並由 curated allowlist override：Claude > OpenAI > grok > Gemini。選擇不受舊 state／pin 或方案標籤限制。已知 OpenAI main 依 gpt-6-astra > gpt-6-sol > gpt-5.6-sol 排序；gpt-6-luna 保持 lightweight，優先用於 Haiku/background。Sol/Luna 使用 live prompt budget，70% compact ratio 僅套用 Astra。-L 顯示 tier／price／context／plan metadata；--why 不寫入只解釋；--json 輸出 raw catalog；-c 顯示完整 profile。[1m] 與 compact ceiling 都來自 metadata。 |
copilot-raycast [status\|generate [--dry-run] [--all]\|diff\|probe [MODEL]\|doctor\|edit] |
function | dot_config/shell/45_copilot_raycast.sh |
從即時的代理 (proxy) 模型清單產生 Raycast 的 AI Custom Providers 設定檔（~/.config/raycast/ai/providers.yaml），讓每個 Copilot 模型都出現在 Quick AI / AI Chat / AI Commands。每個 model id 都經過零額度探針 (zero-quota probe) 過濾——帶 {"messages":[]} 打 POST /chat/completions 會在推論 (inference) 前就被拒絕，而錯誤訊息可區分真正可用的模型（messages must be non-empty）與 /v1/models 只是「宣稱」有提供的模型（model_not_supported、unsupported_api_for_model）；靜態 metadata 裡沒有任何欄位能預測這件事。base_url 沿用 _copilot_pinned_base（throttle shim 開著時指向 shim），但掃描本身直接打 :4141。寫入前會備份到 ~/.local/state/copilot-raycast/backups/、用 yq 驗證後才原子性 (atomic) 搬移——格式壞掉的檔案會讓 Raycast 無聲地丟掉所有 custom provider。檔案裡其他 provider 會原樣保留（需要 yq）。status/doctor 會讀 Raycast prefs 裡的 raycastAI_modelRouterModelInfo，顯示 Raycast 實際載入了什麼。需要 jq + curl；yq 用於驗證與保留。環境變數：COPILOT_RAYCAST_{CONFIG,ID,LABEL,SUFFIX,TEMP,JOBS,PROBE_BASE,KEEP} |
Package Managers & Runtime¶
| Command | Type | Source File | Description |
|---|---|---|---|
load-nvm |
alias | dot_config/shell/10_aliases.sh |
將 NVM 延遲載入 (lazy-load) 到當前 session（啟動時通常會略過） |
bw-update-completion |
alias | dot_config/shell/10_aliases.sh |
重新產生快取的 Bitwarden zsh 補全檔案 |
brew-mirror |
function | dot_config/shell/10_aliases.sh |
即時切換 Homebrew 鏡像（GFW 解法）：brew-mirror {bfsu\|ustc\|aliyun\|tuna}。設定 bottle/API + brew.git 環境變數，並 unset HOMEBREW_CORE_GIT_REMOTE（同時自動 untap 殘留的 >100 MB homebrew/core clone）；無參數時印出當前 endpoints。預設基準為 BFSU（在 dot_config/shell/00_exports.sh.tmpl 中設定;2026-07 benchmark 最快）。Aliyun 的 brew.git 壞掉，所以它的 preset 會保留既有的 git remote |
macOS 系統 (memory / swap / storage)¶
macOS 專屬。Diagnose / reclaim / watch macOS memory pressure 與 swap accumulation — 即「儲存空間 > 系統資料」一夜暴增、Activity Monitor 顯示
Swap Used: 17.59 GB但 Memory Pressure 還是綠的這個經典情況。 完整深入解說：tools/macos-swap.zh-TW.md。Pitfall 案例：pitfalls/macos-swap-files-never-shrink.md。
| Command | Type | Source File | Description |
|---|---|---|---|
mac-mem-status |
function | dot_config/shell/55_macos_mem.sh.tmpl |
單頁 memory + swap + storage 報告：vm.swapusage、memory_pressure、解析過的 vm_stat、swapfile 大小（/System/Volumes/VM/swapfile*）、按 compressed-aware memory 排前 10（top -o mem）、TM 本機快照數、彩色 verdict 行。不需 sudo。短別名：mms。 |
mac-mem-reclaim [--dry-run] [--yes] [--force] [--include LIST] |
function | dot_config/shell/55_macos_mem.sh.tmpl |
互動式清理。永遠安全：sudo purge。--include 加碼選項：spotlight（killall mds_stores+mdworker_shared）、snapshots（tmutil thinlocalsnapshots / 5GB 4）、sleepimage（刪 /private/var/vm/sleepimage —— 筆電不安全）、windowserver（sudo killall -HUP WindowServer —— 會把你登出）。短別名：mmr。 |
mac-mem-watch [INTERVAL_SEC] |
function | dot_config/shell/55_macos_mem.sh.tmpl |
Live 一行一拍 tail：free / compressed / swap_used + 每秒 pageins / pageouts / swapins / swapouts。預設 5 秒。設計給 tmux 旁邊面板用。短別名：mmw。 |