ticket插件系统完全指南:5行bash为tk新增一条自定义命令

原创2026-10-24 18:39:081,813 阅读

ticket插件系统完全指南:5行bash为tk新增一条自定义命令

tk 是 ticket 项目提供的核心命令——一个仅由单个 bash 脚本构成的 git 原生工单(ticket)追踪工具。它的插件系统设计得极其简单:只要在系统 PATH 中放一个名为 tk-<命令名> 的可执行文件,tk 就会自动把它识别为新命令。本文将带你从零理解 ticket 插件系统的运行机制,并用 5 行 bash 为你的 tk 增加一条专属自定义命令。

一、先认识一下 ticket:零依赖的工单追踪器 🎫

在讲插件之前,先快速过一下 ticket 是什么:

  • 工单以 Markdown 文件 + YAML frontmatter 的形式存放在项目的 .tickets/ 目录中
  • 文件名即工单 ID(如 nw-5c46),支持依赖图、优先级、状态流转
  • 核心命令 tk 只有一个 ticket 脚本(约 1400 行 bash),无数据库、无守护进程
  • 依赖图、tk ready、tk blocked 等复杂功能全部内置

这种"一切皆文件 + 单一脚本"的设计,正是它敢把插件系统做成"PATH 发现机制"的前提。

二、插件系统的运行机制:PATH 即插件目录 🔍

ticket 的插件发现规则只有一条:可执行文件,命名规范为 tk-<cmd> 或 ticket-<cmd>,放在 PATH 能找到的任何位置。

当你运行 tk <cmd> 时,核心脚本的调度逻辑(见 ticket)会按以下流程处理:

  1. 若命令是 super,直接跳过插件,执行内置命令
  2. 否则依次探测 tk-<cmd> 和 ticket-<cmd> 是否存在于 PATH
  3. 找到后 exec 该插件,并把上下文通过环境变量传给插件

两个重要的命名约定:

规则 说明
前缀优先级 tk- 前缀优先于 ticket- 前缀(两者同名时 tk- 生效)
可覆盖内置命令 插件命令优先于内置命令匹配,意味着你可以"劫持"内置命令的行为

这些行为都有对应的 BDD 测试用例保障,可参考 features/ticket_plugins.feature。

插件自动获得的两个环境变量

tk 在 exec 插件前会导出(见 ticket):

  • TICKETS_DIR —— .tickets/ 目录的绝对路径(会自动向上搜索父目录,未找到时可能为空)
  • TK_SCRIPT —— tk 脚本的绝对路径,用于插件回调内置命令

💡 小提示:插件目录不存在时,tk 会直接报错 Error: tickets directory '$TICKETS_DIR' does not exist 并退出,因此插件里读 $TICKETS_DIR/*.md 前可以再加一层判空。

三、5行bash:为你的 tk 新增一条自定义命令 ⚡

下面这条命令会为 tk 新增 hello 子命令——总共 5 行:

cat > ~/.local/bin/tk-hello <<'EOF'
#!/bin/bash
# tk-plugin: Say hello
echo "Hello from plugin!"
EOF
chmod +x ~/.local/bin/tk-hello

然后直接体验:

tk hello        # 输出: Hello from plugin!
tk help         # "hello" 会出现在 Plugins 列表中

就这么简单。几点细节:

  • 文件名 tk-hello 决定了子命令名是 hello,去掉前缀即是
  • 第 2 行 # tk-plugin: Say hello 是描述元数据,tk help 会把它显示在命令旁边
  • 插件会原样接收所有参数,例如 tk echo foo bar 会把 foo bar 传给 tk-echo 脚本
  • 想放在项目级也可以:把插件放到项目某个目录并加进 PATH,团队共享同一个命令集

四、进阶:让插件读写工单数据 📝

只打印字符串的插件太弱了,真正好用的插件会操作 .tickets/ 里的工单文件。官方插件 plugins/ticket-edit 是一个绝佳范本(仅 34 行),它实现了 tk edit <id>——用 $EDITOR 打开工单文件,核心逻辑只有三步:

  1. 用精确 ID 拼出文件路径 $TICKETS_DIR/${id}.md
  2. 精确找不到时用 find 做部分匹配(与 tk 内置命令一致的模糊 ID 体验)
  3. 匹配到多个则报错,0 个也报错,恰好 1 个才打开

另一个值得看的是 plugins/ticket-query:它用一段 awk 把 $TICKETS_DIR 下所有 Markdown 工单的 frontmatter 转成 JSON,再交给 jq 过滤。这说明插件不只能"包装"内置命令,还能直接解析工单文件做全新的查询维度。

调用内置命令:$TK_SCRIPT super <cmd>

如果你想"先跑内置逻辑、再做增强"(比如创建工单时强制加默认参数),用 super 绕过插件层、直调内置命令,避免无限递归:

#!/usr/bin/env bash
# tk-plugin: wrapper that creates tickets with defaults
# tk-plugin-version: 1.0.0

"$TK_SCRIPT" super create "$@" --type task --priority 1

把它存为 tk-create,tk create 就会走你的包装版本;想临时回到原生行为,用 tk super create ... 即可。官方文档把这个用法写在 plugins/README.md 中。

五、写好插件元数据,让 tk help 更专业 📖

tk 生成插件列表的方式(见 _list_plugins,ticket):

  • 脚本类插件:读取文件前 10 行,找第一处 # tk-plugin: 注释作为描述
  • 二进制插件:执行 --tk-describe 参数,期望输出 tk-plugin: description
  • 找不到描述时显示 (no description)

所以推荐的插件文件头格式是:

#!/usr/bin/env bash
# tk-plugin: sync tickets with GitHub issues
# tk-plugin-version: 1.0.0

set -euo pipefail
# 你的实现...
  • tk-plugin-version 不是强制项,但官方插件都带了,方便升级管理
  • set -euo pipefail 是官方插件的统一防御写法,建议照抄
  • 描述信息建议直接写用户视角的功能(如 "Open ticket in $EDITOR"),因为 tk help 里别人看到的就是它

六、官方插件与打包分发 📦

仓库 plugins/ 目录下收录了 5 个官方插件,每个都是上面这套规则的活教材:

插件 文件 功能
edit plugins/ticket-edit 用 $EDITOR 打开工单
list / ls plugins/ticket-list 带 --status / -a / -T 过滤的列表
query plugins/ticket-query 输出 JSON,支持 jq 过滤表达式
migrate-beads plugins/ticket-migrate-beads 从 beads 的 .beads/issues.jsonl 导入

它们的打包方式也很干净:

安装时可以按需组合,例如只装核心加单个插件:

brew install ticket-core ticket-query

七、发布你的插件到仓库的 4 个步骤 🚀

按 plugins/README.md 的流程,向 extras 包贡献插件只需:

  1. 创建 plugins/ticket-<name>,带上 # tk-plugin: 描述注释
  2. chmod +x plugins/ticket-<name>
  3. 若希望进入 extras 包,把名字加入 pkg/extras.txt
  4. 提交并打 release tag,发布脚本会自动打包

八、常见问题速查 ❓

Q:为什么 tk mycmd 不生效? 按顺序排查:① 文件名是否是 tk-mycmd 或 ticket-mycmd;② command -v tk-mycmd 能否找到它;③ 文件有没有可执行权限;④ 是否被 tk-super 之外的同名插件覆盖(tk- 优先)。

Q:插件里能直接用内置命令吗? 能,但要用 $TK_SCRIPT super <cmd>。直接调 tk <cmd> 可能再次命中插件层造成递归。

Q:没有 .tickets/ 目录时插件会怎样? tk 不会导出 TICKETS_DIR,插件里拿到的是空值。建议像官方插件一样 2>/dev/null 兜底,或提前给出友好提示。

Q:能否覆盖内置命令? 可以,插件命令优先匹配。例如做一个 tk-ls 就能替换内置 ls 的输出格式——这正是官方 plugins/ticket-ls 的做法。

写在最后

ticket 的插件系统把 Unix 哲学贯彻到了底:没有注册表、没有配置项、没有加载顺序,一个可执行文件就是一条新命令。从本文的 5 行 tk-hello,到 34 行的 ticket-edit,再到支持 jq 过滤的 ticket-query,难度曲线完全平滑。今天就可以给自己写一条常用命令,让 tk 长成你团队专属的样子。🛠️

登录后查看全文
ticket