zentao-snbc

v0.1.1

Published

a month ago

面向 SNBC 老版本禅道的命令行工具，使用经典 index.php JSON 接口

Downloads

168

0High
0Medium
0Low

hukunyang

zentao snbc cli biz6.0 chandao legacy-zentao

禅道 SNBC CLI

通过 zentao-snbc 命令行工具查询和操作 SNBC 老版本禅道数据。CLI 兼容经典 index.php?m=...&f=...&t=json 接口，适用于 biz6.0 等新版 zentao-cli REST v2 登录不兼容的环境。

适用人群与结论

这份 README 适合给第一次接触本工具的同事使用，但前提是按照本文的“快速开始”步骤安装并登录。

需要：

安装 Node.js 18 或更高版本
安装 zentao-snbc
配置自己的禅道登录信息
拥有对应禅道项目/执行/任务的访问权限

主要特性

✅ 兼容 SNBC 老版本禅道经典 JSON 接口
✅ 已实现 token 优先认证；无 token 时自动回退到账号密码登录
✅ 提供简写命令和 ls/get/create/update/delete/do 原始命令入口
✅ 支持工作区上下文、配置管理、自动补全脚本、常见 Agent 的 skill 安装
✅ 支持 Markdown / JSON / Raw 输出
✅ 对 AI Agents 友好，适合在 Codex / Cursor / Qoder / Kiro 中直接调用

说明：命令入口不等于对应 legacy 模块已稳定支持；模块能力以本文“模块与操作速查”、zentao-snbc help <module> 与实测返回为准。

前置准备

环境要求

Node.js >=18
可以访问目标禅道地址
目标账号拥有对应模块的查看或编辑权限

安装

推荐直接从 npm 安装：

npm install -g zentao-snbc

安装完成后，建议重新打开终端并验证：

zentao-snbc help

如果你只想临时执行、不想常驻安装，也可以：

npx zentao-snbc help

从源码本地安装

如果你正在开发本项目，或需要在本地修改源码后测试，可以在当前目录下：

npm install

本地执行：

node bin/zentao-snbc.js help

如需把当前源码目录全局安装到本机，可在包目录下执行：

npm install -g .

如果你不想全局安装源码版本，也可以始终使用本地命令：

node bin/zentao-snbc.js help

快速开始

下面这组步骤是“别人拿到 README 后最快跑通”的最小流程：

npm install -g zentao-snbc

创建配置文件：

Windows：C:\Users\<用户名>\.config\zentao-snbc\zentao.json
macOS/Linux：~/.config/zentao-snbc/zentao.json

{
  "profile": {
    "server": "http://your-zentao.example.com",
    "account": "your-account",
    "password": "your-password"
  }
}

然后执行：

zentao-snbc profile
zentao-snbc project --pick=id,name,status --limit=5

如果最后一条命令能返回项目列表，说明已经可以直接使用。

认证

推荐优先使用配置文件保存地址、账号、密码。

默认配置文件路径：

Windows: C:\Users\<用户名>\.config\zentao-snbc\zentao.json
macOS/Linux: ~/.config/zentao-snbc/zentao.json

配置文件示例：

{
  "profile": {
    "server": "http://zentao.example.com",
    "account": "admin",
    "password": "123456"
  }
}

配置完成后，后续查询和写操作都会自动读取该配置文件。

如果你保存过多个账号/地址组合，也可以通过：

zentao-snbc profile account@http://zentao.example.com

来切换当前使用的 profile。

如需只退出某一个已保存的 profile，也可以执行：

zentao-snbc logout account@http://zentao.example.com

不带参数时，logout 会退出当前 profile；如果这是最后一个已保存 profile，则会清空本地登录配置。

zentao-snbc help logout 可查看 profileKey 参数说明。

如需临时切换到另一份配置文件，也可以在任意命令前显式指定：

zentao-snbc --config /path/to/zentao.json profile
zentao-snbc --config /path/to/zentao.json project --limit=5

如需临时覆盖，也可以在当前命令中显式传参登录：

node bin/zentao-snbc.js login --server http://zentao.example.com --account admin --password 123456

普通查询/写操作也支持直接通过当前命令参数临时覆盖连接信息，例如：

zentao-snbc --server http://zentao.example.com --account admin --password 123456 product --limit=5
zentao-snbc --token abcdef123456 bug --product=239 --limit=5

其中 --server/--account/--password 的直接查询链路已在真实 biz6.0 经典环境下复核通过。

也支持直接通过环境变量或当前命令参数使用 token：

PowerShell:

$env:ZENTAO_TOKEN="abcdef123456"
zentao-snbc bug --product=239 --limit=5

CMD:

set ZENTAO_TOKEN=abcdef123456
zentao-snbc bug --product=239 --limit=5

Bash:

export ZENTAO_TOKEN=abcdef123456
zentao-snbc bug --product=239 --limit=5

环境变量（优先级低于命令行参数）：

| 变量 | 说明 | |------|------| | ZENTAO_URL | 禅道服务地址 | | ZENTAO_ACCOUNT | 用户账号 | | ZENTAO_PASSWORD | 用户密码 | | ZENTAO_TOKEN | 直接指定 token（有此变量可省略账号密码） | | ZENTAO_CONFIG_FILE | 指定独立配置文件路径 |

默认配置文件保存在：

Windows: C:\Users\<用户名>\.config\zentao-snbc\zentao.json
macOS/Linux: ~/.config/zentao-snbc/zentao.json

命令格式

常用全局选项：

| 选项 | 说明 | |------|------| | --config <config_file> | 临时指定配置文件 | | --timeout <ms> | 为当前命令设置请求超时 | | --insecure | 仅对当前 CLI 进程跳过 SSL/TLS 证书验证 | | --machine-readable | 默认切换为 JSON 输出，方便脚本消费 | | --params <json> | 用 JSON 对象补充 API 参数，等价于一组 --key=value | | --options <json> | 用 JSON 对象补充 CLI 选项，等价于一组公共选项 | | --server/--account/--user/--password/--token | 为当前命令临时覆盖连接凭证 | | --useEnv | 强制当前命令只使用环境变量中的连接信息 | | --silent | 关闭正常输出，仅保留错误 | | --format json|markdown|raw | 显式指定输出格式 |

兼容性说明：

--batch-fail-fast、--all 目前会被兼容解析，但本工具不承诺官方 REST CLI 那种批量/全量抓取语义
在当前已验证的 legacy 环境里，真正稳定的仍然是 --limit、本地过滤/搜索/排序，以及按模块范围参数取经典列表

常用短参数：

-h 等价于 --help
-V 等价于版本输出，返回裸版本号
login 与普通业务命令中的 -s/-u/-p/-t 分别等价于 --server/--user/--password/--token

顶层 help 当前也已覆盖更接近官方 CLI 的命令签名，例如 help [command]、logout [profileKey]、profile [profileKey]、workspace [id]。

原始命令形式也已有单独帮助，例如：

zentao-snbc help list
zentao-snbc help get
zentao-snbc help create
zentao-snbc help update
zentao-snbc help delete
zentao-snbc help do

这些 raw-command help 现在也会明确标出当前真实支持的选项，并说明为什么没有照搬官方 CLI 中的 --page、--recPerPage；--all 与 --batch-fail-fast 只做兼容解析，不承诺 legacy 语义。

当前 raw-command usage 也已尽量贴近官方 CLI 的参数顺序，例如：

zentao-snbc list [options] <module> [args...]
zentao-snbc get [options] <module> <id>
zentao-snbc create [options] <module> [args...]
zentao-snbc update [options] <module> [args...]
zentao-snbc delete [options] <module> [args...]
zentao-snbc do [options] <module> <action> [args...]

其他顶层命令帮助也可直接查看，例如：

zentao-snbc help version
zentao-snbc help autocomplete
zentao-snbc help upgrade

部分本地命令子命令也支持更细粒度的帮助，例如：

zentao-snbc config get --help
zentao-snbc config set --help
zentao-snbc config delete --help
zentao-snbc workspace ls --help
zentao-snbc workspace add --help
zentao-snbc workspace set --help
zentao-snbc workspace delete --help

动作级帮助也已支持，便于离线查看参数语义：

zentao-snbc task start help
zentao-snbc help bug resolve
zentao-snbc do task finish help

模块级帮助现在也会显示当前实现对应的范围参数提示。例如：

zentao-snbc task help

会明确提示 --execution / --executionID。

使用简写方式（推荐）：

| 操作 | 命令 | |------|------| | 列表 | zentao-snbc <module> | | 详情 | zentao-snbc <module> <id> | | 创建 | zentao-snbc <module> create --field=value | | 更新 | zentao-snbc <module> update <id> --field=value | | 删除 | zentao-snbc <module> delete <id> | | 动作 | zentao-snbc <module> <action> <id> | | 帮助 | zentao-snbc help [module] |

也支持更贴近 zentao-cli 的原始命令：

| 操作 | 命令 | |------|------| | 列表 | zentao-snbc ls <module> | | 详情 | zentao-snbc get <module> <id> | | 创建 | zentao-snbc create <module> [args...] | | 更新 | zentao-snbc update <module> <id> [args...] | | 删除 | zentao-snbc delete <module> <id> | | 动作 | zentao-snbc do <module> <action> <id> |

也支持 --data='JSON' 传入 JSON 数据。

也支持把零散参数折叠成 JSON 对象：

zentao-snbc bug --options='{"format":"json","limit":"5"}' --params='{"productID":"239","browseType":"all"}'
zentao-snbc product create --params='{"name":"演示产品","type":"normal"}'

模块与操作速查

| 模块名 | 中文 | 支持的操作 | |--------|------|-----------| | program | 项目集 | 部分支持：有入口；当前已验证账号下 list/view 会被 deny | | product | 产品 | 已实测 list/view | | project | 项目 | 已实测 list/view | | execution | 执行/迭代 | 部分支持：详情可用；列表仅稳定验证经典默认第一页，--project 仅作尽力恢复 | | story | 需求 | 部分支持：详情与 activate/change/close 可用；列表范围不可靠 | | bug | Bug | 部分支持：详情与 activate/close/resolve 可用；仅 --product 列表已验证 | | task | 任务 | 部分支持：常用列表/详情/创建/状态动作可用；delete 在已验证账号下会 deny | | testcase | 测试用例 | 已实测 list/view | | testtask | 测试单 | 已实测 list/view（按产品查列表） | | productplan | 产品计划 | 已实测 list；plan 为别名，详情已实测 | | build | 版本 | 部分支持：仅详情已验证；列表未拿到非空样本 | | release | 发布 | 部分支持：有入口；列表未拿到非空样本 | | user | 用户 | 部分支持：有入口；当前已验证账号下 list/view 会被 deny |

这张表只反映当前已验证的 biz6.0 经典环境结论；“有命令”不代表该模块已稳定支持。若你正在维护本仓库，需要核对逐项实测记录，可查看仓库内的 SUPPORTED_FEATURES_CHECKLIST.md；普通安装用户请以本 README、--help 与实际命令返回为准。

与官方 CLI 的差异说明

以下能力是 zentao-snbc 在 legacy 场景下保留的本地扩展或本地管理能力，不应理解为“官方 zentao-cli 也承诺完全相同的接口”：

task pause
task restart
task recordEstimate
config delete
workspace add
workspace delete

这些能力是否可用，仍以本仓库当前实现和维护期实测记录为准；如需追溯验证细节，请在仓库源码中查看 SUPPORTED_FEATURES_CHECKLIST.md。

列表范围参数

部分模块的列表需要指定所属范围：

zentao-snbc story --product=239
zentao-snbc bug --product=239
zentao-snbc task --execution=5048
zentao-snbc execution --project=4221
zentao-snbc build --project=4221
zentao-snbc testtask --product=239
zentao-snbc release --product=153
zentao-snbc productplan --product=153

设置工作区后可省略这些参数（见下方工作区章节）。

配置与工作区

配置管理

说明：

zentao-snbc login --help 或 zentao-snbc help login 查看登录参数帮助
zentao-snbc config 可以直接查看全部配置
zentao-snbc config get <key> 查看单个配置项
zentao-snbc config set <key> <value> 设置配置项
zentao-snbc config delete <key> 删除配置项
zentao-snbc help config 查看配置命令帮助

查看全部配置：

zentao-snbc config

查看单个配置项：

zentao-snbc config get profile.server

设置配置项：

zentao-snbc config set profile.server https://zentao.example.com
zentao-snbc config set profile.account your-account
zentao-snbc config set profile.password 'your-password-or-use-env'

如果你更习惯直接维护配置文件，也可以手动编辑：

{
  "profile": {
    "server": "https://zentao.example.com",
    "account": "your-account",
    "password": "your-password"
  }
}

删除配置项：

zentao-snbc config delete profile.password

说明：

token 不会写入配置文件，也不支持通过 config set profile.token 持久化
如需使用 token，请通过环境变量 ZENTAO_TOKEN 或当前命令参数提供
zentao-snbc config 与 zentao-snbc profile 的输出会自动对 password、token 等敏感字段脱敏
zentao-snbc help profile 可查看 profileKey 参数说明
zentao-snbc profile <profileKey> 会切换当前 profile，并继续兼容旧的 profile 配置镜像

工作区

说明：

zentao-snbc workspace 查看当前工作区
zentao-snbc workspace ls 查看所有工作区
zentao-snbc workspace add ... 新增工作区
zentao-snbc workspace 1 切换到编号为 1 的工作区
zentao-snbc workspace set ... 更新当前工作区
zentao-snbc workspace delete 1 删除工作区
zentao-snbc workspace help 或 zentao-snbc help workspace 查看工作区命令帮助

添加工作区：

zentao-snbc workspace add --product=239 --project=4221 --execution=5048 --name demo

查看当前工作区：

zentao-snbc workspace

查看全部工作区：

zentao-snbc workspace ls

切换工作区：

zentao-snbc workspace 1

更新当前工作区：

zentao-snbc workspace set --product=239 --project=4221 --execution=5048

删除工作区：

zentao-snbc workspace delete 1

AI 使用策略

输出格式

展示给用户：不加 --format 参数，默认输出 Markdown 表格（列表）或列表（单个对象）
需要程序化处理：加 --format=json，返回结构化 JSON
需要统一机器消费风格：加 --machine-readable，默认按 JSON 输出
已有一批公共选项时：可用 --options='{"format":"json","limit":"10"}' 代替多段 CLI 参数
需要安静执行：加 --silent，只保留错误输出

不知道 ID 时

先查列表获取 ID，再操作具体对象：

zentao-snbc product --pick=id,name
zentao-snbc bug --product=239 --pick=id,title
zentao-snbc bug 92462

写操作前确认

执行创建、更新、删除等写操作前，先向用户确认操作内容。用户明确要求不确认时可跳过。

数据处理

摘取字段

zentao-snbc product --pick=id,name,status

过滤

zentao-snbc bug --product=239 --filter='status:active'
zentao-snbc bug --product=239 --filter='severity<=2,pri<=2'

支持的运算符：: 等于、!= 不等于、> < >= <=、~ 包含、!~ 不包含。

当前 --filter 为客户端过滤，即先取回老禅道响应，再在本地筛选。

模糊搜索

zentao-snbc bug --product=239 --search=登录 --search-fields=title,steps

排序

zentao-snbc bug --product=239 --sort=id_desc
zentao-snbc bug --product=239 --orderBy=id_desc

限制条数

zentao-snbc bug --product=239 --limit=10

辅助命令

自动补全

输出 Bash 补全脚本：

zentao-snbc autocomplete bash

输出 PowerShell 补全脚本：

zentao-snbc autocomplete powershell

当前补全词表已覆盖 list、plan 等常用官方风格命令/别名。

升级

如果你是通过 npm 安装的公开版本，升级方式是：

npm install -g zentao-snbc

如果你是从当前本地源码目录安装的，升级方式是：

zentao-snbc upgrade

安装 Skill

将内置 skill 安装到本机 Agent 目录。当前支持：

codex
cursor
qoder
kiro
all

zentao-snbc add-skill codex
zentao-snbc add-skill cursor
zentao-snbc add-skill all

说明：

zentao-snbc help add-skill 可查看支持的 Agent 列表
add-skill 只负责把 skill 文件复制到本机对应目录，不会自动安装本 CLI
对方仍然需要先完成本 README 的安装与登录步骤

MCP 能力现状

官方 zentao-cli 还提供 add-mcp 与 mcp。当前 zentao-snbc 不把这两项当作支持能力，也不建议在本工具上使用它们。

说明：

本工具当前重点是兼容 SNBC 老禅道经典 index.php?...&t=json 数据访问链路
add-mcp / mcp 属于额外的 Agent 集成层，不影响经典 API 的查询与写操作对齐
当前仓库只保留了显式报错/帮助提示，目的是避免用户误判为“未知命令”，不是表示功能已纳入支持范围

对于 feedback、ticket、system、epic、requirement、file 这些官方模块，当前 CLI 也已提供显式命令名与帮助入口；在当前 legacy 目标环境下会明确返回 unsupported，而不是掉成 unknown module。

常用操作示例

查看进行中的项目

zentao-snbc project --filter='status:doing' --pick=id,name,status

查看某产品的 Bug

zentao-snbc bug --product=239 --pick=id,title,status,severity

查看某执行的任务

zentao-snbc task --execution=5048 --pick=id,name,status,assignedTo

创建并解决 Bug

zentao-snbc bug create --product=239 --title="Bug标题" --severity=2 --pri=2 --type=codeerror
zentao-snbc bug resolve 92462 --resolution=fixed --resolvedBuild=trunk --assignedTo=developer

创建、启动并完成任务

zentao-snbc task create --execution=5048 --name="任务名" --type=devel --assignedTo=developer --estimate=4 --estStarted=2026-05-13 --deadline=2026-05-14
zentao-snbc task start 312385
zentao-snbc task finish 312385 --consumed=4

记录任务工时

zentao-snbc task recordEstimate 312385 --date=2026-04-29 --consumed=4 --left=2 --work="修复XSD与excel文档不一致的问题"

错误处理

| 错误码 | 含义 | 处理方式 | |--------|------|---------| | E1001 | 未登录/凭证缺失 | 执行 zentao-snbc login 或补全 profile.server 与认证信息 | | E1003 | 登录失败 | 检查账号密码或 token 是否有效 | | E2001 | 模块或子命令不存在 | 执行 zentao-snbc help 查看可用命令 | | E2002 | 对象不存在或工作区不存在 | 检查 ID 是否正确 | | E2003 | 缺少必要参数 | 执行 zentao-snbc help <module> 查看参数 | | E2006 | 无权限或被重定向到 deny/login | 检查权限、token 或登录状态 | | E2008 | 返回非预期 JSON/HTML | 检查接口入口、权限或服务状态 | | E5002 | 本地辅助命令失败 | 检查 npm、文件权限或本机环境 |

注意事项

不确定模块参数时，先执行 zentao-snbc help <module> 查看帮助
不确定动作参数时，先执行 zentao-snbc <module> <action> help、zentao-snbc help <module> <action> 或 zentao-snbc do <module> <action> help
顶层命令帮助当前已覆盖 help config、workspace help、help add-skill、help login、help logout、help profile
认证顺序为：优先 token，无 token 时回退到账号密码登录
token 链路的实现与自动化测试已覆盖，但本轮仍缺一次独立的真实 legacy token 实测记录
--params 与 --options 当前已支持 JSON 对象语义；同名显式 CLI 参数优先级更高
--batch-fail-fast、--all 当前只做兼容解析，不代表经典接口已经具备稳定批量/全量语义
配置文件不会持久化 token；如需使用 token，请通过环境变量 ZENTAO_TOKEN 或当前命令参数提供
zentao-snbc config 与 zentao-snbc profile 会自动对密码等敏感字段做脱敏显示
连接类参数如 --server、--account、--password、--token 只用于当前命令的连接覆盖，不会再被错误混入 legacy 写请求表单
--page、--recPerPage、--all、--batch-fail-fast 这类兼容性参数也不会再被错误混入 legacy 写请求表单
在当前已验证的 biz6.0 经典环境里，task create 需要显式传入 --estStarted 与 --deadline，否则服务端会直接返回字段校验失败
在当前已验证的 biz6.0 经典环境里，task delete 会被重定向到 deny，创建类联调暂时只能做到“关闭残留任务”，不能保证真正删除
在当前已验证的 biz6.0 经典环境里，execution --project=... 已比早期空列表行为更接近预期，但仍可能因为经典列表首屏限制漏掉部分执行
在当前已验证的 biz6.0 经典环境里，execution all 的默认第一页可稳定返回，但一旦直接带 pageID、recPerPage、某些 orderBy 参数，经典接口会退化成空集或非 JSON，因此当前不建议把执行列表当作完整可翻页数据源
program --status=... 这类官方式列表过滤参数现在已直接映射到经典 browse query，不再需要额外写成 --params='{\"status\":\"...\"}'
story 与 bug 列表现在默认使用更接近官方 CLI 的 browseType=unclosed；如需拿到更宽范围，仍可显式传 --browseType=all
story 与 bug 的 CLI 入口现在也接受 --project / --execution 范围参数，并会直接透传到经典 browse query；但这两个范围在当前已验证的 biz6.0 环境里仍只应视为“可尝试、未完全可信”
task 列表现在也默认使用更接近官方 CLI 的 browseType=unclosed；如需保留老的宽范围抓取方式，可显式传 --browseType=all
testcase 与 testtask 的 CLI 入口现在接受 --product / --project / --execution 三种范围参数，并会直接透传到经典 browse query；当前已验证样本仍主要集中在产品范围
在当前已验证的 biz6.0 经典环境里，story --product=... 与相关经典 browse 探针会返回不属于请求范围的旧数据；按 ID 查看仍可用，但列表范围结果已定性为不可靠
在当前已验证的 biz6.0 经典环境里，bug --product=... 已实测可用；但 bug --project=... 与 bug --execution=... 的经典探针目前只拿到空集，因此本工具只把产品范围列表当作已验证能力
在当前已验证的 biz6.0 经典环境里，build / release 列表入口可调用，但当前样本仍只有空集；在拿到非空且范围正确的返回前，只保留“部分支持”结论
--page、--recPerPage 没有加入，因为在已验证的 biz6.0 实例上会导致异常结果
feedback、ticket、system、file、requirement、epic 已实测探测，但当前实例没有稳定 JSON 能力，因此未加入支持列表
老版本禅道接口返回格式不完全统一，个别写操作可能要求更多表单字段