1. 项目概述一个为命令行注入灵魂的“技能库”如果你是一个重度命令行用户每天在终端里敲击着ls、cd、git commit这些命令有没有那么一瞬间会感到一丝枯燥和重复或者当你看到同事行云流水般地敲出一串你从未见过的组合命令高效地完成了一个复杂任务时是否心生羡慕这就是hermesnest/fish-skill这个项目试图解决的问题。它不是一个全新的命令行工具而是一个基于fish这个现代化 shell 的“技能”或“秘籍”仓库。简单来说你可以把它理解为一个为你的fishshell 量身定制的“应用商店”或“插件市场”但里面售卖的不是软件而是一个个封装好的、能解决特定问题的“技能”Skill。这些技能可能是一个复杂的别名alias一个增强版的函数或者一套组合命令的快捷方式。它的核心价值在于将那些散落在个人笔记、团队 Wiki 或记忆深处的命令行“黑魔法”进行标准化、模块化的封装和分享让高效操作变得可复用、可传播。无论你是运维工程师、开发者还是任何需要与终端打交道的技术从业者这个项目都能让你的命令行体验从“能用”跃升到“好用”甚至“惊艳”的级别。2. 核心设计理念为什么是 Fish Shell Skill 模式2.1 为什么选择 Fish Shell 作为载体在深入技能本身之前必须先理解承载它的平台——Fish Shell。与传统的 Bash 或 Zsh 相比Fish 有几个天生适合做“技能库”的特性这也是hermesnest/fish-skill项目设计的基础。首先是开箱即用的优秀体验。Fish 的自动补全和语法高亮是内置且智能的。你不需要像配置 Zsh 的zsh-autosuggestions和zsh-syntax-highlighting那样安装一堆插件。当你输入命令时Fish 会根据历史和环境以淡色字体给出补全建议按→键即可直接采纳。这种交互模式使得“技能”的调用变得异常流畅。一个复杂的技能命令可能只需要输入前几个字母就能被智能地补全出来。其次是更友好的脚本语法。Fish 的脚本语法设计更接近常规编程语言减少了 Bash 中那些令人头疼的括号、引号转义问题。例如在 Fish 中设置变量直接用set var value条件判断也更直观。这意味着编写一个“技能”本质上是一个 Fish 函数的门槛更低代码更清晰易读也更容易维护和分享。最后是配置的集中化与结构化。Fish 的主要配置文件是~/.config/fish/config.fish函数通常存放在~/.config/fish/functions/目录下每个函数一个独立文件。这种结构化的管理方式与“技能即独立模块”的理念完美契合。安装一个技能本质上就是将一个函数文件放到指定目录卸载则是删除它。管理起来一目了然。注意虽然 Fish 很优秀但它与 Bash 不完全兼容。如果你的工作环境严重依赖 Bash 特有的脚本或.bashrc中的复杂配置迁移可能需要一些适配成本。但对于大多数交互式使用场景和新项目Fish 的优势非常明显。2.2 “Skill”模式与传统别名/脚本的区别你可能用过别名alias比如alias llls -alF。你也可能写过 shell 脚本保存为myscript.sh然后赋予执行权限。那么“Skill”模式和它们有什么区别封装性与复杂性别名适合极其简单的命令替换。而“技能”可以是一个复杂的函数包含参数处理、条件逻辑、错误检查、交互式提示等。例如一个“git 仓库快速初始化并关联远程”的技能可以封装多个步骤并接受仓库名作为参数。集成度与发现性别名散落在配置文件里难以管理和发现。而一个设计良好的“技能库”项目会像软件包一样提供清晰的分类、描述、安装和更新机制。hermesnest/fish-skill的目标就是建立这样一个生态让你能像apt search一样搜索和发现有用的命令行技巧。交互与用户体验技能可以充分利用 Fish 的特性提供丰富的自动补全。当你输入mygit skill然后按 Tab它可以动态补全可用的子命令或参数选项这是简单别名无法实现的。可维护与可分享独立的函数文件易于版本控制如 Git也易于通过仓库分发。你可以将自己的技能提交到hermesnest/fish-skill也可以从别人的提交中汲取灵感形成正向循环。3. 实战从零开始构建与使用你的第一个技能理解了理念我们动手实操。假设我们想创建一个名为mkcd的技能功能是“创建一个目录并立即进入该目录”。这虽然简单但能完整走通创建、安装、使用的流程。3.1 技能创建编写 Fish 函数首先在 Fish 的函数目录下创建对应的文件。函数目录通常是~/.config/fish/functions/。如果不存在可以创建它。# 确保函数目录存在 mkdir -p ~/.config/fish/functions然后用你喜欢的编辑器创建文件~/.config/fish/functions/mkcd.fishfunction mkcd -d 创建目录并进入 # 检查是否提供了参数目录名 if test (count $argv) -eq 0 echo 用法: mkcd 目录名 return 1 # 非零返回值表示错误 end set dir_name $argv[1] # 尝试创建目录-p 参数确保可以创建多层目录 if mkdir -p $dir_name # 创建成功切换进入 cd $dir_name echo 已创建并进入目录: $PWD else # 创建失败报错 echo 创建目录 $dir_name 失败 return 1 end end代码解析与技巧function mkcd -d “...”定义函数名和描述。-d后面的描述会在使用functions -D mkcd时显示有助于文档化。(count $argv)Fish 中获取参数个数的方式。$argv是一个包含所有参数的列表。set dir_name $argv[1]将第一个参数赋值给变量dir_name。Fish 变量不需要$符号来赋值。if mkdir -p $dir_name这里直接以命令的执行结果退出状态码作为条件。如果mkdir成功返回0则执行then后的块。$PWDFish 中表示当前工作目录的环境变量。3.2 技能安装让函数立即生效在 Fish 中当你把函数文件放在~/.config/fish/functions/目录下并以.fish结尾时函数是自动加载的。你不需要source它。只要打开一个新的 Fish shell或者在当前会话中直接输入函数名Fish 就会自动读取并加载该函数。现在你可以直接测试mkcd my_new_project如果一切正常你会看到输出“已创建并进入目录: /path/to/your/my_new_project”并且当前目录已经切换。实操心得这是 Fish 最方便的特性之一——函数即文件文件即函数。管理起来非常清爽。如果你想临时禁用某个技能只需将对应的.fish文件移出functions目录或重命名如加.bak后缀即可无需修改主配置文件。3.3 技能增强添加自动补全一个专业的技能应该提供良好的命令行补全体验。我们为mkcd添加一个简单的补全定义。创建补全文件~/.config/fish/completions/mkcd.fishcomplete -c mkcd -f -a (__fish_complete_directories) -d 创建并进入此目录代码解析-c mkcd指定这个补全规则是针对命令mkcd的。-f表示补全时不进行文件名补全因为我们后面有自己的逻辑。-a (__fish_complete_directories)-a指定补全的参数列表。这里我们使用 Fish 内置的__fish_complete_directories函数来生成目录名作为补全建议。这是一个非常实用的技巧可以复用 shell 自身的智能。-d “...”补全项的描述。保存后重新打开终端或运行source ~/.config/fish/config.fish虽然函数是自动加载但补全文件的加载可能需要触发一下。现在输入mkcd注意后面有个空格然后按 Tab你会看到当前目录下的子目录作为补全建议出现。4. 技能库的架构与管理思路个人技能的管理相对简单但hermesnest/fish-skill作为一个共享仓库需要考虑更复杂的架构。这里我们探讨一个可行的实现方案。4.1 技能包的标准化结构为了让技能易于分发和安装每个技能应该是一个独立的“包”。一个标准的技能包目录结构可能如下skill-git-switch/ ├── README.md # 技能说明、用法、示例 ├── functions/ │ └── gsw.fish # 主函数文件 ├── completions/ │ └── gsw.fish # 自动补全文件 └── conf.d/ └── gsw_env.fish # 可选环境变量配置functions/核心存放技能函数文件。文件名即命令名。completions/存放补全定义文件提升用户体验。conf.d/可选用于设置该技能依赖的环境变量。Fish 会自动加载~/.config/fish/conf.d/目录下所有.fish文件。README.md至关重要应包含描述、安装方法、使用示例、参数说明、依赖项等。4.2 安装管理器手动 vs. 自动化对于终端用户来说安装技能应该尽可能简单。理想状态是有一个像npm或pip那样的包管理器。但在项目初期我们可以设计几种方式方案一Git Clone 符号链接手动但清晰用户将整个技能库克隆到本地然后通过脚本或手动方式将特定技能的functions/和completions/下的文件软链接到对应的~/.config/fish/目录下。优点结构清晰技能更新后进入仓库目录git pull即可更新所有技能。缺点需要用户手动运行链接脚本多技能管理时稍显繁琐。方案二每个技能独立仓库 安装脚本每个技能都是一个独立的 Git 仓库。技能包内自带一个install.fish脚本。用户下载后运行该脚本自动完成文件复制或链接。优点技能间完全解耦安装卸载灵活。缺点技能分散不便于集中发现和浏览。方案三中央仓库 元数据索引 安装工具进阶这是最理想的模式。一个中央仓库如hermesnest/fish-skill不直接存放技能代码而是存放一个index.fish或skills.yaml文件里面记录了所有可用技能的元数据名称、描述、Git地址、作者等。然后开发一个类似于fisherFish 的插件管理器的专用工具例如叫skillman。 用户可以通过skillman search搜索技能通过skillman install skill-name安装。安装工具会根据元数据从技能的独立 Git 地址拉取代码并放置到正确位置。优点体验最佳接近现代包管理器。缺点实现复杂度最高需要维护工具和元数据索引。对于hermesnest/fish-skill项目可以从方案一开始逐步向方案三演进。初期提供一个统一的安装脚本install.fish它读取一个清单文件为用户安装所有或选定的技能。4.3 版本控制与依赖管理技能本身可能会有版本迭代。简单的技能可能不需要考虑依赖。但复杂的技能可能依赖其他技能或者外部命令行工具如fzf,jq,fd等。版本可以通过 Git Tag 来管理技能版本。安装工具可以支持指定版本号安装。依赖在技能的README.md或一个专门的metadata.fish文件中声明依赖。安装工具在安装前检查依赖是否满足。例如# 在技能包内声明 set -l dependencies fzf jq for dep in $dependencies if not command -q $dep echo “错误: 需要命令 $dep请先安装。” return 1 end end5. 高级技能案例剖析一个实用的 Git 工作流增强技能让我们设计一个更复杂、更实用的技能展示“技能”如何真正提升效率。这个技能叫gsw(Git Smart Switch)目标智能地切换或创建 Git 分支。痛点日常开发中我们经常需要基于某个 issue 或 ticket 创建新分支命名规则可能是feature/ISSUE-123-add-login。通常步骤是git fetch origin-git checkout -b feature/ISSUE-123-add-login。如果分支已存在远端则需要git checkout --track origin/feature/...。这个过程需要手动拼接分支名并判断分支是否存在。技能目标gsw ISSUE-123-add-login自动以feature/为前缀。先检查本地是否存在feature/ISSUE-123-add-login存在则切换。若本地不存在检查远程origin是否存在存在则拉取并切换建立跟踪。若都不存在则在当前main或master分支的基础上创建新分支并切换。实现代码 (~/.config/fish/functions/gsw.fish)function gsw -d 智能切换或创建Git分支 # 检查参数 if test (count $argv) -eq 0 echo 用法: gsw 分支名或issue号 echo 示例: gsw 123-add-login # 会操作分支 feature/123-add-login return 1 end set branch_input $argv[1] set full_branch_name feature/$branch_input echo 目标分支: $full_branch_name # 1. 检查是否已在目标分支 set current_branch (git branch --show-current 2/dev/null) if test $current_branch $full_branch_name echo 已经在分支 $full_branch_name 上。 return 0 end # 2. 检查本地是否存在 if git show-ref --verify --quiet refs/heads/$full_branch_name echo 找到本地分支正在切换... git checkout $full_branch_name return $status end # 3. 检查远程是否存在 (假设远程名为 origin) git fetch origin --quiet 2/dev/null # 安静地获取最新信息 if git show-ref --verify --quiet refs/remotes/origin/$full_branch_name echo 找到远程分支正在跟踪并切换... git checkout -t origin/$full_branch_name return $status end # 4. 本地和远程都不存在创建新分支 echo 分支不存在正在从 main/master 创建... # 尝试基于 main 或 master 创建 if git show-ref --verify --quiet refs/heads/main git checkout -b $full_branch_name main else if git show-ref --verify --quiet refs/heads/master git checkout -b $full_branch_name master else echo 错误未找到 main 或 master 分支作为基准。 return 1 end echo 已创建并切换到新分支: $full_branch_name end配套补全 (~/.config/fish/completions/gsw.fish) 我们可以让补全建议显示已有的远程feature/分支。complete -c gsw -f -a (git branch -r | grep origin/feature/ | sed s|origin/feature/|| | sort -u) -d 智能切换Git功能分支使用示例与效果# 场景1分支已存在远程 $ gsw 456-refactor-ui 目标分支: feature/456-refactor-ui 找到远程分支正在跟踪并切换... 分支 feature/456-refactor-ui 设置为跟踪来自 origin 的远程分支 feature/456-refactor-ui。 切换到一个新分支 feature/456-refactor-ui # 场景2全新分支 $ gsw 789-fix-bug 目标分支: feature/789-fix-bug 分支不存在正在从 main/master 创建... 切换到一个新分支 feature/789-fix-bug 已创建并切换到新分支: feature/789-fix-bug这个技能将原本需要多次命令和手动判断的过程压缩成一条直观的命令并且通过补全还能快速选择已有分支效率提升立竿见影。6. 技能开发的最佳实践与避坑指南在创建和分享技能时遵循一些最佳实践能让你的技能更健壮、更友好。6.1 命名规范与作用域命名唯一且具描述性技能命令名应避免与系统已有命令或常用工具冲突。像gsw(Git Smart Switch) 就比一个笼统的gb(git branch) 要好。可以使用前缀如用项目或作者前缀hn_代表 hermesnest但可能会增加输入负担需权衡。作用域最小化技能函数内部使用set -l(local) 来定义局部变量避免污染全局环境。例如set -l local_var value。谨慎修改全局变量如果技能需要设置环境变量最好通过set -gx在函数内设置全局变量并考虑在conf.d/文件中设置或者在函数开始时检查是否已设置。6.2 健壮性错误处理与输入验证这是区分业余脚本和专业技能的关键。检查命令依赖在函数开头使用command -v或 Fish 的command -q检查所需的外部命令是否存在。if not command -q git echo 错误: git 命令未找到请先安装 Git。 return 127 # 命令未找到的标准退出码 end验证参数如前面的例子检查$argv的数量和内容是否符合预期。处理命令失败重要的子命令执行后检查$status上一条命令的退出状态码。git checkout $some_branch if test $status -ne 0 echo 切换分支失败 return $status end提供清晰的错误信息告诉用户哪里出错了以及可能的原因或解决方法。6.3 性能考量避免在提示符Prompt函数中执行慢操作如果你创建了一个用于美化提示符的技能不要在每次渲染提示符时都执行git status或调用网络请求。应该使用异步机制或者缓存结果。使用内置命令和高效工具在 Fish 脚本中尽量使用 Fish 的内置命令如string,path相关命令它们通常比调用外部命令sed,awk更快。6.4 文档与示例一个没有文档的技能是不完整的。README.md应至少包含功能描述一句话说清楚这个技能是干什么的。安装方法明确的步骤。使用方法详细的命令语法、参数说明、选项列表。示例多个从简单到复杂的使用示例这是最有价值的部分。依赖项需要提前安装的工具或其它技能。常见问题记录已知问题和解决方法。7. 技能生态的想象与扩展方向hermesnest/fish-skill项目如果成功其价值远不止于收集几个好用的函数。它可以演化成一个活跃的社区和一套提升生产力的方法论。1. 技能分类与标签系统技能可以按用途分类如git所有 Git 相关增强技能。docker容器管理快捷操作。system系统监控、进程管理。productivity通用效率工具如快速笔记、时间记录。cloudAWS CLI、kubectl 等云服务工具的快捷封装。用户可以根据标签筛选和发现需要的技能。2. 技能组合与管道Fish 优秀的管道Pipe支持使得技能可以像乐高一样组合。例如一个列出当前目录下所有node_modules目录并计算总大小的技能可以和一个交互式选择删除的技能组合使用实现安全清理。# 假设有 find-node-modules 和 interactive-rm 两个技能 find-node-modules | interactive-rm3. 交互式技能使用 fzf 等模糊查找器结合fzf这类工具可以创建出极其强大的交互式技能。例如一个交互式切换 Kubernetes 上下文和命名空间的技能或者一个交互式搜索并执行历史命令的技能。这能将命令行从“记忆命令”转变为“选择操作”大幅降低认知负荷。4. 配置同步与团队共享个人可以将自己精选的技能列表导出为一个清单文件如my-skills.lst。在新环境中通过项目提供的工具一键安装所有技能快速复现高效的工作环境。在团队内部可以维护一个私有的技能仓库共享团队内部的工作流和最佳实践统一开发环境提升协作效率。5. 技能质量评级与安全审核对于公共仓库需要建立简单的审核或评级机制。鼓励用户为有用的技能点赞Star对技能代码进行安全审查避免恶意代码确保共享生态的健康。8. 常见问题与故障排除实录在实际使用和开发技能的过程中你可能会遇到以下问题8.1 技能安装后不生效检查文件位置确保.fish文件放在了正确的~/.config/fish/functions/目录下并且文件名与函数名一致mkcd.fish对应function mkcd。检查文件权限确保文件是可读的。重新启动 Shell 或重新加载配置虽然 Fish 会自动加载但有时可能需要新开一个终端标签页或者执行exec fish重新启动当前 Shell 会话。也可以尝试source ~/.config/fish/config.fish。检查语法错误在函数文件中可能存在语法错误导致加载失败。可以通过fish -n /path/to/your/function.fish来检查语法。8.2 自动补全不工作补全文件位置补全文件应放在~/.config/fish/completions/目录同样以.fish结尾并且文件名通常与命令名一致mkcd.fish。补全脚本语法检查补全脚本的语法特别是complete命令的参数是否正确。可以使用complete -c your_command查看当前已注册的补全规则。补全函数未定义如果你的补全规则依赖于一个自定义的 Fish 函数如__fish_your_command_complete确保那个函数已经被定义和加载。8.3 技能函数与系统命令冲突使用type命令检查输入type your_skill_name。Fish 会告诉你这个命令是函数、内建命令还是外部命令。如果它显示为“函数”并且路径是你的函数文件说明加载成功。如果被其他同名命令覆盖你会看到不同的来源。使用完整路径或别名如果确实有冲突又不想重命名自己的技能可以考虑给技能起一个别名或者在函数内部调用系统命令时使用完整路径如/bin/ls。8.4 技能执行慢分析性能瓶颈在函数开头和结尾使用date命令打印时间戳或者使用 Fish 的time命令time your_skill来定位耗时操作。优化外部命令调用减少在循环中调用外部命令的次数。例如如果需要处理git log的输出尽量用一次git log获取所有数据然后用 Fish 内置的字符串处理命令来操作而不是每处理一行就调用一次awk。延迟加载对于非常重、但不一定每次会话都用的技能可以考虑将其改为“按需加载”。即先定义一个空壳函数当第一次调用时才去source真正的实现。但这会增加复杂度。8.5 如何卸载或禁用某个技能直接删除文件最彻底的方法是从~/.config/fish/functions/和~/.config/fish/completions/目录中删除对应的.fish文件。移动文件将文件移动到其他目录如~/backup_fish_functions/以备不时之需。在函数内返回如果不方便删除文件可以在函数体的第一行直接写return这样函数被调用时会立即退出不执行任何操作。但这只是一种临时禁用手段。我个人在维护自己的技能库时习惯用一个 Git 仓库来管理~/.config/fish目录下的自定义内容。这样所有的技能、配置都在版本控制之下换电脑时直接克隆仓库并创建符号链接即可技能的管理和备份问题也一并解决了。这或许是实践hermesnest/fish-skill理念的终极个人方案。