ticket插件系统完全指南:5行bash为tk新增一条自定义命令
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)会按以下流程处理:
- 若命令是
super,直接跳过插件,执行内置命令 - 否则依次探测
tk-<cmd>和ticket-<cmd>是否存在于 PATH - 找到后
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 打开工单文件,核心逻辑只有三步:
- 用精确 ID 拼出文件路径
$TICKETS_DIR/${id}.md - 精确找不到时用
find做部分匹配(与tk内置命令一致的模糊 ID 体验) - 匹配到多个则报错,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 导入 |
它们的打包方式也很干净:
- 插件名登记在 pkg/extras.txt,一行一个
- 发布时自动拆成 Homebrew / AUR 元包:
ticket-core(纯核心)、ticket-extras(精选插件集)、ticket(core + extras 全家桶) - 对应构建脚本见 scripts/publish-homebrew.sh 和 scripts/publish-aur.sh
安装时可以按需组合,例如只装核心加单个插件:
brew install ticket-core ticket-query
七、发布你的插件到仓库的 4 个步骤 🚀
按 plugins/README.md 的流程,向 extras 包贡献插件只需:
- 创建
plugins/ticket-<name>,带上# tk-plugin:描述注释 chmod +x plugins/ticket-<name>- 若希望进入 extras 包,把名字加入 pkg/extras.txt
- 提交并打 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 长成你团队专属的样子。🛠️