CRITICAL — Before starting, you MUST first use the Read tool to read ../zentao-shared/SKILL.md, which contains authentication, environment variables, error handling, and status value definitions.
Severity Assessment Tips: ZenTao Bug severity is graded 1-5, where 1 is the most severe (system crash, data loss) and 5 is the lowest (feature suggestion). When creating a Bug, the correct level should be selected based on the actual situation:
- severity=1: System crash, feature completely unavailable, data loss
- severity=2: Major feature failure, with a clear workaround
- severity=3: Ordinary defect, with an alternative solution
- severity=4: Minor issue, UI/UX related
- severity=5: Feature suggestion/optimization item
Status and Resolution: A Bug has three main statuses
active(active) /resolved(resolved) /closed(closed), along with the corresponding resolution. A Bug in resolved status needs a resolution specified (fixed/duplicate/notrepro/wonfix/bysdesign), and closed status requires being resolved first before closing.Assignment and Transition: After a Bug is created, it can be assigned to a developer via
bug update. When the Bug is fixed, the status becomes resolved; when the Bug is confirmed and closed, the status becomes closed.Friendly Output: When outputting Bug details, it is recommended to also output the Bug's URL link (ZenTao web UI address), so users can click to view it directly.
Bug Lifecycle
active (激活) ──[修复]──> resolved (已解决) ──[确认]──> closed (已关闭)
│ │
│<────[重打开]─────────────┘
│
└──[转为设计/需求]──> changed (已变更)
Status Transition Rules
| Current Status | Can Transition To | Operation |
|---|---|---|
| active | resolved | Fix completed, set resolution |
| active | closed | Close directly (wonfix/bysdesign, etc.) |
| resolved | active | Reopen Bug |
| resolved | closed | Confirm fix, close Bug |
| closed | active | Reactivate |
Severity Levels
| Level | Name | Description | Example |
|---|---|---|---|
| 1 | Critical | System crash, data loss, feature completely unavailable | Page won't open, critical data lost |
| 2 | Major | Major feature failure, with a workaround | A core button does not respond when clicked |
| 3 | Normal | Ordinary defect, with an alternative solution | A non-critical feature is abnormal |
| 4 | Minor | Minor issue, UI/UX related | Text is not fully displayed |
| 5 | Wishlist | Feature suggestion/optimization item | Hope to add a certain feature |
Commands
bug list— List bugs for a productbug get— Get bug detailsbug create— Create a new bugbug update— Update bug fieldsbug resolve— Resolve a bugbug confirm— Confirm a bugbug close— Close a bugbug activate— Activate a bugbug delete— Delete a bug
Common Use Cases
Scenario 1: Query all active Bugs of a product
# 按产品 ID 列出所有激活状态的 Bug
zentao-cli bug list --product 1 --status active
Scenario 2: Create a new Bug
# 创建严重性为 1 的紧急 Bug
zentao-cli bug create --title "用户登录页面崩溃" --product 1 --severity 1 --pri 1
# 创建带有详细复现步骤的 Bug
zentao-cli bug create \
--title "上传头像失败" \
--product 1 \
--severity 2 \
--pri 2 \
--steps "1. 进入个人资料页\n2. 点击上传头像\n3. 选择图片后无响应"
Scenario 3: Update Bug status and resolution
# 标记 Bug 为已修复
zentao-cli bug update 123 --status resolved --resolution fixed
# 指派给开发人员
zentao-cli bug update 123 --assigned-to developer-name
# 重打开 Bug
zentao-cli bug update 123 --status active
Scenario 4: Filter Bugs by assignee
# 查看指定人员的待办 Bug
zentao-cli bug list --product 1 --assigned-to developer-name
Error Handling
Common Errors
| Error Code | Description | Solution |
|---|---|---|
ZEN_AUTH_FAILED |
Token is invalid or expired | Check whether the ZENTAO_TOKEN configuration is correct |
ZEN_NOT_FOUND |
Bug does not exist | Check whether the Bug ID is correct |
ZEN_CONFIG_INVALID |
Invalid configuration | Verify ZENTAO_URL and ZENTAO_TOKEN |
ZEN_API_ERROR |
ZenTao API returned an error | Check the server status or try again later |
ZEN_PARAM_MISSING |
Missing required parameter | Ensure all required parameters are provided |
Error handling example
# 遇到 auth 错误时检查认证状态
zentao-cli auth status
# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN
Examples
# 列出产品 1 下的所有激活状态的 Bug
zentao-cli bug list --product 1 --status active
# 创建 Bug
zentao-cli bug create --title "用户登录页面崩溃" --product 1 --severity 1 --pri 1
# 标记 Bug 为已修复
zentao-cli bug update 123 --status resolved --resolution fixed
# 查看指定人员的待办 Bug
zentao-cli bug list --product 1 --assigned-to developer-name
Gotchas
-
severity vs pri: severity indicates the defect severity level (1-5), and pri indicates the priority (1-4). The two concepts are different, and both need to be set separately when creating a Bug.
-
resolution depends on status: resolution only needs to be set when status=resolved. fixed/duplicate/notrepro/wonfix/bysdesign are common resolutions.
-
The closed status cannot be entered directly: A Bug cannot change directly from active to closed; it must first be resolved and then closed. However, cases such as wonfix/bysdesign can be exceptions.
-
steps field format: For reproduction steps, it is recommended to use
\nto separate multiple lines, making them easier to read and parse. -
Associating requirements and projects: When creating a Bug, you can use
--storyand--projectto associate it with an existing requirement or project.