Zentao API Skills（禅道 API 技能）

调用禅道（ZenTao）RESTful API v2.0 完成用户请求，包括查询项目、执行、需求、Bug、任务、测试用例等数据，以及创建、编辑、删除等写操作。当用户提到禅道、zentao、查询项目进展、获取Bug列表、更新需求状态、创建任务等项目管理相关操作时使用本技能。

Security Scan

技能功能与禅道 API 使用场景一致，但元数据没有声明所需的环境变量与二进制依赖；随附脚本会在用户主目录写入永久 token 缓存并通过 eval 导出值——这些差异值得在安装前仔细审查和确认。

Purpose & Capability

技能名/描述与实际行为一致：它实现对 ZenTao v2 API 的调用（查询/创建/修改/删除等），并包含完整的端点参考。需要 token、服务器 URL 与可选账号/密码，这与描述的用途是合理且必要的。但 registry 元数据未列出任何必需的环境变量或主凭据（ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT、ZENTAO_PASSWORD），这是元数据与实际需求的不一致。

Instruction Scope

SKILL.md 明确指示运行内置脚本 eval "$(bash scripts/get-token.sh)" 来获得 ZENTAO_URL/ZENTAO_TOKEN/ZENTAO_ACCOUNT，并使用这些值对 ZenTao API 发起请求。脚本只与 ZenTao API 交互（通过 curl）并读写 ~/.zentao-token.json 缓存，没有直接指示将数据发送到其它外部服务；总体上指令集中在技能目的范围内，但会访问/创建主目录下的缓存文件并要求 Node.js 与 curl。

Install Mechanism

无安装规范（instruction-only），没有下载或执行远程二进制。随附 get-token.sh 依赖 curl 与 node（Node.js），这是脚本处理 JSON 的实现选择，虽不危险但在元数据中未声明这些依赖。没有使用不可信的 URL 或提取任意归档。

Credentials

技能运行需要敏感环境变量（至少：ZENTAO_URL、ZENTAO_TOKEN 或 ZENTAO_ACCOUNT + ZENTAO_PASSWORD），并会写入持久缓存文件 ~/.zentao-token.json 来保存 token/url/account。Registry 未声明这些环境变量或主凭据，这使得权限需求与公开元数据不匹配。永久 token（脚本中提到 token 永久有效）增加了长期泄露风险；要求用户通过 env 提供密码也属于高敏感度操作，应在元数据中明确。

Persistence & Privilege

技能不会设置 always:true，但随附脚本会在用户主目录创建/修改 ~/.zentao-token.json（持久化 token）。这是为方便重用而设计的常见行为，但应注意该文件中保存的是长期有效的 token 与 url/account 信息——具有持久影响，建议限制文件权限并确认信任来源。

What to consider before installing

要点和建议： - 总体一致性：技能的功能、示例请求和附带的脚本都与 ZenTao API 的用途相符；没有发现代码向非-ZenTao 端点发送数据或明显的隐藏后门。 - 关注项：registry 元数据没有声明任何必需环境变量或主凭据，但 SKILL.md 和脚本明确会使用 ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT、ZENTAO_PASSWORD 并把 token 持久化到 ~/.zentao-token.json。安装/启用前请确认你信任该技能来源。 - 在运行前的具体建议： · 手动审阅 scripts/get-token.sh（已包含在包里）；如果不信任脚本输出，不要直接用 eval，先单独运行脚本查看其输出（bash scripts/get-token.sh）再决定是否 eval。 · 优先使用 ZENTAO_TOKEN（一次性在环境变量中设置）而不是明文 ZENTAO_PASSWORD 登录；若使用密码登录，确认环境安全并在登录后检查/限制 ~/.zentao-token.json 文件权限（chmod 600 ~/.zentao-token.json）。 · 若不希望持久化 token，可在运行后删除缓存文件（rm ~/.zentao-token.json）或不使用脚本而手工提供短期 token。 · 要求技能开发者/发布者在 registry 元数据中补充所需环境变量与依赖（curl、node），并说明 token 持久化位置与生命周期。 - 如果你要安装/启用该技能：在信任作者并接受持久化 token 的前提下可以使用，但请遵循上述防护措施；若不能接受长期 token 存在或不信任包来源，请不要运行 eval 脚本并拒绝安装。

禅道 API v2.0

配置

优先级从高到低：

变量	说明
ZENTAO_URL	服务器地址，如 http://zentao.example.com
ZENTAO_TOKEN	直接指定 token，跳过登录和缓存（最高优先级），仍然需要提供禅道服务器地址
ZENTAO_ACCOUNT	登录账号，当有 ZENTAO_TOKEN 时，账号是可选的，但如果提供账号可以更好的回答与当前用户相关的问题。
ZENTAO_PASSWORD	登录密码，当有 ZENTAO_TOKEN 时，无需提供密码

ZENTAO_URL、ZENTAO_TOKEN 和 ZENTAO_ACCOUNT 会在首次登录后写入 ~/.zentao-token.json，后续调用无需重复设置。

若必要变量缺失，提示用户并给出 export 命令。如果用户直接提供了服务器、账号和密码，则直接使用，但同时告知用户尽量设置为环境变量。

认证流程

所有业务 API 均需在 Header 携带 token。通过运行脚本 scripts/get-token.sh 自动获取禅道 URL、token 和用户名，避免每次重复登录。

脚本依赖：curl、node（Node.js）

脚本行为：

• 若缓存文件存在，自动补全缺失的 ZENTAO_URL、ZENTAO_TOKEN 和 ZENTAO_ACCOUNT
• 缓存中 URL 与账号均匹配时直接复用 token（token 永久有效，无需密码）
• URL 或账号变更、缓存不存在时，调用登录 API 获取新 token，并将 token、url、account 写入缓存

脚本输出三行 KEY=VALUE，使用 eval 一次性设置所有变量：

eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT

后续所有请求的 Header 中携带：

token: $ZENTAO_TOKEN

执行 API 调用的步骤

1. 运行 eval "$(bash scripts/get-token.sh)" 获取 ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT（自动处理缓存，无需每次登录；仍缺失时提示用户）
2. 根据用户意图选择正确的 API 端点（参见 api-reference.md）
3. 若为 PUT 操作且用户未提供全部字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去
4. 构造请求（方法、URL、Header、Body）并向用户确认写操作内容
5. 执行请求，解析响应
6. 以清晰易读的格式向用户展示结果

常用操作示例

获取所有正在进行的执行（迭代/Sprint）

执行（execution）属于某个项目，需先确定项目 ID，或遍历所有项目：

# 先获取进行中的项目
curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing" -H "token: $ZENTAO_TOKEN"

# 再获取该项目的执行列表（将 {projectID} 替换为实际ID）
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions" -H "token: $ZENTAO_TOKEN"

获取产品的 Bug 列表

curl -s "$ZENTAO_URL/api.php/v2/products/{productID}/bugs" -H "token: $ZENTAO_TOKEN"

修改 Bug

curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}" \
  -H "token: $ZENTAO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "新标题", "severity": 2, "pri": 2}'

解决 Bug

curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" -d '{}'

创建需求

curl -s -X POST "$ZENTAO_URL/api.php/v2/stories" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "需求标题", "assignedTo": "admin"}'

完成任务

curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"consumed": 2, "assignedTo": "admin", "finishedDate": "2026-03-18"}'

意图识别规则

用户意图关键词	对应操作
正在进行的执行/迭代/Sprint	GET projects?browseType=doing + GET projects/{id}/executions
获取所有产品/项目	GET /products 或 GET /projects
某产品/项目的 Bug	GET /products/{id}/bugs 或 /projects/{id}/bugs
更新/修改 Bug	PUT /bugs/{id}
解决 Bug	PUT /bugs/{id}/resolve
关闭需求	PUT /stories/{id}/close
创建任务	POST /tasks
完成任务	PUT /tasks/{id}/finish
获取用户列表	GET /users

注意事项

• URL 中的数字 ID（如 /bugs/1）需替换为实际 ID
• 若不知道 ID，先调用列表接口获取，再操作具体条目
• PUT 接口需提供所有相关字段：禅道的 PUT API 通常要求请求体包含该资源的所有必填字段，而不仅仅是要修改的字段。若用户只指定了部分字段，必须先调用对应的 GET 详情接口获取当前完整数据，再将用户修改的字段覆盖进去，最后一并提交
• 为避免误操作，写操作前向用户确认操作内容，如果用户明确要求不用确认则直接执行
• 响应为 401 表示 token 已被手动吊销，执行 rm ~/.zentao-token.json 清除缓存后重新运行
• browseType 常用值：all（全部）、doing（进行中）、closed（已关闭）

完整 API 参考

详细的端点列表和请求参数见 api-reference.md。

备用资源

• 禅道 API 2.0 官方文档： https://www.zentao.net/book/api/2309.html
• 如果 2.0 的 API 无法满足要求可以参考 1.0 的 API 文档： https://www.zentao.net/book/api/1397.html