@cloudglab/zentao-cli 0.1.4 → 0.1.6

package/skills/zentao-cli/reference/execution.md

@@ -0,0 +1,38 @@
+# Execution
+
+## 查询
+
+```bash
+zentao getExecutionDetail --executionId <id>
+zentao getExecutionDynamic --executionId <id>
+zentao getExecutionBugs --executionId <id>
+zentao getExecutionDailyBugStats --executionId <id> --iterationName 1.2.3迭代
+zentao getExecutionBuilds --executionId <id>
+```
+
+`getExecutionDynamic` 是近似读取：调用禅道 REST `GET /executions/{id}?fields=dynamics`，用于快速查看执行动态摘要。它不是旧版页面 `execution-dynamic-<id>.html` 的完整等价实现，暂不支持 `today/all/自定义时间范围` 参数。
+
+`getExecutionDailyBugStats` 用于“每日迭代执行统计”场景：按执行下 Bug 当前字段统计总 Bug、延期处理、reopen、已关闭、已解决、未解决、测试未及时关闭 Bug、开发今日未及时解决 Bug，并输出参与人员 Bug 情况和文本报告。
+
+统计口径：
+
+- reopen：`activatedCount > 0`
+- 延期处理：`resolution` 为 `postponed/delay/delayed`
+- 测试未及时关闭 Bug：当前 `status=resolved` 但还没关闭
+- 开发今日未及时解决 Bug：当前未解决且创建日期不晚于统计日期
+- 参与人员归属：优先 `resolvedBy`，其次 `assignedTo`，再其次 `openedBy`
+
+## 写入
+
+```bash
+zentao startExecution --executionId <id> --confirm true
+zentao closeExecution --executionId <id> --confirm true
+```
+
+## 场景
+
+- 看执行详情
+- 看执行动态摘要
+- 看执行 Bug / 构建
+- 做每日迭代执行 Bug 统计报告
+- 启动 / 关闭执行

package/skills/zentao-cli/reference/install.md

@@ -0,0 +1,90 @@
+# 安装 / 更新
+
+## 一键安装 CLI + Skill
+
+```bash
+npx -y @cloudglab/zentao-cli@latest install
+```
+
+它会依次执行：
+
+1. 安装全局 CLI：`npm install -g @cloudglab/zentao-cli@latest`
+2. 安装 skill：`npx -y skills add -g cloudglab/zentao-cli`
+3. 如果没有禅道配置，或已有配置登录失败，则提示输入配置并校验
+
+默认通过 GitHub 仓库安装 skill。如果当前环境不能访问远程 `.git` 仓库，但可以访问 npm 包，可改用 npm 静态包模式：
+
+```bash
+npx -y @cloudglab/zentao-cli@latest install --skill-source npm
+```
+
+如果已经提前下载并解压好了 npm 静态包，也可以直接指定本地目录：
+
+```bash
+zentao install --skill-local-path ./package
+```
+
+后续更新可运行：
+
+```bash
+zentao update
+```
+
+`zentao update` 会重新安装最新 CLI 和 skill，并再次校验禅道配置。
+
+## 安装 CLI
+
+```bash
+# 运行时要求：Node.js >= 16
+npm i -g @cloudglab/zentao-cli@latest
+```
+
+或直接运行：
+
+```bash
+npx -y @cloudglab/zentao-cli@latest --help
+```
+
+## 安装 Skill
+
+默认 GitHub 仓库方式：
+
+```bash
+npx -y skills add -g cloudglab/zentao-cli
+```
+
+只能访问 npm、不能 clone `.git` 仓库时：
+
+```bash
+npm pack @cloudglab/zentao-cli@latest
+tar -xzf cloudglab-zentao-cli-*.tgz
+npx -y skills add -g ./package
+```
+
+## 检查是否已安装
+
+```bash
+command -v zentao
+zentao --version
+zentao version
+zentao help
+```
+
+## 更新
+
+```bash
+zentao update
+```
+
+skill 内推荐优先调用本地 `zentao`；只有在当前环境不方便安装时，才退回 `npx -y @cloudglab/zentao-cli@latest`。
+
+如果你不想全局安装，也可以一直用：
+
+```bash
+npx -y @cloudglab/zentao-cli@latest
+```
+
+## 写操作前置条件
+
+- `ZENTAO_ENABLE_WRITE=true`
+- `confirm=true`

package/skills/zentao-cli/reference/overview.md

@@ -0,0 +1,24 @@
+# 总览
+
+## 这个 skill 做什么
+
+- 用命令行方式操作禅道
+- 默认只 preview，不直接写线上
+- 支持任务、Bug、需求、项目、执行、构建、测试用例、测试单等常用场景
+
+## 推荐工作流
+
+1. 先确认本机是否安装 `zentao`
+2. 如果没有，优先安装或升级本地 `zentao`
+3. 先判断用户问的是普通禅道产品数据，还是业务产品的线上 / 客户反馈 / 生产问题
+4. 如果是线上 Bug，固定按 `reference/bug.md` 里的“市场和售后问题跟踪 + 模块匹配”链路查询
+5. 根据问题类型，去对应 reference 文档找命令
+6. 默认只 preview；写操作必须显式确认
+
+补充：当前发布产物运行时目标为 `Node.js >= 16`；开发 / 构建环境可以更高。
+
+## 适合谁
+
+- 需要命令行操作禅道的人
+- 需要把禅道接入智能体的人
+- 需要在旧版本禅道环境下稳定使用的人

package/skills/zentao-cli/reference/plan.md

@@ -0,0 +1,20 @@
+# Plan
+
+## 查询
+
+```bash
+zentao getProductPlans --productId <productId>
+zentao getPlanDetail --planId <id>
+```
+
+## 关系操作
+
+```bash
+zentao linkStoriesToPlan --planId <id> --storyIds <id1,id2>
+zentao linkBugsToPlan --planId <id> --bugIds <id1,id2>
+```
+
+## 场景
+
+- 查看计划
+- 关联需求 / Bug 到计划

package/skills/zentao-cli/reference/product.md

@@ -0,0 +1,14 @@
+# Product
+
+## 查询
+
+```bash
+zentao getProducts
+zentao getProductDetail --productId <id>
+zentao getProductStories --productId <id>
+```
+
+## 场景
+
+- 查看产品信息
+- 查看产品下需求 / Bug / 用例

package/skills/zentao-cli/reference/project.md

@@ -0,0 +1,14 @@
+# Project
+
+## 查询
+
+```bash
+zentao getProjects
+zentao getProjectDetail --projectId <id>
+zentao getProjectExecutions --projectId <id>
+```
+
+## 场景
+
+- 查看项目
+- 查看项目下执行

package/skills/zentao-cli/reference/statistics.md

@@ -0,0 +1,30 @@
+# Statistics
+
+## 查询
+
+```bash
+zentao getMyTaskStatistics
+zentao getMyBugStatistics
+zentao getMyBugStatistics --productId <productId>
+zentao getMyWeeklyActivity --account <account> --week last
+zentao getMyWeeklyActivity --account <account> --dateRange 上周
+zentao getMyWeeklyActivity --account <account> --dateRange 最近3天
+zentao getMyWeeklyActivity --account <account> --dateRange 2026-05-28
+zentao getMyWeeklyActivity --account <account> --startDate 2026-05-25 --endDate 2026-05-29
+```
+
+## 场景
+
+- 看个人任务统计
+- 看个人 Bug 统计
+- 看指定账号上周 / 本周做了什么：解决 Bug、关闭 Bug、评论补充、指派流转、任务相关动作和每日清单
+
+说明：
+
+- `getMyBugStatistics` 不传 `productId` 时，默认统计跨所有产品“指派给我的 Bug”
+- 传 `productId` 时，只统计指定产品内我的 Bug
+- `getMyWeeklyActivity` 是近似读取：调用禅道旧版动态页面 JSON 获取动态原始数据，再按原始 `originalDate` / `date` 在客户端筛选日期范围，用于快速生成“我某段时间做了什么”清单
+- 日期不要写死为周：优先支持 `--dateRange` 自然语言描述，也支持 `--startDate/--endDate` 和 `--days`
+- `--dateRange` 支持示例：`上周`、`本周`、`今天`、`昨天`、`最近3天`、`3天前`、`2026-05-28`、`2026-05-25到2026-05-29`
+- 未传日期范围时，默认兼容旧参数：`--week last` 映射 `lastWeek`，`--week this` 映射 `thisWeek`
+- bug 转任务去重会优先识别动态记录中的来源 Bug 字段；如果动态记录没有来源 Bug 字段，该任务会按独立任务计数并在结果限制说明中提示

package/skills/zentao-cli/reference/story.md

@@ -0,0 +1,22 @@
+# Story
+
+## 查询
+
+```bash
+zentao getStoryDetail --storyId <id>
+zentao getProductStories --productId <productId>
+zentao searchStories --productId <productId> --keyword <keyword>
+```
+
+## 写入
+
+```bash
+zentao updateStory --storyId <id> --confirm true
+zentao changeStory --storyId <id> --confirm true
+```
+
+## 场景
+
+- 查看需求
+- 修改需求内容
+- 变更需求状态

package/skills/zentao-cli/reference/task.md

@@ -0,0 +1,21 @@
+# 任务 Task
+
+## 查询
+
+```bash
+zentao getMyTasks
+zentao getTaskDetail --taskId <id>
+```
+
+## 写入
+
+```bash
+zentao updateTask --taskId <id> --status done --confirm true
+zentao finishTask --taskId <id> --confirm true
+```
+
+## 场景
+
+- 看我的待办
+- 改任务状态
+- 完成任务

package/skills/zentao-cli/reference/testcase.md

@@ -0,0 +1,20 @@
+# TestCase
+
+## 查询
+
+```bash
+zentao getProductTestCases --productId <productId>
+zentao getTestCaseDetail --testCaseId <id>
+```
+
+## 写入
+
+```bash
+zentao createTestCase --productId <productId> --title <title> --type feature --confirm true
+zentao updateTestCase --testCaseId <id> --confirm true
+```
+
+## 场景
+
+- 创建 / 修改测试用例
+- 查看产品用例列表

package/skills/zentao-cli/reference/testtask.md

@@ -0,0 +1,20 @@
+# TestTask
+
+## 查询
+
+```bash
+zentao getTestTasks --productId <productId>
+zentao getTestTaskDetail --testTaskId <id>
+```
+
+## 写入
+
+```bash
+zentao createTestTask --project <projectId> --productID <productId> --name <name> --build <buildId> --begin <YYYY-MM-DD> --end <YYYY-MM-DD> --confirm true
+zentao updateTestTask --testTaskId <id> --confirm true
+```
+
+## 场景
+
+- 创建 / 修改测试单
+- 查看产品测试单列表