zentao-shared
禅道(ZenTao) CLI 共享基础:配置初始化、认证(token-based)、配置优先级、权限错误处理、更新检查、安全规则。当用户说:'配置 zentao'、'初始化配置'、'config init'、'认证'、'登录 zentao'、'禅道登录'、'token'、'查看配置'、'config show'、'config set'、'环境变量'、'ZENTAO_URL'、'ZENTAO_TOKEN'、'权限不足'、'auth status' 时触发。
How do I install this agent skill?
npx skills add https://github.com/imyuyu/zentao-cli --skill zentao-sharedIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides guidance for managing ZenTao via a CLI tool, including credential setup and update notifications. It contains instructions for the agent to suggest execution of maintenance commands based on tool output, which introduces a minor indirect prompt injection surface.
- Socketwarn
1 alert: gptAnomaly
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
zentao-cli 共享规则
本技能指导你如何通过zentao-cli操作ZenTao资源, 以及有哪些注意事项。
配置初始化
自动引导配置流程
当用户未配置或认证失败时:
-
检测配置状态
zentao-cli auth status如果返回
ZEN_AUTH_FAILED或ZEN_CONFIG_INVALID,说明未配置或配置无效。 -
询问用户配置信息和保存位置
必须明确询问保存位置:全局还是当前项目?
向用户询问以下内容:
- ZenTao 服务地址(例如
http://172.168.80.30:8001/zentao) - ZenTao 账号
- ZenTao 密码
- 保存位置:全局(
~/.zentao-cli/config.toml)还是当前项目(.zentao-cli/config.toml)?
⚠️ 重要:必须等用户明确回答保存位置后,才能执行配置命令。禁止在用户未选择的情况下默认使用全局配置。
- ZenTao 服务地址(例如
-
执行配置
全局保存:
zentao-cli config set -g url "用户提供的地址" zentao-cli auth login -g --account 账号 --password 密码当前项目保存:
zentao-cli config set url "用户提供的地址" zentao-cli auth login --account 账号 --password 密码注意:
config set只支持url、token、product_id、project_id,不支持直接设置账号密码。必须分两步:先设置 URL,再用auth login通过账号密码获取 token。 -
验证配置成功
zentao-cli auth status
快速检查
# 检查认证状态
zentao-cli auth status
# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN
获取 Token(手动)
- 登录 ZenTao Web 界面
- 进入个人设置 → API Token
- 生成新 Token
- 设置为
ZENTAO_TOKEN环境变量
环境变量说明
| 变量 | 必需 | 说明 |
|---|---|---|
ZENTAO_URL | 是 | ZenTao 服务器地址,例如 https://zentao.example.com |
ZENTAO_TOKEN | 是 | API Token,用于认证 |
ZENTAO_PRODUCT_ID | 否 | 默认产品 ID |
ZENTAO_PROJECT_ID | 否 | 默认项目 ID |
认证
Token-based 认证
ZenTao 使用 Token 进行认证,Token 通过 ZENTAO_TOKEN 环境变量传递。
# 验证认证状态
zentao-cli auth status
错误响应格式:
{
"status": "error",
"error": {
"code": "ZEN_AUTH_FAILED",
"message": "Invalid token or token expired",
"hint": "Verify ZENTAO_TOKEN is correct"
}
}
常见错误码
| Code | Description | Resolution |
|---|---|---|
ZEN_AUTH_FAILED | Token 无效或过期 | 验证 ZENTAO_TOKEN 是否正确 |
ZEN_NOT_FOUND | 资源不存在 | 检查 ID 后重试 |
ZEN_CONFIG_INVALID | 配置无效 | 验证 ZENTAO_URL 和 ZENTAO_TOKEN |
ZEN_API_ERROR | ZenTao API 返回错误 | 检查服务器状态或稍后重试 |
ZEN_PARAM_MISSING | 缺少必需参数 | 提供所有必需参数 |
权限不足处理
遇到权限相关错误时:
- 确认当前用户角色(ZenTao 中通常是
admin、leader或member) - 验证 Token 是否具有操作该资源所需的权限
- 如果是管理员,请检查该用户是否被正确分配到相关项目/产品
配置优先级
CLI 参数优先级从高到低:
- 命令行参数(
--product,--project等) - 环境变量(
ZENTAO_PRODUCT_ID,ZENTAO_PROJECT_ID) - 默认配置
# 命令行参数优先级最高
zentao-cli task list --project 5 # 使用 --project 参数
# 环境变量作为默认值
export ZENTAO_PROJECT_ID=5
zentao-cli task list # 使用环境变量
# 默认值兜底
zentao-cli task list # 使用配置中的默认值
通用选项
| 选项 | 说明 |
|---|---|
--format | 输出格式:json、pretty、table、ndjson、csv |
--product | 按产品 ID 过滤 |
--project | 按项目 ID 过滤 |
--status | 按状态筛选 |
输出格式
# JSON 输出(默认,用于脚本)
zentao-cli story list --product 1 --format json
# Pretty 打印输出(默认,用于终端)
zentao-cli story list --product 1 --format pretty
# 表格输出
zentao-cli story list --product 1 --format table
更新检查
执行 zentao-cli 命令后,如果检测到新版本,JSON 输出中会包含 _notice.update 字段(含 message、command 等)。
当在输出中看到 _notice.update 时,完成当前请求后补充告知并提议更新:
- 告知当前版本和最新版本号
- 提议执行:
npm update -g zentao-cli && npx skills add zentao/cli -g -y - 提醒用户退出并重新打开 AI Agent 以加载最新 Skills
规则:不要静默忽略更新提示。即使当前任务与更新无关,也应在完成用户请求后补充告知。
安全规则
- 禁止输出密钥(token、appSecret)到终端明文。
- 写入/删除操作前必须确认用户意图。
- 用
--dry-run预览危险请求。
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/imyuyu/zentao-cli/zentao-shared">View zentao-shared on skillZs</a>