zt-devops-cli 0.2.4

DevOps 平台迭代管理 CLI

DevOps CLI

蓝鲸 DevOps（ZTN）平台迭代、任务、缺陷等能力的命令行工具。

打包

uv pip install --upgrade build twine
uv build
uv publish

安装

源码安装

pip install -e .

pip / pipx 安装

pipx install zt-devops-cli

使用

全局选项

根命令 zt-devops-cli 支持：

选项	说明
-p / --project	默认项目 ID；仅对子命令里 -p 为可选的命令生效，解析顺序为「子命令 -p → 根命令 -p → config.yaml 的 default_project」
-o / --output	json（默认）或 human；列表类在 human 下为表格，部分写操作在 human 下仅输出简短成功信息

注意（Click 解析）：若子命令将 -p / --project 标为必填（如 bug list、task list、bug create、缺陷流转等），则必须在该子命令后再写一遍 -p，根命令上的 -p 不会自动填入子命令参数。

示例（sprint list 的 -p 可选，可用根级 -p）：

zt-devops-cli -o human -p k64352 sprint list

示例（bug list 的 -p 为子命令必填，须写在 bug list 之后）：

zt-devops-cli -o human bug list -p b9f157 --num 1 --size 20

登录

首次或 cookie 失效时会走浏览器登录流程；成功后将 cookie 写入本地缓存。

zt-devops-cli login

需要弹出窗口手动登录时（无环境变量自动填表时）：

zt-devops-cli login --headed

无头自动登录依赖环境变量 ZT_SSO_USERNAME、ZT_SSO_PASSWORD（见 auth 模块说明）。

项目管理

zt-devops-cli project list

ZTeam 项目

zt-devops-cli zteam-project list --project f39507

迭代管理

迭代列表

zt-devops-cli sprint list --project k64352
# 或与根命令 -p 组合（本子命令 -p 可选）
zt-devops-cli -p k64352 sprint list

迭代提测列表

zt-devops-cli sprint test-list --project b9f157 \
  --search "BSC_V26.701.01" \
  --num 1 \
  --size 10

可选筛选：--result、--create-user、--create-time、--principal、--obj-id（均可重复传入）。

创建迭代

zt-devops-cli sprint create --project k64352 \
  --title "迭代名称" \
  --start-date 2026-04-04 \
  --end-date 2026-05-30 \
  --purpose "迭代目标"

日期可用简写：-s / --start-date、-e / --end-date。可选：--test-start、--test-end。

启用 / 删除 / 完成迭代

zt-devops-cli sprint start --project k64352 -i <sprint-id>
zt-devops-cli sprint delete --project k64352 -i <sprint-id>
zt-devops-cli sprint done --project k64352 -i <sprint-id>

-i 即 --sprint-id。delete / done 会交互确认。

任务管理

查询任务列表（TASK）

子命令上 -p 必填。另须 --start-date、--end-date。可选：--creator、--num、--size、--remember / --no-remember（默认 --no-remember）。

zt-devops-cli task list -p f39507 \
  --start-date 2026-04-01 \
  --end-date 2026-04-30 \
  --creator zt07905

创建任务（TASK）

子命令上 -p 必填。另须 -t / --title、--owner、--estimate-start、--estimate-end、--zteam-project-id（平台项目 ID 来自 project list，ZTeam 项目 ID 来自 zteam-project list）。

zt-devops-cli task create \
  -p "<project-id>" \
  --title "<任务标题>" \
  --owner zt07905 \
  --estimate-start 2026-04-01 \
  --estimate-end 2026-04-30 \
  --zteam-project-id "<zteam-project-id>"

可选：--model-type-id、--priority、--editor-type、--desc、--parent-id、--demand-classify、--origin-hours、--remain-hours；扩展字段使用 --field fieldId=value（可多次）。

缺陷管理

查询缺陷列表（BUG）

子命令上 -p 必填。与页面表格筛选相近。常用可选：--num、--size、--remember / --no-remember（默认 --no-remember）、--operator（逗号分隔多账号）、--zteam-project、--owner-field / --owner、--state（状态 ID，可先执行 bug get-states）、--creator、--create-date 或 --create-start + --create-end（二者须同时出现）。

zt-devops-cli bug list -p b9f157 \
  --num 1 \
  --size 20

查询缺陷「状态」可选项

zt-devops-cli bug get-states -p b9f157

默认 --all；若与页面不一致可尝试 --no-all。

查询缺陷「发现阶段」可选项

zt-devops-cli bug get-discovery-phases -p b9f157

默认 --no-all（与缺陷表 twBug 一致）。模板不同时可传 --field-id。若与页面不一致可试 --all。

查询缺陷「解决方法」可选项

zt-devops-cli bug get-solution-methods -p b9f157

默认 --no-all。可选 --field-id。

查询缺陷「类型」可选项

zt-devops-cli bug get-types -p b9f157

默认 --no-all。可选 --field-id。

创建缺陷（BUG）

对应 POST .../issue/{project}。--owner 同时写入经办人与缺陷责任人；迭代、ZTeam、严重程度、类型、发现阶段、解决方法等使用代码内固定 fieldId（与团队抓包一致）。若你们项目字段不同，需改源码中的 instance_values 映射。

选项	说明
-p / --project	项目 ID（子命令必填）
--zteam-project-id	ZTeam 项目 ID
--sprint-id	关联迭代 ID；可不关联时传空字符串 ""
-t / --title	标题
--severity / --type / --discovery-phase	与表单选项的 value 一致（非中文展示名）
--solution-method	可选；解决方法字段的 value
--owner	账号
--priority	默认 CENTRAL
--desc / --desc-editor-type	描述 HTML 与编辑器类型，默认带四段模板
--parent-id、--model-type-id、--demand-classify	可选或保持默认

zt-devops-cli bug create -p b9f157 \
  --zteam-project-id 15678224 \
  --sprint-id 3129a9cd7315457eb2963bfe19919e72 \
  -t "缺陷标题示例" \
  --owner zt07905 \
  --severity 9Clfj3I8fR \
  --type bgEHPFOjFt \
  --discovery-phase vENjmMhXMC

缺陷工作流（接受 / 已解决 / 已验证 / 关闭 / 重新打开 / 拒绝）

均调用 POST .../issue_direction/{project}/next。各动作对应的 nextNodeId 写死在 api.BUG_DIRECTION_NEXT_NODE_IDS（与某项目浏览器抓包一致）；若你们项目工作流节点不同，需改源码中该表。

子命令参数（Click 下均为该子命令上的必填项）：

• -i / --bug-id：缺陷 ID。
• -p / --project：项目 ID（须在子命令上显式传入，勿依赖仅写在根命令上的 -p）。
• --operator：经办人账号，英文逗号分隔多个。
• --comment：可选，流转备注（富文本 HTML，例如 '<p>说明</p>'）。

zt-devops-cli bug accept -p b9f157 -i <bug-id> --operator zt07905 --comment '<p>说明</p>'
zt-devops-cli bug resolve -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug verify -p b9f157 -i <bug-id> --operator zt07905,user02
zt-devops-cli bug close -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug reopen -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug reject -p b9f157 -i <bug-id> --operator zt07905

在 ~/.zt-devops-cli/config.yaml 中可写默认项目（便于省略允许默认合并的子命令上的 -p）：

default_project: b9f157

删除缺陷

zt-devops-cli bug delete -p b9f157 -i <bug-id>
zt-devops-cli bug delete -p b9f157 -i <bug-id> -y

-y / --yes 跳过交互确认。

需求 / 工作项

查询自定义字段下拉可选项

子命令上 -p、--field-id、--classify 均为必填。用于按字段与工作项类型拉取与页面 issue_field_value/.../option/{fieldId} 一致的选项列表（classify 与页面一致，如 BUG、TASK、STORY）。

zt-devops-cli issue field-options -p b9f157 \
  --field-id <fieldId> \
  --classify BUG

--all / --no-all：是否对应页面 all 参数（默认 --no-all）。

配置

• Cookie 缓存：~/.zt-devops-cli/cookies.json
• 配置文件：~/.zt-devops-cli/config.yaml（常用键：default_project，解析时等同「根命令 -p」参与合并；另支持 browser_channel，默认 chromium）