@cloudglab/zentao-cli 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.1.6 - 2026-06-06
+
+### Fixed
+
+- 修正 `zentao install` / `zentao update` 的 skill 安装源，默认使用 `cloudglab/zentao-cli` GitHub 仓库源，避免把 npm 包名误解析为错误仓库地址。
+
+### Added
+
+- 新增 `--skill-source npm` 安装模式：在不能访问远程 `.git` 仓库但可以访问 npm 的环境中，自动下载 `@cloudglab/zentao-cli` 静态包、解压并通过本地路径安装 skill。
+- 新增 `--skill-local-path` 参数，支持直接从已解压的本地 skill 包目录安装。
+- 新增安装流程测试，覆盖默认 GitHub 源和 npm 静态包本地路径安装流程。
+
+### Changed
+
+- README、skill 文档和安装参考文档补充 GitHub 源、npm 静态包、本地路径三种 skill 安装方式。
+
+## 0.1.5 - 2026-06-06
+
+### Fixed
+
+- 修正 skill 安装源：默认使用 `cloudglab/zentao-cli` GitHub 仓库源；不能访问远程 `.git` 仓库时，支持通过 npm 静态包解压后的本地路径安装 skill。
+
+### Added
+
+- 新增 `zentao install` / `zentao update` 内置命令，一键安装或更新 CLI 与 skill，并校验禅道配置。
+- 新增 `getExecutionDynamic`，支持按执行 ID 近似读取执行动态摘要。
+- 新增 `getExecutionDailyBugStats`，输出迭代每日 Bug、任务、参与人员和问题明细统计报告。
+- 新增 `getMyWeeklyActivity`，支持上周、本周、最近 N 天、单日和自定义日期范围的个人阶段性工作清单。
+- 新增 Vitest 测试体系、覆盖率配置和 lefthook pre-commit 检查入口。
+- 新增核心函数、API 封装、工具注册、配置、认证和 HTTP 客户端测试。
+
+### Changed
+
+- `getMyTasks` 改为尽量拉取完整任务列表后在客户端按状态和分页过滤，以适配部分禅道部署忽略查询参数的问题。
+- QA 角色新增任务相关命令入口。
+- npm 发布文件列表加入 `skills` 目录，确保 skill 随包发布。
+- README、skill 和 reference 文档同步到新增安装、动态和统计能力。
+
 ## 0.1.4 - 2026-06-05
 
 ### Changed

package/README.md

@@ -1,319 +1,201 @@
 # @cloudglab/zentao-cli
 
-基于 TypeScript 重建的禅道命令行工具，优先适配当前禅道 `18.5` 的 REST v1 API。
-
 ![zentao-cli hero](./assets/readme/zentao-cli-hero.png)
 
-> 把任务、Bug、需求、测试、计划、构建、发布这些禅道操作，直接接进本地 `zentao` 命令，给命令行、脚本和 skill 调用。
+把禅道任务、Bug、执行、构建、动态和统计能力接到命令行，方便在 CI、脚本和 AI Skill 里直接调用。
 
-## 亮点
+## 安装方式
 
-- `60` 个 CLI 命令，覆盖任务、Bug、需求、执行、测试、计划、构建、发布、搜索等核心场景
-- `4` 个内置角色：`Dev / QA / PM / Full`
-- 基于 TypeScript 重建，优先适配禅道 `18.5` REST v1 API
-- 发布产物运行时目标：`Node.js >= 16`
-- 默认写保护，写操作需要显式开启并确认，更适合接入智能体和自动化流程
+### 一键安装 CLI + Skill
 
-## 快速开始
+```bash
+npx -y @cloudglab/zentao-cli@latest install
+```
 
-环境要求：`Node.js >= 16`
+该命令会依次安装全局 CLI、安装 skill，并在禅道配置缺失或登录校验失败时引导输入配置。
 
-### 安装
+默认通过 GitHub 仓库安装 skill。如果当前环境不能访问远程 `.git` 仓库，但可以访问 npm 包，可改用 npm 静态包模式：
 
 ```bash
-# 运行时要求：Node.js >= 16
-
-# 直接运行
-npx -y @cloudglab/zentao-cli@latest
-
-# 全局安装
-npm i -g @cloudglab/zentao-cli@latest
+npx -y @cloudglab/zentao-cli@latest install --skill-source npm
 ```
 
-### 配置
+npm 模式会下载 `@cloudglab/zentao-cli` 包，解压其中的 `skills/` 目录，再通过本地路径安装 skill。
 
-```bash
-export ZENTAO_URL="https://your-zentao.example.com"
-export ZENTAO_USERNAME="your-account"
-export ZENTAO_PASSWORD="your-password"
-export ZENTAO_API_VERSION="v1"
+如果已经提前下载并解压好了 npm 静态包，也可以直接指定本地目录：
 
-# 可选：非标准部署时指定完整 API 基础地址
-# export ZENTAO_API_BASE_URL="https://your-zentao.example.com/custom/api.php/v1"
+```bash
+zentao install --skill-local-path ./package
 ```
 
-### 运行
+后续更新也可以直接运行：
 
 ```bash
-# 查看帮助 / 版本
-zentao help
-zentao --version
-
-# 默认 full 角色
-zentao list
-zentao getMyTasks --status all --limit 20
-
-# 按角色启动
-zentao --role dev getMyTasks --status all
-zentao --role qa getMyBugs --limit 50
-zentao --role pm getProducts
-
-# 也可以直接用 npx
-npx -y @cloudglab/zentao-cli@latest --role qa getMyBugs --limit 50
+zentao update
 ```
 
-## 使用方式
+### CI / 脚本里临时使用
 
-### CLI
+```bash
+npx -y @cloudglab/zentao-cli@latest --help
+npx -y @cloudglab/zentao-cli@latest --role qa getMyTasks --status all --limit 20
+```
 
-适合手动查数据、排查问题、批量执行脚本。
+### 全局安装
 
-常见场景：
-- 查我的任务 / Bug / 统计
-- 查询需求、执行、计划、构建、发布
-- 创建或更新任务、测试用例、测试单
-- 做任务流转、Bug 处理、批量排期、回填工时、同步状态
-- 通过 `Dev / QA / PM / Full` 角色入口提供差异化能力
+```bash
+npm i -g @cloudglab/zentao-cli@latest
+zentao --version
+zentao version
+zentao help
+```
 
-### 智能体 / Skill 接入建议
+### Skill 安装
 
-推荐顺序：
+默认 GitHub 仓库方式：
 
-1. 先检查本机有没有 `zentao`
-2. 没有就安装：`npm i -g @cloudglab/zentao-cli@latest`
-3. skill 内优先调用本地 `zentao`
-4. 只在不能安装时，才退回 `npx -y @cloudglab/zentao-cli@latest`
+```bash
+npx -y skills add -g cloudglab/zentao-cli
+```
 
-常用检查命令：
+如果只能访问 npm，不能 clone `.git` 仓库：
 
 ```bash
-command -v zentao
-zentao --version
+npm pack @cloudglab/zentao-cli@latest
+tar -xzf cloudglab-zentao-cli-*.tgz
+npx -y skills add -g ./package
 ```
 
-skill / 自动化里推荐直接执行：
+Skill / Agent 里推荐优先调用本地命令：
 
 ```bash
 zentao --role qa getMyBugs --limit 50
-zentao getProductBugs --productId 123 --status all --limit 100
 ```
 
-### Skill
-
-适合把当前能力包装成可复用的 AI Skill，对外推广更友好。
-
-相关文档：
-- `skills/zentao-cli/reference/overview.md`
-- `skills/zentao-cli/reference/install.md`
-
-安装 skill 时，统一走：
+本地没有安装时再退回：
 
 ```bash
-npx skills add @cloudglab/zentao-cli -g
+npx -y @cloudglab/zentao-cli@latest --role qa getMyBugs --limit 50
 ```
 
-skill 内部入口建议：
-
-- 优先：`zentao`
-- 或按角色：`zentao --role qa`
-- 无本地安装时兜底：`npx -y @cloudglab/zentao-cli@latest`
-
-适合场景：
-- 给团队成员提供统一入口
-- 给非开发用户提供更低门槛的禅道操作方式
-- 做内部推广和标准化接入
-
-## 当前 MVP 能力
-
-- token 登录：仅在明确鉴权失败时才从明文密码回退到 MD5
-- 登录错误分类：区分账号密码错误、token 接口不存在、网络失败、服务端异常
-- 自动清洗 PHP warning + JSON 混合响应
-- `getMyTasks`
-- `getTaskDetail`
-- `getBugDetail`
-- `getStoryDetail`
-- `getExecutionDetail`
-- `getExecutionBugs`
-- `getMyBugs`
-- `getProductBugs`
-- `getComments`
-- 写操作 preview：`updateTask`、`finishTask`、`resolveBug`、`addComment`
-- `getMyProfile`
-- `getMyTaskStatistics`
-- `getMyBugStatistics`
-- `getStoryRelatedBugs`
-- `getBugRelatedStory`
-- `getDevelopmentContext`
-- `getProducts` / `getProductDetail`
-- `getProjects` / `getProjectDetail`
-- `getProjectExecutions` / `getExecutionBuilds`
-- `getProductStories`
-- `getProductTestCases` / `getTestCaseDetail`
-- `getTestTasks` / `getTestTaskDetail`
-- `getPrograms` / `getProgramDetail`
-- `getProductPlans` / `getPlanDetail`
-- `getProjectBuilds` / `getBuildDetail`
-- `getProjectReleases`
-- `searchStories`
-- `searchStoriesByProductName`
-- `updateStory` / `changeStory`（默认 preview）
-- `createTaskFromStory` / `createTaskFromBug`（默认 preview）
-- `linkStoriesToPlan` / `unlinkStoriesFromPlan`（默认 preview）
-- `linkBugsToPlan` / `unlinkBugsFromPlan`（默认 preview）
-- `updateExecution` / `startExecution` / `closeExecution` / `suspendExecution` / `activateExecution` / `putoffExecution`（默认 preview）
-- `createBuild` / `updateBuild`（默认 preview）
-- `createTestCase` / `updateTestCase`（默认 preview）
-- `createTestTask` / `updateTestTask`（默认 preview）
-
-`updateExecution` 按禅道 18.5 REST v1 文档/源码需要保留/传入：
-
-- `project`
-- `name`
-- `code`
-- `begin`
-- `end`
-
-注意：`updateExecution` 在禅道 18.5 且后台启用代号时存在服务端源码问题：`api/v1/entries/execution.php` 中 `$fields .= 'code'` 缺少前置逗号，导致请求体里的 `code` 不会进入服务端 `$_POST`，服务端会误报 `『迭代代号』不能为空。`。客户端无法稳定绕过；工具仍保留，但调用时会直接返回该诊断错误，不做真实写入。
-
-`createBuild` 当前按禅道 18.5 实机/参考包契约使用 `POST /projects/{project}/builds`，通常需要提供：
-
-- `project`
-- `execution`
-- `product`
-- `name`
-- `builder`
-
-补充说明：
-
-- `createTaskFromStory` / `createTaskFromBug` 在当前实例上实机验证发现通常需要额外提供：
-  - `assignedTo`
-  - `estStarted`
-  - `deadline`
-- `createTaskFromBug` 当前只保证：
-  - 基于 Bug 预填任务内容并尝试创建任务
-  - 不保证创建后自动建立 Bug 关联
-- 角色工具过滤：`full` / `dev` / `qa` / `pm`
-- 写操作保护 helper：默认禁用写操作，后续写工具必须配合 `ZENTAO_ENABLE_WRITE=true` 和 `confirm: true`；已知 18.5 不支持或服务端有缺陷的写工具会保留入口，但调用时直接返回明确诊断错误。
-- Phase 3B 写工具（execution / build / testcase / testtask）默认同样返回 preview，真实执行仍需 `ZENTAO_ENABLE_WRITE=true` + `confirm=true`：
-  - execution：`updateExecution` / `startExecution` / `closeExecution` / `suspendExecution` / `activateExecution` / `putoffExecution`
-  - build：`createBuild` / `updateBuild`
-  - testcase：`createTestCase` / `updateTestCase`
-  - testtask：`createTestTask` / `updateTestTask`
-  - 角色权限：
-    - `full` 拥有 `execution-write` + `build-write` + `testcase-write` + `testtask-write`
-    - `dev` 拥有 `execution-write` + `build-write`
-    - `pm` 仅拥有 `execution-write`
-    - `qa` 拥有 `testcase-write` + `testtask-write`
-- `createTestCase` / `updateTestCase` 当前按禅道 18.5 REST v1 契约：
-  - 创建路径：`POST /products/{productId}/testcases`
-  - 更新路径：`PUT /testcases/{testCaseId}`
-  - `steps` 数组每项形如 `{ desc, expect, type? }`，`type` 支持 `step` / `item` / `group`，默认 `step`
-  - `module` / `story` 允许传 `0` 表示无模块 / 无关联需求
-- `project` / `execution` / `keywords` 不是禅道 18.5 REST v1 用例创建/更新 entry 接收字段，传入会被服务端忽略；18.5 v1 创建的是产品用例，不会直接绑定项目/执行。
-- `createTestTask` 当前按禅道 18.5 REST v1 契约：
-  - 创建路径：`POST /projects/{project}/testtasks`
-  - 创建必填：`project` / `productID` / `name` / `build` / `begin` / `end`，`begin` / `end` 格式 `YYYY-MM-DD`
-  - 创建请求体实际使用 `product` 字段，工具入参保留 `productID` 并在 API 层映射
-  - `build` 兼容数字 ID 和字符串 ID
-  - `createTestTask` 当前实例真实写验证通过
-- `updateTestTask`：禅道 18.5 v1 `api/v1/entries/testtask.php` 只有 `get/delete`，没有 `put` 更新入口。工具仍保留，但调用时会直接返回该诊断错误，不做真实写入。
-- `linkBugsToPlan` 已按 18.5 源码修正为 `POST /productplans/{planId}/linkbugs`。
-- `finishTask` 已按 18.5 源码改为 `POST /tasks/{taskId}/finish`，需要 `currentConsumed` / `realStarted` / `finishedDate`。
-- `addComment`：禅道 18.5 v1 没有 `comment/comments` entry，当前只支持 `getComments` 从对象详情 actions 回退读取；`addComment` 工具仍保留，但调用时会直接返回该诊断错误。
-- token 失效后自动重试一次
-- 可选 `ZENTAO_API_BASE_URL`：用于非标准 `/zentao/api.php/v1` 部署
-
-## 配置
-
-说明：
-
-- `getMyBugs` 当前默认语义是“跨所有产品指派给我的 Bug”；传 `productId` 时收窄到指定产品。
-- `getMyBugStatistics` 默认统计跨所有产品指派给我的 Bug；传 `productId` 时收窄到指定产品。
-- `getComments` 在禅道 18.5 上会 fallback 到对象详情里的 `actions`，返回结果会明确标注 `source: "actions-fallback"`。
-- `updateTask` / `finishTask` 不会默认修改 `assignedTo`，只有显式传入才会更新指派人。
-
-支持环境变量：
+## 环境变量
 
 ```bash
-export ZENTAO_URL="https://zentao.cloudglab.cn"
+export ZENTAO_URL="https://your-zentao.example.com"
 export ZENTAO_USERNAME="your-account"
 export ZENTAO_PASSWORD="your-password"
 export ZENTAO_API_VERSION="v1"
-# 可选：非标准部署时直接指定完整 API 基础地址
-# export ZENTAO_API_BASE_URL="https://zentao.cloudglab.cn/custom/api.php/v1"
-```
-
-注意：`ZENTAO_URL` 传根域名即可，不要带 `/zentao`。
-
-`initZentao` 现在默认只校验并在当前进程内生效，不会自动把密码写入 `~/.zentao/config.json`。
-只有显式传 `save: true` 才会落盘。
-
-## 开发
 
-```bash
-pnpm install
-pnpm typecheck
-pnpm build
+# 可选：非标准部署时指定完整 API 基础地址
+# export ZENTAO_API_BASE_URL="https://your-zentao.example.com/custom/api.php/v1"
 ```
 
-## 发布链路
-
-已内置 GitHub Actions：当你 push 形如 `v*` 的 tag 时，会自动：
-
-1. 安装依赖
-2. 执行 `pnpm typecheck`
-3. 执行 `pnpm build`
-4. 发布 npm 包到 registry
-5. 自动创建对应 GitHub Release
-
-工作流文件：
-
-- `.github/workflows/publish.yml`
-
-### 使用前准备
-
-1. 先把代码推到 GitHub 仓库
-2. 在 npm 上为 `@cloudglab/zentao-cli` 配置 GitHub Actions trusted publisher，绑定仓库 `cloudglab/zentao-cli`
-3. 确保 `package.json` 中的 `version` 与你要打的 tag 一致
-
-### 发版方式
-
-例如当前 `package.json` 版本是 `0.1.0`，则发版命令：
+`ZENTAO_URL` 传根域名即可，不要带 `/zentao`。
+
+## 可以这样描述场景
+
+下面这些话可以交给 AI Skill / Agent 转成对应的 zentao-cli 命令。
+
+### 我的任务和 Bug
+
+- 我今天的 Bug 有多少？
+- 我今天的任务有多少？
+- 获取我的所有任务。
+- 看我等待中的任务。
+- 看我进行中的任务。
+- 看我已取消的任务。
+- 分页看我的任务。
+- 看我当前指派的 Bug。
+- 统计我当前 Bug 的状态分布。
+- 统计我当前任务的状态分布。
+
+### 一段时间内我做了什么
+
+- 分析上周我都干了什么。
+- 查一下我本周解决了多少个 Bug。
+- 查一下 lixm1 上周解决了多少个 Bug。
+- 看 lixm1 最近 3 天做了什么。
+- 看我 2026-05-28 做了什么。
+- 拉一下 2026-05-25 到 2026-05-29 的工作清单。
+- 汇总我上周的评论、指派、流转和解决记录。
+- 按天列出我最近几天处理过的 Bug 和任务。
+
+### 执行 / 迭代统计
+
+- 这个迭代有多少个 Bug？
+- 这个迭代今天解决了多少个问题？
+- 分析 execution 2067 的每日迭代执行统计。
+- 生成 1.2.3 迭代日报。
+- 统计某个迭代今天 Bug 和任务情况。
+- 看这个执行的 Bug、任务、参与人员和风险明细。
+- 统计这个迭代的延期 Bug、reopen Bug 和未解决 Bug。
+- 看这个迭代里测试未及时关闭的问题。
+- 看这个迭代里开发今日未及时解决的问题。
+- 看这个迭代的任务总数、完成数、逾期未完成数和工时消耗。
+- 看这个迭代每个人负责了多少 Bug 和任务。
+
+### 禅道页面 URL 查询
+
+- 列出 `execution-bug-2130.html` 里面的 Bug。
+- 看 `execution-build-2130.html` 这个执行有哪些版本。
+- 看 `execution-dynamic-2130.html` 这个执行最近的动态。
+- 从禅道 Bug 列表页里提取 execution ID 并列出 Bug。
+- 从禅道版本页里提取 execution ID 并列出构建。
+
+### Bug 和版本
+
+- 看某个执行下有哪些版本。
+- 解决 Bug 时关联到某个版本。
+- 查某个执行下已解决但还没关闭的 Bug。
+- 查某个执行下延期处理的 Bug。
+- 查某个执行下 reopen 过的 Bug。
+
+### 需求、产品、项目和测试
+
+- 查某个产品下的需求。
+- 查某个产品下的 Bug。
+- 查某个项目下的执行列表。
+- 查某个执行下的构建列表。
+- 查某个产品下的测试用例。
+- 查某个测试单详情。
+- 搜索包含某个关键词的需求。
+
+## 常用命令示例
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
+# 我的任务
+zentao --role qa getMyTasks --status all --limit 100
+zentao --role qa getMyTasks --status wait --limit 50
+
+# 我的阶段性工作清单
+zentao --role qa getMyWeeklyActivity --account lixm1 --week last
+zentao --role qa getMyWeeklyActivity --account lixm1 --dateRange 最近3天
+zentao --role qa getMyWeeklyActivity --account lixm1 --dateRange 2026-05-25到2026-05-29
+
+# 执行 Bug / 构建 / 动态
+zentao --role qa getExecutionBugs --executionId 2130 --limit 100
+zentao --role qa getExecutionBuilds --executionId 2130
+zentao --role qa getExecutionDynamic --executionId 2130
+
+# 每日迭代执行统计
+zentao --role qa getExecutionDailyBugStats --executionId 2067 --iterationName 1.2.3迭代
+zentao --role qa getExecutionDailyBugStats --executionId 2067 --iterationName 1.2.3迭代 --date 2026-06-06
 ```
 
-工作流会校验：
-
-- tag `v0.1.0` 是否与 `package.json` 中的 `0.1.0` 一致
+## 写操作保护
 
-如果不一致，Action 会直接失败，避免把错误版本发布到 npm。
-
-### 推荐顺序
+默认不写入线上。真实写操作需要同时满足：
 
 ```bash
-# 1. 修改 package.json version
-# 2. 提交代码
-# 3. 推送分支
-# 4. 打 tag
-git tag v0.1.0
-git push origin main
-git push origin v0.1.0
+export ZENTAO_ENABLE_WRITE=true
 ```
 
-### 当前还未自动完成的部分
-
-下面这些仍需要你首次手动完成一次：
+并且命令参数里显式传入 `confirm=true`。
 
-- 初始化本地 git 仓库
-- 首次 commit
-- 创建 GitHub 仓库并 push 上去
-- 在 npm 包侧完成 trusted publisher 绑定
-
-## 启动
+## 更多命令
 
 ```bash
-pnpm dev
+zentao help
+zentao list
+zentao --role qa list
 ```

package/dist/api/execution.d.ts

@@ -26,10 +26,15 @@ export interface PutoffExecutionInput {
     days: number;
     comment?: string;
 }
+export interface ExecutionDailyBugStatsInput {
+    iterationName?: string;
+    date?: string;
+}
 export declare class ExecutionApi {
     private readonly http;
     constructor(http: ZentaoHttpClient);
     getExecutionDetail(executionId: number): Promise<ZentaoExecution>;
+    getExecutionDynamic(executionId: number): Promise<unknown>;
     getProjectExecutions(projectId: number): Promise<unknown>;
     getExecutionBuilds(executionId: number): Promise<unknown>;
     getExecutionBugs(executionId: number, params?: {
@@ -37,10 +42,38 @@ export declare class ExecutionApi {
         limit?: number;
         status?: string;
     }): Promise<unknown>;
+    getExecutionDailyBugStats(executionId: number, input?: ExecutionDailyBugStatsInput): Promise<unknown>;
     updateExecution(executionId: number, update: UpdateExecutionInput): Promise<unknown>;
     startExecution(executionId: number, payload?: ExecutionActionInput): Promise<unknown>;
     closeExecution(executionId: number, payload?: ExecutionActionInput): Promise<unknown>;
     suspendExecution(executionId: number, payload?: ExecutionActionInput): Promise<unknown>;
     activateExecution(executionId: number, payload?: ExecutionActionInput): Promise<unknown>;
     putoffExecution(executionId: number, payload: PutoffExecutionInput): Promise<unknown>;
+    private getAllExecutionBugs;
+    private getAllExecutionTasks;
+    private buildParticipantBugStats;
+    private getBugOwner;
+    private isDelayedBug;
+    private resolveUserNames;
+    private buildDailyBugNotes;
+    private buildSeveritySummary;
+    private buildTaskSummary;
+    private buildTaskParticipantStats;
+    private buildTaskDetails;
+    private getTaskOwner;
+    private isOverdueUnfinishedTask;
+    private buildBugDetails;
+    private formatDailyBugStatsReport;
+    private formatBugDetailSection;
+    private formatTaskDetailSection;
+    private formatCountWithRate;
+    private formatCountWithRateOrZero;
+    private percent;
+    private resolveStatsDate;
+    private parseDate;
+    private toDateOnly;
+    private isOnOrBefore;
+    private addDays;
+    private formatDate;
+    private toString;
 }