ticket列表查询速查表:按状态、负责人、标签筛选的10个实用命令示例
ticket列表查询速查表:按状态、负责人、标签筛选的10个实用命令示例
ticket 是一个用单个 Bash 脚本实现的、git 原生的工单跟踪工具,以 tk 命令为入口,所有工单都以带 YAML frontmatter 的 Markdown 文件存放在 .tickets/ 目录中。这篇 ticket 列表查询速查表整理了 10 个实用命令示例,覆盖按状态、负责人、标签筛选的全部场景,新手和 AI Agent 都能即查即用。
🚀 30 秒上手
ticket 是一个可移植的 bash 脚本,只依赖 coreutils,任何装了 bash 的 POSIX 系统都能开箱即用:
# macOS / Linux(Homebrew)
brew tap wedow/tools
brew install ticket
# Arch Linux(AUR)
yay -S ticket
安装后运行 tk help 即可查看完整命令列表。注意:ls/list/query 等列表查询命令由 ticket-extras 插件包提供,完整的 ticket 包已默认包含(plugins/README.md)。
📋 10 个实用命令示例
示例 1:查看全部工单 tk ls
最常用的"每日站会视图",ls 与 list 等价(plugins/ticket-list):
tk ls # 或 tk list
nw-5c46 [open] - Add SSE connection management
nw-9a2f [in_progress] - Refactor auth module <- [nw-5c46]
行尾的 <- [nw-5c46] 表示该工单还有未关闭的依赖,一眼就能看出"卡在谁手里"。
示例 2:按状态筛选 --status=
工单有三种状态:open、in_progress、closed(ticket):
tk ls --status=open # 所有待处理工单
tk ls --status=in_progress # 进行中的工单
tk ls --status=closed # 所有已关闭工单
示例 3:按负责人筛选 -a
查看某个人的全部待办(短参数 -a 或长参数 --assignee=):
tk ls -a alice
tk ls --assignee=alice
示例 4:按标签筛选 -T
创建工单时用 --tags ui,backend,urgent 打上的标签,可以精确匹配(plugins/ticket-ls):
tk ls -T backend # 后端相关
tk ls --tag=urgent # 紧急事项
示例 5:三个筛选条件组合使用
筛选条件是"与"的关系,可任意叠加,例如"找出 alice 负责的进行中紧急工单":
tk ls --status=in_progress -a alice -T urgent
示例 6:列出"可开工"工单 tk ready
ready 只列出状态为 open/in_progress 且所有依赖均已关闭的工单,并按优先级(P0 最高)排序(ticket):
tk ready # 按优先级 + ID 排序输出
tk ready -a alice # 只看 alice 的
tk ready -T backend # 只看后端标签
nw-5c46 [P1][open] - Add SSE connection management
nw-b21d [P2][in_progress] - Refactor auth module
示例 7:列出被阻塞的工单 tk blocked
与 ready 互补:列出 open/in_progress 且存在未关闭依赖的工单,行尾直接标出阻塞者(ticket):
tk blocked
tk blocked -T backend
nw-9a2f [P2][open] - Refactor auth module <- [nw-5c46]
示例 8:查看最近关闭的工单 tk closed
按文件修改时间倒序列出最近关闭的工单,默认 20 条,同样支持 -a/-T 筛选(ticket):
tk closed --limit=10 # 最近关闭的 10 条
tk closed --limit=5 -a alice
示例 9:JSON 格式查询 tk query
query 把所有工单导出为 JSONL(每行一个工单对象),并可内联传入一个 jq 过滤条件(需要 jq,plugins/ticket-query):
tk query # 导出全部工单 JSON
tk query '.status == "open"' # 筛选 open 状态
tk query '.assignee == "alice"' # 筛选负责人
示例 10:进阶 jq 过滤 + 二次处理
jq 表达式可以任意组合,还能再管道给 jq 做格式化输出(字段参考 features/ticket_query.feature):
tk query '.type == "bug" and .status == "open"' # 开放的 bug
tk query '.deps | length > 0' # 所有有依赖的工单
# 自己再管道处理:输出 id + 状态 + 优先级
tk query | jq -r '[.id, .status, .priority] | @tsv'
🧭 一张表速查
| # | 命令 | 用途 | 关键参数 |
|---|---|---|---|
| 1 | tk ls |
列出全部工单 | — |
| 2 | tk ls --status=open |
按状态筛选 | --status= |
| 3 | tk ls -a alice |
按负责人筛选 | -a / --assignee= |
| 4 | tk ls -T backend |
按标签筛选 | -T / --tag= |
| 5 | tk ls --status=in_progress -a alice -T urgent |
组合筛选 | 三者叠加 |
| 6 | tk ready |
依赖全部关闭、可开工 | -a、-T |
| 7 | tk blocked |
存在未关闭依赖、被阻塞 | -a、-T |
| 8 | tk closed --limit=10 |
最近关闭的工单 | --limit= |
| 9 | tk query '.status == "open"' |
JSON 导出 + jq 过滤 | jq 表达式 |
| 10 | tk query '.deps | length > 0' |
进阶 jq 组合条件 | jq 表达式 |
💡 常见问题与小技巧
- 报错
Error: no .tickets directory found:说明当前目录及上级目录都没有.tickets/。先运行tk create "标题"初始化,或用环境变量TICKETS_DIR手动指定目录。 query命令无反应:它依赖jq,请先安装 jq;ls/query属于 ticket-extras 插件包,请确认装的是完整ticket包。- 性能:列表命令用 awk 批量解析全部工单,有
rg(ripgrep)时会自动用它加速搜索,否则回退到grep。 - ID 支持模糊匹配:如
tk show 5c4可匹配nw-5c46,列表里看到截断的 ID 也能直接跳转详情。 - 测试用例:以上每条命令的行为都有对应的 BDD 测试覆盖,可阅读 features/ticket_listing.feature 和 features/ticket_query.feature 了解预期输出。
📌 建议把
tk ready放进终端别名(如alias mytodo='tk ready -a 你的名字'),每次开工前运行一次,就能快速聚焦"现在该做什么"。完整命令参考见 README.md 与核心脚本 ticket。