Back to Details

ticket

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ticket Management with tk

使用tk进行工单管理

Installation

安装

bash
go install github.com/wedow/ticket/cmd/tk@latest
Tickets stored as markdown in 
.tickets/
. Works from any subdirectory.
bash
go install github.com/wedow/ticket/cmd/tk@latest
工单以Markdown格式存储在
.tickets/
目录下，可在任意子目录中使用。

What Makes a Complete Ticket

什么是完整的工单

A ticket MUST have ALL of:
  1. Clear Acceptance Criteria — Specific, testable "done" conditions
    • ✅ "User can login with email/password and receives JWT"
    • ❌ "Login works"
  2. Clear Requirements — What exactly to build
    • ✅ "POST /api/login accepts {email, password}, returns {token, expiresAt}"
    • ❌ "Add login endpoint"
  3. Design/UI Info (if applicable) — Visual specs, layouts
    • ✅ "Login form: email input, password input, submit button. Error in red below form."
  4. Atomic + Actionable — One focused task, can start immediately
    • ✅ "Implement password reset email"
    • ❌ "Improve auth system"
  5. Testing Requirements — What to test
    • ✅ "Test: valid login→200+token, invalid→401, missing fields→400"
Ask yourself: Can someone implement this without clarifying questions?
一份完整的工单必须包含以下所有内容：
  1. 清晰的验收标准 — 具体、可测试的“完成”条件
    • ✅ “用户可通过邮箱/密码登录并获取JWT”
    • ❌ “登录功能可用”
  2. 明确的需求 — 具体要开发的内容
    • ✅ “POST /api/login接口接收{email, password}参数，返回{token, expiresAt}”
    • ❌ “添加登录接口”
  3. 设计/UI信息（如适用）— 视觉规范、布局
    • ✅ “登录表单：邮箱输入框、密码输入框、提交按钮。表单下方显示红色错误提示。”
  4. 原子性+可执行性 — 聚焦单个任务，可立即启动
    • ✅ “实现密码重置邮件功能”
    • ❌ “改进认证系统”
  5. 测试要求 — 需要测试的内容
    • ✅ “测试场景：有效登录→返回200状态码+token，无效凭证→401，字段缺失→400”
自问： 其他人是否无需进一步询问即可完成该任务？

Quick Reference

快速参考

CommandPurpose
tk create "title"
Create ticket
tk ls
List all
tk ready
Ready to work (deps resolved)
tk blocked
Waiting on deps
tk show <id>
View details
tk edit <id>
Open in $EDITOR
tk start/close/reopen <id>
Change status
tk dep <id> <dep-id>
Add dependency
tk dep tree <id>
Show dep tree
tk undep <id> <dep-id>
Remove dep
tk link <id> <id>...
Link related
tk add-note <id> "text"
Append note
Supports partial ID matching: 
tk show 5c4
matches 
nw-5c46
.
命令用途
tk create "title"
创建工单
tk ls
列出所有工单
tk ready
查看可开始的任务（依赖已解决）
tk blocked
标记任务为阻塞（等待依赖）
tk show <id>
查看工单详情
tk edit <id>
在$EDITOR中打开编辑
tk start/close/reopen <id>
修改工单状态
tk dep <id> <dep-id>
添加依赖关系
tk dep tree <id>
查看依赖树
tk undep <id> <dep-id>
移除依赖关系
tk link <id> <id>...
关联相关工单
tk add-note <id> "text"
添加备注
支持ID部分匹配：
tk show 5c4
可匹配 
nw-5c46
。

Creating Complete Tickets

创建完整工单

bash
tk create "Implement JWT login" -t feature -p 1 \
  --description "POST /api/login validates creds, returns JWT with 24h expiry" \
  --acceptance "- Valid creds → 200 + {token, expiresAt}
- Invalid password → 401
- Missing fields → 400
- Token expires in 24h" \
  --tags backend,auth
Options: 
-t
type (bug/feature/task/epic/chore), 
-p
priority (0-4), 
-d
description, 
--acceptance
, 
--design
, 
-a
assignee, 
--parent
, 
--tags
bash
tk create "Implement JWT login" -t feature -p 1 \
  --description "POST /api/login validates creds, returns JWT with 24h expiry" \
  --acceptance "- Valid creds → 200 + {token, expiresAt}
- Invalid password → 401
- Missing fields → 400
- Token expires in 24h" \
  --tags backend,auth
可选参数：
-t
类型（bug/feature/task/epic/chore），
-p
优先级（0-4），
-d
描述，
--acceptance
验收标准，
--design
设计信息，
-a
经办人，
--parent
父工单，
--tags
标签

Dependencies

依赖管理

bash
tk dep ticket-a ticket-b      # a depends on b
tk dep tree ticket-a          # view tree
tk undep ticket-a ticket-b    # remove
tk dep cycle                  # find cycles
bash
tk dep ticket-a ticket-b      # 工单a依赖工单b
tk dep tree ticket-a          # 查看依赖树
tk undep ticket-a ticket-b    # 移除依赖
tk dep cycle                  # 查找循环依赖

Workflow

工作流示例

bash
tk create "Auth system" -t epic                    # auth-7f3a
tk create "Design schema" --parent auth-7f3a       # sch-2b1c
tk create "Login endpoint" --parent auth-7f3a \
  --acceptance "POST /login returns JWT"           # log-9d4e

tk dep log-9d4e sch-2b1c   # login depends on schema
tk ready                   # shows sch-2b1c
tk close sch-2b1c
tk ready                   # now shows log-9d4e
bash
tk create "Auth system" -t epic                    # 生成auth-7f3a
tk create "Design schema" --parent auth-7f3a       # 生成sch-2b1c
tk create "Login endpoint" --parent auth-7f3a \
  --acceptance "POST /login returns JWT"           # 生成log-9d4e

tk dep log-9d4e sch-2b1c   # 登录工单依赖 schema 工单
tk ready                   # 显示可处理的sch-2b1c
tk close sch-2b1c
tk ready                   # 现在显示可处理的log-9d4e