SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场zentao-cli

zentao-cli

办公与效率

查看项目

更新于 10-14 21:58

技能介绍

用途

zentao-cli 用于通过命令行操作禅道（ZenTao）。它可以查询和维护禅道中的产品、项目、需求、任务与 Bug，执行状态流转并汇总进展，也用于查询个人待办，以及安装、配置和排查 zentao-cli 自身的问题。

主要能力

  • 查询与维护产品、项目、需求、任务、Bug 等业务对象。
  • 执行状态流转和命名操作。
  • 汇总进展，查询个人待办（my tasks、my bugs、my todos）。
  • 通过模块帮助发现 issue、risk、meeting、workflow、doc 等能力。
  • 支持 JSON 输出，便于程序处理。
  • 提供技能安装与导出：zentao add-skill <agent>，或 zentao add-skill --output ./exported-skills。

使用方式

开始前先确认用户要访问的站点、对象范围和操作。常用命令：

zentao --version
zentao help
zentao profile --format=json

help、模块/操作 --help、props 无需登录。先查帮助再准备请求。

命令形式：

  • 列表（仅支持默认列表的模块）：zentao <module> [范围参数]
  • 详情（仅支持 get 的模块）：zentao <module> <id>
  • 创建/更新/删除：zentao <module> create / zentao <module> update <id> / zentao <module> delete <id>
  • 状态流转或命名操作：zentao <module> <action> [参数]
  • 操作参数、必填项、最低版本：zentao <module> <action> --help
  • 返回对象字段定义：zentao <module> props --format=json

业务字段优先使用 --field=value，保留帮助中的大小写。复杂对象、数组或长文本见 references/writes.md。

常用入口示例（先用对应操作的 --help 确认安装版本支持，再代入真实 ID）：

zentao product --pick=id,name
zentao story --product=1 --pick=id,title,status
zentao bug --product=1 --pick=id,title,status
zentao task --executionID=1 --pick=id,name,status
zentao project --browseType=doing --pick=id,name,status
zentao execution projectExecutions --projectID=5 --browseType=all
zentao productplan --productID=1
zentao release --productID=1
zentao build --project=5
zentao my tasks --pick=id,name,status
zentao my bugs --pick=id,title,status
zentao my todos
zentao doc myDocs --spaceID=1 --libID=2

需求分为 epic（业务需求）、requirement（用户需求）、story（研发需求）。

安装

未安装时按用户环境选择：

npm install -g zentao-cli
bun install -g zentao-cli
pnpm install -g zentao-cli

一次性运行可用 npx zentao-cli <参数>。

认证与账号选择

业务命令缺少凭证会报错，不会自动弹出登录。需要登录时让用户在自己的交互终端执行 zentao login，由 CLI 收集凭证。不要在对话里收集密码或 Token，不要读取、打印凭证环境变量或本地凭证文件。

自动化凭证由运行环境提供：ZENTAO_URL + ZENTAO_ACCOUNT + ZENTAO_TOKEN 或 ZENTAO_PASSWORD。同源同时提供 Token 和密码时优先 Token。业务命令优先使用完整环境凭证，再回退到当前保存的 Profile。

切换本地默认账号：

zentao profile 'admin@https://zentao.example.com'

默认凭证文件为 ~/.config/zentao/zentao.json；自定义路径可用全局 --config <路径> 或 ZENTAO_CONFIG_FILE，前者优先。

服务器版本

帮助离线列出完整注册表，不等于服务器支持全部动作。请求前会检查实际服务器版本；最低版本按同一系列比较，例如 22.5 / biz13.5 / max8.5 / ipd5.5。遇到 E2010 时报告当前版本和该动作要求，可改用已支持且语义等价的查询，不能把替代查询当成全量结果，不能为绕过检查修改版本信息。

执行与核实

查询默认适合阅读；程序处理显式加 --format=json。创建、更新和状态流转按用户已授权的目标与字段执行。用户只要求查看、分析或建议时，先返回结果。删除和批量操作先落实用户授权的对象集合；自动化删除必须显式传 --yes。批量部分失败时分开报告成功、失败和跳过的对象。根据返回的 ID 查询详情或在所属列表中核实关键字段，再宣告结果。写入超时或返回不明确时先查询是否已生效。

错误处理

保留错误要点，按原因处理，不要将所有错误都归为重新登录。

  • E1001 / E1006：凭证不完整或没有可用配置；请用户交互登录或配置完整环境凭证。
  • E1003 / E1004：账号密码错误或 Token 失效；请用户重新登录。
  • E1005 / E1007：配置不可读或指定 Profile 不存在；核对配置路径，使用 profile 查看可用账号。
  • E2001 / E2005：模块或动作不存在；查本地帮助。
  • E2002：对象或接口未找到；核对 ID、范围和具体错误 URL。
  • E2003 / E2004 / E2007 / E2009：缺参数、类型/选项错误或无效 JSON；对照动作帮助修正。
  • E2006：无权限；说明受限操作，交由用户处理授权。
  • E2008：服务端业务或 HTTP 错误；检查具体响应。
  • E2010：服务器版本不支持；说明要求，选择受支持的等价能力或由用户升级。
  • E2011 / E2012：版本格式或站点配置无法识别；核对站点根地址及其 ?mode=getconfig 响应。
  • E1002 / E5001 / E5002：地址不可达、超时或证书验证失败；核对网络、地址和证书，写请求先核实结果再决定是否重试。

适用场景

适合需要通过命令行批量查询、维护禅道数据，执行状态流转，汇总项目进展，查询个人待办，以及在自动化环境中集成禅道操作的场景。

限制

  • 字段、动作和最低服务器版本可能随 CLI/SDK 更新，以当前安装版本的离线帮助为准。
  • 并非每个模块都有 CRUD；doc、my 无默认列表，必须选择命名操作。
  • browseType 是各接口自己的服务端筛选值，不能在不同模块间照搬。
  • 帮助离线列出完整注册表，不等于服务器支持全部动作。
  • 业务命令缺少凭证会报错，不会自动弹出登录。
  • 具体收费、价格、平台支持等信息暂未提供。